stream-chat-react 14.11.0 → 14.12.0

package/dist/es/components/Accessibility/hooks/useInertWhenHidden.mjs

@@ -0,0 +1,85 @@
+import React, { useMemo } from "react";
+//#region src/components/Accessibility/hooks/useInertWhenHidden.ts
+var INERT_PRESENT = parseInt(React.version, 10) >= 19 ? true : "true";
+var SHOWN_PROPS = {
+	"aria-hidden": void 0,
+	hidden: void 0,
+	inert: void 0,
+	tabIndex: void 0
+};
+var HIDDEN_PROPS = {
+	"aria-hidden": true,
+	hidden: true,
+	inert: INERT_PRESENT,
+	tabIndex: -1
+};
+var HIDDEN_PROPS_WITHOUT_HIDDEN_ATTRIBUTE = {
+	"aria-hidden": true,
+	hidden: void 0,
+	inert: INERT_PRESENT,
+	tabIndex: -1
+};
+/**
+* Canonical way to fully hide a control from assistive technology AND the tab
+* order while it must stay mounted.
+*
+* @remarks
+* **Prefer not rendering.** The simplest and most robust fix for a control that
+* should be unavailable is to *not render it at all* when it is hidden. Reach
+* for this hook only when the element MUST stay mounted — e.g. to preserve
+* internal state, layout measurements, or enter/exit transitions.
+*
+* @example
+* ```tsx
+* const Toolbar = ({ collapsed }: { collapsed: boolean }) => {
+*   const inertProps = useInertWhenHidden(collapsed);
+*   return <button {...inertProps}>Add attachment</button>;
+* };
+* ```
+*
+* When `hidden === true`, the returned props make the element:
+* - absent from the accessibility tree (`aria-hidden`, `hidden`),
+* - unreachable via Tab (`tabIndex={-1}`, `inert`),
+* - non-interactive (`inert`).
+*
+* When `hidden === false`, every returned attribute is `undefined`, so spreading
+* the object is a no-op and the element behaves exactly as normal. In
+* particular, `aria-hidden` is omitted entirely (never emitted as
+* `aria-hidden="false"`).
+*
+* Exact attribute values rendered to the DOM:
+* - hidden: `aria-hidden=""(true)`, `hidden`, `tabindex="-1"`, `inert`
+* - shown:  none of the above attributes present
+*
+* **Cross-React-version handling of `inert`:** React 19 supports `inert` as a
+* native boolean prop (`inert={true}` → DOM `inert=""`). React 17/18 do not
+* recognize it and only forward it as a string (`inert="true"` → DOM
+* `inert="true"`). Either of the *other* forms (a boolean on React 17/18, or an
+* empty string on React 19) emits a console warning and/or drops the attribute.
+* We therefore pick the correct form per major version via `React.version`. The
+* resulting DOM attribute is present and falls back to `tabIndex={-1}` +
+* `aria-hidden` on the rare engines lacking `inert` support.
+*
+* **Styling is out of scope.** The HTML `hidden` attribute applies
+* `display: none`. If a consumer needs the element to remain *visible in the
+* layout* (e.g. hidden purely via CSS or kept for transitions), pass
+* `{ setHiddenAttribute: false }` so the `hidden` attribute is omitted while the
+* a11y/focus semantics (`aria-hidden`, `inert`, `tabIndex={-1}`) still apply.
+* The remaining styling is then the consumer's concern.
+*
+* @param hidden Whether the control is currently hidden.
+* @param options Behavior options — see {@link UseInertWhenHiddenOptions}. Use
+*   `{ setHiddenAttribute: false }` for elements hidden via CSS/transition.
+* @returns A stable, memoized props object to spread onto the element.
+*/
+var useInertWhenHidden = (hidden, options) => {
+	const setHiddenAttribute = options?.setHiddenAttribute ?? true;
+	return useMemo(() => {
+		if (!hidden) return SHOWN_PROPS;
+		return setHiddenAttribute ? HIDDEN_PROPS : HIDDEN_PROPS_WITHOUT_HIDDEN_ATTRIBUTE;
+	}, [hidden, setHiddenAttribute]);
+};
+//#endregion
+export { useInertWhenHidden };
+
+//# sourceMappingURL=useInertWhenHidden.mjs.map

package/dist/es/components/Accessibility/hooks/useInertWhenHidden.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInertWhenHidden.mjs","names":[],"sources":["../../../../../src/components/Accessibility/hooks/useInertWhenHidden.ts"],"sourcesContent":["import React, { useMemo } from 'react';\n\n/**\n * The set of props returned by {@link useInertWhenHidden}, to be spread onto the\n * element that must remain mounted while visually hidden.\n *\n * `inert` is typed as `boolean | undefined` so the object spreads cleanly onto a\n * JSX host element (React 19 types `inert?: boolean`; React 17/18 don't declare\n * it at all, so an extra prop via spread is accepted). The RUNTIME value differs\n * by React major version (string `'true'` on 17/18) — see the implementation\n * note on {@link useInertWhenHidden} — and is cast to `boolean` at the source so\n * the public type stays spread-safe. Consumers spread it; they never read it.\n */\nexport type InertWhenHiddenProps = {\n  'aria-hidden': true | undefined;\n  hidden: boolean | undefined;\n  inert: boolean | undefined;\n  tabIndex: number | undefined;\n};\n\n/**\n * React 19 recognizes `inert` as a native boolean prop and renders\n * `inert={true}` to the DOM attribute `inert=\"\"` (no warning). React 17/18 do\n * NOT know `inert`; they forward it only as a string, rendering `inert=\"true\"`\n * (a valid present boolean attribute) with no warning. Passing a boolean to\n * React 17/18, or an empty string to React 19, produces a console warning and/or\n * drops the attribute — so we select the warning-free form per major version.\n */\nconst REACT_MAJOR = parseInt(React.version, 10);\n// Runtime value differs by React major (boolean on 19, the string 'true' on 17/18), but the\n// public type is `boolean | undefined` so the props spread cleanly onto JSX. The string form\n// is cast here — it is the only place the type/runtime divergence is reconciled.\nconst INERT_PRESENT = (REACT_MAJOR >= 19 ? true : 'true') as unknown as boolean;\n\nconst SHOWN_PROPS: InertWhenHiddenProps = {\n  'aria-hidden': undefined,\n  hidden: undefined,\n  inert: undefined,\n  tabIndex: undefined,\n};\n\nconst HIDDEN_PROPS: InertWhenHiddenProps = {\n  'aria-hidden': true,\n  hidden: true,\n  inert: INERT_PRESENT,\n  tabIndex: -1,\n};\n\nconst HIDDEN_PROPS_WITHOUT_HIDDEN_ATTRIBUTE: InertWhenHiddenProps = {\n  'aria-hidden': true,\n  hidden: undefined,\n  inert: INERT_PRESENT,\n  tabIndex: -1,\n};\n\n/**\n * Options for {@link useInertWhenHidden}.\n */\nexport type UseInertWhenHiddenOptions = {\n  /**\n   * Whether to set the HTML `hidden` attribute (which applies `display: none`)\n   * when `hidden` is `true`. Defaults to `true`.\n   *\n   * Set to `false` for elements whose visual hiding is already handled by CSS\n   * (e.g. an opacity/scale/`max-width` transition) — the `hidden` attribute\n   * would force `display: none` and kill the transition. With `false`, the hook\n   * still applies `aria-hidden`, `inert`, and `tabIndex={-1}` so the element is\n   * removed from the accessibility tree and tab order while staying laid out.\n   */\n  setHiddenAttribute?: boolean;\n};\n\n/**\n * Canonical way to fully hide a control from assistive technology AND the tab\n * order while it must stay mounted.\n *\n * @remarks\n * **Prefer not rendering.** The simplest and most robust fix for a control that\n * should be unavailable is to *not render it at all* when it is hidden. Reach\n * for this hook only when the element MUST stay mounted — e.g. to preserve\n * internal state, layout measurements, or enter/exit transitions.\n *\n * @example\n * ```tsx\n * const Toolbar = ({ collapsed }: { collapsed: boolean }) => {\n *   const inertProps = useInertWhenHidden(collapsed);\n *   return <button {...inertProps}>Add attachment</button>;\n * };\n * ```\n *\n * When `hidden === true`, the returned props make the element:\n * - absent from the accessibility tree (`aria-hidden`, `hidden`),\n * - unreachable via Tab (`tabIndex={-1}`, `inert`),\n * - non-interactive (`inert`).\n *\n * When `hidden === false`, every returned attribute is `undefined`, so spreading\n * the object is a no-op and the element behaves exactly as normal. In\n * particular, `aria-hidden` is omitted entirely (never emitted as\n * `aria-hidden=\"false\"`).\n *\n * Exact attribute values rendered to the DOM:\n * - hidden: `aria-hidden=\"\"(true)`, `hidden`, `tabindex=\"-1\"`, `inert`\n * - shown:  none of the above attributes present\n *\n * **Cross-React-version handling of `inert`:** React 19 supports `inert` as a\n * native boolean prop (`inert={true}` → DOM `inert=\"\"`). React 17/18 do not\n * recognize it and only forward it as a string (`inert=\"true\"` → DOM\n * `inert=\"true\"`). Either of the *other* forms (a boolean on React 17/18, or an\n * empty string on React 19) emits a console warning and/or drops the attribute.\n * We therefore pick the correct form per major version via `React.version`. The\n * resulting DOM attribute is present and falls back to `tabIndex={-1}` +\n * `aria-hidden` on the rare engines lacking `inert` support.\n *\n * **Styling is out of scope.** The HTML `hidden` attribute applies\n * `display: none`. If a consumer needs the element to remain *visible in the\n * layout* (e.g. hidden purely via CSS or kept for transitions), pass\n * `{ setHiddenAttribute: false }` so the `hidden` attribute is omitted while the\n * a11y/focus semantics (`aria-hidden`, `inert`, `tabIndex={-1}`) still apply.\n * The remaining styling is then the consumer's concern.\n *\n * @param hidden Whether the control is currently hidden.\n * @param options Behavior options — see {@link UseInertWhenHiddenOptions}. Use\n *   `{ setHiddenAttribute: false }` for elements hidden via CSS/transition.\n * @returns A stable, memoized props object to spread onto the element.\n */\nexport const useInertWhenHidden = (\n  hidden: boolean,\n  options?: UseInertWhenHiddenOptions,\n): InertWhenHiddenProps => {\n  const setHiddenAttribute = options?.setHiddenAttribute ?? true;\n  return useMemo(() => {\n    if (!hidden) return SHOWN_PROPS;\n    return setHiddenAttribute ? HIDDEN_PROPS : HIDDEN_PROPS_WITHOUT_HIDDEN_ATTRIBUTE;\n  }, [hidden, setHiddenAttribute]);\n};\n"],"mappings":";;AAgCA,IAAM,gBAJc,SAAS,MAAM,SAAS,EAIrB,KAAe,KAAK,OAAO;AAElD,IAAM,cAAoC;CACxC,eAAe,KAAA;CACf,QAAQ,KAAA;CACR,OAAO,KAAA;CACP,UAAU,KAAA;AACZ;AAEA,IAAM,eAAqC;CACzC,eAAe;CACf,QAAQ;CACR,OAAO;CACP,UAAU;AACZ;AAEA,IAAM,wCAA8D;CAClE,eAAe;CACf,QAAQ,KAAA;CACR,OAAO;CACP,UAAU;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,IAAa,sBACX,QACA,YACyB;CACzB,MAAM,qBAAqB,SAAS,sBAAsB;CAC1D,OAAO,cAAc;EACnB,IAAI,CAAC,QAAQ,OAAO;EACpB,OAAO,qBAAqB,eAAe;CAC7C,GAAG,CAAC,QAAQ,kBAAkB,CAAC;AACjC"}

