concertina 0.8.1 → 0.9.0

package/README.md

@@ -14,21 +14,29 @@
 
 <p align="center"><b>47 tests</b> &middot; 716 lines of source &middot; 1 dependency</p>
 
-## Why this exists
+## The problem
 
-Concertina started because accordions in React are broken. You click an item, it expands, and the thing you just clicked scrolls off the screen. The browser shoved everything down to make room and now you're staring at content you didn't ask for while the thing you wanted is somewhere above you. On mobile it's worse — `scrollIntoView` grabs the entire viewport and drags it around like a dog with a sock.
+Layout shift happens when the browser changes the size of a box and moves everything else to compensate. A button swaps for a stepper — the text next to it reflows. A spinner becomes a table — the page jumps 400 pixels. An accordion opens — the thing you clicked scrolls off the screen.
 
-So concertina started as an accordion wrapper with scroll pinning. But the deeper we got, the more we realized accordions are just one instance of a bigger problem: things change size and the browser moves everything else to compensate. Swap a button for a stepper. Replace a spinner with a table. Mount a panel. Unmount it. Same disease, every time.
+The React ecosystem treats this as a **state problem**. Suspense, skeleton libraries, loading spinners — they model the transition between pending and loaded. They give you a nice-looking placeholder that's a completely different DOM structure from the real content, then act surprised when the swap causes a jump.
 
-The core idea is almost embarrassingly simple: don't swap things. Render all the variants at the same time, in the same grid cell, stacked on top of each other. The cell sizes itself to the biggest one. You toggle which one is visible. The box never changes size because all the variants are always in there. No measurement, no ResizeObserver, no layout effect. CSS grid figured it out on the first frame because that's what it already does.
+It's not a state problem. It's a **structure problem.** The box changed size because you swapped the structure inside it.
 
-That covers the most common source of layout shift. Two cases it doesn't cover:
+## The fix
 
-1. **Data loads.** A spinner sits at 48 pixels. The real table shows up at 500. The scroll region has an episode. You can't enumerate all variants upfront because the content is dynamic, so you need a container that remembers its biggest size and refuses to shrink.
+Don't swap structures. Swap what's inside them.
 
-2. **Conditional content.** A panel mounts or unmounts. Everything below it teleports in a single frame. No transition. No grace. On, off, furniture moved.
+Every tool in concertina is a different expression of this one idea:
 
-Concertina has a small primitive for each.
+| What changes | Tool | How it works |
+|---|---|---|
+| Which variant is visible | StableSlot + Slot | Render all variants in one grid cell, toggle visibility |
+| Content loading | Gigbag | Container remembers its biggest size, refuses to shrink |
+| Data arriving in a table | Stub data pattern | Same render path for loading and loaded — shimmer or content inside the same wrapper |
+| A panel mounting/unmounting | Glide | Animated enter/exit instead of instant DOM swap |
+| Which accordion item is open | Root + Item + Content | Scroll pinning keeps the opened item visible |
+
+Structure is the contract. Content is what varies. If you internalize that, the API is obvious. If you don't, no amount of tooling will save you.
 
 ## Install
 
@@ -41,9 +49,13 @@ import * as Concertina from "concertina";
 import "concertina/styles.css";
 ```
 
-## Variant switching: StableSlot + Slot
+---
+
+## StableSlot + Slot
 
-Your layout shifts when you swap components because the new one is a different size and the browser just rolls with it. The fix: don't swap them. Render all of them at the same time, same grid cell, stacked. The cell sizes to the biggest one. Toggle visibility. The box can't change size. All the variants are always in there.
+Two components swap in one slot. An "Add" button becomes a quantity stepper. The stepper is wider. The text next to it jumps left.
+
+The fix: don't swap them. Render both at the same time, in the same grid cell, stacked. The cell sizes to the bigger one. Toggle which one is visible. The box never changes size because both variants are always in there.
 
 ```tsx
 <Concertina.StableSlot axis="width" className="action-slot">
@@ -108,11 +120,11 @@ Every independently appearing element needs its own StableSlot. An Undo link tha
 </div>
 ```
 
-A single Slot inside a StableSlot is valid. It reserves the element's space, showing or hiding it without shift. This is fine. This is good actually.
+A single Slot inside a StableSlot is valid. It reserves the element's space, showing or hiding it without shift.
 
-## Progressive loading: Gigbag + Warmup
+---
 
-You've seen this a thousand times:
+## Gigbag + Warmup
 
 ```jsx
 if (loading) return <Spinner />;      // 48px
