stablekit.ts 0.5.2 → 0.6.0

package/dist/eslint.cjs

@@ -208,10 +208,14 @@ 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."
         },
-        // --- 4b. Conditional hidden prop (geometric instability) ---
-        {
-          selector: "JSXAttribute[name.name='hidden'] > JSXExpressionContainer > :not(Literal)",
-          message: "Conditional hidden prop causes layout shift \u2014 the element occupies zero space when hidden, then expands when shown. Use <StateSwap> to pre-allocate geometry for all visual states."
+        // --- 4b. Sibling hidden swap (geometric instability) ---
+        // Two sibling elements both using conditional hidden to swap
+        // visibility — neither reserves space for the other.
+        // A single hidden={condition} (e.g. error message at bottom of
+        // layout) is fine and intentionally not flagged.
+        {
+          selector: "JSXElement:has(JSXOpeningElement JSXAttribute[name.name='hidden'] > JSXExpressionContainer > :not(Literal)) ~ JSXElement:has(JSXOpeningElement JSXAttribute[name.name='hidden'] > JSXExpressionContainer > :not(Literal))",
+          message: "Sibling elements swap visibility with conditional hidden \u2014 neither reserves space for the other, causing layout shift. Use <StateSwap> for two states or <LayoutMap> for multiple states."
         },
         // --- 5. className on firewalled components ---
         ...classNameBlocked.length ? [

package/dist/eslint.d.cts

@@ -22,10 +22,10 @@
  *
  * 4. Geometric instability — conditional content in JSX children that
  *    causes layout shift: ternary swaps, && mounts, || / ?? fallbacks,
- *    interpolated template literals, and conditional hidden props.
- *    Each message guides toward extracting the expression to a variable
- *    (for data transforms) or using a StableKit component (for
- *    state-driven swaps). Always on.
+ *    interpolated template literals, and sibling hidden swaps (two+
+ *    siblings using conditional hidden to toggle visibility without
+ *    reserving space for each other). A single hidden={condition} is
+ *    fine and not flagged. Always on.
  *
  * 5. className on custom components — passing className to a PascalCase
  *    component is a presentation leak across the Structure boundary.

package/dist/eslint.d.ts

@@ -22,10 +22,10 @@
  *
  * 4. Geometric instability — conditional content in JSX children that
  *    causes layout shift: ternary swaps, && mounts, || / ?? fallbacks,
- *    interpolated template literals, and conditional hidden props.
- *    Each message guides toward extracting the expression to a variable
- *    (for data transforms) or using a StableKit component (for
- *    state-driven swaps). Always on.
+ *    interpolated template literals, and sibling hidden swaps (two+
+ *    siblings using conditional hidden to toggle visibility without
+ *    reserving space for each other). A single hidden={condition} is
+ *    fine and not flagged. Always on.
  *
  * 5. className on custom components — passing className to a PascalCase
  *    component is a presentation leak across the Structure boundary.

package/dist/eslint.js

@@ -184,10 +184,14 @@ 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."
         },
-        // --- 4b. Conditional hidden prop (geometric instability) ---
-        {
-          selector: "JSXAttribute[name.name='hidden'] > JSXExpressionContainer > :not(Literal)",
-          message: "Conditional hidden prop causes layout shift \u2014 the element occupies zero space when hidden, then expands when shown. Use <StateSwap> to pre-allocate geometry for all visual states."
+        // --- 4b. Sibling hidden swap (geometric instability) ---
+        // Two sibling elements both using conditional hidden to swap
+        // visibility — neither reserves space for the other.
+        // A single hidden={condition} (e.g. error message at bottom of
+        // layout) is fine and intentionally not flagged.
+        {
+          selector: "JSXElement:has(JSXOpeningElement JSXAttribute[name.name='hidden'] > JSXExpressionContainer > :not(Literal)) ~ JSXElement:has(JSXOpeningElement JSXAttribute[name.name='hidden'] > JSXExpressionContainer > :not(Literal))",
+          message: "Sibling elements swap visibility with conditional hidden \u2014 neither reserves space for the other, causing layout shift. Use <StateSwap> for two states or <LayoutMap> for multiple states."
         },
         // --- 5. className on firewalled components ---
         ...classNameBlocked.length ? [

package/dist/stylelint.cjs

@@ -25,6 +25,7 @@ __export(stylelint_exports, {
 module.exports = __toCommonJS(stylelint_exports);
 var pluginRuleName = "stablekit/no-functional-in-utility";
 var descendantColorRuleName = "stablekit/no-descendant-color-in-state";
+var duplicateRulesetRuleName = "stablekit/no-duplicate-ruleset";
 function createFunctionalTokenPlugin(prefixes) {
   const rule = (enabled) => {
     return (root, result) => {
@@ -51,14 +52,17 @@ function createFunctionalTokenPlugin(prefixes) {
 function createDescendantColorPlugin() {
   const dataAttrWithDescendant = /\[data-[^\]]+\]\s+[.#\w]/;
   const colorApplyPattern = /\btext-(?!xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl|left|right|center|justify|wrap|nowrap|ellipsis|clip|truncate)\w/;
-  const message = `Setting color on a descendant inside a data-attribute selector. Set color on the [data-*] container and let children inherit via currentColor.`;
+  const message = `Visual property on a descendant inside a data-attribute selector. Set visual properties on the [data-*] container and let children inherit via currentColor.`;
   const rule = (enabled) => {
     return (root, result) => {
       if (!enabled) return;
       root.walkRules((ruleNode) => {
         if (!dataAttrWithDescendant.test(ruleNode.selector)) return;
-        ruleNode.walkDecls("color", (decl) => {
-          result.warn(message, { node: decl });
+        const visualProps = /^(color|background|background-color|border-color|outline-color|fill|stroke|opacity|box-shadow|text-shadow)$/;
+        ruleNode.walkDecls((decl) => {
+          if (visualProps.test(decl.prop)) {
+            result.warn(message, { node: decl });
+          }
         });
         ruleNode.walkAtRules("apply", (atRule) => {
           if (colorApplyPattern.test(atRule.params)) {
@@ -73,13 +77,54 @@ function createDescendantColorPlugin() {
     rule
   };
 }
+function createDuplicateRulesetPlugin() {
+  function directFingerprint(ruleNode) {
+    const parts = [];
+    for (const child of ruleNode.nodes ?? []) {
+      if (child.type === "decl") {
+        parts.push(`${child.prop}: ${child.value}`);
+      } else if (child.type === "atrule" && child.name === "apply") {
+        parts.push(`@apply ${child.params}`);
+      }
+    }
+    return parts;
+  }
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      const seen = /* @__PURE__ */ new Map();
+      root.walkRules((ruleNode) => {
+        if (ruleNode.parent?.type === "atrule" && ruleNode.parent.name === "keyframes") return;
+        const parts = directFingerprint(ruleNode);
+        if (parts.length < 2) return;
+        const fingerprint = parts.sort().join("; ");
+        const existing = seen.get(fingerprint);
+        if (existing) {
+          const sameSelector = existing === ruleNode.selector;
+          result.warn(
+            sameSelector ? `Redundant rule \u2014 "${ruleNode.selector}" is defined multiple times with identical declarations. Remove the duplicate.
+Declarations: ${fingerprint}` : `Duplicate ruleset \u2014 "${ruleNode.selector}" has identical declarations to "${existing}". Consolidate under a shared class name.
+Declarations: ${fingerprint}`,
+            { node: ruleNode }
+          );
+        } else {
+          seen.set(fingerprint, ruleNode.selector);
+        }
+      });
+    };
+  };
+  return {
+    ruleName: duplicateRulesetRuleName,
+    rule
+  };
+}
 function createStyleLint(options = {}) {
   const {
     ignoreTypes = ["html", "body"],
     functionalTokens = [],
     files = ["src/**/*.css"]
   } = options;
-  const plugins = [createDescendantColorPlugin()];
+  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin()];
   if (functionalTokens.length > 0) {
     plugins.push(createFunctionalTokenPlugin(functionalTokens));
   }
@@ -95,6 +140,8 @@ function createStyleLint(options = {}) {
     "declaration-no-important": true,
     // Ban color on descendants inside data-attribute selectors.
     [descendantColorRuleName]: true,
+    // Flag selectors with identical declarations for consolidation.
+    [duplicateRulesetRuleName]: true,
     // Ban animating layout properties — causes reflow on every frame.
     // Use transform (scaleY, translateY) or opacity instead.
     "declaration-property-value-disallowed-list": [

package/dist/stylelint.d.cts

@@ -18,13 +18,19 @@
  *    in scoped selectors like `.badge[data-status="paid"]`, not in
  *    utilities that can spread via @apply or className.
  *
- * 4. Don't set color on descendants inside data-attribute selectors.
+ * 4. Don't set visual properties on descendants inside data-attribute selectors.
  *    `.card[data-status="error"] .icon { color: red }` is wrong —
  *    set color on the container and let children inherit via currentColor.
+ *    Also catches background, border-color, opacity, box-shadow, etc.
  *
  * 5. Don't animate layout properties (width, height, margin, padding,
  *    top/right/bottom/left). These trigger reflow on every frame.
  *    Use transform (scaleY, translateY) or opacity instead.
+ *
+ * 6. Don't duplicate rulesets — two selectors with byte-identical
+ *    declarations (after sorting) should be consolidated under one
+ *    shared class name. The warning includes the matched declarations
+ *    so the developer can see why they were flagged.
  */
 interface StyleLintOptions {
     /** Element selectors to allow (e.g. in resets).

package/dist/stylelint.d.ts

@@ -18,13 +18,19 @@
  *    in scoped selectors like `.badge[data-status="paid"]`, not in
  *    utilities that can spread via @apply or className.
  *
- * 4. Don't set color on descendants inside data-attribute selectors.
+ * 4. Don't set visual properties on descendants inside data-attribute selectors.
  *    `.card[data-status="error"] .icon { color: red }` is wrong —
  *    set color on the container and let children inherit via currentColor.
+ *    Also catches background, border-color, opacity, box-shadow, etc.
  *
  * 5. Don't animate layout properties (width, height, margin, padding,
  *    top/right/bottom/left). These trigger reflow on every frame.
  *    Use transform (scaleY, translateY) or opacity instead.
+ *
+ * 6. Don't duplicate rulesets — two selectors with byte-identical
+ *    declarations (after sorting) should be consolidated under one
+ *    shared class name. The warning includes the matched declarations
+ *    so the developer can see why they were flagged.
  */
 interface StyleLintOptions {
     /** Element selectors to allow (e.g. in resets).

package/dist/stylelint.js

@@ -1,6 +1,7 @@
 // src/stylelint.ts
 var pluginRuleName = "stablekit/no-functional-in-utility";
 var descendantColorRuleName = "stablekit/no-descendant-color-in-state";
+var duplicateRulesetRuleName = "stablekit/no-duplicate-ruleset";
 function createFunctionalTokenPlugin(prefixes) {
   const rule = (enabled) => {
     return (root, result) => {
@@ -27,14 +28,17 @@ function createFunctionalTokenPlugin(prefixes) {
 function createDescendantColorPlugin() {
   const dataAttrWithDescendant = /\[data-[^\]]+\]\s+[.#\w]/;
   const colorApplyPattern = /\btext-(?!xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl|left|right|center|justify|wrap|nowrap|ellipsis|clip|truncate)\w/;
-  const message = `Setting color on a descendant inside a data-attribute selector. Set color on the [data-*] container and let children inherit via currentColor.`;
+  const message = `Visual property on a descendant inside a data-attribute selector. Set visual properties on the [data-*] container and let children inherit via currentColor.`;
   const rule = (enabled) => {
     return (root, result) => {
       if (!enabled) return;
       root.walkRules((ruleNode) => {
         if (!dataAttrWithDescendant.test(ruleNode.selector)) return;
-        ruleNode.walkDecls("color", (decl) => {
-          result.warn(message, { node: decl });
+        const visualProps = /^(color|background|background-color|border-color|outline-color|fill|stroke|opacity|box-shadow|text-shadow)$/;
+        ruleNode.walkDecls((decl) => {
+          if (visualProps.test(decl.prop)) {
+            result.warn(message, { node: decl });
+          }
         });
         ruleNode.walkAtRules("apply", (atRule) => {
           if (colorApplyPattern.test(atRule.params)) {
@@ -49,13 +53,54 @@ function createDescendantColorPlugin() {
     rule
   };
 }
+function createDuplicateRulesetPlugin() {
+  function directFingerprint(ruleNode) {
+    const parts = [];
+    for (const child of ruleNode.nodes ?? []) {
+      if (child.type === "decl") {
+        parts.push(`${child.prop}: ${child.value}`);
+      } else if (child.type === "atrule" && child.name === "apply") {
+        parts.push(`@apply ${child.params}`);
+      }
+    }
+    return parts;
+  }
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      const seen = /* @__PURE__ */ new Map();
+      root.walkRules((ruleNode) => {
+        if (ruleNode.parent?.type === "atrule" && ruleNode.parent.name === "keyframes") return;
+        const parts = directFingerprint(ruleNode);
+        if (parts.length < 2) return;
+        const fingerprint = parts.sort().join("; ");
+        const existing = seen.get(fingerprint);
+        if (existing) {
+          const sameSelector = existing === ruleNode.selector;
+          result.warn(
+            sameSelector ? `Redundant rule \u2014 "${ruleNode.selector}" is defined multiple times with identical declarations. Remove the duplicate.
+Declarations: ${fingerprint}` : `Duplicate ruleset \u2014 "${ruleNode.selector}" has identical declarations to "${existing}". Consolidate under a shared class name.
+Declarations: ${fingerprint}`,
+            { node: ruleNode }
+          );
+        } else {
+          seen.set(fingerprint, ruleNode.selector);
+        }
+      });
+    };
+  };
+  return {
+    ruleName: duplicateRulesetRuleName,
+    rule
+  };
+}
 function createStyleLint(options = {}) {
   const {
     ignoreTypes = ["html", "body"],
     functionalTokens = [],
     files = ["src/**/*.css"]
   } = options;
-  const plugins = [createDescendantColorPlugin()];
+  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin()];
   if (functionalTokens.length > 0) {
     plugins.push(createFunctionalTokenPlugin(functionalTokens));
   }
@@ -71,6 +116,8 @@ function createStyleLint(options = {}) {
     "declaration-no-important": true,
     // Ban color on descendants inside data-attribute selectors.
     [descendantColorRuleName]: true,
+    // Flag selectors with identical declarations for consolidation.
+    [duplicateRulesetRuleName]: true,
     // Ban animating layout properties — causes reflow on every frame.
     // Use transform (scaleY, translateY) or opacity instead.
     "declaration-property-value-disallowed-list": [

package/package.json

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