package/dist/es/components/Accessibility/hooks/useInteractionAnnouncements.mjs

@@ -0,0 +1,155 @@
+import { useTranslationContext } from "../../../context/TranslationContext.mjs";
+import { useAriaLiveAnnouncer } from "../useAriaLiveAnnouncer.mjs";
+import { useDebouncedAnnounce } from "../scheduling/useDebouncedAnnounce.mjs";
+import { useMemo, useRef } from "react";
+//#region src/components/Accessibility/hooks/useInteractionAnnouncements.ts
+/**
+* One entry per interaction — the single place an interaction is registered. Each
+* resolver contains a LITERAL `t('aria/…')` call so that `i18next-cli extract`
+* (run via `yarn build-translations`) discovers and generates the key across all
+* locales. Keys must never be built dynamically (e.g. `t(someVariable)`) or
+* extraction silently misses them. Adding an interaction = one line here + one
+* line in {@link InteractionAnnouncementParams} (+ an override in
+* {@link INTERACTION_PRIORITIES} only if it is not `polite`).
+*/
+var INTERACTION_MESSAGES = {
+	"audioPlayer.playbackRateChanged": (t, params) => t("Playback speed {{ rate }}x", { rate: params.rate }),
+	"channel.opened": (t, params) => t("aria/Opened channel: {{ name }}", { name: params.name }),
+	"command.selected": (t, params) => t("aria/Command activated: {{ command }}", { command: params.command }),
+	"giphy.canceled": (t) => t("aria/Giphy canceled"),
+	"giphy.sent": (t) => t("aria/Giphy sent"),
+	"giphy.shuffled": (t, params) => params.title ? t("aria/Giphy image changed: {{ title }}", { title: params.title }) : t("aria/Giphy image changed"),
+	"poll.dialogOpened": (t) => `${t("aria/Poll dialog opened")}. ${t("Create a question, add options, and configure poll settings")}. ${t("aria/Press Enter to start typing")}.`,
+	"poll.optionDropped": (t, params) => t("aria/Dropped \"{{ option }}\" at position {{ position }}.", {
+		option: params.option,
+		position: params.position
+	}),
+	"poll.optionPickedUp": (t, params) => t("aria/Picked up \"{{ option }}\". Use arrow keys to reorder. Press Space or Tab to drop.", { option: params.option }),
+	"poll.optionRemoved": (t, params) => t("aria/Removed option {{ option }}", { option: params.option }),
+	"poll.sent": (t) => t("aria/Poll sent"),
+	"search.cleared": (t) => t("aria/Search cleared"),
+	"search.resultCount": (t, params) => {
+		if (params.count <= 0) return t("aria/No search results found");
+		const count = t("aria/{{ count }} search results", { count: params.count });
+		return params.allResultsLoaded ? `${count}. ${t("All results loaded")}` : count;
+	},
+	"suggestions.count": (t, params) => params.suggestionsLabel ? t("aria/{{ count }} {{ suggestionsLabel }}", {
+		count: params.count,
+		suggestionsLabel: params.suggestionsLabel
+	}) : t("aria/{{ count }} suggestions", { count: params.count }),
+	"thread.opened": (t, params) => t("aria/Opened thread in {{ name }}", { name: params.name }),
+	"user.selected": (t, params) => t("aria/User selected: {{ user }}", { user: params.user }),
+	"voiceRecording.attached": (t) => t("aria/Voice recording attached"),
+	"voiceRecording.paused": (t) => t("aria/Recording paused"),
+	"voiceRecording.resumed": (t) => t("aria/Recording resumed"),
+	"voiceRecording.sent": (t) => t("aria/Voice message sent"),
+	"voiceRecording.started": (t) => t("aria/Recording started")
+};
+/**
+* Per-interaction aria-live priority. Interactions default to `polite`; list one
+* here only to override it (e.g. with `assertive`).
+*/
+var INTERACTION_PRIORITIES = {
+	"poll.dialogOpened": "assertive",
+	"poll.optionDropped": "assertive",
+	"poll.optionPickedUp": "assertive"
+};
+/**
+* Per-interaction dedupe window (ms): an identical message for this interaction is announced at
+* most once per window (see {@link AriaLiveAnnounceOptions.dedupeMs}). List an interaction here
+* only when the SAME open/mount can fire it more than once in quick succession — e.g. a mount
+* effect double-invoked by React StrictMode (dev) — so the user does not hear a duplicate.
+*/
+var INTERACTION_DEDUPE_MS = {
+	"audioPlayer.playbackRateChanged": 300,
+	"poll.dialogOpened": 1e3
+};
+/**
+* Default per-interaction debounce delay (ms). Only list rapidly-updating streams where just the
+* settled value should be read (e.g. the autocomplete count as the query filters). Discrete
+* confirmations (Giphy/Poll sent, user selected) are NOT listed and announce immediately. A call
+* site can override (or opt into) a delay for a single call via `params.debounceMs` — see
+* {@link InteractionDeliveryOptions}.
+*
+* `suggestions.count` is a CONSEQUENCE OF TYPING, so the delay does double duty: it coalesces
+* rapid filters into the settled value AND lets the screen reader's per-keystroke typing echo
+* (the spoken character + field re-read) finish first. A polite update that lands mid-echo gets
+* queued behind a long re-read and is perceived as buried; waiting past the echo makes the count
+* the next thing spoken once the user pauses. This is a heuristic — echo length varies with the
+* SR's "speak typed words/characters" setting and field content — so tune if it still collides.
+*/
+var INTERACTION_DEBOUNCE_MS = {
+	"search.resultCount": 1e3,
+	"suggestions.count": 500
+};
+/**
+* Default per-interaction delay (ms) for the immediate (non-debounced) path — a single deferred
+* emit scheduled in the announcer PROVIDER (see {@link AriaLiveAnnounceOptions.delayMs}), so it
+* SURVIVES the calling component unmounting (unlike a debounce, whose timer is cleared on unmount).
+*
+* Opening a channel/thread moves focus to the (auto-focusing) message composer; the screen reader
+* announces that newly-focused element first, and a live-region message emitted alongside it is
+* superseded and dropped. The delay defers the confirmation past that focus read-out so it is spoken
+* next, in a calm moment. It is a provider delay rather than a debounce specifically because
+* selecting the item can unmount its list row (and the whole list, on mobile) — a per-row debounce
+* would be cancelled mid-flight, swallowing the confirmation.
+*/
+var INTERACTION_DELAY_MS = {
+	"channel.opened": 1500,
+	"command.selected": 1500,
+	"thread.opened": 1500
+};
+/**
+* Thin, typed wrapper over the aria-live announcer exposing intention-revealing
+* helpers for transient, user-initiated UI interactions (e.g. a Giphy being
+* sent, a poll being created, a mention being picked). They map to i18n keys with
+* baked-in priorities and reuse the existing live region via
+* {@link useAriaLiveAnnouncer}. New interactions are registered as a single entry
+* in {@link INTERACTION_MESSAGES}.
+*/
+var useInteractionAnnouncements = () => {
+	const announce = useAriaLiveAnnouncer();
+	const { t } = useTranslationContext();
+	const { announce: announceDebounced, cancel: cancelDebounced } = useDebouncedAnnounce(announce);
+	const pendingImmediateCancelsRef = useRef({});
+	return useMemo(() => ({
+		announceInteraction: (interaction, params) => {
+			const resolveMessage = INTERACTION_MESSAGES[interaction];
+			if (!resolveMessage) return;
+			const message = resolveMessage(t, params);
+			const priority = INTERACTION_PRIORITIES[interaction] ?? "polite";
+			const debounceMs = params?.debounceMs ?? INTERACTION_DEBOUNCE_MS[interaction];
+			if (debounceMs === void 0) {
+				const delayMs = params?.delayMs ?? INTERACTION_DELAY_MS[interaction];
+				pendingImmediateCancelsRef.current[interaction]?.();
+				pendingImmediateCancelsRef.current[interaction] = announce(message, {
+					dedupeMs: INTERACTION_DEDUPE_MS[interaction],
+					delayMs,
+					priority
+				});
+				return;
+			}
+			announceDebounced(interaction, message, debounceMs, priority);
+		},
+		cancelInteraction: (interaction) => {
+			cancelDebounced(interaction);
+			const pending = pendingImmediateCancelsRef.current;
+			if (interaction) {
+				pending[interaction]?.();
+				delete pending[interaction];
+			} else {
+				Object.values(pending).forEach((cancel) => cancel?.());
+				pendingImmediateCancelsRef.current = {};
+			}
+		}
+	}), [
+		announce,
+		announceDebounced,
+		cancelDebounced,
+		t
+	]);
+};
+//#endregion
+export { useInteractionAnnouncements };
+
+//# sourceMappingURL=useInteractionAnnouncements.mjs.map

