stablekit.ts 0.4.0 → 0.5.1

package/README.md

@@ -48,10 +48,10 @@ If a component depends on async data, its bounding box is declared synchronously
 
 ### Spatial Pre-allocation
 
-If a UI region has multiple states, all states render simultaneously in a CSS grid overlap. The container sizes to the largest. `LayoutMap` renders a dictionary of views, toggles visibility with `[inert]` + `data-state`, and never changes dimensions. `StateSwap` does the same for boolean content inside buttons and labels.
+If a UI region has multiple states, all states render simultaneously in a CSS grid overlap. The container sizes to the largest. `StateMap` renders a dictionary of views, toggles visibility with `[inert]` + `data-state`, and never changes dimensions. `StateSwap` is a boolean convenience wrapper around `StateMap` for two-state toggles.
 
 ```tsx
-<LayoutMap value={activeTab} map={{
+<StateMap value={activeTab} map={{
   profile: <Profile />,
   invoices: <Invoices />,
   settings: <Settings />,
@@ -74,9 +74,10 @@ Once a container expands, it cannot shrink unless explicitly reset. `SizeRatchet
 | `StableText` | Typography + skeleton in one tag |
 | `MediaSkeleton` | Aspect-ratio placeholder that constrains its child |
 | `CollectionSkeleton` | Loading-aware list with forced stub count |
-| `LayoutMap` | Type-safe dictionary of views with stable dimensions |
-| `LayoutGroup` + `LayoutView` | Multi-state spatial container (use LayoutMap when possible) |
-| `StateSwap` | Boolean content swap — both options rendered, zero shift |
+| `StateMap` | Multi-state content swap — keyed dictionary, inline, zero shift |
+| `StateSwap` | Boolean content swap — thin wrapper around StateMap |
+| `LayoutMap` | Block-level dictionary of views (tab panels, wizards) |
+| `LayoutGroup` + `LayoutView` | Manual multi-state container (use StateMap or LayoutMap) |
 | `StableCounter` | Numeric/text width pre-allocation via ghost reserve |
 | `StableField` | Form error height pre-allocation via ghost reserve |
 | `SizeRatchet` | Container that never shrinks (ResizeObserver ratchet) |

package/dist/eslint.cjs

@@ -190,7 +190,7 @@ function createArchitectureLint(options) {
         // --- 4. Geometric instability (conditional content) ---
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > ConditionalExpression",
-          message: "Conditional content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT replace with the hidden attribute. For state-driven swaps, use <StateSwap> for text, <LayoutMap> for keyed views, or <LoadingBoundary> for async states."
+          message: "Conditional content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT replace with the hidden attribute. For state-driven swaps, use <StateSwap> for text, <StateMap> for keyed views, or <LoadingBoundary> for async states."
         },
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='&&']",
@@ -208,6 +208,11 @@ 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."
+        },
         // --- 5. className on firewalled components ---
         ...classNameBlocked.length ? [
           {

package/dist/eslint.d.cts

@@ -22,9 +22,10 @@
  *
  * 4. Geometric instability — conditional content in JSX children that
  *    causes layout shift: ternary swaps, && mounts, || / ?? fallbacks,
- *    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.
+ *    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.
  *
  * 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,9 +22,10 @@
  *
  * 4. Geometric instability — conditional content in JSX children that
  *    causes layout shift: ternary swaps, && mounts, || / ?? fallbacks,
- *    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.
+ *    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.
  *
  * 5. className on custom components — passing className to a PascalCase
  *    component is a presentation leak across the Structure boundary.

package/dist/eslint.js

@@ -166,7 +166,7 @@ function createArchitectureLint(options) {
         // --- 4. Geometric instability (conditional content) ---
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > ConditionalExpression",
-          message: "Conditional content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT replace with the hidden attribute. For state-driven swaps, use <StateSwap> for text, <LayoutMap> for keyed views, or <LoadingBoundary> for async states."
+          message: "Conditional content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT replace with the hidden attribute. For state-driven swaps, use <StateSwap> for text, <StateMap> for keyed views, or <LoadingBoundary> for async states."
         },
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='&&']",
@@ -184,6 +184,11 @@ 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."
+        },
         // --- 5. className on firewalled components ---
         ...classNameBlocked.length ? [
           {

package/dist/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   StableCounter: () => StableCounter,
   StableField: () => StableField,
   StableText: () => StableText,
+  StateMap: () => StateMap,
   StateSwap: () => StateSwap,
   TextSkeleton: () => TextSkeleton,
   createPrimitive: () => createPrimitive,
@@ -180,25 +181,39 @@ var LayoutView = (0, import_react2.forwardRef)(
   }
 );
 
-// src/components/state-swap.tsx
+// src/components/state-map.tsx
 var import_jsx_runtime3 = require("react/jsx-runtime");
+function StateMap({
+  value,
+  map,
+  as: Tag = "span",
+  ...props
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(LayoutGroup, { as: Tag, value, axis: "both", "data-inline": true, ...props, children: Object.entries(map).map(([key, node]) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(LayoutView, { as: "span", name: key, children: node }, key)) });
+}
+
+// src/components/state-swap.tsx
+var import_jsx_runtime4 = require("react/jsx-runtime");
 function StateSwap({
   state,
   true: onTrue,
   false: onFalse,
-  as: Tag = "span",
   ...props
 }) {
-  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(LayoutGroup, { as: Tag, value: state ? "true" : "false", axis: "both", "data-inline": true, ...props, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(LayoutView, { as: "span", name: "true", children: onTrue }),
-    /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(LayoutView, { as: "span", name: "false", children: onFalse })
-  ] });
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+    StateMap,
+    {
+      value: state ? "true" : "false",
+      map: { true: onTrue, false: onFalse },
+      ...props
+    }
+  );
 }
 
 // src/components/layout-map.tsx
