stablekit.ts 0.3.0 → 0.3.1

package/dist/eslint.cjs

@@ -23,6 +23,65 @@ __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,
@@ -160,13 +219,16 @@ function createArchitectureLint(options) {
             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."
+        ]
+      ],
+      "stablekit/no-loading-conflict": ["error", { passthrough: loadingPassthrough }]
+    },
+    plugins: {
+      stablekit: {
+        rules: {
+          "no-loading-conflict": noLoadingConflictRule
         }
-      ]
+      }
     }
   };
 }

package/dist/eslint.d.cts

@@ -30,10 +30,12 @@
  *    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.
+ * 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.
@@ -68,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

@@ -30,10 +30,12 @@
  *    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.
+ * 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.
@@ -68,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,4 +1,63 @@
 // 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,
@@ -136,13 +195,16 @@ function createArchitectureLint(options) {
             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."
+        ]
+      ],
+      "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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stablekit.ts",
-  "version": "0.3.0",
+  "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",