concertina 0.6.1 → 0.7.0

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,
@@ -1255,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);
@@ -1273,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;
     },
@@ -1298,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

@@ -115,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
@@ -157,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

@@ -115,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
@@ -157,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

@@ -1222,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);
@@ -1250,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;
     },
@@ -1270,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

@@ -65,3 +65,51 @@
   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.6.1",
+  "version": "0.7.0",
   "description": "React toolkit for layout stability.",
   "type": "module",
   "main": "./dist/index.cjs",