@heartlandone/vega 2.95.0 → 2.96.0

package/dist/types/components/vega-rich-text-editor/slimmers/renderers/tools/bullets-numbers/helper/list-tab-indent-handler.d.ts

@@ -0,0 +1,15 @@
+import { Nullable } from '../../../../../../../types/general';
+import { RTEBlock } from '../../../../../dto/blocks/block.abstract';
+import { RTETextNode } from '../../../../../dto/nodes/text-node';
+import { AbstractListKeyboardHandler } from './abstract-list-keyboard-handler';
+/**
+ * Handles Tab key list indentation.
+ * Normalizes the selection, applies a command-style gate on the first
+ * eligible segment, then nests each qualifying segment.
+ */
+export declare class ListTabIndentHandler extends AbstractListKeyboardHandler {
+  /**
+   * @inheritDoc
+   */
+  execute(selectedBlocks: RTEBlock[]): Array<Nullable<[RTETextNode, RTETextNode]>> | null;
+}

package/dist/types/components/vega-rich-text-editor/slimmers/renderers/tools/bullets-numbers/list-keyboard-slimmer.d.ts

@@ -0,0 +1,73 @@
+import { VegaSlimmer } from '../../../../../../vega-slimmer/vega-slimmer-core';
+import { BulletsNumbersToolbarButtonSlimmer } from './bullets-numbers-toolbar-button-slimmer';
+/**
+ * Handles list keyboard shortcuts (Tab/Shift+Tab) for list tooling.
+ */
+export declare class ListKeyboardSlimmer extends VegaSlimmer {
+  protected readonly selectionController: BulletsNumbersToolbarButtonSlimmer['selectionController'];
+  protected readonly valueController: BulletsNumbersToolbarButtonSlimmer['valueController'];
+  protected readonly value: BulletsNumbersToolbarButtonSlimmer['value'];
+  protected readonly toolbarItems: BulletsNumbersToolbarButtonSlimmer['toolbarItems'];
+  protected readonly vegaRichTextEditorRenderer: BulletsNumbersToolbarButtonSlimmer['vegaRichTextEditorRenderer'];
+  private boundEditableElement;
+  private isKeyboardListenerBound;
+  private readonly listTabIndentHandler;
+  private readonly listShiftTabOutdentHandler;
+  /**
+   * @inheritDoc
+   */
+  disconnectedCallback(): void;
+  /**
+   * @inheritDoc
+   */
+  componentDidLoad(): void;
+  /**
+   * Re-sync keyboard listener when toolbarItems prop changes at runtime,
+   * ensuring list shortcuts are bound/unbound as tools are added/removed.
+   */
+  watchToolbarItems(): void;
+  /**
+   * Synchronize the DOM keydown listener with the configured toolbar items.
+   */
+  private syncListKeyboardListener;
+  /**
+   * Determine whether any list keyboard controls are enabled in the toolbar.
+   *
+   * @returns {boolean} True when any list toolbar item is configured.
+   */
+  private hasListToolbarConfigured;
+  /**
+   * Attach the keydown listener to the current editable element when available.
+   * Handles element ref changes by rebinding when the target element differs.
+   */
+  private addListKeyboardListener;
+  /**
+   * Detach the keydown listener from the previously bound editable element.
+   */
+  private removeListKeyboardListener;
+  /**
+   * Handle Tab and Shift+Tab list keyboard interactions.
+   *
+   * @param {KeyboardEvent} e - Keyboard event to process.
+   * @returns {void}
+   */
+  private handleListKeyboardAction;
+  /**
+   * Check whether the Tab event includes modifiers other than Shift.
+   *
+   * @param {KeyboardEvent} e - Keyboard event to inspect.
+   * @returns {boolean} True when non-shift modifier keys are pressed.
+   */
+  private hasNonShiftModifierForTab;
+  /**
+   * Restore the logical selection after a list keyboard action completes.
+   *
+   * @param {Array<Nullable<[RTETextNode, RTETextNode]>>} selectionBoundaries - Boundaries produced by the handler.
+   * @param {Nullable<RTETextNode>} preferredStartNode - Preferred start node from prior selection.
+   * @param {Nullable<RTETextNode>} preferredEndNode - Preferred end node from prior selection.
+   * @param {number} startOffset - Preferred start offset.
+   * @param {number} endOffset - Preferred end offset.
+   * @returns {void}
+   */
+  private restoreListSelection;
+}

package/dist/types/components/vega-section-title/slimmers/a11y-tree/build-section-title-a11y-tree.d.ts

@@ -0,0 +1,41 @@
+import { A11yNode } from '../../../../helpers/a11y-tree/a11y-tree.types';
+interface BuildArgs {
+  titleText: string;
+  icon?: string;
+  iconAlign?: 'left' | 'right';
+  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+}
+/**
+ * Build the semantic A11y Tree for a `vega-section-title` instance.
+ *
+ * The structure uses a presentation wrapper so the container is transparent to
+ * assistive technology — the heading is the semantic anchor:
+ *
+ * ```
+ * presentation  "st-root"    (role=none — AT-transparent wrapper)
+ *   ├── heading "st-heading"  (titleText, level=2 by default)
+ *   └── icon    "st-icon"     (decorative — only when an icon prop is set)
+ * ```
+ *
+ * Description text is not wired into the A11y tree. It is exposed as plain
+ * visible text in the component's shadow DOM, read by screen readers via normal
+ * linear traversal. This avoids three VoiceOver regressions introduced when the
+ * container carried `role="group"` with `aria-label` + `aria-describedby`:
+ *
+ * - Bug 1 (Safari): webkit folded the description into the heading `aria-label`,
+ *   so focusing the H2 announced both title AND description together.
+ * - Bug 2 (Chrome, no description): `role="group"` created an extra navigation
+ *   boundary and announced the title twice (group label + heading).
+ * - Bug 3 (Chrome, with description): description read twice — once via the
+ *   hidden `aria-describedby` span on the group, once via the visible div.
+ *
+ * **No inline ARIA / no double projection**: this function must NOT set
+ * `aria-*` or `role` attributes directly on the component. The A11y Tree
+ * slimmer (`A11yTreeSlimmer`) calls `applyA11yTree()` on every render to
+ * project the semantic intent through the chosen strategy.
+ *
+ * @param {BuildArgs} args - Section-title fields used to author the semantic tree.
+ * @returns {A11yNode} The semantic A11y Tree root for the section title.
+ */
+export declare function buildSectionTitleA11yTree(args: BuildArgs): A11yNode;
+export {};

package/dist/types/components/vega-section-title/vega-section-title.d.ts

@@ -4,6 +4,7 @@ import { IconAlignType } from '../../types/ui.type';
 import { TextColorsTokenType } from '../../types/design-token.type';
 import { VegaSectionTitleSizeType } from './types';
 import { VegaComponentUsageRuntimeMetricsSlimmer } from '../../helpers/slimmers/component-usage-runtime-metrics';
+import { A11yTreeSlimmer } from '../../helpers/slimmers/a11y-tree-slimmer';
 /**
  * @vegaVersion 2.1.0
  */
