@toolbox-web/grid 0.5.0 → 1.0.0

package/lib/plugins/grouping-rows/GroupingRowsPlugin.d.ts

@@ -16,19 +16,89 @@ export interface GroupState {
 /**
  * Row Grouping Plugin for tbw-grid
  *
- * @example
+ * Organizes rows into collapsible hierarchical groups. Perfect for organizing data
+ * by category, department, status, or any other dimension—or even multiple dimensions
+ * for nested grouping. Includes aggregation support for summarizing group data.
+ *
+ * ## Installation
+ *
+ * ```ts
+ * import { GroupingRowsPlugin } from '@toolbox-web/grid/plugins/grouping-rows';
+ * ```
+ *
+ * ## Configuration Options
+ *
+ * | Option | Type | Default | Description |
+ * |--------|------|---------|-------------|
+ * | `groupOn` | `(row) => string[]` | - | Callback returning group path array |
+ * | `defaultExpanded` | `boolean` | `false` | Start all groups expanded |
+ * | `showRowCount` | `boolean` | `true` | Show row count in group header |
+ * | `indentWidth` | `number` | `20` | Indentation per level (pixels) |
+ * | `fullWidth` | `boolean` | `true` | Group row spans full width |
+ * | `animation` | `false \| 'slide' \| 'fade'` | `'slide'` | Expand/collapse animation |
+ *
+ * ## Programmatic API
+ *
+ * | Method | Signature | Description |
+ * |--------|-----------|-------------|
+ * | `expandGroup` | `(path: string[]) => void` | Expand a specific group |
+ * | `collapseGroup` | `(path: string[]) => void` | Collapse a specific group |
+ * | `expandAll` | `() => void` | Expand all groups |
+ * | `collapseAll` | `() => void` | Collapse all groups |
+ * | `isGroupExpanded` | `(path: string[]) => boolean` | Check if group is expanded |
+ * | `getGroupState` | `() => GroupState` | Get current grouping state |
+ *
+ * ## CSS Custom Properties
+ *
+ * | Property | Default | Description |
+ * |----------|---------|-------------|
+ * | `--tbw-group-indent-width` | `1.25em` | Indentation per group level |
+ * | `--tbw-grouping-rows-bg` | `var(--tbw-color-panel-bg)` | Group row background |
+ * | `--tbw-grouping-rows-count-color` | `var(--tbw-color-fg-muted)` | Count badge color |
+ * | `--tbw-animation-duration` | `200ms` | Expand/collapse animation |
+ *
+ * @example Single-Level Grouping by Department
+ * ```ts
+ * import '@toolbox-web/grid';
+ * import { GroupingRowsPlugin } from '@toolbox-web/grid/plugins/grouping-rows';
+ *
+ * const grid = document.querySelector('tbw-grid');
+ * grid.gridConfig = {
+ *   columns: [
+ *     { field: 'name', header: 'Employee' },
+ *     { field: 'department', header: 'Department' },
+ *     { field: 'salary', header: 'Salary', type: 'currency' },
+ *   ],
+ *   plugins: [
+ *     new GroupingRowsPlugin({
+ *       groupOn: (row) => [row.department],
+ *       showRowCount: true,
+ *       defaultExpanded: false,
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @example Multi-Level Grouping
  * ```ts
  * new GroupingRowsPlugin({
- *   enabled: true,
- *   groupOn: (row) => row.category,
- *   defaultExpanded: false,
- *   showRowCount: true,
+ *   groupOn: (row) => [row.region, row.department, row.team],
+ *   indentWidth: 24,
+ *   animation: 'slide',
  * })
  * ```
+ *
+ * @see {@link GroupingRowsConfig} for all configuration options
+ * @see {@link GroupState} for the group state structure
+ *
+ * @internal Extends BaseGridPlugin
  */
 export declare class GroupingRowsPlugin extends BaseGridPlugin<GroupingRowsConfig> {
+    /** @internal */
     readonly name = "groupingRows";
+    /** @internal */
     readonly styles: string;
+    /** @internal */
     protected get defaultConfig(): Partial<GroupingRowsConfig>;
     private expandedKeys;
     private flattenedRows;
@@ -40,19 +110,25 @@ export declare class GroupingRowsPlugin extends BaseGridPlugin<GroupingRowsConfi
      * Uses base class isAnimationEnabled to respect grid-level settings.
      */
     private get animationStyle();
+    /** @internal */
     detach(): void;
     /**
      * Auto-detect grouping configuration from grid config.
      * Called by plugin system to determine if plugin should activate.
      */
     static detect(rows: readonly any[], config: any): boolean;
+    /** @internal */
     processRows(rows: readonly any[]): any[];
+    /** @internal */
     onCellClick(event: CellClickEvent): boolean | void;
+    /** @internal */
     onKeyDown(event: KeyboardEvent): boolean | void;
     /**
      * Render a row. Returns true if we handled the row (group row), false otherwise.
+     * @internal
      */
     renderRow(row: any, rowEl: HTMLElement, _rowIndex: number): boolean;
+    /** @internal */
     afterRender(): void;
     /**
      * Create a toggle button for expanding/collapsing a group.

package/lib/plugins/grouping-rows/GroupingRowsPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GroupingRowsPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/grouping-rows/GroupingRowsPlugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAY/E,OAAO,KAAK,EAEV,kBAAkB,EAGlB,SAAS,EACV,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAClB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;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;IAGD,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,aAAa,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,aAAa,CAAqB;IAK1C;;;OAGG;IACH,OAAO,KAAK,cAAc,GAGzB;IAMQ,MAAM,IAAI,IAAI;IAWvB;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO;IAIhD,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE;IA2DxC,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,GAAG,IAAI;IAalD,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI;IAkBxD;;OAEG;IACM,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAkEnE,WAAW,IAAI,IAAI;IAyB5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,uBAAuB;IA8B/B,OAAO,CAAC,uBAAuB;IAsE/B;;OAEG;IACH,SAAS,IAAI,IAAI;IAKjB;;OAEG;IACH,WAAW,IAAI,IAAI;IAKnB;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAgBzB;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAS3B;;;OAGG;IACH,aAAa,IAAI,UAAU;IAU3B;;;OAGG;IACH,WAAW,IAAI,MAAM;IAIrB;;;OAGG;IACH,aAAa,IAAI,IAAI;IAIrB;;;OAGG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAI7B;;;OAGG;IACH,gBAAgB,IAAI,SAAS,EAAE;IAI/B;;;OAGG;IACH,gBAAgB,IAAI,OAAO;IAI3B;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,SAAS,GAAG,IAAI;CAK7E"}
+{"version":3,"file":"GroupingRowsPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/grouping-rows/GroupingRowsPlugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAY/E,OAAO,KAAK,EAEV,kBAAkB,EAGlB,SAAS,EACV,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAClB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;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;IAGD,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,aAAa,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,aAAa,CAAqB;IAK1C;;;OAGG;IACH,OAAO,KAAK,cAAc,GAGzB;IAMD,gBAAgB;IACP,MAAM,IAAI,IAAI;IAWvB;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO;IAIzD,gBAAgB;IACP,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE;IA2DjD,gBAAgB;IACP,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,GAAG,IAAI;IAa3D,gBAAgB;IACP,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI;IAkBxD;;;OAGG;IACM,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAkE5E,gBAAgB;IACP,WAAW,IAAI,IAAI;IAyB5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,uBAAuB;IA8B/B,OAAO,CAAC,uBAAuB;IAsE/B;;OAEG;IACH,SAAS,IAAI,IAAI;IAKjB;;OAEG;IACH,WAAW,IAAI,IAAI;IAKnB;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAgBzB;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAS3B;;;OAGG;IACH,aAAa,IAAI,UAAU;IAU3B;;;OAGG;IACH,WAAW,IAAI,MAAM;IAIrB;;;OAGG;IACH,aAAa,IAAI,IAAI;IAIrB;;;OAGG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAI7B;;;OAGG;IACH,gBAAgB,IAAI,SAAS,EAAE;IAI/B;;;OAGG;IACH,gBAAgB,IAAI,OAAO;IAI3B;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,SAAS,GAAG,IAAI;CAK7E"}

package/lib/plugins/grouping-rows/index.d.ts

@@ -1,7 +1,9 @@
 /**
  * Grouping Rows Plugin Entry Point
  * Re-exports plugin class and types for tree-shakeable imports.
+ *
+ * @module Plugins/Row Grouping
  */
 export { GroupingRowsPlugin } from './GroupingRowsPlugin';
-export type { GroupingRowsConfig, GroupRowRenderParams } from './types';
+export type { GroupRowRenderParams, GroupingRowsConfig } from './types';
 //# sourceMappingURL=index.d.ts.map

package/lib/plugins/grouping-rows/index.d.ts.map

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

package/lib/plugins/grouping-rows/index.js

@@ -184,23 +184,6 @@ class R {
   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.
@@ -400,13 +383,13 @@ function k(n, e) {
   const t = new Set(n);
   return t.has(e) ? t.delete(e) : t.add(e), t;
 }
-function E(n) {
+function S(n) {
   const e = /* @__PURE__ */ new Set();
   for (const t of n)
     t.kind === "group" && e.add(t.key);
   return e;
 }
-function S() {
+function E() {
   return /* @__PURE__ */ new Set();
 }
 function K(n) {
@@ -414,8 +397,11 @@ function K(n) {
 }
 const G = "@layer tbw-plugins{.group-row{display:grid;grid-template-columns:var(--tbw-column-template);background:var(--tbw-grouping-rows-bg, var(--tbw-color-panel-bg));font-weight:500;border-bottom:var(--tbw-row-divider);min-height:var(--tbw-row-height)}.group-row .cell{display:flex;align-items:center;padding:var(--tbw-cell-padding, .125rem .5rem)}.group-row:hover{background:var(--tbw-grouping-rows-bg-hover, var(--tbw-color-row-hover))}.group-toggle{cursor:pointer;-webkit-user-select:none;user-select:none;display:inline-flex;align-items:center;justify-content:center;width:var(--tbw-toggle-size, 1.25rem);height:var(--tbw-toggle-size, 1.25rem);margin-right:.25rem;background:none;border:0;font:inherit}.group-toggle:hover{background:var(--tbw-grouping-rows-toggle-hover, var(--tbw-color-row-hover));border-radius:var(--tbw-border-radius, .125rem)}.group-label{display:inline-flex;align-items:center;gap:var(--tbw-panel-gap, var(--tbw-spacing-md, .5rem))}.group-count{color:var(--tbw-grouping-rows-count-color, var(--tbw-color-fg-muted));font-size:var(--tbw-font-size-xs, .85em);font-weight:400}.group-row{padding-left:calc(var(--tbw-group-depth, 0) * var(--tbw-group-indent-width, 1.25em))}.data-grid-row.tbw-group-slide-in{animation:tbw-group-slide-in var(--tbw-animation-duration, .2s) var(--tbw-animation-easing, ease-out) forwards}@keyframes tbw-group-slide-in{0%{opacity:0;transform:translate(-8px)}to{opacity:1;transform:translate(0)}}.data-grid-row.tbw-group-fade-in{animation:tbw-group-fade-in var(--tbw-animation-duration, .2s) var(--tbw-animation-easing, ease-out) forwards}@keyframes tbw-group-fade-in{0%{opacity:0}to{opacity:1}}}";
 class T extends R {
+  /** @internal */
   name = "groupingRows";
+  /** @internal */
   styles = G;
+  /** @internal */
   get defaultConfig() {
     return {
       defaultExpanded: !1,
@@ -442,6 +428,7 @@ class T extends R {
   }
   // #endregion
   // #region Lifecycle
+  /** @internal */
   detach() {
     this.expandedKeys.clear(), this.flattenedRows = [], this.isActive = !1, this.previousVisibleKeys.clear(), this.keysToAnimate.clear();
   }
@@ -454,6 +441,7 @@ class T extends R {
   static detect(e, t) {
     return typeof t?.groupOn == "function" || typeof t?.enableRowGrouping == "boolean";
   }
+  /** @internal */
   processRows(e) {
     const t = this.config;
     if (typeof t.groupOn != "function")
@@ -482,11 +470,13 @@ class T extends R {
       __groupRowCount: K(i)
     } : i.row);
   }
+  /** @internal */
   onCellClick(e) {
     const t = e.row;
     if (t?.__isGroupRow && e.originalEvent.target?.closest(".group-toggle"))
       return this.toggle(t.__groupKey), !0;
   }
+  /** @internal */
   onKeyDown(e) {
     if (e.key !== " ") return;
     const t = this.grid._focusRow, r = this.rows[t];
@@ -495,6 +485,7 @@ class T extends R {
   }
   /**
    * Render a row. Returns true if we handled the row (group row), false otherwise.
+   * @internal
    */
   renderRow(e, t, r) {
     if (!e?.__isGroupRow)
@@ -519,6 +510,7 @@ class T extends R {
     };
     return t.className = "data-grid-row group-row", t.__isCustomRow = !0, t.setAttribute("data-group-depth", String(e.__groupDepth)), t.setAttribute("role", "row"), t.setAttribute("aria-expanded", String(e.__groupExpanded)), t.style.setProperty("--tbw-group-depth", String(e.__groupDepth || 0)), s.indentWidth !== void 0 && t.style.setProperty("--tbw-group-indent-width", `${s.indentWidth}px`), t.innerHTML = "", s.fullWidth !== !1 ? this.renderFullWidthGroupRow(e, t, i) : this.renderPerColumnGroupRow(e, t, i), !0;
   }
+  /** @internal */
   afterRender() {
     const e = this.animationStyle;
     if (e === !1 || this.keysToAnimate.size === 0) return;
@@ -598,13 +590,13 @@ class T extends R {
    * Expand all groups.
    */
   expandAll() {
-    this.expandedKeys = E(this.flattenedRows), this.requestRender();
+    this.expandedKeys = S(this.flattenedRows), this.requestRender();
   }
   /**
    * Collapse all groups.
    */
   collapseAll() {
-    this.expandedKeys = S(), this.requestRender();
+    this.expandedKeys = E(), this.requestRender();
   }
   /**
    * Toggle expansion of a specific group.