@timlassiter11/yatl 0.3.21 → 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,632 @@
+import * as lit from 'lit';
+import { LitElement, TemplateResult, nothing, PropertyValues } from 'lit';
+
+type NestedKeyOf<ObjectType> = ObjectType extends object ? {
+    [Key in keyof ObjectType & (string | number)]: NonNullable<ObjectType[Key]> extends unknown[] ? `${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;
+}[];
+declare const whitespaceTokenizer: (value: string) => {
+    value: string;
+    quoted: boolean;
+}[];
+declare function findColumn<T extends {
+    field: string;
+}>(field: string, columns: T[]): T | undefined;
+
+/**
+ * Defines the possible sorting orders for columns.
+ */
+type SortOrder = 'asc' | 'desc';
+/**
+ * Known compareable type
+ */
+type Compareable = string | number | boolean | Date;
+/**
+ * Callback for conditionally adding classes to a row
+ * @param row - The row data.
+ * @returns the part string or list of part strings that should be added to this row.
+ */
+type RowPartsCallback<T> = (row: T) => string | string[];
+/**
+ * Callback for conditionally adding classes to a cell
+ * @param value - The value of the cell.
+ * @param field - The field of the column.
+ * @param row - The row data.
+ */
+type CellPartsCallback<T> = (value: unknown, field: NestedKeyOf<T>, row: T) => string | string[];
+/**
+ * Callback for providing the full contents of a rendered cell.
+ * @param value - The value of the cell.
+ * @param field - The field of the column.
+ * @param row - The row data.
+ * @returns - Should return an HTMLElement or anything Lit can render
+ */
+type CellRenderCallback<T> = (value: unknown, field: NestedKeyOf<T>, row: T) => unknown;
+/**
+ * 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: unknown, row: T) => string | null;
+/**
+ * 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: unknown, b: unknown) => 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: unknown) => Compareable;
+/**
+ * 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>]: unknown;
+}>;
+/**
+ * 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: string) => 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: unknown, filter: unknown) => 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 for tokenizing this column's data.
+     * Fallback to the main table tokenizer if not provided.
+     */
+    searchTokenizer?: TokenizerCallback;
+    /**
+     * A function to format the value for display.
+     */
+    valueFormatter?: ValueFormatterCallback<T>;
+    /**
+     * A function for conditinally adding classes to a cell.
+     */
+    cellParts?: CellPartsCallback<T>;
+    /**
+     * A function for rendering the contents of a cell.
+     * NOTE: Search highlighting will not work for this cell when used.
+     */
+    cellRenderer?: CellRenderCallback<T>;
+    /**
+     * 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.
+     */
+    filter?: ColumnFilterCallback;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+    /**
+     * The current filters applied to the table or null if no filters are applied.
+     */
+    filters: Filters<T> | FilterCallback<T> | null;
+    /**
+     * The current column order represented as a list of their fields from left to right.
+     */
+    columnOrder: NestedKeyOf<T>[];
+}
+interface StorageOptions {
+    /**
+     * The unique key used to store the table state in the browser.
+     * * @example "my-app-users-table-v1"
+     */
+    key: string;
+    /**
+     * Which storage engine to use.
+     * * 'local': Persists after browser is closed (Default).
+     * * 'session': Cleared when tab is closed.
+     */
+    storage?: 'local' | 'session';
+    /** Save the current column sorting */
+    saveColumnSortOrders?: boolean;
+    /** Save the current column visibility */
+    saveColumnVisibility?: boolean;
+    /** Save the current column widths */
+    saveColumnWidths?: boolean;
+    /** Save the current order of columns */
+    saveColumnOrder?: boolean;
+}
+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>[];
+};
+
+declare class YatlEvent<T = unknown> extends CustomEvent<T> {
+    constructor(name: string, detail: T, options?: EventInit);
+}
+declare class YatlRowClickEvent<T> extends YatlEvent<{
+    row: T;
+    index: number;
+    field: NestedKeyOf<T>;
+    originalEvent: MouseEvent;
+}> {
+    static readonly EVENT_NAME = "yatl-row-click";
+    constructor(row: T, index: number, field: NestedKeyOf<T>, originalEvent: MouseEvent);
+}
+declare class YatlChangeEvent<T> extends YatlEvent<{
+    data: T[];
+}> {
+    static readonly EVENT_NAME = "yatl-change";
+    constructor(data: T[]);
+}
+declare class YatlSortEvent<T> extends YatlEvent<{
+    field: NestedKeyOf<T>;
+    order: SortOrder | null;
+}> {
+    static readonly EVENT_NAME = "yatl-sort";
+    constructor(field: NestedKeyOf<T>, order: SortOrder | null);
+}
+declare class YatlColumnToggleEvent<T> extends YatlEvent<{
+    field: NestedKeyOf<T>;
+    visible: boolean;
+}> {
+    static readonly EVENT_NAME = "yatl-column-toggle";
+    constructor(field: NestedKeyOf<T>, visible: boolean);
+}
+declare class YatlColumnResizeEvent<T> extends YatlEvent<{
+    field: NestedKeyOf<T>;
+    width: number;
+}> {
+    static readonly EVENT_NAME = "yatl-column-resize";
+    constructor(field: NestedKeyOf<T>, width: number);
+}
+declare class YatlColumnReorderEvent<T> extends YatlEvent<{
+    draggedColumn: NestedKeyOf<T>;
+    droppedColumn: NestedKeyOf<T>;
+    order: NestedKeyOf<T>[];
+}> {
+    static readonly EVENT_NAME = "yatl-column-reorder";
+    constructor(draggedColumn: NestedKeyOf<T>, droppedColumn: NestedKeyOf<T>, order: NestedKeyOf<T>[]);
+}
+declare class YatlSearchEvent extends YatlEvent<{
+    query: string;
+}> {
+    static readonly EVENT_NAME = "yatl-search";
+    constructor(query: string);
+}
+
+/**
+ * Represents a dynamic and interactive table with features like sorting, searching, filtering,
+ * column resizing, column rearranging, and virtual scrolling.
+ */
+declare class YatlTable<T extends object> extends LitElement {
+    static styles: lit.CSSResult[];
+    private tableElement;
+    private virtualizer?;
+    private _enableSearchTokenization;
+    private _enableSearchScoring;
+    private _columns;
+    private _columnStates;
+    private _storageOptions;
+    private _data;
+    private _searchQuery;
+    private _searchIncludedFields;
+    private _searchTokenizer;
+    private _filters;
+    private _filteredData;
+    private hasRestoredState;
+    private saveTimer;
+    private filterDirty;
+    private sortDirty;
+    private dataLastUpdate;
+    private rowMetadata;
+    private queryTokens;
+    private resizeState;
+    private dragColumn;
+    /**
+     * Enables virtual scrolling for the table.
+     * When enabled, only the visible rows are rendered to the DOM, significantly improving
+     * performance for large datasets (1000+ rows).
+     * @default false
+     */
+    enableVirtualScroll: boolean;
+    /**
+     * When enabled, text matching the current search query will be wrapped in `<mark>` tags.
+     * This applies to all visible cells that contain the search term.
+     * This does NOT apply to content rendered by the user such as the ColumnOptions.render callback.
+     * @default true
+     */
+    enableSearchHighlight: boolean;
+    /**
+     * Enables tokenized search behavior.
+     * When enabled, the search query is split into individual tokens using the
+     * `searchTokenizer` function (defaults to splitting on whitespace).
+     * A row is considered a match if **ANY** of the tokens appear in the searchable fields.
+     * @default false
+     */
+    get enableSearchTokenization(): boolean;
+    set enableSearchTokenization(enable: boolean);
+    /**
+     * Enables weighted relevance scoring for search results.
+     * When enabled, exact matches and prefix matches are ranked higher than substring matches.
+     * Rows are sorted by their relevance score descending.
+     * @default false
+     */
+    get enableSearchScoring(): boolean;
+    set enableSearchScoring(enable: boolean);
+    /**
+     * Allows users to reorder columns by dragging and dropping headers.
+     * @default true
+     */
+    enableColumnReorder: boolean;
+    /**
+     * Shows the built-in footer row which displays the current record count.
+     * The footer content can be customized using the `slot="footer"` element.
+     * @default false
+     */
+    enableFooter: boolean;
+    /**
+     * The string to display in a cell when the data value is `null` or `undefined`.
+     * @default "-"
+     */
+    nullValuePlaceholder: string;
+    /**
+     * The message displayed when the `data` array is empty.
+     * @default "No records to display"
+     */
+    emptyMessage: string;
+    /**
+     * The message displayed when `data` exists but the current search/filter
+     * results in zero visible rows.
+     * @default "No matching records found"
+     */
+    noResultsMessage: string;
+    /**
+     * The definitions for the columns to be rendered.
+     * This defines the field mapping, titles, sortability, and other static options.
+     */
+    get columns(): ColumnOptions<T>[];
+    set columns(columns: ColumnOptions<T>[]);
+    /**
+     * The current dynamic state of the columns (width, visibility, sort order).
+     * This property is updated automatically when users interact with the table.
+     */
+    get columnStates(): ColumnState<T>[];
+    set columnStates(states: ColumnState<T>[]);
+    /**
+     * The current text string used to filter the table data.
+     * Setting this property triggers a new search and render cycle.
+     */
+    get searchQuery(): string;
+    set searchQuery(query: string);
+    /**
+     * A list of extra data fields to include in the search index, even if they are not
+     * displayed as visible columns. Useful for searching by ID, hidden keywords, or tags.
+     */
+    get searchIncludedFields(): NestedKeyOf<T>[];
+    set searchIncludedFields(fields: NestedKeyOf<T>[]);
+    /**
+     * A function that splits the search query into tokens.
+     * Only used if `enableSearchTokenization` is true.
+     * @default whitespaceTokenizer
+     */
+    get searchTokenizer(): TokenizerCallback;
+    set searchTokenizer(tokenizer: TokenizerCallback);
+    /**
+     * An optional set of criteria to filter the visible rows.
+     * This runs **before** the global search query is applied.
+     * * You can provide:
+     * 1. A **Partial Object**: matches rows where specific keys equal specific values (AND logic).
+     * 2. A **Callback Function**: returns `true` to keep the row, `false` to hide it.
+     * * @example
+     * // 1. Object Syntax (Simple Exact Match)
+     * // Shows rows where status is 'active' AND role is 'admin'
+     * table.filters = { status: 'active', role: 'admin' };
+     * * @example
+     * // 2. Callback Syntax (Complex Logic)
+     * // Shows rows where age is over 21 OR they are a VIP
+     * table.filters = (row) => row.age > 21 || row.isVip;
+     */
+    get filters(): Partial<{ [K in NestedKeyOf<T>]: unknown; }> | FilterCallback<T> | null;
+    set filters(filters: Partial<{ [K in NestedKeyOf<T>]: unknown; }> | FilterCallback<T> | null);
+    /**
+     * A callback function to conditionally apply CSS parts to table rows.
+     */
+    rowParts: RowPartsCallback<T> | null;
+    /**
+     * Configuration options for automatically saving and restoring table state
+     * (column width, order, visibility, etc.) to browser storage.
+     */
+    get storageOptions(): StorageOptions | null;
+    set storageOptions(options: StorageOptions | null);
+    /**
+     * The array of data objects to be displayed.
+     * Objects must satisfy the `WeakKey` constraint (objects only, no primitives).
+     */
+    get data(): T[];
+    set data(value: T[]);
+    get filteredData(): T[];
+    /**
+     * Gets a copy of 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;
+    /**
+     * Sorts the table by a specified column and order.
+     * If `order` is `null`, the sort on this column is removed.
+     * @param field - The field name of the column to sort by.
+     * @param order - The sort order: 'asc', 'desc', or `null` to remove sorting for this column.
+     * @param clear - Clear all other sorting
+     */
+    sort(field: NestedKeyOf<T>, order: SortOrder | null, clear?: boolean): void;
+    /**
+     * Sets the visibility of a specified column.
+     * @param field - The field name of the column.
+     * @param visible - `true` to show the column, `false` to hide it.
+     */
+    setColumnVisibility(field: NestedKeyOf<T>, visible: boolean): void;
+    /**
+     * Toggles the visibility of hte specified column
+     * @param field - The field name of the column to toggle.
+     */
+    toggleColumnVisibility(field: NestedKeyOf<T>): void;
+    /**
+     * Shows the specified column
+     * @param field - The field name of the column to show.
+     */
+    showColumn(field: NestedKeyOf<T>): void;
+    /**
+     * Hides the specified 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): Promise<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): Promise<void>;
+    scrollToFilteredIndex(index: number): Promise<void>;
+    scrollToPx(px: number): Promise<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;
+    /**
+     * Finds the first row
+     * @param field
+     * @param value
+     * @returns
+     */
+    findRow(field: NestedKeyOf<T>, value: unknown): T | undefined;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    findRowIndex(field: NestedKeyOf<T>, value: unknown): 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;
+    protected renderColumnSortIcon(column: ColumnOptions<T>, state: ColumnState<T>): TemplateResult<1> | typeof nothing;
+    protected renderColumnResizer(column: ColumnOptions<T>, _state: ColumnState<T>): TemplateResult<1> | typeof nothing;
+    protected renderHeaderCell(column: ColumnOptions<T>): TemplateResult<1> | typeof nothing;
+    protected renderHeader(): TemplateResult<1>;
+    protected renderCellContents(value: unknown, column: ColumnOptions<T>, row: T): unknown;
+    protected renderCell(column: ColumnOptions<T>, row: T): TemplateResult<1> | typeof nothing;
+    protected renderRow(row: T, index: number): TemplateResult<1>;
+    protected renderBody(): TemplateResult<1>;
+    protected renderFooter(): TemplateResult<1> | typeof nothing;
+    protected render(): TemplateResult<1>;
+    protected updated(changedProperties: PropertyValues<YatlTable<T>>): void;
+    disconnectedCallback(): void;
+    /**
+     * Calculates a relevance score for a given query against a target string.
+     *
+     * This function implements a tiered matching strategy:
+     * 1.  **Exact Match**: The query exactly matches the target. This yields the highest score.
+     * 2.  **Prefix Match**: The target starts with the query. This is the next most relevant.
+     * 3.  **Substring Match**: The target contains the query somewhere. This is the least relevant.
+     *
+     * The final score is weighted and adjusted by the length difference between the query and the target
+     * to ensure that more specific matches (e.g., "apple" vs "application" for the query "apple") rank higher.
+     *
+     * @param query The search term (e.g., "app").
+     * @param target The string to be searched (e.g., "Apple" or "Application").
+     * @returns A numerical score representing the relevance of the match. Higher is better. Returns 0 if no match is found.
+     */
+    private calculateSearchScore;
+    private searchField;
+    private filterField;
+    private filterRow;
+    private filterRows;
+    private compareRows;
+    private sortRows;
+    private createColumnStates;
+    private createMetadata;
+    private updateInternalQuery;
+    private get columnData();
+    private get columnWidths();
+    private scheduleSave;
+    private saveStateToStorage;
+    private loadStateFromStorage;
+    private handleHeaderClicked;
+    private handleCellClick;
+    private handleResizeMouseDown;
+    private handleResizeMouseMove;
+    private handleResizeMouseUp;
+    private handleDragColumnStart;
+    private handleDragColumnEnter;
+    private handleDragColumnLeave;
+    private handleDragColumnOver;
+    private handleDragColumnDrop;
+    private handleDragColumnEnd;
+    addEventListener<K extends keyof EventMap<T>>(type: K, listener: (this: EventMap<T>, ev: EventMap<T>[K]) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof EventMap<T>>(type: K, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    dispatchEvent<K extends keyof EventMap<T>>(event: EventMap<T>[K]): boolean;
+}
+/**
+ * Defines the mapping between event names and their detail object types.
+ */
+interface EventMap<T> {
+    'yatl-row-click': YatlRowClickEvent<T>;
+    'yatl-change': YatlChangeEvent<T>;
+    'yatl-sort': YatlSortEvent<T>;
+    'yatl-column-toggle': YatlColumnToggleEvent<T>;
+    'yatl-column-resize': YatlColumnResizeEvent<T>;
+    'yatl-column-reorder': YatlColumnReorderEvent<T>;
+    'yatl-search': YatlSearchEvent;
+}
+
+export { type CellPartsCallback, type CellRenderCallback, type ColumnFilterCallback, type ColumnInitOptions, type ColumnOptions, type ColumnState, type ComparatorCallback, type Compareable, type FilterCallback, type Filters, type NestedKeyOf, type QueryToken, type RestorableColumnState, type RestorableTableState, type RowPartsCallback, type SortOrder, type SortState, type SortValueCallback, type StorageOptions, type TableState, type TokenizerCallback, type ValueFormatterCallback, YatlChangeEvent, YatlColumnReorderEvent, YatlColumnResizeEvent, YatlColumnToggleEvent, YatlEvent, YatlRowClickEvent, YatlSearchEvent, YatlSortEvent, YatlTable, createRegexTokenizer, findColumn, whitespaceTokenizer };