@toolbox-web/grid 0.4.1 → 0.5.0

package/lib/plugins/context-menu/index.js

@@ -25,8 +25,11 @@ class I {
    * ```
    */
   static dependencies;
-  /** Plugin version - override in subclass if needed */
-  version = "1.0.0";
+  /**
+   * 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 */
@@ -110,8 +113,16 @@ class I {
   /**
    * Emit a custom event from the grid.
    */
-  emit(e, n) {
-    this.grid?.dispatchEvent?.(new CustomEvent(e, { detail: n, 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.
@@ -119,6 +130,14 @@ class I {
   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.
@@ -153,10 +172,34 @@ class I {
     return this.grid?._visibleColumns ?? [];
   }
   /**
-   * Get the shadow root of the grid.
+   * 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 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.grid?.shadowRoot ?? null;
+    return this.gridElement;
   }
   /**
    * Get the disconnect signal for event listener cleanup.
@@ -186,6 +229,51 @@ class I {
     const e = this.grid?.gridConfig?.icons ?? {};
     return { ...C, ...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.gridElement;
+    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.gridElement;
+    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.
@@ -194,8 +282,8 @@ class I {
    * @param pluginOverride - Optional plugin-level override
    * @returns The resolved icon value
    */
-  resolveIcon(e, n) {
-    return n !== void 0 ? n : this.gridIcons[e];
+  resolveIcon(e, t) {
+    return t !== void 0 ? t : this.gridIcons[e];
   }
   /**
    * Set an icon value on an element.
@@ -204,8 +292,8 @@ class I {
    * @param element - The element to set the icon on
    * @param icon - The icon value (string or HTMLElement)
    */
-  setIcon(e, n) {
-    typeof n == "string" ? e.innerHTML = n : n instanceof HTMLElement && (e.innerHTML = "", e.appendChild(n.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.
@@ -215,82 +303,81 @@ class I {
   }
   // #endregion
 }
-const g = ".tbw-context-menu{position:fixed;background:light-dark(#f5f5f5,#2a2a2a);color:light-dark(#222,#eee);border:1px solid light-dark(#d0d0d4,#454545);border-radius:4px;box-shadow:0 2px 10px #00000026;min-width:160px;padding:4px 0;z-index:10000;font-size:13px;font-family:system-ui,sans-serif}.tbw-context-menu-item{display:flex;align-items:center;padding:6px 12px;cursor:pointer;gap:8px}.tbw-context-menu-item:hover:not(.disabled){background:light-dark(#e8e8e8,#3a3a3a)}.tbw-context-menu-item.disabled{opacity:.5;cursor:default}.tbw-context-menu-item.danger{color:light-dark(#c00,#f66)}.tbw-context-menu-icon{width:16px;text-align:center}.tbw-context-menu-label{flex:1}.tbw-context-menu-shortcut{color:light-dark(#888,#888);font-size:11px}.tbw-context-menu-arrow{font-size:10px;color:light-dark(#888,#888)}.tbw-context-menu-separator{height:1px;background:light-dark(#d0d0d4,#454545);margin:4px 0}";
-function w(s, e) {
-  return (typeof s == "function" ? s(e) : s).filter((i) => !(i.hidden === !0 || typeof i.hidden == "function" && i.hidden(e)));
+const g = "@layer tbw-plugins{.tbw-context-menu{position:fixed;background:var(--tbw-context-menu-bg, var(--tbw-color-panel-bg, light-dark(#f5f5f5, #2a2a2a)));color:var(--tbw-context-menu-fg, var(--tbw-color-fg, light-dark(#222, #eee)));border:1px solid var(--tbw-context-menu-border, var(--tbw-color-border, light-dark(#d0d0d4, #454545)));border-radius:var(--tbw-border-radius, .25rem);box-shadow:0 2px 10px var(--tbw-color-shadow, rgba(0, 0, 0, .15));min-width:var(--tbw-menu-min-width, 10rem);padding:var(--tbw-spacing-xs, .25rem) 0;z-index:10000;font-size:var(--tbw-font-size-sm, .8125rem);font-family:var(--tbw-font-family, system-ui, sans-serif)}.tbw-context-menu-item{display:flex;align-items:center;padding:var(--tbw-menu-item-padding, .375rem .75rem);cursor:pointer;gap:var(--tbw-menu-item-gap, .5rem)}.tbw-context-menu-item:hover:not(.disabled){background:var(--tbw-context-menu-hover, var(--tbw-color-row-hover, light-dark(#e8e8e8, #3a3a3a)))}.tbw-context-menu-item.disabled{opacity:.5;cursor:default}.tbw-context-menu-item.danger{color:light-dark(#c00,#f66)}.tbw-context-menu-icon{width:var(--tbw-icon-size, 1rem);text-align:center}.tbw-context-menu-label{flex:1}.tbw-context-menu-shortcut{color:var(--tbw-color-fg-muted, light-dark(#888, #888));font-size:var(--tbw-font-size-xs, .6875rem)}.tbw-context-menu-arrow{font-size:var(--tbw-font-size-2xs, .625rem);color:var(--tbw-color-fg-muted, light-dark(#888, #888))}.tbw-context-menu-separator{height:1px;background:var(--tbw-context-menu-border, var(--tbw-color-border, light-dark(#d0d0d4, #454545)));margin:var(--tbw-spacing-xs, .25rem) 0}}";
+function v(r, e) {
+  return (typeof r == "function" ? r(e) : r).filter((n) => !(n.hidden === !0 || typeof n.hidden == "function" && n.hidden(e)));
 }
-function M(s, e) {
-  return s.disabled === !0 ? !0 : typeof s.disabled == "function" ? s.disabled(e) : !1;
+function M(r, e) {
+  return r.disabled === !0 ? !0 : typeof r.disabled == "function" ? r.disabled(e) : !1;
 }
-function v(s, e, n, i = C.submenuArrow) {
-  const r = document.createElement("div");
-  r.className = "tbw-context-menu", r.setAttribute("role", "menu");
-  for (const o of s) {
+function x(r, e, t, n = C.submenuArrow) {
+  const l = document.createElement("div");
+  l.className = "tbw-context-menu", l.setAttribute("role", "menu");
+  for (const o of r) {
     if (o.separator) {
-      const l = document.createElement("div");
-      l.className = "tbw-context-menu-separator", l.setAttribute("role", "separator"), r.appendChild(l);
+      const s = document.createElement("div");
+      s.className = "tbw-context-menu-separator", s.setAttribute("role", "separator"), l.appendChild(s);
       continue;
     }
-    const t = document.createElement("div");
-    t.className = "tbw-context-menu-item", o.cssClass && t.classList.add(o.cssClass), t.setAttribute("role", "menuitem"), t.setAttribute("data-id", o.id);
-    const c = M(o, e);
-    if (c && (t.classList.add("disabled"), t.setAttribute("aria-disabled", "true")), o.icon) {
-      const l = document.createElement("span");
-      l.className = "tbw-context-menu-icon", l.innerHTML = o.icon, t.appendChild(l);
+    const i = document.createElement("div");
+    i.className = "tbw-context-menu-item", o.cssClass && i.classList.add(o.cssClass), i.setAttribute("role", "menuitem"), i.setAttribute("data-id", o.id);
+    const d = M(o, e);
+    if (d && (i.classList.add("disabled"), i.setAttribute("aria-disabled", "true")), o.icon) {
+      const s = document.createElement("span");
+      s.className = "tbw-context-menu-icon", s.innerHTML = o.icon, i.appendChild(s);
     }
-    const d = document.createElement("span");
-    if (d.className = "tbw-context-menu-label", d.textContent = o.name, t.appendChild(d), o.shortcut) {
-      const l = document.createElement("span");
-      l.className = "tbw-context-menu-shortcut", l.textContent = o.shortcut, t.appendChild(l);
+    const a = document.createElement("span");
+    if (a.className = "tbw-context-menu-label", a.textContent = o.name, i.appendChild(a), o.shortcut) {
+      const s = document.createElement("span");
+      s.className = "tbw-context-menu-shortcut", s.textContent = o.shortcut, i.appendChild(s);
     }
     if (o.subMenu?.length) {
-      const l = document.createElement("span");
-      l.className = "tbw-context-menu-arrow", typeof i == "string" ? l.innerHTML = i : i instanceof HTMLElement && l.appendChild(i.cloneNode(!0)), t.appendChild(l), t.addEventListener("mouseenter", () => {
-        if (t.querySelector(".tbw-context-menu") || !o.subMenu) return;
-        const h = w(o.subMenu, e), a = v(h, e, n, i);
-        a.classList.add("tbw-context-submenu"), a.style.position = "absolute", a.style.left = "100%", a.style.top = "0", t.style.position = "relative", t.appendChild(a);
-      }), t.addEventListener("mouseleave", () => {
-        const u = t.querySelector(".tbw-context-menu");
+      const s = document.createElement("span");
+      s.className = "tbw-context-menu-arrow", typeof n == "string" ? s.innerHTML = n : n instanceof HTMLElement && s.appendChild(n.cloneNode(!0)), i.appendChild(s), i.addEventListener("mouseenter", () => {
+        if (i.querySelector(".tbw-context-menu") || !o.subMenu) return;
+        const h = v(o.subMenu, e), c = x(h, e, t, n);
+        c.classList.add("tbw-context-submenu"), c.style.position = "absolute", c.style.left = "100%", c.style.top = "0", i.style.position = "relative", i.appendChild(c);
+      }), i.addEventListener("mouseleave", () => {
+        const u = i.querySelector(".tbw-context-menu");
         u && u.remove();
       });
     }
-    !c && o.action && !o.subMenu && t.addEventListener("click", (l) => {
-      l.stopPropagation(), n(o);
-    }), r.appendChild(t);
+    !d && o.action && !o.subMenu && i.addEventListener("click", (s) => {
+      s.stopPropagation(), t(o);
+    }), l.appendChild(i);
   }
-  return r;
+  return l;
 }
-function y(s, e, n) {
-  s.style.position = "fixed", s.style.left = `${e}px`, s.style.top = `${n}px`, s.style.visibility = "hidden", s.style.zIndex = "10000";
-  const i = s.getBoundingClientRect(), r = window.innerWidth, o = window.innerHeight;
-  let t = e, c = n;
-  e + i.width > r && (t = e - i.width), n + i.height > o && (c = n - i.height), t = Math.max(0, t), c = Math.max(0, c), s.style.left = `${t}px`, s.style.top = `${c}px`, s.style.visibility = "visible";
+function y(r, e, t) {
+  r.style.position = "fixed", r.style.left = `${e}px`, r.style.top = `${t}px`, r.style.visibility = "hidden", r.style.zIndex = "10000";
+  const n = r.getBoundingClientRect(), l = window.innerWidth, o = window.innerHeight;
+  let i = e, d = t;
+  e + n.width > l && (i = e - n.width), t + n.height > o && (d = t - n.height), i = Math.max(0, i), d = Math.max(0, d), r.style.left = `${i}px`, r.style.top = `${d}px`, r.style.visibility = "visible";
 }
-let f = null, p = null, m = null, b = 0;
-const x = [
+let f = null, b = null, m = null, p = 0;
+const w = [
   {
     id: "copy",
     name: "Copy",
     shortcut: "Ctrl+C",
-    action: (s) => {
-      s.grid?.plugins?.clipboard?.copy?.();
+    action: (r) => {
+      r.grid?.plugins?.clipboard?.copy?.();
     }
   },
   { separator: !0, id: "sep1", name: "" },
   {
     id: "export-csv",
     name: "Export CSV",
-    action: (s) => {
-      s.grid?.plugins?.export?.exportCsv?.();
+    action: (r) => {
+      r.grid?.plugins?.export?.exportCsv?.();
     }
   }
 ];
 class H extends I {
   name = "contextMenu";
-  version = "1.0.0";
   get defaultConfig() {
     return {
-      items: x
+      items: w
     };
   }
   // #region Internal State
@@ -301,7 +388,7 @@ class H extends I {
   // #endregion
   // #region Lifecycle
   attach(e) {
-    super.attach(e), this.installGlobalHandlers(), b++;
+    super.attach(e), this.installGlobalHandlers(), p++;
   }
   detach() {
     this.menuElement && (this.menuElement.remove(), this.menuElement = null), this.isOpen = !1, this.params = null, this.uninstallGlobalHandlers();
@@ -310,44 +397,44 @@ class H extends I {
   // #region Private Methods
   installGlobalHandlers() {
     !m && typeof document < "u" && typeof g == "string" && g && (m = document.createElement("style"), m.id = "tbw-context-menu-styles", m.textContent = g, document.head.appendChild(m)), f || (f = () => {
-      document.querySelectorAll(".tbw-context-menu").forEach((n) => n.remove());
-    }, document.addEventListener("click", f)), p || (p = (e) => {
-      e.key === "Escape" && document.querySelectorAll(".tbw-context-menu").forEach((i) => i.remove());
-    }, document.addEventListener("keydown", p));
+      document.querySelectorAll(".tbw-context-menu").forEach((t) => t.remove());
+    }, document.addEventListener("click", f)), b || (b = (e) => {
+      e.key === "Escape" && document.querySelectorAll(".tbw-context-menu").forEach((n) => n.remove());
+    }, document.addEventListener("keydown", b));
   }
   /**
    * Clean up global handlers when the last instance detaches.
    * Uses reference counting to ensure handlers persist while any grid uses the plugin.
    */
   uninstallGlobalHandlers() {
-    b--, !(b > 0) && (f && (document.removeEventListener("click", f), f = null), p && (document.removeEventListener("keydown", p), p = null), m && (m.remove(), m = null));
+    p--, !(p > 0) && (f && (document.removeEventListener("click", f), f = null), b && (document.removeEventListener("keydown", b), b = null), m && (m.remove(), m = null));
   }
   // #endregion
   // #region Hooks
   afterRender() {
-    const e = this.shadowRoot;
+    const e = this.gridElement;
     if (!e) return;
-    const n = e.children[0];
-    n && n.getAttribute("data-context-menu-bound") !== "true" && (n.setAttribute("data-context-menu-bound", "true"), n.addEventListener("contextmenu", (i) => {
-      const r = i;
-      r.preventDefault();
-      const o = r.target, t = o.closest("[data-row][data-col]"), c = o.closest(".header-cell");
-      let d;
-      if (t) {
-        const u = parseInt(t.getAttribute("data-row") ?? "-1", 10), h = parseInt(t.getAttribute("data-col") ?? "-1", 10), a = this.columns[h], E = this.rows[u];
-        d = {
+    const t = e.children[0];
+    t && t.getAttribute("data-context-menu-bound") !== "true" && (t.setAttribute("data-context-menu-bound", "true"), t.addEventListener("contextmenu", (n) => {
+      const l = n;
+      l.preventDefault();
+      const o = l.target, i = o.closest("[data-row][data-col]"), d = o.closest(".header-cell");
+      let a;
+      if (i) {
+        const u = parseInt(i.getAttribute("data-row") ?? "-1", 10), h = parseInt(i.getAttribute("data-col") ?? "-1", 10), c = this.columns[h], E = this.rows[u];
+        a = {
           row: E,
           rowIndex: u,
-          column: a,
+          column: c,
           columnIndex: h,
-          field: a?.field ?? "",
-          value: E?.[a?.field] ?? null,
+          field: c?.field ?? "",
+          value: E?.[c?.field] ?? null,
           isHeader: !1,
-          event: r
+          event: l
         };
-      } else if (c) {
-        const u = parseInt(c.getAttribute("data-col") ?? "-1", 10), h = this.columns[u];
-        d = {
+      } else if (d) {
+        const u = parseInt(d.getAttribute("data-col") ?? "-1", 10), h = this.columns[u];
+        a = {
           row: null,
           rowIndex: -1,
           column: h,
@@ -355,20 +442,20 @@ class H extends I {
           field: h?.field ?? "",
           value: null,
           isHeader: !0,
-          event: r
+          event: l
         };
       } else
         return;
-      this.params = d, this.position = { x: r.clientX, y: r.clientY };
-      const l = w(this.config.items ?? x, d);
-      l.length && (this.menuElement && this.menuElement.remove(), this.menuElement = v(
-        l,
-        d,
+      this.params = a, this.position = { x: l.clientX, y: l.clientY };
+      const s = v(this.config.items ?? w, a);
+      s.length && (this.menuElement && this.menuElement.remove(), this.menuElement = x(
+        s,
+        a,
         (u) => {
-          u.action && u.action(d), this.menuElement?.remove(), this.menuElement = null, this.isOpen = !1;
+          u.action && u.action(a), this.menuElement?.remove(), this.menuElement = null, this.isOpen = !1;
         },
         this.gridIcons.submenuArrow
-      ), document.body.appendChild(this.menuElement), y(this.menuElement, r.clientX, r.clientY), this.isOpen = !0, this.emit("context-menu-open", { params: d, items: l }));
+      ), document.body.appendChild(this.menuElement), y(this.menuElement, l.clientX, l.clientY), this.isOpen = !0, this.emit("context-menu-open", { params: a, items: s }));
     }));
   }
   // #endregion
@@ -379,25 +466,25 @@ class H extends I {
    * @param y - Y coordinate
    * @param params - Partial context menu parameters
    */
-  showMenu(e, n, i) {
-    const r = {
-      row: i.row ?? null,
-      rowIndex: i.rowIndex ?? -1,
-      column: i.column ?? null,
-      columnIndex: i.columnIndex ?? -1,
-      field: i.field ?? "",
-      value: i.value ?? null,
-      isHeader: i.isHeader ?? !1,
-      event: i.event ?? new MouseEvent("contextmenu")
-    }, o = w(this.config.items ?? x, r);
-    this.menuElement && this.menuElement.remove(), this.menuElement = v(
+  showMenu(e, t, n) {
+    const l = {
+      row: n.row ?? null,
+      rowIndex: n.rowIndex ?? -1,
+      column: n.column ?? null,
+      columnIndex: n.columnIndex ?? -1,
+      field: n.field ?? "",
+      value: n.value ?? null,
+      isHeader: n.isHeader ?? !1,
+      event: n.event ?? new MouseEvent("contextmenu")
+    }, o = v(this.config.items ?? w, l);
+    this.menuElement && this.menuElement.remove(), this.menuElement = x(
       o,
-      r,
-      (t) => {
-        t.action && t.action(r), this.menuElement?.remove(), this.menuElement = null, this.isOpen = !1;
+      l,
+      (i) => {
+        i.action && i.action(l), this.menuElement?.remove(), this.menuElement = null, this.isOpen = !1;
       },
       this.gridIcons.submenuArrow
-    ), document.body.appendChild(this.menuElement), y(this.menuElement, e, n), this.isOpen = !0;
+    ), document.body.appendChild(this.menuElement), y(this.menuElement, e, t), this.isOpen = !0;
   }
   /**
    * Hide the context menu.