@terpjs/react-core 0.1.0

package/src/layout.test.tsx

@@ -0,0 +1,72 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { DetailList, Stack } from "./layout";
+
+afterEach(cleanup);
+
+describe("Stack", () => {
+  it("renders a flex column with a token gap by default", () => {
+    render(
+      <Stack data-testid="stack">
+        <span>a</span>
+        <span>b</span>
+      </Stack>,
+    );
+    const el = screen.getByTestId("stack");
+    expect(el.tagName).toBe("DIV");
+    expect(el.style.display).toBe("flex");
+    expect(el.style.flexDirection).toBe("column");
+    expect(el.style.gap).toBe("var(--space-2)");
+  });
+
+  it("renders the requested element with direction, gap, alignment and wrap", () => {
+    render(
+      <Stack data-testid="row" as="section" direction="row" gap={4} align="center" justify="space-between" wrap>
+        <span>a</span>
+      </Stack>,
+    );
+    const el = screen.getByTestId("row");
+    expect(el.tagName).toBe("SECTION");
+    expect(el.style.flexDirection).toBe("row");
+    expect(el.style.gap).toBe("var(--space-4)");
+    expect(el.style.alignItems).toBe("center");
+    expect(el.style.justifyContent).toBe("space-between");
+    expect(el.style.flexWrap).toBe("wrap");
+  });
+
+  it("works as a form (submit handler fires)", () => {
+    let submitted = false;
+    render(
+      <Stack
+        as="form"
+        data-testid="form"
+        onSubmit={(event) => {
+          event.preventDefault();
+          submitted = true;
+        }}
+      >
+        <button type="submit">go</button>
+      </Stack>,
+    );
+    screen.getByText("go").click();
+    expect(submitted).toBe(true);
+  });
+});
+
+describe("DetailList", () => {
+  it("renders label/value pairs as a definition list", () => {
+    render(
+      <DetailList
+        items={[
+          { label: "Owner", value: "Ada" },
+          { label: { id: "detail.purchased", message: "Purchased" }, value: "2023-01-01" },
+        ]}
+      />,
+    );
+    expect(screen.getByText(/Owner/).tagName).toBe("DT");
+    expect(screen.getByText("Ada").tagName).toBe("DD");
+    expect(screen.getByText(/Purchased/)).toBeInTheDocument();
+  });
+});

package/src/layout.tsx

