@terpjs/react-core 0.9.0 → 0.11.0

package/src/layoutContract.test.tsx

@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { Component } from "react";
 import { afterEach, describe, expect, it } from "vitest";
@@ -11,6 +11,11 @@ import { afterEach, describe, expect, it } from "vitest";
 import * as lintLayouts from "../../eslint-boundaries/src/layouts.js";
 
 import { DetailPage } from "./DetailPage";
+import { FormPage } from "./FormPage";
+import { SettingsPage } from "./SettingsPage";
+import { SplitPage, SplitPane } from "./SplitPage";
+import { Input } from "./ui/Input";
+import { Field } from "./Field";
 import { HubCard, HubPage } from "./HubPage";
 import {
   LAYOUT_CONTRACTS,
@@ -19,8 +24,17 @@ import {
   verifySlotChildren,
 } from "./layoutContract";
 import { OverviewPage } from "./OverviewPage";
+
+// The public surface, as source: the archetype-coverage check below derives its list from
+// the entry point's own exports rather than restating one. `raw.d.ts` declares the ambient
+// ImportMeta.glob type this shares with the other scanning tests in the package.
+const entryPoint = Object.values(
+  import.meta.glob("./index.ts", { query: "?raw", import: "default", eager: true }),
+)[0] as string;
 import { Page } from "./Page";
-import { DetailList, Stack } from "./layout";
+import { EmptyState } from "./EmptyState";
+import { DetailList, Divider, Grid, Stack } from "./layout";
+import { Text } from "./typography";
 import { PageActions } from "./PageActions";
 import { ThemeProvider, ThemeToggle } from "./theme";
 import { Button } from "./ui/Button";
@@ -55,6 +69,30 @@ function underContract(children: ReactNode, contract: string | null = "standard"
   );
 }
 
+/**
+ * Assert that a composition was ACCEPTED — after actually letting the check run.
+ *
+ * The obvious spelling is a false green, and it was the shape every acceptance test in this file
+ * used:
+ *
+ *     await waitFor(() => expect(screen.queryByTestId("refused")).toBeNull());
+ *
+ * `waitFor` retries until its callback stops throwing, so a callback asserting that something is
+ * ABSENT passes on the very first attempt — before `Page`'s `setTimeout(0)` slot check has run at
+ * all. It waits for nothing and can never fail. Nine tests claimed to gate the acceptance half of
+ * ADR 0079 and gated nothing; verified by putting a `Grid` — which the OverviewPage slot table
+ * does not admit — into a governed overview body and watching the suite stay green.
+ *
+ * Flushing one macrotask inside `act` is what makes the assertion mean something: the check has
+ * then either thrown into the boundary or decided the body was legal.
+ */
+async function expectAccepted() {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+  expect(screen.queryByTestId("refused")).toBeNull();
+}
+
 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(
@@ -69,6 +107,124 @@ describe("layout contract parity (docs/data can't drift)", () => {
   });
 });
 
