@terpjs/react-core 0.9.0 → 0.10.0

package/src/Field.tsx

@@ -31,6 +31,14 @@ export interface FieldProps {
  * declares either keeps its own value; the field adds to `aria-describedby` rather than replacing
  * it. `Input`, `Select`, `Textarea` and `Combobox` all spread their props onto the DOM element, so
  * the attributes land where assistive tech reads them.
+ *
+ * The error also carries `role="alert"`, and `aria-describedby` is why it has to. A description is
+ * read when focus reaches the control, which covers an error that was already there and covers
+ * nothing about one that appears on submit — by then focus has left the field, or the button, and
+ * the only thing that changed is a span nobody is pointed at. The two are not redundant: they
+ * announce at different moments, and a submit-time rejection only has the second one. Because the
+ * span is conditional, it enters the accessibility tree exactly when the error appears, which is
+ * the event `alert` exists to report.
  */
 export function Field({ label, children, error, hint }: FieldProps) {
   const resolve = useUiText();
@@ -39,17 +47,35 @@ export function Field({ label, children, error, hint }: FieldProps) {
   const hintId = hint !== undefined ? `${baseId}-hint` : undefined;
   const errorId = hasError ? `${baseId}-error` : undefined;
   const described = [hintId, errorId].filter((id) => id !== undefined).join(" ");
+  const labelId = `${baseId}-label`;
 
-  // Only a single element child can be described — which is the documented contract ("the
-  // control"). Anything else is passed through untouched rather than guessed at.
-  const control = described.length > 0 && isValidElement<{
+  // Only a single element child can be named and described — which is the documented contract
+  // ("the control"). Anything else is passed through untouched rather than guessed at.
+  const control = isValidElement<{
     "aria-describedby"?: string;
     "aria-invalid"?: boolean | "true" | "false";
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
   }>(children)
     ? cloneElement(children, {
-        "aria-describedby": [children.props["aria-describedby"], described]
-          .filter((id) => id !== undefined && id !== "")
-          .join(" "),
+        // The control is named by the label TEXT, not by the label element's subtree, and that
+        // distinction is the whole reason this exists. A wrapping label takes its name from
+        // everything inside it, so a control that renders an adornment of its own — the password
+        // reveal is the first — hands its own button's name to the field: Chromium computes
+        // "Password Show password" for that input, which is a WCAG 2.5.3 failure and a sentence
+        // no voice-control user can see to say. Pointing at the span makes the name exact.
+        //
+        // A caller that named the control itself keeps their name; this never overrides one.
+        "aria-labelledby":
+          children.props["aria-label"] === undefined
+            ? (children.props["aria-labelledby"] ?? labelId)
+            : undefined,
+        "aria-describedby":
+          described.length > 0
+            ? [children.props["aria-describedby"], described]
+                .filter((id) => id !== undefined && id !== "")
+                .join(" ")
+            : children.props["aria-describedby"],
         "aria-invalid": children.props["aria-invalid"] ?? (hasError ? true : undefined),
       })
     : children;
@@ -57,7 +83,9 @@ export function Field({ label, children, error, hint }: FieldProps) {
   return (
     <div data-terp="field">
       <label data-terp="field-label">
-        <span data-terp="field-label-text">{resolve(label)}</span>
+        <span id={labelId} data-terp="field-label-text">
+          {resolve(label)}
+        </span>
         {control}
       </label>
       {hint !== undefined && (
@@ -66,7 +94,7 @@ export function Field({ label, children, error, hint }: FieldProps) {
         </span>
       )}
       {hasError && (
-        <span id={errorId} data-terp="field-error">
+        <span id={errorId} role="alert" data-terp="field-error">
           {error}
         </span>
       )}

package/src/FormPage.tsx

@@ -0,0 +1,54 @@
+import type { BreadcrumbItem } from "./Breadcrumbs";
+import { LayoutSlotContext } from "./layoutContract";
+import { Page } from "./Page";
+import type { PageProps } from "./Page";
+
+export interface FormPageProps extends Omit<PageProps, "breadcrumbs"> {
+  /**
+   * The layers this form sits under, outermost first — the list it was reached from, and
+   * anything above that.
+   *
+   * Required, and for the reason `DetailPage`'s is: a create or edit screen is always reached
+   * from somewhere, and a form with no way back is a dead end with unsaved work in it.
+   */
+  parents: readonly (BreadcrumbItem & { to: string })[];
+}
+
+/**
+ * The form archetype: one create-or-edit screen, reached from the collection it writes into.
+ *
+ * It is a `Page` with two things fixed. The frame is `measure="narrow"` by default — header
+ * included — because a form is a single column of controls and a Save button a screen-width
+ * from its last field is worse than one sitting over it. And the body slot admits the shape a
+ * form actually has rather than the shape a record screen has.
+ *
+ * **The body is a container, so `Field` is deliberately not admitted directly.** The slot takes
+ * the form container, plus `Grid` for a two-column arrangement inside a wide form, `Card` for a
+ * grouped section, `Divider` and `Text` between them, and the framework states.
+ *
+ * What that refusal does and does not buy is worth stating exactly, because the obvious claim is
+ * too strong. It keeps fields out of the top level, so a form body is always a container — which
+ * is the shape the archetype is for. It does **not** guarantee the form can be submitted: both
+ * halves of the contract match on `data-terp` markers, and `Stack` renders the same marker
+ * whether or not it was given `as="form"`. So `<Stack><Field/></Stack>` passes and is still
+ * unsubmittable by Enter. Closing that would mean a second marker for the form case, which is
+ * six more names describing the same DOM — the `Section` trade 4b already declined.
+ *
+ * It renders no element of its own — the slot context and `Page`, nothing between them, because
+ * a wrapper around the body would become the sole entry in `article.children` and fail every
+ * governed page closed (ADR 0079).
+ */
+export function FormPage({ parents, measure = "narrow", ...page }: FormPageProps) {
+  return (
+    <LayoutSlotContext.Provider value="FormPage">
+      {/* Spread FIRST, then the archetype's own props — `HubPage`'s order, not
+          `DetailPage`'s. `Omit<PageProps, "breadcrumbs">` removes the key from the type but not
+          from a runtime object, and a JSX spread gets no excess-property check: a wrapper
+          forwarding `{...props}` with a present-but-undefined `breadcrumbs` would otherwise
+          overwrite `parents` and silently drop the trail this archetype requires.
+          (`DetailPage` and `OverviewPage` still spread last. Same latent shape, pre-existing,
+          and left for a change that can re-record their baselines rather than this one.) */}
+      <Page {...page} breadcrumbs={parents} measure={measure} />
+    </LayoutSlotContext.Provider>
+  );
+}

package/src/LoginView.tsx

@@ -37,9 +37,16 @@ export interface DevCredentials {
  *
  * It renders no inline styles: the full-viewport page, the card, the brand row, both button
  * groups, the separator and the error line take their geometry and ink from the injected
- * react-core sheet (ADR 0094). The buttons fill their group through a rule on the group
- * rather than a prop on `Button` — `Button` declares `width: fit-content`, so a grid does not
- * stretch them for free, and a `block` prop for one internal caller is API this does not need.
+ * react-core sheet (ADR 0094).
+ *
+ * Two things here used to be worked around and are not any more, which is worth recording
+ * because the workarounds were both reasonable while they lasted. The buttons filled their
+ * group through a rule on the GROUP, because `Button` declares `width: fit-content` — a
+ * definite width, so a grid does not stretch them for free — and a prop for one internal
+ * caller was API the package did not need. `Button` has `fullWidth` now, so the rule retires
+ * and the four call sites say what they mean. And the submit button hand-rolled a busy state
+ * out of `disabled` plus a swapped label; `loading` is that state, and it adds the spinner and
+ * the `aria-busy` the hand-rolled version never had.
  */
 export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps = {}) {
   const auth = useAuth();
@@ -87,6 +94,9 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
         <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)}
@@ -94,18 +104,20 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
           />
           <Input
             type="password"
+            autoComplete="current-password"
             placeholder={strings.password}
             value={password}
             onChange={(event) => setPassword(event.target.value)}
             required
           />
-          <Button type="submit" disabled={busy}>
+          <Button type="submit" fullWidth loading={busy}>
             {busy ? strings.signingIn : strings.signIn}
           </Button>
           {devCredentials ? (
             <Button
               type="button"
               variant="secondary"
+              fullWidth
               disabled={busy}
               onClick={() => {
                 setEmail(devCredentials.email);
@@ -130,6 +142,7 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
                   key={provider.name}
                   type="button"
                   variant="secondary"
+                  fullWidth
                   disabled={busy}
                   onClick={() => void onSso(provider)}
                 >

package/src/ModuleNav.test.tsx

@@ -61,16 +61,16 @@ describe("ModuleNav", () => {
     );
     expect(screen.getByRole("link", { name: "Overview" })).not.toHaveAttribute("aria-current");
 
-    // The styling key is data-active, and the point is that it is NOT the aria-current
-    // beside it. A router Link merges its own active props last, so aria-current on this
-    // element has a second author — keying the accent edge on it would be the breadcrumb
-    // defect again the moment the two disagreed about "active", which they can, in BOTH
-    // directions: the router also demands an exact query-string match (so it is narrower
-    // on a filtered URL), and it compares paths through removeTrailingSlash while this
-    // component compares them raw (so it is broader on a trailing slash, and then the
-    // accent edge goes missing on a tab the router calls current). The second is a real
-    // defect, older than the marker — the inline styling read the same isActive — and it
-    // is the navigation model's to fix. Neither case is reachable from this specimen.
+    // The styling key is data-active, and the point is that it is NOT the aria-current beside
+    // it: a router Link merges its own active props last, so that attribute has a second author.
+    //
+    // The divergence this comment used to describe is fixed (ADR 0097 §6, amended in 4e). Both
+    // authors now compute the same thing by construction rather than by coincidence. The
+    // component asks `activeNavPath` over the whole strip; the Link is pinned to
+    // `exact: true, includeSearch: false`, so the router volunteers `aria-current` only when the
+    // path equals the URL — the longest possible match, hence always the tab the predicate
+    // picked. It can agree or stay silent; it cannot name a different tab. Which is why the
+    // assertion below can now demand exactly one `aria-current` in the strip.
     const active = screen.getByRole("link", { name: "Projects" });
     const inactive = screen.getByRole("link", { name: "Overview" });
     expect(active).toHaveAttribute("data-terp", "module-nav-link");
@@ -79,6 +79,13 @@ describe("ModuleNav", () => {
     expect(inactive).not.toHaveAttribute("data-active");
     expect(active.getAttribute("style")).toBeNull();
     expect(inactive.getAttribute("style")).toBeNull();
+
+    // Exactly one, over the whole strip. Before 4e the Link was left prefix-matching, so at
+    // /tickets/projects the router added its own aria-current to the /tickets tab as well and a
+    // screen reader announced two current pages.
+    expect(
+      document.querySelectorAll('[data-terp="module-nav"] [aria-current="page"]'),
+    ).toHaveLength(1);
   });
 
   it("returns nothing for an empty tab list", () => {

package/src/ModuleNav.tsx

@@ -1,13 +1,24 @@
 import { Link, useRouterState } from "@tanstack/react-router";
 
+import { activeNavPath } from "./navActive";
 import { useStrings, useUiText } from "./uiText";
 import type { UiText } from "./uiText";
 
 export interface ModuleNavTab {
   /** Display label. */
   label: UiText;
-  /** Router path for an exact sub-page route. */
+  /** Router path for the sub-page route. */
   to: string;
+  /**
+   * Match this tab's path exactly rather than as a segment-aligned prefix.
+   *
+   * The default is the prefix, so a tab stays current on the pages beneath it — a detail route
+   * under `/records/mapping` keeps "Mapping" lit instead of blanking the strip. Set this on a
+   * landing tab that also has siblings deeper in the same strip, where the prefix would keep it
+   * lit alongside them; the shared predicate resolves that case by longest match anyway, so this
+   * is for the narrower job of a tab owning only itself.
+   */
+  exact?: boolean;
 }
 
 export interface ModuleNavProps {
@@ -32,6 +43,12 @@ export function ModuleNav({ items, ariaLabel }: ModuleNavProps) {
   const strings = useStrings();
   const resolve = useUiText();
   const pathname = useRouterState({ select: (state) => state.location.pathname });
+  // Resolved over the whole strip, not per tab, and through the same function the sidebar uses
+  // (ADR 0097 §6, amended in 4e). Two tabs where one path prefixes the other would otherwise
+  // both be current, and this component previously compared `pathname === item.to` raw — which
+  // diverged from its own Link in both directions, as the sheet's comment on the active rule
+  // says. Longest match wins, so `/records` does not steal from `/records/mapping`.
+  const activeTo = activeNavPath(pathname, items);
 
   if (items.length === 0) {
     return null;
@@ -42,12 +59,27 @@ export function ModuleNav({ items, ariaLabel }: ModuleNavProps) {
       <ul data-terp="module-nav-list">
         {items.map((item) => {
           const label = resolve(item.label);
-          const isActive = pathname === item.to;
+          const isActive = item.to === activeTo;
           return (
             <li key={item.to}>
               <Link
                 to={item.to}
-                activeOptions={{ exact: true }}
+                // `exact` is ALWAYS true here, whatever the tab asked for, and the asymmetry is
+                // the mechanism rather than an oversight. The tab's own `exact` governs the
+                // component's predicate above; this governs when the ROUTER volunteers its own
+                // `aria-current`, and the router decides per link with no knowledge of siblings.
+                // Left non-exact it prefix-matches, so at `/tickets/projects` it would mark the
+                // `/tickets` tab current too — a second current item the component never chose.
+                // Exact matching means "the router thinks this is active" implies the path equals
+                // the URL, which is the longest possible match, which is always the tab the
+                // predicate picked. The router can only agree.
+                //
+                // includeSearch: false for the other half. It defaults to true and on an exact
+                // link demands a full query-string match, so at `/tickets/projects?page=2` the
+                // router's own `data-status` said inactive while this component said active.
+                // Nothing paints from `data-status`, which is exactly why that could sit there
+                // unnoticed.
+                activeOptions={{ exact: true, includeSearch: false }}
                 aria-current={isActive ? "page" : undefined}
                 data-terp="module-nav-link"
                 data-active={isActive ? "true" : undefined}

package/src/Page.tsx

@@ -23,6 +23,23 @@ export interface PageProps {
   renderLink?: RenderBreadcrumbLink;
   /** Optional page-level actions, rendered on the heading row (e.g. a primary `Button`). */
   actions?: ReactNode;
+  /**
+   * Cap the whole frame — header included — at a readable measure (default `"full"`).
+   *
+   * `"narrow"` is the single-column-of-controls shape: a create/edit form, a settings screen.
+   * The header is capped WITH the body here, unlike the shell's own content measure, and that
+   * asymmetry is the point rather than an inconsistency. A wide page with a narrow column wants
+   * its title and actions spanning the full track, because the band is what tells you the page
+   * is wider than its text. A form does not: a Save button floating a screen-width away from
+   * the field it saves is worse than one sitting over it.
+   *
+   * `data-measure` is the same attribute name `Text` uses for the same concept, keyed per
+   * marker, so there is one vocabulary for "measure" rather than two.
+   *
+   * `FormPage` and `SettingsPage` default it on; every other archetype leaves it `"full"`,
+   * which stamps nothing.
+   */
+  measure?: "full" | "narrow";
   /** Show the loading state instead of the body (the header stays for orientation). */
   isLoading?: boolean;
   /** Loading slot; defaults to the standard {@link LoadingState} spinner block. */
@@ -61,6 +78,7 @@ export function Page({
   breadcrumbs,
   renderLink,
   actions,
+  measure = "full",
   isLoading,
   loadingState,
   error,
@@ -107,8 +125,12 @@ export function Page({
     ) : (
       children
     );
+  // Hoisted, the density/collapsed idiom: the default stamps nothing, so the expression has a
+  // branch, and a conditional written at the attribute is the form the marker scanner reads
+  // every string literal out of.
+  const measureAttribute = measure === "narrow" ? "narrow" : undefined;
   return (
-    <article ref={articleRef} data-terp="page">
+    <article ref={articleRef} data-terp="page" data-measure={measureAttribute}>
       {/* A <header> ELEMENT, and it has to stay one. The slot check above drops the header
           from the body set by tagName, so re-rendering this as a marked <div> would put it
           back in and fail every governed OverviewPage / DetailPage closed. The marker is

package/src/ProfileView.test.tsx

@@ -76,7 +76,7 @@ describe("ProfileView", () => {
     // jsdom computes no cascade. The address marker matters most of the three — its
     // overflow-wrap has no specimen, since the mock session's address is short, so this is
     // the only gate that the element a long address would need is still the marked one.
-    const avatar = document.querySelector('[data-terp="profile-avatar"]');
+    const avatar = document.querySelector('[data-terp="avatar"]');
     expect(avatar).not.toBeNull();
     expect(avatar?.textContent).toBe("JD");
     expect(avatar?.getAttribute("style")).toBeNull();

package/src/ProfileView.tsx

@@ -3,7 +3,7 @@ import { useAuth } from "./TerpProvider";
 import { LanguageSwitcher } from "./locale";
 import { Stack, DetailList } from "./layout";
 import { ThemeToggle } from "./theme";
-import { userInitials } from "./UserMenu";
+import { Avatar } from "./ui/Avatar";
 import { Button } from "./ui/Button";
 import { useStrings } from "./uiText";
 
@@ -29,9 +29,7 @@ export function ProfileView() {
       <Stack gap={4}>
         <div data-terp="profile-card">
           <Stack direction="row" gap={3} align="center">
-            <span aria-hidden="true" data-terp="profile-avatar">
-              {userInitials(user.email)}
-            </span>
+            <Avatar from={user.email} />
             <Stack gap={0}>
               <strong data-terp="profile-email">{user.email}</strong>
               <p data-terp="profile-role">{user.role_name}</p>

package/src/SettingsPage.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+
+import type { BreadcrumbItem } from "./Breadcrumbs";
+import { LayoutSlotContext } from "./layoutContract";
+import { Page } from "./Page";
+import type { PageProps } from "./Page";
+
+export interface SettingsPageProps extends Omit<PageProps, "breadcrumbs"> {
+  /**
+   * Optional parent layers, for a settings screen nested under an area rather than reached
+   * from the account menu.
+   *
+   * Optional where `FormPage`'s is required, and the difference is real: a form is always
+   * reached from the thing it writes into, while a preferences screen is often a destination in
+   * its own right — the built-in profile page has no parent at all.
+   */
+  parents?: readonly (BreadcrumbItem & { to: string })[];
+}
+
+/**
+ * The settings archetype: preferences and account screens — a stack of titled sections, each
+ * owning a few controls.
+ *
+ * `measure="narrow"` by default, header included, for the reason `FormPage` has it: this is a
+ * single column of controls, not a data surface. `ProfileView`'s own card carries exactly this
+ * measure today, and 4b already named that card as a page measure wearing a card's clothes — so
+ * this is the mechanism it was hand-rolling.
+ *
+ * **The body is `Card` sections and nothing that holds a collection.** No `DataView`, no
+ * `DetailList`, no `Tabs`: a settings screen whose body is a table is an overview, and one with
+ * tabs is a hub with the wrong chrome. `Card` is how a titled region is owned here — which is
+ * what 4b decided when it refused to ship `Section`, and this slot is the first archetype to
+ * depend on that decision rather than merely be compatible with it.
+ *
+ * Renders no element of its own, for the reason every non-hub archetype does not: a wrapper
+ * around the body becomes the sole entry in `article.children` and fails every governed page
+ * closed (ADR 0079).
+ */
+export function SettingsPage({
+  parents,
+  measure = "narrow",
+  ...page
+}: SettingsPageProps): ReactNode {
+  return (
+    <LayoutSlotContext.Provider value="SettingsPage">
+      {/* Spread first, then the archetype's own props — see `FormPage` for why. */}
+      <Page {...page} breadcrumbs={parents} measure={measure} />
+    </LayoutSlotContext.Provider>
+  );
+}

package/src/SplitPage.tsx

@@ -0,0 +1,150 @@
+import type { ReactNode } from "react";
+import { useEffect, useRef, useState } from "react";
+
+import { useLayoutContract, verifySlotChildren } from "./layoutContract";
+import { Page } from "./Page";
+import type { PageProps } from "./Page";
+import { injectTerpStyles } from "./styles";
+import { useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+injectTerpStyles();
+
+/** How much of the row the list pane takes — a step, not a length (ADR 0097 §4). */
+export type SplitListWidth = "sm" | "md" | "lg";
+
+export type SplitPageProps = Omit<PageProps, "children" | "measure"> & {
+  /** Parent trail for a split screen nested below a hub; aliases `Page`'s `breadcrumbs`. */
+  parents?: PageProps["breadcrumbs"];
+  /**
+   * The list pane's track (default `"md"`).
+   *
+   * Enumerable rather than a percentage or a length, which is the same call `Grid`'s
+   * `minColumn` made and for the same reason: a CSS length here would be a measured value and
+   * therefore an inline style on the panes element — a tenth entry in a ledger that admits only
+   * two permanent kinds (ADR 0094 §3). Three steps cover the cases; an app wanting 37% cannot
+   * have it, which is the trade `gap` already makes.
+   *
+   * A **draggable** divider is deliberately not offered: that is a measured value *and* a
+   * per-user preference, so it waits for the preference seam rather than arriving as an inline
+   * style with nowhere to persist.
+   */
+  listWidth?: SplitListWidth;
+  /**
+   * The two panes, **list first** — a `SplitPane role="list"` then a `SplitPane role="detail"`.
+   *
+   * Order is load-bearing: the tracks are filled by grid auto-placement, so the first pane takes
+   * the narrow one. The contract can see that both children are `SplitPane`s and cannot see
+   * which is which, so this is a convention the render makes obvious rather than a rule the
+   * runtime enforces.
+   */
+  children: ReactNode;
+};
+
+/**
+ * The split archetype: a list beside the record it selects — the master-detail screen.
+ *
+ * It is structured on `HubPage`, not on `DetailPage`, and that is the decision worth knowing.
+ * The obvious shape for two panes is one body slot holding two children, but the layout
+ * contract's runtime check takes a single slot owner and reads `article.children`, so two panes
+ * would be two entries in one slot with nothing distinguishing them. Teaching the contract two
+ * slots per archetype was the invasive option. Instead the panes are the governed thing:
+ * `SplitPage` owns the row element and admits `SplitPane` in it and nothing else, exactly as
+ * `HubPage` owns its grid and admits `HubCard`. `verifySlotChildren`, the mirrored table's
+ * shape and the message builder are all untouched.
+ *
+ * It therefore provides **no** `LayoutSlotContext`, for the reason `HubPage` provides none: the
+ * row element carries a marker that appears in no allow table, so a slot context above it would
+ * refuse every split page on its own body.
+ *
+ * Below the mobile breakpoint the panes stack, in DOM order, list first — so the tab sequence is
+ * the reading order in both layouts. That is the property `visual/keyboard.spec.ts` holds.
+ */
+export function SplitPage({
+  parents,
+  breadcrumbs,
+  listWidth = "md",
+  children,
+  ...page
+}: SplitPageProps) {
+  // The runtime half of the slot-typed layout contract control (ADR 0079) for the pane row:
+  // with a contract active, every rendered child of the row must be a SplitPane (its data-terp
+  // marker) — verified one macrotask after mount, refused fail closed. Same shape as HubPage's.
+  const contract = useLayoutContract();
+  const panesRef = useRef<HTMLDivElement>(null);
+  const [slotViolation, setSlotViolation] = useState<string | null>(null);
+  useEffect(() => {
+    if (contract === null) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      const panes = panesRef.current;
+      if (panes === null) {
+        return;
+      }
+      setSlotViolation(verifySlotChildren(contract, "SplitPage", [...panes.children]));
+    }, 0);
+    return () => clearTimeout(timer);
+  });
+  if (slotViolation !== null) {
+    throw new Error(slotViolation);
+  }
+  return (
+    <Page {...page} breadcrumbs={parents ?? breadcrumbs}>
+      <div ref={panesRef} data-terp="splitpage-panes" data-list-width={listWidth}>
+        {children}
+      </div>
+    </Page>
+  );
+}
+
+/** Which half of the split a pane is — the list, or the record it selects. */
+export type SplitPaneRole = "list" | "detail";
+
+export interface SplitPaneProps {
+  /**
+   * Which half this is.
+   *
+   * It does **not** place the pane. The row's tracks are `minmax(0, <listWidth>) minmax(0, 1fr)`
+   * and grid auto-placement fills them in DOM order, so the FIRST pane gets the narrow track
+   * whatever its role says — write the list first. A `detail`-first composition renders the
+   * record in the narrow column, which is wrong and immediately visible.
+   *
+   * Placing by role instead was considered and refused: it would render correctly whatever the
+   * DOM order, and correct-looking is exactly the wrong failure here. Tab order follows the DOM
+   * and CSS cannot change it, so a `detail`-first tree would then read left-to-right and tab
+   * right-to-left — the WCAG 1.3.2 / 2.4.3 mismatch, silent. Leaving placement to the DOM makes
+   * a mis-ordered split look mis-ordered.
+   *
+   * What the role does carry: the pane's identity for anything that needs to tell the two apart
+   * (`visual/keyboard.spec.ts` asserts the tab order through it), and a hook for a rule should
+   * one ever need to distinguish them.
+   */
+  role: SplitPaneRole;
+  /**
+   * The pane's accessible name.
+   *
+   * Required, because each pane is a `<section>` and therefore a landmark: two unnamed regions
+   * side by side are two indistinguishable entries in a screen reader's landmark list, which is
+   * worse than one region containing both.
+   */
+  label: UiText;
+  children: ReactNode;
+}
+
+/**
+ * One half of a {@link SplitPage} — the list, or the detail beside it.
+ *
+ * A named `<section>`, so the two halves are distinguishable landmarks, and the only component
+ * the split's row admits. It renders no inline style, and no style at all beyond a
+ * `min-width: 0` floor: which track it takes comes from its POSITION, not from `role` — see the
+ * prop for why that is the safer of the two.
+ */
+export function SplitPane({ role, label, children }: SplitPaneProps) {
+  const resolve = useUiText();
+  return (
+    <section data-terp="splitpane" data-role={role} aria-label={resolve(label)}>
+      {children}
+    </section>
+  );
+}