@heartlandone/vega 2.94.0 → 2.96.0

package/dist/collection/helpers/a11y-tree/a11y-tree-applier.js

@@ -0,0 +1,189 @@
+import { resolveStrategy } from './strategy-resolver';
+import { tryGetDocument } from '../../utils/try-get-document';
+/**
+ * Applies an A11y Tree to a shadow root by:
+ *
+ *   1. Resolving the `A11yTreeStrategy` that best matches the current
+ *      browser engine / AT environment.
+ *   2. Compiling the semantic tree into a flat list of `AriaPatch`
+ *      instructions.
+ *   3. Clearing any previously managed ARIA attributes (`data-a11y-managed`).
+ *   4. Applying each patch to the `data-a11y-id` target node in the shadow.
+ *   5. Materialising one visually-hidden description `<span>` per patch that
+ *      references `aria-describedby` and whose node carries description text.
+ *   6. Stamping `data-a11y-strategy-applied` on the host for observability.
+ *
+ * This is the generic, component-agnostic projection step. Components
+ * interact with it indirectly through `A11yTreeSlimmer`.
+ *
+ * @param {A11yNode} root - The root `A11yNode` of the semantic tree.
+ * @param {HTMLElement} host - The component's host element. Must have a `shadowRoot`.
+ *   If `shadowRoot` is null (e.g. light-DOM component or early call before first
+ *   render), the function returns immediately without throwing.
+ * @example
+ * ```ts
+ * // Called once per render from A11yTreeSlimmer.projectA11yTree():
+ * applyA11yTree(buildSectionTitleA11yTree({ titleText, description }), this.host);
+ * ```
+ */
+export function applyA11yTree(root, host) {
+  const shadow = host.shadowRoot;
+  if (!shadow)
+    return;
+  const strategy = resolveStrategy(host);
+  const patches = strategy.compile(root);
+  clearPreviousPatches(shadow);
+  for (const patch of patches) {
+    applyPatch(shadow, patch);
+  }
+  // Materialise a visually-hidden description node when any patch
+  // references aria-describedby. This node is what the AT reads via
+  // the describedby relationship.
+  maybeRenderDescriptionNode(root, shadow, patches);
+  host.setAttribute('data-a11y-strategy-applied', strategy.name);
+}
+/**
+ * Remove all ARIA attributes that were set by a previous `applyA11yTree`
+ * call. The `data-a11y-managed` attribute on each node acts as a manifest
+ * of which attributes were set so we can clean up exactly those — and only
+ * those — without disturbing hand-authored ARIA.
+ *
+ * @param {ShadowRoot} shadow - The shadow root to clean previously managed ARIA from.
+ */
+function clearPreviousPatches(shadow) {
+  shadow.querySelectorAll('[data-a11y-managed]').forEach((el) => {
+    var _a;
+    /* istanbul ignore next -- the [data-a11y-managed] selector guarantees the attribute is present, so the `?? ''` fallback is unreachable defensive code */
+    const attrs = ((_a = el.getAttribute('data-a11y-managed')) !== null && _a !== void 0 ? _a : '').split(' ').filter(Boolean);
+    attrs.forEach((a) => el.removeAttribute(a));
+    el.removeAttribute('data-a11y-managed');
+  });
+}
+/**
+ * Apply a single `AriaPatch` to the matching `data-a11y-id` element.
+ * Records every attribute written in `data-a11y-managed` so
+ * `clearPreviousPatches` can undo it on the next render.
+ *
+ * When `patch.value === null` the attribute is removed instead of set.
+ *
+ * @param {ShadowRoot} shadow - The shadow root containing the target element.
+ * @param {AriaPatch} patch - The ARIA patch to apply.
+ */
+function applyPatch(shadow, patch) {
+  var _a;
+  const target = shadow.querySelector(`[data-a11y-id="${patch.targetId}"]`);
+  if (!target)
+    return;
+  if (patch.value === null) {
+    target.removeAttribute(patch.attribute);
+  }
+  else {
+    target.setAttribute(patch.attribute, patch.value);
+  }
+  // Track which attributes we wrote so we can clean them up later.
+  const prev = (_a = target.getAttribute('data-a11y-managed')) !== null && _a !== void 0 ? _a : '';
+  if (!prev.split(' ').includes(patch.attribute)) {
+    target.setAttribute('data-a11y-managed', (prev + ' ' + patch.attribute).trim());
+  }
+}
+/**
+ * Materialise a visually-hidden `<span>` description node for every strategy
+ * patch that references `aria-describedby`. Each `<span>` carries the
+ * description text so assistive technology can read it via the describedby
+ * relationship.
+ *
+ * Spans are created once and reused on subsequent renders; their text content
+ * is updated in place. Spans whose `aria-describedby` reference is dropped on
+ * a later render are pruned by `pruneStaleDescriptionNodes`.
+ *
+ * Visually-hidden styles follow the `.sr-only` pattern (not `display:none`
+ * which would suppress AT reading).
+ *
+ * @param {A11yNode} root - The root of the semantic tree (source of description text).
+ * @param {ShadowRoot} shadow - The shadow root to append/update description nodes in.
+ * @param {AriaPatch[]} patches - The compiled patch list to scan for `aria-describedby`.
+ */
+function maybeRenderDescriptionNode(root, shadow, patches) {
+  // Collect every aria-describedby patch that has a live string target id —
+  // one hidden span is required per described node.
+  const describedByPatches = patches.filter((p) => p.attribute === 'aria-describedby' && typeof p.value === 'string');
+  const keepIds = new Set(describedByPatches.map((p) => p.value));
+  // Remove any previously-materialised description spans that are no longer
+  // referenced by a live aria-describedby patch — e.g. the `description` prop
+  // was cleared, or the description moved to a different node. Without this,
+  // orphaned visually-hidden spans linger in the shadow DOM and are still
+  // announced by AT during linear (non-describedby) traversal.
+  pruneStaleDescriptionNodes(shadow, keepIds);
+  for (const patch of describedByPatches) {
+    const node = findById(root, patch.targetId);
+    /* istanbul ignore next -- describedby patches are only emitted for nodes that carry a description, so this guard is unreachable defensive code */
+    if (!(node === null || node === void 0 ? void 0 : node.description))
+      continue;
+    ensureDescriptionSpan(shadow, patch.value, node.description);
+  }
+}
+/**
+ * Create (or update in place) a visually-hidden `<span>` carrying description
+ * text for a single `aria-describedby` reference.
+ *
+ * @param {ShadowRoot} shadow - The shadow root to append/update the span in.
+ * @param {string} id - The span id, matching the `aria-describedby` value.
+ * @param {string} text - The description text to expose to AT.
+ */
+function ensureDescriptionSpan(shadow, id, text) {
+  let descEl = shadow.getElementById(id);
+  if (!descEl) {
+    const doc = tryGetDocument();
+    /* istanbul ignore next -- document is always present in the browser render path */
+    if (!doc)
+      return;
+    descEl = doc.createElement('span');
+    descEl.id = id;
+    // Stamp the span so pruneStaleDescriptionNodes can find and clean it up
+    // on a later render when it is no longer referenced.
+    descEl.setAttribute('data-a11y-desc', '');
+    descEl.style.position = 'absolute';
+    descEl.style.width = '1px';
+    descEl.style.height = '1px';
+    descEl.style.overflow = 'hidden';
+    // `clip` is kept for legacy engines; `clip-path` + `white-space: nowrap`
+    // cover modern engines and prevent a 1px phantom scrollbar.
+    descEl.style.clip = 'rect(0 0 0 0)';
+    descEl.style.clipPath = 'inset(50%)';
+    descEl.style.whiteSpace = 'nowrap';
+    shadow.appendChild(descEl);
+  }
+  descEl.textContent = text;
+}
+/**
+ * Remove visually-hidden description `<span>`s (stamped `data-a11y-desc`)
+ * that are no longer referenced by a live `aria-describedby` patch.
+ *
+ * @param {ShadowRoot} shadow - The shadow root to prune stale description nodes from.
+ * @param {Set<string>} keepIds - Ids of spans still referenced this render; all
+ *   other stamped spans are removed.
+ */
+function pruneStaleDescriptionNodes(shadow, keepIds) {
+  shadow.querySelectorAll('[data-a11y-desc]').forEach((el) => {
+    if (!keepIds.has(el.id))
+      el.remove();
+  });
+}
+/**
+ * Depth-first search for a node by `id`.
+ *
+ * @param {A11yNode} node - Node to search from.
+ * @param {string} id - The `id` to find.
+ * @returns {A11yNode | undefined} The matching node, or `undefined` when not found.
+ */
+function findById(node, id) {
+  var _a;
+  if (node.id === id)
+    return node;
+  for (const c of (_a = node.children) !== null && _a !== void 0 ? _a : []) {
+    const hit = findById(c, id);
+    if (hit)
+      return hit;
+  }
+  return undefined;
+}

