From 8bafdfe7599e79b72c15310f6e3714e51a69dddd Mon Sep 17 00:00:00 2001 From: Philipp D Date: Tue, 17 Nov 2026 16:10:50 +0100 Subject: [PATCH 1/3] feat(ui): the start page gets a search and a state filter A field above the tiles finds a stack by its name or repository folder (every word typed must match, whatever the case), and three chips, "All", "Running" and "Needs attention", each with its count, narrow the tiles by state. `/` jumps to the field, Esc clears it; text and state are kept in the tab's session storage, so a visit to a stack and back finds them as left. A hidden stack stays out of the tiles, but the line under them says how many hidden stacks match what was typed. `matchesQuery` is the stack's own part of the sidebar's `filterStacks`, which now uses it, so both read the words the same way (ADR-0107). Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 10 ++ ...rt-page-has-a-search-and-a-state-filter.md | 66 +++++++++ docs/adr/README.md | 1 + ui/src/lib/stackOrder.test.ts | 9 ++ ui/src/lib/stackOrder.ts | 20 ++- ui/src/stores/ui.ts | 14 ++ ui/src/views/HomeView.test.ts | 111 ++++++++++++++ ui/src/views/HomeView.vue | 137 +++++++++++++++++- 8 files changed, 356 insertions(+), 12 deletions(-) create mode 100644 docs/adr/0107-the-start-page-has-a-search-and-a-state-filter.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d26c4e3..6e6057db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,16 @@ and listed with their assets on the ## [Unreleased] +### Added + +- **A search and a state filter on the start page.** A field above the tiles + finds a stack by its name or its repository folder (every word typed must + match), and three chips, "All", "Running" and "Needs attention", each with + its count, narrow the tiles by state. `/` jumps to the field, Esc clears + it; text and state are still there after a visit to a stack and back. A + hidden stack stays out, but the line under the tiles says how many hidden + ones match what was typed. + ## [0.48.0] - 2026-11-16 The dashboard opens on a start page with every stack as a tile, a service diff --git a/docs/adr/0107-the-start-page-has-a-search-and-a-state-filter.md b/docs/adr/0107-the-start-page-has-a-search-and-a-state-filter.md new file mode 100644 index 00000000..7f0880e3 --- /dev/null +++ b/docs/adr/0107-the-start-page-has-a-search-and-a-state-filter.md @@ -0,0 +1,66 @@ +# ADR-0107: The start page has a search by name or folder and a filter by state + +- **Status:** Accepted (card in the pull request); built +- **Date:** 2026-11-17 +- **Deciders:** project owner +- **Related:** [ADR-0104](0104-the-start-page-shows-every-stack-as-a-tile.md) (the start page), [ADR-0102](0102-the-stacks-list-orders-by-last-commit-hides-stacks-and-filters.md) (the sidebar's filter), [ADR-0086](0086-favourite-stacks-list-first.md) (favourites), [ADR-0070](0070-a-review-card-comes-before-the-code-an-adr-records-what-was-built.md) + +## Context + +The start page shows every stack as a tile (ADR-0104). With many stacks there +was no quick way to find one, or to see only the ones that run or need +attention; the sidebar's filter (ADR-0102) is a click away from it and +reaches stacks and worktrees, not the tiles. + +## Decision + +The owner approved the points in the conversation on **2026-11-17** (with the +plan that carried them), after choosing that the search covers name and +folder, that the state filter is part of it, and that the page keeps a field +of its own: + +| # | Category | Point | Beats | Reversing costs | +|---|---|---|---|---| +| 1 | concept | The start page has a search field above the tiles; every word typed must be part of the stack's name or repository folder, whatever the case. | Sharing the sidebar's field, which would change the sidebar without cause. | Low: UI code only. | +| 2 | concept | Three state filters, "All", "Running" and "Needs attention", each with its count, combine with the text. | A search field alone, which cannot narrow by state. | Low: UI code only. | +| 3 | concept | The search finds the stack itself, not its worktrees. | Searching worktrees too, which needs every stack's lanes on this page (the sidebar reads them); it can be added later. | Low. | +| 4 | term | Text and state are kept in this tab's session storage, so the way to a stack and back through the "devstack" mark finds them as left. | Starting empty each time. | Low. | + +Decided on its own, not on the card: `/` focuses the field (unless a field +has the keys), Esc clears it and, once empty, leaves it; a hidden stack stays +out of the tiles, but while something is typed the line under them says how +many hidden stacks match, so a search never denies a stack that exists; a +filter with no match says so and offers "Clear the filter". + +As built: + +1. **The match.** `matchesQuery` (`ui/src/lib/stackOrder.ts`) is the stack's + own part of the sidebar's `filterStacks`, which now uses it, so both read + the words the same way. +2. **The state.** "Running" is a stack whose daemon runs, "Needs attention" a + stack with an item on the `attention` event, as the counts in the page's + head. The chips count the listed (not hidden) stacks, whatever is typed. +3. **The page.** `ui/src/views/HomeView.vue`; the text and the state are + `homeQuery` and `homeState` in `ui/src/stores/ui.ts`, saved in the session + storage as the sidebar's filter is. + +## Alternatives considered + +- **One field for the sidebar and the page.** One text for both, but typing + on the page would filter the sidebar and the other way round. +- **Searching worktrees as well.** Matches what the sidebar finds, at the + cost of reading every stack's lanes on the start page. + +## Consequences + +- A filter left on is still on when the page is opened again in the same + tab; the head's figures count every stack, the chips the listed ones. +- A stack that needs attention only through its own state (no item on the + `attention` event) is not counted by the chip, as it is not by the head. +- The page needs no new hub call. + +## Enforced by + +- `ui/src/views/HomeView.vue`, `ui/src/lib/stackOrder.ts` (`matchesQuery`), + `ui/src/stores/ui.ts` (`homeQuery`, `homeState`); tests in + `ui/src/views/HomeView.test.ts` and `ui/src/lib/stackOrder.test.ts`. diff --git a/docs/adr/README.md b/docs/adr/README.md index 406a0579..225b2485 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -189,3 +189,4 @@ stay. | [0104](0104-the-start-page-shows-every-stack-as-a-tile.md) | The start page shows every stack as a tile, with the hub's figures and the favourite programs | Accepted (card in the pull request); built | | [0105](0105-a-service-can-be-a-shortcut-card-on-the-overview.md) | A service can be a shortcut card on the overview, marked in the stack file | Accepted (card in the pull request); built | | [0106](0106-a-running-job-is-running-and-measured.md) | A running job is `running` and measured; it counts as done only when it completed | Accepted (card in the pull request); built | +| [0107](0107-the-start-page-has-a-search-and-a-state-filter.md) | The start page has a search by name or folder and a filter by state | Accepted (card in the pull request); built | diff --git a/ui/src/lib/stackOrder.test.ts b/ui/src/lib/stackOrder.test.ts index ef99475d..1f8e5ff2 100644 --- a/ui/src/lib/stackOrder.test.ts +++ b/ui/src/lib/stackOrder.test.ts @@ -4,6 +4,7 @@ import { forgetFavourite, forgetHidden, forgetOpened, + matchesQuery, noteOpened, openedTimes, orderStacks, @@ -105,4 +106,12 @@ describe('the filter of the stacks', () => { expect(filterStacks(list, 'shop cart', labels).stacks.map((x) => x.id)).toEqual(['a']); expect(filterStacks(list, 'shop search', labels).stacks).toEqual([]); }); + + it('matches the stack itself by every word of name and folder, never by a worktree', () => { + expect(matchesQuery(list[1], '')).toBe(true); + expect(matchesQuery(list[1], 'BILLING ledger')).toBe(true); + expect(matchesQuery(list[1], 'billing shop')).toBe(false); + // `feat` is a worktree label of "shop" only: the stack itself does not match. + expect(matchesQuery(list[0], 'feat')).toBe(false); + }); }); diff --git a/ui/src/lib/stackOrder.ts b/ui/src/lib/stackOrder.ts index b5bb6ec5..deedb0a9 100644 --- a/ui/src/lib/stackOrder.ts +++ b/ui/src/lib/stackOrder.ts @@ -112,6 +112,19 @@ export function orderStacks( return [...stacks].sort((a, b) => fav(a) - fav(b) || within(a, b)); } +const wordsOf = (query: string) => query.toLowerCase().split(/\s+/).filter(Boolean); +const ownText = (s: Named & { repo: string }) => `${s.name} ${s.repo}`.toLowerCase(); + +/** + * Whether what was typed matches the stack itself: every word of it is part + * of the stack's name or repository folder, whatever the case. Nothing typed + * matches every stack. + */ +export function matchesQuery(stack: Named & { repo: string }, query: string): boolean { + const own = ownText(stack); + return wordsOf(query).every((w) => own.includes(w)); +} + /** * The stacks that match what was typed: every word of it is part of the * stack's name or repository folder, or of the label of one of its worktrees @@ -123,14 +136,13 @@ export function filterStacks( query: string, labels: (s: T) => readonly string[], ): { stacks: T[]; byWorktree: Set } { - const words = query.toLowerCase().split(/\s+/).filter(Boolean); + const words = wordsOf(query); if (!words.length) return { stacks: [...stacks], byWorktree: new Set() }; const byWorktree = new Set(); const kept = stacks.filter((s) => { - const own = `${s.name} ${s.repo}`.toLowerCase(); - const all = `${own} ${labels(s).join(' ')}`.toLowerCase(); + const all = `${ownText(s)} ${labels(s).join(' ')}`.toLowerCase(); if (!words.every((w) => all.includes(w))) return false; - if (!words.every((w) => own.includes(w))) byWorktree.add(s.id); + if (!matchesQuery(s, query)) byWorktree.add(s.id); return true; }); return { stacks: kept, byWorktree }; diff --git a/ui/src/stores/ui.ts b/ui/src/stores/ui.ts index c05509ed..5d51657e 100644 --- a/ui/src/stores/ui.ts +++ b/ui/src/stores/ui.ts @@ -3,6 +3,8 @@ import { computed, ref, watch, watchEffect } from 'vue'; import { persist } from '@/lib/persist'; export type ThemePref = 'system' | 'light' | 'dark'; +/** The start page's state filter: every stack, the ones that run, the ones that need attention. */ +export type HomeState = 'all' | 'running' | 'attention'; export type ToastKind = 'success' | 'error' | 'info' | 'warning'; export type Toast = { id: number; kind: ToastKind; title: string; message?: string }; @@ -167,11 +169,23 @@ export const useUi = defineStore('ui', () => { persist.setSession('sidebar.filter.query', query); }); + // The start page's search and state filter: kept for the same reason, so a + // way to a stack and back through the "devstack" mark finds them as left. + const homeQuery = ref(persist.getSession('home.filter.query') ?? ''); + const savedState = persist.getSession('home.filter.state'); + const homeState = ref(savedState === 'running' || savedState === 'attention' ? savedState : 'all'); + watch([homeQuery, homeState], ([query, state]) => { + persist.setSession('home.filter.query', query); + persist.setSession('home.filter.state', state); + }); + return { theme, effectiveTheme, filterOpen, filterQuery, + homeQuery, + homeState, cycleTheme, toasts, toast, diff --git a/ui/src/views/HomeView.test.ts b/ui/src/views/HomeView.test.ts index 181edd31..a37d7db3 100644 --- a/ui/src/views/HomeView.test.ts +++ b/ui/src/views/HomeView.test.ts @@ -44,6 +44,7 @@ let fake: FakeTransport; beforeEach(() => { localStorage.clear(); + sessionStorage.clear(); setActivePinia(createPinia()); fake = new FakeTransport(); t.current = fake; @@ -167,3 +168,113 @@ describe('the start page', () => { unmount(); }); }); + +describe('the search and the state filter of the start page', () => { + const billing = stack('gh78', 'Billing', { repo: '/work/ledger' }); + const search = (el: HTMLElement) => el.querySelector('[data-testid="overview-search"]')!; + const type = async (el: HTMLElement, text: string) => { + search(el).value = text; + search(el).dispatchEvent(new Event('input', { bubbles: true })); + await settle(); + }; + const chip = (el: HTMLElement, key: string) => el.querySelector(`[data-testid="overview-chip-${key}"]`)!; + const attention = (events: { onMessage: (m: unknown) => void }, ...ids: string[]) => + events.onMessage({ + type: 'attention', + items: ids.map((stackId) => ({ stack: stackId, lane: null, service: 'api', text: 'api: failed', detail: '', level: 'error' })), + }); + + it('finds a stack by its name or its repository folder, every word, whatever the case', async () => { + const { el, unmount } = await mounted([shop, crm, billing]); + await type(el, 'BILL'); + expect(names(el)).toEqual(['Billing']); + await type(el, 'ledger'); + expect(names(el)).toEqual(['Billing']); + await type(el, 'work billing'); + expect(names(el)).toEqual(['Billing']); + await type(el, 'work shop'); + expect(names(el)).toEqual([]); + await type(el, ''); + expect(names(el)).toEqual(['Billing', 'crm', 'shop']); + unmount(); + }); + + it('counts the stacks per state and narrows to the ones that run or need attention', async () => { + const { el, events, unmount } = await mounted([shop, crm, billing]); + attention(events, 'cd34'); + await settle(); + expect(chip(el, 'all').textContent?.replace(/\s+/g, ' ').trim()).toBe('All 3'); + expect(chip(el, 'running').textContent).toContain('1'); + expect(chip(el, 'attention').textContent).toContain('1'); + chip(el, 'running').click(); + await settle(); + expect(names(el)).toEqual(['shop']); + expect(chip(el, 'running').getAttribute('aria-pressed')).toBe('true'); + chip(el, 'attention').click(); + await settle(); + expect(names(el)).toEqual(['crm']); + chip(el, 'all').click(); + await settle(); + expect(names(el)).toEqual(['Billing', 'crm', 'shop']); + unmount(); + }); + + it('combines the state with the text, and says so when nothing matches', async () => { + const { el, unmount } = await mounted([shop, crm]); + chip(el, 'running').click(); + await type(el, 'crm'); + expect(names(el)).toEqual([]); + expect(el.querySelector('[data-testid="overview-tiles"]')).toBeNull(); + expect(el.querySelector('[data-testid="overview-empty"]')?.textContent).toContain('No stack matches'); + el.querySelector('[data-testid="overview-clear"]')!.click(); + await settle(); + expect(search(el).value).toBe(''); + expect(chip(el, 'all').getAttribute('aria-pressed')).toBe('true'); + expect(names(el)).toEqual(['crm', 'shop']); + unmount(); + }); + + it('keeps hidden stacks out, and says how many of them the search would have found', async () => { + useHidden().hide('gh78'); + const { el, unmount } = await mounted([shop, billing]); + expect(el.querySelector('[data-testid="overview-hidden"]')?.textContent).toContain('1 hidden stack is not shown'); + await type(el, 'bill'); + expect(names(el)).toEqual([]); + expect(el.querySelector('[data-testid="overview-hidden"]')?.textContent).toContain('1 hidden stack matches'); + await type(el, 'shop'); + expect(el.querySelector('[data-testid="overview-hidden"]')?.textContent).toContain('1 hidden stack is not shown'); + unmount(); + }); + + it('jumps to the search with /, and Esc clears it, then leaves it', async () => { + const { el, unmount } = await mounted([shop, crm]); + window.dispatchEvent(new KeyboardEvent('keydown', { key: '/', bubbles: true })); + expect(document.activeElement).toBe(search(el)); + await type(el, 'crm'); + // A `/` typed into a field is text, not a jump. + const typed = new KeyboardEvent('keydown', { key: '/', bubbles: true, cancelable: true }); + search(el).dispatchEvent(typed); + expect(typed.defaultPrevented).toBe(false); + search(el).dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })); + await settle(); + expect(search(el).value).toBe(''); + expect(document.activeElement).toBe(search(el)); + search(el).dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })); + expect(document.activeElement).not.toBe(search(el)); + unmount(); + }); + + it('is found as it was left when the page is opened again', async () => { + const first = await mounted([shop, crm]); + await type(first.el, 'crm'); + chip(first.el, 'attention').click(); + await settle(); + first.unmount(); + // A new page of the same tab: the store is new, the session storage stays. + setActivePinia(createPinia()); + const again = await mounted([shop, crm]); + expect(search(again.el).value).toBe('crm'); + expect(chip(again.el, 'attention').getAttribute('aria-pressed')).toBe('true'); + again.unmount(); + }); +}); diff --git a/ui/src/views/HomeView.vue b/ui/src/views/HomeView.vue index 1e0c9f8d..2fef0994 100644 --- a/ui/src/views/HomeView.vue +++ b/ui/src/views/HomeView.vue @@ -1,14 +1,17 @@ + + + + diff --git a/ui/src/components/StackTile.vue b/ui/src/components/StackTile.vue index 83bfd291..dd014187 100644 --- a/ui/src/components/StackTile.vue +++ b/ui/src/components/StackTile.vue @@ -7,15 +7,17 @@ // above it. import { computed } from 'vue'; import type { StackEntry } from '@/api/types'; -import { ago, duration, useNow } from '@/lib/format'; +import { commitAge, duration, useNow } from '@/lib/format'; +import { stackFigures } from '@/lib/stackFigures'; import { stackPage } from '@/lib/stackRoutes'; -import type { Tone } from '@/lib/status'; import { useHub } from '@/stores/hub'; import Icon from './icons/Icon.vue'; import StatusPill from './StatusPill.vue'; import FavoriteOpeners from './FavoriteOpeners.vue'; -const props = defineProps<{ stack: StackEntry; favourite: boolean }>(); +// `compact`: the small tile, which leaves out how long it has been up and the +// ports shift, and tells only the first thing that needs attention. +const props = defineProps<{ stack: StackEntry; favourite: boolean; compact?: boolean }>(); const emit = defineEmits<{ toggleFavourite: [] }>(); const hub = useHub(); @@ -24,29 +26,11 @@ const now = useNow(); /** Most attention lines on a tile; the rest are counted. */ const SHOWN_ITEMS = 2; -const glance = computed(() => hub.glances[props.stack.id] ?? null); -const items = computed(() => hub.attention.filter((a) => a.stack === props.stack.id)); - -const look = computed((): { label: string; tone: Tone; busy: boolean } => { - const s = props.stack; - if (!hub.reachable) return { label: 'Unknown', tone: 'neutral', busy: false }; - // A start or stop this page asked for, before the hub's figures say it. - if (hub.stopping[s.id]) return { label: 'Stopping', tone: 'neutral', busy: true }; - if (hub.starting[s.id] && !s.running) return { label: 'Starting', tone: 'accent', busy: true }; - const state = glance.value?.state ?? (s.start_error ? 'attention' : s.running ? 'ok' : 'stopped'); - switch (state) { - case 'attention': - return { label: 'Needs attention', tone: items.value.some((i) => i.level === 'error') || s.start_error ? 'danger' : 'warn', busy: false }; - case 'starting': - return { label: 'Starting', tone: 'accent', busy: true }; - case 'stopping': - return { label: 'Stopping', tone: 'neutral', busy: true }; - case 'ok': - return { label: 'Running', tone: 'ok', busy: false }; - default: - return { label: 'Stopped', tone: 'neutral', busy: false }; - } -}); +const figures = computed(() => stackFigures(props.stack, hub)); +const look = computed(() => figures.value.look); +const items = computed(() => figures.value.items); +const services = computed(() => figures.value.services); +const lanes = computed(() => figures.value.lanes); /** The path's folder and its last part: a long path is cut in the folder, the repository's name stays. */ const parts = computed(() => { @@ -54,28 +38,15 @@ const parts = computed(() => { return m ? { dir: m[1], leaf: m[2] } : { dir: '', leaf: props.stack.repo }; }); -const services = computed(() => { - const g = glance.value; - if (!props.stack.running || !g || !g.total) return null; - return { ready: g.ready, total: g.total, share: g.ready / g.total }; -}); -const lanes = computed(() => (props.stack.running && glance.value ? glance.value.lanes : null)); -const upFor = computed(() => (props.stack.running && props.stack.daemon ? duration(now.value - props.stack.daemon.started) : null)); -const DAY = 86_400_000; -/** Within a day as `ago` says it; older in days, which fits a tile better than a date. */ -const committed = computed(() => { - const at = props.stack.last_commit ? props.stack.last_commit * 1000 : null; - if (!at) return null; - const days = Math.floor((now.value - at) / DAY); - return days >= 1 ? `${days} d ago` : ago(at, now.value); -}); +const upFor = computed(() => (figures.value.upSince !== null ? duration(now.value - figures.value.upSince) : null)); +const committed = computed(() => commitAge(figures.value.committedAt, now.value)); -const shownItems = computed(() => items.value.slice(0, SHOWN_ITEMS)); +const shownItems = computed(() => items.value.slice(0, props.compact ? 1 : SHOWN_ITEMS)); const moreItems = computed(() => items.value.length - shownItems.value.length);