@universal-ember/table 3.0.0 → 3.0.1

package/src/-private/-type-tests/plugins-signature-utils.test.ts

@@ -0,0 +1,154 @@
+import { expectTypeOf } from 'expect-type';
+
+import type {
+  ColumnMetaFor,
+  ColumnOptionsFor,
+  EmptyObject,
+  OptionsFor,
+  PluginSignature,
+  RowMetaFor,
+  TableMetaFor,
+} from '../interfaces/plugins';
+
+class ATableMeta {
+  a = 1;
+}
+class AColumnMeta {
+  ac = 1;
+}
+class ARowMeta {
+  ar = 1;
+}
+interface AOptions {
+  ao: number;
+}
+interface AColumnOptions {
+  aco: number;
+}
+
+interface FullExtendedSignature extends PluginSignature {
+  Meta: {
+    Table: ATableMeta;
+    Column: AColumnMeta;
+    Row: ARowMeta;
+  };
+  Options: {
+    Plugin: AOptions;
+    Column: AColumnOptions;
+  };
+}
+
+expectTypeOf<
+  ColumnOptionsFor<FullExtendedSignature>
+>().toEqualTypeOf<AColumnOptions>();
+expectTypeOf<OptionsFor<FullExtendedSignature>>().toEqualTypeOf<AOptions>();
+expectTypeOf<TableMetaFor<FullExtendedSignature>>().toEqualTypeOf<ATableMeta>();
+expectTypeOf<
+  ColumnMetaFor<FullExtendedSignature>
+>().toEqualTypeOf<AColumnMeta>();
+expectTypeOf<RowMetaFor<FullExtendedSignature>>().toEqualTypeOf<ARowMeta>();
+
+interface FullFreeformSignature {
+  Meta: {
+    Table: ATableMeta;
+    Column: AColumnMeta;
+    Row: ARowMeta;
+  };
+  Options: {
+    Plugin: AOptions;
+    Column: AColumnOptions;
+  };
+}
+
+expectTypeOf<
+  ColumnOptionsFor<FullFreeformSignature>
+>().toEqualTypeOf<AColumnOptions>();
+expectTypeOf<OptionsFor<FullFreeformSignature>>().toEqualTypeOf<AOptions>();
+expectTypeOf<TableMetaFor<FullFreeformSignature>>().toEqualTypeOf<ATableMeta>();
+expectTypeOf<
+  ColumnMetaFor<FullFreeformSignature>
+>().toEqualTypeOf<AColumnMeta>();
+expectTypeOf<RowMetaFor<FullFreeformSignature>>().toEqualTypeOf<ARowMeta>();
+
+interface WithoutOptions {
+  Meta: {
+    Table: ATableMeta;
+    Column: AColumnMeta;
+    Row: ARowMeta;
+  };
+}
+
+expectTypeOf<ColumnOptionsFor<WithoutOptions>>().toEqualTypeOf<EmptyObject>();
+expectTypeOf<OptionsFor<WithoutOptions>>().toEqualTypeOf<EmptyObject>();
+expectTypeOf<TableMetaFor<WithoutOptions>>().toEqualTypeOf<ATableMeta>();
+expectTypeOf<ColumnMetaFor<WithoutOptions>>().toEqualTypeOf<AColumnMeta>();
+expectTypeOf<RowMetaFor<WithoutOptions>>().toEqualTypeOf<ARowMeta>();
+
+interface WithoutMeta {
+  Options: {
+    Plugin: AOptions;
+    Column: AColumnOptions;
+  };
+}
+
+expectTypeOf<ColumnOptionsFor<WithoutMeta>>().toEqualTypeOf<AColumnOptions>();
+expectTypeOf<OptionsFor<WithoutMeta>>().toEqualTypeOf<AOptions>();
+expectTypeOf<TableMetaFor<WithoutMeta>>().toEqualTypeOf<never>();
+expectTypeOf<ColumnMetaFor<WithoutMeta>>().toEqualTypeOf<never>();
+expectTypeOf<RowMetaFor<WithoutMeta>>().toEqualTypeOf<never>();
+
+expectTypeOf<
+  ColumnOptionsFor<{ Options: { Column: AColumnOptions } }>
+>().toEqualTypeOf<AColumnOptions>();
+expectTypeOf<
+  ColumnOptionsFor<{ Options: { Plugin: AOptions } }>
+>().toEqualTypeOf<EmptyObject>();
+
+expectTypeOf<
+  OptionsFor<{ Options: { Plugin: AOptions } }>
+>().toEqualTypeOf<AOptions>();
+expectTypeOf<
+  OptionsFor<{ Options: { Column: AColumnOptions } }>
+>().toEqualTypeOf<EmptyObject>();
+
+expectTypeOf<
+  TableMetaFor<{
+    Meta: {
+      Table: ATableMeta;
+    };
+  }>
+>().toEqualTypeOf<ATableMeta>();
+expectTypeOf<
+  TableMetaFor<{ Meta: { Column: AColumnMeta } }>
+>().toEqualTypeOf<never>();
+expectTypeOf<
+  TableMetaFor<{ Meta: { Row: ARowMeta } }>
+>().toEqualTypeOf<never>();
+
+expectTypeOf<
+  ColumnMetaFor<{
+    Meta: {
+      Table: ATableMeta;
+    };
+  }>
+>().toEqualTypeOf<never>();
+expectTypeOf<
+  ColumnMetaFor<{ Meta: { Column: AColumnMeta } }>
+>().toEqualTypeOf<AColumnMeta>();
+expectTypeOf<
+  ColumnMetaFor<{ Meta: { Row: ARowMeta } }>
+>().toEqualTypeOf<never>();
+
+expectTypeOf<
+  RowMetaFor<{
+    Meta: {
+      Table: ATableMeta;
+    };
+  }>
+>().toEqualTypeOf<never>();
+expectTypeOf<
+  RowMetaFor<{ Meta: { Column: AColumnMeta } }>
+>().toEqualTypeOf<never>();
+expectTypeOf<
+  RowMetaFor<{ Meta: { Row: ARowMeta } }>
+>().toEqualTypeOf<ARowMeta>();

