concertina 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Ward
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ryandward/concertina/main/concertina.svg" width="140" alt="concertina" />
+</p>
+
+<h1 align="center">concertina</h1>
+
+<p align="center">
+  React hook for scroll-pinned <a href="https://www.radix-ui.com/primitives/docs/components/accordion">Radix Accordion</a> panels. Zero runtime dependencies.
+</p>
+
+## The problem
+
+Radix Accordion in a scrollable container breaks in several ways at once. Switching between items plays both a close and open animation, so the scroll position jumps. Calling `scrollIntoView` to fix it cascades to the viewport on mobile and yanks the whole page. Using `flushSync` with inline styles to work around that fights Radix re-renders. Layout measurement happens before animations finish, so scroll targets are wrong. And suppressing animations for the switch has to be temporary or you lose them entirely.
+
+These five issues interact. `concertina` solves them together.
+
+## Install
+
+```bash
+npm install concertina
+```
+
+## Usage
+
+```tsx
+import { useConcertina } from "concertina";
+import "concertina/styles.css";
+import * as Accordion from "@radix-ui/react-accordion";
+
+function MyAccordion({ items }) {
+  const { rootProps, getItemRef } = useConcertina();
+
+  return (
+    <Accordion.Root type="single" collapsible {...rootProps}>
+      {items.map((item) => (
+        <Accordion.Item
+          key={item.id}
+          value={item.id}
+          ref={getItemRef(item.id)}
+        >
+          <Accordion.Header>
+            <Accordion.Trigger>{item.title}</Accordion.Trigger>
+          </Accordion.Header>
+          <Accordion.Content className="concertina-content">
+            {item.content}
+          </Accordion.Content>
+        </Accordion.Item>
+      ))}
+    </Accordion.Root>
+  );
+}
+```
+
+## How it works
+
+The hook tracks which item is open via `value`/`onValueChange`. When switching from one item to another, it sets a `data-switching` attribute on the root. CSS rules keyed to that attribute skip the close/open animations so layout settles in one frame. A `useLayoutEffect` then adjusts the scroll container's `scrollTop` to pin the new item to the top (never `scrollIntoView`, which cascades). After paint, a `useEffect` clears the flag so the next interaction animates normally.
+
+## API
+
+### `useConcertina()`
+
+| Property | Type | Description |
+|---|---|---|
+| `value` | `string` | Currently expanded item, empty string when collapsed |
+| `onValueChange` | `(value: string) => void` | Change handler with switching logic built in |
+| `switching` | `boolean` | `true` during a switch between items |
+| `rootProps` | `object` | Spread onto `Accordion.Root` (includes `value`, `onValueChange`, `data-switching`) |
+| `getItemRef` | `(id: string) => RefCallback` | Ref callback for each `Accordion.Item` |
+
+### `pinToScrollTop(el)`
+
+Also exported standalone. Scrolls `el` to the top of its nearest `overflow-y: auto|scroll` ancestor without touching the viewport.
+
+## Styling
+
+Import `concertina/styles.css` for the default expand/collapse animations. Override timing with CSS custom properties on `.concertina-content`:
+
+```css
+.concertina-content {
+  --concertina-open-duration: 300ms;
+  --concertina-close-duration: 200ms;
+}
+```
+
+Put `.concertina-content` on your `Accordion.Content` elements. The `[data-switching]` suppression rules are handled automatically.
+
+If items near the bottom of your scroll container can't reach the top, add bottom padding:
+
+```css
+.my-scroll-container {
+  padding-bottom: 50vh;
+}
+```
+
+## Requirements
+
+- React >= 16.8
+- `@radix-ui/react-accordion`
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,88 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  pinToScrollTop: () => pinToScrollTop,
+  useConcertina: () => useConcertina
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/use-concertina.ts
+var import_react = require("react");
+
+// src/pin-to-scroll-top.ts
+function pinToScrollTop(el) {
+  if (!el) return;
+  let parent = el.parentElement;
+  while (parent) {
+    const { overflowY } = getComputedStyle(parent);
+    if (overflowY === "auto" || overflowY === "scroll") {
+      const box = parent.getBoundingClientRect();
+      const target = el.getBoundingClientRect();
+      parent.scrollTop += target.top - box.top;
+      return;
+    }
+    parent = parent.parentElement;
+  }
+}
+
+// src/use-concertina.ts
+function useConcertina() {
+  const [value, setValue] = (0, import_react.useState)("");
+  const [switching, setSwitching] = (0, import_react.useState)(false);
+  const itemRefs = (0, import_react.useRef)({});
+  const onValueChange = (0, import_react.useCallback)(
+    (newValue) => {
+      if (!newValue) {
+        setSwitching(false);
+        setValue("");
+        return;
+      }
+      setSwitching(!!value && value !== newValue);
+      setValue(newValue);
+    },
+    [value]
+  );
+  (0, import_react.useLayoutEffect)(() => {
+    if (!value) return;
+    pinToScrollTop(itemRefs.current[value]);
+  }, [value]);
+  (0, import_react.useEffect)(() => {
+    if (switching) setSwitching(false);
+  }, [switching]);
+  const getItemRef = (0, import_react.useCallback)(
+    (id) => (el) => {
+      itemRefs.current[id] = el;
+    },
+    []
+  );
+  const rootProps = {
+    value,
+    onValueChange,
+    ...switching ? { "data-switching": true } : {}
+  };
+  return { value, onValueChange, switching, rootProps, getItemRef };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  pinToScrollTop,
+  useConcertina
+});

