@tristan2828/ui-foundation 4.38.0 → 4.40.0

package/conventions/docs/design-language.md

@@ -3,20 +3,21 @@
 <!-- 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 29–57
-- [The three badge styles](#the-three-badge-styles) · lines 59–76
-- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 78–107
-- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 109–122
-- [Logos and brand marks](#logos-and-brand-marks) · lines 124–168
-- [Categorical colour](#categorical-colour) · lines 170–240
-- [Typography](#typography) · lines 242–324
-  - [Written text (notes)](#written-text-notes) · lines 273–324
-- [Density](#density) · lines 326–383
-- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 385–463
-- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 465–523
-- [Notices](#notices) · lines 525–553
-- [A value over time](#a-value-over-time) · lines 555–588
-- [A list as a board](#a-list-as-a-board) · lines 590–641
+- [Semantic tones](#semantic-tones) · lines 30–58
+- [The three badge styles](#the-three-badge-styles) · lines 60–77
+- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 79–108
+- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 110–123
+- [Logos and brand marks](#logos-and-brand-marks) · lines 125–169
+- [Categorical colour](#categorical-colour) · lines 171–241
+- [Typography](#typography) · lines 243–325
+  - [Written text (notes)](#written-text-notes) · lines 274–325
+- [Density](#density) · lines 327–384
+- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 386–464
+- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 466–524
+- [Notices](#notices) · lines 526–554
+- [A value over time](#a-value-over-time) · lines 556–589
+- [A list as a board](#a-list-as-a-board) · lines 591–642
+- [A list as cards](#a-list-as-cards) · lines 644–690
 
 <!-- /index -->
 
@@ -639,3 +640,51 @@ the table's.
   columns share the width, at least 16rem each, and scroll sideways with
   snap points; a phone shows one column at a time, with the edge of the
   next one showing.
+
+## A list as cards
+
+`DataTable`'s `layouts` (4.39) draw the same rows as cards beside the
+table: a thumbnail grid for a feed, covers for a collection, a dense line
+each for clearing a backlog. They are layouts of one list, not other
+pages: the toolbar, filters, saved views, paging and `groupBy` headings
+are the table's in every one, and so are its loading, empty and error
+states.
+
+```tsx
+const { layout, setLayout } = useTableLayout({
+  layouts: ['table', 'covers'],
+  defaultLayout: 'covers',
+  storageKey: 'my-app:books:layout',
+})
+
+<DataTable
+  {...tableProps}
+  layouts={[{ id: 'covers', label: 'Covers', icon: LayoutGridIcon, size: 'sm', aspect: '2:3', renderCard: (book) => <BookCard book={book} /> }]}
+  layout={layout}
+  onLayoutChange={setLayout}
+/>
+```
+
+- **The switch** sits at the end of the toolbar, the table first (rename
+  it with `tableLayout`, "Rows" for a list-like table with no header).
+  The pick is in the URL (`?layout=`) and remembered per table on the
+  device, so name the `storageKey` for the list. A list opens on the
+  layout it is read in most: covers for something browsed by its art, the
+  table for something compared by its columns.
+- **A grid's sizes** are the package's: `sm` for covers (three across on
+  a phone), `md` for thumbnails (two), `lg` for big ones (one). `list`
+  is one card per line in a bordered box, divided like rows.
+- **The picture** is `Artwork`: a fixed shape (2:3 posters and books,
+  1:1 square art, 16:9 video), the record's image or a neutral
+  placeholder (the list's icon, and the title where most records have no
+  picture), so the grid's rows stay even. Its corners hold an
+  `ArtworkTag` (a length, "Live") and an `ArtworkToggle`, a round button
+  that marks the record (Read, Owned): dark on the picture while off,
+  success's fill while on.
+- **The card holds what the row does**: the title as the link to the
+  record (cell pattern 16), the list's key line in muted text, then its
+  status, rating or quality as the table's own cells draw them, and the
+  same actions. A card leaves an empty value out rather than showing a
+  dash. Never an action only one layout has.
+- `totals` and `highlightRow` are the table's alone. Sorting is the
+  toolbar's in a card layout (there is no header to click).

package/conventions/docs/timed-screens.md

@@ -3,13 +3,14 @@
 <!-- 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
+- [The view](#the-view) · lines 36–109
+  - [The dark stage](#the-dark-stage) · lines 73–109
+- [The clock](#the-clock) · lines 111–141
+- [Sound](#sound) · lines 143–190
+- [Background tabs](#background-tabs) · lines 192–246
+  - [Interruptions](#interruptions) · lines 226–246
+- [Motion](#motion) · lines 248–252
+- [Testing a timed screen in Playwright](#testing-a-timed-screen-in-playwright) · lines 254–408
 
 <!-- /index -->
 
@@ -19,7 +20,8 @@ package has the parts, so a screen like this is assembled, not rebuilt:
 
 | Part | What it does |
 |---|---|
-| `SessionView` | The whole viewport over the app shell: a modal named by its title, focus kept inside, Esc closes it. Optional real fullscreen and a held wake lock |
+| `SessionView` | The whole viewport over the app shell: a modal named by its title, focus kept inside, Esc closes it. Optional real fullscreen, a held wake lock, and `dark` for the dark stage |
+| `SessionStage`, `sessionStageLit`, `sessionStageMain`, `sessionStageQuiet` | The stage under the header: a tone, a glow of it behind the centre, the time lit in it, quiet outline controls |
 | `useSessionClock` | A clock that doesn't drift, with pause, resume and seek: `idle`, `running`, `done` |
 | `useWakeLock` | Keeps the screen on while a session runs (`SessionView`'s `keepAwake` uses it) |
 | `unlockAudio`, `chime`, `sequence`, `cancelCues`, `say`, `hush`, `vibrate` | Sound cues with no audio files, booked ahead where they must be on time |
@@ -29,7 +31,7 @@ package has the parts, so a screen like this is assembled, not rebuilt:
 
 All of them are imported from `@tristan2828/ui-foundation`. The package's
 Storybook has the whole thing working together: `app/SessionView`, the
-Timer story.
+Timer story, and the same run on the dark stage, DarkStage.
 
 ## The view
 
@@ -68,6 +70,44 @@ const primary = useRef<HTMLButtonElement>(null)
   piece by piece. That fights the primitive's own classes on every
   upgrade, and gets the details above wrong.
 
+### The dark stage
+
+For a screen followed in a dim room: always dark while it runs, whatever
+the app's theme. A black stage, the time lit in the phase's colour with a
+soft glow of it behind, everything else dimmed, the controls quiet
+outlines.
+
+```tsx
+<SessionView open onOpenChange={close} title="Timer" dark={darkStage}>
+  <SessionStage tone={darkStage ? phaseTone : 'neutral'} glow={darkStage}>
+    <div role="timer" className={cn('font-mono text-[17cqi]', darkStage && sessionStageLit)}>{time}</div>
+    <Button variant="outline" className={cn(darkStage && sessionStageQuiet)}>Skip</Button>
+  </SessionStage>
+</SessionView>
+```
+
+- **`dark` scopes the dark tokens to the view.** It puts theme.css's
+  `.dark` on the view itself, so every token and `dark:` variant inside
+  is the dark theme's and the page under it keeps its own. A popup opened
+  from the view (a menu, a select) portals to `<body>` and keeps the app's
+  theme.
+- **`SessionStage`** is the box the run draws in, filling the view below
+  the header. `tone` is the phase's (`neutral`, `success`, `info`,
+  `warning`, `destructive`); `glow` washes it behind the centre, faintly
+  for `neutral`. It sets `--stage-tone` and `--stage-tone-text` for
+  what's inside.
+- **`sessionStageLit`** on the big time: the tone's text shade (white
+  for `neutral`) with a glow around the figures. **`sessionStageQuiet`**
+  on an outline `Button`: no fill, a faint border, dimmed text that
+  brightens on hover. **`sessionStageMain`** on the main control (Start,
+  Done, `variant="outline"`): an outline too, in the foreground colour.
+- **Contrast is checked in dark only**, since the stage is never light:
+  the package's axe run covers the DarkStage story in both app themes. An
+  app's own Playwright runs axe on its screen with the stage on, under a
+  light and a dark app theme.
+- **Make it a setting**, remembered per device like Mute, when the app's
+  own look is the default: off, the view and stage are as before.
+
 ## The clock
 
 `useSessionClock({ running?, endsAt? })` returns

package/dist/components/app/artwork.d.ts

@@ -0,0 +1,43 @@
+import { type ReactNode } from 'react';
+import type { IconComponent } from './icon-component.js';
+export type ArtworkAspect = '2:3' | '1:1' | '16:9';
+export type ArtworkProps = {
+    /** The image's URL; null or undefined for the placeholder. */
+    src?: string | null;
+    alt?: string;
+    aspect: ArtworkAspect;
+    /** The placeholder's icon (the list's own: a book, a die); a picture icon when left out. */
+    placeholderIcon?: IconComponent;
+    /** Words under the placeholder's icon, often the title, for a grid where most records have no picture. */
+    placeholderLabel?: ReactNode;
+    topStart?: ReactNode;
+    topEnd?: ReactNode;
+    bottomStart?: ReactNode;
+    bottomEnd?: ReactNode;
+    /** Dims the picture (a watched video), never its overlays. */
+    dimmed?: boolean;
+    className?: string;
+};
+export declare function Artwork({ src, alt, aspect, placeholderIcon: PlaceholderIcon, placeholderLabel, topStart, topEnd, bottomStart, bottomEnd, dimmed, className, }: ArtworkProps): import("react").JSX.Element;
+/**
+ * A small label on a picture (a length, "Live", "Short"): the page's
+ * foreground as its background, so it reads on any image in either theme.
+ */
+export declare function ArtworkTag({ children, className }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+export type ArtworkToggleProps = {
+    /** What it marks, with the record ("Read: Saga"), for a screen reader and the tooltip. */
+    label: string;
+    pressed: boolean;
+    onPressedChange: (pressed: boolean) => void;
+    icon: IconComponent;
+    disabled?: boolean;
+};
+/**
+ * A round button on a picture that marks the record (Read, Owned): dark
+ * on the picture while off, success's solid fill while on, so it reads on
+ * any image. Goes in one of Artwork's corners.
+ */
+export declare function ArtworkToggle({ label, pressed, onPressedChange, icon: Icon, disabled }: ArtworkToggleProps): import("react").JSX.Element;

package/dist/components/app/artwork.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A card's picture (DataTable's card layouts): a box of a fixed shape, a
+// poster's 2:3, a square cover's 1:1 or a video's 16:9, holding the
+// record's image, or a neutral placeholder when it has none (or it fails
+// to load), so a grid of cards keeps its rows even. Overlays sit on top:
+// `topStart`/`topEnd`/`bottomStart`/`bottomEnd` corners for a badge, a
+// length, or a round button such as Read or Owned.
+//
+// The image is decorative by default (`alt=""`): the card's title, beside
+// it, already names the record. Give `alt` only when the picture says
+// something the card doesn't.
+import { useState } from 'react';
+import { ImageIcon } from 'lucide-react';
+import { cn } from 'cn';
+const ASPECT_CLASS = {
+    '2:3': 'aspect-[2/3]',
+    '1:1': 'aspect-square',
+    '16:9': 'aspect-video',
+};
+const CORNER_CLASS = 'absolute z-10 flex items-center gap-1';
+export function Artwork({ src, alt = '', aspect, placeholderIcon: PlaceholderIcon = ImageIcon, placeholderLabel, topStart, topEnd, bottomStart, bottomEnd, dimmed, className, }) {
+    // The src that failed, so a new one gets its own try.
+    const [failed, setFailed] = useState(null);
+    const showImage = Boolean(src) && failed !== src;
+    return (_jsxs("div", { "data-slot": "artwork", "data-aspect": aspect, className: cn('relative w-full overflow-hidden rounded-md bg-muted', ASPECT_CLASS[aspect], className), children: [showImage ? (_jsx("img", { src: src ?? undefined, alt: alt, loading: "lazy", decoding: "async", onError: () => setFailed(src ?? null), className: cn('size-full object-cover', dimmed && 'opacity-55') })) : (_jsxs("div", { "data-slot": "artwork-placeholder", className: cn('flex size-full flex-col items-center justify-center gap-2 p-3 text-center text-muted-foreground', dimmed && 'opacity-55'), children: [_jsx(PlaceholderIcon, { "aria-hidden": "true", className: "size-6 shrink-0" }), placeholderLabel && (_jsx("span", { className: "type-caption line-clamp-3 text-balance text-foreground", children: placeholderLabel }))] })), topStart && _jsx("div", { className: cn(CORNER_CLASS, 'top-1.5 left-1.5'), children: topStart }), topEnd && _jsx("div", { className: cn(CORNER_CLASS, 'top-1.5 right-1.5'), children: topEnd }), bottomStart && _jsx("div", { className: cn(CORNER_CLASS, 'bottom-1.5 left-1.5'), children: bottomStart }), bottomEnd && _jsx("div", { className: cn(CORNER_CLASS, 'right-1.5 bottom-1.5'), children: bottomEnd })] }));
+}
+/**
+ * A small label on a picture (a length, "Live", "Short"): the page's
+ * foreground as its background, so it reads on any image in either theme.
+ */
+export function ArtworkTag({ children, className }) {
+    return (_jsx("span", { "data-slot": "artwork-tag", className: cn('rounded-sm bg-foreground/85 px-1 font-mono text-[0.6875rem] leading-4 font-medium text-background tabular-nums', className), children: children }));
+}
+/**
+ * A round button on a picture that marks the record (Read, Owned): dark
+ * on the picture while off, success's solid fill while on, so it reads on
+ * any image. Goes in one of Artwork's corners.
+ */
+export function ArtworkToggle({ label, pressed, onPressedChange, icon: Icon, disabled }) {
+    return (_jsx("button", { type: "button", "aria-pressed": pressed, "aria-label": label, title: label, disabled: disabled, onClick: () => onPressedChange(!pressed), className: cn('grid size-8 place-items-center rounded-full outline-none focus-visible:ring-3 focus-visible:ring-ring/50', 'disabled:pointer-events-none disabled:opacity-50', pressed
+            ? 'bg-success text-success-foreground hover:bg-success/90'
+            : 'bg-foreground/85 text-background hover:bg-foreground'), children: _jsx(Icon, { "aria-hidden": "true", className: "size-4" }) }));
+}

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

@@ -2,6 +2,8 @@ import { type ReactNode } from 'react';
 import type { CellData, RowData, TableFeatures } from '@tanstack/react-table';
 import { type LegacyColumnDef } from '@tanstack/react-table/legacy';
 import type { AppError } from '../../api/contracts.js';
+import type { ArtworkAspect } from './artwork.js';
+import type { IconComponent } from './icon-component.js';
 import { type RowGroup } from './table-groups.js';
 export type SortingState = {
     id: string;
@@ -107,6 +109,52 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
      * has come) for no row.
      */
     totals?: DataTableTotals | null;
+    /**
+     * Card layouts besides the table (a thumbnail grid, covers, one line
+     * each), and a switch between them at the end of the toolbar, the table
+     * first. Each draws a row with its own `renderCard`; paging, `groupBy`
+     * headings and the loading, empty and error states hold in every one.
+     * The columns still define the table, and sorting is the toolbar's in a
+     * card layout. `totals` and `highlightRow` are the table's alone.
+     */
+    layouts?: readonly DataTableCardLayout<TData>[];
+    /**
+     * The layout showing: `'table'` or a card layout's id, from
+     * useTableLayout (the URL's `?layout=`, then the one remembered for this
+     * table, then its default). An id the table doesn't have shows the table.
+     * Left out, the switch keeps its own state, starting on the table.
+     */
+    layout?: string;
+    onLayoutChange?: (layout: string) => void;
+    /** The table's own entry in the switch: "Table" with a table icon unless set ("Rows", for a list-like table). */
+    tableLayout?: {
+        label?: string;
+        icon?: IconComponent;
+    };
+};
+/** One of DataTable's card layouts (`layouts`). */
+export type DataTableCardLayout<TData> = {
+    /** In the URL (`?layout=covers`) and remembered, so keep it short and stable. */
+    id: string;
+    /** The switch's word for it ("Covers"); its accessible name on a phone, where only the icon shows. */
+    label: string;
+    icon: IconComponent;
+    /** A row as a card. Everything it holds is the app's: the picture (Artwork), the title link, the actions. */
+    renderCard: (row: TData) => ReactNode;
+    /**
+     * `grid` (the default): cards side by side, as many across as fit, the
+     * package's sizing from the table's width; `list`: one card per line,
+     * divided like rows, for a dense one-line-each layout.
+     */
+    arrange?: 'grid' | 'list';
+    /**
+     * A grid card's width: `sm` covers (about 8.5rem, three across on a
+     * phone), `md` (the default) thumbnails (11rem, two on a phone), `lg`
+     * big thumbnails (14rem, one on a phone).
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /** The picture's shape, for the loading skeleton's cards: 16:9 unless set. */
+    aspect?: ArtworkAspect;
 };
 export type DataTableWidth = 'full' | 'content';
 export type DataTableTotals = {
@@ -119,4 +167,4 @@ export type DataTableTotals = {
      */
     cells?: Partial<Record<string, ReactNode>>;
 };
-export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width, groupBy, groupSummary, header: showHeader, highlightRow, totals, }: DataTableProps<TData>): import("react").JSX.Element;
+export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width, groupBy, groupSummary, header: showHeader, highlightRow, totals, layouts, layout: layoutProp, onLayoutChange, tableLayout, }: DataTableProps<TData>): import("react").JSX.Element;

package/dist/components/app/data-table.js

@@ -14,11 +14,12 @@ import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } fr
 import { flexRender } from '@tanstack/react-table';
 import { cn } from 'cn';
 import { getCoreRowModel, useLegacyTable } from '@tanstack/react-table/legacy';
-import { ArrowDownIcon, ArrowUpIcon, ArrowUpDownIcon, ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import { ArrowDownIcon, ArrowUpIcon, ArrowUpDownIcon, ChevronLeftIcon, ChevronRightIcon, TableIcon } from 'lucide-react';
 import { ErrorState } from './error-state.js';
 import { Button } from '../ui/button.js';
 import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from '../ui/empty.js';
 import { Skeleton } from '../ui/skeleton.js';
+import { ToggleGroup, ToggleGroupItem } from '../ui/toggle-group.js';
 import { EditInPlaceContext } from './edit-in-place.js';
 import { EditInPlaceStore } from './edit-in-place-store.js';
 import { LeaveGuard } from './editable-value.js';
@@ -38,6 +39,41 @@ function leafColumnIds(columns) {
         return id === undefined ? [] : [id];
     });
 }
+// A card grid's columns: as many of the size as the table's width holds,
+// and a fixed count on a phone-width table (`@container/data-table-cards`,
+// under 28rem), where minimum widths would leave one lonely column.
+const CARD_GRID_CLASS = {
+    sm: 'grid-cols-[repeat(auto-fill,minmax(8.5rem,1fr))] @max-md/data-table-cards:grid-cols-3',
+    md: 'grid-cols-[repeat(auto-fill,minmax(11rem,1fr))] @max-md/data-table-cards:grid-cols-2',
+    lg: 'grid-cols-[repeat(auto-fill,minmax(14rem,1fr))] @max-md/data-table-cards:grid-cols-1',
+};
+const CARD_GRID_GAP_CLASS = 'gap-x-4 gap-y-6 @max-md/data-table-cards:gap-x-2.5 @max-md/data-table-cards:gap-y-4';
+// A `list` layout: rows in a bordered box, divided as the table's are.
+const CARD_LIST_CLASS = 'divide-y divide-border overflow-hidden rounded-lg border border-border';
+const SKELETON_ASPECT_CLASS = {
+    '2:3': 'aspect-[2/3]',
+    '1:1': 'aspect-square',
+    '16:9': 'aspect-video',
+};
+function CardsSkeleton({ layout }) {
+    if (layout.arrange === 'list') {
+        return (_jsx("div", { className: cn(CARD_LIST_CLASS, 'flex flex-col'), "data-state": "loading", children: Array.from({ length: 6 }, (_, index) => (_jsxs("div", { className: "flex items-center gap-3 px-3 py-2", children: [_jsx(Skeleton, { className: "size-6 shrink-0 rounded-full" }), _jsx(Skeleton, { className: "h-4 flex-1" })] }, index))) }));
+    }
+    return (_jsx("div", { className: "@container/data-table-cards", "data-state": "loading", children: _jsx("div", { className: cn('grid', CARD_GRID_CLASS[layout.size ?? 'md'], CARD_GRID_GAP_CLASS), children: Array.from({ length: 8 }, (_, index) => (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Skeleton, { className: cn('w-full rounded-md', SKELETON_ASPECT_CLASS[layout.aspect ?? '16:9']) }), _jsx(Skeleton, { className: "h-4 w-4/5" }), _jsx(Skeleton, { className: "h-3 w-1/2" })] }, index))) }) }));
+}
+// The layout switch: a toggle group (one tab stop, the arrow keys along
+// it), the pressed one in the muted fill with the foreground's colour and
+// medium weight, the others in muted text, so the difference isn't the
+// fill alone. On a phone only the icons show; the label stays their name.
+const LAYOUT_ITEM_CLASS = 'gap-1.5 text-muted-foreground aria-pressed:bg-muted aria-pressed:font-medium aria-pressed:text-foreground';
+function LayoutSwitch({ options, value, onValueChange, }) {
+    return (_jsx(ToggleGroup, { "aria-label": "Layout", variant: "outline", size: "sm", spacing: 0, "data-slot": "data-table-layout-switch", value: [value], onValueChange: (next) => {
+            // [] is the pressed one pressed again: it stays on.
+            const chosen = next[0];
+            if (chosen !== undefined && chosen !== value)
+                onValueChange(chosen);
+        }, children: options.map(({ id, label, icon: Icon }) => (_jsxs(ToggleGroupItem, { value: id, className: LAYOUT_ITEM_CLASS, title: label, children: [_jsx(Icon, { "aria-hidden": "true", className: "size-4" }), _jsx("span", { className: "max-sm:sr-only", children: label })] }, id))) }));
+}
 function TableSkeleton({ columnCount }) {
     return (_jsx("div", { className: "flex flex-col gap-2 p-2", "data-state": "loading", children: Array.from({ length: 5 }, (_, row) => (_jsx("div", { className: "flex gap-4", children: Array.from({ length: columnCount }, (_, col) => (_jsx(Skeleton, { className: "h-8 flex-1" }, col))) }, row))) }));
 }
@@ -172,7 +208,17 @@ function useBottomScrollbar(containerRef, isSuccessView) {
     }, [containerRef, isSuccessView, isOverflowing]);
     return { barRef, isOverflowing, scrollWidth };
 }
-export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width = 'full', groupBy, groupSummary, header: showHeader = true, highlightRow, totals, }) {
+export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width = 'full', groupBy, groupSummary, header: showHeader = true, highlightRow, totals, layouts, layout: layoutProp, onLayoutChange, tableLayout, }) {
+    // The switch's own state, for a table that doesn't pass `layout`.
+    const [ownLayout, setOwnLayout] = useState('table');
+    const requestedLayout = layoutProp ?? ownLayout;
+    const cardLayout = layouts?.find((candidate) => candidate.id === requestedLayout);
+    const currentLayout = cardLayout?.id ?? 'table';
+    const setLayout = (next) => {
+        if (layoutProp === undefined)
+            setOwnLayout(next);
+        onLayoutChange?.(next);
+    };
     // Editing in place in the rows (cell pattern 18, "In a table's rows"):
     // a cell that renders an <EditableValue> edits where it's shown, one at
     // a time, with the leave-page prompt while one is open, the same rules
@@ -229,15 +275,18 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
         return () => observer.disconnect();
     }, [width, isSuccessView]);
     const containerRef = useRef(null);
-    const { barRef, isOverflowing, scrollWidth } = useBottomScrollbar(containerRef, Boolean(pinFirstColumn) && isSuccessView);
+    const { barRef, isOverflowing, scrollWidth } = useBottomScrollbar(containerRef, Boolean(pinFirstColumn) && isSuccessView && !cardLayout);
     const rows = table.getRowModel().rows;
     const visibleLeafColumns = table.getVisibleLeafColumns();
     const visibleColumnCount = visibleLeafColumns.length;
     // One body row, the same in a plain table and a grouped one.
     const renderRow = (row) => (_jsx(TableRow, { "data-highlighted": highlightRow?.(row.original) || undefined, className: cn(pinFirstColumn && ROW_GROUP_CLASS, highlightRow?.(row.original) && HIGHLIGHTED_ROW_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn && index === row.getVisibleCells().length - 1 && PINNED_LAST_COLUMN_CLASS, alignClass(cell.column.columnDef.meta?.align)), children: pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: flexRender(cell.column.columnDef.cell, cell.getContext()) })) : (flexRender(cell.column.columnDef.cell, cell.getContext())) }, cell.id))) }, row.id));
-    const content = (_jsxs("div", { ref: root, className: cn('flex flex-col gap-4', width === 'content' && CONTENT_WIDTH_CLASS), "data-width": width, style: width === 'content' && !isSuccessView && lastWidth !== null
+    const content = (_jsxs("div", { ref: root, className: cn('flex flex-col gap-4', width === 'content' && CONTENT_WIDTH_CLASS), "data-width": width, "data-layout": layouts?.length ? currentLayout : undefined, style: width === 'content' && !isSuccessView && lastWidth !== null
             ? { '--data-table-last-width': `${lastWidth}px` }
-            : undefined, children: [toolbar, error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (_jsx(TableSkeleton, { columnCount: table.getVisibleLeafColumns().length })) : isEmpty ? (_jsxs(Empty, { "data-state": "empty", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction] })) : (_jsxs(_Fragment, { children: [_jsxs(Table, { "data-state": "success", containerRef: containerRef, 
+            : undefined, children: [layouts?.length ? (_jsxs("div", { className: "flex flex-wrap items-end gap-x-4 gap-y-2", children: [_jsx("div", { className: "min-w-0 flex-1", children: toolbar }), _jsx(LayoutSwitch, { options: [
+                            { id: 'table', label: tableLayout?.label ?? 'Table', icon: tableLayout?.icon ?? TableIcon },
+                            ...layouts,
+                        ], value: currentLayout, onValueChange: setLayout })] })) : (toolbar), error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (cardLayout ? (_jsx(CardsSkeleton, { layout: cardLayout })) : (_jsx(TableSkeleton, { columnCount: table.getVisibleLeafColumns().length }))) : isEmpty ? (_jsxs(Empty, { "data-state": "empty", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction] })) : (_jsxs(_Fragment, { children: [cardLayout ? (_jsx(Cards, { layout: cardLayout, rows: rows, groupBy: groupBy, groupSummary: groupSummary })) : (_jsxs(Table, { "data-state": "success", containerRef: containerRef, 
                         // With the sticky bar below as the visible scrollbar, hide the
                         // container's own. It stays overflow-x-auto and fully
                         // scrollable (wheel, trackpad, drag, and the sync effect); it
@@ -269,6 +318,15 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                     }) }, headerGroup.id))) }), groupBy ? (groupRuns(rows, (row) => groupBy(row.original)).map((run, runIndex) => (_jsxs(TableBody, { "data-slot": "table-group", children: [_jsx(TableRow, { "data-slot": "table-group-heading", className: "hover:bg-transparent", children: _jsx(TableHead, { scope: "rowgroup", colSpan: visibleColumnCount, className: GROUP_HEADING_CLASS, children: _jsxs("span", { className: "sticky left-(--table-cell-px) inline-flex items-baseline gap-2", children: [_jsx("span", { className: "type-label text-foreground", children: run.label }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original)) }))] }) }) }), _jsx("tr", { hidden: true, "aria-hidden": "true", "data-slot": "table-group-stripe-offset" }), run.rows.map(renderRow)] }, `${runIndex}:${run.key}`)))) : (_jsx(TableBody, { children: rows.map(renderRow) })), totals && (_jsx(TableFooter, { className: TOTALS_FOOTER_CLASS, children: _jsx(TableRow, { "data-slot": "table-totals", className: "hover:bg-transparent", children: visibleLeafColumns.map((column, index) => {
                                         const className = cn(pinFirstColumn && index === 0 && PINNED_TOTALS_LABEL_CLASS, pinLastColumn && index === visibleColumnCount - 1 && PINNED_LAST_COLUMN_CLASS, alignClass(column.columnDef.meta?.align));
                                         return index === 0 ? (_jsx(TableHead, { scope: "row", className: cn(TOTALS_LABEL_CLASS, className), children: pinFirstColumn ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: totals.label })) : (totals.label) }, column.id)) : (_jsx(TableCell, { className: className, children: totals.cells?.[column.id] }, column.id));
-                                    }) }) }))] }), pinFirstColumn && isOverflowing && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "type-body text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "type-body text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
+                                    }) }) }))] })), pinFirstColumn && isOverflowing && !cardLayout && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "type-body text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "type-body text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
     return (_jsxs(EditInPlaceContext.Provider, { value: store, children: [editing && _jsx(LeaveGuard, { store: store }), width === 'content' ? _jsx("div", { className: "@container/data-table", children: content }) : content] }));
 }
