@toolbox-web/grid 0.2.8 → 0.3.1

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

@@ -0,0 +1,157 @@
+import { ColumnConfig } from '../../core/types';
+declare module '../../core/types' {
+    interface BaseColumnConfig {
+        /**
+         * Whether this column can be filtered (only applicable when FilteringPlugin is enabled).
+         * @default true
+         */
+        filterable?: boolean;
+    }
+    interface ColumnState {
+        /**
+         * Filter state for this column (only present when FilteringPlugin is used).
+         * Stores the essential filter properties without the redundant 'field'.
+         */
+        filter?: {
+            type: 'text' | 'number' | 'date' | 'set' | 'boolean';
+            operator: string;
+            value: unknown;
+            valueTo?: unknown;
+        };
+    }
+}
+/** Supported filter types */
+export type FilterType = 'text' | 'number' | 'date' | 'set' | 'boolean';
+/** Filter operators for different filter types */
+export type FilterOperator = 'contains' | 'notContains' | 'equals' | 'notEquals' | 'startsWith' | 'endsWith' | 'blank' | 'notBlank' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual' | 'between' | 'in' | 'notIn';
+/** Filter model representing a single filter condition */
+export interface FilterModel {
+    /** The field/column to filter on */
+    field: string;
+    /** The type of filter */
+    type: FilterType;
+    /** The filter operator */
+    operator: FilterOperator;
+    /** The filter value (type depends on operator) */
+    value: unknown;
+    /** Secondary value for 'between' operator */
+    valueTo?: unknown;
+}
+/** Parameters passed to custom filter panel renderer */
+export interface FilterPanelParams {
+    /** The field being filtered */
+    field: string;
+    /** The column configuration */
+    column: ColumnConfig;
+    /** All unique values for this field */
+    uniqueValues: unknown[];
+    /** Currently excluded values (for set filter) */
+    excludedValues: Set<unknown>;
+    /** Current search text */
+    searchText: string;
+    /** Apply a set filter (exclude these values) */
+    applySetFilter: (excludedValues: unknown[]) => void;
+    /** Apply a text filter */
+    applyTextFilter: (operator: FilterOperator, value: string, valueTo?: string) => void;
+    /** Clear the filter for this field */
+    clearFilter: () => void;
+    /** Close the filter panel */
+    closePanel: () => void;
+}
+/** Custom filter panel renderer function. Return undefined to use default panel for this column. */
+export type FilterPanelRenderer = (container: HTMLElement, params: FilterPanelParams) => void | undefined;
+/**
+ * Async handler for fetching unique filter values from a server.
+ *
+ * For server-side datasets where not all values are available locally,
+ * this handler is called when the filter panel opens to fetch all
+ * possible values for the column.
+ *
+ * @param field - The field/column name
+ * @param column - The column configuration
+ * @returns Promise resolving to array of unique values
+ *
+ * @example
+ * ```ts
+ * valuesHandler: async (field, column) => {
+ *   const response = await fetch(`/api/distinct/${field}`);
+ *   return response.json(); // ['Engineering', 'Marketing', 'Sales', ...]
+ * }
+ * ```
+ */
+export type FilterValuesHandler = (field: string, column: ColumnConfig) => Promise<unknown[]>;
+/**
+ * Async handler for applying filters on a server.
+ *
+ * For server-side filtering, this handler is called when filters change.
+ * It should fetch filtered data from the server and return the new rows.
+ * The plugin will replace the grid's rows with the returned data.
+ *
+ * @param filters - Current active filter models
+ * @param currentRows - Current row array (for reference/optimistic updates)
+ * @returns Promise resolving to filtered rows
+ *
+ * @example
+ * ```ts
+ * filterHandler: async (filters) => {
+ *   const params = new URLSearchParams();
+ *   filters.forEach(f => params.append(f.field, `${f.operator}:${f.value}`));
+ *   const response = await fetch(`/api/data?${params}`);
+ *   return response.json();
+ * }
+ * ```
+ */
+export type FilterHandler<TRow = unknown> = (filters: FilterModel[], currentRows: TRow[]) => TRow[] | Promise<TRow[]>;
+/** Configuration options for the filtering plugin */
+export interface FilterConfig<TRow = unknown> {
+    /** Debounce delay in ms for filter input (default: 300) */
+    debounceMs?: number;
+    /** Whether text filtering is case sensitive (default: false) */
+    caseSensitive?: boolean;
+    /** Whether to trim whitespace from filter input (default: true) */
+    trimInput?: boolean;
+    /** Use Web Worker for filtering large datasets >1000 rows (default: true) */
+    useWorker?: boolean;
+    /** Custom filter panel renderer (replaces default panel content) */
+    filterPanelRenderer?: FilterPanelRenderer;
+    /**
+     * Async handler for fetching unique values from a server.
+     * When provided, this is called instead of extracting values from local rows.
+     * Useful for server-side datasets where not all data is loaded.
+     */
+    valuesHandler?: FilterValuesHandler;
+    /**
+     * Async handler for applying filters on a server.
+     * When provided, filtering is delegated to the server instead of local filtering.
+     * Should return the filtered rows from the server.
+     *
+     * Note: When using filterHandler, processRows() becomes a passthrough
+     * and the returned rows replace the grid's data.
+     */
+    filterHandler?: FilterHandler<TRow>;
+}
+/** Internal state managed by the filtering plugin */
+export interface FilterState {
+    /** Map of field name to filter model */
+    filters: Map<string, FilterModel>;
+    /** Cached filtered result for performance */
+    cachedResult: unknown[] | null;
+    /** Cache key for invalidation */
+    cacheKey: string | null;
+    /** Currently open filter panel field (null if none open) */
+    openPanelField: string | null;
+    /** Reference to the open filter panel element */
+    panelElement: HTMLElement | null;
+    /** Current search text per field */
+    searchText: Map<string, string>;
+    /** Set of excluded values per field (for set filter) */
+    excludedValues: Map<string, Set<unknown>>;
+}
+/** Event detail emitted when filters change */
+export interface FilterChangeDetail {
+    /** Current active filters */
+    filters: FilterModel[];
+    /** Number of rows after filtering */
+    filteredRowCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/filtering/types.ts"],"names":[],"mappings":"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"}

package/lib/plugins/grouping-columns/GroupingColumnsPlugin.d.ts

@@ -0,0 +1,51 @@
+import { BaseGridPlugin } from '../../core/plugin/base-plugin';
+import { ColumnConfig } from '../../core/types';
+import { ColumnGroup, GroupingColumnsConfig } from './types';
+/**
+ * Column Groups Plugin for tbw-grid
+ *
+ * @example
+ * ```ts
+ * new GroupingColumnsPlugin({
+ *   enabled: true,
+ *   showGroupBorders: true,
+ * })
+ * ```
+ */
+export declare class GroupingColumnsPlugin extends BaseGridPlugin<GroupingColumnsConfig> {
+    readonly name = "groupingColumns";
+    readonly version = "1.0.0";
+    protected get defaultConfig(): Partial<GroupingColumnsConfig>;
+    private groups;
+    private isActive;
+    detach(): void;
+    /**
+     * Auto-detect column groups from column configuration.
+     * Detects both inline `column.group` properties and declarative `columnGroups` config.
+     */
+    static detect(rows: readonly any[], config: any): boolean;
+    processColumns(columns: readonly ColumnConfig[]): ColumnConfig[];
+    afterRender(): void;
+    /**
+     * Check if column groups are active.
+     * @returns Whether grouping is active
+     */
+    isGroupingActive(): boolean;
+    /**
+     * Get the computed column groups.
+     * @returns Array of column groups
+     */
+    getGroups(): ColumnGroup[];
+    /**
+     * Get columns in a specific group.
+     * @param groupId - The group ID to find
+     * @returns Array of columns in the group
+     */
+    getGroupColumns(groupId: string): ColumnConfig[];
+    /**
+     * Refresh column groups (recompute from current columns).
+     */
+    refresh(): void;
+    readonly styles: string;
+}
+//# sourceMappingURL=GroupingColumnsPlugin.d.ts.map

package/lib/plugins/grouping-columns/GroupingColumnsPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupingColumnsPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/grouping-columns/GroupingColumnsPlugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQrD,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAElE;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,cAAc,CAAC,qBAAqB,CAAC;IAC9E,QAAQ,CAAC,IAAI,qBAAqB;IAClC,SAAkB,OAAO,WAAW;IAEpC,cAAuB,aAAa,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAIrE;IAGD,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAAS;IAKhB,MAAM,IAAI,IAAI;IAQvB;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO;IAchD,cAAc,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,EAAE;IA0ChE,WAAW,IAAI,IAAI;IA0C5B;;;OAGG;IACH,gBAAgB,IAAI,OAAO;IAI3B;;;OAGG;IACH,SAAS,IAAI,WAAW,EAAE;IAI1B;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE;IAKhD;;OAEG;IACH,OAAO,IAAI,IAAI;IAOf,SAAkB,MAAM,SAAU;CAEnC"}

package/lib/plugins/grouping-columns/grouping-columns.d.ts

@@ -0,0 +1,41 @@
+import { ColumnConfig } from '../../core/types';
+import { ColumnGroup } from './types';
+/**
+ * Compute column groups from column configuration.
+ * Handles explicit groups (via column.group) and creates implicit groups for ungrouped columns.
+ *
+ * @param columns - Array of column configurations
+ * @returns Array of column groups, or empty if no meaningful groups
+ */
+export declare function computeColumnGroups<T>(columns: ColumnConfig<T>[]): ColumnGroup<T>[];
+/**
+ * Apply CSS classes to header cells based on their group membership.
+ *
+ * @param headerRowEl - The header row element
+ * @param groups - The computed column groups
+ * @param columns - The column configurations
+ */
+export declare function applyGroupedHeaderCellClasses(headerRowEl: HTMLElement | null, groups: ColumnGroup[], columns: ColumnConfig<any>[]): void;
+/**
+ * Build the group header row element.
+ *
+ * @param groups - The computed column groups
+ * @param columns - The column configurations
+ * @returns The group header row element, or null if no groups
+ */
+export declare function buildGroupHeaderRow(groups: ColumnGroup[], columns: ColumnConfig<any>[]): HTMLElement | null;
+/**
+ * Check if any columns have group configuration.
+ *
+ * @param columns - The column configurations
+ * @returns True if at least one column has a group
+ */
+export declare function hasColumnGroups(columns: ColumnConfig<any>[]): boolean;
+/**
+ * Get group ID for a specific column.
+ *
+ * @param column - The column configuration
+ * @returns The group ID, or undefined if not grouped
+ */
+export declare function getColumnGroupId(column: ColumnConfig<any>): string | undefined;
+//# sourceMappingURL=grouping-columns.d.ts.map

package/lib/plugins/grouping-columns/grouping-columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grouping-columns.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/grouping-columns/grouping-columns.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAuB,MAAM,SAAS,CAAC;AAEhE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,CAmEnF;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,WAAW,GAAG,IAAI,EAC/B,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,GAC3B,IAAI,CA8BN;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,GAC3B,WAAW,GAAG,IAAI,CA0BpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,GAAG,OAAO,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,MAAM,GAAG,SAAS,CAI9E"}

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

@@ -0,0 +1,7 @@
+/**
+ * Grouping Columns Plugin Entry Point
+ * Re-exports plugin class and types for tree-shakeable imports.
+ */
+export { GroupingColumnsPlugin } from './GroupingColumnsPlugin';
+export type { ColumnGroup, ColumnGroupDefinition, GroupingColumnsConfig } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/grouping-columns/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EAAE,WAAW,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC"}

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

@@ -164,69 +164,69 @@ class a {
   }
   // #endregion
 }
