@universal-ember/table 3.0.0 → 3.0.1

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

@@ -0,0 +1,349 @@
+/**
+ * NOTE:
+ *  Empty, EmptyObject, and GetOrElse are copied from @glimmer/component
+ */
+
+import type { Constructor } from '../../-private/private-types.ts';
+import type { Column, Row, Table } from '../../index.ts';
+import type { Destructor } from '../../-private/interfaces';
+
+type DataTypeOf<T> = T extends Table<infer DataType> ? DataType : T;
+
+/**
+ * @private utility class
+ *
+ * This class exists because there isn't a way to, in TS,
+ * get access to static properties from an instance type
+ */
+export type PluginClass<PluginType> = PluginType & {
+  new: (...args: unknown[]) => PluginType;
+  features?: string[];
+  requires?: string[];
+};
+
+export type PluginSubclassInstance<PluginType> = PluginType & {
+  constructor: PluginClass<PluginType>;
+};
+
+/**
+ * @public
+ *
+ * The data passed to a plugin's column APIs
+ */
+export interface ColumnApi<T extends Table = Table> {
+  column: Column<DataTypeOf<T>>;
+  table: T;
+}
+
+/**
+ * @public
+ *
+ * The data passed to a plugin's row APIs
+ */
+export interface RowApi<T extends Table = Table> {
+  row: Row<DataTypeOf<T>>;
+  table: T;
+}
+
+/**
+ * @private utility type
+ *
+ * Note that this exists here, and the Plugin interface exists in general
+ * because we need to derive types in a static context on BasePlugin,
+ * and the source of types need to exist somewhere other than BasePlugin,
+ * so that:
+ * - inference will work
+ * - we avoid infinite recursive type definitions
+ */
+export type SignatureFrom<Klass extends Plugin<any>> =
+  Klass extends Plugin<infer Signature> ? Signature : never;
+
+/**
+ * @public
+ *
+ * Table plugins are stateless objects that optionally provide hooks based on what
+ * the plugin wishes to modify.
+ *
+ * If state is desired, Metadata classes may be provided to manage that state.
+ * As a convenience, when the meta classes are instantiated, they'll be given the same
+ * `owner` as everything else in the application, so service injection will be available
+ * within the meta class instances.
+ *
+ * A plugin can provide components that the consuming Table can opt in to rendering.
+ * (though, often these components will be required to be rendered for the plugin to work)
+ *
+ * a `Plugin` has one type argument:
+ * - Signature - which can provide optional information about the Meta/State and Options the plugin can take
+ *
+ *   Any particular plugin instantiation will have at most 1 instance of their TableMeta
+ *   and `n` instances of their ColumnMeta, where `n` is at most the number of columns.
+ */
+export interface Plugin<Signature = unknown> {
+  /**
+   * Unique name for the plugin.
+   * - only one plugin of the same name is allowed
+   * - the name is used for storing preferences / serializable information
+   */
+  name: string;
+
+  /**
+   * Some plugins may require that other plugins be present.
+   * and because plugins can be interchangeable, the features implemented
+   * by those plugins must be declared via strings so that we can have
+   * a semi-stable reference that isn't tied to object equality or anything like that.
+   *
+   * This enables, for example, the StickyColumns plugin to work with different implementations of the ColumnResizing plugin (such as one
+   * might have between an aria-grid and a data table)
+   */
+  features?: string[];
+
+  /**
+   * List of features to lookup "somewhere" in the list of plugins
+   * order does not matter.
+   */
+  requires?: string[];
+
+  /**
+   * Optional state that this plugin may or may not choose to use
+   *
+   * columns will each have an instance of meta.column.
+   * the table will have only one instance of meta.table.
+   */
+  meta?: {
+    /**
+     * @public
+     *
+     * Specifies the class definition to use for storing column-related state / behavior for this plugin
+     */
+    column?: Constructor<ColumnMetaFor<Signature>>;
+
+    /**
+     * @public
+     *
+     * Specifies the class definition to use for storing table-related state / behavior for this plugin
+     */
+    table?: Constructor<TableMetaFor<Signature>>;
+
+    /**
+     * @public
+     *
+     * Specifies the class definition to use for storing the row-related state / behavior for this plugin
+     */
+    row?: Constructor<RowMetaFor<Signature>>;
+  };
+
+  /**
+   * @public
+   * @kind Column property
+   *
+   * Specify a modifier setup/teardown function to attach to each of the header cells
+   *
+   * Can be used to add / remove attributes, event listeners, etc
+   */
+  headerCellModifier?: (
+    element: HTMLElement,
+    ...args: [ColumnApi<Table<any>>]
+  ) => void | Destructor;
+
+  /**
+   * @public
+   * @kind Row property
+   *
+   * Specify a modifier setup/teardown function to attach to each of the rows
+   *
+   * Can be used to add / remove attributes, event listeners, etc
+   */
+  rowModifier?: (
+    element: HTMLElement,
+    ...args: [RowApi<Table<any>>]
+  ) => void | Destructor;
+
+  /**
+   * @public
+   * @kind Table hook
+   *
+   * Specify a modifier setup/teardown function to attach to the table's containing element
+   */
+  containerModifier?: (
+    element: HTMLElement,
+    ...args: [Table<any>]
+  ) => void | Destructor;
+
+  /**
+   * @public
+   * @kind Table Hook
+   *
+   * If the plugin has state, this should be used to reset that state
+   */
+  reset?: () => void;
+
+  /**
+   * @public
+   * @kind Table Hook
+   *
+   * A plugin may change the columns order, visibility, etc.
+   * By implementing this getter, this plugin's
+   * `columns` property will be used by other plugins via
+   * the `columns.for(table, RequestingPlugin)` api.
+   *
+   * For the end-consumer, they may choose to do
+   * `columns.for(table)`, which will aggregate all column modifications
+   * from all plugins.
+   *
+   * As always, `table.columns` is the way to get the unmodified list of columns.
+   */
+  columns?: Column<any>[];
+}
+
+/**
+ * @private utility type
+ */
+type GetOrElse<Obj, K, Fallback> = K extends keyof Obj ? Obj[K] : Fallback;
+
+/**
+ * @public
+ *
+ * utility class to help with autocompletion / documentation
+ * in the editor while while defining the signature of custom plugins.
+ */
+export interface PluginSignature {
+  /**
+   * Meta is how plugins can manage per-{table,columns,rows}
+   * state, event listeners, and general public API
+   */
+  Meta?: {
+    /**
+     * If a plugin has Table meta/state,
+     * the shape of that state can be described here
+     */
+    Table?: unknown;
+    /**
+     * If a plugin has Column meta/state,
+     * the shape of that state can be described here
+     */
+    Column?: unknown;
+    /**
+     * If a plugin has Row meta/state,
+     * the shape of that state can be described here
+     */
+    Row?: unknown;
+  };
+  Options?: {
+    /**
+     * If a plugin has options configurable for the whole table,
+     * those can be specified here.
+     *
+     * These are passed via the the `withOptions` API
+     *
+     * ```js
+     * headlessTable(this?, {
+     *   // ...
+     *   plugins: [
+     *     MyPlugin.withOptions(() => {
+     *       // the return value here is this is Signature['Options']['Plugin']
+     *       return {};
+     *     })
+     *   ]
+     * })
+     * ```
+     */
+    Plugin?: unknown;
+    /**
+     * If a plugin has options configurable per column,
+     * those can be specified here
+     *
+     * These are passed via the the `forColumn` API
+     *
+     * ```js
+     * headlessTable(this?, {
+     *   // ...
+     *   columns: () => [
+     *     MyPlugin.forColumn(() => {
+     *       // the return value here is this is Signature['Options']['Column']
+     *       return {};
+     *     })
+     *   ]
+     * })
+     * ```
+     */
+    Column?: unknown;
+  };
+}
+
+/**
+ * @private default type
+ *
+ * Describes the shape of all the dynamic parts of a Plugin.
+ *
+ * There are no row options, because rows are not statically configurable.
+ */
+export interface DefaultPluginSignature {
+  Meta: {
+    Row: unknown;
+    Column: unknown;
+    Table: unknown;
+  };
+  Options: {
+    Plugin: unknown;
+    Column: unknown;
+  };
+}
+
+/**
+ * @private utility type
+ */
+export type TableMetaFor<Signature> = Signature extends {
+  Meta: { Table: unknown };
+}
+  ? GetOrElse<Signature['Meta'], 'Table', never>
+  : never;
+
+/**
+ * @private utility type
+ */
+export type ColumnMetaFor<Signature> = Signature extends {
+  Meta: { Column: unknown };
+}
+  ? GetOrElse<Signature['Meta'], 'Column', never>
+  : never;
+
+/**
+ * @private utility type
+ */
+export type RowMetaFor<Signature> = Signature extends { Meta: { Row: unknown } }
+  ? GetOrElse<Signature['Meta'], 'Row', never>
+  : never;
+
+/**
+ * @private utility type
+ */
+export type OptionsFor<Signature> = Signature extends { Options: object }
+  ? GetOrElse<Signature['Options'], 'Plugin', EmptyObject>
+  : EmptyObject;
+
+/**
+ * @private utility type
+ */
+export type ColumnOptionsFor<Signature> = Signature extends { Options: object }
+  ? GetOrElse<Signature['Options'], 'Column', EmptyObject>
+  : EmptyObject;
+
+// Type-only "symbol" to use with `EmptyObject` below, so that it is *not*
+// equivalent to an empty interface.
+declare const Empty: unique symbol;
+
+/**
+ * This provides us a way to have a "fallback" which represents an empty object,
+ * without the downsides of how TS treats `{}`. Specifically: this will
+ * correctly leverage "excess property checking" so that, given a component
+ * which has no named args, if someone invokes it with any named args, they will
+ * get a type error.
+ *
+ * @internal This is exported so declaration emit works (if it were not emitted,
+ *   declarations which fall back to it would not work). It is *not* intended for
+ *   public usage, and the specific mechanics it uses may change at any time.
+ *   The location of this export *is* part of the public API, because moving it
+ *   will break existing declarations, but is not legal for end users to import
+ *   themselves, so ***DO NOT RELY ON IT***.
+ */
+export type EmptyObject = { [Empty]?: true };

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

