@toolbox-web/grid 0.4.0 → 0.4.2

package/lib/plugins/clipboard/types.d.ts

@@ -1,8 +1,25 @@
+import { GridElement } from '../../core/plugin/base-plugin';
 /**
- * Clipboard Plugin Types
+ * Custom paste handler function.
  *
- * Type definitions for clipboard copy/paste functionality.
+ * @param detail - The parsed paste data with target and field info
+ * @param grid - The grid element to update
+ * @returns `false` to prevent the default paste behavior, or `void`/`true` to allow it
+ *
+ * @example
+ * ```ts
+ * // Custom handler that validates before pasting
+ * new ClipboardPlugin({
+ *   pasteHandler: (detail, grid) => {
+ *     if (!detail.target) return false;
+ *     // Apply custom validation/transformation...
+ *     applyPasteData(detail, grid);
+ *     return false; // We handled it, skip default
+ *   }
+ * })
+ * ```
  */
+export type PasteHandler = (detail: PasteDetail, grid: GridElement) => boolean | void;
 /** Configuration options for the clipboard plugin */
 export interface ClipboardConfig {
     /** Include column headers in copied text (default: false) */
@@ -15,6 +32,17 @@ export interface ClipboardConfig {
     quoteStrings?: boolean;
     /** Custom cell value processor for copy operations */
     processCell?: (value: unknown, field: string, row: unknown) => string;
+    /**
+     * Custom paste handler. By default, the plugin applies pasted data to `grid.rows`
+     * starting at the target cell.
+     *
+     * - Set to a custom function to handle paste yourself
+     * - Set to `null` to disable auto-paste (event still fires)
+     * - Return `false` from handler to prevent default behavior
+     *
+     * @default defaultPasteHandler (auto-applies paste data)
+     */
+    pasteHandler?: PasteHandler | null;
 }
 /** Internal state managed by the clipboard plugin */
 export interface ClipboardState {
@@ -30,11 +58,53 @@ export interface CopyDetail {
     /** Number of columns copied */
     columnCount: number;
 }
+/** Target cell coordinates and bounds for paste operations */
+export interface PasteTarget {
+    /** Target row index (top-left of paste area) */
+    row: number;
+    /** Target column index (top-left of paste area) */
+    col: number;
+    /** Target column field name (for easy data mapping) */
+    field: string;
+    /**
+     * Selection bounds that constrain the paste area.
+     * If set, paste data will be clipped to fit within these bounds.
+     * If null, paste expands freely from the target cell.
+     */
+    bounds: {
+        /** End row index (inclusive) */
+        endRow: number;
+        /** End column index (inclusive) */
+        endCol: number;
+    } | null;
+}
 /** Event detail emitted after a paste operation */
 export interface PasteDetail {
     /** Parsed rows from clipboard (2D array of cell values) */
     rows: string[][];
     /** Raw text that was pasted */
     text: string;
+    /** The target cell where paste starts (top-left of paste area). Null if no cell is selected. */
+    target: PasteTarget | null;
+    /**
+     * Column fields for each column in the paste range, starting from target.col.
+     * Useful for mapping parsed cell values to data fields.
+     * Length matches the width of the pasted data (or available columns, whichever is smaller).
+     */
+    fields: string[];
 }
+/**
+ * Default paste handler that applies pasted data to grid.rows.
+ *
+ * This is the built-in handler used when no custom `pasteHandler` is configured.
+ * It clones the rows array for immutability and applies values starting at the target cell.
+ *
+ * Behavior:
+ * - Single cell selection: paste expands freely, adds new rows if needed
+ * - Range/row selection: paste is clipped to fit within selection bounds
+ *
+ * @param detail - The parsed paste data from clipboard
+ * @param grid - The grid element to update
+ */
+export declare function defaultPasteHandler(detail: PasteDetail, grid: GridElement): void;
 //# sourceMappingURL=types.d.ts.map

package/lib/plugins/clipboard/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/clipboard/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sDAAsD;IACtD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;CACvE;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;IACjB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/clipboard/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,GAAG,IAAI,CAAC;AAEtF,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sDAAsD;IACtD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACtE;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CACpC;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,EAAE;QACN,gCAAgC;QAChC,MAAM,EAAE,MAAM,CAAC;QACf,mCAAmC;QACnC,MAAM,EAAE,MAAM,CAAC;KAChB,GAAG,IAAI,CAAC;CACV;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;IACjB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAiDhF"}

package/lib/plugins/column-virtualization/ColumnVirtualizationPlugin.d.ts

@@ -11,7 +11,6 @@ import { ColumnVirtualizationConfig } from './types';
  */
 export declare class ColumnVirtualizationPlugin extends BaseGridPlugin<ColumnVirtualizationConfig> {
     readonly name = "columnVirtualization";
-    readonly version = "1.0.0";
     protected get defaultConfig(): Partial<ColumnVirtualizationConfig>;
     private isVirtualized;
     private startCol;

package/lib/plugins/column-virtualization/ColumnVirtualizationPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ColumnVirtualizationPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/column-virtualization/ColumnVirtualizationPlugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQrD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,cAAc,CAAC,0BAA0B,CAAC;IACxF,QAAQ,CAAC,IAAI,0BAA0B;IACvC,SAAkB,OAAO,WAAW;IAEpC,cAAuB,aAAa,IAAI,OAAO,CAAC,0BAA0B,CAAC,CAM1E;IAGD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,aAAa,CAAgB;IAK5B,MAAM,CAAC,IAAI,EAAE,OAAO,+BAA+B,EAAE,WAAW,GAAG,IAAI;IAWvE,MAAM,IAAI,IAAI;IAad,cAAc,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,EAAE;IAgChE,WAAW,IAAI,IAAI;IA2BnB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAiB3C;;OAEG;IACH,gBAAgB,IAAI,OAAO;IAI3B;;OAEG;IACH,qBAAqB,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;IAIvD;;;OAGG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAOzC;;;OAGG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAI5C;;OAEG;IACH,aAAa,IAAI,MAAM;CAIxB"}
+{"version":3,"file":"ColumnVirtualizationPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/column-virtualization/ColumnVirtualizationPlugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQrD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,cAAc,CAAC,0BAA0B,CAAC;IACxF,QAAQ,CAAC,IAAI,0BAA0B;IAEvC,cAAuB,aAAa,IAAI,OAAO,CAAC,0BAA0B,CAAC,CAM1E;IAGD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,aAAa,CAAgB;IAK5B,MAAM,CAAC,IAAI,EAAE,OAAO,+BAA+B,EAAE,WAAW,GAAG,IAAI;IAWvE,MAAM,IAAI,IAAI;IAad,cAAc,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,EAAE;IAgChE,WAAW,IAAI,IAAI;IA2BnB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAiB3C;;OAEG;IACH,gBAAgB,IAAI,OAAO;IAI3B;;OAEG;IACH,qBAAqB,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;IAIvD;;;OAGG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAOzC;;;OAGG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAI5C;;OAEG;IACH,aAAa,IAAI,MAAM;CAIxB"}

package/lib/plugins/column-virtualization/index.js

@@ -1,4 +1,4 @@
-const m = {
+const C = {
   expand: "▶",
   collapse: "▼",
   sortAsc: "▲",
@@ -8,9 +8,28 @@ const m = {
   dragHandle: "⋮⋮",
   toolPanel: "☰"
 };
-class w {
-  /** Plugin version - override in subclass if needed */
-  version = "1.0.0";
+class b {
+  /**
+   * 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 w {
   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 i = new CustomEvent(t, { detail: e, bubbles: !0, cancelable: !0 });
+    return this.grid?.dispatchEvent?.(i), i.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 w {
   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.
    */
@@ -168,8 +216,53 @@ class w {
    */
   get gridIcons() {
     const t = this.grid?.gridConfig?.icons ?? {};
-    return { ...m, ...t };
+    return { ...C, ...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(), i = parseInt(e, 10);
+      if (!isNaN(i)) return i;
+    }
+    return 200;
+  }
+  // #endregion
   /**
    * Resolve an icon value to string or HTMLElement.
    * Checks plugin config first, then grid-level icons, then defaults.
@@ -200,7 +293,7 @@ class w {
   // #endregion
 }
 const d = 100;
-function u(s) {
+function a(s) {
   if (s == null)
     return d;
   if (typeof s == "number")
@@ -209,40 +302,40 @@ function u(s) {
   return isNaN(t) ? d : t;
 }
 function c(s) {
-  return s.map((t) => u(t.width));
+  return s.map((t) => a(t.width));
 }
 function f(s) {
   const t = [];
   let e = 0;
   for (const i of s)
-    t.push(e), e += u(i.width);
+    t.push(e), e += a(i.width);
   return t;
 }
 function g(s) {
-  return s.reduce((t, e) => t + u(e.width), 0);
+  return s.reduce((t, e) => t + a(e.width), 0);
 }
 function p(s, t, e, i, o) {
   const r = e.length;
   if (r === 0)
     return { startCol: 0, endCol: 0, visibleColumns: [] };
-  let n = b(s, e, i);
+  let n = w(s, e, i);
   n = Math.max(0, n - o);
-  const C = s + t;
-  let h = n;
+  const m = s + t;
+  let u = n;
   for (let l = n; l < r; l++) {
-    if (e[l] >= C) {
-      h = l - 1;
+    if (e[l] >= m) {
+      u = l - 1;
       break;
     }
-    h = l;
+    u = l;
   }
-  h = Math.min(r - 1, h + o);
-  const a = [];
-  for (let l = n; l <= h; l++)
-    a.push(l);
-  return { startCol: n, endCol: h, visibleColumns: a };
+  u = Math.min(r - 1, u + o);
+  const h = [];
+  for (let l = n; l <= u; l++)
+    h.push(l);
+  return { startCol: n, endCol: u, visibleColumns: h };
 }
-function b(s, t, e) {
+function w(s, t, e) {
   let i = 0, o = t.length - 1;
   for (; i < o; ) {
     const r = Math.floor((i + o) / 2);
@@ -253,9 +346,8 @@ function b(s, t, e) {
 function R(s, t, e) {
   return e ? s > t : !1;
 }
-class W extends w {
+class v extends b {
   name = "columnVirtualization";
-  version = "1.0.0";
   get defaultConfig() {
     return {
       autoEnable: !0,
@@ -348,6 +440,6 @@ class W extends w {
   // #endregion
 }
 export {
-  W as ColumnVirtualizationPlugin
+  v as ColumnVirtualizationPlugin
 };
 //# sourceMappingURL=index.js.map