@vaadin/grid 24.2.3 → 24.3.0-alpha10

package/src/vaadin-grid-column-group.js

@@ -3,13 +3,11 @@
  * Copyright (c) 2016 - 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { FlattenedNodesObserver } from '@polymer/polymer/lib/utils/flattened-nodes-observer.js';
+
 import { PolymerElement } from '@polymer/polymer/polymer-element.js';
-import { animationFrame } from '@vaadin/component-base/src/async.js';
-import { Debouncer } from '@vaadin/component-base/src/debounce.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
-import { ColumnBaseMixin } from './vaadin-grid-column.js';
-import { updateColumnOrders } from './vaadin-grid-helpers.js';
+import { GridColumnGroupMixin } from './vaadin-grid-column-group-mixin.js';
+export * from './vaadin-grid-column-group-mixin.js';
 
 /**
  * A `<vaadin-grid-column-group>` is used to make groups of columns in `<vaadin-grid>` and
@@ -42,360 +40,12 @@ import { updateColumnOrders } from './vaadin-grid-helpers.js';
  *
  * @customElement
  * @extends HTMLElement
- * @mixes ColumnBaseMixin
+ * @mixes GridColumnGroupMixin
  */
-class GridColumnGroup extends ColumnBaseMixin(PolymerElement) {
+class GridColumnGroup extends GridColumnGroupMixin(PolymerElement) {
   static get is() {
     return 'vaadin-grid-column-group';
   }
-
-  static get properties() {
-    return {
-      /** @private */
-      _childColumns: {
-        value() {
-          return this._getChildColumns(this);
-        },
-      },
-
-      /**
-       * Flex grow ratio for the column group as the sum of the ratios of its child columns.
-       * @attr {number} flex-grow
-       */
-      flexGrow: {
-        type: Number,
-        readOnly: true,
-      },
-
-      /**
-       * Width of the column group as the sum of the widths of its child columns.
-       */
-      width: {
-        type: String,
-        readOnly: true,
-      },
-
-      /** @private */
-      _visibleChildColumns: Array,
-
-      /** @private */
-      _colSpan: Number,
-
-      /** @private */
-      _rootColumns: Array,
-    };
-  }
-
-  static get observers() {
-    return [
-      '_groupFrozenChanged(frozen, _rootColumns)',
-      '_groupFrozenToEndChanged(frozenToEnd, _rootColumns)',
-      '_groupHiddenChanged(hidden)',
-      '_colSpanChanged(_colSpan, _headerCell, _footerCell)',
-      '_groupOrderChanged(_order, _rootColumns)',
-      '_groupReorderStatusChanged(_reorderStatus, _rootColumns)',
-      '_groupResizableChanged(resizable, _rootColumns)',
-    ];
-  }
-
-  /** @protected */
-  connectedCallback() {
-    super.connectedCallback();
-    this._addNodeObserver();
-    this._updateFlexAndWidth();
-  }
-
-  /** @protected */
-  disconnectedCallback() {
-    super.disconnectedCallback();
-    if (this._observer) {
-      this._observer.disconnect();
-    }
-  }
-
-  /**
-   * @param {string} path
-   * @param {unknown=} value
-   * @protected
-   */
-  _columnPropChanged(path, value) {
-    if (path === 'hidden') {
-      // Prevent synchronization of the hidden state to child columns.
-      // If the group is currently auto-hidden, and one column is made visible,
-      // we don't want the other columns to become visible as well.
-      this._preventHiddenSynchronization = true;
-      this._updateVisibleChildColumns(this._childColumns);
-      this._preventHiddenSynchronization = false;
-    }
-
-    if (/flexGrow|width|hidden|_childColumns/u.test(path)) {
-      this._updateFlexAndWidth();
-    }
-
-    // Don't unfreeze the frozen group because of a non-frozen child
-    if (path === 'frozen' && !this.frozen) {
-      this.frozen = value;
-    }
-
-    // Don't unfreeze the frozen group because of a non-frozen child
-    if (path === 'lastFrozen' && !this._lastFrozen) {
-      this._lastFrozen = value;
-    }
-
-    // Don't unfreeze the frozen group because of a non-frozen child
-    if (path === 'frozenToEnd' && !this.frozenToEnd) {
-      this.frozenToEnd = value;
-    }
-
-    // Don't unfreeze the frozen group because of a non-frozen child
-    if (path === 'firstFrozenToEnd' && !this._firstFrozenToEnd) {
-      this._firstFrozenToEnd = value;
-    }
-  }
-
-  /** @private */
-  _groupOrderChanged(order, rootColumns) {
-    if (rootColumns) {
-      const _rootColumns = rootColumns.slice(0);
-
-      if (!order) {
-        _rootColumns.forEach((column) => {
-          column._order = 0;
-        });
-        return;
-      }
-      // The parent column order number cascades downwards to it's children
-      // so that the resulting order numbering constructs as follows:
-      // [             1000              ]
-      // [     1100    ] | [     1200    ]
-      // [1110] | [1120] | [1210] | [1220]
-
-      // Trailing zeros are counted so we know the level on which we're working on.
-      const trailingZeros = /(0+)$/u.exec(order).pop().length;
-
-      // In an unlikely situation where a group has more than 9 child columns,
-      // the child scope must have 1 digit less...
-      // Log^a_b = Ln(a)/Ln(b)
-      // Number of digits of a number is equal to floor(Log(number)_10) + 1
-      const childCountDigits = ~~(Math.log(rootColumns.length) / Math.LN10) + 1;
-
-      // Final scope for the child columns needs to mind both factors.
-      const scope = 10 ** (trailingZeros - childCountDigits);
-
-      if (_rootColumns[0] && _rootColumns[0]._order) {
-        _rootColumns.sort((a, b) => a._order - b._order);
-      }
-      updateColumnOrders(_rootColumns, scope, order);
-    }
-  }
-
-  /** @private */
-  _groupReorderStatusChanged(reorderStatus, rootColumns) {
-    if (reorderStatus === undefined || rootColumns === undefined) {
-      return;
-    }
-
-    rootColumns.forEach((column) => {
-      column._reorderStatus = reorderStatus;
-    });
-  }
-
-  /** @private */
-  _groupResizableChanged(resizable, rootColumns) {
-    if (resizable === undefined || rootColumns === undefined) {
-      return;
-    }
-
-    rootColumns.forEach((column) => {
-      column.resizable = resizable;
-    });
-  }
-
-  /** @private */
-  _updateVisibleChildColumns(childColumns) {
-    this._visibleChildColumns = Array.prototype.filter.call(childColumns, (col) => !col.hidden);
-    this._colSpan = this._visibleChildColumns.length;
-    this._updateAutoHidden();
-  }
-
-  /** @protected */
-  _updateFlexAndWidth() {
-    if (!this._visibleChildColumns) {
-      return;
-    }
-
-    if (this._visibleChildColumns.length > 0) {
-      const width = this._visibleChildColumns
-        .reduce((prev, curr) => {
-          prev += ` + ${(curr.width || '0px').replace('calc', '')}`;
-          return prev;
-        }, '')
-        .substring(3);
-      this._setWidth(`calc(${width})`);
-    } else {
-      this._setWidth('0px');
-    }
-
-    this._setFlexGrow(Array.prototype.reduce.call(this._visibleChildColumns, (prev, curr) => prev + curr.flexGrow, 0));
-  }
-
-  /**
-   * This method is called before the group's frozen value is being propagated to the child columns.
-   * In case some of the child columns are frozen, while others are not, the non-frozen ones
-   * will get automatically frozen as well. As this may sometimes be unintended, this method
-   * shows a warning in the console in such cases.
-   * @private
-   */
-  __scheduleAutoFreezeWarning(columns, frozenProp) {
-    if (this._grid) {
-      // Derive the attribute name from the property name
-      const frozenAttr = frozenProp.replace(/([A-Z])/gu, '-$1').toLowerCase();
-
-      // Check if all the columns have the same frozen value
-      const firstColumnFrozen = columns[0][frozenProp] || columns[0].hasAttribute(frozenAttr);
-      const allSameFrozen = columns.every((column) => {
-        return (column[frozenProp] || column.hasAttribute(frozenAttr)) === firstColumnFrozen;
-      });
-
-      if (!allSameFrozen) {
-        // Some of the child columns are frozen, some are not. Show a warning.
-        this._grid.__autoFreezeWarningDebouncer = Debouncer.debounce(
-          this._grid.__autoFreezeWarningDebouncer,
-          animationFrame,
-          () => {
-            console.warn(
-              `WARNING: Joining ${frozenProp} and non-${frozenProp} Grid columns inside the same column group! ` +
-                `This will automatically freeze all the joined columns to avoid rendering issues. ` +
-                `If this was intentional, consider marking each joined column explicitly as ${frozenProp}. ` +
-                `Otherwise, exclude the ${frozenProp} columns from the joined group.`,
-            );
-          },
-        );
-      }
-    }
-  }
-
-  /** @private */
-  _groupFrozenChanged(frozen, rootColumns) {
-    if (rootColumns === undefined || frozen === undefined) {
-      return;
-    }
-
-    // Don't propagate the default `false` value.
-    if (frozen !== false) {
-      this.__scheduleAutoFreezeWarning(rootColumns, 'frozen');
-
-      Array.from(rootColumns).forEach((col) => {
-        col.frozen = frozen;
-      });
-    }
-  }
-
-  /** @private */
-  _groupFrozenToEndChanged(frozenToEnd, rootColumns) {
-    if (rootColumns === undefined || frozenToEnd === undefined) {
-      return;
-    }
-
-    // Don't propagate the default `false` value.
-    if (frozenToEnd !== false) {
-      this.__scheduleAutoFreezeWarning(rootColumns, 'frozenToEnd');
-
-      Array.from(rootColumns).forEach((col) => {
-        col.frozenToEnd = frozenToEnd;
-      });
-    }
-  }
-
-  /** @private */
-  _groupHiddenChanged(hidden) {
-    // When initializing the hidden property, only sync hidden state to columns
-    // if group is actually hidden. Otherwise, we could override a hidden column
-    // to be visible.
-    // We always want to run this though if the property is actually changed.
-    if (hidden || this.__groupHiddenInitialized) {
-      this._synchronizeHidden();
-    }
-    this.__groupHiddenInitialized = true;
-  }
-
-  /** @private */
-  _updateAutoHidden() {
-    const wasAutoHidden = this._autoHidden;
-    this._autoHidden = (this._visibleChildColumns || []).length === 0;
-    // Only modify hidden state if group was auto-hidden, or becomes auto-hidden
-    if (wasAutoHidden || this._autoHidden) {
-      this.hidden = this._autoHidden;
-    }
-  }
-
-  /** @private */
-  _synchronizeHidden() {
-    if (this._childColumns && !this._preventHiddenSynchronization) {
-      this._childColumns.forEach((column) => {
-        column.hidden = this.hidden;
-      });
-    }
-  }
-
-  /** @private */
-  _colSpanChanged(colSpan, headerCell, footerCell) {
-    if (headerCell) {
-      headerCell.setAttribute('colspan', colSpan);
-      if (this._grid) {
-        this._grid._a11yUpdateCellColspan(headerCell, colSpan);
-      }
-    }
-    if (footerCell) {
-      footerCell.setAttribute('colspan', colSpan);
-      if (this._grid) {
-        this._grid._a11yUpdateCellColspan(footerCell, colSpan);
-      }
-    }
-  }
-
-  /**
-   * @param {!GridColumnGroup} el
-   * @return {!Array<!GridColumn>}
-   * @protected
-   */
-  _getChildColumns(el) {
-    return FlattenedNodesObserver.getFlattenedNodes(el).filter(this._isColumnElement);
-  }
-
-  /** @private */
-  _addNodeObserver() {
-    this._observer = new FlattenedNodesObserver(this, (info) => {
-      if (
-        info.addedNodes.filter(this._isColumnElement).length > 0 ||
-        info.removedNodes.filter(this._isColumnElement).length > 0
-      ) {
-        // Prevent synchronization of the hidden state to child columns.
-        // If the group is currently auto-hidden, and a visible column is added,
-        // we don't want the other columns to become visible as well.
-        this._preventHiddenSynchronization = true;
-        this._rootColumns = this._getChildColumns(this);
-        this._childColumns = this._rootColumns;
-        this._updateVisibleChildColumns(this._childColumns);
-        this._preventHiddenSynchronization = false;
-
-        // Update the column tree
-        if (this._grid && this._grid._debounceUpdateColumnTree) {
-          this._grid._debounceUpdateColumnTree();
-        }
-      }
-    });
-    this._observer.flush();
-  }
-
-  /**
-   * @param {!Node} node
-   * @return {boolean}
-   * @protected
-   */
-  _isColumnElement(node) {
-    return node.nodeType === Node.ELEMENT_NODE && /\bcolumn\b/u.test(node.localName);
-  }
 }
 
 defineCustomElement(GridColumnGroup);

package/src/vaadin-grid-column-mixin.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+import type { GridItemModel } from './vaadin-grid.js';
+
+export type GridBodyRenderer<TItem, Column extends GridColumnMixin<TItem, Column>> = (
+  root: HTMLElement,
+  column: Column,
+  model: GridItemModel<TItem>,
+) => void;
+
+export type GridColumnTextAlign = 'center' | 'end' | 'start' | null;
+
+export type GridHeaderFooterRenderer<TItem, Column extends ColumnBaseMixinClass<TItem, Column>> = (
+  root: HTMLElement,
+  column: Column,
+) => void;
+
+export declare function ColumnBaseMixin<
+  TItem,
+  Column extends GridColumnMixin<TItem, Column>,
+  T extends Constructor<HTMLElement>,
+>(base: T): Constructor<ColumnBaseMixinClass<TItem, Column>> & T;
+
+export declare class ColumnBaseMixinClass<TItem, Column extends ColumnBaseMixinClass<TItem, Column>> {
+  /**
+   * When set to true, the column is user-resizable.
+   */
+  resizable: boolean | null | undefined;
+
+  /**
+   * When true, the column is frozen. When a column inside of a column group is frozen,
+   * all of the sibling columns inside the group will get frozen also.
+   */
+  frozen: boolean;
+
+  /**
+   * When true, the column is frozen to end of grid.
+   *
+   * When a column inside of a column group is frozen to end, all of the sibling columns
+   * inside the group will get frozen to end also.
+   *
+   * Column can not be set as `frozen` and `frozenToEnd` at the same time.
+   * @attr {boolean} frozen-to-end
+   */
+  frozenToEnd: boolean;
+
+  /**
+   * When true, the cells for this column will be rendered with the `role` attribute
+   * set as `rowheader`, instead of the `gridcell` role value used by default.
+   *
+   * When a column is set as row header, its cells will be announced by screen readers
+   * while navigating to help user identify the current row as uniquely as possible.
+   *
+   * @attr {boolean} row-header
+   */
+  rowHeader: boolean;
+
+  /**
+   * When set to true, the cells for this column are hidden.
+   */
+  hidden: boolean;
+
+  /**
+   * Text content to display in the header cell of the column.
+   */
+  header: string | null | undefined;
+
+  /**
+   * Aligns the columns cell content horizontally.
+   * Supported values: "start", "center" and "end".
+   * @attr {start|center|end} text-align
+   */
+  textAlign: GridColumnTextAlign | null | undefined;
+
+  /**
+   * Custom function for rendering the header content.
+   * Receives two arguments:
+   *
+   * - `root` The header cell content DOM element. Append your content to it.
+   * - `column` The `<vaadin-grid-column>` element.
+   */
+  headerRenderer: GridHeaderFooterRenderer<TItem, Column> | null | undefined;
+
+  /**
+   * Custom function for rendering the footer content.
+   * Receives two arguments:
+   *
+   * - `root` The footer cell content DOM element. Append your content to it.
+   * - `column` The `<vaadin-grid-column>` element.
+   */
+  footerRenderer: GridHeaderFooterRenderer<TItem, Column> | null | undefined;
+
+  /**
+   * Custom part name for the header cell.
+   *
+   * @attr {string} header-part-name
+   */
+  headerPartName: string | null | undefined;
+
+  /**
+   * Custom part name for the footer cell.
+   *
+   * @attr {string} footer-part-name
+   */
+  footerPartName: string | null | undefined;
+}
+
+export interface GridColumnMixin<TItem, Column extends GridColumnMixinClass<TItem, Column>>
+  extends GridColumnMixinClass<TItem, Column> {}
+
+export declare class GridColumnMixinClass<
+  TItem,
+  Column extends GridColumnMixinClass<TItem, Column>,
+> extends ColumnBaseMixinClass<TItem, Column> {
+  /**
+   * Width of the cells for this column.
+   */
+  width: string | null | undefined;
+
+  /**
+   * Flex grow ratio for the cell widths. When set to 0, cell width is fixed.
+   * @attr {number} flex-grow
+   */
+  flexGrow: number;
+
+  /**
+   * Custom function for rendering the cell content.
+   * Receives three arguments:
+   *
+   * - `root` The cell content DOM element. Append your content to it.
+   * - `column` The `<vaadin-grid-column>` element.
+   * - `model` The object with the properties related with
+   *   the rendered item, contains:
+   *   - `model.index` The index of the item.
+   *   - `model.item` The item.
+   *   - `model.expanded` Sublevel toggle state.
+   *   - `model.level` Level of the tree represented with a horizontal offset of the toggle button.
+   *   - `model.selected` Selected state.
+   *   - `model.detailsOpened` Details opened state.
+   */
+  renderer: GridBodyRenderer<TItem, Column> | null | undefined;
+
+  /**
+   * Path to an item sub-property whose value gets displayed in the column body cells.
+   * The property name is also shown in the column header if an explicit header or renderer isn't defined.
+   */
+  path: string | null | undefined;
+
+  /**
+   * Automatically sets the width of the column based on the column contents when this is set to `true`.
+   *
+   * For performance reasons the column width is calculated automatically only once when the grid items
+   * are rendered for the first time and the calculation only considers the rows which are currently
+   * rendered in DOM (a bit more than what is currently visible). If the grid is scrolled, or the cell
+   * content changes, the column width might not match the contents anymore.
+   *
+   * Hidden columns are ignored in the calculation and their widths are not automatically updated when
+   * you show a column that was initially hidden.
+   *
+   * You can manually trigger the auto sizing behavior again by calling `grid.recalculateColumnWidths()`.
+   *
+   * The column width may still grow larger when `flexGrow` is not 0.
+   * @attr {boolean} auto-width
+   */
+  autoWidth: boolean;
+}