package/dist/collection/helpers/a11y-tree/a11y-tree.types.js

@@ -0,0 +1,48 @@
+/**
+ * A11y Tree — generic type definitions.
+ *
+ * The A11y Tree is a browser-agnostic description of the *semantic* a11y
+ * structure of a component. Each node captures the intent (role, label,
+ * description, level, etc.) and a stable `id` that the strategy layer
+ * can use to project ARIA attributes onto the real DOM.
+ *
+ * ## Architecture overview
+ *
+ * ```
+ * Component (TSX)
+ *   ↓  builds semantic tree via DTO helpers (a11y-node-dto.ts)
+ * A11yNode tree (this file)
+ *   ↓  compiled by an A11yTreeStrategy
+ * AriaPatch[]
+ *   ↓  applied by a11y-tree-applier.ts
+ * Shadow DOM (ARIA attributes on data-a11y-id elements)
+ * ```
+ *
+ * The A11y Tree is NOT rendered itself. It is consumed by an
+ * `A11yTreeStrategy` that decides, per browser/AT, which ARIA attributes
+ * to attach to which DOM nodes.
+ *
+ * ## Browser-engine strategy contract
+ *
+ * Assistive technology (AT) cannot be detected from JavaScript (by design,
+ * for user privacy). The strategy resolver therefore branches on *browser
+ * engine* as a coarse proxy for the most likely AT pairing:
+ *
+ * | Engine    | Assumed AT         | Confidence          |
+ * |-----------|-------------------|---------------------|
+ * | WebKit    | VoiceOver (macOS/iOS) | medium on Apple, low elsewhere |
+ * | Gecko     | NVDA (Windows), Orca (Linux) | medium on Win, low elsewhere |
+ * | Chromium  | JAWS / NVDA / TalkBack     | high on non-Apple, medium on Apple |
+ *
+ * **Confidence semantics** (see `A11yStrategyConfidence`):
+ * - `high`   — direct signal (explicit override or confirmed UA).
+ * - `medium` — plausible proxy; AT pairing is an assumption that covers the
+ *              majority of users on that engine+platform combination.
+ * - `low`    — unknown UA or atypical engine/platform combo; dev-mode warning
+ *              fires once per (strategy, reason) tuple via `resolveStrategy`.
+ *
+ * Consumers who know the AT environment (e.g. automated tests, a storybook
+ * knob) can pin a strategy explicitly via `data-a11y-strategy` on the host
+ * element — this is always treated as `high` confidence.
+ */
+export {};

