paris 0.21.2 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # paris
 
+## 0.22.0
+
+### Minor Changes
+
+- eac5768: Add controlled/uncontrolled hybrid state support to Select, Combobox, Checkbox, AccordionSelect, and Popover via a shared `useControllableState` hook. Components now accept a `defaultValue` (or `defaultChecked` for Checkbox) prop for uncontrolled usage while preserving full backwards compatibility with existing controlled APIs. Combobox internal dual-state bug is also fixed.
+- 5fa2efb: Add compound component API for Drawer with paginated page transitions, progress bar, and slot components.
+
+  **New components:** `DrawerPage`, `DrawerTitle`, `DrawerActions`, `DrawerBottomPanel`, `DrawerProgressBar`
+
+  **New hooks:** `useDrawer()`, `useDrawerPagination()`, `useIsPageActive()`
+
+  **New Drawer props:**
+
+  - `pageTransition` — animated page transitions (`'none'` | `'crossfade'` | `'slide'`)
+  - `progressBar` — show an animated progress bar at the top of the bottom panel, with customizable `fill`, `track`, and `height`
+  - `onAfterClose` — callback fired after the drawer's exit animation completes
+
+  Slot components use `createPortal` to render into Drawer chrome (title bar, actions, bottom panel) from within page content, preserving React context (forms, state). Bottom panel slots support `mode="replace|append"` with priority ordering and automatic separator borders.
+
+  Backward compatible with existing `<div key="...">` pagination pattern.
+
+  **Breaking:** Removed `bottomPanel` and `bottomPanelPadding` props. Use `<DrawerBottomPanel>` as a child instead:
+
+  ```diff
+  - <Drawer bottomPanel={<Content />}>
+  + <Drawer>
+  +   <DrawerBottomPanel><Content /></DrawerBottomPanel>
+  ```
+
+## 0.21.3
+
+### Patch Changes
+
+- d4b6239: fix(select,combobox): fix portaled dropdown width and alignment
+
+  - Use correct CSS variables (`--button-width`, `--input-width`) for portaled dropdown width in Select and Combobox since Headless UI v2.2.x no longer sets `--anchor-width`
+  - Measure actual pixel offset between container and input to align Combobox dropdown with the input container, not the input element
+  - Prevent `ComboboxButton` wrapper from intercepting keyboard events (e.g. space key) meant for the input
+
 ## 0.21.2
 
 ### Patch Changes

package/package.json

@@ -2,7 +2,7 @@
     "name": "paris",
     "author": "Sanil Chawla <sanil@slingshot.fm> (https://sanil.co)",
     "description": "Paris is Slingshot's React design system. It's a collection of reusable components, design tokens, and guidelines that help us build consistent, accessible, and performant user interfaces.",
