@astryxdesign/core 0.4.5 → 0.4.6-canary.6a53e69

package/src/BottomSheet/BottomSheetEdgeTint.tsx

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheetEdgeTint.tsx
+ * @input Uses StyleX and core color tokens
+ * @output Exports BottomSheetEdgeTint, an internal decorative element
+ * @position Private helper rendered inside a non-modal BottomSheet dialog
+ *
+ * iOS 26 Safari dropped `<meta name="theme-color">` and instead derives the
+ * colour it paints behind its translucent toolbars by sampling the page: it
+ * hit tests a point just inside each viewport edge, walks up to the nearest
+ * `fixed`/`sticky` ancestor, and extends that element's declared
+ * `background-color` into the browser chrome.
+ *
+ * A modal sheet is served by that heuristic already — WebKit has a dedicated
+ * branch for a dialog's `::backdrop`. A non-modal sheet is not: the nearest
+ * fixed ancestor of the panel is the sheet's own full-viewport `<dialog>`,
+ * which is transparent and viewport-sized, and WebKit answers a viewport-sized
+ * candidate by *keeping the colour it already had* — the host page's. The page
+ * then shows through behind the address bar while the sheet covers the screen
+ * above it.
+ *
+ * This element gives the heuristic something unambiguous to sample: fixed,
+ * full width, flush with the bottom edge, taller than WebKit's 10px minimum
+ * for reading a declared colour, and painted in the sheet's own surface
+ * colour. It is masked out so it never renders for the user; Safari reads the
+ * computed style, not the painted pixels.
+ *
+ * Everywhere else it is inert decoration.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.test.tsx
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+
+/**
+ * WebKit ignores the declared `background-color` of a sampled box thinner than
+ * 10px and falls back to sampling painted pixels, which a masked element has
+ * none of. 12px clears that floor with room to spare and is still far below
+ * the ~40px of chrome it colours.
+ */
+const SAMPLE_HEIGHT_PX = 12;
+
+const styles = stylex.create({
+  tint: {
+    position: 'fixed',
+    insetInline: 0,
+    insetBlockEnd: 0,
+    height: `${SAMPLE_HEIGHT_PX}px`,
+    backgroundColor: colorVars['--color-background-surface'],
+    // Above the panel so the edge hit test lands here, and never in the way of
+    // a touch that was meant for the sheet.
+    zIndex: 2,
+    pointerEvents: 'none',
+    // Invisible to the user. WebKit's sampler checks `visibility` and
+    // `opacity` — either would disqualify the element — but not `mask`, so
+    // this hides the strip while leaving the colour readable. Without it the
+    // strip would show as a hairline under the panel as the sheet slides out.
+    maskImage: 'linear-gradient(transparent, transparent)',
+    WebkitMaskImage: 'linear-gradient(transparent, transparent)',
+  },
+});
+
+/**
+ * Colours the iOS Safari toolbar strip below a non-modal sheet. Renders
+ * nothing visible; see the file header for why it exists.
+ */
+export function BottomSheetEdgeTint() {
+  return (
+    <div
+      {...stylex.props(styles.tint)}
+      data-sheet-edge-tint=""
+      aria-hidden="true"
+    />
+  );
+}

package/src/BottomSheet/BottomSheetPanel.test.tsx

@@ -237,4 +237,161 @@ 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']",
+    );
+  });
+
+  /**
+   * The exit is not the entrance played backwards.
+   *
+   * `--ease-standard` is a decelerate curve: on it the sheet was half gone in
+   * 59ms of a 410ms transition and 90% gone in 163ms, so the close was over
+   * before it could be seen. The closing state therefore carries its own
+   * accelerating curve, and only the closing state does.
+   */
+  it('closes on an accelerating curve of its own, not the entrance timing', () => {
+    const declarationsFor = (element: HTMLElement) => {
+      const classes = new Set(element.className.split(/\s+/));
+      const out: string[] = [];
+      for (const styleSheet of Array.from(document.styleSheets)) {
+        let rules: CSSRuleList;
+        try {
+          rules = styleSheet.cssRules;
+        } catch {
+          continue;
+        }
+        for (const rule of Array.from(rules)) {
+          const selector = (rule as CSSStyleRule).selectorText;
+          const owner = selector?.match(/^\.([\w-]+)/)?.[1];
+          if (owner != null && classes.has(owner)) {
+            out.push(rule.cssText);
+          }
+        }
+      }
+      return out.join('\n');
+    };
+
+    const {container: closing} = render(
+      <BottomSheetPanel
+        state={{kind: 'exiting'}}
+        height="hug"
+        onDismiss={() => {}}
+        onScrimOpacity={() => {}}>
+        Panel content
+      </BottomSheetPanel>,
+    );
+    const closingRules = declarationsFor(
+      closing.querySelector('.astryx-bottom-sheet') as HTMLElement,
+    );
+    // An accelerating curve: no vertical rise at the start (y1 = 0), so the
+    // travel lands inside the duration instead of ahead of it.
+    expect(closingRules).toContain(
+      'transition-timing-function: cubic-bezier(.3,0,.6,.6)',
+    );
+
+    const {container: resting} = render(
+      <BottomSheetPanel
+        state={{kind: 'open', entering: false}}
+        height="hug"
+        onDismiss={() => {}}
+        onScrimOpacity={() => {}}>
+        Panel content
+      </BottomSheetPanel>,
+    );
+    const restingRules = declarationsFor(
+      resting.querySelector('.astryx-bottom-sheet') as HTMLElement,
+    );
+    expect(restingRules).toContain(
+      'transition-timing-function: var(--ease-standard)',
+    );
+    expect(restingRules).not.toContain('cubic-bezier(.3,0,.6,.6)');
+  });
 });

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'],
@@ -123,8 +149,27 @@ const styles = stylex.create({
       transitionDuration: '0.01s',
     },
   },