-function h(u) {
-  if (!u.length) return [];
-  const e = /* @__PURE__ */ new Map(), r = [], t = (s, n) => {
+function h(l) {
+  if (!l.length) return [];
+  const e = /* @__PURE__ */ new Map(), r = [], t = (o, n) => {
     if (!n.length) return;
-    const l = r[r.length - 1];
-    if (l && l.implicit && l.firstIndex + l.columns.length === s) {
-      l.columns.push(...n);
+    const u = r[r.length - 1];
+    if (u && u.implicit && u.firstIndex + u.columns.length === o) {
+      u.columns.push(...n);
       return;
     }
     r.push({
-      id: "__implicit__" + s,
+      id: "__implicit__" + o,
       label: void 0,
       columns: n,
-      firstIndex: s,
+      firstIndex: o,
       implicit: !0
     });
   };
-  let i = [], o = 0;
-  return u.forEach((s, n) => {
-    const l = s.group;
-    if (!l) {
-      i.length === 0 && (o = n), i.push(s);
+  let i = [], s = 0;
+  return l.forEach((o, n) => {
+    const u = o.group;
+    if (!u) {
+      i.length === 0 && (s = n), i.push(o);
       return;
     }
-    i.length && (t(o, i.slice()), i = []);
-    const g = typeof l == "string" ? l : l.id;
+    i.length && (t(s, i.slice()), i = []);
+    const g = typeof u == "string" ? u : u.id;
     let d = e.get(g);
     d || (d = {
       id: g,
-      label: typeof l == "string" ? void 0 : l.label,
+      label: typeof u == "string" ? void 0 : u.label,
       columns: [],
       firstIndex: n
-    }, e.set(g, d), r.push(d)), d.columns.push(s);
-  }), i.length && t(o, i), r.length === 1 && r[0].implicit && r[0].columns.length === u.length ? [] : r;
+    }, e.set(g, d), r.push(d)), d.columns.push(o);
+  }), i.length && t(s, i), r.length === 1 && r[0].implicit && r[0].columns.length === l.length ? [] : r;
 }
-function p(u, e, r) {
-  if (!e.length || !u) return;
+function p(l, e, r) {
+  if (!e.length || !l) return;
   const t = /* @__PURE__ */ new Map();
-  for (const o of e)
-    for (const s of o.columns)
-      s?.field && t.set(s.field, o.id);
-  const i = Array.from(u.querySelectorAll(".cell[data-field]"));
-  i.forEach((o) => {
-    const s = o.getAttribute("data-field") || "", n = t.get(s);
-    n && (o.classList.add("grouped"), o.getAttribute("data-group") || o.setAttribute("data-group", n));
+  for (const s of e)
+    for (const o of s.columns)
+      o?.field && t.set(o.field, s.id);
+  const i = Array.from(l.querySelectorAll(".cell[data-field]"));
+  i.forEach((s) => {
+    const o = s.getAttribute("data-field") || "", n = t.get(o);
+    n && (s.classList.add("grouped"), s.getAttribute("data-group") || s.setAttribute("data-group", n));
   });
-  for (const o of e) {
-    const s = o.columns[o.columns.length - 1], n = i.find((l) => l.getAttribute("data-field") === s.field);
+  for (const s of e) {
+    const o = s.columns[s.columns.length - 1], n = i.find((u) => u.getAttribute("data-field") === o.field);
     n && n.classList.add("group-end");
   }
 }
-function f(u, e) {
-  if (u.length === 0) return null;
+function f(l, e) {
+  if (l.length === 0) return null;
   const r = document.createElement("div");
   r.className = "header-group-row", r.setAttribute("role", "row");
-  for (const t of u) {
-    const i = t.firstIndex != null ? t.firstIndex : e.findIndex((l) => t.columns.includes(l)), o = String(t.id).startsWith("__implicit__"), s = o ? "" : t.label || t.id, n = document.createElement("div");
-    n.className = "cell header-group-cell", o && n.classList.add("implicit-group"), n.setAttribute("data-group", String(t.id)), n.style.gridColumn = `${i + 1} / span ${t.columns.length}`, n.textContent = s, r.appendChild(n);
+  for (const t of l) {
+    const i = t.firstIndex != null ? t.firstIndex : e.findIndex((u) => t.columns.includes(u)), s = String(t.id).startsWith("__implicit__"), o = s ? "" : t.label || t.id, n = document.createElement("div");
+    n.className = "cell header-group-cell", s && n.classList.add("implicit-group"), n.setAttribute("data-group", String(t.id)), n.style.gridColumn = `${i + 1} / span ${t.columns.length}`, n.textContent = o, r.appendChild(n);
   }
   return r;
 }
-function m(u) {
-  return u.some((e) => e.group != null);
+function m(l) {
+  return l.some((e) => e.group != null);
 }
 const b = ".header-group-row{display:grid;grid-auto-flow:column;background:var(--tbw-grouping-columns-header-bg, var(--tbw-color-header-bg));border-bottom:1px solid var(--tbw-grouping-columns-border, var(--tbw-color-border))}.header-group-cell{display:flex;align-items:center;justify-content:center;padding:4px 8px;font-weight:600;font-size:.9em;text-transform:uppercase;letter-spacing:.5px;border-right:1px solid var(--tbw-grouping-columns-border, var(--tbw-color-border))}.header-group-cell:last-child{border-right:none}.header-row .cell.grouped{border-top:none}.header-row .cell.group-end{border-right:2px solid var(--tbw-grouping-columns-separator, var(--tbw-color-border-strong))}.header-row .cell.group-end:last-child{border-right:none}.header-group-row.no-borders{border-bottom:none}.header-group-row.no-borders .header-group-cell{border-right:none}.header-row.no-group-borders .cell.group-end{border-right:1px solid var(--tbw-color-border)}";
 class w extends a {
@@ -249,21 +249,37 @@ class w extends a {
   // #region Static Detection
   /**
    * Auto-detect column groups from column configuration.
+   * Detects both inline `column.group` properties and declarative `columnGroups` config.
    */
   static detect(e, r) {
+    if (r?.columnGroups && Array.isArray(r.columnGroups) && r.columnGroups.length > 0)
+      return !0;
     const t = r?.columns;
     return Array.isArray(t) ? m(t) : !1;
   }
   // #endregion
   // #region Hooks
   processColumns(e) {
-    const r = h(e);
-    return r.length === 0 ? (this.isActive = !1, this.groups = [], [...e]) : (this.isActive = !0, this.groups = r, [...e]);
+    const r = this.grid?.gridConfig?.columnGroups;
+    let t;
+    if (r && Array.isArray(r) && r.length > 0) {
+      const s = /* @__PURE__ */ new Map();
+      for (const o of r)
+        for (const n of o.children)
+          s.set(n, { id: o.id, label: o.header });
+      t = e.map((o) => {
+        const n = s.get(o.field);
+        return n && !o.group ? { ...o, group: n } : o;
+      });
+    } else
+      t = [...e];
+    const i = h(t);
+    return i.length === 0 ? (this.isActive = !1, this.groups = [], t) : (this.isActive = !0, this.groups = i, t);
   }
   afterRender() {
     if (!this.isActive || this.groups.length === 0) {
-      const s = this.shadowRoot?.querySelector(".header")?.querySelector(".header-group-row");
-      s && s.remove();
+      const o = this.shadowRoot?.querySelector(".header")?.querySelector(".header-group-row");
+      o && o.remove();
       return;
     }
     const e = this.shadowRoot?.querySelector(".header");
@@ -273,8 +289,8 @@ class w extends a {
     const t = f(this.groups, this.columns);
     if (t) {
       t.classList.toggle("no-borders", !this.config.showGroupBorders);
-      const o = e.querySelector(".header-row");
-      o ? e.insertBefore(t, o) : e.appendChild(t);
+      const s = e.querySelector(".header-row");
+      s ? e.insertBefore(t, s) : e.appendChild(t);
     }
     const i = e.querySelector(".header-row");
     i && (i.classList.toggle("no-group-borders", !this.config.showGroupBorders), p(i, this.groups, this.columns));