@toolbox-web/grid 0.4.0 → 0.4.2

package/lib/plugins/export/ExportPlugin.d.ts

@@ -15,7 +15,6 @@ import { ExportConfig, ExportFormat, ExportParams } from './types';
  */
 export declare class ExportPlugin extends BaseGridPlugin<ExportConfig> {
     readonly name = "export";
-    readonly version = "1.0.0";
     protected get defaultConfig(): Partial<ExportConfig>;
     private isExportingFlag;
     private lastExportInfo;

package/lib/plugins/export/ExportPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExportPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/export/ExportPlugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAI/D,OAAO,KAAK,EAAwB,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAO9F;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAa,SAAQ,cAAc,CAAC,YAAY,CAAC;IAC5D,QAAQ,CAAC,IAAI,YAAY;IACzB,SAAkB,OAAO,WAAW;IAEpC,cAAuB,aAAa,IAAI,OAAO,CAAC,YAAY,CAAC,CAO5D;IAGD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,cAAc,CAA0D;IAKhF,OAAO,CAAC,aAAa;IAyFrB,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAI/C;;;OAGG;IACH,WAAW,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAIjD;;;OAGG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAIhD;;;OAGG;IACH,WAAW,IAAI,OAAO;IAItB;;;OAGG;IACH,aAAa,IAAI;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,SAAS,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI;CAIlE"}
+{"version":3,"file":"ExportPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/export/ExportPlugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAI/D,OAAO,KAAK,EAAwB,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAO9F;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAa,SAAQ,cAAc,CAAC,YAAY,CAAC;IAC5D,QAAQ,CAAC,IAAI,YAAY;IAEzB,cAAuB,aAAa,IAAI,OAAO,CAAC,YAAY,CAAC,CAO5D;IAGD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,cAAc,CAA0D;IAKhF,OAAO,CAAC,aAAa;IAyFrB,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAI/C;;;OAGG;IACH,WAAW,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAIjD;;;OAGG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAIhD;;;OAGG;IACH,WAAW,IAAI,OAAO;IAItB;;;OAGG;IACH,aAAa,IAAI;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,SAAS,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI;CAIlE"}

package/lib/plugins/export/index.js

@@ -1,4 +1,4 @@
-const x = {
+const w = {
   expand: "▶",
   collapse: "▼",
   sortAsc: "▲",
@@ -8,9 +8,28 @@ const x = {
   dragHandle: "⋮⋮",
   toolPanel: "☰"
 };
-class w {
-  /** Plugin version - override in subclass if needed */
-  version = "1.0.0";
+class x {
+  /**
+   * Plugin dependencies - declare other plugins this one requires.
+   *
+   * Dependencies are validated when the plugin is attached.
+   * Required dependencies throw an error if missing.
+   * Optional dependencies log an info message if missing.
+   *
+   * @example
+   * ```typescript
+   * static readonly dependencies: PluginDependency[] = [
+   *   { name: 'editing', required: true, reason: 'Tracks cell edits for undo/redo' },
+   *   { name: 'selection', required: false, reason: 'Enables selection-based undo' },
+   * ];
+   * ```
+   */
+  static dependencies;
+  /**
+   * Plugin version - defaults to grid version for built-in plugins.
+   * Third-party plugins can override with their own semver.
+   */
+  version = typeof __GRID_VERSION__ < "u" ? __GRID_VERSION__ : "dev";
   /** CSS styles to inject into the grid's shadow DOM */
   styles;
   /** Custom cell renderers keyed by type name */
@@ -39,8 +58,8 @@ class w {
   get defaultConfig() {
     return {};
   }
-  constructor(t = {}) {
-    this.userConfig = t;
+  constructor(e = {}) {
+    this.userConfig = e;
   }
   /**
    * Called when the plugin is attached to a grid.
@@ -57,8 +76,8 @@ class w {
    * }
    * ```
    */
-  attach(t) {
-    this.#e?.abort(), this.#e = new AbortController(), this.grid = t, this.config = { ...this.defaultConfig, ...this.userConfig };
+  attach(e) {
+    this.#e?.abort(), this.#e = new AbortController(), this.grid = e, this.config = { ...this.defaultConfig, ...this.userConfig };
   }
   /**
    * Called when the plugin is detached from a grid.
@@ -88,14 +107,22 @@ class w {
    * }
    * ```
    */
-  getPlugin(t) {
-    return this.grid?.getPlugin(t);
+  getPlugin(e) {
+    return this.grid?.getPlugin(e);
   }
   /**
    * Emit a custom event from the grid.
    */
-  emit(t, e) {
-    this.grid?.dispatchEvent?.(new CustomEvent(t, { detail: e, bubbles: !0 }));
+  emit(e, t) {
+    this.grid?.dispatchEvent?.(new CustomEvent(e, { detail: t, bubbles: !0 }));
+  }
+  /**
+   * Emit a cancelable custom event from the grid.
+   * @returns `true` if the event was cancelled (preventDefault called), `false` otherwise
+   */
+  emitCancelable(e, t) {
+    const n = new CustomEvent(e, { detail: t, bubbles: !0, cancelable: !0 });
+    return this.grid?.dispatchEvent?.(n), n.defaultPrevented;
   }
   /**
    * Request a re-render of the grid.
@@ -103,6 +130,14 @@ class w {
   requestRender() {
     this.grid?.requestRender?.();
   }
+  /**
+   * Request a re-render and restore focus styling afterward.
+   * Use this when a plugin action (like expand/collapse) triggers a render
+   * but needs to maintain keyboard navigation focus.
+   */
+  requestRenderWithFocus() {
+    this.grid?.requestRenderWithFocus?.();
+  }
   /**
    * Request a lightweight style update without rebuilding DOM.
    * Use this instead of requestRender() when only CSS classes need updating.
@@ -136,6 +171,19 @@ class w {
   get visibleColumns() {
     return this.grid?._visibleColumns ?? [];
   }
+  /**
+   * Get the grid as an HTMLElement for direct DOM operations.
+   * Use sparingly - prefer the typed GridElementRef API when possible.
+   *
+   * @example
+   * ```ts
+   * const width = this.gridElement.clientWidth;
+   * this.gridElement.classList.add('my-plugin-active');
+   * ```
+   */
+  get gridElement() {
+    return this.grid;
+  }
   /**
    * Get the shadow root of the grid.
    */
@@ -167,9 +215,54 @@ class w {
    * Returns merged icons (user config + defaults).
    */
   get gridIcons() {
-    const t = this.grid?.gridConfig?.icons ?? {};
-    return { ...x, ...t };
+    const e = this.grid?.gridConfig?.icons ?? {};
+    return { ...w, ...e };
+  }
+  // #region Animation Helpers
+  /**
+   * Check if animations are enabled at the grid level.
+   * Respects gridConfig.animation.mode and the CSS variable set by the grid.
+   *
+   * Plugins should use this to skip animations when:
+   * - Animation mode is 'off' or `false`
+   * - User prefers reduced motion and mode is 'reduced-motion' (default)
+   *
+   * @example
+   * ```ts
+   * private get animationStyle(): 'slide' | 'fade' | false {
+   *   if (!this.isAnimationEnabled) return false;
+   *   return this.config.animation ?? 'slide';
+   * }
+   * ```
+   */
+  get isAnimationEnabled() {
+    const e = this.grid?.effectiveConfig?.animation?.mode ?? "reduced-motion";
+    if (e === !1 || e === "off") return !1;
+    if (e === !0 || e === "on") return !0;
+    const t = this.shadowRoot?.host;
+    return t ? getComputedStyle(t).getPropertyValue("--tbw-animation-enabled").trim() !== "0" : !0;
   }
+  /**
+   * Get the animation duration in milliseconds from CSS variable.
+   * Falls back to 200ms if not set.
+   *
+   * Plugins can use this for their animation timing to stay consistent
+   * with the grid-level animation.duration setting.
+   *
+   * @example
+   * ```ts
+   * element.animate(keyframes, { duration: this.animationDuration });
+   * ```
+   */
+  get animationDuration() {
+    const e = this.shadowRoot?.host;
+    if (e) {
+      const t = getComputedStyle(e).getPropertyValue("--tbw-animation-duration").trim(), n = parseInt(t, 10);
+      if (!isNaN(n)) return n;
+    }
+    return 200;
+  }
+  // #endregion
   /**
    * Resolve an icon value to string or HTMLElement.
    * Checks plugin config first, then grid-level icons, then defaults.
@@ -178,8 +271,8 @@ class w {
    * @param pluginOverride - Optional plugin-level override
    * @returns The resolved icon value
    */
-  resolveIcon(t, e) {
-    return e !== void 0 ? e : this.gridIcons[t];
+  resolveIcon(e, t) {
+    return t !== void 0 ? t : this.gridIcons[e];
   }
   /**
    * Set an icon value on an element.
@@ -188,96 +281,95 @@ class w {
    * @param element - The element to set the icon on
    * @param icon - The icon value (string or HTMLElement)
    */
-  setIcon(t, e) {
-    typeof e == "string" ? t.innerHTML = e : e instanceof HTMLElement && (t.innerHTML = "", t.appendChild(e.cloneNode(!0)));
+  setIcon(e, t) {
+    typeof t == "string" ? e.innerHTML = t : t instanceof HTMLElement && (e.innerHTML = "", e.appendChild(t.cloneNode(!0)));
   }
   /**
    * Log a warning message.
    */
-  warn(t) {
-    console.warn(`[tbw-grid:${this.name}] ${t}`);
+  warn(e) {
+    console.warn(`[tbw-grid:${this.name}] ${e}`);
   }
   // #endregion
 }
-function b(i, t = !0) {
+function m(i, e = !0) {
   if (i == null) return "";
   if (i instanceof Date) return i.toISOString();
   if (typeof i == "object") return JSON.stringify(i);
-  const e = String(i);
-  return t && (e.includes(",") || e.includes('"') || e.includes(`
-`) || e.includes("\r")) ? `"${e.replace(/"/g, '""')}"` : e;
+  const t = String(i);
+  return e && (t.includes(",") || t.includes('"') || t.includes(`
+`) || t.includes("\r")) ? `"${t.replace(/"/g, '""')}"` : t;
 }
-function C(i, t, e, s = {}) {
-  const c = s.delimiter ?? ",", l = s.newline ?? `
-`, n = [], r = s.bom ? "\uFEFF" : "";
-  if (e.includeHeaders !== !1) {
-    const o = t.map((u) => {
-      const d = u.header || u.field, a = e.processHeader ? e.processHeader(d, u.field) : d;
-      return b(a);
+function C(i, e, t, n = {}) {
+  const c = n.delimiter ?? ",", l = n.newline ?? `
+`, o = [], r = n.bom ? "\uFEFF" : "";
+  if (t.includeHeaders !== !1) {
+    const s = e.map((a) => {
+      const d = a.header || a.field, u = t.processHeader ? t.processHeader(d, a.field) : d;
+      return m(u);
     });
-    n.push(o.join(c));
+    o.push(s.join(c));
   }
-  for (const o of i) {
-    const u = t.map((d) => {
-      let a = o[d.field];
-      return e.processCell && (a = e.processCell(a, d.field, o)), b(a);
+  for (const s of i) {
+    const a = e.map((d) => {
+      let u = s[d.field];
+      return t.processCell && (u = t.processCell(u, d.field, s)), m(u);
     });
-    n.push(u.join(c));
+    o.push(a.join(c));
   }
-  return r + n.join(l);
+  return r + o.join(l);
 }
-function h(i, t) {
-  const e = URL.createObjectURL(i), s = document.createElement("a");
-  s.href = e, s.download = t, s.style.display = "none", document.body.appendChild(s), s.click(), document.body.removeChild(s), URL.revokeObjectURL(e);
+function h(i, e) {
+  const t = URL.createObjectURL(i), n = document.createElement("a");
+  n.href = t, n.download = e, n.style.display = "none", document.body.appendChild(n), n.click(), document.body.removeChild(n), URL.revokeObjectURL(t);
 }
-function S(i, t) {
-  const e = new Blob([i], { type: "text/csv;charset=utf-8;" });
-  h(e, t);
+function E(i, e) {
+  const t = new Blob([i], { type: "text/csv;charset=utf-8;" });
+  h(t, e);
 }
-function m(i) {
+function b(i) {
   return i.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
-function E(i, t, e) {
-  let s = `<?xml version="1.0" encoding="UTF-8"?>
+function S(i, e, t) {
+  let n = `<?xml version="1.0" encoding="UTF-8"?>
 <?mso-application progid="Excel.Sheet"?>
 <Workbook xmlns="urn:schemas-microsoft-com:office:spreadsheet"
   xmlns:ss="urn:schemas-microsoft-com:office:spreadsheet">
 <Worksheet ss:Name="Sheet1">
 <Table>`;
-  if (e.includeHeaders !== !1) {
-    s += `
+  if (t.includeHeaders !== !1) {
+    n += `
 <Row>`;
-    for (const c of t) {
-      const l = c.header || c.field, n = e.processHeader ? e.processHeader(l, c.field) : l;
-      s += `<Cell><Data ss:Type="String">${m(n)}</Data></Cell>`;
+    for (const c of e) {
+      const l = c.header || c.field, o = t.processHeader ? t.processHeader(l, c.field) : l;
+      n += `<Cell><Data ss:Type="String">${b(o)}</Data></Cell>`;
     }
-    s += "</Row>";
+    n += "</Row>";
   }
   for (const c of i) {
-    s += `
+    n += `
 <Row>`;
-    for (const l of t) {
-      let n = c[l.field];
-      e.processCell && (n = e.processCell(n, l.field, c));
-      let r = "String", o = "";
-      n == null ? o = "" : typeof n == "number" && !isNaN(n) ? (r = "Number", o = String(n)) : n instanceof Date ? (r = "DateTime", o = n.toISOString()) : o = m(String(n)), s += `<Cell><Data ss:Type="${r}">${o}</Data></Cell>`;
+    for (const l of e) {
+      let o = c[l.field];
+      t.processCell && (o = t.processCell(o, l.field, c));
+      let r = "String", s = "";
+      o == null ? s = "" : typeof o == "number" && !isNaN(o) ? (r = "Number", s = String(o)) : o instanceof Date ? (r = "DateTime", s = o.toISOString()) : s = b(String(o)), n += `<Cell><Data ss:Type="${r}">${s}</Data></Cell>`;
     }
-    s += "</Row>";
+    n += "</Row>";
   }
-  return s += `
+  return n += `
 </Table>
 </Worksheet>
-</Workbook>`, s;
+</Workbook>`, n;
 }
-function y(i, t) {
-  const e = t.endsWith(".xls") ? t : `${t}.xls`, s = new Blob([i], {
+function y(i, e) {
+  const t = e.endsWith(".xls") ? e : `${e}.xls`, n = new Blob([i], {
     type: "application/vnd.ms-excel;charset=utf-8;"
   });
-  h(s, e);
+  h(n, t);
 }
-class R extends w {
+class R extends x {
   name = "export";
-  version = "1.0.0";
   get defaultConfig() {
     return {
       fileName: "export",
@@ -291,59 +383,59 @@ class R extends w {
   lastExportInfo = null;
   // #endregion
   // #region Private Methods
-  performExport(t, e) {
-    const s = this.config, c = {
-      format: t,
-      fileName: e?.fileName ?? s.fileName ?? "export",
-      includeHeaders: e?.includeHeaders ?? s.includeHeaders,
-      processCell: e?.processCell,
-      processHeader: e?.processHeader,
-      columns: e?.columns,
-      rowIndices: e?.rowIndices
+  performExport(e, t) {
+    const n = this.config, c = {
+      format: e,
+      fileName: t?.fileName ?? n.fileName ?? "export",
+      includeHeaders: t?.includeHeaders ?? n.includeHeaders,
+      processCell: t?.processCell,
+      processHeader: t?.processHeader,
+      columns: t?.columns,
+      rowIndices: t?.rowIndices
     };
     let l = [...this.columns];
-    if (s.onlyVisible && (l = l.filter((o) => !o.hidden && !o.field.startsWith("__"))), e?.columns) {
-      const o = new Set(e.columns);
-      l = l.filter((u) => o.has(u.field));
+    if (n.onlyVisible && (l = l.filter((s) => !s.hidden && !s.field.startsWith("__"))), t?.columns) {
+      const s = new Set(t.columns);
+      l = l.filter((a) => s.has(a.field));
     }
-    let n = [...this.rows];
-    if (s.onlySelected) {
-      const o = this.getSelectionState();
-      o?.selected?.size && (n = [...o.selected].sort((d, a) => d - a).map((d) => this.rows[d]).filter(Boolean));
+    let o = [...this.rows];
+    if (n.onlySelected) {
+      const s = this.getSelectionState();
+      s?.selected?.size && (o = [...s.selected].sort((d, u) => d - u).map((d) => this.rows[d]).filter(Boolean));
     }
-    e?.rowIndices && (n = e.rowIndices.map((o) => this.rows[o]).filter(Boolean)), this.isExportingFlag = !0;
+    t?.rowIndices && (o = t.rowIndices.map((s) => this.rows[s]).filter(Boolean)), this.isExportingFlag = !0;
     let r = c.fileName;
     try {
-      switch (t) {
+      switch (e) {
         case "csv": {
-          const o = C(n, l, c, { bom: !0 });
-          r = r.endsWith(".csv") ? r : `${r}.csv`, S(o, r);
+          const s = C(o, l, c, { bom: !0 });
+          r = r.endsWith(".csv") ? r : `${r}.csv`, E(s, r);
           break;
         }
         case "excel": {
-          const o = E(n, l, c);
-          r = r.endsWith(".xls") ? r : `${r}.xls`, y(o, r);
+          const s = S(o, l, c);
+          r = r.endsWith(".xls") ? r : `${r}.xls`, y(s, r);
           break;
         }
         case "json": {
-          const o = n.map((a) => {
+          const s = o.map((u) => {
             const p = {};
             for (const f of l) {
-              let g = a[f.field];
-              c.processCell && (g = c.processCell(g, f.field, a)), p[f.field] = g;
+              let g = u[f.field];
+              c.processCell && (g = c.processCell(g, f.field, u)), p[f.field] = g;
             }
             return p;
-          }), u = JSON.stringify(o, null, 2);
+          }), a = JSON.stringify(s, null, 2);
           r = r.endsWith(".json") ? r : `${r}.json`;
-          const d = new Blob([u], { type: "application/json" });
+          const d = new Blob([a], { type: "application/json" });
           h(d, r);
           break;
         }
       }
-      this.lastExportInfo = { format: t, timestamp: /* @__PURE__ */ new Date() }, this.emit("export-complete", {
-        format: t,
+      this.lastExportInfo = { format: e, timestamp: /* @__PURE__ */ new Date() }, this.emit("export-complete", {
+        format: e,
         fileName: r,
-        rowCount: n.length,
+        rowCount: o.length,
         columnCount: l.length
       });
     } finally {
@@ -363,22 +455,22 @@ class R extends w {
    * Export data to CSV format.
    * @param params - Optional export parameters
    */
-  exportCsv(t) {
-    this.performExport("csv", t);
+  exportCsv(e) {
+    this.performExport("csv", e);
   }
   /**
    * Export data to Excel format (XML Spreadsheet).
    * @param params - Optional export parameters
    */
-  exportExcel(t) {
-    this.performExport("excel", t);
+  exportExcel(e) {
+    this.performExport("excel", e);
   }
   /**
    * Export data to JSON format.
    * @param params - Optional export parameters
    */
-  exportJson(t) {
-    this.performExport("json", t);
+  exportJson(e) {
+    this.performExport("json", e);
   }
   /**
    * Check if an export is currently in progress.