package/dist/collection/helpers/a11y-tree/strategies/baseline-strategy.js

@@ -0,0 +1,78 @@
+/**
+ * Baseline strategy: spec-compliant ARIA, works on evergreen Chromium,
+ * Firefox, and Safari with their default AT pairings (NVDA, Orca,
+ * VoiceOver-macOS). Used as the default when no engine-specific override
+ * matches.
+ *
+ * ## Mapping rules
+ *
+ * | Node role     | ARIA output                                        |
+ * |---------------|----------------------------------------------------|
+ * | heading       | `role="heading"` + `aria-level`                    |
+ * | group/region  | `role` + `aria-label` (if present) + `aria-describedby` (if description) |
+ * | img (decorative) | `aria-hidden="true"`                            |
+ * | img (labelled)   | `role="img"` + `aria-label`                    |
+ * | presentation/none | `role="presentation"`                         |
+ */
+export const baselineStrategy = {
+  name: 'baseline',
+  /**
+   * Compile the semantic tree into spec-compliant ARIA patches.
+   *
+   * @param {A11yNode} root - Root of the semantic A11y Tree to compile.
+   * @returns {AriaPatch[]} Flat list of ARIA attribute patches to apply.
+   */
+  compile(root) {
+    const patches = [];
+    walk(root, patches);
+    return patches;
+  },
+};
+/**
+ * Recursively translate a node and its children into ARIA patches.
+ *
+ * @param {A11yNode} node - Current node being translated.
+ * @param {AriaPatch[]} patches - Accumulator the produced patches are pushed onto.
+ */
+function walk(node, patches) {
+  var _a, _b;
+  switch (node.role) {
+    case 'heading':
+      patches.push({ targetId: node.id, attribute: 'role', value: 'heading' });
+      patches.push({
+        targetId: node.id,
+        attribute: 'aria-level',
+        value: String((_a = node.level) !== null && _a !== void 0 ? _a : 2),
+      });
+      break;
+    case 'group':
+    case 'region':
+      patches.push({ targetId: node.id, attribute: 'role', value: node.role });
+      if (node.label) {
+        patches.push({ targetId: node.id, attribute: 'aria-label', value: node.label });
+      }
+      if (node.description) {
+        // Baseline AT: describedby works reliably on group/region.
+        patches.push({
+          targetId: node.id,
+          attribute: 'aria-describedby',
+          value: `${node.id}__desc`,
+        });
+      }
+      break;
+    case 'img':
+      if (node.decorative) {
+        patches.push({ targetId: node.id, attribute: 'aria-hidden', value: 'true' });
+      }
+      else if (node.label) {
+        patches.push({ targetId: node.id, attribute: 'role', value: 'img' });
+        patches.push({ targetId: node.id, attribute: 'aria-label', value: node.label });
+      }
+      break;
+    case 'presentation':
+    case 'none':
+      patches.push({ targetId: node.id, attribute: 'role', value: 'presentation' });
+      break;
+  }
+  (_b = node.children) === null || _b === void 0 ? void 0 : _b.forEach((c) => walk(c, patches));
+}

