paris 0.21.2 → 0.22.0

package/src/stories/drawer/DrawerActions.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+import { type ReactNode, useId, useLayoutEffect } from 'react';
+import { createPortal } from 'react-dom';
+import { useIsPageActive } from './DrawerPageContext';
+import { useDrawerSlotContext } from './DrawerSlotContext';
+
+export type DrawerActionsProps = {
+    children: ReactNode;
+};
+
+export const DrawerActions = ({ children }: DrawerActionsProps) => {
+    const isActive = useIsPageActive();
+    const slotContext = useDrawerSlotContext();
+    const id = useId();
+
+    useLayoutEffect(() => {
+        if (!isActive || !slotContext) return;
+        const unregister = slotContext.registerActionsSlot();
+        return unregister;
+    }, [isActive, slotContext]);
+
+    if (!isActive || !slotContext?.actionsRef.current) {
+        return null;
+    }
+
+    return createPortal(children, slotContext.actionsRef.current, id);
+};

package/src/stories/drawer/DrawerBottomPanel.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { clsx } from 'clsx';
+import { type ComponentPropsWithoutRef, type ReactNode, useId, useLayoutEffect } from 'react';
+import { createPortal } from 'react-dom';
+import styles from './Drawer.module.scss';
+import { useIsPageActive } from './DrawerPageContext';
+import { useDrawerSlotContext } from './DrawerSlotContext';
+
+export type DrawerBottomPanelProps = ComponentPropsWithoutRef<'div'> & {
+    children: ReactNode;
+    /** 'replace' fully replaces the base bottomPanel. 'append' renders after the base. @default 'replace' */
+    mode?: 'replace' | 'append';
+    /** Render order for append mode. Lower = higher up. @default 0 */
+    priority?: number;
+};
+
+export const DrawerBottomPanel = ({
+    children,
+    className,
+    mode = 'replace',
+    priority = 0,
+    style,
+    ...rest
+}: DrawerBottomPanelProps) => {
+    const isActive = useIsPageActive();
+    const slotContext = useDrawerSlotContext();
+    const id = useId();
+
+    const registerBottomPanel = slotContext?.registerBottomPanel;
+
+    useLayoutEffect(() => {
+        if (!isActive || !registerBottomPanel) return;
+        const unregister = registerBottomPanel({ id, mode, priority });
+        return unregister;
+    }, [isActive, registerBottomPanel, id, mode, priority]);
+
+    if (!isActive || !slotContext?.isBottomPanelMounted || !slotContext.bottomPanelRef.current) {
+        return null;
+    }
+
+    return createPortal(
+        <div
+            data-slot-mode={mode}
+            data-slot-priority={priority}
+            className={clsx(styles.bottomPanelSlotItem, className)}
+            style={{ order: priority, ...style }}
+            {...rest}
+        >
+            {children}
+        </div>,
+        slotContext.bottomPanelRef.current,
+        `${id}-${priority}`,
+    );
+};

package/src/stories/drawer/DrawerContext.tsx

@@ -0,0 +1,31 @@
+'use client';
+
+import { createContext, type ReactNode, useContext, useMemo } from 'react';
+
+export type DrawerContextValue = {
+    close: () => void;
+    isOpen: boolean;
+};
+
+const DrawerContext = createContext<DrawerContextValue | null>(null);
+
+export function useDrawer(): DrawerContextValue {
+    const context = useContext(DrawerContext);
+    if (!context) {
+        throw new Error('useDrawer must be used within a Drawer component');
+    }
+    return context;
+}
+
+export function DrawerProvider({
+    close,
+    isOpen,
+    children,
+}: {
+    close: () => void;
+    isOpen: boolean;
+    children: ReactNode;
+}) {
+    const value = useMemo(() => ({ close, isOpen }), [close, isOpen]);
+    return <DrawerContext.Provider value={value}>{children}</DrawerContext.Provider>;
+}

package/src/stories/drawer/DrawerPage.tsx

@@ -0,0 +1,37 @@
+'use client';
+
+import { type ReactNode, useEffect, useState } from 'react';
+import { useIsPageActive } from './DrawerPageContext';
+
+export type DrawerPageProps<TPageID extends string = string> = {
+    /** Unique identifier for this page. Must match a pagination page ID. */
+    id: TPageID;
+    /** Defer first mount until page becomes active. Once mounted, stays mounted. */
+    lazy?: boolean;
+    /** Page content. */
+    children: ReactNode;
+};
+
+export const DrawerPage = <TPageID extends string = string>({ lazy = false, children }: DrawerPageProps<TPageID>) => {
+    const isActive = useIsPageActive();
+    const [hasBeenActive, setHasBeenActive] = useState(isActive);
+
+    useEffect(() => {
+        if (isActive && !hasBeenActive) {
+            setHasBeenActive(true);
+        }
+    }, [isActive, hasBeenActive]);
+
+    if (lazy && !hasBeenActive) {
+        return null;
+    }
+
+    return <>{children}</>;
+};
+
+/** Type guard to check if a React element is a DrawerPage */
+export const isDrawerPageElement = (element: unknown): element is React.ReactElement<DrawerPageProps> =>
+    element != null &&
+    typeof element === 'object' &&
+    'type' in element &&
+    (element as { type: unknown }).type === DrawerPage;

