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

package/dist/hooks/useMenuPress.js

@@ -6,7 +6,8 @@
  * @file useMenuPress.ts
  * @input The menu root, its trigger, the enabled-row selector, and callbacks
  *   for opening, highlighting, activating and dismissing
- * @output useMenuPress, the marker attributes, and the activation mark
+ * @output useMenuPress, the marker attributes, the activation mark, and the
+ *   internal useDropdownMenuPress entry with its touch model
  * @position Core hook for DropdownMenu, ContextMenu, DropdownMenuSubMenu,
  *   Selector and MenuBottomSheetActionList. The transition table lives in
  *   menuPressGesture.ts.
@@ -19,13 +20,14 @@
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { currentGesture } from "../Layer/gestureCounter.js";
-import { IDLE_MENU_PRESS, menuPressStep } from "./menuPressGesture.js";
+import { IDLE_MENU_PRESS, menuPressTransition } from "./menuPressGesture.js";
 import { MENU_PRESS_MARKER } from "./menuPressMarker.js";
 import { useLongPressDetector } from "./useLongPress.js";
 import { edgeAutoscroll } from "../utils/edgeAutoscroll.js";
 import { focusForLastInput } from "../utils/focusReturn.js";
 import { useInteractionModalityTrackingFor } from "../utils/interactionModality.js";
 import { LONG_PRESS_DURATION_MS } from "../motion/uikit/longPress.js";
+import { clearMenuPressLit, holdMenuPressPaint, markMenuPressLit, releaseMenuPressPaint } from "../privateAttributes/menuPressLit.stylex.js";
 import { __resetClickGuardForTest, armClickGuard, CLICK_GUARD_WINDOW_MS, withoutClickGuard } from "../utils/clickGuard.js";
 export { MENU_PRESS_MARKER };
 const MENU_PRESS_ROOT_SELECTOR = `[${MENU_PRESS_MARKER}]`;
@@ -124,6 +126,34 @@ function isInMenuTree(element, root) {
   const owner = element.closest(MENU_PRESS_ROOT_SELECTOR);
   return owner != null && getOutermostRoot(owner) === root;
 }
+
+/**
+ * DropdownMenu's options for the press model: everything the public hook
+ * takes, plus its touch model. DropdownMenu reaches the touch model through
+ * its `presentation`, so the public hook has no such option.
+ *
+ * @internal
+ */
+
+/**
+ * What core's own menus get from {@link useDropdownMenuPress}: the public
+ * return. Not exported from the hooks entry point.
+ *
+ * @internal
+ */
+
+/**
+ * Where a pointer is, for a finger's handoff distance. Positions reach the
+ * machine only under `touchModel: 'uikit'`. Without them, it keeps the settle
+ * rule.
+ */
+function handoffPosition(event, hasHandoff) {
+  return hasHandoff ? {
+    x: event.clientX,
+    y: event.clientY
+  } : {};
+}
+
 /**
  * The press model for a menu: the row under the release acts, the highlight
  * follows a held pointer, and a mouse opens the menu on press.
@@ -160,6 +190,26 @@ function isInMenuTree(element, root) {
  * ```
  */
 export function useMenuPress(options) {
+  // The touch model is DropdownMenu's alone; an untyped caller's
+  // `touchModel` does not reach the model.
+  const {
+    touchModel: _touchModel,
+    ...publicOptions
+  } = options;
+  return useDropdownMenuPress({
+    ...publicOptions,
+    touchModel: 'pointer'
+  });
+}
+
+/**
+ * The press model with DropdownMenu's touch model
+ * ({@link DropdownMenuPressOptions.touchModel}). Not exported from the hooks
+ * entry point.
+ *
+ * @internal
+ */
+export function useDropdownMenuPress(options) {
   const optionsRef = useRef(options);
   optionsRef.current = options;
   // The highlight, and the hover focus of the rows in this menu, follow the
@@ -247,8 +297,18 @@ export function useMenuPress(options) {
     autoscroll.stop();
     autoscrollRef.current = null;
   }, [autoscroll]);
