@starci/eslint-canon-fe 9.8.4 → 9.9.0

package/dist/skeleton-states.js

@@ -0,0 +1,230 @@
+import { defineRule } from "./lib/rule.js";
+const pathOf = (context) => context.filename.replaceAll("\\", "/");
+/** A hook that reads data for a view: under `hooks/`, and not the SWR layer that makes the reads (`hooks/swr`). */
+const isViewHook = (context) => {
+    const path = pathOf(context);
+    return /\/hooks\//.test(path) && !/\/hooks\/swr\//.test(path) && !/\.(?:spec|test)\.[cm]?tsx?$/.test(path);
+};
+const isApp = (context) => /\/(?:components|features|hooks)\//.test(pathOf(context)) && !/\.(?:spec|test|stories)\.[cm]?tsx?$/.test(pathOf(context));
+const unwrap = (node) => {
+    let current = node;
+    while (current && (current.type === "ChainExpression" || current.type === "TSNonNullExpression" || current.type === "TSAsExpression"))
+        current = current.expression;
+    return current;
+};
+/** The identifier at the root of `a.b?.c()` style access, or null. */
+const rootOf = (input) => {
+    let node = unwrap(input);
+    while (node) {
+        if (node.type === "Identifier")
+            return node;
+        if (node.type === "MemberExpression")
+            node = unwrap(node.object);
+        else if (node.type === "CallExpression")
+            node = unwrap(node.callee);
+        else
+            return null;
+    }
+    return null;
+};
+const enclosingFunction = (node) => {
+    for (let current = node.parent; current; current = current.parent) {
+        if (current.type === "ArrowFunctionExpression" || current.type === "FunctionDeclaration" || current.type === "FunctionExpression")
+            return current;
+    }
+    return null;
+};
+const nameOfKey = (key) => (key.type === "Identifier" ? key.name : key.type === "Literal" && typeof key.value === "string" ? key.value : null);
+// -- no-swr-default-array -----------------------------------------------------------------------------------
+/** Whether an identifier is bound to the result of a hook call (`const read = useX()`, `const { data } = useX()`): a read, not a plain value. */
+const isHookResult = (context, node, identifier) => {
+    for (let scope = context.sourceCode.getScope(node); scope; scope = scope.upper) {
+        const variable = scope.set.get(identifier.name);
+        if (!variable)
+            continue;
+        return variable.defs.some((definition) => {
+            const declarator = definition.node;
+            if (declarator.type !== "VariableDeclarator" || !declarator.init)
+                return false;
+            const init = unwrap(declarator.init);
+            const callee = init?.type === "CallExpression" ? unwrap(init.callee) : null;
+            const name = callee?.type === "Identifier" ? callee.name : callee?.type === "MemberExpression" && callee.property.type === "Identifier" ? callee.property.name : null;
+            return name !== null && /^use[A-Z]/.test(name);
+        });
+    }
+    return false;
+};
+const noSwrDefaultArray = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R367: a hook that folds a read to [] says whether that read is still loading." },
+        schema: [],
+        messages: {
+            fold: "FE_SWR_DEFAULT_ARRAY: `{{read}}` is folded to `[]` and this hook never returns `{{read}}.isLoading`, so the view cannot tell \"still loading\" from \"none\" and draws its empty state while the read is in flight (and a failed read as empty). Return the read's isLoading and error with the list, or return the read itself.",
+        },
+    },
+    create(context) {
+        if (!isViewHook(context))
+            return {};
+        const source = context.sourceCode;
+        return {
+            LogicalExpression(node) {
+                if (node.operator !== "??" || node.right.type !== "ArrayExpression" || node.right.elements.length > 0)
+                    return;
+                const root = rootOf(node.left);
+                if (!root || !isHookResult(context, node, root))
+                    return;
+                const fn = enclosingFunction(node);
+                if (!fn)
+                    return;
+                const text = source.getText(fn);
+                const escaped = root.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+                // The read's own status is read in the same hook: `read.isLoading`, or destructured next to `data`.
+                const readsStatus = new RegExp(`\\b${escaped}\\??\\.(?:isLoading|error|isError)\\b`).test(text)
+                    || new RegExp(`\\{[^}]*\\b(?:isLoading|error)\\b[^}]*\\}\\s*=\\s*${escaped}\\b`).test(text)
+                    || (root.name === "data" && /\bisLoading\b/.test(text));
+                if (readsStatus)
+                    return;
+                context.report({ node, messageId: "fold", data: { read: source.getText(node.left).slice(0, 40) } });
+            },
+        };
+    },
+});
+// -- no-foreign-slot-status ---------------------------------------------------------------------------------
+const SLOT_NAME = /slot$/i;
+const noForeignSlotStatus = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R367: a slot takes its loading and error from its own reads, never from another slot's." },
+        schema: [],
+        messages: {
+            foreign: "FE_FOREIGN_SLOT_STATUS: this slot copies `{{from}}` from another slot, so a region shows another read's loading or error (a list skeleton on a thread read, an error notice in the wrong pane). Build the slot from every read it draws with the one `slotOfReads(...)` helper of hooks/slot.",
+        },
+    },
+    create(context) {
+        if (!isApp(context))
+            return {};
+        const source = context.sourceCode;
+        return {
+            Property(node) {
+                const key = nameOfKey(node.key);
+                if (key !== "isLoading" && key !== "isError" && key !== "error")
+                    return;
+                const value = unwrap(node.value);
+                if (!value || value.type !== "MemberExpression")
+                    return;
+                const property = value.property.type === "Identifier" ? value.property.name : null;
+                const ownerNode = unwrap(value.object);
+                const owner = ownerNode?.type === "Identifier" ? ownerNode.name : ownerNode?.type === "MemberExpression" && ownerNode.property.type === "Identifier" ? ownerNode.property.name : null;
+                if (!property || !owner || !SLOT_NAME.test(owner) || (property !== "isLoading" && property !== "isError" && property !== "error"))
+                    return;
+                if (node.parent.type === "ObjectPattern")
+                    return;
+                context.report({ node, messageId: "foreign", data: { from: source.getText(value).slice(0, 40) } });
+            },
+        };
+    },
+});
+// -- no-validating-as-loading -------------------------------------------------------------------------------
+const LOADING_NAME = /^(?:isLoading|loading|isPending|status)$/;
+const mentionsValidating = (context, node) => /\bisValidating\b/.test(context.sourceCode.getText(node));
+const noValidatingAsLoading = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R367: a background refresh never drives a loading flag or a status." },
+        schema: [],
+        messages: {
+            validating: "FE_VALIDATING_AS_LOADING: `isValidating` is a background refresh, and it drives `{{name}}`, so the screen returns to its skeleton while the content it already has is being revalidated. A skeleton is `isLoading` (no data yet) alone; a refresh keeps the content.",
+        },
+    },
+    create(context) {
+        if (!isApp(context))
+            return {};
+        return {
+            Property(node) {
+                const key = nameOfKey(node.key);
+                if (key === null || !LOADING_NAME.test(key) || node.parent.type === "ObjectPattern")
+                    return;
+                if (mentionsValidating(context, node.value))
+                    context.report({ node, messageId: "validating", data: { name: key } });
+            },
+            VariableDeclarator(node) {
+                if (node.id.type !== "Identifier" || !LOADING_NAME.test(node.id.name) || !node.init)
+                    return;
+                if (mentionsValidating(context, node.init))
+                    context.report({ node, messageId: "validating", data: { name: node.id.name } });
+            },
+        };
+    },
+});
+// -- no-placeholder-object ----------------------------------------------------------------------------------
+const PLACEHOLDER = /Placeholder$/;
+const hasEmptyArray = (node) => node.properties.some((property) => property.type === "Property" && ((property.value.type === "ArrayExpression" && property.value.elements.length === 0)));
+const noPlaceholderObject = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R367: a loading placeholder is not the ready data with its lists emptied." },
+        schema: [],
+        messages: {
+            placeholder: "FE_PLACEHOLDER_OBJECT: `{{name}}` is the ready tree with its data stripped to `[]`: a second description of the real shape that drifts from it (a missing chip, a different row count). Let the component rest as itself with a loading flag.",
+        },
+    },
+    create(context) {
+        if (!isApp(context))
+            return {};
+        return {
+            Property(node) {
+                const key = nameOfKey(node.key);
+                if (key === null || !PLACEHOLDER.test(key) || node.parent.type === "ObjectPattern")
+                    return;
+                const value = unwrap(node.value);
+                if (value?.type === "ObjectExpression" && hasEmptyArray(value))
+                    context.report({ node, messageId: "placeholder", data: { name: key } });
+            },
+            VariableDeclarator(node) {
+                if (node.id.type !== "Identifier" || !PLACEHOLDER.test(node.id.name))
+                    return;
+                const init = unwrap(node.init);
+                if (init?.type === "ObjectExpression" && hasEmptyArray(init))
+                    context.report({ node, messageId: "placeholder", data: { name: node.id.name } });
+            },
+        };
+    },
+});
+// -- no-hand-skeleton ---------------------------------------------------------------------------------------
+const HAND_SKELETONS = new Set(["Skeleton", "ChatBubbleSkeletons", "MessageBubbleSkeletons"]);
+/** Published with the Grammar `isLoading` flag: the Grammar components draw their own loading structure. */
+export const noHandSkeleton = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R367: an app draws no skeleton by hand; the Grammar derives it from the ready structure." },
+        schema: [],
+        messages: {
+            hand: "FE_HAND_SKELETON: `<{{name}}>` is a skeleton drawn by hand, so its shape is a guess the ready screen will not keep. Pass the loading flag to the Grammar component and let it derive the skeleton from the structure it draws.",
+        },
+    },
+    create(context) {
+        if (!isApp(context))
+            return {};
+        return {
+            JSXOpeningElement(node) {
+                const name = node.name.type === "JSXIdentifier" ? node.name.name : null;
+                if (name !== null && HAND_SKELETONS.has(name))
+                    context.report({ node, messageId: "hand", data: { name } });
+            },
+        };
+    },
+});
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "no-swr-default-array": noSwrDefaultArray,
+    "no-foreign-slot-status": noForeignSlotStatus,
+    "no-validating-as-loading": noValidatingAsLoading,
+    "no-placeholder-object": noPlaceholderObject,
+    "no-hand-skeleton": noHandSkeleton,
+};
+/**
+ * The level this law asks for: every rule at error. `no-hand-skeleton` joined when the Grammar took the loading shape (`isLoading` on
+ * Section, the cards, ListBox, Timeline, DataTable, MessageBubble and PaneSection, with the `error` slot).
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));

package/dist/surface-rules.d.ts

@@ -1,6 +1,4 @@
 import { type Recommended } from "./lib/rule.js";
-/** ANATOMY-2: field variants belong to Grammar's context, including across app component boundaries. */
-export declare const nestedControlVariant: import("./lib/rule.js").Rule<"variant" | "tabs", []>;
 /** App classes carry layout; Grammar owns surface paint. */
 export declare const noAppSurfacePaint: import("./lib/rule.js").Rule<"surface", []>;
 /** PADDING-0: app padding wrappers cannot add a second horizontal inset to Grammar's list or section caption. */