-var import_jsx_runtime4 = require("react/jsx-runtime");
+var import_jsx_runtime5 = require("react/jsx-runtime");
 function LayoutMap({ value, map, ...props }) {
-  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(LayoutGroup, { value, ...props, children: Object.entries(map).map(([key, node]) => /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(LayoutView, { name: key, children: node }, key)) });
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(LayoutGroup, { value, ...props, children: Object.entries(map).map(([key, node]) => /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(LayoutView, { name: key, children: node }, key)) });
 }
 
 // src/components/size-ratchet.tsx
@@ -267,13 +282,13 @@ function useStableSlot(options = {}) {
 }
 
 // src/components/size-ratchet.tsx
-var import_jsx_runtime5 = require("react/jsx-runtime");
+var import_jsx_runtime6 = require("react/jsx-runtime");
 var SizeRatchet = (0, import_react4.forwardRef)(
   function SizeRatchet2({ axis = "height", resetKey, as: Tag = "div", className, style, children, ...props }, fwdRef) {
     (0, import_react4.useInsertionEffect)(injectStyles, []);
     const { ref: ratchetRef, style: ratchetStyle } = useStableSlot({ axis, resetKey });
     const merged = className ? `sk-size-ratchet ${className}` : "sk-size-ratchet";
-    return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
+    return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
       Tag,
       {
         ref: mergeRefs(ratchetRef, fwdRef),
@@ -288,7 +303,7 @@ var SizeRatchet = (0, import_react4.forwardRef)(
 
 // src/components/stable-counter.tsx
 var import_react5 = require("react");
-var import_jsx_runtime6 = require("react/jsx-runtime");
+var import_jsx_runtime7 = require("react/jsx-runtime");
 var GHOST_STYLE = {
   visibility: "hidden",
   gridArea: "1 / 1",
@@ -299,7 +314,7 @@ var VALUE_STYLE = {
 };
 var StableCounter = (0, import_react5.forwardRef)(
   function StableCounter2({ value, reserve, as: Tag = "span", style, className, ...props }, ref) {
-    return /* @__PURE__ */ (0, import_jsx_runtime6.jsxs)(
+    return /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(
       Tag,
       {
         ref,
@@ -307,8 +322,8 @@ var StableCounter = (0, import_react5.forwardRef)(
         style: { ...style, display: "inline-grid" },
         ...props,
         children: [
-          /* @__PURE__ */ (0, import_jsx_runtime6.jsx)("span", { "aria-hidden": "true", style: GHOST_STYLE, children: reserve }),
-          /* @__PURE__ */ (0, import_jsx_runtime6.jsx)("span", { style: VALUE_STYLE, children: value })
+          /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("span", { "aria-hidden": "true", style: GHOST_STYLE, children: reserve }),
+          /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("span", { style: VALUE_STYLE, children: value })
         ]
       }
     );
@@ -317,7 +332,7 @@ var StableCounter = (0, import_react5.forwardRef)(
 
 // src/components/stable-field.tsx
 var import_react6 = require("react");
-var import_jsx_runtime7 = require("react/jsx-runtime");
+var import_jsx_runtime8 = require("react/jsx-runtime");
 var GHOST_STYLE2 = {
   visibility: "hidden",
   gridArea: "1 / 1",
@@ -333,11 +348,11 @@ var ERROR_HIDDEN_STYLE = {
 var StableField = (0, import_react6.forwardRef)(
   function StableField2({ error, reserve, children, style, className, ...props }, ref) {
     const hasError = error != null && error !== false && error !== "";
-    return /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)("div", { ref, className, style, ...props, children: [
+    return /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)("div", { ref, className, style, ...props, children: [
       children,
-      /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)("div", { style: { display: "grid" }, children: [
-        /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("span", { "aria-hidden": "true", style: GHOST_STYLE2, children: reserve }),
-        /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+      /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)("div", { style: { display: "grid" }, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("span", { "aria-hidden": "true", style: GHOST_STYLE2, children: reserve }),
+        /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(
           "span",
           {
             role: hasError ? "alert" : void 0,
@@ -355,17 +370,17 @@ var import_react8 = require("react");
 
 // src/components/loading-context.tsx
 var import_react7 = require("react");
-var import_jsx_runtime8 = require("react/jsx-runtime");
+var import_jsx_runtime9 = require("react/jsx-runtime");
 var LoadingStateContext = (0, import_react7.createContext)(false);
 function useLoadingState() {
   return (0, import_react7.useContext)(LoadingStateContext);
 }
 function LoadingContext({ loading, children }) {
-  return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(LoadingStateContext.Provider, { value: loading, children });
+  return /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(LoadingStateContext.Provider, { value: loading, children });
 }
 
 // src/components/loading-boundary.tsx
-var import_jsx_runtime9 = require("react/jsx-runtime");
+var import_jsx_runtime10 = require("react/jsx-runtime");
 var LoadingBoundary = (0, import_react8.forwardRef)(
   function LoadingBoundary2({ loading, exitDuration, as: Tag = "div", className, style, children, ...props }, ref) {
     (0, import_react8.useInsertionEffect)(injectStyles, []);
@@ -373,28 +388,28 @@ var LoadingBoundary = (0, import_react8.forwardRef)(
       ...style,
       "--sk-loading-exit-duration": `${exitDuration}ms`
     };
-    return /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(SizeRatchet, { ref, as: Tag, className, style: merged, ...props, children: /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(LoadingContext, { loading, children }) });
+    return /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(SizeRatchet, { ref, as: Tag, className, style: merged, ...props, children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(LoadingContext, { loading, children }) });
   }
 );
 
 // src/components/text-skeleton.tsx
 var import_react9 = require("react");
-var import_jsx_runtime10 = require("react/jsx-runtime");
+var import_jsx_runtime11 = require("react/jsx-runtime");
 function TextSkeleton({ loading, as: Tag = "span", className, style, children, ...props }) {
   (0, import_react9.useInsertionEffect)(injectStyles, []);
   const contextLoading = useLoadingState();
   const isLoading = loading ?? contextLoading;
-  return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Tag, { className, style: { ...style, display: "inline-grid" }, ...props, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)(Tag, { className, style: { ...style, display: "inline-grid" }, ...props, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(
       "span",
       {
         className: "sk-shimmer-line sk-loading-layer",
         "aria-hidden": "true",
         style: { opacity: isLoading ? 1 : 0 },
-        children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("span", { inert: true, children })
+        children: /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("span", { inert: true, children })
       }
     ),
-    /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+    /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(
       "span",
       {
         className: "sk-loading-layer",
@@ -407,19 +422,19 @@ function TextSkeleton({ loading, as: Tag = "span", className, style, children, .
 }
 
 // src/components/stable-text.tsx
-var import_jsx_runtime11 = require("react/jsx-runtime");
+var import_jsx_runtime12 = require("react/jsx-runtime");
 function StableText({
   as: Tag = "p",
   loading,
   children,
   ...props
 }) {
-  return /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(Tag, { ...props, children: /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(TextSkeleton, { loading, children }) });
+  return /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(Tag, { ...props, children: /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(TextSkeleton, { loading, children }) });
 }
 
 // src/components/media-skeleton.tsx
 var import_react10 = require("react");
-var import_jsx_runtime12 = require("react/jsx-runtime");
+var import_jsx_runtime13 = require("react/jsx-runtime");
 var CHILD_STYLE = {
   position: "absolute",
   inset: 0,
@@ -473,8 +488,8 @@ function MediaSkeleton({
       ...child.props.style
     }
   }) : child;
-  return /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("div", { className: containerClass, style: containerStyle, ...props, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime13.jsxs)("div", { className: containerClass, style: containerStyle, ...props, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime13.jsx)(
       "div",
       {
         className: "sk-media-shimmer",
@@ -491,18 +506,18 @@ var import_react12 = require("react");
 
 // src/components/skeleton-grid.tsx
 var import_react11 = require("react");
-var import_jsx_runtime13 = require("react/jsx-runtime");
+var import_jsx_runtime14 = require("react/jsx-runtime");
 var SkeletonGrid = (0, import_react11.forwardRef)(
   function SkeletonGrid2({ rows, columns, as: Tag = "div", className, children, ...props }, ref) {
     (0, import_react11.useInsertionEffect)(injectStyles, []);
     const merged = className ? `sk-skeleton-grid ${className}` : "sk-skeleton-grid";
     const count = columns ? rows * columns : rows;
-    const cells = Array.from({ length: count }, (_, i) => /* @__PURE__ */ (0, import_jsx_runtime13.jsxs)("div", { className: "sk-skeleton-bone", children: [
-      /* @__PURE__ */ (0, import_jsx_runtime13.jsx)("div", { className: "sk-shimmer-line" }),
-      /* @__PURE__ */ (0, import_jsx_runtime13.jsx)("div", { className: "sk-shimmer-line" })
+    const cells = Array.from({ length: count }, (_, i) => /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { className: "sk-skeleton-bone", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("div", { className: "sk-shimmer-line" }),
+      /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("div", { className: "sk-shimmer-line" })
     ] }, i));
     const gridStyle = columns ? { gridTemplateColumns: `repeat(${columns}, auto)` } : void 0;
-    return /* @__PURE__ */ (0, import_jsx_runtime13.jsx)(
+    return /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
       Tag,
       {
         ref,
@@ -516,7 +531,7 @@ var SkeletonGrid = (0, import_react11.forwardRef)(
 );
 
 // src/components/collection-skeleton.tsx
-var import_jsx_runtime14 = require("react/jsx-runtime");
+var import_jsx_runtime15 = require("react/jsx-runtime");
 function CollectionSkeletonInner({
   items,
   loading,
@@ -534,17 +549,17 @@ function CollectionSkeletonInner({
     display: "grid",
     "--sk-loading-exit-duration": `${exitDuration}ms`
   };
-  return /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)(SizeRatchet, { ref, axis: "height", as: Tag, className, style: merged, ...props, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)(SizeRatchet, { ref, axis: "height", as: Tag, className, style: merged, ...props, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(
       "div",
       {
         className: "sk-loading-layer",
         "aria-hidden": "true",
         style: { opacity: loading ? 1 : 0 },
-        children: /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(SkeletonGrid, { rows: stubCount })
+        children: /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(SkeletonGrid, { rows: stubCount })
       }
     ),
-    /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
+    /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(
       "div",
       {
         className: "sk-loading-layer",
@@ -585,7 +600,7 @@ function usePresence(show) {
 }
 
 // src/components/fade-transition.tsx
-var import_jsx_runtime15 = require("react/jsx-runtime");
+var import_jsx_runtime16 = require("react/jsx-runtime");
 var FadeTransition = (0, import_react14.forwardRef)(
   function FadeTransition2({ show, as: Tag = "div", className, style, children, ...props }, fwdRef) {
     (0, import_react14.useInsertionEffect)(injectStyles, []);
@@ -593,7 +608,7 @@ var FadeTransition = (0, import_react14.forwardRef)(
     if (!mounted) return null;
     const phaseClass = phase === "entering" ? "sk-fade-entering" : phase === "exiting" ? "sk-fade-exiting" : "";
     const merged = ["sk-fade", phaseClass, className].filter(Boolean).join(" ");
-    return /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(
+    return /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(
       Tag,
       {
         ref: fwdRef,
@@ -638,6 +653,7 @@ function createPrimitive(tag, baseClass, variants) {
   StableCounter,
   StableField,
   StableText,
+  StateMap,
   StateSwap,
   TextSkeleton,
   createPrimitive,

package/dist/index.d.cts

@@ -15,6 +15,7 @@ interface StateSwapProps extends HTMLAttributes<HTMLElement> {
 /**
  * Boolean content swap with zero layout shift.
  *
+ * Thin wrapper around StateMap with two keys ("true" / "false").
  * Reserves the width of the wider option so the container never changes
  * dimensions when toggling between states.
  *
@@ -27,17 +28,8 @@ interface StateSwapProps extends HTMLAttributes<HTMLElement> {
  *   <StateSwap state={open} true="Close" false="Open" />
  * </button>
  * ```
- *
- * @example
- * ```tsx
- * <StateSwap
- *   state={expanded}
- *   true={<ChevronUp />}
- *   false={<ChevronDown />}
- * />
- * ```
  */
-declare function StateSwap({ state, true: onTrue, false: onFalse, as: Tag, ...props }: StateSwapProps): react_jsx_runtime.JSX.Element;
+declare function StateSwap({ state, true: onTrue, false: onFalse, ...props }: StateSwapProps): react_jsx_runtime.JSX.Element;
 
 type Axis = "width" | "height" | "both";
 interface LayoutGroupProps extends HTMLAttributes<HTMLElement> {
@@ -147,6 +139,37 @@ interface LayoutMapProps<K extends string> extends HTMLAttributes<HTMLElement> {
  */
 declare function LayoutMap<K extends string>({ value, map, ...props }: LayoutMapProps<K>): react_jsx_runtime.JSX.Element;
 
+interface StateMapProps<K extends string> extends HTMLAttributes<HTMLElement> {
+    /**
+     * The active key — must match one of the keys in `map`.
+     *
+     * Uses `NoInfer<K>` so TypeScript infers the key union from `map`
+     * and checks `value` against it — typos are compile-time errors.
+     */
+    value: NoInfer<K>;
+    /** Dictionary of views keyed by state name. TypeScript infers and enforces the keys. */
+    map: Record<K, ReactNode>;
+    /** HTML element to render. Default: "span" (safe inside buttons). */
+    as?: ElementType;
+}
+/**
+ * Multi-state content swap with zero layout shift.
+ *
+ * The keyed counterpart to StateSwap — same inline defaults,
+ * same grid overlap physics, but for N states instead of two.
+ *
+ * @example
+ * ```tsx
+ * <StateMap value={phase} map={{
+ *   loading: <Shimmer />,
+ *   unconfirmed: <Button intent="secondary">Deliver All</Button>,
+ *   confirmed: <span><CheckCircle /> All confirmed</span>,
+ *   chargeable: <Button intent="primary">Charge All</Button>,
+ * }} />
+ * ```
+ */
+declare function StateMap<K extends string>({ value, map, as: Tag, ...props }: StateMapProps<K>): react_jsx_runtime.JSX.Element;
+
 interface SizeRatchetProps extends HTMLAttributes<HTMLElement> {
     /** Which axis to ratchet. Default: "height". */
     axis?: Axis;
@@ -470,4 +493,4 @@ declare const FadeTransition: react.ForwardRefExoticComponent<FadeTransitionProp
  */
 declare function createPrimitive<Tag extends keyof JSX.IntrinsicElements, const Variants extends Record<string, readonly string[]> = {}>(tag: Tag, baseClass: string, variants?: Variants): (props: Omit<JSX.IntrinsicElements[Tag], "style" | "className" | keyof Variants> & { [K in keyof Variants]: Variants[K][number]; }) => react.DOMElement<Record<string, unknown>, Element>;
 
-export { type Axis, CollectionSkeleton, type CollectionSkeletonProps, FadeTransition, type FadeTransitionProps, LayoutGroup, type LayoutGroupProps, LayoutMap, type LayoutMapProps, LayoutView, type LayoutViewProps, LoadingBoundary, type LoadingBoundaryProps, LoadingContext, type LoadingContextProps, MediaSkeleton, type MediaSkeletonProps, SizeRatchet, type SizeRatchetProps, StableCounter, type StableCounterProps, StableField, type StableFieldProps, StableText, type StableTextProps, StateSwap, type StateSwapProps, TextSkeleton, type TextSkeletonProps, createPrimitive, useLoadingState };
+export { type Axis, CollectionSkeleton, type CollectionSkeletonProps, FadeTransition, type FadeTransitionProps, LayoutGroup, type LayoutGroupProps, LayoutMap, type LayoutMapProps, LayoutView, type LayoutViewProps, LoadingBoundary, type LoadingBoundaryProps, LoadingContext, type LoadingContextProps, MediaSkeleton, type MediaSkeletonProps, SizeRatchet, type SizeRatchetProps, StableCounter, type StableCounterProps, StableField, type StableFieldProps, StableText, type StableTextProps, StateMap, type StateMapProps, StateSwap, type StateSwapProps, TextSkeleton, type TextSkeletonProps, createPrimitive, useLoadingState };

package/dist/index.d.ts

@@ -15,6 +15,7 @@ interface StateSwapProps extends HTMLAttributes<HTMLElement> {
 /**
  * Boolean content swap with zero layout shift.
  *
+ * Thin wrapper around StateMap with two keys ("true" / "false").
  * Reserves the width of the wider option so the container never changes
  * dimensions when toggling between states.
  *
@@ -27,17 +28,8 @@ interface StateSwapProps extends HTMLAttributes<HTMLElement> {
  *   <StateSwap state={open} true="Close" false="Open" />
  * </button>
  * ```
- *
- * @example
- * ```tsx
- * <StateSwap
- *   state={expanded}
- *   true={<ChevronUp />}
- *   false={<ChevronDown />}
- * />
- * ```
  */
-declare function StateSwap({ state, true: onTrue, false: onFalse, as: Tag, ...props }: StateSwapProps): react_jsx_runtime.JSX.Element;
+declare function StateSwap({ state, true: onTrue, false: onFalse, ...props }: StateSwapProps): react_jsx_runtime.JSX.Element;
 
 type Axis = "width" | "height" | "both";
 interface LayoutGroupProps extends HTMLAttributes<HTMLElement> {
@@ -147,6 +139,37 @@ interface LayoutMapProps<K extends string> extends HTMLAttributes<HTMLElement> {
  */
 declare function LayoutMap<K extends string>({ value, map, ...props }: LayoutMapProps<K>): react_jsx_runtime.JSX.Element;
 
+interface StateMapProps<K extends string> extends HTMLAttributes<HTMLElement> {
+    /**
+     * The active key — must match one of the keys in `map`.
+     *
+     * Uses `NoInfer<K>` so TypeScript infers the key union from `map`
+     * and checks `value` against it — typos are compile-time errors.
+     */
+    value: NoInfer<K>;
+    /** Dictionary of views keyed by state name. TypeScript infers and enforces the keys. */
+    map: Record<K, ReactNode>;
+    /** HTML element to render. Default: "span" (safe inside buttons). */
+    as?: ElementType;
+}
+/**
+ * Multi-state content swap with zero layout shift.
+ *
+ * The keyed counterpart to StateSwap — same inline defaults,
+ * same grid overlap physics, but for N states instead of two.
+ *
+ * @example
+ * ```tsx
+ * <StateMap value={phase} map={{
+ *   loading: <Shimmer />,
+ *   unconfirmed: <Button intent="secondary">Deliver All</Button>,
+ *   confirmed: <span><CheckCircle /> All confirmed</span>,
+ *   chargeable: <Button intent="primary">Charge All</Button>,
+ * }} />
+ * ```
+ */
+declare function StateMap<K extends string>({ value, map, as: Tag, ...props }: StateMapProps<K>): react_jsx_runtime.JSX.Element;
+
 interface SizeRatchetProps extends HTMLAttributes<HTMLElement> {
     /** Which axis to ratchet. Default: "height". */
     axis?: Axis;
@@ -470,4 +493,4 @@ declare const FadeTransition: react.ForwardRefExoticComponent<FadeTransitionProp
  */
 declare function createPrimitive<Tag extends keyof JSX.IntrinsicElements, const Variants extends Record<string, readonly string[]> = {}>(tag: Tag, baseClass: string, variants?: Variants): (props: Omit<JSX.IntrinsicElements[Tag], "style" | "className" | keyof Variants> & { [K in keyof Variants]: Variants[K][number]; }) => react.DOMElement<Record<string, unknown>, Element>;
 
-export { type Axis, CollectionSkeleton, type CollectionSkeletonProps, FadeTransition, type FadeTransitionProps, LayoutGroup, type LayoutGroupProps, LayoutMap, type LayoutMapProps, LayoutView, type LayoutViewProps, LoadingBoundary, type LoadingBoundaryProps, LoadingContext, type LoadingContextProps, MediaSkeleton, type MediaSkeletonProps, SizeRatchet, type SizeRatchetProps, StableCounter, type StableCounterProps, StableField, type StableFieldProps, StableText, type StableTextProps, StateSwap, type StateSwapProps, TextSkeleton, type TextSkeletonProps, createPrimitive, useLoadingState };
+export { type Axis, CollectionSkeleton, type CollectionSkeletonProps, FadeTransition, type FadeTransitionProps, LayoutGroup, type LayoutGroupProps, LayoutMap, type LayoutMapProps, LayoutView, type LayoutViewProps, LoadingBoundary, type LoadingBoundaryProps, LoadingContext, type LoadingContextProps, MediaSkeleton, type MediaSkeletonProps, SizeRatchet, type SizeRatchetProps, StableCounter, type StableCounterProps, StableField, type StableFieldProps, StableText, type StableTextProps, StateMap, type StateMapProps, StateSwap, type StateSwapProps, TextSkeleton, type TextSkeletonProps, createPrimitive, useLoadingState };

package/dist/index.js

@@ -152,25 +152,39 @@ var LayoutView = forwardRef2(
   }
 );
 
+// src/components/state-map.tsx
+import { jsx as jsx3 } from "react/jsx-runtime";
+function StateMap({
+  value,
+  map,
+  as: Tag = "span",
+  ...props
+}) {
+  return /* @__PURE__ */ jsx3(LayoutGroup, { as: Tag, value, axis: "both", "data-inline": true, ...props, children: Object.entries(map).map(([key, node]) => /* @__PURE__ */ jsx3(LayoutView, { as: "span", name: key, children: node }, key)) });
+}
+
 // src/components/state-swap.tsx
-import { jsx as jsx3, jsxs } from "react/jsx-runtime";
+import { jsx as jsx4 } from "react/jsx-runtime";
 function StateSwap({
   state,
   true: onTrue,
   false: onFalse,
-  as: Tag = "span",
   ...props
 }) {
-  return /* @__PURE__ */ jsxs(LayoutGroup, { as: Tag, value: state ? "true" : "false", axis: "both", "data-inline": true, ...props, children: [
-    /* @__PURE__ */ jsx3(LayoutView, { as: "span", name: "true", children: onTrue }),
-    /* @__PURE__ */ jsx3(LayoutView, { as: "span", name: "false", children: onFalse })
-  ] });
+  return /* @__PURE__ */ jsx4(
+    StateMap,
+    {
+      value: state ? "true" : "false",
+      map: { true: onTrue, false: onFalse },
+      ...props
+    }
+  );
 }
 
 // src/components/layout-map.tsx
-import { jsx as jsx4 } from "react/jsx-runtime";
+import { jsx as jsx5 } from "react/jsx-runtime";
 function LayoutMap({ value, map, ...props }) {
-  return /* @__PURE__ */ jsx4(LayoutGroup, { value, ...props, children: Object.entries(map).map(([key, node]) => /* @__PURE__ */ jsx4(LayoutView, { name: key, children: node }, key)) });
+  return /* @__PURE__ */ jsx5(LayoutGroup, { value, ...props, children: Object.entries(map).map(([key, node]) => /* @__PURE__ */ jsx5(LayoutView, { name: key, children: node }, key)) });
 }
 
 // src/components/size-ratchet.tsx
@@ -239,13 +253,13 @@ function useStableSlot(options = {}) {
 }
 
 // src/components/size-ratchet.tsx
-import { jsx as jsx5 } from "react/jsx-runtime";
+import { jsx as jsx6 } from "react/jsx-runtime";
 var SizeRatchet = forwardRef3(
   function SizeRatchet2({ axis = "height", resetKey, as: Tag = "div", className, style, children, ...props }, fwdRef) {
     useInsertionEffect3(injectStyles, []);
     const { ref: ratchetRef, style: ratchetStyle } = useStableSlot({ axis, resetKey });
     const merged = className ? `sk-size-ratchet ${className}` : "sk-size-ratchet";
-    return /* @__PURE__ */ jsx5(
+    return /* @__PURE__ */ jsx6(
       Tag,
       {
         ref: mergeRefs(ratchetRef, fwdRef),
@@ -260,7 +274,7 @@ var SizeRatchet = forwardRef3(
 
 // src/components/stable-counter.tsx
 import { forwardRef as forwardRef4 } from "react";
-import { jsx as jsx6, jsxs as jsxs2 } from "react/jsx-runtime";
+import { jsx as jsx7, jsxs } from "react/jsx-runtime";
 var GHOST_STYLE = {
   visibility: "hidden",
   gridArea: "1 / 1",
@@ -271,7 +285,7 @@ var VALUE_STYLE = {
 };
 var StableCounter = forwardRef4(
   function StableCounter2({ value, reserve, as: Tag = "span", style, className, ...props }, ref) {
-    return /* @__PURE__ */ jsxs2(
+    return /* @__PURE__ */ jsxs(
       Tag,
       {
         ref,
@@ -279,8 +293,8 @@ var StableCounter = forwardRef4(
         style: { ...style, display: "inline-grid" },
         ...props,
         children: [
-          /* @__PURE__ */ jsx6("span", { "aria-hidden": "true", style: GHOST_STYLE, children: reserve }),
-          /* @__PURE__ */ jsx6("span", { style: VALUE_STYLE, children: value })
+          /* @__PURE__ */ jsx7("span", { "aria-hidden": "true", style: GHOST_STYLE, children: reserve }),
+          /* @__PURE__ */ jsx7("span", { style: VALUE_STYLE, children: value })
         ]
       }
     );
@@ -289,7 +303,7 @@ var StableCounter = forwardRef4(
 
 // src/components/stable-field.tsx
 import { forwardRef as forwardRef5 } from "react";
-import { jsx as jsx7, jsxs as jsxs3 } from "react/jsx-runtime";
+import { jsx as jsx8, jsxs as jsxs2 } from "react/jsx-runtime";
 var GHOST_STYLE2 = {
   visibility: "hidden",
   gridArea: "1 / 1",
@@ -305,11 +319,11 @@ var ERROR_HIDDEN_STYLE = {
 var StableField = forwardRef5(
   function StableField2({ error, reserve, children, style, className, ...props }, ref) {
     const hasError = error != null && error !== false && error !== "";
-    return /* @__PURE__ */ jsxs3("div", { ref, className, style, ...props, children: [
+    return /* @__PURE__ */ jsxs2("div", { ref, className, style, ...props, children: [
       children,
-      /* @__PURE__ */ jsxs3("div", { style: { display: "grid" }, children: [
-        /* @__PURE__ */ jsx7("span", { "aria-hidden": "true", style: GHOST_STYLE2, children: reserve }),
-        /* @__PURE__ */ jsx7(
+      /* @__PURE__ */ jsxs2("div", { style: { display: "grid" }, children: [
+        /* @__PURE__ */ jsx8("span", { "aria-hidden": "true", style: GHOST_STYLE2, children: reserve }),
+        /* @__PURE__ */ jsx8(
           "span",
           {
             role: hasError ? "alert" : void 0,
@@ -330,17 +344,17 @@ import {
 
 // src/components/loading-context.tsx
 import { createContext as createContext2, useContext as useContext2 } from "react";
-import { jsx as jsx8 } from "react/jsx-runtime";
+import { jsx as jsx9 } from "react/jsx-runtime";
 var LoadingStateContext = createContext2(false);
 function useLoadingState() {
   return useContext2(LoadingStateContext);
 }
 function LoadingContext({ loading, children }) {
-  return /* @__PURE__ */ jsx8(LoadingStateContext.Provider, { value: loading, children });
+  return /* @__PURE__ */ jsx9(LoadingStateContext.Provider, { value: loading, children });
 }
 
 // src/components/loading-boundary.tsx
-import { jsx as jsx9 } from "react/jsx-runtime";
+import { jsx as jsx10 } from "react/jsx-runtime";
 var LoadingBoundary = forwardRef6(
   function LoadingBoundary2({ loading, exitDuration, as: Tag = "div", className, style, children, ...props }, ref) {
     useInsertionEffect4(injectStyles, []);
@@ -348,28 +362,28 @@ var LoadingBoundary = forwardRef6(
       ...style,
       "--sk-loading-exit-duration": `${exitDuration}ms`
     };
-    return /* @__PURE__ */ jsx9(SizeRatchet, { ref, as: Tag, className, style: merged, ...props, children: /* @__PURE__ */ jsx9(LoadingContext, { loading, children }) });
+    return /* @__PURE__ */ jsx10(SizeRatchet, { ref, as: Tag, className, style: merged, ...props, children: /* @__PURE__ */ jsx10(LoadingContext, { loading, children }) });
   }
 );
 
 // src/components/text-skeleton.tsx
 import { useInsertionEffect as useInsertionEffect5 } from "react";
-import { jsx as jsx10, jsxs as jsxs4 } from "react/jsx-runtime";
+import { jsx as jsx11, jsxs as jsxs3 } from "react/jsx-runtime";
 function TextSkeleton({ loading, as: Tag = "span", className, style, children, ...props }) {
   useInsertionEffect5(injectStyles, []);
   const contextLoading = useLoadingState();
   const isLoading = loading ?? contextLoading;
-  return /* @__PURE__ */ jsxs4(Tag, { className, style: { ...style, display: "inline-grid" }, ...props, children: [
-    /* @__PURE__ */ jsx10(
+  return /* @__PURE__ */ jsxs3(Tag, { className, style: { ...style, display: "inline-grid" }, ...props, children: [
+    /* @__PURE__ */ jsx11(
       "span",
       {
         className: "sk-shimmer-line sk-loading-layer",
         "aria-hidden": "true",
         style: { opacity: isLoading ? 1 : 0 },
-        children: /* @__PURE__ */ jsx10("span", { inert: true, children })
+        children: /* @__PURE__ */ jsx11("span", { inert: true, children })
       }
     ),
-    /* @__PURE__ */ jsx10(
+    /* @__PURE__ */ jsx11(
       "span",
       {
         className: "sk-loading-layer",
@@ -382,14 +396,14 @@ function TextSkeleton({ loading, as: Tag = "span", className, style, children, .
 }
 
 // src/components/stable-text.tsx
-import { jsx as jsx11 } from "react/jsx-runtime";
+import { jsx as jsx12 } from "react/jsx-runtime";
 function StableText({
   as: Tag = "p",
   loading,
   children,
   ...props
 }) {
-  return /* @__PURE__ */ jsx11(Tag, { ...props, children: /* @__PURE__ */ jsx11(TextSkeleton, { loading, children }) });
+  return /* @__PURE__ */ jsx12(Tag, { ...props, children: /* @__PURE__ */ jsx12(TextSkeleton, { loading, children }) });
 }
 
 // src/components/media-skeleton.tsx
@@ -403,7 +417,7 @@ import {
   useRef as useRef4,
   useState as useState2
 } from "react";
-import { jsx as jsx12, jsxs as jsxs5 } from "react/jsx-runtime";
+import { jsx as jsx13, jsxs as jsxs4 } from "react/jsx-runtime";
 var CHILD_STYLE = {
   position: "absolute",
   inset: 0,
@@ -457,8 +471,8 @@ function MediaSkeleton({
       ...child.props.style
     }
   }) : child;
-  return /* @__PURE__ */ jsxs5("div", { className: containerClass, style: containerStyle, ...props, children: [
-    /* @__PURE__ */ jsx12(
+  return /* @__PURE__ */ jsxs4("div", { className: containerClass, style: containerStyle, ...props, children: [
+    /* @__PURE__ */ jsx13(
       "div",
       {
         className: "sk-media-shimmer",
@@ -478,18 +492,18 @@ import {
 
 // src/components/skeleton-grid.tsx
 import { forwardRef as forwardRef7, useInsertionEffect as useInsertionEffect7 } from "react";
-import { jsx as jsx13, jsxs as jsxs6 } from "react/jsx-runtime";
+import { jsx as jsx14, jsxs as jsxs5 } from "react/jsx-runtime";
 var SkeletonGrid = forwardRef7(
   function SkeletonGrid2({ rows, columns, as: Tag = "div", className, children, ...props }, ref) {
     useInsertionEffect7(injectStyles, []);
     const merged = className ? `sk-skeleton-grid ${className}` : "sk-skeleton-grid";
     const count = columns ? rows * columns : rows;
-    const cells = Array.from({ length: count }, (_, i) => /* @__PURE__ */ jsxs6("div", { className: "sk-skeleton-bone", children: [
-      /* @__PURE__ */ jsx13("div", { className: "sk-shimmer-line" }),
-      /* @__PURE__ */ jsx13("div", { className: "sk-shimmer-line" })
+    const cells = Array.from({ length: count }, (_, i) => /* @__PURE__ */ jsxs5("div", { className: "sk-skeleton-bone", children: [
+      /* @__PURE__ */ jsx14("div", { className: "sk-shimmer-line" }),
+      /* @__PURE__ */ jsx14("div", { className: "sk-shimmer-line" })
     ] }, i));
     const gridStyle = columns ? { gridTemplateColumns: `repeat(${columns}, auto)` } : void 0;
-    return /* @__PURE__ */ jsx13(
+    return /* @__PURE__ */ jsx14(
       Tag,
       {
         ref,
@@ -503,7 +517,7 @@ var SkeletonGrid = forwardRef7(
 );
 
 // src/components/collection-skeleton.tsx
-import { jsx as jsx14, jsxs as jsxs7 } from "react/jsx-runtime";
+import { jsx as jsx15, jsxs as jsxs6 } from "react/jsx-runtime";
 function CollectionSkeletonInner({
   items,
   loading,
@@ -521,17 +535,17 @@ function CollectionSkeletonInner({
     display: "grid",
     "--sk-loading-exit-duration": `${exitDuration}ms`
   };
-  return /* @__PURE__ */ jsxs7(SizeRatchet, { ref, axis: "height", as: Tag, className, style: merged, ...props, children: [
-    /* @__PURE__ */ jsx14(
+  return /* @__PURE__ */ jsxs6(SizeRatchet, { ref, axis: "height", as: Tag, className, style: merged, ...props, children: [
+    /* @__PURE__ */ jsx15(
       "div",
       {
         className: "sk-loading-layer",
         "aria-hidden": "true",
         style: { opacity: loading ? 1 : 0 },
-        children: /* @__PURE__ */ jsx14(SkeletonGrid, { rows: stubCount })
+        children: /* @__PURE__ */ jsx15(SkeletonGrid, { rows: stubCount })
       }
     ),
-    /* @__PURE__ */ jsx14(
+    /* @__PURE__ */ jsx15(
       "div",
       {
         className: "sk-loading-layer",
@@ -579,7 +593,7 @@ function usePresence(show) {
 }
 
 // src/components/fade-transition.tsx
-import { jsx as jsx15 } from "react/jsx-runtime";
+import { jsx as jsx16 } from "react/jsx-runtime";
 var FadeTransition = forwardRef9(
   function FadeTransition2({ show, as: Tag = "div", className, style, children, ...props }, fwdRef) {
     useInsertionEffect9(injectStyles, []);
@@ -587,7 +601,7 @@ var FadeTransition = forwardRef9(
     if (!mounted) return null;
     const phaseClass = phase === "entering" ? "sk-fade-entering" : phase === "exiting" ? "sk-fade-exiting" : "";
     const merged = ["sk-fade", phaseClass, className].filter(Boolean).join(" ");
-    return /* @__PURE__ */ jsx15(
+    return /* @__PURE__ */ jsx16(
       Tag,
       {
         ref: fwdRef,
@@ -631,6 +645,7 @@ export {
   StableCounter,
   StableField,
   StableText,
+  StateMap,
   StateSwap,
   TextSkeleton,
   createPrimitive,

package/llms.txt

@@ -21,7 +21,7 @@ This means:
   `stubCount`, `StableText` reserves space at line-height.)
 - **Spatial pre-allocation:** If a UI region has multiple states, all
   states must render simultaneously in a CSS grid overlap. The container
-  sizes to the largest. (`LayoutMap`, `LayoutGroup`, `StateSwap`)
+  sizes to the largest. (`StateMap`, `StateSwap`, `LayoutMap`, `LayoutGroup`)
 - **Monotonic geometry:** Once a container expands, it cannot shrink
   unless explicitly reset. (`SizeRatchet` with optional `resetKey`)
 - **Structural Integrity over Temporal Hacks:** Never unmount a state
@@ -46,7 +46,7 @@ rendering for the same UI region.
 | `StateSwap`          | Spatial                | Boolean content swap, zero shift             |
 | `LayoutGroup`        | Spatial                | Multi-state spatial stability container       |
 | `LayoutView`         | Spatial                | Single view inside a LayoutGroup             |
-| `LayoutMap`          | Spatial                | Dictionary-based state mapping (typo-proof)  |
+| `StateMap`           | Spatial                | Multi-state content swap, keyed, inline      |
 | `StableCounter`      | Spatial                | Numeric/text width pre-allocation            |
 | `StableField`        | Spatial                | Form error height pre-allocation             |
 | `SizeRatchet`        | Monotonic              | Container that never shrinks                 |
@@ -125,7 +125,7 @@ CORRECT — one button, swap content inside it:
 Use LayoutGroup/LayoutView only when swapping structurally different
 components (e.g. tab panels, multi-step forms).
 
-### 5. Do not use LayoutGroup/LayoutView for tab content — use LayoutMap
+### 5. Do not use LayoutGroup/LayoutView for tab content — use StateMap
 
 WRONG — string typos silently break rendering:
 ```tsx
@@ -137,7 +137,7 @@ WRONG — string typos silently break rendering:
 
 CORRECT — dictionary keys are checked by TypeScript:
 ```tsx
-<LayoutMap value={activeTab} map={{
+<StateMap value={activeTab} map={{
   profile: <Profile />,
   invoices: <Invoices />,
 }} />
@@ -311,11 +311,15 @@ change to structure requires editing `.css`, a boundary has leaked.
      The linter also enforces geometric stability by banning all conditional
      content in JSX children: ternary swaps (`{x ? <A/> : <B/>}`), conditional
      mounting (`{x && <Panel/>}`), fallback content (`{x || "default"}`),
-     nullish fallbacks (`{x ?? "loading"}`), and interpolated template literals
-     (`` {`text ${var}`} ``). Each error message guides toward the right fix:
+     nullish fallbacks (`{x ?? "loading"}`), interpolated template literals
+     (`` {`text ${var}`} ``), and conditional `hidden` props
+     (`hidden={x || undefined}`). The `hidden` attribute causes an element to
+     occupy zero space — toggling it conditionally is a layout shift. Use
+     `<StateSwap>` to pre-allocate geometry for all visual states instead.
+     Each error message guides toward the right fix:
      extract the expression to a variable above the JSX (for data transforms),
      or use a StableKit component (for state-driven swaps — StateSwap,
-     LayoutMap, LoadingBoundary, FadeTransition, StableField, StableCounter,
+     StateMap, LoadingBoundary, FadeTransition, StableField, StableCounter,
      LayoutGroup). These rules are always on.
      `classNameBlocked` declares your firewalled primitives (e.g.
      `["Badge", "Button", "Card", "Input"]`). Only those components are flagged
@@ -428,6 +432,32 @@ currently behaving.
 .sk-badge[data-variant="active"] { color: var(--color-success); }
 ```
 
+### 12. Do not use conditional hidden props to swap between states
+
+WRONG — hidden element takes zero space, causes layout shift when toggled:
+```tsx
+<Button hidden={status !== "active" || undefined}>
+  <Pause size={14} /> Pause
+</Button>
+<Button hidden={status !== "paused" || undefined}>
+  <Play size={14} /> Resume
+</Button>
+```
+
+CORRECT — StateSwap pre-allocates geometry for the wider option:
+```tsx
+<StateSwap
+  state={status === "active"}
+  true={<Button><Pause size={14} /> Pause</Button>}
+  false={<Button><Play size={14} /> Resume</Button>}
+/>
+```
+
+The `hidden` attribute sets `display: none` — the element is removed from
+flow entirely. When siblings toggle `hidden` with mutually exclusive
+conditions, the container resizes every time. StateSwap renders both states
+in a CSS grid overlap so the bounding box stays stable.
+
 ## Out of Scope: Font-Swap CLS
 
 Do NOT build a component to solve font-swap layout shift. StableKit solves
@@ -444,7 +474,7 @@ or `next/font`.
 |--------------------------------------------|----------------------|
 | Button text changes on toggle              | `StateSwap`          |
 | Icon changes on toggle                     | `StateSwap`          |
-| Tab panels with stable height              | `LayoutMap`          |
+| Tab panels with stable height              | `StateMap`           |
 | Multi-step wizard with stable dimensions   | `LayoutGroup` + `LayoutView` |
 | Text loading from API                      | `StableText` inside `LoadingBoundary` |
 | Image/video loading causes shift           | `MediaSkeleton`      |
@@ -465,7 +495,7 @@ import {
   StableText,
   MediaSkeleton,
   StateSwap,
-  LayoutMap,
+  StateMap,
   SizeRatchet,
   StableCounter,
   StableField,

package/package.json

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