+// A card layout's success view: the rows as cards in a grid or a list,
+// each run of one group (`groupBy`) under its own heading, as the table's
+// heading rows are, with the same label and summary.
+function Cards({ layout, rows, groupBy, groupSummary, }) {
+    const list = (items) => (_jsx("ul", { role: "list", className: cn(layout.arrange === 'list' ? CARD_LIST_CLASS : ['grid', CARD_GRID_CLASS[layout.size ?? 'md'], CARD_GRID_GAP_CLASS]), children: items.map((row) => (_jsx("li", { "data-slot": "data-table-card", className: "min-w-0", children: layout.renderCard(row.original) }, row.id))) }));
+    return (_jsx("div", { className: "@container/data-table-cards flex flex-col gap-6", "data-state": "success", "data-slot": "data-table-cards", children: groupBy
+            ? groupRuns(rows, (row) => groupBy(row.original)).map((run, runIndex) => (_jsxs("section", { "data-slot": "table-group", className: "flex flex-col gap-3", children: [_jsxs("h2", { "data-slot": "table-group-heading", className: "flex items-baseline gap-2 border-b border-border pb-1.5", children: [_jsx("span", { className: "type-label text-foreground", children: run.label }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original)) }))] }), list(run.rows)] }, `${runIndex}:${run.key}`)))
+            : list(rows) }));
+}