@@ -9,11 +7,22 @@ export declare const noListPanelPadding: import("./lib/rule.js").Rule<"padding",
 export declare const dividerFullBleed: import("./lib/rule.js").Rule<"padding", []>;
 /** A multi-pane frame is a PaneGrid: a vertical divider between columns, or columns inside a joined card, is a pane frame drawn by hand. */
 export declare const noHandBuiltPanes: import("./lib/rule.js").Rule<"seam" | "joined", []>;
+/** A table is not placed in a SurfaceCard: plain rows are a `SurfaceCard kind="list"` with the note in its footer. */
+export declare const noTableInCard: import("./lib/rule.js").Rule<"table", []>;
+/** A page or pane command hugs its label and sits at the end of its header row: a Button in a header slot is never `width="fill"`. */
+export declare const noFillCommandInHeader: import("./lib/rule.js").Rule<"fill", []>;
+/** A TagGroup holds values the user entered (remove, reorder); a filter over a collection is a FilterButtonGroup. */
+export declare const noSelectableTagGroup: import("./lib/rule.js").Rule<"selection", []>;
+/** A card has a label by design: a Section holding one card is a hand heading over that card. */
+export declare const noHeadingAboveCard: import("./lib/rule.js").Rule<"name" | "header", []>;
 /** The surface laws ship at error in every composing source tree. */
 export declare const rules: {
     "divider-full-bleed": import("./lib/rule.js").Rule<"padding", []>;
-    "nested-control-variant": import("./lib/rule.js").Rule<"variant" | "tabs", []>;
     "no-hand-built-panes": import("./lib/rule.js").Rule<"seam" | "joined", []>;
+    "no-fill-command-in-header": import("./lib/rule.js").Rule<"fill", []>;
+    "no-selectable-tag-group": import("./lib/rule.js").Rule<"selection", []>;
+    "no-heading-above-card": import("./lib/rule.js").Rule<"name" | "header", []>;
+    "no-table-in-card": import("./lib/rule.js").Rule<"table", []>;
     "no-list-panel-padding": import("./lib/rule.js").Rule<"padding", []>;
     "no-app-surface-paint": import("./lib/rule.js").Rule<"surface", []>;
 };

