concertina 0.5.1 → 0.6.1

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">concertina</h1>
 
 <p align="center">
-  Layout stability primitives + scroll-pinned <a href="https://www.radix-ui.com/primitives/docs/components/accordion">Radix Accordion</a> panels.
+  React toolkit for layout stability.
 </p>
 
 ## Install
@@ -39,10 +39,10 @@ A UI slot toggles between variants of different sizes (Add button ↔ quantity s
 ```
 
 **How it works:**
-1. `display: grid` on container, `grid-area: 1/1` on all slots — everything overlaps
-2. `visibility: hidden` on inactive slots — invisible but still in layout flow
-3. `inert` attribute on inactive slots — no focus, no clicks, no screen reader
-4. Axis-aware collapse (`max-height: 0` or `max-width: 0`) so only the relevant axis contributes to sizing
+1. `display: grid` on container, `grid-area: 1/1` on all Slots — everything overlaps
+2. `visibility: hidden` on inactive Slots — invisible but still in layout flow
+3. `inert` attribute on inactive Slots — no focus, no clicks, no screen reader
+4. `display: flex; flex-direction: column` on Slots — content stretches to fill the reserved width
 5. Zero JS measurement — pure CSS, works on first frame
 
 **StableSlot props:**
@@ -50,15 +50,52 @@ A UI slot toggles between variants of different sizes (Add button ↔ quantity s
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `axis` | `"width"` \| `"height"` \| `"both"` | `"both"` | Which axis to stabilize |
-| `className` | `string` | — | Passed to wrapper div |
+| `as` | `ElementType` | `"div"` | HTML element to render. Use `"span"` inside buttons. |
+| `className` | `string` | — | Passed to wrapper element |
 
-All other div attributes are forwarded.
+All other HTML attributes are forwarded.
 
 **Slot props:**
 
 | Prop | Type | Description |
 |------|------|-------------|
 | `active` | `boolean` | Controls visibility |
+| `as` | `ElementType` | HTML element to render. Default `"div"`. |
+
+#### Rules for correct behavior
+
+**1. Parent containers must allow content-based sizing.**
+A fixed-width parent (e.g., `grid-template-columns: 10rem`) clips the StableSlot and defeats the mechanism. If a grid column contains a StableSlot, use `auto`:
+
+```css
+/* Bad — fixed column ignores StableSlot's intrinsic width */
+grid-template-columns: 1fr 10rem;
+
+/* Good — column auto-sizes to the StableSlot's widest child */
+grid-template-columns: 1fr auto;
+```
+
+**2. Every independently appearing element needs its own StableSlot.**
+If an element appears in one state but not another (e.g., an Undo link below a Charge button), it must be in a separate StableSlot — not nested inside one Slot of the main StableSlot. Stack StableSlots vertically:
+
+```tsx
+<div className="action-column">
+  {/* Main action — morphs between Deliver/Charge/Retry/paid */}
+  <Concertina.StableSlot axis="width">
+    <Concertina.Slot active={showDeliver}><Button>Deliver</Button></Concertina.Slot>
+    <Concertina.Slot active={showCharge}><Button>Charge</Button></Concertina.Slot>
+    <Concertina.Slot active={showRetry}><Button>Retry</Button></Concertina.Slot>
+  </Concertina.StableSlot>
+  {/* Undo — appears only in Charge state, but space is always reserved */}
+  <Concertina.StableSlot>
+    <Concertina.Slot active={showCharge}>
+      <button className="undo-link">Undo</button>
+    </Concertina.Slot>
+  </Concertina.StableSlot>
+</div>
+```
+
+A single Slot inside a StableSlot is valid — it simply reserves the element's space, showing or hiding it without layout shift.
 
 ### useStableSlot — ResizeObserver ratchet for dynamic content
 

package/dist/index.cjs

@@ -1173,30 +1173,24 @@ var import_react10 = require("react");
 var import_jsx_runtime12 = require("react/jsx-runtime");
 var AxisContext = (0, import_react10.createContext)("both");
 var StableSlot = (0, import_react10.forwardRef)(
-  function StableSlot2({ axis = "both", className, children, ...props }, ref) {
+  function StableSlot2({ axis = "both", as: Tag = "div", className, style, children, ...props }, ref) {
     const merged = className ? `concertina-stable-slot ${className}` : "concertina-stable-slot";
-    return /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(AxisContext.Provider, { value: axis, children: /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("div", { ref, className: merged, ...props, children }) });
+    return /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(AxisContext.Provider, { value: axis, children: /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(Tag, { ref, className: merged, style, ...props, children }) });
   }
 );
 
 // src/slot.tsx
 var import_react11 = require("react");
 var import_jsx_runtime13 = require("react/jsx-runtime");
-function inactiveStyle(axis) {
-  const base = { visibility: "hidden", overflow: "hidden" };
-  if (axis === "width") {
-    base.maxHeight = 0;
-  } else if (axis === "height") {
-    base.maxWidth = 0;
-  }
-  return base;
+function inactiveStyle(_axis) {
+  return { visibility: "hidden" };
 }
 var Slot = (0, import_react11.forwardRef)(
-  function Slot2({ active, style, children, ...props }, ref) {
+  function Slot2({ active, as: Tag = "div", style, children, ...props }, ref) {
     const axis = (0, import_react11.useContext)(AxisContext);
     const merged = active ? { ...style } : { ...inactiveStyle(axis), ...style };
     return /* @__PURE__ */ (0, import_jsx_runtime13.jsx)(
-      "div",
+      Tag,
       {
         ref,
         inert: !active || void 0,

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { HTMLAttributes, CSSProperties } from 'react';
+import { HTMLAttributes, ElementType, CSSProperties } from 'react';
 import * as Accordion from '@radix-ui/react-accordion';
 export { Header, Trigger } from '@radix-ui/react-accordion';
 
@@ -40,9 +40,11 @@ declare class ConcertinaStore {
 declare const ConcertinaContext: react.Context<ConcertinaStore | null>;
 
 type Axis = "width" | "height" | "both";
-interface StableSlotProps extends HTMLAttributes<HTMLDivElement> {
+interface StableSlotProps extends HTMLAttributes<HTMLElement> {
     /** Which axis to stabilize. Default: "both". */
     axis?: Axis;
+    /** HTML element to render. Use "span" inside buttons. Default: "div". */
+    as?: ElementType;
 }
 /**
  * Grid container that auto-sizes to the largest child.
@@ -51,25 +53,25 @@ interface StableSlotProps extends HTMLAttributes<HTMLDivElement> {
  *
  * Zero JS measurement — pure CSS grid sizing.
  */
-declare const StableSlot: react.ForwardRefExoticComponent<StableSlotProps & react.RefAttributes<HTMLDivElement>>;
+declare const StableSlot: react.ForwardRefExoticComponent<StableSlotProps & react.RefAttributes<HTMLElement>>;
 
-interface SlotProps extends HTMLAttributes<HTMLDivElement> {
+interface SlotProps extends HTMLAttributes<HTMLElement> {
     /** Whether this slot is the active (visible) variant. */
     active: boolean;
+    /** HTML element to render. Use "span" inside buttons. Default: "div". */
+    as?: ElementType;
 }
 /**
  * A single variant inside a <StableSlot>.
  * All slots overlap via CSS grid. Inactive slots are hidden
  * but still contribute to grid cell sizing.
  *
- * Five things work together:
+ * Three things work together:
  * 1. grid-area: 1/1 — all slots overlap in the same cell
  * 2. visibility: hidden — invisible but in layout flow
  * 3. inert — no focus, no clicks, no screen reader
- * 4. max-height/max-width: 0 — axis-aware collapse
- * 5. overflow: hidden — prevents content bleed from collapsed axis
  */
-declare const Slot: react.ForwardRefExoticComponent<SlotProps & react.RefAttributes<HTMLDivElement>>;
+declare const Slot: react.ForwardRefExoticComponent<SlotProps & react.RefAttributes<HTMLElement>>;
 
 interface UseStableSlotOptions {
     /** Which axis to ratchet. Default: "both". */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { HTMLAttributes, CSSProperties } from 'react';
+import { HTMLAttributes, ElementType, CSSProperties } from 'react';
 import * as Accordion from '@radix-ui/react-accordion';
 export { Header, Trigger } from '@radix-ui/react-accordion';
 
@@ -40,9 +40,11 @@ declare class ConcertinaStore {
 declare const ConcertinaContext: react.Context<ConcertinaStore | null>;
 
 type Axis = "width" | "height" | "both";
-interface StableSlotProps extends HTMLAttributes<HTMLDivElement> {
+interface StableSlotProps extends HTMLAttributes<HTMLElement> {
     /** Which axis to stabilize. Default: "both". */
     axis?: Axis;
+    /** HTML element to render. Use "span" inside buttons. Default: "div". */
+    as?: ElementType;
 }
 /**
  * Grid container that auto-sizes to the largest child.
@@ -51,25 +53,25 @@ interface StableSlotProps extends HTMLAttributes<HTMLDivElement> {
  *
  * Zero JS measurement — pure CSS grid sizing.
  */
-declare const StableSlot: react.ForwardRefExoticComponent<StableSlotProps & react.RefAttributes<HTMLDivElement>>;
+declare const StableSlot: react.ForwardRefExoticComponent<StableSlotProps & react.RefAttributes<HTMLElement>>;
 
-interface SlotProps extends HTMLAttributes<HTMLDivElement> {
+interface SlotProps extends HTMLAttributes<HTMLElement> {
     /** Whether this slot is the active (visible) variant. */
     active: boolean;
+    /** HTML element to render. Use "span" inside buttons. Default: "div". */
+    as?: ElementType;
 }
 /**
  * A single variant inside a <StableSlot>.
  * All slots overlap via CSS grid. Inactive slots are hidden
  * but still contribute to grid cell sizing.
  *
- * Five things work together:
+ * Three things work together:
  * 1. grid-area: 1/1 — all slots overlap in the same cell
  * 2. visibility: hidden — invisible but in layout flow
  * 3. inert — no focus, no clicks, no screen reader
- * 4. max-height/max-width: 0 — axis-aware collapse
- * 5. overflow: hidden — prevents content bleed from collapsed axis
  */
-declare const Slot: react.ForwardRefExoticComponent<SlotProps & react.RefAttributes<HTMLDivElement>>;
+declare const Slot: react.ForwardRefExoticComponent<SlotProps & react.RefAttributes<HTMLElement>>;
 
 interface UseStableSlotOptions {
     /** Which axis to ratchet. Default: "both". */

package/dist/index.js

@@ -1137,9 +1137,9 @@ import {
 import { jsx as jsx11 } from "react/jsx-runtime";
 var AxisContext = createContext4("both");
 var StableSlot = forwardRef7(
-  function StableSlot2({ axis = "both", className, children, ...props }, ref) {
+  function StableSlot2({ axis = "both", as: Tag = "div", className, style, children, ...props }, ref) {
     const merged = className ? `concertina-stable-slot ${className}` : "concertina-stable-slot";
-    return /* @__PURE__ */ jsx11(AxisContext.Provider, { value: axis, children: /* @__PURE__ */ jsx11("div", { ref, className: merged, ...props, children }) });
+    return /* @__PURE__ */ jsx11(AxisContext.Provider, { value: axis, children: /* @__PURE__ */ jsx11(Tag, { ref, className: merged, style, ...props, children }) });
   }
 );
 
@@ -1149,21 +1149,15 @@ import {
   useContext as useContext5
 } from "react";
 import { jsx as jsx12 } from "react/jsx-runtime";
-function inactiveStyle(axis) {
-  const base = { visibility: "hidden", overflow: "hidden" };
-  if (axis === "width") {
-    base.maxHeight = 0;
-  } else if (axis === "height") {
-    base.maxWidth = 0;
-  }
-  return base;
+function inactiveStyle(_axis) {
+  return { visibility: "hidden" };
 }
 var Slot = forwardRef8(
-  function Slot2({ active, style, children, ...props }, ref) {
+  function Slot2({ active, as: Tag = "div", style, children, ...props }, ref) {
     const axis = useContext5(AxisContext);
     const merged = active ? { ...style } : { ...inactiveStyle(axis), ...style };
     return /* @__PURE__ */ jsx12(
-      "div",
+      Tag,
       {
         ref,
         inert: !active || void 0,

package/dist/styles.css

@@ -54,10 +54,14 @@
 }
 
 /* StableSlot — all children overlap in the same grid cell.
-   Grid auto-sizes to the largest child. */
+   Grid auto-sizes to the largest child.
+   Slots use flex-column so their content stretches to fill
+   the reserved width — the visual footprint is constant. */
 .concertina-stable-slot {
   display: grid;
 }
 .concertina-stable-slot > * {
   grid-area: 1 / 1;
+  display: flex;
+  flex-direction: column;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "concertina",
-  "version": "0.5.1",
-  "description": "Layout stability primitives + scroll-pinned Radix Accordion panels with per-item memoization.",
+  "version": "0.6.1",
+  "description": "React toolkit for layout stability.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -27,6 +27,7 @@
   ],
   "scripts": {
     "build": "tsup && cp src/styles.css dist/styles.css",
+    "prepare": "npm run build",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },