@timlassiter11/yatl 0.1.6

package/dist/datatable.d.mts

@@ -0,0 +1,531 @@
+/**
+ * Defines the possible sorting orders for columns.
+ */
+type SortOrder = 'asc' | 'desc' | null;
+/**
+ * Represents a generic data row in the table, an object with string keys and any values.
+ */
+type Row = Record<string, any>;
+/**
+ * Represents filter data where the key should be a field in the Row data and the value
+ * should be comparable to the value of that field, or an array of values.
+ */
+type Filters = Record<string, any>;
+/**
+ * Callback for formatting a row's  HTML element.
+ * @param row - The row data.
+ * @param element - The row element.
+ */
+type RowFormatterCallback = (row: Row, 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 = (value: any, row: Row) => string;
+/**
+ * Callback for formatting a cell's HTML element.
+ * @param value - The value of the field.
+ * @param row - The row data.
+ * @param element - The cell element.
+ */
+type CellFormatterCallback = (value: any, row: Row, 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;
+/**
+ * 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) => string[];
+/**
+ * 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 = (row: Row, 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;
+/**
+ * Column options for the table.
+ */
+interface ColumnOptions {
+    /**
+     * The field name in the data object.
+     */
+    field: string;
+    /**
+     * 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;
+    /**
+     * The initial sort order of the column.
+     */
+    sortOrder?: SortOrder;
+    /**
+     * The initial sort priority of the column for sorting.
+     * Lower numbers are sorted first.
+     */
+    sortPriority?: number;
+    /**
+     * Whether the column should be visible by default.
+     */
+    visible?: boolean;
+    /**
+     * Whether the column should be resizable.
+     * Defaults to the table's resizable option.
+     */
+    resizable?: boolean;
+    /**
+     * The initial width of the column.
+     * Can be a number (in pixels) or a string (e.g. "100px", "50%").
+     */
+    width?: string | number;
+    /**
+     * A function to format the value for display.
+     */
+    valueFormatter?: ValueFormatterCallback;
+    /**
+     * A function to format the element for display.
+     */
+    elementFormatter?: CellFormatterCallback;
+    /**
+     * A function to use for sorting the column.
+     * This overrides the default sorting behavior.
+     */
+    sorter?: ComparatorCallback;
+    /**
+     * 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;
+    /**
+     * 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.
+     * @param value - The cell's value.
+     * @param filterCriterion - The criterion provided for this column in the main filter object.
+     */
+    filter?: ColumnFilterCallback;
+}
+/** Represents the current state of a column, often used for saving and restoring column configurations. */
+interface ColumnState {
+    /**
+     * The unique field name of the column.
+     */
+    readonly field: string;
+    /**
+     * The user friendly title of the column.
+     */
+    readonly title: string;
+    /**
+     * The current visibility of the column.
+     */
+    visible: boolean;
+    /**
+     * The current sort order of the column.
+     */
+    sortOrder: SortOrder;
+    /**
+     * The current sort priority of the column.
+     * Lower numbers are sorted first.
+     */
+    sortPriority: number;
+    /**
+     * The currently set width of the column.
+     */
+    width: string;
+}
+/**
+ * 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 the tfoot element.
+     */
+    tfoot?: 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 {
+    /**
+     * The column options for the table.
+     */
+    columns?: ColumnOptions[];
+    /**
+     * The initial data to load into the table.
+     */
+    data?: Row[];
+    /**
+     * Configures virtual scrolling.
+     */
+    virtualScroll?: boolean;
+    /**
+     * Whether to highlight search results in the table cells.
+     */
+    highlightSearch?: boolean;
+    /**
+     * Whether columns should be sortable by default.
+     * Can be overridden on individual columns.
+     */
+    sortable?: boolean;
+    /**
+     * Whether columns should be searchable by default.
+     * Can be overridden on individual columns.
+     */
+    searchable?: boolean;
+    /**
+     * Whether columns data should be tokenized for searching by default.
+     * Can be overridden on individual columns.
+     */
+    tokenize?: boolean;
+    /**
+     * Whether columns should be resizable by default.
+     * Can be overridden on individual columns.
+     */
+    resizable?: 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?: 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;
+    /**
+     * A function to use for tokenizing values for searching.
+     */
+    tokenizer?: TokenizerCallback;
+}
+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 kepts */
+    keepScroll?: boolean;
+}
+
+/**
+ * Represents a dynamic and interactive table with features like sorting, searching, filtering,
+ * column resizing, column rearranging, and virtual scrolling.
+ *
+ * @example
+ * ```ts
+ * const tableElement = document.getElementById('myTable');
+ * const options = {
+ *   columns: [
+ *     { 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,
+ * };
+ * const dataTable = new DataTable(tableElement, options);
+ * ```
+ */
+declare class DataTable extends EventTarget {
+    #private;
+    private static readonly DEFAULT_OPTIONS;
+    /**
+     * Initializes a new instance of the DataTable.
+     * @param table - The HTMLTableElement or a CSS selector string 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, options?: TableOptions);
+    /**
+     * Gets or sets the state of all columns in the table.
+     * This can be used to save and restore column configurations like visibility, sort order, and width.
+     * When setting, it attempts to apply the states to existing columns.
+     */
+    get columnStates(): ColumnState[];
+    set columnStates(states: ColumnState[]);
+    /**
+     * Gets the currently filtered and sorted rows displayed in the table.
+     */
+    get rows(): Row[];
+    /**
+     * Gets the underlying data
+     */
+    get data(): Row[];
+    /**
+     * Gets the total number of currently filtered and sorted rows.
+     */
+    get length(): number;
+    /**
+     * Gets the underlying HTMLTableElement managed by this DataTable instance.
+     */
+    get table(): HTMLTableElement;
+    /**
+     * Gets or sets the virtual scroll behavior for the table.
+     * When `true`, virtual scrolling is enabled, rendering only visible rows for performance with large datasets.
+     * When `false`, virtual scrolling is disabled, and all rows are rendered.
+     * @default true
+     */
+    get virtualScroll(): boolean;
+    set virtualScroll(value: boolean);
+    /**
+     * Loads data into the table.
+     * @param rows - An array of row data objects to load.
+     * @param append - If true, appends the new rows to existing data. If false (default), overwrites existing data.
+     * @throws {TypeError} If `rows` is not an array.
+     */
+    loadData(rows: Row[], 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 | 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): 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 | FilterCallback): 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: string, order: SortOrder): 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: string, visisble: boolean): void;
+    /**
+     * Shows a previously hidden column.
+     * @param field - The field name of the column to show.
+     */
+    showColumn(field: string): void;
+    /**
+     * Hides a visible column.
+     * @param field - The field name of the column to hide.
+     */
+    hideColumn(field: string): 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: Row): 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: string[]): 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 data - An object containing the new data to assign to the row. Existing fields will be updated, and new fields will be added.
+     * @param index - The original index of the row to update.
+     *
+     * @example
+     * ```ts
+     * const index = dataTable.indexOf('id', 12345);
+     * if (index >= 0) {
+     *  dataTable.updateRow({description: "Updated description"}, index);
+     * }
+     * ```
+     */
+    updateRow(data: Row, index: number): 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) => void): void;
+    addEventListener<K extends keyof DataTableEventMap>(type: K, listener: (this: DataTable, ev: CustomEvent<DataTableEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+/**
+ * Defines the mapping between event names and their detail object types.
+ */
+interface DataTableEventMap {
+    'dt.row.clicked': {
+        row: Row;
+        index: number;
+        column: string | undefined;
+        originalEvent: MouseEvent;
+    };
+    'dt.rows.changed': object;
+    'dt.col.sort': {
+        column: string;
+        order: SortOrder;
+    };
+    'dt.col.visibility': {
+        column: string;
+        visible: boolean;
+    };
+    'dt.col.resize': {
+        column: string;
+        width: number;
+    };
+    'dt.col.reorder': {
+        draggedColumn: string;
+        dropColumn: string;
+        order: string[];
+    };
+}
+
+interface Options {
+    saveColumnSorting: boolean;
+    saveColumnOrder: boolean;
+    saveColumnVisibility: boolean;
+    saveColumnWidth: boolean;
+}
+declare class LocalStorageAdapter {
+    #private;
+    /**
+     * @param dataTable - The DataTable instance to monitor.
+     * @param storageKey - The key to use for saving the state in localStorage.
+     * @param options - The key to use for saving the state in localStorage.
+     */
+    constructor(dataTable: DataTable, storageKey: string, options?: Options);
+    /**
+     * 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 ColumnOptions, type ColumnState, type ComparatorCallback, DataTable, type DataTableEventMap, type FilterCallback, type Filters, type LoadOptions, LocalStorageAdapter, type Row, type RowFormatterCallback, type SortOrder, type SortValueCallback, type TableClasses, type TableOptions, type TokenizerCallback, type ValueFormatterCallback };