feat(headless): add Collapsible primitive

packages/headless/package.json

@@ -33,6 +33,10 @@
  "import": "./dist/primitives/autocomplete/index.js",
  "types": "./dist/primitives/autocomplete/index.d.ts"
  },
+ "./collapsible": {
+ "import": "./dist/primitives/collapsible/index.js",
+ "types": "./dist/primitives/collapsible/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

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

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+
+export interface CollapsibleContextValue {
+ open: boolean;
+ setOpen: (v: boolean) => void;
+ disabled: boolean;
+ triggerId: string;
+ panelId: string;
+}
+
+export const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
+
+export function useCollapsibleContext() {
+ const ctx = useContext(CollapsibleContext);
+ if (!ctx) {
+ throw new Error('Collapsible compound components must be used within <Collapsible.Root>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,79 @@
+'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 { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsiblePanelProps extends ComponentProps<'div'> {}
+
+export function CollapsiblePanel(props: CollapsiblePanelProps) {
+ const { render, ...otherProps } = props;
+ const { open, triggerId, panelId } = useCollapsibleContext();
+
+ const panelRef = useRef<HTMLElement | null>(null);
+ const [height, setHeight] = useState<number | undefined>(undefined);
+ const [width, setWidth] = useState<number | undefined>(undefined);
+
+ const hasBeenClosed = useRef(false);
+ if (!open) hasBeenClosed.current = true;
+
+ const { mounted, transitionProps } = useTransition({
+ open,
+ ref: panelRef as RefObject<HTMLElement>,
+ });
+
+ useLayoutEffect(() => {
+ if (!mounted) return;
+
+ const panel = panelRef.current;
+ if (!panel) return;
+
+ const measure = () => {
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ };
+
+ measure();
+
+ const ro = new ResizeObserver(measure);
+ ro.observe(panel, { box: 'border-box' });
+
+ return () => ro.disconnect();
+ }, [mounted]);
+
+ const state = { open };
+
+ const effectiveTransitionProps = !hasBeenClosed.current
+ ? {
+ ...transitionProps,
+ 'data-cl-starting-style': undefined,
+ style: undefined,
+ }
+ : transitionProps;
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-panel',
+ id: panelId,
+ role: 'region' as const,
+ 'aria-labelledby': triggerId,
+ ref: panelRef,
+ ...effectiveTransitionProps,
+ style: {
+ '--collapsible-panel-height': height != null ? `${height}px` : undefined,
+ '--collapsible-panel-width': width != null ? `${width}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),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible-root.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { type ReactNode, useId, useMemo } from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { CollapsibleContext, type CollapsibleContextValue } from './collapsible-context';
+
+export interface CollapsibleProps extends ComponentProps<'div'> {
+ /** Controlled open state. */
+ open?: boolean;
+ /** Initial open state (uncontrolled). */
+ defaultOpen?: boolean;
+ /** Called when open state changes. */
+ onOpenChange?: (open: boolean) => void;
+ /** Disable the collapsible. @default false */
+ disabled?: boolean;
+ children: ReactNode;
+}
+
+export function CollapsibleRoot(props: CollapsibleProps) {
+ const { render, open: openProp, defaultOpen, onOpenChange, disabled = false, children, ...otherProps } = props;
+
+ const [open, setOpen] = useControllableState(openProp, defaultOpen ?? false, onOpenChange);
+
+ const rootId = useId();
+ const triggerId = `${rootId}trigger`;
+ const panelId = `${rootId}panel`;
+
+ const contextValue = useMemo<CollapsibleContextValue>(
+ () => ({ open, setOpen, disabled, triggerId, panelId }),
+ [open, setOpen, disabled, triggerId, panelId],
+ );
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-root',
+ children,
+ };
+
+ return (
+ <CollapsibleContext.Provider value={contextValue}>
+ {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),
+ })}
+ </CollapsibleContext.Provider>
+ );
+}

packages/headless/src/primitives/collapsible/collapsible-trigger.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsibleTriggerProps extends ComponentProps<'button'> {}
+
+export function CollapsibleTrigger(props: CollapsibleTriggerProps) {
+ const { render, ...otherProps } = props;
+ const { open, setOpen, disabled, triggerId, panelId } = useCollapsibleContext();
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-trigger',
+ id: triggerId,
+ type: 'button' as const,
+ 'aria-expanded': open,
+ 'aria-controls': panelId,
+ 'aria-disabled': disabled || undefined,
+ onClick: () => {
+ if (!disabled) setOpen(!open);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ 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<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -0,0 +1,190 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Collapsible } from './index';
+
+afterEach(() => cleanup());
+
+function renderCollapsible(props: Partial<React.ComponentProps<typeof Collapsible.Root>> = {}) {
+ return render(
+ <Collapsible.Root {...props}>
+ <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ <Collapsible.Panel>Content</Collapsible.Panel>
+ </Collapsible.Root>,
+ );
+}
+
+describe('Collapsible', () => {
+ describe('slot attributes', () => {
+ it('renders root with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toBeInTheDocument();
+ });
+
+ it('renders trigger with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toBeInTheDocument();
+ });
+
+ it('renders panel with data-cl-slot when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).toBeInTheDocument();
+ });
+ });
+
+ describe('open/close', () => {
+ it('opens panel on trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible();
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('closes panel on second trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ defaultOpen: true });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('calls onOpenChange when toggled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+
+ it('starts closed by default', () => {
+ renderCollapsible();
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('starts open with defaultOpen=true', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+ });
+
+ describe('controlled value', () => {
+ it('respects controlled open prop', () => {
+ renderCollapsible({ open: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+
+ it('does not change when controlled', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ open: false });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ });
+ });
+
+ describe('ARIA attributes', () => {
+ it('trigger has aria-expanded=false when closed', () => {
+ renderCollapsible();
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('trigger has aria-expanded=true when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('trigger has aria-controls linked to panel id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(trigger).toHaveAttribute('aria-controls', panel?.getAttribute('id'));
+ });
+
+ it('panel has aria-labelledby linked to trigger id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('aria-labelledby', trigger.getAttribute('id'));
+ });
+
+ it('panel has role=region', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('region')).toBeInTheDocument();
+ });
+ });
+
+ describe('animation lifecycle', () => {
+ it('panel is not in DOM when closed', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).not.toBeInTheDocument();
+ });
+
+ it('applies data-cl-open on panel when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('does not apply starting-style on initially open panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).not.toHaveAttribute('data-cl-starting-style');
+ });
+
+ it('sets --collapsible-panel-height CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ });
+
+ it('sets --collapsible-panel-width CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ });
+ });
+
+ describe('disabled', () => {
+ it('prevents toggle when disabled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ disabled: true, onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).not.toHaveBeenCalled();
+ });
+
+ it('applies aria-disabled on trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('applies data-cl-disabled on root and trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-disabled', '');
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toHaveAttribute('data-cl-disabled', '');
+ });
+ });
+
+ describe('accessibility (axe)', () => {
+ it('has no violations when closed', async () => {
+ const { container } = renderCollapsible();
+ expect(await axe(container)).toHaveNoViolations();
+ });
+
+ it('has no violations when open', async () => {
+ const { container } = renderCollapsible({ defaultOpen: true });
+ expect(await axe(container)).toHaveNoViolations();
+ });
+ });
+});

packages/headless/src/primitives/collapsible/index.ts

@@ -0,0 +1,3 @@
+export * as Collapsible from './parts';
+
+export type { CollapsibleProps, CollapsibleTriggerProps, CollapsiblePanelProps } from './parts';

packages/headless/package.json

@@ -33,6 +33,10 @@
  "import": "./dist/primitives/autocomplete/index.js",
  "types": "./dist/primitives/autocomplete/index.d.ts"
  },
+ "./collapsible": {
+ "import": "./dist/primitives/collapsible/index.js",
+ "types": "./dist/primitives/collapsible/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

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

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+
+export interface CollapsibleContextValue {
+ open: boolean;
+ setOpen: (v: boolean) => void;
+ disabled: boolean;
+ triggerId: string;
+ panelId: string;
+}
+
+export const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
+
+export function useCollapsibleContext() {
+ const ctx = useContext(CollapsibleContext);
+ if (!ctx) {
+ throw new Error('Collapsible compound components must be used within <Collapsible.Root>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,79 @@
+'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 { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsiblePanelProps extends ComponentProps<'div'> {}
+
+export function CollapsiblePanel(props: CollapsiblePanelProps) {
+ const { render, ...otherProps } = props;
+ const { open, triggerId, panelId } = useCollapsibleContext();
+
+ const panelRef = useRef<HTMLElement | null>(null);
+ const [height, setHeight] = useState<number | undefined>(undefined);
+ const [width, setWidth] = useState<number | undefined>(undefined);
+
+ const hasBeenClosed = useRef(false);
+ if (!open) hasBeenClosed.current = true;
+
+ const { mounted, transitionProps } = useTransition({
+ open,
+ ref: panelRef as RefObject<HTMLElement>,
+ });
+
+ useLayoutEffect(() => {
+ if (!mounted) return;
+
+ const panel = panelRef.current;
+ if (!panel) return;
+
+ const measure = () => {
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ };
+
+ measure();
+
+ const ro = new ResizeObserver(measure);
+ ro.observe(panel, { box: 'border-box' });
+
+ return () => ro.disconnect();
+ }, [mounted]);
+
+ const state = { open };
+
+ const effectiveTransitionProps = !hasBeenClosed.current
+ ? {
+ ...transitionProps,
+ 'data-cl-starting-style': undefined,
+ style: undefined,
+ }
+ : transitionProps;
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-panel',
+ id: panelId,
+ role: 'region' as const,
+ 'aria-labelledby': triggerId,
+ ref: panelRef,
+ ...effectiveTransitionProps,
+ style: {
+ '--collapsible-panel-height': height != null ? `${height}px` : undefined,
+ '--collapsible-panel-width': width != null ? `${width}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),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible-root.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { type ReactNode, useId, useMemo } from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { CollapsibleContext, type CollapsibleContextValue } from './collapsible-context';
+
+export interface CollapsibleProps extends ComponentProps<'div'> {
+ /** Controlled open state. */
+ open?: boolean;
+ /** Initial open state (uncontrolled). */
+ defaultOpen?: boolean;
+ /** Called when open state changes. */
+ onOpenChange?: (open: boolean) => void;
+ /** Disable the collapsible. @default false */
+ disabled?: boolean;
+ children: ReactNode;
+}
+
+export function CollapsibleRoot(props: CollapsibleProps) {
+ const { render, open: openProp, defaultOpen, onOpenChange, disabled = false, children, ...otherProps } = props;
+
+ const [open, setOpen] = useControllableState(openProp, defaultOpen ?? false, onOpenChange);
+
+ const rootId = useId();
+ const triggerId = `${rootId}trigger`;
+ const panelId = `${rootId}panel`;
+
+ const contextValue = useMemo<CollapsibleContextValue>(
+ () => ({ open, setOpen, disabled, triggerId, panelId }),
+ [open, setOpen, disabled, triggerId, panelId],
+ );
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-root',
+ children,
+ };
+
+ return (
+ <CollapsibleContext.Provider value={contextValue}>
+ {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),
+ })}
+ </CollapsibleContext.Provider>
+ );
+}

packages/headless/src/primitives/collapsible/collapsible-trigger.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsibleTriggerProps extends ComponentProps<'button'> {}
+
+export function CollapsibleTrigger(props: CollapsibleTriggerProps) {
+ const { render, ...otherProps } = props;
+ const { open, setOpen, disabled, triggerId, panelId } = useCollapsibleContext();
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-trigger',
+ id: triggerId,
+ type: 'button' as const,
+ 'aria-expanded': open,
+ 'aria-controls': panelId,
+ 'aria-disabled': disabled || undefined,
+ onClick: () => {
+ if (!disabled) setOpen(!open);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ 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<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -0,0 +1,190 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Collapsible } from './index';
+
+afterEach(() => cleanup());
+
+function renderCollapsible(props: Partial<React.ComponentProps<typeof Collapsible.Root>> = {}) {
+ return render(
+ <Collapsible.Root {...props}>
+ <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ <Collapsible.Panel>Content</Collapsible.Panel>
+ </Collapsible.Root>,
+ );
+}
+
+describe('Collapsible', () => {
+ describe('slot attributes', () => {
+ it('renders root with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toBeInTheDocument();
+ });
+
+ it('renders trigger with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toBeInTheDocument();
+ });
+
+ it('renders panel with data-cl-slot when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).toBeInTheDocument();
+ });
+ });
+
+ describe('open/close', () => {
+ it('opens panel on trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible();
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('closes panel on second trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ defaultOpen: true });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('calls onOpenChange when toggled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+
+ it('starts closed by default', () => {
+ renderCollapsible();
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('starts open with defaultOpen=true', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+ });
+
+ describe('controlled value', () => {
+ it('respects controlled open prop', () => {
+ renderCollapsible({ open: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+
+ it('does not change when controlled', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ open: false });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ });
+ });
+
+ describe('ARIA attributes', () => {
+ it('trigger has aria-expanded=false when closed', () => {
+ renderCollapsible();
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('trigger has aria-expanded=true when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('trigger has aria-controls linked to panel id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(trigger).toHaveAttribute('aria-controls', panel?.getAttribute('id'));
+ });
+
+ it('panel has aria-labelledby linked to trigger id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('aria-labelledby', trigger.getAttribute('id'));
+ });
+
+ it('panel has role=region', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('region')).toBeInTheDocument();
+ });
+ });
+
+ describe('animation lifecycle', () => {
+ it('panel is not in DOM when closed', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).not.toBeInTheDocument();
+ });
+
+ it('applies data-cl-open on panel when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('does not apply starting-style on initially open panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).not.toHaveAttribute('data-cl-starting-style');
+ });
+
+ it('sets --collapsible-panel-height CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ });
+
+ it('sets --collapsible-panel-width CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ });
+ });
+
+ describe('disabled', () => {
+ it('prevents toggle when disabled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ disabled: true, onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).not.toHaveBeenCalled();
+ });
+
+ it('applies aria-disabled on trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('applies data-cl-disabled on root and trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-disabled', '');
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toHaveAttribute('data-cl-disabled', '');
+ });
+ });
+
+ describe('accessibility (axe)', () => {
+ it('has no violations when closed', async () => {
+ const { container } = renderCollapsible();
+ expect(await axe(container)).toHaveNoViolations();
+ });
+
+ it('has no violations when open', async () => {
+ const { container } = renderCollapsible({ defaultOpen: true });
+ expect(await axe(container)).toHaveNoViolations();
+ });
+ });
+});

