@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/dist/hooks/useAttachment.js

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useAttachment.ts
+ * @input A node ref (an element's, or the document's), an attach function
+ *   and a key
+ * @output Exports useAttachment: keeps the attach function bound to the node
+ *   the ref holds across commits
+ * @position Internal React helper, not in hooks/index.ts: the one attach
+ *   and release lifecycle of the gesture hooks (useGestureRecognizer,
+ *   usePressTracker, useFingerScroll)
+ *
+ * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx
+ * and gestures/__tests__/useFingerScroll.test.tsx.
+ */
+import { useRef } from 'react';
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+
+/**
+ * Keep `attach` bound to the node `ref` holds after each commit: an element,
+ * or the document. A replaced node is released and the new one attached, a
+ * changed `key` re-attaches, and the last attachment is released on unmount;
+ * a commit that changes neither does nothing (react-component-runtime INV3).
+ */
+export function useAttachment(ref, attach, key) {
+  const attachmentRef = useRef(null);
+
+  // Syncs the attachment with the DOM node `ref` holds after this commit.
+  useIsomorphicLayoutEffect(() => {
+    const element = ref.current;
+    const current = attachmentRef.current;
+    if (current?.element === element && current?.key === key) {
+      return;
+    }
+    current?.release();
+    attachmentRef.current = element == null ? null : {
+      element,
+      key,
+      release: attach(element)
+    };
+  });
+
+  // Releases the attachment at unmount.
+  useIsomorphicLayoutEffect(() => () => {
+    attachmentRef.current?.release();
+    attachmentRef.current = null;
+  }, []);
+}

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

