@heartlandone/vega 2.94.0 → 2.96.0

package/dist/collection/components/vega-rich-text-editor/slimmers/renderers/tools/bullets-numbers/list-keyboard-slimmer.js

@@ -0,0 +1,180 @@
+var __decorate = (this && this.__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;
+};
+import { MapToComponentField, MapToComponentMethod, VegaSlimmer } from 'vega-slimmer/core';
+import { RTETextNode } from '../../../../dto/nodes/text-node';
+import { ListTabIndentHandler } from './helper/list-tab-indent-handler';
+import { ListShiftTabOutdentHandler } from './helper/list-shift-tab-outdent-handler';
+const LIST_TOOLBAR_ITEMS = ['bullets', 'numbers', 'bulletsNumbers'];
+/**
+ * Handles list keyboard shortcuts (Tab/Shift+Tab) for list tooling.
+ */
+export class ListKeyboardSlimmer extends VegaSlimmer {
+  constructor() {
+    super(...arguments);
+    this.isKeyboardListenerBound = false;
+    this.listTabIndentHandler = new ListTabIndentHandler();
+    this.listShiftTabOutdentHandler = new ListShiftTabOutdentHandler();
+    // Keyboard action execution
+    /**
+     * Handle Tab and Shift+Tab list keyboard interactions.
+     *
+     * @param {KeyboardEvent} e - Keyboard event to process.
+     * @returns {void}
+     */
+    this.handleListKeyboardAction = (e) => {
+      if (e.key !== 'Tab') {
+        return;
+      }
+      if (this.hasNonShiftModifierForTab(e)) {
+        return;
+      }
+      const selectedBlocks = this.selectionController.getSelectedBlocks();
+      const currentRange = this.selectionController.getCurrentRange().clone();
+      if (e.shiftKey) {
+        const selectionBoundaries = this.listShiftTabOutdentHandler.execute(selectedBlocks);
+        if (selectionBoundaries) {
+          e.preventDefault();
+          void this.valueController.flushChanges(this.value).then(() => {
+            this.restoreListSelection(selectionBoundaries, currentRange.startNode instanceof RTETextNode ? currentRange.startNode : null, currentRange.endNode instanceof RTETextNode ? currentRange.endNode : null, currentRange.startOffset, currentRange.endOffset);
+          });
+        }
+        return;
+      }
+      const selectionBoundaries = this.listTabIndentHandler.execute(selectedBlocks);
+      if (!selectionBoundaries) {
+        return;
+      }
+      e.preventDefault();
+      void this.valueController.flushChanges(this.value).then(() => {
+        this.restoreListSelection(selectionBoundaries, currentRange.startNode instanceof RTETextNode ? currentRange.startNode : null, currentRange.endNode instanceof RTETextNode ? currentRange.endNode : null, currentRange.startOffset, currentRange.endOffset);
+      });
+    };
+  }
+  // Listener lifecycle and gating
+  /**
+   * @inheritDoc
+   */
+  disconnectedCallback() {
+    this.removeListKeyboardListener();
+  }
+  /**
+   * @inheritDoc
+   */
+  componentDidLoad() {
+    this.syncListKeyboardListener();
+  }
+  /**
+   * Re-sync keyboard listener when toolbarItems prop changes at runtime,
+   * ensuring list shortcuts are bound/unbound as tools are added/removed.
+   */
+  watchToolbarItems() {
+    this.syncListKeyboardListener();
+  }
+  /**
+   * Synchronize the DOM keydown listener with the configured toolbar items.
+   */
+  syncListKeyboardListener() {
+    if (this.hasListToolbarConfigured()) {
+      this.addListKeyboardListener();
+      return;
+    }
+    this.removeListKeyboardListener();
+  }
+  /**
+   * Determine whether any list keyboard controls are enabled in the toolbar.
+   *
+   * @returns {boolean} True when any list toolbar item is configured.
+   */
+  hasListToolbarConfigured() {
+    const flatToolbarItems = this.toolbarItems.flat();
+    return flatToolbarItems.some((item) => LIST_TOOLBAR_ITEMS.includes(item));
+  }
+  /**
+   * Attach the keydown listener to the current editable element when available.
+   * Handles element ref changes by rebinding when the target element differs.
+   */
+  addListKeyboardListener() {
+    const editableElement = this.vegaRichTextEditorRenderer.getRTEEditableElementRef();
+    if (this.isKeyboardListenerBound && this.boundEditableElement === editableElement) {
+      return;
+    }
+    if (this.isKeyboardListenerBound) {
+      this.removeListKeyboardListener();
+    }
+    if (!editableElement) {
+      return;
+    }
+    editableElement.addEventListener('keydown', this.handleListKeyboardAction);
+    this.boundEditableElement = editableElement;
+    this.isKeyboardListenerBound = true;
+  }
+  /**
+   * Detach the keydown listener from the previously bound editable element.
+   */
+  removeListKeyboardListener() {
+    if (!this.isKeyboardListenerBound || !this.boundEditableElement) {
+      return;
+    }
+    this.boundEditableElement.removeEventListener('keydown', this.handleListKeyboardAction);
+    this.boundEditableElement = null;
+    this.isKeyboardListenerBound = false;
+  }
+  /**
+   * 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.
+   */
+  hasNonShiftModifierForTab(e) {
+    return e.altKey || e.ctrlKey || e.metaKey || e.getModifierState('AltGraph');
+  }
+  /**
+   * 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}
+   */
+  restoreListSelection(selectionBoundaries, preferredStartNode, preferredEndNode, startOffset, endOffset) {
+    var _a, _b, _c, _d;
+    const firstBoundary = (_a = selectionBoundaries.find(Boolean)) !== null && _a !== void 0 ? _a : null;
+    const lastBoundary = (_b = [...selectionBoundaries].reverse().find(Boolean)) !== null && _b !== void 0 ? _b : null;
+    const firstNode = (_c = preferredStartNode !== null && preferredStartNode !== void 0 ? preferredStartNode : firstBoundary === null || firstBoundary === void 0 ? void 0 : firstBoundary[0]) !== null && _c !== void 0 ? _c : null;
+    const lastNode = (_d = preferredEndNode !== null && preferredEndNode !== void 0 ? preferredEndNode : lastBoundary === null || lastBoundary === void 0 ? void 0 : lastBoundary[1]) !== null && _d !== void 0 ? _d : null;
+    if (!firstNode || !lastNode) {
+      return;
+    }
+    this.selectionController.enqueueSelectionRangeFutureState(firstNode, Math.min(startOffset, firstNode.getRangeEndOffset()), lastNode, Math.min(endOffset, lastNode.getRangeEndOffset()), true);
+  }
+}
+__decorate([
+  MapToComponentField()
+], ListKeyboardSlimmer.prototype, "selectionController", void 0);
+__decorate([
+  MapToComponentField()
+], ListKeyboardSlimmer.prototype, "valueController", void 0);
+__decorate([
+  MapToComponentField()
+], ListKeyboardSlimmer.prototype, "value", void 0);
+__decorate([
+  MapToComponentField()
+], ListKeyboardSlimmer.prototype, "toolbarItems", void 0);
+__decorate([
+  MapToComponentField()
+], ListKeyboardSlimmer.prototype, "vegaRichTextEditorRenderer", void 0);
+__decorate([
+  MapToComponentMethod('disconnectedCallback')
+], ListKeyboardSlimmer.prototype, "disconnectedCallback", null);
+__decorate([
+  MapToComponentMethod('componentDidLoad')
+], ListKeyboardSlimmer.prototype, "componentDidLoad", null);
+__decorate([
+  MapToComponentMethod('watchToolbarItems')
+], ListKeyboardSlimmer.prototype, "watchToolbarItems", null);

package/dist/collection/components/vega-section-title/slimmers/a11y-tree/build-section-title-a11y-tree.js

@@ -0,0 +1,54 @@
+import { A11yHeadingNode, A11yIconNode } from '../../../../helpers/a11y-tree/a11y-node-dto';
+/**
+ * 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 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,
+  };
+}

package/dist/collection/components/vega-section-title/slimmers/renderers/vega-section-title-renderer.js

@@ -8,13 +8,13 @@ import { h } from '@stencil/core';
 import { MapToComponentField, VegaSlimmer } from 'vega-slimmer/core';
 export 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" },
@@ -23,7 +23,7 @@ export 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() {
@@ -31,7 +31,7 @@ export 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" }));

package/dist/collection/components/vega-section-title/vega-section-title.js

@@ -9,6 +9,8 @@ import { sanitizeVegaComponent } from '../../utils/component';
 import { InjectVegaGlobalSlimmer, InjectVegaSlimmer } from 'vega-slimmer/core';
 import { VegaSectionTitleRenderer } from './slimmers/renderers/vega-section-title-renderer';
 import { VegaComponentUsageRuntimeMetricsSlimmer } from '../../helpers/slimmers/component-usage-runtime-metrics';
+import { A11yTreeSlimmer } from '../../helpers/slimmers/a11y-tree-slimmer';
+import { buildSectionTitleA11yTree } from './slimmers/a11y-tree/build-section-title-a11y-tree';
 /**
  * @vegaVersion 2.1.0
  */
@@ -17,6 +19,18 @@ export class VegaSectionTitle {
     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.
@@ -45,8 +59,7 @@ export class VegaSectionTitle {
     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);
   }
   static get is() { return "vega-section-title"; }
   static get encapsulation() { return "shadow"; }
@@ -208,3 +221,6 @@ __decorate([
 __decorate([
   InjectVegaSlimmer()
 ], VegaSectionTitle.prototype, "vegaComponentUsageRuntimeMetricsSlimmer", void 0);
+__decorate([
+  InjectVegaSlimmer()
+], VegaSectionTitle.prototype, "a11yTreeSlimmer", void 0);

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

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