@timlassiter11/yatl 0.3.22 → 1.0.1

package/dist/data-table.d.mts

@@ -1,626 +0,0 @@
-type NestedKeyOf<ObjectType> = ObjectType extends object ? {
-    [Key in keyof ObjectType & (string | number)]: NonNullable<ObjectType[Key]> extends any[] ? `${Key}` : NonNullable<ObjectType[Key]> extends object ? // Recurse with the non-nullable type
-    `${Key}` | `${Key}.${NestedKeyOf<NonNullable<ObjectType[Key]>>}` : `${Key}`;
-}[keyof ObjectType & (string | number)] : never;
-declare const createRegexTokenizer: (exp?: string) => (value: string) => {
-    value: string;
-    quoted: boolean;
-}[];
-
-interface VirtualScrollOptions {
-    generator: (index: number) => HTMLElement;
-    container: HTMLElement;
-    element?: HTMLElement;
-    nodePadding?: number;
-}
-interface IVirtualScroll {
-    start(rowCount: number): void;
-    stop(): void;
-    scrollToIndex(index: number): void;
-    scrollToPx(px: number): void;
-}
-interface IVirtualScrollConstructor {
-    new (options: VirtualScrollOptions): IVirtualScroll;
-}
-
-/**
- * Defines options for loading data into the table
- * */
-interface LoadOptions {
-    /** If the data should replace or be added to the end of the current data */
-    append?: boolean;
-    /** If the current scroll position should be kept */
-    keepScroll?: boolean;
-}
-/**
- * Defines the possible sorting orders for columns.
- */
-type SortOrder = 'asc' | 'desc';
-/**
- * Callback for formatting a row's  HTML element.
- * @param row - The row data.
- * @param element - The row element.
- */
-type RowFormatterCallback<T> = (row: T, element: HTMLElement) => void;
-/**
- * Callback for formatting the value of a cell.
- * Called when the cell is created and when exporting to CSV.
- * @param value - The value of the cell.
- * @param row - The row data.
- */
-type ValueFormatterCallback<T> = (value: any, row: T) => string | null;
-/**
- * Callback for formatting a cell's HTML element.
- * Called when the cell is created but NOT when exporting to CSV.
- * @param value - The value of the field.
- * @param row - The row data.
- * @param element - The cell element.
- */
-type CellFormatterCallback<T> = (value: any, row: T, element: HTMLElement) => void;
-/**
- * Callback for comparing two values.
- * @param a - The first value.
- * @param b - The second value.
- * @returns A negative number if a < b, a positive number if a > b, or 0 if they are equal.
- */
-type ComparatorCallback = (a: any, b: any) => number;
-/**
- * Callback for caching the sort value of a field
- * This function should derive a comparable value (often numerical or lowercase string) from the field's original value, to be used during sorting.
- * @param value - The value of the field.
- * @returns The derived value for sorting (e.g., a number or a standardized string).
- */
-type SortValueCallback = (value: any) => number | string;
-/**
- * A filter object containing keys for the fields to be filtered,
- * and the values used to compare against.
- */
-type Filters<T> = Partial<{
-    [K in NestedKeyOf<T>]: any;
-}>;
-/**
- * A single query token derived from a larger string
- */
-interface QueryToken {
-    /**
-     * The value to use for the token
-     */
-    value: string;
-    /**
-     * If the token should be treated as quoted.
-     * Quoted tokens are searched for exactly, no partial matches.
-     */
-    quoted: boolean;
-}
-/**
- * Callback for tokenizing a value into a list of string tokens.
- * @param value - The value to tokenize.
- * @returns An array of tokens.
- */
-type TokenizerCallback = (value: any) => QueryToken[];
-/**
- * Callback for filtering a row.
- * @param row - The row data.
- * @param index - The index of the row.
- * @returns True if the row matches the filter, false otherwise.
- */
-type FilterCallback<T> = (row: T, index: number) => boolean;
-/**
- * Callback for filtering a field value against the filter data.
- * @param value - The value to filter.
- * @param filter - The filter to apply.
- * @returns True if the value matches the filter, false otherwise.
- */
-type ColumnFilterCallback = (value: any, filter: any) => boolean;
-/**
- * Represents the current sort state
- */
-interface SortState {
-    /**
-     * The sort order
-     */
-    order: SortOrder;
-    /**
-     * The sort priority.
-     * Lower priority means
-     */
-    priority: number;
-}
-/**
- * Column options for the table.
- */
-interface ColumnOptions<T> {
-    /**
-     * The field name in the data object.
-     */
-    field: NestedKeyOf<T>;
-    /**
-     * The title to display in the header.
-     */
-    title?: string;
-    /**
-     * Whether the column is sortable.
-     */
-    sortable?: boolean;
-    /**
-     * Whether the column is searchable.
-     */
-    searchable?: boolean;
-    /**
-     * Whether the column's data should be tokenized for searching.
-     */
-    tokenize?: boolean;
-    /**
-     * Whether the column should be resizable.
-     */
-    resizable?: boolean;
-    /**
-     * A function to format the value for display.
-     */
-    valueFormatter?: ValueFormatterCallback<T> | null;
-    /**
-     * A function to format the element for display.
-     */
-    elementFormatter?: CellFormatterCallback<T> | null;
-    /**
-     * A function to use for sorting the column.
-     * This overrides the default sorting behavior.
-     */
-    sorter?: ComparatorCallback | null;
-    /**
-     * A function to derive a comparable value from the cell's original value, specifically for sorting this column.
-     * This can be used to preprocess and cache values (e.g., convert to lowercase, extract numbers) before comparison.
-     */
-    sortValue?: SortValueCallback | null;
-    /**
-     * A custom function to determine if a cell's value in this column matches a given filter criterion.
-     * This is used when `DataTable.filter()` is called with an object-based filter that targets this column's field.
-     */
-    filter?: ColumnFilterCallback | null;
-}
-/**
- * Represents the current state of a column.
- */
-interface ColumnState<T> {
-    /**
-     * The unique field name of the column.
-     */
-    field: NestedKeyOf<T>;
-    /**
-     * The current visibility of the column.
-     */
-    visible: boolean;
-    /**
-     * The current sort order of the column.
-     */
-    sortState?: SortState | null;
-    /**
-     * The currently set width of the column in pixels.
-     */
-    width?: number | null;
-}
-/**
- * Defines CSS classes to be applied to different parts of the table.
- */
-interface TableClasses {
-    /**
-     * Classes for the scroller element.
-     */
-    scroller?: string | string[];
-    /**
-     * Classes for the thead element.
-     */
-    thead?: string | string[];
-    /**
-     * Classes for the tbody element.
-     */
-    tbody?: string | string[];
-    /**
-     * Classes for each table row element.
-     */
-    tr?: string | string[];
-    /**
-     * Classes for each header element.
-     */
-    th?: string | string[];
-    /**
-     * Classes for each cell element.
-     */
-    td?: string | string[];
-    /**
-     * Classes for the mark elements used to highligh search results.
-     */
-    mark?: string | string[];
-}
-/**
- * Options for configuring the table.
- */
-interface TableOptions<T> {
-    /**
-     * Configures virtual scrolling.
-     */
-    virtualScroll?: boolean | number;
-    /**
-     * Whether to highlight search results in the table cells.
-     */
-    highlightSearch?: boolean;
-    /**
-     * Whether the search query should be tokenized.
-     */
-    tokenizeSearch?: boolean;
-    /**
-     * Whether search results should be scored or not.
-     * Scoring is very computationally expensive...
-     */
-    enableSearchScoring?: boolean;
-    /**
-     * Whether columns should be rearrangeable by drag and drop.
-     */
-    rearrangeable?: boolean;
-    /**
-     * Additional fields to include in the search.
-     * Used for fields that are not displayed as columns.
-     */
-    extraSearchFields?: NestedKeyOf<T>[];
-    /**
-     * A placeholder to use for null or undefined values.
-     */
-    emptyValuePlaceholder?: string;
-    /**
-     * The text to display when there is no data in the table.
-     */
-    noDataText?: string;
-    /**
-     * The text to display when there are no matching records after filtering or searching.
-     */
-    noMatchText?: string;
-    /**
-     * Custom CSS classes to apply to various table elements.
-     */
-    classes?: TableClasses;
-    /**
-     * A function to format each row's HTML element.
-     */
-    rowFormatter?: RowFormatterCallback<T> | null;
-    /**
-     * A function to use for tokenizing values for searching.
-     */
-    tokenizer?: TokenizerCallback;
-    /**
-     * A specific virtual scroll class to use
-     */
-    virtualScrollClass?: IVirtualScrollConstructor;
-}
-/**
- * Represents the current state of the table
- */
-interface TableState<T> {
-    /**
-     * A list of {@link ColumnState}s representing all of the columns in the table.
-     */
-    columns: ColumnState<T>[];
-    /**
-     * The current query applied to the table or null if no query is applied.
-     */
-    searchQuery: string | RegExp | null;
-    /**
-     * The current filters applied to the table or null if no filters are applied.
-     */
-    filters: Filters<T> | FilterCallback<T> | null;
-    /**
-     * The current scroll position of the table
-     */
-    scrollPosition: {
-        top: number;
-        left: number;
-    };
-    /**
-     * The current column order represented as a list of their fields from left to right.
-     */
-    columnOrder: NestedKeyOf<T>[];
-}
-type TableInitOptions<T> = TableOptions<T> & {
-    data?: T[];
-};
-type ColumnInitOptions<T> = ColumnOptions<T> & Partial<ColumnState<T>>;
-type RestorableColumnState<T> = Partial<Omit<ColumnState<T>, 'field'>> & Pick<ColumnState<T>, 'field'>;
-type RestorableTableState<T> = Partial<Omit<TableState<T>, 'columns'>> & {
-    columns?: RestorableColumnState<T>[];
-};
-
-/**
- * Represents a dynamic and interactive table with features like sorting, searching, filtering,
- * column resizing, column rearranging, and virtual scrolling.
- *
- * @example
- * ```ts
- * type DataType = {id: number, name: string, age: number};
- *
- * const dataTable = new DataTable<DataType>('#myTable', [
- *     { field: 'id', title: 'ID', sortable: true },
- *     { field: 'name', title: 'Name', searchable: true },
- *     { field: 'age', title: 'Age', sortable: true, valueFormatter: (value) => `${value} years` }
- *   ], {
- *   data: [
- *     { id: 1, name: 'Alice', age: 30 },
- *     { id: 2, name: 'Bob', age: 24 },
- *   ],
- *   virtualScroll: true,
- *   resizable: true,
- *   rearrangeable: true,
- * });
- * ```
- */
-declare class DataTable<T> extends EventTarget {
-    #private;
-    private static readonly MatchWeights;
-    private readonly DEFAULT_OPTIONS;
-    /**
-     * Initializes a new instance of the DataTable.
-     * @param table - The HTMLTableElement or a CSS selector string for the table.
-     * @param columns - List of {@link ColumnOptions} for the table.
-     * @param options - Optional configuration options for the DataTable.
-     * @throws {SyntaxError} If the table selector does not find an element.
-     * @throws {TypeError} If the provided table element is not an HTMLTableElement or if columns option is not an array.
-     */
-    constructor(table: string | HTMLTableElement, columns: ColumnInitOptions<T>[], options?: TableInitOptions<T>);
-    /**
-     * Gets the current options applied to the table.
-     */
-    get tableOptions(): ConcreteTableOptions<T>;
-    /**
-     * Gets the currently filtered and sorted rows displayed in the table.
-     */
-    get rows(): T[];
-    /**
-     * Gets the underlying data
-     */
-    get data(): T[];
-    /**
-     * Gets the underlying HTMLTableElement managed by this DataTable instance.
-     */
-    get table(): HTMLTableElement;
-    /**
-     * Gets the current state of the table.
-     */
-    getState(): TableState<T>;
-    /**
-     * Restores the table to the provided state.
-     * @param state - The state to restore the table to.
-     */
-    restoreState(state: RestorableTableState<T>): void;
-    updateTableOptions(options: UpdatableTableOptions<T>): void;
-    getColumnOptions(): Required<ColumnOptions<T>>[];
-    getColumnOptions(field: NestedKeyOf<T>): Required<ColumnOptions<T>>;
-    updateColumnOptions(column: NestedKeyOf<T>, options: ColumnOptionsWithoutField<T>): void;
-    /**
-     * Loads data into the table
-     * @param rows - An array of data to be loaded
-     * @param options - Configuration for the load operation
-     */
-    loadData(rows: T[], options?: LoadOptions): void;
-    /**
-     * Displays a message in the table body, typically used for "no data" or "no results" states.
-     * The message is shown in a single row spanning all columns.
-     * @param text - The text or HTML message to display.
-     * @param classes - A string or array of strings for CSS classes to apply to the message row.
-     */
-    showMessage(text: string, ...classes: string[]): void;
-    /**
-     * Clears the current message and dispalsy the normal table data.
-     */
-    clearMessage(): void;
-    /**
-     * Filters rows based on a search query.
-     * The search is performed on columns marked as `searchable` and `extraSearchFields`.
-     * @param query - The search term (string) or a regular expression. An empty string clears the search.
-     */
-    search(query?: string | RegExp | null): void;
-    /**
-     * Applies filters to the table rows.
-     * Filters can be an object where keys are field names and values are the criteria to filter by,
-     * or a callback function that receives a row and its index and returns `true` if the row should be included.
-     * @param filters - An object defining field-based filters or a custom filter callback function.
-     * @throws {TypeError} If `filters` is not an object or a function.
-     */
-    filter(filters?: Filters<T> | FilterCallback<T> | null): void;
-    /**
-     * Sorts the table by a specified column and order.
-     * If `order` is `null`, the sort on this column is removed.
-     * @param colName - The field name of the column to sort by.
-     * @param order - The sort order: 'asc', 'desc', or `null` to remove sorting for this column.
-     */
-    sort(colName: NestedKeyOf<T>, order: SortOrder | null): void;
-    /**
-     * Sets the visibility of a specified column.
-     * @param colName - The field name of the column.
-     * @param visisble - `true` to show the column, `false` to hide it.
-     */
-    setColumnVisibility(colName: NestedKeyOf<T>, visisble: boolean): void;
-    /**
-     * Shows a previously hidden column.
-     * @param field - The field name of the column to show.
-     */
-    showColumn(field: NestedKeyOf<T>): void;
-    /**
-     * Hides a visible column.
-     * @param field - The field name of the column to hide.
-     */
-    hideColumn(field: NestedKeyOf<T>): void;
-    /**
-     * Export the current visible table data to a CSV file.
-     * @param filename - The name of the file to save.
-     * @param all - If `true`, exports all original data (ignoring filters). If `false` (default), exports only the currently visible (filtered and sorted) rows.
-     */
-    export(filename: string, all?: boolean): void;
-    scrollToRow(row: T): void;
-    /**
-     * Scrolls the table to bring the row at the specified original index into view.
-     * @param index - The original index of the row (from the initial dataset).
-     */
-    scrollToOriginalIndex(index: number): void;
-    scrollToFilteredIndex(index: number): void;
-    scrollToPx(px: number): void;
-    /**
-     * Sets the display order of the columns in the table.
-     *
-     * @param fields - An array of field names representing the new order of columns. Columns not included in the array will be placed at the end.
-     * @throws {TypeError} If `fields` is not an array.
-     */
-    setColumnOrder(fields: NestedKeyOf<T>[]): void;
-    /**
-     * Refreshes the table display. This re-applies filters, sorting, and updates headers and rows.
-     */
-    refresh(): void;
-    /**
-     * Finds the original index of the first row where the specified field matches the given value.
-     * This searches through the original, unfiltered dataset.
-     * @param field - The field name within the row data to search.
-     * @param value - The value to match against the field's content.
-     * @returns The original index of the found row, or -1 if no match is found.
-     * @example
-     * ```ts
-     * const index = dataTable.indexOf('id', 12345);
-     * if (index >= 0) {
-     *  dataTable.updateRow({description: "Updated description"}, index);
-     * }
-     * ```
-     */
-    indexOf(field: string, value: any): number;
-    /**
-     * Updates the data of a row at a specific original index.
-     * @param index - The original index of the row to update.
-     * @param data - An object containing the new data to assign to the row. Existing fields will be updated, and new fields will be added.
-     *
-     * @example
-     * ```ts
-     * const index = dataTable.indexOf('id', 12345);
-     * if (index >= 0) {
-     *  dataTable.updateRow(index, {description: "Updated description"});
-     * }
-     * ```
-     */
-    updateRow(index: number, data: Partial<T>): void;
-    /**
-     * Deletes a row at a specific original index from the table.
-     * @param index - The original index of the row to delete.
-     */
-    deleteRow(index: number): void;
-    /**
-     * Executes a callback function without triggering table updates (like re-rendering or event dispatches)
-     * until the callback has completed. This is useful for batching multiple operations.
-     * @param callback - A function to execute. It receives the DataTable instance as its argument.
-     * @example dataTable.withoutUpdates(dt => { dt.sort('name', 'asc'); dt.filter({ age: '>30' }); });
-     */
-    withoutUpdates(callback: (dataTable: DataTable<T>) => void): void;
-    destroy(): void;
-    addEventListener<K extends keyof DataTableEventMap<T>>(type: K, listener: (this: DataTable<T>, ev: CustomEvent<DataTableEventMap<T>[K]>) => any, options?: boolean | AddEventListenerOptions): void;
-    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
-    removeEventListener<K extends keyof DataTableEventMap<T>>(type: K, listener: (this: DataTable<T>, ev: CustomEvent<DataTableEventMap<T>[K]>) => any, options?: boolean | EventListenerOptions): void;
-    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
-    private readonly TABLE_OPTION_CONFIGS;
-    private readonly COLUMN_OPTION_CONFIGS;
-}
-type ConcreteTableClasses = Required<{
-    [K in keyof TableClasses]: string[];
-}>;
-type ConcreteTableOptions<T> = Required<Omit<TableOptions<T>, 'data' | 'classes' | 'virtualScroll'>> & {
-    classes: ConcreteTableClasses;
-    virtualScroll: number;
-};
-type UpdatableTableOptions<T> = TableOptions<T>;
-type ColumnOptionsWithoutField<T> = Omit<ColumnOptions<T>, 'field'>;
-/**
- * Defines the mapping between event names and their detail object types.
- */
-interface DataTableEventMap<T> {
-    'dt.row.clicked': {
-        row: T;
-        index: number;
-        column: NestedKeyOf<T>;
-        originalEvent: MouseEvent;
-    };
-    'dt.rows.changed': object;
-    'dt.col.sort': {
-        column: string;
-        order: SortOrder | null;
-    };
-    'dt.col.visibility': {
-        column: NestedKeyOf<T>;
-        visible: boolean;
-    };
-    'dt.col.resize': {
-        column: NestedKeyOf<T>;
-        width: number;
-    };
-    'dt.col.reorder': {
-        draggedColumn: NestedKeyOf<T>;
-        dropColumn: NestedKeyOf<T>;
-        order: string[];
-    };
-    'dt.search': {
-        query: string | RegExp | null;
-    };
-}
-
-declare class VirtualScroll implements IVirtualScroll {
-    #private;
-    static AVERAGE_RENDER_COUNT: number;
-    constructor({ generator, container, element, nodePadding, }: VirtualScrollOptions);
-    private get rowHeight();
-    get started(): boolean;
-    scrollToIndex(index: number): void;
-    /**
-     * @param px
-     */
-    scrollToPx(px: number): void;
-    start(rowCount: number): void;
-    stop(): void;
-}
-declare class VirtualScrollError extends Error {
-    constructor(message: string);
-}
-
-interface LocalStorageAdapterOptions {
-    saveSearch?: boolean;
-    saveColumnSorting?: boolean;
-    saveColumnOrder?: boolean;
-    saveColumnVisibility?: boolean;
-    saveColumnWidth?: boolean;
-}
-interface IDataTable<T> extends EventTarget {
-    getState(): TableState<T>;
-    restoreState(state: RestorableTableState<T>): void;
-}
-
-/**
- * Monitors a {@link DataTable} instance for changes and saves the state to local storage.
- */
-declare class LocalStorageAdapter<T> {
-    #private;
-    private readonly storageKey;
-    private dataTable?;
-    private options;
-    /**
-     * @param dataTable - The DataTable instance to monitor.
-     * @param storageKey - The key to use for saving the state in localStorage.
-     * @param options - The options for configuring what is stored.
-     */
-    constructor(storageKey: string, dataTable?: IDataTable<T> | undefined, options?: LocalStorageAdapterOptions);
-    setDataTable(dataTable: IDataTable<T>): void;
-    destroy(): void;
-    /**
-     * Saves the current column state to localStorage.
-     */
-    saveState(): void;
-    /**
-     * Restores the column state from localStorage.
-     */
-    restoreState(): void;
-    /**
-     * Clears the saved state from localStorage.
-     */
-    clearState(): void;
-}
-
-export { type CellFormatterCallback, type ColumnFilterCallback, type ColumnInitOptions, type ColumnOptions, type ColumnState, type ComparatorCallback, DataTable, type DataTableEventMap, type FilterCallback, type Filters, type IDataTable, type IVirtualScroll, type IVirtualScrollConstructor, type LoadOptions, LocalStorageAdapter, type LocalStorageAdapterOptions, type NestedKeyOf, type QueryToken, type RestorableColumnState, type RestorableTableState, type RowFormatterCallback, type SortOrder, type SortState, type SortValueCallback, type TableClasses, type TableInitOptions, type TableOptions, type TableState, type TokenizerCallback, type ValueFormatterCallback, VirtualScroll, VirtualScrollError, type VirtualScrollOptions, createRegexTokenizer };