npm - @terpjs/react-core - Versions diffs - 0.9.0 → 0.11.0 - Mend

@terpjs/react-core 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (101) hide show

package/README.md +57 -21
package/package.json +6 -5
package/src/AppShell.test.tsx +323 -4
package/src/AppShell.tsx +401 -66
package/src/EmptyState.test.tsx +30 -0
package/src/EmptyState.tsx +23 -3
package/src/Field.test.tsx +30 -0
package/src/Field.tsx +36 -8
package/src/FormPage.tsx +54 -0
package/src/LoginView.test.tsx +34 -2
package/src/LoginView.tsx +43 -18
package/src/ModuleNav.test.tsx +17 -10
package/src/ModuleNav.tsx +35 -3
package/src/Page.tsx +23 -1
package/src/ProfileView.test.tsx +1 -1
package/src/ProfileView.tsx +2 -4
package/src/SettingsPage.tsx +50 -0
package/src/SplitPage.tsx +150 -0
package/src/UserMenu.test.tsx +28 -5
package/src/UserMenu.tsx +15 -9
package/src/admin/AuditLogAdmin.tsx +21 -7
package/src/admin/GroupCreate.tsx +17 -3
package/src/admin/GroupDetail.tsx +48 -13
package/src/admin/GroupsAdmin.tsx +13 -5
package/src/admin/UserCreate.tsx +40 -11
package/src/admin/UserDetail.tsx +4 -1
package/src/admin/UsersAdmin.tsx +14 -6
package/src/admin/admin.test.tsx +212 -8
package/src/admin/fieldErrors.ts +45 -0
package/src/bootstrap.test.tsx +208 -0
package/src/bootstrap.tsx +121 -5
package/src/breakpoints.ts +41 -0
package/src/dataview/DataView.tsx +12 -5
package/src/dataview/DataViewCardList.tsx +8 -7
package/src/dataview/DataViewPagination.tsx +15 -8
package/src/dataview/DataViewTable.tsx +32 -21
package/src/dataview/README.md +13 -2
package/src/dataview/index.ts +1 -0
package/src/dataview/internal.tsx +31 -1
package/src/dataview/types.ts +26 -3
package/src/format.test.tsx +213 -0
package/src/format.ts +150 -0
package/src/icons.tsx +67 -5
package/src/index.ts +56 -6
package/src/layout.manifest.json +118 -0
package/src/layout.manifest.test.ts +205 -0
package/src/layout.test.tsx +198 -1
package/src/layout.tsx +208 -11
package/src/layoutContract.test.tsx +311 -2
package/src/layoutContract.ts +44 -3
package/src/layoutDeclaration.test.ts +435 -0
package/src/layoutDeclaration.ts +531 -0
package/src/locale.tsx +12 -0
package/src/markers.test.ts +27 -5
package/src/nav.test.ts +234 -4
package/src/nav.ts +180 -6
package/src/navActive.test.ts +115 -0
package/src/navActive.ts +119 -0
package/src/navLink.tsx +20 -2
package/src/previewBridge.test.ts +327 -0
package/src/previewBridge.ts +278 -0
package/src/raw.d.ts +14 -2
package/src/review.test.tsx +272 -0
package/src/router.test.tsx +575 -2
package/src/router.tsx +212 -19
package/src/styles.test.ts +535 -58
package/src/styles.ts +1130 -111
package/src/theme.test.tsx +29 -0
package/src/theme.themes.test.ts +13 -7
package/src/theme.tsx +30 -33
package/src/themes.ts +54 -0
package/src/toast.tsx +2 -1
package/src/tokens.guard.test.ts +239 -0
package/src/typography.test.tsx +213 -0
package/src/typography.tsx +255 -0
package/src/ui/Avatar.test.tsx +63 -0
package/src/ui/Avatar.tsx +65 -0
package/src/ui/Button.test.tsx +69 -3
package/src/ui/Button.tsx +57 -4
package/src/ui/Card.test.tsx +13 -0
package/src/ui/Card.tsx +28 -1
package/src/ui/Checkbox.tsx +10 -2
package/src/ui/Combobox.test.tsx +139 -0
package/src/ui/Combobox.tsx +255 -43
package/src/ui/DatePicker.tsx +44 -12
package/src/ui/Input.test.tsx +123 -0
package/src/ui/Input.tsx +65 -2
package/src/ui/Menu.tsx +16 -5
package/src/ui/Popover.tsx +13 -0
package/src/ui/Radio.tsx +10 -5
package/src/ui/Select.test.tsx +232 -0
package/src/ui/Select.tsx +177 -8
package/src/ui/Switch.tsx +10 -2
package/src/ui/Tabs.test.tsx +28 -0
package/src/ui/Tabs.tsx +30 -6
package/src/ui/Tooltip.test.tsx +56 -1
package/src/ui/Tooltip.tsx +69 -6
package/src/uiText.literals.test.ts +199 -0
package/src/uiText.tsx +36 -0
package/src/unwrap.test.ts +132 -0
package/src/unwrap.ts +118 -32

package/src/bootstrap.test.tsx CHANGED Viewed

@@ -64,4 +64,212 @@ describe("renderTerpApp", () => {
     );
     root.remove();
   });
+  it("forwards the layout declaration to buildAppRouter", () => {
+    // Same shape as the navGroups test below, for the same reason: the forwarding is one line in
+    // a hand-written enumeration, and a missing line leaves every gate on the declaration green
+    // while the one-call entry point — the one apps actually use — ignores the file entirely.
+    //
+    // Gated through a refusal only `buildAppRouter` can raise, and that took a second attempt.
+    // The first version asserted the resolver's enum refusal — which `renderTerpApp` now raises
+    // ITSELF, from its own resolve call, before `buildAppRouter` is reached. So it threw with
+    // the forwarding line deleted and reported green: a test that passes with the bug. An
+    // UNKNOWN CONTRACT is refused only inside `buildAppRouter`, against its own table, so the
+    // throw here observes the one line under test and nothing else.
+    //
+    // Mutation: delete `layout: options.layout` from the buildAppRouter call, and this stops
+    // throwing.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    try {
+      expect(() =>
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          layout: { contract: "bespoke" },
+          rootElement: root,
+        }),
+      ).toThrow(/Unknown layout contract "bespoke"/);
+    } finally {
+      root.remove();
+    }
+  });
+  it("opens on the palette the declaration names, and on the option when it does not", async () => {
+    // The forwarding tests above gate their line through a THROW, because a signed-out mount
+    // renders no shell to read. The palette is the exception and gets the stronger assertion:
+    // `ThemeProvider` wraps `RequireAuth`, so it mounts signed out, and the attribute it writes
+    // on <html> is the actual observable effect an app ships. A throw here would only prove the
+    // file was validated, not that the value reached anything.
+    //
+    // Mutations, both red, and both by reading NULL rather than "midnight": `"system"` is the
+    // provider's default and it REMOVES the attribute, so neither mutation can produce the
+    // string. (An earlier version of this comment said the first one reads "system", which is
+    // not a value `data-theme` ever holds.) Pass `options.defaultTheme` to `ThemeProvider`
+    // instead of `layout.defaultTheme`, or drop `defaultTheme` from the explicit set handed to
+    // the resolver, and the corresponding assertion reads null.
+    for (const [label, options] of [
+      ["from the file", { layout: { defaultTheme: "midnight" } }],
+      ["from the option", { defaultTheme: "midnight" as const }],
+    ] as const) {
+      // A stored choice outranks the default — that is the whole point of a *default* — so the
+      // assertion would be about localStorage rather than about the declaration without this.
+      window.localStorage.clear();
+      document.documentElement.removeAttribute("data-theme");
+      const root = document.createElement("div");
+      document.body.appendChild(root);
+      try {
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          rootElement: root,
+          ...options,
+        });
+        await waitFor(() =>
+          expect(
+            document.documentElement.getAttribute("data-theme"),
+            `${label}: the declared palette must reach <html>`,
+          ).toBe("midnight"),
+        );
+      } finally {
+        root.remove();
+        document.documentElement.removeAttribute("data-theme");
+      }
+    }
+  });
+  it("refuses the palette named in the file and passed as an option", () => {
+    // Non-exclusive per ADR 0009 — either source alone is complete, as the test above shows —
+    // but not both, and not even when they agree. Reachable only through `renderTerpApp`,
+    // because `buildAppRouter` has no palette option to conflict with.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    try {
+      expect(() =>
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          layout: { defaultTheme: "midnight" },
+          defaultTheme: "midnight",
+          rootElement: root,
+        }),
+      ).toThrow(/both declare "defaultTheme" \(file: "midnight", code: "midnight"\)/);
+    } finally {
+      root.remove();
+    }
+  });
+  it("names every doubly-declared key at once, groups included", async () => {
+    // The property the resolver's `conflicts.join("; ")` exists for, asserted through the entry
+    // point apps use — and it was broken here. `renderTerpApp` resolves the declaration itself
+    // (the palette mounts outside the router) and its explicit set omitted `navGroups`, so a
+    // groups conflict was invisible from this side: the author fixed the density conflict,
+    // re-ran, and hit a second, different refusal. Mutation: drop `navGroups: options.navGroups`
+    // from the resolve call at the top of `renderTerpApp` and this names only the density.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    let message = "";
+    try {
+      renderTerpApp({
+        title: "Test",
+        modules: { "./modules/notes/module.tsx": notesModule },
+        layout: {
+          shell: {
+            density: "comfortable",
+            navGroups: [{ id: "work", label: "Workspace" }],
+          },
+        },
+        density: "compact",
+        navGroups: [{ id: "admin", label: "Admin" }],
+        rootElement: root,
+      });
+    } catch (error) {
+      message = (error as Error).message;
+    } finally {
+      root.remove();
+    }
+    expect(message).toContain('"shell.density"');
+    expect(message).toContain('"shell.navGroups"');
+  });
+  it("refuses the navigation groups named in the file and passed as an option", () => {
+    // The array key travelling the same seam as the scalars, end to end: the resolver sees the
+    // file, `buildAppRouter` hands the resolved list to the shell, and declaring the groups in
+    // both places is one fact declared twice. Named by id, because a list of objects stringified
+    // into an error message tells the reader nothing they can match up.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    try {
+      expect(() =>
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          layout: { shell: { navGroups: [{ id: "work", label: "Workspace" }] } },
+          navGroups: [{ id: "admin", label: "Admin" }],
+          rootElement: root,
+        }),
+      ).toThrow(/both declare "shell\.navGroups" \(file: "work", code: "admin"\)/);
+    } finally {
+      root.remove();
+    }
+  });
+  it("refuses duplicate ids declared in the file, through the router's own check", () => {
+    // The check lives in `buildAppRouter` and now reads the RESOLVED list, so this is the proof
+    // that a duplicate reaches it from the file and not only from the option. Mutation: point
+    // the check back at `options.navGroups` and this stops throwing while the option-side test
+    // above stays green.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    try {
+      expect(() =>
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          layout: {
+            shell: {
+              navGroups: [
+                { id: "work", label: "Workspace" },
+                { id: "work", label: "Again" },
+              ],
+            },
+          },
+          rootElement: root,
+        }),
+      ).toThrow(/duplicate id\(s\): work/);
+    } finally {
+      root.remove();
+    }
+  });
+  it("forwards navGroups to buildAppRouter", () => {
+    // `renderTerpApp` hands its options to `buildAppRouter` through a hand-written enumeration of
+    // names, and nothing covered it — `navPlacement`, `contentWidth` and `density` all travel that
+    // same list with no assertion that any of them arrives. A missing line there leaves every
+    // other gate on groups green while the feature does nothing for every app using the one-call
+    // entry point, which is the entry point apps actually use.
+    //
+    // Gated through the duplicate-id refusal rather than through a rendered label, and that is
+    // the point of doing it this way: this test mounts the SIGNED-OUT app, so the shell never
+    // renders and there is no nav to read. The throw only happens if the option was forwarded, so
+    // it observes the one line under test and nothing else. Mutation: delete
+    // `navGroups: options.navGroups` from the buildAppRouter call, and this stops throwing.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    try {
+      expect(() =>
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          navGroups: [
+            { id: "work", label: "Werkruimte" },
+            { id: "work", label: "Weer werkruimte" },
+          ],
+          rootElement: root,
+        }),
+      ).toThrow(/duplicate id\(s\): work/);
+    } finally {
+      root.remove();
+    }
+  });
 });

