@tristan2828/ui-foundation 4.33.0 → 4.35.0

package/conventions/AGENTS.md

@@ -35,9 +35,12 @@ is right. Do not disable, skip, or work around it.
   that also writes a primitive the package ships (a dependency of the one
   you asked for), delete the copy and import the package's. (Enforced: lint
   rejects `@/components/ui/<name>` for any primitive the package ships.)
-- NEVER add a dependency that is not in `deps-allowlist.json`. If you
-  believe one is needed, write the case in `docs/BLOCKERS.md` and stop.
-  (Enforced: `ui-foundation check-deps` in verify.)
+- NEVER add a dependency that is not in `deps-allowlist.json`, npm or
+  Python (its `python` list, for `backend/pyproject.toml`, each pinned
+  with `==`). If you believe one is needed, write the case in
+  `docs/BLOCKERS.md` and stop. (Enforced: `ui-foundation check-deps` in
+  verify; `python -m foundation_backend.scripts.check_deps` in
+  verify:backend.)
 - NEVER hand-write an API type. All types come from `src/api/schema.d.ts`,
   generated from `openapi.yaml`. If a type is missing, run `npm run gen:api`.
   (Enforced: codegen diff in verify.)
@@ -92,6 +95,9 @@ Every screen has one Playwright test per state, forced via MSW overrides
 ## Design Language
 Colour, tone, badges, cell patterns and density follow
 `docs/foundation/design-language.md` and `docs/foundation/cell-patterns.md`.
+The long docs in `docs/foundation/` open with an index of their sections
+and steps, each with the lines it spans: read the index, then only the
+lines you need.
 A pattern the foundation lacks is worth raising there: the design language
 grows in the package so every app gets it, with axe contrast coverage in
 both themes.

package/conventions/docs/add-an-entity.md

@@ -1,5 +1,27 @@
 # Add an Entity
 
