@terpjs/react-core 0.7.0 → 0.8.0

package/src/layoutContract.test.tsx

@@ -21,6 +21,9 @@ import {
 import { OverviewPage } from "./OverviewPage";
 import { Page } from "./Page";
 import { DetailList, Stack } from "./layout";
+import { PageActions } from "./PageActions";
+import { ThemeProvider, ThemeToggle } from "./theme";
+import { Button } from "./ui/Button";
 import { Card } from "./ui/Card";
 
 afterEach(cleanup);
@@ -179,3 +182,95 @@ describe("runtime slot enforcement", () => {
     expect(verifySlotChildren("standard", "Page", [])).toBeNull();
   });
 });
+
+// The styling migration (ADR 0094) is renaming rendered roots: components that used to emit
+// an unmarked <div>, or to borrow Popover's `popover`, now name themselves. Every one of those
+// names is read by this check, because the check IS the marker join — so the question is not
+// whether the names look sensible but whether any slot's verdict moved.
+//
+// It did not, and the reason is worth stating rather than re-derived: verifySlotChildren
+// refuses a direct body-slot child whose data-terp is not in the slot's allow table, and a
+// missing attribute is refused too (`marker === null`). None of the new names is in any table,
+// and neither was the unmarked element each replaced. So each of these was refused before the
+// migration and is refused after it. What changed is the MESSAGE — describeElement now reports
+// a named component instead of a bare tag, which is strictly more useful to the person reading
+// the refusal, and is also a string a test could have pinned.
+describe("layout contract survives the roots the styling migration renames", () => {
+  it("still refuses a chrome menu in a governed body, and now names it", async () => {
+    underContract(
+      // The provider renders no element of its own, so the slot's direct child is still the
+      // toggle. Without it ThemeToggle returns null and the body is empty — which passes for
+      // no reason at all.
+      <ThemeProvider>
+        <OverviewPage title="Records">
+          <ThemeToggle variant="stacked" />
+        </OverviewPage>
+      </ThemeProvider>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId("refused").textContent).toBe(
+        slotViolationMessage("standard", "OverviewPage", '<div data-terp="theme-toggle">'),
+      );
+    });
+  });
+
+  it("still refuses an action cluster in a governed body, and now names it", async () => {
+    underContract(
+      <DetailPage title="Record 1" parents={[{ label: "Records", to: "/records" }]}>
+        <PageActions primary={<Button>Publish</Button>} />
+      </DetailPage>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId("refused").textContent).toBe(
+        slotViolationMessage("standard", "DetailPage", '<div data-terp="page-actions">'),
+      );
+    });
+  });
+
+  it("keeps every marker the allow tables name out of the migration's way", () => {
+    // The tables are the audit surface: a rename of one of THESE would widen or close a slot
+    // silently, so they are the markers the migration may not touch without changing both
+    // halves of the contract. Asserted as a set so an addition has to be deliberate.
+    const named = new Set(
+      Object.values(LAYOUT_CONTRACTS.standard!.slots).flatMap((slot) =>
+        Object.values(slot.components),
+      ),
+    );
+    expect([...named].sort()).toEqual([
+      "alert",
+      "card",
+      "dataview",
+      "detail-list",
+      "dialog",
+      "empty-state",
+      "error-state",
+      "hubcard",
+      "loading-state",
+      "module-nav",
+      "resource-list",
+      "stack",
+      "tabs",
+    ]);
+  });
+
+  it("passes a governed body whose children are still allowed components", async () => {
+    // The other direction: the migration must not have widened anything either. A Stack and a
+    // Card are allowed, and they stay allowed with their markers unchanged.
+    underContract(
+      <ThemeProvider>
+        <DetailPage title="Record 1" parents={[{ label: "Records", to: "/records" }]}>
+          <Card title="A section">body</Card>
+          <Stack>
+            <ThemeToggle variant="stacked" />
+          </Stack>
+        </DetailPage>
+      </ThemeProvider>,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    // And the toggle really did render, or this asserts nothing.
+    expect(document.querySelector('[data-terp="theme-toggle"]')).not.toBeNull();
+    // Nested inside an allowed container is sanctioned composition — the check reads direct
+    // children only, which is what makes a marked root safe to put anywhere below one.
+    expect(screen.queryByTestId("refused")).toBeNull();
+  });
+});

package/src/locale.tsx

@@ -218,8 +218,28 @@ export function LanguageSwitcher({ variant = "stacked" }: LanguageSwitcherProps)
   if (context === null || context.locales.length < 2) {
     return null;
   }
