@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/hooks/modalAnnounce.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Whether what is written inside `dialog` reaches assistive technology: open
+ * as a modal, and not taken out of the accessibility tree by `inert` or
+ * `aria-hidden` — a BottomSheet, standalone or a switcher step, stays open
+ * through its exit motion in exactly that state.
+ */
+export declare function isExposed(dialog: HTMLDialogElement): boolean;
+export declare function notePresented(dialog: HTMLDialogElement): void;
+export declare function forgetPresented(dialog: HTMLDialogElement): void;
+export declare function releaseAllHeld(): void;
+/**
+ * Move whatever `dialog`'s containers hold that assistive technology has not
+ * had yet to the channel exposed now. Called when the dialog stops being
+ * exposed — closed, taken inert or `aria-hidden` for its exit, or unmounted
+ * while open — so a message sent just before is not lost (FR14).
+ */
+export declare function handOffUnexposed(dialog: HTMLDialogElement): void;
+//# sourceMappingURL=modalAnnounce.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modalAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/modalAnnounce.ts"],"names":[],"mappings":"AAqCA;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAM5D;AAyBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAQ7D;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAK/D;AAsHD,wBAAgB,cAAc,IAAI,IAAI,CAIrC;AA4BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAOhE"}

package/dist/hooks/modalAnnounce.js

