@tristan2828/ui-foundation 4.20.0 → 4.21.0

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

@@ -269,6 +269,15 @@ is a filled-in example while the Widgets demo is still here).
      Its badge fields sit beside it, each the same `Badge` and variant map
      as its table cell. Edit (a `Button` rendering a `Link` to
      `/<entity>/:id/edit`) and the delete action go in `actions`.
+   - **The browser tab** reads the record's title once it loads
+     ("Wireless Mouse · <app>"): `EntityView` sets it from `title`, and
+     puts the nav's ("Widgets · <app>") back while loading, on an error
+     and when you leave. Nothing to add. `documentTitle` names the tab
+     otherwise, when the title alone wouldn't say what the tab is (a
+     record named by a date, say: `documentTitle={`Entry ${title}`}`);
+     `false` leaves the nav's. Any other screen names its tab with
+     `useDocumentTitle('New Widget')`, which wins over the nav's while the
+     screen is mounted.
    - **Sections**, one per row of the plan's section table, in order.
      Fields are label/value rows (`fields`), labelled as on the form. A
      section that holds one long text or one sub-record list is a block
@@ -461,7 +470,12 @@ is a filled-in example while the Widgets demo is still here).
      values should stay grey, and colour is never the only signal.
 7. **Register routes** for `/<entity>`, `/<entity>/new`, `/<entity>/:id`
    (the view) and `/<entity>/:id/edit` in `src/App.tsx`, and add a nav
