npm - @timlassiter11/yatl - Versions diffs - 1.0.2 → 1.0.4 - Mend

@timlassiter11/yatl 1.0.2 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md +54 -48
package/dist/index.d.mts +103 -50
package/dist/index.d.ts +103 -50
package/dist/index.js +115 -105
package/dist/index.js.map +1 -1
package/dist/index.mjs +115 -104
package/dist/index.mjs.map +1 -1
package/dist/yatl.min.global.js +25 -23
package/dist/yatl.min.global.js.map +1 -1
package/package.json +3 -1

package/README.md CHANGED Viewed

@@ -1,6 +1,9 @@
-# YATL
+# YATL (Yet Another Table Library)
-**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/advanced.html)
+[![License](https://img.shields.io/npm/l/@timlassiter11/yatl)](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).
@@ -62,11 +65,14 @@ class MyComponent extends LitElement {
    ];
    protected override render() {
-      return html`<yatl-table
-         .columns=${this._columns}
-         .data=${this._tableData}
-         enable-virtual-scroll
-         @dt.row.clicked=${(event) => console.log(event.detail.row)}></yatl-table>`
+      return html`
+        <yatl-table
+          .columns=${this._columns}
+          .data=${this._tableData}
+          enable-virtual-scroll
+          @yatl-row-click=${this.handleRowClicked}>
+        </yatl-table>
+      `;
    }
    private handleRowClicked = (event) => {
@@ -75,11 +81,9 @@ class MyComponent extends LitElement {
 }
 ```
-### npm
-```ts
-import '@timlassiter11/yatl';
+### js
+```js
 const table = document.querySelector('yatl-table');
 table.columns = [
@@ -104,42 +108,52 @@ table.data = [
 ### Vanilla JS
 ```html
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
   <head>
-    <meta charset="UTF-8" />
-    <title>YATL Demo</title>
-    <script src="yatl.min.global.js"></script>
+    <meta charset="utf-8" />
+    <title>Basic Example</title>
     <style>
-      yatl-table {
-        height: 500px;
-        display: block;
-        border: 1px solid #ddd;
+      body {
+        height: 100vh;
+        width: 100vw;
+        margin: 0;
+        padding: 20px;
+        box-sizing: border-box;
       }
     </style>
   </head>
-  <body>
-    <yatl-table id="my-table" enable-footer enable-column-reorder></yatl-table>
+  <body>
+    <yatl-table sortable resizable enable-footer></yatl-table>
+    <script src="../dist/yatl.min.global.js"></script>
     <script>
-      const table = document.getElementById('my-table');
-      // Define Columns
-      table.columns = [
-        { field: 'id', title: 'ID', width: 50 },
-        { field: 'firstName', title: 'First Name', sortable: true },
-        { field: 'lastName', title: 'Last Name', sortable: true },
-        { field: 'email', title: 'Email', width: 200 },
-      ];
-      // Load some data
-      table.data = Array.from({ length: 1000 }, (_, i) => ({
-        id: i + 1,
-        firstName: `User ${i}`,
-        lastName: `Doe`,
-        email: `user${i}@example.com`,
-      }));
+      window.addEventListener('load', () => {
+        const table = document.querySelector('yatl-table');
+        table.columns = [
+          {
+            field: 'index',
+            title: 'ID',
+          },
+          {
+            field: 'name',
+          },
+          {
+            field: 'value',
+          },
+        ];
+        // Generate random rows of data
+        table.data = new Array(100).fill(null).map((v, i) => ({
+          index: i,
+          name: `Row ${i}`,
+          value: Math.random() * 1000,
+        }));
+        table.addEventListener('yatl-row-click', event => {
+          console.log(event.detail);
+        });
+      });
     </script>
   </body>
 </html>
@@ -286,12 +300,4 @@ Most of the time this isn't ideal though and instead we'd like to let the layout
     <div>... Some boring footer info or something</div>
   </div>
 </body>
-```
-### Docs
-Full API docs can be found [here](https://timlassiter11.github.io/YATL/docs/index.html).
-# Examples
-Examples can be found in the examples directoy and are also hosted [here](https://timlassiter11.github.io/YATL/examples/index.html) to view live.
+```

package/dist/index.d.mts CHANGED Viewed

@@ -5,18 +5,10 @@ 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;
+/**
+ * Default type for the table.
+ */
+type UnspecifiedRecord = Record<string, any>;
 /**
  * Defines the possible sorting orders for columns.
  */
@@ -122,22 +114,29 @@ interface SortState {
      */
     priority: number;
 }
+type ColumnRole = 'display' | 'internal';
 /**
- * Column options for the table.
+ * Shared options between both internal and displayed columns.
  */
-interface ColumnOptions<T> {
+interface BaseColumnOptions<T> {
     /**
      * The field name in the data object.
      */
     field: NestedKeyOf<T>;
     /**
-     * The title to display in the header.
+     * Determines if a column is intended to be displayed,
+     * or just for searching and filtering.
      */
-    title?: string;
+    role?: ColumnRole;
     /**
      * Whether the column is sortable.
      */
     sortable?: boolean;
+    /**
+     * A function to use for sorting the column.
+     * This overrides the default sorting behavior.
+     */
+    sorter?: SortValueCallback;
     /**
      * Whether the column is searchable.
      */
@@ -146,15 +145,34 @@ interface ColumnOptions<T> {
      * 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 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;
+}
+/**
+ * Column options for the table.
+ */
+interface DisplayColumnOptions<T> extends BaseColumnOptions<T> {
+    /**
+     * Determines if a column is intended to be displayed,
+     * or just for searching and filtering.
+     */
+    role?: 'display';
+    /**
+     * The title to display in the header.
+     */
+    title?: string;
+    /**
+     * Whether the column should be resizable.
+     */
+    resizable?: boolean;
     /**
      * A function to format the value for display.
      */
@@ -168,22 +186,18 @@ interface ColumnOptions<T> {
      * NOTE: Search highlighting will not work for this cell when used.
      */
     cellRenderer?: CellRenderCallback<T>;
+}
+/**
+ * Internal column definition used for searching and filtering
+ */
+interface InternalColumnOptions<T> extends BaseColumnOptions<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.
+     * Marks this column as internal-only.
+     * It will be indexed for search and filtering, but strictly excluded from the UI.
      */
-    filter?: ColumnFilterCallback;
+    display: 'internal';
 }
+type ColumnOptions<T> = DisplayColumnOptions<T> | InternalColumnOptions<T>;
 /**
  * Represents the current state of a column.
  */
@@ -315,23 +329,32 @@ declare class YatlStateChangeEvent<T> extends YatlEvent<{
     constructor(state: TableState<T>, triggers: string[]);
 }
+declare const createRegexTokenizer: (exp?: string) => (value: string) => {
+    value: string;
+    quoted: boolean;
+}[];
+declare const whitespaceTokenizer: (value: string) => {
+    value: string;
+    quoted: boolean;
+}[];
 /**
  * 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 {
+declare class YatlTable<T extends object = UnspecifiedRecord> extends LitElement {
     static styles: lit.CSSResult[];
     private tableElement;
     private virtualizer?;
     private _enableSearchTokenization;
     private _enableSearchScoring;
     private _columns;
-    private _columnStates;
+    private _columnDefinitionMap;
+    private _columnStateMap;
     private _columnOrder;
     private _storageOptions;
     private _data;
     private _searchQuery;
-    private _searchIncludedFields;
     private _searchTokenizer;
     private _filters;
     private _filteredData;
@@ -344,6 +367,20 @@ declare class YatlTable<T extends object> extends LitElement {
     private queryTokens;
     private resizeState;
     private dragColumn;
+    /**
+     * Default sortability for all columns.
+     * Can be overridden by setting `sortable` on the specific column definition.
+     * * **NOTE:** Changing this will not clear sorted column states.
+     * @default false
+     */
+    sortable: boolean;
+    /**
+     * Default resizability for all columns.
+     * Can be overridden by setting `resizable` on the specific column definition.
+     * *  **NOTE:** Changing this will not clear current column widths.
+     * @default false
+     */
+    resizable: boolean;
     /**
      * Enables virtual scrolling for the table.
      * When enabled, only the visible rows are rendered to the DOM, significantly improving
@@ -408,8 +445,17 @@ declare class YatlTable<T extends object> extends LitElement {
      */
     get columns(): ColumnOptions<T>[];
     set columns(columns: ColumnOptions<T>[]);
+    get displayColumns(): DisplayColumnOptions<T>[];
+    /**
+     * The current order of the columns.
+     * * **NOTE:** This includes hidden columns but not internal columns
+     */
     get columnOrder(): NestedKeyOf<T>[];
     set columnOrder(columns: NestedKeyOf<T>[]);
+    /**
+     * The current visibility state of all columns.
+     * **This will always be ordered by {@link YatlTable.columnOrder}**
+     */
     get columnVisibility(): {
         field: NestedKeyOf<T>;
         visible: boolean;
@@ -418,6 +464,10 @@ declare class YatlTable<T extends object> extends LitElement {
         field: NestedKeyOf<T>;
         visible: boolean;
     }[]);
+    /**
+     * The current sort state of all columns.
+     * **This will always be orderd by {@link YatlTable.columnOrder}**
+     */
     get columnSort(): {
         field: NestedKeyOf<T>;
         sort: SortState | null;
@@ -426,6 +476,10 @@ declare class YatlTable<T extends object> extends LitElement {
         field: NestedKeyOf<T>;
         sort: SortState | null;
     }[]);
+    /**
+     * The current width of all columns.
+     * **This will always be ordered by {@link YatlTable.columnOrder}**
+     */
     get columnWidths(): {
         field: NestedKeyOf<T>;
         width: number | null;
@@ -440,12 +494,6 @@ declare class YatlTable<T extends object> extends LitElement {
      */
     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.
@@ -487,6 +535,8 @@ declare class YatlTable<T extends object> extends LitElement {
     get data(): T[];
     set data(value: T[]);
     get filteredData(): T[];
+    getColumn(field: NestedKeyOf<T>): ColumnOptions<T> | undefined;
+    getDisplayColumn(field: NestedKeyOf<T>): DisplayColumnOptions<T> | undefined;
     /**
      * Gets a copy of the current state of the table.
      */
@@ -580,12 +630,12 @@ declare class YatlTable<T extends object> extends LitElement {
      * @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 renderColumnSortIcon(column: DisplayColumnOptions<T>, state: ColumnState<T>): TemplateResult<1> | typeof nothing;
+    protected renderColumnResizer(column: DisplayColumnOptions<T>, _state: ColumnState<T>): TemplateResult<1> | typeof nothing;
     protected renderHeaderCell(field: NestedKeyOf<T>): TemplateResult<1> | typeof nothing;
     protected renderHeader(): TemplateResult<1>;
-    protected renderCellContents(value: unknown, column: ColumnOptions<T>, row: T): unknown;
-    protected renderCell(field: NestedKeyOf<T>, row: T): TemplateResult<1> | typeof nothing;
+    protected renderCellContents(value: unknown, column: DisplayColumnOptions<T>, row: T): unknown;
+    protected renderCell(field: NestedKeyOf<T>, row: T): TemplateResult<1> | typeof nothing | undefined;
     protected renderRow(row: T, index: number): TemplateResult<1>;
     protected renderBody(): TemplateResult<1>;
     protected renderFooter(): TemplateResult<1> | typeof nothing;
@@ -616,14 +666,17 @@ declare class YatlTable<T extends object> extends LitElement {
     private sortRows;
     private createMetadata;
     private updateInternalQuery;
-    private get columnData();
     /**
      * Gets the width of each column in the
      * order they will appear in the grid.
      */
     private getGridWidths;
     private scheduleSave;
-    private getColumnState;
+    /**
+     * Gets the column state associated with the given field.
+     * If the state doesn't exist, a default state will be created.
+     */
+    private getOrCreateColumnState;
     private saveStateToStorage;
     private loadStateFromStorage;
     private handleHeaderClicked;
@@ -657,8 +710,8 @@ interface EventMap<T> {
 }
 declare global {
     interface HTMLElementTagNameMap {
-        'yatl-table': YatlTable<object>;
+        'yatl-table': YatlTable;
     }
 }
-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, YatlStateChangeEvent, YatlTable, createRegexTokenizer, findColumn, whitespaceTokenizer };
+export { type BaseColumnOptions, type CellPartsCallback, type CellRenderCallback, type ColumnFilterCallback, type ColumnInitOptions, type ColumnOptions, type ColumnRole, type ColumnState, type ComparatorCallback, type Compareable, type DisplayColumnOptions, type FilterCallback, type Filters, type InternalColumnOptions, type NestedKeyOf, type QueryToken, type RestorableColumnState, type RestorableTableState, type RowPartsCallback, type SortOrder, type SortState, type SortValueCallback, type StorageOptions, type TableState, type TokenizerCallback, type UnspecifiedRecord, type ValueFormatterCallback, YatlChangeEvent, YatlColumnReorderEvent, YatlColumnResizeEvent, YatlColumnToggleEvent, YatlEvent, YatlRowClickEvent, YatlSearchEvent, YatlSortEvent, YatlStateChangeEvent, YatlTable, createRegexTokenizer, whitespaceTokenizer };