@starci/eslint-canon-fe 9.8.5 → 9.9.2

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,18 +7,17 @@ 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 SurfaceListCard with the note in its footer. */
+/** 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 SectionHeader above it is a hand heading. */
+/** 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", []>;

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)));
@@ -631,14 +547,14 @@ const standsInCard = (context, node, seen) => {
     });
     return usages.some((usage) => standsInCard(context, usage, seen));
 };
-/** A table is not placed in a SurfaceCard: plain rows are a SurfaceListCard with the note in its footer. */
+/** 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 `SurfaceListCard` of `ListRow` 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.",
+            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) {
@@ -657,7 +573,6 @@ export const noTableInCard = defineRule({
 const HEADER_SLOTS = new Map([
     ["PageHeader", ["actions"]],
     ["SurfaceCard", ["labelEnd"]],
-    ["SurfaceListCard", ["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"));
@@ -725,7 +640,7 @@ export const noSelectableTagGroup = defineRule({
     },
 });
 /** The bounded surfaces that carry their own label. */
-const LABELLED_CARDS = new Set(["SurfaceCard", "SurfaceListCard", "SurfaceAccordionCard"]);
+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);
@@ -742,54 +657,46 @@ const propText = (context, opening, name) => {
 };
 /** 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 SectionHeader above it is a hand heading. */
