@heartlandone/vega 2.94.0 → 2.96.0

package/dist/esm/vega-section-title.entry.js

@@ -1,9 +1,10 @@
 import { h, r as registerInstance, H as Host, g as getElement } from './index-090d31ca.js';
 import { s as sanitizeVegaComponent } from './component-7d906393.js';
-import { c as MapToComponentField, V as VegaSlimmer, I as InjectVegaSlimmer } from './global-slimmer-registry-17c4efd4.js';
+import { c as MapToComponentField, V as VegaSlimmer, M as MapToComponentMethod, I as InjectVegaSlimmer } from './global-slimmer-registry-17c4efd4.js';
 import { V as VegaComponentUsageRuntimeMetricsSlimmer, I as InjectVegaGlobalSlimmer } from './component-usage-runtime-metrics-4b1afd04.js';
+import { t as tryGetDocument } from './try-get-document-bef0f526.js';
 
-var __decorate$1 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+var __decorate$2 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
@@ -11,13 +12,13 @@ var __decorate$1 = (undefined && undefined.__decorate) || function (decorators,
 };
 class VegaSectionTitleRenderer extends VegaSlimmer {
   render() {
-    return (h("vega-flex", { "aria-hidden": "true", "align-items": "start", "justify-content": "start", gap: "size-8", class: this.size === 'small' ? 'section-title-small' : undefined },
+    return (h("vega-flex", { "data-a11y-id": "st-root", "align-items": "start", "justify-content": "start", gap: "size-8", class: this.size === 'small' ? 'section-title-small' : undefined },
       this.renderPrefixIcon(),
       this.renderText()));
   }
   renderPrefixIcon() {
     return (this.icon &&
-      this.iconAlign === 'left' && h("div", { class: "section-title-icon-container" }, this.renderIcon()));
+      this.iconAlign === 'left' && (h("div", { "data-a11y-id": "st-icon", class: "section-title-icon-container" }, this.renderIcon())));
   }
   renderText() {
     return (h("vega-flex", { class: "vega-flex-grow", direction: "col", "align-items": "start", "justify-content": "start", gap: "size-4" },
@@ -26,7 +27,7 @@ class VegaSectionTitleRenderer extends VegaSlimmer {
   }
   renderTitle() {
     return (h("div", { class: "section-title-text vega-flex-grow" },
-      h("span", null, this.titleText),
+      h("span", { "data-a11y-id": "st-heading" }, this.titleText),
       this.renderSuffixIcon()));
   }
   renderDescription() {
@@ -34,34 +35,901 @@ class VegaSectionTitleRenderer extends VegaSlimmer {
   }
   renderSuffixIcon() {
     return (this.icon &&
-      this.iconAlign === 'right' && h("div", { class: "right-icon-container" }, this.renderIcon()));
+      this.iconAlign === 'right' && (h("div", { "data-a11y-id": "st-icon", class: "right-icon-container" }, this.renderIcon())));
   }
   renderIcon() {
     return (h("vega-icon", { icon: this.icon, color: this.iconColor, size: this.size === 'small' ? 'size-16' : 'size-20', class: "vega-flex-shrink-0" }));
   }
 }
-__decorate$1([
+__decorate$2([
   MapToComponentField()
 ], VegaSectionTitleRenderer.prototype, "host", void 0);
-__decorate$1([
+__decorate$2([
   MapToComponentField()
 ], VegaSectionTitleRenderer.prototype, "titleText", void 0);
-__decorate$1([
+__decorate$2([
   MapToComponentField()
 ], VegaSectionTitleRenderer.prototype, "description", void 0);
-__decorate$1([
+__decorate$2([
   MapToComponentField()
 ], VegaSectionTitleRenderer.prototype, "icon", void 0);
-__decorate$1([
+__decorate$2([
   MapToComponentField()
 ], VegaSectionTitleRenderer.prototype, "iconAlign", void 0);
-__decorate$1([
+__decorate$2([
   MapToComponentField()
 ], VegaSectionTitleRenderer.prototype, "iconColor", void 0);
-__decorate$1([
+__decorate$2([
   MapToComponentField()
 ], VegaSectionTitleRenderer.prototype, "size", void 0);
 
+/**
+ * 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"`                         |
+ */
+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));
+}
+
+/**
+ * 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.
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+const webkitVoiceOverStrategy = {
+  name: 'webkit-voiceover',
+  /**
+   * Compile ARIA patches, applying the two VoiceOver workarounds.
+   *
+   * @param {A11yNode} root - Root of the semantic A11y Tree to compile.
+   * @returns {AriaPatch[]} ARIA patches adjusted for WebKit + VoiceOver.
+   */
+  compile(root) {
+    var _a;
+    const patches = baselineStrategy.compile(root);
+    // Quirk #1: fold each described container's description into its heading's
+    // aria-label. The non-focusable-container quirk affects both role="group"
+    // (A11yContainerNode) and role="region" (A11yLandmarkNode). Generalized to
+    // iterate every described container so components with multiple described
+    // groups/regions all get folded correctly instead of only the first pair.
+    for (const container of collectDescribedContainers(root)) {
+      // Use the first heading owned by this container (not crossing nested
+      // described-container boundaries), or fall back to the container itself.
+      const heading = (_a = findOwnedHeading(container)) !== null && _a !== void 0 ? _a : container;
+      const combined = [heading.label, container.description].filter(Boolean).join('. ');
+      // Emit an explicit removal patch (value: null) for the container's
+      // aria-describedby. VoiceOver double-announces the description when it
+      // is both folded into the heading label AND referenced via
+      // aria-describedby, so we untrack the attribute declaratively (rather
+      // than silently dropping the patch) to keep re-render cleanup correct.
+      //
+      // When folding onto the container itself (no owned heading found), also
+      // update the existing aria-label patch in-place so we do not produce a
+      // duplicate patch that would leave the old value visible to consumers
+      // using Array.find().
+      const foldingOntoContainer = heading.id === container.id;
+      for (const p of patches) {
+        if (p.targetId === container.id && p.attribute === 'aria-describedby') {
+          p.value = null;
+        }
+        if (foldingOntoContainer && p.targetId === container.id && p.attribute === 'aria-label') {
+          p.value = combined;
+        }
+      }
+      if (!foldingOntoContainer) {
+        patches.push({ targetId: heading.id, attribute: 'aria-label', value: combined });
+      }
+    }
+    // Quirk #2: harden decorative icons with role="none".
+    walkIcons(root, (n) => {
+      if (n.decorative) {
+        patches.push({ targetId: n.id, attribute: 'role', value: 'none' });
+      }
+    });
+    return patches;
+  },
+};
+/**
+ * Find the first heading node owned directly by a described container,
+ * stopping at nested described-container boundaries.
+ *
+ * A heading "owned" by a container is one that lives in that container's
+ * direct subtree but NOT inside a nested described group/region. Those inner
+ * headings belong to the inner container's own fold pass, so crossing their
+ * boundary would cause the outer container's description to overwrite the
+ * inner heading's aria-label and then be lost when the inner pass runs.
+ *
+ * If no owned heading is found, the caller falls back to the container itself
+ * (the `?? container` in compile()), folding the description onto the
+ * container's own aria-label.
+ *
+ * @param {A11yNode} node - The container to search within.
+ * @returns {A11yNode | undefined} First heading owned by this container, if any.
+ */
+function findOwnedHeading(node) {
+  var _a;
+  for (const c of (_a = node.children) !== null && _a !== void 0 ? _a : []) {
+    // Stop at nested described-container boundaries — their headings belong
+    // to those containers' own fold passes, not this one.
+    if ((c.role === 'group' || c.role === 'region') && c.description) {
+      continue;
+    }
+    if (c.role === 'heading')
+      return c;
+    const hit = findOwnedHeading(c);
+    if (hit)
+      return hit;
+  }
+  return undefined;
+}
+/**
+ * Visit every image node in the tree, invoking the callback on each.
+ *
+ * @param {A11yNode} node - Node to walk from.
+ * @param {(n: A11yNode) => void} fn - Callback invoked for each image node.
+ */
+function walkIcons(node, fn) {
+  var _a;
+  if (node.role === 'img')
+    fn(node);
+  (_a = node.children) === null || _a === void 0 ? void 0 : _a.forEach((c) => walkIcons(c, fn));
+}
+/**
+ * Collect every `group` or `region` node in the tree that carries a
+ * description, in depth-first order. Includes nested described containers.
+ *
+ * @param {A11yNode} node - Node to search from.
+ * @returns {A11yNode[]} All described container nodes, including nested ones.
+ */
+function collectDescribedContainers(node) {
+  var _a;
+  const out = [];
+  // Check if this node is a described container
+  if ((node.role === 'group' || node.role === 'region') && node.description) {
+    out.push(node);
+  }
+  // Always recurse into children to find nested described containers
+  for (const c of (_a = node.children) !== null && _a !== void 0 ? _a : []) {
+    out.push(...collectDescribedContainers(c));
+  }
+  return out;
+}
+
+/**
+ * All registered strategies. The resolver picks from this list; callers that
+ * need exhaustive enumeration (e.g. tests, Storybook knobs) can import this
+ * constant directly.
+ */
+const ALL_A11Y_STRATEGIES = [
+  baselineStrategy,
+  webkitVoiceOverStrategy,
+  firefoxNvdaStrategy,
+];
+/**
+ * Picks an `A11yTreeStrategy` from the runtime environment and returns the
+ * full `A11yStrategyResolution` including confidence and a reason string.
+ *
+ * ## Browser-engine detection
+ *
+ * AT cannot be detected from JS (user privacy). We branch on *browser engine*
+ * as a coarse proxy for the most likely AT pairing on each platform:
+ *
+ * | Engine    | Assumed AT                   | Confidence              |
+ * |-----------|------------------------------|-------------------------|
+ * | WebKit    | VoiceOver (macOS/iOS)        | medium on Apple, low elsewhere |
+ * | Gecko     | NVDA (Win), Orca (Linux)     | medium on Win32, low elsewhere |
+ * | Chromium  | JAWS / NVDA / TalkBack       | high on non-Apple, medium on Apple |
+ *
+ * An explicit `data-a11y-strategy` attribute on the host element is always
+ * treated as `high` confidence (known override). If the override value does
+ * not match any registered strategy name, the resolver falls back to baseline
+ * with `low` confidence and logs an actionable warning.
+ *
+ * @param {HTMLElement} [host] - The component host element. When provided, its
+ *   `data-a11y-strategy` attribute is checked first.
+ * @returns {A11yStrategyResolution} The resolved strategy with confidence and reason.
+ */
+function resolveStrategyDetailed(host) {
+  var _a, _b;
+  // Explicit override takes precedence over UA detection.
+  const override = (_a = host === null || host === void 0 ? void 0 : host.getAttribute('data-a11y-strategy')) !== null && _a !== void 0 ? _a : null;
+  if (override) {
+    const found = ALL_A11Y_STRATEGIES.find((s) => s.name === override);
+    if (found) {
+      return {
+        strategy: found,
+        confidence: 'high',
+        reason: `explicit override via data-a11y-strategy="${override}"`,
+      };
+    }
+    // Unknown override name — warn and fall back to baseline.
+    return {
+      strategy: baselineStrategy,
+      confidence: 'low',
+      reason: `unknown data-a11y-strategy="${override}"; known strategies: ${ALL_A11Y_STRATEGIES.map((s) => s.name).join(', ')}. Falling back to baseline.`,
+    };
+  }
+  // Read the runtime navigator explicitly from `globalThis` (not the bare
+  // `navigator` identifier, which build tooling may substitute). Delegate the
+  // pure UA→strategy mapping to `resolveStrategyFromEnv` so it can be unit
+  // tested deterministically without mocking globals.
+  const nav = globalThis.navigator;
+  return resolveStrategyFromEnv(nav === null || nav === void 0 ? void 0 : nav.userAgent, (_b = nav === null || nav === void 0 ? void 0 : nav.platform) !== null && _b !== void 0 ? _b : '');
+}
+/**
+ * Pure UA→strategy mapping. Separated from `resolveStrategyDetailed` so the
+ * browser-engine detection table can be unit tested deterministically by
+ * passing explicit `userAgent` / `platform` values instead of mocking the
+ * global `navigator` (which build/test tooling may sandbox).
+ *
+ * @param {string | undefined} userAgent - The `navigator.userAgent` string, or
+ *   `undefined` for an SSR / non-browser environment.
+ * @param {string} platform - The `navigator.platform` string (empty string when
+ *   unavailable).
+ * @returns {A11yStrategyResolution} The resolved strategy with confidence and reason.
+ */
+function resolveStrategyFromEnv(userAgent, platform) {
+  // SSR / non-browser environment: no UA available.
+  if (userAgent === undefined) {
+    return {
+      strategy: baselineStrategy,
+      confidence: 'medium',
+      reason: 'no navigator (SSR or non-browser environment); baseline assumed',
+    };
+  }
+  const ua = userAgent;
+  // Order matters: Safari UA contains "Safari" but Chrome UA also does.
+  if (/\bFirefox\//.test(ua)) {
+    // Firefox + NVDA is the canonical pairing on Windows; on other
+    // platforms (macOS VoiceOver, Linux Orca, Windows JAWS) this is a
+    // probabilistic guess.
+    const isWindows = /Win/i.test(platform);
+    return {
+      strategy: firefoxNvdaStrategy,
+      confidence: isWindows ? 'medium' : 'low',
+      reason: isWindows
+        ? 'Firefox on Windows — assumed NVDA (most common pairing on Win32)'
+        : 'Firefox on non-Windows platform — AT pairing is a guess (may be Orca, VoiceOver, or JAWS)',
+    };
+  }
+  if (/^((?!chrome|android).)*safari/i.test(ua)) {
+    const isApple = /Mac|iPhone|iPad|iPod/i.test(platform);
+    return {
+      strategy: webkitVoiceOverStrategy,
+      confidence: isApple ? 'medium' : 'low',
+      reason: isApple
+        ? 'WebKit on Apple platform — assumed VoiceOver'
+        : 'WebKit on non-Apple platform — AT pairing is a guess',
+    };
+  }
+  // Chromium (Edge/Chrome). On macOS, Chromium routes through VoiceOver's
+  // accessibility tree; baseline covers most users but VoiceOver quirks may
+  // surface. Surfaced as medium confidence so the override path stays
+  // discoverable.
+  const onApple = /Mac|iPhone|iPad|iPod/i.test(platform);
+  return {
+    strategy: baselineStrategy,
+    confidence: onApple ? 'medium' : 'high',
+    reason: onApple
+      ? 'Chromium on Apple platform — VoiceOver may diverge from Chromium baseline'
+      : 'Chromium on non-Apple platform — baseline is the expected AT mapping',
+  };
+}
+/**
+ * Convenience wrapper for callers that only need the resolved strategy.
+ * Equivalent to `resolveStrategyDetailed(host).strategy` but additionally
+ * emits a **dev-mode console warning** for `low`-confidence resolutions,
+ * pointing engineers at the `data-a11y-strategy` override mechanism.
+ *
+ * The warning is rate-limited per `(strategyName, reason)` tuple to avoid
+ * log spam on every render cycle.
+ *
+ * @param {HTMLElement} [host] - The component host element (optional). Used for
+ *   the `data-a11y-strategy` override check.
+ * @returns {A11yTreeStrategy} The resolved strategy.
+ */
+function resolveStrategy(host) {
+  const resolution = resolveStrategyDetailed(host);
+  if (resolution.confidence === 'low') {
+    warnOnce(resolution.strategy.name, resolution.reason);
+  }
+  return resolution.strategy;
+}
+const warnedKeys = new Set();
+/**
+ * Emit a console.warn once per (strategy, reason) tuple. Suppressed in
+ * production builds and when `console` is unavailable (SSR).
+ *
+ * @param {string} strategyName - Name of the resolved strategy.
+ * @param {string} reason - Human-readable reason for the resolution.
+ * @internal
+ */
+function warnOnce(strategyName, reason) {
+  var _a, _b;
+  if (typeof console === 'undefined')
+    return;
+  // Only warn in dev mode. Production builds set NODE_ENV=production;
+  // the guard below also handles minified bundles where `process` may
+  // be undefined.
+  const env = (_b = (_a = globalThis.process) === null || _a === void 0 ? void 0 : _a.env) === null || _b === void 0 ? void 0 : _b.NODE_ENV;
+  if (env === 'production')
+    return;
+  const key = `${strategyName}::${reason}`;
+  if (warnedKeys.has(key))
+    return;
+  warnedKeys.add(key);
+  console.warn(`[vega a11y-tree] Low-confidence strategy resolution: using "${strategyName}". ` +
+    `Reason: ${reason}. ` +
+    `Pin via data-a11y-strategy="<strategy-name>" to silence this warning ` +
+    `when you know the correct AT pairing. ` +
+    `Known strategies: ${ALL_A11Y_STRATEGIES.map((s) => s.name).join(', ')}.`);
+}
+
+/**
+ * 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);
+ * ```
+ */
+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;
+}
+
+var __decorate$1 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * Generic A11y Tree slimmer.
+ *
+ * Hooks `componentDidRender` and projects the component's semantic A11y
+ * Tree onto its shadow DOM using the strategy resolved for the current
+ * browser engine.
+ *
+ * ## Opt-in steps for a component
+ *
+ * 1. Tag render targets with `data-a11y-id="<stable-id>"` in the renderer.
+ * 2. Author a `build<Component>A11yTree(host)` function (see
+ *    `a11y-node-dto.ts` for the DTO helpers that make this ergonomic).
+ * 3. Inject this slimmer with `@InjectVegaSlimmer()`:
+ *
+ * ```ts
+ * @InjectVegaSlimmer()
+ * protected a11yTreeSlimmer = new A11yTreeSlimmer<HTMLVegaFooElement>(
+ *   host => buildFooA11yTree({ title: host.title, description: host.description }),
+ * );
+ * ```
+ *
+ * The slimmer handles strategy selection, patch application, and cleanup
+ * on every subsequent render.
+ *
+ * @template T - The concrete `HTMLElement` subtype for the component host.
+ */
+class A11yTreeSlimmer extends VegaSlimmer {
+  constructor(buildA11yTree) {
+    super();
+    this.buildA11yTree = buildA11yTree;
+  }
+  /**
+   * Called by Stencil after each render. Projects the semantic A11y Tree
+   * onto the shadow DOM via the resolved browser-engine strategy.
+   */
+  projectA11yTree() {
+    const tree = this.buildA11yTree(this.host);
+    applyA11yTree(tree, this.host);
+  }
+}
+__decorate$1([
+  MapToComponentField()
+], A11yTreeSlimmer.prototype, "host", void 0);
+__decorate$1([
+  MapToComponentMethod('componentDidRender')
+], A11yTreeSlimmer.prototype, "projectA11yTree", null);
+
+/**
+ * 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.
+ */
+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 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.
+ */
+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.
+ */
+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(),
+    };
+  }
+}
+
+/**
+ * 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.
+ */
+function buildSectionTitleA11yTree(args) {
+  var _a;
+  const children = [];
+  // Only add heading if titleText is provided; avoid empty heading elements
+  // that cause cross-browser inconsistencies (Chrome skips them, Firefox may
+  // announce an empty group). The A11y Tree projection (via strategy) onto
+  // shadow DOM handles all ARIA semantics; no host-level ARIA is used.
+  if (args.titleText) {
+    children.push(new A11yHeadingNode('st-heading', {
+      level: (_a = args.headingLevel) !== null && _a !== void 0 ? _a : 2,
+    }).toA11yNode());
+  }
+  if (args.icon) {
+    children.push(new A11yIconNode('st-icon').toA11yNode());
+  }
+  return {
+    id: 'st-root',
+    role: 'none',
+    children,
+  };
+}
+
 const vegaSectionTitleCss = ":host{display:block}.section-title-text{color:rgba(var(--v-text-primary, 32, 54, 69, 1));font-family:\"Inter\", sans-serif;font-size:20px;font-weight:700;line-height:28px;letter-spacing:0px}@media screen and (min-width: 768px) and (max-width: 1023px){.section-title-text{font-family:\"Inter\", sans-serif;font-size:20px;font-weight:700;line-height:28px;letter-spacing:0px}}@media screen and (min-width: 1024px) and (max-width: 1439px){.section-title-text{font-family:\"Inter\", sans-serif;font-size:20px;font-weight:700;line-height:28px;letter-spacing:0px}}@media screen and (min-width: 1440px) and (max-width: 9999px){.section-title-text{font-family:\"Inter\", sans-serif;font-size:20px;font-weight:700;line-height:28px;letter-spacing:0px}}.section-title-description{font-family:\"Inter\", sans-serif;font-size:18px;font-weight:500;line-height:28px;letter-spacing:0px;color:rgba(var(--v-text-secondary, 107, 116, 125, 1))}@media screen and (min-width: 768px) and (max-width: 1023px){.section-title-description{font-family:\"Inter\", sans-serif;font-size:16px;font-weight:500;line-height:22px;letter-spacing:0px}}@media screen and (min-width: 1024px) and (max-width: 1439px){.section-title-description{font-family:\"Inter\", sans-serif;font-size:16px;font-weight:500;line-height:22px;letter-spacing:0px}}@media screen and (min-width: 1440px) and (max-width: 9999px){.section-title-description{font-family:\"Inter\", sans-serif;font-size:16px;font-weight:500;line-height:22px;letter-spacing:0px}}.section-title-icon-container{margin-top:4px}.right-icon-container{display:inline-block;margin-left:8px;margin-top:4px;vertical-align:middle}.section-title-small .section-title-text{font-family:\"Inter\", sans-serif;font-size:18px;font-weight:700;line-height:25px;letter-spacing:0px}@media screen and (min-width: 768px) and (max-width: 1023px){.section-title-small .section-title-text{font-family:\"Inter\", sans-serif;font-size:18px;font-weight:700;line-height:25px;letter-spacing:0px}}@media screen and (min-width: 1024px) and (max-width: 1439px){.section-title-small .section-title-text{font-family:\"Inter\", sans-serif;font-size:18px;font-weight:700;line-height:25px;letter-spacing:0px}}@media screen and (min-width: 1440px) and (max-width: 9999px){.section-title-small .section-title-text{font-family:\"Inter\", sans-serif;font-size:18px;font-weight:700;line-height:25px;letter-spacing:0px}}";
 
 var __decorate = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
@@ -80,6 +948,18 @@ const VegaSectionTitle = class {
     this.globalSlimmers = {};
     this.renderer = new VegaSectionTitleRenderer();
     this.vegaComponentUsageRuntimeMetricsSlimmer = new VegaComponentUsageRuntimeMetricsSlimmer();
+    /**
+     * 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).
+     */
+    this.a11yTreeSlimmer = new A11yTreeSlimmer((host) => buildSectionTitleA11yTree({
+      titleText: host.titleText,
+      icon: host.icon,
+      iconAlign: host.iconAlign,
+    }));
     /**
      * Specifies the text content of the title displayed
      *    within the section title.
@@ -108,8 +988,7 @@ const VegaSectionTitle = class {
     this.size = 'default';
   }
   render() {
-    const ariaLabel = [this.titleText, this.description].filter(Boolean).join(', ');
-    return sanitizeVegaComponent(h(Host, { role: ariaLabel ? 'group' : undefined, "aria-label": ariaLabel || undefined }, this.renderer.render()), this.host);
+    return sanitizeVegaComponent(h(Host, null, this.renderer.render()), this.host);
   }
   get host() { return getElement(this); }
 };
@@ -122,6 +1001,9 @@ __decorate([
 __decorate([
   InjectVegaSlimmer()
 ], VegaSectionTitle.prototype, "vegaComponentUsageRuntimeMetricsSlimmer", void 0);
+__decorate([
+  InjectVegaSlimmer()
+], VegaSectionTitle.prototype, "a11yTreeSlimmer", void 0);
 VegaSectionTitle.style = vegaSectionTitleCss;
 
 export { VegaSectionTitle as vega_section_title };