@globalpayments/vega 2.97.0 → 2.98.0

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);

package/dist/collection/components/vega-table/slimmers/controllers/vega-table-render-input-controller.js

@@ -107,6 +107,17 @@ export class VegaTableRenderInputController extends VegaSlimmer {
   addHeadCellRenderInputMap(headCell, renderInput) {
     this.headCellRenderInputMap.set(headCell, renderInput);
   }
+  /**
+   * Clear all head row and head cell render-input mappings.
+   *
+   * Used by template-mode lifecycle to invalidate stale grouped-header metadata
+   * before re-registering current mappings. In data-source mode the header renderer
+   * re-registers via ref callbacks each render, so stale entries are overwritten naturally.
+   */
+  clearHeadRenderInputMaps() {
+    this.headRowRenderInputMap.clear();
+    this.headCellRenderInputMap.clear();
+  }
   /**
    * Store body cell render input mapping for pinned cells (used to update sticky positions).
    *
@@ -174,9 +185,6 @@ __decorate([
 __decorate([
   MapToComponentField()
 ], VegaTableRenderInputController.prototype, "columnStructureModel", void 0);
-__decorate([
-  MapToComponentField()
-], VegaTableRenderInputController.prototype, "vegaTableColGroupRenderer", void 0);
 __decorate([
   MapToComponentMethod('connectedCallback')
 ], VegaTableRenderInputController.prototype, "connectedCallback", null);