review

Author: andrewseguin

src/cdk/table/has-sticky-state.ts renamed to src/cdk/table/can-stick.ts

@@ -15,12 +15,14 @@ export type Constructor<T> = new(...args: any[]) => T;
  * sticky value.
  * @docs-private
  */
-export interface HasStickyState {
-  /** State of whether the sticky input has changed since it was last checked. */
+export interface CanStick {
+  /** Whether the sticky input has changed since it was last checked. */
   _hasStickyChanged: boolean;
 
-  checkStickyChanged(): boolean;
+  /** Whether the sticky value has changed since this was last called. */
+  hasStickyChanged(): boolean;
 
+  /** Resets the dirty check for cases where the sticky state has been used without checking. */
   resetStickyChanged(): void;
 }
 
@@ -30,13 +32,13 @@ export interface HasStickyState {
  * sticky value.
  */
 export function mixinHasStickyInput<T extends Constructor<{}>>(base: T):
-    Constructor<HasStickyState> & T {
+    Constructor<CanStick> & T {
   return class extends base {
-    /** State of whether the sticky input has changed since it was last checked. */
+    /** Whether the sticky input has changed since it was last checked. */
     _hasStickyChanged: boolean = false;
 
     /** Whether the sticky value has changed since this was last called. */
-    checkStickyChanged(): boolean {
+    hasStickyChanged(): boolean {
       const hasStickyChanged = this._hasStickyChanged;
       this._hasStickyChanged = false;
       return hasStickyChanged;

src/cdk/table/cell.ts

@@ -8,7 +8,7 @@
 
 import {ContentChild, Directive, ElementRef, Input, TemplateRef} from '@angular/core';
 import {coerceBooleanProperty} from '@angular/cdk/coercion';
-import {HasStickyState, mixinHasStickyInput} from './has-sticky-state';
+import {CanStick, mixinHasStickyInput} from './can-stick';
 
 /** Base interface for a cell definition. Captures a column's cell template definition. */
 export interface CellDef {
@@ -52,7 +52,7 @@ export const _CdkColumnDefBase = mixinHasStickyInput(CdkColumnDefBase);
  * Defines a set of cells available for a table column.
  */
 @Directive({selector: '[cdkColumnDef]'})
-export class CdkColumnDef extends _CdkColumnDefBase implements HasStickyState {
+export class CdkColumnDef extends _CdkColumnDefBase implements CanStick {
   /** Unique name for this column. */
   @Input('cdkColumnDef')
   get name(): string { return this._name; }
@@ -66,25 +66,25 @@ export class CdkColumnDef extends _CdkColumnDefBase implements HasStickyState {
   }
   _name: string;
 
-  /** Whether this column should be sticky positioned on the left of the row */
-  @Input('stickyLeft')
-  get stickyLeft(): boolean { return this._stickyLeft; }
-  set stickyLeft(v: boolean) {
-    const prevValue = this._stickyLeft;
-    this._stickyLeft = coerceBooleanProperty(v);
-    this._hasStickyChanged = prevValue !== this._stickyLeft;
+  /** Whether this column should be sticky positioned on the start of the row */
+  @Input('sticky')
+  get sticky(): boolean { return this._sticky; }
+  set sticky(v: boolean) {
+    const prevValue = this._sticky;
+    this._sticky = coerceBooleanProperty(v);
+    this._hasStickyChanged = prevValue !== this._sticky;
   }
-  _stickyLeft: boolean = false;
-
-  /** Whether this column should be sticky positioned on the right of the right */
-  @Input('stickyRight')
-  get stickyRight(): boolean { return this._stickyRight; }
-  set stickyRight(v: boolean) {
-    const prevValue = this._stickyRight;
-    this._stickyRight = coerceBooleanProperty(v);
-    this._hasStickyChanged = prevValue !== this._stickyRight;
+  _sticky: boolean = false;
+
+  /** Whether this column should be sticky positioned on the end of the row */
+  @Input('stickyEnd')
+  get stickyEnd(): boolean { return this._stickyEnd; }
+  set stickyEnd(v: boolean) {
+    const prevValue = this._stickyEnd;
+    this._stickyEnd = coerceBooleanProperty(v);
+    this._hasStickyChanged = prevValue !== this._stickyEnd;
   }
-  _stickyRight: boolean = false;
+  _stickyEnd: boolean = false;
 
   /** @docs-private */
   @ContentChild(CdkCellDef) cell: CdkCellDef;

src/cdk/table/public-api.ts

@@ -11,7 +11,7 @@ export * from './cell';
 export * from './row';
 export * from './table-module';
 export * from './sticky-styler';
-export * from './has-sticky-state';
+export * from './can-stick';
 
 /** Re-export DataSource for a more intuitive experience for users of just the table. */
 export {DataSource} from '@angular/cdk/collections';

src/cdk/table/row.ts

@@ -21,7 +21,7 @@ import {
 } from '@angular/core';
 import {CdkCellDef, CdkColumnDef} from './cell';
 import {coerceBooleanProperty} from '@angular/cdk/coercion';
-import {HasStickyState, mixinHasStickyInput} from './has-sticky-state';
+import {CanStick, mixinHasStickyInput} from './can-stick';
 
 /**
  * The row template that can be used by the mat-table. Should not be used outside of the
@@ -86,13 +86,13 @@ export const _CdkHeaderRowDefBase = mixinHasStickyInput(CdkHeaderRowDefBase);
   selector: '[cdkHeaderRowDef]',
   inputs: ['columns: cdkHeaderRowDef', 'sticky: cdkHeaderRowDefSticky'],
 })
-export class CdkHeaderRowDef extends _CdkHeaderRowDefBase implements HasStickyState {
+export class CdkHeaderRowDef extends _CdkHeaderRowDefBase implements CanStick {
+  get sticky(): boolean { return this._sticky; }
   set sticky(v: boolean) {
     const prevValue = this._sticky;
     this._sticky = coerceBooleanProperty(v);
     this._hasStickyChanged = prevValue !== this._sticky;
   }
-  get sticky(): boolean { return this._sticky; }
   _sticky: boolean;
 
   constructor(template: TemplateRef<any>, _differs: IterableDiffers) {
@@ -113,13 +113,13 @@ export const _CdkFooterRowDefBase = mixinHasStickyInput(CdkFooterRowDefBase);
   selector: '[cdkFooterRowDef]',
   inputs: ['columns: cdkFooterRowDef', 'sticky: cdkFooterRowDefSticky'],
 })
-export class CdkFooterRowDef extends _CdkFooterRowDefBase implements HasStickyState {
+export class CdkFooterRowDef extends _CdkFooterRowDefBase implements CanStick {
+  get sticky(): boolean { return this._sticky; }
   set sticky(v: boolean) {
     const prevValue = this._sticky;
     this._sticky = coerceBooleanProperty(v);
     this._hasStickyChanged = prevValue !== this._sticky;
   }
-  get sticky(): boolean { return this._sticky; }
   _sticky: boolean;
 
   constructor(template: TemplateRef<any>, _differs: IterableDiffers) {

src/cdk/table/sticky-styler.ts

@@ -6,88 +6,107 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-/** Directions that can be used when setting sticky positioning. */
+/**
+ * Directions that can be used when setting sticky positioning.
+ * @docs-private
+ */
 export type StickyDirection = 'top' | 'bottom' | 'left' | 'right';
 
 /**
- * Z-index values that should be used when sticking row cells to the top and bottom. If one of those
- * cells are also stuck to the left or right, their z-index should be incremented by one. In doing
- * this, it is guaranteed that header cells will always cover footer cells, and both will always
- * cover data rows.
+ * List of all possible directions that can be used for sticky positioning.
+ * @docs-private
  */
-export enum StickyRowZIndex {
-  Top = 100,
-  Bottom = 10,
-  Left = 1,
-  Right = 1,
-}
+export const STICKY_DIRECTIONS: StickyDirection[] = ['top', 'bottom', 'left', 'right'];
 
-/** Applies and removes sticky positioning styles to the `CdkTable` rows and columns cells. */
+/**
+ * Applies and removes sticky positioning styles to the `CdkTable` rows and columns cells.
+ * @docs-private
+ */
 export class StickyStyler {
-  constructor(private usesNativeHtmlTable: boolean, private stickyCellCSS: string) { }
+  /**
+   * @param isNativeHtmlTable Whether the sticky logic should be based on a table
+   *     that uses the native `<table>` element.
+   * @param stickCellCSS The CSS class that will be applied to every row/cell that has
+   *     sticky positioning applied.
+   */
+  constructor(private isNativeHtmlTable: boolean, private stickCellCSS: string) { }
 
   /**
    * Clears the sticky positioning styles from the row and its cells by resetting the `position`
    * style, setting the zIndex to 0, and unsetting each provided sticky direction.
+   * @param rows The list of rows that should be cleared from sticking in the provided directions
+   * @param stickyDirections The directions that should no longer be set as sticky on the rows.
    */
-  clearStickyPositioningStyles(rows: HTMLElement[], stickyDirections: StickyDirection[]) {
-    rows.forEach(row => {
+  clearStickyPositioning(rows: HTMLElement[], stickyDirections: StickyDirection[]) {
+    for (let row of rows) {
       this._removeStickyStyle(row, stickyDirections);
       for (let i = 0; i < row.children.length; i++) {
         const cell = row.children[i] as HTMLElement;
         this._removeStickyStyle(cell, stickyDirections);
       }
-    });
+    }
   }
 
   /**
    * Applies sticky left and right positions to the cells of each row according to the sticky
    * states of the rendered column definitions.
+   * @param rows The rows that should have its set of cells stuck according to the sticky states.
+   * @param stickyStartStates A list of boolean states where each state represents whether the cell
+   *     in this index position should be stuck to the start of the row.
+   * @param stickyEndStates A list of boolean states where each state represents whether the cell
+   *     in this index position should be stuck to the end of the row.
    */
   updateStickyColumns(
-      rows: HTMLElement[], stickyLeftStates: boolean[], stickyRightStates: boolean[]) {
+      rows: HTMLElement[], stickyStartStates: boolean[], stickyEndStates: boolean[]) {
     const hasStickyColumns =
-        stickyLeftStates.some(state => state) || stickyRightStates.some(state => state);
+        stickyStartStates.some(state => state) || stickyEndStates.some(state => state);
     if (!rows.length || !hasStickyColumns) {
       return;
     }
 
+    const numCells = rows[0].children.length;
     const cellWidths: number[] = this._getCellWidths(rows[0]);
-    const leftPositions = this._getStickyLeftColumnPositions(cellWidths, stickyLeftStates);
-    const rightPositions = this._getStickyRightColumnPositions(cellWidths, stickyRightStates);
+    const startPositions = this._getStickyStartColumnPositions(cellWidths, stickyStartStates);
+    const endPositions = this._getStickyEndColumnPositions(cellWidths, stickyEndStates);
 
-    rows.forEach(row => {
-      for (let i = 0; i < row.children.length; i++) {
+    for (let row of rows) {
+      for (let i = 0; i < numCells; i++) {
         const cell = row.children[i] as HTMLElement;
-        if (stickyLeftStates[i]) {
-          this._addStickyStyle(cell, 'left', leftPositions[i]);
+        if (stickyStartStates[i]) {
+          this._addStickyStyle(cell, 'left', startPositions[i]);
         }
 
-        if (stickyRightStates[i]) {
-          this._addStickyStyle(cell, 'right', rightPositions[i]);
+        if (stickyEndStates[i]) {
+          this._addStickyStyle(cell, 'right', endPositions[i]);
         }
       }
-    });
+    }
   }
 
   /**
    * Applies sticky positioning to the row's cells if using the native table layout, and to the
    * row itself otherwise.
+   * @param rowsToStick The list of rows that should be stuck according to their corresponding
+   *     sticky state and to the provided top or bottom position.
+   * @param stickyStates A list of boolean states where each state represents whether the row
+   *     should be stuck in the particular top or bottom position.
+   * @param position The position direction in which the row should be stuck if that row should be
+   *     sticky.
+   *
    */
-  stickRows(rows: HTMLElement[], stickyStates: boolean[], position: 'top' | 'bottom') {
-    // Bottom-positions rows should stick in reverse order
-    // (e.g. last stuck item will be bottom: 0px)
-    if (position === 'bottom') {
-      rows = rows.reverse();
-    }
+  stickRows(rowsToStick: HTMLElement[], stickyStates: boolean[], position: 'top' | 'bottom') {
+    // If positioning the rows to the bottom, reverse their order when evaluating the sticky
+    // position such that the last row stuck will be "bottom: 0px" and so on.
+    const rows = position === 'bottom' ? rowsToStick.reverse() : rowsToStick;
 
     let stickyHeight = 0;
-    rows.forEach((row, i) => {
-      if (!stickyStates[i]) {
-        return;
+    for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+      if (!stickyStates[rowIndex]) {
+        continue;
       }
 
-      if (this.usesNativeHtmlTable) {
+      const row = rows[rowIndex];
+      if (this.isNativeHtmlTable) {
         for (let j = 0; j < row.children.length; j++) {
           const cell = row.children[j] as HTMLElement;
           this._addStickyStyle(cell, position, stickyHeight);
@@ -99,7 +118,7 @@ export class StickyStyler {
       }
 
       stickyHeight += row.getBoundingClientRect().height;
-    });
+    }
   }
 
   /**
@@ -109,7 +128,7 @@ export class StickyStyler {
    * the tfoot element.
    */
   updateStickyFooterContainer(tableElement: Element, stickyStates: boolean[]) {
-    if (!this.usesNativeHtmlTable) {
+    if (!this.isNativeHtmlTable) {
       return;
     }
 
@@ -127,15 +146,17 @@ export class StickyStyler {
    * sticky position if there are no more directions.
    */
   _removeStickyStyle(element: HTMLElement, stickyDirections: StickyDirection[]) {
-    stickyDirections.forEach(dir => element.style[dir] = '');
+    for (let dir of stickyDirections) {
+      element.style[dir] = '';
+    }
     element.style.zIndex = this._getCalculatedZIndex(element);
 
     // If the element no longer has any more sticky directions, remove sticky positioning and
     // the sticky CSS class.
-    const hasDirection = ['top', 'bottom', 'left', 'right'].some(dir => element.style[dir]);
+    const hasDirection = STICKY_DIRECTIONS.some(dir => !!element.style[dir]);
     if (!hasDirection) {
       element.style.position = '';
-      element.classList.remove(this.stickyCellCSS);
+      element.classList.remove(this.stickCellCSS);
     }
   }
 
@@ -145,18 +166,22 @@ export class StickyStyler {
    * direction and value.
    */
   _addStickyStyle(element: HTMLElement, dir: StickyDirection, dirValue: number) {
-    element.classList.add(this.stickyCellCSS);
+    element.classList.add(this.stickCellCSS);
     element.style[dir] = `${dirValue}px`;
     element.style.cssText += 'position: -webkit-sticky; position: sticky; ';
     element.style.zIndex = this._getCalculatedZIndex(element);
   }
 
   /**
-   * Calculate what the z-index should be for the element depending on the sticky directions styles
-   * that it has set. It should be the case that elements with a top direction should always be at
-   * the forefront, followed by bottom direction elements. Finally, anything with left or right
-   * direction should come behind those. All else should be the lowest and not have any increased
-   * z-index.
+   * Calculate what the z-index should be for the element, depending on what directions (top,
+   * bottom, left, right) have been set. It should be true that elements with a top direction
+   * should have the highest index since these are elements like a table header. If any of those
+   * elements are also sticky in another direction, then they should appear above other elements
+   * that are only sticky top (e.g. a sticky column on a sticky header). Bottom-sticky elements
+   * (e.g. footer rows) should then be next in the ordering such that they are below the header
+   * but above any non-sticky elements. Finally, left/right sticky elements (e.g. sticky columns)
+   * should minimally increment so that they are above non-sticky elements but below top and bottom
+   * elements.
    */
   _getCalculatedZIndex(element: HTMLElement): string {
     const zIndexIncrements = {
@@ -167,13 +192,13 @@ export class StickyStyler {
     };
 
     let zIndex = 0;
-    ['top', 'bottom', 'left', 'right'].forEach(dir => {
+    for (let dir of STICKY_DIRECTIONS) {
       if (element.style[dir]) {
         zIndex += zIndexIncrements[dir];
       }
-    });
+    }
 
-    return String(zIndex);
+    return `${zIndex}`;
   }
 
   /** Gets the widths for each cell in the provided row. */
@@ -193,7 +218,7 @@ export class StickyStyler {
    * accumulation of all sticky column cell widths to the left and right, respectively.
    * Non-sticky cells do not need to have a value set since their positions will not be applied.
    */
-  _getStickyLeftColumnPositions(widths: number[], stickyStates: boolean[]): number[] {
+  _getStickyStartColumnPositions(widths: number[], stickyStates: boolean[]): number[] {
     const positions: number[] = [];
     let nextPosition = 0;
 
@@ -212,7 +237,7 @@ export class StickyStyler {
    * accumulation of all sticky column cell widths to the left and right, respectively.
    * Non-sticky cells do not need to have a value set since their positions will not be applied.
    */
-  _getStickyRightColumnPositions(widths: number[], stickyStates: boolean[]): number[] {
+  _getStickyEndColumnPositions(widths: number[], stickyStates: boolean[]): number[] {
     const positions: number[] = [];
     let nextPosition = 0;