@heartlandone/vega 2.95.0 → 2.96.0

package/dist/collection/helpers/a11y-tree/a11y-node-dto.js

@@ -0,0 +1,210 @@
+/**
+ * Semantic DTO layer for the A11y Tree.
+ *
+ * Authoring an A11y Tree with raw `A11yNode` literals asks the developer to
+ * think in ARIA terms (`role: 'group'`, `decorative: true`, etc.). The DTO
+ * classes here provide a higher-level vocabulary that names the *content's
+ * meaning* — "this is a container", "this is a heading", "this is a
+ * decorative icon" — and lets the strategy layer translate intent into ARIA.
+ *
+ * ## Design (Visitor / Strategy + typed semantic DTOs)
+ *
+ * - DTOs are *type-holders for semantic intent*. They do NOT contain ARIA
+ *   generation logic themselves.
+ * - Each DTO compiles to an `A11yNode` whose `kind` field carries the
+ *   semantic discriminator. Strategies can then dispatch on `kind`
+ *   (preferred) or fall back to `role` (for plain `A11yNode` authors).
+ * - This keeps strategies pure and independently testable, while letting
+ *   authors write:
+ *
+ *   ```ts
+ *   new A11yContainerNode('st-root', { label, description })
+ *     .childrenWith(
+ *       new A11yHeadingNode('st-heading', { level: 2, label }),
+ *       new A11yIconNode('st-icon'),
+ *     );
+ *   ```
+ *
+ *   instead of hand-shaping `{ role: 'group', label, description, … }`.
+ *
+ * ## Migration path
+ *
+ * Phase 1 (this file): DTOs are an additive layer on top of `A11yNode`.
+ * Existing strategies continue to work unchanged because each DTO emits
+ * a fully-populated `A11yNode` with `role` set correctly.
+ *
+ * Phase 2 (follow-up): strategies grow `compileNode(node)` methods that
+ * dispatch on `node.kind` for cases where semantic intent is richer than
+ * `role` alone can express.
+ */
+/**
+ * Base class for all semantic DTO nodes. Provides the `childrenWith()`
+ * composition helper and the abstract `toA11yNode()` contract.
+ */
+export class A11yNodeDto {
+  constructor() {
+    this.childDtos = [];
+  }
+  /**
+   * Declare the semantic children of this node in reading order.
+   *
+   * @param {...A11yNodeDto} children - Semantic child DTOs in reading order.
+   * @returns {this} `this`, for fluent chaining.
+   */
+  childrenWith(...children) {
+    this.childDtos = children;
+    return this;
+  }
+  /**
+   * Compile the declared child DTOs into their `A11yNode` representations.
+   *
+   * @returns {A11yNode[] | undefined} The compiled children, or `undefined` when none.
+   */
+  compileChildren() {
+    if (this.childDtos.length === 0)
+      return undefined;
+    return this.childDtos.map((c) => c.toA11yNode());
+  }
+}
+/**
+ * A generic container that groups related content. Maps to `role="group"`
+ * by default; strategies may upgrade to `role="region"` when a description
+ * is present and the platform benefits (e.g. Firefox+NVDA landmark
+ * navigation — see `firefox-nvda-strategy.ts`).
+ */
+export class A11yContainerNode extends A11yNodeDto {
+  constructor(id, opts = {}) {
+    super();
+    this.id = id;
+    this.opts = opts;
+    this.kind = 'container';
+  }
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode() {
+    return {
+      id: this.id,
+      kind: this.kind,
+      role: 'group',
+      label: this.opts.label,
+      description: this.opts.description,
+      children: this.compileChildren(),
+    };
+  }
+}
+/**
+ * A navigable / discoverable section (landmark). Always renders as
+ * `role="region"` so it appears in AT landmark navigation.
+ */
+export class A11yLandmarkNode extends A11yNodeDto {
+  constructor(id, opts = {}) {
+    super();
+    this.id = id;
+    this.opts = opts;
+    this.kind = 'landmark';
+  }
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode() {
+    return {
+      id: this.id,
+      kind: this.kind,
+      role: 'region',
+      label: this.opts.label,
+      description: this.opts.description,
+      children: this.compileChildren(),
+    };
+  }
+}
+/**
+ * A heading at the given level (1–6, defaults to 2).
+ *
+ * Use this instead of a raw `{ role: 'heading', level: 2 }` literal to
+ * benefit from the default-level guard and the `kind` discriminator.
+ */
+export class A11yHeadingNode extends A11yNodeDto {
+  constructor(id, opts = {}) {
+    super();
+    this.id = id;
+    this.opts = opts;
+    this.kind = 'heading';
+  }
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode() {
+    var _a;
+    return {
+      id: this.id,
+      kind: this.kind,
+      role: 'heading',
+      level: (_a = this.opts.level) !== null && _a !== void 0 ? _a : 2,
+      label: this.opts.label,
+      children: this.compileChildren(),
+    };
+  }
+}
+/**
+ * A purely decorative icon. `decorative` is always `true` so authors never
+ * have to remember the flag — that is the whole point of this DTO class.
+ *
+ * Produces `aria-hidden="true"` via the baseline strategy; webkit-voiceover
+ * additionally sets `role="none"` as a belt-and-suspenders guard.
+ */
+export class A11yIconNode extends A11yNodeDto {
+  constructor(id) {
+    super();
+    this.id = id;
+    this.kind = 'icon';
+  }
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode() {
+    return {
+      id: this.id,
+      kind: this.kind,
+      role: 'img',
+      decorative: true,
+      children: this.compileChildren(),
+    };
+  }
+}
+/**
+ * An informative image that requires an accessible label (alt text).
+ *
+ * Produces `role="img"` + `aria-label` via the baseline strategy.
+ * Contrast with `A11yIconNode` which is always decorative.
+ */
+export class A11yImageNode extends A11yNodeDto {
+  constructor(id, opts) {
+    super();
+    this.id = id;
+    this.opts = opts;
+    this.kind = 'image';
+  }
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode() {
+    return {
+      id: this.id,
+      kind: this.kind,
+      role: 'img',
+      label: this.opts.label,
+      children: this.compileChildren(),
+    };
+  }
+}

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;
+}