package/dist/es/components/Accessibility/hooks/useInteractionAnnouncements.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInteractionAnnouncements.mjs","names":[],"sources":["../../../../../src/components/Accessibility/hooks/useInteractionAnnouncements.ts"],"sourcesContent":["import { useMemo, useRef } from 'react';\n\nimport type { AriaLivePriority } from '../useAriaLiveAnnouncer';\nimport { useAriaLiveAnnouncer } from '../useAriaLiveAnnouncer';\nimport { useDebouncedAnnounce } from '../scheduling';\nimport { useTranslationContext } from '../../../context/TranslationContext';\n\ntype TranslateFn = ReturnType<typeof useTranslationContext>['t'];\n\n/**\n * Optional delivery overrides a call site may pass ALONGSIDE an interaction's message params.\n * These are not consumed by the message resolver — they only affect how the announcement is\n * delivered. `debounceMs` overrides that interaction's default debounce ({@link\n * INTERACTION_DEBOUNCE_MS}) for THIS call, and enables debouncing for an interaction that has no\n * default. `delayMs` overrides the default delay ({@link INTERACTION_DELAY_MS}) for the\n * (non-debounced) immediate path. Param-less (discrete) interactions are always immediate and do\n * not accept overrides.\n *\n * `debounceMs` vs `delayMs`: a debounce collapses rapid repeats on a per-call-site timer and is\n * **cancelled if that call site unmounts** — right for a value that keeps changing in place (a\n * result count). `delayMs` schedules a single deferred emit in the shared announcer PROVIDER, so it\n * **survives the caller unmounting** — right for a one-shot confirmation whose origin (e.g. a list\n * row) disappears on the very action being confirmed (opening a channel/thread hides the list on\n * mobile). Both let the message land after a competing focus/typing read-out. `debounceMs` wins if\n * both are given.\n */\nexport type InteractionDeliveryOptions = { debounceMs?: number; delayMs?: number };\n\n/**\n * Parameters accepted by each parameterized interaction announcement.\n * Interactions that take no parameters map to `undefined`. Param-ful interactions additionally\n * accept {@link InteractionDeliveryOptions} (e.g. a per-call `debounceMs`).\n */\nexport type InteractionAnnouncementParams = {\n  /** Audio playback speed was changed via the playback-rate button. `rate` is the new multiplier. */\n  'audioPlayer.playbackRateChanged': InteractionDeliveryOptions & { rate: number };\n  /** A channel was opened from the channel list. `name` is its display title. */\n  'channel.opened': InteractionDeliveryOptions & { name: string };\n  /** A slash command was activated from the Instant Commands menu. `command` is its name. */\n  'command.selected': InteractionDeliveryOptions & { command: string };\n  'giphy.canceled': undefined;\n  'giphy.sent': undefined;\n  'giphy.shuffled': InteractionDeliveryOptions & { title?: string };\n  'poll.dialogOpened': undefined;\n  /** A poll option was dropped at a new position during keyboard reorder. */\n  'poll.optionDropped': InteractionDeliveryOptions & {\n    option: string;\n    position: number;\n  };\n  /** A poll option was picked up to start a keyboard reorder. `option` is its text (or a fallback). */\n  'poll.optionPickedUp': InteractionDeliveryOptions & { option: string };\n  'poll.optionRemoved': InteractionDeliveryOptions & { option: string };\n  'poll.sent': undefined;\n  'search.cleared': undefined;\n  'search.resultCount': InteractionDeliveryOptions & {\n    /** Whether every active source is fully loaded — appends an \"all results loaded\" clause. */\n    allResultsLoaded?: boolean;\n    count: number;\n  };\n  'suggestions.count': InteractionDeliveryOptions & {\n    count: number;\n    suggestionsLabel?: string;\n  };\n  /** A thread was opened from the thread list. `name` is its channel's display title. */\n  'thread.opened': InteractionDeliveryOptions & { name: string };\n  'user.selected': InteractionDeliveryOptions & { user: string };\n  /** A finished voice recording was added to the composer (async multi-send: not sent yet). */\n  'voiceRecording.attached': undefined;\n  'voiceRecording.paused': undefined;\n  'voiceRecording.resumed': undefined;\n  /** A finished voice recording was sent immediately as a message. */\n  'voiceRecording.sent': undefined;\n  'voiceRecording.started': undefined;\n};\n\nexport type InteractionAnnouncementType = keyof InteractionAnnouncementParams;\n\n/**\n * One entry per interaction — the single place an interaction is registered. Each\n * resolver contains a LITERAL `t('aria/…')` call so that `i18next-cli extract`\n * (run via `yarn build-translations`) discovers and generates the key across all\n * locales. Keys must never be built dynamically (e.g. `t(someVariable)`) or\n * extraction silently misses them. Adding an interaction = one line here + one\n * line in {@link InteractionAnnouncementParams} (+ an override in\n * {@link INTERACTION_PRIORITIES} only if it is not `polite`).\n */\nconst INTERACTION_MESSAGES: {\n  [T in InteractionAnnouncementType]: (\n    t: TranslateFn,\n    params: InteractionAnnouncementParams[T],\n  ) => string;\n} = {\n  // Confirms the new audio playback speed after the user cycles it with the playback-rate button.\n  // Reuses the existing (already-localized) button label so the spoken text matches the control.\n  'audioPlayer.playbackRateChanged': (t, params) =>\n    t('Playback speed {{ rate }}x', { rate: params.rate }),\n  // Confirms which channel was opened after selecting it from the list. Delayed (see\n  // INTERACTION_DELAY_MS) so it lands AFTER the screen reader's announcement of the newly-focused\n  // element (the message composer auto-focuses on channel change) rather than competing with — and\n  // being superseded by — that native focus read-out. A provider-managed delay (not a per-row\n  // debounce) so it still fires when selecting the channel unmounts the list (mobile).\n  'channel.opened': (t, params) =>\n    t('aria/Opened channel: {{ name }}', { name: params.name }),\n  // Confirms which slash command was activated after picking it from the Instant Commands menu.\n  // Delayed (INTERACTION_DELAY_MS) for the same reason as the \"opened\" confirmations: selecting a\n  // command closes the menu and focuses the composer textarea (whose name changes, e.g. to\n  // \"Search GIFs\"), so the screen reader reads that focus first — this lands after it. A provider\n  // delay (not a debounce) because the menu that fired it unmounts on selection.\n  'command.selected': (t, params) =>\n    t('aria/Command activated: {{ command }}', { command: params.command }),\n  'giphy.canceled': (t) => t('aria/Giphy canceled'),\n  'giphy.sent': (t) => t('aria/Giphy sent'),\n  // Giphy payloads rarely carry a human title, so include it only when present; otherwise a\n  // generic \"changed\" confirmation. Both literal keys are extracted by i18next-cli.\n  'giphy.shuffled': (t, params) =>\n    params.title\n      ? t('aria/Giphy image changed: {{ title }}', { title: params.title })\n      : t('aria/Giphy image changed'),\n  // Spoken on poll-dialog open. Reuses the already-localized visible description for the middle\n  // clause (so the spoken and visible text stay consistent) and adds two short aria-only phrases:\n  // an explicit \"opened\" confirmation and the Enter affordance to step into the Question field.\n  'poll.dialogOpened': (t) =>\n    `${t('aria/Poll dialog opened')}. ${t(\n      'Create a question, add options, and configure poll settings',\n    )}. ${t('aria/Press Enter to start typing')}.`,\n  // Keyboard reorder pickup/drop. Assertive (see INTERACTION_PRIORITIES) — immediate drag feedback\n  // that must not be queued behind other polite messages.\n  'poll.optionDropped': (t, params) =>\n    t('aria/Dropped \"{{ option }}\" at position {{ position }}.', {\n      option: params.option,\n      position: params.position,\n    }),\n  'poll.optionPickedUp': (t, params) =>\n    t(\n      'aria/Picked up \"{{ option }}\". Use arrow keys to reorder. Press Space or Tab to drop.',\n      { option: params.option },\n    ),\n  // Confirms a poll option was removed, naming it by its text (or positional fallback). Polite so it\n  // queues behind the focus move to the next option field instead of interrupting it.\n  'poll.optionRemoved': (t, params) =>\n    t('aria/Removed option {{ option }}', { option: params.option }),\n  'poll.sent': (t) => t('aria/Poll sent'),\n  'search.cleared': (t) => t('aria/Search cleared'),\n  // The number of items currently listed in the search results; an empty result set is spelled out\n  // rather than announced as \"0\". When the list is fully loaded, the end-of-list status is folded\n  // into THIS one announcement (reusing the visible footer's \"All results loaded\" text) instead of a\n  // competing second live-region message that would supersede the count.\n  'search.resultCount': (t, params) => {\n    if (params.count <= 0) return t('aria/No search results found');\n    const count = t('aria/{{ count }} search results', { count: params.count });\n    return params.allResultsLoaded ? `${count}. ${t('All results loaded')}` : count;\n  },\n  // Name the suggestion type by reusing the already-localized list label (\"5 Command\n  // Suggestions\") so the user knows what the results are; fall back to the bare count when no\n  // label is given. Both literal keys are extracted.\n  'suggestions.count': (t, params) =>\n    params.suggestionsLabel\n      ? t('aria/{{ count }} {{ suggestionsLabel }}', {\n          count: params.count,\n          suggestionsLabel: params.suggestionsLabel,\n        })\n      : t('aria/{{ count }} suggestions', { count: params.count }),\n  // Confirms which thread was opened after selecting it from the list; `name` is the thread's\n  // channel display title. Delayed for the same reason as `channel.opened` (the thread composer\n  // auto-focuses on open, and its focus announcement would otherwise supersede this one).\n  'thread.opened': (t, params) =>\n    t('aria/Opened thread in {{ name }}', { name: params.name }),\n  'user.selected': (t, params) =>\n    t('aria/User selected: {{ user }}', { user: params.user }),\n  // Voice recorder lifecycle — discrete, immediate, polite confirmations. Cancellation is NOT here:\n  // it already emits an app notification (\"Voice message deleted\") announced by NotificationAnnouncer,\n  // and recording errors surface as error notifications; adding them here would double-announce.\n  'voiceRecording.attached': (t) => t('aria/Voice recording attached'),\n  'voiceRecording.paused': (t) => t('aria/Recording paused'),\n  'voiceRecording.resumed': (t) => t('aria/Recording resumed'),\n  'voiceRecording.sent': (t) => t('aria/Voice message sent'),\n  'voiceRecording.started': (t) => t('aria/Recording started'),\n};\n\n/**\n * Per-interaction aria-live priority. Interactions default to `polite`; list one\n * here only to override it (e.g. with `assertive`).\n */\nconst INTERACTION_PRIORITIES: Partial<\n  Record<InteractionAnnouncementType, AriaLivePriority>\n> = {\n  // Assertive on open: a polite update fired around the dialog's focus-entry announcement is\n  // dropped; assertive interrupts and is spoken (VoiceOver demotes the aria-describedby hint).\n  'poll.dialogOpened': 'assertive',\n  // Keyboard reorder feedback must be immediate (interrupt), not queued behind polite messages.\n  'poll.optionDropped': 'assertive',\n  'poll.optionPickedUp': 'assertive',\n};\n\n/**\n * Per-interaction dedupe window (ms): an identical message for this interaction is announced at\n * most once per window (see {@link AriaLiveAnnounceOptions.dedupeMs}). List an interaction here\n * only when the SAME open/mount can fire it more than once in quick succession — e.g. a mount\n * effect double-invoked by React StrictMode (dev) — so the user does not hear a duplicate.\n */\nconst INTERACTION_DEDUPE_MS: Partial<Record<InteractionAnnouncementType, number>> = {\n  // The audio player is pooled: if the same asset is rendered by two widgets they share one player,\n  // so a single rate change fires this from both consumers. Dedupe collapses the identical message.\n  // (Cycling always lands on a different rate → different text, so this never swallows a real change.)\n  'audioPlayer.playbackRateChanged': 300,\n  'poll.dialogOpened': 1000,\n};\n\n/**\n * Default per-interaction debounce delay (ms). Only list rapidly-updating streams where just the\n * settled value should be read (e.g. the autocomplete count as the query filters). Discrete\n * confirmations (Giphy/Poll sent, user selected) are NOT listed and announce immediately. A call\n * site can override (or opt into) a delay for a single call via `params.debounceMs` — see\n * {@link InteractionDeliveryOptions}.\n *\n * `suggestions.count` is a CONSEQUENCE OF TYPING, so the delay does double duty: it coalesces\n * rapid filters into the settled value AND lets the screen reader's per-keystroke typing echo\n * (the spoken character + field re-read) finish first. A polite update that lands mid-echo gets\n * queued behind a long re-read and is perceived as buried; waiting past the echo makes the count\n * the next thing spoken once the user pauses. This is a heuristic — echo length varies with the\n * SR's \"speak typed words/characters\" setting and field content — so tune if it still collides.\n */\nconst INTERACTION_DEBOUNCE_MS: Partial<Record<InteractionAnnouncementType, number>> = {\n  // Coalesce the result count as the query filters / results stream in, and let the screen reader's\n  // typing echo finish first (same rationale as `suggestions.count`, slightly longer as search\n  // results can arrive over the network in bursts). The end-of-list status rides along in this same\n  // message (see `search.resultCount` resolver), so there is no second announcement to compete.\n  'search.resultCount': 1000,\n  'suggestions.count': 500,\n};\n\n/**\n * Default per-interaction delay (ms) for the immediate (non-debounced) path — a single deferred\n * emit scheduled in the announcer PROVIDER (see {@link AriaLiveAnnounceOptions.delayMs}), so it\n * SURVIVES the calling component unmounting (unlike a debounce, whose timer is cleared on unmount).\n *\n * Opening a channel/thread moves focus to the (auto-focusing) message composer; the screen reader\n * announces that newly-focused element first, and a live-region message emitted alongside it is\n * superseded and dropped. The delay defers the confirmation past that focus read-out so it is spoken\n * next, in a calm moment. It is a provider delay rather than a debounce specifically because\n * selecting the item can unmount its list row (and the whole list, on mobile) — a per-row debounce\n * would be cancelled mid-flight, swallowing the confirmation.\n */\nconst INTERACTION_DELAY_MS: Partial<Record<InteractionAnnouncementType, number>> = {\n  'channel.opened': 1500,\n  'command.selected': 1500,\n  'thread.opened': 1500,\n};\n\n// Overloads enforce that parameterized interactions require their params and that\n// param-less interactions reject extra arguments.\ntype AnnounceInteraction = {\n  <T extends InteractionAnnouncementType>(\n    interaction: InteractionAnnouncementParams[T] extends undefined ? T : never,\n  ): void;\n  <T extends InteractionAnnouncementType>(\n    interaction: InteractionAnnouncementParams[T] extends undefined ? never : T,\n    params: InteractionAnnouncementParams[T],\n  ): void;\n};\n\nexport type UseInteractionAnnouncementsValue = {\n  /**\n   * Announce a predefined interaction event to assistive technology. The\n   * interaction name maps to a localized message and a baked-in aria-live\n   * priority.\n   */\n  announceInteraction: AnnounceInteraction;\n  /**\n   * Cancel pending (debounced, not-yet-spoken) announcements: a single `interaction`, or all when\n   * omitted. Call this when the source of a debounced announcement is torn down (e.g. search exited)\n   * so a queued message is not spoken after its context is gone. An announcement already emitted into\n   * the live region cannot be recalled.\n   */\n  cancelInteraction: (interaction?: InteractionAnnouncementType) => void;\n};\n\n/**\n * Thin, typed wrapper over the aria-live announcer exposing intention-revealing\n * helpers for transient, user-initiated UI interactions (e.g. a Giphy being\n * sent, a poll being created, a mention being picked). They map to i18n keys with\n * baked-in priorities and reuse the existing live region via\n * {@link useAriaLiveAnnouncer}. New interactions are registered as a single entry\n * in {@link INTERACTION_MESSAGES}.\n */\nexport const useInteractionAnnouncements = (): UseInteractionAnnouncementsValue => {\n  const announce = useAriaLiveAnnouncer();\n  const { t } = useTranslationContext();\n  // Per-interaction debounce: each type has its own timer + delay from INTERACTION_DEBOUNCE_MS,\n  // so e.g. the typing-driven `suggestions.count` can wait longer (to clear the screen reader's\n  // typing echo) without affecting any other debounced interaction.\n  const { announce: announceDebounced, cancel: cancelDebounced } =\n    useDebouncedAnnounce(announce);\n  // Cancel fn of the still-pending provider-delayed emit per interaction. A second trigger of the\n  // same interaction within its delay window supersedes the first (so only the latest is spoken).\n  // NOT cleared on unmount on purpose — provider-delayed emits are designed to survive the caller\n  // unmounting (e.g. channel.opened fires after its list row is gone).\n  const pendingImmediateCancelsRef = useRef<\n    Partial<Record<InteractionAnnouncementType, () => void>>\n  >({});\n\n  return useMemo(\n    () => ({\n      announceInteraction: (\n        interaction: InteractionAnnouncementType,\n        params?: InteractionAnnouncementParams[InteractionAnnouncementType],\n      ) => {\n        const resolveMessage = INTERACTION_MESSAGES[interaction] as (\n          t: TranslateFn,\n          params: InteractionAnnouncementParams[InteractionAnnouncementType],\n        ) => string;\n\n        if (!resolveMessage) return;\n\n        const message = resolveMessage(t, params as never);\n        const priority = INTERACTION_PRIORITIES[interaction] ?? 'polite';\n\n        // A per-call `params.debounceMs` overrides the registered default (and can opt an\n        // otherwise-immediate interaction into debouncing).\n        const debounceMs =\n          (params as InteractionDeliveryOptions | undefined)?.debounceMs ??\n          INTERACTION_DEBOUNCE_MS[interaction];\n        if (debounceMs === undefined) {\n          // Immediate path. `delayMs` (if any) is a provider-managed deferral that survives this\n          // call site unmounting — used by the \"opened\" confirmations, whose list row disappears on\n          // selection. `debounceMs` takes precedence over `delayMs` when both are set.\n          const delayMs =\n            (params as InteractionDeliveryOptions | undefined)?.delayMs ??\n            INTERACTION_DELAY_MS[interaction];\n          // Supersede a still-pending delayed emit of the same interaction so a rapid re-trigger\n          // (e.g. selecting a second channel within the 1500ms window) speaks only the latest.\n          pendingImmediateCancelsRef.current[interaction]?.();\n          pendingImmediateCancelsRef.current[interaction] = announce(message, {\n            dedupeMs: INTERACTION_DEDUPE_MS[interaction],\n            delayMs,\n            priority,\n          });\n          return;\n        }\n\n        // Debounced stream (e.g. suggestions.count): coalesce rapid updates into the settled\n        // value, on a channel keyed by interaction type with that type's own delay. We do NOT\n        // dedupe an unchanged message here — whether a repeat is meaningful is the caller's call\n        // (e.g. SuggestionList re-announces the count on each genuine re-filter so the user gets\n        // feedback even when the count is steady, such as emoji results capped at a constant N).\n        // The debounce window already collapses idle/rapid duplicates.\n        announceDebounced(interaction, message, debounceMs, priority);\n      },\n      cancelInteraction: (interaction?: InteractionAnnouncementType) => {\n        cancelDebounced(interaction);\n        const pending = pendingImmediateCancelsRef.current;\n        if (interaction) {\n          pending[interaction]?.();\n          delete pending[interaction];\n        } else {\n          Object.values(pending).forEach((cancel) => cancel?.());\n          pendingImmediateCancelsRef.current = {};\n        }\n      },\n    }),\n    [announce, announceDebounced, cancelDebounced, t],\n  );\n};\n"],"mappings":";;;;;;;;;;;;;;AAsFA,IAAM,uBAKF;CAGF,oCAAoC,GAAG,WACrC,EAAE,8BAA8B,EAAE,MAAM,OAAO,KAAK,CAAC;CAMvD,mBAAmB,GAAG,WACpB,EAAE,mCAAmC,EAAE,MAAM,OAAO,KAAK,CAAC;CAM5D,qBAAqB,GAAG,WACtB,EAAE,yCAAyC,EAAE,SAAS,OAAO,QAAQ,CAAC;CACxE,mBAAmB,MAAM,EAAE,qBAAqB;CAChD,eAAe,MAAM,EAAE,iBAAiB;CAGxC,mBAAmB,GAAG,WACpB,OAAO,QACH,EAAE,yCAAyC,EAAE,OAAO,OAAO,MAAM,CAAC,IAClE,EAAE,0BAA0B;CAIlC,sBAAsB,MACpB,GAAG,EAAE,yBAAyB,EAAE,IAAI,EAClC,6DACF,EAAE,IAAI,EAAE,kCAAkC,EAAE;CAG9C,uBAAuB,GAAG,WACxB,EAAE,6DAA2D;EAC3D,QAAQ,OAAO;EACf,UAAU,OAAO;CACnB,CAAC;CACH,wBAAwB,GAAG,WACzB,EACE,2FACA,EAAE,QAAQ,OAAO,OAAO,CAC1B;CAGF,uBAAuB,GAAG,WACxB,EAAE,oCAAoC,EAAE,QAAQ,OAAO,OAAO,CAAC;CACjE,cAAc,MAAM,EAAE,gBAAgB;CACtC,mBAAmB,MAAM,EAAE,qBAAqB;CAKhD,uBAAuB,GAAG,WAAW;EACnC,IAAI,OAAO,SAAS,GAAG,OAAO,EAAE,8BAA8B;EAC9D,MAAM,QAAQ,EAAE,mCAAmC,EAAE,OAAO,OAAO,MAAM,CAAC;EAC1E,OAAO,OAAO,mBAAmB,GAAG,MAAM,IAAI,EAAE,oBAAoB,MAAM;CAC5E;CAIA,sBAAsB,GAAG,WACvB,OAAO,mBACH,EAAE,2CAA2C;EAC3C,OAAO,OAAO;EACd,kBAAkB,OAAO;CAC3B,CAAC,IACD,EAAE,gCAAgC,EAAE,OAAO,OAAO,MAAM,CAAC;CAI/D,kBAAkB,GAAG,WACnB,EAAE,oCAAoC,EAAE,MAAM,OAAO,KAAK,CAAC;CAC7D,kBAAkB,GAAG,WACnB,EAAE,kCAAkC,EAAE,MAAM,OAAO,KAAK,CAAC;CAI3D,4BAA4B,MAAM,EAAE,+BAA+B;CACnE,0BAA0B,MAAM,EAAE,uBAAuB;CACzD,2BAA2B,MAAM,EAAE,wBAAwB;CAC3D,wBAAwB,MAAM,EAAE,yBAAyB;CACzD,2BAA2B,MAAM,EAAE,wBAAwB;AAC7D;;;;;AAMA,IAAM,yBAEF;CAGF,qBAAqB;CAErB,sBAAsB;CACtB,uBAAuB;AACzB;;;;;;;AAQA,IAAM,wBAA8E;CAIlF,mCAAmC;CACnC,qBAAqB;AACvB;;;;;;;;;;;;;;;AAgBA,IAAM,0BAAgF;CAKpF,sBAAsB;CACtB,qBAAqB;AACvB;;;;;;;;;;;;;AAcA,IAAM,uBAA6E;CACjF,kBAAkB;CAClB,oBAAoB;CACpB,iBAAiB;AACnB;;;;;;;;;AAsCA,IAAa,oCAAsE;CACjF,MAAM,WAAW,qBAAqB;CACtC,MAAM,EAAE,MAAM,sBAAsB;CAIpC,MAAM,EAAE,UAAU,mBAAmB,QAAQ,oBAC3C,qBAAqB,QAAQ;CAK/B,MAAM,6BAA6B,OAEjC,CAAC,CAAC;CAEJ,OAAO,eACE;EACL,sBACE,aACA,WACG;GACH,MAAM,iBAAiB,qBAAqB;GAK5C,IAAI,CAAC,gBAAgB;GAErB,MAAM,UAAU,eAAe,GAAG,MAAe;GACjD,MAAM,WAAW,uBAAuB,gBAAgB;GAIxD,MAAM,aACH,QAAmD,cACpD,wBAAwB;GAC1B,IAAI,eAAe,KAAA,GAAW;IAI5B,MAAM,UACH,QAAmD,WACpD,qBAAqB;IAGvB,2BAA2B,QAAQ,YAAY,GAAG;IAClD,2BAA2B,QAAQ,eAAe,SAAS,SAAS;KAClE,UAAU,sBAAsB;KAChC;KACA;IACF,CAAC;IACD;GACF;GAQA,kBAAkB,aAAa,SAAS,YAAY,QAAQ;EAC9D;EACA,oBAAoB,gBAA8C;GAChE,gBAAgB,WAAW;GAC3B,MAAM,UAAU,2BAA2B;GAC3C,IAAI,aAAa;IACf,QAAQ,YAAY,GAAG;IACvB,OAAO,QAAQ;GACjB,OAAO;IACL,OAAO,OAAO,OAAO,CAAC,CAAC,SAAS,WAAW,SAAS,CAAC;IACrD,2BAA2B,UAAU,CAAC;GACxC;EACF;CACF,IACA;EAAC;EAAU;EAAmB;EAAiB;CAAC,CAClD;AACF"}

package/dist/es/components/Accessibility/scheduling/useAnnouncementQueue.mjs

@@ -0,0 +1,43 @@
+import { useCallback, useEffect, useRef } from "react";
+//#region src/components/Accessibility/scheduling/useAnnouncementQueue.ts
+var DEFAULT_GAP_MS = 150;
+/**
+* L2 scheduling policy: announce queued messages one at a time, spaced by `gapMs`, through the
+* provided `announce` (from `useAriaLiveAnnouncer`). Replaces per-consumer queue/timer
+* bookkeeping (e.g. the old `NotificationAnnouncer` state machine). The unified announcer already
+* appends a fresh node per call, so no "clear region first" trick is needed — the gap simply
+* prevents successive messages from clobbering each other in the screen-reader buffer.
+*
+* React 17/18/19 compatible — `useCallback`/`useRef`/`useEffect` only. Pending timers and the
+* queue are cleared on unmount.
+*/
+var useAnnouncementQueue = (announce, { gapMs = DEFAULT_GAP_MS } = {}) => {
+	const queueRef = useRef([]);
+	const timerRef = useRef(null);
+	const announceRef = useRef(announce);
+	announceRef.current = announce;
+	const drain = useCallback(() => {
+		if (timerRef.current) return;
+		const next = queueRef.current.shift();
+		if (!next) return;
+		announceRef.current(next.message, { priority: next.priority });
+		timerRef.current = setTimeout(() => {
+			timerRef.current = null;
+			drain();
+		}, gapMs);
+	}, [gapMs]);
+	const enqueue = useCallback((announcement) => {
+		queueRef.current.push(announcement);
+		drain();
+	}, [drain]);
+	useEffect(() => () => {
+		if (timerRef.current) clearTimeout(timerRef.current);
+		timerRef.current = null;
+		queueRef.current = [];
+	}, []);
+	return { enqueue };
+};
+//#endregion
+export { useAnnouncementQueue };
+
+//# sourceMappingURL=useAnnouncementQueue.mjs.map

package/dist/es/components/Accessibility/scheduling/useAnnouncementQueue.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAnnouncementQueue.mjs","names":[],"sources":["../../../../../src/components/Accessibility/scheduling/useAnnouncementQueue.ts"],"sourcesContent":["import { useCallback, useEffect, useRef } from 'react';\n\nimport type { AriaLiveAnnounce, AriaLivePriority } from '../useAriaLiveAnnouncer';\n\nexport type QueuedAnnouncement = {\n  message: string;\n  priority?: AriaLivePriority;\n};\n\nexport type UseAnnouncementQueueOptions = {\n  /** Minimum delay between successive announcements, in ms. Defaults to 150. */\n  gapMs?: number;\n};\n\nexport type UseAnnouncementQueueResult = {\n  /** Enqueue an announcement. The first drains immediately; the rest are paced by `gapMs`. */\n  enqueue: (announcement: QueuedAnnouncement) => void;\n};\n\nconst DEFAULT_GAP_MS = 150;\n\n/**\n * L2 scheduling policy: announce queued messages one at a time, spaced by `gapMs`, through the\n * provided `announce` (from `useAriaLiveAnnouncer`). Replaces per-consumer queue/timer\n * bookkeeping (e.g. the old `NotificationAnnouncer` state machine). The unified announcer already\n * appends a fresh node per call, so no \"clear region first\" trick is needed — the gap simply\n * prevents successive messages from clobbering each other in the screen-reader buffer.\n *\n * React 17/18/19 compatible — `useCallback`/`useRef`/`useEffect` only. Pending timers and the\n * queue are cleared on unmount.\n */\nexport const useAnnouncementQueue = (\n  announce: AriaLiveAnnounce,\n  { gapMs = DEFAULT_GAP_MS }: UseAnnouncementQueueOptions = {},\n): UseAnnouncementQueueResult => {\n  const queueRef = useRef<QueuedAnnouncement[]>([]);\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n  // Keep the latest `announce` without forcing `enqueue`/`drain` identity to change.\n  const announceRef = useRef(announce);\n  announceRef.current = announce;\n\n  const drain = useCallback(() => {\n    if (timerRef.current) return; // already pacing — the running timer will drain the next item\n\n    const next = queueRef.current.shift();\n    if (!next) return;\n\n    announceRef.current(next.message, { priority: next.priority });\n\n    timerRef.current = setTimeout(() => {\n      timerRef.current = null;\n      drain();\n    }, gapMs);\n  }, [gapMs]);\n\n  const enqueue = useCallback(\n    (announcement: QueuedAnnouncement) => {\n      queueRef.current.push(announcement);\n      drain();\n    },\n    [drain],\n  );\n\n  useEffect(\n    () => () => {\n      if (timerRef.current) clearTimeout(timerRef.current);\n      timerRef.current = null;\n      queueRef.current = [];\n    },\n    [],\n  );\n\n  return { enqueue };\n};\n"],"mappings":";;AAmBA,IAAM,iBAAiB;;;;;;;;;;;AAYvB,IAAa,wBACX,UACA,EAAE,QAAQ,mBAAgD,CAAC,MAC5B;CAC/B,MAAM,WAAW,OAA6B,CAAC,CAAC;CAChD,MAAM,WAAW,OAA6C,IAAI;CAGlE,MAAM,cAAc,OAAO,QAAQ;CACnC,YAAY,UAAU;CAEtB,MAAM,QAAQ,kBAAkB;EAC9B,IAAI,SAAS,SAAS;EAEtB,MAAM,OAAO,SAAS,QAAQ,MAAM;EACpC,IAAI,CAAC,MAAM;EAEX,YAAY,QAAQ,KAAK,SAAS,EAAE,UAAU,KAAK,SAAS,CAAC;EAE7D,SAAS,UAAU,iBAAiB;GAClC,SAAS,UAAU;GACnB,MAAM;EACR,GAAG,KAAK;CACV,GAAG,CAAC,KAAK,CAAC;CAEV,MAAM,UAAU,aACb,iBAAqC;EACpC,SAAS,QAAQ,KAAK,YAAY;EAClC,MAAM;CACR,GACA,CAAC,KAAK,CACR;CAEA,sBACc;EACV,IAAI,SAAS,SAAS,aAAa,SAAS,OAAO;EACnD,SAAS,UAAU;EACnB,SAAS,UAAU,CAAC;CACtB,GACA,CAAC,CACH;CAEA,OAAO,EAAE,QAAQ;AACnB"}

package/dist/es/components/Accessibility/scheduling/useDebouncedAnnounce.mjs

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useRef } from "react";
+//#region src/components/Accessibility/scheduling/useDebouncedAnnounce.ts
+/**
+* L2 scheduling policy: a per-key debounce over the provided `announce` (from
+* `useAriaLiveAnnouncer`). Keeps an independent timer per `key` and takes the delay per call, so
+* distinct rapidly-updating streams can coexist with different debounce windows without clobbering
+* one another (e.g. the autocomplete count, which is a consequence of typing and wants a longer
+* window to clear the screen reader's typing echo, vs. some other future debounced stream). For a
+* single stream, use a constant key.
+*
+* React 17/18/19 compatible — `useCallback`/`useRef`/`useEffect` only. All pending timers are
+* cleared on unmount.
+*
+* ## When to use this vs. {@link useSettledAnnouncement}
+*
+* Both wait out screen-reader noise (the typing echo / field re-read) before speaking, but they
+* model different problems:
+*
+* - **`useDebouncedAnnounce` — an imperative throttle for a value you announce REPEATEDLY.** You
+*   call `announce(key, message, ...)` yourself whenever you have a fresh value (from an event
+*   handler or effect); rapid calls on a key collapse to the last one. The message typically
+*   *changes* each time, it can fire *again and again* (once per pause), and you drive it. Canonical
+*   case: the autocomplete result count re-announced as the user keeps typing. It has no notion of
+*   "active", "once", or re-arming — it just throttles whatever you push through it.
+*
+* - **{@link useSettledAnnouncement} — a declarative ONE-SHOT cue for a state change.** You pass
+*   `{ active, message, settleKey }`; it announces *once* when `active`, deferred until `settleKey`
+*   stops changing, then stays silent until `active` flips back and forth. The message is fixed and
+*   the point is "say this single fact once the UI settles", not "announce the latest value".
+*
+* | | `useDebouncedAnnounce` | `useSettledAnnouncement` |
+* | --- | --- | --- |
+* | Style | Imperative — you call `announce(key, …)` | Declarative — reacts to `{ active, message, settleKey }` |
+* | Repetition | Fires repeatedly, once per pause | Once per `active` epoch (re-arms on reset) |
+* | Message | Typically changes each time | Fixed fact |
+* | Timer reset | Each explicit call | Each `settleKey` change |
+* | Streams | Many, independent per `key` | One logical cue |
+* | Canonical case | Autocomplete count while typing | "Controls just became available" |
+*
+* Rule of thumb: announcing the **latest value of a changing thing** → this hook. Announcing a
+* **fixed fact once, after things settle** → `useSettledAnnouncement`.
+*/
+var useDebouncedAnnounce = (announce) => {
+	const timersRef = useRef(/* @__PURE__ */ new Map());
+	const announceRef = useRef(announce);
+	announceRef.current = announce;
+	const cancel = useCallback((key) => {
+		const timers = timersRef.current;
+		if (key === void 0) {
+			timers.forEach((timerId) => clearTimeout(timerId));
+			timers.clear();
+			return;
+		}
+		const timerId = timers.get(key);
+		if (timerId !== void 0) {
+			clearTimeout(timerId);
+			timers.delete(key);
+		}
+	}, []);
+	useEffect(() => () => cancel(), [cancel]);
+	return {
+		announce: useCallback((key, message, delayMs, priority) => {
+			const timers = timersRef.current;
+			const existing = timers.get(key);
+			if (existing !== void 0) clearTimeout(existing);
+			const timerId = setTimeout(() => {
+				timers.delete(key);
+				announceRef.current(message, { priority });
+			}, delayMs);
+			timers.set(key, timerId);
+		}, []),
+		cancel
+	};
+};
+//#endregion
+export { useDebouncedAnnounce };
+
+//# sourceMappingURL=useDebouncedAnnounce.mjs.map

package/dist/es/components/Accessibility/scheduling/useDebouncedAnnounce.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedAnnounce.mjs","names":[],"sources":["../../../../../src/components/Accessibility/scheduling/useDebouncedAnnounce.ts"],"sourcesContent":["import { useCallback, useEffect, useRef } from 'react';\n\nimport type { AriaLiveAnnounce, AriaLivePriority } from '../useAriaLiveAnnouncer';\n\nexport type DebouncedAnnounceResult = {\n  /**\n   * Schedule an announcement on the channel identified by `key`. Each call on the same key\n   * resets that key's timer, so only the last call within its `delayMs` fires. Different keys\n   * debounce independently — scheduling key `a` never cancels a pending key `b`, and each may\n   * use its own `delayMs`.\n   */\n  announce: (\n    key: string,\n    message: string,\n    delayMs: number,\n    priority?: AriaLivePriority,\n  ) => void;\n  /** Cancel pending announcement(s): a single `key`, or all when omitted (also runs on unmount). */\n  cancel: (key?: string) => void;\n};\n\n/**\n * L2 scheduling policy: a per-key debounce over the provided `announce` (from\n * `useAriaLiveAnnouncer`). Keeps an independent timer per `key` and takes the delay per call, so\n * distinct rapidly-updating streams can coexist with different debounce windows without clobbering\n * one another (e.g. the autocomplete count, which is a consequence of typing and wants a longer\n * window to clear the screen reader's typing echo, vs. some other future debounced stream). For a\n * single stream, use a constant key.\n *\n * React 17/18/19 compatible — `useCallback`/`useRef`/`useEffect` only. All pending timers are\n * cleared on unmount.\n *\n * ## When to use this vs. {@link useSettledAnnouncement}\n *\n * Both wait out screen-reader noise (the typing echo / field re-read) before speaking, but they\n * model different problems:\n *\n * - **`useDebouncedAnnounce` — an imperative throttle for a value you announce REPEATEDLY.** You\n *   call `announce(key, message, ...)` yourself whenever you have a fresh value (from an event\n *   handler or effect); rapid calls on a key collapse to the last one. The message typically\n *   *changes* each time, it can fire *again and again* (once per pause), and you drive it. Canonical\n *   case: the autocomplete result count re-announced as the user keeps typing. It has no notion of\n *   \"active\", \"once\", or re-arming — it just throttles whatever you push through it.\n *\n * - **{@link useSettledAnnouncement} — a declarative ONE-SHOT cue for a state change.** You pass\n *   `{ active, message, settleKey }`; it announces *once* when `active`, deferred until `settleKey`\n *   stops changing, then stays silent until `active` flips back and forth. The message is fixed and\n *   the point is \"say this single fact once the UI settles\", not \"announce the latest value\".\n *\n * | | `useDebouncedAnnounce` | `useSettledAnnouncement` |\n * | --- | --- | --- |\n * | Style | Imperative — you call `announce(key, …)` | Declarative — reacts to `{ active, message, settleKey }` |\n * | Repetition | Fires repeatedly, once per pause | Once per `active` epoch (re-arms on reset) |\n * | Message | Typically changes each time | Fixed fact |\n * | Timer reset | Each explicit call | Each `settleKey` change |\n * | Streams | Many, independent per `key` | One logical cue |\n * | Canonical case | Autocomplete count while typing | \"Controls just became available\" |\n *\n * Rule of thumb: announcing the **latest value of a changing thing** → this hook. Announcing a\n * **fixed fact once, after things settle** → `useSettledAnnouncement`.\n */\nexport const useDebouncedAnnounce = (\n  announce: AriaLiveAnnounce,\n): DebouncedAnnounceResult => {\n  const timersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());\n\n  // Keep the latest `announce` without changing the debounced callback identity.\n  const announceRef = useRef(announce);\n  announceRef.current = announce;\n\n  const cancel = useCallback((key?: string) => {\n    const timers = timersRef.current;\n    if (key === undefined) {\n      timers.forEach((timerId) => clearTimeout(timerId));\n      timers.clear();\n      return;\n    }\n    const timerId = timers.get(key);\n    if (timerId !== undefined) {\n      clearTimeout(timerId);\n      timers.delete(key);\n    }\n  }, []);\n\n  useEffect(() => () => cancel(), [cancel]);\n\n  const debouncedAnnounce = useCallback(\n    (key: string, message: string, delayMs: number, priority?: AriaLivePriority) => {\n      const timers = timersRef.current;\n      const existing = timers.get(key);\n      if (existing !== undefined) clearTimeout(existing);\n      const timerId = setTimeout(() => {\n        timers.delete(key);\n        announceRef.current(message, { priority });\n      }, delayMs);\n      timers.set(key, timerId);\n    },\n    [],\n  );\n\n  return { announce: debouncedAnnounce, cancel };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,IAAa,wBACX,aAC4B;CAC5B,MAAM,YAAY,uBAAmD,IAAI,IAAI,CAAC;CAG9E,MAAM,cAAc,OAAO,QAAQ;CACnC,YAAY,UAAU;CAEtB,MAAM,SAAS,aAAa,QAAiB;EAC3C,MAAM,SAAS,UAAU;EACzB,IAAI,QAAQ,KAAA,GAAW;GACrB,OAAO,SAAS,YAAY,aAAa,OAAO,CAAC;GACjD,OAAO,MAAM;GACb;EACF;EACA,MAAM,UAAU,OAAO,IAAI,GAAG;EAC9B,IAAI,YAAY,KAAA,GAAW;GACzB,aAAa,OAAO;GACpB,OAAO,OAAO,GAAG;EACnB;CACF,GAAG,CAAC,CAAC;CAEL,sBAAsB,OAAO,GAAG,CAAC,MAAM,CAAC;CAgBxC,OAAO;EAAE,UAdiB,aACvB,KAAa,SAAiB,SAAiB,aAAgC;GAC9E,MAAM,SAAS,UAAU;GACzB,MAAM,WAAW,OAAO,IAAI,GAAG;GAC/B,IAAI,aAAa,KAAA,GAAW,aAAa,QAAQ;GACjD,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,GAAG;IACjB,YAAY,QAAQ,SAAS,EAAE,SAAS,CAAC;GAC3C,GAAG,OAAO;GACV,OAAO,IAAI,KAAK,OAAO;EACzB,GACA,CAAC,CAGgB;EAAmB;CAAO;AAC/C"}

package/dist/es/components/Accessibility/scheduling/useSettledAnnouncement.mjs

@@ -0,0 +1,90 @@
+import { useEffect, useRef } from "react";
+//#region src/components/Accessibility/scheduling/useSettledAnnouncement.ts
+/**
+* Announce a message via a live region, but only after the surrounding UI has gone idle.
+*
+* Use this when an immediate announcement would be **swallowed by the screen reader's own speech** —
+* its typing echo, or the field/group re-read it performs when nearby DOM mutates. Such a read-out
+* supersedes a competing live-region update *at any priority*, so the fix is not to fight it but to
+* wait it out: each change to `settleKey` restarts an idle timer, and the message is announced only
+* once the user has paused and the screen reader has fallen quiet — landing in a calm moment instead
+* of being cut off.
+*
+* Typical shape: `active` is the condition that makes the announcement relevant (e.g. some controls
+* just became available), and `settleKey` is the thing still changing (e.g. the list/text being
+* edited). The announcement fires once per `active` epoch and re-arms when `active` goes false.
+*
+* Composable L2 policy over `announce` (from `useAriaLiveAnnouncer`), like
+* {@link useDebouncedAnnounce}. React 17/18/19 compatible — `useEffect`/`useRef` only; the pending
+* timer is cleared on unmount.
+*
+* ## When to use this vs. {@link useDebouncedAnnounce}
+*
+* Both wait out screen-reader noise (the typing echo / field re-read) before speaking, but they
+* model different problems:
+*
+* - **`useSettledAnnouncement` — a declarative ONE-SHOT cue for a STATE CHANGE.** You pass
+*   `{ active, message, settleKey }` and it reacts: it announces *once* when `active`, deferred
+*   until `settleKey` stops changing, then stays silent until `active` flips false and true again.
+*   The message is fixed; the point is "say this single fact once the UI settles". Canonical case:
+*   "the reorder/remove controls just became available" once the option list stops mutating.
+*
+* - **{@link useDebouncedAnnounce} — an imperative throttle for a value you announce REPEATEDLY.**
+*   You call `announce(key, message, ...)` yourself whenever you have a fresh value; rapid calls on
+*   a key collapse to the last. The message typically *changes* and it fires *again and again* (once
+*   per pause). Canonical case: the autocomplete result count re-announced as the user keeps typing.
+*   It has no notion of `active`/`once`/re-arming.
+*
+* | | `useDebouncedAnnounce` | `useSettledAnnouncement` |
+* | --- | --- | --- |
+* | Style | Imperative — you call `announce(key, …)` | Declarative — reacts to `{ active, message, settleKey }` |
+* | Repetition | Fires repeatedly, once per pause | Once per `active` epoch (re-arms on reset) |
+* | Message | Typically changes each time | Fixed fact |
+* | Timer reset | Each explicit call | Each `settleKey` change |
+* | Streams | Many, independent per `key` | One logical cue |
+* | Canonical case | Autocomplete count while typing | "Controls just became available" |
+*
+* Rule of thumb: announcing a **fixed fact once, after things settle** → this hook. Announcing the
+* **latest value of a changing thing** (repeatedly) → `useDebouncedAnnounce`.
+*/
+var useSettledAnnouncement = (announce, { active, idleMs = 1500, message, once = true, priority = "polite", settleKey }) => {
+	const announcedRef = useRef(false);
+	const timeoutRef = useRef(null);
+	const announceRef = useRef(announce);
+	announceRef.current = announce;
+	const messageRef = useRef(message);
+	messageRef.current = message;
+	useEffect(() => {
+		const clearPending = () => {
+			if (timeoutRef.current) {
+				clearTimeout(timeoutRef.current);
+				timeoutRef.current = null;
+			}
+		};
+		if (!active) {
+			announcedRef.current = false;
+			clearPending();
+			return;
+		}
+		if (once && announcedRef.current) return;
+		clearPending();
+		timeoutRef.current = setTimeout(() => {
+			timeoutRef.current = null;
+			announcedRef.current = true;
+			announceRef.current(messageRef.current, { priority });
+		}, idleMs);
+	}, [
+		active,
+		idleMs,
+		once,
+		priority,
+		settleKey
+	]);
+	useEffect(() => () => {
+		if (timeoutRef.current) clearTimeout(timeoutRef.current);
+	}, []);
+};
+//#endregion
+export { useSettledAnnouncement };
+
+//# sourceMappingURL=useSettledAnnouncement.mjs.map

package/dist/es/components/Accessibility/scheduling/useSettledAnnouncement.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSettledAnnouncement.mjs","names":[],"sources":["../../../../../src/components/Accessibility/scheduling/useSettledAnnouncement.ts"],"sourcesContent":["import { useEffect, useRef } from 'react';\n\nimport type { AriaLiveAnnounce, AriaLivePriority } from '../useAriaLiveAnnouncer';\n\nexport type UseSettledAnnouncementParams = {\n  /**\n   * While `true`, the announcement is (re)scheduled; when it flips back to `false` the armed/spoken\n   * state resets, so the message can fire again the next time `active` becomes `true`.\n   */\n  active: boolean;\n  /** The message to announce. The latest value is used when the announcement fires. */\n  message: string;\n  /**\n   * A value whose identity changes whenever the surrounding UI is still \"in motion\" — e.g. the\n   * array/string being edited, or a counter you bump on each relevant change. Every change restarts\n   * the idle timer, so the announcement only fires once activity has stopped. Pass a value that is\n   * stable between changes (an immutably-updated array/string works; avoid a fresh object literal\n   * each render, which would reset the timer forever).\n   */\n  settleKey: unknown;\n  /** Idle window (ms) the `settleKey` must be unchanged before announcing. Default `1500`. */\n  idleMs?: number;\n  /** Announce at most once per `active` epoch. When `false`, re-announces each time it settles again\n   * while still active. Default `true`. */\n  once?: boolean;\n  /** Live-region priority. Default `'polite'`. */\n  priority?: AriaLivePriority;\n};\n\n/**\n * Announce a message via a live region, but only after the surrounding UI has gone idle.\n *\n * Use this when an immediate announcement would be **swallowed by the screen reader's own speech** —\n * its typing echo, or the field/group re-read it performs when nearby DOM mutates. Such a read-out\n * supersedes a competing live-region update *at any priority*, so the fix is not to fight it but to\n * wait it out: each change to `settleKey` restarts an idle timer, and the message is announced only\n * once the user has paused and the screen reader has fallen quiet — landing in a calm moment instead\n * of being cut off.\n *\n * Typical shape: `active` is the condition that makes the announcement relevant (e.g. some controls\n * just became available), and `settleKey` is the thing still changing (e.g. the list/text being\n * edited). The announcement fires once per `active` epoch and re-arms when `active` goes false.\n *\n * Composable L2 policy over `announce` (from `useAriaLiveAnnouncer`), like\n * {@link useDebouncedAnnounce}. React 17/18/19 compatible — `useEffect`/`useRef` only; the pending\n * timer is cleared on unmount.\n *\n * ## When to use this vs. {@link useDebouncedAnnounce}\n *\n * Both wait out screen-reader noise (the typing echo / field re-read) before speaking, but they\n * model different problems:\n *\n * - **`useSettledAnnouncement` — a declarative ONE-SHOT cue for a STATE CHANGE.** You pass\n *   `{ active, message, settleKey }` and it reacts: it announces *once* when `active`, deferred\n *   until `settleKey` stops changing, then stays silent until `active` flips false and true again.\n *   The message is fixed; the point is \"say this single fact once the UI settles\". Canonical case:\n *   \"the reorder/remove controls just became available\" once the option list stops mutating.\n *\n * - **{@link useDebouncedAnnounce} — an imperative throttle for a value you announce REPEATEDLY.**\n *   You call `announce(key, message, ...)` yourself whenever you have a fresh value; rapid calls on\n *   a key collapse to the last. The message typically *changes* and it fires *again and again* (once\n *   per pause). Canonical case: the autocomplete result count re-announced as the user keeps typing.\n *   It has no notion of `active`/`once`/re-arming.\n *\n * | | `useDebouncedAnnounce` | `useSettledAnnouncement` |\n * | --- | --- | --- |\n * | Style | Imperative — you call `announce(key, …)` | Declarative — reacts to `{ active, message, settleKey }` |\n * | Repetition | Fires repeatedly, once per pause | Once per `active` epoch (re-arms on reset) |\n * | Message | Typically changes each time | Fixed fact |\n * | Timer reset | Each explicit call | Each `settleKey` change |\n * | Streams | Many, independent per `key` | One logical cue |\n * | Canonical case | Autocomplete count while typing | \"Controls just became available\" |\n *\n * Rule of thumb: announcing a **fixed fact once, after things settle** → this hook. Announcing the\n * **latest value of a changing thing** (repeatedly) → `useDebouncedAnnounce`.\n */\nexport const useSettledAnnouncement = (\n  announce: AriaLiveAnnounce,\n  {\n    active,\n    idleMs = 1500,\n    message,\n    once = true,\n    priority = 'polite',\n    settleKey,\n  }: UseSettledAnnouncementParams,\n) => {\n  const announcedRef = useRef(false);\n  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n  // Keep the latest announce/message without making them reset the idle timer (only `settleKey`\n  // should do that).\n  const announceRef = useRef(announce);\n  announceRef.current = announce;\n  const messageRef = useRef(message);\n  messageRef.current = message;\n\n  useEffect(() => {\n    const clearPending = () => {\n      if (timeoutRef.current) {\n        clearTimeout(timeoutRef.current);\n        timeoutRef.current = null;\n      }\n    };\n\n    if (!active) {\n      announcedRef.current = false;\n      clearPending();\n      return;\n    }\n\n    if (once && announcedRef.current) return;\n\n    // Restart the idle timer on every `settleKey` change so the message lands only after activity\n    // stops (after the screen reader's typing echo / field re-read, not during it).\n    clearPending();\n    timeoutRef.current = setTimeout(() => {\n      timeoutRef.current = null;\n      announcedRef.current = true;\n      announceRef.current(messageRef.current, { priority });\n    }, idleMs);\n  }, [active, idleMs, once, priority, settleKey]);\n\n  useEffect(\n    () => () => {\n      if (timeoutRef.current) clearTimeout(timeoutRef.current);\n    },\n    [],\n  );\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4EA,IAAa,0BACX,UACA,EACE,QACA,SAAS,MACT,SACA,OAAO,MACP,WAAW,UACX,gBAEC;CACH,MAAM,eAAe,OAAO,KAAK;CACjC,MAAM,aAAa,OAA6C,IAAI;CAIpE,MAAM,cAAc,OAAO,QAAQ;CACnC,YAAY,UAAU;CACtB,MAAM,aAAa,OAAO,OAAO;CACjC,WAAW,UAAU;CAErB,gBAAgB;EACd,MAAM,qBAAqB;GACzB,IAAI,WAAW,SAAS;IACtB,aAAa,WAAW,OAAO;IAC/B,WAAW,UAAU;GACvB;EACF;EAEA,IAAI,CAAC,QAAQ;GACX,aAAa,UAAU;GACvB,aAAa;GACb;EACF;EAEA,IAAI,QAAQ,aAAa,SAAS;EAIlC,aAAa;EACb,WAAW,UAAU,iBAAiB;GACpC,WAAW,UAAU;GACrB,aAAa,UAAU;GACvB,YAAY,QAAQ,WAAW,SAAS,EAAE,SAAS,CAAC;EACtD,GAAG,MAAM;CACX,GAAG;EAAC;EAAQ;EAAQ;EAAM;EAAU;CAAS,CAAC;CAE9C,sBACc;EACV,IAAI,WAAW,SAAS,aAAa,WAAW,OAAO;CACzD,GACA,CAAC,CACH;AACF"}

package/dist/es/components/Accessibility/useAriaLiveAnnouncer.mjs

@@ -0,0 +1,16 @@
+import { createContext, useContext } from "react";
+//#region src/components/Accessibility/useAriaLiveAnnouncer.ts
+var noopAnnounce = () => () => void 0;
+var AriaLiveAnnouncerContext = createContext(void 0);
+var useAriaLiveAnnouncer = () => {
+	const contextValue = useContext(AriaLiveAnnouncerContext);
+	if (!contextValue) {
+		console.warn("The useAriaLiveAnnouncer hook was called outside of an AriaLiveAnnouncerProvider.");
+		return noopAnnounce;
+	}
+	return contextValue.announce;
+};
+//#endregion
+export { AriaLiveAnnouncerContext, useAriaLiveAnnouncer };
+
+//# sourceMappingURL=useAriaLiveAnnouncer.mjs.map

package/dist/es/components/Accessibility/useAriaLiveAnnouncer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAriaLiveAnnouncer.mjs","names":[],"sources":["../../../../src/components/Accessibility/useAriaLiveAnnouncer.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\n\nexport type AriaLivePriority = 'assertive' | 'polite';\n\nexport type AriaLiveAnnounceOptions = {\n  priority?: AriaLivePriority;\n  /**\n   * Delay (ms) before the message is placed in the live region. Use to let a competing\n   * screen-reader utterance settle first — e.g. a dialog-identity announcement made while a\n   * field is being auto-focused is otherwise superseded by the field's focus announcement.\n   * Omitted/0 announces immediately.\n   */\n  delayMs?: number;\n  /**\n   * When set, an identical `message` is announced at most once per this window (ms); a repeat\n   * within the window is suppressed (returns a no-op cancel). The window starts when the message\n   * is actually announced. Guards against duplicate announcements — e.g. an effect double-invoked\n   * by React StrictMode, or rapid re-renders firing the same message.\n   */\n  dedupeMs?: number;\n};\n\n/**\n * Announce `message` to assistive technology. Delivery is controlled by an options object\n * (`priority` defaults to `'polite'`). Returns a `cancel` function: for a delayed announcement it\n * prevents a still-pending message from being announced (call it from effect cleanup so a closing\n * surface does not announce after unmount); for an immediate announcement it is a no-op.\n */\nexport type AriaLiveAnnounce = (\n  message: string,\n  options?: AriaLiveAnnounceOptions,\n) => () => void;\n\nexport type AriaLiveAnnouncerContextValue = {\n  announce: AriaLiveAnnounce;\n};\n\nconst noopAnnounce: AriaLiveAnnounce = () => () => undefined;\n\nexport const AriaLiveAnnouncerContext = createContext<\n  AriaLiveAnnouncerContextValue | undefined\n>(undefined);\n\nexport const useAriaLiveAnnouncer = () => {\n  const contextValue = useContext(AriaLiveAnnouncerContext);\n\n  if (!contextValue) {\n    console.warn(\n      'The useAriaLiveAnnouncer hook was called outside of an AriaLiveAnnouncerProvider.',\n    );\n\n    return noopAnnounce;\n  }\n\n  return contextValue.announce;\n};\n"],"mappings":";;AAqCA,IAAM,2BAA6C,KAAA;AAEnD,IAAa,2BAA2B,cAEtC,KAAA,CAAS;AAEX,IAAa,6BAA6B;CACxC,MAAM,eAAe,WAAW,wBAAwB;CAExD,IAAI,CAAC,cAAc;EACjB,QAAQ,KACN,mFACF;EAEA,OAAO;CACT;CAEA,OAAO,aAAa;AACtB"}