@@ -0,0 +1,82 @@
+export interface PreferencesAdapter {
+  persist?(key: string, data?: TablePreferencesData): void;
+  restore?(key: string): TablePreferencesData | undefined;
+}
+
+/**
+ * The root preferences object
+ *
+ * This object is serialized to JSON for your `PreferencesAdapter` to consume.
+ * This could allow for saving the data off to an API or local storage.
+ */
+export interface TablePreferencesData {
+  /**
+   * Every plugin has its own namespace for preferences storage.
+   *
+   * This is so that plugins can not worry about colliding with other plugins'
+   * keys within the preferences. For example: multiple plugins may use "enabled"
+   */
+  plugins?: Registry;
+}
+
+/**
+ * A type registry for @universal-ember/table Plugin's Preferences.
+ * Meant to be declaration-merged so string lookups resolve to the correct type.
+ *
+ * And so that accessing the full "preferences" object from "persist"
+ * and within "restore" can be fully typed.
+ * This also helps out with Glint, as `unknown` types are not allowed to be rendered
+ *
+ * As a plugin author, to help define what your preferences shape is, you may
+ * ```ts
+ * import { type PluginPreferences } from '@universal-ember/table/plugins';
+ *
+ * interface SortingPreferences extends PluginPreferences {
+ *
+ * }
+ *
+ * declare module '@universal-ember/table/plugins' {
+ *   interface Registry {
+ *     // The key *must* match the same of the class
+ *     Sorting: SortingPreferences;
+ *   }
+ * }
+ * ```
+ */
+export interface Registry {}
+
+export type PluginPreferenceFor<PluginName> = PluginName extends keyof Registry
+  ? Registry[PluginName] & PluginPreferences
+  : PluginPreferences;
+
+export type PreferencesTableKey<PluginName> =
+  keyof PluginPreferenceFor<PluginName>['table'];
+
+export type PreferencesTableValues<PluginName> =
+  PluginPreferenceFor<PluginName>['table'][PreferencesTableKey<PluginName>];
+export type PreferencesColumnValues<PluginName> =
+  PluginPreferenceFor<PluginName>['columns'][keyof PluginPreferenceFor<PluginName>['columns']];
+/**
+ * Preferences for a column may store a map of key-value pairs
+ * for each of
+ * - the table
+ * - each column
+ */
+export interface PluginPreferences {
+  /**
+   * A plugin's preferences for the table can be any
+   * string -> stringifyable mapping
+   */
+  table: Record<string, unknown>;
+  /**
+   * preferences for a plugin's columns-of-interest are mapped out by
+   * the column's key
+   */
+  columns: {
+    /**
+     * For any particular column that a plugin may desire to store preferences on,
+     * the data can be any string -> stringifyable mapping
+     */
+    [columnKey: string]: Record<string, unknown>;
+  };
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Types minimally replicated here so we don't need to depend on the package that
+ * actually defines these types
+ *
+ * This also enables a much broader variety of implementations as these interfaces
+ * describe only what's needed by the headless table, and not the concrete implementation
+ */
+type CurrentState<T> =
+  | {
+      state: 'ALL' | 'NONE';
+    }
+  | {
+      state: 'SOME';
+      includeItems: T[];
+    }
+  | {
+      state: 'ALL_EXCEPT';
+      excludeItems: T[];
+    };
+
+/**
+ * A table can provide a `Selection` object that matches this API
+ */
+export interface Selection<Item = object> {
+  get selected(): Item[];
+  get currentState(): CurrentState<Item>;
+  get isIndeterminate(): boolean;
+  get isAllSelected(): boolean;
+  get numSelected(): number;
+  get numTotal(): number;
+  isSelected(item: Item): boolean;
+  selectItem(item: Item): void;
+  toggleItem(item: Item): void;
+  toggleAll(): void;
+  selectAll(): void;
+  deselectAll(): void;
+  deselectItem(item: Item): void;
+}

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

@@ -0,0 +1,121 @@
+import type { Plugins } from '../../plugins/-private/utils';
+import type { ColumnConfig } from './column';
+import type { Pagination } from './pagination';
+import type { PreferencesAdapter } from './preferences';
+import type { Selection } from './selection';
+
+export interface TableMeta {
+  totalRowCount?: number;
+  totalRowsSelectedCount?: number;
+}
+
+export interface TableConfig<DataType> {
+  /**
+   * Configuration describing how the table will crawl through `data`
+   * and render it. Within this `columns` config, there will also be opportunities
+   * to set the behavior of columns when rendered
+   */
+  columns: () => ColumnConfig<DataType>[];
+  /**
+   * The data to render, as described via the `columns` option.
+   *
+   * This data may or may not match the shape requested by the columns configuration.
+   * When a key-value pair matches what a column config requests, the data will be rendered.
+   * When a key-value pair is misisng, a fallback or empty representation of a value will be
+   * shown instead.
+   */
+  data: () => DataType[];
+
+  /**
+   * A collection of plugins for use in extending table behavior.
+   * plugins have a collection of hooks and properties to use, but for anything
+   * requiring user interaction there will be manual connecting.
+   *
+   * The instance for each plugin can be accessed via HeadlessTable's `pluginOf(<Plugin>)`
+   * method, where it takes the plugin constructor/class/object for lookup purposes.
+   *
+   * Some plugins may require setting options for hooking into behavior
+   * provided by the plugin (for example sorting).
+   *
+   * Example:
+   * ```js
+   * import { DataSorting } from '@universal-ember/table/plugins/data-sorting';
+   * import { ColumnResizing }  from '@universal-ember/table/plugins/column-resizing';
+   *
+   *  ...
+   *
+   *  plugins: [
+   *    DataSorting.with(() => {
+   *      return {
+   *        sorts: [array of sorts],
+   *        onSort: this.doThingWhenSortsChange,
+   *      };
+   *    }),
+   *    ColumnResizing.with(() => {
+   *      return {
+   *        enabled: true,
+   *      }
+   *    }),
+   *  ]
+   * ```
+   *
+   * However, for plugins with no needed options, the list can be simplified:
+   * ```js
+   * import { ColumnResizing }  from '@universal-ember/table/plugins/column-resizing';
+   * import { StickyColumns }  from '@universal-ember/table/plugins/sticky-columns';
+   *
+   *  ...
+   *
+   *  plugins: [
+   *    ColumnResizing,
+   *    StickyColumns,
+   *  ]
+   * ```
+   */
+  plugins?: Plugins;
+
+  // Bulk selection plugin?
+  //   - maybe for providing each row with a checkbox, and some hooks for interacting with
+  //     a potential pagination plugin
+  bulkSelection?: Selection;
+  isCheckboxSelectable?: boolean;
+
+  // Row selection plugin?
+  //   - maybe for clicking on a row to open a side panel?
+  isRowSelectable?: boolean;
+  rowSelection?: () => DataType;
+  onRowSelectionChange?: (selection: DataType | undefined) => void;
+
+  // Uncategorized
+  meta?: TableMeta;
+  pagination?: Pagination;
+
+  /**
+   * Foundational to tables is how to store settings within them.
+   * The `key` is meant to identify a particular kind of table. For example, if
+   * you have a table representing "blog posts", your table key may be "blog-posts".
+   *
+   * And most importantly, the `adapter` is how you load and save the preferences.
+   * This may bo to local storage, or some API.
+   */
+  preferences?: {
+    /**
+     * What to name the table in the preferences storage of your choice.
+     * Any string is valid provided that the storage adapter of your choice supports
+     * the format.
+     *
+     * For example, if you have a table of "blog posts", the preferences key might be
+     * `"all-blog-posts"`
+     */
+    key: string;
+    /**
+     * Configuration for how you wish to `persist` and `restore` the configuration for your table.
+     *
+     * `persist` may be async as it is a fire-and-forget type of action.
+     *
+     * However, `restore` must be synchronous, as this is a blocking operation for rendering the table.
+     * So it's best to load up the table preferences before rendering a table.
+     */
+    adapter?: PreferencesAdapter;
+  };
+}

package/src/-private/js-helper.ts

@@ -0,0 +1,65 @@
+import { Table } from './table.ts';
+
+import type { TableConfig } from './interfaces';
+
+type Args<T> =
+  | [destroyable: object, options: TableConfig<T>]
+  | [options: TableConfig<T>];
+
+/**
+ * Represents a UI-less version of a table
+ *
+ * _For use for building tables in ui frameworks_.
+ *
+ * @example
+ * ```js
+ * import { use } from 'ember-resources';
+ * import { headlessTable } '@universal-ember/table';
+ *
+ * class MyImplementation {
+ *   @use table = headlessTable({
+ *     // your config here
+ *   })
+ * }
+ * ```
+ */
+export function headlessTable<T = unknown>(options: TableConfig<T>): Table<T>;
+
+/**
+ * Represents a UI-less version of a table
+ *
+ * _For use for building tables in ui frameworks_.
+ *
+ * @example
+ * ```js
+ * import { headlessTable } '@universal-ember/table';
+ *
+ * class MyImplementation {
+ *   table = headlessTable(this, {
+ *     // your config here
+ *   })
+ * }
+ * ```
+ *
+ */
+export function headlessTable<T = unknown>(
+  destroyable: object,
+  options: TableConfig<T>,
+): Table<T>;
+
+export function headlessTable<T = unknown>(...args: Args<T>): Table<T> {
+  if (args.length === 2) {
+    const [destroyable, options] = args;
+
+    /**
+     * If any "root level" config changes, we need to throw-away everything.
+     * otherwise individual-property reactivity can be managed on a per-property
+     * "thunk"-basis
+     */
+    return Table.from<Table<T>>(destroyable, () => options);
+  }
+
+  const [options] = args;
+
+  return Table.from<Table<T>>(() => options);
+}