+describe("every archetype the package exports is governed, or says it is not", () => {
+  // The gap this closes was a green build. `verifySlotChildren` returns null for a slot the
+  // table does not name (layoutContract.ts:138-141) and the lint rule early-returns the same
+  // way, so an archetype exported WITHOUT a table entry is silently ungoverned by both halves
+  // of the control — no error, no warning, and a governed app renders it with the body slot
+  // wide open. Nothing asserted the two lists agreed, which means "forgot the table entry"
+  // was indistinguishable from "deliberately unconstrained".
+  //
+  // Derived from the public surface rather than restated as a list, because a list is the
+  // thing that was missing: a new `FormPage` export joins this check by existing, and has to
+  // either take a slot or come here and say why.
+  // Two independent derivations, unioned, because each has a blind spot the other covers.
+  //
+  // The named-export scan reads `export { X } from` and `export { X as Y } from` — the alias
+  // form matters, since the exported name is what a consumer writes. It cannot see
+  // `export * from`, and index.ts already contains one (`./dataview`), so on its own this
+  // derivation would let an archetype re-exported through a sub-namespace escape all three
+  // assertions below INCLUDING the vacuity guard, which is built from the same scan.
+  //
+  // The filename scan covers exactly that: an archetype lives in `<Name>Page.tsx` by
+  // convention, wherever in the tree it sits. It cannot see an archetype declared inside some
+  // other file — which the export scan can.
+  const namedExports = [...entryPoint.matchAll(/^export \{([^}]*)\} from/gm)]
+    .flatMap((match) => match[1]!.split(","))
+    // `A as B` exports B; a bare name exports itself.
+    .map((entry) => entry.trim().split(/\s+as\s+/).pop()!.trim());
+  const archetypeFiles = Object.keys(
+    import.meta.glob("./**/*Page.tsx", { query: "?raw", import: "default", eager: true }),
+  )
+    .filter((file) => !file.includes(".test."))
+    .map((file) => file.split("/").pop()!.replace(/\.tsx$/, ""));
+  const exported = [
+    ...new Set(
+      [...namedExports, ...archetypeFiles]
+        // `endsWith` rather than a `\w*Page$` regex, which cannot match "Page" itself:
+        // after the leading capital there is no "Page" left to match. The vacuity guard below
+        // caught that on the first run, which is the whole reason it is there.
+        .filter((name) => /^[A-Z]\w*$/.test(name) && name.endsWith("Page")),
+    ),
+  ].sort();
+
+  /**
+   * Archetypes with no slot entry, and the reason each is unconstrained.
+   *
+   * One entry, and it is the contract's own pressure valve rather than an omission: the
+   * plain `Page` is what a bespoke screen composes when no archetype fits, and the
+   * contract's description says so in as many words. Anything else added here is a claim
+   * that a screen shape has no vocabulary, which is the claim the table exists to refuse.
+   */
+  const DELIBERATELY_UNCONSTRAINED: Record<string, string> = {
+    Page: "the bespoke pressure valve — a screen no archetype fits composes this, and the contract leaves it open by design",
+  };
+
+  it("finds the archetype exports it is meant to check", () => {
+    // Vacuity guard: a derivation that matched nothing would make every assertion below pass.
+    expect(exported).toEqual([
+      "DetailPage",
+      "FormPage",
+      "HubPage",
+      "OverviewPage",
+      "Page",
+      "SettingsPage",
+      "SplitPage",
+    ]);
+  });
+
+  it("pins the namespace re-exports, which neither derivation can look inside", () => {
+    // `export * from "./x"` is opaque to both scans: the filename scan only sees files named
+    // `*Page.tsx`, and the named-export scan sees no names at all. So the set of namespace
+    // re-exports is pinned instead — adding one is the moment to check it carries no archetype,
+    // and this assertion is what forces that look.
+    const namespaces = [...entryPoint.matchAll(/^export \* from "([^"]+)"/gm)].map(
+      (match) => match[1]!,
+    );
+    expect(namespaces).toEqual(["./dataview"]);
+  });
+
+  it("keeps no excuse for an archetype that is no longer exported", () => {
+    // The reverse-direction test filters these keys out of its comparison, so a stale excuse
+    // changes nothing there and would sit in the file for ever — quietly claiming that a
+    // component nobody exports is deliberately unconstrained.
+    for (const excused of Object.keys(DELIBERATELY_UNCONSTRAINED)) {
+      expect(
+        exported,
+        `${excused} is excused from the slot table but is not an exported archetype — the excuse is stale`,
+      ).toContain(excused);
+    }
+  });
+
+  it("gives every exported archetype a slot, or a named reason for having none", () => {
+    const slots = LAYOUT_CONTRACTS.standard!.slots;
+    for (const archetype of exported) {
+      const governed = archetype in slots;
+      const excused = archetype in DELIBERATELY_UNCONSTRAINED;
+      expect(
+        governed || excused,
+        `${archetype} is exported but has no LAYOUT_CONTRACTS.standard.slots entry, so both ` +
+          "halves of the layout contract silently skip it. Add the slot (in this file AND in " +
+          "eslint-boundaries/src/layouts.js), or add it to DELIBERATELY_UNCONSTRAINED with the " +
+          "reason its body has no vocabulary.",
+      ).toBe(true);
+      expect(
+        governed && excused,
+        `${archetype} is both governed and excused — the excuse is stale, delete it`,
+      ).toBe(false);
+    }
+  });
+
+  it("names no slot that no archetype exports", () => {
+    // The other direction: a slot for an archetype that was renamed or withdrawn is a table
+    // entry nothing can ever satisfy, and the message it phrases names a component that is
+    // no longer there.
+    expect(Object.keys(LAYOUT_CONTRACTS.standard!.slots).sort()).toEqual(
+      exported.filter((name) => !(name in DELIBERATELY_UNCONSTRAINED)),
+    );
+  });
+});
+
 describe("runtime slot enforcement", () => {
   it("refuses a non-HubCard child in a HubPage grid, fail closed, with the directive message", async () => {
     underContract(
@@ -242,14 +398,18 @@ describe("layout contract survives the roots the styling migration renames", ()
       "dataview",
       "detail-list",
       "dialog",
+      "divider",
       "empty-state",
       "error-state",
+      "grid",
       "hubcard",
       "loading-state",
       "module-nav",
       "resource-list",
+      "splitpane",
       "stack",
       "tabs",
+      "text",
     ]);
   });
 
@@ -274,3 +434,152 @@ describe("layout contract survives the roots the styling migration renames", ()
     expect(screen.queryByTestId("refused")).toBeNull();
   });
 });