+/** 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 SectionHeader directly above a single card is a hand heading: the card has a label." },
+        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 SectionHeader is directly followed by a single card, and a card has a label by design. Move the title to the card's `label`, the count to `fact`, the action to `labelEnd` and the note to `footer`. Several cards under one header stay legal.",
-            name: "FE_HEADING_ABOVE_CARD: this card's `ariaLabel` repeats the title of the SectionHeader above it. Give the card that title as its `label` (count in `fact`, action in `labelEnd`, note in `footer`) and drop the header.",
+            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) {
-        const check = (parent) => {
-            const children = meaningfulChildren(parent);
-            children.forEach((child, index) => {
-                if (child.type !== "JSXElement")
+        return {
+            JSXElement(element) {
+                const section = grammarName(context, element.openingElement.name);
+                if (section?.length !== 1 || section[0] !== "Section")
                     return;
-                const header = grammarName(context, child.openingElement.name);
-                if (header?.length !== 1 || header[0] !== "SectionHeader")
+                if (propText(context, element.openingElement, "kind") === "list")
                     return;
-                const cards = [];
-                for (let next = index + 1; next < children.length; next += 1) {
-                    const sibling = children[next];
-                    if (sibling === undefined || sibling.type !== "JSXElement")
-                        break;
-                    const name = grammarName(context, sibling.openingElement.name);
-                    if (name?.length !== 1 || name[0] === undefined || !LABELLED_CARDS.has(name[0]))
-                        break;
-                    cards.push(sibling);
-                }
-                if (cards.length === 1)
-                    context.report({ node: child.openingElement, messageId: "header" });
-                const title = propText(context, child.openingElement, "title");
+                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" });
                 }
-            });
-        };
-        return {
-            JSXElement: check,
-            JSXFragment: check,
+            },
         };
     },
 });
 /** 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-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 };
+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.

package/docs/surface-rules.md

@@ -2,24 +2,6 @@
 
 Law module: `surface-rules.mjs`. HFS rule: R318. Canon: ANATOMY-2 and PADDING-0.
 
-## `starci-fe/nested-control-variant`
-
-Finding code: `FE_NESTED_VARIANT`. Grammar context supplies field variants on the page background and inside painted surfaces. App code omits every static `variant` on layer-aware fields, including fields rendered by imported or helper components. Named import aliases, namespace imports, static constants and props spreads preserve Grammar ownership. `Tabs` are the underline bar everywhere, their labels text on the content edge, so the pill (`variant="secondary"`) is refused wherever it is set: a pill is a filter's shape, and a filter over a collection is a selectable `TagGroup`.
-
-Invalid:
-
-```tsx
-import { SearchField } from "@starci/grammar/core"
-const Search = () => <SearchField variant="secondary" />
-```
-
-Valid:
-
-```tsx
-import { SurfaceCard, SearchField } from "@starci/grammar/core"
-const Panel = () => <SurfaceCard><SearchField /></SurfaceCard>
-```
-
 ## `starci-fe/no-app-surface-paint`
 
 Finding code: `FE_GRAMMAR_LAYOUT_ONLY`. App classes carry layout. A raw `bg-surface` utility paints a surface and is refused, including conditional classes, class builders, responsive variants, important modifiers and opacity suffixes. Compose a painted Grammar surface such as `SurfaceCard`. Static props spreads keep the same obligations. Typed app lint follows imported colocated class declarations as well as local constants.
@@ -77,7 +59,7 @@ const Frame = () => (
 
 ## `starci-fe/no-table-in-card`
 
-Finding code: `FE_TABLE_IN_CARD` (R351). A `DataTable` is not placed in a `SurfaceCard`. Plain rows with a few facts are a `SurfaceListCard` of `ListRow` with the label outside and the note in its `footer`; a table that compares records across many columns sits in its section with no card around it. The rule reads the file: a Grammar `DataTable` enclosed by a Grammar `SurfaceCard` element is a finding, and so is a `DataTable` rendered by a component of the same file (a declaration, a variable's function, a `memo` or `forwardRef` wrapper, followed through other components of the file) that a `SurfaceCard` encloses. A card in another file that renders a table component is judged where the card is written. There is no inline exemption; a table the owner rules complex enough to sit in a card is named in this rule.
+Finding code: `FE_TABLE_IN_CARD` (R351). A `DataTable` is not placed in a `SurfaceCard`. 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 no card around it. The rule reads the file: a Grammar `DataTable` enclosed by a Grammar `SurfaceCard` element is a finding, and so is a `DataTable` rendered by a component of the same file (a declaration, a variable's function, a `memo` or `forwardRef` wrapper, followed through other components of the file) that a `SurfaceCard` encloses. A card in another file that renders a table component is judged where the card is written. There is no inline exemption; a table the owner rules complex enough to sit in a card is named in this rule.
 
 Invalid:
 
@@ -95,17 +77,21 @@ const Rules = () => (
 Valid:
 
 ```tsx
-import { SurfaceListCard, ListRow } from "@starci/grammar/core"
+import { SurfaceCard } from "@starci/grammar/core"
 const Rules = () => (
-  <SurfaceListCard label="Rules" footer={footnote}>
-    {rules.map((rule) => <ListRow key={rule.id} title={rule.title} description={rule.summary} />)}
-  </SurfaceListCard>
+  <SurfaceCard
+    kind="list"
+    label="Rules"
+    footer={footnote}
+    items={rules.map((rule) => ({ id: rule.id, title: rule.title, description: rule.summary }))}
+    empty={<EmptyNotice message="No rules." />}
+  />
 )
 ```
 
 ## `starci-fe/no-fill-command-in-header`
 
-Finding code: `FE_COMMAND_FILLS_HEADER` (R352). A page or pane command hugs its label and sits at the end of its header row: a Grammar `Button` with `width="fill"` written in the `actions` of a `PageHeader` or in the `labelEnd` of a `SurfaceCard` or `SurfaceListCard` is refused. `width="fill"` is for a form submit, an auth panel and a phone action bar (`PinnedActionBar`); the rule judges the header slots only, since a form, an auth panel and a phone action bar are not decidable from the file.
+Finding code: `FE_COMMAND_FILLS_HEADER` (R352). A page or pane command hugs its label and sits at the end of its header row: a Grammar `Button` with `width="fill"` written in the `actions` of a `PageHeader` or in the `labelEnd` of a `SurfaceCard` is refused. `width="fill"` is for a form submit, an auth panel and a phone action bar (`PinnedActionBar`); the rule judges the header slots only, since a form, an auth panel and a phone action bar are not decidable from the file.
 
 Invalid:
 
@@ -141,24 +127,23 @@ const Filter = () => <FilterButtonGroup label="Team" options={options} value={te
 
 ## `starci-fe/no-heading-above-card`
 
-Finding code: `FE_HEADING_ABOVE_CARD` (R354). A card has a label by design (ruling `card-carries-its-own-label`), so a hand heading above it is wrong. A Grammar `SectionHeader` directly followed, in the same parent, by one `SurfaceCard`, `SurfaceListCard` or `SurfaceAccordionCard` is refused, and so is a card whose `ariaLabel` is the header's `title`. Several cards under one header stay legal, and a header followed by anything else is not judged. The fix moves the title to the card's `label`, the count to `fact`, the action to `labelEnd` and the note to `footer`.
+Finding code: `FE_HEADING_ABOVE_CARD` (R354). A card has a label by design (ruling `card-carries-its-own-label`), so a heading over it is wrong. A Grammar `Section` (not `kind="list"`) whose only child is one `SurfaceCard` is refused, and so is a card whose `ariaLabel` is the `Section`'s `title`. Several cards under one `Section` stay legal, and a `Section` holding anything else is not judged. The fix moves the title to the card's `label`, the count to `fact`, the action to `labelEnd` and the note to `footer`.
 
 Invalid:
 
 ```tsx
-import { SectionHeader, SurfaceListCard } from "@starci/grammar/core"
+import { Section, SurfaceCard } from "@starci/grammar/core"
 const Rules = () => (
-  <section>
-    <SectionHeader title="Rules" count={3} action={add} />
-    <SurfaceListCard ariaLabel="Rules">{rows}</SurfaceListCard>
-  </section>
+  <Section title="Rules" count={3} action={add}>
+    <SurfaceCard kind="list" ariaLabel="Rules" items={items} empty={empty} />
+  </Section>
 )
 ```
 
 Valid:
 
 ```tsx
-import { SurfaceListCard } from "@starci/grammar/core"
-const Rules = () => <SurfaceListCard label="Rules" fact="3" labelEnd={add} footer={note}>{rows}</SurfaceListCard>
+import { SurfaceCard } from "@starci/grammar/core"
+const Rules = () => <SurfaceCard kind="list" label="Rules" fact="3" labelEnd={add} footer={note} items={items} empty={empty} />
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.8.5",
+  "version": "9.9.2",
   "description": "Universal front-end lint laws for TypeScript and Next.js, independent of the selected Grammar family.",
   "type": "module",
   "license": "MIT",