@toolbox-web/grid 0.6.0 → 1.1.0

package/lib/plugins/master-detail/MasterDetailPlugin.d.ts

@@ -2,25 +2,103 @@ import { BaseGridPlugin, CellClickEvent, GridElement, RowClickEvent } from '../.
 import { ColumnConfig } from '../../core/types';
 import { MasterDetailConfig } from './types';
 /**
- * Master/Detail Plugin for tbw-grid
+ * Master-Detail Plugin for tbw-grid
+ *
+ * Creates expandable detail rows that reveal additional content beneath each master row.
+ * Perfect for order/line-item UIs, employee/department views, or any scenario where
+ * you need to show related data without navigating away.
+ *
+ * ## Installation
  *
- * @example
+ * ```ts
+ * import { MasterDetailPlugin } from '@toolbox-web/grid/plugins/master-detail';
+ * ```
+ *
+ * ## Configuration Options
+ *
+ * | Option | Type | Default | Description |
+ * |--------|------|---------|-------------|
+ * | `detailRenderer` | `(row) => HTMLElement \| string` | required | Render function for detail content |
+ * | `expandOnRowClick` | `boolean` | `false` | Expand when clicking the row |
+ * | `detailHeight` | `number \| 'auto'` | `'auto'` | Fixed height or auto-size |
+ * | `collapseOnClickOutside` | `boolean` | `false` | Collapse when clicking outside |
+ * | `showExpandColumn` | `boolean` | `true` | Show expand/collapse column |
+ * | `animation` | `false \| 'slide' \| 'fade'` | `'slide'` | Animation style |
+ *
+ * ## Programmatic API
+ *
+ * | Method | Signature | Description |
+ * |--------|-----------|-------------|
+ * | `expandRow` | `(rowIndex) => void` | Expand a specific row |
+ * | `collapseRow` | `(rowIndex) => void` | Collapse a specific row |
+ * | `toggleRow` | `(rowIndex) => void` | Toggle row expansion |
+ * | `expandAll` | `() => void` | Expand all rows |
+ * | `collapseAll` | `() => void` | Collapse all rows |
+ * | `isRowExpanded` | `(rowIndex) => boolean` | Check if row is expanded |
+ *
+ * ## CSS Custom Properties
+ *
+ * | Property | Default | Description |
+ * |----------|---------|-------------|
+ * | `--tbw-master-detail-bg` | `var(--tbw-color-row-alt)` | Detail row background |
+ * | `--tbw-master-detail-border` | `var(--tbw-color-border)` | Detail row border |
+ * | `--tbw-detail-padding` | `1em` | Detail content padding |
+ * | `--tbw-animation-duration` | `200ms` | Expand/collapse animation |
+ *
+ * @example Basic Master-Detail with HTML Template
+ * ```ts
+ * import '@toolbox-web/grid';
+ * import { MasterDetailPlugin } from '@toolbox-web/grid/plugins/master-detail';
+ *
+ * grid.gridConfig = {
+ *   columns: [
+ *     { field: 'orderId', header: 'Order ID' },
+ *     { field: 'customer', header: 'Customer' },
+ *     { field: 'total', header: 'Total', type: 'currency' },
+ *   ],
+ *   plugins: [
+ *     new MasterDetailPlugin({
+ *       detailRenderer: (row) => `
+ *         <div class="order-details">
+ *           <h4>Order Items</h4>
+ *           <ul>${row.items.map(i => `<li>${i.name} - $${i.price}</li>`).join('')}</ul>
+ *         </div>
+ *       `,
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @example Nested Grid in Detail
  * ```ts
  * new MasterDetailPlugin({
- *   enabled: true,
- *   detailRenderer: (row) => `<div>Details for ${row.name}</div>`,
- *   expandOnRowClick: true,
+ *   detailRenderer: (row) => {
+ *     const childGrid = document.createElement('tbw-grid');
+ *     childGrid.style.height = '200px';
+ *     childGrid.gridConfig = { columns: [...] };
+ *     childGrid.rows = row.items || [];
+ *     return childGrid;
+ *   },
  * })
  * ```
+ *
+ * @see {@link MasterDetailConfig} for all configuration options
+ * @see {@link DetailExpandDetail} for expand/collapse event details
+ *
+ * @internal Extends BaseGridPlugin
  */
 export declare class MasterDetailPlugin extends BaseGridPlugin<MasterDetailConfig> {
     #private;
+    /** @internal */
     readonly name = "masterDetail";
+    /** @internal */
     readonly styles: string;
+    /** @internal */
     protected get defaultConfig(): Partial<MasterDetailConfig>;
     /**
      * Called when plugin is attached to the grid.
      * Parses light DOM for `<tbw-grid-detail>` elements to configure detail templates.
+     * @internal
      */
     attach(grid: GridElement): void;
     /**
@@ -71,15 +149,22 @@ export declare class MasterDetailPlugin extends BaseGridPlugin<MasterDetailConfi
      * Toggle a row's detail and emit event.
      */
     private toggleAndEmit;
+    /** @internal */
     detach(): void;
+    /** @internal */
     processColumns(columns: readonly ColumnConfig[]): ColumnConfig[];
+    /** @internal */
     onRowClick(event: RowClickEvent): boolean | void;
+    /** @internal */
     onCellClick(event: CellClickEvent): boolean | void;
+    /** @internal */
     onKeyDown(event: KeyboardEvent): boolean | void;
+    /** @internal */
     afterRender(): void;
     /**
      * Called on scroll to sync detail elements with visible rows.
      * Removes details for rows that scrolled out of view and reattaches for visible rows.
+     * @internal
      */
     onScrollRender(): void;
     /**

package/lib/plugins/master-detail/MasterDetailPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MasterDetailPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/master-detail/MasterDetailPlugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE3G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AASrD,OAAO,KAAK,EAA+C,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE/F;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,kBAAkB,CAAC;;IACxE,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,SAAkB,MAAM,SAAU;IAElC,cAAuB,aAAa,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAQlE;IAID;;;OAGG;IACM,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAKxC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,mBAAmB;IAqE3B;;;OAGG;IACH,OAAO,KAAK,cAAc,GAGzB;IAED;;OAEG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,cAAc,CAAoC;IAE1D,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAO;IAEpD;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,aAAa;IAaZ,MAAM,IAAI,IAAI;IAQd,cAAc,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,EAAE;IA2ChE,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI;IAMhD,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,GAAG,IAAI;IAgBlD,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI;IAsB/C,WAAW,IAAI,IAAI;IAI5B;;;OAGG;IACM,cAAc,IAAI,IAAI;IA2E/B;;;OAGG;IACM,cAAc,IAAI,MAAM;IAQjC;;;OAGG;IACM,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM;IAY7D;;;OAGG;IACM,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IA8CxF;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQhC;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ9B;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKrC;;OAEG;IACH,SAAS,IAAI,IAAI;IAOjB;;OAEG;IACH,WAAW,IAAI,IAAI;IAKnB;;;OAGG;IACH,eAAe,IAAI,MAAM,EAAE;IAS3B;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAK3D;;;;;;OAMG;IACH,qBAAqB,IAAI,IAAI;CA0B9B"}
+{"version":3,"file":"MasterDetailPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/master-detail/MasterDetailPlugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE3G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AASrD,OAAO,KAAK,EAA+C,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,kBAAkB,CAAC;;IACxE,gBAAgB;IAChB,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,gBAAgB;IAChB,SAAkB,MAAM,SAAU;IAElC,gBAAgB;IAChB,cAAuB,aAAa,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAQlE;IAID;;;;OAIG;IACM,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAKxC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,mBAAmB;IAqE3B;;;OAGG;IACH,OAAO,KAAK,cAAc,GAGzB;IAED;;OAEG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,cAAc,CAAoC;IAE1D,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAO;IAEpD;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,aAAa;IAarB,gBAAgB;IACP,MAAM,IAAI,IAAI;IAQvB,gBAAgB;IACP,cAAc,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,EAAE;IA2CzE,gBAAgB;IACP,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI;IAMzD,gBAAgB;IACP,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,GAAG,IAAI;IAgB3D,gBAAgB;IACP,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI;IAsBxD,gBAAgB;IACP,WAAW,IAAI,IAAI;IAI5B;;;;OAIG;IACM,cAAc,IAAI,IAAI;IA2E/B;;;OAGG;IACM,cAAc,IAAI,MAAM;IAQjC;;;OAGG;IACM,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM;IAY7D;;;OAGG;IACM,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IA8CxF;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQhC;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ9B;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKrC;;OAEG;IACH,SAAS,IAAI,IAAI;IAOjB;;OAEG;IACH,WAAW,IAAI,IAAI;IAKnB;;;OAGG;IACH,eAAe,IAAI,MAAM,EAAE;IAS3B;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAK3D;;;;;;OAMG;IACH,qBAAqB,IAAI,IAAI;CA0B9B"}

package/lib/plugins/master-detail/index.d.ts

@@ -1,6 +1,8 @@
 /**
  * Master Detail Plugin Entry Point
  * Re-exports plugin class and types for tree-shakeable imports.
+ *
+ * @module Plugins/Master-Detail
  */
 export { MasterDetailPlugin } from './MasterDetailPlugin';
 export type { ExpandCollapseAnimation, MasterDetailConfig } from './types';

package/lib/plugins/master-detail/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/master-detail/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/master-detail/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC"}

package/lib/plugins/master-detail/index.js

@@ -119,6 +119,28 @@ class T {
    * ```
    */
   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.
@@ -278,23 +300,6 @@ class T {
   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.
@@ -449,8 +454,11 @@ function M(n, e, t, i) {
 }
 const F = "@layer tbw-plugins{tbw-grid .cell[data-field=__tbw_expander]{border-right:none!important;padding:0;display:flex;align-items:center;justify-content:center}tbw-grid .header-row .cell[data-field=__tbw_expander]{display:none}tbw-grid .header-row .cell[data-field=__tbw_expander]+.cell{grid-column:1 / 3}tbw-grid .master-detail-expander{display:flex;align-items:center;justify-content:center;width:100%;height:100%}tbw-grid .master-detail-toggle{cursor:pointer;opacity:.7;-webkit-user-select:none;user-select:none;display:inline-flex;align-items:center;justify-content:center}tbw-grid .master-detail-toggle:hover{opacity:1}tbw-grid .master-detail-row{grid-column:1 / -1;display:grid;background:var(--tbw-master-detail-bg, var(--tbw-color-row-alt));border-bottom:1px solid var(--tbw-master-detail-border, var(--tbw-color-border));overflow:hidden}tbw-grid .master-detail-cell{padding:var(--tbw-detail-padding, var(--tbw-spacing-xl, 1rem));overflow:auto}tbw-grid .master-detail-row.tbw-expanding{animation:tbw-detail-expand var(--tbw-animation-duration, .2s) var(--tbw-animation-easing, ease-out) forwards}tbw-grid .master-detail-row.tbw-collapsing{animation:tbw-detail-collapse var(--tbw-animation-duration, .2s) var(--tbw-animation-easing, ease-out) forwards}@keyframes tbw-detail-expand{0%{opacity:0;max-height:0;padding-top:0;padding-bottom:0}to{opacity:1;max-height:var(--tbw-detail-max-height, 31.25rem);padding-top:var(--tbw-detail-padding, var(--tbw-spacing-xl, 1rem));padding-bottom:var(--tbw-detail-padding, var(--tbw-spacing-xl, 1rem))}}@keyframes tbw-detail-collapse{0%{opacity:1;max-height:var(--tbw-detail-max-height, 31.25rem)}to{opacity:0;max-height:0}}}";
 class w extends T {
+  /** @internal */
   name = "masterDetail";
+  /** @internal */
   styles = F;
+  /** @internal */
   get defaultConfig() {
     return {
       detailHeight: "auto",
@@ -465,6 +473,7 @@ class w extends T {
   /**
    * Called when plugin is attached to the grid.
    * Parses light DOM for `<tbw-grid-detail>` elements to configure detail templates.
+   * @internal
    */
   attach(e) {
     super.attach(e), this.parseLightDomDetail();
@@ -572,11 +581,13 @@ class w extends T {
   }
   // #endregion
   // #region Lifecycle
+  /** @internal */
   detach() {
     this.expandedRows.clear(), this.detailElements.clear();
   }
   // #endregion
   // #region Hooks
+  /** @internal */
   processColumns(e) {
     if (!this.config.detailRenderer || this.config.showExpandColumn === !1)
       return [...e];
@@ -591,15 +602,18 @@ class w extends T {
       return d.className = `master-detail-toggle${r ? " expanded" : ""}`, this.setIcon(d, this.resolveIcon(r ? "collapse" : "expand")), d.setAttribute("role", "button"), d.setAttribute("tabindex", "0"), d.setAttribute("aria-expanded", String(r)), d.setAttribute("aria-label", r ? "Collapse details" : "Expand details"), a.appendChild(d), a;
     }, [s, ...t];
   }
+  /** @internal */
   onRowClick(e) {
     if (!(!this.config.expandOnRowClick || !this.config.detailRenderer))
       return this.toggleAndEmit(e.row, e.rowIndex), !1;
   }
+  /** @internal */
   onCellClick(e) {
     if (e.originalEvent?.target?.classList.contains("master-detail-toggle"))
       return this.toggleAndEmit(e.row, e.rowIndex), !0;
     this.expandedRows.size > 0 && queueMicrotask(() => this.#e());
   }
+  /** @internal */
   onKeyDown(e) {
     if (e.key !== " ") return;
     const t = this.grid._focusCol, i = this.grid._focusRow, s = this.columns[t];
@@ -608,12 +622,14 @@ class w extends T {
     if (l)
       return e.preventDefault(), this.toggleAndEmit(l, i), this.requestRenderWithFocus(), !0;
   }
+  /** @internal */
   afterRender() {
     this.#e();
   }
   /**
    * Called on scroll to sync detail elements with visible rows.
    * Removes details for rows that scrolled out of view and reattaches for visible rows.
+   * @internal
    */
   onScrollRender() {
     !this.config.detailRenderer || this.expandedRows.size === 0 || this.#e();