npm - @terpjs/react-core - Versions diffs - 0.13.1 → 0.14.0 - Mend

@terpjs/react-core 0.13.1 → 0.14.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 (16) hide show

package/README.md +4 -4
package/package.json +2 -2
package/src/AppShell.tsx +9 -1
package/src/Breadcrumbs.test.tsx +30 -0
package/src/Breadcrumbs.tsx +34 -6
package/src/HubPage.test.tsx +14 -3
package/src/Page.test.tsx +80 -12
package/src/Page.tsx +89 -18
package/src/layout.test.tsx +36 -0
package/src/layout.tsx +39 -0
package/src/markers.test.ts +2 -1
package/src/styles.test.ts +350 -3
package/src/styles.ts +398 -68
package/src/tokens.guard.test.ts +53 -13
package/src/ui/Card.test.tsx +39 -1
package/src/ui/Card.tsx +17 -5

package/README.md CHANGED Viewed

@@ -77,7 +77,7 @@ runtime, fail closed (ADR 0059), so every screen keeps the breadcrumb/title/erro
 | Export | Use |
 |---|---|
 | `AppShell` | The responsive level-1 frame: a home-linked brand, icon/label nav and account footer. Desktop collapses to a persisted, scrollbar-free rail with one fixed icon slot; mobile becomes a scroll-locking drawer. The sticky header holds the sidebar toggle and icon-only preferences. Router-agnostic link renderers receive framework-owned expanded/collapsed geometry. |
