feat(headless): add Accordion primitive

packages/headless/package.json

@@ -5,6 +5,10 @@
   "sideEffects": false,
   "type": "module",
   "exports": {
+    "./accordion": {
+      "import": "./dist/primitives/accordion/index.js",
+      "types": "./dist/primitives/accordion/index.d.ts"
+    },
     "./dialog": {
       "import": "./dist/primitives/dialog/index.js",
       "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/accordion/README.md

@@ -0,0 +1,128 @@
+# Accordion
+
+A vertically stacked set of collapsible sections. Supports single or multiple open panels, keyboard navigation, and CSS-driven expand/collapse animations.
+
+## When to Use
+
+- FAQ sections, settings panels, or any UI where content should be shown/hidden in discrete sections.
+- When you need accessible expand/collapse with proper ARIA attributes and keyboard support.
+- Prefer Accordion over manual show/hide toggles — it handles focus management, ARIA, and animation lifecycle automatically.
+
+## Usage
+
+```tsx
+import { Accordion } from '@/primitives/accordion';
+
+<Accordion.Root
+  type='single'
+  defaultValue={['item-1']}
+>
+  <Accordion.Item value='item-1'>
+    <Accordion.Header>
+      <Accordion.Trigger>Section 1</Accordion.Trigger>
+    </Accordion.Header>
+    <Accordion.Panel>Content for section 1</Accordion.Panel>
+  </Accordion.Item>
+  <Accordion.Item value='item-2'>
+    <Accordion.Header>
+      <Accordion.Trigger>Section 2</Accordion.Trigger>
+    </Accordion.Header>
+    <Accordion.Panel>Content for section 2</Accordion.Panel>
+  </Accordion.Item>
+</Accordion.Root>;
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState<string[]>(['item-1']);
+
+<Accordion.Root
+  value={value}
+  onValueChange={setValue}
+>
+  {/* ... */}
+</Accordion.Root>;
+```
+
+## Parts
+
+| Part                | Default Element | Description                        |
+| ------------------- | --------------- | ---------------------------------- |
+| `Accordion.Root`    | `<div>`         | Root wrapper, provides context     |
+| `Accordion.Item`    | `<div>`         | Wraps a single collapsible section |
+| `Accordion.Header`  | `<h3>`          | Heading wrapper for the trigger    |
+| `Accordion.Trigger` | `<button>`      | Clickable toggle for its panel     |
+| `Accordion.Panel`   | `<div>`         | Collapsible content area           |
+
+## Props
+
+### `Accordion.Root`
+
+| Prop            | Type                        | Default      | Description                               |
+| --------------- | --------------------------- | ------------ | ----------------------------------------- |
+| `value`         | `string[]`                  | —            | Controlled open items                     |
+| `defaultValue`  | `string[]`                  | `[]`         | Initial open items (uncontrolled)         |
+| `onValueChange` | `(value: string[]) => void` | —            | Called when open items change             |
+| `type`          | `"single" \| "multiple"`    | `"multiple"` | `"single"` enforces at most one open item |
+| `disabled`      | `boolean`                   | `false`      | Disables all items                        |
+
+### `Accordion.Item`
+
+| Prop       | Type      | Default       | Description                     |
+| ---------- | --------- | ------------- | ------------------------------- |
+| `value`    | `string`  | **required**  | Unique identifier for this item |
+| `disabled` | `boolean` | inherits root | Disables this specific item     |
+
+### `Accordion.Header`
+
+No additional props. Renders as `<h3>` by default.
+
+### `Accordion.Trigger`
+
+No additional props. Renders as `<button>` by default.
+
+### `Accordion.Panel`
+
+No additional props. Renders as `<div>` by default.
+
+All parts accept a `render` prop for polymorphic rendering and standard HTML attributes for their default element.
+
+## Keyboard Navigation
+
+| Key               | Action                         |
+| ----------------- | ------------------------------ |
+| `ArrowDown`       | Move focus to next trigger     |
+| `ArrowUp`         | Move focus to previous trigger |
+| `Enter` / `Space` | Toggle the focused item        |
+
+## Data Attributes
+
+| Attribute          | Applies To           | Description                                       |
+| ------------------ | -------------------- | ------------------------------------------------- |
+| `data-cl-slot`     | All parts            | Identifies each part (e.g. `"accordion-trigger"`) |
+| `data-cl-open`     | Item, Trigger, Panel | Present when the item is expanded                 |
+| `data-cl-closed`   | Item, Trigger, Panel | Present when the item is collapsed                |
+| `data-cl-disabled` | Item, Trigger        | Present when the item is disabled                 |
+
+## CSS Animation
+
+`Accordion.Panel` exposes a `--cl-accordion-panel-height` CSS custom property set to the panel's `scrollHeight` in pixels. Use this for height-based expand/collapse animations:
+
+```css
+[data-cl-slot='accordion-panel'] {
+  overflow: hidden;
+  height: var(--cl-accordion-panel-height);
+  transition: height 200ms ease;
+}
+[data-cl-slot='accordion-panel'][data-cl-closed] {
+  height: 0;
+}
+```
+
+The panel suppresses the enter animation on initial mount — only subsequent opens animate.
+
+## ARIA
+
+- Trigger: `aria-expanded`, `aria-controls` (pointing to its panel), `aria-disabled`
+- Panel: `role="region"`, `aria-labelledby` (pointing to its trigger)

packages/headless/src/primitives/accordion/accordion-context.ts

@@ -0,0 +1,36 @@
+import { createContext, useContext } from 'react';
+
+export interface AccordionContextValue {
+  value: string[];
+  toggle: (itemValue: string) => void;
+  disabled: boolean;
+  accordionId: string;
+}
+
+export const AccordionContext = createContext<AccordionContextValue | null>(null);
+
+export function useAccordionContext() {
+  const ctx = useContext(AccordionContext);
+  if (!ctx) {
+    throw new Error('Accordion compound components must be used within <Accordion.Root>');
+  }
+  return ctx;
+}
+
+export interface AccordionItemContextValue {
+  itemValue: string;
+  open: boolean;
+  disabled: boolean;
+  triggerId: string;
+  panelId: string;
+}
+
+export const AccordionItemContext = createContext<AccordionItemContextValue | null>(null);
+
+export function useAccordionItemContext() {
+  const ctx = useContext(AccordionItemContext);
+  if (!ctx) {
+    throw new Error('Accordion.Trigger/Header/Panel must be used within <Accordion.Item>');
+  }
+  return ctx;
+}

packages/headless/src/primitives/accordion/accordion-header.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+
+export interface AccordionHeaderProps extends ComponentProps<'h3'> {}
+
+export function AccordionHeader(props: AccordionHeaderProps) {
+  const { render, ...otherProps } = props;
+
+  const defaultProps = {
+    'data-cl-slot': 'accordion-header',
+  };
+
+  return renderElement({
+    defaultTagName: 'h3',
+    render,
+    props: mergeProps<'h3'>(defaultProps, otherProps),
+  });
+}

packages/headless/src/primitives/accordion/accordion-item.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import { useMemo } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { AccordionItemContext, type AccordionItemContextValue, useAccordionContext } from './accordion-context';
+
+export interface AccordionItemProps extends ComponentProps<'div'> {
+  /** Unique value identifying this item. */
+  value: string;
+  /** Disable this specific item. */
+  disabled?: boolean;
+}
+
+export function AccordionItem(props: AccordionItemProps) {
+  const { render, value: itemValue, disabled: itemDisabled, ...otherProps } = props;
+  const ctx = useAccordionContext();
+
+  const open = ctx.value.includes(itemValue);
+  const disabled = itemDisabled ?? ctx.disabled;
+  const triggerId = `${ctx.accordionId}-trigger-${itemValue}`;
+  const panelId = `${ctx.accordionId}-panel-${itemValue}`;
+
+  const itemContextValue = useMemo<AccordionItemContextValue>(
+    () => ({ itemValue, open, disabled, triggerId, panelId }),
+    [itemValue, open, disabled, triggerId, panelId],
+  );
+
+  const state = { open, disabled };
+
+  const defaultProps = {
+    'data-cl-slot': 'accordion-item',
+  };
+
+  return (
+    <AccordionItemContext.Provider value={itemContextValue}>
+      {renderElement({
+        defaultTagName: 'div',
+        render,
+        state,
+        stateAttributesMapping: {
+          open: (v: boolean): Record<string, string> | null => (v ? { 'data-cl-open': '' } : { 'data-cl-closed': '' }),
+          disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+        },
+        props: mergeProps<'div'>(defaultProps, otherProps),
+      })}
+    </AccordionItemContext.Provider>
+  );
+}

packages/headless/src/primitives/accordion/accordion-panel.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+import { type RefObject, useLayoutEffect, useRef, useState } from 'react';
+import { useTransition } from '../../hooks/use-transition';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useAccordionItemContext } from './accordion-context';
+
+export interface AccordionPanelProps extends ComponentProps<'div'> {}
+
+export function AccordionPanel(props: AccordionPanelProps) {
+  const { render, ...otherProps } = props;
+  const { open, triggerId, panelId } = useAccordionItemContext();
+
+  const panelRef = useRef<HTMLElement | null>(null);
+  const [height, setHeight] = useState<number | undefined>(undefined);
+
+  // Track whether open has ever transitioned from true→false.
+  // Until that happens, skip enter animations (prevents animate-on-load).
+  const hasBeenClosed = useRef(false);
+  if (!open) hasBeenClosed.current = true;
+
+  const { mounted, transitionProps } = useTransition({
+    open,
+    ref: panelRef as RefObject<HTMLElement>,
+  });
+
+  // Measure the content height and keep it in sync via ResizeObserver
+  useLayoutEffect(() => {
+    if (!mounted) return;
+
+    const panel = panelRef.current;
+    if (!panel) return;
+
+    // Measure scrollHeight of the panel's content
+    const measure = () => {
+      setHeight(panel.scrollHeight);
+    };
+
+    measure();
+
+    const ro = new ResizeObserver(measure);
+    // Observe children mutations that affect height
+    ro.observe(panel, { box: 'border-box' });
+
+    return () => ro.disconnect();
+  }, [mounted]);
+
+  const state = { open };
+
+  // Skip enter animation for panels that have never been closed
+  const effectiveTransitionProps = !hasBeenClosed.current
+    ? {
+        ...transitionProps,
+        'data-cl-starting-style': undefined,
+        style: undefined,
+      }
+    : transitionProps;
+
+  const defaultProps: Record<string, unknown> = {
+    'data-cl-slot': 'accordion-panel',
+    id: panelId,
+    role: 'region' as const,
+    'aria-labelledby': triggerId,
+    ref: panelRef,
+    ...effectiveTransitionProps,
+    style: {
+      '--cl-accordion-panel-height': height != null ? `${height}px` : undefined,
+      ...effectiveTransitionProps.style,
+    },
+  };
+
+  return renderElement({
+    defaultTagName: 'div',
+    render,
+    enabled: mounted,
+    state,
+    stateAttributesMapping: {
+      open: (v: boolean): Record<string, string> | null => (v ? { 'data-cl-open': '' } : { 'data-cl-closed': '' }),
+    },
+    props: mergeProps<'div'>(defaultProps, otherProps),
+  });
+}