@@ -0,0 +1,90 @@
+import type { CSSProperties, ElementType, HTMLAttributes, ReactNode } from "react";
+
+import { useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+/** The spacing scale — indexes into the `--space-*` design tokens (no arbitrary pixel gaps). */
+export type SpaceToken = 0 | 1 | 2 | 3 | 4 | 6 | 8;
+
+export interface StackProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
+  /** The rendered element (`"div"` by default; use `"form"`, `"section"`, `"ul"`, …). */
+  as?: ElementType;
+  /** Main axis: `"column"` (default) stacks, `"row"` lines up. */
+  direction?: "column" | "row";
+  /** Gap between children, as a step on the token spacing scale (default `2`). */
+  gap?: SpaceToken;
+  /** Cross-axis alignment (e.g. `"center"`, `"start"`, `"end"`, `"stretch"`). */
+  align?: CSSProperties["alignItems"];
+  /** Main-axis distribution (e.g. `"space-between"`, `"center"`, `"end"`). */
+  justify?: CSSProperties["justifyContent"];
+  /** Allow row items to wrap onto new lines (rows of tags, toolbars). */
+  wrap?: boolean;
+  children?: ReactNode;
+}
+
+/**
+ * The layout primitive: a flex container whose gap comes from the token spacing scale, so
+ * app modules compose layout **without writing CSS or `style={}`** (the boundary lint refuses
+ * the `style` attribute in module code). A vertical `Stack` lays out a form; a `row` Stack
+ * with `justify="space-between"` is a toolbar. Anything more bespoke belongs in a react-core
+ * component, not ad-hoc styles in a module.
+ */
+export function Stack({
+  as: Component = "div",
+  direction = "column",
+  gap = 2,
+  align,
+  justify,
+  wrap = false,
+  ...rest
+}: StackProps) {
+  const style: CSSProperties = {
+    display: "flex",
+    flexDirection: direction,
+    gap: `var(--space-${gap})`,
+    margin: 0,
+    ...(align !== undefined ? { alignItems: align } : undefined),
+    ...(justify !== undefined ? { justifyContent: justify } : undefined),
+    ...(wrap ? { flexWrap: "wrap" } : undefined),
+  };
+  return <Component {...rest} data-terp="stack" style={style} />;
+}
+
+export interface DetailItem {
+  /** The item's label (rendered as `<dt>`). */
+  label: UiText;
+  /** The item's value (rendered as `<dd>`). */
+  value: ReactNode;
+}
+
+export interface DetailListProps extends Omit<HTMLAttributes<HTMLDListElement>, "style"> {
+  /** The label/value pairs to render, in order. */
+  items: readonly DetailItem[];
+}
+
+const detailListStyle: CSSProperties = {
+  margin: 0,
+  display: "grid",
+  gap: "var(--space-1)",
+};
+const detailTermStyle: CSSProperties = { display: "inline", fontWeight: "var(--font-weight-medium)" };
+const detailValueStyle: CSSProperties = { display: "inline", margin: 0 };
+
+/**
+ * Token-styled label/value pairs as a semantic `<dl>` — record metadata on a detail page,
+ * an expanded row's summary. Centralizes the "Label: value" pattern so modules never
+ * hand-style definition lists.
+ */
+export function DetailList({ items, ...rest }: DetailListProps) {
+  const text = useUiText();
+  return (
+    <dl {...rest} data-terp="detail-list" style={detailListStyle}>
+      {items.map((item, index) => (
+        <div key={index}>
+          <dt style={detailTermStyle}>{text(item.label)}: </dt>
+          <dd style={detailValueStyle}>{item.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}

package/src/layoutContract.test.tsx

@@ -0,0 +1,179 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { Component } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+
+// The lint-side source of the contract table (spec-as-data in @terpjs/eslint-boundaries);
+// react-core carries a TS mirror because a published runtime package cannot depend on a
+// lint package. This parity test keeps the two identical, so the data cannot drift.
+// @ts-expect-error — monorepo-relative untyped JS import, test-only
+import * as lintLayouts from "../../eslint-boundaries/src/layouts.js";
+
+import { DetailPage } from "./DetailPage";
+import { HubCard, HubPage } from "./HubPage";
+import {
+  LAYOUT_CONTRACTS,
+  LayoutContractContext,
+  slotViolationMessage,
+  verifySlotChildren,
+} from "./layoutContract";
+import { OverviewPage } from "./OverviewPage";
+import { Page } from "./Page";
+import { DetailList, Stack } from "./layout";
+
+afterEach(cleanup);
+
+class CatchBoundary extends Component<
+  { children: ReactNode },
+  { message: string | null }
+> {
+  state = { message: null };
+  static getDerivedStateFromError(error: Error) {
+    return { message: error.message };
+  }
+  render() {
+    return this.state.message === null ? (
+      this.props.children
+    ) : (
+      <p data-testid="refused">{this.state.message}</p>
+    );
+  }
+}
+
+function underContract(children: ReactNode, contract: string | null = "standard") {
+  return render(
+    <CatchBoundary>
+      <LayoutContractContext.Provider value={contract}>
+        {children}
+      </LayoutContractContext.Provider>
+    </CatchBoundary>,
+  );
+}
+
+describe("layout contract parity (docs/data can't drift)", () => {
+  it("mirrors the eslint-boundaries contract table byte-for-byte", () => {
+    expect(JSON.parse(JSON.stringify(LAYOUT_CONTRACTS))).toEqual(
+      JSON.parse(JSON.stringify(lintLayouts.LAYOUT_CONTRACTS)),
+    );
+  });
+
+  it("phrases the identical directive message on both halves", () => {
+    expect(slotViolationMessage("standard", "HubPage", "<div>")).toBe(
+      lintLayouts.slotViolationMessage("standard", "HubPage", "<div>"),
+    );
+  });
+});
+
+describe("runtime slot enforcement", () => {
+  it("refuses a non-HubCard child in a HubPage grid, fail closed, with the directive message", async () => {
+    underContract(
+      <HubPage title="Home">
+        {/* not a HubCard — a rogue list item */}
+        <li>rogue</li>
+      </HubPage>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId("refused").textContent).toBe(
+        slotViolationMessage("standard", "HubPage", "<li>"),
+      );
+    });
+  });
+
+  it("passes a conforming HubPage of HubCards", async () => {
+    underContract(
+      <HubPage title="Home">
+        <HubCard to="/a" title="Area A" />
+        <HubCard to="/b" title="Area B" />
+      </HubPage>,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(screen.queryByTestId("refused")).toBeNull();
+    expect(screen.getByText("Area A")).toBeDefined();
+  });
+
+  it("refuses bespoke content in an OverviewPage body and names the found element", async () => {
+    underContract(
+      <OverviewPage title="Records">
+        <div>hand-rolled listing</div>
+      </OverviewPage>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId("refused").textContent).toBe(
+        slotViolationMessage("standard", "OverviewPage", "<div>"),
+      );
+    });
+  });
+
+  it("passes an OverviewPage whose body is allowed components", async () => {
+    underContract(
+      <OverviewPage title="Records">
+        <Stack>
+          <span>toolbar content lives inside allowed containers</span>
+        </Stack>
+      </OverviewPage>,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(screen.queryByTestId("refused")).toBeNull();
+  });
+
+  it("passes a DetailPage of record sections and refuses a rogue one", async () => {
+    underContract(
+      <DetailPage title="Record 1" parents={[{ label: "Records", to: "/records" }]}>
+        <Stack>
+          <DetailList items={[{ label: "Status", value: "open" }]} />
+        </Stack>
+      </DetailPage>,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(screen.queryByTestId("refused")).toBeNull();
+    cleanup();
+
+    underContract(
+      <DetailPage title="Record 1" parents={[{ label: "Records", to: "/records" }]}>
+        <table />
+      </DetailPage>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId("refused").textContent).toBe(
+        slotViolationMessage("standard", "DetailPage", "<table>"),
+      );
+    });
+  });
+
+  it("leaves the plain Page unconstrained (the contract's bespoke pressure valve)", async () => {
+    underContract(
+      <Page title="Bespoke">
+        <div>anything goes here</div>
+      </Page>,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(screen.queryByTestId("refused")).toBeNull();
+  });
+
+  it("skips the check while the archetype shows the loading / error frame", async () => {
+    underContract(
+      <OverviewPage title="Records" isLoading>
+        <div>never rendered</div>
+      </OverviewPage>,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(screen.queryByTestId("refused")).toBeNull();
+  });
+
+  it("does nothing without an opted-in contract (backwards compatible)", async () => {
+    underContract(
+      <OverviewPage title="Records">
+        <div>legacy body</div>
+      </OverviewPage>,
+      null,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(screen.queryByTestId("refused")).toBeNull();
+  });
+
+  it("verifySlotChildren returns null for an ungoverned contract/slot", () => {
+    expect(verifySlotChildren("ghost", "HubPage", [])).toBeNull();
+    expect(verifySlotChildren("standard", "Page", [])).toBeNull();
+  });
+});

package/src/layoutContract.ts

@@ -0,0 +1,137 @@
+import { createContext, useContext } from "react";
+
+/**
+ * The runtime half of the slot-typed layout contract control (ADR 0079) — the layout
+ * analog of ./pageMarker.ts. When an app opts into a contract
+ * (`renderTerpApp({ layoutContract })` / `buildAppRouter(..., { layoutContract })`),
+ * each governed page archetype verifies after mount that its body slot's rendered DOM
+ * children are components the contract allows there — every sanctioned component stamps
+ * a `data-terp` marker on its root — and refuses the view, fail closed, with the same
+ * agent-directive message the `terp/layout-contract` lint rule phrases.
+ *
+ * This table is the TypeScript mirror of the spec-as-data source in
+ * `@terpjs/eslint-boundaries/src/layouts.js` (react-core ships standalone, so it cannot
+ * import a lint package); the parity test in ./layoutContract.test.tsx keeps the two
+ * identical, so the data cannot drift.
+ */
+
+/** One governed slot: allowed component names mapped to their `data-terp` root markers. */
+export interface LayoutSlotSpec {
+  readonly components: Readonly<Record<string, string>>;
+}
+
+/** One named layout contract: a description and its per-archetype slot specs. */
+export interface LayoutContractSpec {
+  readonly description: string;
+  readonly slots: Readonly<Record<string, LayoutSlotSpec>>;
+}
+
+/** Every layout contract, keyed by id (mirror of the eslint-boundaries source table). */
+export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
+  standard: {
+    description:
+      "The standard three-level shape: hub bodies are card grids (HubCard only), " +
+      "overview bodies are data collections (DataView / ResourceList + framework " +
+      "states), detail bodies are record sections (DetailList / Stack / Tabs + " +
+      "framework states). A bespoke screen composes the plain Page, which the " +
+      "contract deliberately leaves unconstrained.",
+    slots: {
+      HubPage: {
+        components: { HubCard: "hubcard" },
+      },
+      OverviewPage: {
+        components: {
+          DataView: "dataview",
+          ResourceList: "resource-list",
+          ModuleNav: "module-nav",
+          Stack: "stack",
+          EmptyState: "empty-state",
+          ErrorState: "error-state",
+          LoadingState: "loading-state",
+          Alert: "alert",
+          ConfirmDialog: "dialog",
+        },
+      },
+      DetailPage: {
+        components: {
+          DetailList: "detail-list",
+          Stack: "stack",
+          Tabs: "tabs",
+          ModuleNav: "module-nav",
+          DataView: "dataview",
+          EmptyState: "empty-state",
+          ErrorState: "error-state",
+          LoadingState: "loading-state",
+          Alert: "alert",
+          ConfirmDialog: "dialog",
+        },
+      },
+    },
+  },
+};
+
+/**
+ * The one agent-directive violation message both enforcement halves phrase: the
+ * contract, the slot, what was found, what is allowed, and the concrete fix.
+ * (Byte-identical to the eslint-boundaries builder; parity-tested.)
+ */
+export function slotViolationMessage(
+  contractId: string,
+  slotOwner: string,
+  found: string,
+): string {
+  const allowed = Object.keys(LAYOUT_CONTRACTS[contractId]!.slots[slotOwner]!.components);
+  return (
+    `Layout contract "${contractId}": the ${slotOwner} body slot accepts only ` +
+    `${allowed.join(" / ")}; found ${found}. Compose the body from those react-core ` +
+    "components (recipe: terp guide layouts), move bespoke content to a plain Page, " +
+    "or opt out on this line with a justified // terp-allow-layout-contract: <reason> " +
+    "marker (counted by the escape-hatch budget)."
+  );
+}
+
+/** The active contract id for the current routed view, or null (no contract = no checks). */
+export const LayoutContractContext = createContext<string | null>(null);
+
+/** Read the active layout contract id (null outside an opted-in app). */
+export function useLayoutContract(): string | null {
+  return useContext(LayoutContractContext);
+}
+
+/**
+ * The body-slot owner the enclosing archetype declared for its `Page` (set by
+ * `OverviewPage` / `DetailPage`; `Page` resets it to null around its own children so a
+ * nested tree is never judged by an ancestor's slot).
+ */
+export const LayoutSlotContext = createContext<string | null>(null);
+
+/** How a rendered DOM child is described in a violation message. */
+function describeElement(element: Element): string {
+  const marker = element.getAttribute("data-terp");
+  const tag = element.tagName.toLowerCase();
+  return marker !== null ? `<${tag} data-terp="${marker}">` : `<${tag}>`;
+}
+
+/**
+ * Verify a slot's rendered DOM children against the active contract: every child must
+ * carry the `data-terp` marker of an allowed component. Returns the directive violation
+ * message, or null when the slot conforms (or the contract/slot is not governed).
+ */
+export function verifySlotChildren(
+  contractId: string,
+  slotOwner: string,
+  children: readonly Element[],
+): string | null {
+  const slot = LAYOUT_CONTRACTS[contractId]?.slots[slotOwner];
+  if (slot === undefined) {
+    return null;
+  }
+  const allowed = new Set(Object.values(slot.components));
+  for (const child of children) {
+    const marker = child.getAttribute("data-terp");
+    if (marker === null || !allowed.has(marker)) {
+      return slotViolationMessage(contractId, slotOwner, describeElement(child));
+    }
+  }
+  return null;
+}

package/src/locale.test.tsx

@@ -0,0 +1,97 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { LOCALE_EN, LOCALE_NL, LOCALE_STORAGE_KEY, LanguageSwitcher, LocaleProvider } from "./locale";
+import { DEFAULT_STRINGS, useStrings } from "./uiText";
+
+afterEach(() => {
+  cleanup();
+  window.localStorage.clear();
+});
+
+function SignOutLabel() {
+  return <p>{useStrings().signOut}</p>;
+}
+
+const NL = { label: "Nederlands", strings: { signOut: "Uitloggen", language: "Taal" } };
+
+describe("LocaleProvider + LanguageSwitcher", () => {
+  it("feeds the active catalog's overrides through the UiText seam", () => {
+    render(
+      <LocaleProvider locales={{ en: LOCALE_EN, nl: NL }} defaultLocale="nl">
+        <SignOutLabel />
+      </LocaleProvider>,
+    );
+    expect(screen.getByText("Uitloggen")).toBeInTheDocument();
+  });
+
+  it("switches locale via the LanguageSwitcher and persists the choice", () => {
+    render(
+      <LocaleProvider locales={{ en: LOCALE_EN, nl: NL }}>
+        <LanguageSwitcher />
+        <SignOutLabel />
+      </LocaleProvider>,
+    );
+    expect(screen.getByText("Sign out")).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Language" }));
+    fireEvent.click(screen.getByRole("menuitemradio", { name: "Nederlands" }));
+    expect(screen.getByText("Uitloggen")).toBeInTheDocument();
+    expect(window.localStorage.getItem(LOCALE_STORAGE_KEY)).toBe("nl");
+    // The switcher itself follows the active catalog too.
+    expect(screen.getByLabelText("Taal")).toBeInTheDocument();
+  });
+
+  it("restores a persisted locale and lists native names", () => {
+    window.localStorage.setItem(LOCALE_STORAGE_KEY, "nl");
+    render(
+      <LocaleProvider locales={{ en: LOCALE_EN, nl: NL }}>
+        <LanguageSwitcher />
+      </LocaleProvider>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Taal" }));
+    expect(screen.getByRole("menuitemradio", { name: "English" })).toBeInTheDocument();
+    expect(screen.getByRole("menuitemradio", { name: "Nederlands" })).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("ignores a persisted locale the app no longer declares", () => {
+    window.localStorage.setItem(LOCALE_STORAGE_KEY, "fr");
+    render(
+      <LocaleProvider locales={{ en: LOCALE_EN, nl: NL }}>
+        <SignOutLabel />
+      </LocaleProvider>,
+    );
+    expect(screen.getByText("Sign out")).toBeInTheDocument();
+  });
+
+  it("renders no switcher with a single locale, or outside a provider", () => {
+    render(
+      <LocaleProvider locales={{ en: LOCALE_EN }}>
+        <LanguageSwitcher />
+      </LocaleProvider>,
+    );
+    render(<LanguageSwitcher />);
+    expect(screen.queryByLabelText("Language")).not.toBeInTheDocument();
+  });
+
+  it("offers an icon-only inline variant for the shell header", () => {
+    render(
+      <LocaleProvider locales={{ en: LOCALE_EN, nl: NL }}>
+        <LanguageSwitcher variant="inline" />
+      </LocaleProvider>,
+    );
+    expect(screen.getByRole("button", { name: "Language" })).toBeInTheDocument();
+    // No visible label text in the inline variant.
+    expect(screen.queryByText("Language")).not.toBeInTheDocument();
+  });
+});
+
+describe("LOCALE_NL", () => {
+  it("translates every framework string (completeness drift-guard)", () => {
+    // A new TerpStrings key without a Dutch translation fails here, so the
+    // bundled catalog can never silently fall back to English for new chrome.
+    expect(Object.keys(LOCALE_NL.strings ?? {}).sort()).toEqual(
+      Object.keys(DEFAULT_STRINGS).sort(),
+    );
+  });
+});