@toolbox-web/grid 0.4.0 → 0.4.2

package/lib/plugins/filtering/index.js

@@ -10,7 +10,7 @@ function P(p) {
     totalHeight: e * l
   };
 }
-function M(p, e) {
+function _(p, e) {
   return p <= e;
 }
 const V = {
@@ -23,9 +23,28 @@ const V = {
   dragHandle: "⋮⋮",
   toolPanel: "☰"
 };
-class _ {
-  /** Plugin version - override in subclass if needed */
-  version = "1.0.0";
+class M {
+  /**
+   * 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 */
@@ -112,12 +131,28 @@ class _ {
   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 r = new CustomEvent(e, { detail: t, bubbles: !0, cancelable: !0 });
+    return this.grid?.dispatchEvent?.(r), r.defaultPrevented;
+  }
   /**
    * Request a re-render of the grid.
    */
   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.
@@ -151,6 +186,19 @@ class _ {
   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.
    */
@@ -185,6 +233,51 @@ class _ {
     const e = this.grid?.gridConfig?.icons ?? {};
     return { ...V, ...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(), r = parseInt(t, 10);
+      if (!isNaN(r)) return r;
+    }
+    return 200;
+  }
+  // #endregion
   /**
    * Resolve an icon value to string or HTMLElement.
    * Checks plugin config first, then grid-level icons, then defaults.
@@ -277,10 +370,10 @@ function N(p, e) {
   }
   return [...t].sort((r, l) => typeof r == "number" && typeof l == "number" ? r - l : String(r).localeCompare(String(l)));
 }
-const $ = ':host .tbw-quick-filter-input{flex:1;max-width:300px;height:28px;padding:0 8px;border:1px solid var(--tbw-color-border);border-radius:var(--tbw-border-radius);background:var(--tbw-color-bg);color:var(--tbw-color-fg);font-size:13px}:host .tbw-quick-filter-input:focus{outline:none;border-color:var(--tbw-color-accent)}:host .header-cell.filtered:before{content:"";position:absolute;top:4px;right:4px;width:6px;height:6px;background:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6));border-radius:50%}:host .tbw-filter-btn{display:inline-flex;align-items:center;justify-content:center;background:transparent;border:none;cursor:pointer;padding:2px;margin-left:4px;opacity:.4;transition:opacity .15s;color:inherit;vertical-align:middle}:host .tbw-filter-btn:hover,:host .tbw-filter-btn.active{opacity:1}:host .tbw-filter-btn.active{color:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6))}', K = ".tbw-filter-panel{position:fixed;background:var(--tbw-filter-panel-bg, var(--tbw-color-panel-bg, light-dark(#eeeeee, #222222)));color:var(--tbw-filter-panel-fg, var(--tbw-color-fg, light-dark(#222222, #eeeeee)));border:1px solid var(--tbw-filter-panel-border, var(--tbw-color-border, light-dark(#d0d0d4, #454545)));border-radius:var(--tbw-filter-panel-radius, var(--tbw-border-radius, 4px));box-shadow:0 4px 16px var(--tbw-filter-panel-shadow, var(--tbw-color-shadow, light-dark(rgba(0, 0, 0, .1), rgba(0, 0, 0, .3))));padding:12px;z-index:10000;min-width:200px;max-width:280px;max-height:350px;display:flex;flex-direction:column;font-family:var(--tbw-font-family, system-ui, sans-serif);font-size:var(--tbw-font-size, 13px)}.tbw-filter-search{margin-bottom:8px}.tbw-filter-search-input{width:100%;padding:6px 10px;background:var(--tbw-filter-input-bg, var(--tbw-color-bg, transparent));color:inherit;border:1px solid var(--tbw-filter-input-border, var(--tbw-color-border, light-dark(#d0d0d4, #454545)));border-radius:var(--tbw-filter-input-radius, 4px);font-size:inherit;box-sizing:border-box}.tbw-filter-search-input:focus{outline:none;border-color:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6));box-shadow:0 0 0 2px rgba(from var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6)) r g b / 15%)}.tbw-filter-actions{display:flex;padding:4px 2px;margin-bottom:8px;border-bottom:1px solid var(--tbw-filter-divider, var(--tbw-color-border, light-dark(#d0d0d4, #454545)))}.tbw-filter-action-btn{background:transparent;border:none;color:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6));cursor:pointer;font-size:12px;padding:2px 0}.tbw-filter-action-btn:hover{text-decoration:underline}.tbw-filter-values{flex:1;overflow-y:auto;margin-bottom:8px;max-height:180px;position:relative}.tbw-filter-values-spacer{width:1px}.tbw-filter-values-content{position:absolute;top:0;left:0;right:0}.tbw-filter-value-item{display:flex;align-items:center;gap:8px;padding:4px 2px;cursor:pointer;border-radius:3px}.tbw-filter-value-item:hover{background:var(--tbw-filter-hover, var(--tbw-color-row-hover, light-dark(#f0f6ff, #1c1c1c)))}.tbw-filter-checkbox{margin:0;cursor:pointer;accent-color:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6))}.tbw-filter-no-match{color:var(--tbw-filter-muted, var(--tbw-color-fg-muted, light-dark(#555555, #aaaaaa)));padding:8px 0;text-align:center;font-style:italic}.tbw-filter-buttons{display:flex;gap:8px;padding-top:8px;border-top:1px solid var(--tbw-filter-divider, var(--tbw-color-border, light-dark(#d0d0d4, #454545)))}.tbw-filter-apply-btn{flex:1;padding:6px 12px;background:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6));color:var(--tbw-filter-accent-fg, var(--tbw-color-accent-fg, light-dark(#ffffff, #000000)));border:none;border-radius:4px;cursor:pointer;font-size:13px}.tbw-filter-apply-btn:hover{filter:brightness(.9)}.tbw-filter-clear-btn{flex:1;padding:6px 12px;background:transparent;color:var(--tbw-filter-muted, var(--tbw-color-fg-muted, light-dark(#555555, #aaaaaa)));border:1px solid var(--tbw-filter-input-border, var(--tbw-color-border, light-dark(#d0d0d4, #454545)));border-radius:4px;cursor:pointer;font-size:13px}.tbw-filter-clear-btn:hover{background:var(--tbw-filter-hover, var(--tbw-color-row-hover, light-dark(#f0f6ff, #1c1c1c)))}";
-class x extends _ {
+const G = ':host .tbw-quick-filter-input{flex:1;max-width:300px;height:28px;padding:0 8px;border:1px solid var(--tbw-color-border);border-radius:var(--tbw-border-radius);background:var(--tbw-color-bg);color:var(--tbw-color-fg);font-size:13px}:host .tbw-quick-filter-input:focus{outline:none;border-color:var(--tbw-color-accent)}:host .header-cell.filtered:before{content:"";position:absolute;top:4px;right:4px;width:6px;height:6px;background:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6));border-radius:50%}:host .tbw-filter-btn{display:inline-flex;align-items:center;justify-content:center;background:transparent;border:none;cursor:pointer;padding:2px;margin-left:4px;opacity:.4;transition:opacity .15s;color:inherit;vertical-align:middle}:host .tbw-filter-btn:hover,:host .tbw-filter-btn.active{opacity:1}:host .tbw-filter-btn.active{color:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6))}', $ = ".tbw-filter-panel{position:fixed;background:var(--tbw-filter-panel-bg, var(--tbw-color-panel-bg, light-dark(#eeeeee, #222222)));color:var(--tbw-filter-panel-fg, var(--tbw-color-fg, light-dark(#222222, #eeeeee)));border:1px solid var(--tbw-filter-panel-border, var(--tbw-color-border, light-dark(#d0d0d4, #454545)));border-radius:var(--tbw-filter-panel-radius, var(--tbw-border-radius, 4px));box-shadow:0 4px 16px var(--tbw-filter-panel-shadow, var(--tbw-color-shadow, light-dark(rgba(0, 0, 0, .1), rgba(0, 0, 0, .3))));padding:12px;z-index:10000;min-width:200px;max-width:280px;max-height:350px;display:flex;flex-direction:column;font-family:var(--tbw-font-family, system-ui, sans-serif);font-size:var(--tbw-font-size, 13px)}.tbw-filter-search{margin-bottom:8px}.tbw-filter-search-input{width:100%;padding:6px 10px;background:var(--tbw-filter-input-bg, var(--tbw-color-bg, transparent));color:inherit;border:1px solid var(--tbw-filter-input-border, var(--tbw-color-border, light-dark(#d0d0d4, #454545)));border-radius:var(--tbw-filter-input-radius, 4px);font-size:inherit;box-sizing:border-box}.tbw-filter-search-input:focus{outline:none;border-color:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6));box-shadow:0 0 0 2px rgba(from var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6)) r g b / 15%)}.tbw-filter-actions{display:flex;padding:4px 2px;margin-bottom:8px;border-bottom:1px solid var(--tbw-filter-divider, var(--tbw-color-border, light-dark(#d0d0d4, #454545)))}.tbw-filter-action-btn{background:transparent;border:none;color:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6));cursor:pointer;font-size:12px;padding:2px 0}.tbw-filter-action-btn:hover{text-decoration:underline}.tbw-filter-values{flex:1;overflow-y:auto;margin-bottom:8px;max-height:180px;position:relative}.tbw-filter-values-spacer{width:1px}.tbw-filter-values-content{position:absolute;top:0;left:0;right:0}.tbw-filter-value-item{display:flex;align-items:center;gap:8px;padding:4px 2px;cursor:pointer;border-radius:3px}.tbw-filter-value-item:hover{background:var(--tbw-filter-hover, var(--tbw-color-row-hover, light-dark(#f0f6ff, #1c1c1c)))}.tbw-filter-checkbox{margin:0;cursor:pointer;accent-color:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6))}.tbw-filter-no-match{color:var(--tbw-filter-muted, var(--tbw-color-fg-muted, light-dark(#555555, #aaaaaa)));padding:8px 0;text-align:center;font-style:italic}.tbw-filter-buttons{display:flex;gap:8px;padding-top:8px;border-top:1px solid var(--tbw-filter-divider, var(--tbw-color-border, light-dark(#d0d0d4, #454545)))}.tbw-filter-apply-btn{flex:1;padding:6px 12px;background:var(--tbw-filter-accent, var(--tbw-color-accent, #3b82f6));color:var(--tbw-filter-accent-fg, var(--tbw-color-accent-fg, light-dark(#ffffff, #000000)));border:none;border-radius:4px;cursor:pointer;font-size:13px}.tbw-filter-apply-btn:hover{filter:brightness(.9)}.tbw-filter-clear-btn{flex:1;padding:6px 12px;background:transparent;color:var(--tbw-filter-muted, var(--tbw-color-fg-muted, light-dark(#555555, #aaaaaa)));border:1px solid var(--tbw-filter-input-border, var(--tbw-color-border, light-dark(#d0d0d4, #454545)));border-radius:4px;cursor:pointer;font-size:13px}.tbw-filter-clear-btn:hover{background:var(--tbw-filter-hover, var(--tbw-color-row-hover, light-dark(#f0f6ff, #1c1c1c)))}";
+class x extends M {
   name = "filtering";
-  version = "1.0.0";
+  styles = G;
   get defaultConfig() {
     return {
       debounceMs: 300,
@@ -305,6 +398,12 @@ class x extends _ {
   static LIST_OVERSCAN = 3;
   static LIST_BYPASS_THRESHOLD = 50;
   // Don't virtualize if < 50 items
+  /**
+   * Sync excludedValues map from a filter model (for set filters).
+   */
+  syncExcludedValues(e, t) {
+    t ? t.type === "set" && t.operator === "notIn" && Array.isArray(t.value) ? this.excludedValues.set(e, new Set(t.value)) : t.type === "set" && this.excludedValues.delete(e) : this.excludedValues.delete(e);
+  }
   // #endregion
   // #region Lifecycle
   attach(e) {
@@ -356,7 +455,13 @@ class x extends _ {
    * Pass null to remove the filter.
    */
   setFilter(e, t) {
-    t === null ? (this.filters.delete(e), this.excludedValues.delete(e)) : (this.filters.set(e, { ...t, field: e }), t.type === "set" && t.operator === "notIn" && Array.isArray(t.value) ? this.excludedValues.set(e, new Set(t.value)) : t.type === "set" && this.excludedValues.delete(e)), this.cachedResult = null, this.cacheKey = null, this.emit("filter-change", {
+    if (t === null)
+      this.filters.delete(e), this.syncExcludedValues(e, null);
+    else {
+      const r = { ...t, field: e };
+      this.filters.set(e, r), this.syncExcludedValues(e, r);
+    }
+    this.cachedResult = null, this.cacheKey = null, this.emit("filter-change", {
       filters: [...this.filters.values()],
       filteredRowCount: 0
       // Will be accurate after processRows
@@ -386,7 +491,7 @@ class x extends _ {
   setFilterModel(e) {
     this.filters.clear(), this.excludedValues.clear();
     for (const t of e)
-      this.filters.set(t.field, t), t.type === "set" && t.operator === "notIn" && Array.isArray(t.value) && this.excludedValues.set(t.field, new Set(t.value));
+      this.filters.set(t.field, t), this.syncExcludedValues(t.field, t);
     this.cachedResult = null, this.cacheKey = null, this.emit("filter-change", {
       filters: [...this.filters.values()],
       filteredRowCount: 0
@@ -441,7 +546,7 @@ class x extends _ {
       return;
     }
     const e = document.createElement("style");
-    e.id = "tbw-filter-panel-styles", e.textContent = K, document.head.appendChild(e), this.globalStylesInjected = !0;
+    e.id = "tbw-filter-panel-styles", e.textContent = $, document.head.appendChild(e), this.globalStylesInjected = !0;
   }
   /**
    * Toggle the filter panel for a field
@@ -535,39 +640,39 @@ class x extends _ {
     const C = document.createElement("span");
     C.textContent = "Select All", f.appendChild(b), f.appendChild(C), s.appendChild(f);
     const k = () => {
-      const a = [...m.values()], u = a.every((d) => d), h = a.every((d) => !d);
+      const a = [...v.values()], u = a.every((d) => d), h = a.every((d) => !d);
       b.checked = u, b.indeterminate = !u && !h;
     };
     b.addEventListener("change", () => {
       const a = b.checked;
-      for (const u of m.keys())
-        m.set(u, a);
+      for (const u of v.keys())
+        v.set(u, a);
       k(), F();
     }), e.appendChild(s);
-    const v = document.createElement("div");
-    v.className = "tbw-filter-values";
-    const S = document.createElement("div");
-    S.className = "tbw-filter-values-spacer", v.appendChild(S);
+    const m = document.createElement("div");
+    m.className = "tbw-filter-values";
+    const E = document.createElement("div");
+    E.className = "tbw-filter-values-spacer", m.appendChild(E);
     const g = document.createElement("div");
-    g.className = "tbw-filter-values-content", v.appendChild(g);
-    const m = /* @__PURE__ */ new Map();
+    g.className = "tbw-filter-values-content", m.appendChild(g);
+    const v = /* @__PURE__ */ new Map();
     r.forEach((a) => {
       const u = a == null ? "__null__" : String(a);
-      m.set(u, !l.has(a));
+      v.set(u, !l.has(a));
     }), k();
     let y = [];
     const I = (a, u) => {
       const h = a == null ? "(Blank)" : String(a), d = a == null ? "__null__" : String(a), c = document.createElement("label");
       c.className = "tbw-filter-value-item", c.style.position = "absolute", c.style.top = `${u * x.LIST_ITEM_HEIGHT}px`, c.style.left = "0", c.style.right = "0", c.style.height = `${x.LIST_ITEM_HEIGHT}px`, c.style.boxSizing = "border-box";
       const w = document.createElement("input");
-      w.type = "checkbox", w.className = "tbw-filter-checkbox", w.checked = m.get(d) ?? !0, w.dataset.value = d, w.addEventListener("change", () => {
-        m.set(d, w.checked), k();
+      w.type = "checkbox", w.className = "tbw-filter-checkbox", w.checked = v.get(d) ?? !0, w.dataset.value = d, w.addEventListener("change", () => {
+        v.set(d, w.checked), k();
       });
-      const H = document.createElement("span");
-      return H.textContent = h, c.appendChild(w), c.appendChild(H), c;
+      const A = document.createElement("span");
+      return A.textContent = h, c.appendChild(w), c.appendChild(A), c;
     }, F = () => {
-      const a = y.length, u = v.clientHeight, h = v.scrollTop;
-      if (S.style.height = `${a * x.LIST_ITEM_HEIGHT}px`, M(a, x.LIST_BYPASS_THRESHOLD / 3)) {
+      const a = y.length, u = m.clientHeight, h = m.scrollTop;
+      if (E.style.height = `${a * x.LIST_ITEM_HEIGHT}px`, _(a, x.LIST_BYPASS_THRESHOLD / 3)) {
         g.innerHTML = "", g.style.transform = "translateY(0px)", y.forEach((c, w) => {
           g.appendChild(I(c, w));
         });
@@ -589,32 +694,32 @@ class x extends _ {
         const d = h == null ? "(Blank)" : String(h);
         return !a || d.toLowerCase().includes(u);
       }), y.length === 0) {
-        S.style.height = "0px", g.innerHTML = "";
+        E.style.height = "0px", g.innerHTML = "";
         const h = document.createElement("div");
         h.className = "tbw-filter-no-match", h.textContent = "No matching values", g.appendChild(h);
         return;
       }
       F();
     };
-    v.addEventListener(
+    m.addEventListener(
       "scroll",
       () => {
         y.length > 0 && F();
       },
       { passive: !0 }
-    ), L(i.value), e.appendChild(v);
-    let A;
+    ), L(i.value), e.appendChild(m);
+    let H;
     i.addEventListener("input", () => {
-      clearTimeout(A), A = setTimeout(() => {
+      clearTimeout(H), H = setTimeout(() => {
         this.searchText.set(n, i.value), L(i.value);
       }, this.config.debounceMs ?? 150);
     });
-    const T = document.createElement("div");
-    T.className = "tbw-filter-buttons";
-    const E = document.createElement("button");
-    E.className = "tbw-filter-apply-btn", E.textContent = "Apply", E.addEventListener("click", () => {
+    const S = document.createElement("div");
+    S.className = "tbw-filter-buttons";
+    const R = document.createElement("button");
+    R.className = "tbw-filter-apply-btn", R.textContent = "Apply", R.addEventListener("click", () => {
       const a = [];
-      for (const [u, h] of m)
+      for (const [u, h] of v)
         if (!h)
           if (u === "__null__")
             a.push(null);
@@ -623,11 +728,11 @@ class x extends _ {
             a.push(d !== void 0 ? d : u);
           }
       t.applySetFilter(a);
-    }), T.appendChild(E);
-    const R = document.createElement("button");
-    R.className = "tbw-filter-clear-btn", R.textContent = "Clear Filter", R.addEventListener("click", () => {
+    }), S.appendChild(R);
+    const T = document.createElement("button");
+    T.className = "tbw-filter-clear-btn", T.textContent = "Clear Filter", T.addEventListener("click", () => {
       t.clearFilter();
-    }), T.appendChild(R), e.appendChild(T);
+    }), S.appendChild(T), e.appendChild(S);
   }
   /**
    * Apply a set filter (exclude values)
@@ -710,9 +815,6 @@ class x extends _ {
     this.filters.set(e, r), this.cachedResult = null, this.cacheKey = null;
   }
   // #endregion
-  // #region Styles
-  styles = $;
-  // #endregion
 }
 export {
   x as FilteringPlugin