package/dist/surface-rules.js

@@ -13,13 +13,9 @@ const memberName = (node) => (node.computed ? stringOf(node.property) : node.pro
 const present = (value) => Boolean(value);
 const GRAMMAR_ENTRY = /^@starci\/grammar(?:\/(?:common|core|offset-pop))?$/;
 const SURFACES = new Set([
-    "SurfaceCard", "SurfaceListCard", "SurfaceAccordionCard", "Sidebar",
+    "SurfaceCard", "Sidebar",
     "Dialog", "Drawer", "AlertDialog", "Popover",
-    "WorkspaceShell", "TopBar", "NavigationFeatureNav", "Pane", "PaneSection",
-]);
-const FIELDS = new Set([
-    "Input", "TextField", "Textarea", "TextArea", "SearchField", "NumberField", "DateField", "TimeField",
-    "Select", "ComboBox", "DatePicker", "DateRangePicker", "Checkbox", "CheckboxGroup", "RadioGroup", "PressableField", "OtpInput", "CopyField",
+    "WorkspaceShell", "TopBar", "Pane", "PaneSection",
 ]);
 const CLASS_BUILDERS = new Set(["cn", "clsx", "classNames", "cva", "tv"]);
 /** Resolve a JSX name to its Grammar export and optional compound parts, preserving lexical import identity. */
@@ -104,16 +100,6 @@ const isSurface = (context, node, descendant) => {
     const name = grammarName(context, node.name);
     if (name?.length !== 1)
         return false;
-    if (name[0] === "SurfaceAccordionCard") {
-        let frame = "painted";
-        for (const entry of node.attributes) {
-            const value = entry.type === "JSXSpreadAttribute" ? frameEffect(context, entry.argument, frame)
-                : entry.name.name === "frame" ? unpaintedFrame(context, attributeValue(entry)) ? "unpainted" : "painted" : "absent";
-            if (value !== "absent")
-                frame = value;
-        }
-        return frame !== "unpainted";
-    }
     if (name[0] === "WorkspaceShell") {
         for (let current = descendant; current && current !== node.parent; current = current.parent) {
             if (current.type === "JSXAttribute" && current.parent === node && current.name.name === "header")
@@ -202,45 +188,6 @@ const propStrings = (context, entry, name, mode = "classes") => {
     }
     return entry.name.name === name ? authoredStrings(context, attributeValue(entry), new Set(), mode) : [];
 };
-/** Only a fully known unpainted frame removes the accordion's bounded surface context. */
-const unpaintedFrame = (context, input, seen = new Set()) => {
-    const node = unwrap(input);
-    if (!node || seen.has(node))
-        return false;
-    seen.add(node);
-    const text = stringOf(node);
-    if (text !== null)
-        return text === "unpainted";
-    if (node.type === "ConditionalExpression")
-        return [node.consequent, node.alternate].every((branch) => unpaintedFrame(context, branch, new Set(seen)));
-    const values = node.type === "Identifier" ? bindingValues(context, node)
-        : node.type === "MemberExpression" ? propertyValues(context, node.object, memberName(node)) : [];
-    return values.length > 0 && values.every((value) => unpaintedFrame(context, value, new Set(seen)));
-};
-/** A spread overrides preceding frame props; an unresolved spread may install a bounded frame. */
-const frameEffect = (context, input, prior, seen = new Set()) => {
-    const node = unwrap(input);
-    if (!node || seen.has(node))
-        return "painted";
-    seen.add(node);
-    if (node.type === "ObjectExpression") {
-        let effect = prior;
-        for (const property of node.properties) {
-            const key = property.type === "Property" ? propertyName(context, property) : null;
-            const value = property.type === "SpreadElement" ? frameEffect(context, property.argument, effect, new Set(seen))
-                : key === "frame" ? unpaintedFrame(context, property.value) ? "unpainted" : "painted" : key === null ? "painted" : "absent";
-            if (value !== "absent")
-                effect = value;
-        }
-        return effect;
-    }
-    const values = node.type === "Identifier" ? bindingValues(context, node)
-        : node.type === "MemberExpression" ? propertyValues(context, node.object, memberName(node))
-            : node.type === "ConditionalExpression" ? [node.consequent, node.alternate] : [];
-    const effects = values.map((value) => frameEffect(context, value, prior, new Set(seen)));
-    const [first] = effects;
-    return first !== undefined && effects.every((effect) => effect === first) ? first : "painted";
-};
 /** Resolve authored style objects without treating unrelated object siblings or conditions as CSS. */
 const stylePaint = (context, input, seen = new Set()) => {
     const node = unwrap(input?.type === "JSXExpressionContainer" ? input.expression : input);
@@ -285,37 +232,6 @@ const inSectionCaption = (context, node) => {
     }
     return false;
 };
-/** ANATOMY-2: field variants belong to Grammar's context, including across app component boundaries. */
-export const nestedControlVariant = defineRule({
-    meta: {
-        type: "problem",
-        docs: { description: "ANATOMY-2: Grammar context supplies field variants; Tabs are the underline bar, never the pill." },
-        schema: [],
-        messages: {
-            variant: "FE_NESTED_VARIANT: app fields cannot set a static variant. Omit variant so Grammar's surface context supplies the appropriate default.",
-            tabs: "FE_NESTED_VARIANT: Tabs are the underline bar, their labels text on the content edge; variant=\"secondary\" is the pill, a filter's shape. Omit variant, or filter a collection with a selectable TagGroup.",
-        },
-    },
-    create(context) {
-        return {
-            JSXOpeningElement(node) {
-                const name = grammarName(context, node.name);
-                if (name?.length !== 1)
-                    return;
-                if (FIELDS.has(name[0])) {
-                    const variant = node.attributes.find((entry) => propStrings(context, entry, "variant", "variant").length > 0);
-                    if (variant)
-                        context.report({ node: variant, messageId: "variant" });
-                }
-                else if (name[0] === "Tabs") {
-                    const pill = node.attributes.find((entry) => propStrings(context, entry, "variant", "variant").some((value) => value.text === "secondary"));
-                    if (pill)
-                        context.report({ node: pill, messageId: "tabs" });
-                }
-            },
-        };
-    },
-});
 /** App classes carry layout; Grammar owns surface paint. */
 export const noAppSurfacePaint = exemptFreestyle(defineRule({
     meta: {
@@ -506,8 +422,8 @@ const elementsOfChild = (child) => {
 };
 /** The children that render: whitespace-only text and empty expressions are left out. */
 const renderedChildren = (element) => element.children.filter((child) => child.type === "JSXText" ? child.value.trim() !== "" : child.type !== "JSXExpressionContainer" || child.expression.type !== "JSXEmptyExpression");
-/** A column of a hand-built split: a plain block element (`div`, `aside`) or a Grammar `Region`. */
-const isColumn = (context, element) => rawElement(element.openingElement) || grammarName(context, element.openingElement.name)?.[0] === "Region";
+/** A column of a hand-built split: a plain block element (`div`, `aside`) or a Grammar `Section`. */
+const isColumn = (context, element) => rawElement(element.openingElement) || grammarName(context, element.openingElement.name)?.[0] === "Section";
 /** How a plain element lays out its children, read from its authored classes: `row`, `stack` (a column), `none` (not flex or grid), or `unknown` (no static class). */
 const flowOf = (context, opening) => {
     const texts = opening.attributes.flatMap((entry) => ["className", "class"].flatMap((name) => propStrings(context, entry, name).map((value) => value.text)));
@@ -595,7 +511,192 @@ export const noHandBuiltPanes = defineRule({
         };
     },
 });
+/** The capitalised same-file component a node renders inside (a declaration, a variable's function, or a wrapped one), or null. */
+const componentNameOf = (node) => {
+    for (let current = node.parent; current; current = current.parent) {
+        if (current.type === "FunctionDeclaration") {
+            if (current.id !== null && /^[A-Z]/.test(current.id.name))
+                return current.id.name;
+            continue;
+        }
+        if (current.type !== "ArrowFunctionExpression" && current.type !== "FunctionExpression")
+            continue;
+        const holder = current.parent.type === "CallExpression" ? current.parent.parent : current.parent;
+        if (holder.type === "VariableDeclarator" && holder.id.type === "Identifier" && /^[A-Z]/.test(holder.id.name))
+            return holder.id.name;
+    }
+    return null;
+};
+/** True when a SurfaceCard element encloses the node, or a component of this file that renders the node is itself rendered inside one. */
+const standsInCard = (context, node, seen) => {
+    for (let current = node.parent; current; current = current.parent) {
+        if (current.type !== "JSXElement")
+            continue;
+        const name = grammarName(context, current.openingElement.name);
+        if (name?.length === 1 && name[0] === "SurfaceCard")
+            return true;
+    }
+    const component = componentNameOf(node);
+    if (component === null || seen.has(component))
+        return false;
+    seen.add(component);
+    const usages = [];
+    walk(context.sourceCode, context.sourceCode.ast, (visited) => {
+        if (visited.type === "JSXOpeningElement" && visited.name.type === "JSXIdentifier" && visited.name.name === component)
+            usages.push(visited);
+    });
+    return usages.some((usage) => standsInCard(context, usage, seen));
+};
+/** A table is not placed in a SurfaceCard: plain rows are a `SurfaceCard kind="list"` with the note in its footer. */
+export const noTableInCard = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "A DataTable is not placed inside a SurfaceCard." },
+        schema: [],
+        messages: {
+            table: "FE_TABLE_IN_CARD: this DataTable stands inside a SurfaceCard (here or in the component that renders it). Plain rows with a few facts are a `SurfaceCard kind=\"list\"` with the label outside and the note in its `footer`; a table that compares records across many columns sits in its section with its label outside, with no card around it.",
+        },
+    },
+    create(context) {
+        return {
+            JSXOpeningElement(node) {
+                const name = grammarName(context, node.name);
+                if (name?.length !== 1 || name[0] !== "DataTable")
+                    return;
+                if (standsInCard(context, node, new Set()))
+                    context.report({ node, messageId: "table" });
+            },
+        };
+    },
+});
+/** The header slots whose command hugs its label: `PageHeader` `actions` and the `labelEnd` of a card or a list card. */
+const HEADER_SLOTS = new Map([
+    ["PageHeader", ["actions"]],
+    ["SurfaceCard", ["labelEnd"]],
+]);
+/** True when the Button's own opening element sets `width="fill"`. */
+const fillsWidth = (context, opening) => opening.attributes.some((entry) => propStrings(context, entry, "width", "variant").some((value) => value.text === "fill"));
+/** The header slot (`PageHeader actions`, `labelEnd`) a node is written in, or null. */
+const headerSlotOf = (context, node) => {
+    for (let current = node.parent; current; current = current.parent) {
+        if (current.type !== "JSXAttribute" || current.name.type !== "JSXIdentifier")
+            continue;
+        const owner = current.parent;
+        if (owner.type !== "JSXOpeningElement")
+            continue;
+        const name = grammarName(context, owner.name);
+        if (name?.length === 1 && name[0] !== undefined && HEADER_SLOTS.get(name[0])?.includes(current.name.name) === true)
+            return `${name[0]} ${current.name.name}`;
+    }
+    return null;
+};
+/** A page or pane command hugs its label and sits at the end of its header row: a Button in a header slot is never `width="fill"`. */
+export const noFillCommandInHeader = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "A command in a page or card header hugs its label." },
+        schema: [],
+        messages: {
+            fill: "FE_COMMAND_FILLS_HEADER: this Button is `width=\"fill\"` in {{slot}}. A page or pane command hugs its label and sits at the end of its header row; `width=\"fill\"` is for a form submit, an auth panel and a phone action bar (`PinnedActionBar`). Drop `width`.",
+        },
+    },
+    create(context) {
+        return {
+            JSXOpeningElement(node) {
+                const name = grammarName(context, node.name);
+                if (name?.length !== 1 || name[0] !== "Button" || !fillsWidth(context, node))
+                    return;
+                const slot = headerSlotOf(context, node);
+                if (slot !== null)
+                    context.report({ node, messageId: "fill", data: { slot } });
+            },
+        };
+    },
+});
+/** The props that made a TagGroup a selectable filter. */
+const TAG_SELECTION_PROPS = new Set(["selectionMode", "selectedIds", "defaultSelectedIds", "onSelectionChange"]);
+/** A TagGroup holds values the user entered (remove, reorder); a filter over a collection is a FilterButtonGroup. */
+export const noSelectableTagGroup = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "A TagGroup has no selection: a filter over a collection is a FilterButtonGroup." },
+        schema: [],
+        messages: {
+            selection: "FE_TAG_GROUP_SELECTION: a TagGroup holds values the user entered, to remove or to order, and has no selection. Peer values that filter a collection that stays in place are a `FilterButtonGroup` (`sm` toggle buttons on one row, the rest behind a \"+n\" search list).",
+        },
+    },
+    create(context) {
+        return {
+            JSXOpeningElement(node) {
+                const name = grammarName(context, node.name);
+                if (name?.length !== 1 || name[0] !== "TagGroup")
+                    return;
+                for (const entry of node.attributes) {
+                    if (entry.type === "JSXAttribute" && entry.name.type === "JSXIdentifier" && TAG_SELECTION_PROPS.has(entry.name.name))
+                        context.report({ node: entry, messageId: "selection" });
+                }
+            },
+        };
+    },
+});
+/** The bounded surfaces that carry their own label. */
+const LABELLED_CARDS = new Set(["SurfaceCard"]);
+/** The source text of a prop value, or null when the prop is absent: `"a"` and `{"a"}` read the same, an expression reads as written. */
+const propText = (context, opening, name) => {
+    const attribute = opening.attributes.find((entry) => entry.type === "JSXAttribute" && entry.name.type === "JSXIdentifier" && entry.name.name === name);
+    if (attribute === undefined || attribute.type !== "JSXAttribute" || attribute.value === null)
+        return null;
+    const value = attribute.value;
+    if (value.type === "Literal")
+        return String(value.value);
+    if (value.type === "JSXExpressionContainer" && value.expression.type !== "JSXEmptyExpression") {
+        const expression = value.expression;
+        return expression.type === "Literal" ? String(expression.value) : context.sourceCode.getText(expression);
+    }
+    return null;
+};
+/** The element children of a JSX parent, whitespace-only text and empty expressions left out. */
+const meaningfulChildren = (parent) => parent.children.filter((child) => !(child.type === "JSXText" && child.value.trim() === "") && !(child.type === "JSXExpressionContainer" && child.expression.type === "JSXEmptyExpression"));
+/** A card has a label by design: a Section holding one card is a hand heading over that card. */
+export const noHeadingAboveCard = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "A Section that holds a single card is a hand heading: the card has a label." },
+        schema: [],
+        messages: {
+            header: "FE_HEADING_ABOVE_CARD: this Section holds a single card, and a card has a label by design. Drop the Section: move its title to the card's `label`, the count to `fact`, the action to `labelEnd` and the note to `footer`. Several cards under one Section stay legal.",
+            name: "FE_HEADING_ABOVE_CARD: this card's `ariaLabel` repeats the title of the Section around it. Give the card that title as its `label` (count in `fact`, action in `labelEnd`, note in `footer`) and drop the Section.",
+        },
+    },
+    create(context) {
+        return {
+            JSXElement(element) {
+                const section = grammarName(context, element.openingElement.name);
+                if (section?.length !== 1 || section[0] !== "Section")
+                    return;
+                if (propText(context, element.openingElement, "kind") === "list")
+                    return;
+                const children = meaningfulChildren(element);
+                const cards = children.filter((child) => {
+                    if (child.type !== "JSXElement")
+                        return false;
+                    const name = grammarName(context, child.openingElement.name);
+                    return name?.length === 1 && name[0] !== undefined && LABELLED_CARDS.has(name[0]);
+                });
+                if (cards.length === 1 && children.length === 1)
+                    context.report({ node: element.openingElement, messageId: "header" });
+                const title = propText(context, element.openingElement, "title");
+                if (title === null)
+                    return;
+                for (const card of cards) {
+                    if (propText(context, card.openingElement, "ariaLabel") === title)
+                        context.report({ node: card.openingElement, messageId: "name" });
+                }
+            },
+        };
+    },
+});
 /** The surface laws ship at error in every composing source tree. */