@@ -120,11 +132,11 @@ if (empty)   return <EmptyMsg />;     // 64px
 return <BigTable data={data} />;      // 500px+
 ```
 
-The spinner is 48 pixels. The table is 500. When the data arrives, the container quintuples in height and everything the user was looking at gets launched off screen.
+Three different structures, three different heights. Every transition jumps.
 
-Gigbag is a container that remembers its largest-ever size via ResizeObserver and will not shrink. Will not. Put a spinner in there, then a table, then a spinner again — it stays at the table's height the whole time. Like a guitar case. You don't reshape the case every time you take the guitar out. The case is the size of the guitar. Always. It also uses `contain: layout style` so internal reflows don't bother the ancestors.
+Gigbag is a container that remembers its largest-ever size via ResizeObserver and will not shrink. Put a spinner in there, then a table, then a spinner again — it stays at the table's height the whole time. Like a guitar case. You don't reshape the case every time you take the guitar out. It also uses `contain: layout style` so internal reflows don't bother the ancestors.
 
-Warmup is a CSS-only shimmer grid that goes inside the Gigbag while you're loading. Instead of a spinner that tells the browser nothing about what's coming, the Warmup looks like the content. Rows. Columns. Pulsing. The browser knows how tall things will be because you told it. With shapes.
+Warmup is a CSS-only shimmer grid that goes inside the Gigbag while you're loading. Instead of a spinner that tells the browser nothing about what's coming, the Warmup approximates the content's shape. The browser knows how tall things will be because you told it.
 
 ```tsx
 <Concertina.Gigbag axis="height">