@@ -1 +1 @@
-{"version":3,"file":"useAutoMediaMode.d.ts","sourceRoot":"","sources":["../../src/hooks/useAutoMediaMode.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,gBAAgB,CAAC;AAMzC,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAqFzD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,IAAI,EAChB,OAAO,EAAE,IAAI,GAAG,IAAI,EACpB,MAAM,EAAE,IAAI,GAAG,IAAI,EACnB,OAAO,EAAE,IAAI,GAAG,IAAI,GACnB,iBAAiB,GAAG,IAAI,CAe1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,SAAS,EAAE,OAAO,GACjB,iBAAiB,GAAG,IAAI,CAsD1B"}
+{"version":3,"file":"useAutoMediaMode.d.ts","sourceRoot":"","sources":["../../src/hooks/useAutoMediaMode.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,gBAAgB,CAAC;AAMzC,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AA4EzD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,IAAI,EAChB,OAAO,EAAE,IAAI,GAAG,IAAI,EACpB,MAAM,EAAE,IAAI,GAAG,IAAI,EACnB,OAAO,EAAE,IAAI,GAAG,IAAI,GACnB,iBAAiB,GAAG,IAAI,CAe1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,SAAS,EAAE,OAAO,GACjB,iBAAiB,GAAG,IAAI,CAmD1B"}

package/dist/hooks/useAutoMediaMode.js

@@ -6,32 +6,19 @@
  * @file useAutoMediaMode.ts
  * @input Ref to the element whose backdrop should be measured
  * @output 'dark' | 'light' | null (not yet measurable)
- * @position INTERNAL — powers `MediaTheme mode="auto"`. Not exported from the
- *   package: MediaTheme is the supported surface for this behavior.
- *   Sibling to useImageMode, which answers the same question for images.
- *
- * Picks the media context a surface wants by measuring what the browser
- * actually painted, rather than trusting a token's name.
- *
- * The bug it exists for: `--color-background-inverted` is not required to be
- * inverted. A theme can define it as a pale grey, and a hardcoded
- * `mode="dark"` then paints white text on it at 1.25:1. Because the surface
- * colour is a runtime value and the mode is a compile-time guess, no amount
- * of care in the component can catch that.
- *
- * The answer can also be `'off'`: when the surface's own ambient text already
- * reads on it, the surface is not effectively inverted and does not want a
- * media context. Verified in Chromium that this loses nothing on a surface
- * that is chromatic but legible — the dark-mode error toast renders
- * identically either way, because a dark page already resolves those tokens
- * to the values the media context would install.
- *
- * @example
- * ```
- * // Inside MediaTheme; see its `mode="auto"`.
- * const detected = useAutoMediaMode(ref, mode === 'auto');
- * ```
+ * @position Internal; powers `MediaTheme mode="auto"`. Not exported from the
+ *   package. Sibling to useImageMode, which does the same for images.
  */
+
+// The hook measures what the browser painted and does not trust a token's
+// name. `--color-background-inverted` need not be inverted: a theme can make
+// it pale grey, and a fixed `mode="dark"` then paints white text on it at
+// 1.25:1. The surface color is a runtime value, so only a measurement can
+// catch this.
+//
+// The answer can be `'off'` when the surface's own text already reads on it.
+// A dark page already resolves those tokens to the media context's values,
+// so a chromatic but legible surface loses nothing.
 import { useRef, useState } from 'react';
 import { parseColor, formatColor } from "../utils/color.js";
 import { contrastRatio, compositeOver } from "../theme/contrast.js";
@@ -41,17 +28,11 @@ import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 /** A surface luminance context, or `"off"` when no media context is wanted. */
 
 /**
- * Resolve token references to the colors they actually paint, by reading them
- * back off a hidden probe.
- *
- * A custom property cannot simply be read: `getPropertyValue` returns the
- * token's *specified* text, and Astryx tokens are `light-dark(a, b)` pairs
- * that resolve only once used in a real property. The probe assigns each
- * token to `color` and reads the computed value back, which the browser has
- * resolved against the host's own color-scheme and any overrides.
- *
- * `display: none` keeps the probe out of layout — computed color still
- * resolves — so this costs a style recalc and no reflow.
+ * Resolve token references to the colors they paint, through a hidden probe.
+ * `getPropertyValue` returns a token's specified text, and Astryx tokens are
+ * `light-dark(a, b)` pairs that resolve only in a real property. The probe
+ * sets each token as `color` and reads the computed value. `display: none`
+ * keeps the probe out of layout, so this costs a style recalc and no reflow.
  */
 function resolvePaintedColors(host, tokens) {
   const probe = document.createElement('span');
@@ -104,14 +85,11 @@ function resolveBackdrop(element) {
 }
 
 /**
- * Contrast at which a surface's own ambient text counts as reading well
- * enough that no media context is wanted.
- *
- * WCAG's non-text / large-text line. It is deliberately low: this decides
- * whether a surface is *effectively inverted*, not whether its text meets a
- * standard. A pairing that clears 3:1 is one the theme is rendering
- * successfully, and swapping in a media context there changes accent,
- * overlays and borders for no legibility gain.
+ * Contrast at which a surface's own text reads well enough that no media
+ * context is wanted. This is WCAG's large-text line. It is low on purpose: it
+ * decides if a surface is effectively inverted, not if its text meets a
+ * standard. A media context on a 3:1 pairing changes accent, overlays and
+ * borders with no legibility gain.
  */
 const AMBIENT_READS_AT = 3;
 
@@ -157,12 +135,10 @@ export function useAutoMediaMode(ref, isEnabled) {
   } = useTheme();
   const lastRef = useRef(null);
 
-  // Deliberately no dependency array. A surface's color is a painted value:
-  // it changes when a prop on some ancestor changes, and no dependency this
-  // hook could name would catch that (an earlier revision took a `watch`
-  // array and silently went stale whenever a caller forgot an entry). So the
-  // measurement re-runs whenever anything re-renders, and skips its own
-  // expensive half when nothing moved — see the early return below.
+  // No dependency array. A surface color is a painted value, and it changes
+  // when a prop on some ancestor changes. No dependency that this hook can
+  // name catches that. So the measurement runs on each render, and it skips
+  // its expensive half when nothing moved (see the early return below).
   useIsomorphicLayoutEffect(() => {
     const surface = ref.current?.parentElement ?? null;
     if (!isEnabled || surface === null) {
@@ -173,10 +149,9 @@ export function useAutoMediaMode(ref, isEnabled) {
       return;
     }
 
-    // The backdrop walk above is a couple of getComputedStyle reads; the
-    // probe below appends a node and forces another style resolution. Skip
-    // it when neither the painted backdrop nor the theme has moved, which is
-    // the overwhelmingly common render.
+    // The probe adds a node and forces another style resolution. Skip it when
+    // neither the painted backdrop nor the theme moved, which is the usual
+    // case.
     const backgroundKey = formatColor(background);
     const last = lastRef.current;
     if (last !== null && last.background === backgroundKey && last.tokens === tokens) {

package/dist/hooks/useBusyAnnouncement.d.ts

@@ -4,22 +4,8 @@
  *   to an element inside the control
  * @output Announces each busy start once, through the shared polite channel
  *   or a persistent region inside the open modal dialog holding the control
- * @position Core a11y hook for controls that show a decorative busy Spinner
- *
- * The busy Spinner inside a control is decorative (hidden, no live role); the
- * control announces its busy state instead (`spec:AST-086` FR8), once per busy
- * start (FR6): rerenders and StrictMode replay do not repeat it, and settling
- * re-arms it. The returned function is called by an owner announcing the
- * busy operation's outcome: a busy start not yet announced is dropped, so it
- * never follows its own outcome (FR8). While a native modal is open, the body-level channel is not
- * exposed, so a control inside it announces through that dialog's polite
- * container, the one `useAnnounce` uses for every message from inside the
- * modal (FR14), inserted empty and filled a frame later (FR3); the control's
- * own element locates the modal, so a busy start inside a native modal an app
- * renders without Astryx is heard inside it too.
- *
- * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —
- * this is a shared implementation detail of Astryx's busy controls.
+ * @position Core a11y hook for controls that show a decorative busy Spinner.
+ *   It is a shared detail of the busy controls, so it is not in hooks/index.ts.
  */
 import { type RefObject } from 'react';
 export declare function useBusyAnnouncement(isBusy: boolean, message: string, elementRef: RefObject<Element | null>): () => void;

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

@@ -1 +1 @@
-{"version":3,"file":"useBusyAnnouncement.d.ts","sourceRoot":"","sources":["../../src/hooks/useBusyAnnouncement.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAUrE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,GACpC,MAAM,IAAI,CAgEZ"}
+{"version":3,"file":"useBusyAnnouncement.d.ts","sourceRoot":"","sources":["../../src/hooks/useBusyAnnouncement.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAWH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAUrE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,GACpC,MAAM,IAAI,CA8DZ"}

package/dist/hooks/useBusyAnnouncement.js

@@ -8,23 +8,18 @@
  *   to an element inside the control
  * @output Announces each busy start once, through the shared polite channel
  *   or a persistent region inside the open modal dialog holding the control
- * @position Core a11y hook for controls that show a decorative busy Spinner
- *
- * The busy Spinner inside a control is decorative (hidden, no live role); the
- * control announces its busy state instead (`spec:AST-086` FR8), once per busy
- * start (FR6): rerenders and StrictMode replay do not repeat it, and settling
- * re-arms it. The returned function is called by an owner announcing the
- * busy operation's outcome: a busy start not yet announced is dropped, so it
- * never follows its own outcome (FR8). While a native modal is open, the body-level channel is not
- * exposed, so a control inside it announces through that dialog's polite
- * container, the one `useAnnounce` uses for every message from inside the
- * modal (FR14), inserted empty and filled a frame later (FR3); the control's
- * own element locates the modal, so a busy start inside a native modal an app
- * renders without Astryx is heard inside it too.
- *
- * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —
- * this is a shared implementation detail of Astryx's busy controls.
+ * @position Core a11y hook for controls that show a decorative busy Spinner.
+ *   It is a shared detail of the busy controls, so it is not in hooks/index.ts.
  */
+
+// The busy Spinner is decorative, so the control announces its busy state,
+// once for each busy start (AST-086). A re-render or a StrictMode replay does
+// not repeat it, and the settle re-arms it. An owner calls the returned function
+// when it announces the outcome. A busy start that is not yet announced is
+// then dropped, so it never follows its own outcome. While a native modal is
+// open, the page-body channel is not exposed. So a control in a modal
+// announces through that dialog's polite region, also in a modal that an app
+// renders without Astryx.
 import { useCallback, useEffect, useRef } from 'react';
 import { announceInModal, enclosingModalDialog, takeJoinedAnnouncement, useAnnounce, withdrawPendingAnnouncement } from "./useAnnounce.js";
 export function useBusyAnnouncement(isBusy, message, elementRef) {
@@ -52,10 +47,8 @@ export function useBusyAnnouncement(isBusy, message, elementRef) {
     const frame = requestAnimationFrame(() => {
       frameRef.current = null;
       hasAnnouncedRef.current = true;
-      // The nearest open native modal around the control's own element,
-      // Astryx or app-rendered, so a busy start inside a modal an app renders
-      // without Astryx is still heard inside it (`spec:AST-086` FR14); the
-      // shared `useAnnounce` route otherwise, which itself follows the
+      // The nearest open native modal around the control's element, Astryx or
+      // app-rendered. Else the shared `useAnnounce` route, which follows the
       // nearest Astryx modal around this hook's caller.
       const dialog = enclosingModalDialog(elementRef.current);
       if (dialog != null) {

package/dist/hooks/useClickableContainer.d.ts

@@ -1,21 +1,22 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list
- * @position Core hook for clickable containers that safely handle nested interactive elements
- *
- * Solves the "nested interactive elements" problem: when a card is clickable
- * but contains buttons/links, clicking those should NOT trigger the card's action.
- *
- * Every navigation exit here (window.open, location.href, and the delegated
- * click on the interactive ref) runs after the shared navigation-destination
- * rule in utils/safeUrl.ts; a blocked href does not navigate by any
- * activation method.
+ * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;
+ *   hasInteractiveAncestor and the shared innermostInteractive walk
+ * @position Core hook for clickable containers with nested interactive
+ *   elements. A click on a nested button or link does not run the card's
+ *   action. Each navigation passes the rule in utils/safeUrl.ts first.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
  */
 import { type RefObject, type MouseEvent } from 'react';
+/**
+ * The attribute this hook sets on the container it makes clickable. A click
+ * inside a nested marked container belongs to that container (see
+ * INTERACTIVE_SELECTORS).
+ */
+export declare const PRESSABLE_CONTAINER_ATTRIBUTE = "data-pressable-container";
 /**
  * Canonical list of interactive element selectors — native controls plus
  * role-based interactive elements. Clicks on these (or their descendants)
@@ -29,15 +30,31 @@ import { type RefObject, type MouseEvent } from 'react';
  */
 export declare const INTERACTIVE_SELECTORS: string;
 /**
- * Check whether an element has an interactive ancestor between it and the root.
- * If the click target is inside a nested button/link/etc., we should NOT
- * handle it at the container level.
+ * Whether this element is interactive by INTERACTIVE_SELECTORS: a control,
+ * link, editor, or nested clickable container, and not marked read-only.
+ */
+export declare function matchesInteractiveSelectors(element: Element): boolean;
+/**
+ * The innermost element, from `el` up to (not including) `rootEl` or the
+ * document body, that `isInteractive` accepts: by default the
+ * INTERACTIVE_SELECTORS match. The one walk every "does this event belong
+ * to a control" check shares; a hover layer's tap passes its own test
+ * (useTouchTrigger's `tapLandsOnDisabledControl`).
+ */
+export declare function innermostInteractive(el: Element, rootEl: Element | null, isInteractive?: (element: Element) => boolean): Element | null;
+/**
+ * Check whether an element has an interactive ancestor between it and the
+ * root (the element itself included). If the click target is inside a nested
+ * button/link/etc., we should NOT handle it at the container level.
  *
  * Exported for containers that cannot use the hook itself — a `<tr>` whose
  * props are assembled inside a Table plugin's `transformBodyRow`, for
  * instance, has no ref to hand the hook but needs the identical rule. Sharing
  * the walk keeps one definition of "this click belongs to something else"
  * instead of a short hand-rolled selector list per caller.
+ *
+ * A press inside an open Tooltip or HoverCard surface also answers true: it
+ * belongs to that surface, not the container around its trigger.
  */
 export declare function hasInteractiveAncestor(el: Element, rootEl: Element): boolean;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"useClickableContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useClickableContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAyB,KAAK,SAAS,EAAE,KAAK,UAAU,EAAC,MAAM,OAAO,CAAC;AAG9E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAmBvB,CAAC;AAIZ;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAY5E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CASvD;AAED,MAAM,WAAW,4BAA4B;IAC3C,yCAAyC;IACzC,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,mEAAmE;IACnE,cAAc,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,oBAAoB;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACnD;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAClD,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,YAAY,EACZ,cAAc,EACd,OAAO,EAAE,WAAW,EACpB,IAAI,EACJ,MAAM,EACN,QAAgB,GACjB,EAAE,4BAA4B,GAAG,wBAAwB,CAmHzD"}
+{"version":3,"file":"useClickableContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useClickableContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAyB,KAAK,SAAS,EAAE,KAAK,UAAU,EAAC,MAAM,OAAO,CAAC;AAI9E;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAmBvB,CAAC;AAIZ;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAKrE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,OAAO,GAAG,IAAI,EACtB,aAAa,GAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAqC,GACzE,OAAO,GAAG,IAAI,CAShB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAE5E;AASD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CASvD;AAED,MAAM,WAAW,4BAA4B;IAC3C,yCAAyC;IACzC,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,mEAAmE;IACnE,cAAc,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,oBAAoB;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACnD;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAClD,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,YAAY,EACZ,cAAc,EACd,OAAO,EAAE,WAAW,EACpB,IAAI,EACJ,MAAM,EACN,QAAgB,GACjB,EAAE,4BAA4B,GAAG,wBAAwB,CA+GzD"}

package/dist/hooks/useClickableContainer.js

@@ -5,23 +5,26 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list
- * @position Core hook for clickable containers that safely handle nested interactive elements
- *
- * Solves the "nested interactive elements" problem: when a card is clickable
- * but contains buttons/links, clicking those should NOT trigger the card's action.
- *
- * Every navigation exit here (window.open, location.href, and the delegated
- * click on the interactive ref) runs after the shared navigation-destination
- * rule in utils/safeUrl.ts; a blocked href does not navigate by any
- * activation method.
+ * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;
+ *   hasInteractiveAncestor and the shared innermostInteractive walk
+ * @position Core hook for clickable containers with nested interactive
+ *   elements. A click on a nested button or link does not run the card's
+ *   action. Each navigation passes the rule in utils/safeUrl.ts first.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
  */
 import { useCallback, useEffect } from 'react';
+import { isLayerSurface } from "../Layer/layerSurfacePress.js";
 import { isSafeUrl } from "../utils/safeUrl.js";
 
+/**
+ * The attribute this hook sets on the container it makes clickable. A click
+ * inside a nested marked container belongs to that container (see
+ * INTERACTIVE_SELECTORS).
+ */
+export const PRESSABLE_CONTAINER_ATTRIBUTE = 'data-pressable-container';
+
 /**
  * Canonical list of interactive element selectors — native controls plus
  * role-based interactive elements. Clicks on these (or their descendants)
@@ -33,29 +36,58 @@ import { isSafeUrl } from "../utils/safeUrl.js";
  * consumers that need focusable elements must additionally exclude
  * unfocusable/disabled targets (e.g. `[tabindex="-1"]`, `:disabled`).
  */
-export const INTERACTIVE_SELECTORS = ['button', 'a', 'input', 'select', 'textarea', '[role="button"]', '[role="link"]', '[role="checkbox"]', '[role="radio"]', '[role="switch"]', '[role="tab"]', '[role="menuitem"]', '[role="option"]', '[role="combobox"]', '[role="listbox"]', '[role="slider"]', '[role="spinbutton"]', '[data-pressable-container]'].join(',');
+export const INTERACTIVE_SELECTORS = ['button', 'a', 'input', 'select', 'textarea', '[role="button"]', '[role="link"]', '[role="checkbox"]', '[role="radio"]', '[role="switch"]', '[role="tab"]', '[role="menuitem"]', '[role="option"]', '[role="combobox"]', '[role="listbox"]', '[role="slider"]', '[role="spinbutton"]', `[${PRESSABLE_CONTAINER_ATTRIBUTE}]`].join(',');
 const NON_INTERACTIVE_SELECTORS = '[aria-readonly="true"]';
 
 /**
- * Check whether an element has an interactive ancestor between it and the root.
- * If the click target is inside a nested button/link/etc., we should NOT
- * handle it at the container level.
+ * Whether this element is interactive by INTERACTIVE_SELECTORS: a control,
+ * link, editor, or nested clickable container, and not marked read-only.
+ */
+export function matchesInteractiveSelectors(element) {
+  return element.matches(INTERACTIVE_SELECTORS) && !element.matches(NON_INTERACTIVE_SELECTORS);
+}
+
+/**
+ * The innermost element, from `el` up to (not including) `rootEl` or the
+ * document body, that `isInteractive` accepts: by default the
+ * INTERACTIVE_SELECTORS match. The one walk every "does this event belong
+ * to a control" check shares; a hover layer's tap passes its own test
+ * (useTouchTrigger's `tapLandsOnDisabledControl`).
+ */
+export function innermostInteractive(el, rootEl, isInteractive = matchesInteractiveSelectors) {
+  let current = el;
+  while (current != null && current !== rootEl && current !== document.body) {
+    if (isInteractive(current)) {
+      return current;
+    }
+    current = current.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Check whether an element has an interactive ancestor between it and the
+ * root (the element itself included). If the click target is inside a nested
+ * button/link/etc., we should NOT handle it at the container level.
  *
  * Exported for containers that cannot use the hook itself — a `<tr>` whose
  * props are assembled inside a Table plugin's `transformBodyRow`, for
  * instance, has no ref to hand the hook but needs the identical rule. Sharing
  * the walk keeps one definition of "this click belongs to something else"
  * instead of a short hand-rolled selector list per caller.
+ *
+ * A press inside an open Tooltip or HoverCard surface also answers true: it
+ * belongs to that surface, not the container around its trigger.
  */
 export function hasInteractiveAncestor(el, rootEl) {
-  let current = el;
-  while (current != null && current !== rootEl && current !== document.body) {
-    if (current.matches(INTERACTIVE_SELECTORS) && !current.matches(NON_INTERACTIVE_SELECTORS)) {
-      return true;
-    }
-    current = current.parentElement;
-  }
-  return false;
+  return innermostInteractive(el, rootEl, belongsToSomethingElse) != null;
+}
+
+// hasInteractiveAncestor documents this answer until the next minor.
+// A layer root stops such a press before any bubble-phase React handler.
+// A native listener or a capture-phase handler still sees it.
+function belongsToSomethingElse(element) {
+  return matchesInteractiveSelectors(element) || isLayerSurface(element);
 }
 
 /**
@@ -115,7 +147,7 @@ export function useClickableContainer({
   useEffect(() => {
     const el = containerRef.current;
     if (el) {
-      el.setAttribute('data-pressable-container', 'true');
+      el.setAttribute(PRESSABLE_CONTAINER_ATTRIBUTE, 'true');
     }
   }, [containerRef]);
   const onClick = useCallback(event => {
@@ -126,8 +158,6 @@ export function useClickableContainer({
     if (!containerEl) {
       return;
     }
-
-    // Don't trigger on text selection
     if (hasTextSelection(containerEl)) {
       return;
     }
@@ -135,23 +165,18 @@ export function useClickableContainer({
     if (!(eventTarget instanceof Element)) {
       return;
     }
-
-    // If the click landed on or inside a nested interactive element, bail
     if (eventTarget !== event.currentTarget && hasInteractiveAncestor(eventTarget, containerEl)) {
       return;
     }
-
-    // Fire the click handler
     onClickProp?.(event);
     if (event.defaultPrevented) {
       return;
     }
 
-    // Navigate if href is provided. React DOM vets the hrefs it writes as
-    // attributes; nothing below passes through React, so the shared
-    // navigation rule decides once, before target, modifier key, or the
-    // delegated anchor can select a sink. A blocked href simply does not
-    // navigate — the click handler above still ran.
+    // React DOM checks the hrefs that it writes, but nothing below passes
+    // through React. So the shared navigation rule decides once, before the
+    // target, a modifier key, or the delegated anchor picks a sink. A
+    // blocked href does not navigate, but the click handler above still ran.
     if (href != null && isSafeUrl(href)) {
       const shouldOpenNewTab = target === '_blank' || event.ctrlKey || event.metaKey;
       if (shouldOpenNewTab) {

package/dist/hooks/useContainerReveal.d.ts

@@ -1,41 +1,9 @@
 /**
  * @file useContainerReveal.ts
- * @input Uses the containerReveal styles
- * @output Exports useContainerReveal — a headless hover/focus reveal primitive
- * @position Core hook. Consumed by any component that reveals (or conceals)
- *   content when its container is hovered or focused — e.g. Thumbnail's remove
- *   button, TreeList row actions.
- *
- * Gives a container a scoped hover/focus-within trigger that reveals or
- * conceals content inside it, entirely in CSS (no hover state in JS, no
- * re-render on hover). The caller authors NO StyleX: the hook hands out the
- * container style and the matching content styles.
- *
- * Scoping is by inheritance: the container publishes its reveal state as
- * custom properties on itself and the content reads them, so a nested
- * container shadows its ancestor's state for its own subtree. See
- * containerReveal.stylex.ts.
- *
- * Two levers sit on top of the pointer, both still CSS-only. On the container:
- * `hoverDelay` (dwell before the reveal starts — the Tooltip / HoverCard
- * intent gate applied to a reveal) and `forceState` (pin the trigger state a
- * caller owns: a motion gate, a scroll, an open menu). On a single piece of
- * content: `forceVisibility`, which pins how THAT element looks. State belongs
- * to the container because one container feeds children whose looks are
- * opposite; appearance belongs to the element, where it is unambiguous.
- * Neither lever can hide content from a keyboard user — see ACCESSIBILITY.
- *
- * ACCESSIBILITY (WCAG 2.2 by construction):
- * - Revealed content is visually hidden at rest via position + opacity, so it
- *   stays in the accessibility tree and tab order — never display:none.
- * - Keyboard: revealed on :focus-within, so tabbing in shows it — with no dwell
- *   to wait through, and neither an inactive container nor a forced-hidden
- *   element can keep it dark.
- * - Touch: always visible on coarse pointers; never gated behind hover.
- * - Concealed (inverted) content is a mouse-only visual swap: it ignores
- *   :focus-within (a keyboard user must never watch content vanish) and stays
- *   visible on touch and in the a11y tree.
- * - Motion: honors prefers-reduced-motion.
+ * @input The containerReveal styles
+ * @output useContainerReveal, a headless hover and focus reveal primitive
+ * @position Core hook for content that shows or hides when its container is
+ *   hovered or focused, such as Thumbnail's remove button
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
@@ -124,6 +92,11 @@ export interface UseContainerRevealReturn {
 /**
  * Scoped, CSS-only hover/focus reveal for content inside a container.
  *
+ * Revealed content stays in the accessibility tree and the tab order. It
+ * shows on :focus-within without a delay, and it always shows on touch.
+ * Concealed content hides only for a mouse. Motion honors
+ * prefers-reduced-motion.
+ *
  * @example
  * ```
  * const {getContainerProps, getContentRevealProps} = useContainerReveal({

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

@@ -1 +1 @@
-{"version":3,"file":"useContainerReveal.d.ts","sourceRoot":"","sources":["../../src/hooks/useContainerReveal.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAU,KAAK,aAAa,EAAC,MAAM,OAAO,CAAC;AAIlD,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IACnC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CACtC;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,iBAAiB,EAAE,CAAC,OAAO,CAAC,EAAE,sBAAsB,KAAK;QACvD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,aAAa,CAAC;KACvB,CAAC;IACF,mDAAmD;IACnD,qBAAqB,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK;QACzD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,aAAa,CAAC;KACvB,CAAC;CACH;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,CA4C1B"}
+{"version":3,"file":"useContainerReveal.d.ts","sourceRoot":"","sources":["../../src/hooks/useContainerReveal.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAU,KAAK,aAAa,EAAC,MAAM,OAAO,CAAC;AAIlD,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IACnC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CACtC;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,iBAAiB,EAAE,CAAC,OAAO,CAAC,EAAE,sBAAsB,KAAK;QACvD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,aAAa,CAAC;KACvB,CAAC;IACF,mDAAmD;IACnD,qBAAqB,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK;QACzD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,aAAa,CAAC;KACvB,CAAC;CACH;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,CA4C1B"}

package/dist/hooks/useContainerReveal.js

@@ -4,42 +4,10 @@
 
 /**
  * @file useContainerReveal.ts
- * @input Uses the containerReveal styles
- * @output Exports useContainerReveal — a headless hover/focus reveal primitive
- * @position Core hook. Consumed by any component that reveals (or conceals)
- *   content when its container is hovered or focused — e.g. Thumbnail's remove
- *   button, TreeList row actions.
- *
- * Gives a container a scoped hover/focus-within trigger that reveals or
- * conceals content inside it, entirely in CSS (no hover state in JS, no
- * re-render on hover). The caller authors NO StyleX: the hook hands out the
- * container style and the matching content styles.
- *
- * Scoping is by inheritance: the container publishes its reveal state as
- * custom properties on itself and the content reads them, so a nested
- * container shadows its ancestor's state for its own subtree. See
- * containerReveal.stylex.ts.
- *
- * Two levers sit on top of the pointer, both still CSS-only. On the container:
- * `hoverDelay` (dwell before the reveal starts — the Tooltip / HoverCard
- * intent gate applied to a reveal) and `forceState` (pin the trigger state a
- * caller owns: a motion gate, a scroll, an open menu). On a single piece of
- * content: `forceVisibility`, which pins how THAT element looks. State belongs
- * to the container because one container feeds children whose looks are
- * opposite; appearance belongs to the element, where it is unambiguous.
- * Neither lever can hide content from a keyboard user — see ACCESSIBILITY.
- *
- * ACCESSIBILITY (WCAG 2.2 by construction):
- * - Revealed content is visually hidden at rest via position + opacity, so it
- *   stays in the accessibility tree and tab order — never display:none.
- * - Keyboard: revealed on :focus-within, so tabbing in shows it — with no dwell
- *   to wait through, and neither an inactive container nor a forced-hidden
- *   element can keep it dark.
- * - Touch: always visible on coarse pointers; never gated behind hover.
- * - Concealed (inverted) content is a mouse-only visual swap: it ignores
- *   :focus-within (a keyboard user must never watch content vanish) and stays
- *   visible on touch and in the a11y tree.
- * - Motion: honors prefers-reduced-motion.
+ * @input The containerReveal styles
+ * @output useContainerReveal, a headless hover and focus reveal primitive
+ * @position Core hook for content that shows or hides when its container is
+ *   hovered or focused, such as Thumbnail's remove button
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
@@ -53,6 +21,11 @@ const EMPTY = Object.freeze({});
 /**
  * Scoped, CSS-only hover/focus reveal for content inside a container.
  *
+ * Revealed content stays in the accessibility tree and the tab order. It
+ * shows on :focus-within without a delay, and it always shows on touch.
+ * Concealed content hides only for a mouse. Motion honors
+ * prefers-reduced-motion.
+ *
  * @example
  * ```
  * const {getContainerProps, getContentRevealProps} = useContainerReveal({

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

@@ -1 +1 @@
-{"version":3,"file":"useDevWarning.d.ts","sourceRoot":"","sources":["../../src/hooks/useDevWarning.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,OAAc,GACxB,IAAI,CAQN"}
+{"version":3,"file":"useDevWarning.d.ts","sourceRoot":"","sources":["../../src/hooks/useDevWarning.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,OAAc,GACxB,IAAI,CAQN"}