package/dist/components/app/session-view.d.ts

@@ -13,7 +13,23 @@ export type SessionViewProps = {
     fullscreenControl?: boolean;
     /** What takes focus on open (default: the first focusable control, which is the header's). */
     initialFocus?: DialogPrimitive.Popup.Props['initialFocus'];
+    /** Render the view with the dark theme's tokens, whatever the app's theme. */
+    dark?: boolean;
     /** On the area below the header, which holds `children`. */
     className?: string;
 };
-export declare function SessionView({ open, onOpenChange, title, children, keepAwake, fullscreenControl, initialFocus, className, }: SessionViewProps): React.JSX.Element;
+export declare function SessionView({ open, onOpenChange, title, children, keepAwake, fullscreenControl, initialFocus, dark, className, }: SessionViewProps): React.JSX.Element;
+export type SessionStageTone = 'neutral' | 'success' | 'info' | 'warning' | 'destructive';
+export type SessionStageProps = React.ComponentProps<'div'> & {
+    /** The phase's tone: what the glow and `sessionStageLit` take. */
+    tone?: SessionStageTone;
+    /** A soft wash of the tone behind the centre of the stage. */
+    glow?: boolean;
+};
+export declare function SessionStage({ tone, glow, className, style, ...props }: SessionStageProps): React.JSX.Element;
+/** The big time on a stage: the tone's text shade, with a glow of the tone around the figures. */
+export declare const sessionStageLit = "text-[var(--stage-tone-text)] [text-shadow:0_0_0.3em_color-mix(in_oklab,var(--stage-tone)_55%,transparent)]";
+/** A quiet outline control on a stage: no fill, a faint border, dimmed text that brightens on hover. */
+export declare const sessionStageQuiet = "border-foreground/25 bg-transparent text-muted-foreground shadow-none hover:border-foreground hover:bg-transparent hover:text-foreground dark:border-foreground/25 dark:bg-transparent dark:hover:border-foreground dark:hover:bg-transparent";
+/** The main control on a stage (Start, Done): an outline too, in the foreground colour. */
+export declare const sessionStageMain = "border-foreground bg-transparent text-foreground shadow-none hover:bg-foreground/10 hover:text-foreground dark:border-foreground dark:bg-transparent dark:hover:bg-foreground/10";