+  const litRowRef = useRef(null);
+  const heldMenuRef = useRef(null);
   const endGesture = useCallback(() => {
     longPressApiRef.current?.cancel();
+    if (litRowRef.current != null) {
+      clearMenuPressLit(litRowRef.current);
+      litRowRef.current = null;
+    }
+    if (heldMenuRef.current != null) {
+      releaseMenuPressPaint(heldMenuRef.current);
+      heldMenuRef.current = null;
+    }
     touchMovePreventerRef.current?.();
     touchMovePreventerRef.current = null;
     stopAutoscroll();
@@ -259,10 +319,36 @@ export function useMenuPress(options) {
     gestureRef.current = IDLE_MENU_PRESS;
   }, [stopAutoscroll]);
   const highlight = useCallback(row => {
+    // A held finger or pen marks the row it lights, for the row's pressed
+    // paint. A held mouse keeps the hover tint, as on a desktop.
+    const gesture = gestureRef.current;
+    const isHeld = gesture.phase !== 'idle' && gesture.pointerType !== 'mouse';
+    const lit = isHeld ? row : null;
+    if (litRowRef.current !== lit) {
+      if (litRowRef.current != null) {
+        clearMenuPressLit(litRowRef.current);
+      }
+      litRowRef.current = lit;
+      if (lit != null) {
+        markMenuPressLit(lit);
+      }
+    }
     const {
       onHighlight,
       menuRef
     } = optionsRef.current;
+    // The row the press began on stays :active where a pointer hovers, so
+    // the menu holds every row but the lit one off that paint.
+    const held = isHeld ? menuRef.current : null;
+    if (heldMenuRef.current !== held) {
+      if (heldMenuRef.current != null) {
+        releaseMenuPressPaint(heldMenuRef.current);
+      }
+      heldMenuRef.current = held;
+      if (held != null) {
+        holdMenuPressPaint(held);
+      }
+    }
     if (onHighlight != null) {
       onHighlight(row);
       return;
@@ -369,7 +455,7 @@ export function useMenuPress(options) {
     }
   }, [activate, endGesture, getDocument, highlight]);
   const step = useCallback((event, native) => {
-    const result = menuPressStep(gestureRef.current, event);
+    const result = menuPressTransition(gestureRef.current, event);
     gestureRef.current = result.gesture;
     applyEffect(result.effect, result.gesture, native);
   }, [applyEffect]);
@@ -466,7 +552,8 @@ export function useMenuPress(options) {
         type: 'move',
         row: point.row,
         isInMenu: point.isInMenu,
-        time: Date.now()
+        time: Date.now(),
+        ...handoffPosition(event, optionsRef.current.touchModel === 'uikit')
       }, event);
       updateAutoscroll(event);
     };
