@astryxdesign/core 0.4.4 → 0.4.5-canary.1fdecb1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.4.4",
+  "version": "0.4.5-canary.1fdecb1",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -656,6 +656,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/cli": "0.4.5-canary.1fdecb1",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",
@@ -664,8 +665,7 @@
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
-    "rimraf": "^6.0.1",
-    "@astryxdesign/cli": "0.4.4"
+    "rimraf": "^6.0.1"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/BottomSheet/BottomSheet.doc.mjs

@@ -13,6 +13,9 @@ export const docs = {
     'touch',
     'drag',
     'swipe',
+    'snap point',
+    'detent',
+    'resize',
     'dismiss',
     'grab handle',
     'dialog',
@@ -54,7 +57,7 @@ export const docs = {
     targets: [{className: 'astryx-bottom-sheet', visualProps: []}],
   },
   description:
-    "A mobile touch sheet that rises from the bottom edge, with animated entrance and exit, a grab handle, drag-to-resize snap points, and purpose-controlled dismissal. A standalone sheet owns a native <dialog>; inside BottomSheetSwitcher it renders a panel in the switcher's shared dialog. In both modes, ref and shared DOM props target the visual panel <div>.",
+    "A mobile touch sheet that rises from the bottom edge, with animated entrance and exit, a grab handle, optional drag-to-resize snap points, and purpose-controlled dismissal. A standalone sheet owns a native <dialog>; inside BottomSheetSwitcher it renders a panel in the switcher's shared dialog. In both modes, ref and shared DOM props target the visual panel <div>.",
   props: [
     {
       name: 'isOpen',
@@ -99,9 +102,15 @@ export const docs = {
       name: 'height',
       type: "'hug' | 'capped' | 'tall' | number | string",
       description:
-        "How tall the sheet is. Named budgets: 'hug' fits its content up to 92% of the viewport, 'capped' is a scrolling mid-height panel (~62%), and 'tall' is a pinned near-full panel (~92%) for content that streams in. Or pass a number (px) / CSS length for a custom budget. The user can drag between snap points regardless. On shorter viewports the sheet fills the available height. Only a fully expanded 'tall' sheet provides mobile-keyboard accommodation: it stays put and scrolls each focused control above the keyboard. Hug, Capped, numeric and CSS-length heights never do, and a Tall sheet stops doing it the moment the user drags it to a shorter detent — resuming when they drag it back. Outside that state the sheet neither moves nor adds keyboard scroll space, and the browser's own focus reveal is left in place; on iOS that reveal can shift the whole page.",
+        "How tall the sheet is. Named budgets: 'hug' fits its content up to 92% of the viewport, 'capped' is a scrolling mid-height panel (~62%), and 'tall' is a pinned near-full panel (~92%) for content that streams in. Or pass a number (px) / CSS length for a custom budget. Give snapPoints to let the user drag between heights. On shorter viewports the sheet fills the available height. Only a fully expanded 'tall' sheet provides mobile-keyboard accommodation: it stays put and scrolls each focused control above the keyboard. Hug, Capped, numeric and CSS-length heights never do, and a Tall sheet stops doing it the moment the user drags it to a shorter detent — resuming when they drag it back. Outside that state the sheet neither moves nor adds keyboard scroll space, and the browser's own focus reveal is left in place; on iOS that reveal can shift the whole page.",
       default: "'capped'",
     },
+    {
+      name: 'snapPoints',
+      type: 'ReadonlyArray<number | string>',
+      description:
+        "Extra heights the sheet can rest at when dragged; its own height is always the tallest stop, and omitting this gives a sheet that only opens and closes. Each stop is the sheet's visible height: a number is a viewport fraction (0.5 is half the screen), '50%' the same in CSS, '320px' an absolute length. A stop of a quarter of the sheet or less is a peek — it slides away instead of reflowing, and thins the scrim.",
+    },
     {
       name: 'hasScrim',
       type: 'boolean',
@@ -156,6 +165,30 @@ export const docs = {
   label="Nearby places"
   height="tall">
   <PlaceList />
+</BottomSheet>`,
+    },
+    {
+      label: 'Collapsible to half the screen',
+      code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  label="Nearby places"
+  height="tall"
+  snapPoints={[0.5]}>
+  <PlaceList />
+</BottomSheet>`,
+    },
+    {
+      label: 'A peek, a working height, and full',
+      code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  label="Route"
+  height="tall"
+  snapPoints={['96px', '50%']}>
+  <RouteDetails />
 </BottomSheet>`,
     },
     {
@@ -236,7 +269,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
-    'mobile touch sheet rising from the bottom edge (native <dialog>): grab handle, transform-based drag-to-resize snap points, scrolling area resizes to the snapped visible height on release (the peek detent keeps the full height and slides instead), Dialog-aligned dismissal purpose (info/form/required), purpose-gated swipe-to-dismiss, fully-expanded Tall visual-viewport mobile-keyboard handling, named height scale, modal (default) or non-modal (hasScrim={false}) presentation',
+    'mobile touch sheet rising from the bottom edge (native <dialog>): grab handle, opt-in transform-based drag-to-resize snap points (snapPoints: viewport fraction, percent or px length), scrolling area resizes to the snapped visible height on release (a peek stop — a quarter of the sheet or less — keeps the full height and slides instead), Dialog-aligned dismissal purpose (info/form/required), purpose-gated swipe-to-dismiss, fully-expanded Tall visual-viewport mobile-keyboard handling, named height scale, modal (default) or non-modal (hasScrim={false}) presentation',
   usage: {
     description:
       'Mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport; use BottomSheetSwitcher for multi-step flows.',

package/src/BottomSheet/BottomSheet.test.tsx

@@ -15,6 +15,12 @@ import {createRef, useState} from 'react';
 import {BottomSheet} from './BottomSheet';
 import {BottomSheetSwitcher} from './BottomSheetSwitcher';
 
+// A sheet has no stops unless its host asks for them, so the tests that
+// exercise detents pass their own. These three — a 14% peek, a half-height
+// stop, and a 92% stop the Tall budget already covers — are the geometry the
+// height assertions below are written against.
+const SNAP_POINTS: ReadonlyArray<number> = [0.14, 0.5, 0.92];
+
 // jsdom doesn't implement <dialog> open/close or pointer capture; stub them.
 beforeEach(() => {
   HTMLDialogElement.prototype.showModal = vi.fn(function (
@@ -178,13 +184,20 @@ function finishSheetExit() {
   fireEvent.transitionEnd(getSheet(), {propertyName: 'transform'});
 }
 
-function ExitHarness({hasScrim}: {hasScrim?: boolean}) {
+function ExitHarness({
+  hasScrim,
+  snapPoints,
+}: {
+  hasScrim?: boolean;
+  snapPoints?: ReadonlyArray<number>;
+}) {
   const [isOpen, setIsOpen] = useState(true);
   return (
     <BottomSheet
       isOpen={isOpen}
       onOpenChange={setIsOpen}
       label="Filters"
+      snapPoints={snapPoints}
       hasScrim={hasScrim}>
       <button type="button" onClick={() => setIsOpen(false)}>
         Close sheet
@@ -616,6 +629,7 @@ describe('BottomSheet', () => {
           isOpen
           onOpenChange={() => {}}
           label="Release notes"
+          snapPoints={SNAP_POINTS}
           height="tall">
           Content
         </BottomSheet>,
@@ -667,6 +681,7 @@ describe('BottomSheet', () => {
           isOpen
           onOpenChange={() => {}}
           label="Release notes"
+          snapPoints={SNAP_POINTS}
           height="tall">
           Content
         </BottomSheet>,
@@ -720,6 +735,7 @@ describe('BottomSheet', () => {
           isOpen
           onOpenChange={() => {}}
           label="Release notes"
+          snapPoints={SNAP_POINTS}
           height="tall">
           Content
         </BottomSheet>,
@@ -797,6 +813,7 @@ describe('BottomSheet', () => {
           isOpen
           onOpenChange={() => {}}
           label="Release notes"
+          snapPoints={SNAP_POINTS}
           height="tall"
           style={{transition: 'none'}}>
           Content
@@ -830,6 +847,7 @@ describe('BottomSheet', () => {
           isOpen
           onOpenChange={() => {}}
           label="Release notes"
+          snapPoints={SNAP_POINTS}
           height="tall">
           Content
         </BottomSheet>,
@@ -890,7 +908,7 @@ describe('BottomSheet', () => {
       const observers = mockResizeObserverInstances();
       mockVisualViewport(800);
       mockWindowHeight(800);
-      render(<ExitHarness />);
+      render(<ExitHarness snapPoints={SNAP_POINTS} />);
       const sheet = getSheet();
       const sheetObserver = observers.find(instance =>
         instance.observed.has(sheet),
@@ -936,6 +954,7 @@ describe('BottomSheet', () => {
           isOpen
           onOpenChange={() => {}}
           label="Release notes"
+          snapPoints={SNAP_POINTS}
           height="tall">
           Content
         </BottomSheet>,
@@ -1000,6 +1019,7 @@ describe('BottomSheet', () => {
           isOpen
           onOpenChange={() => {}}
           label="Release notes"
+          snapPoints={SNAP_POINTS}
           height="tall">
           Content
         </BottomSheet>,
@@ -1039,6 +1059,136 @@ describe('BottomSheet', () => {
     });
   });
 
+  describe('snapPoints', () => {
+    // A Tall sheet in an 800px window: a 784px border box, 48px of which is
+    // the reserve below the fold, so 736px of it is visible.
+    function renderTallSheet(
+      snapPoints?: ReadonlyArray<number | string>,
+      onOpenChange: (isOpen: boolean) => void = () => {},
+    ) {
+      const observers = mockResizeObserverInstances();
+      mockVisualViewport(800);
+      mockWindowHeight(800);
+      const view = render(
+        <BottomSheet
+          isOpen
+          onOpenChange={onOpenChange}
+          label="Release notes"
+          snapPoints={snapPoints}
+          height="tall">
+          Content
+        </BottomSheet>,
+      );
+      const sheet = getSheet();
+      const sheetObserver = observers.find(instance =>
+        instance.observed.has(sheet),
+      );
+      act(() => {
+        sheetObserver?.callback(
+          [resizeEntry(784, 736)],
+          sheetObserver as unknown as ResizeObserver,
+        );
+      });
+      return {sheet, view};
+    }
+
+    function dragHandleTo(y: number) {
+      fireTimedPointer(getHandle(), 'pointerdown', {time: 0, y: 0});
+      fireTimedPointer(getHandle(), 'pointermove', {time: 1000, y});
+      fireTimedPointer(getHandle(), 'pointerup', {time: 2000, y});
+      fireEvent.transitionEnd(getSheet(), {propertyName: 'transform'});
+    }
+
+    it('has no stops of its own, so a released drag springs back', () => {
+      const onOpenChange = vi.fn();
+      const {sheet} = renderTallSheet(undefined, onOpenChange);
+
+      // 200px down is well short of the dismiss threshold, and there is no
+      // stop to catch it, so the sheet returns to fully open.
+      dragHandleTo(200);
+
+      expect(sheet.style.transform).toBe('');
+      expect(sheet.style.height).toBe('');
+      expect(onOpenChange).not.toHaveBeenCalled();
+    });
+
+    it('rests at a stop given as a fraction of the viewport', () => {
+      const {sheet} = renderTallSheet([0.5]);
+
+      // Half of the 800px window is 400px of visible sheet: 736 - 400 = 336px
+      // of travel, taken as layout height once the snap lands.
+      dragHandleTo(336);
+
+      expect(sheet.style.height).toBe('448px');
+      expect(sheet.style.transform).toBe('');
+    });
+
+    it('reads a percentage as the same stop as the fraction', () => {
+      const {sheet} = renderTallSheet(['50%']);
+      dragHandleTo(336);
+      expect(sheet.style.height).toBe('448px');
+    });
+
+    it('rests at a stop given as an absolute px length', () => {
+      const {sheet} = renderTallSheet(['320px']);
+
+      // A 320px stop sits 736 - 320 = 416px down, whatever the window does.
+      dragHandleTo(416);
+
+      expect(sheet.style.height).toBe('368px');
+      expect(sheet.style.transform).toBe('');
+    });
+
+    it('re-anchors to the same stop when the points change under a resting sheet', () => {
+      const {sheet, view} = renderTallSheet([0.5]);
+      dragHandleTo(336);
+      expect(sheet.style.height).toBe('448px');
+
+      // Without an inline height the sheet renders its natural 92dvh budget.
+      vi.spyOn(sheet, 'getBoundingClientRect').mockImplementation(() =>
+        rect({
+          top: 0,
+          bottom: sheet.style.height
+            ? Number.parseFloat(sheet.style.height)
+            : 784,
+        }),
+      );
+
+      // The host moves its one stop from half the window to a quarter of it.
+      // The sheet is resting on that stop, so it follows — no gesture, and
+      // nothing to animate.
+      view.rerender(
+        <BottomSheet
+          isOpen
+          onOpenChange={() => {}}
+          label="Release notes"
+          snapPoints={[0.25]}
+          height="tall">
+          Content
+        </BottomSheet>,
+      );
+
+      // 200px of visible sheet is 736 - 200 = 536px of travel.
+      expect(sheet.style.height).toBe('248px');
+      expect(sheet.style.transform).toBe('');
+    });
+
+    it('ignores a stop it cannot resolve, and warns which one', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      // 200 is the px mistake: a bare number is a fraction, never a length.
+      const {sheet} = renderTallSheet([0.5, 200]);
+
+      expect(
+        warn.mock.calls.some(args => String(args[0]).includes('200')),
+      ).toBe(true);
+
+      // The stop it could read still works.
+      dragHandleTo(336);
+      expect(sheet.style.height).toBe('448px');
+      warn.mockRestore();
+    });
+  });
+
   describe('mobile keyboard', () => {
     it('claims a transition between fields and delivers it with preventScroll', () => {
       mockIOSWebKit();
@@ -1293,6 +1443,7 @@ describe('BottomSheet', () => {
           isOpen
           onOpenChange={() => {}}
           label="Add a comment"
+          snapPoints={SNAP_POINTS}
           height="tall">
           <input aria-label="Comment" />
         </BottomSheet>,
@@ -2111,4 +2262,28 @@ describe('BottomSheet', () => {
       expect(screen.getByRole('dialog')).toBeInTheDocument();
     });
   });
+
+  describe('container padding isolation', () => {
+    it('resets container padding custom properties to 0px on the sheet panel element', () => {
+      render(
+        <BottomSheet isOpen onOpenChange={() => {}} label="Filters">
+          Content
+        </BottomSheet>,
+      );
+      const sheet = getSheet();
+      const computed = window.getComputedStyle(sheet);
+      expect(
+        computed.getPropertyValue('--container-padding-inline-start'),
+      ).toBe('0px');
+      expect(computed.getPropertyValue('--container-padding-inline-end')).toBe(
+        '0px',
+      );
+      expect(computed.getPropertyValue('--container-padding-block-start')).toBe(
+        '0px',
+      );
+      expect(computed.getPropertyValue('--container-padding-block-end')).toBe(
+        '0px',
+      );
+    });
+  });
 });

package/src/BottomSheet/BottomSheet.tsx

@@ -49,8 +49,8 @@ import {
   type BottomSheetSwitcherPhase,
 } from './BottomSheetSwitcherContext';
 
-export type {BottomSheetHeight} from './BottomSheetPanel';
-import type {BottomSheetHeight} from './BottomSheetPanel';
+export type {BottomSheetHeight, BottomSheetSnapPoint} from './BottomSheetPanel';
+import type {BottomSheetHeight, BottomSheetSnapPoint} from './BottomSheetPanel';
 
 const styles = stylex.create({
   dialog: {
@@ -122,6 +122,16 @@ interface BottomSheetSharedProps extends BaseProps<HTMLDivElement> {
   /** Height budget or custom CSS length. Only fully expanded Tall is keyboard-aware. @default 'capped' */
   height?: BottomSheetHeight | number | string;
 
+  /**
+   * Extra heights the sheet can rest at when dragged; its own height is always
+   * the tallest stop, and omitting this gives a sheet that only opens and
+   * closes. Each stop is the sheet's visible height: a number is a viewport
+   * fraction (`0.5` is half the screen), `'50%'` the same in CSS, `'320px'` an
+   * absolute length. A stop of a quarter of the sheet or less is a peek — it
+   * slides away instead of reflowing, and thins the scrim.
+   */
+  snapPoints?: ReadonlyArray<BottomSheetSnapPoint>;
+
   /**
    * Configures implicit dismissal behavior, matching Dialog.
    * - required: Blocks swipe, scrim click, and Escape
@@ -193,6 +203,7 @@ function StandaloneBottomSheet({
   label,
   children,
   height = 'capped',
+  snapPoints,
   hasScrim = true,
   purpose = 'info',
   xstyle,
@@ -333,6 +344,7 @@ function StandaloneBottomSheet({
           ref={ref}
           state={panelState}
           height={height}
+          snapPoints={snapPoints}
           isSwipeDismissAllowed={purpose === 'info'}
           isPageScrollLocked={shouldPresent && hasScrim}
           xstyle={xstyle}
@@ -358,6 +370,7 @@ function SwitcherBottomSheetItem({
   label,
   children,
   height = 'capped',
+  snapPoints,
   purpose = 'info',
   xstyle,
   ...props
@@ -488,6 +501,7 @@ function SwitcherBottomSheetItem({
         ref={ref}
         state={panelState}
         height={height}
+        snapPoints={snapPoints}
         isSwipeDismissAllowed={purpose === 'info'}
         isPageScrollLocked={hasScrim}
         xstyle={xstyle}

package/src/BottomSheet/BottomSheetPanel.test.tsx

@@ -237,4 +237,45 @@ describe('BottomSheetPanel', () => {
     expect(panelRef).toHaveBeenLastCalledWith(null);
     expect(panelRef).toHaveBeenCalledTimes(2);
   });
+
+  it('floats the handle bar over content that starts at the sheet top edge', () => {
+    renderPanel({kind: 'open', entering: false});
+
+    const bar = getPanel().querySelector<HTMLElement>(
+      'div[aria-hidden="true"]',
+    );
+    if (bar == null) {
+      throw new Error('handle bar not found');
+    }
+    const body = bar.nextElementSibling as HTMLElement;
+
+    // Out of flow: the bar costs the content no layout space. That is the
+    // point of it -- the content sits closer to the sheet's top edge, and
+    // scrolled content passes beneath the pill rather than stopping at a
+    // hard edge.
+    expect(getComputedStyle(bar).position).toBe('absolute');
+
+    // So the body must not reserve room for it. A top padding here would
+    // push the content back down and undo the change.
+    expect(getComputedStyle(body).paddingTop).toBe('');
+  });
+
+  // The pill is only legible over the content riding up beneath it because
+  // the bar carries a backdrop; without it, text runs straight through the
+  // pill. jsdom's StyleX runtime does not inject the rule, so assert on the
+  // style definition itself (same approach as AspectRatio's reset.css tests).
+  it('backs the floating handle bar with a surface gradient', async () => {
+    const fs = await import('fs');
+    const path = await import('path');
+    const source = fs.readFileSync(
+      path.resolve(__dirname, './BottomSheetPanel.tsx'),
+      'utf-8',
+    );
+
+    const handleBar = source.match(/handleBar: \{([\s\S]*?)\n {2}\},/);
+    expect(handleBar).not.toBeNull();
+    expect(handleBar![1]).toContain("position: 'absolute'");
+    expect(handleBar![1]).toContain('linear-gradient(to bottom');
+    expect(handleBar![1]).toContain("colorVars['--color-background-surface']");
+  });
 });

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -16,6 +16,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
  * - /packages/core/src/BottomSheet/BottomSheetPanel.test.tsx
+ * - /packages/core/src/BottomSheet/snapOffsets.ts
  * - /packages/core/src/BottomSheet/useMobileKeyboard.ts
  * - /packages/core/src/BottomSheet/useSheetGestures.ts
  */
@@ -25,11 +26,13 @@ import {
   useEffect,
   useImperativeHandle,
   useLayoutEffect,
+  useMemo,
   useRef,
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
+import {useDevWarning} from '../hooks';
 import {
   colorVars,
   durationVars,
@@ -40,11 +43,15 @@ import {
   spacingVars,
 } from '../theme/tokens.stylex';
 import {mergeProps, themeProps} from '../utils';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
+import {
+  isValidSnapPoint,
+  resolveSnapPoints,
+  type BottomSheetSnapPoint,
+} from './snapOffsets';
 import {useMobileKeyboard} from './useMobileKeyboard';
 import {useSheetGestures} from './useSheetGestures';
 
-const SNAP_FRACTIONS = [0.14, 0.5, 0.92];
-
 const HEIGHT_BUDGETS = {
   hug: '92dvh',
   capped: '62dvh',
@@ -52,29 +59,53 @@ const HEIGHT_BUDGETS = {
 } as const;
 
 export type BottomSheetHeight = keyof typeof HEIGHT_BUDGETS;
+export type {BottomSheetSnapPoint};
 
 // SYNC: must match OVERSCROLL_MAX in useSheetGestures.ts.
 const OVERSCROLL_PADDING = 48;
 const MOBILE_KEYBOARD_BOTTOM_CLEARANCE = 48;
 const TRANSITION_BACKSTOP_BUFFER_MS = 50;
+// The floating handle bar's height. The bar is out of flow, so this is not
+// layout space the content pays for -- the pill (4px, centered) lands 10-14px
+// from the sheet's top edge, inside the space a content wrapper's own top
+// padding already provides.
+const HANDLE_BAR_HEIGHT = spacingVars['--spacing-6'];
+
+// Measure the same viewport the height budgets are written against. Those are
+// `dvh`, which the virtual keyboard does not shrink, so reading
+// `visualViewport` here would make the two disagree by exactly the keyboard's
+// height: every detent would move while the sheet it measures did not. A
+// keyboard is `useMobileKeyboard`'s business — it holds the sheet still and
+// scrolls the body — and it does not redefine the sheet's detents.
+function layoutViewportHeight(): number {
+  return typeof window === 'undefined' ? 0 : window.innerHeight;
+}
 
-function defaultSnapHeights(): number[] {
-  if (typeof window === 'undefined') {
-    return [];
+/**
+ * A stable identity for a set of snap points. Type-tagged, so the fraction
+ * `0.5` and the (invalid) string `'0.5'` cannot collide on one key.
+ *
+ * Recomputed every render — the panel re-renders on every frame of a drag — so
+ * it stays a single pass over a handful of values, and everything derived from
+ * the points hangs off it instead of being rebuilt per frame.
+ */
+function snapPointsKeyFor(
+  points: ReadonlyArray<BottomSheetSnapPoint> | undefined,
+): string {
+  let key = '';
+  for (const point of points ?? []) {
+    key += `${typeof point}:${point}|`;
   }
-  // Measure the same viewport the height budgets are written against. Those
-  // are `dvh`, which the virtual keyboard does not shrink, so reading
-  // `visualViewport` here made the two disagree by exactly the keyboard's
-  // height: every detent moved while the sheet it was measuring did not. A
-  // keyboard is `useMobileKeyboard`'s business — it holds the sheet still and
-  // scrolls the body — and it does not redefine the sheet's detents.
-  return SNAP_FRACTIONS.map(fraction => fraction * window.innerHeight);
+  return key;
 }
 
 const styles = stylex.create({
   sheet: {
     pointerEvents: 'auto',
     boxSizing: 'border-box',
+    // Containing block for the floating handle bar, which is lifted out of
+    // flow so the scrolling body reaches the sheet's top edge.
+    position: 'relative',
     display: 'flex',
     flexDirection: 'column',
     minHeight: 0,
@@ -111,11 +142,23 @@ const styles = stylex.create({
     pointerEvents: 'none',
   },
   handleBar: {
-    flexShrink: 0,
+    // Floats over the body rather than taking a row in the flex column. The
+    // content starts at the sheet's top edge and rides up under the pill --
+    // both moving it closer to the top and letting scrolled content pass
+    // beneath instead of stopping at a hard edge.
+    position: 'absolute',
+    insetBlockStart: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
+    zIndex: 1,
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
-    height: spacingVars['--spacing-12'],
+    height: HANDLE_BAR_HEIGHT,
+    // Keeps the pill legible over whatever sits or scrolls under it: opaque
+    // surface behind the pill itself, fading out across the lower half so the
+    // content emerging below has no visible cut line.
+    backgroundImage: `linear-gradient(to bottom, ${colorVars['--color-background-surface']} 60%, transparent)`,
     touchAction: 'none',
     cursor: 'grab',
   },
@@ -132,6 +175,10 @@ const styles = stylex.create({
     overflowY: 'auto',
     overscrollBehavior: 'none',
     touchAction: 'pan-y',
+    // No reserve for the handle bar: it floats, so the content starts at the
+    // sheet's top edge and rides up under the pill. The pill is 4px centered
+    // in a 24px band, so it occupies only 10-14px from the edge -- inside the
+    // space a content wrapper's own top padding already provides.
     paddingBlockEnd: 0,
   },
   tallKeyboardBody: {
@@ -171,6 +218,7 @@ interface BottomSheetPanelProps extends BaseProps<HTMLDivElement> {
   state: BottomSheetPanelState;
   height: BottomSheetHeight | number | string;
   children: ReactNode;
+  snapPoints?: ReadonlyArray<BottomSheetSnapPoint>;
   isSwipeDismissAllowed?: boolean;
   /** Whether the host has locked page scrolling (a modal, scrim-backed sheet). */
   isPageScrollLocked?: boolean;
@@ -296,6 +344,7 @@ export function BottomSheetPanel({
   state,
   height,
   children,
+  snapPoints,
   className,
   style,
   tabIndex,
@@ -340,6 +389,36 @@ export function BottomSheetPanel({
   const isFading = isRetained && state.motion === 'fading';
   const alignmentOffset = isRetained ? state.alignmentOffset : 0;
 
+  // Everything derived from the snap points keys off their identity, not the
+  // array's: the resolver's identity is the hook's signal that the stops
+  // changed, so it must not churn on a re-render the drag caused. The memo
+  // reads the points through a ref, so the resolver resolves them at call time
+  // — against whatever the viewport is then, not what it was at memo time.
+  const snapPointsKey = snapPointsKeyFor(snapPoints);
+  const snapPointsRef = useRef(snapPoints);
+  snapPointsRef.current = snapPoints;
+  const {snapHeights, ignoredSnapPointsMessage} = useMemo(() => {
+    if (snapPointsKey === '') {
+      return {snapHeights: undefined, ignoredSnapPointsMessage: ''};
+    }
+    const ignored = (snapPointsRef.current ?? []).filter(
+      point => !isValidSnapPoint(point),
+    );
+    return {
+      snapHeights: () =>
+        resolveSnapPoints(snapPointsRef.current ?? [], layoutViewportHeight()),
+      ignoredSnapPointsMessage:
+        ignored.length === 0
+          ? ''
+          : `snapPoints ignored ${JSON.stringify(ignored)}. A snap point is a viewport fraction above 0 and up to 1 (0.5 is half the screen), a px length ('320px'), or a percentage ('50%').`,
+    };
+  }, [snapPointsKey]);
+  useDevWarning(
+    'BottomSheet',
+    ignoredSnapPointsMessage,
+    ignoredSnapPointsMessage !== '',
+  );
+
   const {
     contentProps,
     handleProps,
@@ -359,7 +438,7 @@ export function BottomSheetPanel({
     canDismiss: isSwipeDismissAllowed,
     offscreenBlockEndInset: OVERSCROLL_PADDING,
     onDismiss,
-    snapHeights: defaultSnapHeights,
+    snapHeights,
     onScrimOpacity,
   });
 
@@ -502,6 +581,7 @@ export function BottomSheetPanel({
         themeProps('bottom-sheet'),
         stylex.props(
           styles.sheet,
+          overlayPaddingReset.reset,
           height === 'hug' ? styles.hugHeight : styles.budget,
           isClosing && styles.sheetClosing,
           isFading && styles.sheetFading,