@@ -136,7 +148,7 @@ Warmup is a CSS-only shimmer grid that goes inside the Gigbag while you're loadi
 </Concertina.Gigbag>
 ```
 
-The Gigbag ratchets to whichever is taller. On subsequent re-fetches it holds at the table's height instead of collapsing back. The data can come and go. The container does not care.
+The Gigbag ratchets to whichever child is taller. On subsequent re-fetches it holds at the table's height instead of collapsing back.
 
 ### Gigbag props
 
@@ -155,7 +167,7 @@ The Gigbag ratchets to whichever is taller. On subsequent re-fetches it holds at
 
 ### Theming Warmup
 
-All dimensions are CSS custom properties. Override them to match your app:
+All dimensions are CSS custom properties:
 
 ```css
 .concertina-warmup {
@@ -166,9 +178,186 @@ All dimensions are CSS custom properties. Override them to match your app:
 }
 ```
 
-## Conditional content: Glide
+### Shimmer dimensions come from the text styles, not from the shimmer
+
+This is the single most important thing in the library and the easiest to get wrong.
+
+A shimmer line replaces text. It needs to be exactly as tall as the text it replaces. For 17 years, CSS had no unit for "one line of text." `em` is font-size, not line-height. `rem` is the root font-size. `px` is absolute. Every shimmer library picked a number — `height: 0.75em`, `height: 12px`, `height: 1rem` — and it was wrong, because text height is determined by line-height, which is determined by the font styles on the element. A shimmer that invents its own height is a shimmer that shifts layout when the real text arrives.
+
+CSS now has the `lh` unit. `1lh` resolves to the element's computed line-height. The shimmer uses `height: 1lh`. That's not a magic number — it's a relative unit that derives its value from the element's styles, the same way `100%` derives its value from the container's size.
+
+But `1lh` only works if the shimmer has the right styles. A bare `<div className="concertina-warmup-line" />` inherits line-height from its parent. If it's inside a `<span className="text-sm">`, it inherits `text-sm`'s line-height. Correct. But if it's a direct child of a toolbar with no font context, `1lh` resolves against the default line-height. Wrong.
+
+**The `WarmupLine` component exists so you can pass the text styles explicitly:**
+
+```tsx
+// Toolbar — no parent provides text styles, so pass them directly
+{loading
+  ? <Concertina.WarmupLine className="text-sm text-stone flex-1" />
+  : <span className="text-sm text-stone">{count} customers</span>
+}
+
+// Grid cell — parent wrapper provides text styles via inheritance
+<span className="table-val-primary">
+  {row._warmup
+    ? <div className="concertina-warmup-line" />
+    : row.name
+  }
+</span>
+```
+
+In grid cells, the shimmer inherits from its wrapper (wrapper-once pattern). In standalone contexts like toolbars, pass the same `className` you'd put on the text element. The shimmer's `1lh` resolves against those styles and matches the text exactly.
+
+**Width** comes from the container, not the shimmer. In a grid cell, the column definition provides width (`minmax(4rem, auto)`). In a flex toolbar, pass `flex-1` so the shimmer fills the available space. The shimmer never invents a width — it fills whatever its context provides.
+
+```css
+/* The shimmer stretches to fill whatever its container provides */
+grid-template-columns: minmax(10rem, 2fr) minmax(3rem, auto) minmax(4.5rem, auto) auto;
+/*                      name column         qty column          total column        action (StableSlot) */
+```
+
+One thing knows the expected content width: the grid column definition. Zero things should guess it.
+
+---
+
+## The stub-data pattern
+
+Gigbag + Warmup works for flat containers. But when your content renders through structured components — an accordion with `Root > Item > Trigger > Content`, or a data table with cell wrappers — a separate loading skeleton is a different DOM structure. Different wrappers, different padding, different height. The swap from skeleton to real content shifts layout. It has to. The structures are different.
+
+This is where the core principle applies directly. Don't build a separate loading path. **Pass placeholder data through the same render path as real data.**
+
+### How it works
+
+Create stub objects with the same shape as your real data, marked with a `_warmup` flag. Pass them to the same component that renders real data. Each cell renders shimmer or content inside the same wrapper — one wrapper definition, ternary on the guts:
+
+```tsx
+// Stub data — same shape as real rows
+const STUB_ROWS = Array.from({ length: 8 }, (_, i) => ({
+  _warmup: true as const,
+  id: `warmup-${i}`,
+  name: null,
+  items: [],
+}));
+
+// Cell renderer — wrapper defined once, content varies inside it
+cell: ({ row }) => (
+  <span className="table-val-primary">
+    {row.original._warmup
+      ? <div className="concertina-warmup-line" />
+      : row.original.name
+    }
+  </span>
+)
+
+// Table component — no separate loading branch
+function MyTable({ data, loading }) {
+  return (
+    <Concertina.Root>
+      {(loading ? STUB_ROWS : data).map((row) => (
+        <Concertina.Item key={row.id} value={row.id}>
+          <Concertina.Trigger>
+            {/* cells render shimmer or content in the same wrappers */}
+          </Concertina.Trigger>
+          <Concertina.Content>
+            {row._warmup ? null : <DetailPanel row={row} />}
+          </Concertina.Content>
+        </Concertina.Item>
+      ))}
+    </Concertina.Root>
+  );
+}
+```
+
+The stub rows go through `Root > Item > Trigger > Content` — the exact same components as real rows. The `Content` element exists in the DOM (collapsed, zero height) for both stubs and real data. Every wrapper, every padding, every border is identical. The only difference is what's inside the cells.
+
+### The wrapper-once rule
+
+This is the part that matters. The wrapper is the structural contract — it determines padding, font-size, line-height, and therefore the cell's height. Define it once. Put the ternary inside it. Never write the wrapper in two branches.
+
+```tsx
+// WRONG — wrapper duplicated, will drift apart silently
+if (row.original._warmup) {
+  return <span className="table-val-money"><div className="concertina-warmup-line" /></span>;
+}
+return <span className="table-val-money">${total}</span>;
+
+// RIGHT — wrapper defined once, content switches inside it
+<span className="table-val-money">
+  {row.original._warmup
+    ? <div className="concertina-warmup-line" />
+    : `$${total}`
+  }
+</span>
+```
+
+When the wrapper is duplicated across branches, it will drift. Someone adds a class to the live branch, forgets the warmup branch. The heights diverge. Layout shifts. And nobody notices until a user watches their screen jump on every page load.
 
-`{show && <Panel />}`. The panel is either in the DOM or it's not. When it enters, everything below it gets shoved down in a single frame. When it leaves, everything snaps back up. It's a light switch that also moves your furniture.
+One wrapper. One definition. Ternary on the guts. That's the whole rule.
+
+### Action columns with StableSlot
+
+For columns with interactive controls, pass `null` as the entity during warmup. The StableSlot still renders all variants in `visibility: hidden`, reserving the exact same space:
+
+```tsx
+<ActionCell entity={row._warmup ? null : row} />
+```
+
+### What TypeScript enforces (and what it doesn't)
+
+A discriminated union guarantees you check `_warmup` before accessing real data:
+
+```ts
+type WarmupRow = {
+  _warmup: true;
+  id: string;
+};
+
+type RealRow = {
+  _warmup?: never;
+  id: string;
+  name: string;
+  items: Item[];
+};
+
+type Row = WarmupRow | RealRow;
+```
+
+The compiler forces the branch:
+
+```ts
+function renderCell(row: Row) {
+  // TS error: 'name' doesn't exist on WarmupRow
+  return <span className="table-val-primary">{row.name}</span>;
+
+  // compiles — wrapper once, ternary inside
+  return (
+    <span className="table-val-primary">
+      {row._warmup
+        ? <div className="concertina-warmup-line" />
+        : row.name  // TS narrows to RealRow here
+      }
+    </span>
+  );
+}
+```
+
+You can't access `row.name` without checking `_warmup` first. A cell renderer that forgets the check fails at build time.
+
+**What TypeScript does NOT enforce:** that you use the wrapper-once pattern. The compiler can't see inside JSX structure. This compiles without error and shifts layout:
+
+```ts
+// TS is happy. Layout shifts anyway. Don't do this.
+if (row._warmup) return <div className="concertina-warmup-line" />;
+return <span className="table-val-primary">{row.name}</span>;
+```
+
+TypeScript prevents you from forgetting the branch. The wrapper-once pattern prevents you from forgetting the wrapper. Use both.
+
+---
+
+## Glide
+
+`{show && <Panel />}`. The panel is either in the DOM or it's not. When it enters, everything below it gets shoved down in a single frame. When it leaves, everything snaps back up. A light switch that also moves your furniture.
 
 Glide wraps conditional content with enter/exit CSS animations and delays unmount until the exit animation finishes. The panel slides in, the panel slides out, content around it moves smoothly.
 
@@ -196,7 +385,9 @@ When `show` goes true, children mount with a `concertina-glide-entering` class.
 }
 ```
 