package/src/bootstrap.tsx CHANGED Viewed

@@ -2,7 +2,7 @@ import { RouterProvider } from "@tanstack/react-router";
 import { StrictMode } from "react";
 import type { ComponentType, ReactNode } from "react";
 import { createRoot } from "react-dom/client";
-import type { ModuleManifest } from "@terpjs/contract";
+import type { ModuleManifest, NavGroup } from "@terpjs/contract";
 import { LoginView } from "./LoginView";
 import type { DevCredentials } from "./LoginView";
@@ -10,7 +10,10 @@ import { RequireAuth } from "./RequireAuth";
 import { TerpProvider } from "./TerpProvider";
 import { AdminHub } from "./admin/AdminHub";
 import { adminModule } from "./admin/module";
+import { resolveLayoutDeclaration } from "./layoutDeclaration";
+import type { LayoutDeclaration } from "./layoutDeclaration";
 import { LocaleProvider } from "./locale";
+import { installPreviewBridge } from "./previewBridge";
 import type { LocaleCatalog } from "./locale";
 import { buildAppRouter } from "./router";
 import type { SsoProvider } from "./sso";
@@ -97,8 +100,61 @@ export interface RenderTerpAppOptions {
   modules: Record<string, unknown>;
   /** Brand mark in the sidebar (any rendered node); default: the placeholder TerpMark. */
   logo?: ReactNode;
+  /**
+   * The dark-theme brand mark ({@link AppShell.logoDark}); the stylesheet picks per appearance,
+   * with no code of the app's involved.
+   *
+   * Forwarded because it was not, and the template already told every new app to pass it — so
+   * the documented example did not typecheck. Third instance of the shape this ADR's Context
+   * names for `headerActions`: a slot that exists on the shell and cannot be reached from the
+   * one-call bootstrap.
+   */
+  logoDark?: ReactNode;
+  /**
+   * Extra header content, rendered before the theme / language controls.
+   *
+   * `AppShell` has had this slot all along and `renderTerpApp` did not pass it, so the only way
+   * to reach it was to abandon the one-call bootstrap for `TerpProvider` + `buildAppRouter` —
+   * a slot that existed and was unreachable from the entry point every app uses.
+   */
+  headerActions?: ReactNode;
   /** Footer line under the content; default: a muted line with the app title. */
   footer?: ReactNode;
+  /**
+   * Cap routed content at the published measure, with each page's header on the full track
+   * ({@link AppShell.contentWidth}); default `"full"`, which changes nothing. Move the measure
+   * itself from an app's own `theme.css`: `--shell-content-max-width`.
+   */
+  contentWidth?: "full" | "measured";
+  /**
+   * App-wide density — one attribute on the shell root, from which every control height and cell
+   * padding follows by token inheritance.
+   *
+   * **No default.** Omitting it stamps nothing, so an app setting `data-density` on `<html>`
+   * (ADR 0094 §4's app-wide case) still reaches everything; a shell default would silently win
+   * against it.
+   */
+  density?: "comfortable" | "compact";
+  /**
+   * Where the primary navigation lives on desktop ({@link AppShell.navPlacement}): the
+   * full-height `"sidebar"` (default, and what every shell renders today) or `"header"`, a
+   * horizontal row in the header with no sidebar at all. Below the mobile breakpoint both are
+   * the drawer.
+   */
+  navPlacement?: "sidebar" | "header";
+  /**
+   * The app's navigation groups ({@link AppShell.navGroups}), referenced by manifest items
+   * through `NavItem.group`. Omit for the flat, unlabelled sidebar every app renders today.
+   *
+   * This is the app's half of the model and there is no module-side equivalent: a group spans
+   * modules, so its label and its position cannot belong to any one of them. A duplicate id is
+   * refused when the router is built.
+   *
+   * Prefer {@link RenderTerpAppOptions.layout}: `shell.navGroups` in the app's own
+   * `frontend/layout-contract.json` says the same thing in the one document a tool can read and
+   * rewrite. Declaring the groups in both places is refused rather than silently resolved.
+   */
+  navGroups?: readonly NavGroup[];
   /**
    * Ship the packaged admin area (default `true`): the admin-gated sidebar entry, the
    * `/admin` hub, and the users / groups / audit screens over the base-profile
@@ -131,15 +187,40 @@ export interface RenderTerpAppOptions {
   locales?: Record<string, LocaleCatalog>;
   /** Starting locale when the user has not chosen one; default: the first `locales` key. */
   defaultLocale?: string;
-  /** Starting theme when the user has not chosen one; default "system" (OS preference). */
+  /**
+   * Starting theme when the user has not chosen one; default `"system"` (OS preference).
+   *
+   * Prefer {@link RenderTerpAppOptions.layout}: `"defaultTheme"` in the app's own
+   * `frontend/layout-contract.json` says the same thing in the one document a tool can read and
+   * rewrite, which is the whole reason the declaration exists. Declaring it in both places is
+   * refused rather than silently resolved.
+   */
   defaultTheme?: Theme;
   /**
    * Opt into a slot-typed layout contract (ADR 0079), e.g. `"standard"`: every routed
    * archetype's body slot then accepts only the components the contract allows there,
-   * verified at runtime (fail closed). Keep it in sync with the app's checked-in
-   * `layout-contract.json` (the `terp/layout-contract` lint half).
+   * verified at runtime (fail closed).
+   *
+   * Prefer {@link RenderTerpAppOptions.layout} — importing the app's own
+   * `frontend/layout-contract.json` declares this once for both halves. This option used to
+   * carry the instruction "keep it in sync with the checked-in file", which is a defect
+   * written as advice: the lint rule reads the file, this read the option, and nothing
+   * compared them.
    */
   layoutContract?: string;
+  /**
+   * The app's checked-in layout declaration: `import layout from "../layout-contract.json"`.
+   *
+   * One file declaring the layout contract for both the lint rule and the runtime check, plus
+   * the palette the app opens on and the shell's own shape — density, navigation placement,
+   * content measure, and the navigation groups a module's items name by id. Declaring a key
+   * here and passing the matching option is refused rather than silently resolved.
+   *
+   * The authoritative list is `TOP_LEVEL_KEYS` and `SHELL_KEYS` in
+   * {@link ./layoutDeclaration}, and the published `layout.manifest.json` beside them. This
+   * sentence is a restatement and has already drifted once.
+   */
+  layout?: LayoutDeclaration;
   /** Mount point; default `document.getElementById("root")`. */
   rootElement?: HTMLElement | null;
 }
