Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,29 @@ and listed with their assets on the

## [Unreleased]

### Added

- **An order menu on the start page.** The same menu as the sidebar's (by
name, last opened first, last edited first; favourites always first) sits
in the filter row and orders the tiles and the list. The order is one
choice for the sidebar and the start page: choosing it in either shows in
both at once, where the start page used to take it only when it opened.
- **Small tiles and a list on the start page.** A switch beside the search
shows the stacks as large tiles (as before), as small tiles (the same tile,
closer together, without the time up and the ports shift) or as a list: a
table with a column each for state, services, lanes, time up, last commit
and what needs attention, sortable by its headers, with the star and the
favourite programs in each row; a click on a row opens the stack. The
search and the state filter apply in every view, and the choice is kept in
the browser.
- **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
Expand Down
66 changes: 66 additions & 0 deletions docs/adr/0107-the-start-page-has-a-search-and-a-state-filter.md
Original file line number Diff line number Diff line change
@@ -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`.
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# ADR-0108: The start page shows the stacks as large tiles, small tiles or a sortable list

- **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, its tile), [ADR-0107](0107-the-start-page-has-a-search-and-a-state-filter.md) (search and state 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 (ADR-0104) shows every stack as a large tile. With many stacks
the large tiles take much room, and a column of figures to compare (which
stack was committed to last, which has the most lanes) is easier to read in a
table than in tiles.

## Decision

The owner approved the points in the conversation on **2026-11-17** (with the
plan that carried them), after choosing three views (large tiles, small
tiles, a list) and that the choice is kept in the browser:

| # | Category | Point | Beats | Reversing costs |
|---|---|---|---|---|
| 1 | concept | The start page has three views of the same stacks: large tiles (as before), small tiles, a list. A switch beside the search chooses; the search and the state filter apply in each. | A page of its own for each view, which would repeat the filters. | Low: UI code only. |
| 2 | concept | The small tile is the same tile, closer together: name, state, folder, services, lanes, last commit and the first thing that needs attention; how long it has been up and the ports shift are left out. | A second tile component. | Low. |
| 3 | concept | The list is a table with the sortable column headers every table has: favourite star, name (folder below), state, services, lanes, up, last commit, attention, programs. Until a column is chosen the order is the tiles' (favourites first); a column's order applies in the list only. | One order for every view, which would take the sidebar's order from the tiles. | Low. |
| 4 | term | The views are "Large tiles", "Small tiles" and "List"; the choice is kept in this browser (local storage, as the sidebar's order and the favourites are), while the search text and the state stay with the tab (ADR-0107). | Keeping the view per tab. | Low. |

Decided on its own, not on the card: a click on a row opens the stack (the
name is a link, the star and the programs do not open it); the attention
column is the number of items, its tooltip lists them; the "Up" column goes
on a narrow screen; the stack's folder is the second line of the name cell; a
stack without its stack file shows a warning mark beside its name.

As built:

1. **The figures.** `ui/src/lib/stackFigures.ts` (`stackFigures`) takes what
the tile worked out (state, services, lanes, since when it runs, last
commit, items) into plain values, with the state's `rank` for sorting; the
tile, the row and the sort read the same values.
2. **The tile.** `ui/src/components/StackTile.vue` has a `compact` prop for
the small tile.
3. **The row.** `ui/src/components/StackRow.vue`, a `<tr>` with `FavoriteOpeners`
and `StatusPill`.
4. **The page.** `ui/src/views/HomeView.vue`: the switch is `homeView` in
`ui/src/stores/ui.ts` (`devstack.home.view`); the list sorts with
`useSort` (`ui/src/lib/sort.ts`, kept as `devstack.sort.home`), by name,
state (the most urgent first), services, lanes, up (the longest first),
last commit (the newest first) or attention (the most first).

## Alternatives considered

- **A table as the only second view.** Less to build, but the small tiles keep
the overview's look at a third of the room.
- **Sorting the tiles by a column too.** The tiles keep the sidebar's order
(ADR-0102); a second way to order them would need a place to choose it.

## Consequences

- A column sort set in the list stays in this browser until it is turned back
to the tiles' order (a third click on the header); the tiles do not follow
it.
- The list scrolls sideways inside its frame where the screen is too narrow
for its columns.
- The tile's figures moved out of `StackTile.vue`: a change to them is made in
`stackFigures.ts` and shows in all three views.

## Enforced by

- `ui/src/lib/stackFigures.ts`, `ui/src/components/StackTile.vue`,
`ui/src/components/StackRow.vue`, `ui/src/views/HomeView.vue`,
`ui/src/stores/ui.ts` (`homeView`); tests in
`ui/src/views/HomeView.test.ts` and `ui/src/lib/stackFigures.test.ts`.
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# ADR-0109: The order of the stacks is one choice for the sidebar and the start page

- **Status:** Accepted (card in the pull request); built
- **Date:** 2026-11-17
- **Deciders:** project owner
- **Related:** [ADR-0084](0084-the-sidebar-orders-stacks-by-name-or-last-opened.md) (the order menu), [ADR-0102](0102-the-stacks-list-orders-by-last-commit-hides-stacks-and-filters.md) (last edited first), [ADR-0086](0086-favourite-stacks-list-first.md) (favourites first), [ADR-0104](0104-the-start-page-shows-every-stack-as-a-tile.md) (its point 3: the tiles follow the sidebar's order, read when the page opens), [ADR-0108](0108-the-start-page-has-large-and-small-tiles-and-a-list.md) (the list), [ADR-0070](0070-a-review-card-comes-before-the-code-an-adr-records-what-was-built.md)

## Context

The start page took the sidebar's order when it opened (ADR-0104), but had no
way to change it: the choice had to be made in the sidebar's menu, and the
page showed it only after it was opened again.

## Decision

The owner approved the points in the conversation on **2026-11-17**, after
choosing that the order is one setting for both:

| # | Category | Point | Beats | Reversing costs |
|---|---|---|---|---|
| 1 | concept | The start page gets the sidebar's order menu (by name, last opened first, last edited first; favourites always first) as a button in the filter row. | A menu of its own with other entries. | Low: UI code only. |
| 2 | concept | The order is one setting for the sidebar and the start page, and a choice in either shows in both at once. | Two separate orders. | Medium: the state lives in one shared module; separating them splits it again. |
| 3 | concept | The menu sets the order of the tiles and of the list; in the list a column chosen on its header overrides it until it is turned back. | The menu for the tiles only. | Low. |

Decided on its own, not on the card: the menu is a component both pages use
(`StackOrderMenu.vue`), each drawing its button in its own look; last opened
and last edited stay snapshots that a page takes when it opens and when an
order is chosen (also the one already chosen), so nothing moves under the
pointer.

As built:

1. **The choice.** `useOrderChoice` (`ui/src/lib/stackOrder.ts`) holds the
order in one place, written to `devstack.sidebar.order` as before and read
from the browser when a page opens; every choice also counts up, which the
pages watch to take their snapshots anew.
2. **The ordering.** `useStackOrdering` takes the snapshots of one page and
sorts a list with them; the sidebar and the start page both use it, the
copy of that code in each is gone.
3. **The menu.** `ui/src/components/StackOrderMenu.vue` is the menu with its
outside-click and Escape handling, the button comes from the page
(`data-testid` `sidebar-order`, `overview-order`).

## Consequences

- The tiles of the start page follow a choice made while it is open; ADR-0104's
"when the page opens" no longer holds for the order (it holds for the
snapshots).
- A choice in one browser tab does not reach another tab until it is opened.

## Enforced by

- `ui/src/lib/stackOrder.ts` (`useOrderChoice`, `useStackOrdering`),
`ui/src/components/StackOrderMenu.vue`, `ui/src/components/Sidebar.vue`,
`ui/src/views/HomeView.vue`; tests in `ui/src/lib/stackOrder.test.ts`,
`ui/src/views/HomeView.test.ts` and `ui/src/components/Sidebar.test.ts`.
3 changes: 3 additions & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,3 +189,6 @@ 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 |
| [0108](0108-the-start-page-has-large-and-small-tiles-and-a-list.md) | The start page shows the stacks as large tiles, small tiles or a sortable list | Accepted (card in the pull request); built |
| [0109](0109-the-order-of-the-stacks-is-one-choice-for-the-sidebar-and-the-start-page.md) | The order of the stacks is one choice for the sidebar and the start page | Accepted (card in the pull request); built |
Loading
Loading