@universal-ember/table 3.0.0 → 3.0.1

package/src/plugins/row-selection/plugin.ts

@@ -0,0 +1,218 @@
+import { cached } from '@glimmer/tracking';
+import { assert } from '@ember/debug';
+
+import { BasePlugin, meta, options } from '../-private/base.ts';
+
+import type { Row, Table } from '../../index.ts';
+import type { PluginSignature, RowApi } from '../../-private/interfaces';
+
+export interface Signature<DataType = any, Key = DataType>
+  extends PluginSignature {
+  Meta: {
+    Table: TableMeta;
+    Row: RowMeta;
+  };
+  Options: {
+    Plugin: {
+      /**
+       * A set of selected things using the same type of Identifier
+       * returned from `key`
+       */
+      selection: Set<Key> | Array<Key>;
+    } & (
+      | {
+          /**
+           * For a given row's data, how should the key be determined?
+           * this could be a remote id from a database, or some other attribute
+           *
+           * This could be useful for indicating in UI if a particular item is selected.
+           *
+           * If not provided, the row's data will be used as the key
+           */
+          key: (data: DataType) => Key;
+          /**
+           * When a row is clicked, this will be invoked,
+           * allowing you to update your selection object
+           */
+          onSelect: (item: Key, row: Row<DataType>) => void;
+          /**
+           * When a row is clicked (and the row is selected), this will be invoked,
+           * allowing you to update your selection object
+           */
+          onDeselect: (item: Key, row: Row<DataType>) => void;
+        }
+      | {
+          /**
+           * When a row is clicked (and the row is not selected), this will be invoked,
+           * allowing you to update your selection object
+           */
+          onSelect: (item: DataType | any, row: Row<DataType>) => void;
+          /**
+           * When a row is clicked (and the row is selected), this will be invoked,
+           * allowing you to update your selection object
+           */
+          onDeselect: (item: DataType | any, row: Row<DataType>) => void;
+        }
+    );
+  };
+}
+
+/**
+ * This plugin provides a means of managing selection of a single row in a table.
+ *
+ * The state of what is actually selected is managed by you, but this plugin
+ * will wire up the click listeners as well as let you know which *data* is clicked.
+ */
+export class RowSelection<DataType = any, Key = DataType> extends BasePlugin<
+  Signature<DataType, Key>
+> {
+  name = 'row-selection';
+
+  meta = {
+    row: RowMeta,
+    table: TableMeta,
+  };
+
+  constructor(table: Table) {
+    super(table);
+
+    const pluginOptions = options.forTable(this.table, RowSelection);
+
+    assert(
+      `selection, onSelect, and onDeselect are all required arguments for the RowSelection plugin. ` +
+        `Specify these options via \`RowSelection.with(() => ({ selection, onSelect, onDeselect }))\``,
+      pluginOptions.selection &&
+        pluginOptions.onSelect &&
+        pluginOptions.onDeselect,
+    );
+  }
+
+  rowModifier = (element: HTMLElement, { row }: RowApi<Table<any>>) => {
+    const handler = (event: Event) => {
+      this.#clickHandler(row, event);
+    };
+
+    element.addEventListener('click', handler);
+
+    return () => {
+      element.removeEventListener('click', handler);
+    };
+  };
+
+  #clickHandler = (row: Row, event: Event) => {
+    assert(
+      `expected event.target to be an instance of HTMLElement`,
+      event.target instanceof HTMLElement || event.target instanceof SVGElement,
+    );
+
+    const selection = document.getSelection();
+
+    if (selection) {
+      const { type, anchorNode } = selection;
+      const isSelectingText =
+        type === 'Range' && event.target?.contains(anchorNode);
+
+      if (isSelectingText) {
+        event.stopPropagation();
+
+        return;
+      }
+    }
+
+    // Ignore clicks on interactive elements within the row
+    const inputParent = event.target.closest('input, button, label, a, select');
+
+    if (inputParent) {
+      return;
+    }
+
+    const rowMeta = meta.forRow(row, RowSelection);
+
+    rowMeta.toggle();
+  };
+}
+
+class TableMeta {
+  #table: Table;
+
+  constructor(table: Table) {
+    this.#table = table;
+  }
+
+  @cached
+  get selection(): Set<unknown> {
+    const passedSelection = options.forTable(
+      this.#table,
+      RowSelection,
+    ).selection;
+
+    assert(`Cannot access selection because it is undefined`, passedSelection);
+
+    if (passedSelection instanceof Set) {
+      return passedSelection;
+    }
+
+    return new Set(passedSelection);
+  }
+}
+
+class RowMeta {
+  #row: Row<any>;
+
+  constructor(row: Row<any>) {
+    this.#row = row;
+  }
+
+  get isSelected(): boolean {
+    const tableMeta = meta.forTable(this.#row.table, RowSelection);
+    const pluginOptions = options.forTable(this.#row.table, RowSelection);
+
+    if ('key' in pluginOptions && pluginOptions.key) {
+      const compareWith = pluginOptions.key(this.#row.data);
+
+      return tableMeta.selection.has(compareWith);
+    }
+
+    const compareWith = this.#row.data;
+
+    return tableMeta.selection.has(compareWith);
+  }
+
+  toggle = () => {
+    if (this.isSelected) {
+      this.deselect();
+
+      return;
+    }
+
+    this.select();
+  };
+
+  select = () => {
+    const pluginOptions = options.forTable(this.#row.table, RowSelection);
+
+    if ('key' in pluginOptions && pluginOptions.key) {
+      const key = pluginOptions.key(this.#row.data);
+
+      pluginOptions.onSelect?.(key, this.#row);
+
+      return;
+    }
+
+    pluginOptions.onSelect?.(this.#row.data, this.#row);
+  };
+
+  deselect = () => {
+    const pluginOptions = options.forTable(this.#row.table, RowSelection);
+
+    if ('key' in pluginOptions && pluginOptions.key) {
+      const key = pluginOptions.key(this.#row.data);
+
+      pluginOptions.onDeselect?.(key, this.#row);
+
+      return;
+    }
+
+    pluginOptions.onDeselect?.(this.#row.data, this.#row);
+  };
+}

package/src/plugins/sticky-columns/helpers.ts

@@ -0,0 +1,59 @@
+import { htmlSafe } from '@ember/template';
+
+import { meta } from '../-private/base.ts';
+import { StickyColumns } from './plugin.ts';
+
+import type { Column } from '../../index.ts';
+
+export const isSticky = <DataType = unknown>(column: Column<DataType>) =>
+  meta.forColumn(column, StickyColumns).isSticky;
+
+export const styleFor = <DataType = unknown>(
+  column: Column<DataType>,
+): Partial<CSSStyleDeclaration> => meta.forColumn(column, StickyColumns).style;
+
+/**
+ * In this plugin, both header and cells have the same styles,
+ * if applicable.
+ *
+ * Until this RFC https://github.com/emberjs/rfcs/pull/883
+ * is merged and implemented, we can't performantly
+ * use modifiers for apply styles.
+ *
+ * In the mean time, we'll need to append style strings, which is more work
+ * for consumers, but is a reasonable trade-off for now.
+ */
+export const styleStringFor = <DataType = unknown>(
+  column: Column<DataType>,
+): ReturnType<typeof htmlSafe> => {
+  const columnMeta = meta.forColumn(column, StickyColumns);
+
+  let result = '';
+
+  if (columnMeta.isSticky) {
+    for (const [key, value] of Object.entries(columnMeta.style)) {
+      result += `${toStyle(key)}:${value};`;
+    }
+
+    result = ';' + result;
+  }
+
+  return htmlSafe(result);
+};
+
+/**
+ * the JS API for styles is camel case,
+ * but CSS is kebab-case. To save on complexity and
+ * amount of code, we have a super small conversion function
+ * for only the properties relevant to the sticky plugin.
+ */
+const toStyle = (key: string): string => {
+  switch (key) {
+    case 'zIndex':
+      return 'z-index';
+    case 'minWidth':
+      return 'min-width';
+    default:
+      return key;
+  }
+};

package/src/plugins/sticky-columns/index.ts

@@ -0,0 +1,7 @@
+// Public API
+export * from './helpers.ts';
+export { StickyColumns } from './plugin.ts';
+export { StickyColumns as Plugin } from './plugin.ts';
+
+// Public types
+export type { Signature } from './plugin.ts';

package/src/plugins/sticky-columns/plugin.ts

@@ -0,0 +1,201 @@
+import { cached } from '@glimmer/tracking';
+import { assert } from '@ember/debug';
+
+import { BasePlugin, columns, meta, options } from '../-private/base.ts';
+import { applyStyles } from '../-private/utils.ts';
+
+import type { ColumnApi } from '../../plugins/index.ts';
+import type { Column } from '../../index.ts';
+
+const DEFAULT_Z_INDEX = '8';
+
+interface ColumnOptions {
+  /**
+   * Whether or not to enable stickiness on the column
+   * (default is false)
+   *
+   * valid values: 'left', 'right', false
+   */
+  sticky?: boolean | string;
+}
+
+export interface Signature {
+  Options: {
+    Column: ColumnOptions;
+    Plugin: {
+      /**
+       * Opts this plugin out of engaging in the modifier system
+       * and instead requires setting a `style` attribute on
+       * th / td tags for getting the "position: sticky" behovior
+       * on columns.
+       */
+      workaroundForModifierTimingUpdateRFC883?: boolean;
+    };
+  };
+  Meta: {
+    Table: TableMeta;
+    Column: ColumnMeta;
+  };
+}
+
+export class StickyColumns extends BasePlugin<Signature> {
+  name = 'sticky-columns';
+
+  /**
+   * This plugin requires that the resizing plugin be present, because the resizing plugin is
+   * what manages the base width of the columns.
+   *
+   * Other width-management plugins can be used instead of ColumnResizing, but they must declare
+   * that they manage the width of the columns.
+   */
+  static requires = ['columnWidth'];
+
+  meta = {
+    table: TableMeta,
+    column: ColumnMeta,
+  };
+
+  conditionallyRemoveStyles = (element: HTMLElement) => {
+    if (element.style.getPropertyValue('position') === 'sticky') {
+      element.style.removeProperty('position');
+    }
+
+    if (element.style.getPropertyValue('left')) {
+      element.style.left = '';
+    }
+
+    if (element.style.getPropertyValue('right')) {
+      element.style.right = '';
+    }
+
+    if (element.style.zIndex === DEFAULT_Z_INDEX) {
+      element.style.zIndex = '';
+    }
+  };
+
+  headerCellModifier = (element: HTMLElement, { column, table }: ColumnApi) => {
+    if (
+      options.forTable(table, StickyColumns)
+        .workaroundForModifierTimingUpdateRFC883
+    ) {
+      return;
+    }
+
+    const columnMeta = meta.forColumn(column, StickyColumns);
+
+    if (columnMeta.isSticky) {
+      applyStyles(element, columnMeta.style);
+    } else {
+      this.conditionallyRemoveStyles(element);
+    }
+  };
+
+  /**
+   * Not yet supported. Pending Ember RFC #883
+   *
+   * TODO: switch ColumnApi to "RowApi", add the row's data
+   */
+  cellModifier = (element: HTMLElement, { column, table }: ColumnApi) => {
+    if (
+      options.forTable(table, StickyColumns)
+        .workaroundForModifierTimingUpdateRFC883
+    ) {
+      return;
+    }
+
+    const columnMeta = meta.forColumn(column, StickyColumns);
+
+    if (columnMeta.isSticky) {
+      applyStyles(element, columnMeta.style);
+    } else {
+      this.conditionallyRemoveStyles(element);
+    }
+  };
+}
+
+/**
+ * @private
+ *
+ * Contains state and behaviors for the sticiness
+ */
+export class ColumnMeta {
+  constructor(private column: Column) {}
+
+  get isSticky() {
+    return this.position !== 'none';
+  }
+
+  get position(): 'left' | 'right' | 'none' {
+    const sticky = options.forColumn(this.column, StickyColumns)?.sticky;
+
+    assert(
+      `Invalid sticky value, ${sticky}. Valid values: 'left', 'right', false`,
+      sticky === 'left' ||
+        sticky === 'right' ||
+        sticky === false ||
+        sticky === undefined,
+    );
+
+    return sticky || 'none';
+  }
+
+  @cached
+  get offset() {
+    if (!this.isSticky) {
+      return;
+    }
+
+    if (this.position === 'left') {
+      const leftColumns = columns.before(this.column);
+      const left = leftColumns.reduce((acc, column) => {
+        const columnMeta = meta.withFeature.forColumn(column, 'columnWidth');
+
+        if (hasWidth(columnMeta)) {
+          return acc + (columnMeta.width ?? 0);
+        }
+
+        return acc;
+      }, 0);
+
+      return `${left}px`;
+    }
+
+    if (this.position === 'right') {
+      const rightColumns = columns.after(this.column);
+      const right = rightColumns.reduce((acc, column) => {
+        const columnMeta = meta.withFeature.forColumn(column, 'columnWidth');
+
+        if (hasWidth(columnMeta)) {
+          return acc + (columnMeta.width ?? 0);
+        }
+
+        return acc;
+      }, 0);
+
+      return `${right}px`;
+    }
+
+    return;
+  }
+
+  get style(): Partial<
+    Pick<CSSStyleDeclaration, 'position' | 'left' | 'right' | 'zIndex'>
+  > {
+    if (this.isSticky) {
+      return {
+        position: 'sticky',
+        [this.position]: this.offset,
+        zIndex: DEFAULT_Z_INDEX,
+      };
+    }
+
+    return {};
+  }
+}
+
+function hasWidth(obj: any): obj is { width?: number } {
+  return typeof obj === 'object' && obj && 'width' in obj;
+}
+
+/* This Plugin does not need table state */
+export class TableMeta {}

package/src/test-support/index.ts

@@ -0,0 +1,76 @@
+import { assert } from '@ember/debug';
+import { find, settled, triggerEvent } from '@ember/test-helpers';
+
+interface Selectors {
+  resizeHandle?: string;
+  scrollContainer?: string;
+}
+
+export function createHelpers(selectors: Selectors) {
+  async function resize(parent: Element, delta: number) {
+    assert(
+      `Can't use the dragLeft/dragRight/resize helpers without a \`resizeHandle\` selector`,
+      selectors.resizeHandle,
+    );
+
+    const element = parent.querySelector(selectors.resizeHandle);
+
+    assert(`Can't resize without a handle`, element);
+
+    /**
+     * Start the click in exactly the middle of the element.
+     * "startX" is the horizontal middle of "element"
+     */
+    const rect = element.getBoundingClientRect();
+    const startX = (rect.right + rect.left) / 2;
+
+    const targetX = startX + delta;
+
+    triggerEvent(element, 'mousedown', { clientX: startX, button: 0 });
+    triggerEvent(element, 'mousemove', { clientX: targetX, button: 0 });
+    triggerEvent(element, 'mouseup', { clientX: targetX, button: 0 });
+
+    await settled();
+  }
+
+  function horizontalScrollElement() {
+    assert(
+      `Can't use scrollRight/swipeLeft helpers without a \`scrollContainer\` selector`,
+      selectors.scrollContainer,
+    );
+
+    const element = find(selectors.scrollContainer);
+
+    assert(`scroll container not found`, element instanceof HTMLElement);
+
+    return element;
+  }
+
+  async function scrollRight(distance: number) {
+    const element = horizontalScrollElement();
+
+    element.scrollLeft += distance;
+    await requestAnimationFrameSettled();
+  }
+
+  async function scrollLeft(distance: number) {
+    const element = horizontalScrollElement();
+
+    element.scrollLeft -= distance;
+    await requestAnimationFrameSettled();
+  }
+
+  return {
+    dragLeft: (column: Element, amount: number) => resize(column, -amount),
+    dragRight: (column: Element, amount: number) => resize(column, amount),
+    scrollLeft,
+    scrollRight,
+    swipeLeft: scrollRight,
+    swipeRight: scrollLeft,
+  };
+}
+
+export async function requestAnimationFrameSettled() {
+  await new Promise(requestAnimationFrame);
+  await settled();
+}

package/src/utils.ts

@@ -0,0 +1,85 @@
+import { assert } from '@ember/debug';
+import { camelize, underscore } from '@ember/string';
+
+import { SortDirection } from './plugins/data-sorting/types.ts';
+
+import type { Sort, SortsOptions } from './plugins/data-sorting/types.ts';
+
+/**
+ * @example
+ *
+ * ```ts
+ * deserializeSorts('first_name.asc', { separator: '.', transform: 'camelize' });
+ * // => [{ property: 'firstName', direction: 'ascending' }]
+ *
+ * deserializeSorts('last_name.desc', { separator: '.', transform: 'camelize' });
+ * // => [{ property: 'lastName', direction: 'descending' }]
+ * ```
+ */
+
+export const deserializeSorts = (
+  sortString: string,
+  options: SortsOptions = { separator: '.', transform: 'camelize' },
+): Sort[] => {
+  if (!sortString) {
+    return [];
+  }
+
+  const { transform, separator } = options;
+  let [key, direction] = sortString.split(separator);
+
+  assert(
+    `No key found for input: \`${sortString}\` using \`${separator}\` as a separator`,
+    key,
+  );
+
+  if (transform === 'camelize') {
+    key = camelize(key);
+  } else if (transform === 'underscore') {
+    key = underscore(key);
+  }
+
+  return [
+    {
+      property: key,
+      direction:
+        direction === 'asc'
+          ? SortDirection.Ascending
+          : SortDirection.Descending,
+    },
+  ];
+};
+
+/**
+ * @example
+ *
+ * ```ts
+ * serializeSorts([{ property: 'firstName', direction: 'ascending' }],{ separator: '.', transform: 'camelize' });
+ * // => 'first_name.asc'
+ *
+ * serializeSorts([{ property: 'lastName', direction: 'descending' }],{ separator: '.', transform: 'camelize' });
+ * // => 'last_name.desc'
+ * ```
+ */
+export function serializeSorts(
+  sorts: Sort[],
+  options: SortsOptions = { separator: '.', transform: 'underscore' },
+): string {
+  const { transform, separator } = options;
+
+  const sortParameters = sorts.map(({ direction, property }) => {
+    const shortDirection = direction === 'ascending' ? 'asc' : 'desc';
+
+    let sortField = property;
+
+    if (transform === 'underscore') {
+      sortField = underscore(property);
+    } else if (transform === 'camelize') {
+      sortField = camelize(property);
+    }
+
+    return `${sortField}${separator}${shortDirection}`;
+  });
+
+  return sortParameters.join('+');
+}