package/dist/collection/helpers/a11y-tree/strategies/firefox-nvda-strategy.js

@@ -0,0 +1,56 @@
+import { baselineStrategy } from './baseline-strategy';
+/**
+ * Firefox + NVDA strategy.
+ *
+ * Firefox/NVDA generally handles spec-compliant ARIA correctly. The one
+ * known quirk for the Vega component family:
+ *
+ * **NVDA browse-mode may skip `aria-describedby` on `role="group"`.**
+ * When a group container carries a description, NVDA in browse (reading)
+ * mode sometimes does not announce it. Workaround: promote the container to
+ * `role="region"`, which is part of the landmark navigation set and is
+ * reliably announced by NVDA when encountered during linear reading.
+ *
+ * All other node types fall back to baseline behaviour.
+ */
+export const firefoxNvdaStrategy = {
+  name: 'firefox-nvda',
+  /**
+   * Compile ARIA patches, applying the NVDA group-description workaround.
+   *
+   * @param {A11yNode} root - Root of the semantic A11y Tree to compile.
+   * @returns {AriaPatch[]} ARIA patches with group promoted to region when needed.
+   */
+  compile(root) {
+    const patches = baselineStrategy.compile(root);
+    // Promote all described groups to region (not just the first one).
+    for (const group of collectDescribedGroups(root)) {
+      for (const p of patches) {
+        if (p.targetId === group.id && p.attribute === 'role' && p.value === 'group') {
+          p.value = 'region';
+        }
+      }
+    }
+    return patches;
+  },
+};
+/**
+ * Collect every `group` node in the tree that carries a description,
+ * in depth-first order. Includes nested described groups.
+ *
+ * @param {A11yNode} node - Node to search from.
+ * @returns {A11yNode[]} All described group nodes, including nested ones.
+ */
+function collectDescribedGroups(node) {
+  var _a;
+  const out = [];
+  // Check if this node is a described group
+  if (node.role === 'group' && node.description) {
+    out.push(node);
+  }
+  // Always recurse into children to find nested described groups
+  for (const c of (_a = node.children) !== null && _a !== void 0 ? _a : []) {
+    out.push(...collectDescribedGroups(c));
+  }
+  return out;
+}