package/src/-private/-type-tests/table-api.test.ts

@@ -0,0 +1,20 @@
+import { expectTypeOf } from 'expect-type';
+
+import { ColumnReordering } from '../../plugins/column-reordering/index.ts';
+import { ColumnResizing } from '../../plugins/column-resizing/index.ts';
+import { DataSorting } from '../../plugins/data-sorting/index.ts';
+
+import type { Table } from '../../index.ts';
+
+// We're testing types, not behaviors
+const x = 0 as unknown as Table<{ x: number }>;
+
+//////////////////////////////
+// <Table>#pluginOf
+expectTypeOf(x.pluginOf(DataSorting)).toEqualTypeOf<DataSorting | undefined>();
+expectTypeOf(x.pluginOf(ColumnReordering)).toEqualTypeOf<
+  ColumnReordering | undefined
+>();
+expectTypeOf(x.pluginOf(ColumnResizing)).toEqualTypeOf<
+  ColumnResizing | undefined
+>();

package/src/-private/-type-tests/table-config.test.ts

@@ -0,0 +1,70 @@
+import { expectTypeOf } from 'expect-type';
+
+import { BasePlugin } from '../../plugins/-private/base.ts';
+import { ColumnReordering } from '../../plugins/column-reordering/index.ts';
+import { ColumnResizing } from '../../plugins/column-resizing/index.ts';
+import { ColumnVisibility } from '../../plugins/column-visibility/index.ts';
+import { DataSorting } from '../../plugins/data-sorting/index.ts';
+import { StickyColumns } from '../../plugins/sticky-columns/index.ts';
+
+import type { Plugins } from '../../plugins/-private/utils';
+import type { SortItem } from '../../plugins/data-sorting';
+import type { Plugin } from '../../plugins/index.ts';
+import type { TableConfig } from '../../index.ts';
+import type { Constructor } from '../../-private/private-types.ts';
+
+type TablePluginConfig = NonNullable<TableConfig<unknown>['plugins']>;
+
+/////////////////////////////////////////////
+// Sanity checks
+expectTypeOf<Plugins>().toMatchTypeOf<TablePluginConfig>();
+expectTypeOf<Constructor<Plugin>[]>().toMatchTypeOf<TablePluginConfig>();
+expectTypeOf<[Constructor<Plugin>]>().toMatchTypeOf<TablePluginConfig>();
+expectTypeOf<
+  [Constructor<Plugin>, Constructor<Plugin>]
+>().toMatchTypeOf<TablePluginConfig>();
+expectTypeOf<Constructor<BasePlugin>[]>().toMatchTypeOf<TablePluginConfig>();
+expectTypeOf<[Constructor<BasePlugin>]>().toMatchTypeOf<TablePluginConfig>();
+expectTypeOf<
+  [Constructor<BasePlugin>, Constructor<BasePlugin>]
+>().toMatchTypeOf<TablePluginConfig>();
+
+class SomeClass {
+  foo = 'bar';
+}
+class LocalPlugin extends BasePlugin<{ Meta: { Table: SomeClass } }> {
+  name = 'local-plugin';
+}
+
+expectTypeOf([LocalPlugin]).toMatchTypeOf<TablePluginConfig>();
+
+/////////////////////////////////////////////
+// Making sure all plugins are subclassed appropriately
+expectTypeOf(LocalPlugin).toMatchTypeOf<Constructor<BasePlugin<any>>>();
+expectTypeOf(ColumnReordering).toMatchTypeOf<Constructor<BasePlugin<any>>>();
+expectTypeOf(LocalPlugin).toMatchTypeOf<Constructor<Plugin<any>>>();
+expectTypeOf(ColumnReordering).toMatchTypeOf<Constructor<Plugin<any>>>();
+
+// Actual plugins match the actual table config
+expectTypeOf([DataSorting]).toMatchTypeOf<TablePluginConfig>();
+expectTypeOf([ColumnReordering]).toMatchTypeOf<TablePluginConfig>();
+expectTypeOf([ColumnResizing]).toMatchTypeOf<TablePluginConfig>();
+expectTypeOf([ColumnVisibility]).toMatchTypeOf<TablePluginConfig>();
+expectTypeOf([StickyColumns]).toMatchTypeOf<TablePluginConfig>();
+
+/////////////////////////////////////////////
+// The various ways to define plugins
+expectTypeOf([
+  DataSorting,
+  ColumnReordering,
+]).toMatchTypeOf<TablePluginConfig>();
+
+const onSort = (_sorts: SortItem<number>[]) => {
+  /* intentionally empty */
+};
+const sorts: SortItem<number>[] = [];
+
+expectTypeOf([DataSorting.with(() => ({}))]).toMatchTypeOf<TablePluginConfig>();
+expectTypeOf([
+  DataSorting.with(() => ({ onSort, sorts })),
+]).toMatchTypeOf<TablePluginConfig>();

