@terpjs/react-core 0.8.0 → 0.10.0

package/src/markers.test.ts

@@ -39,6 +39,8 @@ const STYLESHEET = "./styles.ts";
  * stylesheet and the layout contract, so it belongs in a release note.
  */
 const MARKERS = [
+  "admin-form",
+  "admin-section-title",
   "alert",
   "alert-body",
   "alert-icon",
@@ -53,10 +55,15 @@ const MARKERS = [
   "appshell-header",
   "appshell-header-group",
   "appshell-main",
+  "appshell-mark",
   "appshell-nav",
+  "appshell-nav-group",
+  "appshell-nav-group-label",
   "appshell-nav-label",
   "appshell-nav-list",
   "appshell-sidebar",
+  "appshell-skip-link",
+  "avatar",
   "badge",
   "breadcrumbs",
   "breadcrumbs-current",
@@ -77,6 +84,8 @@ const MARKERS = [
   "card-heading",
   "card-title",
   "checkbox",
+  "code",
+  "code-block",
   "combobox",
   "combobox-empty",
   "combobox-field",
@@ -121,6 +130,7 @@ const MARKERS = [
   "dataview-toolbar-spacer",
   "dataview-toolbar-status",
   "detail-list",
+  "detail-list-row",
   "detail-list-term",
   "detail-list-value",
   "dialog",
@@ -128,6 +138,7 @@ const MARKERS = [
   "dialog-body",
   "dialog-description",
   "dialog-title",
+  "divider",
   "drawer-focus-end",
   "drawer-focus-start",
   "empty-state",
@@ -143,6 +154,8 @@ const MARKERS = [
   "field-hint",
   "field-label",
   "field-label-text",
+  "grid",
+  "heading",
   "hubcard",
   "hubcard-body",
   "hubcard-description",
@@ -155,10 +168,21 @@ const MARKERS = [
   "icon",
   "iconbutton",
   "input",
+  "input-password",
   "language-switcher",
   "language-switcher-label",
+  "link",
   "loading-state",
   "loading-state-spinner",
+  "login-brand",
+  "login-card",
+  "login-error",
+  "login-form",
+  "login-separator",
+  "login-separator-rule",
+  "login-sso",
+  "login-title",
+  "login-view",
   "markdown",
   "menu",
   "menu-item",
@@ -166,23 +190,41 @@ const MARKERS = [
   "menu-item-icon",
   "menu-trigger",
   "module-nav",
+  "module-nav-link",
+  "module-nav-list",
   "nav-icon",
   "nav-icon-fallback",
+  "page",
   "page-actions",
+  "page-breadcrumbs",
+  "page-header",
+  "page-heading",
+  "page-title",
   "popover",
   "popover-panel",
+  "profile-card",
+  "profile-email",
+  "profile-role",
   "radio",
   "radio-group",
   "radio-group-legend",
   "radio-group-options",
   "resource-list",
+  "resource-list-create",
+  "resource-list-empty",
+  "resource-list-error",
+  "resource-list-items",
+  "resource-list-row",
   "spinner-ring",
+  "splitpage-panes",
+  "splitpane",
   "stack",
   "switch",
   "tab",
   "tab-list",
   "tab-panel",
   "tabs",
+  "text",
   "theme-toggle",
   "theme-toggle-label",
   "toast",
@@ -193,7 +235,6 @@ const MARKERS = [
   "tooltip",
   "tooltip-anchor",
   "user-menu",
-  "user-menu-avatar",
   "user-menu-email",
   "user-menu-header",
   "user-menu-identity",
@@ -254,6 +295,17 @@ const MARKERS = [
  * 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.
  *
+ * `DetailPage` and `OverviewPage` have left the same way, and they were on this list by
+ * mistake rather than by migration: each is a `LayoutSlotContext.Provider` wrapped around
+ * `Page` and renders no element of its own at all, so they are view compositions — which the
+ * paragraph above already excludes. There is nothing to mark without inventing a box, and the
+ * box is the one thing that must not exist here: `Page`'s slot check reads `article.children`,
+ * so a wrapper around the body — `display: contents` included, since that check is a DOM
+ * traversal and the node is still in the collection — becomes the sole body-slot child, is in
+ * no allow table, and fails every governed page closed. Their archetype identity is a context
+ * value, which is the right place for it: `Page` renders the only box either of them has, and
+ * it is marked.
+ *
  * 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
@@ -262,13 +314,14 @@ const MARKERS = [
  *
  * `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.
+ *
+ * THE LIST IS EMPTY. `LoginView` was the last entry, and it is kept rather than deleted for
+ * the same reason as the ledger below: this is where a new unmarked styled surface has to
+ * argue for itself. Note what an empty list does NOT say, because the shape above already
+ * flatters two files — it names modules with NO marker at all, so one marker anywhere in a
+ * file exempts the rest of it.
  */
-const UNMARKED_STYLED_SURFACES = [
-  "./DetailPage.tsx",
-  "./LoginView.tsx",
-  "./OverviewPage.tsx",
-  "./ProfileView.tsx",
-];
+const UNMARKED_STYLED_SURFACES: string[] = [];
 
 /**
  * How many module-scope base style objects each file still declares — the migration's own
@@ -291,13 +344,64 @@ const UNMARKED_STYLED_SURFACES = [
  * `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.
+ *
+ * IT HAS REACHED ZERO, and the honest reading of that is narrow. The detector matches a
+ * module-scope declaration annotated `CSSProperties`, which means a call-site literal and an
+ * unannotated module-scope object are both invisible to it. Four of the built-in admin views
+ * carried five base styles through this entire migration for exactly that reason — four as
+ * call-site object literals (two of them the same `<h2>` declaration, two the same form
+ * measure) and one as an unannotated `payloadStyle` — while both ratchets read clean.
+ * The next commit widens the detector and migrates them, so that zero means what it looks
+ * like it means.
+ */
+const INLINE_BASE_STYLES: Record<string, number> = {};
+
+/**
+ * Every module that renders an inline `style={}` at all, and how many times.
+ *
+ * This closes the gap the ledger above leaves, and the gap was not theoretical. That one
+ * matches a module-scope declaration annotated `CSSProperties`, so a call-site literal and
+ * an unannotated module-scope object are both invisible to it — and four of the built-in
+ * admin views carried five base styles through the entire styling migration for exactly
+ * that reason, with both ratchets reading clean the whole time. Widening the annotation
+ * pattern would not have found them either. What finds them is counting the SITES.
+ *
+ * So this list is the complete one, and every entry has to be a value ADR 0094 §3 puts on
+ * the inline side permanently. There are only two such kinds, and a new entry is a claim
+ * that there is a third:
+ *
+ *   - A measured value the sheet has no business owning. `icons.tsx` and `LoadingState.tsx`
+ *     size a box from a prop taking any CSS length; `layout.tsx` passes Stack's `align` /
+ *     `justify`, an open vocabulary CSS already has; `ui/Popover.tsx` positions its panel
+ *     from a rect measured at runtime; `dataview/DataViewTable.tsx` carries a column's width
+ *     while it is being dragged.
+ *   - The caller's own `style` prop, forwarded to a root. `ui/Checkbox.tsx`, `ui/Radio.tsx`,
+ *     `ui/Switch.tsx` and `ui/Combobox.tsx` do this and nothing else — it is not the
+ *     component styling itself, it is the escape a framework component owes its caller, and
+ *     `ui/Button.test.tsx` asserts it keeps working.
+ *
+ * Exact equality in both directions, like the ledger above: a new site fails, and a removed
+ * one fails until this record is corrected. Comments are stripped first, because this file's
+ * own prose says `style={}` repeatedly and the measure is otherwise a grep of its own
+ * documentation.
+ *
+ * Counted with a regex rather than by splitting on the literal `style={`, and that is not
+ * tidying. JSX permits whitespace around the `=`, so `style = {{ … }}` and a value on the
+ * next line are both valid and both invisible to a literal split — either would have let a
+ * base style back in past a green gate, which is the exact failure this list exists to
+ * prevent. Verified: the two forms count 0 under the split and 1 under the regex, while
+ * every file above counts identically either way.
  */
-const INLINE_BASE_STYLES: Record<string, number> = {
-  "./LoginView.tsx": 9,
-  "./ModuleNav.tsx": 4,
-  "./Page.tsx": 5,
-  "./ProfileView.tsx": 3,
-  "./ResourceList.tsx": 2,
+const INLINE_STYLE_SITES: Record<string, number> = {
+  "./LoadingState.tsx": 1,
+  "./dataview/DataViewTable.tsx": 1,
+  "./icons.tsx": 1,
+  "./layout.tsx": 1,
+  "./ui/Checkbox.tsx": 1,
+  "./ui/Combobox.tsx": 1,
+  "./ui/Popover.tsx": 1,
+  "./ui/Radio.tsx": 1,
+  "./ui/Switch.tsx": 1,
 };
 
 /**
@@ -436,6 +540,21 @@ describe("data-terp markers", () => {
     expect(declared).toEqual(INLINE_BASE_STYLES);
   });
 
+  it("accounts for every inline style site, not only the annotated ones", () => {
+    // The measure the admin views escaped. A base style declared as a call-site literal, or
+    // as a module-scope object nobody annotated, is a base style either way — and the ledger
+    // above cannot see either. This one counts sites, so the only way to stay out of it is to
+    // render no inline style at all.
+    const sites: Record<string, number> = {};
+    for (const [file, text] of production) {
+      const count = stripComments(text).match(/style\s*=\s*\{/g)?.length ?? 0;
+      if (count > 0) {
+        sites[file] = count;
+      }
+    }
+    expect(sites).toEqual(INLINE_STYLE_SITES);
+  });
+
   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
@@ -443,8 +562,15 @@ describe("data-terp markers", () => {
     // 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");
+    // One CODE entry point, which is the property. Data subpaths are allowed and do not
+    // weaken it: `./layout.manifest.json` is JSON a tool reads out of node_modules, no module
+    // imports it, and importing JSON loads no JavaScript at all — so there is still exactly one
+    // way into this package's modules. Asserted by extension rather than by key count, so that
+    // publishing a second entry point is what fails and publishing another data file is not.
+    const codeEntries = Object.entries(manifest.exports).filter(([, target]) =>
+      /\.(ts|tsx|js|mjs|cjs)$/.test(target),
+    );
+    expect(codeEntries).toEqual([[".", "./src/index.ts"]]);
     expect(
       "sideEffects" in manifest,
       "declaring sideEffects would let a bundler drop the modules that inject the stylesheet",

package/src/nav.test.ts

@@ -1,21 +1,251 @@
 import { describe, expect, it } from "vitest";
 import type { ModuleManifest } from "@terpjs/contract";
 
-import { visibleNav } from "./nav";
+import { groupNav, isDeclarationVisible, visibleNav } from "./nav";
+import type { NavVisibilityContext } from "./nav";
 
 const manifests: ModuleManifest[] = [
   { name: "notes", routes: [], nav: [{ label: "Notes", to: "/notes" }] },
   { name: "admin", routes: [], nav: [{ label: "Users", to: "/users", role: "admin" }] },
+  {
+    name: "billing",
+    routes: [],
+    nav: [{ label: "Export", to: "/export", permission: "billing.export" }],
+  },
+  {
+    name: "audit",
+    // Both gates on one item, which is the case the AND exists for.
+    routes: [],
+    nav: [{ label: "Audit", to: "/audit", role: "admin", permission: "audit.read" }],
+  },
   { name: "noNav", routes: [] },
 ];
 
+/** A context that says yes to everything, so each test can deny exactly one thing. */
+function allowAll(overrides: Partial<NavVisibilityContext> = {}): NavVisibilityContext {
+  return {
+    canSeeRole: () => true,
+    permissions: ["billing.export", "audit.read"],
+    ...overrides,
+  };
+}
+
 describe("visibleNav", () => {
   it("flattens nav across manifests when everything is visible", () => {
-    expect(visibleNav(manifests, () => true).map((i) => i.to)).toEqual(["/notes", "/users"]);
+    expect(visibleNav(manifests, allowAll()).map((i) => i.to)).toEqual([
+      "/notes",
+      "/users",
+      "/export",
+      "/audit",
+    ]);
   });
 
   it("filters items by their required role", () => {
-    const onlyPublic = visibleNav(manifests, (role) => role === undefined);
-    expect(onlyPublic.map((i) => i.to)).toEqual(["/notes"]);
+    const onlyPublic = visibleNav(manifests, allowAll({ canSeeRole: (role) => role === undefined }));
+    // /export declares no role, so the role gate lets it through; /audit declares both.
+    expect(onlyPublic.map((i) => i.to)).toEqual(["/notes", "/export"]);
+  });
+
+  it("filters items by their required permission", () => {
+    const noGrants = visibleNav(manifests, allowAll({ permissions: [] }));
+    expect(noGrants.map((i) => i.to)).toEqual(["/notes", "/users"]);
+  });
+});
+
+describe("isDeclarationVisible", () => {
+  it("requires BOTH gates when an item declares both", () => {
+    // The composition, stated as a truth table. Either alone is not enough, which is what the
+    // server does: a Policy carrying a Permission enforces the permission's role floor AND the
+    // grant. A client checking one would disagree with the endpoint in one direction or another.
+    const both = { role: "admin", permission: "audit.read" };
+    expect(isDeclarationVisible(both, allowAll())).toBe(true);
+    expect(isDeclarationVisible(both, allowAll({ canSeeRole: () => false }))).toBe(false);
+    expect(isDeclarationVisible(both, allowAll({ permissions: [] }))).toBe(false);
+    expect(
+      isDeclarationVisible(both, { canSeeRole: () => false, permissions: [] }),
+    ).toBe(false);
+  });
+
+  it("is unchanged for a declaration that names neither gate", () => {
+    // The additivity claim. Nothing an existing manifest declares moves, because a missing
+    // permission short-circuits to true and `role` keeps its exact meaning.
+    expect(isDeclarationVisible({}, allowAll({ permissions: [] }))).toBe(true);
+    expect(isDeclarationVisible({}, allowAll({ canSeeRole: () => false }))).toBe(false);
+  });
+
+  it("fails closed on a permission nobody granted", () => {
+    // Three ways in, one outcome. A misspelled name is indistinguishable from an ungranted one,
+    // and that is correct: both mean "the server would refuse this".
+    expect(isDeclarationVisible({ permission: "billing.exprot" }, allowAll())).toBe(false);
+    // An app that mounts no grant capability has an empty list — which must hide the item, not
+    // wave it through. This is the branch a "treat empty as unrestricted" shortcut would break.
+    expect(isDeclarationVisible({ permission: "billing.export" }, allowAll({ permissions: [] }))).toBe(
+      false,
+    );
+    // Signed out: `canSeeRole` already answers false for a null rank, before permissions matter.
+    expect(
+      isDeclarationVisible({ permission: "billing.export" }, {
+        canSeeRole: () => false,
+        permissions: ["billing.export"],
+      }),
+    ).toBe(false);
+  });
+});
+
+// `groupNav` — the app's declared groups meeting the modules' declared items.
+//
+// Every row below names the mutation that turns it red, because two of this phase's earlier
+// gates could not fail and were only found by trying. Two are worth reading before adding a row
+// here. "Sorts stably" cannot be falsified by DELETING the sort: `Array.prototype.sort` is stable
+// by specification, so a tied array comes out in declaration order whether or not it was sorted,
+// and the assertion passes over the mutant. The comparator that does reorder ties is
+// `(a, b) => ((a.order ?? 0) - (b.order ?? 0)) || -1`, which was measured in this repo's node to
+// fully reverse a tied array at every length from 2 upward. And "sorts" is only falsifiable
+// against `?? Infinity` if the fixture carries a POSITIVE order beside an absent one — with only
+// negatives and absents the two rules agree.
+describe("groupNav", () => {
+  const items = (...tos: string[]) => tos.map((to) => ({ label: to, to }));
+  const tos = (sections: ReturnType<typeof groupNav>) =>
+    sections.map((section) => section.items.map((item) => item.to));
+  /** Section identity and heading, without the items — asserted separately via `tos`. */
+  const shape = (sections: ReturnType<typeof groupNav>) =>
+    sections.map((section) => ({ id: section.id, label: section.label }));
+
+  it("renders one unlabelled section when the app declares no groups", () => {
+    // The additivity claim, as a test rather than an argument: same items, same order, one
+    // section that renders no heading. Mutation: `return [{ id: "default", label: "", items }]`,
+    // which falsifies the null id and the null label together.
+    expect(groupNav(items("/a", "/b", "/c"))).toEqual([
+      { id: null, label: null, items: items("/a", "/b", "/c") },
+    ]);
+  });
+
+  it("emits the ungrouped bucket last, after every declared group", () => {
+    // The rule that changed under review. The packaged admin entry carries no `group` and no app
+    // can give it one, so a first-emitted default bucket would hoist it to the top of the sidebar
+    // the moment an app declared its first group. Mutation: emit the ungrouped section first.
+    const sections = groupNav(
+      [
+        { label: "Loose", to: "/loose" },
+        { label: "Sales", to: "/sales", group: "work" },
+      ],
+      [{ id: "work", label: "Werkruimte" }],
+    );
+    expect(sections.map((section) => section.id)).toEqual(["work", null]);
+    expect(tos(sections)).toEqual([["/sales"], ["/loose"]]);
+  });
+
+  it("drops a group left empty rather than rendering a label over nothing", () => {
+    // Reachable on a first render: a group holding only the role-gated `/admin` entry is empty
+    // for everyone who is not an admin, because `visibleNav` has already removed it.
+    // Mutation: push the section regardless of `bucket.length`.
+    const sections = groupNav(items("/a"), [
+      { id: "empty", label: "Beheer" },
+      { id: "used", label: "Werk" },
+    ]);
+    expect(sections.map((section) => section.id)).toEqual([null]);
+    expect(sections.some((section) => section.label === "Beheer")).toBe(false);
+  });
+
+  it("falls an item naming an undeclared group open into the ungrouped bucket", () => {
+    // A module ships before the app declares its group; the link must still be reachable.
+    // Mutation: drop the `declared.has(item.group)` half of the key expression, and the item
+    // lands in a bucket nothing reads — it vanishes from the sidebar with nothing reporting it.
+    const sections = groupNav(
+      [{ label: "Orphan", to: "/orphan", group: "not-declared" }],
+      [{ id: "work", label: "Werkruimte" }],
+    );
+    expect(tos(sections)).toEqual([["/orphan"]]);
+    expect(sections[0]!.id).toBeNull();
+  });
+
+  it("sorts items on order, treating absent as 0", () => {
+    // Mutation: `order ?? Infinity`, which sends both unordered items to the end and yields
+    // /up, /down, /a, /b. The POSITIVE order is what makes the two rules disagree.
+    const sections = groupNav([
+      { label: "down", to: "/down", order: 1 },
+      { label: "a", to: "/a" },
+      { label: "up", to: "/up", order: -1 },
+      { label: "b", to: "/b" },
+    ]);
+    expect(tos(sections)).toEqual([["/up", "/a", "/b", "/down"]]);
+  });
+
+  it("keeps tied items in declaration order", () => {
+    // Mutation: `((a.order ?? 0) - (b.order ?? 0)) || -1` — measured to reverse a tied array at
+    // every length from 2 up. Deleting the sort does NOT falsify this, which is the point.
+    expect(tos(groupNav(items("/first", "/second", "/third")))).toEqual([
+      ["/first", "/second", "/third"],
+    ]);
+  });
+
+  it("sorts groups on order, treating absent as 0", () => {
+    // Same shape one level up, and the same `?? Infinity` mutation.
+    const sections = groupNav(
+      [
+        { label: "d", to: "/d", group: "down" },
+        { label: "p", to: "/p", group: "plain" },
+        { label: "u", to: "/u", group: "up" },
+      ],
+      [
+        { id: "down", label: "Down", order: 1 },
+        { id: "plain", label: "Plain" },
+        { id: "up", label: "Up", order: -1 },
+      ],
+    );
+    expect(sections.map((section) => section.id)).toEqual(["up", "plain", "down"]);
+  });
+
+  it("keeps tied groups in declaration order", () => {
+    const sections = groupNav(
+      [
+        { label: "a", to: "/a", group: "one" },
+        { label: "b", to: "/b", group: "two" },
+        { label: "c", to: "/c", group: "three" },
+      ],
+      [
+        { id: "one", label: "One" },
+        { id: "two", label: "Two" },
+        { id: "three", label: "Three" },
+      ],
+    );
+    expect(sections.map((section) => section.id)).toEqual(["one", "two", "three"]);
+  });
+
+  it("lets the first declaration of a duplicated id win, without duplicating its items", () => {
+    // `groupNav` stays total so a render can never throw; `buildAppRouter` refuses the duplicate
+    // at composition time instead. Mutation: drop the `declared.has` guard on insertion, and the
+    // second declaration overwrites the first, so the label becomes "Second".
+    const sections = groupNav([{ label: "a", to: "/a", group: "dup" }], [
+      { id: "dup", label: "First" },
+      { id: "dup", label: "Second" },
+    ]);
+    expect(shape(sections)).toEqual([{ id: "dup", label: "First" }]);
+    expect(tos(sections)).toEqual([["/a"]]);
+  });
+
+  it("treats the empty string as a real group id, not as the ungrouped bucket", () => {
+    // The default bucket is keyed on `null` rather than on a falsy sentinel precisely so that
+    // `id: ""` — a legal string — stays a group of its own. Mutation: key the bucket on `""`,
+    // and this item's group merges into the ungrouped section and loses its label.
+    const sections = groupNav([{ label: "a", to: "/a", group: "" }], [{ id: "", label: "Blank" }]);
+    expect(shape(sections)).toEqual([{ id: "", label: "Blank" }]);
+    expect(tos(sections)).toEqual([["/a"]]);
+  });
+
+  it("renders a null-labelled group as pure positioning", () => {
+    // The escape an app uses to place its otherwise-ungrouped items somewhere other than last.
+    const sections = groupNav(
+      [
+        { label: "main", to: "/main", group: "main" },
+        { label: "loose", to: "/loose" },
+      ],
+      [{ id: "main", label: null }],
+    );
+    expect(shape(sections)).toEqual([
+      { id: "main", label: null },
+      { id: null, label: null },
+    ]);
+    expect(tos(sections)).toEqual([["/main"], ["/loose"]]);
   });
 });