@astryxdesign/core 0.7.5 → 0.7.6-canary.00146a7

package/dist/hooks/useAnnounce.js

@@ -7,10 +7,11 @@
  * @input Uses React context and useCallback; DOM APIs and cancellable
  *   animation frames for a singleton live-region pair on the page body and
  *   one persistent polite/assertive pair inside each open Astryx modal
- * @output Exports useAnnounce hook and AnnouncePoliteness type; the internal
- *   modal context, the in-dialog region writer the busy-announcement hook
- *   uses, and the hook the modal route (`modalAnnounce.ts`, loaded only with
- *   an Astryx modal) installs itself through
+ * @output Exports useAnnounce hook (with its `hasReplace` option),
+ *   AnnouncePoliteness and UseAnnounceOptions types; the internal modal
+ *   context, the in-dialog region writer the busy-announcement hook uses, and
+ *   the hook the modal route (`modalAnnounce.ts`, loaded only with an Astryx
+ *   modal) installs itself through
  * @position Core a11y hook; provides imperative screen-reader announcements.
  *   A message follows the nearest open native modal enclosing its caller
  *   (`spec:AST-086` FR14): inside an Astryx modal it is written to that
@@ -18,15 +19,19 @@
  *   while a native modal is open; otherwise to the shared page-body pair.
  *   Containers are created empty (FR3), carry the two urgencies (FR5), join
  *   messages written before the previous is exposed and say an identical
- *   same-frame repeat once (FR9), and clear shortly after each announcement;
+ *   same-frame repeat once (FR9), except that a `hasReplace` instance's
+ *   message withdraws that instance's previous one not yet exposed, and clear
+ *   shortly after each announcement;
  *   the route in `modalAnnounce.ts` hands a message still unexposed when its
  *   modal stops being exposed to the channel exposed after it — the modal
- *   then on top, or the page body once no modal is open.
+ *   then on top, or the page body once no modal is open. Each write keeps a
+ *   receipt per announcer beside the words, which follows them wherever
+ *   they are moved, so the announcer can take back its own share.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
  */
-import { createContext, use, useCallback } from 'react';
+import { createContext, use, useCallback, useRef } from 'react';
 
 /**
  * Announcement urgency:
@@ -40,6 +45,51 @@ import { createContext, use, useCallback } from 'react';
  * Imperative screen-reader announcement function.
  */
 
+/** Options for `useAnnounce`. */
+
+/**
+ * Takes back one announcer's share of a message while it is not yet exposed,
+ * wherever the route put it. @internal
+ */
+
+/**
+ * One announcer's share of words on their way to being exposed. Whatever
+ * holds the words keeps the receipt beside them; when the words move — a
+ * modal hands them to the channel exposed after it, or releases words it
+ * held through an exit — the mover points the receipt at the new place, so
+ * the announcer's handle follows its words. @internal
+ */
+
+/** Words waiting to be exposed, with their announcers' receipts. @internal */
+
+/**
+ * The announcer's handle to `receipt`: it takes back the words wherever they
+ * are now, once. @internal
+ */
+export function handleOf(receipt) {
+  return () => {
+    const withdraw = receipt.withdraw;
+    receipt.withdraw = null;
+    withdraw?.();
+  };
+}
+
+/**
+ * Move `waiting` words elsewhere, one delivery per announcer and in order,
+ * and point each receipt at its delivery, so every announcer can still take
+ * back its own share (`spec:AST-086` FR9, FR14). The deliveries join where
+ * they land, so the words are spoken once. @internal
+ */
+export function forwardWaiting(waiting, deliver) {
+  for (const {
+    text,
+    receipts
+  } of waiting) {
+    for (const receipt of receipts) {
+      receipt.withdraw = deliver(text);
+    }
+  }
+}
 const CONTAINER_ATTR = 'data-astryx-live-region';
 
 // Visually-hidden clip block (matches the VisuallyHidden primitive). Applied
@@ -134,17 +184,22 @@ function getRegions() {
   };
   return regions;
 }
