@universal-ember/table 3.0.0 → 3.0.1

package/src/plugins/column-visibility/plugin.ts

@@ -0,0 +1,155 @@
+import { cached } from '@glimmer/tracking';
+import { action } from '@ember/object';
+
+import { BasePlugin, meta, options, preferences } from '../-private/base.ts';
+
+import type { Plugin, PluginPreferences } from '../../plugins/index.ts';
+import type { Column, Table } from '../../index.ts';
+
+interface ColumnVisibilityPreferences extends PluginPreferences {
+  columns: {
+    [columnKey: string]: {
+      isVisible?: boolean;
+    };
+  };
+}
+
+declare module '@universal-ember/table/plugins' {
+  interface Registry {
+    ColumnVisibility?: ColumnVisibilityPreferences;
+    'column-visibility'?: ColumnVisibilityPreferences;
+  }
+}
+
+export interface Signature {
+  Meta: {
+    Table: TableMeta;
+    Column: ColumnMeta;
+  };
+  Options: {
+    Plugin: {
+      enabled?: boolean;
+    };
+    Column: {
+      /**
+       * The default visibilty of the column, when rendered.
+       * The column can still be toggled on and off.
+       *
+       * When interacting with preferences, the value stored in preferenced
+       * will be the inverse of this value (to save space in storage).
+       */
+      isVisible?: boolean;
+    };
+  };
+}
+
+export class ColumnVisibility
+  extends BasePlugin<Signature>
+  implements Plugin<Signature>
+{
+  name = 'column-visibility';
+  static features = ['columnVisibility'];
+
+  meta = {
+    column: ColumnMeta,
+    table: TableMeta,
+  };
+
+  reset() {
+    preferences.forAllColumns(this.table, ColumnVisibility).delete('isVisible');
+  }
+
+  get columns() {
+    return meta.forTable(this.table, ColumnVisibility).visibleColumns;
+  }
+}
+
+export class ColumnMeta<Data = unknown> {
+  constructor(private column: Column<Data>) {}
+
+  get isVisible(): boolean {
+    const columnPreferences = preferences.forColumn(
+      this.column,
+      ColumnVisibility,
+    );
+    const columnOptions = options.forColumn(this.column, ColumnVisibility);
+
+    return Boolean(
+      columnPreferences.get('isVisible') ?? columnOptions?.isVisible ?? true,
+    );
+  }
+
+  get isHidden(): boolean {
+    return !this.isVisible;
+  }
+
+  hide = () => {
+    if (!this.isVisible) return;
+
+    const myPreferences = preferences.forColumn(this.column, ColumnVisibility);
+    const myOptions = options.forColumn(this.column, ColumnVisibility);
+    const currentSaved = myPreferences.get('isVisible');
+    const willBeDefault = Boolean(currentSaved) === !myOptions?.isVisible;
+
+    if (willBeDefault) {
+      myPreferences.set('isVisible', false);
+      // TODO: open an issue about tracked-built-ins' delete not being reactive
+      // myPreferences.delete('isVisible');
+
+      return;
+    }
+
+    myPreferences.set('isVisible', false);
+  };
+
+  show = () => {
+    if (this.isVisible) return;
+
+    const myPreferences = preferences.forColumn(this.column, ColumnVisibility);
+    const myOptions = options.forColumn(this.column, ColumnVisibility);
+    const currentSaved = myPreferences.get('isVisible');
+    const willBeDefault = currentSaved === !myOptions?.isVisible;
+
+    if (willBeDefault) {
+      myPreferences.set('isVisible', true);
+      // TODO: open an issue about tracked-built-ins' delete not being reactive
+      // myPreferences.delete('isVisible');
+
+      return;
+    }
+
+    myPreferences.set('isVisible', true);
+  };
+
+  toggle = () => {
+    if (this.isVisible) {
+      this.hide();
+
+      return;
+    }
+
+    this.show();
+  };
+}
+
+export class TableMeta<Data = unknown> {
+  constructor(private table: Table<Data>) {}
+
+  @cached
+  get visibleColumns(): Column<Data>[] {
+    const allColumns = this.table.columns.values();
+
+    return allColumns.filter((column) => {
+      const columnMeta = meta.forColumn(column, ColumnVisibility);
+
+      return columnMeta.isVisible;
+    });
+  }
+
+  @action
+  toggleColumnVisibility(column: Column<Data>) {
+    const columnMeta = meta.forColumn(column, ColumnVisibility);
+
+    columnMeta.toggle();
+  }
+}