+  // Hoisted out of the attribute rather than inlined as `variant === "inline"`, and not for
+  // readability: the marker inventory scanner reads every string literal inside a
+  // `data-terp={…}` expression as a marker, so the comparison's own "inline" was picked up as
+  // a component marker that nothing styles. Keep marker expressions to marker literals.
+  const isInline = variant === "inline";
   const menu = (
-    <Menu trigger={<Icon name="globe" size="1.15rem" />} triggerLabel={strings.language}>
+    <Menu
+      // Claim the root ONLY when this Menu is the root, which is the inline variant. The
+      // stacked variant renders its own div and puts the menu inside it, so stamping the
+      // same marker unconditionally put it on BOTH elements — and the inner wrapper then
+      // matched the stacked grid rule instead of the popover wrapper's geometry. The
+      // baselines did not catch that: a one-child grid and a one-child inline-flex box
+      // shrink-wrap to the same pixels, so it was wrong and invisible at the same time.
+      data-terp={isInline ? "language-switcher" : undefined}
+      data-variant={isInline ? "inline" : undefined}
+      // Unconditional, unlike the root marker: the panel is the same panel in both variants, so
+      // a rule for it must reach both. Deriving the owner from the conditional root marker made
+      // this panel "language-switcher" when inline and "popover" when stacked.
+      data-owner="language-switcher"
+      trigger={<Icon name="globe" size="1.15rem" />}
+      triggerLabel={strings.language}
+    >
       {({ close }) => (
         <>
           {context.locales.map((code) => (
@@ -237,12 +257,12 @@ export function LanguageSwitcher({ variant = "stacked" }: LanguageSwitcherProps)
       )}
     </Menu>
   );
-  if (variant === "inline") {
+  if (isInline) {
     return menu;
   }
   return (
-    <div style={{ display: "grid", justifyItems: "start", gap: "var(--space-1)", fontSize: "var(--font-size-sm)" }}>
-      <span style={{ color: "var(--color-neutral-600)" }}>{strings.language}</span>
+    <div data-terp="language-switcher" data-variant="stacked">
+      <span data-terp="language-switcher-label">{strings.language}</span>
       {menu}
     </div>
   );

package/src/markers.test.ts

@@ -21,6 +21,8 @@ import { describe, expect, it } from "vitest";
 //
 // The ambient `ImportMeta.glob` type lives in raw.d.ts, shared with the other scanning tests.
 
+import manifest from "../package.json";
+
 const sources = import.meta.glob("./**/*.{ts,tsx}", {
   query: "?raw",
   import: "default",
@@ -38,50 +40,164 @@ const STYLESHEET = "./styles.ts";
  */
 const MARKERS = [
   "alert",
+  "alert-body",
+  "alert-icon",
+  "alert-title",
+  "appshell",
+  "appshell-backdrop",
   "appshell-brand",
+  "appshell-brand-row",
+  "appshell-brand-title",
+  "appshell-column",
+  "appshell-footer",
+  "appshell-header",
+  "appshell-header-group",
+  "appshell-main",
   "appshell-nav",
+  "appshell-nav-label",
+  "appshell-nav-list",
+  "appshell-sidebar",
   "badge",
   "breadcrumbs",
+  "breadcrumbs-current",
+  "breadcrumbs-separator",
   "button",
+  "button-icon",
+  "calendar",
+  "calendar-day",
+  "calendar-grid",
+  "calendar-header",
+  "calendar-title",
+  "calendar-week",
+  "calendar-weekday",
   "card",
   "card-actions",
+  "card-description",
   "card-header",
+  "card-heading",
+  "card-title",
   "checkbox",
+  "combobox",
+  "combobox-empty",
+  "combobox-field",
+  "combobox-list",
+  "combobox-option",
+  "control-label",
   "dataview",
+  "dataview-actions-cell",
   "dataview-card",
+  "dataview-card-body",
+  "dataview-card-expanded",
+  "dataview-card-fields",
+  "dataview-card-heading",
+  "dataview-card-list",
+  "dataview-card-main",
+  "dataview-card-meta",
+  "dataview-card-status",
+  "dataview-card-title",
+  "dataview-column-option",
+  "dataview-column-resizer",
+  "dataview-column-settings",
+  "dataview-column-settings-title",
+  "dataview-column-sort",
+  "dataview-error",
+  "dataview-expand-cell",
+  "dataview-expanded-cell",
+  "dataview-inline-action",
+  "dataview-pager",
+  "dataview-pagination",
   "dataview-row",
+  "dataview-row-actions",
   "dataview-row-open",
+  "dataview-scroll",
+  "dataview-select-cell",
+  "dataview-skeleton",
   "dataview-table",
   "dataview-toolbar",
+  "dataview-toolbar-actions",
+  "dataview-toolbar-count",
+  "dataview-toolbar-layout",
+  "dataview-toolbar-search",
+  "dataview-toolbar-spacer",
+  "dataview-toolbar-status",
   "detail-list",
+  "detail-list-term",
+  "detail-list-value",
   "dialog",
+  "dialog-actions",
+  "dialog-body",
+  "dialog-description",
+  "dialog-title",
   "drawer-focus-end",
   "drawer-focus-start",
   "empty-state",
+  "empty-state-description",
+  "empty-state-icon",
+  "empty-state-title",
   "error-state",
+  "error-state-description",
+  "error-state-icon",
+  "error-state-title",
+  "field",
+  "field-error",
+  "field-hint",
+  "field-label",
+  "field-label-text",
   "hubcard",
   "hubcard-body",
   "hubcard-description",
+  "hubcard-heading",
+  "hubcard-icon",
   "hubcard-link",
   "hubcard-stat",
   "hubcard-title",
+  "hubpage-grid",
+  "icon",
   "iconbutton",
   "input",
+  "language-switcher",
+  "language-switcher-label",
   "loading-state",
+  "loading-state-spinner",
+  "markdown",
   "menu",
   "menu-item",
+  "menu-item-check",
+  "menu-item-icon",
+  "menu-trigger",
   "module-nav",
   "nav-icon",
+  "nav-icon-fallback",
+  "page-actions",
   "popover",
   "popover-panel",
   "radio",
+  "radio-group",
+  "radio-group-legend",
+  "radio-group-options",
   "resource-list",
   "spinner-ring",
   "stack",
   "switch",
   "tab",
+  "tab-list",
+  "tab-panel",
   "tabs",
+  "theme-toggle",
+  "theme-toggle-label",
+  "toast",
+  "toast-body",
+  "toast-icon",
+  "toast-title",
+  "toast-viewport",
   "tooltip",
+  "tooltip-anchor",
+  "user-menu",
+  "user-menu-avatar",
+  "user-menu-email",
+  "user-menu-header",
+  "user-menu-identity",
+  "user-menu-role",
 ];
 
 /**
@@ -98,35 +214,92 @@ const MARKERS = [
  * the reason splits into two shapes worth knowing before the styling migration is planned:
  *
  *   - **Delegates its root.** `theme.tsx` (ThemeToggle) and `locale.tsx` (LanguageSwitcher)
- *     return a bare `Menu` in their `inline` variant — the variant the app shell header
- *     actually uses — so their root already carries `data-terp="menu"` and is
- *     indistinguishable from any other menu. `UserMenu` is the same shape. Marking them
- *     means either threading a marker through `Menu` or introducing a wrapper element.
- *   - **Returns a fragment.** `Markdown` emits a sequence of block elements with no root at
- *     all. A marker requires a wrapper, and a wrapper is a new block box in every consumer's
- *     layout.
+ *     returned a bare `Menu` in their `inline` variant — the variant the app shell header
+ *     actually uses — so their root was `Popover`'s wrapper and indistinguishable from any
+ *     other popover. Both have graduated, and the answer added no DOM: `Popover` takes the
+ *     root's marker as a prop named `data-terp`, `Menu` threads it through, and each
+ *     component names its own root with `data-variant` separating the variants. `UserMenu` was
+ *     the same shape and has graduated too — it was also the last consumer of `Menu`'s
+ *     `triggerStyle` and `panelStyle` props, which are gone: a marked root makes the trigger
+ *     reachable by descending from it, and the PANEL, which is portalled to `document.body`
+ *     and so reachable from nowhere, carries a `data-owner` attribute naming whose panel it
+ *     is.
+ *
+ *     The prop is named for the attribute deliberately. The scanner below reads `data-terp`
+ *     sites in component source, so `<Menu data-terp="theme-toggle">` is seen exactly where
+ *     it looks; a `rootMarker` prop would have put the only mention of the name somewhere the
+ *     scanner never looks, and a marker rendered by nobody's `data-terp` site is precisely
+ *     the blind spot this file exists to close.
+ *   - **Returned a fragment.** `Markdown` emitted a sequence of block elements with no root at
+ *     all, and the objection to marking it was that a wrapper is a new block box in every
+ *     consumer's layout. It has graduated, and that objection turned out to be answerable
+ *     rather than true: the wrapper is `display: contents`, which generates no box, so the
+ *     blocks stay in-flow siblings and become real flex or grid items of any parent that
+ *     spaces its children with `gap`. Zero diff by construction — and a prose-rhythm block
+ *     wrapper remains a later, deliberate change rather than a side effect of marking.
  *
  * Both are styling decisions with visible consequences, not bookkeeping, so they belong to
- * the migration itself rather than to preparation for it. The archetypes, `Field`,
- * `PageActions` and the DataView internals are still unexamined.
+ * the migration itself rather than to preparation for it. The archetypes and the DataView
+ * internals are still unexamined.
+ *
+ * `PageActions` has graduated, and it was the easiest of the shapes above: it already rendered
+ * a real root of its own, so the marker landed on an element that existed and no DOM moved.
+ * Note the one thing it does that a rule cannot — it returns `null` when it has no actions at
+ * all, so its presence is conditional rather than styled, and `:empty` is not a substitute.
+ *
+ * `files.tsx` has left the list without gaining a marker, which is the one exit this ratchet
+ * allows that is not a migration: it turned out to have no styled surface. Its single
+ * declaration was `display: none` on the file picker's hidden plumbing input — the visible
+ * control is a `Button` — and that element is now `hidden`, the attribute HTML provides for
+ * exactly this. A marker plus a `display: none` rule would have put a component with no visual
+ * design into the sheet and offered an app the chance to un-hide it.
+ *
+ * Worth knowing about the shape of this list, because it flatters two files: it names files
+ * with NO marker at all, so one marker on one element exempts the rest of the file. `toast.tsx`
+ * and `ConfirmDialog.tsx` were never on it despite styling five and four unreachable elements
+ * respectively, because each rendered one `iconbutton` or one `dialog`. Both have since
+ * migrated; the gap in the ratchet has not.
+ *
+ * `Field` has graduated: it renders a root plus label, label text, hint and error markers,
+ * so each part of a form field is addressable from the sheet.
  */
 const UNMARKED_STYLED_SURFACES = [
   "./DetailPage.tsx",
-  "./Field.tsx",
   "./LoginView.tsx",
   "./OverviewPage.tsx",
-  "./PageActions.tsx",
   "./ProfileView.tsx",
-  "./UserMenu.tsx",
-  "./dataview/DataViewColumnSettings.tsx",
-  "./dataview/DataViewExpandableRow.tsx",
-  "./dataview/DataViewRowActions.tsx",
-  "./files.tsx",
-  "./locale.tsx",
-  "./theme.tsx",
-  "./ui/Markdown.tsx",
 ];
 
+/**
+ * How many module-scope base style objects each file still declares — the migration's own
+ * measurable, as a ratchet.
+ *
+ * This exists because `UNMARKED_STYLED_SURFACES` above flatters a file: it lists modules with
+ * NO `data-terp` at all, so a single marker on a single element exempts everything else in the
+ * file. `toast.tsx` and `ConfirmDialog.tsx` were never on that list while styling five and four
+ * unreachable elements respectively, because each rendered one `iconbutton` or one `dialog`.
+ * Both have migrated, and the gap had not — until this.
+ *
+ * Counted per file rather than as a set of filenames, so a PARTIAL migration shows: moving half
+ * of `AppShell`'s twenty-two objects into the sheet has to update the number here. Asserted as
+ * exact equality, which makes it a ratchet in both directions — a new base style object fails,
+ * and a removed one fails until the ledger is corrected. That is the same bargain `MARKERS`
+ * strikes, and it is the point: the number is meant to be read during review.
+ *
+ * What is deliberately NOT counted: a measured value passed inline at a call site. `Icon` sizes
+ * its box from a prop that takes any CSS length, `Stack` passes `align` / `justify` through, and
+ * `Popover` positions its panel from a rect it measured — ADR 0094 §3 puts all three on the
+ * inline side of the line permanently, so counting them would make this list unable to reach
+ * zero and therefore unable to mean anything.
+ */
+const INLINE_BASE_STYLES: Record<string, number> = {
+  "./LoginView.tsx": 9,
+  "./ModuleNav.tsx": 4,
+  "./Page.tsx": 5,
+  "./ProfileView.tsx": 3,
+  "./ResourceList.tsx": 2,
+};
+
 /**
  * `text` with comments removed, so prose naming a marker cannot stand in for rendering one.
  *
@@ -144,6 +317,13 @@ function stripComments(text: string) {
  *
  * A regex anchored to `data-terp="…"` alone misses the conditional form — which is how the
  * DataView row markers are written — so renaming one of those would not fail anything.
+ *
+ * The cost of reading a whole expression is that EVERY string literal inside one counts as a
+ * marker. `data-terp={variant === "inline" ? "theme-toggle" : undefined}` reports both
+ * `inline` and `theme-toggle`, and the first is not a marker at all. That is caught rather
+ * than tolerated — the inventory assertion fails on the phantom name — and the fix is to keep
+ * a marker expression to marker literals by hoisting the comparison out. Worth knowing before
+ * writing a conditional marker, because the failure names a marker nobody added.
  */
 function markersIn(text: string) {
   const source = stripComments(text);
@@ -242,4 +422,47 @@ describe("data-terp markers", () => {
       "the worklist must stay sorted and duplicate-free",
     ).toEqual([...new Set(UNMARKED_STYLED_SURFACES)].sort());
   });
+  it("keeps the inline base-style ledger honest, file by file", () => {
+    // The migration's measurable, gated. A base style object is a module-scope CSSProperties
+    // literal or factory — the shape a component uses to style its own root, and the shape the
+    // sheet replaces. Comments are stripped first so prose naming the type cannot count.
+    const declared: Record<string, number> = {};
+    for (const [file, text] of production) {
+      const matches = stripComments(text).match(/CSSProperties\s*(?:=\s*\{|=>\s*\()/g);
+      if (matches !== null) {
+        declared[file] = matches.length;
+      }
+    }
+    expect(declared).toEqual(INLINE_BASE_STYLES);
+  });
+
+  it("injects the sheet from every module that owns a rule, or is reachable from one that does", () => {
+    // Twelve marker-rendering modules never call injectTerpStyles and do not need to: the
+    // package publishes ONE entry point and declares no `sideEffects`, so importing anything
+    // from it loads every module and two dozen of them inject. That guarantee is a packaging
+    // property, and nothing asserted it — a `sideEffects: false` added for bundle size, plus
+    // tree-shaking, would remove it silently and the first symptom would be Markdown's blocks
+    // collapsing into one grid item. So the property itself is what this pins.
+    expect(Object.keys(manifest.exports)).toEqual(["."]);
+    expect(manifest.exports["."]).toBe("./src/index.ts");
+    expect(
+      "sideEffects" in manifest,
+      "declaring sideEffects would let a bundler drop the modules that inject the stylesheet",
+    ).toBe(false);
+    // And the sheet has many independent injectors reachable from that entry, or the packaging
+    // properties above prove nothing on their own. The entry does NOT re-export ./styles — the
+    // injection is a module side effect of the components themselves, which is exactly why the
+    // sideEffects assertion is the one that matters.
+    const injectors = production.filter(([, text]) =>
+      stripComments(text).includes("injectTerpStyles()"),
+    );
+    expect(injectors.length).toBeGreaterThan(20);
+    const index = sources["./index.ts"] ?? "";
+    for (const [file] of injectors.slice(0, 3)) {
+      const module = file.replace(/^\.\//, "./").replace(/\.tsx?$/, "");
+      expect(index, `${file} injects the sheet but is not reachable from the entry point`).toContain(
+        `from "${module}"`,
+      );
+    }
+  });
 });

package/src/router.tsx

@@ -265,18 +265,15 @@ export function buildAppRouter(
         logo={options.logo}
         footer={options.footer}
         nav={nav}
-        renderBrandLink={({ to, children, style }) => (
-          <Link to={to} data-terp="appshell-brand" style={style}>
+        renderBrandLink={({ to, children }) => (
+          <Link to={to} data-terp="appshell-brand">
             {children}
           </Link>
         )}
-        renderLink={(item, children, context) => (
-          <Link
-            to={item.to}
-            style={context.style}
-            activeProps={{ style: { ...context.style, ...context.activeStyle } }}
-            activeOptions={{ exact: item.to === "/" }}
-          >
+        // No style objects and no activeProps: the shell's stylesheet owns the link
+        // geometry and keys the active route on aria-current="page", which Link sets.
+        renderLink={(item, children) => (
+          <Link to={item.to} activeOptions={{ exact: item.to === "/" }}>
             {children}
           </Link>
         )}

package/src/ssr.test.tsx

@@ -24,9 +24,7 @@ describe("server rendering", () => {
       <AppShell
         title="Terp"
         nav={[{ label: "Home", to: "/", icon: "home" }]}
-        renderLink={(item, children, context) => (
-          <a href={item.to} style={context.style}>{children}</a>
-        )}
+        renderLink={(item, children) => <a href={item.to}>{children}</a>}
       >
         <p>content</p>
       </AppShell>,