package/dist/collection/helpers/a11y-tree/strategies/webkit-voiceover-strategy.js

@@ -0,0 +1,140 @@
+import { baselineStrategy } from './baseline-strategy';
+/**
+ * WebKit + VoiceOver strategy.
+ *
+ * Applies on top of the baseline to work around two known VoiceOver quirks:
+ *
+ * **Quirk #1 — `aria-describedby` on non-focusable containers is skipped.**
+ * VoiceOver on Safari often does not read `aria-describedby` on non-focusable
+ * `role="group"` (A11yContainerNode) or `role="region"` (A11yLandmarkNode)
+ * containers. Workaround: fold the description text directly into the
+ * heading's `aria-label` (joined with `. `) so it is read together with the
+ * title, and remove the orphaned `aria-describedby` patch.
+ *
+ * **Quirk #2 — Decorative `<vega-icon>` announced twice.**
+ * Safari occasionally announces a decorative icon twice when only
+ * `aria-hidden` is set on the host. We additionally set `role="none"` as a
+ * belt-and-suspenders guard that suppresses the extra announcement.
+ *
+ * These adjustments are applied as a *diff* on top of the baseline patch
+ * list — the A11y Tree itself is unchanged. Other node types fall back to
+ * baseline behaviour.
+ */
+export const webkitVoiceOverStrategy = {
+  name: 'webkit-voiceover',
+  /**
+   * Compile ARIA patches, applying the two VoiceOver workarounds.
+   *
+   * @param {A11yNode} root - Root of the semantic A11y Tree to compile.
+   * @returns {AriaPatch[]} ARIA patches adjusted for WebKit + VoiceOver.
+   */
+  compile(root) {
+    var _a;
+    const patches = baselineStrategy.compile(root);
+    // Quirk #1: fold each described container's description into its heading's
+    // aria-label. The non-focusable-container quirk affects both role="group"
+    // (A11yContainerNode) and role="region" (A11yLandmarkNode). Generalized to
+    // iterate every described container so components with multiple described
+    // groups/regions all get folded correctly instead of only the first pair.
+    for (const container of collectDescribedContainers(root)) {
+      // Use the first heading owned by this container (not crossing nested
+      // described-container boundaries), or fall back to the container itself.
+      const heading = (_a = findOwnedHeading(container)) !== null && _a !== void 0 ? _a : container;
+      const combined = [heading.label, container.description].filter(Boolean).join('. ');
+      // Emit an explicit removal patch (value: null) for the container's
+      // aria-describedby. VoiceOver double-announces the description when it
+      // is both folded into the heading label AND referenced via
+      // aria-describedby, so we untrack the attribute declaratively (rather
+      // than silently dropping the patch) to keep re-render cleanup correct.
+      //
+      // When folding onto the container itself (no owned heading found), also
+      // update the existing aria-label patch in-place so we do not produce a
+      // duplicate patch that would leave the old value visible to consumers
+      // using Array.find().
+      const foldingOntoContainer = heading.id === container.id;
+      for (const p of patches) {
+        if (p.targetId === container.id && p.attribute === 'aria-describedby') {
+          p.value = null;
+        }
+        if (foldingOntoContainer && p.targetId === container.id && p.attribute === 'aria-label') {
+          p.value = combined;
+        }
+      }
+      if (!foldingOntoContainer) {
+        patches.push({ targetId: heading.id, attribute: 'aria-label', value: combined });
+      }
+    }
+    // Quirk #2: harden decorative icons with role="none".
+    walkIcons(root, (n) => {
+      if (n.decorative) {
+        patches.push({ targetId: n.id, attribute: 'role', value: 'none' });
+      }
+    });
+    return patches;
+  },
+};
+/**
+ * Find the first heading node owned directly by a described container,
+ * stopping at nested described-container boundaries.
+ *
+ * A heading "owned" by a container is one that lives in that container's
+ * direct subtree but NOT inside a nested described group/region. Those inner
+ * headings belong to the inner container's own fold pass, so crossing their
+ * boundary would cause the outer container's description to overwrite the
+ * inner heading's aria-label and then be lost when the inner pass runs.
+ *
+ * If no owned heading is found, the caller falls back to the container itself
+ * (the `?? container` in compile()), folding the description onto the
+ * container's own aria-label.
+ *
+ * @param {A11yNode} node - The container to search within.
+ * @returns {A11yNode | undefined} First heading owned by this container, if any.
+ */
+function findOwnedHeading(node) {
+  var _a;
+  for (const c of (_a = node.children) !== null && _a !== void 0 ? _a : []) {
+    // Stop at nested described-container boundaries — their headings belong
+    // to those containers' own fold passes, not this one.
+    if ((c.role === 'group' || c.role === 'region') && c.description) {
+      continue;
+    }
+    if (c.role === 'heading')
+      return c;
+    const hit = findOwnedHeading(c);
+    if (hit)
+      return hit;
+  }
+  return undefined;
+}
+/**
+ * Visit every image node in the tree, invoking the callback on each.
+ *
+ * @param {A11yNode} node - Node to walk from.
+ * @param {(n: A11yNode) => void} fn - Callback invoked for each image node.
+ */
+function walkIcons(node, fn) {
+  var _a;
+  if (node.role === 'img')
+    fn(node);
+  (_a = node.children) === null || _a === void 0 ? void 0 : _a.forEach((c) => walkIcons(c, fn));
+}
+/**
+ * Collect every `group` or `region` node in the tree that carries a
+ * description, in depth-first order. Includes nested described containers.
+ *
+ * @param {A11yNode} node - Node to search from.
+ * @returns {A11yNode[]} All described container nodes, including nested ones.
+ */
+function collectDescribedContainers(node) {
+  var _a;
+  const out = [];
+  // Check if this node is a described container
+  if ((node.role === 'group' || node.role === 'region') && node.description) {
+    out.push(node);
+  }
+  // Always recurse into children to find nested described containers
+  for (const c of (_a = node.children) !== null && _a !== void 0 ? _a : []) {
+    out.push(...collectDescribedContainers(c));
+  }
+  return out;
+}

