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

@terpjs/react-core 0.9.0 → 0.10.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 (96) hide show

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

package/README.md CHANGED Viewed

@@ -53,7 +53,7 @@ JSDoc, so your editor shows the same guidance inline. **Never deep-import** from
 | `LoginView` | The standard sign-in screen: username/password, plus optional SSO provider buttons via `ssoProviders` and a dev-only credential-fill button via `devCredentials` (gate it on `import.meta.env.DEV`). |
 | `useSso`, `parseSsoCallback`, `fetchSsoAuthorizationUrl`, `completeSsoCallback` | The SSO login seam (ADR 0058): `useSso().begin(provider)` opens an OIDC flow; `TerpProvider` completes the `/auth/callback/{provider}` redirect landing into a normal session on boot. `renderTerpApp({ ssoProviders })` wires the buttons in one line. |
 | `RequireAuth` | Renders children only with a session; pairs with the router so the app mounts only when signed in. |
-| `ThemeProvider`, `ThemeToggle`, `useTheme` | Theming over the five shipped palettes — `light`, `dark`, `midnight`, `twilight`, `contrast` — plus `system` to follow the OS preference. Applies `data-theme` on `<html>` (the token stylesheet carries every palette) and persists the choice. `defaultTheme` is how an app ships on a named theme. `renderTerpApp` mounts it for every app; the shell header uses an icon-only, token-themed `variant="inline"` menu. |
+| `ThemeProvider`, `ThemeToggle`, `useTheme` | Theming over the shipped palettes — `light`, `dark`, `midnight`, `twilight`, `contrast` — plus `system` to follow the OS preference. Applies `data-theme` on `<html>` (the token stylesheet carries every palette) and persists the choice. `defaultTheme` is how an app ships on a named theme — declare it in `layout-contract.json` so a tool can read and rewrite it, or pass the bootstrap option; both is refused. `renderTerpApp` mounts it for every app; the shell header uses an icon-only, token-themed `variant="inline"` menu. |
 | `LocaleProvider`, `LanguageSwitcher`, `useLocale`, `LOCALE_EN`, `LOCALE_NL` | The language seam over `UiTextProvider`: per-locale string catalogs, a persisted active locale, and an icon-only, token-themed menu in the shell header once an app declares a second locale. English and Dutch catalogs ship complete; `renderTerpApp({ locales })` wires them. |
 | `UserMenu`, `userInitials` | The signed-in user's menu, pinned by `buildAppRouter` to the bottom of the sidebar: an initials avatar trigger opening the identity block, **Settings** (the built-in profile page) and sign-out. Collapses to the avatar in the icon rail. |
 | `ProfileView` | The built-in profile / settings page (`/profile`): the server-validated identity, theme + language preferences, and sign-out. |