@@ -223,6 +304,27 @@ export function withAdminArea(
  * stylesheet import. Drop to `TerpProvider` + `buildAppRouter` for full control.
  */
 export function renderTerpApp(options: RenderTerpAppOptions): void {
+  // Resolved here as well as inside `buildAppRouter`, because the one key mounted OUTSIDE the
+  // router is the palette: `ThemeProvider` wraps everything, the router included.
+  //
+  // Two calls, one answer — but only while both are handed the SAME option set, and that is a
+  // standing obligation rather than something the code enforces. It was broken once already,
+  // within a day: `navGroups` was added to the router's set and not to this one, so a groups
+  // conflict declared through `renderTerpApp` was invisible here and the resolver's
+  // report-every-conflict-at-once property quietly became report-some. Anything added to
+  // `BuildAppRouterOptions` and passed at the bottom of this function belongs in this call too;
+  // `bootstrap.test.tsx` names both conflicts in one message to hold that.
+  //
+  // `layout` and every option still go down untouched, so a key added to the declaration later
+  // reaches the router without being threaded through this function first.
+  const layout = resolveLayoutDeclaration(options.layout, {
+    contract: options.layoutContract,
+    density: options.density,
+    navPlacement: options.navPlacement,
+    contentWidth: options.contentWidth,
+    navGroups: options.navGroups,
+    defaultTheme: options.defaultTheme,
+  });
   const collected = collectModules(options.modules);
   const { manifests, views } = withAdminArea(
     collected.manifests,
@@ -233,16 +335,30 @@ export function renderTerpApp(options: RenderTerpAppOptions): void {
     views,
     title: options.title,
     logo: options.logo,
+    logoDark: options.logoDark,
+    headerActions: options.headerActions,
     footer: options.footer,
+    contentWidth: options.contentWidth,
+    density: options.density,
+    navPlacement: options.navPlacement,
+    navGroups: options.navGroups,
     layoutContract: options.layoutContract,
+    layout: options.layout,
   });
   const root = options.rootElement ?? document.getElementById("root");
   if (!root) {
     throw new Error('renderTerpApp: no root element (add <div id="root"> or pass rootElement).');
   }
+  // The channel a tool showing this app in an iframe can ask it questions through, and it exists
+  // ONLY in a development build: `import.meta.env.DEV` folds to false in production and the
+  // module goes with it, so a deployed app carries no listener at all. Same mechanism, and the
+  // same reason, as the template's dev sign-in credentials. See ./previewBridge.
+  if (import.meta.env.DEV) {
+    installPreviewBridge();
+  }
   createRoot(root).render(
     <StrictMode>
-      <ThemeProvider defaultTheme={options.defaultTheme}>
+      <ThemeProvider defaultTheme={layout.defaultTheme}>
         <LocaleProvider
           locales={options.locales ?? { en: {} }}
           defaultLocale={options.defaultLocale}

package/src/breakpoints.ts ADDED Viewed

@@ -0,0 +1,41 @@
+/**
+ * The one viewport cutover the framework has, in the one place it is written.
+ *
+ * It was written in three: `AppShell` and `DataView` each declared
+ * `const MOBILE_BREAKPOINT = "(max-width: 768px)"` verbatim — the duplication the diagnosis
+ * named — and the responsive `Stack` props would have made a third copy, this time in the
+ * stylesheet where the first two could not see it.
+ *
+ * ## Why the value is a literal and not `var(--breakpoint-md)`
+ *
+ * The contract publishes `--breakpoint-md: 768px`, and neither consumer can read it. CSS
+ * forbids a custom property in a media-query condition, and `matchMedia` takes a string, so
+ * a component would have to resolve the property off `document.documentElement` at runtime —
+ * which is a layout read on every mount, breaks under SSR where there is no document, and
+ * turns a static query into a value that can change after first paint.
+ *
+ * So the literal stays, and the drift it invites is gated instead:
+ * `styles.test.ts` reads `--breakpoint-md` out of the contract's token sheet and refuses a
+ * mismatch here or in the stylesheet. The token remains the published source of truth about
+ * what the number IS; this module is the single place it is spelled for use.
+ *
+ * ## Why WIDE is a negation
+ *
+ * `NARROW` and `WIDE` have to partition the viewport exactly: a width that satisfies both
+ * would render the shell's drawer beside a row-direction toolbar, and a width satisfying
+ * neither would render nothing at all. Two independent queries cannot guarantee that — the
+ * conventional pairing is `max-width: 767.98px` with `min-width: 768px`, which works but
+ * makes the partition depend on an epsilon somebody chose, and picking one here would also
+ * have moved the shell's existing behaviour at exactly 768px.
+ *
+ * `not all and (max-width: 768px)` is the complement of `NARROW` by construction. The
+ * `not all and` spelling rather than the shorter `not (…)` because it is the form every
+ * browser has supported since media queries existed, and this is a stylesheet a consumer
+ * cannot patch.
+ */
+/** The condition both narrow-viewport components match on (`matchMedia`, so no `@media`). */
+export const NARROW_VIEWPORT = "(max-width: 768px)";
+/** The stylesheet's complement of {@link NARROW_VIEWPORT} — everything above the cutover. */
+export const WIDE_VIEWPORT_QUERY = "not all and (max-width: 768px)";

package/src/dataview/DataView.tsx CHANGED Viewed

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { ReactNode } from "react";
+import { NARROW_VIEWPORT } from "../breakpoints";
 import { EmptyState } from "../EmptyState";
 import { ErrorState } from "../ErrorState";
 import type { BadgeTone } from "../ui/Badge";
@@ -26,7 +27,6 @@ import type {
   ViewStateRepository,
 } from "./types";
-const MOBILE_BREAKPOINT = "(max-width: 768px)";
 /** Embedded views render all rows; the parent owns paging. */
 const EMBEDDED_PAGE_SIZE = 10_000;
@@ -49,7 +49,14 @@ interface DataViewBaseProps<T> {
    *
    * `"comfortable"` stamps NO attribute, because comfortable IS the token sheet's
    * `:root` value and an attribute for it would match no rule. The consequence worth
-   * knowing: inside an already-compact subtree, `density="comfortable"` does not make
+   * (Historic note, since the prop's behaviour changed: `"comfortable"` used to stamp
+   * nothing, on the grounds that comfortable was the sheet's own `:root` value — which was
+   * true until the shell could make an ancestor compact. Both values are stamped now, and
+   * both have a rule. Where nothing above is compact the two compute identically, so the
+   * change is zero-diff by construction.)
+   *
+   * What used to be worth knowing: inside an already-compact subtree, `density="comfortable"`
+   * did not make
    * this view comfortable again. Expressing that needs a named comfortable copy of
    * each live token, which ADR 0094 defers until something asks — nothing can ask
    * until the shell takes a density of its own.
@@ -129,13 +136,13 @@ function useIsMobile(): boolean {
     () =>
       typeof window !== "undefined" &&
       typeof window.matchMedia === "function" &&
-      window.matchMedia(MOBILE_BREAKPOINT).matches,
+      window.matchMedia(NARROW_VIEWPORT).matches,
   );
   useEffect(() => {
     if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
       return;
     }
-    const media = window.matchMedia(MOBILE_BREAKPOINT);
+    const media = window.matchMedia(NARROW_VIEWPORT);
     const onChange = () => setIsMobile(media.matches);
     media.addEventListener("change", onChange);
     return () => media.removeEventListener("change", onChange);
@@ -147,7 +154,7 @@ function DataViewInner<T>(props: DataViewProps<T>) {
   const { strings, resolve } = useDataViewText();
   const embedded = props.variant === "embedded";
   // Only the compact value is expressible as an attribute; see the prop's doc comment.
-  const densityAttribute = props.density === "compact" ? "compact" : undefined;
+  const densityAttribute = props.density;
   // Hoisted rather than written inline at the two roots, which is what the density
   // attribute above already does and what keeps the marker scanner out of a trap: it
   // reads a whole expression container, so every string literal inside one counts as a

package/src/dataview/DataViewCardList.tsx CHANGED Viewed

@@ -5,7 +5,7 @@ import type { UiText } from "../uiText";
 import { DataViewExpandToggle } from "./DataViewExpandableRow";
 import { DataViewRowActions } from "./DataViewRowActions";
-import { useDataViewText } from "./internal";
+import { useCellFormatter, useDataViewText } from "./internal";
 import type { DataViewColumn, DataViewRowAction } from "./types";
 export interface DataViewCardListProps<T> {
@@ -33,6 +33,7 @@ function slotValue<T>(
   columns: DataViewColumn<T>[],
   row: T,
   slot: "title" | "subtitle" | "status" | "date",
+  formatCell: (value: unknown) => ReactNode,
 ): ReactNode {
   const column = columns.find((candidate) => candidate.meta?.mobileSlot === slot);
   if (column === undefined) {
@@ -41,8 +42,7 @@ function slotValue<T>(
   if (column.cell !== undefined) {
     return column.cell(row);
   }
-  const value = column.accessor?.(row);
-  return value === null || value === undefined ? null : String(value);
+  return formatCell(column.accessor?.(row));
 }
 /**
@@ -129,10 +129,11 @@ export function DataViewCardList<T>(props: DataViewCardListProps<T>) {
 }
 function DefaultCardBody<T>({ row, columns }: { row: T; columns: DataViewColumn<T>[] }) {
-  const title = slotValue(columns, row, "title");
-  const subtitle = slotValue(columns, row, "subtitle");
-  const status = slotValue(columns, row, "status");
-  const date = slotValue(columns, row, "date");
+  const formatCell = useCellFormatter();
+  const title = slotValue(columns, row, "title", formatCell);
+  const subtitle = slotValue(columns, row, "subtitle", formatCell);
+  const status = slotValue(columns, row, "status", formatCell);
+  const date = slotValue(columns, row, "date", formatCell);
   return (
     <div data-terp="dataview-card-fields">
       <div data-terp="dataview-card-heading">

package/src/dataview/DataViewPagination.tsx CHANGED Viewed

@@ -37,14 +37,21 @@ export function DataViewPagination({
   return (
     <div data-terp="dataview-pagination">
       <span>{format(strings.resultsRange, { from, to, total: totalCount })}</span>
+      {/* aria-disabled, not disabled, and the difference is where focus goes. Each of these
+          four buttons has a bound condition recomputed from what its own click just changed, so
+          pressing "next" until the last page disabled the very control the user was operating —
+          and a disabled element cannot hold focus, so the browser dropped it to <body>. A
+          keyboard user paging to the end lost their place in the document at the exact moment
+          they arrived. Kept focusable and announced as disabled instead, with the handler inert
+          on the bound; the sheet paints [aria-disabled="true"] identically to :disabled. */}
       {pageCount > 1 && (
         <span data-terp="dataview-pager">
           <span>{format(strings.pageOf, { page: pageIndex + 1, pages: pageCount })}</span>
           <button
             type="button"
             aria-label={format(strings.firstPage, {})}
-            disabled={atFirst}
-            onClick={() => goTo(0)}
+            aria-disabled={atFirst || undefined}
+            onClick={() => (atFirst ? undefined : goTo(0))}
             data-terp="iconbutton"
           >
             <PageFirstGlyph />
@@ -52,8 +59,8 @@ export function DataViewPagination({
           <button
             type="button"
             aria-label={format(strings.previousPage, {})}
-            disabled={atFirst}
-            onClick={() => goTo(pageIndex - 1)}
+            aria-disabled={atFirst || undefined}
+            onClick={() => (atFirst ? undefined : goTo(pageIndex - 1))}
             data-terp="iconbutton"
           >
             <PagePrevGlyph />
@@ -61,8 +68,8 @@ export function DataViewPagination({
           <button
             type="button"
             aria-label={format(strings.nextPage, {})}
-            disabled={atLast}
-            onClick={() => goTo(pageIndex + 1)}
+            aria-disabled={atLast || undefined}
+            onClick={() => (atLast ? undefined : goTo(pageIndex + 1))}
             data-terp="iconbutton"
           >
             <PageNextGlyph />
@@ -70,8 +77,8 @@ export function DataViewPagination({
           <button
             type="button"
             aria-label={format(strings.lastPage, {})}
-            disabled={atLast}
-            onClick={() => goTo(pageCount - 1)}
+            aria-disabled={atLast || undefined}
+            onClick={() => (atLast ? undefined : goTo(pageCount - 1))}
             data-terp="iconbutton"
           >
             <PageLastGlyph />