packages/headless/src/primitives/collapsible/index.ts

@@ -0,0 +1,3 @@
+export * as Collapsible from './parts';
+
+export type { CollapsibleProps, CollapsibleTriggerProps, CollapsiblePanelProps } from './parts';

packages/headless/package.json

@@ -33,6 +33,10 @@
  "import": "./dist/primitives/autocomplete/index.js",
  "types": "./dist/primitives/autocomplete/index.d.ts"
  },
+ "./collapsible": {
+ "import": "./dist/primitives/collapsible/index.js",
+ "types": "./dist/primitives/collapsible/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

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

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+
+export interface CollapsibleContextValue {
+ open: boolean;
+ setOpen: (v: boolean) => void;
+ disabled: boolean;
+ triggerId: string;
+ panelId: string;
+}
+
+export const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
+
+export function useCollapsibleContext() {
+ const ctx = useContext(CollapsibleContext);
+ if (!ctx) {
+ throw new Error('Collapsible compound components must be used within <Collapsible.Root>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,79 @@
+'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 { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsiblePanelProps extends ComponentProps<'div'> {}
+
+export function CollapsiblePanel(props: CollapsiblePanelProps) {
+ const { render, ...otherProps } = props;
+ const { open, triggerId, panelId } = useCollapsibleContext();
+
+ const panelRef = useRef<HTMLElement | null>(null);
+ const [height, setHeight] = useState<number | undefined>(undefined);
+ const [width, setWidth] = useState<number | undefined>(undefined);
+
+ const hasBeenClosed = useRef(false);
+ if (!open) hasBeenClosed.current = true;
+
+ const { mounted, transitionProps } = useTransition({
+ open,
+ ref: panelRef as RefObject<HTMLElement>,
+ });
+
+ useLayoutEffect(() => {
+ if (!mounted) return;
+
+ const panel = panelRef.current;
+ if (!panel) return;
+
+ const measure = () => {
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ };
+
+ measure();
+
+ const ro = new ResizeObserver(measure);
+ ro.observe(panel, { box: 'border-box' });
+
+ return () => ro.disconnect();
+ }, [mounted]);
+
+ const state = { open };
+
+ const effectiveTransitionProps = !hasBeenClosed.current
+ ? {
+ ...transitionProps,
+ 'data-cl-starting-style': undefined,
+ style: undefined,
+ }
+ : transitionProps;
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-panel',
+ id: panelId,
+ role: 'region' as const,
+ 'aria-labelledby': triggerId,
+ ref: panelRef,
+ ...effectiveTransitionProps,
+ style: {
+ '--collapsible-panel-height': height != null ? `${height}px` : undefined,
+ '--collapsible-panel-width': width != null ? `${width}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),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible-root.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { type ReactNode, useId, useMemo } from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { CollapsibleContext, type CollapsibleContextValue } from './collapsible-context';
+
+export interface CollapsibleProps extends ComponentProps<'div'> {
+ /** Controlled open state. */
+ open?: boolean;
+ /** Initial open state (uncontrolled). */
+ defaultOpen?: boolean;
+ /** Called when open state changes. */
+ onOpenChange?: (open: boolean) => void;
+ /** Disable the collapsible. @default false */
+ disabled?: boolean;
+ children: ReactNode;
+}
+
+export function CollapsibleRoot(props: CollapsibleProps) {
+ const { render, open: openProp, defaultOpen, onOpenChange, disabled = false, children, ...otherProps } = props;
+
+ const [open, setOpen] = useControllableState(openProp, defaultOpen ?? false, onOpenChange);
+
+ const rootId = useId();
+ const triggerId = `${rootId}trigger`;
+ const panelId = `${rootId}panel`;
+
+ const contextValue = useMemo<CollapsibleContextValue>(
+ () => ({ open, setOpen, disabled, triggerId, panelId }),
+ [open, setOpen, disabled, triggerId, panelId],
+ );
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-root',
+ children,
+ };
+
+ return (
+ <CollapsibleContext.Provider value={contextValue}>
+ {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),
+ })}
+ </CollapsibleContext.Provider>
+ );
+}

packages/headless/src/primitives/collapsible/collapsible-trigger.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsibleTriggerProps extends ComponentProps<'button'> {}
+
+export function CollapsibleTrigger(props: CollapsibleTriggerProps) {
+ const { render, ...otherProps } = props;
+ const { open, setOpen, disabled, triggerId, panelId } = useCollapsibleContext();
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-trigger',
+ id: triggerId,
+ type: 'button' as const,
+ 'aria-expanded': open,
+ 'aria-controls': panelId,
+ 'aria-disabled': disabled || undefined,
+ onClick: () => {
+ if (!disabled) setOpen(!open);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ 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<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -0,0 +1,190 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Collapsible } from './index';
+
+afterEach(() => cleanup());
+
+function renderCollapsible(props: Partial<React.ComponentProps<typeof Collapsible.Root>> = {}) {
+ return render(
+ <Collapsible.Root {...props}>
+ <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ <Collapsible.Panel>Content</Collapsible.Panel>
+ </Collapsible.Root>,
+ );
+}
+
+describe('Collapsible', () => {
+ describe('slot attributes', () => {
+ it('renders root with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toBeInTheDocument();
+ });
+
+ it('renders trigger with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toBeInTheDocument();
+ });
+
+ it('renders panel with data-cl-slot when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).toBeInTheDocument();
+ });
+ });
+
+ describe('open/close', () => {
+ it('opens panel on trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible();
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('closes panel on second trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ defaultOpen: true });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('calls onOpenChange when toggled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+
+ it('starts closed by default', () => {
+ renderCollapsible();
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('starts open with defaultOpen=true', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+ });
+
+ describe('controlled value', () => {
+ it('respects controlled open prop', () => {
+ renderCollapsible({ open: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+
+ it('does not change when controlled', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ open: false });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ });
+ });
+
+ describe('ARIA attributes', () => {
+ it('trigger has aria-expanded=false when closed', () => {
+ renderCollapsible();
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('trigger has aria-expanded=true when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('trigger has aria-controls linked to panel id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(trigger).toHaveAttribute('aria-controls', panel?.getAttribute('id'));
+ });
+
+ it('panel has aria-labelledby linked to trigger id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('aria-labelledby', trigger.getAttribute('id'));
+ });
+
+ it('panel has role=region', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('region')).toBeInTheDocument();
+ });
+ });
+
+ describe('animation lifecycle', () => {
+ it('panel is not in DOM when closed', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).not.toBeInTheDocument();
+ });
+
+ it('applies data-cl-open on panel when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('does not apply starting-style on initially open panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).not.toHaveAttribute('data-cl-starting-style');
+ });
+
+ it('sets --collapsible-panel-height CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ });
+
+ it('sets --collapsible-panel-width CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ });
+ });
+
+ describe('disabled', () => {
+ it('prevents toggle when disabled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ disabled: true, onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).not.toHaveBeenCalled();
+ });
+
+ it('applies aria-disabled on trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('applies data-cl-disabled on root and trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-disabled', '');
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toHaveAttribute('data-cl-disabled', '');
+ });
+ });
+
+ describe('accessibility (axe)', () => {
+ it('has no violations when closed', async () => {
+ const { container } = renderCollapsible();
+ expect(await axe(container)).toHaveNoViolations();
+ });
+
+ it('has no violations when open', async () => {
+ const { container } = renderCollapsible({ defaultOpen: true });
+ expect(await axe(container)).toHaveNoViolations();
+ });
+ });
+});

packages/headless/src/primitives/collapsible/index.ts

@@ -0,0 +1,3 @@
+export * as Collapsible from './parts';
+
+export type { CollapsibleProps, CollapsibleTriggerProps, CollapsiblePanelProps } from './parts';

packages/headless/package.json

@@ -33,6 +33,10 @@
  "import": "./dist/primitives/autocomplete/index.js",
  "types": "./dist/primitives/autocomplete/index.d.ts"
  },
+ "./collapsible": {
+ "import": "./dist/primitives/collapsible/index.js",
+ "types": "./dist/primitives/collapsible/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

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

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+
+export interface CollapsibleContextValue {
+ open: boolean;
+ setOpen: (v: boolean) => void;
+ disabled: boolean;
+ triggerId: string;
+ panelId: string;
+}
+
+export const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
+
+export function useCollapsibleContext() {
+ const ctx = useContext(CollapsibleContext);
+ if (!ctx) {
+ throw new Error('Collapsible compound components must be used within <Collapsible.Root>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,79 @@
+'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 { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsiblePanelProps extends ComponentProps<'div'> {}
+
+export function CollapsiblePanel(props: CollapsiblePanelProps) {
+ const { render, ...otherProps } = props;
+ const { open, triggerId, panelId } = useCollapsibleContext();
+
+ const panelRef = useRef<HTMLElement | null>(null);
+ const [height, setHeight] = useState<number | undefined>(undefined);
+ const [width, setWidth] = useState<number | undefined>(undefined);
+
+ const hasBeenClosed = useRef(false);
+ if (!open) hasBeenClosed.current = true;
+
+ const { mounted, transitionProps } = useTransition({
+ open,
+ ref: panelRef as RefObject<HTMLElement>,
+ });
+
+ useLayoutEffect(() => {
+ if (!mounted) return;
+
+ const panel = panelRef.current;
+ if (!panel) return;
+
+ const measure = () => {
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ };
+
+ measure();
+
+ const ro = new ResizeObserver(measure);
+ ro.observe(panel, { box: 'border-box' });
+
+ return () => ro.disconnect();
+ }, [mounted]);
+
+ const state = { open };
+
+ const effectiveTransitionProps = !hasBeenClosed.current
+ ? {
+ ...transitionProps,
+ 'data-cl-starting-style': undefined,
+ style: undefined,
+ }
+ : transitionProps;
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-panel',
+ id: panelId,
+ role: 'region' as const,
+ 'aria-labelledby': triggerId,
+ ref: panelRef,
+ ...effectiveTransitionProps,
+ style: {
+ '--collapsible-panel-height': height != null ? `${height}px` : undefined,
+ '--collapsible-panel-width': width != null ? `${width}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),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible-root.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { type ReactNode, useId, useMemo } from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { CollapsibleContext, type CollapsibleContextValue } from './collapsible-context';
+
+export interface CollapsibleProps extends ComponentProps<'div'> {
+ /** Controlled open state. */
+ open?: boolean;
+ /** Initial open state (uncontrolled). */
+ defaultOpen?: boolean;
+ /** Called when open state changes. */
+ onOpenChange?: (open: boolean) => void;
+ /** Disable the collapsible. @default false */
+ disabled?: boolean;
+ children: ReactNode;
+}
+
+export function CollapsibleRoot(props: CollapsibleProps) {
+ const { render, open: openProp, defaultOpen, onOpenChange, disabled = false, children, ...otherProps } = props;
+
+ const [open, setOpen] = useControllableState(openProp, defaultOpen ?? false, onOpenChange);
+
+ const rootId = useId();
+ const triggerId = `${rootId}trigger`;
+ const panelId = `${rootId}panel`;
+
+ const contextValue = useMemo<CollapsibleContextValue>(
+ () => ({ open, setOpen, disabled, triggerId, panelId }),
+ [open, setOpen, disabled, triggerId, panelId],
+ );
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-root',
+ children,
+ };
+
+ return (
+ <CollapsibleContext.Provider value={contextValue}>
+ {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),
+ })}
+ </CollapsibleContext.Provider>
+ );
+}

packages/headless/src/primitives/collapsible/collapsible-trigger.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsibleTriggerProps extends ComponentProps<'button'> {}
+
+export function CollapsibleTrigger(props: CollapsibleTriggerProps) {
+ const { render, ...otherProps } = props;
+ const { open, setOpen, disabled, triggerId, panelId } = useCollapsibleContext();
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-trigger',
+ id: triggerId,
+ type: 'button' as const,
+ 'aria-expanded': open,
+ 'aria-controls': panelId,
+ 'aria-disabled': disabled || undefined,
+ onClick: () => {
+ if (!disabled) setOpen(!open);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ 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<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -0,0 +1,190 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Collapsible } from './index';
+
+afterEach(() => cleanup());
+
+function renderCollapsible(props: Partial<React.ComponentProps<typeof Collapsible.Root>> = {}) {
+ return render(
+ <Collapsible.Root {...props}>
+ <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ <Collapsible.Panel>Content</Collapsible.Panel>
+ </Collapsible.Root>,
+ );
+}
+
+describe('Collapsible', () => {
+ describe('slot attributes', () => {
+ it('renders root with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toBeInTheDocument();
+ });
+
+ it('renders trigger with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toBeInTheDocument();
+ });
+
+ it('renders panel with data-cl-slot when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).toBeInTheDocument();
+ });
+ });
+
+ describe('open/close', () => {
+ it('opens panel on trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible();
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('closes panel on second trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ defaultOpen: true });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('calls onOpenChange when toggled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+
+ it('starts closed by default', () => {
+ renderCollapsible();
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('starts open with defaultOpen=true', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+ });
+
+ describe('controlled value', () => {
+ it('respects controlled open prop', () => {
+ renderCollapsible({ open: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+
+ it('does not change when controlled', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ open: false });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ });
+ });
+
+ describe('ARIA attributes', () => {
+ it('trigger has aria-expanded=false when closed', () => {
+ renderCollapsible();
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('trigger has aria-expanded=true when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('trigger has aria-controls linked to panel id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(trigger).toHaveAttribute('aria-controls', panel?.getAttribute('id'));
+ });
+
+ it('panel has aria-labelledby linked to trigger id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('aria-labelledby', trigger.getAttribute('id'));
+ });
+
+ it('panel has role=region', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('region')).toBeInTheDocument();
+ });
+ });
+
+ describe('animation lifecycle', () => {
+ it('panel is not in DOM when closed', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).not.toBeInTheDocument();
+ });
+
+ it('applies data-cl-open on panel when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('does not apply starting-style on initially open panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).not.toHaveAttribute('data-cl-starting-style');
+ });
+
+ it('sets --collapsible-panel-height CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ });
+
+ it('sets --collapsible-panel-width CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ });
+ });
+
+ describe('disabled', () => {
+ it('prevents toggle when disabled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ disabled: true, onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).not.toHaveBeenCalled();
+ });
+
+ it('applies aria-disabled on trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('applies data-cl-disabled on root and trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-disabled', '');
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toHaveAttribute('data-cl-disabled', '');
+ });
+ });
+
+ describe('accessibility (axe)', () => {
+ it('has no violations when closed', async () => {
+ const { container } = renderCollapsible();
+ expect(await axe(container)).toHaveNoViolations();
+ });
+
+ it('has no violations when open', async () => {
+ const { container } = renderCollapsible({ defaultOpen: true });
+ expect(await axe(container)).toHaveNoViolations();
+ });
+ });
+});