@@ -76,11 +76,25 @@ 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. |
-| `NavIcon`, `Icon`, `TerpMark`, `ICON_GLYPHS` | The dependency-free icon layer: manifest `NavItem.icon` names resolve to bundled inline-SVG glyphs (label-initial fallback), `Icon` renders any glyph by name (`<Icon name="plus" size="1em" />`) — 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, …) — and `TerpMark` is the placeholder brand mark until an app passes its own `logo`. |
+| 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. |
+| `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. |
+| `defaultDrawerOpen` (shell) | Opens the mobile drawer on mount. A dev/specimen affordance — an app opening it on load shows every mobile user a menu they did not ask for — and the only way to render the drawer's own geometry and backdrop at all, since below the breakpoint the sidebar exists only while the drawer is open. |
+| `headerActions` (shell) | Extra header content before the theme and language controls. Now forwarded by `renderTerpApp` and `buildAppRouter`; it was previously reachable only by dropping to `TerpProvider` + `buildAppRouter` by hand. |
+| `permission` (nav + route) | A named grant from `CurrentUser.permissions`, **ANDed** with `role` — the same composition `Authorized` ships, because a server `Policy` carrying a `Permission` enforces the permission's role floor *and* the grant. Declared on both `NavItem` and `ModuleRoute`, so a hidden link never leaves a reachable route. Fails closed three ways: signed out, unknown name, and an app with no grant capability (empty list). Not a combinator — the server's own `AuthzRef` is one ref per read and one per write, so an any-of could express a gate no `Policy` can declare. |
+| `activeNavPath` / `isNavItemActive` | Which nav item is current, as one predicate. Longest **segment-aligned** match wins across the set, because "at most one is current" cannot be decided one link at a time — a router marks every prefix-active link, so `/settings` and `/settings/users` are both current at `/settings/users`. `NavItem.exact` narrows a single item to itself. Search and hash are ignored: a tab's identity is its path, so filtering a list must not unhighlight it. |
+| `groupNav` / `NavGroup` | The app declares named sections (`{ id, label, order }`); modules point items at them with `NavItem.group`, and `NavItem.order` sorts within one. A group spans modules, so no module can own its label or position — which is why this is the one part of the navigation model that is not on a module manifest. Additive: declare none and the sidebar is the flat list it is today. Absent `order` is 0 and the sort is stable (CSS `order` semantics), an item naming an undeclared group falls **open** into the ungrouped bucket rather than vanishing, a group left empty by `role`/`permission` filtering renders nothing at all, and the ungrouped bucket is emitted **last** so the packaged `/admin` entry stays where it already is. A `label: null` group renders no heading — pure positioning. Declare the groups in `layout-contract.json` under `shell.navGroups` (where `label: ""` is how a file spells `null`) so a tool can read and rewrite them, or pass the bootstrap option; both is refused. |
+| `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. |
 | `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. |
+| `FormPage` | A create-or-edit screen. `measure="narrow"` by default, so the whole frame — header, actions and all — caps at 32rem over a single column of controls. Its body slot takes the form container (`Stack as="form"`), plus `Grid` / `Card` / `Divider` / `Text`; a bare `Field` at the top level is refused, because a run of fields has no `<form>` and cannot be submitted. |
+| `SettingsPage` | Preferences and account screens: `Card` sections, also `measure="narrow"`. No `DataView`, `DetailList` or `Tabs` — a settings screen whose body is a collection is an overview with the wrong chrome. `parents` is optional, unlike `FormPage`'s. |
+| `SplitPage`, `SplitPane` | A list beside the record it selects. The archetype owns the pane row and admits **only** `SplitPane` in it (`HubPage`'s shape, not `DetailPage`'s), so the panes are the governed thing. `listWidth` is a step — `sm` / `md` / `lg` — not a length; a draggable divider waits for the preference seam. Each pane is a named `<section>`, and below the mobile breakpoint they stack list-first, so the reading order and the tab order agree at both widths. |
 | `Breadcrumbs` | The trail itself (used by the archetypes; rarely composed directly). Ancestor crumbs use the router's `Link` by default — `renderLink` is only for rendering outside a Terp router. |
 | `NavLinkContext`, `useNavLink` | The ambient link renderer `buildAppRouter` publishes (and the layout components default to); provide it yourself in a standalone story/test tree or a bespoke shell. |
 | `useRouteParam` | Read one route param, fail closed: the declared param comes back as a string, an undeclared name throws a directive error instead of silently yielding `undefined`. Replaces the unchecked `useParams({ strict: false }) as {…}` cast (ADR 0092). Checked against the generated route table when the app has one. |
@@ -127,17 +141,28 @@ a generated file every helper falls back to `string`, so adopting is opt-in: add
 ### Slot-typed layout contracts (opt-in, ADR 0079)
-An app can ratchet the archetype control further with a named **layout contract**:
-`renderTerpApp({ layoutContract: "standard" })` (runtime half) plus a checked-in
-`layout-contract.json` next to the frontend sources (`{ "contract": "standard" }`, the
-`terp/layout-contract` lint half — keep the two in sync; the project template generates
-both). Each governed archetype's body slot then accepts **only** the contract's
+An app can ratchet the archetype control further with a named **layout contract**,
+declared once in a checked-in `layout-contract.json` next to the frontend sources
+(`{ "contract": "standard" }`) and read by both halves: the `terp/layout-contract` lint
+rule finds the file on disk, and `main.tsx` imports it —
+`renderTerpApp({ layout })`. The same file carries the palette the app opens on
+(`defaultTheme`) and the shell's own shape under `shell` (`density`, `navPlacement`,
+`contentWidth`, the `navGroups` a module's `NavItem.group` names by id, and the `brand` marks
+as paths), which is what lets a tool read and rewrite those choices instead of them living
+only in TypeScript. Declaring a key in the file AND
+passing the matching bootstrap option is refused when the router is composed, with both
+sources named; `layoutContract: "standard"` on its own still works for an app that would
+rather write code than check in a file. Each governed archetype's body slot then accepts **only** the contract's
 components — `standard`: hub bodies hold `HubCard` only; overview bodies hold
-`DataView` / `ResourceList` / `ModuleNav` / `Stack` / `Card` plus the framework states
-(`EmptyState` / `ErrorState` / `LoadingState` / `Alert`) and `ConfirmDialog`; detail
-bodies hold `DetailList` / `Stack` / `Tabs` / `ModuleNav` / `DataView` / `Card` plus
-the same states. The plain `Page` stays unconstrained (the sanctioned home for a
-bespoke screen). Only the slot's **direct** children are governed — an allowed
+`DataView` / `ResourceList` / `ModuleNav` / `Stack` / `Card` / `Divider` / `Text` plus
+the framework states (`EmptyState` / `ErrorState` / `LoadingState` / `Alert`) and
+`ConfirmDialog`; detail bodies hold `DetailList` / `Stack` / `Tabs` / `ModuleNav` /
+`DataView` / `Card` / `Grid` / `Divider` / `Text` plus the same states. The asymmetry is
+deliberate and pinned by tests rather than left to the table: `Grid` joins **detail**
+bodies only (an overview body is a collection, and a grid of summary cards is a hub,
+which has its own archetype), while `Heading` joins **neither** — a heading in a governed
+body must own its section, and `Card` is how a section is owned. The plain `Page` stays
+unconstrained (the sanctioned home for a bespoke screen). Only the slot's **direct** children are governed — an allowed
 container's own subtree (a `Card` body, a `Stack` of rows) is the app's to compose.
 Enforcement is two-layer and fail-closed: the lint rule checks static JSX
 children; the archetypes verify the rendered DOM (sanctioned components stamp a
@@ -145,7 +170,9 @@ children; the archetypes verify the rendered DOM (sanctioned components stamp a
 message** — contract, slot, what was found, what is allowed, and the fix — so a
 failing check tells the author (human or agent) exactly how to build the screen.
 `LAYOUT_CONTRACTS` exports the table; no config means no checks (fully backwards
-compatible). The one opt-out is a justified `// terp-allow-layout-contract: <reason>`
+compatible). Every exported archetype must appear in it or name its reason for not
+appearing — an archetype missing from the table is silently ungoverned by both halves,
+which used to be a green build. The one opt-out is a justified `// terp-allow-layout-contract: <reason>`
 marker, counted by the escape-hatch budget.
 ## Data
