feat: Drawer & Pagination APIs

[saescapa]

This PR introduces a comprehensive enhancement to the Drawer and Pagination components, adding three powerful new APIs that improve developer experience for multi-step drawer flows and eliminate prop drilling.

New Features

1. pageConfig API - Declarative Per-Page Configuration

Configure drawer properties on a per-page basis without conditional logic:

<Drawer
  pagination={pagination}
  pageConfig={{
    details: {
      title: 'View Details',
      bottomPanel: <Button onClick={() => pagination.open('edit')}>Edit</Button>,
    },
    edit: {
      title: 'Edit Information',
      bottomPanel: <Button onClick={() => pagination.open('confirm')}>Continue</Button>,
    },
    confirm: {
      title: 'Confirm Changes',
      bottomPanel: (
        <div style={{ display: 'flex', gap: '8px' }}>
          <Button onClick={handleConfirm}>Confirm</Button>
          <Button kind="secondary" onClick={() => pagination.back()}>Go Back</Button>
        </div>
      ),
    },
  }}
>
  <div key="details">...</div>
  <div key="edit">...</div>
  <div key="confirm">...</div>
</Drawer>

Benefits:

• ✅ Clean, declarative API
• ✅ Eliminates conditional logic in parent component
• ✅ Clear mapping between pages and their configurations
• ✅ Configure title, bottomPanel, and additionalActions per page

2. DrawerBottomPanelPortal - Content Injection Without Prop Drilling

Allow child components to control their own bottom panel content:

// Separate component file - no prop drilling needed!
const EditUserForm = () => {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const { close } = useDrawer();

  const handleSubmit = async () => {
    setIsSubmitting(true);
    await saveUser();
    close();
  };

  return (
    <>
      <div className="form-fields">
        <Input label="Name" />
        <Input label="Email" />
      </div>

      <DrawerBottomPanelPortal>
        <Button onClick={handleSubmit} loading={isSubmitting}>
          Save Changes
        </Button>
      </DrawerBottomPanelPortal>
    </>
  );
};

// In parent component
<Drawer pagination={pagination}>
  <div key="edit"><EditUserForm /></div>
  <div key="review"><ReviewForm /></div>
</Drawer>

Benefits:

• ✅ Co-locate bottom panel actions with page content
• ✅ Perfect for components defined in separate files
• ✅ Automatic page-active detection in paginated drawers
• ✅ Supports replace, append, prepend modes

3. Context Hooks - Access Drawer State Anywhere

New hooks for accessing drawer and pagination state without prop drilling:

// useDrawer() - Close drawer or check if it's open
const MyComponent = () => {
  const { close, isOpen } = useDrawer();
  return <Button onClick={close}>Done</Button>;
};

// usePaginationContext() - Navigate between pages
const FormStep = () => {
  const pagination = usePaginationContext();
  return <Button onClick={() => pagination.open('review')}>Next</Button>;
};

// useDrawerBottomPanel() - Imperative control (advanced)
const DynamicForm = () => {
  const { setBottomPanel } = useDrawerBottomPanel();
  useEffect(() => {
    if (isDirty) {
      setBottomPanel(<Button>Save Changes</Button>);
    } else {
      setBottomPanel(<Button>Close</Button>);
    }
  }, [isDirty]);
};

Implementation Details

How Page Active Tracking Works

// Drawer wraps each paginated child in DrawerPageProvider
<Transition show={isActive} unmount={false}>
  <DrawerPageProvider isActive={isActive}>
    {child}
  </DrawerPageProvider>
</Transition>

// Portal automatically detects if it's on the active page
const DrawerBottomPanelPortal = ({ children }) => {
  const isPageActive = useIsDrawerPageActive();

  useEffect(() => {
    if (isPageActive) {
      setPortalContent(children);
    }
    return () => setPortalContent(null);
  }, [isPageActive, children]);
};

closes ENG-1687

[changeset-bot]

🦋 Changeset detected

Latest commit: 9475919

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
paris	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
paris	Ready	Preview	Comment	Oct 6, 2025 4:30am