ember-headless-table 0.0.0 → 1.0.0

package/dist/plugins/-private/base.d.ts

@@ -0,0 +1,267 @@
+import { Table } from "../../table-8e46554b";
+import { ColumnReordering } from "../column-reordering/index";
+import { ColumnVisibility } from "../column-visibility/index";
+import { Class, Constructor } from "../../-private/private-types";
+import { Column, Row } from "../../index";
+import { ColumnMetaFor, ColumnOptionsFor, OptionsFor, Plugin, RowMetaFor, TableMetaFor } from "../../-private/interfaces/index";
+type InstanceOf<T> = T extends Class<infer Instance> ? Instance : T;
+/**
+ * @public
+ *
+ * list of interfaces by feature name that consumers may provide alternative
+ * implementation for
+ */
+interface TableFeatures extends Record<string, unknown | undefined> {
+    /**
+     * @public
+     *
+     * interface for the table meta of a "column visibility plugin"
+     */
+    columnVisibility: InstanceOf<ColumnVisibility['meta']['table']>;
+    /**
+     * @public
+     *
+     * interface for the table meta of a "column order plugin"
+     */
+    columnOrder: InstanceOf<ColumnReordering['meta']['table']>;
+}
+/**
+ * @public
+ *
+ * list of interfaces by feature name that consumers may provide alternative
+ * implementation for
+ */
+interface ColumnFeatures extends Record<string, unknown | undefined> {
+    /**
+     * @public
+     *
+     * interface for the column meta of a "column visibility plugin"
+     */
+    columnVisibility: InstanceOf<ColumnVisibility['meta']['column']>;
+    /**
+     * @public
+     *
+     * interface for the column meta of a "column order plugin"
+     */
+    columnOrder: InstanceOf<ColumnReordering['meta']['column']>;
+}
+/**
+ * @private utility type
+ *
+ */
+type SignatureFrom<Klass extends BasePlugin<any>> = Klass extends BasePlugin<infer Signature> ? Signature : never;
+declare const __Signature__: unique symbol;
+/**
+ * @public
+ *
+ * If your table plugin is a class, you may extend from BasePlugin, which provides
+ * small utility methods and properties for getting the metadata for your plugin
+ * for the table and each column
+ *
+ * One instance of a plugin exists per table
+ */
+declare abstract class BasePlugin<Signature = unknown> implements Plugin<Signature> {
+    protected table: Table;
+    constructor(table: Table);
+    /**
+     * @private (secret)
+     *
+     * Because classes are kind of like interfaces,
+     * we need "something" to help TS know what a Resource is.
+     *
+     * This isn't a real API, but does help with type inference
+     * with the SignatureFrom utility above
+     */
+    [__Signature__]: Signature;
+    /**
+     * Helper for specifying plugins on `headlessTable` with the plugin-level options
+     */
+    /**
+     * Helper for specifying plugins on `headlessTable` with the plugin-level options
+     */
+    static with<T extends BasePlugin<any>>(this: Constructor<T>, configFn: () => OptionsFor<SignatureFrom<T>>): [Constructor<T>, () => OptionsFor<SignatureFrom<T>>];
+    /**
+     * Helper for specifying column-level configurations for a plugin on `headlessTable`'s
+     * columns option
+     */
+    /**
+     * Helper for specifying column-level configurations for a plugin on `headlessTable`'s
+     * columns option
+     */
+    static forColumn<T extends BasePlugin<any>>(this: Constructor<T>, configFn: () => ColumnOptionsFor<SignatureFrom<T>>): [Constructor<T>, () => ColumnOptionsFor<SignatureFrom<T>>];
+    meta?: {
+        column?: Constructor<ColumnMetaFor<Signature>>;
+        table?: Constructor<TableMetaFor<Signature>>;
+        row?: Constructor<RowMetaFor<Signature>>;
+    };
+    abstract name: string;
+    static features?: string[];
+    static requires?: string[];
+}
+declare const preferences: {
+    /**
+     * @public
+     *
+     * returns an object for getting and setting preferences data
+     * based on the column (scoped to key)
+     *
+     * Only the provided plugin will have access to these preferences
+     * (though, if other plugins can guess how the underlying plugin access
+     * works, they can access this data, too. No security guaranteed)
+     */
+    forColumn<P extends BasePlugin<any>, Data = unknown>(column: Column<Data>, klass: Class<P>): {
+        /**
+         * delete an entry on the underlying `Map` used for this column-plugin pair
+         */
+        delete(key: string): void | undefined;
+        /**
+         * get an entry on the underlying `Map` used for this column-plugin pair
+         */
+        get(key: string): unknown;
+        /**
+         * set an entry on the underlying `Map` used for this column-plugin pair
+         */
+        set(key: string, value: unknown): void;
+    };
+    /**
+     * @public
+     *
+     * returns an object for getting and setting preferences data
+     * based on the table (scoped to the key: "table")
+     *
+     * Only the provided plugin will have access to these preferences
+     * (though, if other plugins can guess how the underlying plugin access
+     * works, they can access this data, too. No security guaranteed)
+     */
+    forTable<P_1 extends BasePlugin<any>, Data_1 = unknown>(table: Table<Data_1>, klass: Class<P_1>): {
+        /**
+         * delete an entry on the underlying `Map` used for this column-plugin pair
+         */
+        delete(key: string): void | undefined;
+        /**
+         * get an entry on the underlying `Map` used for this column-plugin pair
+         */
+        get(key: string): unknown;
+        /**
+         * set an entry on the underlying `Map` used for this column-plugin pair
+         */
+        set(key: string, value: unknown): void | undefined;
+    };
+};
+/**
+ * if a `requester` is not provided,
+ * Get the columns for the table, considering any and all plugins that could modify columns.
+ *
+ * If you are an end-consumer of ember-headless-table, this is the function to use.
+ * If you are a plugin-author, you'll want to pass your plugin class as the second parameter.
+ *
+ * For a given plugin, `requester`, determine what columns should be returned.
+ * Since multiple plugins could be used in a table, there is an implicit hierarchy of
+ * column modifications that can occur from each of those plugins.
+ *
+ * If a plugin defines other plugins as either *requirements* or *optional requirements*,
+ * and that upstream plugin defines a `columns` property, then those columns will be returned here.
+ *
+ * This works recursively up the plugin tree up until a plugin has no requirements, and then
+ * all columns from the table are returned.
+ */
+declare function columnsFor<DataType = any>(table: Table<DataType>, requester?: Plugin<any> | undefined): Column<DataType>[];
+declare const columns: {
+    for: typeof columnsFor;
+    /**
+     * for a given current or reference column, return the column that
+     * is immediately next, or to the right of that column.
+     *
+     * If a plugin class is provided, the hierarchy of column list modifications
+     * will be respected.
+     */
+    next: <Data = unknown>(current: Column<Data>, requester?: Plugin<any>) => Column<Data> | undefined;
+    /**
+     * for a given current or reference column, return the column that
+     * is immediately previous, or to the left of that column.
+     *
+     * If a plugin class is provided, the hierarchy of column list modifications
+     * will be respected.
+     */
+    previous: <Data_1 = unknown>(current: Column<Data_1>, requester?: Plugin<any>) => Column<Data_1> | undefined;
+    /**
+     * for a given current or reference column, return the columns that
+     * should appear before, or to the left of that column.
+     *
+     * if a plugin class is provided, the hierarchy of column list modifications
+     * will be respected.
+     */
+    before: <Data_2 = unknown>(current: Column<Data_2>, requester?: Plugin<any>) => Column<Data_2>[];
+    /**
+     * for a given current or reference column, return the columns that
+     * should appear after, or to the right of that column.
+     *
+     * if a plugin class is provided, the hierarchy of column list modifications
+     * will be respected.
+     */
+    after: <Data_3 = unknown>(current: Column<Data_3>, requester?: Plugin<any>) => Column<Data_3>[];
+};
+declare const meta: {
+    /**
+     * @public
+     *
+     * For a given column and plugin, return the meta / state bucket for the
+     * plugin<->column instance pair.
+     *
+     * Note that this requires the column instance to exist on the table.
+     */
+    forColumn<P extends BasePlugin<any>, Data = unknown>(column: Column<Data>, klass: Class<P>): ColumnMetaFor<SignatureFrom<P>>;
+    /**
+     * @public
+     *
+     * For a given row and plugin, return the meta / state bucket for the
+     * plugin<->row instance pair.
+     *
+     * Note that this requires the row instance to exist on the table.
+     */
+    forRow<P_1 extends BasePlugin<any>, Data_1 = unknown>(row: Row<Data_1>, klass: Class<P_1>): RowMetaFor<SignatureFrom<P_1>>;
+    /**
+     * @public
+     *
+     * For a given table and plugin, return the meta / state bucket for the
+     * plugin<->table instance pair.
+     */
+    forTable<P_2 extends BasePlugin<any>, Data_2 = unknown>(table: Table<Data_2>, klass: Class<P_2>): TableMetaFor<SignatureFrom<P_2>>;
+    /**
+     * Instead of finding meta based on column or table instances,
+     * you can search for meta based on feature strings, such as `columnWidth`
+     */
+    withFeature: {
+        /**
+         * @public
+         *
+         * for a given column and feature name, return the "ColumnMeta" for that feature.
+         * This is useful when plugins may depend on one another but may not necessarily care which
+         * plugin is providing what behavior.
+         *
+         * For example, multiple column-focused plugins may care about width or visibility
+         */
+        forColumn<FeatureName extends string, Data_3 = unknown>(column: Column<Data_3>, featureName: FeatureName): ColumnFeatures[FeatureName];
+        /**
+         * @public
+         *
+         * for a given table and feature name, return the "TableMeta" for that feature.
+         * This is useful when plugins may depend on one another but may not necessarily care
+         * which plugin is providing that behavior.
+         *
+         * For example, multiple column-focused plugins may care about width or visibility.
+         */
+        forTable<FeatureName_1 extends string, Data_4 = unknown>(table: Table<Data_4>, featureName: FeatureName_1): TableFeatures[FeatureName_1];
+    };
+};
+declare const options: {
+    /**
+     * @public
+     *
+     * For a given table and plugin, return the options, if any were given from the user
+     * during construction of the table.
+     */
+    forTable<P extends BasePlugin<any>, Data = unknown>(table: Table<Data>, klass: Class<P>): Partial<OptionsFor<SignatureFrom<P>>>;
+    forColumn<P_1 extends BasePlugin<any>, Data_1 = unknown>(column: Column<Data_1>, klass: Class<P_1>): Partial<ColumnOptionsFor<SignatureFrom<P_1>>>;
+};
+export { TableFeatures, ColumnFeatures, SignatureFrom, BasePlugin, preferences, columns, meta, options };