@tristan2828/ui-foundation 4.32.0 → 4.34.0

package/dist/components/app/widget-card.d.ts

@@ -31,10 +31,20 @@ export interface WidgetCardProps {
     emptyMessage: string;
     /** How many rows the loading skeleton shows: the number the widget usually holds. */
     skeletonRows?: number;
+    /** A button at the header's end that folds the card to its header, and opens it again. */
+    collapsible?: boolean;
+    /** Whether a collapsible card starts folded, until the person folds or opens it. */
+    defaultCollapsed?: boolean;
+    /**
+     * Remembers a collapsible card folded or open on this device, under this
+     * key (name it for the app and the widget: `"my-app:hub.waiting"`).
+     * Left out, it starts at `defaultCollapsed` on every visit.
+     */
+    storageKey?: string;
     children?: ReactNode;
     className?: string;
 }
-export declare function WidgetCard({ title, icon: Icon, headingLevel, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows, children, className, }: WidgetCardProps): import("react").JSX.Element;
+export declare function WidgetCard({ title, icon: Icon, headingLevel, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows, collapsible, defaultCollapsed, storageKey, children, className, }: WidgetCardProps): import("react").JSX.Element;
 /** The rows of a WidgetCard: a list with a divider between rows. */
 export declare function WidgetList({ children, className }: {
     children: ReactNode;

package/dist/components/app/widget-card.js

@@ -16,6 +16,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // outline and its landmarks. Height follows content (`self-start` in a
 // grid), so a short widget doesn't stretch to its tallest neighbour.
 //
+// `collapsible` (#233) folds a card to its header, for a hub with more
+// widgets than a phone screen holds: a chevron button at the header's end
+// (named by the title, `aria-expanded`, `aria-controls` the body), the
+// header's link still there while folded. With `storageKey` the choice is
+// remembered on this device (useRememberedFlag: localStorage, in memory
+// where that's blocked). The body is hidden, not unmounted, so whatever
+// the app keeps in it stays put.
+//
 // WidgetList and WidgetListItem are the common body: rows with dividers,
 // each a primary link (or plain text) truncated to one line, an optional
 // muted note ("2 h ago") and an optional trailing element (a badge, a
@@ -28,18 +36,26 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // finger's target.
 import { useId } from 'react';
 import { Link } from 'react-router';
-import { ExternalLinkIcon } from 'lucide-react';
+import { ChevronDownIcon, ExternalLinkIcon } from 'lucide-react';
 import { cn } from 'cn';
 import { ErrorState } from './error-state.js';
+import { Button } from '../ui/button.js';
 import { Card, CardContent, CardHeader } from '../ui/card.js';
 import { Skeleton } from '../ui/skeleton.js';
+import { useRememberedFlag } from '../../hooks/use-remembered-flag.js';
 const HEADER_LINK_CLASS = 'shrink-0 rounded-sm type-label text-foreground underline underline-offset-4 outline-none ' +
     'hover:decoration-2 focus-visible:ring-3 focus-visible:ring-ring/50';
-export function WidgetCard({ title, icon: Icon, headingLevel = 2, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows = 3, children, className, }) {
+export function WidgetCard({ title, icon: Icon, headingLevel = 2, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows = 3, collapsible = false, defaultCollapsed = false, storageKey, children, className, }) {
     const headingId = useId();
+    const contentId = useId();
     const Heading = `h${headingLevel}`;
     const state = error ? 'error' : isLoading ? 'loading' : isEmpty ? 'empty' : 'success';
-    return (_jsx("section", { "aria-labelledby": headingId, "data-slot": "widget-card", "data-state": state, className: cn('min-w-0 self-start', className), children: _jsxs(Card, { className: "density-compact:[--card-spacing:--spacing(3)]", children: [_jsxs(CardHeader, { className: "flex items-center justify-between gap-3", children: [_jsxs(Heading, { id: headingId, className: "flex min-w-0 items-center gap-2 type-section-title text-foreground", children: [Icon && _jsx(Icon, { "aria-hidden": "true", className: "size-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: title })] }), link && (_jsx(Link, { to: link.to, "aria-describedby": headingId, className: HEADER_LINK_CLASS, children: link.label }))] }), _jsx(CardContent, { "aria-busy": state === 'loading' || undefined, children: error ? (_jsx(ErrorState, { error: error, onRetry: onRetry, size: "compact" })) : state === 'loading' ? (_jsx(WidgetListSkeleton, { rows: skeletonRows })) : state === 'empty' ? (_jsx("p", { "data-state": "empty", className: "py-2 type-body text-muted-foreground", children: emptyMessage })) : (children) })] }) }));
+    const [folded, setFolded] = useRememberedFlag(collapsible && storageKey !== undefined ? `${storageKey}:collapsed` : undefined, defaultCollapsed);
+    const collapsed = collapsible && folded;
+    return (_jsx("section", { "aria-labelledby": headingId, "data-slot": "widget-card", "data-state": state, "data-collapsed": collapsed || undefined, className: cn('min-w-0 self-start', className), children: _jsxs(Card, { className: "density-compact:[--card-spacing:--spacing(3)]", children: [_jsxs(CardHeader, { className: "flex items-center justify-between gap-3", children: [_jsxs(Heading, { id: headingId, className: "flex min-w-0 items-center gap-2 type-section-title text-foreground", children: [Icon && _jsx(Icon, { "aria-hidden": "true", className: "size-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: title })] }), (link || collapsible) && (_jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [link && (_jsx(Link, { to: link.to, "aria-describedby": headingId, className: HEADER_LINK_CLASS, children: link.label })), collapsible && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-labelledby": headingId, "aria-expanded": !collapsed, "aria-controls": contentId, onClick: () => setFolded(!collapsed), 
+                                    // The button's own open look (a filled background) would
+                                    // read as pressed: the chevron says it.
+                                    className: "-my-1 -mr-1.5 aria-expanded:not-hover:bg-transparent", children: _jsx(ChevronDownIcon, { "aria-hidden": "true", className: cn('transition-transform', collapsed && '-rotate-90') }) }))] }))] }), _jsx(CardContent, { id: contentId, hidden: collapsed, "aria-busy": state === 'loading' || undefined, children: error ? (_jsx(ErrorState, { error: error, onRetry: onRetry, size: "compact" })) : state === 'loading' ? (_jsx(WidgetListSkeleton, { rows: skeletonRows })) : state === 'empty' ? (_jsx("p", { "data-state": "empty", className: "py-2 type-body text-muted-foreground", children: emptyMessage })) : (children) })] }) }));
 }
 // One row's height, shared by the skeleton and the list so the card doesn't
 // jump: py-2 around one line of type-body (or a small control). Compact

package/dist/components/ui/collapsible.d.ts

@@ -0,0 +1,5 @@
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+declare function Collapsible({ ...props }: CollapsiblePrimitive.Root.Props): import("react").JSX.Element;
+declare function CollapsibleTrigger({ ...props }: CollapsiblePrimitive.Trigger.Props): import("react").JSX.Element;
+declare function CollapsibleContent({ ...props }: CollapsiblePrimitive.Panel.Props): import("react").JSX.Element;
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };

package/dist/components/ui/collapsible.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+function Collapsible({ ...props }) {
+    return _jsx(CollapsiblePrimitive.Root, { "data-slot": "collapsible", ...props });
+}
+function CollapsibleTrigger({ ...props }) {
+    return (_jsx(CollapsiblePrimitive.Trigger, { "data-slot": "collapsible-trigger", ...props }));
+}
+function CollapsibleContent({ ...props }) {
+    return (_jsx(CollapsiblePrimitive.Panel, { "data-slot": "collapsible-content", ...props }));
+}
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };

package/dist/hooks/use-muted.d.ts

@@ -1,15 +1,9 @@
-type StorageLike = Pick<Storage, 'getItem' | 'setItem'>;
-export type MutedStore = {
-    get: (key: string) => boolean;
-    set: (key: string, muted: boolean) => void;
-    subscribe: (key: string, listener: () => void) => () => void;
-    /** Another tab changed `key` (a `storage` event): forget the in-memory value and re-read. */
-    changedElsewhere: (key: string) => void;
-};
-export declare function createMutedStore(getStorage: () => StorageLike | undefined): MutedStore;
+import { createFlagStore, type FlagStore } from './use-remembered-flag.js';
+export type MutedStore = FlagStore;
+/** The store under useMuted, for its unit tests (tests/use-muted.test.ts). */
+export declare const createMutedStore: typeof createFlagStore;
 /**
  * `[muted, setMuted]`, remembered on this device under `key` (name it for
  * the app and screen: `"my-app:timer:muted"`). Unmuted until set.
  */
 export declare function useMuted(key: string): readonly [boolean, (muted: boolean) => void];
-export {};

package/dist/hooks/use-muted.js

@@ -1,73 +1,10 @@
-import { useCallback, useSyncExternalStore } from 'react';
-export function createMutedStore(getStorage) {
-    // Values this page set, for when storage refuses them.
-    const memory = new Map();
-    const listeners = new Map();
-    const notify = (key) => {
-        for (const listener of listeners.get(key) ?? [])
-            listener();
-    };
-    return {
-        get(key) {
-            const kept = memory.get(key);
-            if (kept !== undefined)
-                return kept;
-            try {
-                const stored = getStorage()?.getItem(key);
-                if (stored === 'true')
-                    return true;
-                if (stored === 'false')
-                    return false;
-            }
-            catch {
-                // Storage blocked: unmuted.
-            }
-            return false;
-        },
-        set(key, muted) {
-            memory.set(key, muted);
-            try {
-                getStorage()?.setItem(key, String(muted));
-            }
-            catch {
-                // Storage blocked or full: remembered in memory for this page only.
-            }
-            notify(key);
-        },
-        subscribe(key, listener) {
-            let set = listeners.get(key);
-            if (!set)
-                listeners.set(key, (set = new Set()));
-            set.add(listener);
-            return () => set.delete(listener);
-        },
-        changedElsewhere(key) {
-            memory.delete(key);
-            notify(key);
-        },
-    };
-}
-const browserStore = createMutedStore(() => (typeof window === 'undefined' ? undefined : window.localStorage));
-let listeningForOtherTabs = false;
-function listenForOtherTabs() {
-    if (listeningForOtherTabs || typeof window === 'undefined')
-        return;
-    listeningForOtherTabs = true;
-    window.addEventListener('storage', (event) => {
-        if (event.key !== null)
-            browserStore.changedElsewhere(event.key);
-    });
-}
+import { createFlagStore, useRememberedFlag } from './use-remembered-flag.js';
+/** The store under useMuted, for its unit tests (tests/use-muted.test.ts). */
+export const createMutedStore = createFlagStore;
 /**
  * `[muted, setMuted]`, remembered on this device under `key` (name it for
  * the app and screen: `"my-app:timer:muted"`). Unmuted until set.
  */
 export function useMuted(key) {
-    const subscribe = useCallback((listener) => {
-        listenForOtherTabs();
-        return browserStore.subscribe(key, listener);
-    }, [key]);
-    const muted = useSyncExternalStore(subscribe, () => browserStore.get(key), () => false);
-    const setMuted = useCallback((next) => browserStore.set(key, next), [key]);
-    return [muted, setMuted];
+    return useRememberedFlag(key, false);
 }

package/dist/hooks/use-remembered-flag.d.ts

@@ -0,0 +1,18 @@
+type StorageLike = Pick<Storage, 'getItem' | 'setItem'>;
+export type FlagStore = {
+    /** What's held for `key`, or `fallback` when nothing is (or storage is blocked). */
+    get: (key: string, fallback?: boolean) => boolean;
+    set: (key: string, value: boolean) => void;
+    subscribe: (key: string, listener: () => void) => () => void;
+    /** Another tab changed `key` (a `storage` event): forget the in-memory value and re-read. */
+    changedElsewhere: (key: string) => void;
+};
+export declare function createFlagStore(getStorage: () => StorageLike | undefined): FlagStore;
+/**
+ * `[value, setValue]`, remembered on this device under `key` (name it for
+ * the app and what it's about: `"my-app:hub.waiting:collapsed"`), and
+ * `fallback` until set. Without a key it's plain state, starting at
+ * `fallback` and forgotten with the page.
+ */
+export declare function useRememberedFlag(key: string | undefined, fallback?: boolean): readonly [boolean, (value: boolean) => void];
+export {};

package/dist/hooks/use-remembered-flag.js

@@ -0,0 +1,78 @@
+import { useCallback, useState, useSyncExternalStore } from 'react';
+export function createFlagStore(getStorage) {
+    // Values this page set, for when storage refuses them.
+    const memory = new Map();
+    const listeners = new Map();
+    const notify = (key) => {
+        for (const listener of listeners.get(key) ?? [])
+            listener();
+    };
+    return {
+        get(key, fallback = false) {
+            const kept = memory.get(key);
+            if (kept !== undefined)
+                return kept;
+            try {
+                const stored = getStorage()?.getItem(key);
+                if (stored === 'true')
+                    return true;
+                if (stored === 'false')
+                    return false;
+            }
+            catch {
+                // Storage blocked: the fallback.
+            }
+            return fallback;
+        },
+        set(key, value) {
+            memory.set(key, value);
+            try {
+                getStorage()?.setItem(key, String(value));
+            }
+            catch {
+                // Storage blocked or full: remembered in memory for this page only.
+            }
+            notify(key);
+        },
+        subscribe(key, listener) {
+            let set = listeners.get(key);
+            if (!set)
+                listeners.set(key, (set = new Set()));
+            set.add(listener);
+            return () => set.delete(listener);
+        },
+        changedElsewhere(key) {
+            memory.delete(key);
+            notify(key);
+        },
+    };
+}
+const browserStore = createFlagStore(() => (typeof window === 'undefined' ? undefined : window.localStorage));
+let listeningForOtherTabs = false;
+function listenForOtherTabs() {
+    if (listeningForOtherTabs || typeof window === 'undefined')
+        return;
+    listeningForOtherTabs = true;
+    window.addEventListener('storage', (event) => {
+        if (event.key !== null)
+            browserStore.changedElsewhere(event.key);
+    });
+}
+/**
+ * `[value, setValue]`, remembered on this device under `key` (name it for
+ * the app and what it's about: `"my-app:hub.waiting:collapsed"`), and
+ * `fallback` until set. Without a key it's plain state, starting at
+ * `fallback` and forgotten with the page.
+ */
+export function useRememberedFlag(key, fallback = false) {
+    const [local, setLocal] = useState(fallback);
+    const subscribe = useCallback((listener) => {
+        if (key === undefined)
+            return () => { };
+        listenForOtherTabs();
+        return browserStore.subscribe(key, listener);
+    }, [key]);
+    const stored = useSyncExternalStore(subscribe, () => (key === undefined ? fallback : browserStore.get(key, fallback)), () => fallback);
+    const set = useCallback((next) => (key === undefined ? setLocal(next) : browserStore.set(key, next)), [key]);
+    return [key === undefined ? local : stored, set];
+}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { AppShell, type AppShellProps, type AppShellVersion, type NavEntry, type NavItem, type NavSection } from './components/app/app-shell.js';
+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 { CountLink, type CountLinkProps } from './components/app/count-link.js';
-export { DataTable, type DataTableProps, type DataTableWidth, type SortingState } from './components/app/data-table.js';
+export { DataTable, 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';
@@ -13,6 +13,7 @@ export { ErrorState } from './components/app/error-state.js';
 export { InlineCreate, type InlineCreateProps } from './components/app/inline-create.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown, type MarkdownProps } from './components/app/markdown.js';
+export type { HeadingFrom, HeadingLevel } from './components/app/prose-look.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';
 export { MultiPick, type MultiPickOption, type MultiPickProps } from './components/app/multi-pick.js';
@@ -29,6 +30,7 @@ export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCi
 export { Notice, type NoticeProps, type NoticeTone } from './components/app/notice.js';
 export { SourceCredit, type Source, type SourceCreditProps } from './components/app/source-credit.js';
 export { ProgressRing, type ProgressRingProps } from './components/app/progress-ring.js';
+export { LineChart, type LineChartMark, type LineChartPoint, type LineChartProps, } from './components/app/line-chart.js';
 export { StepBar, type StepBarProps } from './components/app/step-bar.js';
 export { RatingStar, type RatingStarProps, type RatingStarValue } from './components/app/rating-star.js';
 export { DateField, type DateFieldProps } from './components/app/date-field.js';

package/dist/index.js

@@ -3,9 +3,9 @@
 // the gateway seam, MSW support and Playwright suites have their own entry
 // points (`/gateway`, `/mocks`, `/testing`) so each stays behind its boundary.
 // Composites
-export { AppShell } from './components/app/app-shell.js';
+export { AppShell, } from './components/app/app-shell.js';
 export { CountLink } from './components/app/count-link.js';
-export { DataTable } from './components/app/data-table.js';
+export { DataTable, } from './components/app/data-table.js';
 export {} from './components/app/table-groups.js';
 export { byDay } from './lib/group-by-day.js';
 export { EntityForm } from './components/app/entity-form.js';
@@ -33,6 +33,7 @@ export { StageCircle, } from './components/app/stage-circle.js';
 export { Notice } from './components/app/notice.js';
 export { SourceCredit } from './components/app/source-credit.js';
 export { ProgressRing } from './components/app/progress-ring.js';
+export { LineChart, } from './components/app/line-chart.js';
 export { StepBar } from './components/app/step-bar.js';
 export { RatingStar } from './components/app/rating-star.js';
 export { DateField } from './components/app/date-field.js';

package/dist/lib/line-chart-layout.d.ts

@@ -0,0 +1,23 @@
+export type LineChartPoint = {
+    /** A day (`'YYYY-MM-DD'`), a timestamp or any number. Points sit apart by it; if one isn't a time or a number, they're evenly spaced. */
+    x: string | number;
+    y: number;
+};
+export type LineChartMark = 'min' | 'max' | 'last';
+export type ChartLayout = {
+    /** Each point's place, in the order given. */
+    places: {
+        x: number;
+        y: number;
+    }[];
+    /** The y range drawn, bottom to top: the values and the target, with room around them. */
+    domain: {
+        min: number;
+        max: number;
+    };
+    /** The target line's height, if there's a target. */
+    targetY?: number;
+    /** Which point the mark is on, if any. */
+    markIndex?: number;
+};
+export declare function chartLayout(points: readonly LineChartPoint[], target?: number, mark?: LineChartMark): ChartLayout;

package/dist/lib/line-chart-layout.js

@@ -0,0 +1,44 @@
+// Where LineChart's points, target and mark go (#238), React-free so the
+// rules are unit tested on their own (tests/line-chart-layout.test.ts).
+// Positions are fractions of the plot, 0…1, x from the left and y from
+// the top, so the chart fills whatever width it's given.
+// A point's position along x: a number as it is, a day or a timestamp as
+// its time.
+function along(x) {
+    return typeof x === 'number' ? x : Date.parse(x);
+}
+// Room above and below the values, as a share of their range, so the line
+// never runs along the plot's edge.
+const PAD = 0.1;
+export function chartLayout(points, target, mark) {
+    const values = points.map((point) => point.y);
+    const all = target === undefined ? values : [...values, target];
+    let min = Math.min(...all);
+    let max = Math.max(...all);
+    // One value (or all the same): a band around it, so the line sits mid-plot.
+    const spread = max - min || Math.abs(max) || 1;
+    min -= spread * PAD;
+    max += spread * PAD;
+    const height = (y) => (max - y) / (max - min);
+    const times = points.map((point) => along(point.x));
+    const timed = times.every(Number.isFinite) && times.length > 1 && times.at(-1) !== times[0];
+    const first = timed ? Math.min(...times) : 0;
+    const span = timed ? Math.max(...times) - first : points.length - 1;
+    const across = (index) => (span === 0 ? 0.5 : ((timed ? times[index] : index) - first) / span);
+    let markIndex;
+    if (points.length > 0 && mark) {
+        if (mark === 'last')
+            markIndex = points.length - 1;
+        else {
+            const pick = mark === 'min' ? Math.min(...values) : Math.max(...values);
+            // The latest of equal values: the one that's still true.
+            markIndex = values.lastIndexOf(pick);
+        }
+    }
+    return {
+        places: points.map((point, index) => ({ x: across(index), y: height(point.y) })),
+        domain: { min, max },
+        targetY: target === undefined ? undefined : height(target),
+        markIndex,
+    };
+}

package/dist/lib/markdown-top-heading.d.ts

@@ -0,0 +1,2 @@
+/** The lowest `depth` of any heading in the text, nested ones included; 1 when it has none. */
+export declare function textTopHeading(markdown: string): number;

package/dist/lib/markdown-top-heading.js

@@ -0,0 +1,21 @@
+// The text's own highest heading level (1 for `#`), for `headingFrom="text"`
+// on <Markdown> and the rich-text editor: notes pasted or imported from
+// another tool often start at `##`, and that level is the one that takes
+// the field's `headingLevel`. Parsed as both parse it (remark, GFM), so a
+// `#` in a code block or a setext heading counts as they render it.
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+const parser = unified().use(remarkParse).use(remarkGfm);
+/** The lowest `depth` of any heading in the text, nested ones included; 1 when it has none. */
+export function textTopHeading(markdown) {
+    let top = 7;
+    const visit = (node) => {
+        if (node.type === 'heading' && node.depth)
+            top = Math.min(top, node.depth);
+        for (const child of node.children ?? [])
+            visit(child);
+    };
+    visit(parser.parse(markdown));
+    return top === 7 ? 1 : top;
+}

package/dist/testing/index.d.ts

@@ -43,8 +43,11 @@ export type A11ySuiteOptions = {
      * sparse one, so both filled values and "not set" labels are checked.
      */
     viewRoutes?: readonly string[];
-    /** Screens outside the app shell, e.g. '/login' (and '/register' if the app has it). */
-    loggedOutRoutes: readonly string[];
+    /**
+     * Screens outside the app shell, e.g. '/login' (and '/register' if the
+     * app has it). An app with several a11y spec files lists them in one.
+     */
+    loggedOutRoutes?: readonly string[];
     /**
      * The app's nav, the same `NavEntry[]` passed to `AppShell` (`src/nav.ts`).
      * Given, each page in it is a test of its own, so the suite's time per
@@ -54,6 +57,13 @@ export type A11ySuiteOptions = {
      * their number.
      */
     nav?: readonly NavEntry[];
+    /**
+     * Whether to check that the rendered sidebar links exactly `nav`'s pages
+     * (default true). An app with one a11y spec per module passes each
+     * module's own entries as `nav` with `checkSidebar: false`, and keeps
+     * the check in one file that passes the whole nav.
+     */
+    checkSidebar?: boolean;
 };
 /**
  * Every data view on the page has loaded: at least one shows its data (or,
@@ -71,12 +81,14 @@ export declare function expectDataViewsLoaded(page: Page, { success }?: {
  * Accessibility of the real screens in light and dark mode: every page in
  * the Primary nav (one test each from `nav`, or discovered in the sidebar
  * when `nav` is left out), the given form routes, and the logged-out
- * screens. axe's
+ * screens. A modular app can split it into a spec per module: each passes
+ * its module's `nav` entries and routes with `checkSidebar: false`, and
+ * one file keeps the whole-sidebar check. axe's
  * color-contrast rule against the rendered dark DOM is also what keeps the
  * dark-mode tokens readable. The theme follows the OS setting, so
  * emulateMedia switches it.
  */
-export declare function defineA11ySuite({ formRoutes, viewRoutes, loggedOutRoutes, nav }: A11ySuiteOptions): void;
+export declare function defineA11ySuite({ formRoutes, viewRoutes, loggedOutRoutes, nav, checkSidebar, }: A11ySuiteOptions): void;
 export type MockModeBannerSuiteOptions = {
     /** Screens to check, logged-out ones included (e.g. '/login'). */
     routes: readonly string[];

package/dist/testing/index.js

@@ -140,16 +140,18 @@ async function expectNavPageAccessible(page, route, colorScheme) {
  * Accessibility of the real screens in light and dark mode: every page in
  * the Primary nav (one test each from `nav`, or discovered in the sidebar
  * when `nav` is left out), the given form routes, and the logged-out
- * screens. axe's
+ * screens. A modular app can split it into a spec per module: each passes
+ * its module's `nav` entries and routes with `checkSidebar: false`, and
+ * one file keeps the whole-sidebar check. axe's
  * color-contrast rule against the rendered dark DOM is also what keeps the
  * dark-mode tokens readable. The theme follows the OS setting, so
  * emulateMedia switches it.
  */
-export function defineA11ySuite({ formRoutes, viewRoutes = [], loggedOutRoutes, nav }) {
+export function defineA11ySuite({ formRoutes, viewRoutes = [], loggedOutRoutes = [], nav, checkSidebar = true, }) {
     // Each `to` as given, query string and all, so a page that opens on a
     // saved view is checked on it.
     const listed = nav && navTargets(nav);
-    if (listed) {
+    if (listed && checkSidebar) {
         test('the sidebar links exactly the pages in nav', async ({ page, isMobile }) => {
             const rendered = await navRoutes(page, isMobile);
             expect(pagePaths(rendered), 'The sidebar and the nav given to defineA11ySuite differ: pass the same NavEntry[] AppShell gets').toEqual(pagePaths(listed));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.32.0",
+  "version": "4.34.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": {
@@ -65,10 +65,11 @@
     "prepack": "npm run build",
     "gen:api": "openapi-typescript ./openapi/foundation.yaml -o ./src/api/schema.ts",
     "lint": "eslint .",
+    "docs:index": "node scripts/doc-index.mjs",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "preview-storybook": "vite preview --outDir storybook-static --port 6006 --strictPort",
-    "verify:fast": "npm run gen:api && git diff --exit-code -- src/api/schema.ts && tsc -b && eslint . --max-warnings 0 && node bin/ui-foundation.mjs check-deps && npm run build && vitest run",
+    "verify:fast": "npm run gen:api && git diff --exit-code -- src/api/schema.ts && node scripts/doc-index.mjs --check && tsc -b && eslint . --max-warnings 0 && node bin/ui-foundation.mjs check-deps && npm run build && vitest run",
     "verify": "npm run verify:fast && playwright test -c playwright.storybook.config.ts"
   },
   "peerDependencies": {