package/src/stories/drawer/DrawerPageContext.tsx

@@ -0,0 +1,35 @@
+'use client';
+
+import { createContext, type ReactNode, useContext, useMemo } from 'react';
+
+export type DrawerPageContextValue = {
+    isActive: boolean;
+    pageID: string;
+};
+
+const DrawerPageContext = createContext<DrawerPageContextValue | null>(null);
+
+export function useDrawerPageContext(): DrawerPageContextValue | null {
+    return useContext(DrawerPageContext);
+}
+
+export function useIsPageActive(): boolean {
+    const context = useContext(DrawerPageContext);
+    if (!context) {
+        return true;
+    }
+    return context.isActive;
+}
+
+export function DrawerPageProvider({
+    isActive,
+    pageID,
+    children,
+}: {
+    isActive: boolean;
+    pageID: string;
+    children: ReactNode;
+}) {
+    const value = useMemo(() => ({ isActive, pageID }), [isActive, pageID]);
+    return <DrawerPageContext.Provider value={value}>{children}</DrawerPageContext.Provider>;
+}

package/src/stories/drawer/DrawerPaginationContext.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { createContext, type ReactNode, useContext } from 'react';
+import type { PaginationState } from '../pagination';
+
+type AnyPaginationState = PaginationState<string[] | readonly string[]>;
+
+const DrawerPaginationContext = createContext<AnyPaginationState | null>(null);
+
+export function useDrawerPagination(): AnyPaginationState | null {
+    return useContext(DrawerPaginationContext);
+}
+
+export function DrawerPaginationProvider({
+    pagination,
+    children,
+}: {
+    pagination: AnyPaginationState | null;
+    children: ReactNode;
+}) {
+    return <DrawerPaginationContext.Provider value={pagination}>{children}</DrawerPaginationContext.Provider>;
+}

package/src/stories/drawer/DrawerProgressBar.tsx

@@ -0,0 +1,72 @@
+'use client';
+
+import { useLayoutEffect } from 'react';
+import { createPortal } from 'react-dom';
+import styles from './Drawer.module.scss';
+import { useDrawerPagination } from './DrawerPaginationContext';
+import { useDrawerSlotContext } from './DrawerSlotContext';
+
+export type DrawerProgressBarStyleProps = {
+    /** Fill color. @default 'var(--pte-new-colors-contentPrimary)' */
+    fill?: string;
+    /** Track (unfilled) color. @default 'var(--pte-new-colors-borderMedium)' */
+    track?: string;
+    /** Bar height as a CSS value. @default '2px' */
+    height?: string | number;
+};
+
+export type DrawerProgressBarProps = DrawerProgressBarStyleProps & {
+    /** Page IDs in order. Determines fill percentage based on the current page. */
+    steps?: readonly string[];
+    /** Fill percentage (0–100). When provided, takes precedence over the auto-calculated value from `steps`. */
+    value?: number;
+};
+
+export const DrawerProgressBar = ({ steps, value, fill, track, height }: DrawerProgressBarProps) => {
+    const pagination = useDrawerPagination();
+    const slotContext = useDrawerSlotContext();
+
+    const registerProgressBar = slotContext?.registerProgressBar;
+    useLayoutEffect(() => {
+        if (!registerProgressBar) return;
+        return registerProgressBar();
+    }, [registerProgressBar]);
+
+    let progress: number;
+    if (value != null) {
+        progress = Math.max(0, Math.min(100, value));
+    } else if (steps && steps.length > 0 && pagination) {
+        const activeIndex = steps.indexOf(pagination.currentPage);
+        progress = ((activeIndex + 1) / steps.length) * 100;
+    } else {
+        progress = 0;
+    }
+
+    if (!slotContext?.progressBarRef.current) {
+        return null;
+    }
+
+    return createPortal(
+        <div
+            className={styles.progressBar}
+            role="progressbar"
+            aria-valuemin={0}
+            aria-valuenow={Math.round(progress)}
+            aria-valuemax={100}
+            aria-label="Page progress"
+            style={{
+                ...(track && { background: track }),
+                ...(height != null && { height: typeof height === 'number' ? `${height}px` : height }),
+            }}
+        >
+            <div
+                className={styles.progressBarFill}
+                style={{
+                    width: `${progress}%`,
+                    ...(fill && { background: fill }),
+                }}
+            />
+        </div>,
+        slotContext.progressBarRef.current,
+    );
+};

