@toolbox-web/grid 0.6.0 → 1.1.0

package/lib/plugins/selection/types.d.ts

@@ -4,16 +4,63 @@
  * Type definitions for the selection feature.
  */
 /**
- * Selection mode for the grid:
- * - 'cell': Single cell selection (default). No border, just focus highlight.
- * - 'row': Row selection. Clicking a cell selects the entire row. Uses focus outline color.
- * - 'range': Range selection. Shift+click or drag to select rectangular cell ranges. Uses success border color.
+ * Selection mode for the grid.
+ *
+ * Each mode offers different selection behavior suited to different use cases:
+ *
+ * | Mode | Use Case | Behavior |
+ * |------|----------|----------|
+ * | `'cell'` | Spreadsheet-style editing | Single cell focus. Click to select one cell at a time. |
+ * | `'row'` | Record-based operations | Full row selection. Click anywhere to select the entire row. |
+ * | `'range'` | Bulk operations, export | Rectangular selection. Drag or Shift+Click to select ranges. |
+ *
+ * @example
+ * ```ts
+ * // Cell mode (default) - for spreadsheet-like interaction
+ * new SelectionPlugin({ mode: 'cell' })
+ *
+ * // Row mode - for selecting complete records
+ * new SelectionPlugin({ mode: 'row' })
+ *
+ * // Range mode - for bulk copy/paste operations
+ * new SelectionPlugin({ mode: 'range' })
+ * ```
+ *
+ * @see [Cell Mode Demo](?path=/story/grid-plugins-selection--default) - Click cells to select
+ * @see [Row Mode Demo](?path=/story/grid-plugins-selection--row-mode) - Full row selection
+ * @see [Range Mode Demo](?path=/story/grid-plugins-selection--range-mode) - Drag to select ranges
  */
 export type SelectionMode = 'cell' | 'row' | 'range';