@@ -480,7 +567,8 @@ export function useMenuPress(options) {
         row: point.row,
         isInMenu: point.isInMenu,
         isOnTrigger: point.isOnTrigger,
-        time: Date.now()
+        time: Date.now(),
+        ...handoffPosition(event, optionsRef.current.touchModel === 'uikit')
       }, event);
     };
     const onCancel = event => {

package/dist/hooks/useOverflow.d.ts

@@ -74,4 +74,14 @@ export interface UseOverflowReturn {
  * ```
  */
 export declare function useOverflow(itemCount: number, options?: UseOverflowOptions): UseOverflowReturn;
+/**
+ * `useOverflow` for a host inside Core that states whether it renders from
+ * `rows` and `rowHeight`. With `tracksRows` false, the hook does not track
+ * them and reports `rows: 1` and `rowHeight: 0`. A state write that nobody
+ * reads still re-renders the host. Internal: the public hook always tracks
+ * them.
+ */
+export declare function useOverflowInternal(itemCount: number, options: UseOverflowOptions, { tracksRows }: {
+    tracksRows: boolean;
+}): UseOverflowReturn;
 //# sourceMappingURL=useOverflow.d.ts.map

package/dist/hooks/useOverflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOverflow.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAE/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,wDAAwD;IACxD,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC3C,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAiKnB"}
+{"version":3,"file":"useOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOverflow.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAE/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,wDAAwD;IACxD,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC3C,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;CACnB;AA6JD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAEnB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,EAC3B,EAAC,UAAU,EAAC,EAAE;IAAC,UAAU,EAAE,OAAO,CAAA;CAAC,GAClC,iBAAiB,CA2OnB"}

package/dist/hooks/useOverflow.js

@@ -4,7 +4,8 @@
 
 /**
  * @file useOverflow.ts
- * @input Uses React useState, useCallback, useRef; useIsomorphicLayoutEffect
+ * @input Uses React useState, useCallback, useRef; react-dom flushSync;
+ *   useIsomorphicLayoutEffect
  * @output Exports useOverflow hook for measuring and managing horizontal overflow
  * @position Core hook; used by OverflowList and consumers for overflow patterns.
  *   Hidden copies of the children are measured, so nothing flickers. The
@@ -15,10 +16,138 @@
  * - /packages/core/src/hooks/computeOverflow.ts (the pure computation)
  */
 import { useState, useCallback, useRef } from 'react';
+import { flushSync } from 'react-dom';
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 import { observeResize } from "../utils/sharedResizeObserver.js";
-import { computeOverflow } from "./computeOverflow.js";
+import { computeOverflow, countRows } from "./computeOverflow.js";
 import { useDevWarning } from "./useDevWarning.js";
+
+// A measurement either applies its result at once or returns the update to
+// apply after the frame paints.
+
+// Measurements that the resize observer reported in the current frame.
+const pendingMeasures = new Set();
+
+/**
+ * Measures again for a resize the observer reported.
+ *
+ * The observer reports after layout and before paint. A state update here
+ * renders in a later task, after the frame paints. A microtask still runs
+ * before paint. It measures every reported list and renders the results once.
+ * An update that a measurement returns renders in a later task, after paint.
+ */
+function measureBeforePaint(measure) {
+  if (pendingMeasures.size === 0) {
+    queueMicrotask(() => {
+      const measures = [...pendingMeasures];
+      pendingMeasures.clear();
+      const afterPaint = [];
+      // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the new visible set must render before the frame that reported the resize paints
+      flushSync(() => {
+        for (const run of measures) {
+          const deferred = run('beforePaint');
+          if (deferred) {
+            afterPaint.push(deferred);
+          }
+        }
+      });
+      for (const update of afterPaint) {
+        update();
+      }
+    });
+  }
+  pendingMeasures.add(measure);
+}
+
+/**
+ * The registration call runs while React commits the ref, before paint, so it
+ * measures at once.
+ */
+function observeForOverflow(element, measure) {
+  let isRegistering = true;
+  const unobserve = observeResize(element, () => {
+    if (isRegistering) {
+      measure('now');
+    } else {
+      measureBeforePaint(measure);
+    }
+  });
+  isRegistering = false;
+  return unobserve;
+}
+
+/** A visible set as the list renders it, sized from the measure copy. */
+
+/**
+ * The rows a set fills at `availableWidth`, up to `maxRows`, or `null` when
+ * they are not known. The measured indicator holds every item, so the
+ * rendered one can be narrower. When the rows with and without it differ,
+ * the rows are not known.
+ */
+function rowsFilled(set, gap, availableWidth, maxRows) {
+  const rowsWithout = Math.min(countRows(set.widths, gap, availableWidth), maxRows);
+  if (!set.indicator) {
+    return rowsWithout;
+  }
+  const widths = set.indicatorFirst ? [set.indicator.width, ...set.widths] : [...set.widths, set.indicator.width];
+  const rowsWith = Math.min(countRows(widths, gap, availableWidth), maxRows);
+  return rowsWith === rowsWithout ? rowsWith : null;
+}
+
+/**
+ * The list's height follows its tallest child and, in a multi-row list, the
+ * rows it fills.
+ */
+function canChangeListHeight(now, next, gap, availableWidth, maxRows) {
+  const tallest = set => Math.max(0, ...set.heights, set.indicator?.height ?? 0);
+  if (tallest(now) !== tallest(next)) {
+    return true;
+  }
+  if (maxRows <= 1) {
+    return false;
+  }
+  const rowsNow = rowsFilled(now, gap, availableWidth, maxRows);
+  const rowsNext = rowsFilled(next, gap, availableWidth, maxRows);
+  return rowsNow === null || rowsNext === null || rowsNow !== rowsNext;
+}
+
+/**
+ * Whether the observed element's size follows the list's items: a list in a
+ * flex item sized from its content, a shrink-to-fit box, or such an ancestor.
+ * A fold then changes an observed size, so it cannot render inside the
+ * observer step. Size containment drops the items' contribution to the
+ * list's inline size, so a size that moves under it follows the items. The
+ * probe reverts at once, before any observer or the frame can see it.
+ */
+function observedSizeFollowsItems(list, observed) {
+  const style = list.style;
+  if (style == null || typeof style.setProperty !== 'function') {
+    return false;
+  }
+  const hadStyleAttribute = list.hasAttribute('style');
+  const value = style.getPropertyValue('contain');
+  const priority = style.getPropertyPriority('contain');
+  const width = observed.offsetWidth;
+  const height = observed.offsetHeight;
+  style.setProperty('contain', 'inline-size', 'important');
+  const follows = observed.offsetWidth !== width || observed.offsetHeight !== height;
+  if (value !== '') {
+    style.setProperty('contain', value, priority);
+  } else if (hadStyleAttribute) {
+    style.removeProperty('contain');
+  } else {
+    style.removeProperty('contain');
+    // Chromium writes the inline style back to the attribute lazily. Reading
+    // the attribute first stops the removal from leaving `style=""`.
+    void list.getAttribute('style');
+    list.removeAttribute('style');
+  }
+  // Lay out again now. A later observer in this delivery reads the current
+  // layout without updating it, so it would get the contained size.
+  void observed.offsetWidth;
+  return follows;
+}
+
 /**
  * Hook for managing horizontal overflow of a list of items.
  *
@@ -38,6 +167,21 @@ import { useDevWarning } from "./useDevWarning.js";
  * ```
  */
 export function useOverflow(itemCount, options = {}) {
+  return useOverflowInternal(itemCount, options, {
+    tracksRows: true
+  });
+}
+
+/**
+ * `useOverflow` for a host inside Core that states whether it renders from
+ * `rows` and `rowHeight`. With `tracksRows` false, the hook does not track
+ * them and reports `rows: 1` and `rowHeight: 0`. A state write that nobody
+ * reads still re-renders the host. Internal: the public hook always tracks
+ * them.
+ */
+export function useOverflowInternal(itemCount, options, {
+  tracksRows
+}) {
   const {
     gap = 0,
     minVisibleItems = 0,
@@ -51,13 +195,40 @@ export function useOverflow(itemCount, options = {}) {
   const [visibleCount, setVisibleCount] = useState(itemCount);
   const [rows, setRows] = useState(1);
   const [rowHeight, setRowHeight] = useState(0);
+  // The values last written to state. A measurement that matches them writes
+  // nothing, so a resize that changes nothing renders nothing.
+  const appliedRef = useRef({
+    visibleCount: itemCount,
+    rows: 1,
+    rowHeight: 0
+  });
   const containerElRef = useRef(null);
   const measureElRef = useRef(null);
   const observedElRef = useRef(null);
   const observedMeasureElRef = useRef(null);
   const unobserveContainerRef = useRef(null);
   const unobserveMeasureRef = useRef(null);
-  const calculate = useCallback(() => {
+  const apply = useCallback((nextVisible, nextRows, nextRowHeight) => {
+    const applied = appliedRef.current;
+    if (applied.visibleCount !== nextVisible) {
+      applied.visibleCount = nextVisible;
+      setVisibleCount(nextVisible);
+    }
+    // A host that does not track rows renders from neither value, so they
+    // are not written.
+    if (!tracksRows) {
+      return;
+    }
+    if (applied.rows !== nextRows) {
+      applied.rows = nextRows;
+      setRows(nextRows);
+    }
+    if (applied.rowHeight !== nextRowHeight) {
+      applied.rowHeight = nextRowHeight;
+      setRowHeight(nextRowHeight);
+    }
+  }, [tracksRows]);
+  const calculate = useCallback((timing = 'now') => {
     const container = containerElRef.current;
     const measure = measureElRef.current;
     if (!container || !measure) {
@@ -79,10 +250,7 @@ export function useOverflow(itemCount, options = {}) {
     const children = hasIndicator ? allChildren.slice(0, itemCount) : allChildren;
     const indicatorWidth = hasIndicator ? allChildren[allChildren.length - 1].offsetWidth : 0;
     if (children.length === 0) {
-      // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
-      setVisibleCount(0);
-      // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
-      setRows(0);
+      apply(0, 0, appliedRef.current.rowHeight);
       return;
     }
     const widths = children.map(child => child.offsetWidth);
@@ -101,13 +269,38 @@ export function useOverflow(itemCount, options = {}) {
       collapseFrom
     });
 
-    // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
-    setVisibleCount(nextVisible);
-    // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
-    setRows(prev => prev === nextRows ? prev : nextRows);
-    // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
-    setRowHeight(prev => prev === measuredRowHeight ? prev : measuredRowHeight);
-  }, [itemCount, gap, minVisibleItems, maxVisibleItems, maxRows, collapseFrom, observeParent]);
+    // Folding to a new list height inside the resize step makes Chromium
+    // report a loop error. That update renders after paint. The measure copy
+    // sizes both sets, a plain-text indicator included.
+    if (timing === 'beforePaint') {
+      const indicator = hasIndicator ? allChildren[allChildren.length - 1] : null;
+      const renderedSet = count => {
+        const shown = collapseFrom === 'end' ? children.slice(0, count) : children.slice(children.length - count);
+        return {
+          widths: shown.map(child => child.offsetWidth),
+          heights: shown.map(child => child.offsetHeight || 0),
+          indicator: indicator && count < itemCount ? {
+            width: indicatorWidth,
+            height: indicator.offsetHeight || 0
+          } : null,
+          indicatorFirst: collapseFrom === 'start'
+        };
+      };
+      // Under observeParent the list fills its parent's width only while
+      // items are collapsed. A fold that shows or hides the indicator
+      // changes that width, which can change the observed parent's height
+      // when a sibling wraps.
+      const changesParentFill = observeParent && appliedRef.current.visibleCount < itemCount !== nextVisible < itemCount;
+      // A multi-row list's max height follows the measured row height.
+      const changesRowHeight = (maxRows ?? 1) > 1 && measuredRowHeight !== appliedRef.current.rowHeight;
+      const observed = observeParent && container.parentElement ? container.parentElement : container;
+      if (changesParentFill || changesRowHeight || nextVisible !== appliedRef.current.visibleCount && observedSizeFollowsItems(container, observed) || canChangeListHeight(renderedSet(appliedRef.current.visibleCount), renderedSet(nextVisible), gap, availableWidth, maxRows ?? 1)) {
+        return () => apply(nextVisible, nextRows, measuredRowHeight);
+      }
+    }
+    apply(nextVisible, nextRows, measuredRowHeight);
+    return undefined;
+  }, [itemCount, gap, minVisibleItems, maxVisibleItems, maxRows, collapseFrom, observeParent, apply]);
   const containerRef = useCallback(el => {
     containerElRef.current = el;
 
@@ -117,9 +310,7 @@ export function useOverflow(itemCount, options = {}) {
     observedElRef.current = null;
     if (el) {
       const target = observeParent && el.parentElement ? el.parentElement : el;
-      unobserveContainerRef.current = observeResize(target, () => {
-        calculate();
-      });
+      unobserveContainerRef.current = observeForOverflow(target, calculate);
       observedElRef.current = target;
     }
   }, [calculate, observeParent]);
@@ -131,16 +322,14 @@ export function useOverflow(itemCount, options = {}) {
     if (!el) {
       return;
     }
-    unobserveMeasureRef.current = observeResize(el, () => {
-      calculate();
-    });
+    unobserveMeasureRef.current = observeForOverflow(el, calculate);
     observedMeasureElRef.current = el;
   }, [calculate]);
 
   // Syncs the visible count with the rendered layout. It measures again after
   // the items change.
   useIsomorphicLayoutEffect(() => {
-    calculate();
+    calculate('now');
   }, [calculate]);
   const hasOverflow = visibleCount < itemCount;
   return {
@@ -148,7 +337,9 @@ export function useOverflow(itemCount, options = {}) {
     measureRef,
     visibleCount,
     hasOverflow,
-    rows,
-    rowHeight
+    // A host that stops tracking keeps state from earlier measurements, so
+    // the return uses the fixed values.
+    rows: tracksRows ? rows : 1,
+    rowHeight: tracksRows ? rowHeight : 0
   };
 }

package/dist/hooks/usePressFeedback.d.ts

@@ -7,11 +7,11 @@ import { pressableProps } from '../utils/pressFeedback.js';
  * `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same
  * element: `backgroundColor` or `backgroundImage` for a surface whose hover
  * and press are the system's overlays, `pressedBackgroundColor` for one
- * whose hover is its own. The controller writes its attribute on the element
- * while a touch press is believed (after the onset delay, cancelled by travel
- * or by a scroll) and for the release, and the composed style paints the
- * pressed token at the press's strength on the first frame and fades it over
- * the release, keeping `:active` for a mouse on a desktop. On a phone or
+ * whose hover is its own. Under a finger the controller tracks the press the
+ * way UIKit tracks a control and writes its
+ * attribute on the element while the press is held and for the release; the
+ * composed style paints the pressed token on the first frame and fades it
+ * over the release, keeping `:active` for a mouse on a desktop. On a phone or
  * tablet the stylesheet drops `:active` for every press, so the controller
  * also paints a mouse, trackpad or Space-key press there, at once. A press is
  * themed through `--color-overlay-pressed`, which the hold, the flash and the
@@ -27,7 +27,7 @@ import { pressableProps } from '../utils/pressFeedback.js';
  * @example
  * ```
  * const pressable = usePressFeedback();
- * return <div role="button" {...pressable} {...stylex.props(styles.row)} />;
+ * return <button {...pressable} {...stylex.props(styles.button)} />;
  * ```
  */
 export declare function usePressFeedback(): typeof pressableProps;

package/dist/hooks/usePressFeedback.js

@@ -25,11 +25,11 @@ import { installPressFeedback, pressableProps } from "../utils/pressFeedback.js"
  * `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same
  * element: `backgroundColor` or `backgroundImage` for a surface whose hover
  * and press are the system's overlays, `pressedBackgroundColor` for one
- * whose hover is its own. The controller writes its attribute on the element
- * while a touch press is believed (after the onset delay, cancelled by travel
- * or by a scroll) and for the release, and the composed style paints the
- * pressed token at the press's strength on the first frame and fades it over
- * the release, keeping `:active` for a mouse on a desktop. On a phone or
+ * whose hover is its own. Under a finger the controller tracks the press the
+ * way UIKit tracks a control and writes its
+ * attribute on the element while the press is held and for the release; the
+ * composed style paints the pressed token on the first frame and fades it
+ * over the release, keeping `:active` for a mouse on a desktop. On a phone or
  * tablet the stylesheet drops `:active` for every press, so the controller
  * also paints a mouse, trackpad or Space-key press there, at once. A press is
  * themed through `--color-overlay-pressed`, which the hold, the flash and the
@@ -45,7 +45,7 @@ import { installPressFeedback, pressableProps } from "../utils/pressFeedback.js"
  * @example
  * ```
  * const pressable = usePressFeedback();
- * return <div role="button" {...pressable} {...stylex.props(styles.row)} />;
+ * return <button {...pressable} {...stylex.props(styles.button)} />;
  * ```
  */
 export function usePressFeedback() {

package/dist/hooks/useScrollRegionProps.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file useScrollRegionProps.ts
+ * @input Whether a region may scroll, and the caller's role and label
+ * @output useScrollRegionProps: a ref for the region, and the role and
+ *   accessible name that the region carries while its content overflows
+ * @position Internal hook for LayoutContent, LayoutPanel and StackItem.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useScrollRegionProps.test.tsx
+ * - /packages/core/src/AppShell/observeMainOverflow.ts
+ */
+import { type AriaRole, type RefCallback } from 'react';
+export interface ScrollRegionOptions {
+    /** Whether the region may scroll at all (`overflow: auto`). */
+    isScrollable: boolean;
+    /** The caller's role. It always wins, and takes no default name. */
+    role?: AriaRole;
+    /** The caller's accessible name. It always wins. */
+    label?: string;
+}
+export interface ScrollRegionProps {
+    ref: RefCallback<HTMLElement>;
+    role: AriaRole | undefined;
+    'aria-label': string | undefined;
+}
+/**
+ * The region's ref, role and accessible name. While the region may scroll
+ * and its content overflows, it is a group named by the caller's `label`, or
+ * by the translated "Content". A caller's `role` is kept with only the
+ * caller's `label`: a single main landmark relies on its role alone. When
+ * the region does not scroll, the caller's own `role` and `label` pass
+ * through unchanged.
+ */
+export declare function useScrollRegionProps({ isScrollable, role, label, }: ScrollRegionOptions): ScrollRegionProps;
+//# sourceMappingURL=useScrollRegionProps.d.ts.map

package/dist/hooks/useScrollRegionProps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollRegionProps.d.ts","sourceRoot":"","sources":["../../src/hooks/useScrollRegionProps.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAwB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAC,MAAM,OAAO,CAAC;AAU7E,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAC9B,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,YAAY,EACZ,IAAI,EACJ,KAAK,GACN,EAAE,mBAAmB,GAAG,iBAAiB,CAsBzC"}

package/dist/hooks/useScrollRegionProps.js

@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useScrollRegionProps.ts
+ * @input Whether a region may scroll, and the caller's role and label
+ * @output useScrollRegionProps: a ref for the region, and the role and
+ *   accessible name that the region carries while its content overflows
+ * @position Internal hook for LayoutContent, LayoutPanel and StackItem.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useScrollRegionProps.test.tsx
+ * - /packages/core/src/AppShell/observeMainOverflow.ts
+ */
+import { useCallback, useState } from 'react';
+import { registerEnglishFallback, useComponentTranslator } from "../i18n/useComponentTranslator.js";
+import english from "../i18n/generated-english/hooks/useScrollRegionProps.generated.js";
+import { observeMainOverflow } from "../AppShell/observeMainOverflow.js";
+registerEnglishFallback(english);
+/**
+ * The region's ref, role and accessible name. While the region may scroll
+ * and its content overflows, it is a group named by the caller's `label`, or
+ * by the translated "Content". A caller's `role` is kept with only the
+ * caller's `label`: a single main landmark relies on its role alone. When
+ * the region does not scroll, the caller's own `role` and `label` pass
+ * through unchanged.
+ */
+export function useScrollRegionProps({
+  isScrollable,
+  role,
+  label
+}) {
+  const t = useComponentTranslator();
+  const [overflows, setOverflows] = useState(false);
+  // A caller's role takes no default name, so its region is not observed.
+  const hasRole = role != null;
+  const ref = useCallback(element => {
+    if (element == null || !isScrollable || hasRole) {
+      setOverflows(false);
+      return undefined;
+    }
+    return observeMainOverflow(element, setOverflows);
+  }, [hasRole, isScrollable]);
+  const isGroup = !hasRole && isScrollable && overflows;
+  return {
+    ref,
+    role: role ?? (isGroup ? 'group' : undefined),
+    'aria-label': label ?? (isGroup ? t('@astryx.scrollRegion.label') : undefined)
+  };
+}

package/dist/i18n/InternationalizationContext.d.ts

@@ -1,8 +1,14 @@
 import { getResolve } from './resolve.js';
 import type { Locale, MessagesByLocale, Overrides } from './types.js';
+import type { CalendarSystem } from '../utils/calendarSystem.js';
 export interface InternationalizationContextValue {
     locale: Locale;
     direction: 'ltr' | 'rtl';
+    /**
+     * The provider's requested calendar system. A context without it means
+     * Gregorian dates.
+     */
+    calendar?: CalendarSystem;
     messages: MessagesByLocale;
     overrides?: Overrides;
     translate: ReturnType<typeof getResolve>;