-The height variable is a ceiling, not an exact value. `max-height` is how you animate height on auto-height elements. `overflow: hidden` clips any overshoot. CSS doesn't give us anything better.
+The height variable is a ceiling, not an exact value. `max-height` is how you animate height on auto-height elements. `overflow: hidden` clips any overshoot.
+
+---
 
 ## Composing them
 
@@ -211,7 +402,9 @@ Gigbag and Glide solve different problems and they compose:
 </Concertina.Glide>
 ```
 
-## Dynamic text: useStableSlot
+---
+
+## useStableSlot
 
 For content that changes size unpredictably (prices, names, status messages) where you can't enumerate all variants upfront. This is what Gigbag uses internally. Use it directly when you want a ref-based API instead of a wrapper component.
 
@@ -229,7 +422,7 @@ const slot = Concertina.useStableSlot({ axis: "width" });
 
 Returns `{ ref, style }`. Attach both to the container element.
 
-## Animation suppression: useTransitionLock
+## useTransitionLock
 
 Suppresses CSS transitions during batched state changes. Sets a flag synchronously (batched with state updates in React 18), auto-clears after paint.
 
@@ -246,7 +439,7 @@ const handleChange = (newValue) => {
 </div>
 ```
 
-## Scroll pinning: pinToScrollTop
+## pinToScrollTop
 
 Scrolls an element to the top of its nearest scrollable ancestor. Only touches `scrollTop` on that one container. Never cascades to the viewport — no full-page drag on mobile. Accounts for sticky headers automatically.
 
@@ -254,6 +447,8 @@ Scrolls an element to the top of its nearest scrollable ancestor. Only touches `
 Concertina.pinToScrollTop(element);
 ```
 
+---
+
 ## Accordion
 
 Wraps Radix Accordion with scroll pinning, animation suppression during switches, and per-item memoization via `useSyncExternalStore`.
@@ -314,6 +509,8 @@ const { rootProps, getItemRef } = Concertina.useConcertina();
 
 If items near the bottom can't scroll to the top, add `padding-bottom: 50vh` to the scroll container.
 
+---
+
 ## Picking the right tool
 
 | Problem | Tool |
@@ -321,6 +518,7 @@ If items near the bottom can't scroll to the top, add `padding-bottom: 50vh` to
 | Two variants swap in one slot | StableSlot + Slot |
 | Text changes width unpredictably | useStableSlot (or CSS `tabular-nums` for numbers) |
 | Spinner replaced by loaded content | Gigbag + Warmup |
+| Accordion/table loading skeleton | Stub data through same render path |
 | Panel mounts/unmounts conditionally | Glide |
 | Accordion with scroll pinning | Root + Item + Content |
 

package/dist/index.cjs

@@ -42,6 +42,7 @@ __export(index_exports, {
   StableSlot: () => StableSlot,
   Trigger: () => Trigger2,
   Warmup: () => Warmup,
+  WarmupLine: () => WarmupLine,
   pinToScrollTop: () => pinToScrollTop,
   useConcertina: () => useConcertina,
   useExpanded: () => useExpanded,
@@ -49,7 +50,8 @@ __export(index_exports, {
   useScrollPin: () => useScrollPin,
   useSize: () => useSize,
   useStableSlot: () => useStableSlot,
-  useTransitionLock: () => useTransitionLock
+  useTransitionLock: () => useTransitionLock,
+  useWarmupExit: () => useWarmupExit
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1306,34 +1308,41 @@ var Warmup = (0, import_react15.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.jsxs)("div", { className: "concertina-warmup-bone", children: [
-      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { className: "concertina-warmup-line concertina-warmup-line-short" }),
-      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { className: "concertina-warmup-line concertina-warmup-line-long" })
+      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { className: "concertina-warmup-line" }),
+      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { className: "concertina-warmup-line" })
     ] }, i));
-    return /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)(
+    return /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(
       Tag,
       {
         ref,
         className: merged,
         style: { gridTemplateColumns: `repeat(${columns}, 1fr)` },
         ...props,
-        children: [
-          children,
-          cells
-        ]
+        children: cells
       }
     );
   }
 );
 