package/dist/index.d.cts

@@ -0,0 +1,39 @@
+interface ConcertinaRootProps {
+    value: string;
+    onValueChange: (value: string) => void;
+    "data-switching"?: true;
+}
+interface UseConcertinaReturn {
+    /** Currently expanded item value, empty string when collapsed. */
+    value: string;
+    /** Change handler. Manages switching state automatically. */
+    onValueChange: (value: string) => void;
+    /** True during a switch between items (animations suppressed). */
+    switching: boolean;
+    /** Spread onto Accordion.Root. Includes value, onValueChange, data-switching. */
+    rootProps: ConcertinaRootProps;
+    /** Returns a ref callback for an Accordion.Item. Pass the item's value. */
+    getItemRef: (id: string) => (el: HTMLElement | null) => void;
+}
+/**
+ * React hook for scroll-pinned Radix Accordion panels.
+ *
+ * Handles five things:
+ * 1. Suppresses close/open animations when switching between items
+ * 2. Pins the newly opened item to the top of the scroll container
+ * 3. Uses scrollTop adjustment instead of scrollIntoView (no viewport cascade)
+ * 4. Coordinates React state batching so layout is final before scroll measurement
+ * 5. Clears the switching flag after paint so future animations work normally
+ */
+declare function useConcertina(): UseConcertinaReturn;
+
+/**
+ * Scroll `el` to the top of its nearest scrollable ancestor.
+ *
+ * Only adjusts one container's scrollTop. Never cascades to the
+ * viewport, which matters on mobile where scrollIntoView pulls
+ * the whole page.
+ */
+declare function pinToScrollTop(el: HTMLElement | null): void;
+
+export { type ConcertinaRootProps, type UseConcertinaReturn, pinToScrollTop, useConcertina };

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+interface ConcertinaRootProps {
+    value: string;
+    onValueChange: (value: string) => void;
+    "data-switching"?: true;
+}
+interface UseConcertinaReturn {
+    /** Currently expanded item value, empty string when collapsed. */
+    value: string;
+    /** Change handler. Manages switching state automatically. */
+    onValueChange: (value: string) => void;
+    /** True during a switch between items (animations suppressed). */
+    switching: boolean;
+    /** Spread onto Accordion.Root. Includes value, onValueChange, data-switching. */
+    rootProps: ConcertinaRootProps;
+    /** Returns a ref callback for an Accordion.Item. Pass the item's value. */
+    getItemRef: (id: string) => (el: HTMLElement | null) => void;
+}
+/**
+ * React hook for scroll-pinned Radix Accordion panels.
+ *
+ * Handles five things:
+ * 1. Suppresses close/open animations when switching between items
+ * 2. Pins the newly opened item to the top of the scroll container
+ * 3. Uses scrollTop adjustment instead of scrollIntoView (no viewport cascade)
+ * 4. Coordinates React state batching so layout is final before scroll measurement
+ * 5. Clears the switching flag after paint so future animations work normally
+ */
+declare function useConcertina(): UseConcertinaReturn;
+
+/**
+ * Scroll `el` to the top of its nearest scrollable ancestor.
+ *
+ * Only adjusts one container's scrollTop. Never cascades to the
+ * viewport, which matters on mobile where scrollIntoView pulls
+ * the whole page.
+ */
+declare function pinToScrollTop(el: HTMLElement | null): void;
+
+export { type ConcertinaRootProps, type UseConcertinaReturn, pinToScrollTop, useConcertina };