-   entry to `src/nav.ts`.
+   entry to `src/nav.ts`. Its label names the browser tab on the list and
+   every page under it ("Widgets · <app>"; the home entry, '/', gives the
+   app's name alone). For a list that should open on one of its saved
+   views, `to` carries that view's query string
+   (`/widgets?status=active`): the entry is still matched on its path, so
+   it stays current on the list and the records under it.
 8. **Add Playwright specs for all three screens**, one test per state
    (`loading`, `empty`, `error`, `validation`, `success`), forced through
    MSW overrides — `forceMswOverride`, `waitForMswReady` and the

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

@@ -1,6 +1,10 @@
 import type { ComponentType } from 'react';
 export type NavItem = {
-    /** The route this entry links to. */
+    /**
+     * The route this entry links to. It may carry a query string, to open a
+     * list on a saved view ('/widgets?status=active'): the entry is matched
+     * on its path alone, so it's still current anywhere under /widgets.
+     */
     to: string;
     label: string;
     icon: ComponentType;
@@ -39,8 +43,25 @@ export type NavGroup = {
  */
 export declare function navGroups(nav: readonly NavEntry[]): NavGroup[];
 /**
- * The `to` of the one entry to mark active: the most specific that matches.
- * With '/tasks' and '/tasks/categories' both in the nav, '/tasks/categories/2'
- * marks Categories only, and '/tasks/3' marks Tasks.
+ * The path a `to` names, without its query string or hash: what an entry is
+ * matched on, and what the a11y suite compares with the rendered sidebar.
+ */
+export declare function navPathname(to: string): string;
+/** Every `to` in a nav, each once, in order: the pages its sidebar links. */
+export declare function navTargets(nav: readonly NavEntry[]): string[];
+/**
+ * The one entry to mark active: the most specific that matches, by the path
+ * of its `to` (its query string ignored). With '/tasks' and
+ * '/tasks/categories' both in the nav, '/tasks/categories/2' marks
+ * Categories only, and '/tasks/3' marks Tasks. Of two entries with the same
+ * path, the first.
  */
+export declare function activeNavItem(nav: readonly NavEntry[], pathname: string): NavItem | undefined;
+/** The `to` of the one entry to mark active (`activeNavItem`). */
 export declare function activeNavTo(nav: readonly NavEntry[], pathname: string): string | undefined;
+/**
+ * The page the nav names for `pathname`, for the browser tab: the active
+ * entry's label. None on the home entry ('/'), whose page is the app
+ * itself, or on a page no entry covers.
+ */
+export declare function navPageLabel(nav: readonly NavEntry[], pathname: string): string | undefined;

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

@@ -30,27 +30,58 @@ export function navGroups(nav) {
         groups.push({ items: run });
     return groups;
 }
-function matches(item, pathname) {
-    if (item.end)
-        return pathname === item.to;
-    if (pathname === item.to)
+/**
+ * The path a `to` names, without its query string or hash: what an entry is
+ * matched on, and what the a11y suite compares with the rendered sidebar.
+ */
+export function navPathname(to) {
+    const end = to.search(/[?#]/);
+    return end === -1 ? to : to.slice(0, end);
+}
+/** Every `to` in a nav, each once, in order: the pages its sidebar links. */
+export function navTargets(nav) {
+    return [...new Set(nav.flatMap((entry) => (isNavSection(entry) ? entry.items : [entry]).map((item) => item.to)))];
+}
+function matches(path, end, pathname) {
+    if (end)
+        return pathname === path;
+    if (pathname === path)
         return true;
     // On a path-segment boundary: '/tasks' is active on '/tasks/3', not on
     // '/tasks-archive'.
-    return pathname.startsWith(item.to.endsWith('/') ? item.to : `${item.to}/`);
+    return pathname.startsWith(path.endsWith('/') ? path : `${path}/`);
 }
 /**
- * The `to` of the one entry to mark active: the most specific that matches.
- * With '/tasks' and '/tasks/categories' both in the nav, '/tasks/categories/2'
- * marks Categories only, and '/tasks/3' marks Tasks.
+ * The one entry to mark active: the most specific that matches, by the path
+ * of its `to` (its query string ignored). With '/tasks' and
+ * '/tasks/categories' both in the nav, '/tasks/categories/2' marks
+ * Categories only, and '/tasks/3' marks Tasks. Of two entries with the same
+ * path, the first.
  */
-export function activeNavTo(nav, pathname) {
+export function activeNavItem(nav, pathname) {
     let best;
+    let bestLength = -1;
     for (const entry of nav) {
         for (const item of isNavSection(entry) ? entry.items : [entry]) {
-            if (matches(item, pathname) && (best === undefined || item.to.length > best.length))
-                best = item.to;
+            const path = navPathname(item.to);
+            if (matches(path, item.end, pathname) && path.length > bestLength) {
+                best = item;
+                bestLength = path.length;
+            }
         }
     }
     return best;
 }
+/** The `to` of the one entry to mark active (`activeNavItem`). */
+export function activeNavTo(nav, pathname) {
+    return activeNavItem(nav, pathname)?.to;
+}
+/**
+ * The page the nav names for `pathname`, for the browser tab: the active
+ * entry's label. None on the home entry ('/'), whose page is the app
+ * itself, or on a page no entry covers.
+ */
+export function navPageLabel(nav, pathname) {
+    const item = activeNavItem(nav, pathname);
+    return item && navPathname(item.to) !== '/' ? item.label : undefined;
+}

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

@@ -4,14 +4,21 @@ import { type AppShellVersion } from './app-shell-version.js';
 export type { NavEntry, NavItem, NavSection } from './app-shell-nav.js';
 export type { AppShellVersion } from './app-shell-version.js';
 export type AppShellProps = {
-    /** Shown at the top of the sidebar (hidden on the collapsed icon rail). */
+    /**
+     * Shown at the top of the sidebar (hidden on the collapsed icon rail), and
+     * the app's part of the browser tab's title: "<page> · <title>", the page
+     * named by the current nav entry, or the title alone on the home entry
+     * ('/'). A screen names its own page with `useDocumentTitle` (EntityView
+     * does, with its record's title).
+     */
     title: string;
     /**
      * The app's primary navigation, in order: pages, and labelled sections of
      * 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. A section marked `collapsible` folds under its label,
+     * both be listed. An entry is matched on its `to`'s path, so `to` can
+     * open a list on a saved view ('/tasks?status=open'). A section marked `collapsible` folds under its label,
      * remembered per browser (`defaultOpen` for the first visit); the one
      * holding the current page stays open, and the icon rail shows every
      * section's items.

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

@@ -4,11 +4,12 @@ import { useTheme } from 'next-themes';
 import { useEffect, useId, useState } from 'react';
 import { Link, Navigate, Outlet, useLocation } from 'react-router';
 import { useAuth } from '../../auth/use-auth.js';
-import { activeNavTo, navGroups } from './app-shell-nav.js';
+import { activeNavTo, navGroups, navPageLabel } from './app-shell-nav.js';
 import { versionHref, versionLabel } from './app-shell-version.js';
 import { ErrorState } from './error-state.js';
 import { useErrorReporter } from '../../error-reporting/error-reporting-context.js';
 import { ReportRoutePattern } from '../../error-reporting/error-reporting-provider.js';
+import { useShellDocumentTitle } from '../../hooks/use-document-title.js';
 import { cn } from 'cn';
 import { Button } from '../ui/button.js';
 import { Skeleton } from '../ui/skeleton.js';
@@ -118,6 +119,7 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true,
     // resolves: that runs before React re-renders, and the <Navigate> this
     // component then renders starts a second navigation that wins.
     const [isLoggingOut, setIsLoggingOut] = useState(false);
+    useShellDocumentTitle(title, navPageLabel(nav, location.pathname));
     if (status === 'loading') {
         return _jsx(AppShellSkeleton, {});
     }

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

@@ -53,8 +53,15 @@ export type EntityViewPlacement = 'main' | 'rail';
  */
 export type EntityViewLayout = 'column' | 'rail';
 export type EntityViewProps = {
-    /** The record's name or title, the page's <h1>. */
+    /** The record's name or title, the page's <h1>, and the browser tab's once it loads (`documentTitle`). */
     title?: string;
+    /**
+     * The browser tab's name for this record once it has loaded: `title`
+     * unless this says otherwise, read as "<this> · <app>" inside `AppShell`.
+     * `false` leaves the tab to the nav ("Widgets · <app>"). Loading, an
+     * error, and leaving the view all show the nav's title.
+     */
+    documentTitle?: string | false;
     /** The title is editable in place; `label` is the field's ("Name"). */
     titleEdit?: EditInPlace & {
         label: string;
@@ -94,4 +101,4 @@ export type EntityViewProps = {
         label: string;
     };
 };
-export declare function EntityView({ title, titleEdit, badges, actions, notice, sections, footer, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;
+export declare function EntityView({ title, documentTitle, titleEdit, badges, actions, notice, sections, footer, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;

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

@@ -49,6 +49,7 @@ import { Button } from '../ui/button.js';
 import { Card, CardContent, CardHeader } from '../ui/card.js';
 import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from '../ui/empty.js';
 import { Skeleton } from '../ui/skeleton.js';
+import { useDocumentTitle } from '../../hooks/use-document-title.js';
 import { EditInPlaceContext } from './edit-in-place.js';
 import { EditInPlaceStore } from './edit-in-place-store.js';
 import { EditableList } from './editable-list.js';
@@ -140,11 +141,12 @@ function Rail({ label, sections }) {
     const [ref, fits] = useFitsWindow();
     return (_jsx("aside", { ref: ref, "aria-label": label, "data-fits": fits ? '' : undefined, className: cn(RAIL_LAYOUT.rail, RAIL_LAYOUT.sticky, 'flex min-w-0 flex-col gap-6'), children: sections.map((section) => (_jsx(ViewSection, { section: section, inRail: true }, section.title))) }));
 }
-export function EntityView({ title, titleEdit, badges, actions, notice, sections, footer, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
+export function EntityView({ title, documentTitle, titleEdit, badges, actions, notice, sections, footer, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
     // Editing in place: one store per view, and the leave-page prompt only
     // while a field is open (or one is always editable).
     const [store] = useState(() => new EditInPlaceStore());
     const editing = useSyncExternalStore(store.subscribe, () => store.editing, () => store.editing);
+    useDocumentTitle(isLoading || error || documentTitle === false ? undefined : (documentTitle ?? title));
     if (error?.kind === 'notfound') {
         // A record that doesn't exist and one that belongs to another user are
         // the same plain 404, so this never says which. Retrying can't help.

package/dist/hooks/use-document-title.d.ts

@@ -0,0 +1,27 @@
+export declare const DOCUMENT_TITLE_SEPARATOR = " \u00B7 ";
+type TitleTarget = {
+    title: string;
+};
+export type DocumentTitles = {
+    /** AppShell's: the app's name and the nav's page (none on the home page). `null` once it unmounts. */
+    setShell: (shell: {
+        app: string;
+        page?: string;
+    } | null) => void;
+    /** A view's page title, by the view's id. `undefined` (not loaded yet) leaves the tab to the others; its place is kept. */
+    setView: (id: string, page: string | undefined) => void;
+    /** The view unmounted. */
+    releaseView: (id: string) => void;
+};
+export declare function createDocumentTitles(target: TitleTarget): DocumentTitles;
+/**
+ * Names the browser tab after this screen while it's mounted: "New Widget"
+ * reads "New Widget · <app>" inside `AppShell`. Wins over the page the nav
+ * names, whichever arrives first; when the screen goes, the nav's title
+ * comes back. `undefined` (a record still loading) leaves the nav's.
+ * `EntityView` already does this with its `title`.
+ */
+export declare function useDocumentTitle(title: string | undefined): void;
+/** AppShell's side: the app's name and the page its nav names. */
+export declare function useShellDocumentTitle(app: string, page: string | undefined): void;
+export {};

package/dist/hooks/use-document-title.js

@@ -0,0 +1,72 @@
+import { useEffect, useId } from 'react';
+// The browser tab's title, "<page> · <app>", from two sources that can
+// arrive in either order: AppShell's (the app's name, and the page its nav
+// names for the current path) and the views' own (useDocumentTitle, and
+// EntityView's record once it loads). A view's title wins over the nav's
+// while that view is mounted, whichever was set first, and the nav's comes
+// back when it goes. With neither, the tab keeps the title it had before
+// (index.html's).
+//
+// createDocumentTitles takes the document, so the rules are unit tested
+// against a fake one (tests/use-document-title.test.ts).
+export const DOCUMENT_TITLE_SEPARATOR = ' · ';
+export function createDocumentTitles(target) {
+    let shell = null;
+    // In the order views first set a title: the latest one showing wins.
+    const views = new Map();
+    // The title before anything here set one, put back once nothing sets one.
+    let before = null;
+    function apply() {
+        const view = [...views.values()].reverse().find((page) => page);
+        const page = view ?? shell?.page;
+        const title = shell ? (page ? `${page}${DOCUMENT_TITLE_SEPARATOR}${shell.app}` : shell.app) : page;
+        if (title) {
+            before ??= target.title;
+            target.title = title;
+        }
+        else if (before !== null) {
+            target.title = before;
+            before = null;
+        }
+    }
+    return {
+        setShell(next) {
+            shell = next;
+            apply();
+        },
+        setView(id, page) {
+            views.set(id, page || undefined);
+            apply();
+        },
+        releaseView(id) {
+            views.delete(id);
+            apply();
+        },
+    };
+}
+// One per page, made on first use (never while rendering on a server).
+let documentTitles;
+const titles = () => (documentTitles ??= createDocumentTitles(document));
+/**
+ * Names the browser tab after this screen while it's mounted: "New Widget"
+ * reads "New Widget · <app>" inside `AppShell`. Wins over the page the nav
+ * names, whichever arrives first; when the screen goes, the nav's title
+ * comes back. `undefined` (a record still loading) leaves the nav's.
+ * `EntityView` already does this with its `title`.
+ */
+export function useDocumentTitle(title) {
+    const id = useId();
+    // Two effects, so a changed title keeps this screen's place among others
+    // and only unmounting gives it up.
+    useEffect(() => {
+        titles().setView(id, title);
+    }, [id, title]);
+    useEffect(() => () => titles().releaseView(id), [id]);
+}
+/** AppShell's side: the app's name and the page its nav names. */
+export function useShellDocumentTitle(app, page) {
+    useEffect(() => {
+        titles().setShell({ app, page });
+    }, [app, page]);
+    useEffect(() => () => titles().setShell(null), []);
+}

package/dist/index.d.ts

@@ -46,6 +46,7 @@ export { createQueryClient } from './api/query-client.js';
 export { useTableUrlState } from './hooks/use-table-url-state.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';
 export { useRecordUpdate, type RecordChange, type RecordUpdateOptions, } from './hooks/use-record-update.js';
 export { useIsMobile } from './hooks/use-mobile.js';
 export { useWakeLock } from './hooks/use-wake-lock.js';

package/dist/index.js

@@ -50,6 +50,7 @@ export { createQueryClient } from './api/query-client.js';
 // Hooks
 export { useTableUrlState } from './hooks/use-table-url-state.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';
 export { useIsMobile } from './hooks/use-mobile.js';
 // Timed screens (docs/foundation/timed-screens.md)

package/dist/testing/index.js

@@ -13,7 +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';
+import { navPathname, navTargets } 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
@@ -80,7 +80,8 @@ export async function expectNoAxeViolations(page, options = {}) {
     const results = await builder.analyze();
     expect(results.violations).toEqual([]);
 }
-// The app's own pages, read from the Primary nav. Below the sidebar's
+// The app's own pages, read from the Primary nav: each link's path and
+// query string, as it would be visited. Below the sidebar's
 // mobile breakpoint the nav renders into an off-canvas Sheet *portaled to
 // document.body*, outside the <nav aria-label="Primary"> landmark, so the
 // links are read from the sheet there. Keyed off the `isMobile` fixture,
@@ -100,13 +101,14 @@ async function navRoutes(page, isMobile) {
         .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))];
+    const own = hrefs.map((href) => new URL(href)).filter((url) => url.origin === origin);
+    return [...new Set(own.map((url) => `${url.pathname}${url.search}`))];
 }
+// The pages a list of routes names, by path: a `to` that opens a list on a
+// saved view ('/widgets?status=active') is the /widgets page.
+const pagePaths = (routes) => [...new Set(routes.map(navPathname))].sort();
 // 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)))];
-}
 /**
  * Every data view on the page has loaded: at least one shows its data (or,
  * with `{ success: false }`, the page has its screen up), and none still
@@ -144,11 +146,13 @@ async function expectNavPageAccessible(page, route, colorScheme) {
  * emulateMedia switches it.
  */
 export function defineA11ySuite({ formRoutes, viewRoutes = [], loggedOutRoutes, nav }) {
-    const listed = nav && navEntryRoutes(nav);
+    // 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) {
         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());
+            expect(pagePaths(rendered), 'The sidebar and the nav given to defineA11ySuite differ: pass the same NavEntry[] AppShell gets').toEqual(pagePaths(listed));
         });
     }
     for (const colorScheme of ['light', 'dark']) {

package/package.json

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