@tristan2828/ui-foundation 4.13.0 → 4.15.0

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

@@ -515,8 +515,9 @@ is a filled-in example while the Widgets demo is still here).
    `NAV_ENTRIES` so the shell smoke test covers the new screen, add
    `/<entity>/new` to `e2e/a11y.spec.ts`'s `formRoutes`, and add the view
    of a full record and of the sparse one to its `viewRoutes` (the table
-   page is picked up from the sidebar automatically; the form and the view
-   aren't in it). With fields edited in place, copy `e2e/a11y.spec.ts`'s
+   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
    "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/dist/components/app/app-shell-nav.d.ts

@@ -11,6 +11,15 @@ export type NavItem = {
 export type NavSection = {
     label: string;
     items: readonly NavItem[];
+    /**
+     * The label folds the section away: a button with a chevron. Whether
+     * it's open is remembered per browser, by the section's label. The
+     * section holding the page you're on is always open, and the icon rail
+     * shows every section's items whatever their state.
+     */
+    collapsible?: boolean;
+    /** Whether a collapsible section starts open for someone who has never folded it. Defaults to true. */
+    defaultOpen?: boolean;
 };
 /** One entry of `AppShell`'s `nav`: a page, or a labelled section of pages. */
 export type NavEntry = NavItem | NavSection;
@@ -19,6 +28,9 @@ export declare function isNavSection(entry: NavEntry): entry is NavSection;
 export type NavGroup = {
     label?: string;
     items: readonly NavItem[];
+    /** From its section: the label folds it (NavSection's `collapsible`). */
+    collapsible?: boolean;
+    defaultOpen?: boolean;
 };
 /**
  * The sidebar groups for a nav, in order. A flat nav (no sections) is the

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

@@ -16,7 +16,11 @@ export function navGroups(nav) {
             if (run.length)
                 groups.push({ items: run });
             run = [];
-            groups.push({ label: entry.label, items: entry.items });
+            groups.push({
+                label: entry.label,
+                items: entry.items,
+                ...(entry.collapsible && { collapsible: true, defaultOpen: entry.defaultOpen ?? true }),
+            });
         }
         else {
             run.push(entry);

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

@@ -11,7 +11,10 @@ export type AppShellProps = {
      * pages (`{ label, items }`, one per module, say). A nav with no sections
      * is the single "Navigation" group. One entry is marked active: the most
      * specific whose route matches, so '/tasks' and '/tasks/categories' can
-     * both be listed.
+     * both be listed. 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.
      */
     nav: readonly NavEntry[];
     /**

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

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { LogOutIcon, MoonIcon, SunIcon } from 'lucide-react';
+import { ChevronRightIcon, LogOutIcon, MoonIcon, SunIcon } from 'lucide-react';
 import { useTheme } from 'next-themes';
-import { useEffect, useState } from 'react';
+import { useEffect, useId, useState } from 'react';
 import { Link, Navigate, Outlet, useLocation } from 'react-router';
 import { useAuth } from '../../auth/use-auth.js';
 import { activeNavTo, navGroups } from './app-shell-nav.js';
@@ -9,6 +9,7 @@ import { versionHref, versionLabel } from './app-shell-version.js';
 import { ErrorState } from './error-state.js';
 import { useErrorReporter } from '../../error-reporting/error-reporting-context.js';
 import { ReportRoutePattern } from '../../error-reporting/error-reporting-provider.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';
@@ -47,6 +48,64 @@ function VersionEntry({ version }) {
     const className = 'block truncate px-2 type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden';
     return href ? (_jsx("a", { href: href, target: "_blank", rel: "noreferrer", className: `${className} hover:underline`, children: label })) : (_jsx("span", { className: className, children: label }));
 }
+// One group's entries. A plain Link, not NavLink: NavLink marks every
+// matching entry current, and only the most specific one should be
+// (activeNavTo).
+function NavMenu({ items, activeTo }) {
+    return (_jsx(SidebarMenu, { children: items.map(({ to, label, icon: Icon }) => {
+            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));
+        }) }));
+}
+// Whether a collapsible section is open, remembered per browser by its
+// label. Storage can be missing or refuse (a private window): then it's
+// remembered for the page's life only.
+const SECTION_KEY = (label) => `ui-foundation:nav-section:${label}`;
+function storedSectionOpen(label) {
+    try {
+        const stored = window.localStorage.getItem(SECTION_KEY(label));
+        return stored === null ? null : stored === 'open';
+    }
+    catch {
+        return null;
+    }
+}
+function storeSectionOpen(label, open) {
+    try {
+        window.localStorage.setItem(SECTION_KEY(label), open ? 'open' : 'closed');
+    }
+    catch {
+        // Not remembered; the state still holds until the page reloads.
+    }
+}
+// A section whose label folds it (#152). On the icon rail (the collapsed
+// sidebar on a wide screen) its items always show and its label stays the
+// rail's hidden one, so no page is out of reach and no hidden button
+// takes a tab stop. The section holding the current page is always open:
+// arriving in a closed one opens it and remembers that.
+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);
+    // Arriving in a folded section unfolds it, and it stays unfolded after.
+    if (holdsCurrent && stored !== true)
+        setStored(true);
+    useEffect(() => {
+        if (holdsCurrent)
+            storeSectionOpen(group.label, true);
+    }, [holdsCurrent, group.label]);
+    if (state === 'collapsed' && !isMobile) {
+        return (_jsxs(SidebarGroup, { children: [_jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(NavMenu, { items: group.items, activeTo: activeTo }) })] }));
+    }
+    const open = holdsCurrent || (stored ?? group.defaultOpen ?? true);
+    return (_jsxs(SidebarGroup, { "data-collapsible-section": open ? 'open' : 'closed', children: [_jsxs(SidebarGroupLabel, { render: _jsx("button", { type: "button", "aria-expanded": open, "aria-controls": contentId, "aria-disabled": holdsCurrent || undefined, onClick: () => {
+                        if (holdsCurrent)
+                            return;
+                        setStored(!open);
+                        storeSectionOpen(group.label, !open);
+                    } }), className: "w-full justify-between text-left hover:bg-sidebar-accent hover:text-sidebar-accent-foreground aria-disabled:hover:bg-transparent aria-disabled:hover:text-sidebar-foreground/70", children: [group.label, _jsx(ChevronRightIcon, { "aria-hidden": "true", className: cn('transition-transform', open && 'rotate-90') })] }), _jsx(SidebarGroupContent, { id: contentId, hidden: !open, children: _jsx(NavMenu, { items: group.items, activeTo: 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" })] })] }));
 }
@@ -79,13 +138,7 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true,
         return _jsx(Navigate, { to: "/login", replace: true, state: isLoggingOut ? undefined : { from } });
     }
     const activeTo = activeNavTo(nav, location.pathname);
-    return (_jsxs(TooltipProvider, { children: [reporter && _jsx(ReportRoutePattern, { reporter: reporter }), _jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [navGroups(nav).map((group, groupIndex) => (_jsxs(SidebarGroup, { children: [group.label !== undefined && _jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: group.items.map(({ to, label, icon: Icon }) => {
-                                                            // A plain Link, not NavLink: NavLink marks every
-                                                            // matching entry current, and only the most specific
-                                                            // one should be (activeNavTo).
-                                                            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));
-                                                        }) }) })] }, `${groupIndex}:${group.label ?? ''}`))), sidebarExtra] }), _jsxs(SidebarFooter, { children: [version && _jsx(VersionEntry, { version: version }), _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
+    return (_jsxs(TooltipProvider, { children: [reporter && _jsx(ReportRoutePattern, { reporter: reporter }), _jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [navGroups(nav).map((group, groupIndex) => group.collapsible && group.label !== undefined ? (_jsx(CollapsibleNavGroup, { group: { ...group, label: group.label }, activeTo: activeTo }, `${groupIndex}:${group.label}`)) : (_jsxs(SidebarGroup, { children: [group.label !== undefined && _jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(NavMenu, { items: group.items, activeTo: activeTo }) })] }, `${groupIndex}:${group.label ?? ''}`))), sidebarExtra] }), _jsxs(SidebarFooter, { children: [version && _jsx(VersionEntry, { version: version }), _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
                                                         setIsLoggingOut(true);
                                                         // A failed request still ends the session on screen
                                                         // (AuthProvider), so this stays a deliberate logout: a

package/dist/testing/index.d.ts

@@ -1,4 +1,5 @@
 import { type Page } from '@playwright/test';
+import { type NavEntry } from '../components/app/app-shell-nav.js';
 import type { MswOverride } from '../mocks/override.js';
 export type { MswHandle, MswOverride } from '../mocks/override.js';
 /**
@@ -44,16 +45,26 @@ export type A11ySuiteOptions = {
     viewRoutes?: readonly string[];
     /** Screens outside the app shell, e.g. '/login' (and '/register' if the app has it). */
     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
+     * test stays flat as the app grows, and one more test checks the
+     * rendered sidebar links exactly those pages. Left out, the pages are
+     * found in the sidebar at run time, in one test whose timeout grows with
+     * their number.
+     */
+    nav?: readonly NavEntry[];
 };
 /**
  * Accessibility of the real screens in light and dark mode: every page in
- * the Primary nav (discovered, so a new entity's table is covered with no
- * edit), the given form routes, and the logged-out screens. axe's
+ * 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
  * 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 }: A11ySuiteOptions): void;
+export declare function defineA11ySuite({ formRoutes, viewRoutes, loggedOutRoutes, nav }: A11ySuiteOptions): void;
 export type MockModeBannerSuiteOptions = {
     /** Screens to check, logged-out ones included (e.g. '/login'). */
     routes: readonly string[];

package/dist/testing/index.js

@@ -13,6 +13,7 @@
 // are optional peer dependencies, needed only by apps that import this.
 import AxeBuilder from '@axe-core/playwright';
 import { expect, test } from '@playwright/test';
+import { isNavSection } from '../components/app/app-shell-nav.js';
 /**
  * Forces a response for the page's *first* load: set before navigation, so
  * it wins the race against the app's own first fetch. For states forced
@@ -92,36 +93,66 @@ async function navRoutes(page, isMobile) {
         ? (await page.getByRole('button', { name: 'Toggle Sidebar' }).first().click(), page.getByRole('dialog'))
         : page.getByRole('navigation', { name: 'Primary' });
     await expect(nav.getByRole('link').first()).toBeVisible();
+    // By element, not role: a link inside a folded sidebar section is hidden
+    // (AppShell's collapsible sections) and role queries skip it.
     const hrefs = await nav
-        .getByRole('link')
+        .locator('a[href]')
         .evaluateAll((links) => links.map((link) => link.href));
     // Only this app's pages: a sidebarExtra group may link to other sites.
     const origin = new URL(page.url()).origin;
     return [...new Set(hrefs.filter((href) => new URL(href).origin === origin).map((href) => new URL(href).pathname))];
 }
+// A page's share of the one discovering test's time: load, data, axe.
+const NAV_PAGE_BUDGET_MS = 10_000;
+function navEntryRoutes(nav) {
+    return [...new Set(nav.flatMap((entry) => (isNavSection(entry) ? entry.items : [entry]).map((item) => item.to)))];
+}
+async function expectNavPageAccessible(page, route, colorScheme) {
+    await page.goto(route);
+    await expect(page.locator('html')).toHaveClass(colorScheme);
+    // Wait for data, not the loading skeleton, so the real UI is checked.
+    await expect(page.locator('[data-state="loading"]')).toHaveCount(0);
+    await expectNoAxeViolations(page);
+}
 /**
  * Accessibility of the real screens in light and dark mode: every page in
- * the Primary nav (discovered, so a new entity's table is covered with no
- * edit), the given form routes, and the logged-out screens. axe's
+ * 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
  * 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 }) {
+export function defineA11ySuite({ formRoutes, viewRoutes = [], loggedOutRoutes, nav }) {
+    const listed = nav && navEntryRoutes(nav);
+    if (listed) {
+        test('the sidebar links exactly the pages in nav', async ({ page, isMobile }) => {
+            const rendered = await navRoutes(page, isMobile);
+            expect([...rendered].sort(), 'The sidebar and the nav given to defineA11ySuite differ: pass the same NavEntry[] AppShell gets').toEqual([...listed].sort());
+        });
+    }
     for (const colorScheme of ['light', 'dark']) {
         test.describe(`accessibility (${colorScheme})`, () => {
             test.beforeEach(async ({ page }) => {
                 await page.emulateMedia({ colorScheme });
             });
-            test('every nav page has zero axe violations', async ({ page, isMobile }) => {
-                for (const route of await navRoutes(page, isMobile)) {
-                    await page.goto(route);
-                    await expect(page.locator('html')).toHaveClass(colorScheme);
-                    // Wait for data, not the loading skeleton, so the real UI is checked.
-                    await expect(page.locator('[data-state="loading"]')).toHaveCount(0);
-                    await test.step(route, () => expectNoAxeViolations(page));
+            if (listed) {
+                for (const route of listed) {
+                    test(`nav page ${route} has zero axe violations`, async ({ page }) => {
+                        await expectNavPageAccessible(page, route, colorScheme);
+                    });
                 }
-            });
+            }
+            else {
+                test('every nav page has zero axe violations', async ({ page, isMobile }, testInfo) => {
+                    const routes = await navRoutes(page, isMobile);
+                    // One test for every page: its time grows with the app.
+                    test.setTimeout(testInfo.timeout + routes.length * NAV_PAGE_BUDGET_MS);
+                    for (const route of routes) {
+                        await test.step(route, () => expectNavPageAccessible(page, route, colorScheme));
+                    }
+                });
+            }
             for (const route of [...formRoutes, ...loggedOutRoutes]) {
                 test(`${route} has zero axe violations`, async ({ page }) => {
                     await page.goto(route);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.13.0",
+  "version": "4.15.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": {