@terpjs/react-core 0.9.0 → 0.10.0

package/src/layout.manifest.json

@@ -0,0 +1,118 @@
+{
+  "$comment": "The vocabulary of frontend/layout-contract.json as THIS release reads it — the standard's layout-declaration.schema.json with the per-stack value sets filled in. Published so a tool that edits an app's files can offer exactly the keys and values the app's own pinned framework will honour, rather than the ones the tool happens to know about; that inversion is the whole point, because an unknown key is refused at compose time rather than ignored. Hand-written rather than generated: every machine fact here — the keys at all three levels, the enums, the declared types, the emptiness floors, the required pair and the unknown-key refusals — mirrors a literal in layoutDeclaration.ts, themes.ts or layoutContract.ts, and layout.manifest.test.ts holds each of them to its source. The titles and descriptions are the part no generator could produce, and are held only to being present. The copy stays a copy, and the copy is checked.",
+  "title": "The app's layout declaration",
+  "description": "What this app declares once, in a file both its build-time checker and its running shell read. Every key is optional and an absent key is not a default: it is the app declining to declare, leaving whatever was already in force alone. Declaring a key here and passing the matching bootstrap option in code is refused when the router is composed.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "contract": {
+      "type": "string",
+      "minLength": 1,
+      "title": "Page contract",
+      "enum": [
+        "standard"
+      ],
+      "description": "Constrain every page archetype's body to the contract's own components, checked at lint time and again on the rendered page. Leaving it unset keeps archetype-only enforcement. Adopting one on an app that has none can turn a green build red, because it starts governing screens that were legal a moment earlier."
+    },
+    "defaultTheme": {
+      "type": "string",
+      "minLength": 1,
+      "title": "Starting palette",
+      "enum": [
+        "light",
+        "dark",
+        "midnight",
+        "twilight",
+        "contrast",
+        "system"
+      ],
+      "description": "The palette the app opens on, until a person picks another from the theme menu and for as long as they have not. \"system\" opens on whatever light or dark preference the viewer's own device reports."
+    },
+    "shell": {
+      "type": "object",
+      "additionalProperties": false,
+      "title": "Shell",
+      "description": "The frame around every page: how dense its controls are, where its navigation sits, how wide its content runs, and which groups that navigation is arranged into.",
+      "properties": {
+        "density": {
+          "type": "string",
+          "title": "Density",
+          "enum": [
+            "comfortable",
+            "compact"
+          ],
+          "description": "Control height and table cell padding for the whole app, from one attribute on the shell. Compact fits more rows on a screen; comfortable is easier to hit on a touch device."
+        },
+        "navPlacement": {
+          "type": "string",
+          "title": "Navigation placement",
+          "enum": [
+            "sidebar",
+            "header"
+          ],
+          "description": "Where the primary navigation sits on a wide screen: a full-height rail beside the content, or a row inside the header with no rail at all. On a narrow screen both become the same drawer."
+        },
+        "contentWidth": {
+          "type": "string",
+          "title": "Content width",
+          "enum": [
+            "full",
+            "measured"
+          ],
+          "description": "Whether a page's content runs the full width of the track or is capped at the shell's reading measure. Measured keeps long prose readable; full suits wide tables."
+        },
+        "brand": {
+          "type": "object",
+          "additionalProperties": false,
+          "title": "Brand mark",
+          "description": "The image your app is recognised by, shown beside its name in the header. Put the file in the app's frontend/public folder and name it here the way a browser would ask for it, starting with a slash.",
+          "properties": {
+            "logo": {
+              "type": "string",
+              "minLength": 1,
+              "title": "Mark",
+              "description": "The mark shown inside the app. It is sized to the header's own box, so a large file is scaled down rather than cut off."
+            },
+            "logoDark": {
+              "type": "string",
+              "minLength": 1,
+              "title": "Mark for dark palettes",
+              "description": "A second file for the dark palettes. Only worth setting when the first one has fixed colours that disappear on a dark background — most company marks do. Leave it empty and the same mark is used everywhere."
+            }
+          }
+        },
+        "navGroups": {
+          "type": "array",
+          "title": "Navigation groups",
+          "description": "The named sections the navigation is arranged into. A module's own navigation item points at one by id; an item naming a group that is not declared here is not an error, it simply lands in a trailing section with no heading. Declared here rather than on a module, because a group spans modules and no module can own one. Two groups may not share an id: every field of the second one is legal on its own, and the app still refuses to start.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "label"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "title": "Id",
+                "description": "What a module's navigation item names to join this group. Never shown to anyone, and no two groups may share one."
+              },
+              "label": {
+                "type": "string",
+                "title": "Heading",
+                "description": "The heading shown above this group's links. Leave it empty for a group that shows no heading at all — a way to place items somewhere other than the end without inventing a title for them."
+              },
+              "order": {
+                "type": "integer",
+                "title": "Position",
+                "description": "Where this group sits against its siblings, lowest first. Groups that share a position keep the order they are written in, so a list that is already in the right order needs no positions at all."
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/layout.manifest.test.ts

@@ -0,0 +1,205 @@
+import { readFileSync } from "node:fs";
+
+import { describe, expect, it } from "vitest";
+
+import { LAYOUT_CONTRACTS } from "./layoutContract";
+import {
+  BRAND_FIELDS,
+  NAV_GROUP_FIELDS,
+  NAV_GROUP_REQUIRED,
+  SHELL_STRUCTURED_KEYS,
+  SHELL_VALUES,
+  TOP_LEVEL_KEYS,
+} from "./layoutDeclaration";
+import { THEMES } from "./themes";
+
+// The published layout vocabulary against the module that enforces it.
+//
+// `layout.manifest.json` exists so that a tool editing an app's files can offer exactly the keys
+// and values THAT APP'S OWN pinned framework will honour. That inversion is the point: an unknown
+// key is refused when the router is composed, so a tool working from its own idea of the
+// vocabulary can hand an app a file its framework will not start on. Reading the vocabulary out
+// of the app's own node_modules removes the guess.
+//
+// Which makes every drift here a live defect rather than a tidiness problem, and both directions
+// fail differently:
+//
+//   * A key or value the resolver reads and the manifest omits is a choice no tool will ever
+//     offer — declarable, documented, and invisible to the audience the file was published for.
+//   * A key or value the manifest offers and the resolver does not read is worse: a tool writes
+//     it in good faith and the app refuses to start, naming a key the tool was told to use.
+//
+// The manifest is hand-written rather than generated, for the reason `theme.themes.test.ts` gives
+// about the theme union: generating it would need a TypeScript loader in a build step this package
+// does not have, and half its content — the titles and descriptions an operator reads — is not
+// derivable from the source at all. So the copy stays a copy, and the copy is checked.
+//
+// What "checked" covers, precisely, because an earlier version of this comment claimed more than
+// the assertions delivered: every key at all three levels, every enum, every declared type, every
+// emptiness floor, the required pair, the unknown-key refusals, and the export subpath. What it
+// does NOT cover is prose — a title or description is asserted present, never compared to
+// anything, because there is nothing to compare it to.
+
+interface ManifestProperty {
+  type?: string;
+  title?: string;
+  description?: string;
+  enum?: string[];
+  properties?: Record<string, ManifestProperty>;
+  items?: ManifestProperty;
+  required?: string[];
+  additionalProperties?: boolean;
+  minLength?: number;
+}
+
+const manifest: ManifestProperty = JSON.parse(
+  readFileSync(new URL("./layout.manifest.json", import.meta.url), "utf-8"),
+);
+
+const properties = manifest.properties ?? {};
+const shell = properties.shell?.properties ?? {};
+const group = shell.navGroups?.items?.properties ?? {};
+
+/** Every property in the document, by the path a refusal would name it with. */
+function everyProperty(): [string, ManifestProperty][] {
+  return [
+    ...Object.entries(properties).map(([key, value]): [string, ManifestProperty] => [key, value]),
+    ...Object.entries(shell).map(([key, value]): [string, ManifestProperty] => [
+      `shell.${key}`,
+      value,
+    ]),
+    ...Object.entries(group).map(([key, value]): [string, ManifestProperty] => [
+      `shell.navGroups.items.${key}`,
+      value,
+    ]),
+  ];
+}
+
+describe("the published layout vocabulary", () => {
+  it("reads the manifest it is asserting about", () => {
+    // Every assertion below compares against something parsed out of the file. A file that
+    // failed to parse into the expected shape would compare empty objects and report green,
+    // which is the one failure mode a parity test cannot afford.
+    expect(Object.keys(properties).length).toBeGreaterThan(2);
+    expect(Object.keys(shell).length).toBeGreaterThan(2);
+    expect(Object.keys(group).length).toBeGreaterThan(2);
+  });
+
+  it("offers exactly the keys the document admits", () => {
+    expect(Object.keys(properties).sort()).toEqual([...TOP_LEVEL_KEYS].sort());
+  });
+
+  it("offers exactly the keys the shell admits", () => {
+    const declared = [...Object.keys(SHELL_VALUES), ...SHELL_STRUCTURED_KEYS];
+    expect(Object.keys(shell).sort()).toEqual(declared.sort());
+  });
+
+  it("offers exactly the values each shell key accepts", () => {
+    for (const [key, values] of Object.entries(SHELL_VALUES)) {
+      expect(shell[key]?.enum, `shell.${key}`).toEqual([...values]);
+    }
+  });
+
+  it("offers every palette this release ships, and no other", () => {
+    // Including "system", which is a real thing to declare rather than the absence of one — an
+    // absent key leaves whatever was in force alone, this one pins the platform preference.
+    expect(properties.defaultTheme?.enum).toEqual([...THEMES]);
+  });
+
+  it("offers every layout contract this release knows, and no other", () => {
+    // A contract offered here that `buildAppRouter` cannot find is an app that refuses to
+    // start with "Unknown layout contract", pointing at a value a tool was told was legal.
+    expect(properties.contract?.enum?.slice().sort()).toEqual(Object.keys(LAYOUT_CONTRACTS).sort());
+  });
+
+  it("offers exactly the fields a navigation group carries", () => {
+    expect(Object.keys(group).sort()).toEqual([...NAV_GROUP_FIELDS].sort());
+    // Against the resolver's own list, not against a copy of it written here. Comparing a
+    // mirror to a second copy of the thing it mirrors proves nothing about either.
+    expect(shell.navGroups?.items?.required?.slice().sort()).toEqual(
+      [...NAV_GROUP_REQUIRED].sort(),
+    );
+  });
+
+  it("offers exactly the slots a brand declares", () => {
+    const brand = shell.brand?.properties ?? {};
+    expect(Object.keys(brand).sort()).toEqual([...BRAND_FIELDS].sort());
+    expect(shell.brand?.type).toBe("object");
+    expect(shell.brand?.additionalProperties).toBe(false);
+    // Both floored and neither required: an empty path is a mark that fails to load, while an
+    // absent one is the app saying it has no second file.
+    for (const slot of BRAND_FIELDS) {
+      expect(brand[slot]?.type, slot).toBe("string");
+      expect(brand[slot]?.minLength, slot).toBe(1);
+    }
+    expect(shell.brand?.required).toBeUndefined();
+  });
+
+  it("refuses an unknown key at every level it has one", () => {
+    // The manifest describes a document whose consumer refuses unknown keys at both levels and
+    // on a group entry. A manifest that said otherwise would tell a tool it may write anything.
+    expect(manifest.additionalProperties).toBe(false);
+    expect(properties.shell?.additionalProperties).toBe(false);
+    expect(shell.navGroups?.items?.additionalProperties).toBe(false);
+  });
+
+  it("gives every property a title and a description", () => {
+    // The half of the file no generator could produce, and the reason it is hand-written. A
+    // property with neither renders in a form as its own key and nothing else, which for
+    // `navPlacement` is a shrug and for `contract` is a choice that can turn a build red.
+    for (const [path, property] of everyProperty()) {
+      expect(property.title?.trim(), `${path}: title`).toBeTruthy();
+      expect(property.description?.trim(), `${path}: description`).toBeTruthy();
+    }
+  });
+
+  it("declares a type for every property, so a renderer never has to guess", () => {
+    for (const [path, property] of everyProperty()) {
+      expect(property.type, `${path}: type`).toBeTruthy();
+    }
+  });
+
+  it("declares the type the resolver actually refuses anything else for", () => {
+    // Truthiness was the whole of this check, and truthiness is not a type: with `navGroups`
+    // retyped to "object" and `order` to "string" every assertion in this file stayed green,
+    // while `resolveNavGroups` refuses a non-array and a non-integer by name. That is exactly
+    // the failure the header calls worse — a tool writes `"navGroups": {}` in good faith,
+    // reading a type the manifest offered, and the app will not compose.
+    expect(shell.navGroups?.type).toBe("array");
+    expect(shell.navGroups?.items?.type).toBe("object");
+    expect(group.order?.type).toBe("integer");
+    expect(group.id?.type).toBe("string");
+    expect(group.label?.type).toBe("string");
+    for (const key of Object.keys(SHELL_VALUES)) {
+      expect(shell[key]?.type, `shell.${key}`).toBe("string");
+    }
+  });
+
+  it("declares the emptiness floors the resolver refuses, and no others", () => {
+    // Each of these is a value the resolver rejects, so a manifest offering it without the
+    // floor tells a tool the empty string is legal. And `label` must NOT carry one: the empty
+    // label is how the document declares a group that renders no heading, and a floor there
+    // would tell a tool to refuse the one way of stating that.
+    expect(properties.contract?.minLength).toBe(1);
+    expect(properties.defaultTheme?.minLength).toBe(1);
+    expect(group.id?.minLength).toBe(1);
+    expect(group.label?.minLength).toBeUndefined();
+    expect(group.order?.minLength).toBeUndefined();
+  });
+
+  it("is reachable by the subpath a consumer imports it from", () => {
+    // The file only does its job from inside an app's node_modules, and the only thing that
+    // puts it there under a stable name is the package's own export map. A rename that moved
+    // the file would leave every gate above green while the published path 404s in the one
+    // place the file is read — and this package's own suite reads it by relative URL, so
+    // nothing else here would notice.
+    const pkg: { exports: Record<string, string> } = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf-8"),
+    );
+    const subpath = pkg.exports["./layout.manifest.json"];
+    expect(subpath).toBe("./src/layout.manifest.json");
+    expect(
+      readFileSync(new URL(`../${subpath!.slice(2)}`, import.meta.url), "utf-8").length,
+    ).toBeGreaterThan(0);
+  });
+});

package/src/layout.test.tsx

@@ -2,7 +2,7 @@
 import { cleanup, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it } from "vitest";
 
-import { DetailList, Stack } from "./layout";
+import { DetailList, Divider, Grid, Stack } from "./layout";
 
 afterEach(cleanup);
 
@@ -51,6 +51,77 @@ describe("Stack", () => {
     expect(el.style.display).toBe("");
   });
 
+  it("splits a responsive prop into a narrow attribute and a wide one", () => {
+    // jsdom evaluates no media query, so the unit-level claim is the attributes and nothing
+    // more — which is the honest boundary. That the rules then apply at the right width is a
+    // browser fact, held by the `stack-responsive-*` specimen pair at 420 and 900.
+    render(
+      <Stack
+        data-testid="toolbar"
+        direction={{ narrow: "column", wide: "row" }}
+        gap={{ narrow: 2, wide: 4 }}
+      >
+        <span>a</span>
+      </Stack>,
+    );
+    const el = screen.getByTestId("toolbar");
+    expect(el).toHaveAttribute("data-direction", "column");
+    expect(el).toHaveAttribute("data-direction-wide", "row");
+    expect(el).toHaveAttribute("data-gap", "2");
+    expect(el).toHaveAttribute("data-gap-wide", "4");
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("stamps no wide attribute when the prop is not responsive", () => {
+    // The back-compatibility claim, asserted as absence: every Stack in every consuming app
+    // passes scalars, so it must render exactly the attributes it always did — which is why
+    // adding the feature moved no baseline anywhere.
+    render(
+      <Stack data-testid="plain" direction="row" gap={4}>
+        <span>a</span>
+      </Stack>,
+    );
+    const el = screen.getByTestId("plain");
+    expect(el).toHaveAttribute("data-direction", "row");
+    expect(el).toHaveAttribute("data-gap", "4");
+    expect(el.hasAttribute("data-direction-wide")).toBe(false);
+    expect(el.hasAttribute("data-gap-wide")).toBe(false);
+  });
+
+  it("accepts a responsive gap of 0, which a falsy check would drop", () => {
+    // `gap: 0` is a legal step and the only one that is falsy, so a `value.wide || undefined`
+    // anywhere in the split would silently render the narrow gap at every width.
+    render(
+      <Stack data-testid="zero" gap={{ narrow: 4, wide: 0 }}>
+        <span>a</span>
+      </Stack>,
+    );
+    expect(screen.getByTestId("zero")).toHaveAttribute("data-gap-wide", "0");
+  });
+
+  it("names padding on the token scale, including the falsy zero step", () => {
+    // `padding={0}` is a legal step and the only falsy one, so a truthiness check anywhere in
+    // the stamp would silently drop it and inherit the container's inset instead.
+    const { rerender } = render(
+      <Stack data-testid="padded" padding={4}>
+        <span>a</span>
+      </Stack>,
+    );
+    expect(screen.getByTestId("padded")).toHaveAttribute("data-padding", "4");
+    rerender(
+      <Stack data-testid="padded" padding={0}>
+        <span>a</span>
+      </Stack>,
+    );
+    expect(screen.getByTestId("padded")).toHaveAttribute("data-padding", "0");
+    rerender(
+      <Stack data-testid="padded">
+        <span>a</span>
+      </Stack>,
+    );
+    expect(screen.getByTestId("padded").hasAttribute("data-padding")).toBe(false);
+  });
+
   it("works as a form (submit handler fires)", () => {
     let submitted = false;
     render(
@@ -70,7 +141,133 @@ describe("Stack", () => {
   });
 });
 
+describe("Grid", () => {
+  it("leaves every default unstamped, because the defaults ARE the base rule", () => {
+    // auto columns, the sm track floor and stretched cells are what the base rule declares, so
+    // their attributes would describe the standard shape a second time. Same idiom as density's
+    // "comfortable" and Button's md — and asserted as absence, deliberately, because a later
+    // change that starts stamping them would leave the sheet with two accounts of one default.
+    render(
+      <Grid data-testid="grid">
+        <span>a</span>
+      </Grid>,
+    );
+    const el = screen.getByTestId("grid");
+    expect(el.tagName).toBe("DIV");
+    expect(el).toHaveAttribute("data-terp", "grid");
+    expect(el).toHaveAttribute("data-gap", "4");
+    expect(el.hasAttribute("data-columns")).toBe(false);
+    expect(el.hasAttribute("data-min-column")).toBe(false);
+    expect(el.hasAttribute("data-align")).toBe(false);
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("names a fixed count, the element and the gap", () => {
+    render(
+      <Grid data-testid="grid" as="ul" columns={3} gap={2}>
+        <li>a</li>
+      </Grid>,
+    );
+    const el = screen.getByTestId("grid");
+    expect(el.tagName).toBe("UL");
+    // A number prop, a text attribute: `columns={3}` has to produce "3" or the rule misses.
+    expect(el).toHaveAttribute("data-columns", "3");
+    expect(el).toHaveAttribute("data-gap", "2");
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("names a non-default track floor, and only while the columns are auto", () => {
+    // `minColumn` is meaningless at a fixed count — the tracks are counted, not floored — so
+    // stamping it there would put an attribute on the element that no rule reads and that a
+    // reader would take for an active choice.
+    const { rerender } = render(
+      <Grid data-testid="grid" minColumn="lg">
+        <span>a</span>
+      </Grid>,
+    );
+    expect(screen.getByTestId("grid")).toHaveAttribute("data-min-column", "lg");
+    rerender(
+      <Grid data-testid="grid" columns={2} minColumn="lg">
+        <span>a</span>
+      </Grid>,
+    );
+    const fixed = screen.getByTestId("grid");
+    expect(fixed).toHaveAttribute("data-columns", "2");
+    expect(fixed.hasAttribute("data-min-column")).toBe(false);
+  });
+
+  it("keeps alignment an attribute, unlike Stack's, and takes no style", () => {
+    // The deliberate divergence: Stack's align is an open set of CSS keywords and stays inline
+    // (ADR 0094 §3); Grid's is a closed four, so it is an attribute and Grid renders no inline
+    // style at all. That is what keeps a new primitive out of the inline-style ledger.
+    render(
+      <Grid data-testid="grid" align="center">
+        <span>a</span>
+      </Grid>,
+    );
+    const el = screen.getByTestId("grid");
+    expect(el).toHaveAttribute("data-align", "center");
+    expect(el.getAttribute("style")).toBeNull();
+  });
+});
+
+describe("Divider", () => {
+  it("is an hr, so the separation reaches the accessibility tree", () => {
+    // A bordered div is what a module reaches for without a primitive, and it says nothing to
+    // a screen reader. The element is the point of the component.
+    render(<Divider data-testid="rule" />);
+    const el = screen.getByTestId("rule");
+    expect(el.tagName).toBe("HR");
+    expect(el).toHaveAttribute("data-terp", "divider");
+    expect(el.hasAttribute("data-orientation")).toBe(false);
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("announces a vertical rule as one, which hr does not imply", () => {
+    render(<Divider data-testid="rule" orientation="vertical" />);
+    const el = screen.getByTestId("rule");
+    expect(el).toHaveAttribute("data-orientation", "vertical");
+    expect(el).toHaveAttribute("aria-orientation", "vertical");
+  });
+});
+
 describe("DetailList", () => {
+  it("leaves the inline default unstamped, and marks each row", () => {
+    // `inline` and one column are the base rule. The row marker is new and load-bearing: the
+    // aligned layout turns the wrapper into `display: contents` so the dt and dd become grid
+    // items of the dl itself, which is the only way to align labels across rows without
+    // changing the DOM — and a rule cannot reach an unmarked wrapper.
+    render(<DetailList data-testid="dl" items={[{ label: "Owner", value: "Ada" }]} />);
+    const el = screen.getByTestId("dl");
+    expect(el.hasAttribute("data-layout")).toBe(false);
+    expect(el.hasAttribute("data-columns")).toBe(false);
+    expect(el.querySelector('[data-terp="detail-list-row"]')).not.toBeNull();
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("names a layout and a column count", () => {
+    render(
+      <DetailList
+        data-testid="dl"
+        layout="aligned"
+        columns={2}
+        items={[{ label: "Owner", value: "Ada" }]}
+      />,
+    );
+    const el = screen.getByTestId("dl");
+    expect(el).toHaveAttribute("data-layout", "aligned");
+    expect(el).toHaveAttribute("data-columns", "2");
+  });
+
+  it("puts no colon in the markup, because two layouts must not have one", () => {
+    // The colon is a rule on the inline layout, not a text node — `aligned` and `stacked` must
+    // not carry one, and no rule can withdraw a text node. It is decorative either way: the
+    // dt/dd pairing is what carries the relationship to assistive tech, so moving it out of the
+    // markup also stops it being read aloud.
+    render(<DetailList items={[{ label: "Owner", value: "Ada" }]} />);
+    expect(screen.getByText("Owner").textContent).toBe("Owner");
+  });
+
   it("renders label/value pairs as a definition list", () => {
     render(
       <DetailList