package/src/plugins/data-sorting/helpers.ts

@@ -0,0 +1,56 @@
+import { meta } from '../-private/base.ts';
+import { Sorting } from './plugin.ts';
+
+import type { Column } from '../../index.ts';
+
+/**
+ * Query a specific column's current sort direction
+ */
+export const sortDirection = (column: Column) =>
+  meta.forColumn(column, Sorting).sortDirection;
+
+/**
+ * Ask if a column is sortable
+ */
+export const isSortable = (column: Column) =>
+  meta.forColumn(column, Sorting).isSortable;
+
+/**
+ * Ask if a column is ascending
+ */
+export const isAscending = (column: Column) =>
+  meta.forColumn(column, Sorting).isAscending;
+
+/**
+ * Ask if a column is sorted descending
+ */
+export const isDescending = (column: Column) =>
+  meta.forColumn(column, Sorting).isDescending;
+
+/**
+ * Ask if a column is not sorted
+ */
+export const isUnsorted = (column: Column) =>
+  meta.forColumn(column, Sorting).isUnsorted;
+
+/**
+ * Sort the specified column's data using a tri-toggle.
+ *
+ * States go in this order:
+ *   Ascending => None => Descending
+ *    ⬑ ---------- <= ---------- ↲
+ */
+export const sort = (column: Column) =>
+  meta.forTable(column.table, Sorting).handleSort(column);
+
+/**
+ * Toggle a column between descending and not unsorted states
+ */
+export const sortDescending = (column: Column) =>
+  meta.forTable(column.table, Sorting).toggleDescending(column);
+
+/**
+ * Toggle a column between ascending and not unsorted states
+ */
+export const sortAscending = (column: Column) =>
+  meta.forTable(column.table, Sorting).toggleAscending(column);

package/src/plugins/data-sorting/index.ts

@@ -0,0 +1,8 @@
+export * from './helpers.ts';
+export { Sorting as Plugin } from './plugin.ts';
+export { Sorting as DataSorting } from './plugin.ts';
+export { SortDirection } from './types.ts';
+
+// Public Types
+export type { Signature } from './plugin.ts';
+export type { Sort, SortItem } from './types.ts';

package/src/plugins/data-sorting/plugin.ts

