@toolbox-web/grid 0.4.0 → 0.4.2

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

@@ -11,9 +11,28 @@ const g = {
   /** Ask if a column can be moved. Context: ColumnConfig. Response: boolean | undefined */
   CAN_MOVE_COLUMN: "canMoveColumn"
 };
-class k {
-  /** 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 */
@@ -97,8 +116,16 @@ class k {
   /**
    * Emit a custom event from the grid.
    */
-  emit(t, s) {
-    this.grid?.dispatchEvent?.(new CustomEvent(t, { detail: s, 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 s = new CustomEvent(t, { detail: e, bubbles: !0, cancelable: !0 });
+    return this.grid?.dispatchEvent?.(s), s.defaultPrevented;
   }
   /**
    * Request a re-render of the grid.
@@ -106,6 +133,14 @@ class k {
   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.
@@ -139,6 +174,19 @@ class k {
   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.
    */
@@ -173,6 +221,51 @@ class k {
     const t = this.grid?.gridConfig?.icons ?? {};
     return { ...g, ...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(), s = parseInt(e, 10);
+      if (!isNaN(s)) return s;
+    }
+    return 200;
+  }
+  // #endregion
   /**
    * Resolve an icon value to string or HTMLElement.
    * Checks plugin config first, then grid-level icons, then defaults.
@@ -181,8 +274,8 @@ class k {
    * @param pluginOverride - Optional plugin-level override
    * @returns The resolved icon value
    */
-  resolveIcon(t, s) {
-    return s !== void 0 ? s : this.gridIcons[t];
+  resolveIcon(t, e) {
+    return e !== void 0 ? e : this.gridIcons[t];
   }
   /**
    * Set an icon value on an element.
@@ -191,8 +284,8 @@ class k {
    * @param element - The element to set the icon on
    * @param icon - The icon value (string or HTMLElement)
    */
-  setIcon(t, s) {
-    typeof s == "string" ? t.innerHTML = s : s instanceof HTMLElement && (t.innerHTML = "", t.appendChild(s.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.
@@ -205,48 +298,47 @@ class k {
 function p(n) {
   return n.filter((t) => t.sticky === "left");
 }
-function C(n) {
+function k(n) {
   return n.filter((t) => t.sticky === "right");
 }
 function a(n) {
   return n.some((t) => t.sticky === "left" || t.sticky === "right");
 }
-function h(n, t) {
-  const s = n.shadowRoot;
-  if (!s) return;
-  const e = Array.from(s.querySelectorAll(".header-row .cell"));
-  if (!e.length) return;
+function u(n, t) {
+  const e = n.shadowRoot;
+  if (!e) return;
+  const s = Array.from(e.querySelectorAll(".header-row .cell"));
+  if (!s.length) return;
   const c = /* @__PURE__ */ new Map();
   t.forEach((r, o) => {
     r.field && c.set(r.field, o);
   });
-  let d = 0;
+  let f = 0;
   for (const r of t)
     if (r.sticky === "left") {
-      const o = c.get(r.field), i = e.find((l) => l.getAttribute("data-field") === r.field);
-      i && (i.classList.add("sticky-left"), i.style.position = "sticky", i.style.left = d + "px", o !== void 0 && s.querySelectorAll(`.data-grid-row .cell[data-col="${o}"]`).forEach((l) => {
-        l.classList.add("sticky-left"), l.style.position = "sticky", l.style.left = d + "px";
-      }), d += i.offsetWidth);
+      const o = c.get(r.field), i = s.find((l) => l.getAttribute("data-field") === r.field);
+      i && (i.classList.add("sticky-left"), i.style.position = "sticky", i.style.left = f + "px", o !== void 0 && e.querySelectorAll(`.data-grid-row .cell[data-col="${o}"]`).forEach((l) => {
+        l.classList.add("sticky-left"), l.style.position = "sticky", l.style.left = f + "px";
+      }), f += i.offsetWidth);
     }
-  let f = 0;
+  let d = 0;
   for (const r of [...t].reverse())
     if (r.sticky === "right") {
-      const o = c.get(r.field), i = e.find((l) => l.getAttribute("data-field") === r.field);
-      i && (i.classList.add("sticky-right"), i.style.position = "sticky", i.style.right = f + "px", o !== void 0 && s.querySelectorAll(`.data-grid-row .cell[data-col="${o}"]`).forEach((l) => {
-        l.classList.add("sticky-right"), l.style.position = "sticky", l.style.right = f + "px";
-      }), f += i.offsetWidth);
+      const o = c.get(r.field), i = s.find((l) => l.getAttribute("data-field") === r.field);
+      i && (i.classList.add("sticky-right"), i.style.position = "sticky", i.style.right = d + "px", o !== void 0 && e.querySelectorAll(`.data-grid-row .cell[data-col="${o}"]`).forEach((l) => {
+        l.classList.add("sticky-right"), l.style.position = "sticky", l.style.right = d + "px";
+      }), d += i.offsetWidth);
     }
 }
-function u(n) {
+function h(n) {
   const t = n.shadowRoot;
   if (!t) return;
-  t.querySelectorAll(".sticky-left, .sticky-right").forEach((e) => {
-    e.classList.remove("sticky-left", "sticky-right"), e.style.position = "", e.style.left = "", e.style.right = "";
+  t.querySelectorAll(".sticky-left, .sticky-right").forEach((s) => {
+    s.classList.remove("sticky-left", "sticky-right"), s.style.position = "", s.style.left = "", s.style.right = "";
   });
 }
-class m extends k {
+class C extends m {
   name = "pinnedColumns";
-  version = "1.0.0";
   get defaultConfig() {
     return {};
   }
@@ -264,9 +356,9 @@ class m extends k {
   /**
    * Auto-detect sticky columns from column configuration.
    */
-  static detect(t, s) {
-    const e = s?.columns;
-    return Array.isArray(e) ? a(e) : !1;
+  static detect(t, e) {
+    const s = e?.columns;
+    return Array.isArray(s) ? a(s) : !1;
   }
   // #endregion
   // #region Hooks
@@ -276,13 +368,13 @@ class m extends k {
   afterRender() {
     if (!this.isApplied)
       return;
-    const t = this.grid, s = [...this.columns];
-    if (!a(s)) {
-      u(t), this.isApplied = !1;
+    const t = this.grid, e = [...this.columns];
+    if (!a(e)) {
+      h(t), this.isApplied = !1;
       return;
     }
     queueMicrotask(() => {
-      h(t, s);
+      u(t, e);
     });
   }
   /**
@@ -291,10 +383,10 @@ class m extends k {
   onPluginQuery(t) {
     switch (t.type) {
       case y.CAN_MOVE_COLUMN: {
-        const s = t.context, e = s.sticky;
-        if (e === "left" || e === "right")
+        const e = t.context, s = e.sticky;
+        if (s === "left" || s === "right")
           return !1;
-        const c = s.meta?.sticky;
+        const c = e.meta?.sticky;
         return c === "left" || c === "right" ? !1 : void 0;
       }
       default:
@@ -308,7 +400,7 @@ class m extends k {
    */
   refreshStickyOffsets() {
     const t = [...this.columns];
-    h(this.grid, t);
+    u(this.grid, t);
   }
   /**
    * Get columns pinned to the left.
@@ -322,41 +414,41 @@ class m extends k {
    */
   getRightPinnedColumns() {
     const t = [...this.columns];
-    return C(t);
+    return k(t);
   }
   /**
    * Clear all sticky positioning.
    */
   clearStickyPositions() {
-    u(this.grid);
+    h(this.grid);
   }
   /**
    * Report horizontal scroll boundary offsets for pinned columns.
    * Used by keyboard navigation to ensure focused cells aren't hidden behind sticky columns.
    */
-  getHorizontalScrollOffsets(t, s) {
+  getHorizontalScrollOffsets(t, e) {
     if (!this.isApplied)
       return;
-    let e = 0, c = 0;
+    let s = 0, c = 0;
     if (t) {
-      const f = t.querySelectorAll(".sticky-left"), r = t.querySelectorAll(".sticky-right");
-      f.forEach((o) => {
-        e += o.offsetWidth;
+      const d = t.querySelectorAll(".sticky-left"), r = t.querySelectorAll(".sticky-right");
+      d.forEach((o) => {
+        s += o.offsetWidth;
       }), r.forEach((o) => {
         c += o.offsetWidth;
       });
     } else {
       const r = this.grid.shadowRoot;
       r && r.querySelectorAll(".header-row .cell").forEach((i) => {
-        i.classList.contains("sticky-left") ? e += i.offsetWidth : i.classList.contains("sticky-right") && (c += i.offsetWidth);
+        i.classList.contains("sticky-left") ? s += i.offsetWidth : i.classList.contains("sticky-right") && (c += i.offsetWidth);
       });
     }
-    const d = s?.classList.contains("sticky-left") || s?.classList.contains("sticky-right");
-    return { left: e, right: c, skipScroll: d };
+    const f = e?.classList.contains("sticky-left") || e?.classList.contains("sticky-right");
+    return { left: s, right: c, skipScroll: f };
   }
   // #endregion
 }
 export {
-  m as PinnedColumnsPlugin
+  C as PinnedColumnsPlugin
 };
 //# sourceMappingURL=index.js.map