@toolbox-web/grid 0.4.0 → 0.4.2

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

@@ -9,8 +9,27 @@ const C = {
   toolPanel: "☰"
 };
 class I {
-  /** Plugin version - override in subclass if needed */
-  version = "1.0.0";
+  /**
+   * 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 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.
@@ -103,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.
@@ -136,6 +171,19 @@ class I {
   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.
    */
@@ -170,6 +218,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.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 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.
@@ -188,8 +281,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.
@@ -201,54 +294,54 @@ class I {
 }
 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)));
+  return (typeof s == "function" ? s(e) : s).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 v(s, e, n, i = C.submenuArrow) {
-  const r = document.createElement("div");
-  r.className = "tbw-context-menu", r.setAttribute("role", "menu");
+function v(s, e, t, n = C.submenuArrow) {
+  const l = document.createElement("div");
+  l.className = "tbw-context-menu", l.setAttribute("role", "menu");
   for (const o of s) {
     if (o.separator) {
-      const l = document.createElement("div");
-      l.className = "tbw-context-menu-separator", l.setAttribute("role", "separator"), r.appendChild(l);
+      const r = document.createElement("div");
+      r.className = "tbw-context-menu-separator", r.setAttribute("role", "separator"), l.appendChild(r);
       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 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 a = M(o, e);
-    if (a && (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);
+    if (a && (i.classList.add("disabled"), i.setAttribute("aria-disabled", "true")), o.icon) {
+      const r = document.createElement("span");
+      r.className = "tbw-context-menu-icon", r.innerHTML = o.icon, i.appendChild(r);
     }
     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);
+    if (d.className = "tbw-context-menu-label", d.textContent = o.name, i.appendChild(d), o.shortcut) {
+      const r = document.createElement("span");
+      r.className = "tbw-context-menu-shortcut", r.textContent = o.shortcut, i.appendChild(r);
     }
     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), c = v(h, e, n, i);
-        c.classList.add("tbw-context-submenu"), c.style.position = "absolute", c.style.left = "100%", c.style.top = "0", t.style.position = "relative", t.appendChild(c);
-      }), t.addEventListener("mouseleave", () => {
-        const u = t.querySelector(".tbw-context-menu");
+      const r = document.createElement("span");
+      r.className = "tbw-context-menu-arrow", typeof n == "string" ? r.innerHTML = n : n instanceof HTMLElement && r.appendChild(n.cloneNode(!0)), i.appendChild(r), i.addEventListener("mouseenter", () => {
+        if (i.querySelector(".tbw-context-menu") || !o.subMenu) return;
+        const h = w(o.subMenu, e), c = v(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();
       });
     }
-    !a && o.action && !o.subMenu && t.addEventListener("click", (l) => {
-      l.stopPropagation(), n(o);
-    }), r.appendChild(t);
+    !a && o.action && !o.subMenu && i.addEventListener("click", (r) => {
+      r.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, a = n;
-  e + i.width > r && (t = e - i.width), n + i.height > o && (a = n - i.height), t = Math.max(0, t), a = Math.max(0, a), s.style.left = `${t}px`, s.style.top = `${a}px`, s.style.visibility = "visible";
+function y(s, e, t) {
+  s.style.position = "fixed", s.style.left = `${e}px`, s.style.top = `${t}px`, s.style.visibility = "hidden", s.style.zIndex = "10000";
+  const n = s.getBoundingClientRect(), l = window.innerWidth, o = window.innerHeight;
+  let i = e, a = t;
+  e + n.width > l && (i = e - n.width), t + n.height > o && (a = t - n.height), i = Math.max(0, i), a = Math.max(0, a), s.style.left = `${i}px`, s.style.top = `${a}px`, s.style.visibility = "visible";
 }
 let f = null, p = null, m = null, b = 0;
 const x = [
@@ -269,9 +362,8 @@ const x = [
     }
   }
 ];
-class H extends I {
+class R extends I {
   name = "contextMenu";
-  version = "1.0.0";
   get defaultConfig() {
     return {
       items: x
@@ -294,9 +386,9 @@ 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.querySelectorAll(".tbw-context-menu").forEach((t) => t.remove());
     }, document.addEventListener("click", f)), p || (p = (e) => {
-      e.key === "Escape" && document.querySelectorAll(".tbw-context-menu").forEach((i) => i.remove());
+      e.key === "Escape" && document.querySelectorAll(".tbw-context-menu").forEach((n) => n.remove());
     }, document.addEventListener("keydown", p));
   }
   /**
@@ -311,14 +403,14 @@ class H extends I {
   afterRender() {
     const e = this.shadowRoot;
     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]"), a = o.closest(".header-cell");
+    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]"), a = 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), c = this.columns[h], E = this.rows[u];
+      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];
         d = {
           row: E,
           rowIndex: u,
@@ -327,7 +419,7 @@ class H extends I {
           field: c?.field ?? "",
           value: E?.[c?.field] ?? null,
           isHeader: !1,
-          event: r
+          event: l
         };
       } else if (a) {
         const u = parseInt(a.getAttribute("data-col") ?? "-1", 10), h = this.columns[u];
@@ -339,20 +431,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,
+      this.params = d, this.position = { x: l.clientX, y: l.clientY };
+      const r = w(this.config.items ?? x, d);
+      r.length && (this.menuElement && this.menuElement.remove(), this.menuElement = v(
+        r,
         d,
         (u) => {
           u.action && u.action(d), 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: d, items: r }));
     }));
   }
   // #endregion
@@ -363,25 +455,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);
+  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 = w(this.config.items ?? x, l);
     this.menuElement && this.menuElement.remove(), this.menuElement = v(
       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.
@@ -400,6 +492,6 @@ class H extends I {
   // Styles are injected globally via installGlobalHandlers() since menu renders in document.body
 }
 export {
-  H as ContextMenuPlugin
+  R as ContextMenuPlugin
 };
 //# sourceMappingURL=index.js.map