+
+describe("what 4b's widening does and does not admit", () => {
+  it("accepts a Grid in a detail body, which is the two-column form case", async () => {
+    // The diagnosis's headline evidence was a fifteen-field form shipped as one vertical run.
+    // Shipping `Grid` without this widening would have shipped a component no governed page
+    // could use — and only a copier-generated project has the contract switched on, so the
+    // example app could not have detected that either.
+    underContract(
+      <DetailPage title="Record" parents={[{ label: "Records", to: "/records" }]}>
+        <Grid columns={2}>
+          <span>one</span>
+          <span>two</span>
+        </Grid>
+      </DetailPage>,
+    );
+    await expectAccepted();
+  });
+
+  it("still refuses a Grid in an overview body, because a grid there is a hub", () => {
+    // The asymmetry IS the decision, so it is pinned rather than left to the table. An
+    // overview body is a data collection; a grid of summary cards is a hub, and the contract
+    // has a hub archetype for that. Widening both slots identically would have been the easy
+    // move and would have dissolved the distinction the three levels exist to carry.
+    underContract(
+      <OverviewPage title="Records">
+        <Grid columns={2}>
+          <span>one</span>
+        </Grid>
+      </OverviewPage>,
+    );
+    return waitFor(() => {
+      expect(screen.getByTestId("refused").textContent).toBe(
+        slotViolationMessage("standard", "OverviewPage", '<div data-terp="grid">'),
+      );
+    });
+  });
+
+  it("refuses a bare Field at the top of a form body, because that form cannot submit", () => {
+    // The one refusal in FormPage's slot that is a decision rather than an omission. A run of
+    // bare fields looks like a finished form and cannot be submitted: Enter does nothing
+    // without a <form>, and the house spelling of one is `Stack as="form"`. So the slot takes
+    // the container and not the fields — which is the opposite of what a reader would guess
+    // from "a form page's body is fields".
+    underContract(
+      <FormPage title="New sync" parents={[{ label: "Syncs", to: "/syncs" }]}>
+        <Field label="Name">
+          <Input />
+        </Field>
+      </FormPage>,
+    );
+    return waitFor(() => {
+      expect(screen.getByTestId("refused")).toHaveTextContent(
+        /the FormPage body slot accepts only Stack \/ Grid \/ Card/,
+      );
+    });
+  });
+
+  it("accepts a form body that is a form container with sections beside it", () => {
+    underContract(
+      <FormPage title="New sync" parents={[{ label: "Syncs", to: "/syncs" }]}>
+        <Text>Every definition needs a source and a target.</Text>
+        <Stack as="form">
+          <Field label="Name">
+            <Input />
+          </Field>
+        </Stack>
+      </FormPage>,
+    );
+    return waitFor(() => {
+      expect(screen.queryByTestId("refused")).not.toBeInTheDocument();
+    });
+  });
+
+  it("refuses a collection in a settings body, because that screen is an overview", () => {
+    // SettingsPage's slot is Card sections and nothing that holds a collection. A settings
+    // screen whose body is a table is an overview with the wrong chrome, and the contract is
+    // where that distinction is enforceable rather than advisory.
+    underContract(
+      <SettingsPage title="Preferences">
+        <DetailList items={[{ label: "Theme", value: "Dark" }]} />
+      </SettingsPage>,
+    );
+    return waitFor(() => {
+      expect(screen.getByTestId("refused")).toHaveTextContent(
+        /the SettingsPage body slot accepts only Card \/ Stack/,
+      );
+    });
+  });
+
+  it("refuses anything but a SplitPane inside a split, and accepts the two panes", async () => {
+    // The split governs its PANE ROW rather than the page body, which is HubPage's shape and
+    // not DetailPage's — so this is the assertion that the choice actually took effect. A
+    // Card dropped straight into the split is the realistic mistake.
+    underContract(
+      <SplitPage title="Syncs">
+        <Card title="Not a pane" />
+      </SplitPage>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId("refused")).toHaveTextContent(
+        /the SplitPage body slot accepts only SplitPane/,
+      );
+    });
+    cleanup();
+    underContract(
+      <SplitPage title="Syncs">
+        <SplitPane role="list" label="Definitions">
+          <DetailList items={[{ label: "Customer master", value: "ok" }]} />
+        </SplitPane>
+        <SplitPane role="detail" label="Selected definition">
+          <Card title="Customer master" />
+        </SplitPane>
+      </SplitPage>,
+    );
+    await waitFor(() => {
+      expect(screen.queryByTestId("refused")).not.toBeInTheDocument();
+    });
+  });
+
+  it("accepts a Divider and a lead paragraph in both governed bodies", async () => {
+    // A rule between sections and a paragraph above them — the two things a body wanted that
+    // needed no container. `Heading` is deliberately NOT admitted: a heading in a governed body
+    // must own its section, and `Card` (plain or boxed) is how a section is owned. A bare
+    // heading with siblings after it is a grouping the contract cannot see.
+    for (const page of [
+      <OverviewPage key="o" title="Records">
+        <Text>Lead paragraph.</Text>
+        <Divider />
+        <EmptyState title="No records yet" />
+      </OverviewPage>,
+      <DetailPage key="d" title="Record" parents={[{ label: "Records", to: "/records" }]}>
+        <Text>Lead paragraph.</Text>
+        <Divider />
+        <DetailList items={[{ label: "Owner", value: "Ada" }]} />
+      </DetailPage>,
+    ]) {
+      cleanup();
+      underContract(page);
+      // Per iteration, not once after the loop. Two separate faults met here and only the
+      // second one mattered. `Page` schedules its check as a setTimeout(0) and clears it on
+      // unmount while RTL's `cleanup` unmounts synchronously, so a single trailing assertion
+      // cancelled the OverviewPage timer and only ever reached the DetailPage. But moving the
+      // assertion inside the loop changed nothing on its own, because the assertion itself
+      // could not fail — see `expectAccepted`. Verified together: an illegal Grid in the
+      // OverviewPage body above is green under either old form and red under this one.
+      await expectAccepted();
+    }
+  });
+});