package/src/-private/column.ts

@@ -0,0 +1,67 @@
+import { action, get } from '@ember/object';
+import { isEmpty } from '@ember/utils';
+
+import type { Row } from './row';
+import type { Table } from './table';
+import type { ContentValue } from '@glint/template';
+import type { ColumnConfig } from './interfaces';
+
+const DEFAULT_VALUE = '--';
+const DEFAULT_VALUE_KEY = 'defaultValue';
+const DEFAULT_OPTIONS = {
+  [DEFAULT_VALUE_KEY]: DEFAULT_VALUE,
+};
+
+export class Column<T = unknown> {
+  get Cell() {
+    return this.config.Cell;
+  }
+
+  get key() {
+    return this.config.key;
+  }
+
+  get name() {
+    return this.config.name;
+  }
+
+  constructor(
+    public table: Table<T>,
+    public config: ColumnConfig<T>,
+  ) {}
+
+  @action
+  getValueForRow(row: Row<T>): ContentValue {
+    if (this.config.value) {
+      return this.config.value({ column: this, row });
+    }
+
+    // Cast here, because ember get's types do not support nested keys
+    // even though the real implementation does
+    const value = get(row.data, this.config.key);
+
+    if (isEmpty(value)) {
+      return this.getDefaultValue(row);
+    }
+
+    /**
+     * UNSAFE: casting to ContentValue is incorrect, because we have not
+     *         properly constrained the type of value, (isEmpty doesn't narrow types either)
+     */
+    return value as ContentValue;
+  }
+
+  private getDefaultValue(row: Row<T>) {
+    return this.getOptionsForRow(row)[DEFAULT_VALUE_KEY];
+  }
+
+  @action
+  getOptionsForRow(row: Row<T>) {
+    const defaults = DEFAULT_OPTIONS;
+
+    return {
+      ...defaults,
+      ...this.config.options?.({ column: this, row }),
+    };
+  }
+}

package/src/-private/ember-compat.ts