+<!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
+## Index
+
+- [The reference files](#the-reference-files) · lines 37–59
+- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 61–702
+  - Step 1: Add `<Entity>` to `openapi.yaml` · lines 99–106
+  - Step 2: `npm run gen:api` · lines 107–108
+  - Step 3: Add gateway tests in `tests/gateway/<entity>.test.ts`, derived from the spec · lines 109–120
+  - Step 4: Add MSW handlers in `src/mocks/<entity>.ts` · lines 121–130
+  - Step 5: Add a gateway module in `src/api/gateway/<entity>.ts` · lines 131–135
+  - Step 6: Copy the reference files, one for one, not just the two screens · lines 136–598
+  - Step 7: Register routes · lines 599–609
+  - Step 8: Add Playwright specs for all three screens · lines 610–684
+  - Step 9: Register the nav entry and route names · lines 685–699
+  - Step 10: `npm run verify`. · lines 700–702
+- [What not to copy](#what-not-to-copy) · lines 704–730
+- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 732–749
+- [Deleting](#deleting) · lines 751–780
+- [Fields only a script writes](#fields-only-a-script-writes) · lines 782–803
+
+<!-- /index -->
+
 The most-repeated task in this system: add a full CRUD entity — spec, mocks,
 gateway, tests, table, view, form, routes — following the patterns in
 `src/routes/widgets/`. This file is the only copy of the steps, written for
@@ -449,7 +471,8 @@ is a filled-in example while the Widgets demo is still here).
      breaks). Give `<Markdown>` and `RichTextEditor` a `headingLevel` for
      where they sit: the default (3) in an `EntityView` section,
      `headingLevel={2}` for a `RichTextEditor` on a form straight under
-     the page's `<h1>`.
+     the page's `<h1>`. Text that's imported or pasted from another
+     tool (often starting at `##`) also gets `headingFrom="text"`.
    - **Quick actions: only the fields the plan's `Quick actions` line
      names**, each a control that saves on its own (cell pattern 17,
      `widget-quick-actions.tsx`). A `yes/no` is a
@@ -580,7 +603,10 @@ is a filled-in example while the Widgets demo is still here).
    app's name alone). For a list that should open on one of its saved
    views, `to` carries that view's query string
    (`/widgets?status=active`): the entry is still matched on its path, so
-   it stays current on the list and the records under it.
+   it stays current on the list and the records under it. A page that
+   belongs to a module already in the nav (its categories, its channels)
+   goes in that module's entry's `children`, not a new top-level entry:
+   it shows under the module while you're in it.
 8. **Add Playwright specs for all three screens**, one test per state
    (`loading`, `empty`, `error`, `validation`, `success`), forced through
    MSW overrides — `forceMswOverride`, `waitForMswReady` and the
@@ -662,7 +688,11 @@ is a filled-in example while the Widgets demo is still here).
    of a full record and of the sparse one to its `viewRoutes` (the table
    page comes from `src/nav.ts`, which the suite is given as `nav`: each
    nav page is a test of its own, so the suite's time per test stays flat
-   as the app grows; the form and the view aren't in the nav). With fields edited in place, copy `e2e/a11y.spec.ts`'s
+   as the app grows; the form and the view aren't in the nav). An app
+   with one a11y spec per module (`e2e/a11y-<module>.spec.ts`) adds them
+   to its module's file instead, which passes only that module's nav
+   entries with `checkSidebar: false`; one file keeps the whole nav and
+   the sidebar check. With fields edited in place, copy `e2e/a11y.spec.ts`'s
    "editing in place" block for them: a field open, saving and refused,
    the rich-text editor, an open list, a list edited in place (an item
    open, one being added, a refused change), and the leave prompt, in

package/conventions/docs/cell-patterns.md

@@ -1,5 +1,42 @@
 # Cell Patterns
 
+<!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
+## Index
+
+- [The rules that apply to every cell](#the-rules-that-apply-to-every-cell) · lines 65–84
+- [1. Plain text](#1-plain-text) · lines 86–93
+- [2. Icon + label](#2-icon--label) · lines 95–118
+- [3. Icon in a badge](#3-icon-in-a-badge) · lines 120–133
+- [4. Icon only, label in a tooltip](#4-icon-only-label-in-a-tooltip) · lines 135–212
+  - [Several values: the icons side by side, every name in one tooltip](#several-values-the-icons-side-by-side-every-name-in-one-tooltip) · lines 160–212
+- [5. Enum → tone-mapped badge](#5-enum--tone-mapped-badge) · lines 214–227
+- [6. Multi-value enum, clustered](#6-multi-value-enum-clustered) · lines 229–241
+- [7. Link as an outline button](#7-link-as-an-outline-button) · lines 243–264
+- [8. Date, relative](#8-date-relative) · lines 266–303
+- [9. Ordinal scale (bounded integer)](#9-ordinal-scale-bounded-integer) · lines 305–353
+  - [Two variants the package draws: a step bar and a star](#two-variants-the-package-draws-a-step-bar-and-a-star) · lines 323–353
+- [10. Summary in the cell, detail in a popover](#10-summary-in-the-cell-detail-in-a-popover) · lines 355–405
+  - [A second example: what a row depends on](#a-second-example-what-a-row-depends-on) · lines 373–405
+- [11. Number or currency — Unproven](#11-number-or-currency--unproven) · lines 407–447
+- [12. Boolean](#12-boolean) · lines 449–479
+- [13. Progress bar — Unproven](#13-progress-bar--unproven) · lines 481–517
+  - [The compact form: `ProgressRing`](#the-compact-form-progressring) · lines 501–517
+- [14. Avatar and name — Unproven](#14-avatar-and-name--unproven) · lines 519–536
+- [15. Yes/no you flip in the row](#15-yesno-you-flip-in-the-row) · lines 538–647
+  - [A variant: a pressed icon inside another value's cell](#a-variant-a-pressed-icon-inside-another-values-cell) · lines 564–647
+- [16. Title linking to the record's view](#16-title-linking-to-the-records-view) · lines 649–684
+- [17. Quick action on the view](#17-quick-action-on-the-view) · lines 686–753
+- [18. Editable value](#18-editable-value) · lines 755–1170
+  - [A list of sub-items](#a-list-of-sub-items) · lines 1014–1071
+  - [In a table's rows](#in-a-tables-rows) · lines 1073–1158
+  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1160–1170
+- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1172–1238
+- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1240–1304
+- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1306–1371
+- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1373–1401
+
+<!-- /index -->
+
 How a column's value should *look*. Each entry is markup plus the bits a
 first attempt gets wrong — **not components**: the lookup maps are always
 per-entity, and only the shape is reusable. Copy the markup into your
@@ -375,14 +412,23 @@ A count, a quantity, a price.
 // Module scope: one formatter per column, not one per cell render.
 const priceFormatter = new Intl.NumberFormat(undefined, { style: 'currency', currency: 'USD' })
 
-cell: ({ getValue }) => {
-  const value = getValue<string | null>()
-  return value == null ? emptyCell : <span className="tabular-nums">{priceFormatter.format(Number(value))}</span>
+{
+  accessorKey: 'price',
+  header: 'Price',
+  meta: { align: 'right' },
+  cell: ({ getValue }) => {
+    const value = getValue<string | null>()
+    return value == null ? emptyCell : <span className="tabular-nums">{priceFormatter.format(Number(value))}</span>
+  },
 }
 ```
 
-- `tabular-nums` gives every digit the same width, so values line up down
-  the column even when left-aligned.
+- **Money and counts are right-aligned** (`meta: { align: 'right' }`), with
+  `tabular-nums`, so the units line up down the column and with the
+  `totals` under it. The header's label is right-aligned too, a sort
+  arrow on its left, so its right edge sits on the values'. A number
+  that's an identifier or a year (an order number, 2024) isn't a
+  quantity: leave it left-aligned like text.
 - **Zero is a value, not an empty cell.** Test `value == null`, never
   falsiness, or `0` renders as an em dash.
 - An API `format: decimal` arrives as a **string**. `Number()` is exact
@@ -396,10 +442,6 @@ cell: ({ getValue }) => {
   each value under its column in that column's alignment and tabular
   figures, above a 2px border. A hidden column's value isn't shown, and
   the row is hidden while loading, on error and when empty.
-- **Right-aligning isn't available yet.** `DataTable`'s `meta.align` only
-  supports `'center'`, and a right-aligned cell under a left-aligned header
-  looks broken. Stay left-aligned until a real column needs
-  `align: 'right'`, then raise it for the foundation.
 - The currency code comes from the data or the plan, never a guess. The
   template's `USD` is the demo's.
 - **Cost:** none to speak of. It's the plain-text pattern with formatting.

package/conventions/docs/design-language.md

@@ -1,5 +1,24 @@
 # Design Language
 
+<!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
+## Index
+
+- [Semantic tones](#semantic-tones) · lines 28–56
+- [The three badge styles](#the-three-badge-styles) · lines 58–75
+- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 77–106
+- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 108–121
+- [Logos and brand marks](#logos-and-brand-marks) · lines 123–167
+- [Categorical colour](#categorical-colour) · lines 169–239
+- [Typography](#typography) · lines 241–323
+  - [Written text (notes)](#written-text-notes) · lines 272–323
+- [Density](#density) · lines 325–382
+- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 384–459
+- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 461–519
+- [Notices](#notices) · lines 521–549
+- [A value over time](#a-value-over-time) · lines 551–584
+
+<!-- /index -->
+
 The part of this foundation a consuming app cannot cheaply get right on
 its own: color that carries meaning, checked for contrast in both themes.
 Tokens and styles here **grow freely**, in the foundation package, so every
@@ -275,7 +294,11 @@ renders as: 2 straight under the page's `<h1>` (a form, or a page that is
 the note), 3 under a section's `<h2>` (the default). `##` is one below it
 and `###` two below, never past `<h6>`, so the outline never skips a
 level (axe's heading-order). Only the element moves: each level keeps its
-look, and the editor saves `#` as `#`.
+look, and the editor saves `#` as `#`. Text pasted or imported from
+another tool often has no `#` and starts at `##`; `headingFrom="text"`
+puts the text's own highest heading at `headingLevel` instead, the rest
+keeping their distance from it (the editor reads it from the text it
+opens with). The text isn't rewritten.
 
 A table wider than the text scrolls sideways. While it does, its box is a
 tab stop and a region named "Table, scrolls sideways: " and its first
@@ -411,6 +434,12 @@ const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of
   default) and names the card's region, so the page's outline and its
   landmarks list every widget. Give each widget on a page a different
   title.
+- **More widgets than a phone screen holds:** make the ones read less
+  often `collapsible`, with a `storageKey` per widget
+  (`"<app>:hub.<widget>"`) so a card folded stays folded on that device,
+  and `defaultCollapsed` for one that should start folded. The chevron
+  at the header's end is named by the title; the header's link stays
+  while folded.
 - **A row is one line:** its text is a link (`to` for a route in the
   app, `href` for an external address, which opens in a new tab with the
   external-link mark) or plain text, cut with an ellipsis, the whole of
@@ -518,3 +547,38 @@ under its own header.
   region in its place, so one appearing or clearing later is announced.
   Elsewhere, put it in a status region that is rendered before it
   changes.
+
+## A value over time
+
+`LineChart` (4.34) is the one chart: a single series on a record's page
+(a price checked daily, a weight, a balance), oldest first, with an
+optional dashed `target` and one point marked (`mark`: `'min'`, `'max'`
+or `'last'`) with its value.
+
+```tsx
+<LineChart
+  label="Price over time"
+  points={data.history.map(({ checkedOn, price }) => ({ x: checkedOn, y: Number(price) }))}
+  target={{ y: Number(data.targetPrice), label: 'Buy at' }}
+  mark="min"
+  formatY={usd}
+  formatX={(x) => formatPlainDate(String(x), { month: 'short', day: 'numeric' })}
+  isLoading={isLoading}
+/>
+```
+
+- **Points sit apart by their x** when every x is a day (`'YYYY-MM-DD'`)
+  or a number, so a gap in the checks shows as a gap; otherwise they're
+  evenly spaced.
+- **The colours are fixed:** the line in `info-text`, the target in
+  `success-text`, each clearing 3:1 on a card in both themes. Don't
+  restyle them; a chart that needs another meaning (a limit not to
+  cross) is a request for the foundation.
+- **It owns its states:** a skeleton at `height` while loading, one
+  quiet line with no points (`emptyMessage`), a dot for one point.
+- **A screen reader gets the values, not the picture:** the figure is
+  named by `label`, with a summary (first, last, lowest, highest, the
+  target) and a table of every point. Give it the same `formatY` and
+  `formatX` the page uses for those values elsewhere.
+- One series and a few dozen points. Several series, zoom or tooltips
+  are a request for the foundation, not a hand-drawn chart in the app.

package/conventions/docs/reminders.md

@@ -13,8 +13,8 @@ to the device, where the app's service worker shows it.
 | `usePushPermission()` | the package | Whether this device gets reminders, and `enable`/`disable` |
 | `AllowReminders` | the package | The control: says what reminders are, then asks, on a click |
 | `/push/public-key`, `/push/subscriptions` | `openapi.yaml`, the foundation's part (optional) | The VAPID key to subscribe with; this device's subscription saved or dropped |
-| `app/push.py` | the reference backend | `send_push(session, user_id, title, body, url)`: encrypted (RFC 8291), signed (VAPID), to every device the user allowed |
-| `app/reminders.py`, `reminders` | the reference backend | A reminder row (when, which days, the text, the path), and the `send-reminders` job that sends each one when it's due |
+| `foundation_backend.push` | `ui-foundation-backend` | `send_push(session, user_id, title, body, url)`: encrypted (RFC 8291), signed (VAPID), to every device the user allowed |
+| `foundation_backend.reminders`, `reminders` | `ui-foundation-backend` | A reminder row (when, which days, the text, the path), and the `send-reminders` job that sends each one when it's due |
 
 Off until the backend turns it on (`PUSH_ENABLED`, `docs/deploy.md`
 "Reminders (Web Push)"). An app without reminders leaves `/push/*` out of
@@ -82,4 +82,4 @@ reads `mock` and never subscribes: screens show the `mock` state, and a
 Playwright spec checks it the same way. The rest is the backend's: its
 tests decrypt every message as a browser would. To try it end to end, run
 the real backend with push on, allow reminders in the browser, then
-`backend/scripts/send_test_push.py <email>`.
+`python -m foundation_backend.scripts.send_test_push <email>` (from `backend/`).

package/conventions/docs/timed-screens.md

@@ -1,5 +1,18 @@
 # Timed Screens
 
+<!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
+## Index
+
+- [The view](#the-view) · lines 34–69
+- [The clock](#the-clock) · lines 71–101
+- [Sound](#sound) · lines 103–150
+- [Background tabs](#background-tabs) · lines 152–206
+  - [Interruptions](#interruptions) · lines 186–206
+- [Motion](#motion) · lines 208–212
+- [Testing a timed screen in Playwright](#testing-a-timed-screen-in-playwright) · lines 214–368
+
+<!-- /index -->
+
 A screen that runs on its own for minutes: a paced timer, a step-by-step
 player, a recipe step, anything followed from across the room. The
 package has the parts, so a screen like this is assembled, not rebuilt:

package/dist/components/app/app-shell-bottom-bar.d.ts

@@ -0,0 +1,11 @@
+import { type BottomBarItem, type NavEntry } from './app-shell-nav.js';
+/**
+ * What the shell pads its content's bottom by on a phone: its own p-6,
+ * plus the bar (4rem and its 1px border) and the phone's safe area.
+ */
+export declare const BOTTOM_BAR_PADDING = "max-md:pb-[calc(--spacing(22)+1px+env(safe-area-inset-bottom))]";
+export declare function BottomBar({ items, nav, activeTo, }: {
+    items: readonly BottomBarItem[];
+    nav: readonly NavEntry[];
+    activeTo: string | undefined;
+}): import("react").JSX.Element;

package/dist/components/app/app-shell-bottom-bar.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// AppShell's bottom bar on a phone (#240): Home and a few of the nav's
+// sections in thumb reach, where the sidebar is a sheet behind the
+// header's menu button. An item is a link, or a nav section by its label,
+// which opens a sheet from the bottom listing that section's entries (and
+// their children, under them). The sheet closes on navigation, as the
+// sidebar's does. The item holding the current page is marked
+// (`aria-current`). Shown below the md breakpoint only (the sidebar's own
+// mobile breakpoint); the shell pads its content by the bar's height and
+// the phone's safe area, so a page's last row clears it.
+import { useState } from 'react';
+import { Link, useLocation } from 'react-router';
+import { bottomBarCurrent, bottomBarSection } from './app-shell-nav.js';
+import { Sheet, SheetContent, SheetHeader, SheetTitle } from '../ui/sheet.js';
+const ITEM_CLASS = 'flex min-w-0 flex-1 flex-col items-center justify-center gap-0.5 rounded-md px-1 type-caption text-muted-foreground ' +
+    'outline-none focus-visible:ring-3 focus-visible:ring-ring/50 aria-[current]:text-foreground aria-[current]:font-medium ' +
+    '[&>svg]:size-5 [&>svg]:shrink-0';
+const SHEET_LINK_CLASS = 'flex min-h-11 items-center gap-3 rounded-md px-3 type-body text-foreground outline-none ' +
+    'hover:bg-accent focus-visible:ring-3 focus-visible:ring-ring/50 aria-[current=page]:bg-accent aria-[current=page]:font-medium ' +
+    '[&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-muted-foreground';
+/**
+ * What the shell pads its content's bottom by on a phone: its own p-6,
+ * plus the bar (4rem and its 1px border) and the phone's safe area.
+ */
+export const BOTTOM_BAR_PADDING = 'max-md:pb-[calc(--spacing(22)+1px+env(safe-area-inset-bottom))]';
+function SheetLinks({ items, activeTo }) {
+    return (_jsx("ul", { className: "flex flex-col gap-0.5", children: items.map(({ to, label, icon: Icon, children }) => (_jsxs("li", { children: [_jsxs(Link, { to: to, "aria-current": to === activeTo ? 'page' : undefined, className: SHEET_LINK_CLASS, children: [_jsx(Icon, {}), _jsx("span", { className: "truncate", children: label })] }), children && children.length > 0 && (_jsx("div", { className: "ml-5 border-l border-border pl-2", children: _jsx(SheetLinks, { items: children, activeTo: activeTo }) }))] }, to))) }));
+}
+export function BottomBar({ items, nav, activeTo, }) {
+    // The section open, and the location it was opened at: following a link
+    // in the sheet (or anywhere) moves to a new location, which closes it.
+    const [opened, setOpened] = useState(null);
+    const { key } = useLocation();
+    const openGroup = opened?.at === key ? opened.group : null;
+    const setOpenGroup = (group) => setOpened(group === null ? null : { group, at: key });
+    // At most five: a sixth wouldn't fit a phone's width with its label.
+    const shown = items.slice(0, 5);
+    const current = bottomBarCurrent(shown, nav, activeTo);
+    const section = openGroup === null ? undefined : bottomBarSection(nav, openGroup);
+    return (_jsxs(_Fragment, { children: [_jsx("nav", { "aria-label": "Bottom bar", "data-slot": "app-shell-bottom-bar", className: "fixed inset-x-0 bottom-0 z-20 border-t border-border bg-background pb-[env(safe-area-inset-bottom)] md:hidden", children: _jsx("ul", { className: "flex h-16 items-stretch gap-1 px-2 py-1.5", children: shown.map((item, index) => {
+                        const Icon = item.icon;
+                        const isCurrent = index === current;
+                        if ('to' in item) {
+                            return (_jsx("li", { className: "flex min-w-0 flex-1", children: _jsxs(Link, { to: item.to, "aria-current": isCurrent ? 'page' : undefined, className: ITEM_CLASS, children: [_jsx(Icon, { "aria-hidden": "true" }), _jsx("span", { className: "max-w-full truncate", children: item.label })] }) }, `to:${item.to}`));
+                        }
+                        const label = item.label ?? item.group;
+                        return (_jsx("li", { className: "flex min-w-0 flex-1", children: _jsxs("button", { type: "button", "aria-haspopup": "dialog", "aria-expanded": openGroup === item.group, "aria-current": isCurrent ? 'true' : undefined, onClick: () => setOpenGroup(item.group), className: ITEM_CLASS, children: [_jsx(Icon, { "aria-hidden": "true" }), _jsx("span", { className: "max-w-full truncate", children: label })] }) }, `group:${item.group}`));
+                    }) }) }), _jsx(Sheet, { open: section !== undefined, onOpenChange: (open) => !open && setOpenGroup(null), children: _jsx(SheetContent, { side: "bottom", className: "max-h-[80dvh] gap-2 pb-[calc(--spacing(4)+env(safe-area-inset-bottom))] md:hidden", children: section && (_jsxs(_Fragment, { children: [_jsx(SheetHeader, { className: "pb-0", children: _jsx(SheetTitle, { children: section.label }) }), _jsx("nav", { "aria-label": section.label, className: "overflow-y-auto px-2", children: _jsx(SheetLinks, { items: section.items, activeTo: activeTo }) })] })) }) })] }));
+}

package/dist/components/app/app-shell-nav.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentType } from 'react';
+import type { IconComponent } from './icon-component.js';
 export type NavItem = {
     /**
      * The route this entry links to. It may carry a query string, to open a
@@ -10,6 +11,15 @@ export type NavItem = {
     icon: ComponentType;
     /** Active only on an exact match (use for '/'); otherwise on any sub-path too. */
     end?: boolean;
+    /**
+     * A module's own pages, listed under this entry (one level deep): its
+     * channels under YouTube, its series under Comics. They show while the
+     * page is this entry or one of them (`open: 'current'`), or always
+     * (`'always'`). On the icon rail they're named in this entry's tooltip.
+     */
+    children?: readonly NavItem[];
+    /** When `children` show: while you're in them (`'current'`, the default) or `'always'`. */
+    open?: 'current' | 'always';
 };
 /** A labelled group of sidebar entries: one module's pages, say. */
 export type NavSection = {
@@ -42,6 +52,15 @@ export type NavGroup = {
  * labelled group, and each run of plain items between them an unlabelled one.
  */
 export declare function navGroups(nav: readonly NavEntry[]): NavGroup[];
+/** Each item and, after it, its children: every page a list of items links. */
+export declare function withChildren(items: readonly NavItem[]): NavItem[];
+/** Every page in a nav, sections' items and children included, in order. */
+export declare function navItems(nav: readonly NavEntry[]): NavItem[];
+/**
+ * Whether an item's children show: always, or while the current page
+ * (`activeTo`) is the item or one of its children.
+ */
+export declare function childrenOpen(item: NavItem, activeTo: string | undefined): boolean;
 /**
  * The path a `to` names, without its query string or hash: what an entry is
  * matched on, and what the a11y suite compares with the rendered sidebar.
@@ -65,3 +84,25 @@ export declare function activeNavTo(nav: readonly NavEntry[], pathname: string):
  * itself, or on a page no entry covers.
  */
 export declare function navPageLabel(nav: readonly NavEntry[], pathname: string): string | undefined;
+/**
+ * One item of `AppShell`'s `bottomBar`, the phone's bar of shortcuts: a
+ * page, or one of the nav's sections by its label, which opens a sheet of
+ * that section's entries. `label` is a shorter name for the bar
+ * ("Household" for "Home and money").
+ */
+export type BottomBarItem = {
+    to: string;
+    label: string;
+    icon: IconComponent;
+} | {
+    group: string;
+    label?: string;
+    icon: IconComponent;
+};
+/** The nav's section with this label, if there is one. */
+export declare function bottomBarSection(nav: readonly NavEntry[], label: string): NavSection | undefined;
+/**
+ * Which bar item holds the current page (`activeTo`, from activeNavTo):
+ * the page's own link, or else the section it's in, children included.
+ */
+export declare function bottomBarCurrent(items: readonly BottomBarItem[], nav: readonly NavEntry[], activeTo: string | undefined): number | undefined;

package/dist/components/app/app-shell-nav.js

@@ -30,6 +30,23 @@ export function navGroups(nav) {
         groups.push({ items: run });
     return groups;
 }
+/** Each item and, after it, its children: every page a list of items links. */
+export function withChildren(items) {
+    return items.flatMap((item) => [item, ...(item.children ?? [])]);
+}
+/** Every page in a nav, sections' items and children included, in order. */
+export function navItems(nav) {
+    return nav.flatMap((entry) => withChildren(isNavSection(entry) ? entry.items : [entry]));
+}
+/**
+ * Whether an item's children show: always, or while the current page
+ * (`activeTo`) is the item or one of its children.
+ */
+export function childrenOpen(item, activeTo) {
+    if (!item.children?.length)
+        return false;
+    return item.open === 'always' || item.to === activeTo || item.children.some((child) => child.to === activeTo);
+}
 /**
  * The path a `to` names, without its query string or hash: what an entry is
  * matched on, and what the a11y suite compares with the rendered sidebar.
@@ -40,7 +57,7 @@ export function navPathname(to) {
 }
 /** Every `to` in a nav, each once, in order: the pages its sidebar links. */
 export function navTargets(nav) {
-    return [...new Set(nav.flatMap((entry) => (isNavSection(entry) ? entry.items : [entry]).map((item) => item.to)))];
+    return [...new Set(navItems(nav).map((item) => item.to))];
 }
 function matches(path, end, pathname) {
     if (end)
@@ -61,13 +78,11 @@ function matches(path, end, pathname) {
 export function activeNavItem(nav, pathname) {
     let best;
     let bestLength = -1;
-    for (const entry of nav) {
-        for (const item of isNavSection(entry) ? entry.items : [entry]) {
-            const path = navPathname(item.to);
-            if (matches(path, item.end, pathname) && path.length > bestLength) {
-                best = item;
-                bestLength = path.length;
-            }
+    for (const item of navItems(nav)) {
+        const path = navPathname(item.to);
+        if (matches(path, item.end, pathname) && path.length > bestLength) {
+            best = item;
+            bestLength = path.length;
         }
     }
     return best;
@@ -85,3 +100,20 @@ export function navPageLabel(nav, pathname) {
     const item = activeNavItem(nav, pathname);
     return item && navPathname(item.to) !== '/' ? item.label : undefined;
 }
+/** The nav's section with this label, if there is one. */
+export function bottomBarSection(nav, label) {
+    return nav.find((entry) => isNavSection(entry) && entry.label === label);
+}
+/**
+ * Which bar item holds the current page (`activeTo`, from activeNavTo):
+ * the page's own link, or else the section it's in, children included.
+ */
+export function bottomBarCurrent(items, nav, activeTo) {
+    if (activeTo === undefined)
+        return undefined;
+    const link = items.findIndex((item) => 'to' in item && item.to === activeTo);
+    if (link !== -1)
+        return link;
+    const group = items.findIndex((item) => 'group' in item && withChildren(bottomBarSection(nav, item.group)?.items ?? []).some((entry) => entry.to === activeTo));
+    return group === -1 ? undefined : group;
+}

package/dist/components/app/app-shell.d.ts

@@ -1,8 +1,8 @@
 import { type ReactNode } from 'react';
-import { type NavEntry } from './app-shell-nav.js';
+import { type BottomBarItem, type NavEntry } from './app-shell-nav.js';
 import { type AppShellVersion } from './app-shell-version.js';
 import type { IconComponent } from './icon-component.js';
-export type { NavEntry, NavItem, NavSection } from './app-shell-nav.js';
+export type { BottomBarItem, NavEntry, NavItem, NavSection } from './app-shell-nav.js';
 export type { AppShellVersion } from './app-shell-version.js';
 export type AppShellProps = {
     /**
@@ -30,7 +30,8 @@ export type AppShellProps = {
      * open a list on a saved view ('/tasks?status=open'). A section marked `collapsible` folds under its label,
      * remembered per browser (`defaultOpen` for the first visit); the one
      * holding the current page stays open, and the icon rail shows every
-     * section's items.
+     * section's items. An entry's `children` (a module's own pages) show
+     * under it while you're on one of them.
      */
     nav: readonly NavEntry[];
     /**
@@ -52,5 +53,15 @@ export type AppShellProps = {
      * `@tristan2828/ui-foundation/vite` (`import.meta.env.VITE_BUILD_*`).
      */
     version?: AppShellVersion;
+    /**
+     * A bar of shortcuts at the bottom of a phone's screen (below the md
+     * breakpoint), in thumb reach: at most five, each a page
+     * (`{ to, label, icon }`) or a nav section by its label
+     * (`{ group: 'Every day', icon }`, with an optional shorter `label`),
+     * which opens a sheet of that section's entries. The item holding the
+     * current page is marked. The header's menu button stays, for
+     * everything. The shell pads its content so nothing sits under the bar.
+     */
+    bottomBar?: readonly BottomBarItem[];
 };
-export declare function AppShell({ title, logo: Logo, nav, sidebarExtra, defaultSidebarOpen, version }: AppShellProps): import("react").JSX.Element;
+export declare function AppShell({ title, logo: Logo, nav, sidebarExtra, defaultSidebarOpen, version, bottomBar, }: AppShellProps): import("react").JSX.Element;

package/dist/components/app/app-shell.js

@@ -4,7 +4,8 @@ import { useTheme } from 'next-themes';
 import { useEffect, useId, useState } from 'react';
 import { Link, Navigate, Outlet, useLocation } from 'react-router';
 import { useAuth } from '../../auth/use-auth.js';
-import { activeNavTo, navGroups, navPageLabel } from './app-shell-nav.js';
+import { BottomBar, BOTTOM_BAR_PADDING } from './app-shell-bottom-bar.js';
+import { activeNavTo, childrenOpen, navGroups, navPageLabel, withChildren, } from './app-shell-nav.js';
 import { versionHref, versionLabel } from './app-shell-version.js';
 import { ErrorState } from './error-state.js';
 import { useErrorReporter } from '../../error-reporting/error-reporting-context.js';
@@ -13,7 +14,7 @@ import { useShellDocumentTitle } from '../../hooks/use-document-title.js';
 import { cn } from 'cn';
 import { Button } from '../ui/button.js';
 import { Skeleton } from '../ui/skeleton.js';
-import { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider, SidebarTrigger, useSidebar, } from '../ui/sidebar.js';
+import { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarTrigger, useSidebar, } from '../ui/sidebar.js';
 import { Toaster } from '../ui/sonner.js';
 import { TooltipProvider } from '../ui/tooltip.js';
 // Must match SIDEBAR_COOKIE_NAME in ../ui/sidebar.tsx, which writes the
@@ -52,10 +53,23 @@ function VersionEntry({ version }) {
 // One group's entries. A plain Link, not NavLink: NavLink marks every
 // matching entry current, and only the most specific one should be
 // (activeNavTo).
+//
+// An entry's children (#239) are a list inside its item, so they're read
+// as its pages, shown while you're in them (childrenOpen) and otherwise
+// in the page but hidden, as a folded section's are. The icon rail has no
+// room for them: there the entry looks current while one of them is, and
+// its tooltip names them.
 function NavMenu({ items, activeTo }) {
-    return (_jsx(SidebarMenu, { children: items.map(({ to, label, icon: Icon }) => {
+    const { state, isMobile } = useSidebar();
+    const rail = state === 'collapsed' && !isMobile;
+    return (_jsx(SidebarMenu, { children: items.map((item) => {
+            const { to, label, icon: Icon, children } = item;
             const isActive = to === activeTo;
-            return (_jsx(SidebarMenuItem, { children: _jsxs(SidebarMenuButton, { isActive: isActive, tooltip: label, render: _jsx(Link, { to: to, "aria-current": isActive ? 'page' : undefined }), children: [_jsx(Icon, {}), _jsx("span", { children: label })] }) }, to));
+            const childActive = children?.some((child) => child.to === activeTo) ?? false;
+            return (_jsxs(SidebarMenuItem, { children: [_jsxs(SidebarMenuButton, { isActive: isActive || (rail && childActive), tooltip: children?.length ? `${label}: ${children.map((child) => child.label).join(', ')}` : label, render: _jsx(Link, { to: to, "aria-current": isActive ? 'page' : undefined }), children: [_jsx(Icon, {}), _jsx("span", { children: label })] }), children && children.length > 0 && (_jsx(SidebarMenuSub, { hidden: !childrenOpen(item, activeTo), children: children.map(({ to: childTo, label: childLabel, icon: ChildIcon }) => {
+                            const isChildActive = childTo === activeTo;
+                            return (_jsx(SidebarMenuSubItem, { children: _jsxs(SidebarMenuSubButton, { isActive: isChildActive, render: _jsx(Link, { to: childTo, "aria-current": isChildActive ? 'page' : undefined }), children: [_jsx(ChildIcon, {}), _jsx("span", { children: childLabel })] }) }, childTo));
+                        }) }))] }, to));
         }) }));
 }
 // Whether a collapsible section is open, remembered per browser by its
@@ -88,7 +102,7 @@ function CollapsibleNavGroup({ group, activeTo }) {
     const { state, isMobile } = useSidebar();
     const contentId = useId();
     const [stored, setStored] = useState(() => storedSectionOpen(group.label));
-    const holdsCurrent = group.items.some((item) => item.to === activeTo);
+    const holdsCurrent = withChildren(group.items).some((item) => item.to === activeTo);
     // Arriving in a folded section unfolds it, and it stays unfolded after.
     if (holdsCurrent && stored !== true)
         setStored(true);
@@ -110,7 +124,7 @@ function CollapsibleNavGroup({ group, activeTo }) {
 function AppShellSkeleton() {
     return (_jsxs("div", { className: "flex h-screen w-full gap-4 p-4", "data-state": "loading", children: [_jsx(Skeleton, { className: "h-full w-56 shrink-0" }), _jsxs("div", { className: "flex-1 space-y-4 pt-2", children: [_jsx(Skeleton, { className: "h-8 w-64" }), _jsx(Skeleton, { className: "h-40 w-full" })] })] }));
 }
-export function AppShell({ title, logo: Logo, nav, sidebarExtra, defaultSidebarOpen = true, version }) {
+export function AppShell({ title, logo: Logo, nav, sidebarExtra, defaultSidebarOpen = true, version, bottomBar, }) {
     const { user, status, error, retry, logout } = useAuth();
     const location = useLocation();
     const reporter = useErrorReporter();
@@ -146,5 +160,5 @@ export function AppShell({ title, logo: Logo, nav, sidebarExtra, defaultSidebarO
                                                         // (AuthProvider), so this stays a deliberate logout: a
                                                         // clean /login, never the previous user's page as `from`.
                                                         logout().catch(() => { });
-                                                    }, children: _jsx(LogOutIcon, {}) })] })] })] }) }), _jsxs(SidebarInset, { className: "min-w-0", children: [_jsxs("header", { className: "flex h-14 shrink-0 items-center gap-2 border-b border-border px-4", children: [_jsx(SidebarTrigger, {}), _jsx("div", { className: "flex-1" }), _jsx(ThemeToggle, {})] }), _jsx("div", { className: "flex-1 p-6", children: _jsx(Outlet, {}) })] })] }), _jsx(Toaster, { position: "top-center" })] }));
+                                                    }, children: _jsx(LogOutIcon, {}) })] })] })] }) }), _jsxs(SidebarInset, { className: "min-w-0", children: [_jsxs("header", { className: "flex h-14 shrink-0 items-center gap-2 border-b border-border px-4", children: [_jsx(SidebarTrigger, {}), _jsx("div", { className: "flex-1" }), _jsx(ThemeToggle, {})] }), _jsx("div", { className: cn('flex-1 p-6', bottomBar?.length && BOTTOM_BAR_PADDING), children: _jsx(Outlet, {}) })] }), bottomBar && bottomBar.length > 0 && _jsx(BottomBar, { items: bottomBar, nav: nav, activeTo: activeTo })] }), _jsx(Toaster, { position: "top-center" })] }));
 }

package/dist/components/app/data-table.d.ts

@@ -9,7 +9,7 @@ export type SortingState = {
 }[];
 declare module '@tanstack/table-core' {
     interface ColumnMeta<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData> {
-        align?: 'center';
+        align?: 'center' | 'right';
     }
 }
 export type DataTableProps<TData extends Record<string, unknown>> = {