@@ -0,0 +1,382 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file modalAnnounce.ts
+ * @input Uses the live-region internals of useAnnounce and DOM dialog state
+ * @output Installs the modal route into useAnnounce as it loads, and exports
+ *   the presentation bookkeeping ModalAnnounceProvider drives
+ * @position Core a11y internal (spec:AST-086 FR14): where a message from
+ *   inside an Astryx modal is heard. A dialog is exposed when it is open as
+ *   a modal and neither inert nor aria-hidden; the top-layer order is kept
+ *   by `open` alone; a message a dialog holds when it stops being exposed is
+ *   handed to the channel exposed then, or held while an exiting modal still
+ *   covers everything, and released at its real close; a covered modal is
+ *   not written to; a caller inside a modal being presented in this commit
+ *   waits one frame for the route. Loaded only by ModalAnnounceProvider, so
+ *   a component that calls useAnnounce and renders no modal does not carry
+ *   it.
+ *
+ * SYNC: not exported from /packages/core/src/hooks/index.ts.
+ */
+import { announceMessage, clearModalRegion, clearRegion, installModalRoute, isOpenModal, modalRegion, unexposedMessages, withdrawFromModalRegion, writeModalRegion } from "./useAnnounce.js";
+
+/**
+ * Whether what is written inside `dialog` reaches assistive technology: open
+ * as a modal, and not taken out of the accessibility tree by `inert` or
+ * `aria-hidden` — a BottomSheet, standalone or a switcher step, stays open
+ * through its exit motion in exactly that state.
+ */
+export function isExposed(dialog) {
+  return isOpenModal(dialog) && !dialog.inert && dialog.getAttribute('aria-hidden') !== 'true';
+}
+
+/**
+ * The nearest open native modal dialog among the Astryx modals enclosing a
+ * caller: a scrimless BottomSheet or Drawer is a dialog that is open but not
+ * modal, so the walk continues to the modal above it.
+ */
+function enclosingOpenModal(scope) {
+  for (let s = scope; s != null; s = s.parent) {
+    const dialog = s.dialogRef.current;
+    if (isOpenModal(dialog)) {
+      return dialog;
+    }
+  }
+  return null;
+}
+
+// The dialogs the providers have seen open, in the order they were last
+// presented. `showModal()` sets `open` as it is called, so the order of the
+// attribute records is the top-layer order, and the last one still open as a
+// modal is the modal on top.
+const presented = [];
+export function notePresented(dialog) {
+  const at = presented.indexOf(dialog);
+  if (at !== -1) {
+    presented.splice(at, 1);
+  }
+  if (dialog.open) {
+    presented.push(dialog);
+  }
+}
+export function forgetPresented(dialog) {
+  const at = presented.indexOf(dialog);
+  if (at !== -1) {
+    presented.splice(at, 1);
+  }
+}
+
+/**
+ * The modal on top among the ones Astryx renders: the last presented that is
+ * open, modal and exposed. One above it that is exiting (open, not exposed)
+ * is on its way out and does not count — the step the person went back to
+ * is on top while the step they left fades.
+ */
+function topExposedModal() {
+  for (let i = presented.length - 1; i >= 0; i -= 1) {
+    if (isExposed(presented[i])) {
+      return presented[i];
+    }
+  }
+  return null;
+}
+
+/**
+ * The channel exposed to the person right now, other than `except`, read
+ * down the top-layer order: the first dialog that is exposed is it; a dialog
+ * still open as a modal but not exposed — one running its exit above the
+ * rest — covers everything beneath it, so nothing is exposed yet
+ * (`'covered'`); the page body (`null`) is exposed once no native modal is
+ * open.
+ */
+function nextExposedChannel(except) {
+  for (let i = presented.length - 1; i >= 0; i -= 1) {
+    const dialog = presented[i];
+    if (dialog !== except && isExposed(dialog)) {
+      return dialog;
+    }
+    // `except` itself, still an open modal through its exit, covers what is
+    // beneath it as any other exiting modal does.
+    if (isOpenModal(dialog)) {
+      return 'covered';
+    }
+  }
+  // A modal presented in this same task is not in the list yet (its
+  // attribute record is delivered after the task): the document still knows
+  // it. With no presentation order to go by, the last such dialog in the
+  // document stands for the one on top.
+  let fallback = null;
+  for (const dialog of document.querySelectorAll('dialog')) {
+    if (dialog !== except && !presented.includes(dialog) && isExposed(dialog)) {
+      fallback = dialog;
+    }
+  }
+  return fallback;
+}
+
+/** Whether any native modal dialog is open in the document right now. */
+function isAnyModalOpen() {
+  for (const dialog of document.querySelectorAll('dialog')) {
+    if (isOpenModal(dialog)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Words waiting for an exiting modal's real close: their dialog has left
+// the accessibility tree for its exit but is still an open native modal, or
+// such a dialog covers the channel they would go to, so nothing is exposed
+// yet. They are delivered when a dialog closes (or theirs is exposed again).
+const held = new Map();
+function hold(dialog, message, politeness) {
+  let slot = held.get(dialog);
+  if (slot == null) {
+    slot = {
+      polite: [],
+      assertive: []
+    };
+    held.set(dialog, slot);
+  }
+  if (!slot[politeness].includes(message)) {
+    slot[politeness].push(message);
+  }
+}
+
+/** Drop what `dialog` holds for `politeness`: the owner took it back. */
+function dropHeld(dialog, politeness) {
+  const slot = held.get(dialog);
+  if (slot == null) {
+    return;
+  }
+  slot[politeness] = [];
+  if (slot.polite.length === 0 && slot.assertive.length === 0) {
+    held.delete(dialog);
+  }
+}
+
+/** Deliver what `dialog` held, now that a channel may be exposed. */
+function releaseHeld(dialog) {
+  const slot = held.get(dialog);
+  if (slot == null) {
+    return;
+  }
+  held.delete(dialog);
+  for (const politeness of ['polite', 'assertive']) {
+    if (slot[politeness].length > 0) {
+      const message = slot[politeness].join(' ');
+      if (isExposed(dialog)) {
+        announceInModalRouted(dialog, message, politeness);
+      } else {
+        // Holds again if still nothing is exposed.
+        deliverBeyond(dialog, message, politeness);
+      }
+    }
+  }
+}
+export function releaseAllHeld() {
+  for (const dialog of [...held.keys()]) {
+    releaseHeld(dialog);
+  }
+}
+
+/**
+ * Deliver `message` through the channel exposed now that `dialog` is not:
+ * the modal on top, the page body once no modal is open, or — while the
+ * dialog is still an open modal through its exit, with nothing exposed —
+ * held until it closes.
+ */
+function deliverBeyond(dialog, message, politeness) {
+  const next = nextExposedChannel(dialog);
+  if (next === 'covered' || next == null && isAnyModalOpen()) {
+    // An exiting modal — this one, or one above the next candidate — is
+    // still open and covers what is beneath it: nothing is exposed until
+    // it closes.
+    hold(dialog, message, politeness);
+    return;
+  }
+  if (next != null) {
+    announceInModalRouted(next, message, politeness);
+    return;
+  }
+  announceMessage(message, politeness);
+}
+
+/**
+ * Move whatever `dialog`'s containers hold that assistive technology has not
+ * had yet to the channel exposed now. Called when the dialog stops being
+ * exposed — closed, taken inert or `aria-hidden` for its exit, or unmounted
+ * while open — so a message sent just before is not lost (FR14).
+ */
+export function handOffUnexposed(dialog) {
+  for (const politeness of ['polite', 'assertive']) {
+    const waiting = takeUnexposed(dialog, politeness);
+    if (waiting.length > 0) {
+      deliverBeyond(dialog, waiting.join(' '), politeness);
+    }
+  }
+}
+
+/**
+ * An empty message from inside `dialog`: withdraw the words its region for
+ * `politeness` holds or is about to hold, and the words of that urgency
+ * waiting for the dialog's real close, so a status taken back while the
+ * dialog exits ("3 results", then the query is cleared) is not delivered
+ * after all once the dialog has closed.
+ */
+function withdrawFromModal(dialog, politeness) {
+  clearModalRegion(dialog, politeness);
+  dropHeld(dialog, politeness);
+}
+
+/** Take the unexposed messages out of a dialog's region, clearing it. */
+function takeUnexposed(dialog, politeness) {
+  const region = modalRegion(dialog, politeness);
+  if (region == null) {
+    return [];
+  }
+  const waiting = unexposedMessages(region);
+  clearModalRegion(dialog, politeness);
+  return waiting;
+}
+function announceInModalRouted(dialog, message, politeness = 'polite') {
+  if (!isExposed(dialog)) {
+    deliverBeyond(dialog, message, politeness);
+    return;
+  }
+  const top = topExposedModal();
+  if (top != null && top !== dialog && presented.includes(dialog)) {
+    // Covered by a later Astryx modal: the owner is not operable until that
+    // one closes, and a message announced meanwhile is not heard — the
+    // container is clear before this modal is on top again.
+    clearModalRegion(dialog, politeness);
+    return;
+  }
+  writeModalRegion(dialog, message, politeness, {
+    isExposed: () => isExposed(dialog),
+    redirect: joined => deliverBeyond(dialog, joined, politeness)
+  });
+}
+function withdrawFromModalPendingRouted(dialog, message, politeness) {
+  withdrawFromModalRegion(dialog, message, politeness);
+  const slot = held.get(dialog);
+  if (slot != null) {
+    slot[politeness] = slot[politeness].filter(text => text !== message);
+    if (slot.polite.length === 0 && slot.assertive.length === 0) {
+      held.delete(dialog);
+    }
+  }
+}
+
+// Messages from callers whose enclosing modal is being presented in this
+// commit, waiting one frame for the route; an empty message among them
+// withdraws the earlier ones of its urgency, as it would on a channel.
+
+const deferredByScope = new WeakMap();
+function deferUntilPresented(scope, message, politeness) {
+  let deferred = deferredByScope.get(scope);
+  if (deferred == null) {
+    const created = {
+      frame: requestAnimationFrame(() => {
+        deferredByScope.delete(scope);
+        const opened = enclosingOpenModal(scope);
+        for (const urgency of ['polite', 'assertive']) {
+          if (created.clears[urgency]) {
+            if (opened != null) {
+              withdrawFromModal(opened, urgency);
+            } else {
+              clearRegion(urgency);
+            }
+          }
+          for (const text of created.messages[urgency]) {
+            if (opened != null) {
+              announceInModalRouted(opened, text, urgency);
+            } else {
+              announceMessage(text, urgency);
+            }
+          }
+        }
+      }),
+      messages: {
+        polite: [],
+        assertive: []
+      },
+      clears: {
+        polite: false,
+        assertive: false
+      }
+    };
+    deferred = created;
+    deferredByScope.set(scope, deferred);
+  }
+  if (!message) {
+    deferred.messages[politeness] = [];
+    deferred.clears[politeness] = true;
+    return;
+  }
+  if (!deferred.messages[politeness].includes(message)) {
+    deferred.messages[politeness].push(message);
+  }
+}
+
+/**
+ * Whether a provider nearer than the first open modal in the chain is meant
+ * to be open but its dialog is not open yet: the caller sits inside a modal
+ * being presented in this commit, which will be the one on top.
+ */
+function isBeingPresented(scope) {
+  for (let s = scope; s != null; s = s.parent) {
+    const dialog = s.dialogRef.current;
+    if (isOpenModal(dialog)) {
+      return false;
+    }
+    if (s.isOpen && (dialog == null || !dialog.open)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * `useAnnounce` from inside `scope`, resolved per call: the same owner is
+ * sometimes inside a modal and sometimes not, and the modal it is in may have
+ * just opened or closed.
+ */
+function announceFromScope(scope, message, politeness) {
+  if (isBeingPresented(scope)) {
+    // Announced in the commit that opens the enclosing modal — a field error
+    // inside `{isOpen && <Dialog isOpen>}`, alone or inside an already-open
+    // Dialog — before the Dialog's own Effect, which runs after its
+    // content's, has called showModal(). Choose the route a frame later,
+    // when it has, rather than the modal beneath, which the new one is about
+    // to cover; an empty message in the same commit withdraws what waits
+    // (FR9). A caller inside a modal that is meant to be closed (its content
+    // stays mounted) is not waiting for anything: it takes the route of
+    // where it is now, joined with the frame's other messages.
+    deferUntilPresented(scope, message, politeness);
+    return;
+  }
+  const dialog = enclosingOpenModal(scope);
+  if (!message) {
+    // An empty message clears any lingering status, including messages
+    // joined but not yet exposed and words held for the dialog's close.
+    if (dialog != null) {
+      withdrawFromModal(dialog, politeness);
+    } else {
+      clearRegion(politeness);
+    }
+    return;
+  }
+  if (dialog != null) {
+    announceInModalRouted(dialog, message, politeness);
+    return;
+  }
+  announceMessage(message, politeness);
+}
+installModalRoute({
+  announce: announceFromScope,
+  announceInModal: announceInModalRouted,
+  withdrawFromModalPending: withdrawFromModalPendingRouted
+});

package/dist/hooks/scrollGeometry.d.ts

@@ -21,4 +21,32 @@ export declare function getLogicalAxisMapping(writingMode: string, direction: st
 export declare function isScrollCapableOverflow(value: string): boolean;
 export declare function measureLogicalOverflowGeometry(element: HTMLElement, logicalAxis: LogicalScrollAxis, mapping: LogicalAxisMapping): boolean | null;
 export declare function measureLogicalScrollAxis(element: HTMLElement, logicalAxis: LogicalScrollAxis, mapping: LogicalAxisMapping): MeasuredScrollAxisState | null;
+/** Where a scroll left one logical axis, read from geometry alone. */
+export interface LogicalScrollPosition {
+    /** Content exceeds the viewport by more than the shared tolerance. */
+    overflows: boolean;
+    atStart: boolean;
+    atEnd: boolean;
+    /**
+     * The offset's sign contradicts the mapping: negative on an axis the
+     * mapping reads forward, or positive on one it reads reversed. The writing
+     * mode or direction changed without the last full measurement seeing it
+     * (a stylesheet alone, for one), so the mapping is stale.
+     */
+    contradictsMapping: boolean;
+}
+/**
+ * Reads one logical axis after a scroll without reading computed style.
+ *
+ * A scroll moves the offset and nothing else: the writing-mode mapping and
+ * whether the computed overflow can scroll are the ones the last full
+ * measurement read, so the caller passes that mapping in. Only box geometry
+ * is read here, which costs nothing while layout is clean, as it is during a
+ * scroll; a computed-style read would force a style recalculation on every
+ * frame of the scroll whenever anything else on the page has dirtied style.
+ *
+ * Returns null when the viewport is disconnected or has no box (the caller
+ * keeps its last valid state, as a full measurement does).
+ */
+export declare function measureLogicalScrollPosition(element: HTMLElement, logicalAxis: LogicalScrollAxis, mapping: LogicalAxisMapping): LogicalScrollPosition | null;
 //# sourceMappingURL=scrollGeometry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"scrollGeometry.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollGeometry.ts"],"names":[],"mappings":"AAEA,oEAAoE;AAEpE,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,OAAO,CAAC;AACnD,MAAM,MAAM,kBAAkB,GAAG,GAAG,GAAG,GAAG,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAQD,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,kBAAkB,CAyBpB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9D;AAwCD,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,iBAAiB,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,GAAG,IAAI,CAYhB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,iBAAiB,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,uBAAuB,GAAG,IAAI,CA2BhC"}
+{"version":3,"file":"scrollGeometry.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollGeometry.ts"],"names":[],"mappings":"AAEA,oEAAoE;AAEpE,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,OAAO,CAAC;AACnD,MAAM,MAAM,kBAAkB,GAAG,GAAG,GAAG,GAAG,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAQD,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,kBAAkB,CAyBpB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9D;AAwCD,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,iBAAiB,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,GAAG,IAAI,CAYhB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,iBAAiB,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,uBAAuB,GAAG,IAAI,CAwBhC;AAiBD,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,iBAAiB,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,qBAAqB,GAAG,IAAI,CAqB9B"}

package/dist/hooks/scrollGeometry.js

@@ -76,11 +76,45 @@ export function measureLogicalScrollAxis(element, logicalAxis, mapping) {
   if (!isScrollCapableOverflow(metrics.overflow) || maxOffset <= SCROLL_OVERFLOW_TOLERANCE) {
     return INACTIVE_AXIS_STATE;
   }
-  const isReversed = mapping[`${logicalAxis}Reversed`];
-  const logicalOffset = Math.min(maxOffset, Math.max(0, isReversed ? Math.abs(metrics.offset) : metrics.offset));
   return {
     isScrollable: true,
+    ...logicalEdges(metrics.offset, maxOffset, mapping[`${logicalAxis}Reversed`])
+  };
+}
+function logicalEdges(offset, maxOffset, isReversed) {
+  const logicalOffset = Math.min(maxOffset, Math.max(0, isReversed ? Math.abs(offset) : offset));
+  return {
     atStart: logicalOffset <= SCROLL_OVERFLOW_TOLERANCE,
     atEnd: logicalOffset >= maxOffset - SCROLL_OVERFLOW_TOLERANCE
   };
+}
+
+/** Where a scroll left one logical axis, read from geometry alone. */
+
+/**
+ * Reads one logical axis after a scroll without reading computed style.
+ *
+ * A scroll moves the offset and nothing else: the writing-mode mapping and
+ * whether the computed overflow can scroll are the ones the last full
+ * measurement read, so the caller passes that mapping in. Only box geometry
+ * is read here, which costs nothing while layout is clean, as it is during a
+ * scroll; a computed-style read would force a style recalculation on every
+ * frame of the scroll whenever anything else on the page has dirtied style.
+ *
+ * Returns null when the viewport is disconnected or has no box (the caller
+ * keeps its last valid state, as a full measurement does).
+ */
+export function measureLogicalScrollPosition(element, logicalAxis, mapping) {
+  if (!element.isConnected || element.clientWidth <= 0 || element.clientHeight <= 0) {
+    return null;
+  }
+  const isX = mapping[logicalAxis] === 'x';
+  const isReversed = mapping[`${logicalAxis}Reversed`];
+  const offset = isX ? element.scrollLeft : element.scrollTop;
+  const maxOffset = isX ? element.scrollWidth - element.clientWidth : element.scrollHeight - element.clientHeight;
+  return {
+    overflows: maxOffset > SCROLL_OVERFLOW_TOLERANCE,
+    ...logicalEdges(offset, maxOffset, isReversed),
+    contradictsMapping: isReversed ? offset > SCROLL_OVERFLOW_TOLERANCE : offset < -SCROLL_OVERFLOW_TOLERANCE
+  };
 }

package/dist/hooks/useAdaptivePresentation.d.ts

@@ -1,5 +1,13 @@
 export type AdaptivePresentation = 'popover' | 'bottom-sheet' | 'adaptive';
 export type ResolvedAdaptivePresentation = Exclude<AdaptivePresentation, 'adaptive'>;
-export declare const COMPACT_TOUCH_PRESENTATION_QUERY = "(max-width: 768px) and (pointer: coarse)";
+export declare const COMPACT_TOUCH_PRESENTATION_QUERY: string;
+/**
+ * Resolve `adaptive` against the active theme's compact-touch query
+ * (`useCompactDefinition()`, so a theme that moves `md` is honored —
+ * spec:AST-012 FR9). Only an `adaptive` presentation subscribes to
+ * `matchMedia`; a fixed presentation never reads the query, so it holds no
+ * listener for it (`architecture:react-component-runtime` INV5). SSR-safe:
+ * the server snapshot is "not compact", as `useMediaQuery`'s default is.
+ */
 export declare function useAdaptivePresentation(presentation: AdaptivePresentation): ResolvedAdaptivePresentation;
 //# sourceMappingURL=useAdaptivePresentation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useAdaptivePresentation.d.ts","sourceRoot":"","sources":["../../src/hooks/useAdaptivePresentation.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;AAC3E,MAAM,MAAM,4BAA4B,GAAG,OAAO,CAChD,oBAAoB,EACpB,UAAU,CACX,CAAC;AAKF,eAAO,MAAM,gCAAgC,6CACD,CAAC;AAE7C,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,oBAAoB,GACjC,4BAA4B,CAO9B"}
+{"version":3,"file":"useAdaptivePresentation.d.ts","sourceRoot":"","sources":["../../src/hooks/useAdaptivePresentation.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;AAC3E,MAAM,MAAM,4BAA4B,GAAG,OAAO,CAChD,oBAAoB,EACpB,UAAU,CACX,CAAC;AAMF,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAKpE;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,oBAAoB,GACjC,4BAA4B,CA4B9B"}

package/dist/hooks/useAdaptivePresentation.js

@@ -4,16 +4,41 @@
 
 /**
  * @file useAdaptivePresentation.ts
- * @input Uses the shared SSR-safe media-query hook
+ * @input Uses React's external-store subscription over window.matchMedia
+ *   and the touch presentation's compact-touch query
  * @output Resolves popover/bottom-sheet presentation policy
  * @position Internal overlay policy shared across component families
  */
-import { useMediaQuery } from "./useMediaQuery.js";
-// Width keeps desktop-class tablets and large touch displays anchored by
-// default. Pointer capability, rather than `hover: none`, avoids excluding
-// touch browsers that also report hover capability.
-export const COMPACT_TOUCH_PRESENTATION_QUERY = '(max-width: 768px) and (pointer: coarse)';
+import { useCallback, useSyncExternalStore } from 'react';
+import { COMPACT_TOUCH_QUERY, useCompactDefinition } from "../utils/touchPresentation.js";
+// A sheet needs both a compact viewport and a coarse primary pointer: tablets
+// and large touch displays stay anchored, phones in either orientation get
+// the sheet. Compact is the active theme's definition (spec:AST-012 FR9);
+// this constant is its value at the default width points.
+export const COMPACT_TOUCH_PRESENTATION_QUERY = COMPACT_TOUCH_QUERY;
+const noSubscription = () => () => {};
+const notCompact = () => false;
+
+/**
+ * Resolve `adaptive` against the active theme's compact-touch query
+ * (`useCompactDefinition()`, so a theme that moves `md` is honored —
+ * spec:AST-012 FR9). Only an `adaptive` presentation subscribes to
+ * `matchMedia`; a fixed presentation never reads the query, so it holds no
+ * listener for it (`architecture:react-component-runtime` INV5). SSR-safe:
+ * the server snapshot is "not compact", as `useMediaQuery`'s default is.
+ */
 export function useAdaptivePresentation(presentation) {
-  const isCompactTouch = useMediaQuery(COMPACT_TOUCH_PRESENTATION_QUERY);
-  return presentation === 'adaptive' ? isCompactTouch ? 'bottom-sheet' : 'popover' : presentation;
+  const isAdaptive = presentation === 'adaptive';
+  const query = useCompactDefinition().coarsePointerQuery;
+  const subscribe = useCallback(onStoreChange => {
+    if (!isAdaptive) {
+      return noSubscription();
+    }
+    const mql = window.matchMedia(query);
+    mql.addEventListener('change', onStoreChange);
+    return () => mql.removeEventListener('change', onStoreChange);
+  }, [isAdaptive, query]);
+  const getSnapshot = useCallback(() => isAdaptive ? window.matchMedia(query).matches : false, [isAdaptive, query]);
+  const isCompactTouch = useSyncExternalStore(subscribe, getSnapshot, notCompact);
+  return isAdaptive ? isCompactTouch ? 'bottom-sheet' : 'popover' : presentation;
 }

package/dist/hooks/useAnimatedLayout.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file useAnimatedLayout.ts
+ * @input React (useMemo), motion/animatedLayout.ts
+ * @output Exports `useAnimatedLayout` and the opaque `AnimatedLayout` handle
+ *   type
+ * @position Public hook (`spec:AST-105`) over the one size-change module
+ *   (`architecture:react-component-runtime` INV12)
+ *
+ * SYNC: When modified, update /packages/core/src/motion/animatedLayout.ts
+ */
+import { type RefObject } from 'react';
+import { type AnimatedLayout } from '../motion/animatedLayout.js';
+export type { AnimatedLayout } from '../motion/animatedLayout.js';
+export interface UseAnimatedLayoutOptions {
+    /** The container whose content glides: a scroll container or a panel. */
+    containerRef: RefObject<HTMLElement | null>;
+}
+/**
+ * Returns a handle to pass to a component whose size changes, such as
+ * TreeList or Collapsible. When that component changes size, it and the
+ * content after it inside `containerRef` animate together on one shared
+ * motion role. Fixed and stuck sticky elements stay put, the glide never
+ * scrolls the area, and Reduce Motion is respected.
+ *
+ * `containerRef` names the area: an app passes the ref it already gives its
+ * scroll container or panel (a ScrollableArea's ref reaches its native scroll
+ * viewport). The handle has no public members (`spec:AST-105` FR1).
+ *
+ * @example
+ * ```
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const animatedLayout = useAnimatedLayout({containerRef});
+ * return (
+ *   <div ref={containerRef}>
+ *     <TreeList items={items} animatedLayout={animatedLayout} />
+ *     <p>Notes</p>
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useAnimatedLayout({ containerRef, }: UseAnimatedLayoutOptions): AnimatedLayout;
+//# sourceMappingURL=useAnimatedLayout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useAnimatedLayout.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnimatedLayout.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAC,cAAc,EAAC,MAAM,0BAA0B,CAAC;AAE7D,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,YAAY,GACb,EAAE,wBAAwB,GAAG,cAAc,CAO3C"}

package/dist/hooks/useAnimatedLayout.js

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useAnimatedLayout.ts
+ * @input React (useMemo), motion/animatedLayout.ts
+ * @output Exports `useAnimatedLayout` and the opaque `AnimatedLayout` handle
+ *   type
+ * @position Public hook (`spec:AST-105`) over the one size-change module
+ *   (`architecture:react-component-runtime` INV12)
+ *
+ * SYNC: When modified, update /packages/core/src/motion/animatedLayout.ts
+ */
+import { useMemo } from 'react';
+import { createAnimatedLayout } from "../motion/animatedLayout.js";
+/**
+ * Returns a handle to pass to a component whose size changes, such as
+ * TreeList or Collapsible. When that component changes size, it and the
+ * content after it inside `containerRef` animate together on one shared
+ * motion role. Fixed and stuck sticky elements stay put, the glide never
+ * scrolls the area, and Reduce Motion is respected.
+ *
+ * `containerRef` names the area: an app passes the ref it already gives its
+ * scroll container or panel (a ScrollableArea's ref reaches its native scroll
+ * viewport). The handle has no public members (`spec:AST-105` FR1).
+ *
+ * @example
+ * ```
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const animatedLayout = useAnimatedLayout({containerRef});
+ * return (
+ *   <div ref={containerRef}>
+ *     <TreeList items={items} animatedLayout={animatedLayout} />
+ *     <p>Notes</p>
+ *   </div>
+ * );
+ * ```
+ */
+export function useAnimatedLayout({
+  containerRef
+}) {
+  // The container is read when a change runs, so the handle stays stable
+  // across renders and a later ref assignment is still seen.
+  return useMemo(() => createAnimatedLayout(() => containerRef.current), [containerRef]);
+}