@toolbox-web/grid 0.4.0 → 0.4.2

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

@@ -1,4 +1,4 @@
-const A = {
+const R = {
   expand: "▶",
   collapse: "▼",
   sortAsc: "▲",
@@ -8,9 +8,28 @@ const A = {
   dragHandle: "⋮⋮",
   toolPanel: "☰"
 };
-class R {
-  /** Plugin version - override in subclass if needed */
-  version = "1.0.0";
+class A {
+  /**
+   * 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 */
@@ -94,8 +113,16 @@ class R {
   /**
    * Emit a custom event from the grid.
    */
-  emit(t, n) {
-    this.grid?.dispatchEvent?.(new CustomEvent(t, { detail: n, bubbles: !0 }));
+  emit(t, e) {
+    this.grid?.dispatchEvent?.(new CustomEvent(t, { detail: e, bubbles: !0 }));
+  }
+  /**
+   * Emit a cancelable custom event from the grid.
+   * @returns `true` if the event was cancelled (preventDefault called), `false` otherwise
+   */
+  emitCancelable(t, e) {
+    const i = new CustomEvent(t, { detail: e, bubbles: !0, cancelable: !0 });
+    return this.grid?.dispatchEvent?.(i), i.defaultPrevented;
   }
   /**
    * Request a re-render of the grid.
@@ -103,6 +130,14 @@ class R {
   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 R {
   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.
    */
@@ -168,8 +216,53 @@ class R {
    */
   get gridIcons() {
     const t = this.grid?.gridConfig?.icons ?? {};
-    return { ...A, ...t };
+    return { ...R, ...t };
   }
+  // #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 t = this.grid?.effectiveConfig?.animation?.mode ?? "reduced-motion";
+    if (t === !1 || t === "off") return !1;
+    if (t === !0 || t === "on") return !0;
+    const e = this.shadowRoot?.host;
+    return e ? getComputedStyle(e).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 t = this.shadowRoot?.host;
+    if (t) {
+      const e = getComputedStyle(t).getPropertyValue("--tbw-animation-duration").trim(), i = parseInt(e, 10);
+      if (!isNaN(i)) return i;
+    }
+    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 R {
    * @param pluginOverride - Optional plugin-level override
    * @returns The resolved icon value
    */
-  resolveIcon(t, n) {
-    return n !== void 0 ? n : this.gridIcons[t];
+  resolveIcon(t, e) {
+    return e !== void 0 ? e : this.gridIcons[t];
   }
   /**
    * Set an icon value on an element.
@@ -188,8 +281,8 @@ class R {
    * @param element - The element to set the icon on
    * @param icon - The icon value (string or HTMLElement)
    */
-  setIcon(t, n) {
-    typeof n == "string" ? t.innerHTML = n : n instanceof HTMLElement && (t.innerHTML = "", t.appendChild(n.cloneNode(!0)));
+  setIcon(t, e) {
+    typeof e == "string" ? t.innerHTML = e : e instanceof HTMLElement && (t.innerHTML = "", t.appendChild(e.cloneNode(!0)));
   }
   /**
    * Log a warning message.
@@ -200,87 +293,87 @@ class R {
   // #endregion
 }
 const p = {
-  sum: (e, t) => e.reduce((n, i) => n + (Number(i[t]) || 0), 0),
-  avg: (e, t) => {
-    const n = e.reduce((i, r) => i + (Number(r[t]) || 0), 0);
-    return e.length ? n / e.length : 0;
+  sum: (n, t) => n.reduce((e, i) => e + (Number(i[t]) || 0), 0),
+  avg: (n, t) => {
+    const e = n.reduce((i, r) => i + (Number(r[t]) || 0), 0);
+    return n.length ? e / n.length : 0;
   },
-  count: (e) => e.length,
-  min: (e, t) => Math.min(...e.map((n) => Number(n[t]) || 1 / 0)),
-  max: (e, t) => Math.max(...e.map((n) => Number(n[t]) || -1 / 0)),
-  first: (e, t) => e[0]?.[t],
-  last: (e, t) => e[e.length - 1]?.[t]
-}, u = /* @__PURE__ */ new Map(), d = {
+  count: (n) => n.length,
+  min: (n, t) => Math.min(...n.map((e) => Number(e[t]) || 1 / 0)),
+  max: (n, t) => Math.max(...n.map((e) => Number(e[t]) || -1 / 0)),
+  first: (n, t) => n[0]?.[t],
+  last: (n, t) => n[n.length - 1]?.[t]
+}, f = /* @__PURE__ */ new Map(), d = {
   /**
    * Register a custom aggregator function.
    */
-  register(e, t) {
-    u.set(e, t);
+  register(n, t) {
+    f.set(n, t);
   },
   /**
    * Unregister a custom aggregator function.
    */
-  unregister(e) {
-    u.delete(e);
+  unregister(n) {
+    f.delete(n);
   },
   /**
    * Get an aggregator function by reference.
    */
-  get(e) {
-    if (e !== void 0)
-      return typeof e == "function" ? e : u.get(e) ?? p[e];
+  get(n) {
+    if (n !== void 0)
+      return typeof n == "function" ? n : f.get(n) ?? p[n];
   },
   /**
    * Run an aggregator on a set of rows.
    */
-  run(e, t, n, i) {
-    const r = this.get(e);
-    return r ? r(t, n, i) : void 0;
+  run(n, t, e, i) {
+    const r = this.get(n);
+    return r ? r(t, e, i) : void 0;
   },
   /**
    * Check if an aggregator exists.
    */
-  has(e) {
-    return u.has(e) || e in p;
+  has(n) {
+    return f.has(n) || n in p;
   },
   /**
    * List all available aggregator names.
    */
   list() {
-    return [...Object.keys(p), ...u.keys()];
+    return [...Object.keys(p), ...f.keys()];
   }
 };
 d.register.bind(d);
 d.unregister.bind(d);
-const w = d.get.bind(d);
+const b = d.get.bind(d);
 d.run.bind(d);
 d.list.bind(d);
-function E(e) {
-  return typeof e == "object" && e !== null && "aggFunc" in e;
+function E(n) {
+  return typeof n == "object" && n !== null && "aggFunc" in n;
 }
-function m(e, t) {
-  const n = document.createElement("div");
-  n.className = "tbw-pinned-rows", n.setAttribute("role", "presentation"), n.setAttribute("aria-live", "polite");
+function m(n, t) {
+  const e = document.createElement("div");
+  e.className = "tbw-pinned-rows", e.setAttribute("role", "presentation"), e.setAttribute("aria-live", "polite");
   const i = document.createElement("div");
   i.className = "tbw-pinned-rows-left";
   const r = document.createElement("div");
   r.className = "tbw-pinned-rows-center";
   const s = document.createElement("div");
-  if (s.className = "tbw-pinned-rows-right", e.showRowCount !== !1) {
+  if (s.className = "tbw-pinned-rows-right", n.showRowCount !== !1) {
     const o = document.createElement("span");
     o.className = "tbw-status-panel tbw-status-panel-row-count", o.textContent = `Total: ${t.totalRows} rows`, i.appendChild(o);
   }
-  if (e.showFilteredCount && t.filteredRows !== t.totalRows) {
+  if (n.showFilteredCount && t.filteredRows !== t.totalRows) {
     const o = document.createElement("span");
     o.className = "tbw-status-panel tbw-status-panel-filtered-count", o.textContent = `Filtered: ${t.filteredRows}`, i.appendChild(o);
   }
-  if (e.showSelectedCount && t.selectedRows > 0) {
+  if (n.showSelectedCount && t.selectedRows > 0) {
     const o = document.createElement("span");
     o.className = "tbw-status-panel tbw-status-panel-selected-count", o.textContent = `Selected: ${t.selectedRows}`, s.appendChild(o);
   }
-  if (e.customPanels)
-    for (const o of e.customPanels) {
-      const a = x(o, t);
+  if (n.customPanels)
+    for (const o of n.customPanels) {
+      const a = y(o, t);
       switch (o.position) {
         case "left":
           i.appendChild(a);
@@ -293,62 +386,62 @@ function m(e, t) {
           break;
       }
     }
-  return n.appendChild(i), n.appendChild(r), n.appendChild(s), n;
+  return e.appendChild(i), e.appendChild(r), e.appendChild(s), e;
 }
-function b(e) {
+function w(n) {
   const t = document.createElement("div");
-  return t.className = `tbw-aggregation-rows tbw-aggregation-rows-${e}`, t.setAttribute("role", "presentation"), t;
+  return t.className = `tbw-aggregation-rows tbw-aggregation-rows-${n}`, t.setAttribute("role", "presentation"), t;
 }
-function C(e, t, n, i) {
-  e.innerHTML = "";
+function C(n, t, e, i) {
+  n.innerHTML = "";
   for (const r of t) {
     const s = document.createElement("div");
     if (s.className = "tbw-aggregation-row", s.setAttribute("role", "presentation"), r.id && s.setAttribute("data-aggregation-id", r.id), r.fullWidth) {
       const o = document.createElement("div");
       o.className = "tbw-aggregation-cell tbw-aggregation-cell-full", o.style.gridColumn = "1 / -1", o.textContent = r.label || "", s.appendChild(o);
     } else
-      for (const o of n) {
+      for (const o of e) {
         const a = document.createElement("div");
         a.className = "tbw-aggregation-cell", a.setAttribute("data-field", o.field);
-        let l, f;
+        let l, u;
         const h = r.aggregators?.[o.field];
         if (h)
           if (E(h)) {
-            const g = w(h.aggFunc);
-            g && (l = g(i, o.field, o)), f = h.formatter;
+            const g = b(h.aggFunc);
+            g && (l = g(i, o.field, o)), u = h.formatter;
           } else {
-            const g = w(h);
+            const g = b(h);
             g && (l = g(i, o.field, o));
           }
         else if (r.cells && Object.prototype.hasOwnProperty.call(r.cells, o.field)) {
           const g = r.cells[o.field];
           typeof g == "function" ? l = g(i, o.field, o) : l = g;
         }
-        l != null ? a.textContent = f ? f(l, o.field, o) : String(l) : a.textContent = "", s.appendChild(a);
+        l != null ? a.textContent = u ? u(l, o.field, o) : String(l) : a.textContent = "", s.appendChild(a);
       }
-    e.appendChild(s);
+    n.appendChild(s);
   }
 }
-function x(e, t) {
-  const n = document.createElement("div");
-  n.className = "tbw-status-panel tbw-status-panel-custom", n.id = `status-panel-${e.id}`;
-  const i = e.render(t);
-  return typeof i == "string" ? n.innerHTML = i : n.appendChild(i), n;
+function y(n, t) {
+  const e = document.createElement("div");
+  e.className = "tbw-status-panel tbw-status-panel-custom", e.id = `status-panel-${n.id}`;
+  const i = n.render(t);
+  return typeof i == "string" ? e.innerHTML = i : e.appendChild(i), e;
 }
-function v(e, t, n, i, r) {
+function v(n, t, e, i, r) {
   return {
-    totalRows: e.length,
-    filteredRows: r?.cachedResult?.length ?? e.length,
+    totalRows: n.length,
+    filteredRows: r?.cachedResult?.length ?? n.length,
     selectedRows: i?.selected?.size ?? 0,
     columns: t,
-    rows: e,
-    grid: n
+    rows: n,
+    grid: e
   };
 }
-const B = ".tbw-footer{flex-shrink:0;z-index:var(--tbw-z-layer-pinned-rows, 20);background:var(--tbw-color-panel-bg)}.tbw-pinned-rows{display:flex;align-items:center;justify-content:space-between;padding:8px 12px;background:var(--tbw-pinned-rows-bg, var(--tbw-color-panel-bg));border-top:1px solid var(--tbw-pinned-rows-border, var(--tbw-color-border));font-size:12px;color:var(--tbw-pinned-rows-color, var(--tbw-color-fg-muted));min-height:32px;box-sizing:border-box;min-width:fit-content}.tbw-pinned-rows-left,.tbw-pinned-rows-center,.tbw-pinned-rows-right{display:flex;align-items:center;gap:16px}.tbw-pinned-rows-left{justify-content:flex-start}.tbw-pinned-rows-center{justify-content:center;flex:1}.tbw-pinned-rows-right{justify-content:flex-end}.tbw-status-panel{white-space:nowrap}.tbw-aggregation-rows{min-width:fit-content;background:var(--tbw-aggregation-bg, var(--tbw-color-header-bg))}.tbw-aggregation-rows-top{border-bottom:1px solid var(--tbw-aggregation-border, var(--tbw-color-border))}.tbw-aggregation-rows-bottom{border-top:1px solid var(--tbw-aggregation-border, var(--tbw-color-border))}.tbw-aggregation-row{display:grid;grid-template-columns:var(--tbw-column-template);font-size:var(--tbw-aggregation-font-size, .8em);font-weight:var(--tbw-aggregation-font-weight, 600)}.tbw-aggregation-cell{padding:var(--tbw-cell-padding, 2px 8px);min-height:var(--tbw-row-height, 28px);display:flex;align-items:center;border-right:1px solid var(--tbw-color-border-cell)}.tbw-aggregation-cell:last-child{border-right:0}.tbw-aggregation-cell-full{grid-column:1 / -1;border-right:0}";
-class y extends R {
+const S = ".tbw-footer{flex-shrink:0;z-index:var(--tbw-z-layer-pinned-rows, 20);background:var(--tbw-color-panel-bg)}.tbw-pinned-rows{display:flex;align-items:center;justify-content:space-between;padding:8px 12px;background:var(--tbw-pinned-rows-bg, var(--tbw-color-panel-bg));border-top:1px solid var(--tbw-pinned-rows-border, var(--tbw-color-border));font-size:12px;color:var(--tbw-pinned-rows-color, var(--tbw-color-fg-muted));min-height:32px;box-sizing:border-box;min-width:fit-content}.tbw-pinned-rows-left,.tbw-pinned-rows-center,.tbw-pinned-rows-right{display:flex;align-items:center;gap:16px}.tbw-pinned-rows-left{justify-content:flex-start}.tbw-pinned-rows-center{justify-content:center;flex:1}.tbw-pinned-rows-right{justify-content:flex-end}.tbw-status-panel{white-space:nowrap}.tbw-aggregation-rows{min-width:fit-content;background:var(--tbw-aggregation-bg, var(--tbw-color-header-bg))}.tbw-aggregation-rows-top{border-bottom:1px solid var(--tbw-aggregation-border, var(--tbw-color-border))}.tbw-aggregation-rows-bottom{border-top:1px solid var(--tbw-aggregation-border, var(--tbw-color-border))}.tbw-aggregation-row{display:grid;grid-template-columns:var(--tbw-column-template);font-size:var(--tbw-aggregation-font-size, .8em);font-weight:var(--tbw-aggregation-font-weight, 600)}.tbw-aggregation-cell{padding:var(--tbw-cell-padding, 2px 8px);min-height:var(--tbw-row-height, 28px);display:flex;align-items:center;border-right:1px solid var(--tbw-color-border-cell)}.tbw-aggregation-cell:last-child{border-right:0}.tbw-aggregation-cell-full{grid-column:1 / -1;border-right:0}";
+class x extends A {
   name = "pinnedRows";
-  version = "1.0.0";
+  styles = S;
   get defaultConfig() {
     return {
       position: "bottom",
@@ -372,9 +465,9 @@ class y extends R {
   afterRender() {
     const t = this.shadowRoot;
     if (!t) return;
-    const n = t.querySelector(".tbw-scroll-area") ?? t.querySelector(".tbw-grid-content") ?? t.children[0];
-    if (!n) return;
-    this.footerWrapper && !n.contains(this.footerWrapper) && (this.footerWrapper = null, this.bottomAggregationContainer = null, this.infoBarElement = null), this.topAggregationContainer && !n.contains(this.topAggregationContainer) && (this.topAggregationContainer = null), this.infoBarElement && !n.contains(this.infoBarElement) && (this.infoBarElement = null);
+    const e = t.querySelector(".tbw-scroll-area") ?? t.querySelector(".tbw-grid-content") ?? t.children[0];
+    if (!e) return;
+    this.footerWrapper && !e.contains(this.footerWrapper) && (this.footerWrapper = null, this.bottomAggregationContainer = null, this.infoBarElement = null), this.topAggregationContainer && !e.contains(this.topAggregationContainer) && (this.topAggregationContainer = null), this.infoBarElement && !e.contains(this.infoBarElement) && (this.infoBarElement = null);
     const i = this.getSelectionState(), r = this.getFilterState(), s = v(
       this.rows,
       this.columns,
@@ -384,9 +477,9 @@ class y extends R {
     ), o = this.config.aggregationRows || [], a = o.filter((c) => c.position === "top"), l = o.filter((c) => c.position !== "top");
     if (a.length > 0) {
       if (!this.topAggregationContainer) {
-        this.topAggregationContainer = b("top");
+        this.topAggregationContainer = w("top");
         const c = t.querySelector(".header");
-        c && c.nextSibling ? n.insertBefore(this.topAggregationContainer, c.nextSibling) : n.appendChild(this.topAggregationContainer);
+        c && c.nextSibling ? e.insertBefore(this.topAggregationContainer, c.nextSibling) : e.appendChild(this.topAggregationContainer);
       }
       C(
         this.topAggregationContainer,
@@ -395,16 +488,16 @@ class y extends R {
         this.rows
       );
     } else this.topAggregationContainer && (this.topAggregationContainer.remove(), this.topAggregationContainer = null);
-    const f = this.config.showRowCount !== !1 || this.config.showSelectedCount && s.selectedRows > 0 || this.config.showFilteredCount && s.filteredRows !== s.totalRows || this.config.customPanels && this.config.customPanels.length > 0, h = f && this.config.position !== "top", g = l.length > 0 || h;
-    if (f && this.config.position === "top")
+    const u = this.config.showRowCount !== !1 || this.config.showSelectedCount && s.selectedRows > 0 || this.config.showFilteredCount && s.filteredRows !== s.totalRows || this.config.customPanels && this.config.customPanels.length > 0, h = u && this.config.position !== "top", g = l.length > 0 || h;
+    if (u && this.config.position === "top")
       if (!this.infoBarElement)
-        this.infoBarElement = m(this.config, s), n.insertBefore(this.infoBarElement, n.firstChild);
+        this.infoBarElement = m(this.config, s), e.insertBefore(this.infoBarElement, e.firstChild);
       else {
         const c = m(this.config, s);
         this.infoBarElement.replaceWith(c), this.infoBarElement = c;
       }
     else this.config.position === "top" && this.infoBarElement && (this.infoBarElement.remove(), this.infoBarElement = null);
-    g ? (this.footerWrapper || (this.footerWrapper = document.createElement("div"), this.footerWrapper.className = "tbw-footer", n.appendChild(this.footerWrapper)), this.footerWrapper.innerHTML = "", l.length > 0 && (this.bottomAggregationContainer || (this.bottomAggregationContainer = b("bottom")), this.footerWrapper.appendChild(this.bottomAggregationContainer), C(
+    g ? (this.footerWrapper || (this.footerWrapper = document.createElement("div"), this.footerWrapper.className = "tbw-footer", e.appendChild(this.footerWrapper)), this.footerWrapper.innerHTML = "", l.length > 0 && (this.bottomAggregationContainer || (this.bottomAggregationContainer = w("bottom")), this.footerWrapper.appendChild(this.bottomAggregationContainer), C(
       this.bottomAggregationContainer,
       l,
       this.visibleColumns,
@@ -446,13 +539,13 @@ class y extends R {
    * @returns The context with row counts and other info
    */
   getContext() {
-    const t = this.getSelectionState(), n = this.getFilterState();
+    const t = this.getSelectionState(), e = this.getFilterState();
     return v(
       this.rows,
       this.columns,
       this.grid,
       t,
-      n
+      e
     );
   }
   /**
@@ -467,7 +560,7 @@ class y extends R {
    * @param id - The panel ID to remove
    */
   removePanel(t) {
-    this.config.customPanels && (this.config.customPanels = this.config.customPanels.filter((n) => n.id !== t), this.requestRender());
+    this.config.customPanels && (this.config.customPanels = this.config.customPanels.filter((e) => e.id !== t), this.requestRender());
   }
   /**
    * Add an aggregation row.
@@ -481,14 +574,11 @@ class y extends R {
    * @param id - The aggregation row ID to remove
    */
   removeAggregationRow(t) {
-    this.config.aggregationRows && (this.config.aggregationRows = this.config.aggregationRows.filter((n) => n.id !== t), this.requestRender());
+    this.config.aggregationRows && (this.config.aggregationRows = this.config.aggregationRows.filter((e) => e.id !== t), this.requestRender());
   }
   // #endregion
-  // #region Styles
-  styles = B;
-  // #endregion
 }
 export {
-  y as PinnedRowsPlugin
+  x as PinnedRowsPlugin
 };
 //# sourceMappingURL=index.js.map