package/dist/components/app/session-view.js

@@ -8,6 +8,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Optional: a "Full screen" control that also asks the browser for real
 // fullscreen and quietly isn't there where the browser can't (iOS Safari
 // on a phone), and keepAwake, which holds a screen wake lock while open.
+// `dark` renders the view in the dark theme whatever the app's (the dark
+// stage, #253): the dark tokens are scoped to the view, so the page under
+// it keeps its own. SessionStage, below, is the stage under the header.
 // Recipes for its states in Playwright: docs/foundation/timed-screens.md.
 import * as React from 'react';
 import { Dialog as DialogPrimitive } from '@base-ui/react/dialog';
@@ -16,10 +19,12 @@ import { cn } from 'cn';
 import { Button } from '../ui/button.js';
 import { Dialog, DialogClose, DialogPortal, DialogTitle } from '../ui/dialog.js';
 import { useWakeLock } from '../../hooks/use-wake-lock.js';
-export function SessionView({ open, onOpenChange, title, children, keepAwake = false, fullscreenControl = false, initialFocus, className, }) {
+export function SessionView({ open, onOpenChange, title, children, keepAwake = false, fullscreenControl = false, initialFocus, dark = false, className, }) {
     useWakeLock(open && keepAwake);
     const fullscreen = useDocumentFullscreen(open);
-    return (_jsx(Dialog, { open: open, onOpenChange: (next) => onOpenChange(next), children: _jsx(DialogPortal, { children: _jsxs(DialogPrimitive.Popup, { "data-slot": "session-view", initialFocus: initialFocus, className: cn('fixed inset-0 z-50 flex flex-col bg-background text-foreground outline-none', 
+    return (_jsx(Dialog, { open: open, onOpenChange: (next) => onOpenChange(next), children: _jsx(DialogPortal, { children: _jsxs(DialogPrimitive.Popup, { "data-slot": "session-view", "data-look": dark ? 'dark' : undefined, initialFocus: initialFocus, className: cn('fixed inset-0 z-50 flex flex-col bg-background text-foreground outline-none', 
+                // theme.css's .dark block remaps the tokens for this subtree only.
+                dark && 'dark scheme-dark', 
                 // The insets are 0 unless the page's viewport meta has viewport-fit=cover.
                 'pt-[env(safe-area-inset-top)] pr-[env(safe-area-inset-right)] pb-[env(safe-area-inset-bottom)] pl-[env(safe-area-inset-left)]', 'duration-150 data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0'), children: [_jsxs("header", { className: "flex items-center gap-1 px-4 py-2", children: [_jsx(DialogTitle, { className: "min-w-0 flex-1 truncate type-section-title", children: title }), fullscreenControl && fullscreen.supported && (_jsx(Button, { variant: "ghost", size: "icon", "aria-label": "Full screen", "aria-pressed": fullscreen.active, onClick: fullscreen.toggle, children: fullscreen.active ? _jsx(Minimize2Icon, {}) : _jsx(Maximize2Icon, {}) })), _jsx(DialogClose, { render: _jsx(Button, { variant: "ghost", size: "icon", "aria-label": "Close" }), children: _jsx(XIcon, {}) })] }), _jsx("div", { className: cn('flex min-h-0 flex-1 flex-col overflow-auto px-4 pb-4', className), children: children })] }) }) }));
 }
@@ -66,3 +71,29 @@ function useDocumentFullscreen(open) {
     };
     return { supported, active, toggle };
 }
+// Each tone's solid fill (the glow) and its text shade (the lit time).
+// Neutral glows with the foreground, faintly, and lights in it.
+const STAGE_TONES = {
+    neutral: { solid: 'var(--foreground)', text: 'var(--foreground)', wash: '8%' },
+    success: { solid: 'var(--success)', text: 'var(--success-text)', wash: '24%' },
+    info: { solid: 'var(--info)', text: 'var(--info-text)', wash: '24%' },
+    warning: { solid: 'var(--warning)', text: 'var(--warning-text)', wash: '26%' },
+    destructive: { solid: 'var(--destructive)', text: 'var(--destructive-text)', wash: '24%' },
+};
+// The stage: the area a timed screen draws its run in, filling the view
+// below the header. It sets --stage-tone (the tone's solid) and
+// --stage-tone-text (its text shade) for what's inside, and with `glow` a
+// radial wash of the tone on the page colour, fading out to the edges. Made
+// for a dark SessionView, where the wash reads as light; on a light page it
+// is a faint tint.
+export function SessionStage({ tone = 'neutral', glow = false, className, style, ...props }) {
+    const t = STAGE_TONES[tone];
+    return (_jsx("div", { "data-slot": "session-stage", "data-tone": tone, "data-glow": glow || undefined, className: cn('relative flex min-h-0 flex-1 flex-col', glow &&
+            'bg-[radial-gradient(ellipse_70%_60%_at_50%_52%,color-mix(in_oklab,var(--stage-tone)_var(--stage-wash),var(--background))_0,var(--background)_75%)]', className), style: { '--stage-tone': t.solid, '--stage-tone-text': t.text, '--stage-wash': t.wash, ...style }, ...props }));
+}
+/** The big time on a stage: the tone's text shade, with a glow of the tone around the figures. */
+export const sessionStageLit = 'text-[var(--stage-tone-text)] [text-shadow:0_0_0.3em_color-mix(in_oklab,var(--stage-tone)_55%,transparent)]';
+/** A quiet outline control on a stage: no fill, a faint border, dimmed text that brightens on hover. */
+export const sessionStageQuiet = 'border-foreground/25 bg-transparent text-muted-foreground shadow-none hover:border-foreground hover:bg-transparent hover:text-foreground dark:border-foreground/25 dark:bg-transparent dark:hover:border-foreground dark:hover:bg-transparent';
+/** The main control on a stage (Start, Done): an outline too, in the foreground colour. */
+export const sessionStageMain = 'border-foreground bg-transparent text-foreground shadow-none hover:bg-foreground/10 hover:text-foreground dark:border-foreground dark:bg-transparent dark:hover:bg-foreground/10';

package/dist/hooks/use-table-layout.d.ts

@@ -0,0 +1,31 @@
+type StorageLike = Pick<Storage, 'getItem' | 'setItem'>;
+export type LayoutStore = {
+    get: (key: string) => string | null;
+    set: (key: string, value: string) => void;
+    subscribe: (key: string, listener: () => void) => () => void;
+};
+export declare function createLayoutStore(getStorage: () => StorageLike | undefined): LayoutStore;
+/** The layout to show: the URL's if the table has it, then the remembered one, then the default. */
+export declare function resolveLayout(layouts: readonly string[], fromUrl: string | null, remembered: string | null, defaultLayout: string): string;
+export type TableLayoutOptions = {
+    /** Every layout id the table has, the table's own `'table'` among them. */
+    layouts: readonly string[];
+    /** The one shown until another is picked; `'table'` when left out. */
+    defaultLayout?: string;
+    /**
+     * Where the pick is remembered on this device, one key per table: name it
+     * for the app and the list (`"my-app:comics:layout"`). Without one the
+     * pick lives only in the URL.
+     */
+    storageKey?: string;
+};
+/**
+ * `{ layout, setLayout }` for DataTable's `layout` and `onLayoutChange`.
+ * Setting one writes `?layout=` (replacing the history entry, as a filter
+ * does) and remembers it under `storageKey`.
+ */
+export declare function useTableLayout({ layouts, defaultLayout, storageKey }: TableLayoutOptions): {
+    layout: string;
+    setLayout: (next: string) => void;
+};
+export {};

package/dist/hooks/use-table-layout.js

@@ -0,0 +1,67 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { useSearchParams } from 'react-router';
+export function createLayoutStore(getStorage) {
+    const memory = new Map();
+    const listeners = new Map();
+    return {
+        get(key) {
+            const kept = memory.get(key);
+            if (kept !== undefined)
+                return kept;
+            try {
+                return getStorage()?.getItem(key) ?? null;
+            }
+            catch {
+                return null;
+            }
+        },
+        set(key, value) {
+            memory.set(key, value);
+            try {
+                getStorage()?.setItem(key, value);
+            }
+            catch {
+                // Storage blocked or full: remembered in memory for this page only.
+            }
+            for (const listener of listeners.get(key) ?? [])
+                listener();
+        },
+        subscribe(key, listener) {
+            let set = listeners.get(key);
+            if (!set)
+                listeners.set(key, (set = new Set()));
+            set.add(listener);
+            return () => set.delete(listener);
+        },
+    };
+}
+/** The layout to show: the URL's if the table has it, then the remembered one, then the default. */
+export function resolveLayout(layouts, fromUrl, remembered, defaultLayout) {
+    if (fromUrl !== null && layouts.includes(fromUrl))
+        return fromUrl;
+    if (remembered !== null && layouts.includes(remembered))
+        return remembered;
+    return defaultLayout;
+}
+const browserStore = createLayoutStore(() => (typeof window === 'undefined' ? undefined : window.localStorage));
+/**
+ * `{ layout, setLayout }` for DataTable's `layout` and `onLayoutChange`.
+ * Setting one writes `?layout=` (replacing the history entry, as a filter
+ * does) and remembers it under `storageKey`.
+ */
+export function useTableLayout({ layouts, defaultLayout = 'table', storageKey }) {
+    const [params, setParams] = useSearchParams();
+    const subscribe = useCallback((listener) => (storageKey === undefined ? () => { } : browserStore.subscribe(storageKey, listener)), [storageKey]);
+    const remembered = useSyncExternalStore(subscribe, () => (storageKey === undefined ? null : browserStore.get(storageKey)), () => null);
+    const layout = resolveLayout(layouts, params.get('layout'), remembered, defaultLayout);
+    const setLayout = useCallback((next) => {
+        if (storageKey !== undefined)
+            browserStore.set(storageKey, next);
+        setParams((previous) => {
+            const updated = new URLSearchParams(previous);
+            updated.set('layout', next);
+            return updated;
+        }, { replace: true });
+    }, [setParams, storageKey]);
+    return { layout, setLayout };
+}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { AppShell, type AppShellProps, type AppShellVersion, type BottomBarItem, type NavEntry, type NavItem, type NavSection, } from './components/app/app-shell.js';
 export type { IconComponent } from './components/app/icon-component.js';
 export { Board, type BoardColumn, type BoardMoveTarget, type BoardProps } from './components/app/board.js';
+export { Artwork, ArtworkTag, ArtworkToggle, type ArtworkAspect, type ArtworkProps, type ArtworkToggleProps, } from './components/app/artwork.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
-export { DataTable, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
+export { DataTable, type DataTableCardLayout, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
 export { type RowGroup } from './components/app/table-groups.js';
 export { byDay, type ByDayOptions } from './lib/group-by-day.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
@@ -25,7 +26,7 @@ export { RichTextEditor, type RichTextEditorProps } from './components/app/rich-
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter, type PillFilterOption, type PillFilterProps } from './components/app/pill-filter.js';
 export { SecondaryFilters, type ActiveFilter, type SecondaryFiltersProps } from './components/app/secondary-filters.js';
-export { SessionView, type SessionViewProps } from './components/app/session-view.js';
+export { SessionStage, SessionView, sessionStageLit, sessionStageMain, sessionStageQuiet, type SessionStageProps, type SessionStageTone, type SessionViewProps, } from './components/app/session-view.js';
 export { AllowReminders, type AllowRemindersProps } from './components/app/allow-reminders.js';
 export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCircleTone, } from './components/app/stage-circle.js';
 export { Notice, type NoticeProps, type NoticeTone } from './components/app/notice.js';
@@ -51,6 +52,7 @@ export type { AppError, Page, QuerySpec } from './api/contracts.js';
 export type { ErrorReportingOptions } from './error-reporting/reporter.js';
 export { createQueryClient } from './api/query-client.js';
 export { useTableUrlState } from './hooks/use-table-url-state.js';
+export { useTableLayout, type TableLayoutOptions } from './hooks/use-table-layout.js';
 export type { TableView, UrlChanges } from './hooks/table-url-changes.js';
 export { useDebouncedValue } from './hooks/use-debounced-value.js';
 export { useDocumentTitle } from './hooks/use-document-title.js';

package/dist/index.js

@@ -5,6 +5,7 @@
 // Composites
 export { AppShell, } from './components/app/app-shell.js';
 export { Board } from './components/app/board.js';
+export { Artwork, ArtworkTag, ArtworkToggle, } from './components/app/artwork.js';
 export { CountLink } from './components/app/count-link.js';
 export { DataTable, } from './components/app/data-table.js';
 export {} from './components/app/table-groups.js';
@@ -28,7 +29,7 @@ export { RichTextEditor } from './components/app/rich-text-editor.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter } from './components/app/pill-filter.js';
 export { SecondaryFilters } from './components/app/secondary-filters.js';
-export { SessionView } from './components/app/session-view.js';
+export { SessionStage, SessionView, sessionStageLit, sessionStageMain, sessionStageQuiet, } from './components/app/session-view.js';
 export { AllowReminders } from './components/app/allow-reminders.js';
 export { StageCircle, } from './components/app/stage-circle.js';
 export { Notice } from './components/app/notice.js';
@@ -54,6 +55,7 @@ export { AuthProvider, useAuth } from './auth/use-auth.js';
 export { createQueryClient } from './api/query-client.js';
 // Hooks
 export { useTableUrlState } from './hooks/use-table-url-state.js';
+export { useTableLayout } from './hooks/use-table-layout.js';
 export { useDebouncedValue } from './hooks/use-debounced-value.js';
 export { useDocumentTitle } from './hooks/use-document-title.js';
 export { useRecordUpdate, } from './hooks/use-record-update.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.38.0",
+  "version": "4.40.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {