@heartlandone/vega 2.94.0 → 2.96.0

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;
@@ -3246,7 +3246,7 @@ export namespace Components {
          */
         "animation": boolean;
         /**
-          * Provides options for controlling the behavior of the backdrop. - `default`:      indicates that the user can close the modal      by clicking on the backdrop. - `static`:      means that the user cannot close the modal by      clicking on the backdrop. - `none`:      specifies that the backdrop will not be rendered.  _Note_:    When changing this value, a page refresh is required    for the changes to take effect.
+          * Provides options for controlling the behavior of the backdrop. - `default`:      indicates that the user can close the modal      by clicking on the backdrop. - `static`:      means that the user cannot close the modal by      clicking on the backdrop. - `none`:      specifies that the backdrop will not be rendered.
           * @vegaVersion 1.0.6
          */
         "backdrop": VegaModalBackdrop;
@@ -3318,9 +3318,15 @@ export namespace Components {
         "showCloseButton": boolean;
         /**
           * Determines the size of the modal.  It can be specified as a number, a percentage string ending with "%",    or a ResponsiveType.  It is important to note that there are different maximum widths    for modal windows based on the viewport size. If the specified size exceeds    the maximum width, the maximum modal width will be used instead.
+          * @deprecated This property will be removed soon and replaced by prop width
           * @vegaVersion 1.0.6
          */
         "size": ResponsiveType<SizeType>;
+        /**
+          * Determines the width of the modal.  It can be specified as a number or a percentage string ending with "%". ResponsiveType can also be used for responsive configurations.  Note: There are different maximum widths for modal windows based on viewport size. If the specified width exceeds the maximum width, the maximum modal width will be used instead.
+          * @vegaVersion 2.95.0
+         */
+        "width": ResponsiveType<SizeType>;
     }
     interface VegaNavCard {
         /**
@@ -7846,6 +7852,12 @@ declare namespace LocalJSX {
           * @vegaVersion 2.0.0
          */
         "onCreate"?: (event: VegaComboBoxCustomEvent<string>) => void;
+        /**
+          * 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
+         */
+        "onDropdownSelectAllClick"?: (event: VegaComboBoxCustomEvent<boolean>) => void;
         /**
           * An event emitter notifying the user's search action in the combo box,    but only if the `useDefaultFilter` property is set to `false`.
           * @eventSemantics namespace:native
@@ -7862,6 +7874,11 @@ declare namespace LocalJSX {
           * @vegaVersion 1.14.0
          */
         "onVegaCreate"?: (event: VegaComboBoxCustomEvent<string>) => void;
+        /**
+          * 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;
         /**
           * An event emitter notifying the user's search action in the combo box,    but only if the `useDefaultFilter` property is set to `false`.
           * @vegaVersion 1.24.0
@@ -8292,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;
@@ -8358,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
          */
@@ -8392,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;
@@ -9934,6 +9951,12 @@ declare namespace LocalJSX {
           * @vegaVersion 2.0.0
          */
         "onChange"?: (event: VegaInputSelectCustomEvent<SelectValueType<SelectType>>) => void;
+        /**
+          * 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
+         */
+        "onDropdownSelectAllClick"?: (event: VegaInputSelectCustomEvent<boolean>) => void;
         /**
           * An event emitter notifying that the suffix button associated with the field label has been clicked.
           * @eventSemantics namespace:native
@@ -9957,6 +9980,11 @@ declare namespace LocalJSX {
           * @vegaVersion 1.0.11
          */
         "onVegaChange"?: (event: VegaInputSelectCustomEvent<SelectValueType<SelectType>>) => void;
+        /**
+          * 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;
         /**
           * Event emitter notifying that the input-select has been dismissed,    either programmatically or via user interaction.
           * @vegaVersion 2.32.0
@@ -10288,7 +10316,7 @@ declare namespace LocalJSX {
          */
         "animation"?: boolean;
         /**
-          * Provides options for controlling the behavior of the backdrop. - `default`:      indicates that the user can close the modal      by clicking on the backdrop. - `static`:      means that the user cannot close the modal by      clicking on the backdrop. - `none`:      specifies that the backdrop will not be rendered.  _Note_:    When changing this value, a page refresh is required    for the changes to take effect.
+          * Provides options for controlling the behavior of the backdrop. - `default`:      indicates that the user can close the modal      by clicking on the backdrop. - `static`:      means that the user cannot close the modal by      clicking on the backdrop. - `none`:      specifies that the backdrop will not be rendered.
           * @vegaVersion 1.0.6
          */
         "backdrop"?: VegaModalBackdrop;
@@ -10377,9 +10405,15 @@ declare namespace LocalJSX {
         "showCloseButton"?: boolean;
         /**
           * Determines the size of the modal.  It can be specified as a number, a percentage string ending with "%",    or a ResponsiveType.  It is important to note that there are different maximum widths    for modal windows based on the viewport size. If the specified size exceeds    the maximum width, the maximum modal width will be used instead.
+          * @deprecated This property will be removed soon and replaced by prop width
           * @vegaVersion 1.0.6
          */
         "size"?: ResponsiveType<SizeType>;
+        /**
+          * Determines the width of the modal.  It can be specified as a number or a percentage string ending with "%". ResponsiveType can also be used for responsive configurations.  Note: There are different maximum widths for modal windows based on viewport size. If the specified width exceeds the maximum width, the maximum modal width will be used instead.
+          * @vegaVersion 2.95.0
+         */
+        "width"?: ResponsiveType<SizeType>;
     }
     interface VegaNavCard {
         /**

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;

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

@@ -0,0 +1,59 @@
+import { A11yStrategyResolution, A11yTreeStrategy } from './a11y-tree.types';
+/**
+ * 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 declare const ALL_A11Y_STRATEGIES: A11yTreeStrategy[];
+/**
+ * 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 declare function resolveStrategyDetailed(host?: HTMLElement): A11yStrategyResolution;
+/**
+ * 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 declare function resolveStrategyFromEnv(userAgent: string | undefined, platform: string): A11yStrategyResolution;
+/**
+ * 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 declare function resolveStrategy(host?: HTMLElement): A11yTreeStrategy;

package/dist/types/helpers/backdrop/shared-backdrop-manager.d.ts

@@ -39,6 +39,14 @@ export declare abstract class SharedBackdropManager extends VegaSlimmer {
    * @param {boolean} visible - Desired visibility.
    */
   protected setVisibilityIntent(visible: boolean): void;
+  /**
+   * Whether this manager type handles backdrop existence lazily (on demand).
+   * Override and return `true` in derived classes that create/remove the backdrop
+   * per visibility cycle instead of at connectedCallback.
+   *
+   * @returns {boolean} False by default — backdrop is created eagerly at connect time.
+   */
+  protected usesLazyBackdrop(): boolean;
   /**
    * Ensure a backdrop exists for this subclass and return it.
    *
@@ -53,6 +61,14 @@ export declare abstract class SharedBackdropManager extends VegaSlimmer {
    * Sync shared backdrop `visible` based on current visibility intents.
    */
   private syncVisibility;
+  /**
+   * Handles visibility sync for manager types that opt into lazy backdrop lifecycle.
+   * When `shouldShow` is true the backdrop is created (if needed) and made visible.
+   * When `shouldShow` is false the backdrop is removed from the DOM.
+   *
+   * @param {boolean} shouldShow - Whether the backdrop should be visible.
+   */
+  private syncLazyBackdrop;
   /**
    * Reset stale static shared state when the tracked backdrop is no longer in the DOM.
    */