package/src/stories/drawer/DrawerSlotContext.tsx

@@ -0,0 +1,172 @@
+'use client';
+
+import {
+    createContext,
+    type ReactNode,
+    type RefObject,
+    useCallback,
+    useContext,
+    useMemo,
+    useRef,
+    useState,
+} from 'react';
+
+export type BottomPanelEntry = {
+    id: string;
+    mode: 'replace' | 'append';
+    priority: number;
+};
+
+export type DrawerSlotContextValue = {
+    titleRef: RefObject<HTMLDivElement | null>;
+    actionsRef: RefObject<HTMLDivElement | null>;
+    bottomPanelRef: RefObject<HTMLDivElement | null>;
+    /** Callback ref for the bottom panel portal target — triggers re-render when assigned */
+    bottomPanelCallbackRef: (node: HTMLDivElement | null) => void;
+    /** Whether the bottom panel portal target is mounted in the DOM */
+    isBottomPanelMounted: boolean;
+
+    /** Portal target for the progress bar, rendered at the very top of the bottom panel */
+    progressBarRef: RefObject<HTMLDivElement | null>;
+
+    hasTitleSlot: boolean;
+    hasActionsSlot: boolean;
+    hasProgressBar: boolean;
+
+    /** Whether a replace-mode bottom panel is registered */
+    hasBottomPanelReplace: boolean;
+    /** Whether any bottom panel slot (replace or append) is registered */
+    hasAnyBottomPanelSlot: boolean;
+    /** Sorted list of append-mode bottom panel entries */
+    bottomPanelAppendEntries: BottomPanelEntry[];
+
+    registerTitleSlot: () => () => void;
+    registerActionsSlot: () => () => void;
+    registerProgressBar: () => () => void;
+    registerBottomPanel: (entry: BottomPanelEntry) => () => void;
+};
+
+const DrawerSlotContext = createContext<DrawerSlotContextValue | null>(null);
+
+export function useDrawerSlotContext(): DrawerSlotContextValue | null {
+    return useContext(DrawerSlotContext);
+}
+
+export function DrawerSlotProvider({ children }: { children: ReactNode }) {
+    const titleRef = useRef<HTMLDivElement | null>(null);
+    const actionsRef = useRef<HTMLDivElement | null>(null);
+    const progressBarRef = useRef<HTMLDivElement | null>(null);
+    const bottomPanelRef = useRef<HTMLDivElement | null>(null);
+    const [isBottomPanelMounted, setIsBottomPanelMounted] = useState(false);
+
+    const bottomPanelCallbackRef = useCallback((node: HTMLDivElement | null) => {
+        bottomPanelRef.current = node;
+        setIsBottomPanelMounted(node !== null);
+    }, []);
+
+    const [titleSlotCount, setTitleSlotCount] = useState(0);
+    const [actionsSlotCount, setActionsSlotCount] = useState(0);
+    const [progressBarCount, setProgressBarCount] = useState(0);
+    const [bottomPanelEntries, setBottomPanelEntries] = useState<BottomPanelEntry[]>([]);
+
+    const registerTitleSlot = useCallback((): (() => void) => {
+        setTitleSlotCount((prev) => {
+            const next = prev + 1;
+            if (process.env.NODE_ENV === 'development' && next > 1) {
+                console.warn(
+                    'DrawerSlotContext: Multiple title slots registered simultaneously. Only one is expected.',
+                );
+            }
+            return next;
+        });
+        return () => {
+            setTitleSlotCount((prev) => Math.max(0, prev - 1));
+        };
+    }, []);
+
+    const registerActionsSlot = useCallback((): (() => void) => {
+        setActionsSlotCount((prev) => {
+            const next = prev + 1;
+            if (process.env.NODE_ENV === 'development' && next > 1) {
+                console.warn(
+                    'DrawerSlotContext: Multiple actions slots registered simultaneously. Only one is expected.',
+                );
+            }
+            return next;
+        });
+        return () => {
+            setActionsSlotCount((prev) => Math.max(0, prev - 1));
+        };
+    }, []);
+
+    const registerProgressBar = useCallback((): (() => void) => {
+        setProgressBarCount((prev) => prev + 1);
+        return () => {
+            setProgressBarCount((prev) => Math.max(0, prev - 1));
+        };
+    }, []);
+
+    const registerBottomPanel = useCallback((entry: BottomPanelEntry): (() => void) => {
+        setBottomPanelEntries((prev) => {
+            if (process.env.NODE_ENV === 'development' && entry.mode === 'replace') {
+                const existingReplace = prev.find((e) => e.mode === 'replace');
+                if (existingReplace) {
+                    console.warn(
+                        `DrawerSlotContext: Multiple replace-mode bottom panels registered (existing: "${existingReplace.id}", new: "${entry.id}"). Only one replace-mode panel is expected.`,
+                    );
+                }
+            }
+            return [...prev, entry];
+        });
+        return () => {
+            setBottomPanelEntries((prev) => prev.filter((e) => e.id !== entry.id));
+        };
+    }, []);
+
+    const hasTitleSlot = titleSlotCount > 0;
+    const hasActionsSlot = actionsSlotCount > 0;
+    const hasProgressBar = progressBarCount > 0;
+    const hasBottomPanelReplace = bottomPanelEntries.some((e) => e.mode === 'replace');
+    const hasAnyBottomPanelSlot = bottomPanelEntries.length > 0;
+    const bottomPanelAppendEntries = useMemo(
+        () => bottomPanelEntries.filter((e) => e.mode === 'append').sort((a, b) => a.priority - b.priority),
+        [bottomPanelEntries],
+    );
+
+    const value = useMemo<DrawerSlotContextValue>(
+        () => ({
+            titleRef,
+            actionsRef,
+            progressBarRef,
+            bottomPanelRef,
+            bottomPanelCallbackRef,
+            isBottomPanelMounted,
+            hasTitleSlot,
+            hasActionsSlot,
+            hasProgressBar,
+            hasBottomPanelReplace,
+            hasAnyBottomPanelSlot,
+            bottomPanelAppendEntries,
+            registerTitleSlot,
+            registerActionsSlot,
+            registerProgressBar,
+            registerBottomPanel,
+        }),
+        [
+            bottomPanelCallbackRef,
+            isBottomPanelMounted,
+            hasTitleSlot,
+            hasActionsSlot,
+            hasProgressBar,
+            hasBottomPanelReplace,
+            hasAnyBottomPanelSlot,
+            bottomPanelAppendEntries,
+            registerTitleSlot,
+            registerActionsSlot,
+            registerProgressBar,
+            registerBottomPanel,
+        ],
+    );
+
+    return <DrawerSlotContext.Provider value={value}>{children}</DrawerSlotContext.Provider>;
+}