packages/headless/src/primitives/collapsible/index.ts

@@ -0,0 +1,3 @@
+export * as Collapsible from './parts';
+
+export type { CollapsibleProps, CollapsibleTriggerProps, CollapsiblePanelProps } from './parts';

packages/headless/package.json

@@ -33,6 +33,10 @@
  "import": "./dist/primitives/autocomplete/index.js",
  "types": "./dist/primitives/autocomplete/index.d.ts"
  },
+ "./collapsible": {
+ "import": "./dist/primitives/collapsible/index.js",
+ "types": "./dist/primitives/collapsible/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

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

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+
+export interface CollapsibleContextValue {
+ open: boolean;
+ setOpen: (v: boolean) => void;
+ disabled: boolean;
+ triggerId: string;
+ panelId: string;
+}
+
+export const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
+
+export function useCollapsibleContext() {
+ const ctx = useContext(CollapsibleContext);
+ if (!ctx) {
+ throw new Error('Collapsible compound components must be used within <Collapsible.Root>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,79 @@
+'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 { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsiblePanelProps extends ComponentProps<'div'> {}
+
+export function CollapsiblePanel(props: CollapsiblePanelProps) {
+ const { render, ...otherProps } = props;
+ const { open, triggerId, panelId } = useCollapsibleContext();
+
+ const panelRef = useRef<HTMLElement | null>(null);
+ const [height, setHeight] = useState<number | undefined>(undefined);
+ const [width, setWidth] = useState<number | undefined>(undefined);
+
+ const hasBeenClosed = useRef(false);
+ if (!open) hasBeenClosed.current = true;
+
+ const { mounted, transitionProps } = useTransition({
+ open,
+ ref: panelRef as RefObject<HTMLElement>,
+ });
+
+ useLayoutEffect(() => {
+ if (!mounted) return;
+
+ const panel = panelRef.current;
+ if (!panel) return;
+
+ const measure = () => {
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ };
+
+ measure();
+
+ const ro = new ResizeObserver(measure);
+ ro.observe(panel, { box: 'border-box' });
+
+ return () => ro.disconnect();
+ }, [mounted]);
+
+ const state = { open };
+
+ const effectiveTransitionProps = !hasBeenClosed.current
+ ? {
+ ...transitionProps,
+ 'data-cl-starting-style': undefined,
+ style: undefined,
+ }
+ : transitionProps;
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-panel',
+ id: panelId,
+ role: 'region' as const,
+ 'aria-labelledby': triggerId,
+ ref: panelRef,
+ ...effectiveTransitionProps,
+ style: {
+ '--collapsible-panel-height': height != null ? `${height}px` : undefined,
+ '--collapsible-panel-width': width != null ? `${width}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),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible-root.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { type ReactNode, useId, useMemo } from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { CollapsibleContext, type CollapsibleContextValue } from './collapsible-context';
+
+export interface CollapsibleProps extends ComponentProps<'div'> {
+ /** Controlled open state. */
+ open?: boolean;
+ /** Initial open state (uncontrolled). */
+ defaultOpen?: boolean;
+ /** Called when open state changes. */
+ onOpenChange?: (open: boolean) => void;
+ /** Disable the collapsible. @default false */
+ disabled?: boolean;
+ children: ReactNode;
+}
+
+export function CollapsibleRoot(props: CollapsibleProps) {
+ const { render, open: openProp, defaultOpen, onOpenChange, disabled = false, children, ...otherProps } = props;
+
+ const [open, setOpen] = useControllableState(openProp, defaultOpen ?? false, onOpenChange);
+
+ const rootId = useId();
+ const triggerId = `${rootId}trigger`;
+ const panelId = `${rootId}panel`;
+
+ const contextValue = useMemo<CollapsibleContextValue>(
+ () => ({ open, setOpen, disabled, triggerId, panelId }),
+ [open, setOpen, disabled, triggerId, panelId],
+ );
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-root',
+ children,
+ };
+
+ return (
+ <CollapsibleContext.Provider value={contextValue}>
+ {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),
+ })}
+ </CollapsibleContext.Provider>
+ );
+}

packages/headless/src/primitives/collapsible/collapsible-trigger.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsibleTriggerProps extends ComponentProps<'button'> {}
+
+export function CollapsibleTrigger(props: CollapsibleTriggerProps) {
+ const { render, ...otherProps } = props;
+ const { open, setOpen, disabled, triggerId, panelId } = useCollapsibleContext();
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-trigger',
+ id: triggerId,
+ type: 'button' as const,
+ 'aria-expanded': open,
+ 'aria-controls': panelId,
+ 'aria-disabled': disabled || undefined,
+ onClick: () => {
+ if (!disabled) setOpen(!open);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ 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<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -0,0 +1,190 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Collapsible } from './index';
+
+afterEach(() => cleanup());
+
+function renderCollapsible(props: Partial<React.ComponentProps<typeof Collapsible.Root>> = {}) {
+ return render(
+ <Collapsible.Root {...props}>
+ <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ <Collapsible.Panel>Content</Collapsible.Panel>
+ </Collapsible.Root>,
+ );
+}
+
+describe('Collapsible', () => {
+ describe('slot attributes', () => {
+ it('renders root with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toBeInTheDocument();
+ });
+
+ it('renders trigger with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toBeInTheDocument();
+ });
+
+ it('renders panel with data-cl-slot when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).toBeInTheDocument();
+ });
+ });
+
+ describe('open/close', () => {
+ it('opens panel on trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible();
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('closes panel on second trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ defaultOpen: true });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('calls onOpenChange when toggled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+
+ it('starts closed by default', () => {
+ renderCollapsible();
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('starts open with defaultOpen=true', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+ });
+
+ describe('controlled value', () => {
+ it('respects controlled open prop', () => {
+ renderCollapsible({ open: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+
+ it('does not change when controlled', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ open: false });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ });
+ });
+
+ describe('ARIA attributes', () => {
+ it('trigger has aria-expanded=false when closed', () => {
+ renderCollapsible();
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('trigger has aria-expanded=true when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('trigger has aria-controls linked to panel id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(trigger).toHaveAttribute('aria-controls', panel?.getAttribute('id'));
+ });
+
+ it('panel has aria-labelledby linked to trigger id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('aria-labelledby', trigger.getAttribute('id'));
+ });
+
+ it('panel has role=region', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('region')).toBeInTheDocument();
+ });
+ });
+
+ describe('animation lifecycle', () => {
+ it('panel is not in DOM when closed', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).not.toBeInTheDocument();
+ });
+
+ it('applies data-cl-open on panel when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('does not apply starting-style on initially open panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).not.toHaveAttribute('data-cl-starting-style');
+ });
+
+ it('sets --collapsible-panel-height CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ });
+
+ it('sets --collapsible-panel-width CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ });
+ });
+
+ describe('disabled', () => {
+ it('prevents toggle when disabled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ disabled: true, onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).not.toHaveBeenCalled();
+ });
+
+ it('applies aria-disabled on trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('applies data-cl-disabled on root and trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-disabled', '');
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toHaveAttribute('data-cl-disabled', '');
+ });
+ });
+
+ describe('accessibility (axe)', () => {
+ it('has no violations when closed', async () => {
+ const { container } = renderCollapsible();
+ expect(await axe(container)).toHaveNoViolations();
+ });
+
+ it('has no violations when open', async () => {
+ const { container } = renderCollapsible({ defaultOpen: true });
+ expect(await axe(container)).toHaveNoViolations();
+ });
+ });
+});

packages/headless/src/primitives/collapsible/index.ts

@@ -0,0 +1,3 @@
+export * as Collapsible from './parts';
+
+export type { CollapsibleProps, CollapsibleTriggerProps, CollapsiblePanelProps } from './parts';

packages/headless/package.json

@@ -33,6 +33,10 @@
  "import": "./dist/primitives/autocomplete/index.js",
  "types": "./dist/primitives/autocomplete/index.d.ts"
  },
+ "./collapsible": {
+ "import": "./dist/primitives/collapsible/index.js",
+ "types": "./dist/primitives/collapsible/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

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

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+
+export interface CollapsibleContextValue {
+ open: boolean;
+ setOpen: (v: boolean) => void;
+ disabled: boolean;
+ triggerId: string;
+ panelId: string;
+}
+
+export const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
+
+export function useCollapsibleContext() {
+ const ctx = useContext(CollapsibleContext);
+ if (!ctx) {
+ throw new Error('Collapsible compound components must be used within <Collapsible.Root>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,79 @@
+'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 { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsiblePanelProps extends ComponentProps<'div'> {}
+
+export function CollapsiblePanel(props: CollapsiblePanelProps) {
+ const { render, ...otherProps } = props;
+ const { open, triggerId, panelId } = useCollapsibleContext();
+
+ const panelRef = useRef<HTMLElement | null>(null);
+ const [height, setHeight] = useState<number | undefined>(undefined);
+ const [width, setWidth] = useState<number | undefined>(undefined);
+
+ const hasBeenClosed = useRef(false);
+ if (!open) hasBeenClosed.current = true;
+
+ const { mounted, transitionProps } = useTransition({
+ open,
+ ref: panelRef as RefObject<HTMLElement>,
+ });
+
+ useLayoutEffect(() => {
+ if (!mounted) return;
+
+ const panel = panelRef.current;
+ if (!panel) return;
+
+ const measure = () => {
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ };
+
+ measure();
+
+ const ro = new ResizeObserver(measure);
+ ro.observe(panel, { box: 'border-box' });
+
+ return () => ro.disconnect();
+ }, [mounted]);
+
+ const state = { open };
+
+ const effectiveTransitionProps = !hasBeenClosed.current
+ ? {
+ ...transitionProps,
+ 'data-cl-starting-style': undefined,
+ style: undefined,
+ }
+ : transitionProps;
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-panel',
+ id: panelId,
+ role: 'region' as const,
+ 'aria-labelledby': triggerId,
+ ref: panelRef,
+ ...effectiveTransitionProps,
+ style: {
+ '--collapsible-panel-height': height != null ? `${height}px` : undefined,
+ '--collapsible-panel-width': width != null ? `${width}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),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible-root.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { type ReactNode, useId, useMemo } from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { CollapsibleContext, type CollapsibleContextValue } from './collapsible-context';
+
+export interface CollapsibleProps extends ComponentProps<'div'> {
+ /** Controlled open state. */
+ open?: boolean;
+ /** Initial open state (uncontrolled). */
+ defaultOpen?: boolean;
+ /** Called when open state changes. */
+ onOpenChange?: (open: boolean) => void;
+ /** Disable the collapsible. @default false */
+ disabled?: boolean;
+ children: ReactNode;
+}
+
+export function CollapsibleRoot(props: CollapsibleProps) {
+ const { render, open: openProp, defaultOpen, onOpenChange, disabled = false, children, ...otherProps } = props;
+
+ const [open, setOpen] = useControllableState(openProp, defaultOpen ?? false, onOpenChange);
+
+ const rootId = useId();
+ const triggerId = `${rootId}trigger`;
+ const panelId = `${rootId}panel`;
+
+ const contextValue = useMemo<CollapsibleContextValue>(
+ () => ({ open, setOpen, disabled, triggerId, panelId }),
+ [open, setOpen, disabled, triggerId, panelId],
+ );
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-root',
+ children,
+ };
+
+ return (
+ <CollapsibleContext.Provider value={contextValue}>
+ {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),
+ })}
+ </CollapsibleContext.Provider>
+ );
+}

packages/headless/src/primitives/collapsible/collapsible-trigger.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsibleTriggerProps extends ComponentProps<'button'> {}
+
+export function CollapsibleTrigger(props: CollapsibleTriggerProps) {
+ const { render, ...otherProps } = props;
+ const { open, setOpen, disabled, triggerId, panelId } = useCollapsibleContext();
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-trigger',
+ id: triggerId,
+ type: 'button' as const,
+ 'aria-expanded': open,
+ 'aria-controls': panelId,
+ 'aria-disabled': disabled || undefined,
+ onClick: () => {
+ if (!disabled) setOpen(!open);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ 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<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -0,0 +1,190 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Collapsible } from './index';
+
+afterEach(() => cleanup());
+
+function renderCollapsible(props: Partial<React.ComponentProps<typeof Collapsible.Root>> = {}) {
+ return render(
+ <Collapsible.Root {...props}>
+ <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ <Collapsible.Panel>Content</Collapsible.Panel>
+ </Collapsible.Root>,
+ );
+}
+
+describe('Collapsible', () => {
+ describe('slot attributes', () => {
+ it('renders root with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toBeInTheDocument();
+ });
+
+ it('renders trigger with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toBeInTheDocument();
+ });
+
+ it('renders panel with data-cl-slot when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).toBeInTheDocument();
+ });
+ });
+
+ describe('open/close', () => {
+ it('opens panel on trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible();
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('closes panel on second trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ defaultOpen: true });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('calls onOpenChange when toggled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+
+ it('starts closed by default', () => {
+ renderCollapsible();
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('starts open with defaultOpen=true', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+ });
+
+ describe('controlled value', () => {
+ it('respects controlled open prop', () => {
+ renderCollapsible({ open: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+
+ it('does not change when controlled', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ open: false });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ });
+ });
+
+ describe('ARIA attributes', () => {
+ it('trigger has aria-expanded=false when closed', () => {
+ renderCollapsible();
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('trigger has aria-expanded=true when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('trigger has aria-controls linked to panel id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(trigger).toHaveAttribute('aria-controls', panel?.getAttribute('id'));
+ });
+
+ it('panel has aria-labelledby linked to trigger id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('aria-labelledby', trigger.getAttribute('id'));
+ });
+
+ it('panel has role=region', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('region')).toBeInTheDocument();
+ });
+ });
+
+ describe('animation lifecycle', () => {
+ it('panel is not in DOM when closed', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).not.toBeInTheDocument();
+ });
+
+ it('applies data-cl-open on panel when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('does not apply starting-style on initially open panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).not.toHaveAttribute('data-cl-starting-style');
+ });
+
+ it('sets --collapsible-panel-height CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ });
+
+ it('sets --collapsible-panel-width CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ });
+ });
+
+ describe('disabled', () => {
+ it('prevents toggle when disabled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ disabled: true, onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).not.toHaveBeenCalled();
+ });
+
+ it('applies aria-disabled on trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('applies data-cl-disabled on root and trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-disabled', '');
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toHaveAttribute('data-cl-disabled', '');
+ });
+ });
+
+ describe('accessibility (axe)', () => {
+ it('has no violations when closed', async () => {
+ const { container } = renderCollapsible();
+ expect(await axe(container)).toHaveNoViolations();
+ });
+
+ it('has no violations when open', async () => {
+ const { container } = renderCollapsible({ defaultOpen: true });
+ expect(await axe(container)).toHaveNoViolations();
+ });
+ });
+});