@@ -0,0 +1,222 @@
+import { cached } from '@glimmer/tracking';
+import { action } from '@ember/object';
+
+import { BasePlugin, meta, options } from '../-private/base.ts';
+import { SortDirection } from './types.ts';
+
+import type { Sort, SortItem } from './types.ts';
+import type { ColumnApi, PluginPreferences } from '../../plugins/index.ts';
+import type { Column, Table } from '../../index.ts';
+
+interface SortingPreferences extends PluginPreferences {
+  table: {
+    sorts?: Sort[];
+  };
+}
+
+declare module '@universal-ember/table/plugins' {
+  interface Registry {
+    Sorting?: SortingPreferences;
+    sorting?: SortingPreferences;
+  }
+}
+
+export interface Signature<DataType = unknown> {
+  Meta: {
+    Column: ColumnMeta;
+    Table: TableMeta;
+  };
+  Options: {
+    Plugin: Options<DataType>;
+    Column: ColumnOptions;
+  };
+}
+
+interface Options<DataType = unknown> {
+  /**
+   * Handler for interpreting sort requests from the headless table.
+   *
+   * Does not actually do the sorting.
+   *
+   * if omitted, the DataSorting plugin will disable itself
+   */
+  onSort?: (sorts: SortItem<DataType>[]) => void;
+  /**
+   * Provided sorts that the table should assume are true.
+   *
+   * if omitted, the DataSorting plugin will disable itself
+   */
+  sorts?: SortItem<DataType>[];
+}
+
+interface ColumnOptions {
+  /**
+   * Opt in or out of sorting for a particular column.
+   * Default is true.
+   */
+  isSortable?: boolean;
+  /**
+   * Use this key instead of the `key` on the column config.
+   * This has no bearing on any behavior in the plugin, *other than*,
+   * swapping out the `property`'s value on the `SortItem`s passed to
+   * the table plugin config's `onSort` callback
+   */
+  sortProperty?: string;
+}
+
+/**
+ * Manages basic data-sorting behaviors. Ascending -> Descending -> None
+ *
+ * This plugin requires a table plugin configuration, `onSort` for handling *how* sorting happens.
+ * communicating back to the table that sorting has succeeded can be done by setting the `sorts`
+ * property in the table plugin configuration.
+ *
+ * Note that this plugin doesn't actually sort the data, as data management is not the responsibility
+ * of the table, but of the surrounding context providing the data to the table. So sorting can happen
+ * client-side still, just in a component -- much the same way you'd handel sorting via API requests.
+ *
+ * This plugin is for *conveying* what the current sorts are, rather than _doing_ the sorting.
+ */
+export class Sorting<DataType = unknown> extends BasePlugin<
+  Signature<DataType>
+> {
+  name = 'data-sorting';
+
+  meta = {
+    column: ColumnMeta,
+    table: TableMeta,
+  };
+
+  headerCellModifier = (element: HTMLElement, { column }: ColumnApi) => {
+    const columnMeta = meta.forColumn(column, Sorting);
+
+    element.setAttribute('data-test-is-sortable', `${columnMeta.isSortable}`);
+    element.setAttribute('aria-sort', `${columnMeta.sortDirection}`);
+  };
+}
+
+export class ColumnMeta {
+  constructor(private column: Column) {}
+
+  @cached
+  get options() {
+    return options.forColumn(this.column, Sorting);
+  }
+
+  get isSortable() {
+    return this.options?.isSortable ?? this.tableMeta.isSortable;
+  }
+
+  get tableMeta() {
+    return meta.forTable(this.column.table, Sorting);
+  }
+
+  get sortDirection() {
+    const sort = this.tableMeta.sorts.find(
+      (sort) => sort.property === this.sortProperty,
+    );
+
+    return sort?.direction ?? SortDirection.None;
+  }
+
+  get isAscending() {
+    return this.sortDirection === SortDirection.Ascending;
+  }
+
+  get isDescending() {
+    return this.sortDirection === SortDirection.Descending;
+  }
+
+  get isUnsorted() {
+    return this.sortDirection === SortDirection.None;
+  }
+
+  get sortProperty() {
+    return this.options?.sortProperty ?? this.column.config.key;
+  }
+}
+
+export class TableMeta {
+  constructor(private table: Table) {}
+
+  @cached
+  get options() {
+    return options.forTable(this.table, Sorting);
+  }
+
+  get sorts() {
+    return this.options?.sorts ?? [];
+  }
+
+  get isSortable() {
+    return Boolean(this.options?.onSort) && Boolean(this.options?.sorts);
+  }
+
+  get onSort() {
+    return this.options?.onSort;
+  }
+
+  @action
+  handleSort(column: Column) {
+    const columnMeta = meta.forColumn(column, Sorting);
+
+    if (!columnMeta.sortProperty) {
+      return;
+    }
+
+    if (columnMeta.sortDirection === SortDirection.Ascending) {
+      this.onSort?.([]);
+    } else if (columnMeta.sortDirection === SortDirection.Descending) {
+      this.onSort?.([
+        {
+          direction: SortDirection.Ascending,
+          property: columnMeta.sortProperty,
+        },
+      ]);
+    } else {
+      this.onSort?.([
+        {
+          direction: SortDirection.Descending,
+          property: columnMeta.sortProperty,
+        },
+      ]);
+    }
+  }
+
+  @action
+  toggleAscending(column: Column) {
+    const columnMeta = meta.forColumn(column, Sorting);
+
+    if (!columnMeta.sortProperty) {
+      return;
+    }
+
+    if (columnMeta.sortDirection === SortDirection.Ascending) {
+      return this.onSort?.([]);
+    }
+
+    this.onSort?.([
+      { direction: SortDirection.Ascending, property: columnMeta.sortProperty },
+    ]);
+  }
+
+  @action
+  toggleDescending(column: Column) {
+    const columnMeta = meta.forColumn(column, Sorting);
+
+    if (!columnMeta.sortProperty) {
+      return;
+    }
+
+    if (columnMeta.sortDirection === SortDirection.Descending) {
+      return this.onSort?.([]);
+    }
+
+    this.onSort?.([
+      {
+        direction: SortDirection.Descending,
+        property: columnMeta.sortProperty,
+      },
+    ]);
+  }
+}

