@astryxdesign/core 0.4.6 → 0.4.7-canary.4c3982f

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>(

package/src/DateInput/DateInputTouch.test.tsx

@@ -419,6 +419,42 @@ describe('DateInput — field parity', () => {
     expect(onChange).toHaveBeenCalledWith(undefined);
   });
 
+  it('returns focus to the field without letting the page scroll', async () => {
+    // Clearing unmounts the clear button, and focusing another element in the
+    // same task as that unmount makes iOS Safari scroll the document to the
+    // top. Measured on the iOS 26 simulator against the live docsite, field at
+    // scrollY 2055: synchronous focus lands at 0, deferred focus stays at
+    // 2055. `preventScroll` alone does not fix it, so both halves are
+    // asserted: the focus is deferred past the unmount, and it is passed
+    // preventScroll. jsdom implements no scrolling, so the guard is asserted
+    // at the call.
+    vi.useFakeTimers();
+    try {
+      render(
+        <DateInput
+          label="Ship date"
+          value="2026-03-21"
+          hasClear
+          onChange={() => {}}
+        />,
+      );
+      const input = field();
+      const focus = vi.spyOn(input, 'focus');
+
+      fireEvent.click(screen.getByRole('button', {name: /Clear Ship date/}));
+
+      // Not synchronous — that is the whole point.
+      expect(focus).not.toHaveBeenCalled();
+
+      vi.runAllTimers();
+
+      expect(focus).toHaveBeenCalledWith({preventScroll: true});
+      focus.mockRestore();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('does not open the picker until the field is tapped', () => {
     withLayout(() => {
       render(<DateInput label="Ship date" onChange={() => {}} />);

package/src/DateInput/TouchDateField.tsx

@@ -599,6 +599,16 @@ export function TouchDateField({
   const [isSheetOpen, setIsSheetOpen] = useState(false);
   const [isWheelOpen, setIsWheelOpen] = useState(false);
   const scrollerHandleRef = useRef<MonthScrollerHandle | null>(null);
+  // Pending focus handoff from the clear button; see handleClear.
+  const clearFocusTimerRef = useRef<number | null>(null);
+  useEffect(
+    () => () => {
+      if (clearFocusTimerRef.current != null) {
+        clearTimeout(clearFocusTimerRef.current);
+      }
+    },
+    [],
+  );
 
   const today = useMemo(() => plainDateToday(), []);
   const selectedDate = useMemo(
@@ -708,7 +718,31 @@ export function TouchDateField({
 
   const handleClear = useCallback(() => {
     fireChange(undefined);
-    inputRef.current?.focus();
+    // Focus goes back to the field on the NEXT task, not synchronously.
+    //
+    // Clearing unmounts this button (it only renders while there is a value),
+    // and focusing another element in the same task as that unmount makes iOS
+    // Safari scroll the whole document to the top — the user is thrown from
+    // wherever the field sat to the start of the page. Measured on the iOS 26
+    // simulator against the live docsite, field at scrollY 2055: synchronous
+    // focus lands at 0, deferred focus stays at 2055.
+    //
+    // `preventScroll` alone does NOT fix it (verified: still 0) — this is not
+    // the browser's ordinary scroll-the-focused-element-into-view step, so the
+    // deferral is the load-bearing half. It is kept because the reveal scroll
+    // is real too, and unwanted for the same reason: the field the user just
+    // tapped is already on screen (+12px on a plain page without it).
+    //
+    // Skipping the focus entirely would also stop the scroll, but then focus
+    // dies with the unmounting button and lands on <body>.
+    const field = inputRef.current;
+    if (field == null) {
+      return;
+    }
+    clearFocusTimerRef.current = window.setTimeout(() => {
+      clearFocusTimerRef.current = null;
+      field.focus({preventScroll: true});
+    }, 0);
   }, [fireChange]);
 
   /**

package/src/Popover/Popover.test.tsx

@@ -2,7 +2,8 @@
 
 /**
  * @file Popover.test.tsx
- * @input Uses vitest, @testing-library/react, Popover component
+ * @input Uses vitest, @testing-library/react, Popover, Dialog,
+ *   SegmentedControl
  * @output Unit tests for Popover component behavior
  * @position Testing; validates Popover.tsx implementation
  *
@@ -14,6 +15,7 @@ import {render, screen, fireEvent} from '@testing-library/react';
 import React, {useRef} from 'react';
 import {Popover} from './Popover';
 import {Dialog} from '../Dialog';
+import {SegmentedControl, SegmentedControlItem} from '../SegmentedControl';
 
 // Store original matches to restore later
 const originalMatches = HTMLElement.prototype.matches;
@@ -306,6 +308,30 @@ describe('Popover', () => {
       expect(trigger).toHaveAttribute('aria-expanded', 'false');
     });
 
+    it('dismisses on Escape pressed inside a roving-focus list', () => {
+      render(
+        <Popover
+          content={
+            <SegmentedControl value="grid" onChange={() => {}} label="View">
+              <SegmentedControlItem value="grid" label="Grid" />
+              <SegmentedControlItem value="list" label="List" />
+            </SegmentedControl>
+          }
+          label="Test">
+          <button type="button">Open</button>
+        </Popover>,
+      );
+      const trigger = screen.getByRole('button', {name: 'Open'});
+      fireEvent.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+      // From the segment, so the list's own key handler runs first. jsdom has
+      // no popover display, so the open content still reads as hidden.
+      const segment = screen.getByRole('radio', {name: 'Grid', hidden: true});
+      fireEvent.keyDown(segment, {key: 'Escape'});
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
     it('stays open on Escape when hasEscapeDismiss is false', () => {
       render(
         <Popover

package/src/TabList/Tab.tsx

@@ -260,7 +260,11 @@ export function Tab({
     ...(isLabelHidden ? {'aria-label': label} : {}),
     [EDGE_COMP_ATTR]: '',
     'data-tab-value': value,
-    'aria-current': isSelected ? ('page' as const) : undefined,
+    // Generic `true` ("the current item within a set"), not `page`: the strip
+    // switches views in place at least as often as it navigates, and claiming
+    // "current page" when no page changed is a false statement to a screen
+    // reader. Stays truthful for the `href` case too, just less specific.
+    'aria-current': isSelected ? ('true' as const) : undefined,
     // Roving tabindex: the tab strip is a single Tab stop. The selected tab is
     // the tabbable one; the rest are reachable via arrow keys (handled by
     // TabList's onKeyDown). When no tab is selected, TabList's repair effect

package/src/TabList/TabList.test.tsx

@@ -106,7 +106,7 @@ describe('TabList', () => {
     );
   });
 
-  it('marks selected tab with aria-current', () => {
+  it('marks selected tab with a generic aria-current, not "page"', () => {
     render(
       <TabList value="home" onChange={() => {}}>
         <Tab value="home" label="Home" />
@@ -116,13 +116,30 @@ describe('TabList', () => {
 
     expect(screen.getByRole('button', {name: 'Home'})).toHaveAttribute(
       'aria-current',
-      'page',
+      'true',
     );
     expect(screen.getByRole('button', {name: 'Settings'})).not.toHaveAttribute(
       'aria-current',
     );
   });
 
+  it('marks a selected link tab with the same generic aria-current', () => {
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" href="/home" />
+        <Tab value="settings" label="Settings" href="/settings" />
+      </TabList>,
+    );
+
+    expect(screen.getByRole('link', {name: 'Home'})).toHaveAttribute(
+      'aria-current',
+      'true',
+    );
+    expect(screen.getByRole('link', {name: 'Settings'})).not.toHaveAttribute(
+      'aria-current',
+    );
+  });
+
   it('calls onChange when a tab is clicked', async () => {
     const user = userEvent.setup();
     const handleChange = vi.fn();
@@ -148,7 +165,7 @@ describe('TabList', () => {
 
     expect(screen.getByRole('button', {name: 'Home'})).toHaveAttribute(
       'aria-current',
-      'page',
+      'true',
     );
 
     rerender(
@@ -163,7 +180,7 @@ describe('TabList', () => {
     );
     expect(screen.getByRole('button', {name: 'Settings'})).toHaveAttribute(
       'aria-current',
-      'page',
+      'true',
     );
   });
 

package/src/hooks/useListFocus.doc.mjs

@@ -36,7 +36,7 @@ export const docs = {
     {
       name: 'options.onEscape',
       type: '() => void',
-      description: 'Callback when Escape key is pressed (e.g., close menu).',
+      description: 'Callback when Escape key is pressed (e.g., close menu). Supplying it also consumes the key (preventDefault); without it Escape passes through to the surrounding layer.',
       required: false,
     },
     {
@@ -144,7 +144,7 @@ export const docsDense = {
     'options.itemSelector': 'selector for focusable items in list.',
     'options.boundarySelector': "boundary selector for lists that contain nested lists (e.g. submenu flyouts); scopes items + key handling to this level.",
     'options.wrap': 'whether arrow navigation wraps around at ends.',
-    'options.onEscape': 'callback when Escape key pressed (e.g. close menu).',
+    'options.onEscape': 'callback when Escape key pressed (e.g. close menu). Also consumes the key; without it Escape passes through to the surrounding layer.',
     'options.orientation': "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",
     'options.hasHomeEnd': 'whether Home/End jump to first/last enabled item.',
     'options.isRtl': 'ArrowLeft/ArrowRight swap for horizontal nav (RTL). default: auto-detect from container computed direction; explicit boolean wins.',

package/src/hooks/useListFocus.test.tsx

@@ -3,14 +3,14 @@
 /**
  * @file useListFocus.test.tsx
  * @input Uses vitest, @testing-library/react, useListFocus hook
- * @output Unit tests for useListFocus disabled-item skipping, navigation, and
- *   RTL auto-detection
+ * @output Unit tests for useListFocus disabled-item skipping, navigation,
+ *   Escape consumption, and RTL auto-detection
  * @position Testing; validates useListFocus.ts keyboard navigation
  *
  * SYNC: When useListFocus.ts changes, update tests to match new behavior
  */
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import type {KeyboardEvent as ReactKeyboardEvent} from 'react';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {useListFocus} from './useListFocus';
@@ -525,3 +525,65 @@ describe('useListFocus boundarySelector (nested lists)', () => {
     expect(innerProbe).toHaveAttribute('data-owns', 'false');
   });
 });
+
+// A list inside a host that dismisses on Escape. The host's guard mirrors
+// `useFocusTrap`: it acts only on a key no inner handler has consumed.
+function EscapeHost({
+  onEscape,
+  onHostEscape,
+}: {
+  onEscape?: () => void;
+  onHostEscape: () => void;
+}) {
+  const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({onEscape});
+  return (
+    <div
+      data-testid="host"
+      onKeyDown={e => {
+        if (e.key === 'Escape' && !e.defaultPrevented) {
+          onHostEscape();
+        }
+      }}>
+      <div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
+        <div role="menuitem" tabIndex={-1} data-testid="One">
+          One
+        </div>
+        <div role="menuitem" tabIndex={-1} data-testid="Two">
+          Two
+        </div>
+      </div>
+    </div>
+  );
+}
+
+describe('useListFocus Escape', () => {
+  it('leaves Escape to the host when no onEscape is supplied', () => {
+    const onHostEscape = vi.fn();
+    render(<EscapeHost onHostEscape={onHostEscape} />);
+
+    fireEvent.keyDown(screen.getByRole('menu'), {key: 'Escape'});
+    expect(onHostEscape).toHaveBeenCalledTimes(1);
+  });
+
+  it('consumes Escape and runs onEscape when one is supplied', () => {
+    const onEscape = vi.fn();
+    const onHostEscape = vi.fn();
+    render(<EscapeHost onEscape={onEscape} onHostEscape={onHostEscape} />);
+
+    fireEvent.keyDown(screen.getByRole('menu'), {key: 'Escape'});
+    expect(onEscape).toHaveBeenCalledTimes(1);
+    expect(onHostEscape).not.toHaveBeenCalled();
+  });
+
+  it('still consumes arrow keys with no onEscape (page-scroll suppression)', () => {
+    render(<EscapeHost onHostEscape={() => {}} />);
+    screen.getByTestId('One').focus();
+
+    // fireEvent returns false when a handler cancelled the event.
+    const wasCancelled = !fireEvent.keyDown(screen.getByRole('menu'), {
+      key: 'ArrowDown',
+    });
+    expect(wasCancelled).toBe(true);
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+});

package/src/hooks/useListFocus.ts

@@ -14,6 +14,8 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useListFocus.doc.mjs
+ * - /packages/core/src/hooks/useListFocus.test.tsx
  */
 
 import {useCallback, useRef} from 'react';
@@ -64,7 +66,9 @@ export interface UseListFocusOptions {
   wrap?: boolean;
 
   /**
-   * Callback when Escape key is pressed.
+   * Callback when Escape key is pressed. Supplying it also makes the list
+   * consume the key (`preventDefault`); without it Escape passes through to
+   * the surrounding layer.
    */
   onEscape?: () => void;
 
@@ -277,7 +281,8 @@ function shouldDeferToCaret(target: EventTarget | null, key: string): boolean {
  * - ArrowUp/ArrowLeft: Move to previous item (wraps to last)
  * - Home: Move to first item
  * - End: Move to last item
- * - Escape: Custom callback (e.g., close menu)
+ * - Escape: runs `onEscape` and consumes the key. With no `onEscape` the key
+ *   is left alone, so a surrounding layer can still dismiss on it.
  *
  * By default the hook only *moves* focus and leaves `tabindex` management to
  * the caller. Opt into {@link UseListFocusOptions.hasRovingTabIndex} for a hook
@@ -557,12 +562,15 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
         return;
       }
 
-      // Escape is handled regardless of orientation. Preserve the historical
-      // behavior of always consuming Escape here (preventDefault) so consumers
-      // that relied on it are unaffected.
+      // Escape is handled regardless of orientation, but only *consumed* when
+      // a handler asked for it: a list with no dismissal to perform must leave
+      // the key to whatever host layer does have one, and those defer to
+      // `defaultPrevented` (see `useFocusTrap`) or to the native popover.
       if (e.key === 'Escape') {
-        e.preventDefault();
-        onEscape?.();
+        if (onEscape) {
+          e.preventDefault();
+          onEscape();
+        }
         return;
       }
 

package/src/theme/MediaTheme.doc.mjs

@@ -68,7 +68,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Prefer mode="auto" when the surface color comes from a theme token. A token named "inverted" is not guaranteed to be inverted, and auto measures what was actually painted instead of trusting the name — including deciding that a surface needs no media context at all.',
+          'Prefer mode="auto" when the surface color comes from a theme token. A token named "inverted" is not guaranteed to be inverted, and auto measures what was actually painted instead of trusting the name. It can even decide that a surface needs no media context at all.',
       },
       {
         guidance: true,
@@ -93,14 +93,14 @@ export const docs = {
       type: "'dark' | 'light' | 'auto' | 'off'",
       required: true,
       description:
-        'Surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from the painted surface — no media context when the ambient text already reads on the surface (3:1), otherwise the side that reads better — and off to turn it off explicitly. The element renders either way, so a surface can switch contexts without remounting children.',
+        'Surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from the painted surface (no media context when the ambient text already reads on the surface at 3:1, otherwise the side that reads better), and off to turn it off explicitly. The element renders either way, so a surface can switch contexts without remounting children.',
     },
     {
       name: 'fallback',
       type: "'dark' | 'light'",
       default: "'dark'",
       description:
-        'Which side auto uses when the surface cannot be measured: during SSR, on the first client frame, and whenever the backdrop is not knowable from CSS — most often a background-image, whose pixels need sampling (useImageMode) rather than a computed style. Ignored unless mode is auto.',
+        'Which side auto uses when the surface cannot be measured: during SSR, on the first client frame, and whenever the backdrop is not knowable from CSS, most often a background-image, whose pixels need sampling (useImageMode) rather than a computed style. Ignored unless mode is auto.',
     },
     {
       name: 'children',
@@ -126,7 +126,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'Prefer mode="auto" when surface color comes from a theme token — a token named "inverted" is not guaranteed to be; auto measures what was painted.',
+          'Prefer mode="auto" when surface color comes from a theme token; a token named "inverted" is not guaranteed to be; auto measures what was painted.',
       },
       {
         guidance: true,
@@ -148,6 +148,6 @@ export const docsDense = {
   propDescriptions: {
     mode: 'surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from painted surface (none if ambient text already reads at 3:1, else better-reading side), off to turn off explicitly (element still renders, so children never remount)',
     fallback:
-      'side auto uses when surface is unmeasurable (SSR, first frame, background-image — those need useImageMode sampling); ignored unless mode is auto',
+      'side auto uses when surface is unmeasurable (SSR, first frame, background-image, which needs useImageMode sampling); ignored unless mode is auto',
   },
 };