@astryxdesign/core 0.4.4 → 0.4.5-canary.0472ec1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.4.4",
+  "version": "0.4.5-canary.0472ec1",
   "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.0472ec1",
     "@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/AvatarGroup/AvatarGroupOverflow.tsx

@@ -88,7 +88,7 @@ const styles = stylex.create({
     // Interactive overlay states layered on top via backgroundImage
     backgroundImage: {
       default: `linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']}), linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']}), linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,

package/src/Banner/Banner.doc.mjs

@@ -221,6 +221,8 @@ export const docsDense = {
       {guidance: true, description: 'Keep titles short: "Payment failed" not "There was a problem processing your payment."'},
       {guidance: false, description: 'Use for auto-dismissing messages; use Toast instead.'},
       {guidance: false, description: 'Stack multiple banners of the same status; combine into one.'},
+      {guidance: true, description: 'Error/warning render role="alert", info/success role="status"; mount an alert banner on an event, not first paint, so assistive tech announces it.'},
+      {guidance: false, description: 'Rely on status color or icon alone; state the status in the title text, since the icon is decorative to a screen reader.'},
     ],
     anatomy: [
       {name: 'Icon', required: true, description: 'Set automatically from status.'},

package/src/Blockquote/Blockquote.doc.mjs

@@ -19,7 +19,7 @@ export const docs = {
     {
       name: 'cite',
       type: 'ReactNode',
-      description: 'Optional attribution for the quote. Rendered in a <footer> with <cite>.',
+      description: 'Optional attribution for the quote. Rendered in a <cite> element after the quoted content.',
     },
     {
       name: 'xstyle',
@@ -28,17 +28,31 @@ export const docs = {
         'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
     },
   ],
+  playground: {
+    defaults: {
+      children:
+        'Design is not just what it looks like and feels like. Design is how it works.',
+      cite: 'Steve Jobs',
+    },
+  },
   theming: {
     targets: [
       {className: 'astryx-blockquote', visualProps: []},
     ],
   },
   usage: {
-    description: 'A styled quotation block with an accent-colored left border and secondary text color. Use to highlight quoted content, testimonials, or excerpts.',
+    description: 'A quotation block with a rule on its inline-start edge and secondary text color. Use to highlight quoted content, testimonials, or excerpts. The rule and padding are logical, so they move to the right edge in right-to-left locales.',
+    anatomy: [
+      {name: 'Rule', required: true, description: 'The border on the inline-start edge, drawn with --color-border-emphasized.'},
+      {name: 'Quotation', required: true, description: 'The quoted content, passed as children. Renders inside the <blockquote> element.'},
+      {name: 'Attribution', required: false, description: 'The source, passed as cite. Renders as a <cite> element below the quotation.'},
+    ],
     bestPractices: [
       { guidance: true, description: 'Use for quoted text, testimonials, or highlighted excerpts from external sources.' },
       { guidance: true, description: 'Provide a cite prop when the source of the quote is known.' },
+      { guidance: true, description: 'Pass the source through cite rather than typing it into children, so it renders as a semantic <cite> element that assistive technology can distinguish from the quotation.' },
       { guidance: false, description: 'Use for callout boxes or informational notes; use Banner for those.' },
+      { guidance: false, description: 'Wrap the attribution in your own <footer>. A <footer> inside a <blockquote> becomes a contentinfo document landmark, and a page with several quotes then reports several page footers.' },
     ],
   },
 };
@@ -57,7 +71,7 @@ export const docsZh = {
     {
       name: 'cite',
       type: 'ReactNode',
-      description: '引用的可选出处。在 <footer> 中以 <cite> 渲染。',
+      description: '引用的可选出处。在引用内容之后以 <cite> 元素渲染。',
     },
     {
       name: 'xstyle',
@@ -72,29 +86,38 @@ export const docsZh = {
     ],
   },
   usage: {
-    description: '带有强调色左边框和次要文本颜色的引用块。用于突出显示引用内容、推荐语或摘录。',
+    description: '带有行首边框和次要文本颜色的引用块。用于突出显示引用内容、推荐语或摘录。边框和内边距使用逻辑属性，因此在从右到左的语言环境中会移到右侧。',
+    anatomy: [
+      {name: '边框', required: true, description: '行首边缘的边框，使用 --color-border-emphasized 绘制。'},
+      {name: '引用内容', required: true, description: '通过 children 传入的引用内容，渲染在 <blockquote> 元素内。'},
+      {name: '出处', required: false, description: '通过 cite 传入的来源，在引用内容下方以 <cite> 元素渲染。'},
+    ],
     bestPractices: [
       { guidance: true, description: '用于引用文本、推荐语或来自外部来源的高亮摘录。' },
       { guidance: true, description: '当引用来源已知时，提供 cite 属性。' },
+      { guidance: true, description: '通过 cite 传入来源，而不是写在 children 里，这样它会渲染为语义化的 <cite> 元素，辅助技术可以将其与引用内容区分开。' },
       { guidance: false, description: '用于提示框或信息说明，应使用 Banner。' },
+      { guidance: false, description: '自行用 <footer> 包裹出处。<blockquote> 内的 <footer> 会成为 contentinfo 文档地标，页面上有多个引用时就会报告多个页脚。' },
     ],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'styled quotation block w/ accent left border, secondary text, optional citation',
+  description: 'quotation block w/ inline-start rule, secondary text, optional citation',
   usage: {
-    description: 'A styled quotation block with an accent-colored left border and secondary text color. Use to highlight quoted content, testimonials, or excerpts.',
+    description: 'A quotation block with a rule on its inline-start edge and secondary text color. Use to highlight quoted content, testimonials, or excerpts.',
     bestPractices: [
       { guidance: true, description: 'Use for quoted text, testimonials, or highlighted excerpts.' },
       { guidance: true, description: 'Provide cite when source is known.' },
+      { guidance: true, description: 'Pass the source via cite, not inside children.' },
       { guidance: false, description: 'Use for callouts/notes; use Banner instead.' },
+      { guidance: false, description: 'Wrap the attribution in <footer>; it becomes a contentinfo landmark.' },
     ],
   },
   propDescriptions: {
     children: 'blockquote content',
-    cite: 'optional attribution rendered in <footer><cite>',
+    cite: 'optional attribution rendered as <cite> after the quote',
     xstyle: 'StyleX styles for layout; must be stylex.create() value',
   },
 };

package/src/Blockquote/Blockquote.test.tsx

@@ -11,6 +11,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
+import {renderToString} from 'react-dom/server';
 import {Blockquote} from './Blockquote';
 
 describe('Blockquote', () => {
@@ -31,7 +32,6 @@ describe('Blockquote', () => {
   it('renders without cite by default', () => {
     render(<Blockquote data-testid="bq">Quote</Blockquote>);
     const element = screen.getByTestId('bq');
-    expect(element.querySelector('footer')).toBeNull();
     expect(element.querySelector('cite')).toBeNull();
   });
 
@@ -42,13 +42,34 @@ describe('Blockquote', () => {
       </Blockquote>,
     );
     const element = screen.getByTestId('bq');
-    const footer = element.querySelector('footer');
-    expect(footer).toBeInTheDocument();
     const cite = element.querySelector('cite');
     expect(cite).toBeInTheDocument();
     expect(cite).toHaveTextContent('Steve Jobs');
   });
 
+  it('never wraps the attribution in a landmark element', () => {
+    render(
+      <Blockquote cite="Steve Jobs" data-testid="bq">
+        Quote
+      </Blockquote>,
+    );
+    const element = screen.getByTestId('bq');
+    expect(element.querySelector('footer')).toBeNull();
+    expect(screen.queryByRole('contentinfo')).toBeNull();
+  });
+
+  it.each([
+    ['false', false],
+    ['an empty string', ''],
+  ])('renders no cite element when cite is %s', (_label, cite) => {
+    render(
+      <Blockquote cite={cite} data-testid="bq">
+        Quote
+      </Blockquote>,
+    );
+    expect(screen.getByTestId('bq').querySelector('cite')).toBeNull();
+  });
+
   it('renders cite as ReactNode', () => {
     render(
       <Blockquote
@@ -87,4 +108,14 @@ describe('Blockquote', () => {
     );
     expect(screen.getByTestId('child-p')).toBeInTheDocument();
   });
+
+  it('renders on the server', () => {
+    const html = renderToString(
+      <Blockquote cite="Steve Jobs">Design is how it works.</Blockquote>,
+    );
+    expect(html).toContain('<blockquote');
+    expect(html).toContain('astryx-blockquote');
+    expect(html).toContain('<cite');
+    expect(html).toContain('Steve Jobs');
+  });
 });

package/src/Blockquote/Blockquote.tsx

@@ -17,7 +17,7 @@ import type {ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, typeScaleVars} from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
 export interface BlockquoteProps extends BaseProps<HTMLQuoteElement> {
@@ -26,7 +26,8 @@ export interface BlockquoteProps extends BaseProps<HTMLQuoteElement> {
   /** Content of the blockquote */
   children: ReactNode;
   /**
-   * Optional attribution for the quote. Rendered in a <footer> with <cite>.
+   * Optional attribution for the quote. Rendered in a `<cite>` element after
+   * the quoted content.
    */
   cite?: ReactNode;
 }
@@ -38,6 +39,7 @@ const styles = stylex.create({
     borderInlineStartColor: colorVars['--color-border-emphasized'],
     paddingInlineStart: spacingVars['--spacing-4'],
     color: colorVars['--color-text-secondary'],
+    overflowWrap: 'break-word',
     marginInlineStart: 0,
     marginInlineEnd: 0,
     marginBlockStart: 0,
@@ -55,8 +57,8 @@ const styles = stylex.create({
 /**
  * Blockquote component for displaying quoted content.
  *
- * Renders a semantic `<blockquote>` with an accent-colored left border
- * and secondary text color, matching the Astryx visual language.
+ * Renders a semantic `<blockquote>` with an inline-start rule and secondary
+ * text color, matching the Astryx visual language.
  *
  * @example
  * ```
@@ -83,11 +85,11 @@ export function Blockquote({
       )}
       {...props}>
       {children}
-      {cite != null && (
-        <footer>
-          <cite {...stylex.props(styles.cite)}>{cite}</cite>
-        </footer>
-      )}
+      {/*
+        A bare <cite>, never wrapped in <footer>: <blockquote> is a sectioning
+        root, so a <footer> inside it maps to a contentinfo document landmark.
+      */}
+      {isRenderable(cite) && <cite {...stylex.props(styles.cite)}>{cite}</cite>}
     </blockquote>
   );
 }

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}