+  /**
+   * The exit is its own motion, not the entrance played backwards.
+   *
+   * `--ease-standard` is `cubic-bezier(0.24, 1, 0.4, 1)`, a decelerate curve:
+   * it spends its speed immediately and coasts. That is right for an entrance,
+   * where the sheet arrives fast and settles, and wrong for an exit. Measured
+   * on device, it put the sheet half off-screen in 59ms of a 410ms close and
+   * 90% off in 163ms -- the travel is over before the eye has followed it, and
+   * the rest of the duration moves pixels already below the fold.
+   *
+   * An exit accelerates instead: away from rest, gathering speed, quickest as
+   * it leaves the screen. The curve is deliberately gentle rather than a hard
+   * `ease-in` -- it is moving within ~50ms, so the close reads as one
+   * departure rather than a hesitation and a snap. The duration is the
+   * entrance's own band, so only the curve differs between the two
+   * directions; a shorter band leaves too little visible travel once a theme
+   * scales the motion scale down (neutral's medium is 300ms against 410ms).
+   */
   sheetClosing: {
     transform: 'translateY(100%)',
+    transitionTimingFunction: 'cubic-bezier(0.3, 0, 0.6, 0.6)',
   },
   sheetFading: {
     opacity: 0,
@@ -133,13 +178,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 +214,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 +629,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,

package/src/BottomSheet/BottomSheetSwitcher.tsx

@@ -22,6 +22,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
  * - /packages/core/src/BottomSheet/index.ts
@@ -51,6 +52,7 @@ import {
   useScrollLock,
 } from '../hooks';
 import {composeEventHandlers, mergeProps, mergeRefs} from '../utils';
+import {BottomSheetEdgeTint} from './BottomSheetEdgeTint';
 import {
   BottomSheetSwitcherContext,
   type BottomSheetSwitcherContextValue,
@@ -103,6 +105,14 @@ const styles = stylex.create({
       },
     },
   },
+  // The flow's dim leaves with its last panel. Same rule, same reasoning, as
+  // a standalone sheet's -- see `scrimClosing` in BottomSheet.tsx. A handoff
+  // between two sheets is not a close, and keeps the entrance curve.
+  scrimClosing: {
+    '::backdrop': {
+      transitionTimingFunction: 'linear',
+    },
+  },
 });
 
 type RetainedSheetPhase = 'covered' | 'aligning' | 'fading' | 'exiting';
@@ -593,6 +603,7 @@ export function BottomSheetSwitcher({
     styles.dialog,
     isFlowVisible && styles.dialogOpen,
     hasScrim && styles.scrim,
+    hasScrim && isFlowVisible && activeSheet == null && styles.scrimClosing,
     !hasScrim && styles.dialogNonModal,
     xstyle,
   );
@@ -620,6 +631,8 @@ export function BottomSheetSwitcher({
           ? {role: 'alertdialog'}
           : undefined)}>
         {children}
+        {/* A modal flow's ::backdrop already answers Safari's edge sampler. */}
+        {hasScrim ? null : <BottomSheetEdgeTint />}
       </dialog>
     </BottomSheetSwitcherContext>
   );

package/src/BottomSheet/useSheetGestures.test.ts

@@ -530,6 +530,33 @@ describe('useSheetGestures', () => {
       expect(hook.result.current.dragOffset).toBe(40);
     });
 
