stablekit.ts 0.5.3 → 0.6.1

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,8 @@ __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";
+var nearDuplicateRuleName = "stablekit/no-near-duplicate-ruleset";
 function createFunctionalTokenPlugin(prefixes) {
   const rule = (enabled) => {
     return (root, result) => {
@@ -76,13 +78,113 @@ 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 createNearDuplicatePlugin() {
+  function collectDirectDecls(ruleNode) {
+    const map = /* @__PURE__ */ new Map();
+    for (const child of ruleNode.nodes ?? []) {
+      if (child.type === "decl") {
+        map.set(child.prop, child.value);
+      } else if (child.type === "atrule" && child.name === "apply") {
+        map.set(`@apply`, child.params);
+      }
+    }
+    return map;
+  }
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      const groups = /* @__PURE__ */ new Map();
+      root.walkRules((ruleNode) => {
+        if (ruleNode.parent?.type === "atrule" && ruleNode.parent.name === "keyframes") return;
+        const propMap = collectDirectDecls(ruleNode);
+        if (propMap.size < 2) return;
+        const propKey = [...propMap.keys()].sort().join(", ");
+        const entry = { selector: ruleNode.selector, propKey, propMap, node: ruleNode };
+        const group = groups.get(propKey);
+        if (group) {
+          for (const existing of group) {
+            let diffCount = 0;
+            let diffProp = "";
+            let diffOld = "";
+            let diffNew = "";
+            for (const [prop, value] of entry.propMap) {
+              const existingValue = existing.propMap.get(prop);
+              if (existingValue !== value) {
+                diffCount++;
+                diffProp = prop;
+                diffOld = existingValue ?? "(missing)";
+                diffNew = value;
+              }
+            }
+            if (diffCount === 0) continue;
+            if (diffCount === 1 && diffProp !== "@apply") {
+              result.warn(
+                `Near-duplicate ruleset \u2014 "${ruleNode.selector}" differs from "${existing.selector}" only in ${diffProp} (${diffOld} \u2192 ${diffNew}). Consider consolidating to a single class.`,
+                { node: ruleNode }
+              );
+              break;
+            }
+          }
+          group.push(entry);
+        } else {
+          groups.set(propKey, [entry]);
+        }
+      });
+    };
+  };
+  return {
+    ruleName: nearDuplicateRuleName,
+    rule
+  };
+}
 function createStyleLint(options = {}) {
   const {
     ignoreTypes = ["html", "body"],
     functionalTokens = [],
     files = ["src/**/*.css"]
   } = options;
-  const plugins = [createDescendantColorPlugin()];
+  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin(), createNearDuplicatePlugin()];
   if (functionalTokens.length > 0) {
     plugins.push(createFunctionalTokenPlugin(functionalTokens));
   }
@@ -98,6 +200,10 @@ 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,
+    // Flag near-duplicate rulesets (same props, differ by 1 value).
+    [nearDuplicateRuleName]: 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

@@ -26,6 +26,11 @@
  * 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

@@ -26,6 +26,11 @@
  * 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,8 @@
 // src/stylelint.ts
 var pluginRuleName = "stablekit/no-functional-in-utility";
 var descendantColorRuleName = "stablekit/no-descendant-color-in-state";
+var duplicateRulesetRuleName = "stablekit/no-duplicate-ruleset";
+var nearDuplicateRuleName = "stablekit/no-near-duplicate-ruleset";
 function createFunctionalTokenPlugin(prefixes) {
   const rule = (enabled) => {
     return (root, result) => {
@@ -52,13 +54,113 @@ 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 createNearDuplicatePlugin() {
+  function collectDirectDecls(ruleNode) {
+    const map = /* @__PURE__ */ new Map();
+    for (const child of ruleNode.nodes ?? []) {
+      if (child.type === "decl") {
+        map.set(child.prop, child.value);
+      } else if (child.type === "atrule" && child.name === "apply") {
+        map.set(`@apply`, child.params);
+      }
+    }
+    return map;
+  }
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      const groups = /* @__PURE__ */ new Map();
+      root.walkRules((ruleNode) => {
+        if (ruleNode.parent?.type === "atrule" && ruleNode.parent.name === "keyframes") return;
+        const propMap = collectDirectDecls(ruleNode);
+        if (propMap.size < 2) return;
+        const propKey = [...propMap.keys()].sort().join(", ");
+        const entry = { selector: ruleNode.selector, propKey, propMap, node: ruleNode };
+        const group = groups.get(propKey);
+        if (group) {
+          for (const existing of group) {
+            let diffCount = 0;
+            let diffProp = "";
+            let diffOld = "";
+            let diffNew = "";
+            for (const [prop, value] of entry.propMap) {
+              const existingValue = existing.propMap.get(prop);
+              if (existingValue !== value) {
+                diffCount++;
+                diffProp = prop;
+                diffOld = existingValue ?? "(missing)";
+                diffNew = value;
+              }
+            }
+            if (diffCount === 0) continue;
+            if (diffCount === 1 && diffProp !== "@apply") {
+              result.warn(
+                `Near-duplicate ruleset \u2014 "${ruleNode.selector}" differs from "${existing.selector}" only in ${diffProp} (${diffOld} \u2192 ${diffNew}). Consider consolidating to a single class.`,
+                { node: ruleNode }
+              );
+              break;
+            }
+          }
+          group.push(entry);
+        } else {
+          groups.set(propKey, [entry]);
+        }
+      });
+    };
+  };
+  return {
+    ruleName: nearDuplicateRuleName,
+    rule
+  };
+}
 function createStyleLint(options = {}) {
   const {
     ignoreTypes = ["html", "body"],
     functionalTokens = [],
     files = ["src/**/*.css"]
   } = options;
-  const plugins = [createDescendantColorPlugin()];
+  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin(), createNearDuplicatePlugin()];
   if (functionalTokens.length > 0) {
     plugins.push(createFunctionalTokenPlugin(functionalTokens));
   }
@@ -74,6 +176,10 @@ 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,
+    // Flag near-duplicate rulesets (same props, differ by 1 value).
+    [nearDuplicateRuleName]: 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.3",
+  "version": "0.6.1",
   "description": "React toolkit for layout stability — zero-shift components for loading states, content swaps, and spatial containers.",
   "type": "module",
   "main": "./dist/index.cjs",