package/src/plugins/data-sorting/types.ts

@@ -0,0 +1,26 @@
+import type { ColumnKey } from '../../-private/interfaces';
+
+export enum SortDirection {
+  Ascending = 'ascending',
+  Descending = 'descending',
+  None = 'none',
+}
+
+export interface Sort {
+  property: string;
+  direction: SortDirection;
+}
+
+export enum SortTransform {
+  Underscore = 'underscore',
+  Camelize = 'camelize',
+}
+export interface SortsOptions {
+  separator: string;
+  transform: string | null;
+}
+
+export interface SortItem<T> {
+  direction: SortDirection;
+  property: ColumnKey<T>;
+}

package/src/plugins/index.ts

@@ -0,0 +1,20 @@
+// Public API
+export {
+  BasePlugin,
+  columns,
+  hasPlugin,
+  meta,
+  options,
+  preferences,
+} from './-private/base.ts';
+export { applyStyles, removeStyles } from './-private/utils.ts';
+
+// Public Types
+export type { ColumnFeatures, TableFeatures } from './-private/base.ts';
+export type {
+  ColumnApi,
+  Plugin,
+  PluginPreferences,
+  Registry,
+} from '../-private/interfaces';
+export type { PluginSignature } from '../-private/interfaces/plugins';

package/src/plugins/metadata/helpers.ts

@@ -0,0 +1,12 @@
+import { options } from '../-private/base.ts';
+import { Metadata } from './plugin.ts';
+
+import type { Column, Table } from '../../index.ts';
+
+export const forColumn = (column: Column<any>, key: string) => {
+  return options.forColumn(column, Metadata)[key];
+};
+
+export const forTable = (table: Table<any>, key: string) => {
+  return options.forTable(table, Metadata)[key];
+};

package/src/plugins/metadata/index.ts

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

package/src/plugins/metadata/plugin.ts

@@ -0,0 +1,26 @@
+import { BasePlugin } from '../-private/base.ts';
+
+/**
+ * Data stored per column or table can be arbitrary
+ *
+ */
+type ArbitraryData = Record<string, any>;
+
+export interface Signature<Data = ArbitraryData> {
+  Options: {
+    Column: Data;
+    Plugin: Data;
+  };
+}
+
+/**
+ * This plugin does noting,
+ * but gives consumer of it a safe way to store and associate "any" data with columns
+ * (and have a generic top-level bucket of data as well)
+ *
+ * This "metadata" stored per column per table is managed via the "options" part of the Signature, as
+ * "meta" is a term used for plugins for plugin authors.
+ */
+export class Metadata<S extends Signature> extends BasePlugin<S> {
+  name = 'metadata';
+}

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

@@ -0,0 +1,13 @@
+import { meta } from '../-private/base.ts';
+import { RowSelection } from './plugin.ts';
+
+import type { Row } from '../../-private/row.ts';
+
+export const isSelected = (row: Row<any>) =>
+  meta.forRow(row, RowSelection).isSelected;
+export const select = (row: Row<any>) =>
+  meta.forRow(row, RowSelection).select();
+export const deselect = (row: Row<any>) =>
+  meta.forRow(row, RowSelection).deselect();
+export const toggle = (row: Row<any>) =>
+  meta.forRow(row, RowSelection).toggle();

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

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