-| Shell geometry (tokens, not props) | `--shell-sidebar-width-expanded` / `-collapsed`, `--shell-header-height`, `--shell-content-max-width` and `--shell-brand-size` are published contract tokens: an app moves them from its own unlayered `theme.css` with no prop at all, and the Studio gets them from the manifest. |
+| Shell geometry (tokens, not props) | `--shell-sidebar-width-expanded` / `-collapsed`, `--shell-header-height`, `--shell-content-max-width`, `--shell-brand-size` and `--shell-gutter` (the content column's inline gutter, read by the app header, `main`, the footer and the page band, and tightened one step below the mobile breakpoint) are published contract tokens: an app moves them from its own unlayered `theme.css` with no prop at all, and the Studio gets them from the manifest. |
 | `logo` / `logoDark` (shell) | The brand mark, rendered in a box of `--shell-brand-size` so an asset larger than the 4rem icon rail is scaled rather than clipped — which is why there is no separate collapsed-mark slot: `logo` is the mark, `title` is the wordmark, and the rail already hides the second. `logoDark` is for a fixed-colour mark that cannot survive a dark theme; both render and the stylesheet shows one, switched on `--appearance-show-light` / `--appearance-show-dark`, which the token build emits from each theme's declared `appearance`. Resolving it in React would be wrong: the theme is `<html data-theme>` and an app may set it with no provider mounted. |
 | `density` (shell) | App-wide `"comfortable"` or `"compact"`, stamped on the shell root; every control height and cell padding follows by token inheritance. **No default** — omitting it stamps nothing, so an app's own `data-density` on `<html>` still wins. A subtree may override it: a `DataView density="comfortable"` inside a compact shell really is comfortable, because comfortable now has named tokens and a rule rather than being the absence of an attribute. |
 | Skip to content | The shell renders the skip link and owns the landmarks it skips: `main` carries `tabIndex={-1}` and a per-instance id, so activating the link *moves focus* rather than only scrolling and two shells on one page get two distinct targets. It is not rendered while the mobile drawer is open — the drawer is `aria-modal` and its target sits inside the `inert` column. |
@@ -89,7 +89,7 @@ runtime, fail closed (ADR 0059), so every screen keeps the breadcrumb/title/erro
 | `navPlacement` (shell) | Where the primary navigation lives on desktop: `"sidebar"` (default, stamps nothing) or `"header"` — a horizontal row in the header with no sidebar at all, for an app whose destinations are few enough that 15rem of permanent chrome is a tax. The header then *becomes* the sidebar surface, so every `--color-sidebar-*` an app themes carries over and no property is overridden. Below the mobile breakpoint both placements are the drawer. `defaultCollapsed` is `never` under `"header"`: with no sidebar there is nothing to collapse. Available on `AppShell`, `buildAppRouter` and `renderTerpApp`. |
 | `contentWidth` (shell) | `"measured"` caps routed content at `--shell-content-max-width` while each page's own header keeps the full track — the subheader band. Default `"full"` stamps no attribute, so nothing moves until an app asks. Available on `AppShell`, `buildAppRouter` and `renderTerpApp`. |
 | `NavIcon`, `Icon`, `TerpMark`, `ICON_GLYPHS`, `ICON_NAMES` | The dependency-free icon layer. `ICON_NAMES` is published by `@terpjs/contract` as data and `IconName` is derived from it, so `NavItem.icon` and `Icon`'s `name` are **checked names** — a typo is a typecheck error, not a picture of nothing. `NavIcon`'s `name` stays a plain `string` on purpose: its unknown-name behaviour is a designed, visible fallback (the label's initial in a tile), while `Icon` rendered an empty box. The glyph table is held to the name set exhaustively in both directions by `satisfies`, so a glyph without a name or a name without a glyph fails to compile. The bundled catalogue covers common UI, action, object and status glyphs (home, list, folder, users, plus, edit, trash, search, check, x, chevron-{left,right,down}, arrow-left, external, logout, user, bell, key, globe, lock, tag, mail, refresh, filter, download, upload, star, heart, database, code, truck, cart, wallet, map-pin, clock, link, grid, book, briefcase, building, clipboard, layers, send, phone, image, video, music, wrench, zap, …). `TerpMark` is the placeholder brand mark until an app passes its own `logo`. |
-| `Page` | The base routed screen: optional breadcrumb row, then one compact `h1` + intrinsic-width actions row (title-first on narrow layouts), then the body with loading/error slots. |
+| `Page` | The base routed screen: one band carrying the breadcrumb trail — whose leaf **is** the view's single `h1` — plus `badges`, a truncated `description` lead line and the `actions` cluster, then the body with loading/error slots. Every page renders a trail, even one of a single crumb, so an overview's title sits where a detail's does. Inside a shell the band bleeds to the content column's edge and takes `--shell-header-height`; a `measure="narrow"` frame keeps the row and drops the chrome. |
 | `HubPage`, `HubCard` | Responsive `auto-fit` landing grid. Cards share equal outer and internal tracks even when descriptions/stats differ; nested hubs use the ordinary breadcrumb contract via `parents`. |
 | `OverviewPage` | A module's top-level listing screen (level 2); detail pages crumb back to it. |
 | `DetailPage` | One record's screen (level 3); breadcrumb trail = ancestors + record title. |
@@ -234,9 +234,9 @@ token spacing scale, so spacing is themed centrally):
 |---|---|
 | `Stack` | The layout primitive: a flex container with a token gap. Vertical by default (forms, sections); `direction="row"` + `justify` for toolbars; `as="form"` etc. for semantics. `padding` insets on the same token scale; `direction` and `gap` also take a `{ narrow, wide }` pair, which changes over at the one viewport cutover the shell and the DataView already use. |
 | `Grid` | The two-dimensional primitive, and the one that lifts a real ceiling — a two-column form could not be expressed at all before it. `columns` takes a fixed 1–4 or `"auto"` (the default), which reflows to whatever the **container** can hold with no breakpoint anywhere; `minColumn` is the track floor for `auto`; `gap` indexes the spacing scale; `align` is a closed four. Renders no inline style. No `span`, and therefore no twelve-column option — a span system needs a child component to carry it. |
-| `Card` | A token-styled surface (border + background + padding) grouping one block of a page — the sanctioned visual separation between sections. Optional header row: `title` (semantic `<h3>`), muted `description`, `actions` slot. `variant="plain"` keeps the heading and drops the box, for a titled region inside something that is already a surface — a section whose body is a `DataView` gets a border inside a border otherwise. There is no separate `Section` or `Surface`: both are this element with declarations removed. |
+| `Card` | A token-styled frame (a border, a radius and padding — no fill, so the page's canvas shows through) grouping one block of a page — the sanctioned visual separation between sections. Optional header row: `title` (semantic `<h3>`), muted `description`, `actions` slot — and the slot stays on the title's line whether or not there is a description, which took a rule: a content-sized heading is as wide as its longest line, and flex breaks lines on that width before it shrinks anything. `variant="plain"` keeps the heading and drops the box, for a titled region inside something that is already a surface — a section whose body is a `DataView` gets a border inside a border otherwise. There is no separate `Section` or `Surface`: both are this element with declarations removed. |
 | `Divider` | A rule between groups, as a semantic `<hr>` so the separation reaches the accessibility tree — `Separator` under its other name, shipped once. `orientation="vertical"` takes its height from its flex or grid line rather than inventing one, so it works between the items of a row `Stack` and is zero-height in a block parent. |
-| `DetailList` | Token-styled label/value pairs as a semantic `<dl>` (record metadata, expanded-row summaries). A real grid: `layout="aligned"` puts every label in a shared column so the values line up, `"stacked"` puts the label above its value, and `columns` takes two pairs per row. Tracks are floored at zero and long values wrap, so a 64-character digest no longer pushes the list past its container. |
+| `DetailList` | Token-styled label/value pairs as a semantic `<dl>` (record metadata, expanded-row summaries). A real grid: `layout="aligned"` puts every label in a shared column so the values line up, `"stacked"` puts the label above its value, and `columns` takes two pairs per row. Tracks are floored at zero and long values wrap, so a 64-character digest no longer pushes the list past its container. Both non-inline layouts mute their label to the small, regular step — at the value's own size and weight a card of labelled values is a wall of bold text — and space their rows so a pair groups; `gap` moves that distance on the spacing scale, and it is the **row** gap, since the column gap is the label-to-value distance. Below the framework's viewport cutover it reflows to one column, where `Grid` deliberately does not for a fixed count: `Grid` publishes `columns="auto"` as its responsive answer and this component's closed one-or-two has none, so the reflow has to be its own. |
 | `Heading` | A section heading inside a page body — `h2`–`h4`, with `size` a **separate** choice from `level` so a visually small `h2` is expressible without picking the wrong element. No level 1: `Page` renders the single `h1` of every routed view. |
 | `Text` | Body copy with themeable ink — `tone` (default / muted / subtle), `size`, and an enumerable `measure` that caps the line length in `ch`. What a bare `<p>` in a module cannot be, since a bare element carries no marker for a rule to reach. |
 | `Code` | An identifier or a snippet in the mono family. `block` wraps it in a focusable `<pre>`, which is what preserves the whitespace and what makes a long line scrollable by keyboard. |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/react-core",
-  "version": "0.13.1",
+  "version": "0.14.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.13.1"
+    "@terpjs/contract": "^0.14.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/AppShell.tsx CHANGED Viewed

@@ -104,7 +104,15 @@ interface AppShellBaseProps {
    *
    * "Full width" means the full width of the article's own track. `appshell-main`'s padding
    * sits outside it, so this is a measure within the content column rather than a bleed to the
-   * window edge — which would need a negative margin, and therefore an inline site.
+   * window edge.
+   *
+   * The page's header does reach past that padding, to the content column's edge, and it does
+   * it with a negative margin of one `--shell-gutter` per side — so a band and the app
+   * header above it read as one piece of chrome. This paragraph used to say such a bleed
+   * "would need a negative margin, and therefore an inline site"; the margin is right and the
+   * inline site is not, because the sheet knows both viewport variants and the gutter is a
+   * published token. ADR 0097 §2 carries the amendment. Nothing here needs the app's help:
+   * the band is `Page`'s own header, not something `contentWidth` switches on.
    */
   contentWidth?: "full" | "measured";
   /**

package/src/Breadcrumbs.test.tsx CHANGED Viewed

@@ -43,6 +43,36 @@ describe("Breadcrumbs", () => {
     expect(screen.getByText("Section")).not.toHaveAttribute("aria-current");
   });
+  it("renders the current crumb as the page heading when asked, and only then", () => {
+    // The page band's case: the trail IS the title, so its leaf is the view's single h1
+    // rather than a second copy of the same string sitting under the trail. The element
+    // changes and the accessible current-ness does not.
+    const { container } = render(
+      <Breadcrumbs
+        items={[{ label: "Tasks", to: "/tasks" }, { label: "Fix the door" }]}
+        currentAs="h1"
+      />,
+    );
+    const heading = screen.getByRole("heading", { level: 1, name: "Fix the door" });
+    expect(heading).toHaveAttribute("aria-current", "page");
+    // The marker moves with the element, because the two mean different things to the sheet:
+    // a trail's end, versus a heading that happens to sit at the trail's end.
+    expect(heading).toHaveAttribute("data-terp", "page-title");
+    expect(container.querySelector('[data-terp="breadcrumbs-current"]')).toBeNull();
+    // The ancestor is untouched: currentAs describes the LEAF only.
+    expect(screen.getByRole("link", { name: "Tasks" })).toHaveAttribute("href", "/tasks");
+  });
+  it("defaults to a span, so a standalone trail mints no heading", () => {
+    // The default matters as much as the option. A wayfinding trail rendered anywhere on a
+    // page must not introduce an h1 competing with that page's own.
+    render(<Breadcrumbs items={[{ label: "Tasks", to: "/tasks" }, { label: "Here" }]} />);
+    expect(screen.queryByRole("heading")).not.toBeInTheDocument();
+    expect(screen.getByText("Here")).toHaveAttribute("data-terp", "breadcrumbs-current");
+  });
   it("marks only the final crumb as current, on a marker of its own", () => {
     // The current-crumb styling deliberately does NOT key on aria-current. A router's Link
     // stamps aria-current="page" on every link whose path is a prefix of the current one —

package/src/Breadcrumbs.tsx CHANGED Viewed

@@ -21,6 +21,21 @@ export type RenderBreadcrumbLink = (item: { label: string; to: string }) => Reac
 export interface BreadcrumbsProps {
   /** The trail, outermost first; the last item is the current page. */
   items: readonly BreadcrumbItem[];
+  /**
+   * What element the current (last) crumb renders as. Default `"span"`.
+   *
+   * `"h1"` is the page band's case (see `Page`): there the trail IS the page title, so its
+   * leaf is the view's single heading rather than a second copy of the same string sitting
+   * under the trail. It carries `data-terp="page-title"` instead of `breadcrumbs-current`,
+   * because the two mean different things to the sheet: one is a trail's end, the other is a
+   * heading that happens to sit at the trail's end and is styled as such.
+   *
+   * The heading lands inside the list item, which is deliberate rather than convenient. `li`
+   * takes flow content, so it is valid; it keeps the separator logic in one place instead of
+   * asking the caller to draw a chevron; and it leaves `aria-current="page"` on the same node
+   * a screen reader reads as the heading.
+   */
+  currentAs?: "span" | "h1";
   /**
    * Link renderer for ancestor crumbs. Defaults to the surrounding router's `Link`
    * (published by `buildAppRouter`), falling back to a plain `<a href>` only outside a
@@ -56,7 +71,7 @@ const anchorRenderLink: RenderBreadcrumbLink = (item) => <a href={item.to}>{item
  * list, and `aria-current="page"` on the final crumb. Router-agnostic — `renderLink` turns
  * an ancestor crumb into the active stack's link, exactly like `AppShell`'s `renderLink`.
  */
-export function Breadcrumbs({ items, renderLink }: BreadcrumbsProps) {
+export function Breadcrumbs({ items, renderLink, currentAs = "span" }: BreadcrumbsProps) {
   const navLink = useNavLink();
   const renderCrumbLink =
     renderLink ??
@@ -75,13 +90,26 @@ export function Breadcrumbs({ items, renderLink }: BreadcrumbsProps) {
             <li key={`${index}-${label}`}>
               {!isLast && item.to !== undefined ? (
                 renderCrumbLink({ label, to: item.to })
-              ) : (
-                <span
-                  aria-current={isLast ? "page" : undefined}
-                  data-terp={isLast ? "breadcrumbs-current" : undefined}
-                >
+              ) : isLast && currentAs === "h1" ? (
+                // Two spelled-out branches rather than one element with a computed tag and a
+                // computed marker, and the marker scanner is the reason rather than taste: it
+                // reads string literals out of a data-terp attribute, so a ternary there
+                // published "h1" as a marker and hid breadcrumbs-current from the inventory.
+                // The sheet records the same idiom for the same scanner ("a conditional
+                // written at the attribute is the form the marker scanner reads every string
+                // literal out of"); spelling both out keeps one literal per element.
+                <h1 aria-current="page" data-terp="page-title">
+                  {label}
+                </h1>
+              ) : isLast ? (
+                <span aria-current="page" data-terp="breadcrumbs-current">
                   {label}
                 </span>
+              ) : (
+                // An ancestor with no `to`: plain text, never a dead link, and never the
+                // heading either — `currentAs` describes the LEAF, and an intermediate layer
+                // that happens to be unlinked is not the page.
+                <span>{label}</span>
               )}
               {!isLast && (
                 <span aria-hidden="true" data-terp="breadcrumbs-separator">

package/src/HubPage.test.tsx CHANGED Viewed

@@ -15,15 +15,26 @@ describe("HubPage", () => {
       </HubPage>,
     );
-    expect(screen.getByRole("heading", { level: 1, name: "Administration" })).toBeInTheDocument();
-    expect(screen.queryByRole("navigation", { name: "Breadcrumb" })).not.toBeInTheDocument();
+    const heading = screen.getByRole("heading", { level: 1, name: "Administration" });
+    expect(heading).toBeInTheDocument();
+    // A parentless hub is a trail of ONE, not a bare heading, so its title sits exactly where
+    // an overview's and a detail's do and does not move when you descend. The trail is
+    // therefore present and has nothing to link to yet.
+    expect(heading).toHaveAttribute("data-terp", "page-title");
+    expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toBeInTheDocument();
     expect(screen.getAllByText("Administration")).toHaveLength(1);
     // The marker, not the declaration. jsdom does not compute the cascade, so toHaveStyle
     // can only ever see an inline style — asserting gridAutoRows here was asserting that the
     // grid is styled from a style object, which is the thing ADR 0094 removes. What a test
     // should assert is the fact the sheet keys on; the geometry is gated by styles.test.ts
     // (the rule exists) and by the hub-page baselines (it does what it says).
-    expect(screen.getByRole("list")).toHaveAttribute("data-terp", "hubpage-grid");
+    // getByRole("list") would be ambiguous now that the trail renders an <ol> of its own, and
+    // the ambiguity is the assertion's own fault rather than the trail's: what it means is
+    // "the grid is the marked element", so it asks for the grid.
+    expect(
+      screen.getAllByRole("list").find((list) => list.dataset.terp === "hubpage-grid"),
+      "the card grid must be the marked list",
+    ).toBeDefined();
     expect(screen.getByRole("link", { name: /Users/ })).toBeInTheDocument();
     expect(screen.getByRole("link", { name: /Roles/ })).toBeInTheDocument();
     expect(screen.getByText("Manage accounts")).toBeInTheDocument();

package/src/Page.test.tsx CHANGED Viewed

@@ -33,11 +33,37 @@ describe("Page", () => {
     expect(screen.getByText("body")).toBeInTheDocument();
   });
-  it("does not repeat a root page title as a current-page-only breadcrumb", () => {
-    render(<Page title="Tasks">x</Page>);
-    expect(screen.queryByRole("navigation", { name: "Breadcrumb" })).not.toBeInTheDocument();
+  it("renders a parentless page as a trail of one, in the same boxes as a deeper page", () => {
+    // The overview and the detail have to put the title in the SAME place, or the name moves
+    // the moment you open a record. So a parentless page is a trail of one rather than a bare
+    // heading: same nav, same list, same leaf, no ancestors in front of it yet.
+    const root = render(<Page title="Tasks">x</Page>);
+    const rootLeaf = screen.getByRole("heading", { level: 1, name: "Tasks" });
+    expect(rootLeaf).toHaveAttribute("data-terp", "page-title");
+    // Still exactly once: the leaf IS the heading, so there is nothing to repeat.
     expect(screen.getAllByText("Tasks")).toHaveLength(1);
+    // The ancestry of the heading is the shape that must not differ between the two.
+    const chain = (node: HTMLElement) => {
+      const tags: string[] = [];
+      for (let at = node.parentElement; at !== null; at = at.parentElement) {
+        tags.push(at.tagName);
+        if (at.dataset.terp === "page-heading") break;
+      }
+      return tags;
+    };
+    const rootChain = chain(rootLeaf);
+    expect(rootChain).toEqual(["LI", "OL", "NAV", "DIV"]);
+    root.unmount();
+    const deep = render(
+      <Page title="Fix the door" breadcrumbs={[{ label: "Tasks", to: "/tasks" }]}>
+        x
+      </Page>,
+    );
+    expect(chain(screen.getByRole("heading", { level: 1, name: "Fix the door" }))).toEqual(
+      rootChain,
+    );
+    deep.unmount();
   });
   it("appends its own crumb to the supplied trail", () => {
@@ -49,10 +75,47 @@ describe("Page", () => {
     expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toBeInTheDocument();
     expect(screen.getByRole("link", { name: "Tasks" })).toHaveAttribute("href", "/tasks");
-    expect(screen.getByText("Fix the door", { selector: "span" })).toHaveAttribute(
-      "aria-current",
-      "page",
+    // The leaf of the trail IS the h1 now, so the page's name appears ONCE. It used to
+    // appear twice: Page built its trail as [...breadcrumbs, { label: title }] and then
+    // rendered <h1>{title}</h1>, so every DetailPage printed its own name as the leaf crumb
+    // and again a couple of dozen pixels below it. That duplication was the whole reason the
+    // header collapsed into one band, and this is the assertion that holds it.
+    const heading = screen.getByRole("heading", { level: 1, name: "Fix the door" });
+    expect(heading).toHaveAttribute("aria-current", "page");
+    expect(heading).toHaveAttribute("data-terp", "page-title");
+    expect(screen.getAllByText("Fix the door")).toHaveLength(1);
+  });
+  it("renders badges and a lead line on the band, and neither when absent", () => {
+    const { container, unmount } = render(
+      <Page title="Fix the door" badges={<span>Open</span>} description="Reported yesterday">
+        x
+      </Page>,
+    );
+    expect(screen.getByText("Open")).toBeInTheDocument();
+    expect(screen.getByText("Reported yesterday")).toBeInTheDocument();
+    expect(container.querySelector('[data-terp="page-badges"]')).not.toBeNull();
+    expect(container.querySelector('[data-terp="page-description"]')).not.toBeNull();
+    unmount();
+    // Absent is not an empty row: a band that reserved space for slots no page filled would
+    // put a gap next to every title in every app that passes neither.
+    const bare = render(<Page title="Fix the door">x</Page>);
+    expect(bare.container.querySelector('[data-terp="page-badges"]')).toBeNull();
+    expect(bare.container.querySelector('[data-terp="page-description"]')).toBeNull();
+  });
+  it("takes several badges as one row, not one row each", () => {
+    const { container } = render(
+      <Page title="Fix the door" badges={[<span key="a">Open</span>, <span key="b">Urgent</span>]}>
+        x
+      </Page>,
     );
+    expect(container.querySelectorAll('[data-terp="page-badges"]')).toHaveLength(1);
+    expect(screen.getByText("Open")).toBeInTheDocument();
+    expect(screen.getByText("Urgent")).toBeInTheDocument();
   });
   it("replaces the body with the loading state while keeping the header", () => {
@@ -116,11 +179,15 @@ describe("Page", () => {
 });
 describe("OverviewPage", () => {
-  it("is a root-level Page with one title and no redundant breadcrumb", () => {
+  it("puts its title where a detail page puts its own: the trail's leaf", () => {
     render(<OverviewPage title="Tasks">list</OverviewPage>);
-    expect(screen.getByRole("heading", { level: 1, name: "Tasks" })).toBeInTheDocument();
-    expect(screen.queryByRole("navigation", { name: "Breadcrumb" })).not.toBeInTheDocument();
+    const leaf = screen.getByRole("heading", { level: 1, name: "Tasks" });
+    expect(leaf).toHaveAttribute("data-terp", "page-title");
+    expect(leaf).toHaveAttribute("aria-current", "page");
+    // A trail of one has no ancestors to link to, which is the whole difference between an
+    // overview and the detail beneath it.
+    expect(screen.queryByRole("link")).not.toBeInTheDocument();
     expect(screen.getAllByText("Tasks")).toHaveLength(1);
     expect(screen.getByText("list")).toBeInTheDocument();
   });
@@ -140,8 +207,9 @@ describe("DetailPage", () => {
     expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toBeInTheDocument();
     expect(screen.getByRole("link", { name: "Tasks" })).toHaveAttribute("href", "/tasks");
-    expect(screen.getByRole("heading", { level: 1, name: "Fix the door" })).toBeInTheDocument();
-    expect(screen.getByText("Fix the door", { selector: "span" })).toHaveAttribute(
+    const leaf = screen.getByRole("heading", { level: 1, name: "Fix the door" });
+    expect(screen.getAllByText("Fix the door")).toHaveLength(1);
+    expect(leaf).toHaveAttribute(
       "aria-current",
       "page",
     );

package/src/Page.tsx CHANGED Viewed

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import { useContext, useEffect, useRef, useState } from "react";
+import { Fragment, useContext, useEffect, useRef, useState } from "react";
 import { Breadcrumbs } from "./Breadcrumbs";
 import type { BreadcrumbItem, RenderBreadcrumbLink } from "./Breadcrumbs";
@@ -11,8 +11,8 @@ import {
 } from "./layoutContract";
 import { LoadingState } from "./LoadingState";
 import { usePageMarker } from "./pageMarker";
-import { useUiText } from "./uiText";
-import type { UiText } from "./uiText";
+import { resolveUiTextNode, useUiText } from "./uiText";
+import type { UiText, UiTextNode } from "./uiText";
 export interface PageProps {
   /** The page heading (rendered as the single `h1`). */
@@ -21,8 +21,31 @@ export interface PageProps {
   breadcrumbs?: readonly BreadcrumbItem[];
   /** Link renderer for ancestor crumbs; defaults to the surrounding router's `Link` (see {@link Breadcrumbs}). */
   renderLink?: RenderBreadcrumbLink;
-  /** Optional page-level actions, rendered on the heading row (e.g. a primary `Button`). */
+  /** Optional page-level actions, rendered at the band's right edge (e.g. a primary `Button`). */
   actions?: ReactNode;
+  /**
+   * Status pill(s) for the page's subject, shown next to the title — an entity's state, a
+   * visibility marker. Pass a `Badge` (or several) so the tone is the caller's choice; a
+   * bare string is not accepted, because "which tone" is a decision this frame cannot make.
+   *
+   * Keep it to a handful of short labels. This is a badge row on a bounded band, not a place
+   * for prose — that is what `description` is, and neither is a place for a paragraph.
+   */
+  badges?: ReactNode | readonly ReactNode[];
+  /**
+   * One short line about the page, shown after the badges and truncated to a single line.
+   *
+   * It is chrome, not content: the band has a height, so a lead line that would wrap is
+   * clipped rather than allowed to set it. An explanation that does not fit is describing the
+   * body and belongs in the body.
+   *
+   * `UiTextNode`, like `EmptyState`'s own description, rather than a bare `ReactNode`: this is
+   * user-facing prose, so it goes through the localization seam. Typed as `ReactNode` it took
+   * a plain string that never reached the resolver, which is the failure that does not
+   * announce itself — every other string on the band translates and the lead line stays in the
+   * source language.
+   */
+  description?: UiTextNode;
   /**
    * Cap the whole frame — header included — at a readable measure (default `"full"`).
    *
@@ -58,11 +81,27 @@ export interface PageProps {
 }
 /**
- * The base content-page frame: every routed view is constructed the same way — one
- * header holding the breadcrumb trail (when there is a path back up through the
- * layers), then one row with the single `h1` title on the left and the page's
- * `actions` slot on the right, then the body. A root page omits the redundant
- * current-page-only crumb. Title-first DOM order keeps narrow layouts natural.
+ * The base content-page frame: every routed view is constructed the same way — one band
+ * carrying the page's identity and its actions, then the body.
+ *
+ * **The band is one row, the row is the title, and the title is the trail's leaf.** Every
+ * page renders a trail: its ancestors link up through the layers and its leaf is the view's
+ * single `h1` (see `Breadcrumbs`' `currentAs`). An overview with no parents is a trail of
+ * one, which is deliberately the same node in the same boxes as a detail's leaf — so
+ * opening a record slides the name right behind its new parents instead of moving it between
+ * two different layouts.
+ *
+ * The page's name therefore appears exactly ONCE, which is the defect this shape fixed: the
+ * frame used to append `title` to the trail *and* render it as an `h1`, so every `DetailPage`
+ * printed its own name twice, a couple of dozen pixels apart.
+ *
+ * `badges` and `description` sit after the title and `actions` at the right edge, all on that
+ * one line. Inside a shell the band bleeds to the content column's edge and takes the app
+ * header's own height and a bottom border, so the two read as one piece of chrome; standalone
+ * — the workbench, the unit tests — it is the same row without the bleed. A `measure="narrow"`
+ * frame (`FormPage`, `SettingsPage`) keeps the row and drops the chrome, because a form is
+ * capped with its header (ADR 0098 §3).
+ *
  * `OverviewPage` and `DetailPage` specialise it for the standard overview -> detail
  * layering; a bespoke screen composes `Page` directly.
  *
@@ -78,6 +117,8 @@ export function Page({
   breadcrumbs,
   renderLink,
   actions,
+  badges,
+  description,
   measure = "full",
   isLoading,
   loadingState,
@@ -115,8 +156,30 @@ export function Page({
   if (slotViolation !== null) {
     throw new Error(slotViolation);
   }
-  const hasAncestors = breadcrumbs !== undefined && breadcrumbs.length > 0;
-  const trail: BreadcrumbItem[] = hasAncestors ? [...breadcrumbs, { label: title }] : [];
+  // ALWAYS a trail, even of one, and that is the point rather than a simplification.
+  // An overview's title has to be the same node in the same boxes as a detail's, or the name
+  // moves the moment you open a record: one path rendered a bare h1 and the other rendered
+  // the h1 inside nav > ol > li, so the text sat at two slightly different places and the
+  // transition showed it. A trail of one is the overview's title; append an ancestor and the
+  // same leaf slides right behind its parents, which is the only motion there should be.
+  const trail: BreadcrumbItem[] = [...(breadcrumbs ?? []), { label: title }];
+  // Normalised rather than branched at the site, so one badge and several take the same path
+  // and the row exists or does not exist for one reason.
+  //
+  // Filtered on RENDERABILITY, not on undefined, and the difference is the whole bug it fixes:
+  // the idiomatic call is `badges={isPublished && <Badge/>}`, which hands this `false` when the
+  // condition fails. Testing `!== undefined` let `[false]` through, so the row existed, was
+  // empty, and put a gap beside the title — the exact "absent is not an empty row"
+  // invariant the band promises. `false`, `null`, `undefined` and `""` all mean absent here.
+  const badgeList: readonly ReactNode[] = ([] as ReactNode[])
+    .concat(badges ?? [])
+    .filter((badge) => badge !== false && badge !== null && badge !== undefined && badge !== "");
+  // Same test for the lead line, for the same reason: `description={error && error.message}`.
+  const hasDescription =
+    description !== undefined &&
+    description !== null &&
+    description !== false &&
+    description !== "";
   const body =
     error !== null && error !== undefined ? (
       (errorState ?? <ErrorState error={error} />)
@@ -138,15 +201,23 @@ export function Page({
           wrapper of its own — not even a display: contents one, since article.children is a
           DOM traversal and would see it. */}
       <header data-terp="page-header">
-        {hasAncestors && (
-          <div data-terp="page-breadcrumbs">
-            <Breadcrumbs items={trail} renderLink={renderLink} />
-          </div>
-        )}
         <div data-terp="page-heading">
-          <h1 data-terp="page-title">{resolve(title)}</h1>
-          {actions}
+          {/* The trail carries the h1 as its leaf. No wrapper of its own any more: the crumb
+              row it used to sit in existed to hold a 2rem floor above the title row, and
+              there is no title row to be above. */}
+          <Breadcrumbs items={trail} renderLink={renderLink} currentAs="h1" />
+          {badgeList.length > 0 && (
+            <div data-terp="page-badges">
+              {badgeList.map((badge, index) => (
+                <Fragment key={index}>{badge}</Fragment>
+              ))}
+            </div>
+          )}
+          {hasDescription && (
+            <p data-terp="page-description">{resolveUiTextNode(description, resolve)}</p>
+          )}
         </div>
+        {actions}
       </header>
       {/* Reset the slot for the body's own subtree, so nested content is never judged
           by an ancestor archetype's slot. */}

package/src/layout.test.tsx CHANGED Viewed

@@ -259,6 +259,42 @@ describe("DetailList", () => {
     expect(el).toHaveAttribute("data-columns", "2");
   });
+  it("stamps a gap only when one was asked for, because the default is the layout's", () => {
+    // Unlike Stack's and Grid's, this attribute is conditional, and the condition is the point:
+    // the default row gap differs per layout — --space-3 for aligned and stacked, --space-1 for
+    // inline, where a pair is one line of a paragraph rather than a block. There is no single
+    // default to compare against, so an unset gap must stamp NOTHING and leave the layout rule
+    // standing. Stamping a default here would silently flatten all three back to one value,
+    // which is the grouping defect the layouts' own gap was added to fix.
+    const { rerender } = render(
+      <DetailList data-testid="dl" layout="aligned" items={[{ label: "Owner", value: "Ada" }]} />,
+    );
+    expect(screen.getByTestId("dl").hasAttribute("data-gap")).toBe(false);
+    rerender(
+      <DetailList
+        data-testid="dl"
+        layout="aligned"
+        gap={6}
+        items={[{ label: "Owner", value: "Ada" }]}
+      />,
+    );
+    expect(screen.getByTestId("dl")).toHaveAttribute("data-gap", "6");
+    // Step 0 is a real step and must survive the conditional — a falsy-check rather than an
+    // undefined-check would drop it, and "no gap between pairs" would silently render the
+    // layout's default instead.
+    rerender(
+      <DetailList
+        data-testid="dl"
+        layout="aligned"
+        gap={0}
+        items={[{ label: "Owner", value: "Ada" }]}
+      />,
+    );
+    expect(screen.getByTestId("dl")).toHaveAttribute("data-gap", "0");
+    // And still no inline style: every step is a rule the sheet keys on (ADR 0097).
+    expect(screen.getByTestId("dl").getAttribute("style")).toBeNull();
+  });
   it("puts no colon in the markup, because two layouts must not have one", () => {
     // The colon is a rule on the inline layout, not a text node — `aligned` and `stacked` must
     // not carry one, and no rule can withdraw a text node. It is decorative either way: the

package/src/layout.tsx CHANGED Viewed

@@ -241,6 +241,22 @@ export interface DetailListProps extends Omit<HTMLAttributes<HTMLDListElement>,
   layout?: DetailListLayout;
   /** Pairs per row (default `1`). */
   columns?: 1 | 2;
+  /**
+   * Distance **between pairs**, as a step on the token spacing scale.
+   *
+   * Defaults to the layout's own: `--space-3` for `aligned` and `stacked`, `--space-1` for
+   * `inline`, where a pair is one line of a paragraph rather than a block of its own.
+   *
+   * It sets the ROW gap only, and that is a guarantee rather than an implementation detail. The
+   * column gap is the label-to-value distance in `aligned` and the space between pair groups at
+   * `columns={2}`, so a caller who could set it would be reaching past the layout into its
+   * internals; a `gap` shorthand from here would reset both.
+   *
+   * The prop exists because its absence was the reason the value was unreachable: `Stack`,
+   * `Grid` and `Card` all take a `gap` on this scale, and app modules may write neither `style`
+   * nor `className` (ADR 0059), so a detail list needing looser rows had nowhere to say so.
+   */
+  gap?: SpaceToken;
 }
 /**
@@ -263,11 +279,30 @@ export interface DetailListProps extends Omit<HTMLAttributes<HTMLDListElement>,
  * layout alone — `aligned` and `stacked` must not have one, and a text node cannot be
  * withdrawn by a rule. It is decorative either way: the `<dt>` / `<dd>` pairing is what carries
  * the relationship to assistive tech.
+ *
+ * Three later corrections are worth knowing, because each was measured rather than reasoned:
+ *
+ * - **The label is muted, and `aligned` shares that rule with `stacked`.** It did not, and the
+ *   gap was the whole legibility complaint: an aligned `<dt>` rendered at the value's own size,
+ *   weight and ink, so a card of five labelled values was a wall of bold text with nothing
+ *   saying which half to read first. `inline` keeps its plain term deliberately — there the
+ *   label is half a sentence.
+ * - **Rows are `--space-3` apart in both non-inline layouts.** At the old `--space-1` the
+ *   distance within a pair equalled the distance between pairs, so nothing grouped. {@link
+ *   DetailListProps.gap} makes it a caller's choice on the same scale as every other primitive.
+ * - **It reflows to one column below the framework's viewport cutover**, where `Grid`
+ *   deliberately does not for a fixed `columns` count. The asymmetry is a decision: `Grid`
+ *   publishes `columns="auto"` as its responsive answer and this component's closed `1 | 2` has
+ *   no such escape, so the reflow has to be its own. Above the cutover the shape is what it
+ *   was, bar a label column now capped at `max-content` rather than floored at min-content;
+ *   below it, four tracks in a phone's width met `overflow-wrap: anywhere` — correct for an
+ *   unbreakable digest, wrong as a way to fit a label — and broke ordinary values mid-word.
  */
 export function DetailList({
   items,
   layout = "inline",
   columns = 1,
+  gap,
   ...rest
 }: DetailListProps) {
   const text = useUiText();
@@ -278,6 +313,10 @@ export function DetailList({
       // `inline` and one column are the base rule, so neither stamps an attribute.
       data-layout={layout === "inline" ? undefined : layout}
       data-columns={columns === 1 ? undefined : String(columns)}
+      // No default to compare against: the default row gap is the LAYOUT's, so an unset gap
+      // must stamp no attribute at all and leave the layout rule standing. Stack's and Grid's
+      // gaps stamp unconditionally because their defaults are one value, not three.
+      data-gap={gap === undefined ? undefined : String(gap)}
     >
       {items.map((item, index) => (
         <div key={index} data-terp="detail-list-row">

package/src/markers.test.ts CHANGED Viewed

@@ -198,7 +198,8 @@ const MARKERS = [
   "nav-icon-fallback",
   "page",
   "page-actions",
-  "page-breadcrumbs",
+  "page-badges",
+  "page-description",
   "page-header",
   "page-heading",
   "page-title",