@@ -11,6 +12,14 @@ export declare class VegaSectionTitle {
   protected readonly globalSlimmers: GlobalSlimmers;
   protected readonly renderer: VegaSectionTitleRenderer;
   protected vegaComponentUsageRuntimeMetricsSlimmer: VegaComponentUsageRuntimeMetricsSlimmer<HTMLVegaSectionTitleElement>;
+  /**
+   * Projects the component's semantic accessibility intent onto the shadow
+   * DOM via the A11y Tree foundation. Replaces the previous inline `role` /
+   * `aria-label` on the host element so ARIA is authored once, in
+   * `buildSectionTitleA11yTree`, and projected through the browser-engine
+   * strategy layer (no double projection).
+   */
+  protected readonly a11yTreeSlimmer: A11yTreeSlimmer<HTMLVegaSectionTitleElement>;
   host: HTMLVegaSectionTitleElement;
   /**
    * Specifies the text content of the title displayed

package/dist/types/components.d.ts

@@ -1684,8 +1684,8 @@ export namespace Components {
          */
         "isLoading": boolean;
         /**
-          * Determines whether the dropdown position is calculated relative to the screen.
-          * @VegaWarning - It will overrides the positionRelativeTo and matchContainerHeight properties, rendering them ineffective. - Currently, when set to true, the position calculation may be inaccurate if the popover is placed inside a scrollable container within a shadowRoot (e.g., inside a vega-modal with scrollable content).
+          * Determines whether the dropdown uses viewport-based positioning (`position: fixed`) or container-based positioning (`position: absolute`).  **Technical Implementation:**  - When `false` (default): The dropdown content box renders with `position: absolute` and its coordinates are calculated relative to the nearest positioned ancestor. Combined with `positionRelativeTo`, you can specify which ancestor to measure from, which ensures the menu scrolls together with that ancestor.  - When `true`: The dropdown content box renders with `position: fixed` and its coordinates are calculated from the viewport. The menu is visually anchored to the trigger element via JavaScript and moves with it on scroll, even though it is not part of the document flow. `positionRelativeTo` has no effect in this mode.  When to set `isScreenPosition` to `true`:  - Dropdowns that need to break out of container constraints (non-Shadow-DOM only):    When you want the dropdown to appear outside its container's boundaries (e.g., to avoid being clipped by a parent's    `overflow: hidden` or small dimensions), viewport-based positioning allows it to render freely.    This only works for regular (non-Shadow-DOM) containers. Shadow DOM boundaries cannot be escaped with `position: fixed`.  - Dropdowns in fixed or sticky positioned containers:    When the dropdown trigger is inside a fixed or sticky positioned container, viewport-based positioning ensures correct alignment.  When to keep `isScreenPosition` as `false` (default):  - Simple layouts where the dropdown and its trigger are not inside scrollable containers - When you want the dropdown to scroll naturally with its container (using `position: absolute`) - When you need `positionRelativeTo` to control which ancestor the dropdown is positioned relative to - When `matchContainerHeight` is needed (this property is overridden when `isScreenPosition` is `true`)
+          * @VegaWarning - Setting this to `true` override the `positionRelativeTo` and `matchContainerHeight` properties, rendering them ineffective. - Currently, when set to `true`, the position calculation may be inaccurate if the popover is placed inside a scrollable container within a shadowRoot (e.g., inside a vega-modal with scrollable content).
           * @vegaVersion 2.36.0
          */
         "isScreenPosition": boolean;
@@ -7853,7 +7853,7 @@ declare namespace LocalJSX {
          */
         "onCreate"?: (event: VegaComboBoxCustomEvent<string>) => void;
         /**
-          * An event emitter notifying that the Select All option in the dropdown has been clicked.  The event's `detail` property is `true` when all items become selected, and `false` when Select All is cleared.
+          * An event emitter only fired when the Select All checkbox in the dropdown has been clicked.  The event's `detail` property is `true` when the Select All checkbox is clicked to select all items,    and `false` when the Select All checkbox is clicked to clear all selected items.
           * @eventSemantics namespace:native
           * @vegaVersion 2.95.0
          */
@@ -7875,7 +7875,7 @@ declare namespace LocalJSX {
          */
         "onVegaCreate"?: (event: VegaComboBoxCustomEvent<string>) => void;
         /**
-          * An event emitter notifying that the Select All option in the dropdown has been clicked.  The event's `detail` property is `true` when all items become selected, and `false` when Select All is cleared.
+          * An event emitter only fired when the Select All checkbox in the dropdown has been clicked.  The event's `detail` property is `true` when the Select All checkbox is clicked to select all items,    and `false` when the Select All checkbox is clicked to clear all selected items.
           * @vegaVersion 2.95.0
          */
         "onVegaDropdownSelectAllClick"?: (event: VegaComboBoxCustomEvent<boolean>) => void;
@@ -8309,8 +8309,8 @@ declare namespace LocalJSX {
          */
         "isLoading"?: boolean;
         /**
-          * Determines whether the dropdown position is calculated relative to the screen.
-          * @VegaWarning - It will overrides the positionRelativeTo and matchContainerHeight properties, rendering them ineffective. - Currently, when set to true, the position calculation may be inaccurate if the popover is placed inside a scrollable container within a shadowRoot (e.g., inside a vega-modal with scrollable content).
+          * Determines whether the dropdown uses viewport-based positioning (`position: fixed`) or container-based positioning (`position: absolute`).  **Technical Implementation:**  - When `false` (default): The dropdown content box renders with `position: absolute` and its coordinates are calculated relative to the nearest positioned ancestor. Combined with `positionRelativeTo`, you can specify which ancestor to measure from, which ensures the menu scrolls together with that ancestor.  - When `true`: The dropdown content box renders with `position: fixed` and its coordinates are calculated from the viewport. The menu is visually anchored to the trigger element via JavaScript and moves with it on scroll, even though it is not part of the document flow. `positionRelativeTo` has no effect in this mode.  When to set `isScreenPosition` to `true`:  - Dropdowns that need to break out of container constraints (non-Shadow-DOM only):    When you want the dropdown to appear outside its container's boundaries (e.g., to avoid being clipped by a parent's    `overflow: hidden` or small dimensions), viewport-based positioning allows it to render freely.    This only works for regular (non-Shadow-DOM) containers. Shadow DOM boundaries cannot be escaped with `position: fixed`.  - Dropdowns in fixed or sticky positioned containers:    When the dropdown trigger is inside a fixed or sticky positioned container, viewport-based positioning ensures correct alignment.  When to keep `isScreenPosition` as `false` (default):  - Simple layouts where the dropdown and its trigger are not inside scrollable containers - When you want the dropdown to scroll naturally with its container (using `position: absolute`) - When you need `positionRelativeTo` to control which ancestor the dropdown is positioned relative to - When `matchContainerHeight` is needed (this property is overridden when `isScreenPosition` is `true`)
+          * @VegaWarning - Setting this to `true` override the `positionRelativeTo` and `matchContainerHeight` properties, rendering them ineffective. - Currently, when set to `true`, the position calculation may be inaccurate if the popover is placed inside a scrollable container within a shadowRoot (e.g., inside a vega-modal with scrollable content).
           * @vegaVersion 2.36.0
          */
         "isScreenPosition"?: boolean;
@@ -8375,7 +8375,7 @@ declare namespace LocalJSX {
          */
         "onDropdownSearch"?: (event: VegaDropdownCustomEvent<string>) => void;
         /**
-          * An event emitter notifying that the Select All option has been clicked.  The event's `detail` property is `true` when all items become selected, and `false` when Select All is cleared.
+          * An event emitter only fired when the Select All checkbox has been clicked.  The event's `detail` property is `true` when the Select All checkbox is clicked to select all items,    and `false` when the Select All checkbox is clicked to clear all selected items.
           * @eventSemantics namespace:native
           * @vegaVersion 2.93.0
          */
@@ -8409,7 +8409,7 @@ declare namespace LocalJSX {
          */
         "onVegaDropdownClick"?: (event: VegaDropdownCustomEvent<string>) => void;
         /**
-          * An event emitter notifying that the Select All option has been clicked.  The event's `detail` property is `true` when all items become selected, and `false` when Select All is cleared.
+          * An event emitter only fired when the Select All checkbox has been clicked.  The event's `detail` property is `true` when the Select All checkbox is clicked to select all items,    and `false` when the Select All checkbox is clicked to clear all selected items.
           * @vegaVersion 2.93.0
          */
         "onVegaDropdownSelectAllClick"?: (event: VegaDropdownCustomEvent<boolean>) => void;
@@ -9952,7 +9952,7 @@ declare namespace LocalJSX {
          */
         "onChange"?: (event: VegaInputSelectCustomEvent<SelectValueType<SelectType>>) => void;
         /**
-          * An event emitter notifying that the Select All option in the dropdown has been clicked.  The event's `detail` property is `true` when all items become selected, and `false` when Select All is cleared.
+          * An event emitter only fired when the Select All checkbox in the dropdown has been clicked.  The event's `detail` property is `true` when the Select All checkbox is clicked to select all items,    and `false` when the Select All checkbox is clicked to clear all selected items.
           * @eventSemantics namespace:native
           * @vegaVersion 2.95.0
          */
@@ -9981,7 +9981,7 @@ declare namespace LocalJSX {
          */
         "onVegaChange"?: (event: VegaInputSelectCustomEvent<SelectValueType<SelectType>>) => void;
         /**
-          * An event emitter notifying that the Select All option in the dropdown has been clicked.  The event's `detail` property is `true` when all items become selected, and `false` when Select All is cleared.
+          * An event emitter only fired when the Select All checkbox in the dropdown has been clicked.  The event's `detail` property is `true` when the Select All checkbox is clicked to select all items,    and `false` when the Select All checkbox is clicked to clear all selected items.
           * @vegaVersion 2.95.0
          */
         "onVegaDropdownSelectAllClick"?: (event: VegaInputSelectCustomEvent<boolean>) => void;

package/dist/types/helpers/a11y-tree/a11y-node-dto.d.ts

@@ -0,0 +1,173 @@
+import { A11yNode, A11ySemanticKind } from './a11y-tree.types';
+/**
+ * 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 declare abstract class A11yNodeDto {
+  protected childDtos: A11yNodeDto[];
+  abstract readonly kind: A11ySemanticKind;
+  /**
+   * 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: A11yNodeDto[]): this;
+  /**
+   * Compile the declared child DTOs into their `A11yNode` representations.
+   *
+   * @returns {A11yNode[] | undefined} The compiled children, or `undefined` when none.
+   */
+  protected compileChildren(): A11yNode[] | undefined;
+  /** Compile this DTO (and its subtree) into an `A11yNode`. */
+  abstract toA11yNode(): A11yNode;
+}
+/**
+ * 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 declare class A11yContainerNode extends A11yNodeDto {
+  readonly id: string;
+  readonly opts: {
+    label?: string;
+    description?: string;
+  };
+  readonly kind: A11ySemanticKind;
+  constructor(id: string, opts?: {
+    label?: string;
+    description?: string;
+  });
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode(): A11yNode;
+}
+/**
+ * A navigable / discoverable section (landmark). Always renders as
+ * `role="region"` so it appears in AT landmark navigation.
+ */
+export declare class A11yLandmarkNode extends A11yNodeDto {
+  readonly id: string;
+  readonly opts: {
+    label?: string;
+    description?: string;
+  };
+  readonly kind: A11ySemanticKind;
+  constructor(id: string, opts?: {
+    label?: string;
+    description?: string;
+  });
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode(): A11yNode;
+}
+/**
+ * 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 declare class A11yHeadingNode extends A11yNodeDto {
+  readonly id: string;
+  readonly opts: {
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    label?: string;
+  };
+  readonly kind: A11ySemanticKind;
+  constructor(id: string, opts?: {
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    label?: string;
+  });
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode(): A11yNode;
+}
+/**
+ * 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 declare class A11yIconNode extends A11yNodeDto {
+  readonly id: string;
+  readonly kind: A11ySemanticKind;
+  constructor(id: string);
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode(): A11yNode;
+}
+/**
+ * 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 declare class A11yImageNode extends A11yNodeDto {
+  readonly id: string;
+  readonly opts: {
+    label: string;
+  };
+  readonly kind: A11ySemanticKind;
+  constructor(id: string, opts: {
+    label: string;
+  });
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode(): A11yNode;
+}

package/dist/types/helpers/a11y-tree/a11y-tree-applier.d.ts

@@ -0,0 +1,28 @@
+import { A11yNode } from './a11y-tree.types';
+/**
+ * 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 declare function applyA11yTree(root: A11yNode, host: HTMLElement): void;

package/dist/types/helpers/a11y-tree/a11y-tree.types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 declare type A11yRole = 'heading' | 'group' | 'region' | 'img' | 'presentation' | 'none';
+/**
+ * Semantic kind — describes *what the content is*, independent of which
+ * ARIA attribute it ultimately produces. Strategies may dispatch on `kind`
+ * for fine-grained control beyond what `role` can express.
+ *
+ * Authoritative definition: `a11y-node-dto.ts`. Re-exported here so tree
+ * literal authors can type-check without importing the DTO module.
+ */
+export declare type A11ySemanticKind = 'container' | 'landmark' | 'heading' | 'icon' | 'image' | 'button' | 'live';
+/**
+ * A single node in the semantic A11y Tree.
+ *
+ * Nodes are authored via the DTO helpers in `a11y-node-dto.ts` to avoid
+ * hand-shaping ARIA field names. Raw literals are still accepted by all
+ * APIs for backwards compatibility and quick inline use.
+ */
+export interface A11yNode {
+  /** Stable identifier; DOM nodes opt in via `data-a11y-id`. */
+  id: string;
+  /** Semantic role for this node. */
+  role: A11yRole;
+  /**
+   * Optional semantic discriminator emitted by the DTO layer.
+   * Strategies that need to distinguish intent beyond `role`
+   * (e.g. landmark vs plain container) dispatch on this first
+   * and fall back to `role` when absent.
+   */
+  kind?: A11ySemanticKind;
+  /** Visible text label (used for aria-label / aria-labelledby). */
+  label?: string;
+  /** Supplementary description (used for aria-describedby). */
+  description?: string;
+  /** Heading level (1–6) when role === 'heading'. */
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Whether this node is purely decorative. */
+  decorative?: boolean;
+  /** Child semantic nodes. */
+  children?: A11yNode[];
+}
+/**
+ * A flat instruction emitted by the strategy: "on the DOM node carrying
+ * `data-a11y-id=<targetId>`, set this attribute to this value".
+ *
+ * `value === null` means the attribute should be removed.
+ */
+export interface AriaPatch {
+  targetId: string;
+  attribute: string;
+  value: string | null;
+}
+/**
+ * Strategy contract. Each strategy encapsulates the per-browser/AT quirks
+ * needed to project an `A11yNode` tree onto real ARIA attributes.
+ *
+ * Strategies MUST be pure functions of the tree: same input → same output.
+ * Side effects (DOM manipulation) belong in `a11y-tree-applier.ts`.
+ */
+export interface A11yTreeStrategy {
+  /** Machine-readable name, used for `data-a11y-strategy` lookups. */
+  name: string;
+  /** Convert a semantic A11y tree into a flat list of ARIA patches. */
+  compile(root: A11yNode): AriaPatch[];
+}
+/**
+ * Confidence level for the strategy-resolver's UA→AT mapping.
+ *
+ *   - `high`   : we observed a direct signal (explicit override, or a
+ *                UA the resolver has confirmed test coverage for).
+ *   - `medium` : UA pattern is a known proxy but the AT pairing is an
+ *                assumption (e.g. Firefox → NVDA on Windows; users on
+ *                Linux running Orca will also match this branch).
+ *   - `low`    : we are falling back to baseline because we could not
+ *                recognise the UA at all.
+ *
+ * Low-confidence matches surface a dev-mode console warning (rate-limited
+ * per strategy+reason tuple) so product teams know when to pin a strategy
+ * explicitly via `data-a11y-strategy`.
+ */
+export declare type A11yStrategyConfidence = 'high' | 'medium' | 'low';
+/**
+ * Full resolution result including the strategy, how confident we are,
+ * and a human-readable reason string for dev warnings.
+ */
+export interface A11yStrategyResolution {
+  strategy: A11yTreeStrategy;
+  confidence: A11yStrategyConfidence;
+  /** Human-readable reason — surfaced in dev warnings. */
+  reason: string;
+}

package/dist/types/helpers/a11y-tree/strategies/baseline-strategy.d.ts

@@ -0,0 +1,18 @@
+import { A11yTreeStrategy } from '../a11y-tree.types';
+/**
+ * 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 declare const baselineStrategy: A11yTreeStrategy;

package/dist/types/helpers/a11y-tree/strategies/firefox-nvda-strategy.d.ts

@@ -0,0 +1,16 @@
+import { A11yTreeStrategy } from '../a11y-tree.types';
+/**
+ * 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 declare const firefoxNvdaStrategy: A11yTreeStrategy;

package/dist/types/helpers/a11y-tree/strategies/webkit-voiceover-strategy.d.ts

@@ -0,0 +1,23 @@
+import { A11yTreeStrategy } from '../a11y-tree.types';
+/**
+ * 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 declare const webkitVoiceOverStrategy: A11yTreeStrategy;