concertina 0.5.2 → 0.7.0

package/README.md

@@ -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

@@ -33,12 +33,15 @@ __export(index_exports, {
   ConcertinaContext: () => ConcertinaContext,
   ConcertinaStore: () => ConcertinaStore,
   Content: () => Content3,
+  Gigbag: () => Gigbag,
+  Glide: () => Glide,
   Header: () => Header,
   Item: () => Item2,
   Root: () => Root3,
   Slot: () => Slot,
   StableSlot: () => StableSlot,
   Trigger: () => Trigger2,
+  Warmup: () => Warmup,
   pinToScrollTop: () => pinToScrollTop,
   useConcertina: () => useConcertina,
   useExpanded: () => useExpanded,
@@ -1173,30 +1176,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,
@@ -1261,13 +1258,96 @@ function useStableSlot(options = {}) {
   return { ref, style };
 }
 
-// src/use-concertina.ts
+// src/gigbag.tsx
 var import_react13 = require("react");
+var import_jsx_runtime14 = require("react/jsx-runtime");
+var Gigbag = (0, import_react13.forwardRef)(
+  function Gigbag2({ axis = "height", as: Tag = "div", className, style, children, ...props }, fwdRef) {
+    const { ref: ratchetRef, style: ratchetStyle } = useStableSlot({ axis });
+    const merged = className ? `concertina-gigbag ${className}` : "concertina-gigbag";
+    return /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
+      Tag,
+      {
+        ref: (el) => {
+          ratchetRef(el);
+          if (typeof fwdRef === "function") fwdRef(el);
+          else if (fwdRef) fwdRef.current = el;
+        },
+        className: merged,
+        style: { ...ratchetStyle, ...style },
+        ...props,
+        children
+      }
+    );
+  }
+);
+
+// src/warmup.tsx
+var import_react14 = require("react");
+var import_jsx_runtime15 = require("react/jsx-runtime");
+var Warmup = (0, import_react14.forwardRef)(
+  function Warmup2({ rows = 3, columns = 1, as: Tag = "div", className, children, ...props }, ref) {
+    const merged = className ? `concertina-warmup ${className}` : "concertina-warmup";
+    const cells = Array.from({ length: rows * columns }, (_, i) => /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { className: "concertina-warmup-bone" }, i));
+    return /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(
+      Tag,
+      {
+        ref,
+        className: merged,
+        style: { gridTemplateColumns: `repeat(${columns}, 1fr)` },
+        ...props,
+        children: cells
+      }
+    );
+  }
+);
+
+// src/glide.tsx
+var import_react15 = require("react");
+var import_jsx_runtime16 = require("react/jsx-runtime");
+var Glide = (0, import_react15.forwardRef)(
+  function Glide2({ show, as: Tag = "div", className, children, ...props }, ref) {
+    const [mounted, setMounted] = (0, import_react15.useState)(show);
+    const [phase, setPhase] = (0, import_react15.useState)(show ? "entered" : "exiting");
+    (0, import_react15.useEffect)(() => {
+      if (show) {
+        setMounted(true);
+        setPhase("entering");
+      } else if (mounted) {
+        setPhase("exiting");
+      }
+    }, [show]);
+    const onAnimationEnd = (0, import_react15.useCallback)(
+      (e) => {
+        if (e.target !== e.currentTarget) return;
+        if (phase === "entering") setPhase("entered");
+        if (phase === "exiting") setMounted(false);
+      },
+      [phase]
+    );
+    if (!mounted) return null;
+    const phaseClass = phase === "entering" ? "concertina-glide-entering" : phase === "exiting" ? "concertina-glide-exiting" : "";
+    const merged = ["concertina-glide", phaseClass, className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(
+      Tag,
+      {
+        ref,
+        className: merged,
+        onAnimationEnd,
+        ...props,
+        children
+      }
+    );
+  }
+);
+
+// src/use-concertina.ts
+var import_react16 = require("react");
 function useConcertina() {
-  const [value, setValue] = (0, import_react13.useState)("");
-  const [switching, setSwitching] = (0, import_react13.useState)(false);
-  const itemRefs = (0, import_react13.useRef)({});
-  const onValueChange = (0, import_react13.useCallback)(
+  const [value, setValue] = (0, import_react16.useState)("");
+  const [switching, setSwitching] = (0, import_react16.useState)(false);
+  const itemRefs = (0, import_react16.useRef)({});
+  const onValueChange = (0, import_react16.useCallback)(
     (newValue) => {
       if (!newValue) {
         setSwitching(false);
@@ -1279,14 +1359,14 @@ function useConcertina() {
     },
     [value]
   );
-  (0, import_react13.useLayoutEffect)(() => {
+  (0, import_react16.useLayoutEffect)(() => {
     if (!value) return;
     pinToScrollTop(itemRefs.current[value]);
   }, [value]);
-  (0, import_react13.useEffect)(() => {
+  (0, import_react16.useEffect)(() => {
     if (switching) setSwitching(false);
   }, [switching]);
-  const getItemRef = (0, import_react13.useCallback)(
+  const getItemRef = (0, import_react16.useCallback)(
     (id) => (el) => {
       itemRefs.current[id] = el;
     },
@@ -1304,12 +1384,15 @@ function useConcertina() {
   ConcertinaContext,
   ConcertinaStore,
   Content,
+  Gigbag,
+  Glide,
   Header,
   Item,
   Root,
   Slot,
   StableSlot,
   Trigger,
+  Warmup,
   pinToScrollTop,
   useConcertina,
   useExpanded,

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". */
@@ -113,6 +115,60 @@ declare function useTransitionLock(): {
     readonly lock: () => void;
 };
 
+interface GigbagProps extends HTMLAttributes<HTMLElement> {
+    /** Which axis to ratchet. Default: "height". */
+    axis?: Axis;
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Size-reserving container.
+ *
+ * Remembers its largest-ever size (ResizeObserver ratchet) and never
+ * shrinks. Swap a spinner for a table inside — no reflow.
+ *
+ * Uses `contain: layout style` to isolate internal reflow from
+ * ancestors.
+ */
+declare const Gigbag: react.ForwardRefExoticComponent<GigbagProps & react.RefAttributes<HTMLElement>>;
+
+interface WarmupProps extends HTMLAttributes<HTMLElement> {
+    /** Number of placeholder rows. Default: 3. */
+    rows?: number;
+    /** Number of columns per row. Default: 1. */
+    columns?: number;
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Structural placeholder — CSS-only shimmer grid.
+ *
+ * Renders `rows x columns` animated bones that approximate the
+ * dimensions of the real content. Pair with <Gigbag> so the
+ * container ratchets to the larger of placeholder vs real content.
+ *
+ * All dimensions are CSS custom properties — consuming apps theme
+ * without forking.
+ */
+declare const Warmup: react.ForwardRefExoticComponent<WarmupProps & react.RefAttributes<HTMLElement>>;
+
+interface GlideProps extends HTMLAttributes<HTMLElement> {
+    /** Whether the content is visible. */
+    show: boolean;
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Enter/exit animation wrapper.
+ *
+ * State machine:
+ *   show=true  -> mount + "entering" -> animationEnd -> "entered"
+ *   show=false -> "exiting" -> animationEnd -> unmount
+ *
+ * CSS classes: concertina-glide-entering, concertina-glide-exiting
+ */
+declare const Glide: react.ForwardRefExoticComponent<GlideProps & react.RefAttributes<HTMLElement>>;
+
 /**
  * Scroll `el` to the top of its nearest scrollable ancestor,
  * clearing any sticky headers. Only adjusts one container's
@@ -155,4 +211,4 @@ interface UseConcertinaReturn {
  */
 declare function useConcertina(): UseConcertinaReturn;
 
-export { type Axis, ConcertinaContext, type ConcertinaRootProps, ConcertinaStore, Content, Item, Root, Slot, type SlotProps, StableSlot, type StableSlotProps, type UseConcertinaReturn, pinToScrollTop, useConcertina, useExpanded, useStableSlot, useTransitionLock };
+export { type Axis, ConcertinaContext, type ConcertinaRootProps, ConcertinaStore, Content, Gigbag, type GigbagProps, Glide, type GlideProps, Item, Root, Slot, type SlotProps, StableSlot, type StableSlotProps, type UseConcertinaReturn, Warmup, type WarmupProps, pinToScrollTop, useConcertina, useExpanded, useStableSlot, useTransitionLock };

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". */
@@ -113,6 +115,60 @@ declare function useTransitionLock(): {
     readonly lock: () => void;
 };
 
+interface GigbagProps extends HTMLAttributes<HTMLElement> {
+    /** Which axis to ratchet. Default: "height". */
+    axis?: Axis;
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Size-reserving container.
+ *
+ * Remembers its largest-ever size (ResizeObserver ratchet) and never
+ * shrinks. Swap a spinner for a table inside — no reflow.
+ *
+ * Uses `contain: layout style` to isolate internal reflow from
+ * ancestors.
+ */
+declare const Gigbag: react.ForwardRefExoticComponent<GigbagProps & react.RefAttributes<HTMLElement>>;
+
+interface WarmupProps extends HTMLAttributes<HTMLElement> {
+    /** Number of placeholder rows. Default: 3. */
+    rows?: number;
+    /** Number of columns per row. Default: 1. */
+    columns?: number;
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Structural placeholder — CSS-only shimmer grid.
+ *
+ * Renders `rows x columns` animated bones that approximate the
+ * dimensions of the real content. Pair with <Gigbag> so the
+ * container ratchets to the larger of placeholder vs real content.
+ *
+ * All dimensions are CSS custom properties — consuming apps theme
+ * without forking.
+ */
+declare const Warmup: react.ForwardRefExoticComponent<WarmupProps & react.RefAttributes<HTMLElement>>;
+
+interface GlideProps extends HTMLAttributes<HTMLElement> {
+    /** Whether the content is visible. */
+    show: boolean;
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Enter/exit animation wrapper.
+ *
+ * State machine:
+ *   show=true  -> mount + "entering" -> animationEnd -> "entered"
+ *   show=false -> "exiting" -> animationEnd -> unmount
+ *
+ * CSS classes: concertina-glide-entering, concertina-glide-exiting
+ */
+declare const Glide: react.ForwardRefExoticComponent<GlideProps & react.RefAttributes<HTMLElement>>;
+
 /**
  * Scroll `el` to the top of its nearest scrollable ancestor,
  * clearing any sticky headers. Only adjusts one container's
@@ -155,4 +211,4 @@ interface UseConcertinaReturn {
  */
 declare function useConcertina(): UseConcertinaReturn;
 
-export { type Axis, ConcertinaContext, type ConcertinaRootProps, ConcertinaStore, Content, Item, Root, Slot, type SlotProps, StableSlot, type StableSlotProps, type UseConcertinaReturn, pinToScrollTop, useConcertina, useExpanded, useStableSlot, useTransitionLock };
+export { type Axis, ConcertinaContext, type ConcertinaRootProps, ConcertinaStore, Content, Gigbag, type GigbagProps, Glide, type GlideProps, Item, Root, Slot, type SlotProps, StableSlot, type StableSlotProps, type UseConcertinaReturn, Warmup, type WarmupProps, pinToScrollTop, useConcertina, useExpanded, useStableSlot, useTransitionLock };

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,
@@ -1228,19 +1222,107 @@ function useStableSlot(options = {}) {
   return { ref, style };
 }
 
-// src/use-concertina.ts
+// src/gigbag.tsx
+import { forwardRef as forwardRef9 } from "react";
+import { jsx as jsx13 } from "react/jsx-runtime";
+var Gigbag = forwardRef9(
+  function Gigbag2({ axis = "height", as: Tag = "div", className, style, children, ...props }, fwdRef) {
+    const { ref: ratchetRef, style: ratchetStyle } = useStableSlot({ axis });
+    const merged = className ? `concertina-gigbag ${className}` : "concertina-gigbag";
+    return /* @__PURE__ */ jsx13(
+      Tag,
+      {
+        ref: (el) => {
+          ratchetRef(el);
+          if (typeof fwdRef === "function") fwdRef(el);
+          else if (fwdRef) fwdRef.current = el;
+        },
+        className: merged,
+        style: { ...ratchetStyle, ...style },
+        ...props,
+        children
+      }
+    );
+  }
+);
+
+// src/warmup.tsx
+import { forwardRef as forwardRef10 } from "react";
+import { jsx as jsx14 } from "react/jsx-runtime";
+var Warmup = forwardRef10(
+  function Warmup2({ rows = 3, columns = 1, as: Tag = "div", className, children, ...props }, ref) {
+    const merged = className ? `concertina-warmup ${className}` : "concertina-warmup";
+    const cells = Array.from({ length: rows * columns }, (_, i) => /* @__PURE__ */ jsx14("div", { className: "concertina-warmup-bone" }, i));
+    return /* @__PURE__ */ jsx14(
+      Tag,
+      {
+        ref,
+        className: merged,
+        style: { gridTemplateColumns: `repeat(${columns}, 1fr)` },
+        ...props,
+        children: cells
+      }
+    );
+  }
+);
+
+// src/glide.tsx
 import {
+  forwardRef as forwardRef11,
   useState as useState7,
-  useCallback as useCallback9,
+  useEffect as useEffect6,
+  useCallback as useCallback9
+} from "react";
+import { jsx as jsx15 } from "react/jsx-runtime";
+var Glide = forwardRef11(
+  function Glide2({ show, as: Tag = "div", className, children, ...props }, ref) {
+    const [mounted, setMounted] = useState7(show);
+    const [phase, setPhase] = useState7(show ? "entered" : "exiting");
+    useEffect6(() => {
+      if (show) {
+        setMounted(true);
+        setPhase("entering");
+      } else if (mounted) {
+        setPhase("exiting");
+      }
+    }, [show]);
+    const onAnimationEnd = useCallback9(
+      (e) => {
+        if (e.target !== e.currentTarget) return;
+        if (phase === "entering") setPhase("entered");
+        if (phase === "exiting") setMounted(false);
+      },
+      [phase]
+    );
+    if (!mounted) return null;
+    const phaseClass = phase === "entering" ? "concertina-glide-entering" : phase === "exiting" ? "concertina-glide-exiting" : "";
+    const merged = ["concertina-glide", phaseClass, className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsx15(
+      Tag,
+      {
+        ref,
+        className: merged,
+        onAnimationEnd,
+        ...props,
+        children
+      }
+    );
+  }
+);
+
+// src/use-concertina.ts
+import {
+  useState as useState8,
+  useCallback as useCallback10,
   useRef as useRef7,
   useLayoutEffect as useLayoutEffect4,
-  useEffect as useEffect6
+  useEffect as useEffect7
 } from "react";
 function useConcertina() {
-  const [value, setValue] = useState7("");
-  const [switching, setSwitching] = useState7(false);
+  const [value, setValue] = useState8("");
+  const [switching, setSwitching] = useState8(false);
   const itemRefs = useRef7({});
-  const onValueChange = useCallback9(
+  const onValueChange = useCallback10(
     (newValue) => {
       if (!newValue) {
         setSwitching(false);
@@ -1256,10 +1338,10 @@ function useConcertina() {
     if (!value) return;
     pinToScrollTop(itemRefs.current[value]);
   }, [value]);
-  useEffect6(() => {
+  useEffect7(() => {
     if (switching) setSwitching(false);
   }, [switching]);
-  const getItemRef = useCallback9(
+  const getItemRef = useCallback10(
     (id) => (el) => {
       itemRefs.current[id] = el;
     },
@@ -1276,12 +1358,15 @@ export {
   ConcertinaContext,
   ConcertinaStore,
   Content3 as Content,
+  Gigbag,
+  Glide,
   Header,
   Item2 as Item,
   Root3 as Root,
   Slot,
   StableSlot,
   Trigger2 as Trigger,
+  Warmup,
   pinToScrollTop,
   useConcertina,
   useExpanded,

package/dist/styles.css

@@ -54,10 +54,62 @@
 }
 
 /* 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;
+}
+
+/* Gigbag — size-reserving container.
+   contain isolates internal reflow from ancestors. */
+.concertina-gigbag {
+  contain: layout style;
+}
+
+/* Warmup — structural placeholder shimmer grid. */
+.concertina-warmup {
+  display: grid;
+  gap: var(--concertina-warmup-gap, 0.75rem);
+  contain: layout style;
+}
+
+.concertina-warmup-bone {
+  height: var(--concertina-warmup-bone-height, 1rem);
+  border-radius: var(--concertina-warmup-bone-radius, 0.25rem);
+  background: var(--concertina-warmup-bone-color, #e5e7eb);
+  animation: concertina-shimmer 1.5s ease-in-out infinite;
+}
+
+@keyframes concertina-shimmer {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+
+/* Glide — enter/exit animation wrapper. */
+.concertina-glide {
+  --concertina-glide-duration: 200ms;
+}
+
+.concertina-glide-entering {
+  animation: concertina-glide-in var(--concertina-glide-duration) ease-out;
+}
+
+.concertina-glide-exiting {
+  animation: concertina-glide-out var(--concertina-glide-duration) ease-out forwards;
+}
+
+@keyframes concertina-glide-in {
+  from { opacity: 0; max-height: 0; overflow: hidden; }
+  to   { opacity: 1; max-height: var(--concertina-glide-height, 1000px); overflow: hidden; }
+}
+
+@keyframes concertina-glide-out {
+  from { opacity: 1; max-height: var(--concertina-glide-height, 1000px); overflow: hidden; }
+  to   { opacity: 0; max-height: 0; overflow: hidden; }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concertina",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "React toolkit for layout stability.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -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"
   },