@@ -159,7 +186,8 @@ marker, counted by the escape-hatch budget.
 | `useRecord` | The singleton counterpart of `useResource` — the one record a detail screen shows: `item` (or `null`) + loading/error + reload + mutate. Deletes the one-element-list wart (`list: async () => [unwrap(…)]` then `items[0]`). |
 | `useRealtimeChannel` | The sanctioned typed SSE/WebSocket seam for the optional realtime capability: mints a short-lived one-use ticket via the authenticated generated client, validates every inbound JSON payload with the channel's runtime type guard, and exposes connection state / last message / WebSocket send. App modules never touch raw transports. |
 | `ResourceList` | The standard simple CRUD list screen: titled section, write-gated create form, loading/error/empty states. Composable — screens needing more render their own React. |
-| `unwrap`, `unwrapOptional`, `ApiError` | Turn a generated-client result into data-or-throw; `ApiError` carries the envelope's `code` / `status` / `requestId`. `unwrapOptional` returns `null` on a 404 instead — for resources whose absence is a normal state (a `/latest` snapshot not yet published), the client-side analog of `BaseService.find` beside `get`. |
+| `unwrap`, `unwrapOptional`, `ApiError` | Turn a generated-client result into data-or-throw; `ApiError` carries the envelope's `code` / `status` / `requestId`, plus `fields` — the per-field reasons of a 422, keyed by dotted path, ready to hand to `Field`'s `error` prop (`{}` when the failure names no field). `unwrapOptional` returns `null` on a 404 instead — for resources whose absence is a normal state (a `/latest` snapshot not yet published), the client-side analog of `BaseService.find` beside `get`. |
+| `useFormatDate`, `useFormatDateTime`, `useFormatNumber` (and locale-explicit `formatDate` / `formatDateTime` / `formatNumber`) | Render a date or a number in the **app's** locale. `toLocaleDateString()` with no argument asks the browser, so an app shipping one language renders its own tables in whatever the visitor's OS is set to. The hooks read `LocaleProvider` and are `useCallback`-stable, so a column list built in a `useMemo` can depend on one. An absent or unparseable value renders as an em dash rather than throwing. |
 | `FileUpload`, `useFileDownload` | The files-capability surface (ADR 0056/0057): a token-styled attachment picker that uploads through the typed client, and an authenticated download helper (a raw `<a href>` would carry no bearer token). |
 | `useEndpointDownload`, `saveBlob` | Download an artifact the backend **generates** — an evidence bundle, a CSV export — which has no stored file id (ADR 0096). Goes through the session client, so it carries the base URL and bearer token and rejects a non-2xx instead of saving the error body under the intended filename. |
@@ -178,20 +206,22 @@ marker, counted by the escape-hatch budget.
 | Export | Use |
 |---|---|
-| `Button` | Token-styled, content-sized command (`variant`: primary / secondary / danger / ghost; optional leading `icon`). Explicit `width: 100%` opts into full width. |
-| `Input`, `Select`, `Textarea` | Token-styled controls with stable framework typography, independent of surrounding display text (raw elements are lint-refused). Numeric inputs suppress unthemeable browser steppers. |
+| `Button` | Token-styled command: `variant` (primary / secondary / danger / ghost), `size` (sm / md / lg, composing with density), `loading` (spinner in the icon slot, `aria-busy`, and disabled so a second click cannot start the request twice), `fullWidth` to fill the container instead of the label, and an optional leading `icon`. Content-sized by default. |
+| `Input`, `Select`, `Textarea` | Token-styled controls with stable framework typography, independent of surrounding display text (raw elements are lint-refused). Numeric inputs suppress unthemeable browser steppers. `Input type="password"` grows a reveal toggle — the type decides, so there is no second export and no prop; an app could not add one itself, because the toggle needs a positioned wrapper and module files may use neither `style` nor `className`. |
+| `Select` options (`SelectOption<T>`) | Two forms. Pass `options={[{ value, label, disabled? }]}` with `onValueChange` when the choices are data — `T` is inferred from the list, so a closed enum is checked at both ends and the `event.target.value as Status` cast goes away; `placeholder` renders the disabled empty-valued leading row. Or pass `<option>` children as before. The two are mutually exclusive at the type level, so neither can silently ignore the other. |
 | `Combobox` | Accessible autocomplete/typeahead single-select: filterable options, controlled or uncontrolled value, loading state, disabled state, and ARIA combobox/listbox keyboard navigation. |
 | `DatePicker`, `DateRangePicker` | Locale-aware calendar popover controls with keyboard-navigable month grids, min/max bounds, and range selection for ERP date filters. |
 | `Checkbox` | Labelled checkbox with `checked` / `defaultChecked` and boolean `onChange`. |
 | `Radio`, `RadioGroup` | Labelled radio and accessible grouped radio options with controlled or uncontrolled value. |
 | `Switch` | Labelled boolean toggle (`role="switch"`) with `checked` / `defaultChecked` and boolean `onChange`. |
 | `Tabs` | In-page (non-routed) tab set with `tablist` / `tab` / `tabpanel` roles, arrow-key navigation, and controlled or uncontrolled value. |
+| `Avatar` | The initials tile: `from` (an email or a name) or explicit `initials`, and a closed `size` of `sm` (2rem, an account menu) or `md` (3.5rem, a profile header). `aria-hidden`, because the name it abbreviates is always rendered beside it. No `src`: `/me` carries no avatar URL, so an image slot would be a prop with nothing behind it. |
 | `Badge` | Small status pill: `<Badge tone="success">Synced</Badge>` (or `label="Synced"`); `tone`: neutral / info / success / warning / danger. |
 | `Tooltip` | Accessible focus/hover tooltip that describes its trigger with `aria-describedby`. |
 | `Popover`, `Menu`, `MenuItem` | Shared anchored overlay and dropdown-menu primitives: body-portaled, viewport-aware panels that escape scroll/table clipping, with outside-click/Escape close, focus return, selected-item semantics, and roving keyboard navigation. |
 | `Alert` | Inline banner for persistent feedback (`tone`: neutral / info / success / warning / danger); warnings and danger announce as `alert`, others as `status`. |
 | `Markdown` | Safe, dependency-free markdown renderer for headings, paragraphs, bold, italic, inline code, code blocks, lists, and safe links; raw HTML is rendered as text and never passed through. |