+// src/components/warmup-line.tsx
+var import_react16 = require("react");
+var import_jsx_runtime16 = require("react/jsx-runtime");
+var WarmupLine = (0, import_react16.forwardRef)(
+  function WarmupLine2({ as: Tag = "div", className, ...props }, ref) {
+    const merged = className ? `concertina-warmup-line ${className}` : "concertina-warmup-line";
+    return /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(Tag, { ref, className: merged, ...props });
+  }
+);
+
 // src/components/glide.tsx
-var import_react17 = require("react");
+var import_react18 = require("react");
 
 // src/primitives/use-presence.ts
-var import_react16 = require("react");
+var import_react17 = require("react");
 function usePresence2(show) {
-  const [mounted, setMounted] = (0, import_react16.useState)(show);
-  const [phase, setPhase] = (0, import_react16.useState)(show ? "entered" : "exiting");
-  (0, import_react16.useEffect)(() => {
+  const [mounted, setMounted] = (0, import_react17.useState)(show);
+  const [phase, setPhase] = (0, import_react17.useState)(show ? "entered" : "exiting");
+  (0, import_react17.useEffect)(() => {
     if (show) {
       setMounted(true);
       setPhase("entering");
@@ -1341,7 +1350,7 @@ function usePresence2(show) {
       setPhase("exiting");
     }
   }, [show]);
-  const onAnimationEnd = (0, import_react16.useCallback)(
+  const onAnimationEnd = (0, import_react17.useCallback)(
     (e) => {
       if (e.target !== e.currentTarget) return;
       if (phase === "entering") setPhase("entered");
@@ -1353,14 +1362,14 @@ function usePresence2(show) {
 }
 
 // src/components/glide.tsx
-var import_jsx_runtime16 = require("react/jsx-runtime");
-var Glide = (0, import_react17.forwardRef)(
+var import_jsx_runtime17 = require("react/jsx-runtime");
+var Glide = (0, import_react18.forwardRef)(
   function Glide2({ show, as: Tag = "div", className, children, ...props }, ref) {
     const { mounted, phase, onAnimationEnd } = usePresence2(show);
     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)(
+    return /* @__PURE__ */ (0, import_jsx_runtime17.jsx)(
       Tag,
       {
         ref,
@@ -1374,11 +1383,11 @@ var Glide = (0, import_react17.forwardRef)(
 );
 
 // src/primitives/use-size.ts
-var import_react18 = require("react");
+var import_react19 = require("react");
 function useSize() {
-  const [size, setSize] = (0, import_react18.useState)({ width: 0, height: 0 });
-  const observerRef = (0, import_react18.useRef)(null);
-  const ref = (0, import_react18.useCallback)((el) => {
+  const [size, setSize] = (0, import_react19.useState)({ width: 0, height: 0 });
+  const observerRef = (0, import_react19.useRef)(null);
+  const ref = (0, import_react19.useCallback)((el) => {
     if (observerRef.current) {
       observerRef.current.disconnect();
       observerRef.current = null;
@@ -1406,13 +1415,35 @@ function useSize() {
   return { ref, size };
 }
 
+// src/primitives/use-warmup-exit.ts
+var import_react20 = require("react");
+function useWarmupExit(loading, duration = 150) {
+  const [exiting, setExiting] = (0, import_react20.useState)(false);
+  const prevLoading = (0, import_react20.useRef)(loading);
+  (0, import_react20.useEffect)(() => {
+    if (prevLoading.current && !loading) {
+      setExiting(true);
+      const id = setTimeout(() => setExiting(false), duration);
+      prevLoading.current = loading;
+      return () => clearTimeout(id);
+    }
+    prevLoading.current = loading;
+  }, [loading, duration]);
+  return {
+    /** True during loading AND during exit animation — use for data selection */
+    showWarmup: loading || exiting,
+    /** True only during the exit animation — use for CSS class */
+    exiting
+  };
+}
+
 // src/accordion/use-concertina.ts
-var import_react19 = require("react");
+var import_react21 = require("react");
 function useConcertina() {
-  const [value, setValue] = (0, import_react19.useState)("");
-  const [switching, setSwitching] = (0, import_react19.useState)(false);
-  const itemRefs = (0, import_react19.useRef)({});
-  const onValueChange = (0, import_react19.useCallback)(
+  const [value, setValue] = (0, import_react21.useState)("");
+  const [switching, setSwitching] = (0, import_react21.useState)(false);
+  const itemRefs = (0, import_react21.useRef)({});
+  const onValueChange = (0, import_react21.useCallback)(
     (newValue) => {
       if (!newValue) {
         setSwitching(false);
@@ -1424,14 +1455,14 @@ function useConcertina() {
     },
     [value]
   );
-  (0, import_react19.useLayoutEffect)(() => {
+  (0, import_react21.useLayoutEffect)(() => {
     if (!value) return;
     pinToScrollTop(itemRefs.current[value]);
   }, [value]);
-  (0, import_react19.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     if (switching) setSwitching(false);
   }, [switching]);
-  const getItemRef = (0, import_react19.useCallback)(
+  const getItemRef = (0, import_react21.useCallback)(
     (id) => (el) => {
       itemRefs.current[id] = el;
     },
@@ -1458,6 +1489,7 @@ function useConcertina() {
   StableSlot,
   Trigger,
   Warmup,
+  WarmupLine,
   pinToScrollTop,
   useConcertina,
   useExpanded,
@@ -1465,5 +1497,6 @@ function useConcertina() {
   useScrollPin,
   useSize,
   useStableSlot,
-  useTransitionLock
+  useTransitionLock,
+  useWarmupExit
 });

package/dist/index.d.cts

@@ -105,14 +105,28 @@ interface WarmupProps extends HTMLAttributes<HTMLElement> {
  * dimensions of the real content. Pair with <Gigbag> so the
  * container ratchets to the larger of placeholder vs real content.
  *
- * Pass children to inject structure before the generated bones
- * (e.g. a toolbar placeholder that spans all grid columns).
- *
  * All dimensions are CSS custom properties — consuming apps theme
  * without forking.
  */
 declare const Warmup: react.ForwardRefExoticComponent<WarmupProps & react.RefAttributes<HTMLElement>>;
 
+interface WarmupLineProps extends HTMLAttributes<HTMLElement> {
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Single shimmer line — CSS-aware placeholder for text.
+ *
+ * Sizes itself from inherited text styles (font-size, line-height)
+ * via an invisible `::before` character. No explicit height — the
+ * shimmer IS one line of text in whatever font context it lives in.
+ *
+ * Pass `className` to apply the same text styles as the content
+ * this shimmer stands in for. Width fills the container by default
+ * (block element).
+ */
+declare const WarmupLine: react.ForwardRefExoticComponent<WarmupLineProps & react.RefAttributes<HTMLElement>>;
+
 interface GlideProps extends HTMLAttributes<HTMLElement> {
     /** Whether the content is visible. */
     show: boolean;
@@ -234,6 +248,23 @@ declare function useTransitionLock(): {
  */
 declare function pinToScrollTop(el: HTMLElement | null): void;
 
+/**
+ * Manages the warmup → content transition for stub-data tables.
+ *
+ * When `loading` transitions from true to false, holds stub data
+ * for one animation cycle so warmup lines can fade out before
+ * real content mounts.
+ *
+ * @param loading - Whether data is still loading
+ * @param duration - Exit animation duration in ms (default 150, matches CSS)
+ */
+declare function useWarmupExit(loading: boolean, duration?: number): {
+    /** True during loading AND during exit animation — use for data selection */
+    showWarmup: boolean;
+    /** True only during the exit animation — use for CSS class */
+    exiting: boolean;
+};
+
 interface ConcertinaRootProps {
     value: string;
     onValueChange: (value: string) => void;
@@ -263,4 +294,4 @@ interface UseConcertinaReturn {
  */
 declare function useConcertina(): UseConcertinaReturn;
 
-export { type Axis, ConcertinaContext, type ConcertinaRootProps, ConcertinaStore, Content, Gigbag, type GigbagProps, Glide, type GlideProps, Item, type Phase, Root, type Size, Slot, type SlotProps, StableSlot, type StableSlotProps, type UseConcertinaReturn, type UsePresenceReturn, Warmup, type WarmupProps, pinToScrollTop, useConcertina, useExpanded, usePresence, useScrollPin, useSize, useStableSlot, useTransitionLock };
+export { type Axis, ConcertinaContext, type ConcertinaRootProps, ConcertinaStore, Content, Gigbag, type GigbagProps, Glide, type GlideProps, Item, type Phase, Root, type Size, Slot, type SlotProps, StableSlot, type StableSlotProps, type UseConcertinaReturn, type UsePresenceReturn, Warmup, WarmupLine, type WarmupLineProps, type WarmupProps, pinToScrollTop, useConcertina, useExpanded, usePresence, useScrollPin, useSize, useStableSlot, useTransitionLock, useWarmupExit };

package/dist/index.d.ts

@@ -105,14 +105,28 @@ interface WarmupProps extends HTMLAttributes<HTMLElement> {
  * dimensions of the real content. Pair with <Gigbag> so the
  * container ratchets to the larger of placeholder vs real content.
  *
- * Pass children to inject structure before the generated bones
- * (e.g. a toolbar placeholder that spans all grid columns).
- *
  * All dimensions are CSS custom properties — consuming apps theme
  * without forking.
  */
 declare const Warmup: react.ForwardRefExoticComponent<WarmupProps & react.RefAttributes<HTMLElement>>;
 
+interface WarmupLineProps extends HTMLAttributes<HTMLElement> {
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Single shimmer line — CSS-aware placeholder for text.
+ *
+ * Sizes itself from inherited text styles (font-size, line-height)
+ * via an invisible `::before` character. No explicit height — the
+ * shimmer IS one line of text in whatever font context it lives in.
+ *
+ * Pass `className` to apply the same text styles as the content
+ * this shimmer stands in for. Width fills the container by default
+ * (block element).
+ */
+declare const WarmupLine: react.ForwardRefExoticComponent<WarmupLineProps & react.RefAttributes<HTMLElement>>;
+
 interface GlideProps extends HTMLAttributes<HTMLElement> {
     /** Whether the content is visible. */
     show: boolean;
@@ -234,6 +248,23 @@ declare function useTransitionLock(): {
  */
 declare function pinToScrollTop(el: HTMLElement | null): void;
 
+/**
+ * Manages the warmup → content transition for stub-data tables.
+ *
+ * When `loading` transitions from true to false, holds stub data
+ * for one animation cycle so warmup lines can fade out before
+ * real content mounts.
+ *
+ * @param loading - Whether data is still loading
+ * @param duration - Exit animation duration in ms (default 150, matches CSS)
+ */
+declare function useWarmupExit(loading: boolean, duration?: number): {
+    /** True during loading AND during exit animation — use for data selection */
+    showWarmup: boolean;
+    /** True only during the exit animation — use for CSS class */
+    exiting: boolean;
+};
+
 interface ConcertinaRootProps {
     value: string;
     onValueChange: (value: string) => void;
@@ -263,4 +294,4 @@ interface UseConcertinaReturn {
  */
 declare function useConcertina(): UseConcertinaReturn;
 
-export { type Axis, ConcertinaContext, type ConcertinaRootProps, ConcertinaStore, Content, Gigbag, type GigbagProps, Glide, type GlideProps, Item, type Phase, Root, type Size, Slot, type SlotProps, StableSlot, type StableSlotProps, type UseConcertinaReturn, type UsePresenceReturn, Warmup, type WarmupProps, pinToScrollTop, useConcertina, useExpanded, usePresence, useScrollPin, useSize, useStableSlot, useTransitionLock };
+export { type Axis, ConcertinaContext, type ConcertinaRootProps, ConcertinaStore, Content, Gigbag, type GigbagProps, Glide, type GlideProps, Item, type Phase, Root, type Size, Slot, type SlotProps, StableSlot, type StableSlotProps, type UseConcertinaReturn, type UsePresenceReturn, Warmup, WarmupLine, type WarmupLineProps, type WarmupProps, pinToScrollTop, useConcertina, useExpanded, usePresence, useScrollPin, useSize, useStableSlot, useTransitionLock, useWarmupExit };

package/dist/index.js

@@ -1266,28 +1266,35 @@ 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__ */ jsxs("div", { className: "concertina-warmup-bone", children: [
-      /* @__PURE__ */ jsx14("div", { className: "concertina-warmup-line concertina-warmup-line-short" }),
-      /* @__PURE__ */ jsx14("div", { className: "concertina-warmup-line concertina-warmup-line-long" })
+      /* @__PURE__ */ jsx14("div", { className: "concertina-warmup-line" }),
+      /* @__PURE__ */ jsx14("div", { className: "concertina-warmup-line" })
     ] }, i));
-    return /* @__PURE__ */ jsxs(
+    return /* @__PURE__ */ jsx14(
       Tag,
       {
         ref,
         className: merged,
         style: { gridTemplateColumns: `repeat(${columns}, 1fr)` },
         ...props,
-        children: [
-          children,
-          cells
-        ]
+        children: cells
       }
     );
   }
 );
 
+// src/components/warmup-line.tsx
+import { forwardRef as forwardRef11 } from "react";
+import { jsx as jsx15 } from "react/jsx-runtime";
+var WarmupLine = forwardRef11(
+  function WarmupLine2({ as: Tag = "div", className, ...props }, ref) {
+    const merged = className ? `concertina-warmup-line ${className}` : "concertina-warmup-line";
+    return /* @__PURE__ */ jsx15(Tag, { ref, className: merged, ...props });
+  }
+);
+
 // src/components/glide.tsx
 import {
-  forwardRef as forwardRef11
+  forwardRef as forwardRef12
 } from "react";
 
 // src/primitives/use-presence.ts
@@ -1319,14 +1326,14 @@ function usePresence2(show) {
 }
 
 // src/components/glide.tsx
-import { jsx as jsx15 } from "react/jsx-runtime";
-var Glide = forwardRef11(
+import { jsx as jsx16 } from "react/jsx-runtime";
+var Glide = forwardRef12(
   function Glide2({ show, as: Tag = "div", className, children, ...props }, ref) {
     const { mounted, phase, onAnimationEnd } = usePresence2(show);
     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(
+    return /* @__PURE__ */ jsx16(
       Tag,
       {
         ref,
@@ -1372,18 +1379,40 @@ function useSize() {
   return { ref, size };
 }
 
+// src/primitives/use-warmup-exit.ts
+import { useState as useState9, useEffect as useEffect7, useRef as useRef8 } from "react";
+function useWarmupExit(loading, duration = 150) {
+  const [exiting, setExiting] = useState9(false);
+  const prevLoading = useRef8(loading);
+  useEffect7(() => {
+    if (prevLoading.current && !loading) {
+      setExiting(true);
+      const id = setTimeout(() => setExiting(false), duration);
+      prevLoading.current = loading;
+      return () => clearTimeout(id);
+    }
+    prevLoading.current = loading;
+  }, [loading, duration]);
+  return {
+    /** True during loading AND during exit animation — use for data selection */
+    showWarmup: loading || exiting,
+    /** True only during the exit animation — use for CSS class */
+    exiting
+  };
+}
+
 // src/accordion/use-concertina.ts
 import {
-  useState as useState9,
+  useState as useState10,
   useCallback as useCallback11,
-  useRef as useRef8,
+  useRef as useRef9,
   useLayoutEffect as useLayoutEffect4,
-  useEffect as useEffect7
+  useEffect as useEffect8
 } from "react";
 function useConcertina() {
-  const [value, setValue] = useState9("");
-  const [switching, setSwitching] = useState9(false);
-  const itemRefs = useRef8({});
+  const [value, setValue] = useState10("");
+  const [switching, setSwitching] = useState10(false);
+  const itemRefs = useRef9({});
   const onValueChange = useCallback11(
     (newValue) => {
       if (!newValue) {
@@ -1400,7 +1429,7 @@ function useConcertina() {
     if (!value) return;
     pinToScrollTop(itemRefs.current[value]);
   }, [value]);
-  useEffect7(() => {
+  useEffect8(() => {
     if (switching) setSwitching(false);
   }, [switching]);
   const getItemRef = useCallback11(
@@ -1429,6 +1458,7 @@ export {
   StableSlot,
   Trigger2 as Trigger,
   Warmup,
+  WarmupLine,
   pinToScrollTop,
   useConcertina,
   useExpanded,
@@ -1436,5 +1466,6 @@ export {
   useScrollPin,
   useSize,
   useStableSlot,
-  useTransitionLock
+  useTransitionLock,
+  useWarmupExit
 };

package/dist/styles.css

@@ -87,6 +87,7 @@
 }
 
 .concertina-warmup-line {
+  height: 1lh;
   border-radius: var(--concertina-warmup-line-radius, 0.125rem);
   background: linear-gradient(
     90deg,
@@ -98,21 +99,13 @@
   animation: concertina-shimmer 1.5s ease-in-out infinite;
 }
 
-.concertina-warmup-line-short {
-  height: var(--concertina-warmup-line-short, 0.5rem);
-  width: 40%;
-}
-
-.concertina-warmup-line-long {
-  height: var(--concertina-warmup-line-long, 0.75rem);
-  width: 75%;
-}
 
 @keyframes concertina-shimmer {
   0% { background-position: 200% 0; }
   100% { background-position: -200% 0; }
 }
 
+
 /* Glide — enter/exit animation wrapper. */
 .concertina-glide {
   --concertina-glide-duration: 200ms;
@@ -136,6 +129,16 @@
   to   { opacity: 0; max-height: 0; overflow: hidden; }
 }
 
+/* Warmup exit — fade out shimmer lines before content mounts.
+   Applied by useWarmupExit() via className on the grid container. */
+.concertina-warmup-exiting .concertina-warmup-line {
+  animation: concertina-warmup-exit var(--concertina-close-duration, 150ms) ease-out forwards;
+}
+
+@keyframes concertina-warmup-exit {
+  to { opacity: 0; }
+}
+
 /* Respect reduced-motion preferences.
    Disables all animations — accordion open/close, shimmer, and glide enter/exit.
    Layout changes still happen instantly so functionality is preserved. */
@@ -144,7 +147,8 @@
   .concertina-content[data-state="closed"],
   .concertina-glide-entering,
   .concertina-glide-exiting,
-  .concertina-warmup-line {
+  .concertina-warmup-line,
+  .concertina-warmup-exiting .concertina-warmup-line {
     animation-duration: 0s !important;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concertina",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "React toolkit for layout stability.",
   "type": "module",
   "main": "./dist/index.cjs",