+/**
+ * Mouse event type that triggers selection.
+ *
+ * - `'click'` - Single click activates selection (default)
+ * - `'dblclick'` - Double-click activates selection; single-click only focuses
+ *
+ * **Note:** Only applies to `'cell'` and `'row'` modes. Range mode uses drag
+ * selection (mousedown → mousemove) which is unaffected by this option.
+ *
+ * @example
+ * ```ts
+ * // Double-click to select - useful for data entry grids
+ * new SelectionPlugin({ mode: 'cell', triggerOn: 'dblclick' })
+ * ```
+ */
+export type SelectionTrigger = 'click' | 'dblclick';
 /** Configuration options for the selection plugin */
 export interface SelectionConfig {
     /** Selection mode (default: 'cell') */
     mode: SelectionMode;
+    /**
+     * Mouse event type that triggers selection (default: 'click').
+     *
+     * - `'click'` - Single click activates selection
+     * - `'dblclick'` - Double-click activates selection; single-click only focuses
+     *
+     * **Note:** Only applies to `'cell'` and `'row'` modes. Range mode uses drag
+     * selection which is unaffected by this option.
+     */
+    triggerOn?: SelectionTrigger;
 }
 /** Internal state managed by the selection plugin */
 export interface SelectionState {

package/lib/plugins/selection/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/selection/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AAErD,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,wDAAwD;IACxD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAID,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,8BAA8B;IAC9B,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,IAAI,EAAE,aAAa,CAAC;IACpB,iHAAiH;IACjH,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,IAAI,EAAE,aAAa,CAAC;IACpB,yDAAyD;IACzD,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,yFAAyF;IACzF,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7C;AAED,0CAA0C;AAC1C,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,uEAAuE;IACvE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,+CAA+C;IAC/C,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,sCAAsC;IACtC,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,0CAA0C;IAC1C,UAAU,EAAE,OAAO,CAAC;IACpB,oCAAoC;IACpC,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACnD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/selection/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AAErD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,UAAU,CAAC;AAEpD,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,IAAI,EAAE,aAAa,CAAC;IAEpB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,wDAAwD;IACxD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAID,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,8BAA8B;IAC9B,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,IAAI,EAAE,aAAa,CAAC;IACpB,iHAAiH;IACjH,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,IAAI,EAAE,aAAa,CAAC;IACpB,yDAAyD;IACzD,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,yFAAyF;IACzF,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7C;AAED,0CAA0C;AAC1C,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,uEAAuE;IACvE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,+CAA+C;IAC/C,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,sCAAsC;IACtC,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,0CAA0C;IAC1C,UAAU,EAAE,OAAO,CAAC;IACpB,oCAAoC;IACpC,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACnD"}

package/lib/plugins/server-side/ServerSidePlugin.d.ts

@@ -1,16 +1,74 @@
 import { BaseGridPlugin, ScrollEvent } from '../../core/plugin/base-plugin';
 import { ServerSideConfig, ServerSideDataSource } from './types';
 /**
- * Server-Side Plugin for tbw-grid
+ * Server-Side Data Plugin for tbw-grid
  *
- * @example
+ * Enables lazy loading of data from a remote server with caching and block-based fetching.
+ * Ideal for large datasets where loading all data upfront is impractical.
+ *
+ * ## Installation
+ *
+ * ```ts
+ * import { ServerSidePlugin } from '@toolbox-web/grid/plugins/server-side';
+ * ```
+ *
+ * ## Configuration Options
+ *
+ * | Option | Type | Default | Description |
+ * |--------|------|---------|-------------|
+ * | `pageSize` | `number` | `100` | Rows per block |
+ * | `cacheBlockSize` | `number` | `pageSize` | Cache block size |
+ * | `maxConcurrentRequests` | `number` | `2` | Max parallel data requests |
+ *
+ * ## DataSource Interface
+ *
+ * ```ts
+ * interface ServerSideDataSource {
+ *   getRows(params: GetRowsParams): Promise<GetRowsResult>;
+ * }
+ * ```
+ *
+ * ## Programmatic API
+ *
+ * | Method | Signature | Description |
+ * |--------|-----------|-------------|
+ * | `setDataSource` | `(ds: ServerSideDataSource) => void` | Set the data source |
+ * | `refresh` | `() => void` | Refresh current data |
+ * | `clearCache` | `() => void` | Clear all cached blocks |
+ *
+ * @example Basic Server-Side Loading
  * ```ts
- * const plugin = new ServerSidePlugin({ cacheBlockSize: 100 });
- * plugin.setDataSource(myDataSource);
+ * import '@toolbox-web/grid';
+ * import { ServerSidePlugin } from '@toolbox-web/grid/plugins/server-side';
+ *
+ * const dataSource = {
+ *   async getRows(params) {
+ *     const response = await fetch(
+ *       `/api/data?start=${params.startRow}&end=${params.endRow}`
+ *     );
+ *     const data = await response.json();
+ *     return { rows: data.rows, totalRowCount: data.total };
+ *   },
+ * };
+ *
+ * const plugin = new ServerSidePlugin({ pageSize: 50 });
+ * grid.gridConfig = {
+ *   columns: [...],
+ *   plugins: [plugin],
+ * };
+ *
+ * grid.ready().then(() => plugin.setDataSource(dataSource));
  * ```
+ *
+ * @see {@link ServerSideConfig} for configuration options
+ * @see {@link ServerSideDataSource} for data source interface
+ *
+ * @internal Extends BaseGridPlugin
  */
 export declare class ServerSidePlugin extends BaseGridPlugin<ServerSideConfig> {
+    /** @internal */
     readonly name = "serverSide";
+    /** @internal */
     protected get defaultConfig(): Partial<ServerSideConfig>;
     private dataSource;
     private totalRowCount;
@@ -18,12 +76,15 @@ export declare class ServerSidePlugin extends BaseGridPlugin<ServerSideConfig> {
     private loadingBlocks;
     private lastRequestId;
     private scrollDebounceTimer?;
+    /** @internal */
     detach(): void;
     /**
      * Check current viewport and load any missing blocks.
      */
     private loadRequiredBlocks;
+    /** @internal */
     processRows(rows: readonly unknown[]): unknown[];
+    /** @internal */
     onScroll(event: ScrollEvent): void;
     /**
      * Set the data source for server-side loading.

package/lib/plugins/server-side/ServerSidePlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServerSidePlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/server-side/ServerSidePlugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAE5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAKtE;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,SAAQ,cAAc,CAAC,gBAAgB,CAAC;IACpE,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,cAAuB,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAMhE;IAGD,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,mBAAmB,CAAC,CAAgC;IAKnD,MAAM,IAAI,IAAI;IAevB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA0CjB,WAAW,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,EAAE;IAahD,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAkB3C;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,oBAAoB,GAAG,IAAI;IAcrD;;OAEG;IACH,OAAO,IAAI,IAAI;IAOf;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAMtC;;OAEG;IACH,mBAAmB,IAAI,MAAM;CAI9B"}
+{"version":3,"file":"ServerSidePlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/server-side/ServerSidePlugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAE5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAKtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,qBAAa,gBAAiB,SAAQ,cAAc,CAAC,gBAAgB,CAAC;IACpE,gBAAgB;IAChB,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,gBAAgB;IAChB,cAAuB,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAMhE;IAGD,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,mBAAmB,CAAC,CAAgC;IAK5D,gBAAgB;IACP,MAAM,IAAI,IAAI;IAevB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA0C1B,gBAAgB;IACP,WAAW,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,EAAE;IAazD,gBAAgB;IACP,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAkB3C;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,oBAAoB,GAAG,IAAI;IAcrD;;OAEG;IACH,OAAO,IAAI,IAAI;IAOf;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAMtC;;OAEG;IACH,mBAAmB,IAAI,MAAM;CAI9B"}

package/lib/plugins/server-side/index.d.ts

@@ -1,7 +1,9 @@
 /**
  * Server Side Plugin Entry Point
  * Re-exports plugin class and types for tree-shakeable imports.
+ *
+ * @module Plugins/Server-Side
  */
 export { ServerSidePlugin } from './ServerSidePlugin';
-export type { ServerSideConfig, ServerSideDataSource, GetRowsParams, GetRowsResult } from './types';
+export type { GetRowsParams, GetRowsResult, ServerSideConfig, ServerSideDataSource } from './types';
 //# sourceMappingURL=index.d.ts.map

package/lib/plugins/server-side/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/server-side/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/server-side/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC"}

package/lib/plugins/server-side/index.js

@@ -25,6 +25,28 @@ class d {
    * ```
    */
   static dependencies;
+  /**
+   * Plugin manifest - declares owned properties, config rules, and hook priorities.
+   *
+   * This is read by the configuration validator to:
+   * - Validate that required plugins are loaded when their properties are used
+   * - Execute configRules to detect invalid/conflicting settings
+   * - Order hook execution based on priority
+   *
+   * @example
+   * ```typescript
+   * static override readonly manifest: PluginManifest<MyConfig> = {
+   *   ownedProperties: [
+   *     { property: 'myProp', level: 'column', description: 'the "myProp" column property' },
+   *   ],
+   *   configRules: [
+   *     { id: 'myPlugin/conflict', severity: 'warn', message: '...', check: (c) => c.a && c.b },
+   *   ],
+   * };
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static manifest;
   /**
    * Plugin version - defaults to grid version for built-in plugins.
    * Third-party plugins can override with their own semver.
@@ -184,23 +206,6 @@ class d {
   get gridElement() {
     return this.grid;
   }
-  /**
-   * Get the render root of the grid for DOM queries.
-   * @deprecated Use `gridElement` instead. This getter exists only for backward compatibility.
-   *
-   * With Shadow DOM removed, the grid element itself is the render root.
-   * All new code should use `this.gridElement` for DOM queries.
-   *
-   * @example
-   * // OLD (deprecated)
-   * const rows = this.shadowRoot?.querySelector('.rows');
-   *
-   * // NEW (preferred)
-   * const rows = this.gridElement.querySelector('.rows');
-   */
-  get shadowRoot() {
-    return this.gridElement;
-  }
   /**
    * Get the disconnect signal for event listener cleanup.
    * This signal is aborted when the grid disconnects from the DOM.
@@ -335,7 +340,9 @@ function g(s, e, t) {
 }
 const f = 100;
 class R extends d {
+  /** @internal */
   name = "serverSide";
+  /** @internal */
   get defaultConfig() {
     return {
       pageSize: 100,
@@ -352,6 +359,7 @@ class R extends d {
   scrollDebounceTimer;
   // #endregion
   // #region Lifecycle
+  /** @internal */
   detach() {
     this.dataSource = null, this.totalRowCount = 0, this.loadedBlocks.clear(), this.loadingBlocks.clear(), this.lastRequestId = 0, this.scrollDebounceTimer && (clearTimeout(this.scrollDebounceTimer), this.scrollDebounceTimer = void 0);
   }
@@ -376,6 +384,7 @@ class R extends d {
   }
   // #endregion
   // #region Hooks
+  /** @internal */
   processRows(e) {
     if (!this.dataSource) return [...e];
     const t = [];
@@ -385,6 +394,7 @@ class R extends d {
     }
     return t;
   }
+  /** @internal */
   onScroll(e) {
     this.dataSource && (this.loadRequiredBlocks(), this.scrollDebounceTimer && clearTimeout(this.scrollDebounceTimer), this.scrollDebounceTimer = setTimeout(() => {
       this.loadRequiredBlocks();