stablekit.ts 0.2.3 → 0.3.0

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

@@ -28,6 +28,8 @@ function createArchitectureLint(options) {
     stateTokens,
     variantProps = [],
     banColorUtilities = true,
+    classNamePassthrough = [],
+    loadingPassthrough = ["LoadingBoundary"],
     files = ["src/components/**/*.{tsx,jsx}"]
   } = options;
   const tokenPattern = stateTokens.join("|");
@@ -146,6 +148,23 @@ 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."
+          }
+        ],
+        // --- 6. Dual-paradigm conflict (loading + variable children) ---
+        {
+          selector: `JSXElement:has(JSXOpeningElement[name.name=/^[A-Z]/]:not([name.name=/^(${loadingPassthrough.join("|")})$/]) > JSXAttribute[name.name='loading']) > JSXExpressionContainer > Identifier`,
+          message: "Variable children inside 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."
         }
       ]
     }

package/dist/eslint.d.cts

@@ -25,6 +25,15 @@
  *    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 — a component with a `loading` prop does
+ *    internal content swapping (StateSwap). If children are also variable,
+ *    both sides of the swap change simultaneously, defeating pre-allocation.
+ *    Children of loading-swappable components must be static.
  */
 interface ArchitectureLintOptions {
     /** State token names that should never appear in JS as Tailwind classes.
@@ -38,6 +47,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[];

package/dist/eslint.d.ts

@@ -25,6 +25,15 @@
  *    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 — a component with a `loading` prop does
+ *    internal content swapping (StateSwap). If children are also variable,
+ *    both sides of the swap change simultaneously, defeating pre-allocation.
+ *    Children of loading-swappable components must be static.
  */
 interface ArchitectureLintOptions {
     /** State token names that should never appear in JS as Tailwind classes.
@@ -38,6 +47,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[];

package/dist/eslint.js

@@ -4,6 +4,8 @@ function createArchitectureLint(options) {
     stateTokens,
     variantProps = [],
     banColorUtilities = true,
+    classNamePassthrough = [],
+    loadingPassthrough = ["LoadingBoundary"],
     files = ["src/components/**/*.{tsx,jsx}"]
   } = options;
   const tokenPattern = stateTokens.join("|");
@@ -122,6 +124,23 @@ 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."
+          }
+        ],
+        // --- 6. Dual-paradigm conflict (loading + variable children) ---
+        {
+          selector: `JSXElement:has(JSXOpeningElement[name.name=/^[A-Z]/]:not([name.name=/^(${loadingPassthrough.join("|")})$/]) > JSXAttribute[name.name='loading']) > JSXExpressionContainer > Identifier`,
+          message: "Variable children inside 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."
         }
       ]
     }

package/llms.txt

@@ -415,6 +415,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.0",
   "description": "React toolkit for layout stability — zero-shift components for loading states, content swaps, and spatial containers.",
   "type": "module",
   "main": "./dist/index.cjs",