feat: [select, sidebar, drawer] forward positioner props, unify side

apps/www/src/content/docs/(overview)/upgrading.mdx

@@ -7,6 +7,43 @@ One section per release, newest first, with only the changes that need action
 from you. The full record of every release, features and fixes included, is
 on [GitHub releases](https://github.com/raystack/apsara/releases).
 
+## Unreleased: Sidebar and Drawer use one `side`
+
+`Sidebar` names its edge with `side`, as other components do. `Drawer` takes
+`side` on the root only.
+
+### 1. Rename Sidebar `position` to `side`
+
+| Before | After |
+|---|---|
+| `<Sidebar position="right">` | `<Sidebar side="right">` |
+| `[data-position="right"]` on the sidebar element | `[data-side="right"]` |
+| `useSidebar().position` | `useSidebar().side` |
+
+The `position` prop and `useSidebar().position` still work, and are
+deprecated. The `data-position` attribute is gone, so update CSS that selects
+it.
+
+### 2. Remove `side` from `Drawer.Content`
+
+`Drawer.Content` reads `side` from `Drawer`. Delete `side` from
+`Drawer.Content`, and set it on `Drawer`.
+
+```tsx
+// Before
+<Drawer side="left">
+  <Drawer.Content side="left">...</Drawer.Content>
+</Drawer>
+
+// After
+<Drawer side="left">
+  <Drawer.Content>...</Drawer.Content>
+</Drawer>
+```
+
+If only `Drawer.Content` had `side`, the drawer now slides in from the right,
+the default of `Drawer`.
+
 ## Unreleased: date filters compare whole days
 
 `DataView`, `DataTable` and `FilterChip` read and compare dates as calendar

apps/www/src/content/docs/components/drawer/demo.ts

@@ -4,10 +4,11 @@ import type { ComponentPropsType } from '@/components/demo/types';
 import { getPropsString } from '@/lib/utils';
 
 export const getCode = (props: ComponentPropsType) => {
+  const { side, ...contentProps } = props;
   return `
-    <Drawer${getPropsString(props)}>
+    <Drawer${getPropsString({ ...(side ? { side } : {}) })}>
       <Drawer.Trigger render={<Button />}>Drawer</Drawer.Trigger>
-      <Drawer.Content${getPropsString(props)}>
+      <Drawer.Content${getPropsString(contentProps)}>
         <Drawer.Header>
           <Drawer.Title>Drawer</Drawer.Title>
           <Drawer.Description>A simple drawer</Drawer.Description>
@@ -56,7 +57,7 @@ export const positionDemo = {
   <Flex gap={5}>
     <Drawer side="top">
       <Drawer.Trigger render={<Button />}>Top Drawer</Drawer.Trigger>
-      <Drawer.Content side="top">
+      <Drawer.Content>
         <Drawer.Header>
           <Drawer.Title>Top Drawer</Drawer.Title>
           <Drawer.Description>Slides in from the Top</Drawer.Description>
@@ -66,7 +67,7 @@ export const positionDemo = {
     </Drawer>
     <Drawer side="right">
       <Drawer.Trigger render={<Button />}>Right Drawer</Drawer.Trigger>
-      <Drawer.Content side="right">
+      <Drawer.Content>
         <Drawer.Header>
           <Drawer.Title>Right Drawer</Drawer.Title>
           <Drawer.Description>Slides in from the Right</Drawer.Description>
@@ -76,7 +77,7 @@ export const positionDemo = {
     </Drawer>
     <Drawer side="left">
       <Drawer.Trigger render={<Button />}>Left Drawer</Drawer.Trigger>
-      <Drawer.Content side="left">
+      <Drawer.Content>
         <Drawer.Header>
           <Drawer.Title>Left Drawer</Drawer.Title>
           <Drawer.Description>Slides in from the Left</Drawer.Description>
@@ -86,7 +87,7 @@ export const positionDemo = {
     </Drawer>
     <Drawer side="bottom">
       <Drawer.Trigger render={<Button />}>Bottom Drawer</Drawer.Trigger>
-      <Drawer.Content side="bottom">
+      <Drawer.Content>
         <Drawer.Header>
           <Drawer.Title>Bottom Drawer</Drawer.Title>
           <Drawer.Description>Slides in from the Bottom</Drawer.Description>

apps/www/src/content/docs/components/drawer/index.mdx

@@ -41,7 +41,7 @@ A drawer slides in from the edge named by `side` and traps focus while open.
 
 ### Positioning
 
-The Drawer can slide in from different sides of the screen. Swipe-to-dismiss is automatically configured based on the `side` prop.
+Set `side` on the root. `Drawer.Content` slides in from that edge, and swipe-to-dismiss follows it.
 
 <Demo data={positionDemo} />
 

apps/www/src/content/docs/components/drawer/props.ts

@@ -1,5 +1,8 @@
 export interface DrawerProps {
-  /** The direction from which the drawer appears and can be swiped to dismiss. */
+  /**
+   * The edge the drawer slides in from. It also sets the swipe-to-dismiss direction.
+   * @default "right"
+   */
   side?: 'top' | 'right' | 'bottom' | 'left';
 
   /** Boolean to control the default open state. */
@@ -28,9 +31,6 @@ export interface DrawerProps {
 }
 
 export interface DrawerContentProps {
-  /** The direction from which the drawer appears. */
-  side?: 'top' | 'right' | 'bottom' | 'left';
-
   /** Whether to show the close button. */
   showCloseButton?: boolean;
 

apps/www/src/content/docs/components/select/index.mdx

@@ -113,7 +113,7 @@ The button that triggers the Select.
 
 ### Content
 
-The container that holds the Select items.
+The container that holds the Select items. It passes the Base UI Positioner props, such as `collisionPadding` and `sticky`, to the positioner.
 
 <auto-type-table path="./props.ts" name="SelectContentProps" />
 

apps/www/src/content/docs/components/select/props.ts

@@ -79,6 +79,49 @@ export interface SelectContentProps {
    */
   sideOffset?: number;
 
+  /**
+   * Additional offset in pixels along the alignment axis.
+   * @default 0
+   */
+  alignOffset?: number;
+
+  /** Space in pixels to keep from the edge of the collision boundary. */
+  collisionPadding?: number;
+
+  /**
+   * The element or area that confines the content.
+   * @default "clipping-ancestors"
+   */
+  collisionBoundary?: Element | Element[] | 'clipping-ancestors';
+
+  /** How the content moves when it does not fit on the chosen side. */
+  collisionAvoidance?: {
+    side?: 'flip' | 'shift' | 'none';
+    align?: 'flip' | 'shift' | 'none';
+    fallbackAxisSide?: 'start' | 'end' | 'none';
+  };
+
+  /**
+   * Keeps the content in the viewport after the trigger scrolls out of view.
+   * @default false
+   */
+  sticky?: boolean;
+
+  /**
+   * The CSS `position` of the content.
+   * @default "absolute"
+   */
+  positionMethod?: 'absolute' | 'fixed';
+
+  /** An element to place the content against, in place of the trigger. */
+  anchor?: Element | React.RefObject<Element | null> | null;
+
+  /**
+   * Stops the content from following layout shifts of the anchor.
+   * @default false
+   */
+  disableAnchorTracking?: boolean;
+
   /** Additional CSS class names. */
   className?: string;
 

apps/www/src/content/docs/components/sidebar/demo.ts

@@ -66,13 +66,13 @@ export const preview = {
   style: styleDemo
 };
 
-export const positionDemo = {
+export const sideDemo = {
   type: 'code',
   tabs: [
     {
       name: 'Left',
       code: sidebarLayout(`
-      <Sidebar open={true} position="left">
+      <Sidebar open={true} side="left">
           <Sidebar.Header>
             <Flex align="center" gap={3} style={{padding:"var(--rs-space-2)"}}>
               <IconButton size={4} aria-label="Logo">
@@ -97,7 +97,7 @@ export const positionDemo = {
     {
       name: 'Right',
       code: sidebarLayoutRight(`
-      <Sidebar open={true} position="right">
+      <Sidebar open={true} side="right">
           <Sidebar.Header>
             <Flex align="center" gap={3} style={{padding:"var(--rs-space-2)"}}>
               <IconButton size={4} aria-label="Logo">

apps/www/src/content/docs/components/sidebar/index.mdx

@@ -6,7 +6,7 @@ source: packages/react/components/sidebar
 
 import {
   preview,
-  positionDemo,
+  sideDemo,
   variantDemo,
   collapsibleGroupDemo,
   controlledGroupDemo,
@@ -50,11 +50,11 @@ import { Sidebar } from "@raystack/apsara";
 
 Most of a sidebar's behaviour is about collapsing: what it looks like collapsed, who controls it, and how the user gets it back.
 
-### Position
+### Side
 
-`left` (the default) or `right`. Put it on the right only when the main content is the thing people arrive for and navigation is secondary.
+Set `side` to `left` (the default) or `right`. Put it on the right only when the main content is the thing people arrive for and navigation is secondary.
 
-<Demo data={positionDemo} />
+<Demo data={sideDemo} />
 
 ### Variants
 
@@ -266,7 +266,8 @@ It returns:
 - `open`: `true` when the sidebar is expanded
 - `setOpen(open)`: expand or collapse the sidebar
 - `collapsible`: mirrors the `collapsible` prop: `"icon"`, `"hidden"`, or `"none"` (`"none"` means it cannot be collapsed)
-- `position`: `"left"` or `"right"`
+- `side`: `"left"` or `"right"`
+- `position`: deprecated alias of `side`
 - `hideItemTooltips`: whether the tooltips the Sidebar adds to items are disabled
 
 ```tsx
@@ -313,7 +314,7 @@ The Sidebar implements the following accessibility features:
 
 - Truncation handling
   - Long item and group labels truncate with an ellipsis
-  - Items whose label is clipped show the full text in a tooltip on hover or focus (positioned away from the sidebar's edge based on `position`; disable with `hideItemTooltips`)
+  - Items whose label is clipped show the full text in a tooltip on hover or focus (positioned away from the sidebar's edge based on `side`; disable with `hideItemTooltips`)
 
 - Keyboard navigation support
 

apps/www/src/content/docs/components/sidebar/props.ts

@@ -39,9 +39,12 @@ export interface SidebarRootProps {
   /** Called when a hover peek starts or ends. */
   onPeekChange?: (isPeeking: boolean) => void;
 
-  /** Position of the Sidebar.
+  /** The edge of the layout the sidebar sits on.
    * @default "left"
    */
+  side?: 'left' | 'right';
+
+  /** @deprecated Use `side`. */
   position?: 'left' | 'right';
 
   /** Visual style variant of the Sidebar.

packages/react/components/drawer/__tests__/drawer.test.tsx

@@ -22,7 +22,7 @@ const BasicDrawer = ({
 } & Record<string, unknown>) => (
   <Drawer side={side} {...props}>
     <Drawer.Trigger render={<Button />}>{TRIGGER_TEXT}</Drawer.Trigger>
-    <Drawer.Content side={side} showCloseButton={showCloseButton}>
+    <Drawer.Content showCloseButton={showCloseButton}>
       <Drawer.Header>
         <Drawer.Title>{DRAWER_TITLE}</Drawer.Title>
         <Drawer.Description>{DRAWER_DESCRIPTION}</Drawer.Description>

packages/react/components/drawer/drawer-content.tsx

@@ -1,13 +1,14 @@
 'use client';
 
 import { Drawer as DrawerPrimitive } from '@base-ui/react/drawer';
-import { cva, cx, type VariantProps } from 'class-variance-authority';
+import { cva, cx } from 'class-variance-authority';
 import { ReactNode } from 'react';
 import { XIcon } from '~/icons';
 import { type Radius, radiusVariants } from '../../shared/radius';
 import { IconButton } from '../icon-button';
 import { useThemeInjection } from '../theme/portal';
 import styles from './drawer.module.css';
+import { useDrawerSide } from './drawer-root';
 
 const drawerPopup = cva(styles.drawerPopup, {
   variants: {
@@ -18,15 +19,11 @@ const drawerPopup = cva(styles.drawerPopup, {
       left: styles['drawerPopup-left'],
       right: styles['drawerPopup-right']
     }
-  },
-  defaultVariants: {
-    side: 'right'
   }
 });
 
 export interface DrawerContentProps
-  extends Omit<DrawerPrimitive.Popup.Props, 'children'>,
-    VariantProps<typeof drawerPopup> {
+  extends Omit<DrawerPrimitive.Popup.Props, 'children'> {
   showCloseButton?: boolean;
   overlayProps?: DrawerPrimitive.Backdrop.Props;
   children?: ReactNode;
@@ -42,7 +39,6 @@ export interface DrawerContentProps
 export function DrawerContent({
   className,
   children,
-  side = 'right',
   showCloseButton = true,
   overlayProps,
   'aria-label': ariaLabel,
@@ -51,6 +47,7 @@ export function DrawerContent({
   radius,
   ...props
 }: DrawerContentProps) {
+  const side = useDrawerSide();
   const resolvedAriaLabel =
     ariaLabel ?? (ariaLabelledBy ? undefined : 'Drawer');
   const theme = useThemeInjection();

packages/react/components/drawer/drawer-root.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import { Drawer as DrawerPrimitive } from '@base-ui/react/drawer';
+import { createContext, useContext } from 'react';
 
 type Side = 'top' | 'right' | 'bottom' | 'left';
 
@@ -14,8 +15,15 @@ const sideToSwipeDirection: Record<
   left: 'left'
 };
 
+const DrawerSideContext = createContext<Side>('right');
+
+export const useDrawerSide = () => useContext(DrawerSideContext);
+
 export interface DrawerRootProps extends DrawerPrimitive.Root.Props {
-  /** The direction from which the drawer appears and can be swiped to dismiss. */
+  /**
+   * The edge the drawer slides in from. It also sets the swipe-to-dismiss direction.
+   * @default 'right'
+   */
   side?: Side;
 }
 
@@ -25,10 +33,12 @@ export function DrawerRoot({
   ...props
 }: DrawerRootProps) {
   return (
-    <DrawerPrimitive.Root
-      swipeDirection={swipeDirection ?? sideToSwipeDirection[side]}
-      {...props}
-    />
+    <DrawerSideContext value={side}>
+      <DrawerPrimitive.Root
+        swipeDirection={swipeDirection ?? sideToSwipeDirection[side]}
+        {...props}
+      />
+    </DrawerSideContext>
   );
 }
 DrawerRoot.displayName = 'Drawer';

packages/react/components/select/__tests__/select.test.tsx

@@ -80,6 +80,30 @@ describe('Select', () => {
     });
   });
 
+  describe('Positioning', () => {
+    it.each([
+      false,
+      true
+    ])('forwards positioner props to the positioner (autocomplete: %s)', async autocomplete => {
+      render(
+        <Select autocomplete={autocomplete}>
+          <Select.Trigger>
+            <Select.Value placeholder={TRIGGER_TEXT} />
+          </Select.Trigger>
+          <Select.Content positionMethod='fixed'>
+            <Select.Item value='apple'>Apple</Select.Item>
+          </Select.Content>
+        </Select>
+      );
+      fireEvent.click(screen.getByLabelText('Select option'));
+      await flushMicrotasks();
+
+      expect(
+        document.querySelector('[data-slot="select-positioner"]')
+      ).toHaveStyle({ position: 'fixed' });
+    });
+  });
+
   describe('Single Selection', () => {
     it('displays selected value in trigger', async () => {
       render(<BasicSelect defaultValue='apple' />);