@terpjs/react-core 0.10.0 → 0.11.0

package/README.md

@@ -70,7 +70,7 @@ JSDoc, so your editor shows the same guidance inline. **Never deep-import** from
 ## Page archetypes (the three-level screen pattern)
 
 Every routed view **must** render one of the archetypes (`Page`, or `OverviewPage` /
-`DetailPage` / `HubPage`, which compose it) — `buildAppRouter` refuses an unframed view at
+`DetailPage` / `HubPage` / `FormPage` / `SettingsPage` / `SplitPage`, which compose it) — `buildAppRouter` refuses an unframed view at
 runtime, fail closed (ADR 0059), so every screen keeps the breadcrumb/title/error frame.
 
 | Export | Use |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/react-core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Terp React stack core — typed @terpjs/contract client provider, auth session, capability gates, TanStack Router adapter, app shell, page archetypes, DataView and token-styled UI primitives. First frontend stack; see README.md for the component catalog.",
   "exports": {
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@tanstack/react-router": "^1.170.16",
-    "@terpjs/contract": "^0.10.0"
+    "@terpjs/contract": "^0.11.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/AppShell.test.tsx

@@ -43,15 +43,20 @@ function stubMobileViewport() {
 }
 
 describe("AppShell", () => {
-  it("renders the landmarks, brand, footer, and the nav via renderLink", () => {
+  it("renders the landmarks, brand, and the nav via renderLink — and NO footer", () => {
     renderShell();
 
     expect(screen.getByRole("banner")).toBeInTheDocument();
     expect(screen.getByRole("navigation", { name: "Primary" })).toBeInTheDocument();
     expect(screen.getByRole("main")).toBeInTheDocument();
-    expect(screen.getByRole("contentinfo")).toBeInTheDocument();
-    // The brand is the standard home affordance; the default footer echoes the title.
-    expect(screen.getAllByText("Terp").length).toBeGreaterThanOrEqual(2);
+    // No `contentinfo` unless the app asks for one. The default used to be a strip
+    // restating the app title already in the header and the browser tab — on every screen
+    // of every app, costing vertical space on exactly the viewports with least of it. An
+    // empty landmark is worse than none: it is somewhere a screen-reader user can navigate
+    // to and find nothing.
+    expect(screen.queryByRole("contentinfo")).toBeNull();
+    // The brand is the standard home affordance.
+    expect(screen.getAllByText("Terp").length).toBeGreaterThanOrEqual(1);
     expect(screen.getByRole("link", { name: "Terp" })).toHaveAttribute("href", "/");
     expect(screen.getByRole("link", { name: "Notes" })).toHaveAttribute("href", "/notes");
     expect(screen.getByText("page content")).toBeInTheDocument();

package/src/AppShell.tsx

@@ -125,7 +125,11 @@ interface AppShellBaseProps {
   density?: "comfortable" | "compact";
   /** Pinned to the bottom of the sidebar (the {@link UserMenu}); may read the rail state. */
   navFooter?: ReactNode | ((context: AppShellSlotContext) => ReactNode);
-  /** Footer line under the content; default: a muted line with the app title. */
+  /**
+   * Footer content under the routed view. **Omit it and no footer renders** — there is no
+   * default, because the default was a strip restating the app title already in the header
+   * and the browser tab, on every screen of every app, and nobody chose it.
+   */
   footer?: ReactNode;
   /**
    * The current URL path, so the shell can decide which nav item is current.
@@ -298,7 +302,7 @@ function PanelIcon() {
  *   nav and the same user menu render in the header, and the drawer still handles mobile;
  * - a **sticky** header over the content: the sidebar toggle on the left, then
  *   `headerActions` and the standard theme + language controls on the right;
- * - the routed `children` in a `main` landmark, with a slim `footer` underneath.
+ * - the routed `children` in a `main` landmark, with an optional `footer` underneath.
  *
  * Router-agnostic: `renderLink` wraps the shell-styled icon + label in the active
  * stack's link. Landmarks (`header` / `nav` / `main` / `footer`) keep it accessible.
@@ -688,7 +692,17 @@ export function AppShell({
         <main id={mainId} data-terp="appshell-main" tabIndex={-1}>
           {children}
         </main>
-        <footer data-terp="appshell-footer">{footer ?? <small>{resolvedTitle}</small>}</footer>
+        {/* Rendered only when the app asks for one. It used to default to the app's own
+            title, which meant every screen in every app carried a footer restating the
+            name already in the header and the browser tab — a permanent strip of chrome
+            nobody chose, costing vertical space on exactly the small viewports that have
+            least of it. `footer` is now the switch: pass content to get a footer, pass
+            nothing to get none. The landmark goes with it, which is correct — an empty
+            `contentinfo` is a landmark a screen-reader user can navigate to and find
+            nothing in. */}
+        {footer !== undefined && (
+          <footer data-terp="appshell-footer">{footer}</footer>
+        )}
       </div>
     </div>
   );

package/src/EmptyState.test.tsx

@@ -0,0 +1,30 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { EmptyState } from "./EmptyState";
+
+afterEach(cleanup);
+
+describe("EmptyState size", () => {
+  it("stamps no attribute at the default size", () => {
+    // The full-page block's geometry IS the base rule, so the default matches no
+    // attribute selector — the same shape Button's sizes and the shell's density take.
+    render(<EmptyState title="Nothing yet" />);
+    expect(screen.getByText("Nothing yet").closest("[data-terp='empty-state']")).not.toHaveAttribute(
+      "data-size",
+    );
+  });
+
+  it("stamps compact, and keeps the frame and the wording", () => {
+    // Two default blocks stacked on one screen were 480px of chrome repeating a sentence:
+    // the emptiness of one section is not the page's headline. Compact takes the space back
+    // without changing what the block says or that it is recognisably an empty state.
+    render(
+      <EmptyState size="compact" title="No connections" description="Add one to begin." />,
+    );
+    const block = screen.getByText("No connections").closest("[data-terp='empty-state']");
+    expect(block).toHaveAttribute("data-size", "compact");
+    expect(screen.getByText("Add one to begin.")).toBeInTheDocument();
+  });
+});

package/src/EmptyState.tsx

@@ -19,6 +19,17 @@ export interface EmptyStateProps {
   description?: ReactNode;
   /** Optional call to action (typically a `Button`). */
   action?: ReactNode;
+  /**
+   * `"compact"` for an empty block that is not the whole screen.
+   *
+   * The default is sized to be the only thing on a page — generous padding, a 2rem
+   * glyph, centred. That is right for an empty list and wrong the moment a screen has two
+   * of them: stacked, they were 480px of chrome repeating a sentence, and the emptiness of
+   * one section is not the page's headline. Compact keeps the frame and the wording and
+   * takes back the space — tighter padding, a smaller glyph, left-aligned, because a
+   * block that is one item among several reads as a row rather than a poster.
+   */
+  size?: "default" | "compact";
 }
 
 /**
@@ -27,15 +38,24 @@ export interface EmptyStateProps {
  * UX platform-wide tells the user "this is not an error — there is just nothing to show",
  * and the `action` slot turns the dead end into the obvious next step.
  */
-export function EmptyState({ icon, title, description, action }: EmptyStateProps) {
+export function EmptyState({
+  icon,
+  title,
+  description,
+  action,
+  size = "default",
+}: EmptyStateProps) {
   const resolve = useUiText();
+  const compact = size === "compact";
   const leading = icon ?? (
     <span data-terp="empty-state-icon">
-      <Icon name="inbox" size="2rem" />
+      <Icon name="inbox" size={compact ? "1.25rem" : "2rem"} />
     </span>
   );
+  // Stamped only for `compact`: the full-page block's geometry IS the base rule, the same
+  // shape `Button`'s sizes and the shell's density take.
   return (
-    <div data-terp="empty-state">
+    <div data-terp="empty-state" data-size={compact ? "compact" : undefined}>
       {leading}
       <p data-terp="empty-state-title">{resolve(title)}</p>
       {description !== undefined && <div data-terp="empty-state-description">{description}</div>}

package/src/LoginView.test.tsx

@@ -51,7 +51,39 @@ describe("LoginView dev credentials", () => {
       </TerpProvider>,
     );
     fireEvent.click(await screen.findByRole("button", { name: "Fill dev credentials" }));
-    expect(screen.getByPlaceholderText("Email")).toHaveValue("admin@example.test");
-    expect(screen.getByPlaceholderText("Password")).toHaveValue("correct horse battery staple");
+    // By label, not by placeholder. Reaching for a placeholder here was itself a symptom:
+    // it was the only handle these inputs had.
+    expect(screen.getByLabelText("Email")).toHaveValue("admin@example.test");
+    expect(screen.getByLabelText("Password")).toHaveValue("correct horse battery staple");
+  });
+});
+
+describe("LoginView accessible names", () => {
+  it("labels both credentials so they survive typing and can be addressed by name", async () => {
+    // The first screen of every Terp app, and it was labelled by placeholder alone. A
+    // placeholder is not an accessible name and it disappears the moment someone types, so
+    // the field a user is halfway through filling had nothing identifying it (WCAG 3.3.2)
+    // — and `getByLabel` could not find either input, which made the one screen every app
+    // ships the one screen its own tests could not address by name.
+    stubFetch();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LoginView />
+      </TerpProvider>,
+    );
+    await screen.findByRole("heading", { name: "Sign in" });
+
+    const email = screen.getByLabelText("Email");
+    const password = screen.getByLabelText("Password");
+    expect(email).toHaveAttribute("type", "email");
+    expect(password).toHaveAttribute("type", "password");
+
+    // The name has to survive typing, which is the whole difference from a placeholder.
+    fireEvent.change(email, { target: { value: "someone@example.test" } });
+    expect(screen.getByLabelText("Email")).toHaveValue("someone@example.test");
+
+    // And the autocomplete tokens stay, so a password manager still offers to fill.
+    expect(email).toHaveAttribute("autocomplete", "username");
+    expect(password).toHaveAttribute("autocomplete", "current-password");
   });
 });

package/src/LoginView.tsx

@@ -5,6 +5,7 @@ import { TerpMark } from "./icons";
 import { useAuth, useSso } from "./TerpProvider";
 import { useStrings } from "./uiText";
 import { Button } from "./ui/Button";
+import { Field } from "./Field";
 import { Input } from "./ui/Input";
 import type { SsoProvider } from "./sso";
 
@@ -92,24 +93,35 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
           <h1 data-terp="login-title">{strings.signIn}</h1>
         </div>
         <form data-terp="login-form" onSubmit={onSubmit}>
-          <Input
-            type="email"
-            // Neither field declared an autocomplete token, so no password manager offered to
-            // fill or save this form — the one place in the framework where that matters most.
-            autoComplete="username"
-            placeholder={strings.email}
-            value={email}
-            onChange={(event) => setEmail(event.target.value)}
-            required
-          />
-          <Input
-            type="password"
-            autoComplete="current-password"
-            placeholder={strings.password}
-            value={password}
-            onChange={(event) => setPassword(event.target.value)}
-            required
-          />
+          {/* Labelled through `Field`, not by placeholder. A placeholder is not an
+              accessible name and it disappears the moment someone types, so the field a
+              user is halfway through filling has nothing identifying it — WCAG 3.3.2 asks
+              for a label that survives typing. It also made these two inputs unreachable
+              by `getByLabel`, so every app's very first screen was the one place its own
+              tests could not address by name. The framework's own answer was already here:
+              `Field` wraps the control in a `<label>`, which is why it needs no id wiring.
+              The comment below is left because it dates the omission — an autocomplete
+              token was considered for these fields and a label was not. */}
+          <Field label={strings.email}>
+            <Input
+              type="email"
+              // Neither field declared an autocomplete token, so no password manager offered to
+              // fill or save this form — the one place in the framework where that matters most.
+              autoComplete="username"
+              value={email}
+              onChange={(event) => setEmail(event.target.value)}
+              required
+            />
+          </Field>
+          <Field label={strings.password}>
+            <Input
+              type="password"
+              autoComplete="current-password"
+              value={password}
+              onChange={(event) => setPassword(event.target.value)}
+              required
+            />
+          </Field>
           <Button type="submit" fullWidth loading={busy}>
             {busy ? strings.signingIn : strings.signIn}
           </Button>

package/src/locale.tsx

@@ -29,6 +29,15 @@ export const LOCALE_EN: LocaleCatalog = { label: "English" };
 export const LOCALE_NL: LocaleCatalog = {
   label: "Nederlands",
   strings: {
+    clearSelection: "Selectie wissen",
+    clearAllSelections: "Alle selecties wissen",
+    comboboxRemove: "Verwijderen",
+    comboboxLoading: "Laden…",
+    comboboxNoOptions: "Geen opties",
+    previousMonth: "Vorige maand",
+    selectDate: "Kies een datum",
+    selectDateRange: "Kies een periode",
+    nextMonth: "Volgende maand",
     loading: "Laden...",
     emptyList: "Nog niets te zien.",
     add: "Toevoegen",

package/src/markers.test.ts

@@ -91,6 +91,8 @@ const MARKERS = [
   "combobox-field",
   "combobox-list",
   "combobox-option",
+  "combobox-token",
+  "combobox-token-remove",
   "control-label",
   "dataview",
   "dataview-actions-cell",

package/src/router.tsx

@@ -461,8 +461,18 @@ export function buildAppRouter(
     // render it through useNavLink), so an unstable identity is worse than a re-render: it
     // remounts every in-app link in the tree on each navigation.
     const renderNavLink = useCallback<NavLinkRenderer>(
+      // `activeOptions={{ exact: true }}` for the same reason the shell's `renderLink`
+      // below carries it, and it matters MORE here: this renderer is what `Breadcrumbs`
+      // and `HubCard` use, so its job is rendering ANCESTORS. Under the router's default
+      // prefix matching every ancestor link matched the URL and was marked active, which
+      // on any detail route emitted a second `aria-current="page"` — one on the crumb for
+      // `/definitions` and one on the current crumb — plus a stray `.active` class and
+      // `data-status="active"` that made an ancestor look like the current page. The fix
+      // was applied to the nav and missed on the component whose whole purpose is the
+      // trail; exact matching means a crumb is only ever current when it IS the URL, and
+      // the current crumb is a span rather than a link.
       ({ to, children, attributes }) => (
-        <Link to={to} {...attributes}>
+        <Link to={to} activeOptions={{ exact: true }} {...attributes}>
           {children}
         </Link>
       ),

package/src/styles.test.ts

@@ -366,20 +366,30 @@ describe("cascade structure", () => {
     ).toContain("height: 100%");
   });
 
-  it("puts the DataView's surface on the full variant, not on the bare marker", () => {
+  it("puts the DataView's surface on the full variant's TABLE, not on the root or the marker", () => {
     // Both values of data-variant are stamped and only one has a rule, which is what keeps
     // the embedded variant a bare grid. The alternative — surface on the marker, un-declared
     // under [data-variant="embedded"] — needs background: transparent, border: 0 and
     // border-radius: 0, the un-declaring shape ADR 0094 exists to avoid.
     //
     // dataview-embedded is the negative evidence this rests on: deleting the full-variant
-    // rule must move five baselines and leave that one untouched.
+    // rule must move the full-variant baselines and leave that one untouched.
+    //
+    // The OWNER changed and the guarantee did not. The surface used to sit on the root, which
+    // made one card of the toolbar, the table and the pagination, divided by internal borders
+    // — and left the table's cells flush against the outer frame. It now sits on whatever
+    // occupies the table's slot, so the table is the object and the controls above and below
+    // it float on the page. Still keyed on the variant, for the reason above.
     const base = layerBody("terp.base");
     expect(declaresRuleFor(base, '[data-terp="dataview"]'), "the root needs a display").toBe(true);
     expect(
-      declaresRuleFor(base, '[data-terp="dataview"][data-variant="full"]'),
-      "the surface belongs to the full variant",
+      declaresRuleFor(base, '[data-terp="dataview"][data-variant="full"] > [data-terp="dataview-scroll"]'),
+      "the surface belongs to the full variant's table slot",
     ).toBe(true);
+    expect(
+      declaresRuleFor(base, '[data-terp="dataview"][data-variant="full"]'),
+      "the root must NOT carry a surface — that is the card this change removed",
+    ).toBe(false);
     expect(
       base,
       "un-declaring a surface under the embedded variant is the shape ADR 0094 avoids",
@@ -402,38 +412,30 @@ describe("cascade structure", () => {
     );
   });
 
-  it("keeps the toolbar band declaring its own surface, and no ink", () => {
-    // Three separate invariants about one element, and each has a way of going wrong that
-    // nothing else in the suite can see.
-    //
-    // The background. The inline style this replaced read `selectionMode ? neutral-50 :
-    // neutral-0` — an explicit value in BOTH branches, so the resting rule has to carry
-    // neutral-0 rather than leaving it to the host. Against every composed DataView specimen
-    // dropping it moves nothing, because the full variant's root and the workbench's specimen
-    // card are both neutral-0; it breaks the EMBEDDED variant in a real app, whose root
-    // declares nothing but a display, and the band would show the page canvas through it.
-    // `dataview-toolbar-bare` renders on a neutral-50 host so that mutation fails a baseline.
+  it("keeps the toolbar FLOATING — no surface, no divider, and still no ink", () => {
+    // This assertion reversed, and the reversal is the change: the band used to declare
+    // neutral-0 and two top radii because it was the top third of a card, and nothing else
+    // kept the selection colour inside the root's rounded frame. There is no card now. A
+    // background on a strip that sits on the page canvas paints a rectangle the design does
+    // not have, and a border under it draws a line across nothing.
     //
-    // The two top radii, which are load-bearing rather than decorative: the DataView root
-    // rounds its border with no overflow: hidden, so nothing else keeps the selection band's
-    // neutral-50 inside the rounded frame.
+    // The radii went with the card for the same reason: there is no rounded frame above the
+    // toolbar to stay inside. Selection mode keeps a fill — it marks a MODE and losing that
+    // makes selection invisible — but as a surface of its own, with its own padding and
+    // radius, asserted below.
     //
-    // And NO colour. Two of this element's direct children are arbitrary caller slots
-    // (`children` and `trailing`), so a muted ink here would inherit into app-authored filter
-    // controls — a silent restyle of app DOM, which is exactly what this migration exists to
-    // stop the framework doing.
+    // NO colour survives unchanged, and it is the invariant with the sharpest edge: two of
+    // this element's direct children are arbitrary caller slots (`children` and `trailing`),
+    // so a muted ink here would inherit into app-authored filter controls — a silent restyle
+    // of app DOM, which is what the styling migration exists to stop the framework doing.
     const base = layerBody("terp.base");
     const at = base.indexOf('[data-terp="dataview-toolbar"]');
     expect(at, "the toolbar band should have a base rule").toBeGreaterThan(-1);
     const block = base.slice(base.indexOf("{", at) + 1, base.indexOf("}", at));
-    expect(block, "the band must declare its own surface, not inherit the host's").toContain(
-      "background: var(--color-neutral-0)",
+    expect(block, "a floating strip paints no surface of its own").not.toContain("background:");
+    expect(block, "a divider under a floating strip is a line across nothing").not.toContain(
+      "border-block-end:",
     );
-    for (const radius of ["border-top-left-radius", "border-top-right-radius"]) {
-      expect(block, `${radius} keeps the selection band inside the root's rounded frame`).toContain(
-        `${radius}: var(--radius-lg)`,
-      );
-    }
     expect(
       /(^|;)\s*color:/.test(block),
       "a colour here inherits into the caller's filter slot and trailing slot",
@@ -449,11 +451,27 @@ describe("cascade structure", () => {
       layerBody("terp.state"),
       "selection mode is a resting surface, not an interaction state",
     ).not.toContain('[data-variant="selection"]');
-    // The bar reads the density token rather than a literal --space-3, which is what makes a
-    // compact view's band line up with its first cell. Zero-diff at comfortable, because
-    // comfortable --density-cell-pad-x IS --space-3 — so only dataview-compact can catch it.
-    expect(block, "the band's inline padding must follow density").toContain(
-      "padding: var(--space-2) var(--density-cell-pad-x)",
+    // The band used to read --density-cell-pad-x for its INLINE padding, so a compact view's
+    // band lined up with its first cell. That alignment target is gone with the card: the
+    // toolbar now aligns with the table's outer frame, whose position does not move with
+    // density, so inline padding here would push the controls off it. Block padding stays on
+    // the spacing scale — vertical rhythm was never the density question.
+    expect(block, "the band's block padding stays on the spacing scale").toContain(
+      "padding-block: var(--space-2)",
+    );
+    expect(
+      /padding-inline|padding:/.test(block),
+      "inline padding would push the controls off the table frame they now align to",
+    ).toBe(false);
+    // Selection mode is the exception and declares its own inline padding, because there it
+    // IS a surface and its fill needs to clear its text.
+    const selectionAt = base.indexOf('[data-terp="dataview-toolbar"][data-variant="selection"]');
+    const selectionBlock = base.slice(
+      base.indexOf("{", selectionAt) + 1,
+      base.indexOf("}", selectionAt),
+    );
+    expect(selectionBlock, "the selection surface reads density for its own inset").toContain(
+      "padding-inline: var(--density-cell-pad-x)",
     );
   });