@terpjs/eslint-boundaries 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/eslint-boundaries",
-  "version": "0.8.0",
+  "version": "0.9.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.25.0",
     "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/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.25.0";
 
 export const BOUNDARY_SPEC = {
   /** App module files the boundary + frontend security defaults apply to. */
@@ -38,6 +38,26 @@ 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.
+   *
+   * `dialog` is the one that needed it. The replacement is `ConfirmDialog`, which is right
+   * for a confirmation and wrong advice for anything else — and an author who reads "use
+   * ConfirmDialog" for an edit form concludes the framework ships no dialog and that 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.
+   */
+  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.",
+  },
   restrictedAttributes: ["style", "className"],
   /**
    * Raw in-app anchors (`<a href="/...">`) bypass the router (full reload, no role-aware