package/dist/collection/helpers/a11y-tree/strategy-resolver.js

@@ -0,0 +1,172 @@
+import { baselineStrategy } from './strategies/baseline-strategy';
+import { firefoxNvdaStrategy } from './strategies/firefox-nvda-strategy';
+import { webkitVoiceOverStrategy } from './strategies/webkit-voiceover-strategy';
+/**
+ * All registered strategies. The resolver picks from this list; callers that
+ * need exhaustive enumeration (e.g. tests, Storybook knobs) can import this
+ * constant directly.
+ */
+export const ALL_A11Y_STRATEGIES = [
+  baselineStrategy,
+  webkitVoiceOverStrategy,
+  firefoxNvdaStrategy,
+];
+/**
+ * Picks an `A11yTreeStrategy` from the runtime environment and returns the
+ * full `A11yStrategyResolution` including confidence and a reason string.
+ *
+ * ## Browser-engine detection
+ *
+ * AT cannot be detected from JS (user privacy). We branch on *browser engine*
+ * as a coarse proxy for the most likely AT pairing on each platform:
+ *
+ * | Engine    | Assumed AT                   | Confidence              |
+ * |-----------|------------------------------|-------------------------|
+ * | WebKit    | VoiceOver (macOS/iOS)        | medium on Apple, low elsewhere |
+ * | Gecko     | NVDA (Win), Orca (Linux)     | medium on Win32, low elsewhere |
+ * | Chromium  | JAWS / NVDA / TalkBack       | high on non-Apple, medium on Apple |
+ *
+ * An explicit `data-a11y-strategy` attribute on the host element is always
+ * treated as `high` confidence (known override). If the override value does
+ * not match any registered strategy name, the resolver falls back to baseline
+ * with `low` confidence and logs an actionable warning.
+ *
+ * @param {HTMLElement} [host] - The component host element. When provided, its
+ *   `data-a11y-strategy` attribute is checked first.
+ * @returns {A11yStrategyResolution} The resolved strategy with confidence and reason.
+ */
+export function resolveStrategyDetailed(host) {
+  var _a, _b;
+  // Explicit override takes precedence over UA detection.
+  const override = (_a = host === null || host === void 0 ? void 0 : host.getAttribute('data-a11y-strategy')) !== null && _a !== void 0 ? _a : null;
+  if (override) {
+    const found = ALL_A11Y_STRATEGIES.find((s) => s.name === override);
+    if (found) {
+      return {
+        strategy: found,
+        confidence: 'high',
+        reason: `explicit override via data-a11y-strategy="${override}"`,
+      };
+    }
+    // Unknown override name — warn and fall back to baseline.
+    return {
+      strategy: baselineStrategy,
+      confidence: 'low',
+      reason: `unknown data-a11y-strategy="${override}"; known strategies: ${ALL_A11Y_STRATEGIES.map((s) => s.name).join(', ')}. Falling back to baseline.`,
+    };
+  }
+  // Read the runtime navigator explicitly from `globalThis` (not the bare
+  // `navigator` identifier, which build tooling may substitute). Delegate the
+  // pure UA→strategy mapping to `resolveStrategyFromEnv` so it can be unit
+  // tested deterministically without mocking globals.
+  const nav = globalThis.navigator;
+  return resolveStrategyFromEnv(nav === null || nav === void 0 ? void 0 : nav.userAgent, (_b = nav === null || nav === void 0 ? void 0 : nav.platform) !== null && _b !== void 0 ? _b : '');
+}
+/**
+ * Pure UA→strategy mapping. Separated from `resolveStrategyDetailed` so the
+ * browser-engine detection table can be unit tested deterministically by
+ * passing explicit `userAgent` / `platform` values instead of mocking the
+ * global `navigator` (which build/test tooling may sandbox).
+ *
+ * @param {string | undefined} userAgent - The `navigator.userAgent` string, or
+ *   `undefined` for an SSR / non-browser environment.
+ * @param {string} platform - The `navigator.platform` string (empty string when
+ *   unavailable).
+ * @returns {A11yStrategyResolution} The resolved strategy with confidence and reason.
+ */
+export function resolveStrategyFromEnv(userAgent, platform) {
+  // SSR / non-browser environment: no UA available.
+  if (userAgent === undefined) {
+    return {
+      strategy: baselineStrategy,
+      confidence: 'medium',
+      reason: 'no navigator (SSR or non-browser environment); baseline assumed',
+    };
+  }
+  const ua = userAgent;
+  // Order matters: Safari UA contains "Safari" but Chrome UA also does.
+  if (/\bFirefox\//.test(ua)) {
+    // Firefox + NVDA is the canonical pairing on Windows; on other
+    // platforms (macOS VoiceOver, Linux Orca, Windows JAWS) this is a
+    // probabilistic guess.
+    const isWindows = /Win/i.test(platform);
+    return {
+      strategy: firefoxNvdaStrategy,
+      confidence: isWindows ? 'medium' : 'low',
+      reason: isWindows
+        ? 'Firefox on Windows — assumed NVDA (most common pairing on Win32)'
+        : 'Firefox on non-Windows platform — AT pairing is a guess (may be Orca, VoiceOver, or JAWS)',
+    };
+  }
+  if (/^((?!chrome|android).)*safari/i.test(ua)) {
+    const isApple = /Mac|iPhone|iPad|iPod/i.test(platform);
+    return {
+      strategy: webkitVoiceOverStrategy,
+      confidence: isApple ? 'medium' : 'low',
+      reason: isApple
+        ? 'WebKit on Apple platform — assumed VoiceOver'
+        : 'WebKit on non-Apple platform — AT pairing is a guess',
+    };
+  }
+  // Chromium (Edge/Chrome). On macOS, Chromium routes through VoiceOver's
+  // accessibility tree; baseline covers most users but VoiceOver quirks may
+  // surface. Surfaced as medium confidence so the override path stays
+  // discoverable.
+  const onApple = /Mac|iPhone|iPad|iPod/i.test(platform);
+  return {
+    strategy: baselineStrategy,
+    confidence: onApple ? 'medium' : 'high',
+    reason: onApple
+      ? 'Chromium on Apple platform — VoiceOver may diverge from Chromium baseline'
+      : 'Chromium on non-Apple platform — baseline is the expected AT mapping',
+  };
+}
+/**
+ * Convenience wrapper for callers that only need the resolved strategy.
+ * Equivalent to `resolveStrategyDetailed(host).strategy` but additionally
+ * emits a **dev-mode console warning** for `low`-confidence resolutions,
+ * pointing engineers at the `data-a11y-strategy` override mechanism.
+ *
+ * The warning is rate-limited per `(strategyName, reason)` tuple to avoid
+ * log spam on every render cycle.
+ *
+ * @param {HTMLElement} [host] - The component host element (optional). Used for
+ *   the `data-a11y-strategy` override check.
+ * @returns {A11yTreeStrategy} The resolved strategy.
+ */
+export function resolveStrategy(host) {
+  const resolution = resolveStrategyDetailed(host);
+  if (resolution.confidence === 'low') {
+    warnOnce(resolution.strategy.name, resolution.reason);
+  }
+  return resolution.strategy;
+}
+const warnedKeys = new Set();
+/**
+ * Emit a console.warn once per (strategy, reason) tuple. Suppressed in
+ * production builds and when `console` is unavailable (SSR).
+ *
+ * @param {string} strategyName - Name of the resolved strategy.
+ * @param {string} reason - Human-readable reason for the resolution.
+ * @internal
+ */
+function warnOnce(strategyName, reason) {
+  var _a, _b;
+  if (typeof console === 'undefined')
+    return;
+  // Only warn in dev mode. Production builds set NODE_ENV=production;
+  // the guard below also handles minified bundles where `process` may
+  // be undefined.
+  const env = (_b = (_a = globalThis.process) === null || _a === void 0 ? void 0 : _a.env) === null || _b === void 0 ? void 0 : _b.NODE_ENV;
+  if (env === 'production')
+    return;
+  const key = `${strategyName}::${reason}`;
+  if (warnedKeys.has(key))
+    return;
+  warnedKeys.add(key);
+  console.warn(`[vega a11y-tree] Low-confidence strategy resolution: using "${strategyName}". ` +
+    `Reason: ${reason}. ` +
+    `Pin via data-a11y-strategy="<strategy-name>" to silence this warning ` +
+    `when you know the correct AT pairing. ` +
+    `Known strategies: ${ALL_A11Y_STRATEGIES.map((s) => s.name).join(', ')}.`);
+}