@toolbox-web/grid 0.6.0 → 1.1.0

package/lib/plugins/visibility/VisibilityPlugin.d.ts

@@ -15,22 +15,104 @@ export interface ColumnReorderRequestDetail {
 /**
  * Column Visibility Plugin for tbw-grid
  *
- * @example
+ * Gives users control over which columns are displayed. Hide less important columns
+ * by default, let users toggle them via a column chooser UI, or programmatically
+ * show/hide columns based on user preferences or screen size.
+ *
+ * > **Optional Enhancement:** When ReorderPlugin is also loaded, columns in the
+ * > visibility panel become draggable for reordering.
+ *
+ * ## Installation
+ *
+ * ```ts
+ * import { VisibilityPlugin } from '@toolbox-web/grid/plugins/visibility';
+ * ```
+ *
+ * ## Configuration Options
+ *
+ * | Option | Type | Default | Description |
+ * |--------|------|---------|-------------|
+ * | `allowHideAll` | `boolean` | `false` | Allow hiding all columns (no minimum) |
+ *
+ * ## Column Configuration
+ *
+ * | Property | Type | Default | Description |
+ * |----------|------|---------|-------------|
+ * | `visible` | `boolean` | `true` | Initial visibility state |
+ * | `meta.lockVisibility` | `boolean` | `false` | Prevent user from toggling |
+ *
+ * ## Programmatic API
+ *
+ * | Method | Signature | Description |
+ * |--------|-----------|-------------|
+ * | `hideColumn` | `(field: string) => void` | Hide a column |
+ * | `showColumn` | `(field: string) => void` | Show a column |
+ * | `toggleColumn` | `(field: string) => void` | Toggle visibility |
+ * | `showAllColumns` | `() => void` | Show all columns |
+ * | `getHiddenColumns` | `() => string[]` | Get list of hidden column fields |
+ *
+ * ## CSS Custom Properties
+ *
+ * | Property | Default | Description |
+ * |----------|---------|-------------|
+ * | `--tbw-visibility-hover` | `var(--tbw-color-row-hover)` | Row hover background |
+ * | `--tbw-panel-padding` | `0.75em` | Panel content padding |
+ * | `--tbw-panel-gap` | `0.5em` | Gap between items |
+ *
+ * @example Columns Hidden by Default
  * ```ts
- * new VisibilityPlugin({ enabled: true, allowHideAll: false })
+ * import '@toolbox-web/grid';
+ * import { VisibilityPlugin } from '@toolbox-web/grid/plugins/visibility';
+ *
+ * const grid = document.querySelector('tbw-grid');
+ * grid.gridConfig = {
+ *   columns: [
+ *     { field: 'id', header: 'ID' },
+ *     { field: 'name', header: 'Name' },
+ *     { field: 'phone', header: 'Phone', visible: false }, // Hidden by default
+ *     { field: 'address', header: 'Address', visible: false },
+ *   ],
+ *   plugins: [new VisibilityPlugin()],
+ * };
+ *
+ * // Toggle programmatically
+ * const plugin = grid.getPlugin(VisibilityPlugin);
+ * plugin.showColumn('phone');
  * ```
+ *
+ * @example With Drag-to-Reorder
+ * ```ts
+ * import { VisibilityPlugin } from '@toolbox-web/grid/plugins/visibility';
+ * import { ReorderPlugin } from '@toolbox-web/grid/plugins/reorder';
+ *
+ * grid.gridConfig = {
+ *   plugins: [
+ *     new ReorderPlugin(),      // Enables drag-drop in visibility panel
+ *     new VisibilityPlugin(),
+ *   ],
+ * };
+ * ```
+ *
+ * @see {@link VisibilityConfig} for configuration options
+ * @see {@link ReorderPlugin} for drag-to-reorder integration
+ *
+ * @internal Extends BaseGridPlugin
  */
 export declare class VisibilityPlugin extends BaseGridPlugin<VisibilityConfig> {
     /**
      * Plugin dependencies - VisibilityPlugin optionally uses ReorderPlugin for drag-drop reordering.
      *
      * When ReorderPlugin is present, columns in the visibility panel become draggable.
+     * @internal
      */
     static readonly dependencies: PluginDependency[];
+    /** @internal */
     readonly name = "visibility";
     /** Tool panel ID for shell integration */
     static readonly PANEL_ID = "columns";
+    /** @internal */
     readonly styles: string;
+    /** @internal */
     protected get defaultConfig(): Partial<VisibilityConfig>;
     private columnListElement;
     private isDragging;
@@ -39,9 +121,11 @@ export declare class VisibilityPlugin extends BaseGridPlugin<VisibilityConfig> {
     private dropIndex;
     /** Clear drag-related classes from all rows in a list. */
     private clearDragClasses;
+    /** @internal */
     detach(): void;
     /**
      * Register the column visibility tool panel with the shell.
+     * @internal
      */
     getToolPanel(): ToolPanelDefinition | undefined;
     /**

package/lib/plugins/visibility/VisibilityPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VisibilityPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/visibility/VisibilityPlugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,KAAK,EAAgB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGhD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAWD;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,cAAc,CAAC,gBAAgB,CAAC;IACpE;;;;OAIG;IACH,gBAAyB,YAAY,EAAE,gBAAgB,EAAE,CAEvD;IAEF,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,0CAA0C;IAC1C,MAAM,CAAC,QAAQ,CAAC,QAAQ,aAAa;IACrC,SAAkB,MAAM,SAAU;IAElC,cAAuB,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAIhE;IAGD,OAAO,CAAC,iBAAiB,CAA4B;IAGrD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,SAAS,CAAuB;IAExC,0DAA0D;IAC1D,OAAO,CAAC,gBAAgB;IASf,MAAM,IAAI,IAAI;IAWvB;;OAEG;IACM,YAAY,IAAI,mBAAmB,GAAG,SAAS;IAcxD;;;OAGG;IACH,IAAI,IAAI,IAAI;IAQZ;;OAEG;IACH,IAAI,IAAI,IAAI;IAIZ;;OAEG;IACH,MAAM,IAAI,IAAI;IAQd;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIvC;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAIvD;;;OAGG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAO7B;;;OAGG;IACH,gBAAgB,IAAI,MAAM,EAAE;IAO5B;;;OAGG;IACH,OAAO,IAAI,IAAI;IAIf;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;OAIG;IACH,aAAa,IAAI,KAAK,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IAIF;;;OAGG;IACH,cAAc,IAAI,OAAO;IAOzB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAoC1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA4DtB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAqF3B"}
+{"version":3,"file":"VisibilityPlugin.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/visibility/VisibilityPlugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,KAAK,EAAgB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGhD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,qBAAa,gBAAiB,SAAQ,cAAc,CAAC,gBAAgB,CAAC;IACpE;;;;;OAKG;IACH,gBAAyB,YAAY,EAAE,gBAAgB,EAAE,CAEvD;IAEF,gBAAgB;IAChB,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,0CAA0C;IAC1C,MAAM,CAAC,QAAQ,CAAC,QAAQ,aAAa;IACrC,gBAAgB;IAChB,SAAkB,MAAM,SAAU;IAElC,gBAAgB;IAChB,cAAuB,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAIhE;IAGD,OAAO,CAAC,iBAAiB,CAA4B;IAGrD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,SAAS,CAAuB;IAExC,0DAA0D;IAC1D,OAAO,CAAC,gBAAgB;IASxB,gBAAgB;IACP,MAAM,IAAI,IAAI;IAWvB;;;OAGG;IACM,YAAY,IAAI,mBAAmB,GAAG,SAAS;IAcxD;;;OAGG;IACH,IAAI,IAAI,IAAI;IAQZ;;OAEG;IACH,IAAI,IAAI,IAAI;IAIZ;;OAEG;IACH,MAAM,IAAI,IAAI;IAQd;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIvC;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAIvD;;;OAGG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAO7B;;;OAGG;IACH,gBAAgB,IAAI,MAAM,EAAE;IAO5B;;;OAGG;IACH,OAAO,IAAI,IAAI;IAIf;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;OAIG;IACH,aAAa,IAAI,KAAK,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IAIF;;;OAGG;IACH,cAAc,IAAI,OAAO;IAOzB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAoC1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA4DtB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAqF3B"}

package/lib/plugins/visibility/index.d.ts

@@ -1,6 +1,8 @@
 /**
  * Visibility Plugin Entry Point
  * Re-exports plugin class and types for tree-shakeable imports.
+ *
+ * @module Plugins/Visibility
  */
 export type { VisibilityConfig } from './types';
 export { VisibilityPlugin } from './VisibilityPlugin';

package/lib/plugins/visibility/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/visibility/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../libs/grid/src/lib/plugins/visibility/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC"}

package/lib/plugins/visibility/index.js

@@ -25,6 +25,28 @@ class w {
    * ```
    */
   static dependencies;
+  /**
+   * Plugin manifest - declares owned properties, config rules, and hook priorities.
+   *
+   * This is read by the configuration validator to:
+   * - Validate that required plugins are loaded when their properties are used
+   * - Execute configRules to detect invalid/conflicting settings
+   * - Order hook execution based on priority
+   *
+   * @example
+   * ```typescript
+   * static override readonly manifest: PluginManifest<MyConfig> = {
+   *   ownedProperties: [
+   *     { property: 'myProp', level: 'column', description: 'the "myProp" column property' },
+   *   ],
+   *   configRules: [
+   *     { id: 'myPlugin/conflict', severity: 'warn', message: '...', check: (c) => c.a && c.b },
+   *   ],
+   * };
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static manifest;
   /**
    * Plugin version - defaults to grid version for built-in plugins.
    * Third-party plugins can override with their own semver.
@@ -184,23 +206,6 @@ class w {
   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.gridElement;
-  }
   /**
    * Get the disconnect signal for event listener cleanup.
    * This signal is aborted when the grid disconnects from the DOM.
@@ -313,14 +318,18 @@ class g extends w {
    * Plugin dependencies - VisibilityPlugin optionally uses ReorderPlugin for drag-drop reordering.
    *
    * When ReorderPlugin is present, columns in the visibility panel become draggable.
+   * @internal
    */
   static dependencies = [
     { name: "reorder", required: !1, reason: "Enables drag-to-reorder columns in visibility panel" }
   ];
+  /** @internal */
   name = "visibility";
   /** Tool panel ID for shell integration */
   static PANEL_ID = "columns";
+  /** @internal */
   styles = C;
+  /** @internal */
   get defaultConfig() {
     return {
       allowHideAll: !1
@@ -341,6 +350,7 @@ class g extends w {
   }
   // #endregion
   // #region Lifecycle
+  /** @internal */
   detach() {
     this.columnListElement = null, this.isDragging = !1, this.draggedField = null, this.draggedIndex = null, this.dropIndex = null;
   }
@@ -348,6 +358,7 @@ class g extends w {
   // #region Shell Integration
   /**
    * Register the column visibility tool panel with the shell.
+   * @internal
    */
   getToolPanel() {
     return {