@timlassiter11/yatl 1.0.17 → 1.0.19

package/README.md

@@ -1,12 +1,17 @@
 # YATL (Yet Another Table Library)
 
-[![NPM Version](https://img.shields.io/npm/v/@timlassiter11/yatl)](https://www.npmjs.com/package/@timlassiter11/yatl)
-[![API Docs](https://img.shields.io/badge/docs-typedoc-blue)](https://timlassiter11.github.io/YATL/docs/index.html)
-[![Live Demo](https://img.shields.io/badge/demo-online-green)](https://timlassiter11.github.io/YATL/examples/index.html)
-[![License](https://img.shields.io/npm/l/@timlassiter11/yatl)](LICENSE)
+[![NPM Version](https://img.shields.io/npm/v/@timlassiter11/yatl?style=for-the-badge)](https://www.npmjs.com/package/@timlassiter11/yatl)
+[![License](https://img.shields.io/npm/l/@timlassiter11/yatl?style=for-the-badge)](LICENSE)
 
 YATL is a powerful, feature-rich, and lightweight Web Component data table built with Lit. It handles large datasets with ease using virtual scrolling, offers advanced fuzzy search capabilities, supports state persistence, and works in any framework (React, Vue, Angular, or Vanilla JS).
 
+
+[Try the Live Demo](https://timlassiter11.github.io/YATL/examples/index.html)  | [Check out the Docs](https://timlassiter11.github.io/YATL/docs/index.html)
+
+
+![Showcase](./docs/YATL-demo.gif)
+
+
 ## Why?!?
 
 I needed a free and simple table library for vanilla JS that was easy to customize and could handle large datasets... so I created YATL. As the project that I wrote this for grew, so did this library. Now it is a web component built using Lit that is fairly feature rich for simple use cases. There are many other great table libraries out there but if you want something simple to just drop in but with all of the major features already included, YATL might be for you.
@@ -32,6 +37,7 @@ npm install @timlassiter11/yatl
 Alternatively you can manually download the source files from the [releases](https://github.com/timlassiter11/YATL/releases) section.
 
 ## Examples
+
 ### Lit
 
 ```ts

package/dist/index.d.mts

@@ -11,13 +11,22 @@ declare class YatlButton extends LitElement {
     type: 'button' | 'submit' | 'reset';
     render(): lit_html.TemplateResult<1>;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-button': YatlButton;
+    }
+}
 
 declare class YatlButtonGroup extends LitElement {
     static styles: lit.CSSResult[];
     render(): lit_html.TemplateResult<1>;
-    private getFlattenedElements;
     private handleSlotChange;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-button-group': YatlButtonGroup;
+    }
+}
 
 declare class YatlDropdown extends LitElement {
     static styles: lit.CSSResult[];
@@ -27,9 +36,14 @@ declare class YatlDropdown extends LitElement {
     private handleDropdownTriggerClick;
     private handleDocumentClick;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-dropdown': YatlDropdown;
+    }
+}
 
 /**
- * @fires yatl-dropdown-toggle - Fired when a dropdown item's checked state changes
+ * @emits yatl-dropdown-toggle - Fired when a dropdown item's checked state changes
  */
 declare class YatlDropdownItem extends LitElement {
     static styles: lit.CSSResult[];
@@ -38,6 +52,11 @@ declare class YatlDropdownItem extends LitElement {
     protected render(): lit_html.TemplateResult<1>;
     private handleCheckboxChanged;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-dropdown-item': YatlDropdownItem;
+    }
+}
 
 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
@@ -473,6 +492,7 @@ declare class YatlTableController<T extends object = UnspecifiedRecord> implemen
     private _rowIdCallback;
     private _data;
     private _filteredData;
+    private _dataUpdateTimestamp;
     private _searchQuery;
     private _searchTokenizer;
     private _filters;
@@ -587,6 +607,7 @@ declare class YatlTableController<T extends object = UnspecifiedRecord> implemen
     get data(): T[];
     set data(data: T[]);
     get filteredData(): T[];
+    get dataUpdateTimestamp(): Date | null;
     constructor(host?: ReactiveControllerHost, options?: TableControllerOptions<T>);
     attach(host: ReactiveControllerHost): void;
     detach(host: ReactiveControllerHost): void;
@@ -778,12 +799,12 @@ declare class YatlTable<T extends object = UnspecifiedRecord> extends LitElement
     static styles: lit.CSSResult[];
     private tableElement;
     private virtualizer?;
-    private dataLastUpdate;
     private resizeState;
     private dragColumn;
     private _controller;
     get controller(): YatlTableController<T>;
     set controller(controller: YatlTableController<T>);
+    striped: boolean;
     /**
      * Default sortability for all columns.
      * Can be overridden by setting `sortable` on the specific column definition.
@@ -955,6 +976,7 @@ declare class YatlTable<T extends object = UnspecifiedRecord> extends LitElement
     get data(): T[];
     set data(value: T[]);
     get filteredData(): T[];
+    get dataUpdateTimestamp(): Date | null;
     getColumn(field: NestedKeyOf<T>): ColumnOptions<T> | undefined;
     getDisplayColumn(field: NestedKeyOf<T>): DisplayColumnOptions<T> | undefined;
     /**
@@ -1128,13 +1150,39 @@ declare global {
     }
 }
 
+/**
+ * A "Batteries Included" wrapper for `<yatl-table>` that provides a built-in toolbar.
+ *
+ * This element extends the core table engine to automatically render UI controls
+ * for common user actions, such as toggling column visibility and exporting data.
+ *
+ * It inherits all properties and events from `<yatl-table>`.
+ *
+ * @element yatl-table-ui
+ *
+ * @slot toolbar - Adds contents to the right of the toolbar button group
+ * @slot toolbar-button-group - Adds content into the toolbar button group.
+ * @slot footer - Inherited from `yatl-table`. Content to display in the table footer area.
+ * @slot body - Inherited from `yatl-table`. Custom rendering for the table body.
+ */
 declare class YatlTableUi<T extends object = UnspecifiedRecord> extends YatlTable<T> {
     static styles: lit.CSSResult[];
+    /**
+     * Toggles the visibility of the column picker button in the toolbar. Defaults to `true`.
+     */
     showColumnPicker: boolean;
+    /**
+     * Toggles the visibility of the CSV export button in the toolbar. Defaults to `true`.
+     */
     showExportButton: boolean;
     protected render(): lit_html.TemplateResult<1>;
     private handleTableExportClicked;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-table-ui': YatlTableUi;
+    }
+}
 
 /**
  * A table toolbar component with a search input, column picker, and export button.
@@ -1143,8 +1191,11 @@ declare class YatlTableUi<T extends object = UnspecifiedRecord> extends YatlTabl
  * @summary Provides a cohesive set of controls for searching, exporting, and managing column visibility,
  * along with a flexible slot for custom actions.
  *
- * @slot - The default slot for adding custom action buttons (e.g., "Add Record", "Refresh").
- * Items placed here are automatically styled to match the toolbar's button group layout.
+ * @slot - Adds contents to the right of the toolbar button group
+ * @slot toolbar-button-group - Adds content into the toolbar button group.
+ * @slot column-picker-trigger - Replaces the button used to trigger the column picker.
+ * @slot column-picker-icon - Replaces the icon for the column picker button.
+ * @slot export-button-icon - Replaces the icon for the export button.
  *
  * @fires yatl-toolbar-search-input - Fired synchronously as the user types in the search box. Useful for real-time highlighting or suggestions.
  * @fires yatl-toolbar-search-change - Fired when the user commits a search query (e.g., on 'Enter' or blur). Use this for triggering the actual table filter.
@@ -1168,5 +1219,26 @@ declare class YatlToolbar<T extends object = UnspecifiedRecord> extends LitEleme
     private onSearchChange;
     private onExportClick;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-toolbar': YatlToolbar;
+    }
+}
+
+declare function findColumn<TData extends Record<string, unknown>, TCol extends {
+    field: NestedKeyOf<TData>;
+}>(columns: TCol[], field: NestedKeyOf<TData>): TCol | undefined;
+declare function isInternalColumn<T>(col: ColumnOptions<T> | undefined | null): col is InternalColumnOptions<T>;
+declare function isDisplayColumn<T>(col: ColumnOptions<T> | undefined | null): col is DisplayColumnOptions<T>;
+declare function createState<T>(field: NestedKeyOf<T>, defaults?: Partial<ColumnState<T>>): ColumnState<T>;
+
+declare const createRegexTokenizer: (exp?: string) => (value: string) => {
+    value: string;
+    quoted: boolean;
+}[];
+declare const whitespaceTokenizer: (value: string) => {
+    value: string;
+    quoted: boolean;
+}[];
 
-export { type BaseColumnOptions, type CellPartsCallback, type CellRenderCallback, type ColumnFilterCallback, type ColumnOptions, type ColumnRole, type ColumnState, type Compareable, type DisplayColumnOptions, type ExportOptions, type FilterCallback, type Filters, type InternalColumnOptions, type NestedKeyOf, type QueryToken, type Renderable, type RestorableColumnState, type RestorableTableState, type RowId, type RowIdCallback, type RowPartsCallback, type RowSelectionMethod, type SortOrder, type SortState, type SortValueCallback, type StorageOptions, type TableControllerOptions, type TableState, type TokenizerCallback, type UnspecifiedRecord, type ValueFormatterCallback, YatlButton, YatlButtonGroup, YatlColumnReorderEvent, YatlColumnReorderRequestEvent, YatlColumnResizeEvent, YatlColumnSortEvent, YatlColumnSortRequestEvent, YatlColumnToggleEvent, YatlColumnToggleRequestEvent, YatlDropdown, YatlDropdownItem, YatlDropdownToggleEvent, YatlEvent, YatlRowClickEvent, YatlRowSelectEvent, YatlRowSelectRequestEvent, YatlTable, YatlTableController, YatlTableSearchEvent, YatlTableStateChangeEvent, YatlTableUi, YatlTableViewChangeEvent, YatlToolbar, YatlToolbarExportClick, YatlToolbarSearchChange, YatlToolbarSearchInput };
+export { type BaseColumnOptions, type CellPartsCallback, type CellRenderCallback, type ColumnFilterCallback, type ColumnOptions, type ColumnRole, type ColumnState, type Compareable, type DisplayColumnOptions, type ExportOptions, type FilterCallback, type Filters, type InternalColumnOptions, type NestedKeyOf, type QueryToken, type Renderable, type RestorableColumnState, type RestorableTableState, type RowId, type RowIdCallback, type RowPartsCallback, type RowSelectionMethod, type SortOrder, type SortState, type SortValueCallback, type StorageOptions, type TableControllerOptions, type TableState, type TokenizerCallback, type UnspecifiedRecord, type ValueFormatterCallback, YatlButton, YatlButtonGroup, YatlColumnReorderEvent, YatlColumnReorderRequestEvent, YatlColumnResizeEvent, YatlColumnSortEvent, YatlColumnSortRequestEvent, YatlColumnToggleEvent, YatlColumnToggleRequestEvent, YatlDropdown, YatlDropdownItem, YatlDropdownToggleEvent, YatlEvent, YatlRowClickEvent, YatlRowSelectEvent, YatlRowSelectRequestEvent, YatlTable, YatlTableController, YatlTableSearchEvent, YatlTableStateChangeEvent, YatlTableUi, YatlTableViewChangeEvent, YatlToolbar, YatlToolbarExportClick, YatlToolbarSearchChange, YatlToolbarSearchInput, createRegexTokenizer, createState, findColumn, isDisplayColumn, isInternalColumn, whitespaceTokenizer };

package/dist/index.d.ts

@@ -11,13 +11,22 @@ declare class YatlButton extends LitElement {
     type: 'button' | 'submit' | 'reset';
     render(): lit_html.TemplateResult<1>;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-button': YatlButton;
+    }
+}
 
 declare class YatlButtonGroup extends LitElement {
     static styles: lit.CSSResult[];
     render(): lit_html.TemplateResult<1>;
-    private getFlattenedElements;
     private handleSlotChange;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-button-group': YatlButtonGroup;
+    }
+}
 
 declare class YatlDropdown extends LitElement {
     static styles: lit.CSSResult[];
@@ -27,9 +36,14 @@ declare class YatlDropdown extends LitElement {
     private handleDropdownTriggerClick;
     private handleDocumentClick;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-dropdown': YatlDropdown;
+    }
+}
 
 /**
- * @fires yatl-dropdown-toggle - Fired when a dropdown item's checked state changes
+ * @emits yatl-dropdown-toggle - Fired when a dropdown item's checked state changes
  */
 declare class YatlDropdownItem extends LitElement {
     static styles: lit.CSSResult[];
@@ -38,6 +52,11 @@ declare class YatlDropdownItem extends LitElement {
     protected render(): lit_html.TemplateResult<1>;
     private handleCheckboxChanged;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-dropdown-item': YatlDropdownItem;
+    }
+}
 
 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
@@ -473,6 +492,7 @@ declare class YatlTableController<T extends object = UnspecifiedRecord> implemen
     private _rowIdCallback;
     private _data;
     private _filteredData;
+    private _dataUpdateTimestamp;
     private _searchQuery;
     private _searchTokenizer;
     private _filters;
@@ -587,6 +607,7 @@ declare class YatlTableController<T extends object = UnspecifiedRecord> implemen
     get data(): T[];
     set data(data: T[]);
     get filteredData(): T[];
+    get dataUpdateTimestamp(): Date | null;
     constructor(host?: ReactiveControllerHost, options?: TableControllerOptions<T>);
     attach(host: ReactiveControllerHost): void;
     detach(host: ReactiveControllerHost): void;
@@ -778,12 +799,12 @@ declare class YatlTable<T extends object = UnspecifiedRecord> extends LitElement
     static styles: lit.CSSResult[];
     private tableElement;
     private virtualizer?;
-    private dataLastUpdate;
     private resizeState;
     private dragColumn;
     private _controller;
     get controller(): YatlTableController<T>;
     set controller(controller: YatlTableController<T>);
+    striped: boolean;
     /**
      * Default sortability for all columns.
      * Can be overridden by setting `sortable` on the specific column definition.
@@ -955,6 +976,7 @@ declare class YatlTable<T extends object = UnspecifiedRecord> extends LitElement
     get data(): T[];
     set data(value: T[]);
     get filteredData(): T[];
+    get dataUpdateTimestamp(): Date | null;
     getColumn(field: NestedKeyOf<T>): ColumnOptions<T> | undefined;
     getDisplayColumn(field: NestedKeyOf<T>): DisplayColumnOptions<T> | undefined;
     /**
@@ -1128,13 +1150,39 @@ declare global {
     }
 }
 
+/**
+ * A "Batteries Included" wrapper for `<yatl-table>` that provides a built-in toolbar.
+ *
+ * This element extends the core table engine to automatically render UI controls
+ * for common user actions, such as toggling column visibility and exporting data.
+ *
+ * It inherits all properties and events from `<yatl-table>`.
+ *
+ * @element yatl-table-ui
+ *
+ * @slot toolbar - Adds contents to the right of the toolbar button group
+ * @slot toolbar-button-group - Adds content into the toolbar button group.
+ * @slot footer - Inherited from `yatl-table`. Content to display in the table footer area.
+ * @slot body - Inherited from `yatl-table`. Custom rendering for the table body.
+ */
 declare class YatlTableUi<T extends object = UnspecifiedRecord> extends YatlTable<T> {
     static styles: lit.CSSResult[];
+    /**
+     * Toggles the visibility of the column picker button in the toolbar. Defaults to `true`.
+     */
     showColumnPicker: boolean;
+    /**
+     * Toggles the visibility of the CSV export button in the toolbar. Defaults to `true`.
+     */
     showExportButton: boolean;
     protected render(): lit_html.TemplateResult<1>;
     private handleTableExportClicked;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-table-ui': YatlTableUi;
+    }
+}
 
 /**
  * A table toolbar component with a search input, column picker, and export button.
@@ -1143,8 +1191,11 @@ declare class YatlTableUi<T extends object = UnspecifiedRecord> extends YatlTabl
  * @summary Provides a cohesive set of controls for searching, exporting, and managing column visibility,
  * along with a flexible slot for custom actions.
  *
- * @slot - The default slot for adding custom action buttons (e.g., "Add Record", "Refresh").
- * Items placed here are automatically styled to match the toolbar's button group layout.
+ * @slot - Adds contents to the right of the toolbar button group
+ * @slot toolbar-button-group - Adds content into the toolbar button group.
+ * @slot column-picker-trigger - Replaces the button used to trigger the column picker.
+ * @slot column-picker-icon - Replaces the icon for the column picker button.
+ * @slot export-button-icon - Replaces the icon for the export button.
  *
  * @fires yatl-toolbar-search-input - Fired synchronously as the user types in the search box. Useful for real-time highlighting or suggestions.
  * @fires yatl-toolbar-search-change - Fired when the user commits a search query (e.g., on 'Enter' or blur). Use this for triggering the actual table filter.
@@ -1168,5 +1219,26 @@ declare class YatlToolbar<T extends object = UnspecifiedRecord> extends LitEleme
     private onSearchChange;
     private onExportClick;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'yatl-toolbar': YatlToolbar;
+    }
+}
+
+declare function findColumn<TData extends Record<string, unknown>, TCol extends {
+    field: NestedKeyOf<TData>;
+}>(columns: TCol[], field: NestedKeyOf<TData>): TCol | undefined;
+declare function isInternalColumn<T>(col: ColumnOptions<T> | undefined | null): col is InternalColumnOptions<T>;
+declare function isDisplayColumn<T>(col: ColumnOptions<T> | undefined | null): col is DisplayColumnOptions<T>;
+declare function createState<T>(field: NestedKeyOf<T>, defaults?: Partial<ColumnState<T>>): ColumnState<T>;
+
+declare const createRegexTokenizer: (exp?: string) => (value: string) => {
+    value: string;
+    quoted: boolean;
+}[];
+declare const whitespaceTokenizer: (value: string) => {
+    value: string;
+    quoted: boolean;
+}[];
 
-export { type BaseColumnOptions, type CellPartsCallback, type CellRenderCallback, type ColumnFilterCallback, type ColumnOptions, type ColumnRole, type ColumnState, type Compareable, type DisplayColumnOptions, type ExportOptions, type FilterCallback, type Filters, type InternalColumnOptions, type NestedKeyOf, type QueryToken, type Renderable, type RestorableColumnState, type RestorableTableState, type RowId, type RowIdCallback, type RowPartsCallback, type RowSelectionMethod, type SortOrder, type SortState, type SortValueCallback, type StorageOptions, type TableControllerOptions, type TableState, type TokenizerCallback, type UnspecifiedRecord, type ValueFormatterCallback, YatlButton, YatlButtonGroup, YatlColumnReorderEvent, YatlColumnReorderRequestEvent, YatlColumnResizeEvent, YatlColumnSortEvent, YatlColumnSortRequestEvent, YatlColumnToggleEvent, YatlColumnToggleRequestEvent, YatlDropdown, YatlDropdownItem, YatlDropdownToggleEvent, YatlEvent, YatlRowClickEvent, YatlRowSelectEvent, YatlRowSelectRequestEvent, YatlTable, YatlTableController, YatlTableSearchEvent, YatlTableStateChangeEvent, YatlTableUi, YatlTableViewChangeEvent, YatlToolbar, YatlToolbarExportClick, YatlToolbarSearchChange, YatlToolbarSearchInput };
+export { type BaseColumnOptions, type CellPartsCallback, type CellRenderCallback, type ColumnFilterCallback, type ColumnOptions, type ColumnRole, type ColumnState, type Compareable, type DisplayColumnOptions, type ExportOptions, type FilterCallback, type Filters, type InternalColumnOptions, type NestedKeyOf, type QueryToken, type Renderable, type RestorableColumnState, type RestorableTableState, type RowId, type RowIdCallback, type RowPartsCallback, type RowSelectionMethod, type SortOrder, type SortState, type SortValueCallback, type StorageOptions, type TableControllerOptions, type TableState, type TokenizerCallback, type UnspecifiedRecord, type ValueFormatterCallback, YatlButton, YatlButtonGroup, YatlColumnReorderEvent, YatlColumnReorderRequestEvent, YatlColumnResizeEvent, YatlColumnSortEvent, YatlColumnSortRequestEvent, YatlColumnToggleEvent, YatlColumnToggleRequestEvent, YatlDropdown, YatlDropdownItem, YatlDropdownToggleEvent, YatlEvent, YatlRowClickEvent, YatlRowSelectEvent, YatlRowSelectRequestEvent, YatlTable, YatlTableController, YatlTableSearchEvent, YatlTableStateChangeEvent, YatlTableUi, YatlTableViewChangeEvent, YatlToolbar, YatlToolbarExportClick, YatlToolbarSearchChange, YatlToolbarSearchInput, createRegexTokenizer, createState, findColumn, isDisplayColumn, isInternalColumn, whitespaceTokenizer };