@terpjs/eslint-boundaries 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/eslint-boundaries",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Terp frontend boundary rules (as data) + the ESLint adapter: no cross-module imports, no package internals, design-token-only styling (no style/className/module stylesheets), token-styled components for raw HTML tags, router-only in-app links, generated-client-only, and browser XSS/navigation sink bans. Strict-only (no modes); governed opt-outs via terp-allow markers + the escape-hatch budget ratchet (terp-boundaries-budget).",
   "main": "./src/index.js",
@@ -25,7 +25,7 @@
     "typescript-eslint": "^8.20.0"
   },
   "devDependencies": {
-    "@terpjs/spec": "0.24.0",
+    "@terpjs/spec": "0.26.1",
     "eslint": "^10.8.0",
     "vitest": "^4.1.9"
   },

package/src/index.js

@@ -412,11 +412,16 @@ const styleImportMessage =
  * {@link catalogRuleId}). {@link restrictedSyntax} strips the tag for the ESLint config.
  */
 function restrictedSyntaxWithCatalogIds() {
-  const rawElements = Object.entries(BOUNDARY_SPEC.restrictedElements).map(([element, use]) => ({
-    catalogId: "frontend/token-styled-elements",
-    selector: `JSXOpeningElement[name.name='${element}']`,
-    message: `Use ${use} from @terpjs/react-core, not a raw <${element}>.`,
-  }));
+  const rawElements = Object.entries(BOUNDARY_SPEC.restrictedElements).map(([element, use]) => {
+    const guidance = BOUNDARY_SPEC.restrictedElementGuidance?.[element];
+    return {
+      catalogId: "frontend/token-styled-elements",
+      selector: `JSXOpeningElement[name.name='${element}']`,
+      message:
+        `Use ${use} from @terpjs/react-core, not a raw <${element}>.` +
+        (guidance === undefined ? "" : ` ${guidance}`),
+    };
+  });
   const rawAttributes = BOUNDARY_SPEC.restrictedAttributes.map((attribute) => ({
     catalogId: "frontend/no-inline-styling",
     selector: `JSXAttribute[name.name='${attribute}']`,

package/src/index.test.js

@@ -18,6 +18,12 @@ async function lint(code, filePath = MODULE_FILE) {
   return result.messages.map((message) => message.ruleId);
 }
 
+async function lintMessages(code, filePath = MODULE_FILE) {
+  const eslint = new ESLint({ overrideConfigFile: true, overrideConfig: terpBoundaries });
+  const [result] = await eslint.lintText(code, { filePath });
+  return result.messages.map((message) => message.message);
+}
+
 describe("terpBoundaries", () => {
   it("passes clean module code (react-core components + generated client)", async () => {
     const code = [
@@ -315,4 +321,22 @@ describe("terpBoundaries", () => {
     const code = ["/* eslint-disable */", "export const W = () => <button>x</button>;"].join("\n");
     expect(await lint(code)).toContain("no-restricted-syntax");
   });
+
+  it("the dialog refusal says what to do instead of naming only ConfirmDialog", async () => {
+    // "Use ConfirmDialog" is right for a confirmation and wrong advice for an edit form,
+    // and an author who reads it for one concludes the rule cannot be obeyed. The reported
+    // evidence was an app that built the editor in an expanded row instead and recorded
+    // that as the better outcome — so the refusal carries that guidance, rather than the
+    // framework shipping a general modal whose absence produced the better UI.
+    const messages = await lintMessages("export const W = () => <dialog>x</dialog>;");
+    const refusal = messages.find((message) => message.includes("<dialog>"));
+    expect(refusal).toContain("ConfirmDialog");
+    expect(refusal).toContain("routed page");
+    expect(refusal).toContain("expanded row");
+  });
+
+  it("an element with no extra guidance keeps the plain one-line refusal", async () => {
+    const messages = await lintMessages("export const W = () => <button>x</button>;");
+    expect(messages).toContain("Use Button from @terpjs/react-core, not a raw <button>.");
+  });
 });

package/src/layouts.js

@@ -35,9 +35,15 @@ export const LAYOUT_CONTRACTS = {
     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: {
@@ -50,6 +56,8 @@ export const LAYOUT_CONTRACTS = {
           ModuleNav: "module-nav",
           Stack: "stack",
           Card: "card",
+          Divider: "divider",
+          Text: "text",
           EmptyState: "empty-state",
           ErrorState: "error-state",
           LoadingState: "loading-state",
@@ -57,6 +65,36 @@ export const LAYOUT_CONTRACTS = {
           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",
@@ -65,6 +103,9 @@ export const LAYOUT_CONTRACTS = {
           ModuleNav: "module-nav",
           DataView: "dataview",
           Card: "card",
+          Grid: "grid",
+          Divider: "divider",
+          Text: "text",
           EmptyState: "empty-state",
           ErrorState: "error-state",
           LoadingState: "loading-state",

package/src/spec.js

@@ -15,7 +15,7 @@
  * NOT by this package's own suite, which certification runs against candidate spec releases
  * whose version is allowed to be newer).
  */
-export const SPEC_VERSION = "0.24.0";
+export const SPEC_VERSION = "0.26.1";
 
 export const BOUNDARY_SPEC = {
   /** App module files the boundary + frontend security defaults apply to. */
@@ -38,6 +38,42 @@ export const BOUNDARY_SPEC = {
    * react-core components (`Stack` for layout), never ad-hoc per screen. `className` would be
    * a side channel into hand-authored CSS, so it is refused alongside `style`.
    */
+  /**
+   * Extra guidance for an element whose named replacement does not fit every case, so the
+   * refusal states what to do instead of implying something is missing.
+   *
+   * The criterion: a restricted element earns a sentence here when its named replacement is
+   * right for some cases and actively misleading for others, so that an author who reads the
+   * bare rule concludes the framework ships nothing for their case. Two elements meet it.
+   *
+   * `dialog` was the first. The replacement is `ConfirmDialog`, which is right for a
+   * confirmation and wrong advice for anything else — an author who reads "use ConfirmDialog"
+   * for an edit form concludes the framework ships no dialog and the rule cannot be obeyed.
+   * The guidance below is what a reporting app arrived at on its own, and recorded as the
+   * better outcome: the editor moved into an expanded row, so the finding that sent the author
+   * there stayed on screen while they fixed it.
+   *
+   * `table` is the second (ADR 0099 §4). "Use DataView" reads as disproportionate for five
+   * static rows unless the sentence names the two-line recipe, so it does.
+   */
+  restrictedElementGuidance: {
+    dialog:
+      "A modal is for a confirmation (ConfirmDialog) or an explicit post-action moment. " +
+      "An edit form or a detail view belongs in a routed page, or in an expanded row " +
+      "beside the thing it edits — which keeps the context that sent the author there on " +
+      "screen. If you have a case neither covers, say so rather than reaching for a raw " +
+      "<dialog>: the modal contract (focus trap, focus restore, Escape, top layer) is " +
+      "what ConfirmDialog exists to provide and a hand-rolled one silently drops.",
+    table:
+      "Use DataView, and if it looks like too much for five static rows, the recipe is " +
+      "two lines: variant=\"embedded\" drops the view toggle, the page-size selector and " +
+      "the footer, and InMemoryDataViewRepository needs two functions: getRowId and " +
+      "getValue. That is worth " +
+      "saying because \"use DataView\" on its own reads as wrong advice here, and an " +
+      "author who believes it reaches for a raw <table> — which silently gives up " +
+      "sorting, column resizing and settings, the mobile card reflow and the row-level " +
+      "activation the rest of the app has.",
+  },
   restrictedAttributes: ["style", "className"],
   /**
    * Raw in-app anchors (`<a href="/...">`) bypass the router (full reload, no role-aware

package/src/surface.test.js

@@ -44,6 +44,22 @@ describe("structural parity: BOUNDARY_SPEC realises exactly the declared surface
     );
   });
 
+  it("every guidance sentence belongs to an element that is actually restricted", () => {
+    // ADR 0099 §4 makes the WORDING a control: a restricted element whose named replacement is
+    // right for some cases and wrong advice for others gets a sentence naming the recipe. A
+    // sentence keyed to an element nobody restricts is never emitted, so it reads as shipped
+    // guidance while being unreachable — and nothing else here would notice, because the two
+    // objects are only ever read one key at a time at lint time.
+    const guided = Object.keys(BOUNDARY_SPEC.restrictedElementGuidance).sort();
+    const restricted = Object.keys(BOUNDARY_SPEC.restrictedElements);
+    expect(guided.filter((element) => !restricted.includes(element))).toEqual([]);
+    // And the sentences are non-empty: an empty string is falsy, so it would silently fall back
+    // to the bare refusal at the call site.
+    for (const element of guided) {
+      expect(BOUNDARY_SPEC.restrictedElementGuidance[element].length).toBeGreaterThan(0);
+    }
+  });
+
   it("restricted attributes match", () => {
     expect([...BOUNDARY_SPEC.restrictedAttributes].sort()).toEqual(
       [...SURFACE.restrictedAttributes].sort(),