+
+/**
+ * Write `message` to the shared region for `politeness`, joining the messages
+ * not yet exposed. Returns how to take this write back while it waits.
+ */
 export function announceMessage(message, politeness) {
   const r = getRegions();
   if (!r) {
-    return;
+    return null;
   }
   const target = politeness === 'assertive' ? r.assertive : r.polite;
   const repeat = pendingMessages[politeness].find(pending => pending.text === message);
   if (repeat != null) {
     repeat.holders += 1;
     lastJoined = repeat;
-    return;
+    return () => withdrawPendingAnnouncement(repeat, politeness);
   }
   const pending = {
     text: message,
@@ -168,6 +223,7 @@ export function announceMessage(message, politeness) {
   // indefinitely. Scheduled per announce, so a newer announcement always
   // resets the countdown (the delay comfortably outlasts the rAF re-set).
   scheduleClear(politeness, target);
+  return () => withdrawPendingAnnouncement(pending, politeness);
 }
 
 /**
@@ -197,6 +253,12 @@ export function clearRegion(politeness) {
  * announced, so users browsing the DOM later do not encounter stale status
  * text; announcing again before the clear simply resets the countdown.
  *
+ * An instance created with `hasReplace` states one current state, such as a
+ * search's result count: each message it writes withdraws its previous one
+ * while that one is not yet exposed, so typing faster than a frame says only
+ * the latest count (`spec:AST-086` FR9).
+ *
+ * @param options - `hasReplace` (default false)
  * @example
  * ```
  * function Search() {
@@ -208,25 +270,38 @@ export function clearRegion(politeness) {
  * }
  * ```
  */
-export function useAnnounce() {
+export function useAnnounce({
+  hasReplace = false
+} = {}) {
   const modal = use(ModalAnnounceContext);
+  // A `hasReplace` instance's latest write, which its next message takes back
+  // if assistive technology has not had it yet.
+  const withdrawPreviousRef = useRef(null);
   return useCallback((message, politeness = 'polite') => {
+    if (hasReplace) {
+      const withdrawPrevious = withdrawPreviousRef.current;
+      withdrawPreviousRef.current = null;
+      withdrawPrevious?.();
+    }
+    let written;
     // Inside an Astryx modal's provider: the modal route decides, per call,
     // where the caller is heard — `modal` is non-null only where a provider
     // rendered, and rendering one loads the route.
     if (modal != null && modalRoute != null) {
-      modalRoute.announce(modal, message, politeness);
-      return;
-    }
-    if (!message) {
+      written = modalRoute.announce(modal, message, politeness);
+    } else if (!message) {
       // An empty message clears any lingering status from the region,
       // including messages joined but not yet exposed — useful when the
       // triggering context ends.
       clearRegion(politeness);
-      return;
+      written = null;
+    } else {
+      written = announceMessage(message, politeness);
+    }
+    if (hasReplace) {
+      withdrawPreviousRef.current = written;
     }
-    announceMessage(message, politeness);
-  }, [modal]);
+  }, [hasReplace, modal]);
 }
 
 // =============================================================================
@@ -292,33 +367,19 @@ export function enclosingModalDialog(element) {
  * exposure, covered and hold rules; without it — a native modal an app
  * renders without Astryx, and no Astryx modal anywhere — the words are
  * written to the dialog while it is open as a modal, else to the shared
- * channel. Internal: used by the busy-announcement hook.
+ * channel. Returns how to take the words back while they wait, wherever they
+ * move, so a busy start overtaken by its own outcome is never heard ahead of
+ * it inside a modal (`spec:AST-086` FR8). Internal: used by the
+ * busy-announcement hook.
  */
 export function announceInModal(dialog, message, politeness = 'polite') {
   if (modalRoute != null) {
-    modalRoute.announceInModal(dialog, message, politeness);
-    return;
+    return modalRoute.announceInModal(dialog, message, politeness);
   }
   if (isOpenModal(dialog)) {
-    writeModalRegion(dialog, message, politeness);
-  } else {
-    announceMessage(message, politeness);
-  }
-}
-
-/**
- * Withdraw one announcer's share of `message` from `dialog` before it is
- * exposed, written to its region or held by the route for the dialog's
- * close, so a busy start overtaken by its own outcome is never heard ahead
- * of it inside a modal (`spec:AST-086` FR8). Internal: used by the
- * busy-announcement hook's settle function.
- */
-export function withdrawFromModalPending(dialog, message, politeness = 'polite') {
-  if (modalRoute != null) {
-    modalRoute.withdrawFromModalPending(dialog, message, politeness);
-    return;
+    return writeModalRegion(dialog, message, politeness);
   }
-  withdrawFromModalRegion(dialog, message, politeness);
+  return announceMessage(message, politeness);
 }
 
 /** What the route asks of the writer in the write frame. @internal */
@@ -344,11 +405,25 @@ function cancelPending(pending) {
 
 /** Words written to `target` that assistive technology has not had yet. */
 export function unexposedMessages(target) {
+  return unexposedWords(target).map(words => words.text);
+}
+function waitingIn(pending) {
+  return pending.messages.map(text => ({
+    text,
+    receipts: pending.receipts.get(text) ?? []
+  }));
+}
+
+/**
+ * The words written to `target` that assistive technology has not had yet,
+ * with their announcers' receipts, for a hand-off that forwards them.
+ */
+export function unexposedWords(target) {
   const pending = pendingByRegion.get(target);
   if (pending == null) {
     return [];
   }
-  return pending.frame != null || pending.settleFrame != null ? pending.messages : [];
+  return pending.frame != null || pending.settleFrame != null ? waitingIn(pending) : [];
 }
 export function modalRegion(dialog, politeness) {
   return dialog.querySelector(`:scope > [${MODAL_REGION_ATTR}="${politeness}"]`);
@@ -376,20 +451,24 @@ function ensureModalRegion(dialog, politeness) {
 /**
  * Write `message` to the modal `dialog`'s own live region for `politeness`,
  * joining it to messages written there that are not yet exposed and saying
- * an identical repeat once; a holder count per text lets one announcer take
- * its share back (`withdrawFromModalPending`). The region-writing core,
- * shared by the full modal route and by the busy-announcement hook's fallback
- * for a native modal an app renders without Astryx. `guard`, supplied by the
- * route, re-checks exposure in the write frame and redirects the joined words
- * when the dialog stopped being exposed meanwhile.
+ * an identical repeat once. The region-writing core, shared by the full
+ * modal route and by the busy-announcement hook's fallback for a native
+ * modal an app renders without Astryx. `guard`, supplied by the route,
+ * re-checks exposure in the write frame and redirects the waiting words when
+ * the dialog stopped being exposed meanwhile. Returns this announcer's
+ * handle: it takes back only its own share, only while the words wait, and
+ * follows them when the route moves them.
  */
 export function writeModalRegion(dialog, message, politeness, guard) {
   const target = ensureModalRegion(dialog, politeness);
   const unexposed = unexposedMessages(target);
   const messages = unexposed.includes(message) ? unexposed : [...unexposed, message];
   const previous = pendingByRegion.get(target);
-  const holders = new Map(unexposed.length > 0 && previous != null ? previous.holders : []);
-  holders.set(message, (holders.get(message) ?? 0) + 1);
+  const receipts = unexposed.length > 0 && previous != null ? previous.receipts : new Map();
+  const receipt = {
+    withdraw: null
+  };
+  receipts.set(message, [...(receipts.get(message) ?? []), receipt]);
   if (previous != null) {
     cancelPending(previous);
   }
@@ -398,7 +477,7 @@ export function writeModalRegion(dialog, message, politeness, guard) {
   target.textContent = '';
   const pending = {
     messages,
-    holders,
+    receipts,
     frame: null,
     settleFrame: null,
     timer: null
@@ -407,9 +486,9 @@ export function writeModalRegion(dialog, message, politeness, guard) {
     pending.frame = null;
     if (guard != null && !guard.isExposed()) {
       // Stopped being exposed between the call and this frame: the words go
-      // where they will be heard.
+      // where they will be heard, their receipts with them.
       pendingByRegion.delete(target);
-      guard.redirect(pending.messages.join(' '));
+      guard.redirect(waitingIn(pending));
       return;
     }
     target.textContent = pending.messages.join(' ');
@@ -422,35 +501,42 @@ export function writeModalRegion(dialog, message, politeness, guard) {
     }, CLEAR_DELAY_MS);
   });
   pendingByRegion.set(target, pending);
+  receipt.withdraw = () => withdrawFromRegion(target, message, receipt);
+  return handleOf(receipt);
 }
 
 /**
- * Withdraw one announcer's share of `message` from `dialog`'s region before
- * it is exposed — written but not yet spoken — so a busy start overtaken by
- * its own outcome is never heard ahead of it (`spec:AST-086` FR8). The
- * message stays while another announcer holds it. The region half of
- * `withdrawFromModalPending`; the route also drops words it holds for the
- * dialog's close.
+ * Withdraw one announcer's share of `message` from `target` while it is not
+ * yet exposed — written but not yet spoken — so a busy start overtaken by its
+ * own outcome is never heard ahead of it (`spec:AST-086` FR8), and a
+ * `hasReplace` instance's next message replaces its previous one (FR9,
+ * FR14). The message stays while another announcer holds it; a receipt not
+ * among the waiting words (they were exposed, cleared, or moved) takes back
+ * nothing.
  */
-export function withdrawFromModalRegion(dialog, message, politeness = 'polite') {
-  const region = modalRegion(dialog, politeness);
-  const pending = region == null ? undefined : pendingByRegion.get(region);
-  if (region != null && pending != null && (pending.frame != null || pending.settleFrame != null)) {
-    const count = pending.holders.get(message) ?? 0;
-    if (count > 1) {
-      pending.holders.set(message, count - 1);
-    } else if (count === 1) {
-      pending.holders.delete(message);
-      pending.messages = pending.messages.filter(text => text !== message);
-      if (pending.messages.length === 0) {
-        cancelPending(pending);
-        pendingByRegion.delete(region);
-        region.textContent = '';
-      } else if (pending.frame == null) {
-        // Already written this frame, not yet taken: show the rest.
-        region.textContent = pending.messages.join(' ');
-      }
-    }
+function withdrawFromRegion(target, message, receipt) {
+  const pending = pendingByRegion.get(target);
+  if (pending == null || pending.frame == null && pending.settleFrame == null) {
+    return;
+  }
+  const receipts = pending.receipts.get(message);
+  const at = receipts?.indexOf(receipt) ?? -1;
+  if (receipts == null || at < 0) {
+    return;
+  }
+  receipts.splice(at, 1);
+  if (receipts.length > 0) {
+    return;
+  }
+  pending.receipts.delete(message);
+  pending.messages = pending.messages.filter(text => text !== message);
+  if (pending.messages.length === 0) {
+    cancelPending(pending);
+    pendingByRegion.delete(target);
+    target.textContent = '';
+  } else if (pending.frame == null) {
+    // Already written this frame, not yet taken: show the rest.
+    target.textContent = pending.messages.join(' ');
   }
 }
 

package/dist/hooks/useAnnounceRenderedText.d.ts

@@ -3,7 +3,7 @@
  * @input A ref to a rendered element, whether it is showing, and a token that
  *   marks a new occasion to speak
  * @output Announces that element's own rendered text through the persistent
- *   polite live region
+ *   polite live region, or through the announcer the owner passes
  * @position Core a11y hook; mirrors on-screen content into the shared live
  *   region by reading the DOM
  *
@@ -39,7 +39,7 @@
  * admission. Import it by path from inside the package.
  */
 import { type RefObject } from 'react';
-import { type AnnouncePoliteness } from './useAnnounce.js';
+import { type AnnounceFn, type AnnouncePoliteness } from './useAnnounce.js';
 export interface AnnounceRenderedTextOptions {
     /**
      * Text present or changed while the document loads or hydrates is silent;
@@ -53,6 +53,14 @@ export interface AnnounceRenderedTextOptions {
      * every other message polite (`spec:AST-086` FR5). Defaults to polite.
      */
     politeness?: AnnouncePoliteness;
+    /**
+     * The owner's announcer to speak through, when the rendered text states
+     * the next value of a state that announcer states: a picker's empty-panel
+     * message goes through its search's `hasReplace` instance, so the two
+     * replace each other while not yet exposed (`spec:AST-086` FR13).
+     * Defaults to this hook's own instance.
+     */
+    announce?: AnnounceFn;
 }
 /** The rendered text an assistive technology would read from `element`. */
 export declare function renderedText(element: HTMLElement): string;
@@ -76,5 +84,5 @@ export declare function renderedText(element: HTMLElement): string;
  * useAnnounceRenderedText(emptyStateRef, isPanelEmpty, searchQuery);
  * ```
  */
-export declare function useAnnounceRenderedText(ref: RefObject<HTMLElement | null>, isShown: boolean, occasion: string, { skipFirstRender, politeness, }?: AnnounceRenderedTextOptions): void;
+export declare function useAnnounceRenderedText(ref: RefObject<HTMLElement | null>, isShown: boolean, occasion: string, { skipFirstRender, politeness, announce: ownerAnnounce, }?: AnnounceRenderedTextOptions): void;
 //# sourceMappingURL=useAnnounceRenderedText.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useAnnounceRenderedText.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounceRenderedText.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAClE,OAAO,EAAc,KAAK,kBAAkB,EAAC,MAAM,eAAe,CAAC;AAgCnE,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAOzD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,EACE,eAAuB,EACvB,UAAqB,GACtB,GAAE,2BAAgC,GAClC,IAAI,CAqDN"}
+{"version":3,"file":"useAnnounceRenderedText.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounceRenderedText.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAClE,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAgCvB,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAOzD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,EACE,eAAuB,EACvB,UAAqB,EACrB,QAAQ,EAAE,aAAa,GACxB,GAAE,2BAAgC,GAClC,IAAI,CAsDN"}

package/dist/hooks/useAnnounceRenderedText.js

@@ -7,7 +7,7 @@
  * @input A ref to a rendered element, whether it is showing, and a token that
  *   marks a new occasion to speak
  * @output Announces that element's own rendered text through the persistent
- *   polite live region
+ *   polite live region, or through the announcer the owner passes
  * @position Core a11y hook; mirrors on-screen content into the shared live
  *   region by reading the DOM
  *
@@ -101,9 +101,11 @@ export function renderedText(element) {
  */
 export function useAnnounceRenderedText(ref, isShown, occasion, {
   skipFirstRender = false,
-  politeness = 'polite'
+  politeness = 'polite',
+  announce: ownerAnnounce
 } = {}) {
-  const announce = useAnnounce();
+  const ownAnnounce = useAnnounce();
+  const announce = ownerAnnounce ?? ownAnnounce;
   const spokenRef = useRef(null);
   const isHydrating = useIsHydrating();
   // Captured once: an owner rendered before the document finished loading, or

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,CAmEZ"}
+{"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"}

package/dist/hooks/useBusyAnnouncement.js

@@ -26,7 +26,7 @@
  * this is a shared implementation detail of Astryx's busy controls.
  */
 import { useCallback, useEffect, useRef } from 'react';
-import { announceInModal, enclosingModalDialog, takeJoinedAnnouncement, useAnnounce, withdrawFromModalPending, withdrawPendingAnnouncement } from "./useAnnounce.js";
+import { announceInModal, enclosingModalDialog, takeJoinedAnnouncement, useAnnounce, withdrawPendingAnnouncement } from "./useAnnounce.js";
 export function useBusyAnnouncement(isBusy, message, elementRef) {
   const announce = useAnnounce();
   const hasAnnouncedRef = useRef(false);
@@ -34,7 +34,8 @@ export function useBusyAnnouncement(isBusy, message, elementRef) {
   // This busy start's share of the shared channel's pending text, until it
   // settles.
   const channelMessageRef = useRef(null);
-  // Or its write inside a modal's container, until it settles.
+  // Or how to take back its write inside a modal, wherever the modal moves
+  // it, until it settles.
   const modalMessageRef = useRef(null);
   useEffect(() => {
     if (!isBusy) {
@@ -58,11 +59,7 @@ export function useBusyAnnouncement(isBusy, message, elementRef) {
       // nearest Astryx modal around this hook's caller.
       const dialog = enclosingModalDialog(elementRef.current);
       if (dialog != null) {
-        announceInModal(dialog, message);
-        modalMessageRef.current = {
-          dialog,
-          message
-        };
+        modalMessageRef.current = announceInModal(dialog, message);
       } else {
         announce(message, 'polite');
         channelMessageRef.current = takeJoinedAnnouncement();
@@ -88,12 +85,9 @@ export function useBusyAnnouncement(isBusy, message, elementRef) {
       channelMessageRef.current = null;
     }
     if (modalMessageRef.current != null) {
-      const {
-        dialog,
-        message
-      } = modalMessageRef.current;
-      withdrawFromModalPending(dialog, message, 'polite');
+      const withdraw = modalMessageRef.current;
       modalMessageRef.current = null;
+      withdraw();
     }
   }, []);
 }

package/dist/hooks/useClickableContainer.d.ts

@@ -1,7 +1,8 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list
+ * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;
+ *   hasInteractiveAncestor and the shared innermostInteractive walk
  * @position Core hook for clickable containers that safely handle nested interactive elements
  *
  * Solves the "nested interactive elements" problem: when a card is clickable
@@ -16,6 +17,12 @@
  * - /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,9 +36,22 @@ 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

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;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAyB,KAAK,SAAS,EAAE,KAAK,UAAU,EAAC,MAAM,OAAO,CAAC;AAG9E;;;;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;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAE5E;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"}

package/dist/hooks/useClickableContainer.js

@@ -5,7 +5,8 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list
+ * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;
+ *   hasInteractiveAncestor and the shared innermostInteractive walk
  * @position Core hook for clickable containers that safely handle nested interactive elements
  *
  * Solves the "nested interactive elements" problem: when a card is clickable
@@ -22,6 +23,13 @@
 import { useCallback, useEffect } from 'react';
 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,13 +41,39 @@ 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
@@ -48,14 +82,7 @@ const NON_INTERACTIVE_SELECTORS = '[aria-readonly="true"]';
  * instead of a short hand-rolled selector list per caller.
  */
 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) != null;
 }
 
 /**
@@ -115,7 +142,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 => {