package/src/stories/drawer/DrawerTitle.tsx

@@ -0,0 +1,35 @@
+'use client';
+
+import { type ReactNode, useId, useLayoutEffect } from 'react';
+import { createPortal } from 'react-dom';
+import { TextWhenString } from '../utility/TextWhenString';
+import { useIsPageActive } from './DrawerPageContext';
+import { useDrawerSlotContext } from './DrawerSlotContext';
+
+export type DrawerTitleProps = {
+    children: ReactNode;
+};
+
+export const DrawerTitle = ({ children }: DrawerTitleProps) => {
+    const isActive = useIsPageActive();
+    const slotContext = useDrawerSlotContext();
+    const id = useId();
+
+    useLayoutEffect(() => {
+        if (!isActive || !slotContext) return;
+        const unregister = slotContext.registerTitleSlot();
+        return unregister;
+    }, [isActive, slotContext]);
+
+    if (!isActive || !slotContext?.titleRef.current) {
+        return null;
+    }
+
+    return createPortal(
+        <TextWhenString kind="paragraphSmall" weight="medium">
+            {children}
+        </TextWhenString>,
+        slotContext.titleRef.current,
+        id,
+    );
+};

package/src/stories/drawer/index.ts

@@ -1 +1,10 @@
 export * from './Drawer';
+export { DrawerActions, type DrawerActionsProps } from './DrawerActions';
+export { DrawerBottomPanel, type DrawerBottomPanelProps } from './DrawerBottomPanel';
+export type { DrawerContextValue } from './DrawerContext';
+export { useDrawer } from './DrawerContext';
+export { DrawerPage, type DrawerPageProps } from './DrawerPage';
+export { useIsPageActive } from './DrawerPageContext';
+export { useDrawerPagination } from './DrawerPaginationContext';
+export { DrawerProgressBar, type DrawerProgressBarProps, type DrawerProgressBarStyleProps } from './DrawerProgressBar';
+export { DrawerTitle, type DrawerTitleProps } from './DrawerTitle';

