stablekit.ts 0.2.3 → 0.3.1

package/README.md

@@ -202,6 +202,31 @@ For CSP nonce support:
 <meta name="stablekit-nonce" content="your-nonce-here" />
 ```
 
+## Out of Scope: Font-Swap CLS
+
+StableKit solves **structural** layout shifts — conditional mounting, dynamic content sizing, state-driven geometry changes. These are DOM structure problems that React components can fix.
+
+Font-swap CLS is a different beast. When a web font loads and replaces the fallback font, the browser re-renders text with different metrics. This is a **typographic metrics** problem, not a DOM structure problem. No React component can pre-allocate geometry for a font that hasn't been downloaded yet — the browser doesn't know the dimensions until the font file arrives.
+
+To fix font-swap CLS, use CSS `@font-face` metric overrides:
+
+```css
+@font-face {
+  font-family: "Inter Fallback";
+  src: local("Arial");
+  size-adjust: 107%;
+  ascent-override: 90%;
+  descent-override: 22%;
+  line-gap-override: 0%;
+}
+
+body {
+  font-family: "Inter", "Inter Fallback", sans-serif;
+}
+```
+
+Tools like [Capsize](https://seek-oss.github.io/capsize/), [Fontaine](https://github.com/unjs/fontaine), and `next/font` generate these overrides automatically.
+
 ## License
 
 MIT

package/dist/eslint.cjs

@@ -23,11 +23,72 @@ __export(eslint_exports, {
   createArchitectureLint: () => createArchitectureLint
 });
 module.exports = __toCommonJS(eslint_exports);
+function findVariable(scope, name) {
+  let current = scope;
+  while (current) {
+    const variable = current.set.get(name);
+    if (variable) return variable;
+    current = current.upper;
+  }
+  return null;
+}
+var noLoadingConflictRule = {
+  meta: {
+    type: "problem",
+    schema: [
+      {
+        type: "object",
+        properties: {
+          passthrough: { type: "array", items: { type: "string" } }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      conflict: "Conditional variable as children of a component with a loading prop. The loading prop triggers an internal content swap \u2014 if children also change, both sides shrink simultaneously and pre-allocation is defeated. Use static children with the loading prop, or handle the entire swap explicitly with <StateSwap> in the caller."
+    }
+  },
+  create(context) {
+    const passthrough = context.options[0]?.passthrough ?? [];
+    return {
+      JSXElement(node) {
+        const opening = node.openingElement;
+        if (opening.name?.type !== "JSXIdentifier") return;
+        const name = opening.name.name;
+        if (!/^[A-Z]/.test(name)) return;
+        if (passthrough.includes(name)) return;
+        const hasLoading = opening.attributes.some(
+          (attr) => attr.type === "JSXAttribute" && attr.name?.name === "loading"
+        );
+        if (!hasLoading) return;
+        for (const child of node.children) {
+          if (child.type !== "JSXExpressionContainer") continue;
+          const expr = child.expression;
+          if (expr.type !== "Identifier") continue;
+          const scope = context.sourceCode ? context.sourceCode.getScope(node) : context.getScope();
+          const variable = findVariable(scope, expr.name);
+          if (!variable) continue;
+          for (const def of variable.defs) {
+            if (def.type === "Parameter") continue;
+            if (def.type === "Variable" && def.node.init) {
+              const initType = def.node.init.type;
+              if (initType === "ConditionalExpression" || initType === "LogicalExpression" || initType === "TemplateLiteral") {
+                context.report({ node: expr, messageId: "conflict" });
+              }
+            }
+          }
+        }
+      }
+    };
+  }
+};
 function createArchitectureLint(options) {
   const {
     stateTokens,
     variantProps = [],
     banColorUtilities = true,
+    classNamePassthrough = [],
+    loadingPassthrough = ["LoadingBoundary"],
     files = ["src/components/**/*.{tsx,jsx}"]
   } = options;
   const tokenPattern = stateTokens.join("|");
@@ -146,8 +207,28 @@ function createArchitectureLint(options) {
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > TemplateLiteral",
           message: "Interpolated text in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven values, use <StableCounter> for numbers or <StateSwap> for text variants."
+        },
+        // --- 5. className on custom components ---
+        ...classNamePassthrough.length ? [
+          {
+            selector: `JSXOpeningElement[name.name=/^[A-Z]/]:not([name.name=/^(${classNamePassthrough.join("|")})$/]) > JSXAttribute[name.name='className']`,
+            message: "className on a custom component. Components own their own styling \u2014 use a data-attribute, variant prop, or CSS class internally instead of passing Tailwind utilities from the consumer."
+          }
+        ] : [
+          {
+            selector: "JSXOpeningElement[name.name=/^[A-Z]/] > JSXAttribute[name.name='className']",
+            message: "className on a custom component. Components own their own styling \u2014 use a data-attribute, variant prop, or CSS class internally instead of passing Tailwind utilities from the consumer."
+          }
+        ]
+      ],
+      "stablekit/no-loading-conflict": ["error", { passthrough: loadingPassthrough }]
+    },
+    plugins: {
+      stablekit: {
+        rules: {
+          "no-loading-conflict": noLoadingConflictRule
         }
-      ]
+      }
     }
   };
 }

package/dist/eslint.d.cts

@@ -25,6 +25,17 @@
  *    and interpolated template literals. Each message guides toward
  *    extracting the expression to a variable (for data transforms) or
  *    using a StableKit component (for state-driven swaps). Always on.
+ *
+ * 5. className on custom components — passing className to a PascalCase
+ *    component is a presentation leak across the Structure boundary.
+ *    The component should own its own styling. Always on.
+ *
+ * 6. Dual-paradigm conflict (custom rule with scope analysis) — a component
+ *    with a `loading` prop does internal content swapping (StateSwap). If
+ *    children are a variable derived from a conditional expression, both
+ *    sides of the swap change simultaneously, defeating pre-allocation.
+ *    Only flags locals initialized with ternaries/logical expressions.
+ *    Props (function parameters) are allowed — they're static per mount.
  */
 interface ArchitectureLintOptions {
     /** State token names that should never appear in JS as Tailwind classes.
@@ -38,6 +49,16 @@ interface ArchitectureLintOptions {
      *  Colors must live in CSS — not in component classNames.
      *  @default true */
     banColorUtilities?: boolean;
+    /** Components that transparently pass className to their root element.
+     *  These are excluded from the className-on-component ban.
+     *  e.g. ["StableText", "StableCounter", "MediaSkeleton", "ChevronDown"]
+     *  @default [] */
+    classNamePassthrough?: string[];
+    /** Components where `loading` prop does NOT trigger a content swap
+     *  (e.g. LoadingBoundary controls opacity, not geometry).
+     *  These are excluded from the dual-paradigm conflict rule.
+     *  @default ["LoadingBoundary"] */
+    loadingPassthrough?: string[];
     /** Glob patterns for files to lint.
      *  @default ["src/components/**\/*.{tsx,jsx}"] */
     files?: string[];
@@ -49,6 +70,16 @@ declare function createArchitectureLint(options: ArchitectureLintOptions): {
             selector: string;
             message: string;
         })[];
+        "stablekit/no-loading-conflict": (string | {
+            passthrough: string[];
+        })[];
+    };
+    plugins: {
+        stablekit: {
+            rules: {
+                "no-loading-conflict": any;
+            };
+        };
     };
 };
 

package/dist/eslint.d.ts

@@ -25,6 +25,17 @@
  *    and interpolated template literals. Each message guides toward
  *    extracting the expression to a variable (for data transforms) or
  *    using a StableKit component (for state-driven swaps). Always on.
+ *
+ * 5. className on custom components — passing className to a PascalCase
+ *    component is a presentation leak across the Structure boundary.
+ *    The component should own its own styling. Always on.
+ *
+ * 6. Dual-paradigm conflict (custom rule with scope analysis) — a component
+ *    with a `loading` prop does internal content swapping (StateSwap). If
+ *    children are a variable derived from a conditional expression, both
+ *    sides of the swap change simultaneously, defeating pre-allocation.
+ *    Only flags locals initialized with ternaries/logical expressions.
+ *    Props (function parameters) are allowed — they're static per mount.
  */
 interface ArchitectureLintOptions {
     /** State token names that should never appear in JS as Tailwind classes.
@@ -38,6 +49,16 @@ interface ArchitectureLintOptions {
      *  Colors must live in CSS — not in component classNames.
      *  @default true */
     banColorUtilities?: boolean;
+    /** Components that transparently pass className to their root element.
+     *  These are excluded from the className-on-component ban.
+     *  e.g. ["StableText", "StableCounter", "MediaSkeleton", "ChevronDown"]
+     *  @default [] */
+    classNamePassthrough?: string[];
+    /** Components where `loading` prop does NOT trigger a content swap
+     *  (e.g. LoadingBoundary controls opacity, not geometry).
+     *  These are excluded from the dual-paradigm conflict rule.
+     *  @default ["LoadingBoundary"] */
+    loadingPassthrough?: string[];
     /** Glob patterns for files to lint.
      *  @default ["src/components/**\/*.{tsx,jsx}"] */
     files?: string[];
@@ -49,6 +70,16 @@ declare function createArchitectureLint(options: ArchitectureLintOptions): {
             selector: string;
             message: string;
         })[];
+        "stablekit/no-loading-conflict": (string | {
+            passthrough: string[];
+        })[];
+    };
+    plugins: {
+        stablekit: {
+            rules: {
+                "no-loading-conflict": any;
+            };
+        };
     };
 };
 

package/dist/eslint.js

@@ -1,9 +1,70 @@
 // src/eslint.ts
+function findVariable(scope, name) {
+  let current = scope;
+  while (current) {
+    const variable = current.set.get(name);
+    if (variable) return variable;
+    current = current.upper;
+  }
+  return null;
+}
+var noLoadingConflictRule = {
+  meta: {
+    type: "problem",
+    schema: [
+      {
+        type: "object",
+        properties: {
+          passthrough: { type: "array", items: { type: "string" } }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      conflict: "Conditional variable as children of a component with a loading prop. The loading prop triggers an internal content swap \u2014 if children also change, both sides shrink simultaneously and pre-allocation is defeated. Use static children with the loading prop, or handle the entire swap explicitly with <StateSwap> in the caller."
+    }
+  },
+  create(context) {
+    const passthrough = context.options[0]?.passthrough ?? [];
+    return {
+      JSXElement(node) {
+        const opening = node.openingElement;
+        if (opening.name?.type !== "JSXIdentifier") return;
+        const name = opening.name.name;
+        if (!/^[A-Z]/.test(name)) return;
+        if (passthrough.includes(name)) return;
+        const hasLoading = opening.attributes.some(
+          (attr) => attr.type === "JSXAttribute" && attr.name?.name === "loading"
+        );
+        if (!hasLoading) return;
+        for (const child of node.children) {
+          if (child.type !== "JSXExpressionContainer") continue;
+          const expr = child.expression;
+          if (expr.type !== "Identifier") continue;
+          const scope = context.sourceCode ? context.sourceCode.getScope(node) : context.getScope();
+          const variable = findVariable(scope, expr.name);
+          if (!variable) continue;
+          for (const def of variable.defs) {
+            if (def.type === "Parameter") continue;
+            if (def.type === "Variable" && def.node.init) {
+              const initType = def.node.init.type;
+              if (initType === "ConditionalExpression" || initType === "LogicalExpression" || initType === "TemplateLiteral") {
+                context.report({ node: expr, messageId: "conflict" });
+              }
+            }
+          }
+        }
+      }
+    };
+  }
+};
 function createArchitectureLint(options) {
   const {
     stateTokens,
     variantProps = [],
     banColorUtilities = true,
+    classNamePassthrough = [],
+    loadingPassthrough = ["LoadingBoundary"],
     files = ["src/components/**/*.{tsx,jsx}"]
   } = options;
   const tokenPattern = stateTokens.join("|");
@@ -122,8 +183,28 @@ function createArchitectureLint(options) {
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > TemplateLiteral",
           message: "Interpolated text in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven values, use <StableCounter> for numbers or <StateSwap> for text variants."
+        },
+        // --- 5. className on custom components ---
+        ...classNamePassthrough.length ? [
+          {
+            selector: `JSXOpeningElement[name.name=/^[A-Z]/]:not([name.name=/^(${classNamePassthrough.join("|")})$/]) > JSXAttribute[name.name='className']`,
+            message: "className on a custom component. Components own their own styling \u2014 use a data-attribute, variant prop, or CSS class internally instead of passing Tailwind utilities from the consumer."
+          }
+        ] : [
+          {
+            selector: "JSXOpeningElement[name.name=/^[A-Z]/] > JSXAttribute[name.name='className']",
+            message: "className on a custom component. Components own their own styling \u2014 use a data-attribute, variant prop, or CSS class internally instead of passing Tailwind utilities from the consumer."
+          }
+        ]
+      ],
+      "stablekit/no-loading-conflict": ["error", { passthrough: loadingPassthrough }]
+    },
+    plugins: {
+      stablekit: {
+        rules: {
+          "no-loading-conflict": noLoadingConflictRule
         }
-      ]
+      }
     }
   };
 }

package/llms.txt

@@ -317,6 +317,19 @@ change to structure requires editing `.css`, a boundary has leaked.
      or use a StableKit component (for state-driven swaps — StateSwap,
      LayoutMap, LoadingBoundary, FadeTransition, StableField, StableCounter,
      LayoutGroup). These rules are always on.
+     `className` on PascalCase components is banned — components own their own
+     styling. Use `classNamePassthrough` to exempt transparent wrappers (e.g.
+     `StableText`, `MediaSkeleton`, Lucide icons) that forward className to
+     their root element.
+     A custom rule (`stablekit/no-loading-conflict`) catches dual-paradigm
+     conflicts: if a component has a `loading` prop (which triggers an internal
+     content swap via StateSwap), children must not be variables derived from
+     conditional expressions. The `loading` prop controls geometry — if children
+     also change, both sides shrink simultaneously and pre-allocation is
+     defeated. Props (function parameters) are allowed because they are static
+     per mount. Use `loadingPassthrough` to exempt components where `loading`
+     does not trigger a content swap (e.g. `LoadingBoundary` controls opacity,
+     not geometry). Default passthrough: `["LoadingBoundary"]`.
   4. **Stylelint** (`stablekit/stylelint`) — `createStyleLint({ functionalTokens })`
      bans element selectors in CSS (`& svg`, `& span`), bans `!important`, and
      bans functional color tokens inside `@utility` blocks. `functionalTokens`
@@ -415,6 +428,16 @@ currently behaving.
 .sk-badge[data-variant="active"] { color: var(--color-success); }
 ```
 
+## Out of Scope: Font-Swap CLS
+
+Do NOT build a component to solve font-swap layout shift. StableKit solves
+structural CLS (conditional mounting, dynamic content sizing). Font-swap CLS
+is a typographic metrics problem — no React component can pre-allocate
+geometry for a font that hasn't been downloaded yet. The fix is CSS
+`@font-face` metric overrides (`size-adjust`, `ascent-override`,
+`descent-override`, `line-gap-override`) via tools like Capsize, Fontaine,
+or `next/font`.
+
 ## Component selection guide
 
 | Problem                                    | Component            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stablekit.ts",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "React toolkit for layout stability — zero-shift components for loading states, content swaps, and spatial containers.",
   "type": "module",
   "main": "./dist/index.cjs",