-    "version": "0.21.2",
+    "version": "0.22.0",
     "homepage": "https://paris.slingshot.fm",
     "license": "MIT",
     "repository": {

package/src/helpers/OpenChangeEffect.tsx

@@ -0,0 +1,21 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * A renderless component that fires a callback when an `open` boolean changes.
+ * Designed to sit inside a Headless UI render-prop child to bridge
+ * the library's internal open state to a consumer-facing `onOpenChange` callback.
+ *
+ * Does not fire on the initial mount — only on subsequent changes.
+ */
+export function OpenChangeEffect({ open, onOpenChange }: { open: boolean; onOpenChange?: (open: boolean) => void }) {
+    const previousOpen = useRef(open);
+
+    useEffect(() => {
+        if (previousOpen.current !== open) {
+            previousOpen.current = open;
+            onOpenChange?.(open);
+        }
+    }, [open, onOpenChange]);
+
+    return null;
+}

package/src/helpers/useControllableState.test.ts

@@ -0,0 +1,88 @@
+import { act, renderHook } from '@testing-library/react';
+import { useControllableState } from './useControllableState';
+
+describe('useControllableState', () => {
+    describe('uncontrolled mode', () => {
+        it('initializes to defaultValue when value is undefined', () => {
+            const { result } = renderHook(() => useControllableState({ defaultValue: 'hello' }));
+            expect(result.current[0]).toBe('hello');
+        });
+
+        it('updates internal state via setter', () => {
+            const { result } = renderHook(() => useControllableState({ defaultValue: 'a' }));
+            act(() => result.current[1]('b'));
+            expect(result.current[0]).toBe('b');
+        });
+
+        it('supports functional updates', () => {
+            const { result } = renderHook(() => useControllableState({ defaultValue: 1 }));
+            act(() => result.current[1]((prev) => prev + 1));
+            expect(result.current[0]).toBe(2);
+        });
+
+        it('calls onChange when setter is invoked', () => {
+            const onChange = vi.fn();
+            const { result } = renderHook(() => useControllableState({ defaultValue: 'a', onChange }));
+            act(() => result.current[1]('b'));
+            expect(onChange).toHaveBeenCalledWith('b');
+        });
+    });
+
+    describe('controlled mode', () => {
+        it('uses the provided value', () => {
+            const { result } = renderHook(() => useControllableState({ value: 'controlled', defaultValue: 'default' }));
+            expect(result.current[0]).toBe('controlled');
+        });
+
+        it('reflects value changes from props', () => {
+            const { result, rerender } = renderHook(
+                ({ value }) => useControllableState({ value, defaultValue: 'default' }),
+                { initialProps: { value: 'a' as string | undefined } },
+            );
+            expect(result.current[0]).toBe('a');
+
+            rerender({ value: 'b' });
+            expect(result.current[0]).toBe('b');
+        });
+
+        it('treats null as controlled (not uncontrolled)', () => {
+            const { result } = renderHook(() =>
+                useControllableState<string | null>({ value: null, defaultValue: 'default' }),
+            );
+            expect(result.current[0]).toBe(null);
+        });
+
+        it('calls onChange but does not update internal state', () => {
+            const onChange = vi.fn();
+            const { result } = renderHook(() =>
+                useControllableState({ value: 'locked', defaultValue: 'default', onChange }),
+            );
+            act(() => result.current[1]('new'));
+            expect(onChange).toHaveBeenCalledWith('new');
+            expect(result.current[0]).toBe('locked');
+        });
+    });
+
+    describe('dev warning', () => {
+        it('warns when both value and defaultValue are provided', () => {
+            const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+            renderHook(() => useControllableState({ value: 'a', defaultValue: 'b' }));
+            expect(spy).toHaveBeenCalledWith(expect.stringContaining('received both `value` and `defaultValue`'));
+            spy.mockRestore();
+        });
+
+        it('does not warn when only value is provided', () => {
+            const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+            renderHook(() => useControllableState({ value: 'a' }));
+            expect(spy).not.toHaveBeenCalled();
+            spy.mockRestore();
+        });
+
+        it('does not warn when only defaultValue is provided', () => {
+            const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+            renderHook(() => useControllableState({ defaultValue: 'a' }));
+            expect(spy).not.toHaveBeenCalled();
+            spy.mockRestore();
+        });
+    });
+});

package/src/helpers/useControllableState.ts

@@ -0,0 +1,59 @@
+import { useCallback, useRef, useState } from 'react';
+
+type UseControllableStateProps<T> = {
+    value?: T;
+    defaultValue?: T;
+    onChange?: (value: T) => void;
+};
+
+export function useControllableState<T>({
+    value: controlledValue,
+    defaultValue,
+    onChange,
+}: UseControllableStateProps<T>): [T, (next: T | ((prev: T) => T)) => void] {
+    const isControlled = controlledValue !== undefined;
+    const [internalValue, setInternalValue] = useState(defaultValue);
+
+    const hasWarned = useRef(false);
+    if (process.env.NODE_ENV !== 'production' && !hasWarned.current) {
+        hasWarned.current = true;
+        if (controlledValue !== undefined && defaultValue !== undefined) {
+            console.warn(
+                '[Paris] A component received both `value` and `defaultValue`. ' +
+                    'A component can be either controlled or uncontrolled, not both. ' +
+                    'Decide between using `value` (controlled) or `defaultValue` (uncontrolled) ' +
+                    'and remove the other. Defaulting to controlled mode.',
+            );
+        }
+    }
+
+    const resolvedValue = isControlled ? controlledValue : internalValue;
+
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+
+    const setValue = useCallback(
+        (next: T | ((prev: T) => T)) => {
+            if (typeof next === 'function') {
+                const updater = next as (prev: T) => T;
+                if (!isControlled) {
+                    setInternalValue((prev) => {
+                        const nextValue = updater(prev as T);
+                        onChangeRef.current?.(nextValue);
+                        return nextValue;
+                    });
+                } else {
+                    onChangeRef.current?.(updater(controlledValue));
+                }
+            } else {
+                if (!isControlled) {
+                    setInternalValue(next);
+                }
+                onChangeRef.current?.(next);
+            }
+        },
+        [isControlled, controlledValue],
+    );
+
+    return [resolvedValue as T, setValue];
+}

package/src/stories/accordionselect/AccordionSelect.test.tsx

@@ -249,4 +249,76 @@ describe('AccordionSelect', () => {
         expect(screen.getByText('On a rooftop, watching the sunset')).toBeInTheDocument();
         expect(screen.getByText('In a garden, under the stars')).toBeInTheDocument();
     });
+
+    describe('uncontrolled selection', () => {
+        it('renders with defaultValue', () => {
+            render(<AccordionSelect options={options} defaultValue="champagne" />);
+            expect(screen.getByText('In an alleyway, drinking champagne')).toBeInTheDocument();
+        });
+
+        it('renders with placeholder when no defaultValue', () => {
+            render(<AccordionSelect options={options} placeholder="Where were we?" />);
+            expect(screen.getByText('Where were we?')).toBeInTheDocument();
+        });
+
+        it('updates selection without external state', async () => {
+            const { user, container } = render(<AccordionSelect options={options} defaultValue="champagne" />);
+
+            const header = container.querySelector('[role="button"][tabindex="0"]') as HTMLElement;
+            await user.click(header);
+
+            await waitFor(() => {
+                expect(screen.getByText('On a rooftop, watching the sunset')).toBeInTheDocument();
+            });
+
+            await user.click(screen.getByText('On a rooftop, watching the sunset'));
+
+            await waitFor(() => {
+                expect(header).toHaveTextContent('On a rooftop, watching the sunset');
+            });
+        });
+
+        it('calls onChange in uncontrolled mode', async () => {
+            const handleChange = vi.fn();
+            const { user, container } = render(
+                <AccordionSelect options={options} defaultValue="champagne" onChange={handleChange} />,
+            );
+
+            const header = container.querySelector('[role="button"][tabindex="0"]') as HTMLElement;
+            await user.click(header);
+
+            await waitFor(() => {
+                expect(screen.getByText('On a rooftop, watching the sunset')).toBeInTheDocument();
+            });
+
+            await user.click(screen.getByText('On a rooftop, watching the sunset'));
+
+            expect(handleChange).toHaveBeenCalledWith(expect.objectContaining({ id: 'rooftop' }));
+        });
+
+        it('renders disabled option as selected when defaultValue points to it', async () => {
+            const disabledOptions = [
+                ...options,
+                { id: 'nowhere', node: 'Nowhere, it was all a dream', disabled: true },
+            ];
+            const { user, container } = render(<AccordionSelect options={disabledOptions} defaultValue="nowhere" />);
+
+            // Header shows the disabled option's text
+            const allMatches = screen.getAllByText('Nowhere, it was all a dream');
+            expect(allMatches.length).toBeGreaterThanOrEqual(1);
+
+            // Open and verify the option button is disabled
+            const header = container.querySelector('[role="button"][tabindex="0"]') as HTMLElement;
+            await user.click(header);
+
+            await waitFor(() => {
+                // Find the option button (not the header text)
+                const optionButtons = container.querySelectorAll('button[data-selected]');
+                const disabledButton = Array.from(optionButtons).find((btn) => btn.textContent?.includes('Nowhere'));
+                expect(disabledButton).toBeTruthy();
+                expect(disabledButton).toBeDisabled();
+                expect(disabledButton).toHaveAttribute('data-selected', 'true');
+            });
+        });
+    });
 });