-export const rules = { "divider-full-bleed": dividerFullBleed, "nested-control-variant": nestedControlVariant, "no-hand-built-panes": noHandBuiltPanes, "no-list-panel-padding": noListPanelPadding, "no-app-surface-paint": noAppSurfacePaint };
+export const rules = { "divider-full-bleed": dividerFullBleed, "no-hand-built-panes": noHandBuiltPanes, "no-fill-command-in-header": noFillCommandInHeader, "no-selectable-tag-group": noSelectableTagGroup, "no-heading-above-card": noHeadingAboveCard, "no-table-in-card": noTableInCard, "no-list-panel-padding": noListPanelPadding, "no-app-surface-paint": noAppSurfacePaint };
 /** No app can lower or omit a surface law. */
 export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));

package/dist/ui-rulings.js

@@ -81,7 +81,7 @@ export const noGrammarInternalSelector = defineRule({
         },
         schema: [],
         messages: {
-            internal: "Remove this starci-core- selector. Compose the Grammar public API; message actions belong in the ChatBubble floating toolbar.",
+            internal: "Remove this starci-core- selector. Compose the Grammar public API; message actions belong in the MessageBubble floating toolbar.",
         },
     },
     create(context) {

package/docs/button-intent.md

@@ -7,7 +7,6 @@ App `Button` and `IconButton` commands declare `intent`. Grammar derives their v
 | Rule | Finding code | Required behavior |
 | --- | --- | --- |
 | `starci-fe/button-intent-required` | `FE_BUTTON_INTENT_REQUIRED` | Pass the command's `intent`. A known props spread may supply it. |
-| `starci-fe/button-no-variant` | `FE_BUTTON_NO_VARIANT` | Omit `variant`, including variants in known props spreads. |
 | `starci-fe/destructive-confirm-in-dialog` | `FE_DESTRUCTIVE_CONFIRM_IN_DIALOG` | Put `intent="destructive" step="confirm"` inside the same-file `AlertDialog` or `ConfirmDialog` content subtree. Its trigger uses `step="entry"`. A separate component's definition does not inherit its caller's JSX ancestry. |
 | `starci-fe/single-commit-per-render` | `FE_SINGLE_COMMIT_PER_RENDER` | Render at most one commit per component path. Different return paths, opposite conditional arms and opposite guards are mutually exclusive. |
 | `starci-fe/no-commit-in-collection-item` | `FE_NO_COMMIT_IN_COLLECTION_ITEM` | Use `alternative` for an item's next action. A `.map` callback or explicit Grammar collection item context cannot expose commit. |

package/docs/size-and-state-budget.md

@@ -92,4 +92,4 @@ const UpdatedAt = () => <RelativeTime dateTime={instant} locale={locale} mode="r
 
 **Finding code:** `FE_SIZE_AND_STATE_BUDGET`
 
-**Fix:** Render the Grammar primitive and pass the instant; its single shared ticker owns updates and its deterministic fallback owns the server render.
+**Fix:** Render the Grammar RelativeTime leaf and pass the instant; its single shared ticker owns updates and its deterministic fallback owns the server render.