@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.8",
+  "version": "0.7.9-canary.0200dfe",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -838,6 +838,16 @@
       "source": "./src/internal/selectable-card.ts",
       "types": "./dist/internal/selectable-card.d.ts",
       "default": "./dist/internal/selectable-card.js"
+    },
+    "./internal/spinner-rotor": {
+      "source": "./src/internal/spinner-rotor.ts",
+      "types": "./dist/internal/spinner-rotor.d.ts",
+      "default": "./dist/internal/spinner-rotor.js"
+    },
+    "./internal/calendar-system": {
+      "source": "./src/internal/calendar-system.ts",
+      "types": "./dist/internal/calendar-system.d.ts",
+      "default": "./dist/internal/calendar-system.js"
     }
   },
   "files": [
@@ -870,6 +880,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.9-canary.0200dfe",
+    "@astryxdesign/cli": "0.7.9-canary.0200dfe",
+    "@astryxdesign/interaction-harness": "0.7.9-canary.0200dfe",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -881,9 +894,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
     "tailwindcss": "^4.3.2",
-    "@astryxdesign/cli": "0.7.8",
-    "@astryxdesign/interaction-harness": "0.0.0",
-    "@astryxdesign/a11y-spec": "0.0.0"
+    "temporal-polyfill": "^1.0.6"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AppShell/observeMainOverflow.ts

@@ -4,20 +4,23 @@
 
 /**
  * @file observeMainOverflow.ts
- * @input AppShell's main region under `height="fill"`: its own scroll
- *   container, holding its content as direct children with no wrapper
+ * @input A scroll container that holds its content as direct children with
+ *   no wrapper: AppShell's main region under `height="fill"`, or a scrolling
+ *   LayoutContent, LayoutPanel or StackItem
  * @output observeMainOverflow(main, onChange): reports whether main's content
  *   overflows it on either axis, once at the start and on every change, and
  *   returns the function that stops observing
- * @position Internal to AppShell and never exported. AppShell makes main a
+ * @position Internal and never exported. AppShell makes main a
  *   keyboard stop only while it overflows (`spec:AST-025` FR12,
- *   `component:AppShell` FR4 and PR1). Main has no inner content box, so its
- *   content grows inside it without resizing it: its direct children's sizes
- *   are watched instead.
+ *   `component:AppShell` FR4 and PR1). useScrollRegionProps names a
+ *   scrolling region only while it overflows. Main has no inner content
+ *   box, so its content grows inside it without resizing it: its direct
+ *   children's sizes are watched instead.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/AppShell/AppShell.tsx
  * - /packages/core/src/AppShell/observeMainOverflow.test.ts
+ * - /packages/core/src/hooks/useScrollRegionProps.ts
  */
 
 import {

package/src/BottomSheet/BottomSheet.tsx

@@ -81,7 +81,11 @@ import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 import {useModalOutlet} from '../Layer/modalOutlet';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
-import {focusForLastInput} from '../utils/focusReturn';
+import {useFocusRegionContainment} from '../hooks/useFocusTrap';
+import {
+  prepareFocusRepairOnRemoval,
+  returnFocusForLastInput,
+} from '../utils/focusReturn';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {
   BottomSheetPanel,
@@ -444,6 +448,10 @@ function StandaloneBottomSheet({
     false,
   );
   const isEntrySettled = settledOpen && isOpen;
+  // Only a modal sheet contains Tab; a non-modal one leaves the page's focus
+  // order alone. A closing sheet stops containing as soon as it starts to
+  // leave.
+  useFocusRegionContainment(dialogRef, isOpen && hasScrim);
   // Presentation outlives the controlled prop: a closing sheet stays mounted
   // and in its native host through its exit, and only its motion completion
   // (or a replace finishing) clears it. The open flip is derived during
@@ -548,7 +556,15 @@ function StandaloneBottomSheet({
       return;
     }
     const key = stackKeyRef.current;
-    return registerBottomSheet(
+    const dialog = dialogRef.current;
+    // Removing an open dialog runs no close, so focus would drop to the page.
+    // After the commit, the repair sends focus where a close would, if the
+    // removal lost focus.
+    const repairOnRemoval =
+      dialog == null
+        ? null
+        : prepareFocusRepairOnRemoval(dialog, {keepRestingFocus: true});
+    const leave = registerBottomSheet(
       {
         key,
         getElement: () => dialogRef.current,
@@ -606,6 +622,32 @@ function StandaloneBottomSheet({
       isOpenRef.current,
       hasScrim,
     );
+    return () => {
+      // Read before the registry lets go of the sheet beneath. Focus the
+      // person had already moved out of the sheet to the page body stays
+      // there: the removal did not lose it.
+      if (repairOnRemoval != null && isSheetHostPresented(dialog)) {
+        const returnTarget =
+          finalFocusRefRef.current?.current ?? triggerRef.current;
+        const revealed = hasScrim ? getBottomSheetBeneath(key) : null;
+        repairOnRemoval(() => {
+          // The sheet beneath left too. Its own repair returns focus for the
+          // stack.
+          if (revealed != null && !revealed.element.isConnected) {
+            return;
+          }
+          if (
+            revealed != null &&
+            (returnTarget == null || !revealed.element.contains(returnTarget))
+          ) {
+            revealed.focus();
+          } else if (returnTarget != null && returnTarget.isConnected) {
+            returnFocusForLastInput(returnTarget);
+          }
+        });
+      }
+      leave();
+    };
   }, [hasScrim, shouldPresent, writeScrim]);
   useLayoutEffect(() => {
     if (!isOpen) {
@@ -720,7 +762,7 @@ function StandaloneBottomSheet({
       ) {
         revealed.focus();
       } else if (returnTarget != null) {
-        focusForLastInput(returnTarget);
+        returnFocusForLastInput(returnTarget);
       }
       triggerRef.current = null;
     },

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -26,6 +26,7 @@ import {
   useLayoutEffect,
   useMemo,
   useRef,
+  useSyncExternalStore,
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -60,6 +61,7 @@ import {
   paddingStyles,
   spacingStepToToken,
 } from '../Layout/padding.stylex';
+import {subscribeInput} from '../utils/inputStream';
 import type {SpacingStep} from '../utils/types';
 import {
   isValidSnapPoint,
@@ -82,8 +84,20 @@ const HEIGHT_BUDGETS = {
 export type BottomSheetHeight = keyof typeof HEIGHT_BUDGETS;
 export type {BottomSheetSnapPoint};
 
-// SYNC: must match OVERSCROLL_MAX in useSheetGestures.ts.
-const OVERSCROLL_PADDING = 48;
+// The reserve: how far the sheet's surface reaches below the screen, so a
+// pull past the top never shows the page under it.
+// SYNC: OVERSCROLL_MAX in useSheetGestures.ts must not exceed MIN_RESERVE.
+const MIN_RESERVE = 48;
+// A finger can pull past the top by at most the viewport's height. The rubber
+// band over a sheet as tall as the viewport then shows 35.5% of it.
+const RESERVE_VIEWPORT_SHARE = 0.4;
+
+function sheetReserve(viewportHeight: number): number {
+  return Math.max(
+    MIN_RESERVE,
+    Math.ceil(viewportHeight * RESERVE_VIEWPORT_SHARE),
+  );
+}
 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
@@ -92,6 +106,22 @@ const TRANSITION_BACKSTOP_BUFFER_MS = 50;
 // padding already provides.
 const HANDLE_BAR_HEIGHT = spacingVars['--spacing-6'];
 
+const BLOCK_SIZE_PROPERTIES = [
+  'height',
+  'minHeight',
+  'maxHeight',
+  'blockSize',
+  'minBlockSize',
+  'maxBlockSize',
+] as const;
+
+/** Whether StyleX styles hold any style: they can nest in arrays. */
+function hasStyles(xstyle: unknown): boolean {
+  return Array.isArray(xstyle)
+    ? xstyle.some(hasStyles)
+    : xstyle != null && typeof xstyle === 'object';
+}
+
 // Measure the viewport that the height budgets use. They are `dvh`, which
 // the virtual keyboard does not shrink, so `visualViewport` would differ by
 // the keyboard's height. `useMobileKeyboard` handles the keyboard and does
@@ -100,6 +130,14 @@ function layoutViewportHeight(): number {
   return typeof window === 'undefined' ? 0 : window.innerHeight;
 }
 
+function subscribeToResize(onChange: () => void): () => void {
+  return subscribeInput(window, 'resize', onChange);
+}
+
+function subscribeToNothing(): () => void {
+  return () => {};
+}
+
 /**
  * A stable identity for a set of snap points. Type-tagged, so the fraction
  * `0.5` and the (invalid) string `'0.5'` cannot collide on one key.
@@ -159,8 +197,8 @@ const styles = stylex.create({
     boxShadow: shadowVars['--shadow-high'],
     outline: 'none',
     overflow: 'hidden',
-    paddingBlockEnd: `calc(env(safe-area-inset-bottom, 0px) + ${OVERSCROLL_PADDING}px)`,
-    marginBlockEnd: `${-OVERSCROLL_PADDING}px`,
+    paddingBlockEnd: `calc(env(safe-area-inset-bottom, 0px) + var(--_sheet-reserve, ${MIN_RESERVE}px))`,
+    marginBlockEnd: `calc(-1 * var(--_sheet-reserve, ${MIN_RESERVE}px))`,
     // Under reduced motion no transform runs. On a coarse primary pointer the
     // entrance is an opacity cross-fade of at most 200 ms. A fine pointer gets
     // the change at once (the 0.01s collapse).
@@ -340,11 +378,11 @@ const styles = stylex.create({
     },
   }),
   budget: {
-    height: `calc(var(--_sheet-budget) + ${OVERSCROLL_PADDING}px)`,
+    height: `calc(var(--_sheet-budget) + var(--_sheet-reserve, ${MIN_RESERVE}px))`,
   },
   hugHeight: {
     height: 'fit-content',
-    maxHeight: `calc(${HEIGHT_BUDGETS.hug} + ${OVERSCROLL_PADDING}px)`,
+    maxHeight: `calc(${HEIGHT_BUDGETS.hug} + var(--_sheet-reserve, ${MIN_RESERVE}px))`,
   },
 });
 
@@ -649,6 +687,24 @@ export function BottomSheetPanel({
 
   // A caller's height owns the element's height: the drag never writes it.
   const consumerHeight = style?.height;
+  // StyleX styles and a class name can size the sheet too. Their rules are
+  // only class names here, so any of them counts as a size.
+  const isSizedByCaller =
+    BLOCK_SIZE_PROPERTIES.some(property => style?.[property] != null) ||
+    hasStyles(xstyle) ||
+    (className != null && className !== '');
+  // Only a finger stretches the sheet past MIN_RESERVE, so a device with no
+  // touch pointer keeps the smallest reserve. So does a sheet the caller
+  // sizes, which nothing extends by the reserve; the stretch stops at it.
+  const hasTouchPointer = useMediaQuery('(any-pointer: coarse)');
+  const tracksViewport = isPresented && hasTouchPointer && !isSizedByCaller;
+  const viewportHeight = useSyncExternalStore(
+    tracksViewport ? subscribeToResize : subscribeToNothing,
+    () => (tracksViewport ? layoutViewportHeight() : 0),
+    () => 0,
+  );
+  const reserve =
+    viewportHeight > 0 ? sheetReserve(viewportHeight) : MIN_RESERVE;
   const {
     contentProps,
     handleProps,
@@ -668,7 +724,7 @@ export function BottomSheetPanel({
     isOpen: isInteractive,
     isOpenRequested: isOpenRequested ?? isInteractive,
     canDismiss: isSwipeDismissAllowed,
-    offscreenBlockEndInset: OVERSCROLL_PADDING,
+    offscreenBlockEndInset: reserve,
     onDismiss,
     snapHeights,
     onTravelStart: () => {
@@ -931,6 +987,7 @@ export function BottomSheetPanel({
         className,
         {
           ['--_sheet-budget' as string]: budget,
+          ['--_sheet-reserve' as string]: `${reserve}px`,
           ...(isInteractive
             ? gestureStyle
             : isRetained || isClosing

package/src/BottomSheet/bottomSheetStack.ts

@@ -4,7 +4,8 @@
 
 /**
  * @file bottomSheetStack.ts
- * @input The DOM (dialog elements, document order) and focusForLastInput
+ * @input The DOM (dialog elements, document order) and the focus-return
+ *   utilities
  * @output The private bottom-sheet stack registry: host registration,
  *   open-order ranking, top-layer reconciliation, one view per host, the
  *   replace handoff, and the shared native show/hide and focus helpers
@@ -50,7 +51,7 @@
 // version keeps its own stack. Each document is its own stack.
 
 import {notifyTopLayerEntry} from '../Layer/modalOutlet';
-import {focusForLastInput} from '../utils/focusReturn';
+import {focusForLastInput, returnFocusForLastInput} from '../utils/focusReturn';
 
 export interface BottomSheetStackView {
   /** Another modal sheet is presented alongside this one. */
@@ -458,7 +459,7 @@ function completeClosingGroup(group: ClosingGroup): void {
   group.reported = true;
   const target = group.returnTarget;
   if (target != null && target.isConnected) {
-    focusForLastInput(target);
+    returnFocusForLastInput(target);
   }
 }
 

package/src/BottomSheet/useSheetGestures.ts

@@ -64,6 +64,8 @@ import {
   type UIEvent as ReactUIEvent,
 } from 'react';
 
+import {rubberBand} from '../motion/rubberBand';
+import {scroll} from '../motion/uikit/scroll';
 import {
   computeDetentOffsets,
   peekOffsetFor,
@@ -112,12 +114,19 @@ function isSyntheticTouch(event: ReactPointerEvent): boolean {
   return (event as SyntheticTouchPointer).syntheticTouch === true;
 }
 
-// Rubber-band factor for dragging up past fully-open, capped at OVERSCROLL_MAX
-// (the sheet reserves that much bottom padding for the lift to reveal).
+type StylusTouch = Touch & {touchType?: string};
+
+// An Apple Pencil raises touch events too, marked `stylus`. Its drag is a
+// pen's, as on the grabber, where WebKit reports it as a pen.
+function touchPointerType(touch: Touch): string {
+  return (touch as StylusTouch).touchType === 'stylus' ? 'pen' : 'touch';
+}
+
+// A mouse's or a pen's stretch past fully open: a resisted fraction of the
+// drag, capped at OVERSCROLL_MAX.
 const OVERSCROLL_RESISTANCE = 0.35;
-// SYNC: must match OVERSCROLL_PADDING in BottomSheetPanel.tsx (the reserved
-// bottom padding the lift reveals). Kept as a local const rather than a shared
-// import so it can be used inside stylex.create there.
+// SYNC: must not exceed MIN_RESERVE in BottomSheetPanel.tsx, the smallest
+// reserve the sheet keeps below the screen.
 const OVERSCROLL_MAX = 48;
 // Travel past the point where a scrolling gesture ran out of content before it
 // hands the sheet the rest of the pull. Small enough to feel continuous with
@@ -308,6 +317,36 @@ function chainAtBottom(chain: ReadonlyArray<HTMLElement>): boolean {
   return chain.every(elementAtBottom);
 }
 
+function chainScrolls(chain: ReadonlyArray<HTMLElement>): boolean {
+  return chain.some(element => element.scrollHeight - element.clientHeight > 1);
+}
+
+/**
+ * iOS rubber-bands a scroller past its end even under `overscroll-behavior:
+ * contain`. While the content sits at its end mid-pull, `none` holds it still,
+ * so only the sheet moves. Returns the undo.
+ */
+function holdAtEnd(chain: ReadonlyArray<HTMLElement>): () => void {
+  const previous = chain.map(element => element.style.overscrollBehaviorY);
+  for (const element of chain) {
+    element.style.overscrollBehaviorY = 'none';
+  }
+  return () => {
+    chain.forEach((element, index) => {
+      element.style.overscrollBehaviorY = previous[index];
+    });
+  };
+}
+
+function releaseContentHold(
+  armed: {releaseContentHold: (() => void) | null} | null,
+): void {
+  if (armed?.releaseContentHold != null) {
+    armed.releaseContentHold();
+    armed.releaseContentHold = null;
+  }
+}
+
 function visibleHeightForOffset(
   sheetHeight: number,
   offset: number,
@@ -690,6 +729,8 @@ export function useSheetGestures({
     samples: {t: number; y: number}[];
     velocity: number;
     height: number;
+    /** The surface kept below the screen when the drag began. */
+    reserve: number;
     baseOffset: number;
     baseLayoutOffset: number;
     renderedOffset: number;
@@ -1171,7 +1212,7 @@ export function useSheetGestures({
       const baseLayoutOffset = settledLayoutOffsetRef.current;
       dragStateRef.current = {
         syntheticTouch,
-        pointerType: syntheticTouch ? 'touch' : event.pointerType,
+        pointerType: event.pointerType,
         pointerId: event.pointerId,
         startCoord: start,
         lastCoord: event.clientY,
@@ -1179,6 +1220,7 @@ export function useSheetGestures({
         samples: [{t: event.timeStamp, y: event.clientY}],
         velocity: 0,
         height: sheetHeight,
+        reserve: offscreenBlockEndInsetRef.current,
         baseOffset: settledOffset,
         baseLayoutOffset,
         renderedOffset: settledOffset,
@@ -1279,8 +1321,19 @@ export function useSheetGestures({
       const maxDetentOffset = offsets[offsets.length - 1];
       let next: number;
       if (raw < 0) {
-        // Up past fully-open: damped + capped rubber-band; springs back on release.
-        next = Math.max(-OVERSCROLL_MAX, raw * OVERSCROLL_RESISTANCE);
+        // A touch device's reserve covers the whole stretch. The clamp binds
+        // only where the reserve is short.
+        next =
+          state.pointerType === 'touch'
+            ? Math.max(
+                -state.reserve,
+                rubberBand(
+                  raw,
+                  state.height - state.reserve,
+                  scroll.rubberBand.coefficient,
+                ),
+              )
+            : Math.max(-OVERSCROLL_MAX, raw * OVERSCROLL_RESISTANCE);
       } else if (raw > maxDetentOffset) {
         // In the dismiss zone: no magnet, so it doesn't fight a drag-to-close.
         next = raw;
@@ -1482,6 +1535,8 @@ export function useSheetGestures({
     // armed at `touchstart`. That drag never cancelled the native scroll, so
     // it has to yield again if the finger comes back down.
     promotedAtContentEnd: boolean;
+    // Null while no hold is set.
+    releaseContentHold: (() => void) | null;
   } | null>(null);
   const previousTouchHandlersRef = useRef<{
     start: (e: TouchEvent) => void;
@@ -1495,6 +1550,7 @@ export function useSheetGestures({
   // the gesture; the sheet returns to its detent.
   const yieldToPinch = useCallback(
     (target?: HTMLElement) => {
+      releaseContentHold(touchDragRef.current);
       touchDragRef.current = null;
       armedBodyRef.current = null;
       cancelDrag(target);
@@ -1522,6 +1578,7 @@ export function useSheetGestures({
       ({
         syntheticTouch: true,
         pointerId: touch.identifier,
+        pointerType: touchPointerType(touch),
         clientY: touch.clientY,
         timeStamp: Date.now(),
         currentTarget: target,
@@ -1542,21 +1599,21 @@ export function useSheetGestures({
       // scroll, but it is tracked all the same: the scroller can run out of
       // content while the finger is still down (see onTouchMove). A touch
       // inside a layer this sheet hosts is that layer's, never tracked here.
+      releaseContentHold(touchDragRef.current);
       if (!touch || isInsideNestedLayer(event.target, body)) {
         touchDragRef.current = null;
         return;
       }
       const scrollers = scrollChainUnder(event.target, body);
       const top = chainAtTop(scrollers);
-      // The bottom edge hands off so the sheet can EXPAND, so it is only a
-      // handoff when a taller detent exists. Already at the tallest, an
-      // upward pull has nowhere to travel: promoting it would trade the
-      // user's scroll for a rubber-band the release throws straight back, and
-      // — because promotion preventDefault()s the rest of the gesture — would
-      // strand the scroller for as long as the finger stays down, so reversing
-      // downward to scroll back would collapse the sheet instead. Leave the
-      // gesture with the content.
-      const bottom = chainAtBottom(scrollers) && activeOffsetRef.current > 0;
+      // Claiming a pull up from its first move blocks the content's scroll for
+      // the whole touch. So it is claimed here only below the tallest detent,
+      // or over content that cannot scroll. At the tallest detent, a list at
+      // its end keeps its touch. Its pull reaches the sheet through the
+      // content-end hand-off below, and a reversal hands it back.
+      const bottom =
+        chainAtBottom(scrollers) &&
+        (activeOffsetRef.current > 0 || !chainScrolls(scrollers));
       touchDragRef.current = {
         id: touch.identifier,
         startY: touch.clientY,
@@ -1565,6 +1622,7 @@ export function useSheetGestures({
         bottom,
         contentEndY: null,
         promotedAtContentEnd: false,
+        releaseContentHold: null,
       };
     };
 
@@ -1594,6 +1652,7 @@ export function useSheetGestures({
             // at once; a later pull past the end promotes again.
             armed.contentEndY = null;
             armed.promotedAtContentEnd = false;
+            releaseContentHold(armed);
             cancelDragRef.current(scroller);
             return;
           }
@@ -1627,6 +1686,7 @@ export function useSheetGestures({
         chainAtBottom(armed.scrollers);
       if (pullDownAtTop || pullUpAtBottom) {
         event.preventDefault();
+        releaseContentHold(armed);
         touchDragRef.current = null;
         beginDragRef.current(
           asPointer(t, scroller),
@@ -1646,13 +1706,14 @@ export function useSheetGestures({
       // cannot see this, and re-arming for a preventDefault() promotion would
       // be useless anyway: once the browser has committed the gesture to
       // scrolling, every remaining touchmove is non-cancelable. Nothing needs
-      // cancelling either — the scroller is clamped at its maximum, so further
-      // upward travel scrolls nothing. Anchor at the point where the content
+      // cancelling either: the hold clamps the scroller at its maximum, so
+      // further upward travel scrolls nothing. Anchor at the point where the content
       // ran out and give the sheet everything past it, so the pull continues
       // into the sheet with no jump and no lost scrolling.
-      if (activeOffsetRef.current > 0 && chainAtBottom(armed.scrollers)) {
+      if (chainAtBottom(armed.scrollers)) {
         if (armed.contentEndY == null) {
           armed.contentEndY = t.clientY;
+          armed.releaseContentHold ??= holdAtEnd(armed.scrollers);
         } else if (armed.contentEndY - t.clientY >= CONTENT_END_HANDOFF_SLOP) {
           armed.promotedAtContentEnd = true;
           beginDragRef.current(
@@ -1664,10 +1725,12 @@ export function useSheetGestures({
         }
       } else {
         armed.contentEndY = null;
+        releaseContentHold(armed);
       }
     };
 
     const onTouchEnd = (event: TouchEvent) => {
+      releaseContentHold(touchDragRef.current);
       touchDragRef.current = null;
       const pointerId = dragStateRef.current?.pointerId;
       if (pointerId == null) {