@heartlandone/vega 2.94.0 → 2.96.0

package/dist/types/components/vega-rich-text-editor/dto/action-handle-strategies/modify-content-strategies/list-transform-to-paragraph-strategy.d.ts

@@ -1,14 +1,110 @@
 import { TransformParagraphAction } from '../../actions/transform-paragraph-action';
-import type { RTEListBlock } from '../../blocks/list-block';
-import { ActionHandleStrategy } from '../action-handle-strategy.abstract';
+import { RTEListBlock } from '../../blocks/list-block';
+import { ListAnnotationStrategy } from './list-annotation-strategy.abstract';
 /**
  * Convert the selected list block to paragraph strategy.
  */
-export declare class ListTransformToParagraphStrategy extends ActionHandleStrategy<TransformParagraphAction, RTEListBlock> {
+export declare class ListTransformToParagraphStrategy extends ListAnnotationStrategy<TransformParagraphAction, RTEListBlock> {
   /**
    * @inheritDoc
    */
   protected handleAction(action: TransformParagraphAction, target: RTEListBlock): void;
+  /**
+   * Ensure the action is applied to the first selected item's parent list and
+   * every selected item belongs to the same editor content.
+   *
+   * @param {RTEListItemBlock[][]} selectedSegments - Normalized selection segments.
+   * @param {RTEListBlock} target - List receiving the transform action.
+   * @returns {boolean} Whether the target and root content are consistent.
+   */
+  private hasConsistentTargetAndRoot;
+  /**
+   * Capture selected text nodes in document order before reverse-order tree
+   * mutations move them into paragraphs.
+   *
+   * @param {RTEListItemBlock[][]} selectedSegments - Normalized selection segments.
+   */
+  private syncSelection;
+  /**
+   * Transform one normalized segment without recursively dispatching another
+   * flushable action.
+   *
+   * @param {RTEListItemBlock[]} segment - Contiguous items sharing one parent list.
+   */
+  private transformSegment;
+  /**
+   * Handle the case where the target list is at root level (parent is VegaRTEContent).
+   *
+   * @param {TransformParagraphAction} action - The paragraph transform action.
+   * @param {RTEListBlock} target - The root list being transformed.
+   */
+  private handleRootListCase;
+  /**
+   * Handle the case where the target list is nested (parent is RTEListItemBlock).
+   *
+   * Algorithm:
+   * 1. Build the ancestor path from root list down to the target nested list.
+   * 2. At each level on the path, collect "trailing" items (items after the ancestor).
+   * 3. Trim each list along the path to keep only the "before" portion.
+   * 4. Collect trailing items from all levels + selected item's own nestList children.
+   * 5. Group trailing items into lists by consecutive type.
+   * 6. Insert into content: [before-root-list, paragraphs, ...after-lists].
+   *
+   * @param {TransformParagraphAction} action - The paragraph transform action.
+   * @param {RTEListBlock} target - The nested list being transformed.
+   */
+  private handleNestedListCase;
+  /**
+   * Normalize selected items into document order and split them into contiguous
+   * segments that share the same immediate parent list. Unlike Shift+Tab, the
+   * toolbar action keeps selected descendants so every selected item becomes a
+   * paragraph.
+   *
+   * @param {RTEBlock[]} selectedBlocks - Raw selected blocks.
+   * @returns {RTEListItemBlock[][]} Parent-based contiguous selection segments.
+   */
+  private getSelectedSegments;
+  /**
+   * Resolve a list item's structural document path, including the positions of
+   * root lists, owning list items, nested lists, and the item itself.
+   *
+   * @param {RTEListItemBlock} item - Selected list item.
+   * @returns {number[] | null} Structural path, or null for a detached item.
+   */
+  private getStructuralPath;
+  /**
+   * Resolve a root list's path through zero or more HTML containers to the
+   * editor content.
+   *
+   * @param {RTEListBlock} rootList - List whose parent is a content container.
+   * @returns {number[] | null} Container path, or null for detached/cyclic ownership.
+   */
+  private getContainerPath;
+  /**
+   * Compare two structural paths in document order.
+   *
+   * @param {number[]} firstPath - First structural path.
+   * @param {number[]} secondPath - Second structural path.
+   * @returns {number} Relative document order.
+   */
+  private compareStructuralPaths;
+  /**
+   * Append a list to an operation-local block sequence, merging only with the
+   * immediately preceding same-type list in that sequence.
+   *
+   * @param {RTEBlock[]} blocks - Operation-local output sequence.
+   * @param {RTEListBlock} list - List to append or merge.
+   */
+  private appendListBlock;
+  /**
+   * Create a list through the content factory and retain the source list's
+   * container annotations when a structural split requires a new list block.
+   *
+   * @param {VegaRTEContent} rootContent - Editor content that owns the factory.
+   * @param {RTEListBlock} source - List whose type and annotations should be retained.
+   * @returns {RTEListBlock} Newly created list shell.
+   */
+  private createListFromSource;
   /**
    * Converts a RTEListItemBlock to a RTETextBlock representing a paragraph.
    *

package/dist/types/components/vega-rich-text-editor/dto/action-handle-strategies/modify-content-strategies/list-unnest-items-strategy.d.ts

@@ -0,0 +1,22 @@
+import { UnnestListItemsAction } from '../../actions/unnest-list-items-action';
+import { RTEListBlock } from '../../blocks/list-block';
+import { AbstractListItemsStrategy } from './list-items-strategy.abstract';
+/**
+ * Promote selected nested list items one level up.
+ */
+export declare class ListUnnestItemsStrategy extends AbstractListItemsStrategy<UnnestListItemsAction> {
+  /**
+   * @inheritDoc
+   */
+  protected handleAction(action: UnnestListItemsAction, target: RTEListBlock): void;
+  /**
+   * Collect and remove nestList entries that appear after the given target list
+   * in the parent item's nestList array. These trailing entries need to be
+   * transferred to the unnested item to preserve visual document order.
+   *
+   * @param {RTEListItemBlock} parentListItem - The list item owning the nestList.
+   * @param {RTEListBlock} target - The list being removed (used as the reference point).
+   * @returns {RTEListBlock[]} The trailing nestList entries (already removed from parentListItem).
+   */
+  private collectTrailingNestLists;
+}

package/dist/types/components/vega-rich-text-editor/dto/actions/modify-content-action.abstract.d.ts

@@ -15,6 +15,8 @@ export declare enum ModifyContentActionType {
   'LINE_BREAK_MULTIPLE_BLOCKS' = "LINE_BREAK_MULTIPLE_BLOCKS",
   'TRANSFORM_LIST_BLOCK' = "TRANSFORM_LIST_BLOCK",
   'TRANSFORM_PARAGRAPH_BLOCK' = "TRANSFORM_PARAGRAPH_BLOCK",
+  'NEST_LIST_ITEMS' = "NEST_LIST_ITEMS",
+  'UNNEST_LIST_ITEMS' = "UNNEST_LIST_ITEMS",
   'DELETE_BLOCK_CONTENT' = "DELETE_BLOCK_CONTENT",
   'INSERT_IMAGE_TO_BLOCK' = "INSERT_IMAGE_TO_BLOCK",
   'UPDATE_IMAGE_NODE_URL' = "UPDATE_IMAGE_NODE_URL",

package/dist/types/components/vega-rich-text-editor/dto/actions/nest-list-items-action.d.ts

@@ -0,0 +1,11 @@
+import { RTEListItemBlock } from '../blocks/list-item-block';
+import { ModifyContentAction, ModifyContentActionType } from './modify-content-action.abstract';
+/**
+ * Action to nest the selected list items under the previous sibling.
+ */
+export declare class NestListItemsAction extends ModifyContentAction {
+  readonly type: ModifyContentActionType;
+  isFlushable: boolean;
+  selectedBlocks: RTEListItemBlock[];
+  constructor(selectedBlocks: RTEListItemBlock[]);
+}

package/dist/types/components/vega-rich-text-editor/dto/actions/unnest-list-items-action.d.ts

@@ -0,0 +1,11 @@
+import { RTEListItemBlock } from '../blocks/list-item-block';
+import { ModifyContentAction, ModifyContentActionType } from './modify-content-action.abstract';
+/**
+ * Action to promote the selected nested list items one level up.
+ */
+export declare class UnnestListItemsAction extends ModifyContentAction {
+  readonly type: ModifyContentActionType;
+  isFlushable: boolean;
+  selectedBlocks: RTEListItemBlock[];
+  constructor(selectedBlocks: RTEListItemBlock[]);
+}

package/dist/types/components/vega-rich-text-editor/dto/annotations/list-annotation.d.ts

@@ -12,6 +12,14 @@ export declare class ListAnnotation extends BlockAnnotation {
    * @returns {AnnotationStyle} The default styles.
    */
   static getDefaultStyles(): AnnotationStyle;
+  /**
+   * Get the default standalone styles for a list block's item marker
+   * (`li::marker`). Capping the marker font-size keeps bullets/numbers
+   * at a normal size when list items are styled as title/subtitle.
+   *
+   * @returns {AnnotationStyle} The default marker styles.
+   */
+  static getDefaultMarkerStyles(): AnnotationStyle;
   /**
    * @inheritDoc
    */

package/dist/types/components/vega-rich-text-editor/dto/blocks/list-block.d.ts

@@ -7,7 +7,12 @@ import { Nullable } from '../../../../types/general';
 import { RTEHtmlBlock } from './html-block';
 export declare type RTEListBlockTagType = 'ol' | 'ul';
 /**
- * List block
+ * List block.
+ *
+ * Bidirectional nesting contract:
+ * - Every child list item must have item.parent === this list block.
+ * - If this list block is nested, its parent must be a list item and that
+ *   list item keeps this block in listItem.nestList.
  */
 export declare class RTEListBlock extends RTEBlock<VegaRTEContent | RTEListItemBlock | RTEHtmlBlock, RTEListItemBlock> {
   static readonly dtoName: string;

package/dist/types/components/vega-rich-text-editor/dto/blocks/list-item-block.d.ts

@@ -3,7 +3,11 @@ import { RTETextNode } from '../nodes/text-node';
 import { RTEListBlock } from './list-block';
 import { RTETextBlock } from './text-block';
 /**
- * List item block
+ * List item block.
+ *
+ * Bidirectional nesting contract:
+ * - nestList stores nested list blocks owned by this list item.
+ * - Every nested list block must have listBlock.parent === this list item.
  */
 export declare class RTEListItemBlock extends RTETextBlock {
   static readonly dtoName: string;

package/dist/types/components/vega-rich-text-editor/dto/content-state.d.ts

@@ -86,10 +86,10 @@ export declare class VegaRTEContent {
   /**
    * Convert text to list.
    *
-   * @param {RTETextBlock} block - block
+   * @param {RTETextBlock | RTEListItemBlock} block - Block to convert or rebuild.
    * @returns {RTEListItemBlock} list item block dto.
    */
-  toListItem(block: RTETextBlock): RTEListItemBlock;
+  toListItem(block: RTETextBlock | RTEListItemBlock): RTEListItemBlock;
   /**
    * create list.
    *

package/dist/types/components/vega-rich-text-editor/dto/renderers/blocks/list-block-renderer.d.ts

@@ -3,6 +3,8 @@ import { RTEListBlock } from '../../blocks/list-block';
 import { RTERenderContext } from '../../../interface';
 declare class RTEListBlockRenderer extends RTEBlockRenderer {
   render(block: RTEListBlock, renderContext: RTERenderContext): HTMLElement;
+  private resolveListMarker;
+  private getListDepth;
 }
 declare const _default: RTEListBlockRenderer;
 export default _default;

package/dist/types/components/vega-rich-text-editor/dto/renderers/blocks/list-item-block-renderer.d.ts

@@ -3,6 +3,14 @@ import { RTERenderContext } from '../../../interface';
 import { RTEBlockTextNodesRenderer } from './block-text-nodes-renderer.abstract';
 declare class RTEListItemBlockRenderer extends RTEBlockTextNodesRenderer {
   render(block: RTEListItemBlock, renderContext: RTERenderContext): HTMLElement;
+  /**
+   * Include structural ownership and direct nested-list identity in the key so
+   * list mutations recreate the li when its rendered child shape changes.
+   *
+   * @param {RTEListItemBlock} block - List item being rendered.
+   * @returns {string} Structure-aware render key.
+   */
+  private getRenderKey;
   private renderChildren;
 }
 declare const _default: RTEListItemBlockRenderer;

package/dist/types/components/vega-rich-text-editor/extensions/table/annotation-handler/table-annotation-handler-base.d.ts

@@ -5,6 +5,13 @@ import { VegaRTETableBorderType } from '../annotations/table-annotation';
  * Base class for table annotation handlers with common extraction methods.
  */
 export declare abstract class TableAnnotationHandlerBase extends AnnotationGeneratorStrategyAbstract {
+  /**
+   * CSS border-width keywords. These are produced as serialization artifacts when a
+   * shorthand border without an explicit width is round-tripped (e.g. `border: none`
+   * expands to `border-width: medium`). They are not valid numeric dimensions for the
+   * table/cell properties "Weight" field, so they are normalized away on import.
+   */
+  private static readonly BORDER_WIDTH_KEYWORDS;
   /**
    * Extract background color from element.
    *
@@ -19,6 +26,17 @@ export declare abstract class TableAnnotationHandlerBase extends AnnotationGener
    * @returns {Nullable<VegaRTETableBorderType>} Border properties.
    */
   protected getBorder(element: HTMLElement): Nullable<VegaRTETableBorderType>;
+  /**
+   * Normalize a border width read from the DOM, dropping the `initial` value and the
+   * CSS keyword widths (`thin`/`medium`/`thick`). Those only appear as serialization
+   * artifacts of shorthand borders (e.g. `border: none` → `border-width: medium`) and
+   * are not valid numeric dimensions, so leaving them in would populate the properties
+   * "Weight" field with an invalid value and block the whole form from saving.
+   *
+   * @param {string} borderWidth - The raw border width read from the element style.
+   * @returns {string} The normalized border width (empty string when it is a keyword).
+   */
+  protected normalizeBorderWidth(borderWidth: string): string;
   /**
    * Extract width from element.
    *

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

@@ -1,13 +1,21 @@
 import { ToolbarInternalButtonConfig } from '../toolbar-button-slimmer.abstract';
 import { VegaRichTextEditor } from '../../../../vega-rich-text-editor';
+import { ListKeyboardSlimmer } from './list-keyboard-slimmer';
 import { BulletsToolbarButtonSlimmer } from './bullets-toolbar-button-slimmer';
 import { NumbersToolbarButtonSlimmer } from './numbers-toolbar-button-slimmer';
 import { VisualModeToolbarButtonSlimmer } from '../visual-mode-toolbar-button-slimmer.abstract';
 export declare class BulletsNumbersToolbarButtonSlimmer extends VisualModeToolbarButtonSlimmer {
   protected readonly selectionController: VegaRichTextEditor['selectionController'];
+  protected readonly valueController: VegaRichTextEditor['valueController'];
+  protected readonly value: VegaRichTextEditor['value'];
+  protected readonly toolbarItems: VegaRichTextEditor['toolbarItems'];
+  protected readonly vegaRichTextEditorRenderer: VegaRichTextEditor['vegaRichTextEditorRenderer'];
   protected readonly bulletsToolbarButtonSlimmer: BulletsToolbarButtonSlimmer;
   protected readonly numbersToolbarButtonSlimmer: NumbersToolbarButtonSlimmer;
+  protected readonly listKeyboardSlimmer: ListKeyboardSlimmer;
   protected popoverRef: HTMLVegaPopoverElement;
+  disconnectedCallback(): void;
+  componentDidLoad(): void;
   componentWillRender(): void;
   constructor();
   protected renderBtnWrapper(renderBtn: (toolbarInternalButton: ToolbarInternalButtonConfig) => HTMLElement): HTMLElement;

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

@@ -0,0 +1,99 @@
+import { Nullable } from '../../../../../../../types/general';
+import { RTEBlock } from '../../../../../dto/blocks/block.abstract';
+import { RTEListItemBlock } from '../../../../../dto/blocks/list-item-block';
+import { RTETextNode } from '../../../../../dto/nodes/text-node';
+/**
+ * Abstract base for list keyboard (Tab / Shift+Tab) handlers.
+ * Provides shared selection-normalization utilities used by both the indent
+ * and outdent concrete handlers.
+ */
+export declare abstract class AbstractListKeyboardHandler {
+  /**
+   * Filter the ordered selection down to only the "root" items —
+   * items whose ancestor is not also present in the selection.
+   *
+   * @param {RTEListItemBlock[]} selection - Ordered selected list items.
+   * @returns {RTEListItemBlock[]} Root items that do not have selected ancestors.
+   */
+  protected getOutdentRoots(selection: RTEListItemBlock[]): RTEListItemBlock[];
+  /**
+   * Check whether a list item has an ancestor that is also selected.
+   *
+   * @param {RTEListItemBlock} item - Item to inspect.
+   * @param {Set<RTEListItemBlock>} selectedItems - Selected items lookup set.
+   * @returns {boolean} True when an ancestor item is selected.
+   */
+  protected hasSelectedAncestor(item: RTEListItemBlock, selectedItems: Set<RTEListItemBlock>): boolean;
+  /**
+   * Split an ordered flat list of items into groups that share the same
+   * parent list and are contiguous siblings.
+   *
+   * @param {RTEListItemBlock[]} selection - Ordered list-item selection.
+   * @returns {RTEListItemBlock[][]} Contiguous parent-based segments.
+   */
+  protected splitSelectionIntoParentSegments(selection: RTEListItemBlock[]): RTEListItemBlock[][];
+  /**
+   * Normalize the selection and split into parent-based contiguous segments.
+   * Returns null when the result is empty.
+   *
+   * @param {RTEBlock[]} selectedBlocks - Raw selected blocks.
+   * @returns {RTEListItemBlock[][] | null} Contiguous segments or null when invalid.
+   */
+  protected normalizeToSegments(selectedBlocks: RTEBlock[]): RTEListItemBlock[][] | null;
+  /**
+   * Return the first and last RTETextNode spanning the provided blocks,
+   * or null when either boundary cannot be resolved.
+   *
+   * @param {RTEBlock[]} blocks - Blocks defining the range boundary.
+   * @returns {Nullable<[RTETextNode, RTETextNode]>} First and last boundary nodes.
+   */
+  protected getSelectionBoundary(blocks: RTEBlock[]): Nullable<[RTETextNode, RTETextNode]>;
+  /**
+   * Normalize the raw selectedBlocks into an ordered list of RTEListItemBlocks,
+   * truncating at the first non-list block.  Returns null when no list items
+   * are present.
+   *
+   * @param {RTEBlock[]} selectedBlocks - Raw selected blocks.
+   * @returns {RTEListItemBlock[] | null} Ordered list items or null.
+   */
+  protected getOrderedListItems(selectedBlocks: RTEBlock[]): RTEListItemBlock[] | null;
+  /**
+   * Collect contiguous selected list items until a non-list block is found.
+   *
+   * @param {RTEBlock[]} selectedBlocks - Raw selected blocks.
+   * @returns {RTEListItemBlock[]} Selected list items up to first non-list block.
+   */
+  protected getSelectedListItemsUntilFirstNonList(selectedBlocks: RTEBlock[]): RTEListItemBlock[];
+  /**
+   * Build a hierarchical index path for a list item in the list tree.
+   *
+   * @param {RTEListItemBlock} item - Item whose tree path is being resolved.
+   * @returns {number[]} Tree index path from root to the item.
+   */
+  protected getTreePath(item: RTEListItemBlock): number[];
+  /**
+   * Compare two list-item tree paths.
+   *
+   * @param {number[]} a - First tree path.
+   * @param {number[]} b - Second tree path.
+   * @returns {number} Negative when a < b, positive when a > b, otherwise 0.
+   */
+  protected compareTreePath(a: number[], b: number[]): number;
+  /**
+   * Check whether a value exposes a children array.
+   *
+   * @param {unknown} entity - Candidate value.
+   * @returns {boolean} True when entity has children array.
+   */
+  protected hasChildren(entity: unknown): entity is {
+    children: unknown[];
+  };
+  /**
+   * Execute the keyboard action for the given selection and return the
+   * resulting selection boundaries, or null when no action was taken.
+   *
+   * @param {RTEBlock[]} selectedBlocks - Currently selected blocks.
+   * @returns {Array<Nullable<[RTETextNode, RTETextNode]>> | null} Selection boundaries after action.
+   */
+  abstract execute(selectedBlocks: RTEBlock[]): Array<Nullable<[RTETextNode, RTETextNode]>> | null;
+}

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

@@ -0,0 +1,15 @@
+import { Nullable } from '../../../../../../../types/general';
+import { RTEBlock } from '../../../../../dto/blocks/block.abstract';
+import { RTETextNode } from '../../../../../dto/nodes/text-node';
+import { AbstractListKeyboardHandler } from './abstract-list-keyboard-handler';
+/**
+ * Handles Shift+Tab key list outdent.
+ * Normalizes the selection, then promotes each segment, either moving nested
+ * items or promoting top-level items to paragraphs.
+ */
+export declare class ListShiftTabOutdentHandler extends AbstractListKeyboardHandler {
+  /**
+   * @inheritDoc
+   */
+  execute(selectedBlocks: RTEBlock[]): Array<Nullable<[RTETextNode, RTETextNode]>> | null;
+}

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

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

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

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

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

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

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

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