@toolbox-web/grid 0.4.0 → 0.4.2

package/lib/plugins/undo-redo/index.js

@@ -9,8 +9,27 @@ const d = {
   toolPanel: "☰"
 };
 class u {
-  /** 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 */
@@ -97,12 +116,28 @@ class u {
   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 r = new CustomEvent(t, { detail: e, 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.
@@ -136,6 +171,19 @@ class u {
   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 u {
     const t = this.grid?.gridConfig?.icons ?? {};
     return { ...d, ...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(), r = parseInt(e, 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.
@@ -209,7 +302,7 @@ function S(n, t, e) {
     // Clear redo on new action
   };
 }
-function a(n) {
+function c(n) {
   if (n.undoStack.length === 0)
     return { newState: n, action: null };
   const t = [...n.undoStack], e = t.pop();
@@ -236,10 +329,10 @@ function s(n) {
 function h(n) {
   return n.undoStack.length > 0;
 }
-function k(n) {
+function l(n) {
   return n.redoStack.length > 0;
 }
-function l() {
+function k() {
   return { undoStack: [], redoStack: [] };
 }
 function g(n, t, e, r) {
@@ -253,8 +346,15 @@ function g(n, t, e, r) {
   };
 }
 class f extends u {
+  /**
+   * Plugin dependencies - UndoRedoPlugin requires EditingPlugin to track edits.
+   *
+   * The EditingPlugin must be loaded BEFORE this plugin in the plugins array.
+   */
+  static dependencies = [
+    { name: "editing", required: !0, reason: "UndoRedoPlugin tracks cell edit history" }
+  ];
   name = "undoRedo";
-  version = "1.0.0";
   get defaultConfig() {
     return {
       maxHistorySize: 100
@@ -277,7 +377,7 @@ class f extends u {
   onKeyDown(t) {
     const e = (t.ctrlKey || t.metaKey) && t.key === "z" && !t.shiftKey, r = (t.ctrlKey || t.metaKey) && (t.key === "y" || t.key === "z" && t.shiftKey);
     if (e) {
-      const o = a({ undoStack: this.undoStack, redoStack: this.redoStack });
+      const o = c({ undoStack: this.undoStack, redoStack: this.redoStack });
       if (o.action) {
         const i = this.rows;
         i[o.action.rowIndex] && (i[o.action.rowIndex][o.action.field] = o.action.oldValue), this.undoStack = o.newState.undoStack, this.redoStack = o.newState.redoStack, this.emit("undo", {
@@ -311,12 +411,12 @@ class f extends u {
    * @param newValue - The value after the edit
    */
   recordEdit(t, e, r, o) {
-    const i = g(t, e, r, o), c = S(
+    const i = g(t, e, r, o), a = S(
       { undoStack: this.undoStack, redoStack: this.redoStack },
       i,
       this.config.maxHistorySize ?? 100
     );
-    this.undoStack = c.undoStack, this.redoStack = c.redoStack;
+    this.undoStack = a.undoStack, this.redoStack = a.redoStack;
   }
   /**
    * Programmatically undo the last action.
@@ -324,7 +424,7 @@ class f extends u {
    * @returns The undone action, or null if nothing to undo
    */
   undo() {
-    const t = a({ undoStack: this.undoStack, redoStack: this.redoStack });
+    const t = c({ undoStack: this.undoStack, redoStack: this.redoStack });
     if (t.action) {
       const e = this.rows;
       e[t.action.rowIndex] && (e[t.action.rowIndex][t.action.field] = t.action.oldValue), this.undoStack = t.newState.undoStack, this.redoStack = t.newState.redoStack, this.requestRender();
@@ -354,13 +454,13 @@ class f extends u {
    * Check if there are any actions that can be redone.
    */
   canRedo() {
-    return k({ undoStack: this.undoStack, redoStack: this.redoStack });
+    return l({ undoStack: this.undoStack, redoStack: this.redoStack });
   }
   /**
    * Clear all undo/redo history.
    */
   clearHistory() {
-    const t = l();
+    const t = k();
     this.undoStack = t.undoStack, this.redoStack = t.redoStack;
   }
   /**