+    /**
+     * A finger is never still. Tapping a control inside the sheet drifts a
+     * pixel or two, and with no slop that drift promoted to a sheet drag —
+     * which wrote `transition: none` onto the panel across the release, so the
+     * close the tap triggered cut instead of animating. That is the "the sheet
+     * closes with no animation" report: only on a tap, and only on a tap
+     * inside the sheet (the scrim never arms a drag).
+     */
+    it('treats a few pixels of finger drift as a tap, not a drag', () => {
+      const {hook} = setup({snapHeights: () => [200]});
+      const body = makeBody(0); // at the top, where a pull-down would promote
+      bodyDown(hook, 0, 0, body);
+      bodyMove(hook, 3, 40, body); // the drift of a finger tapping a button
+      expect(hook.result.current.isDragging).toBe(false);
+      // and nothing suppressed the panel's transition, so a close that lands
+      // now still animates
+      expect(hook.result.current.contentProps.style.transition).toBeUndefined();
+    });
+
+    it('still promotes once the pull passes the tap slop', () => {
+      const {hook} = setup({snapHeights: () => [200]});
+      const body = makeBody(0);
+      bodyDown(hook, 0, 0, body);
+      bodyMove(hook, 9, 40, body); // just past the 8px slop
+      expect(hook.result.current.isDragging).toBe(true);
+    });
+
     it('does not hijack scrolling when the body is scrolled down', () => {
       const {hook} = setup({snapHeights: () => [200]});
       const body = makeBody(120); // scrolled, not at the top

package/src/BottomSheet/useSheetGestures.ts

@@ -118,6 +118,20 @@ const OVERSCROLL_MAX = 48;
 // the scroll, large enough that a swipe merely coming to rest on the last pixel
 // doesn't start a drag on jitter.
 const CONTENT_END_HANDOFF_SLOP = 4;
+// How far a finger resting on the body must travel before the pull becomes a
+// sheet drag rather than a tap.
+//
+// This used to be zero: any downward movement promoted. A finger is never
+// still, so tapping a control inside the sheet drifted a pixel or two and
+// started a drag -- which suppresses the panel's transition, correctly, for as
+// long as the sheet is tracking the finger. The close that the tap triggered
+// then landed inside that window and cut instead of animating. A deliberate
+// pull was unaffected; only a tap, and only a tap inside the sheet, since the
+// scrim is outside the body and arms nothing.
+//
+// 8px is the conventional tap slop, a shade over iOS's own recognizer, and
+// well under what a real pull covers in its first frames.
+const DRAG_PROMOTION_SLOP = 8;
 
 // Short haptic tick on detent settle where supported. iOS Safari doesn't
 // expose navigator.vibrate, so this is a no-op there; skipped under
@@ -1140,7 +1154,7 @@ export function useSheetGestures({
         return;
       }
       const delta = event.clientY - armed.startCoord;
-      if (delta > 0 && armed.scroller.scrollTop <= 0) {
+      if (delta > DRAG_PROMOTION_SLOP && armed.scroller.scrollTop <= 0) {
         // Downward pull at the top: promote to a sheet drag, anchored at the
         // original pointer-down position so the pull distance carries over.
         armedBodyRef.current = null;
@@ -1302,8 +1316,10 @@ export function useSheetGestures({
       // no longer scroll that way: at the top, a downward pull (delta > 0)
       // collapses; at the bottom, an upward pull (delta < 0) expands. The
       // opposite direction is a real scroll, so disarm and let it through.
-      const pullDownAtTop = armed.top && delta > 0 && atTop(scroller);
-      const pullUpAtBottom = armed.bottom && delta < 0 && atBottom(scroller);
+      const pullDownAtTop =
+        armed.top && delta > DRAG_PROMOTION_SLOP && atTop(scroller);
+      const pullUpAtBottom =
+        armed.bottom && delta < -DRAG_PROMOTION_SLOP && atBottom(scroller);
       if (pullDownAtTop || pullUpAtBottom) {
         event.preventDefault();
         touchDragRef.current = null;
@@ -1433,15 +1449,19 @@ export function useSheetGestures({
       style: {
         transform:
           activeOffset !== 0 ? `translateY(${activeOffset}px)` : undefined,
+        // Gated on the sheet being up: suppression must not outlive the sheet
+        // it was suppressing for. The host swaps the panel to its closing
+        // state in whatever frame the dismissal lands, and a stale `none`
+        // would apply to that transform too, cutting the exit.
         transition:
-          isDragging || isScrollAreaReconciling || reducedMotion
+          isOpen && (isDragging || isScrollAreaReconciling || reducedMotion)
             ? 'none'
             : undefined,
         touchAction: 'none',
         overscrollBehavior: 'contain',
       },
     }),
-    [activeOffset, isDragging, isScrollAreaReconciling, reducedMotion],
+    [activeOffset, isDragging, isOpen, isScrollAreaReconciling, reducedMotion],
   );
 
   const handleProps = useMemo<SheetHandleProps>(