package/src/stories/menu/Menu.test.tsx

@@ -208,4 +208,47 @@ describe('Menu', () => {
         const archiveItem = screen.getByText('Archive');
         expect(archiveItem.closest('[data-disabled]')).toBeInTheDocument();
     });
+
+    describe('onOpenChange', () => {
+        it('calls onOpenChange when the menu opens', async () => {
+            const handleOpenChange = vi.fn();
+            const { user } = render(
+                <Menu onOpenChange={handleOpenChange}>
+                    <MenuButton>Options</MenuButton>
+                    <MenuItems>
+                        <MenuItem as="button">Edit</MenuItem>
+                    </MenuItems>
+                </Menu>,
+            );
+
+            await user.click(screen.getByText('Options'));
+
+            await waitFor(() => {
+                expect(handleOpenChange).toHaveBeenCalledWith(true);
+            });
+        });
+
+        it('calls onOpenChange when the menu closes', async () => {
+            const handleOpenChange = vi.fn();
+            const { user } = render(
+                <Menu onOpenChange={handleOpenChange}>
+                    <MenuButton>Options</MenuButton>
+                    <MenuItems>
+                        <MenuItem as="button">Edit</MenuItem>
+                    </MenuItems>
+                </Menu>,
+            );
+
+            await user.click(screen.getByText('Options'));
+            await waitFor(() => {
+                expect(screen.getByText('Edit')).toBeInTheDocument();
+            });
+
+            await user.click(screen.getByText('Edit'));
+
+            await waitFor(() => {
+                expect(handleOpenChange).toHaveBeenCalledWith(false);
+            });
+        });
+    });
 });

package/src/stories/menu/Menu.tsx

@@ -7,6 +7,7 @@ import {
 } from '@headlessui/react';
 import { clsx } from 'clsx';
 import type { FC } from 'react';
+import { OpenChangeEffect } from '../../helpers/OpenChangeEffect';
 
 import styles from './Menu.module.scss';
 
@@ -27,9 +28,19 @@ import styles from './Menu.module.scss';
  * </Menu>
  * ```
  */
-export const Menu: FC<MenuProps<React.ElementType>> = ({ className, children, ...props }) => (
+export const Menu: FC<MenuProps<React.ElementType> & { onOpenChange?: (open: boolean) => void }> = ({
+    className,
+    children,
+    onOpenChange,
+    ...props
+}) => (
     <HeadlessMenu as="div" className={clsx(styles.menu, className)} {...props}>
-        {children}
+        {({ open, close }) => (
+            <>
+                <OpenChangeEffect open={open} onOpenChange={onOpenChange} />
+                {typeof children === 'function' ? children({ open, close }) : children}
+            </>
+        )}
     </HeadlessMenu>
 );
 

package/src/stories/popover/Popover.tsx

@@ -2,9 +2,10 @@
 
 import { clsx } from 'clsx';
 import type { ComponentPropsWithoutRef, FC, ReactElement, ReactNode } from 'react';
-import { forwardRef, useState } from 'react';
+import { forwardRef } from 'react';
 import type { PopoverProps as RTPopoverProps } from 'react-tiny-popover';
 import { Popover as RTPopover } from 'react-tiny-popover';
+import { useControllableState } from '../../helpers/useControllableState';
 import typography from '../text/Typography.module.css';
 import styles from './Popover.module.scss';
 
@@ -57,25 +58,27 @@ export const Popover: FC<PopoverProps> = ({
     setIsOpen,
     ...props
 }) => {
-    const [open, setOpen] = useState(false);
+    const [open, setOpen] = useControllableState({
+        value: isOpen,
+        defaultValue: false,
+        onChange: setIsOpen,
+    });
 
     return (
         <RTPopover
             positions={positions || ['bottom', 'top', 'left', 'right']}
             align={align || 'start'}
             padding={padding || 8}
-            isOpen={typeof isOpen === 'undefined' ? open : isOpen}
+            isOpen={open}
             containerClassName={clsx(typography.paragraphSmall, styles.content)}
             content={<>{children}</>}
             onClickOutside={() => {
-                setIsOpen?.(false);
                 setOpen(false);
             }}
             {...props}
         >
             <Trigger
                 onClick={() => {
-                    setIsOpen?.(!isOpen);
                     setOpen((cur) => !cur);
                 }}
             >

package/src/stories/select/Select.module.scss

@@ -25,7 +25,7 @@
 }
 
 .options {
-    width: var(--anchor-width);
+    width: max(var(--button-width, 0px), var(--input-width, 0px));
     max-height: var(--options-maxHeight, auto);
     overflow-y: auto;
     overflow-x: hidden;