-| `Field` | Label + control + hint/error wrapper for one form field. |
+| `Field` | Label + control + hint/error wrapper for one form field. The error is announced (`role="alert"`) as well as described, because `aria-describedby` alone is silent for a rejection that arrives after focus has left the control. |
 ## Layout
@@ -201,9 +231,15 @@ token spacing scale, so spacing is themed centrally):
 | Export | Use |
 |---|---|
-| `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. |
-| `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. |
-| `DetailList` | Token-styled label/value pairs as a semantic `<dl>` (record metadata, expanded-row summaries). |
+| `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. |
+| `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. |
+| `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. |
+| `Link` | A link with themeable ink, routing in-app paths through the surrounding router and degrading to a plain anchor outside one. An external `newTab` gets `rel="noreferrer"`. The boundary lint refuses a raw in-app `<a href="/…">`; this is the thing to use instead. |
 ## The packaged admin area

package/package.json CHANGED Viewed

@@ -1,10 +1,11 @@
 {
   "name": "@terpjs/react-core",
-  "version": "0.9.0",
+  "version": "0.10.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": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./layout.manifest.json": "./src/layout.manifest.json"
   },
   "types": "./src/index.ts",
   "scripts": {
@@ -13,11 +14,11 @@
   },
   "dependencies": {
     "@tanstack/react-router": "^1.170.16",
-    "@terpjs/contract": "^0.9.0"
+    "@terpjs/contract": "^0.10.0"
   },
   "peerDependencies": {
-    "react": "^18.3.0 || ^19.0.0",
-    "react-dom": "^18.3.0 || ^19.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/src/AppShell.test.tsx CHANGED Viewed

@@ -117,6 +117,79 @@ describe("AppShell", () => {
     ).not.toHaveAttribute("data-collapsed");
   });
+  it("stamps no density unless one is asked for, so an app's own html-level choice wins", () => {
+    // The regression this exists to prevent shipped for one commit. The prop was defaulted to
+    // "comfortable" and stamped unconditionally, which reads as harmless — comfortable is the
+    // :root value, after all. It is not: comfortable now has a RULE of its own (that is what
+    // makes an island possible), so stamping it on the shell root overrides
+    // `data-density="compact"` set on <html>, which ADR 0094 section 4 names as the app-wide
+    // case and which an app sets from its own theme.css.
+    //
+    // So absence has to mean "inherit whatever is above me". The two values mean what they say.
+    const { unmount } = renderShell();
+    expect(
+      document.querySelector('[data-terp="appshell"]'),
+      "an unasked-for shell prop must not beat an app-wide choice",
+    ).not.toHaveAttribute("data-density");
+    unmount();
+    renderShell({ density: "compact" });
+    expect(document.querySelector('[data-terp="appshell"]')).toHaveAttribute(
+      "data-density",
+      "compact",
+    );
+    cleanup();
+    // And comfortable IS stamped when asked for, because it is now an instruction rather than
+    // a no-op: it is how a shell inside something compact says it is not.
+    renderShell({ density: "comfortable" });
+    expect(document.querySelector('[data-terp="appshell"]')).toHaveAttribute(
+      "data-density",
+      "comfortable",
+    );
+  });
+  it("stamps data-content-width only when the measure is asked for", () => {
+    // The default has to stamp NOTHING, and that is the assertion rather than a detail: the
+    // rule is keyed on `[data-content-width="measured"]`, so an attribute for the full-width
+    // case would match nothing while looking like it configured something — and every app on
+    // the default must render byte-identically to before the prop existed.
+    const { unmount } = renderShell();
+    expect(document.querySelector('[data-terp="appshell"]')).not.toHaveAttribute(
+      "data-content-width",
+    );
+    unmount();
+    renderShell({ contentWidth: "full" });
+    expect(
+      document.querySelector('[data-terp="appshell"]'),
+      'contentWidth="full" is the sheet\'s own behaviour, so it stamps no attribute',
+    ).not.toHaveAttribute("data-content-width");
+    cleanup();
+    renderShell({ contentWidth: "measured" });
+    expect(document.querySelector('[data-terp="appshell"]')).toHaveAttribute(
+      "data-content-width",
+      "measured",
+    );
+  });
+  it("keeps the measure attribute on the shell root, above the page it constrains", () => {
+    // Ownership, which the selector depends on: the rule descends from the shell root to
+    // `[data-terp="page"]`, so the attribute cannot live on `main` or on the page itself. A
+    // later refactor moving it one element down would break the measure with no test failing
+    // unless this says where it belongs.
+    renderShell({ contentWidth: "measured" });
+    const root = document.querySelector('[data-terp="appshell"]')!;
+    expect(root.getAttribute("data-content-width")).toBe("measured");
+    for (const marker of ["appshell-column", "appshell-main", "appshell-header"]) {
+      expect(
+        document.querySelector(`[data-terp="${marker}"]`),
+        `${marker} must not carry the measure attribute — the rule keys on the shell root`,
+      ).not.toHaveAttribute("data-content-width");
+    }
+  });
   it("renders a custom logo and footer in their slots", () => {
     renderShell({ logo: <span>MyMark</span>, footer: <span>v1.2.3</span> });
     expect(screen.getByText("MyMark")).toBeInTheDocument();
@@ -170,4 +243,245 @@ describe("AppShell", () => {
     expect(screen.queryByRole("navigation", { name: "Primary" })).not.toBeInTheDocument();
     expect(document.body.style.overflow).toBe("");
   });
+  describe("the brand mark", () => {
+    it("gives the mark a box of its own, with one child when there is no dark pair", () => {
+      renderShell({ logo: <img src="/logo.svg" alt="" /> });
+      const box = document.querySelector('[data-terp="appshell-mark"]');
+      expect(box).not.toBeNull();
+      expect(box!.children).toHaveLength(1);
+      // No attribute in the common case: the switch exists only when there is something to
+      // switch between, so an app that passes one asset renders one node and no mechanism.
+      expect(box!.querySelector("[data-appearance]")).toBeNull();
+    });
+    it("renders both marks when a dark one is given, and labels which is which", () => {
+      renderShell({
+        logo: <img src="/logo-light.svg" alt="" />,
+        logoDark: <img src="/logo-dark.svg" alt="" />,
+      });
+      const box = document.querySelector('[data-terp="appshell-mark"]')!;
+      // Both are in the DOM and the SHEET picks — the theme is `<html data-theme>`, which an
+      // app may set with no provider mounted, so a React branch would be wrong for every shell
+      // outside `renderTerpApp`. That is why this asserts presence rather than absence.
+      expect(box.querySelector('[data-appearance="light"] img')).toHaveAttribute(
+        "src",
+        "/logo-light.svg",
+      );
+      expect(box.querySelector('[data-appearance="dark"] img')).toHaveAttribute(
+        "src",
+        "/logo-dark.svg",
+      );
+    });
+  });
+  describe('navPlacement="header"', () => {
+    it("moves the whole navigation into the header and renders no sidebar", () => {
+      renderShell({ navPlacement: "header" });
+      const header = screen.getByRole("banner");
+      const navigation = screen.getByRole("navigation", { name: "Primary" });
+      // The same nav, in a different parent — the assertion is containment rather than
+      // existence, because existence passes in both placements.
+      expect(header).toContainElement(navigation);
+      expect(header).toContainElement(screen.getByRole("link", { name: "Terp" }));
+      // The user menu follows it. Losing it is the failure a placement prop invites, since it
+      // is where an app puts sign-out and the sidebar was the only thing holding it.
+      expect(header).toContainElement(screen.getByText("pinned footer"));
+      expect(document.querySelector('[data-terp="appshell-sidebar"]')).toBeNull();
+      expect(document.querySelector('[data-terp="appshell"]')).toHaveAttribute(
+        "data-nav-placement",
+        "header",
+      );
+    });
+    it("renders no sidebar toggle, because there is no sidebar to collapse", () => {
+      renderShell({ navPlacement: "header" });
+      // Not a tidying assertion: the button carries aria-expanded, so rendering it would
+      // announce a state about an element that does not exist.
+      expect(screen.queryByRole("button", { name: "Collapse sidebar" })).toBeNull();
+      expect(screen.queryByRole("button", { name: "Expand sidebar" })).toBeNull();
+      expect(document.querySelector("[aria-expanded]")).toBeNull();
+    });
+    it("does not leak a persisted rail choice into the header's link context", () => {
+      // The regression this exists for: `collapsed` is persisted, so a user who had collapsed
+      // the rail before the app moved its nav would get icon-only links in a header with room
+      // for labels — and the sidebar attribute that normally reveals the state lands nowhere.
+      window.localStorage.setItem(SIDEBAR_STORAGE_KEY, "collapsed");
+      renderShell({
+        navPlacement: "header",
+        navFooter: ({ collapsed }) => <p>{collapsed ? "rail" : "full"}</p>,
+      });
+      expect(screen.getByText("full")).toBeInTheDocument();
+    });
+    it("is desktop-only: below the breakpoint it is still the drawer", () => {
+      stubMobileViewport();
+      renderShell({ navPlacement: "header" });
+      // The attribute is derived from the viewport, not stamped from the prop, which is what
+      // lets every rule keyed on it skip a [data-variant] guard.
+      expect(document.querySelector('[data-terp="appshell"]')).not.toHaveAttribute(
+        "data-nav-placement",
+      );
+      expect(screen.queryByRole("navigation", { name: "Primary" })).not.toBeInTheDocument();
+      fireEvent.click(screen.getByRole("button", { name: "Open navigation" }));
+      expect(screen.getByRole("dialog", { name: "Primary" })).toBeInTheDocument();
+    });
+  });
+});
+// Navigation groups, as the shell renders them.
+//
+// Every assertion here is on the SHELL'S OUTPUT, never on a fixture literal. That distinction is
+// the one this phase keeps paying for: nine AppShell specimens hand-write `aria-current` in their
+// own renderLink, so no baseline gates the shell's active paint at all. A group label read back
+// from the string that was passed in would be the same mistake.
+//
+// The name queries are `getByRole("list", { name })` rather than `toHaveAttribute`, and that is a
+// gate decision rather than a style one. A dropped or dangling `aria-labelledby` is not a
+// violation any lane in this repo can see — axe files a bad IDREF as `incomplete`, and the a11y
+// lane reads `results.violations` only — so the accessible NAME has to be the thing asserted, and
+// only a name query computes it.
+describe("AppShell navigation groups", () => {
+  const grouped: NavItem[] = [
+    { label: "Notes", to: "/notes", group: "work" },
+    { label: "Reports", to: "/reports", group: "work" },
+    { label: "Loose", to: "/loose" },
+  ];
+  it("labels each group's list with its own visible label", () => {
+    render(
+      <AppShell
+        title="Terp"
+        nav={grouped}
+        navGroups={[{ id: "work", label: "Werkruimte" }]}
+        renderLink={(item, children) => <a href={item.to}>{children}</a>}
+      >
+        <p>page content</p>
+      </AppShell>,
+    );
+    // The accessible name is computed from the rendered span, so this is red on a dropped
+    // attribute AND on an id that resolves nowhere.
+    const labelled = screen.getByRole("list", { name: "Werkruimte" });
+    expect(labelled).toBeInTheDocument();
+    expect(
+      [...labelled.querySelectorAll("a")].map((anchor) => anchor.getAttribute("href")),
+    ).toEqual(["/notes", "/reports"]);
+    // The ungrouped bucket is a second list, and it has no name of its own.
+    expect(screen.getAllByRole("list")).toHaveLength(2);
+  });
+  it("gives two shells on one page distinct label ids", () => {
+    // The workbench catalogue renders three shells on one page. With a module-constant id the
+    // second shell's `aria-labelledby` resolves into the FIRST shell's span — a wrong accessible
+    // name rather than a missing one, which nothing reports: `duplicate-id` is deprecated in axe
+    // and does not run, and a resolvable IDREF is not a violation whatever it points at.
+    // Mutation: replace `useId()` with a module constant, and the two ids below become equal.
+    const shell = (label: string) => (
+      <AppShell
+        title="Terp"
+        nav={[{ label: "Notes", to: "/notes", group: "g" }]}
+        navGroups={[{ id: "g", label }]}
+        renderLink={(item, children) => <a href={item.to}>{children}</a>}
+      >
+        <p>page content</p>
+      </AppShell>
+    );
+    render(
+      <>
+        {shell("Eerste")}
+        {shell("Tweede")}
+      </>,
+    );
+    const ids = screen
+      .getAllByRole("list")
+      .map((list) => list.getAttribute("aria-labelledby"));
+    expect(ids.filter(Boolean)).toHaveLength(2);
+    expect(new Set(ids)).toHaveProperty("size", 2);
+    // And each one still resolves to its OWN label, which is what the distinct ids are for.
+    expect(screen.getByRole("list", { name: "Eerste" })).toBeInTheDocument();
+    expect(screen.getByRole("list", { name: "Tweede" })).toBeInTheDocument();
+  });
+  it("renders no label element and no aria-labelledby for the default group", () => {
+    // The additive case: a shell given no groups at all must render exactly what it renders
+    // today, plus the wrapper. Mutation: render a span for a null label.
+    const { container } = renderShell();
+    expect(container.querySelectorAll('[data-terp="appshell-nav-group"]')).toHaveLength(1);
+    expect(container.querySelectorAll('[data-terp="appshell-nav-group-label"]')).toHaveLength(0);
+    expect(
+      container.querySelector('[data-terp="appshell-nav-list"]')?.hasAttribute("aria-labelledby"),
+    ).toBe(false);
+  });
+  it("renders nothing at all for a group no visible item references", () => {
+    // Reachable on a first render: `visibleNav` removes the role-gated `/admin` entry for
+    // everyone else, so a group holding only it arrives here empty.
+    // Mutation: emit the empty section, and the label appears over no links.
+    const { container } = render(
+      <AppShell
+        title="Terp"
+        nav={[{ label: "Loose", to: "/loose" }]}
+        navGroups={[{ id: "beheer", label: "Beheer" }]}
+        renderLink={(item, children) => <a href={item.to}>{children}</a>}
+      >
+        <p>page content</p>
+      </AppShell>,
+    );
+    expect(screen.queryByText("Beheer")).not.toBeInTheDocument();
+    expect(container.querySelectorAll('[data-terp="appshell-nav-group"]')).toHaveLength(1);
+    expect(container.querySelectorAll('[data-terp="appshell-nav-group-label"]')).toHaveLength(0);
+  });
+  it("renders no wrapper and no list when every item is gated away", () => {
+    // The degenerate case of "a section with no items is not emitted", and a real change: the
+    // shell used to render an empty <ul> here. It moves nothing — an empty grid list has no
+    // height — and it takes an empty `list` role back out of the accessibility tree, which is
+    // why it is pinned rather than worked around. Reachable whenever `visibleNav` removes every
+    // item, e.g. a viewer in an app whose whole nav is role-gated.
+    // Mutation: emit the ungrouped section unconditionally, and an empty list reappears.
+    const { container } = render(
+      <AppShell title="Terp" nav={[]} renderLink={(item, children) => <a href={item.to}>{children}</a>}>
+        <p>page content</p>
+      </AppShell>,
+    );
+    expect(screen.getByRole("navigation", { name: "Primary" })).toBeInTheDocument();
+    expect(container.querySelectorAll('[data-terp="appshell-nav-group"]')).toHaveLength(0);
+    expect(container.querySelectorAll('[data-terp="appshell-nav-list"]')).toHaveLength(0);
+    expect(screen.queryAllByRole("list")).toHaveLength(0);
+  });
+  it("renders no heading element anywhere in the navigation", () => {
+    // The decision the prose argues and nothing enforced. `Heading` refuses level 1 to reserve
+    // the outline for the routed view's title, and the sidebar renders BEFORE `<main>` — so a
+    // heading per group would sit above every page's h1 on every page in the product. axe cannot
+    // catch it: `heading-order` is best-practice, outside the lane's tags, and h2 -> h1 is a
+    // decrease that passes anyway. Mutation: render the label as an <h2>.
+    render(
+      <AppShell
+        title="Terp"
+        nav={grouped}
+        navGroups={[{ id: "work", label: "Werkruimte" }]}
+        renderLink={(item, children) => <a href={item.to}>{children}</a>}
+      >
+        <p>page content</p>
+      </AppShell>,
+    );
+    const navigation = screen.getByRole("navigation", { name: "Primary" });
+    expect(navigation.querySelector("h1, h2, h3, h4, h5, h6")).toBeNull();
+    // The label is still there and still announced — this is not "no label", it is "no heading".
+    expect(screen.getByText("Werkruimte")).toBeInTheDocument();
+  });
 });