packages/headless/src/primitives/collapsible/index.ts

@@ -0,0 +1,3 @@
+export * as Collapsible from './parts';
+
+export type { CollapsibleProps, CollapsibleTriggerProps, CollapsiblePanelProps } from './parts';

packages/headless/package.json

@@ -33,6 +33,10 @@
  "import": "./dist/primitives/autocomplete/index.js",
  "types": "./dist/primitives/autocomplete/index.d.ts"
  },
+ "./collapsible": {
+ "import": "./dist/primitives/collapsible/index.js",
+ "types": "./dist/primitives/collapsible/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

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

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+
+export interface CollapsibleContextValue {
+ open: boolean;
+ setOpen: (v: boolean) => void;
+ disabled: boolean;
+ triggerId: string;
+ panelId: string;
+}
+
+export const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
+
+export function useCollapsibleContext() {
+ const ctx = useContext(CollapsibleContext);
+ if (!ctx) {
+ throw new Error('Collapsible compound components must be used within <Collapsible.Root>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,79 @@
+'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 { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsiblePanelProps extends ComponentProps<'div'> {}
+
+export function CollapsiblePanel(props: CollapsiblePanelProps) {
+ const { render, ...otherProps } = props;
+ const { open, triggerId, panelId } = useCollapsibleContext();
+
+ const panelRef = useRef<HTMLElement | null>(null);
+ const [height, setHeight] = useState<number | undefined>(undefined);
+ const [width, setWidth] = useState<number | undefined>(undefined);
+
+ const hasBeenClosed = useRef(false);
+ if (!open) hasBeenClosed.current = true;
+
+ const { mounted, transitionProps } = useTransition({
+ open,
+ ref: panelRef as RefObject<HTMLElement>,
+ });
+
+ useLayoutEffect(() => {
+ if (!mounted) return;
+
+ const panel = panelRef.current;
+ if (!panel) return;
+
+ const measure = () => {
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ };
+
+ measure();
+
+ const ro = new ResizeObserver(measure);
+ ro.observe(panel, { box: 'border-box' });
+
+ return () => ro.disconnect();
+ }, [mounted]);
+
+ const state = { open };
+
+ const effectiveTransitionProps = !hasBeenClosed.current
+ ? {
+ ...transitionProps,
+ 'data-cl-starting-style': undefined,
+ style: undefined,
+ }
+ : transitionProps;
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-panel',
+ id: panelId,
+ role: 'region' as const,
+ 'aria-labelledby': triggerId,
+ ref: panelRef,
+ ...effectiveTransitionProps,
+ style: {
+ '--collapsible-panel-height': height != null ? `${height}px` : undefined,
+ '--collapsible-panel-width': width != null ? `${width}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),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible-root.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { type ReactNode, useId, useMemo } from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { CollapsibleContext, type CollapsibleContextValue } from './collapsible-context';
+
+export interface CollapsibleProps extends ComponentProps<'div'> {
+ /** Controlled open state. */
+ open?: boolean;
+ /** Initial open state (uncontrolled). */
+ defaultOpen?: boolean;
+ /** Called when open state changes. */
+ onOpenChange?: (open: boolean) => void;
+ /** Disable the collapsible. @default false */
+ disabled?: boolean;
+ children: ReactNode;
+}
+
+export function CollapsibleRoot(props: CollapsibleProps) {
+ const { render, open: openProp, defaultOpen, onOpenChange, disabled = false, children, ...otherProps } = props;
+
+ const [open, setOpen] = useControllableState(openProp, defaultOpen ?? false, onOpenChange);
+
+ const rootId = useId();
+ const triggerId = `${rootId}trigger`;
+ const panelId = `${rootId}panel`;
+
+ const contextValue = useMemo<CollapsibleContextValue>(
+ () => ({ open, setOpen, disabled, triggerId, panelId }),
+ [open, setOpen, disabled, triggerId, panelId],
+ );
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-root',
+ children,
+ };
+
+ return (
+ <CollapsibleContext.Provider value={contextValue}>
+ {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),
+ })}
+ </CollapsibleContext.Provider>
+ );
+}

packages/headless/src/primitives/collapsible/collapsible-trigger.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsibleTriggerProps extends ComponentProps<'button'> {}
+
+export function CollapsibleTrigger(props: CollapsibleTriggerProps) {
+ const { render, ...otherProps } = props;
+ const { open, setOpen, disabled, triggerId, panelId } = useCollapsibleContext();
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-trigger',
+ id: triggerId,
+ type: 'button' as const,
+ 'aria-expanded': open,
+ 'aria-controls': panelId,
+ 'aria-disabled': disabled || undefined,
+ onClick: () => {
+ if (!disabled) setOpen(!open);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ 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<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -0,0 +1,190 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Collapsible } from './index';
+
+afterEach(() => cleanup());
+
+function renderCollapsible(props: Partial<React.ComponentProps<typeof Collapsible.Root>> = {}) {
+ return render(
+ <Collapsible.Root {...props}>
+ <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ <Collapsible.Panel>Content</Collapsible.Panel>
+ </Collapsible.Root>,
+ );
+}
+
+describe('Collapsible', () => {
+ describe('slot attributes', () => {
+ it('renders root with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toBeInTheDocument();
+ });
+
+ it('renders trigger with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toBeInTheDocument();
+ });
+
+ it('renders panel with data-cl-slot when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).toBeInTheDocument();
+ });
+ });
+
+ describe('open/close', () => {
+ it('opens panel on trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible();
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('closes panel on second trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ defaultOpen: true });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('calls onOpenChange when toggled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+
+ it('starts closed by default', () => {
+ renderCollapsible();
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('starts open with defaultOpen=true', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+ });
+
+ describe('controlled value', () => {
+ it('respects controlled open prop', () => {
+ renderCollapsible({ open: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+
+ it('does not change when controlled', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ open: false });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ });
+ });
+
+ describe('ARIA attributes', () => {
+ it('trigger has aria-expanded=false when closed', () => {
+ renderCollapsible();
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('trigger has aria-expanded=true when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('trigger has aria-controls linked to panel id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(trigger).toHaveAttribute('aria-controls', panel?.getAttribute('id'));
+ });
+
+ it('panel has aria-labelledby linked to trigger id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('aria-labelledby', trigger.getAttribute('id'));
+ });
+
+ it('panel has role=region', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('region')).toBeInTheDocument();
+ });
+ });
+
+ describe('animation lifecycle', () => {
+ it('panel is not in DOM when closed', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).not.toBeInTheDocument();
+ });
+
+ it('applies data-cl-open on panel when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('does not apply starting-style on initially open panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).not.toHaveAttribute('data-cl-starting-style');
+ });
+
+ it('sets --collapsible-panel-height CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ });
+
+ it('sets --collapsible-panel-width CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ });
+ });
+
+ describe('disabled', () => {
+ it('prevents toggle when disabled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ disabled: true, onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).not.toHaveBeenCalled();
+ });
+
+ it('applies aria-disabled on trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('applies data-cl-disabled on root and trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-disabled', '');
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toHaveAttribute('data-cl-disabled', '');
+ });
+ });
+
+ describe('accessibility (axe)', () => {
+ it('has no violations when closed', async () => {
+ const { container } = renderCollapsible();
+ expect(await axe(container)).toHaveNoViolations();
+ });
+
+ it('has no violations when open', async () => {
+ const { container } = renderCollapsible({ defaultOpen: true });
+ expect(await axe(container)).toHaveNoViolations();
+ });
+ });
+});

packages/headless/src/primitives/collapsible/index.ts

@@ -0,0 +1,3 @@
+export * as Collapsible from './parts';
+
+export type { CollapsibleProps, CollapsibleTriggerProps, CollapsiblePanelProps } from './parts';

packages/headless/package.json

@@ -33,6 +33,10 @@
  "import": "./dist/primitives/autocomplete/index.js",
  "types": "./dist/primitives/autocomplete/index.d.ts"
  },
+ "./collapsible": {
+ "import": "./dist/primitives/collapsible/index.js",
+ "types": "./dist/primitives/collapsible/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

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

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+
+export interface CollapsibleContextValue {
+ open: boolean;
+ setOpen: (v: boolean) => void;
+ disabled: boolean;
+ triggerId: string;
+ panelId: string;
+}
+
+export const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
+
+export function useCollapsibleContext() {
+ const ctx = useContext(CollapsibleContext);
+ if (!ctx) {
+ throw new Error('Collapsible compound components must be used within <Collapsible.Root>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,79 @@
+'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 { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsiblePanelProps extends ComponentProps<'div'> {}
+
+export function CollapsiblePanel(props: CollapsiblePanelProps) {
+ const { render, ...otherProps } = props;
+ const { open, triggerId, panelId } = useCollapsibleContext();
+
+ const panelRef = useRef<HTMLElement | null>(null);
+ const [height, setHeight] = useState<number | undefined>(undefined);
+ const [width, setWidth] = useState<number | undefined>(undefined);
+
+ const hasBeenClosed = useRef(false);
+ if (!open) hasBeenClosed.current = true;
+
+ const { mounted, transitionProps } = useTransition({
+ open,
+ ref: panelRef as RefObject<HTMLElement>,
+ });
+
+ useLayoutEffect(() => {
+ if (!mounted) return;
+
+ const panel = panelRef.current;
+ if (!panel) return;
+
+ const measure = () => {
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ };
+
+ measure();
+
+ const ro = new ResizeObserver(measure);
+ ro.observe(panel, { box: 'border-box' });
+
+ return () => ro.disconnect();
+ }, [mounted]);
+
+ const state = { open };
+
+ const effectiveTransitionProps = !hasBeenClosed.current
+ ? {
+ ...transitionProps,
+ 'data-cl-starting-style': undefined,
+ style: undefined,
+ }
+ : transitionProps;
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-panel',
+ id: panelId,
+ role: 'region' as const,
+ 'aria-labelledby': triggerId,
+ ref: panelRef,
+ ...effectiveTransitionProps,
+ style: {
+ '--collapsible-panel-height': height != null ? `${height}px` : undefined,
+ '--collapsible-panel-width': width != null ? `${width}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),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible-root.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { type ReactNode, useId, useMemo } from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { CollapsibleContext, type CollapsibleContextValue } from './collapsible-context';
+
+export interface CollapsibleProps extends ComponentProps<'div'> {
+ /** Controlled open state. */
+ open?: boolean;
+ /** Initial open state (uncontrolled). */
+ defaultOpen?: boolean;
+ /** Called when open state changes. */
+ onOpenChange?: (open: boolean) => void;
+ /** Disable the collapsible. @default false */
+ disabled?: boolean;
+ children: ReactNode;
+}
+
+export function CollapsibleRoot(props: CollapsibleProps) {
+ const { render, open: openProp, defaultOpen, onOpenChange, disabled = false, children, ...otherProps } = props;
+
+ const [open, setOpen] = useControllableState(openProp, defaultOpen ?? false, onOpenChange);
+
+ const rootId = useId();
+ const triggerId = `${rootId}trigger`;
+ const panelId = `${rootId}panel`;
+
+ const contextValue = useMemo<CollapsibleContextValue>(
+ () => ({ open, setOpen, disabled, triggerId, panelId }),
+ [open, setOpen, disabled, triggerId, panelId],
+ );
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-root',
+ children,
+ };
+
+ return (
+ <CollapsibleContext.Provider value={contextValue}>
+ {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),
+ })}
+ </CollapsibleContext.Provider>
+ );
+}

packages/headless/src/primitives/collapsible/collapsible-trigger.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useCollapsibleContext } from './collapsible-context';
+
+export interface CollapsibleTriggerProps extends ComponentProps<'button'> {}
+
+export function CollapsibleTrigger(props: CollapsibleTriggerProps) {
+ const { render, ...otherProps } = props;
+ const { open, setOpen, disabled, triggerId, panelId } = useCollapsibleContext();
+
+ const state = { open, disabled };
+
+ const defaultProps: Record<string, unknown> = {
+ 'data-cl-slot': 'collapsible-trigger',
+ id: triggerId,
+ type: 'button' as const,
+ 'aria-expanded': open,
+ 'aria-controls': panelId,
+ 'aria-disabled': disabled || undefined,
+ onClick: () => {
+ if (!disabled) setOpen(!open);
+ },
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ 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<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -0,0 +1,190 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Collapsible } from './index';
+
+afterEach(() => cleanup());
+
+function renderCollapsible(props: Partial<React.ComponentProps<typeof Collapsible.Root>> = {}) {
+ return render(
+ <Collapsible.Root {...props}>
+ <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ <Collapsible.Panel>Content</Collapsible.Panel>
+ </Collapsible.Root>,
+ );
+}
+
+describe('Collapsible', () => {
+ describe('slot attributes', () => {
+ it('renders root with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toBeInTheDocument();
+ });
+
+ it('renders trigger with data-cl-slot', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toBeInTheDocument();
+ });
+
+ it('renders panel with data-cl-slot when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).toBeInTheDocument();
+ });
+ });
+
+ describe('open/close', () => {
+ it('opens panel on trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible();
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('closes panel on second trigger click', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ defaultOpen: true });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('calls onOpenChange when toggled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+
+ it('starts closed by default', () => {
+ renderCollapsible();
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-closed', '');
+ });
+
+ it('starts open with defaultOpen=true', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+ });
+
+ describe('controlled value', () => {
+ it('respects controlled open prop', () => {
+ renderCollapsible({ open: true });
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+
+ it('does not change when controlled', async () => {
+ const user = userEvent.setup();
+ renderCollapsible({ open: false });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(screen.queryByText('Content')).not.toBeInTheDocument();
+ });
+ });
+
+ describe('ARIA attributes', () => {
+ it('trigger has aria-expanded=false when closed', () => {
+ renderCollapsible();
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('trigger has aria-expanded=true when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('trigger has aria-controls linked to panel id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(trigger).toHaveAttribute('aria-controls', panel?.getAttribute('id'));
+ });
+
+ it('panel has aria-labelledby linked to trigger id', () => {
+ renderCollapsible({ defaultOpen: true });
+ const trigger = screen.getByRole('button', { name: 'Toggle' });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('aria-labelledby', trigger.getAttribute('id'));
+ });
+
+ it('panel has role=region', () => {
+ renderCollapsible({ defaultOpen: true });
+ expect(screen.getByRole('region')).toBeInTheDocument();
+ });
+ });
+
+ describe('animation lifecycle', () => {
+ it('panel is not in DOM when closed', () => {
+ renderCollapsible();
+ expect(document.querySelector('[data-cl-slot="collapsible-panel"]')).not.toBeInTheDocument();
+ });
+
+ it('applies data-cl-open on panel when open', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).toHaveAttribute('data-cl-open', '');
+ });
+
+ it('does not apply starting-style on initially open panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]');
+ expect(panel).not.toHaveAttribute('data-cl-starting-style');
+ });
+
+ it('sets --collapsible-panel-height CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ });
+
+ it('sets --collapsible-panel-width CSS variable on panel', () => {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ });
+ });
+
+ describe('disabled', () => {
+ it('prevents toggle when disabled', async () => {
+ const onOpenChange = vi.fn();
+ const user = userEvent.setup();
+ renderCollapsible({ disabled: true, onOpenChange });
+
+ await user.click(screen.getByRole('button', { name: 'Toggle' }));
+
+ expect(onOpenChange).not.toHaveBeenCalled();
+ });
+
+ it('applies aria-disabled on trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('applies data-cl-disabled on root and trigger', () => {
+ renderCollapsible({ disabled: true });
+ expect(document.querySelector('[data-cl-slot="collapsible-root"]')).toHaveAttribute('data-cl-disabled', '');
+ expect(document.querySelector('[data-cl-slot="collapsible-trigger"]')).toHaveAttribute('data-cl-disabled', '');
+ });
+ });
+
+ describe('accessibility (axe)', () => {
+ it('has no violations when closed', async () => {
+ const { container } = renderCollapsible();
+ expect(await axe(container)).toHaveNoViolations();
+ });
+
+ it('has no violations when open', async () => {
+ const { container } = renderCollapsible({ defaultOpen: true });
+ expect(await axe(container)).toHaveNoViolations();
+ });
+ });
+});

packages/headless/src/primitives/collapsible/index.ts

@@ -0,0 +1,3 @@
+export * as Collapsible from './parts';
+
+export type { CollapsibleProps, CollapsibleTriggerProps, CollapsiblePanelProps } from './parts';