package/src/layoutContract.ts

@@ -36,9 +36,15 @@ export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
     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); Card is allowed in overview and detail bodies as the " +
-      "sanctioned visual separation between sections. A bespoke screen composes " +
+      "states), detail bodies are record sections (DetailList / Stack / Grid / Tabs " +
+      "+ framework states); Card is allowed in overview and detail bodies as the " +
+      "sanctioned visual separation between sections, and Divider / Text as a rule " +
+      "between sections and a lead paragraph above them. Three specialised shapes sit " +
+      "beside those: a form body is a container (Stack) with optional Grid / Card " +
+      "sections and no Field at the top level, so the body is always a container rather " +
+      "than a loose run of controls; a settings body is Card sections and holds no " +
+      "collection; and a split " +
+      "body is two SplitPanes and nothing else. A bespoke screen composes " +
       "the plain Page, which the contract deliberately leaves unconstrained.",
     slots: {
       HubPage: {
@@ -51,6 +57,8 @@ export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
           ModuleNav: "module-nav",
           Stack: "stack",
           Card: "card",
+          Divider: "divider",
+          Text: "text",
           EmptyState: "empty-state",
           ErrorState: "error-state",
           LoadingState: "loading-state",
@@ -58,6 +66,36 @@ export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
           ConfirmDialog: "dialog",
         },
       },
+      FormPage: {
+        components: {
+          Stack: "stack",
+          Grid: "grid",
+          Card: "card",
+          Divider: "divider",
+          Text: "text",
+          EmptyState: "empty-state",
+          ErrorState: "error-state",
+          LoadingState: "loading-state",
+          Alert: "alert",
+          ConfirmDialog: "dialog",
+        },
+      },
+      SettingsPage: {
+        components: {
+          Card: "card",
+          Stack: "stack",
+          Divider: "divider",
+          Text: "text",
+          EmptyState: "empty-state",
+          ErrorState: "error-state",
+          LoadingState: "loading-state",
+          Alert: "alert",
+          ConfirmDialog: "dialog",
+        },
+      },
+      SplitPage: {
+        components: { SplitPane: "splitpane" },
+      },
       DetailPage: {
         components: {
           DetailList: "detail-list",
@@ -66,6 +104,9 @@ export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
           ModuleNav: "module-nav",
           DataView: "dataview",
           Card: "card",
+          Grid: "grid",
+          Divider: "divider",
+          Text: "text",
           EmptyState: "empty-state",
           ErrorState: "error-state",
           LoadingState: "loading-state",