@@ -0,0 +1,26 @@
+import {
+  dependencySatisfies,
+  importSync,
+  macroCondition,
+} from '@embroider/macros';
+
+import type Owner from '@ember/owner';
+
+interface CompatOwner {
+  getOwner: (context: unknown) => Owner | undefined;
+  setOwner: (context: unknown, owner: Owner) => void;
+}
+
+export const compatOwner = {} as CompatOwner;
+
+if (macroCondition(dependencySatisfies('ember-source', '>=4.12.0'))) {
+  // In no version of ember where `@ember/owner` tried to be imported did it exist
+  // if (macroCondition(false)) {
+  // Using 'any' here because importSync can't lookup types correctly
+  compatOwner.getOwner = (importSync('@ember/owner') as any).getOwner;
+  compatOwner.setOwner = (importSync('@ember/owner') as any).setOwner;
+} else {
+  // Using 'any' here because importSync can't lookup types correctly
+  compatOwner.getOwner = (importSync('@ember/application') as any).getOwner;
+  compatOwner.setOwner = (importSync('@ember/application') as any).setOwner;
+}

package/src/-private/interfaces/column.ts

@@ -0,0 +1,73 @@
+import type { BasePlugin, Plugin } from '../../plugins';
+import type { Column } from '../column';
+import type { Row } from '../row';
+import type { ColumnOptionsFor, SignatureFrom } from './plugins';
+import type { Constructor } from '../private-types';
+import type { ComponentLike, ContentValue } from '@glint/template';
+
+export interface CellContext<T> {
+  column: Column<T>;
+  row: Row<T>;
+}
+
+type ColumnPluginOption<P = Plugin> = P extends BasePlugin
+  ? [Constructor<P>, () => ColumnOptionsFor<SignatureFrom<P>>]
+  : [P | Constructor<P>, () => unknown];
+
+export type CellOptions = {
+  /**
+   * when no value is present for a given set of data for the given column config
+   */
+  defaultValue?: string;
+} & Record<string, unknown>;
+
+export interface ColumnConfig<T = unknown> {
+  /**
+   * the `key` is required for preferences storage, as well as
+   * managing uniqueness of the columns in an easy-to-understand way.
+   *
+   * key may be anything if a `value` is provided, but _should_
+   * be a property-path on each data object passed to the table.
+   *
+   * @example `someObj.property.path`
+   * @example `someProperty`
+   */
+  key: string;
+
+  /**
+   * Optionally provide a function to determine the value of a row at this column
+   */
+  value?: (context: CellContext<T>) => ContentValue;
+
+  /**
+   * Recommended property to use for custom components for each cell per column.
+   * Out-of-the-box, this property isn't used, but the provided type may be
+   * a convenience for consumers of the headless table
+   */
+  Cell?: ComponentLike;
+
+  /**
+   * The name or title of the column, shown in the column heading / th
+   */
+  name?: string;
+
+  /**
+   * Bag of extra properties to pass to Cell via `@options`, if desired
+   */
+  options?: (context: CellContext<T>) => CellOptions;
+
+  /**
+   * Each plugin may provide column options, and provides similar syntax to how
+   * options for the table are specified in the plugins entry,
+   *
+   * ```js
+   * pluginOptions: [
+   *   ColumnVisibility.forColumn(() => ({ isVisible: false })),
+   *   StickyColumns.forColumn(() => ({ sticky: 'right' })),
+   * ],
+   * ```
+   */
+  pluginOptions?: ColumnPluginOption[];
+}
+
+export type ColumnKey<T> = NonNullable<ColumnConfig<T>['key']>;

package/src/-private/interfaces/index.ts

@@ -0,0 +1,7 @@
+export * from './column.ts';
+export * from './modifier.ts';
+export * from './pagination.ts';
+export * from './plugins.ts';
+export * from './preferences.ts';
+export * from './selection.ts';
+export * from './table.ts';

package/src/-private/interfaces/modifier.ts

@@ -0,0 +1,7 @@
+export interface Destructor {
+  (): void;
+}
+
+export interface FunctionModifier<Args extends unknown[]> {
+  (element: HTMLElement, ...args: Args): void | Destructor;
+}

package/src/-private/interfaces/pagination.ts

@@ -0,0 +1,13 @@
+export interface Pagination {
+  formatItemSummary?: (data: {
+    end: number;
+    start: number;
+    totalItems: number;
+  }) => string;
+  onChange: (value: { page: number; pageSize: number }) => Promise<void> | void;
+  page: number;
+  pageSize: number;
+  pageSizeLabel?: string;
+  pageSizes?: number[];
+  totalItems: number;
+}