@globalpayments/vega 2.96.0 → 2.98.0

package/dist/collection/components/vega-signature-capture/vega-signature-capture.js

@@ -14,12 +14,14 @@ import { WrittenModeRenderer } from './slimmers/written-mode/renderers/written-m
 import { WrittenModeSvgController } from './slimmers/written-mode/controllers/written-mode-svg-controller';
 import { createEventEmitSlimmer, } from '../../helpers/event-manager/slimmers/event-emit-slimmer';
 import { VegaChange } from '../../helpers/event-manager/event-id/vega-event-id';
-import { FormFieldControllerSlimmer } from '../../helpers/slimmers/form-field-controller-slimmer';
+import { FormFieldControllerSlimmer } from '../../helpers/slimmers/form/form-field-controller-slimmer';
 import { RequiredFieldRule } from '../../helpers/validator/rules/required-field-rule';
 import { PageResizeObserverSlimmer } from '../../helpers/slimmers/page-resize-observer-slimmer';
 import { getCurrentBreakpoint } from '../../utils/breakpoints';
 import { TranslationSlimmer } from '../../helpers/slimmers/translation';
 /**
+ * This component displays an area for users to draw their signature, emulating a signature captured on paper.
+ *
  * @vegaVersion 2.19.0
  */
 export class VegaSignatureCapture {
@@ -81,6 +83,14 @@ export class VegaSignatureCapture {
      * @vegaVersion 2.89.0
      */
     this.optional = false;
+    /**
+     * Specifies the name attribute used to identify the form field during data submission.
+     *   It functions identically to the `data-vega-form` attribute but operates at a lower priority.
+     *
+     * @default ''
+     * @vegaVersion 2.97.0
+     */
+    this.name = '';
     /**
      * Determines whether the clear button is displayed.
      *
@@ -264,6 +274,30 @@ export class VegaSignatureCapture {
       "reflect": true,
       "defaultValue": "false"
     },
+    "name": {
+      "type": "string",
+      "mutable": false,
+      "complexType": {
+        "original": "string",
+        "resolved": "string",
+        "references": {}
+      },
+      "required": false,
+      "optional": false,
+      "docs": {
+        "tags": [{
+            "name": "default",
+            "text": "''"
+          }, {
+            "name": "vegaVersion",
+            "text": "2.97.0"
+          }],
+        "text": "Specifies the name attribute used to identify the form field during data submission.\n  It functions identically to the `data-vega-form` attribute but operates at a lower priority."
+      },
+      "attribute": "name",
+      "reflect": true,
+      "defaultValue": "''"
+    },
     "showClearBtn": {
       "type": "boolean",
       "mutable": false,

package/dist/collection/components/vega-skeleton/vega-skeleton.js

@@ -15,6 +15,8 @@ import { VegaSkeletonTableRenderer } from './slimmers/renderers/vega-skeleton-ta
 import { VegaSkeletonRendererManager } from './slimmers/renderers/vega-skeleton-renderer-manager';
 import { VegaSkeletonEllipseRenderer } from './slimmers/renderers/vega-skeleton-ellipse-renderer';
 /**
+ * A Skeleton component is used to create placeholders representing content on a page.
+ *
  * @vegaVersion 2.15.0
  */
 export class VegaSkeleton {

package/dist/collection/components/vega-stepper/vega-stepper.js

@@ -10,7 +10,7 @@ import { MinNumberRule } from '../../helpers/validator/rules/min-number-rule';
 import { sanitizeVegaComponent } from '../../utils/component';
 import { convertToNumber, normalizeNumberByRanger } from '../../utils/number';
 import { InjectVegaGlobalSlimmer, InjectVegaSlimmer } from 'vega-slimmer/core';
-import { FormFieldControllerSlimmer } from '../../helpers/slimmers/form-field-controller-slimmer';
+import { FormFieldControllerSlimmer } from '../../helpers/slimmers/form/form-field-controller-slimmer';
 import { ChildNodesEventPreventSlimmer } from '../../helpers/event-manager/slimmers/child-nodes-event-prevent-slimmer';
 import { DomNodeSubjectObserverFactory } from '../../helpers/change-manager/subject/dom-node-subject/dom-node-subject-observer-factory';
 import { VegaBlur, VegaChange, VegaClick } from '../../helpers/event-manager/event-id/vega-event-id';
@@ -21,6 +21,8 @@ import { arrayToClassString } from '../../utils/ui';
 import { VegaComponentUsageRuntimeMetricsSlimmer } from '../../helpers/slimmers/component-usage-runtime-metrics';
 import { VegaStepperRuntimeMetricsPayloadDefinition } from '../../constants/runtime-metrics-payload-definition/vega-stepper/runtime-metrics-payload-definition';
 /**
+ * The Stepper component allows users to modify a numerical value either by text input or with increment and decrement buttons.
+ *
  * @vegaVersion 1.0.5
  */
 export class VegaStepper {
@@ -101,6 +103,14 @@ export class VegaStepper {
      * @vegaVersion 1.18.0
      */
     this.autoValidation = true;
+    /**
+     * Specifies the name attribute used to identify the form field during data submission.
+     *   It functions identically to the `data-vega-form` attribute but operates at a lower priority.
+     *
+     * @default ''
+     * @vegaVersion 2.97.0
+     */
+    this.name = '';
     /**
      * Specifies the style variant for the stepper buttons.
      *
@@ -184,7 +194,7 @@ export class VegaStepper {
         h("vega-button-circle", { label: "Decrease", showTooltip: false, icon: "minus-sign", ref: (ref) => {
             DomNodeSubjectObserverFactory.addUniqueObserverToNode(ref, VegaClick, () => this.onDecrease());
           }, disabled: this.value <= this.min || this.disabled, size: "small", variant: this.buttonVariant == 'secondary' ? 'secondary' : 'primary' }),
-        h("vega-input", { size: "small", type: "number", max: this.max, min: this.min, value: `${this.value}`, disabled: this.inputDisabled || this.disabled, showClearIcon: false, ref: (el) => {
+        h("vega-input", { size: "small", type: "number", max: this.max, min: this.min, value: `${this.value}`, disabled: this.inputDisabled || this.disabled, name: this.name, showClearIcon: false, ref: (el) => {
             DomNodeSubjectObserverFactory.addUniqueObserverToNode(el, VegaBlur, (input) => this.handleInputBlur(input));
             DomNodeSubjectObserverFactory.addUniqueObserverToNode(el, VegaChange, (input) => this.onChildInputChange(input));
             return (this.inputRef = el);
@@ -394,6 +404,30 @@ export class VegaStepper {
       "reflect": true,
       "defaultValue": "true"
     },
+    "name": {
+      "type": "string",
+      "mutable": false,
+      "complexType": {
+        "original": "string",
+        "resolved": "string",
+        "references": {}
+      },
+      "required": false,
+      "optional": false,
+      "docs": {
+        "tags": [{
+            "name": "default",
+            "text": "''"
+          }, {
+            "name": "vegaVersion",
+            "text": "2.97.0"
+          }],
+        "text": "Specifies the name attribute used to identify the form field during data submission.\n  It functions identically to the `data-vega-form` attribute but operates at a lower priority."
+      },
+      "attribute": "name",
+      "reflect": true,
+      "defaultValue": "''"
+    },
     "buttonVariant": {
       "type": "string",
       "mutable": false,

package/dist/collection/components/vega-tab-group/vega-tab-group.js

@@ -24,6 +24,8 @@ import { VegaClick } from '../../helpers/event-manager/event-id/vega-event-id';
 import { VegaComponentUsageRuntimeMetricsSlimmer } from '../../helpers/slimmers/component-usage-runtime-metrics';
 import { VegaTabGroupRuntimeMetricsPayloadDefinition } from '../../constants/runtime-metrics-payload-definition/vega-tab-group/runtime-metrics-payload-definition';
 /**
+ * The Tab Group component organizes content into separate views, and allows users to switch between them without navigating away from the parent page.
+ *
  * @vegaVersion 1.0.6
  */
 export class VegaTabGroup {

package/dist/collection/components/vega-table/slimmers/controllers/vega-table-column-structure-model-controller.js

@@ -8,7 +8,7 @@ import { MapToComponentField, MapToComponentMethod, VegaSlimmer } from 'vega-sli
 import { ColumnStructureModel } from './dto/column-structure-model';
 /**
  * Controller responsible for building and keeping the ColumnStructureModel in sync
- * with the component's `columns` and `groupColumns` properties.
+ * with data source and template-derived column configuration.
  *
  * This slimmer maps relevant component fields and lifecycle/watch hooks to
  * automatically rebuild the column structure when inputs change.
@@ -36,22 +36,29 @@ export class VegaTableColumnStructureModelController extends VegaSlimmer {
     this.setColumnStructureModel();
   }
   /**
-   * Build and assign the ColumnStructureModel from current `columns` and `groupColumns`.
-   * Uses `ColumnStructureModel.from` which returns a root model representing the column tree.
+   * Rebuilds the ColumnStructureModel when template-derived grouping changes.
+   */
+  watchTemplateGroupColumns() {
+    this.setColumnStructureModel();
+  }
+  /**
+   * Build and assign the ColumnStructureModel from current inputs.
+   * Template-derived grouping takes precedence over the public `groupColumns` input.
    */
   setColumnStructureModel() {
-    this.columnStructureModel = ColumnStructureModel.from(this.columns, this.groupColumns);
+    var _a;
+    this.columnStructureModel = ColumnStructureModel.from(this.columns, (_a = this.templateGroupColumns) !== null && _a !== void 0 ? _a : this.groupColumns);
   }
 }
-__decorate([
-  MapToComponentField()
-], VegaTableColumnStructureModelController.prototype, "host", void 0);
 __decorate([
   MapToComponentField()
 ], VegaTableColumnStructureModelController.prototype, "columns", void 0);
 __decorate([
   MapToComponentField()
 ], VegaTableColumnStructureModelController.prototype, "groupColumns", void 0);
+__decorate([
+  MapToComponentField()
+], VegaTableColumnStructureModelController.prototype, "templateGroupColumns", void 0);
 __decorate([
   MapToComponentField({ writable: true })
 ], VegaTableColumnStructureModelController.prototype, "columnStructureModel", void 0);
@@ -64,3 +71,6 @@ __decorate([
 __decorate([
   MapToComponentMethod('watchGroupColumns')
 ], VegaTableColumnStructureModelController.prototype, "watchGroupColumns", null);
+__decorate([
+  MapToComponentMethod('watchTemplateGroupColumns')
+], VegaTableColumnStructureModelController.prototype, "watchTemplateGroupColumns", null);

package/dist/collection/components/vega-table/slimmers/controllers/vega-table-head-template-structure-controller.js

@@ -0,0 +1,440 @@
+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 { InjectVegaSlimmer, MapToComponentField, MapToComponentMethod, methodPlaceholder, VegaSlimmer, } from 'vega-slimmer/core';
+import { TagNameAndAttributeMutationFilter } from '../../../../helpers/slimmers/mutation-observer/mutation-observer-filters';
+import { MutationObserverSlimmer } from '../../../../helpers/slimmers/mutation-observer/mutation-observer-slimmer';
+import { Observer } from '../../../../helpers/change-manager/observer/observer';
+import changeManager from '../../../../helpers/change-manager/change-manager';
+import domNodeSubjectFactory from '../../../../helpers/change-manager/subject/dom-node-subject/dom-node-subject-factory';
+import { VegaInternalTableHeadTemplateStructureChange, VegaInternalVegaTableRenderInputChange, } from '../../../../helpers/event-manager/event-id/vega-internal-event-id';
+/**
+ * Derives column configuration from the authored `<vega-table-head>` markup.
+ *
+ * Currently produces grouped-column configuration; header-declared column concerns
+ * (e.g. pinning) are intended to live here as well.
+ */
+export class VegaTableHeadTemplateStructureController extends VegaSlimmer {
+  constructor() {
+    super(...arguments);
+    this.templateHeadObserver = new MutationObserverSlimmer({
+      // eslint-disable-next-line jsdoc/require-jsdoc
+      target: () => this.host,
+      options: {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['group-key', 'parent-group-key', 'pinned', 'col-span'],
+      },
+      mutationFilter: TagNameAndAttributeMutationFilter('VEGA-TABLE-HEAD', 'VEGA-TABLE-HEAD-ROW', 'VEGA-TABLE-HEAD-CELL'),
+      callback: 
+      /* istanbul ignore next */
+      // eslint-disable-next-line jsdoc/require-jsdoc
+      () => this.handleTemplateHeadStructureChange(),
+    });
+    // Head node the explicit observer is currently bound to, so it can be rebound when replaced.
+    this.observedTemplateHead = null;
+    this.lastTemplateHeadStructureSnapshot = null;
+  }
+  /**
+   * Refresh template grouping before the mutation observer resumes after reconnecting.
+   */
+  connectedCallback() {
+    this.setTemplateGroupColumns();
+    this.lastTemplateHeadStructureSnapshot = this.getTemplateHeadStructureSnapshot();
+    this.registerTemplateHeadStructureObserver();
+  }
+  /**
+   * Used by {@link templateHeadObserver} to stop observing while the table is disconnected.
+   */
+  disconnectedCallback() {
+    this.unRegisterTemplateHeadStructureObserver();
+    methodPlaceholder();
+  }
+  /**
+   * Initialize template grouping before the column structure is built.
+   */
+  componentWillLoad() {
+    this.setTemplateGroupColumns();
+    this.lastTemplateHeadStructureSnapshot = this.getTemplateHeadStructureSnapshot();
+  }
+  /**
+   * Used by {@link templateHeadObserver}.
+   */
+  componentDidLoad() {
+    this.registerTemplateHeadMaps();
+    // Runtime changes are notified by the render-input watcher; initial load has no
+    // following componentDidRender, so it needs one synchronous notification here.
+    changeManager.notify(domNodeSubjectFactory.getSubject(this.host, VegaInternalVegaTableRenderInputChange), {});
+  }
+  /**
+   * Rebuild template grouping when render mode changes.
+   */
+  watchTemplateRenderMode() {
+    this.setTemplateGroupColumns();
+    this.lastTemplateHeadStructureSnapshot = this.getTemplateHeadStructureSnapshot();
+  }
+  /**
+   * Update the internal template grouping configuration.
+   */
+  setTemplateGroupColumns() {
+    this.templateGroupColumns = this.getTemplateGroupColumns();
+  }
+  /**
+   * Recompute template grouping and row/cell render-input mappings after template head changes.
+   *
+   * Map registration is done here directly instead of via watchColumnStructureModel because
+   * this controller is registered before the render-input controller. If map registration
+   * were deferred to the columnStructureModel watcher, render inputs would still be stale
+   * (render-input controller's watcher hasn't fired yet due to slimmer registration order).
+   */
+  handleTemplateHeadStructureChange() {
+    const nextSnapshot = this.getTemplateHeadStructureSnapshot();
+    if (this.isSameTemplateHeadStructure(nextSnapshot, this.lastTemplateHeadStructureSnapshot))
+      return;
+    this.lastTemplateHeadStructureSnapshot = nextSnapshot;
+    this.setTemplateGroupColumns();
+    this.registerTemplateHeadStructureObserver();
+    this.registerTemplateHeadMaps();
+  }
+  /**
+   * Collect a normalized snapshot for template-head hierarchy keys.
+   *
+   * This lets us ignore duplicated observer notifications that represent the same logical
+   * structure (e.g. reflected-attribute path and explicit watcher path firing for one update).
+   *
+   * @returns {Nullable<TemplateHeadStructureCell[]>} Snapshot of current template head structure.
+   */
+  getTemplateHeadStructureSnapshot() {
+    if (!this.isTemplateRenderMode)
+      return null;
+    const templateHead = this.getTemplateHead();
+    if (!templateHead)
+      return null;
+    const rows = Array.from(templateHead.children).filter((child) => child.tagName === 'VEGA-TABLE-HEAD-ROW');
+    return rows.flatMap((row, rowIndex) => {
+      const cells = Array.from(row.children).filter((child) => child.tagName === 'VEGA-TABLE-HEAD-CELL');
+      return cells.map((cell, cellIndex) => ({
+        rowIndex,
+        cellIndex,
+        key: this.getCellProperty(cell, 'groupKey', 'group-key'),
+        parentKey: this.getCellProperty(cell, 'parentGroupKey', 'parent-group-key'),
+        pinned: this.getCellProperty(cell, 'pinned', 'pinned'),
+      }));
+    });
+  }
+  /**
+   * Compare two structure snapshots by authored order and key values.
+   *
+   * @param {Nullable<TemplateHeadStructureCell[]>} nextSnapshot - Latest snapshot.
+   * @param {Nullable<TemplateHeadStructureCell[]>} prevSnapshot - Previous snapshot.
+   * @returns {boolean} True when snapshots represent the same logical structure.
+   */
+  isSameTemplateHeadStructure(nextSnapshot, prevSnapshot) {
+    if (nextSnapshot === prevSnapshot)
+      return true;
+    if (!nextSnapshot || !prevSnapshot)
+      return false;
+    if (nextSnapshot.length !== prevSnapshot.length)
+      return false;
+    return nextSnapshot.every((nextCell, index) => {
+      const prevCell = prevSnapshot[index];
+      return (nextCell.rowIndex === prevCell.rowIndex &&
+        nextCell.cellIndex === prevCell.cellIndex &&
+        nextCell.key === prevCell.key &&
+        nextCell.parentKey === prevCell.parentKey &&
+        nextCell.pinned === prevCell.pinned);
+    });
+  }
+  /**
+   * Register explicit head-cell structure-change observer for property-assignment updates.
+   */
+  registerTemplateHeadStructureObserver() {
+    const templateHead = this.getTemplateHead();
+    if (!templateHead || templateHead === this.observedTemplateHead)
+      return;
+    // Rebind when the authored head node was replaced so property-update notifications from the
+    // new head's subject are still observed.
+    this.unRegisterTemplateHeadStructureObserver();
+    if (!this.templateHeadStructureObserver) {
+      this.templateHeadStructureObserver = new Observer((input) => {
+        return Boolean(input && input.host);
+      }, () => this.handleTemplateHeadStructureChange());
+    }
+    changeManager.register(domNodeSubjectFactory.getSubject(templateHead, VegaInternalTableHeadTemplateStructureChange), this.templateHeadStructureObserver);
+    this.observedTemplateHead = templateHead;
+  }
+  /**
+   * Unregister explicit head-cell structure-change observer.
+   */
+  unRegisterTemplateHeadStructureObserver() {
+    const templateHead = this.observedTemplateHead;
+    if (!templateHead || !this.templateHeadStructureObserver)
+      return;
+    changeManager.unregister(domNodeSubjectFactory.getSubject(templateHead, VegaInternalTableHeadTemplateStructureChange), this.templateHeadStructureObserver);
+    this.observedTemplateHead = null;
+  }
+  /**
+   * Find authored template head element under table host.
+   *
+   * @typedef {import('../../../../types/components').HTMLVegaTableHeadElement} HTMLVegaTableHeadElement
+   * @returns {Nullable<HTMLVegaTableHeadElement>} Template head element if present.
+   */
+  getTemplateHead() {
+    return Array.from(this.host.children).find((child) => child.tagName === 'VEGA-TABLE-HEAD');
+  }
+  /**
+   * Register template head rows/cells with render-input maps using authored position.
+   *
+   * This mirrors data-source mode, where header renderer registers maps during JSX ref callbacks.
+   * Runtime changes are notified after the column model rebuilds, keeping maps ready without a
+   * second notification for the same template mutation.
+   */
+  registerTemplateHeadMaps() {
+    if (!this.isTemplateRenderMode)
+      return;
+    const templateHead = this.getTemplateHead();
+    if (!templateHead)
+      return;
+    // Clear all head mappings before rebuilding to prevent stale entries
+    // from persisting when template transitions from valid to invalid/unresolved.
+    this.vegaTableRenderInputController.clearHeadRenderInputMaps();
+    const renderInputs = this.vegaTableRenderInputController.getHeadRenderInputs() || [];
+    const renderInputByKey = new Map(renderInputs
+      .flatMap((model) => model.iterator())
+      .map((model) => [model.key, model]));
+    const templateRows = Array.from(templateHead.children).filter((child) => child.tagName === 'VEGA-TABLE-HEAD-ROW');
+    // Leaf render inputs in authored order, used to map headers without group keys by position.
+    const leafRenderInputs = this.vegaTableRenderInputController.getLeafRenderInputs() || [];
+    templateRows.forEach((templateRow) => {
+      const templateCells = Array.from(templateRow.children).filter((child) => child.tagName === 'VEGA-TABLE-HEAD-CELL');
+      // A header without group keys carries no grouping identity, so pinning is resolved by position:
+      // the authored cell index maps directly onto the leaf render input at the same index.
+      const rowHasKey = templateCells.some((templateCell) => Boolean(this.getCellProperty(templateCell, 'groupKey', 'group-key')));
+      const rowRenderInputs = templateCells.map((templateCell, cellIndex) => {
+        if (!rowHasKey)
+          return leafRenderInputs[cellIndex] || null;
+        const key = this.getCellProperty(templateCell, 'groupKey', 'group-key');
+        return renderInputByKey.get(key) || null;
+      });
+      // Register only when every authored cell has a matching render input.
+      // Partial mappings can corrupt row-level edge/span calculations.
+      if (rowRenderInputs.some((renderInput) => !renderInput))
+        return;
+      const resolvedRowRenderInputs = rowRenderInputs;
+      this.vegaTableRenderInputController.addHeadRowRenderInputMap(templateRow, resolvedRowRenderInputs);
+      templateCells.forEach((templateCell, cellIndex) => {
+        this.vegaTableRenderInputController.addHeadCellRenderInputMap(templateCell, resolvedRowRenderInputs[cellIndex]);
+      });
+    });
+  }
+  /**
+   * Convert a hand-authored template head into the public grouped-column model.
+   *
+   * Grouping needs authored keys: every cell must have a unique `groupKey`, and cells below the
+   * first row must declare `parentGroupKey` pointing to a cell in the immediately preceding row.
+   * Pinning, in contrast, is purely positional, so a header without group keys that only declares edge
+   * `pinned` is handled by {@link getFlatPinnedColumns} instead of being treated as unkeyed.
+   * Group labels are derived from cell text and default to an empty string because template
+   * markup remains responsible for the visible content.
+   *
+   * @returns {Nullable<VegaTableGroupColumnConfig[]>} Derived grouping configuration; null for a
+   * header without group keys with no edge pinning, or an empty array for malformed structured markup.
+   */
+  getTemplateGroupColumns() {
+    if (!this.isTemplateRenderMode)
+      return null;
+    const templateHead = this.getTemplateHead();
+    if (!templateHead)
+      return null;
+    const nodes = this.collectTemplateNodes(templateHead);
+    if (nodes.length === 0)
+      return null;
+    if (nodes.every((node) => !node.key))
+      return this.getFlatPinnedColumns(nodes);
+    if (nodes.some((node) => !node.key))
+      return [];
+    const nodesByKey = new Map(nodes.map((node) => [node.key, node]));
+    if (nodesByKey.size !== nodes.length)
+      return [];
+    if (!this.linkTemplateNodes(nodes, nodesByKey))
+      return [];
+    const topLevelNodes = nodes.filter((node) => node.rowIndex === 0);
+    this.dropNonEdgePinned(topLevelNodes);
+    return topLevelNodes.map((node) => this.toGroupColumnConfig(node));
+  }
+  /**
+   * Derive flat, position-keyed leaf columns for a header without group keys whose only column concern is
+   * edge pinning. Grouping requires authored keys, but pinning is positional, so a single-row
+   * header that declares `pinned` without any `group-key` still yields pinned leaf columns.
+   *
+   * Returns null when the header spans multiple rows (grouping cannot be inferred without keys) or
+   * declares no honorable edge pin, preserving the legacy behavior where a plain header without group keys
+   * derives no column model and simply renders its authored cells.
+   *
+   * @param {TemplateColumnNode[]} nodes - Template nodes in authored order (all row 0 when valid).
+   * @returns {Nullable<VegaTableGroupColumnConfig[]>} Position-keyed leaf configs, or null.
+   */
+  getFlatPinnedColumns(nodes) {
+    if (nodes.some((node) => node.rowIndex !== 0))
+      return null;
+    this.dropNonEdgePinned(nodes);
+    if (nodes.every((node) => !node.pinned))
+      return null;
+    // The authored index is the identity here; these keys are never used for head-cell lookup
+    // (registerTemplateHeadMaps maps headers without group keys by position, matching the positional body zip).
+    return nodes.map((node, index) => {
+      node.key = String(index);
+      return this.toGroupColumnConfig(node);
+    });
+  }
+  /**
+   * Drop `pinned` from top-level cells that are not at the physical edge.
+   *
+   * Data-source mode reorders columns to `[left, none, right]` via `orderChildrenByPinned`, so any
+   * pinned column ends up at an edge. Template mode renders authored cells in place and never
+   * reorders them, and sticky pinning only works when the pinned column already sits at the edge.
+   * So we honor `pinned` only for a contiguous leading run (left) and trailing run (right) of the
+   * authored top-level cells; a pinned cell anywhere in between would freeze mid-table and let the
+   * columns authored before it scroll underneath, so its pin is ignored.
+   *
+   * @param {TemplateColumnNode[]} topLevelNodes - Row-0 nodes in authored (physical) order.
+   */
+  dropNonEdgePinned(topLevelNodes) {
+    // End of the leading run of left-pinned cells (exclusive).
+    let leadingLeftEnd = 0;
+    while (leadingLeftEnd < topLevelNodes.length && topLevelNodes[leadingLeftEnd].pinned === 'left') {
+      leadingLeftEnd++;
+    }
+    // Start of the trailing run of right-pinned cells (exclusive lower bound).
+    let trailingRightStart = topLevelNodes.length - 1;
+    while (trailingRightStart >= 0 && topLevelNodes[trailingRightStart].pinned === 'right') {
+      trailingRightStart--;
+    }
+    topLevelNodes.forEach((node, index) => {
+      const isEdgeLeft = node.pinned === 'left' && index < leadingLeftEnd;
+      const isEdgeRight = node.pinned === 'right' && index > trailingRightStart;
+      if (!isEdgeLeft && !isEdgeRight)
+        node.pinned = undefined;
+    });
+  }
+  /**
+   * Flatten the authored template head rows into row-major template nodes.
+   *
+   * @param {HTMLElement} templateHead - Authored `<vega-table-head>` element.
+   * @returns {TemplateColumnNode[]} Template nodes in authored order.
+   */
+  collectTemplateNodes(templateHead) {
+    const rows = Array.from(templateHead.children).filter((child) => child.tagName === 'VEGA-TABLE-HEAD-ROW');
+    return rows.flatMap((row, rowIndex) => Array.from(row.children)
+      .filter((child) => child.tagName === 'VEGA-TABLE-HEAD-CELL')
+      .map((cell, cellIndex) => ({
+      cell,
+      key: this.getCellProperty(cell, 'groupKey', 'group-key'),
+      rowIndex,
+      cellIndex,
+      children: [],
+      pinned: this.getCellProperty(cell, 'pinned', 'pinned'),
+    })));
+  }
+  /**
+   * Validate parent references and link each node to its parent in place.
+   *
+   * Children must reference a cell in the immediately preceding row, be grouped by parent, and
+   * list parents left-to-right; first-row cells must not declare a parent.
+   *
+   * @param {TemplateColumnNode[]} nodes - Template nodes in authored order.
+   * @param {Map<string, TemplateColumnNode>} nodesByKey - Node lookup by group key.
+   * @returns {boolean} True when the hierarchy is well-formed.
+   */
+  linkTemplateNodes(nodes, nodesByKey) {
+    var _a;
+    const lastParentIndexByRow = new Map();
+    for (const node of nodes) {
+      const parentKey = this.getCellProperty(node.cell, 'parentGroupKey', 'parent-group-key');
+      if (node.rowIndex === 0) {
+        if (parentKey)
+          return false;
+        continue;
+      }
+      const parent = nodesByKey.get(parentKey);
+      if (!parent || parent.rowIndex !== node.rowIndex - 1)
+        return false;
+      // Children must be listed grouped by parent and parents left-to-right, so a parent's
+      // cell index can never move backwards within a row. This single check rejects both
+      // non-contiguous children and out-of-order parent groups.
+      if (parent.cellIndex < ((_a = lastParentIndexByRow.get(node.rowIndex)) !== null && _a !== void 0 ? _a : -1))
+        return false;
+      lastParentIndexByRow.set(node.rowIndex, parent.cellIndex);
+      parent.children.push(node);
+    }
+    return true;
+  }
+  /**
+   * Convert a template node tree into a grouped-column configuration.
+   *
+   * @param {TemplateColumnNode} node - Template node to convert.
+   * @returns {VegaTableGroupColumnConfig} Group or leaf configuration.
+   */
+  toGroupColumnConfig(node) {
+    // A childless top-level node carries its pinning through the group-model `pinned` field
+    // (which applies to top-level nodes), so `VegaTableColumnGroupingLeafModel` stays a plain
+    // `{ key }` reference and does not need a variant-only pinned property.
+    if (node.children.length === 0) {
+      return node.pinned
+        ? { key: node.key, label: (node.cell.textContent || '').trim(), pinned: node.pinned }
+        : { key: node.key };
+    }
+    return Object.assign(Object.assign({ key: node.key, label: (node.cell.textContent || '').trim() }, (node.pinned ? { pinned: node.pinned } : {})), { children: node.children.map((child) => this.toGroupColumnConfig(child)) });
+  }
+  /**
+   * Read a reflected template-cell property with an attribute fallback.
+   *
+   * The `pinned` variant returns only valid pinning values; invalid values return undefined.
+   *
+   * @param {HTMLElement} cell - Template head cell.
+   * @param {'groupKey' | 'parentGroupKey' | 'pinned'} property - Component property name.
+   * @param {'group-key' | 'parent-group-key' | 'pinned'} attribute - Reflected attribute name.
+   * @returns {string | undefined} Normalized property value.
+   */
+  getCellProperty(cell, property, attribute) {
+    const value = (cell[property] || cell.getAttribute(attribute) || '').trim();
+    if (property === 'pinned') {
+      return value === 'left' || value === 'right' ? value : undefined;
+    }
+    return value;
+  }
+}
+__decorate([
+  MapToComponentField()
+], VegaTableHeadTemplateStructureController.prototype, "host", void 0);
+__decorate([
+  MapToComponentField()
+], VegaTableHeadTemplateStructureController.prototype, "isTemplateRenderMode", void 0);
+__decorate([
+  MapToComponentField({ writable: true })
+], VegaTableHeadTemplateStructureController.prototype, "templateGroupColumns", void 0);
+__decorate([
+  MapToComponentField()
+], VegaTableHeadTemplateStructureController.prototype, "vegaTableRenderInputController", void 0);
+__decorate([
+  InjectVegaSlimmer()
+], VegaTableHeadTemplateStructureController.prototype, "templateHeadObserver", void 0);
+__decorate([
+  MapToComponentMethod('connectedCallback')
+], VegaTableHeadTemplateStructureController.prototype, "connectedCallback", null);
+__decorate([
+  MapToComponentMethod('disconnectedCallback')
+], VegaTableHeadTemplateStructureController.prototype, "disconnectedCallback", null);
+__decorate([
+  MapToComponentMethod('componentWillLoad')
+], VegaTableHeadTemplateStructureController.prototype, "componentWillLoad", null);
+__decorate([
+  MapToComponentMethod('componentDidLoad')
+], VegaTableHeadTemplateStructureController.prototype, "componentDidLoad", null);
+__decorate([
+  MapToComponentMethod('watchTemplateRenderMode')
+], VegaTableHeadTemplateStructureController.prototype, "watchTemplateRenderMode", null);