package/dist/index.js

@@ -0,0 +1,66 @@
+// src/use-concertina.ts
+import {
+  useState,
+  useCallback,
+  useRef,
+  useLayoutEffect,
+  useEffect
+} from "react";
+
+// src/pin-to-scroll-top.ts
+function pinToScrollTop(el) {
+  if (!el) return;
+  let parent = el.parentElement;
+  while (parent) {
+    const { overflowY } = getComputedStyle(parent);
+    if (overflowY === "auto" || overflowY === "scroll") {
+      const box = parent.getBoundingClientRect();
+      const target = el.getBoundingClientRect();
+      parent.scrollTop += target.top - box.top;
+      return;
+    }
+    parent = parent.parentElement;
+  }
+}
+
+// src/use-concertina.ts
+function useConcertina() {
+  const [value, setValue] = useState("");
+  const [switching, setSwitching] = useState(false);
+  const itemRefs = useRef({});
+  const onValueChange = useCallback(
+    (newValue) => {
+      if (!newValue) {
+        setSwitching(false);
+        setValue("");
+        return;
+      }
+      setSwitching(!!value && value !== newValue);
+      setValue(newValue);
+    },
+    [value]
+  );
+  useLayoutEffect(() => {
+    if (!value) return;
+    pinToScrollTop(itemRefs.current[value]);
+  }, [value]);
+  useEffect(() => {
+    if (switching) setSwitching(false);
+  }, [switching]);
+  const getItemRef = useCallback(
+    (id) => (el) => {
+      itemRefs.current[id] = el;
+    },
+    []
+  );
+  const rootProps = {
+    value,
+    onValueChange,
+    ...switching ? { "data-switching": true } : {}
+  };
+  return { value, onValueChange, switching, rootProps, getItemRef };
+}
+export {
+  pinToScrollTop,
+  useConcertina
+};

package/dist/styles.css

@@ -0,0 +1,54 @@
+/* concertina — Radix Accordion expand/collapse with scroll pinning support
+ *
+ * Add .concertina-content to your Accordion.Content elements.
+ * The [data-switching] rules are managed automatically by useConcertina().
+ */
+
+.concertina-content {
+  --concertina-open-duration: 200ms;
+  --concertina-close-duration: 150ms;
+  overflow: hidden;
+}
+
+.concertina-content[data-state="open"] {
+  animation: concertina-open var(--concertina-open-duration) ease-out;
+}
+
+.concertina-content[data-state="closed"] {
+  animation: concertina-close var(--concertina-close-duration) ease-out forwards;
+}
+
+@keyframes concertina-open {
+  from {
+    height: 0;
+    opacity: 0;
+  }
+  to {
+    height: var(--radix-accordion-content-height);
+    opacity: 1;
+  }
+}
+
+@keyframes concertina-close {
+  from {
+    height: var(--radix-accordion-content-height);
+    opacity: 1;
+  }
+  to {
+    height: 0;
+    opacity: 0;
+  }
+}
+
+/* When switching between items, suppress all animations so the layout
+   is immediately in its final state for scroll pinning.
+   data-switching is set by useConcertina(), cleared after paint. */
+[data-switching] .concertina-content[data-state="closed"] {
+  animation: none;
+  height: 0;
+  opacity: 0;
+}
+
+[data-switching] .concertina-content[data-state="open"] {
+  animation: none;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "concertina",
+  "version": "0.1.0",
+  "description": "React hook for scroll-pinned Radix Accordion panels. Zero dependencies.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "./dist/styles.css"
+  ],
+  "scripts": {
+    "build": "tsup && cp src/styles.css dist/styles.css",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "radix",
+    "accordion",
+    "scroll",
+    "pin",
+    "react",
+    "hook"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ryandward/concertina"
+  },
+  "author": "Ryan Ward"
+}