package/src/stories/accordionselect/AccordionSelect.tsx

@@ -3,7 +3,8 @@
 import { clsx } from 'clsx';
 import { AnimatePresence, motion } from 'framer-motion';
 import type { ComponentPropsWithoutRef, FC, ReactNode } from 'react';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useEffect, useRef } from 'react';
+import { useControllableState } from '../../helpers/useControllableState';
 import { Check, ChevronRight, Icon } from '../icon';
 import { TextWhenString } from '../utility';
 import styles from './AccordionSelect.module.scss';
@@ -37,6 +38,10 @@ export type AccordionSelectProps<T = Record<string, unknown>> = {
      * The currently selected option ID.
      */
     value?: string | null;
+    /**
+     * The initial selected option ID for uncontrolled mode. If `value` is provided, this is ignored.
+     */
+    defaultValue?: string | null;
     /**
      * Called when the user selects an option.
      */
@@ -109,6 +114,7 @@ export type AccordionSelectProps<T = Record<string, unknown>> = {
 export const AccordionSelect: FC<AccordionSelectProps> = ({
     options,
     value,
+    defaultValue,
     onChange,
     renderSelected,
     renderOption,
@@ -121,19 +127,23 @@ export const AccordionSelect: FC<AccordionSelectProps> = ({
     label,
     overrides,
 }) => {
-    const [internalOpen, setInternalOpen] = useState(false);
-    const open = controlledOpen ?? internalOpen;
+    const [open, setOpen] = useControllableState({
+        value: controlledOpen,
+        defaultValue: false,
+        onChange: onOpenChange,
+    });
     const rootRef = useRef<HTMLDivElement>(null);
 
-    const setOpen = useCallback(
-        (nextOpen: boolean) => {
-            setInternalOpen(nextOpen);
-            onOpenChange?.(nextOpen);
+    const [resolvedValue, setResolvedValue] = useControllableState<string | null>({
+        value,
+        defaultValue,
+        onChange: (id) => {
+            const option = options.find((o) => o.id === id);
+            if (option) onChange?.(option);
         },
-        [onOpenChange],
-    );
+    });
 
-    const selectedOption = options.find((o) => o.id === value);
+    const selectedOption = options.find((o) => o.id === resolvedValue);
 
     useEffect(() => {
         if (!closeOnClickOutside || !open) {
@@ -207,7 +217,7 @@ export const AccordionSelect: FC<AccordionSelectProps> = ({
                             className={clsx(styles.dropdownContent, overrides?.dropdownContent?.className)}
                         >
                             {options.map((option) => {
-                                const isOptionSelected = option.id === value;
+                                const isOptionSelected = option.id === resolvedValue;
                                 return (
                                     <button
                                         key={option.id}
@@ -217,7 +227,7 @@ export const AccordionSelect: FC<AccordionSelectProps> = ({
                                         {...overrides?.option}
                                         className={clsx(styles.option, overrides?.option?.className)}
                                         onClick={() => {
-                                            onChange?.(option);
+                                            setResolvedValue(option.id);
                                             if (closeOnSelect) setOpen(false);
                                         }}
                                     >

package/src/stories/checkbox/Checkbox.test.tsx

@@ -480,6 +480,59 @@ describe('Checkbox', () => {
         });
     });
 
+    // ─── Uncontrolled mode ───────────────────────────────────────────
+
+    describe('uncontrolled mode', () => {
+        it('renders unchecked when defaultChecked is false', () => {
+            render(<Checkbox defaultChecked={false}>Label</Checkbox>);
+            expect(screen.getByRole('checkbox')).not.toBeChecked();
+        });
+
+        it('renders checked when defaultChecked is true', () => {
+            render(<Checkbox defaultChecked={true}>Label</Checkbox>);
+            expect(screen.getByRole('checkbox')).toBeChecked();
+        });
+
+        it('toggles without external state', async () => {
+            const { user } = render(<Checkbox defaultChecked={false}>Toggle</Checkbox>);
+
+            const checkbox = screen.getByRole('checkbox');
+            expect(checkbox).not.toBeChecked();
+
+            await user.click(checkbox);
+            expect(checkbox).toBeChecked();
+
+            await user.click(checkbox);
+            expect(checkbox).not.toBeChecked();
+        });
+
+        it('calls onChange in uncontrolled mode', async () => {
+            const handleChange = vi.fn();
+            const { user } = render(
+                <Checkbox defaultChecked={false} onChange={handleChange}>
+                    Toggle
+                </Checkbox>,
+            );
+
+            await user.click(screen.getByRole('checkbox'));
+            expect(handleChange).toHaveBeenCalledWith(true);
+        });
+
+        it('toggles switch kind without external state', async () => {
+            const { user } = render(
+                <Checkbox kind="switch" defaultChecked={false}>
+                    Switch
+                </Checkbox>,
+            );
+
+            const switchEl = screen.getByRole('switch');
+            expect(switchEl).not.toBeChecked();
+
+            await user.click(switchEl);
+            expect(switchEl).toBeChecked();
+        });
+    });
+
     // ─── Edge cases ──────────────────────────────────────────────────
 
     describe('edge cases', () => {

package/src/stories/checkbox/Checkbox.tsx

@@ -1,8 +1,10 @@
+'use client';
 import { Switch } from '@headlessui/react';
 import * as RadixCheckbox from '@radix-ui/react-checkbox';
 import { clsx } from 'clsx';
 import type { FC, ReactNode } from 'react';
 import { useId } from 'react';
+import { useControllableState } from '../../helpers/useControllableState';
 import { Check, Icon } from '../icon';
 import { TextWhenString, VisuallyHidden } from '../utility';
 import styles from './Checkbox.module.scss';
@@ -19,6 +21,8 @@ export type CheckboxProps = {
      * @default false
      */
     hideLabel?: boolean;
+    /** The initial checked state for uncontrolled mode. If `checked` is provided, this is ignored. */
+    defaultChecked?: boolean;
     /** The contents of the Checkbox. */
     children?: ReactNode | ReactNode[];
 } & Omit<React.ComponentPropsWithoutRef<'label'>, 'onChange' | 'children'>;
@@ -38,6 +42,7 @@ export type CheckboxProps = {
 export const Checkbox: FC<CheckboxProps> = ({
     kind = 'default',
     checked,
+    defaultChecked,
     onChange,
     disabled,
     hideLabel = false,
@@ -46,18 +51,28 @@ export const Checkbox: FC<CheckboxProps> = ({
     ...props
 }) => {
     const inputID = useId();
+    const [resolvedChecked, setResolvedChecked] = useControllableState({
+        value: checked,
+        defaultValue: defaultChecked,
+        onChange: onChange as ((value: boolean) => void) | undefined,
+    });
     return (
         <label
             htmlFor={inputID}
-            className={clsx(styles.container, disabled && styles.disabled, className, checked && styles.checked)}
+            className={clsx(
+                styles.container,
+                disabled && styles.disabled,
+                className,
+                resolvedChecked && styles.checked,
+            )}
             {...props}
         >
             {(kind === 'default' || kind === 'surface' || kind === 'panel') && (
                 <RadixCheckbox.Root
                     id={inputID}
                     className={clsx(styles.root, styles[kind])}
-                    checked={checked}
-                    onCheckedChange={onChange}
+                    checked={resolvedChecked}
+                    onCheckedChange={(v) => setResolvedChecked(!!v)}
                     data-disabled={disabled}
                     aria-details={typeof children === 'string' ? children : undefined}
                 >
@@ -89,14 +104,14 @@ export const Checkbox: FC<CheckboxProps> = ({
             )}
             {kind === 'switch' && (
                 <Switch
-                    checked={checked}
-                    onChange={onChange}
+                    checked={resolvedChecked}
+                    onChange={setResolvedChecked}
                     className={styles.switchContainer}
                     data-disabled={disabled}
                     id={inputID}
                     aria-details={typeof children === 'string' ? children : undefined}
                 >
-                    <span aria-hidden="true" className={clsx(styles.knob, checked && styles.knobChecked)} />
+                    <span aria-hidden="true" className={clsx(styles.knob, resolvedChecked && styles.knobChecked)} />
                 </Switch>
             )}
             {(kind === 'default' || kind === 'switch') && !hideLabel && (

package/src/stories/combobox/Combobox.test.tsx

@@ -161,4 +161,115 @@ describe('Combobox', () => {
             expect(screen.getByText('Add "New Artist"')).toBeInTheDocument();
         });
     });
+
+    describe('uncontrolled mode', () => {
+        it('renders with placeholder when no defaultValue', () => {
+            render(<Combobox options={options} placeholder="Search..." />);
+            expect(screen.getByPlaceholderText('Search...')).toBeInTheDocument();
+        });
+
+        it('renders with defaultValue', () => {
+            render(
+                <Combobox options={options} defaultValue={{ id: '1', node: 'Mia Dolan' }} placeholder="Search..." />,
+            );
+            expect(screen.getByDisplayValue('Mia Dolan')).toBeInTheDocument();
+        });
+
+        it('selects an option without external state', async () => {
+            const { user } = render(<Combobox options={options} defaultValue={null} placeholder="Search..." />);
+            const input = screen.getByPlaceholderText('Search...');
+            await user.click(input);
+
+            await waitFor(() => {
+                expect(screen.getByText('Amy Brandt')).toBeInTheDocument();
+            });
+
+            await user.click(screen.getByText('Amy Brandt'));
+
+            await waitFor(() => {
+                expect(screen.getByDisplayValue('Amy Brandt')).toBeInTheDocument();
+            });
+        });
+
+        it('calls onChange in uncontrolled mode', async () => {
+            const handleChange = vi.fn();
+            const { user } = render(
+                <Combobox options={options} defaultValue={null} onChange={handleChange} placeholder="Search..." />,
+            );
+            const input = screen.getByPlaceholderText('Search...');
+            await user.click(input);
+
+            await waitFor(() => {
+                expect(screen.getByText('Amy Brandt')).toBeInTheDocument();
+            });
+
+            await user.click(screen.getByText('Amy Brandt'));
+            expect(handleChange).toHaveBeenCalledWith(expect.objectContaining({ id: '3', node: 'Amy Brandt' }));
+        });
+
+        it('clears selection in uncontrolled mode', async () => {
+            const { user, container } = render(
+                <Combobox options={options} defaultValue={{ id: '1', node: 'Mia Dolan' }} placeholder="Search..." />,
+            );
+
+            expect(screen.getByDisplayValue('Mia Dolan')).toBeInTheDocument();
+
+            const clearButton = container.querySelector('button[aria-details="Clear"]');
+            expect(clearButton).toBeInTheDocument();
+            await user.click(clearButton!);
+
+            await waitFor(() => {
+                expect(screen.getByPlaceholderText('Search...')).toBeInTheDocument();
+                expect(screen.queryByDisplayValue('Mia Dolan')).not.toBeInTheDocument();
+            });
+        });
+
+        it('renders with defaultValue using non-string node', () => {
+            const optionsWithNode = [
+                { id: '1', node: <span data-testid="custom-node">Custom Mia</span> },
+                { id: '2', node: 'Sebastian Wilder' },
+            ];
+            render(
+                <Combobox
+                    options={optionsWithNode}
+                    defaultValue={{ id: '1', node: <span data-testid="custom-node">Custom Mia</span> }}
+                    placeholder="Search..."
+                />,
+            );
+            expect(screen.getByTestId('custom-node')).toBeInTheDocument();
+        });
+    });
+
+    describe('onOpenChange', () => {
+        it('calls onOpenChange when the dropdown opens', async () => {
+            const handleOpenChange = vi.fn();
+            const { user } = render(
+                <Combobox options={options} onOpenChange={handleOpenChange} placeholder="Search..." />,
+            );
+
+            await user.click(screen.getByPlaceholderText('Search...'));
+
+            await waitFor(() => {
+                expect(handleOpenChange).toHaveBeenCalledWith(true);
+            });
+        });
+
+        it('calls onOpenChange when the dropdown closes after selection', async () => {
+            const handleOpenChange = vi.fn();
+            const { user } = render(<ControlledCombobox onOpenChange={handleOpenChange} />);
+
+            const input = screen.getByPlaceholderText('Search...');
+            await user.click(input);
+
+            await waitFor(() => {
+                expect(screen.getByText('Amy Brandt')).toBeInTheDocument();
+            });
+
+            await user.click(screen.getByText('Amy Brandt'));
+
+            await waitFor(() => {
+                expect(handleOpenChange).toHaveBeenCalledWith(false);
+            });
+        });
+    });
 });