@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/src/AvatarGroup/AvatarGroupOverflow.tsx

@@ -18,11 +18,13 @@ import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
   typographyVars,
+  typeScaleVars,
   fontWeightVars,
   radiusVars,
   spacingVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {resolveSize} from '../Avatar';
 import {useAvatarGroup} from './AvatarGroupContext';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -57,7 +59,10 @@ export interface AvatarGroupOverflowProps extends Omit<
 const styles = stylex.create({
   base: {
     position: 'relative',
-    display: 'flex',
+    // inline-flex, not flex: outside an AvatarGroup this span is not a flex
+    // item, and a block-level flex container stretches to its parent's width
+    // instead of staying a circle.
+    display: 'inline-flex',
     alignItems: 'center',
     justifyContent: 'center',
     borderRadius: radiusVars['--radius-full'],
@@ -81,14 +86,17 @@ const styles = stylex.create({
     backgroundImage: `linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
   },
   button: {
-    cursor: 'pointer',
+    cursor: {
+      default: 'pointer',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
     // Reset the UA button's block padding only; the inline padding from `base`
     // provides the pill's breathing room and must be preserved.
     paddingBlock: 0,
     // 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']})`,
@@ -96,7 +104,12 @@ const styles = stylex.create({
     // Focus ring via focus-visible
   },
   overlap: {
-    marginInlineStart: 'var(--_avatar-group-overlap)',
+    // Matches Avatar's own overlap rule: the first item in the row must not be
+    // pulled outside the group's box.
+    marginInlineStart: {
+      default: null,
+      ':not(:first-child)': 'var(--_avatar-group-overlap)',
+    },
   },
 });
 
@@ -113,7 +126,13 @@ const dynamicStyles = stylex.create({
     height: s + BORDER_WIDTH * 2,
   }),
   fontSize: (s: number) => ({
-    fontSize: s * OVERFLOW_FONT_RATIO,
+    // Scales with the avatar, but never below the supporting-text role token,
+    // which is the 12px legibility floor. At xsm the bare ratio computes 7px,
+    // where the glyph stroke is thinner than a pixel and never reaches its
+    // own text colour (measured 1.63:1 against a 4.5:1 requirement).
+    fontSize: `max(${typeScaleVars['--text-supporting-size']}, ${
+      s * OVERFLOW_FONT_RATIO
+    }px)`,
   }),
   overlap: (offset: number) => ({
     '--_avatar-group-overlap': `${offset}px`,
@@ -147,11 +166,15 @@ export function AvatarGroupOverflow({
   const t = useTranslator();
   const group = useAvatarGroup();
   const size = group?.size ?? 'md';
-  const numericSize = group?.numericSize ?? 36;
+  const numericSize = group?.numericSize ?? resolveSize('md');
   const overlap = group?.overlap ?? 0;
 
-  const label = t('@astryx.avatarGroup.overflow', {count});
-  const content = children ?? `+${count}`;
+  // count is a plain number, and the documented shape for it is
+  // `total - visibleCount`, which goes negative whenever the list is shorter
+  // than the slice. Clamping keeps that from rendering "+-3".
+  const safeCount = Math.max(0, count);
+  const label = t('@astryx.avatarGroup.overflow', {count: safeCount});
+  const content = children ?? `+${safeCount}`;
 
   if (onClick) {
     return (

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

@@ -102,14 +102,14 @@ 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. 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.",
+        "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.",
+        "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',
@@ -269,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, 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',
+    '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

@@ -2262,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/BottomSheetPanel.test.tsx

@@ -237,4 +237,95 @@ 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']");
+  });
+
+  // In dark mode the surface fill and the scrim sit a few RGB steps apart and
+  // the drop shadow is black on near-black, so the fill alone leaves the
+  // sheet's left and right edges invisible against the scrim. A hairline on
+  // the scrim-facing edges is what draws them. Asserted on the style
+  // definition for the same reason as the test above.
+  it('draws a hairline on the three edges that face the scrim', async () => {
+    const fs = await import('fs');
+    const path = await import('path');
+    const source = fs.readFileSync(
+      path.resolve(__dirname, './BottomSheetPanel.tsx'),
+      'utf-8',
+    );
+
+    const sheet = source.match(/\n {2}sheet: \{([\s\S]*?)\n {2}\},/);
+    expect(sheet).not.toBeNull();
+    for (const edge of [
+      'borderBlockStart',
+      'borderInlineStart',
+      'borderInlineEnd',
+    ]) {
+      expect(sheet![1]).toContain(`${edge}Width: borderVars['--border-width']`);
+      expect(sheet![1]).toContain(`${edge}Style: 'solid'`);
+      expect(sheet![1]).toContain(`${edge}Color: colorVars['--color-border']`);
+    }
+    // The block-end edge sits below the viewport, under the overscroll
+    // padding, so it carries no hairline to draw.
+    expect(sheet![1]).not.toContain('borderBlockEndWidth');
+  });
+
+  // A theme that packs an inset ring into --shadow-high (the bundled themes all
+  // add one in dark mode) draws it just inside the sheet, where an opaque
+  // content wrapper such as Section paints over it -- so it showed only in the
+  // gap below the content and the side edges appeared to change width partway
+  // down. The scrolling body paints the surface across the whole inner box to
+  // hide the ring evenly.
+  it('paints the surface across the scrolling body so the edge stays uniform', async () => {
+    const fs = await import('fs');
+    const path = await import('path');
+    const source = fs.readFileSync(
+      path.resolve(__dirname, './BottomSheetPanel.tsx'),
+      'utf-8',
+    );
+
+    const body = source.match(/\n {2}body: \{([\s\S]*?)\n {2}\},/);
+    expect(body).not.toBeNull();
+    expect(body![1]).toContain(
+      "backgroundColor: colorVars['--color-background-surface']",
+    );
+  });
 });

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -34,6 +34,7 @@ import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import {useDevWarning} from '../hooks';
 import {
+  borderVars,
   colorVars,
   durationVars,
   easeVars,
@@ -43,6 +44,7 @@ import {
   spacingVars,
 } from '../theme/tokens.stylex';
 import {mergeProps, themeProps} from '../utils';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
 import {
   isValidSnapPoint,
   resolveSnapPoints,
@@ -64,6 +66,11 @@ export type {BottomSheetSnapPoint};
 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
@@ -97,12 +104,31 @@ 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,
     width: '100%',
     maxWidth: 640,
     backgroundColor: colorVars['--color-background-surface'],
+    // Hairline on the three edges that face the scrim. The surface fill alone
+    // separates sheet from scrim in light mode, but not in dark: there the two
+    // sit within a few RGB steps of each other and the drop shadow is black on
+    // near-black, so the sheet's left and right edges disappear. Same
+    // treatment MobileNav gives its scrim-facing edge. The block-end edge is
+    // deliberately left bare; it sits below the viewport, under the overscroll
+    // padding.
+    borderBlockStartWidth: borderVars['--border-width'],
+    borderBlockStartStyle: 'solid',
+    borderBlockStartColor: colorVars['--color-border'],
+    borderInlineStartWidth: borderVars['--border-width'],
+    borderInlineStartStyle: 'solid',
+    borderInlineStartColor: colorVars['--color-border'],
+    borderInlineEndWidth: borderVars['--border-width'],
+    borderInlineEndStyle: 'solid',
+    borderInlineEndColor: colorVars['--color-border'],
     borderStartStartRadius: radiusVars['--radius-container'],
     borderStartEndRadius: radiusVars['--radius-container'],
     boxShadow: shadowVars['--shadow-high'],
@@ -133,13 +159,28 @@ 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',
+    cursor: {
+      default: 'grab',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
   },
   handlePill: {
     width: sizeVars['--size-element-lg'],
@@ -154,6 +195,19 @@ const styles = stylex.create({
     overflowY: 'auto',
     overscrollBehavior: 'none',
     touchAction: 'pan-y',
+    // The scrolling area paints the surface itself, covering the sheet's whole
+    // inner box. Without it the sheet's edge is not uniform: a theme that packs
+    // an inset ring into --shadow-high (the bundled themes all add one in dark
+    // mode) draws that ring just inside the sheet, where an opaque content
+    // wrapper such as Section paints over it -- so the ring shows only in the
+    // gap below where the content ends, and the sheet's side edges appear to
+    // change width partway down. Painting the surface here hides the ring
+    // evenly, leaving the border below as the sheet's one edge.
+    backgroundColor: colorVars['--color-background-surface'],
+    // 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: {
@@ -556,6 +610,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,