@astryxdesign/lab 0.1.9-canary.d2d84f8 → 0.1.9-canary.e00a241

package/src/BottomSheet/BottomSheet.test.tsx

@@ -0,0 +1,233 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheet.test.tsx
+ * @input Uses vitest, @testing-library/react, BottomSheet component
+ * @output Unit tests for BottomSheet component behavior
+ * @position Lab testing; validates BottomSheet.tsx implementation
+ *
+ * SYNC: When BottomSheet.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render, screen, fireEvent, act} from '@testing-library/react';
+import {useState} from 'react';
+import {BottomSheet} from './BottomSheet';
+
+// jsdom doesn't implement <dialog> open/close or pointer capture; stub them.
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  if (!Element.prototype.setPointerCapture) {
+    Element.prototype.setPointerCapture = vi.fn();
+    Element.prototype.releasePointerCapture = vi.fn();
+  }
+
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockReturnValue({
+      matches: false,
+      media: '',
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }),
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function getHandle(): HTMLElement {
+  const handle = document.querySelector<HTMLElement>(
+    '[data-astryx-sheet-handle]',
+  );
+  if (!handle) {
+    throw new Error('grab handle not found');
+  }
+  return handle;
+}
+
+// Drive a pointer drag on the grab handle. jsdom PointerEvents don't carry
+// clientY, so dispatch plain events with the coords the handlers read.
+function drag(handle: HTMLElement, points: Array<{y: number}>) {
+  const [down, ...rest] = points;
+  fireEvent.pointerDown(handle, {pointerId: 1, clientY: down.y});
+  for (const p of rest) {
+    fireEvent.pointerMove(handle, {pointerId: 1, clientY: p.y});
+  }
+  const last = points[points.length - 1];
+  fireEvent.pointerUp(handle, {pointerId: 1, clientY: last.y});
+}
+
+describe('BottomSheet', () => {
+  it('renders children when open and applies the accessible label', () => {
+    render(
+      <BottomSheet isOpen onOpenChange={() => {}} label="Filters">
+        Sheet content
+      </BottomSheet>,
+    );
+    const dialog = screen.getByRole('dialog');
+    expect(dialog).toBeInTheDocument();
+    expect(dialog).toHaveAccessibleName('Filters');
+    expect(screen.getByText('Sheet content')).toBeInTheDocument();
+  });
+
+  it('does not show when isOpen is false', () => {
+    render(
+      <BottomSheet isOpen={false} onOpenChange={() => {}} label="Filters">
+        Hidden
+      </BottomSheet>,
+    );
+    expect(HTMLDialogElement.prototype.showModal).not.toHaveBeenCalled();
+  });
+
+  it('opens modally (showModal + aria-modal)', () => {
+    render(
+      <BottomSheet isOpen onOpenChange={() => {}} label="Filters">
+        Content
+      </BottomSheet>,
+    );
+    expect(HTMLDialogElement.prototype.showModal).toHaveBeenCalled();
+    expect(screen.getByRole('dialog')).toHaveAttribute('aria-modal', 'true');
+  });
+
+  it('requests close on Escape', () => {
+    const onOpenChange = vi.fn();
+    render(
+      <BottomSheet isOpen onOpenChange={onOpenChange} label="Filters">
+        Content
+      </BottomSheet>,
+    );
+    fireEvent.keyDown(screen.getByRole('dialog'), {key: 'Escape'});
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it('requests close when the scrim (dialog element itself) is clicked', () => {
+    const onOpenChange = vi.fn();
+    render(
+      <BottomSheet isOpen onOpenChange={onOpenChange} label="Filters">
+        Content
+      </BottomSheet>,
+    );
+    fireEvent.click(screen.getByRole('dialog'));
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  describe('grab handle', () => {
+    it('renders a decorative handle hidden from assistive tech', () => {
+      render(
+        <BottomSheet isOpen onOpenChange={() => {}} label="Filters">
+          Content
+        </BottomSheet>,
+      );
+      const handle = getHandle();
+      expect(handle).toHaveAttribute('aria-hidden', 'true');
+    });
+  });
+
+  describe('swipe to dismiss', () => {
+    it('requests close when dragged past the dismiss threshold', () => {
+      const onOpenChange = vi.fn();
+      render(
+        <BottomSheet isOpen onOpenChange={onOpenChange} label="Filters">
+          Content
+        </BottomSheet>,
+      );
+      // No measured height in jsdom (0) -> any downward drag dismisses via
+      // the distance branch (offset > 0.25) once released downward.
+      drag(getHandle(), [{y: 0}, {y: 40}, {y: 120}]);
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+  });
+
+  describe('height', () => {
+    it('renders for each named height without error', () => {
+      for (const height of ['short', 'medium', 'tall', 'auto'] as const) {
+        const {unmount} = render(
+          <BottomSheet
+            isOpen
+            onOpenChange={() => {}}
+            label="Filters"
+            height={height}>
+            Content
+          </BottomSheet>,
+        );
+        expect(screen.getByRole('dialog')).toBeInTheDocument();
+        unmount();
+      }
+    });
+  });
+
+  describe('focus restore', () => {
+    function Harness() {
+      const [isOpen, setIsOpen] = useState(false);
+      return (
+        <>
+          <button type="button" onClick={() => setIsOpen(true)}>
+            Open sheet
+          </button>
+          <BottomSheet isOpen={isOpen} onOpenChange={setIsOpen} label="Filters">
+            <button type="button" onClick={() => setIsOpen(false)}>
+              Done
+            </button>
+          </BottomSheet>
+        </>
+      );
+    }
+
+    it('restores focus to the opener after close', async () => {
+      vi.useFakeTimers();
+      try {
+        render(<Harness />);
+        const opener = screen.getByRole('button', {name: 'Open sheet'});
+        opener.focus();
+        fireEvent.click(opener);
+        fireEvent.click(screen.getByRole('button', {name: 'Done'}));
+        await act(async () => {
+          vi.runAllTimers();
+        });
+        expect(document.activeElement).toBe(opener);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+  });
+
+  describe('reduced motion', () => {
+    it('opens without throwing when prefers-reduced-motion is set', () => {
+      vi.stubGlobal(
+        'matchMedia',
+        vi.fn().mockReturnValue({
+          matches: true,
+          media: '(prefers-reduced-motion: reduce)',
+          onchange: null,
+          addEventListener: vi.fn(),
+          removeEventListener: vi.fn(),
+          addListener: vi.fn(),
+          removeListener: vi.fn(),
+          dispatchEvent: vi.fn(),
+        }),
+      );
+      render(
+        <BottomSheet isOpen onOpenChange={() => {}} label="Filters">
+          Content
+        </BottomSheet>,
+      );
+      expect(screen.getByRole('dialog')).toBeInTheDocument();
+    });
+  });
+});

package/src/BottomSheet/BottomSheet.tsx

@@ -0,0 +1,226 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheet.tsx
+ * @input Uses React, StyleX, theme tokens, Drawer, useSheetGestures, themeProps
+ * @output Exports BottomSheet component and BottomSheetProps
+ * @position Lab implementation; consumed by index.ts, tested by BottomSheet.test.tsx, demonstrated in Storybook
+ *
+ * A mobile touch surface that rises from the bottom edge with a grab handle
+ * and swipe-to-dismiss. Built ON TOP OF the lab Drawer's native `<dialog>`
+ * engine (`side="bottom"`) rather than forking it — Drawer owns
+ * showModal/show, the open/close slide animation, focus trap + restore,
+ * scroll lock, the Escape/scrim contract, and the LIFO overlay registry.
+ * BottomSheet layers the grab handle and the drag-to-dismiss gesture on top,
+ * inside the dialog.
+ *
+ * The gesture translate is applied to an inner sheet wrapper, not the
+ * `<dialog>` itself, so Drawer owns the open/close slide and the drag
+ * translates within it without the two transforms fighting.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/BottomSheet/BottomSheet.doc.mjs (props table, features, usage)
+ * - /packages/lab/src/BottomSheet/BottomSheet.test.tsx (tests for new/changed behavior)
+ * - /packages/lab/src/BottomSheet/index.ts (exports if types change)
+ * - /apps/storybook/stories/BottomSheet.stories.tsx (examples and visual coverage)
+ */
+
+import {type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '@astryxdesign/core';
+import {
+  colorVars,
+  radiusVars,
+  spacingVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+import {mergeProps, themeProps} from '@astryxdesign/core/utils';
+import {Drawer} from '../Drawer';
+import {useSheetGestures} from './useSheetGestures';
+
+/**
+ * Height budget for each named size. `medium`/`tall` track the viewport so
+ * the sheet scales with the device; `short` is a fixed peek height. `auto`
+ * is handled separately (fits content, capped at the `tall` budget).
+ */
+const HEIGHT_BUDGETS = {
+  short: '240px',
+  medium: '50dvh',
+  tall: '90dvh',
+  auto: '90dvh',
+} as const;
+
+export type BottomSheetHeight = keyof typeof HEIGHT_BUDGETS;
+
+// Sheets on wide touch devices (tablets) shouldn't stretch edge to edge;
+// cap and center them. Matches the `sm` layout breakpoint. On phones the
+// viewport is narrower than this, so the sheet stays full-width.
+const MAX_SHEET_WIDTH = 640;
+
+const styles = stylex.create({
+  // Inner wrapper that carries the live drag translate AND the visible sheet
+  // surface (background, rounded top, width cap). The translate must live on
+  // the painted surface — not the <dialog> — so the whole sheet follows the
+  // swipe instead of the content sliding out of a fixed white panel. Drawer
+  // owns the open/close slide on the <dialog>; this wrapper adds the gesture
+  // offset within it so the two transforms don't fight. Safe-area padding
+  // clears the home indicator on notched devices.
+  sheet: {
+    display: 'flex',
+    flexDirection: 'column',
+    minHeight: 0,
+    height: '100%',
+    width: '100%',
+    maxWidth: MAX_SHEET_WIDTH,
+    marginInline: 'auto',
+    backgroundColor: colorVars['--color-background-surface'],
+    borderStartStartRadius: radiusVars['--radius-page'],
+    borderStartEndRadius: radiusVars['--radius-page'],
+    overflow: 'hidden',
+    paddingBlockEnd: `env(safe-area-inset-bottom, 0px)`,
+    willChange: 'transform',
+  },
+  // Neutralize Drawer's <dialog> surface so only the swipeable wrapper paints.
+  // Without this the dialog's white background + shadow stay fixed while the
+  // wrapper slides, leaving a static panel behind the drag. The scrim behind
+  // the sheet provides the depth separation a shadow would.
+  dialogSurface: {
+    backgroundColor: 'transparent',
+    boxShadow: 'none',
+    borderBlockStartWidth: 0,
+  },
+  handleBar: {
+    flexShrink: 0,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingBlock: spacingVars['--spacing-2'],
+    touchAction: 'none',
+    cursor: 'grab',
+  },
+  handlePill: {
+    width: 36,
+    height: 4,
+    borderRadius: radiusVars['--radius-full'],
+    backgroundColor: colorVars['--color-border'],
+  },
+  body: {
+    flexGrow: 1,
+    minHeight: 0,
+    overflowY: 'auto',
+    overscrollBehavior: 'contain',
+  },
+  // `auto` fits content instead of filling the height budget; the budget
+  // becomes an upper bound. Applied to the <dialog> (overrides Drawer's
+  // block-size treatment, which is applied earlier in the props chain).
+  autoHeight: {
+    height: 'fit-content',
+    maxHeight: HEIGHT_BUDGETS.auto,
+  },
+});
+export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
+  /** Ref forwarded to the underlying <dialog> element. */
+  ref?: React.Ref<HTMLDialogElement>;
+
+  /** Whether the sheet is open. Fully controlled — pair with `onOpenChange`. */
+  isOpen: boolean;
+
+  /**
+   * Called when the sheet opens or closes. The boolean is the requested
+   * next state (`false` on Escape, scrim click, or a swipe past the dismiss
+   * threshold). The caller owns the open state.
+   */
+  onOpenChange: (isOpen: boolean) => void;
+
+  /**
+   * Accessible label for the sheet (required — the sheet has no built-in
+   * heading to derive a name from).
+   */
+  label: string;
+
+  /** Sheet content, rendered below the grab handle in a scrollable area. */
+  children: ReactNode;
+
+  /**
+   * How tall the sheet is:
+   * - `'short'` — a fixed peek height
+   * - `'medium'` — half the viewport
+   * - `'tall'` — nearly the full viewport
+   * - `'auto'` — fits its content, capped at the `'tall'` budget
+   *
+   * On viewports shorter than the budget the sheet fills the available
+   * height.
+   * @default 'medium'
+   */
+  height?: BottomSheetHeight;
+
+  /** Test ID for the root element. */
+  'data-testid'?: string;
+}
+
+/**
+ * A mobile touch sheet that rises from the bottom edge, with a grab handle
+ * and swipe-to-dismiss. Built on the lab Drawer's `<dialog>` engine
+ * (`side="bottom"`): Drawer owns the open/close slide, focus trap + restore,
+ * scroll lock, and the Escape/scrim contract, while BottomSheet layers the
+ * grab handle and drag-to-dismiss on top.
+ *
+ * @example
+ * ```
+ * const [isOpen, setIsOpen] = useState(false);
+ * <BottomSheet
+ *   isOpen={isOpen}
+ *   onOpenChange={setIsOpen}
+ *   label="Filters">
+ *   <FilterControls />
+ * </BottomSheet>
+ * ```
+ */
+export function BottomSheet({
+  isOpen,
+  onOpenChange,
+  label,
+  children,
+  height = 'medium',
+  xstyle,
+  ...props
+}: BottomSheetProps) {
+  const close = () => onOpenChange(false);
+  const {contentProps, handleProps} = useSheetGestures({
+    isOpen,
+    onDismiss: close,
+  });
+
+  return (
+    <Drawer
+      isOpen={isOpen}
+      onClose={close}
+      side="bottom"
+      size={HEIGHT_BUDGETS[height]}
+      label={label}
+      hasScrim
+      hasCloseButton={false}
+      xstyle={[styles.dialogSurface, height === 'auto' && styles.autoHeight]}
+      {...props}>
+      <div
+        data-astryx-sheet=""
+        {...mergeProps(
+          themeProps('bottom-sheet'),
+          stylex.props(styles.sheet, xstyle),
+          contentProps.style,
+        )}>
+        <div
+          data-astryx-sheet-handle=""
+          {...stylex.props(styles.handleBar)}
+          {...handleProps}
+          aria-hidden="true">
+          <div {...stylex.props(styles.handlePill)} />
+        </div>
+        <div {...stylex.props(styles.body)}>{children}</div>
+      </div>
+    </Drawer>
+  );
+}
+
+BottomSheet.displayName = 'BottomSheet';

package/src/BottomSheet/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input BottomSheet.tsx
+ * @output Re-exports BottomSheet component and BottomSheetProps type
+ * @position Lab entry point for the BottomSheet directory
+ */
+
+export {BottomSheet} from './BottomSheet';
+export type {BottomSheetProps} from './BottomSheet';

package/src/BottomSheet/useSheetGestures.doc.mjs

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../core/src/docs-types').HookDoc} */
+export const docs = {
+  name: 'useSheetGestures',
+  displayName: 'useSheetGestures',
+  keywords: ['sheet', 'drag', 'swipe', 'dismiss', 'gesture', 'pointer', 'touch', 'bottom sheet'],
+  params: [
+    {
+      name: 'options',
+      type: 'UseSheetGesturesOptions',
+      description: 'isOpen and onDismiss. Internal to BottomSheet; not exported from the lab entry point.',
+      required: true,
+    },
+  ],
+  returns: [
+    {
+      name: 'result',
+      type: 'UseSheetGesturesResult',
+      description: 'contentProps (spread on the sliding surface for the live translate + touch-action guard), handleProps (spread on the grab handle for the pointer drag), plus dragOffset and isDragging for callers that want to drive their own animation.',
+    },
+  ],
+  usage: {
+    description:
+      'Drag-to-dismiss machinery for the bottom sheet. Tracks a pointer drag down the block axis, translates the sliding surface live, and on release either dismisses (past a distance or velocity threshold) or springs back to fully open. Pointer-events based (one path for mouse + touch), SSR-safe, and respects prefers-reduced-motion. Escape (routed by the owning dialog) provides the keyboard equivalent of the swipe.',
+    bestPractices: [
+      { guidance: true, description: 'Spread handleProps on the grab-handle element and contentProps on the sliding surface (the panel that carries the translate).' },
+      { guidance: false, description: 'Wire onDismiss to anything other than the owning sheet close; it fires when a swipe crosses the dismiss threshold.' },
+    ],
+  },
+};

package/src/BottomSheet/useSheetGestures.test.ts

@@ -0,0 +1,160 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useSheetGestures.test.ts
+ * @input Uses vitest, @testing-library/react renderHook, useSheetGestures
+ * @output Unit tests for useSheetGestures behavior
+ * @position Testing; validates useSheetGestures.ts implementation
+ *
+ * SYNC: When useSheetGestures.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {act, renderHook} from '@testing-library/react';
+import {
+  useSheetGestures,
+  type UseSheetGesturesOptions,
+} from './useSheetGestures';
+
+const SHEET_HEIGHT = 400;
+
+// A fake pointer event object good enough for the handlers, which only read
+// pointerId, clientY, timeStamp, and currentTarget's capture + measure APIs.
+function pointerEvent(
+  clientY: number,
+  timeStamp: number,
+  target: HTMLElement,
+  pointerId = 1,
+) {
+  return {
+    pointerId,
+    clientY,
+    timeStamp,
+    currentTarget: target,
+  } as unknown as React.PointerEvent;
+}
+
+function makeTarget(): HTMLElement {
+  const el = document.createElement('div');
+  el.setAttribute('data-astryx-sheet', '');
+  el.setPointerCapture = vi.fn();
+  el.releasePointerCapture = vi.fn();
+  el.getBoundingClientRect = () => ({height: SHEET_HEIGHT}) as DOMRect;
+  return el;
+}
+
+beforeEach(() => {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockReturnValue({
+      matches: false,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    }),
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function setup(options: Partial<UseSheetGesturesOptions> = {}) {
+  const onDismiss = vi.fn();
+  const hook = renderHook(
+    (props: UseSheetGesturesOptions) => useSheetGestures(props),
+    {
+      initialProps: {
+        isOpen: true,
+        onDismiss,
+        ...options,
+      } as UseSheetGesturesOptions,
+    },
+  );
+  return {hook, onDismiss};
+}
+
+describe('useSheetGestures', () => {
+  it('dismisses when dragged past the distance threshold (slow drag)', () => {
+    const {hook, onDismiss} = setup();
+    const target = makeTarget();
+    const {handleProps} = hook.result.current;
+    act(() => {
+      handleProps.onPointerDown(pointerEvent(0, 0, target));
+    });
+    // Drag down slowly, well past 25% of 400px, low velocity.
+    act(() => {
+      handleProps.onPointerMove(pointerEvent(60, 200, target));
+      handleProps.onPointerMove(pointerEvent(140, 600, target));
+    });
+    act(() => {
+      handleProps.onPointerUp(pointerEvent(140, 620, target));
+    });
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it('dismisses on a fast flick even below the distance threshold', () => {
+    const {hook, onDismiss} = setup();
+    const target = makeTarget();
+    const {handleProps} = hook.result.current;
+    act(() => {
+      handleProps.onPointerDown(pointerEvent(0, 0, target));
+    });
+    // Small distance (30px < 100px) but very fast (30px / 10ms = 3px/ms).
+    act(() => {
+      handleProps.onPointerMove(pointerEvent(30, 10, target));
+    });
+    act(() => {
+      handleProps.onPointerUp(pointerEvent(30, 12, target));
+    });
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it('springs back (no dismiss) below the threshold', () => {
+    const {hook, onDismiss} = setup();
+    const target = makeTarget();
+    const {handleProps} = hook.result.current;
+    act(() => {
+      handleProps.onPointerDown(pointerEvent(0, 0, target));
+    });
+    act(() => {
+      handleProps.onPointerMove(pointerEvent(20, 300, target));
+    });
+    act(() => {
+      handleProps.onPointerUp(pointerEvent(20, 620, target));
+    });
+    expect(onDismiss).not.toHaveBeenCalled();
+    expect(hook.result.current.dragOffset).toBe(0);
+    expect(hook.result.current.isDragging).toBe(false);
+  });
+
+  it('translates the surface live during a drag', () => {
+    const {hook} = setup();
+    const target = makeTarget();
+    const {handleProps} = hook.result.current;
+    act(() => {
+      handleProps.onPointerDown(pointerEvent(0, 0, target));
+    });
+    act(() => {
+      handleProps.onPointerMove(pointerEvent(50, 100, target));
+    });
+    expect(hook.result.current.dragOffset).toBe(50);
+    expect(hook.result.current.isDragging).toBe(true);
+    expect(hook.result.current.contentProps.style.transform).toBe(
+      'translateY(50px)',
+    );
+  });
+
+  it('ignores upward drag past the fully-open position', () => {
+    const {hook} = setup();
+    const target = makeTarget();
+    const {handleProps} = hook.result.current;
+    act(() => {
+      handleProps.onPointerDown(pointerEvent(100, 0, target));
+    });
+    // Drag UP (clientY decreasing) — no rubber-band overscroll.
+    act(() => {
+      handleProps.onPointerMove(pointerEvent(20, 100, target));
+    });
+    expect(hook.result.current.dragOffset).toBe(0);
+  });
+});