@toolbox-web/grid 1.21.2 → 1.22.1

package/lib/plugins/print/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../../../libs/grid/src/lib/plugins/print/print-isolated.ts","../../../../../../libs/grid/src/lib/core/types.ts","../../../../../../libs/grid/src/lib/core/plugin/base-plugin.ts","../../../../../../libs/grid/src/lib/plugins/print/PrintPlugin.ts"],"sourcesContent":["/**\n * Utility for printing a grid in isolation by hiding all other page content.\n *\n * This approach keeps the grid in place (with virtualization disabled by PrintPlugin)\n * and uses CSS to hide everything else on the page during printing.\n */\n\nimport type { PrintOrientation } from './types';\n\nexport interface PrintIsolatedOptions {\n  /** Page orientation hint */\n  orientation?: PrintOrientation;\n}\n\n/** ID for the isolation stylesheet */\nconst ISOLATION_STYLE_ID = 'tbw-print-isolation-style';\n\n/**\n * Create a stylesheet that hides everything except the target grid.\n * Uses the grid's ID to target it specifically.\n */\nfunction createIsolationStylesheet(gridId: string, orientation: PrintOrientation): HTMLStyleElement {\n  const style = document.createElement('style');\n  style.id = ISOLATION_STYLE_ID;\n  style.textContent = `\n    /* Print isolation: hide everything except the target grid */\n    @media print {\n      /* Hide all body children by default */\n      body > *:not(#${gridId}) {\n        display: none !important;\n      }\n\n      /* But show the grid and ensure it's not hidden by ancestor rules */\n      #${gridId} {\n        display: block !important;\n        position: static !important;\n        visibility: visible !important;\n        opacity: 1 !important;\n        overflow: visible !important;\n        height: auto !important;\n        width: 100% !important;\n        max-height: none !important;\n        margin: 0 !important;\n        padding: 0 !important;\n        transform: none !important;\n      }\n\n      /* If grid is nested, we need to show its ancestors too */\n      #${gridId},\n      #${gridId} * {\n        visibility: visible !important;\n      }\n\n      /* Walk up the DOM and show all ancestors of the grid */\n      body *:has(> #${gridId}),\n      body *:has(#${gridId}) {\n        display: block !important;\n        visibility: visible !important;\n        opacity: 1 !important;\n        overflow: visible !important;\n        height: auto !important;\n        position: static !important;\n        transform: none !important;\n        background: transparent !important;\n        border: none !important;\n        padding: 0 !important;\n        margin: 0 !important;\n      }\n\n      /* Hide siblings of ancestors (everything that's not in the path to the grid) */\n      body *:has(#${gridId}) > *:not(:has(#${gridId})):not(#${gridId}) {\n        display: none !important;\n      }\n\n      /* Page settings */\n      @page {\n        size: ${orientation};\n        margin: 1cm;\n      }\n\n      /* Ensure proper print styling */\n      body {\n        margin: 0 !important;\n        padding: 0 !important;\n        background: white !important;\n        color-scheme: light !important;\n      }\n    }\n\n    /* Screen: also apply isolation for print preview */\n    @media screen {\n      /* When this stylesheet is active, we're about to print */\n      /* No screen-specific rules needed - isolation only applies to print */\n    }\n  `;\n  return style;\n}\n\n/**\n * Print a grid in isolation by hiding all other page content.\n *\n * This function adds a temporary stylesheet that uses CSS to hide everything\n * on the page except the target grid during printing. The grid stays in place\n * with all its data (virtualization should be disabled separately).\n *\n * @param gridElement - The tbw-grid element to print (must have an ID)\n * @param options - Optional configuration\n * @returns Promise that resolves when the print dialog closes\n *\n * @example\n * ```typescript\n * import { printGridIsolated } from '@toolbox-web/grid/plugins/print';\n *\n * const grid = document.querySelector('tbw-grid');\n * await printGridIsolated(grid, { orientation: 'landscape' });\n * ```\n */\nexport async function printGridIsolated(gridElement: HTMLElement, options: PrintIsolatedOptions = {}): Promise<void> {\n  const { orientation = 'landscape' } = options;\n\n  const gridId = gridElement.id;\n\n  // Warn if multiple elements share this ID (user-set IDs could collide)\n  const elementsWithId = document.querySelectorAll(`#${CSS.escape(gridId)}`);\n  if (elementsWithId.length > 1) {\n    console.warn(\n      `[tbw-grid:print] Multiple elements found with id=\"${gridId}\". ` +\n        `Print isolation may not work correctly. Ensure each grid has a unique ID.`,\n    );\n  }\n\n  // Remove any existing isolation stylesheet\n  document.getElementById(ISOLATION_STYLE_ID)?.remove();\n\n  // Add the isolation stylesheet\n  const isolationStyle = createIsolationStylesheet(gridId, orientation);\n  document.head.appendChild(isolationStyle);\n\n  return new Promise((resolve) => {\n    // Listen for afterprint event to cleanup\n    const onAfterPrint = () => {\n      window.removeEventListener('afterprint', onAfterPrint);\n      // Remove isolation stylesheet\n      document.getElementById(ISOLATION_STYLE_ID)?.remove();\n      resolve();\n    };\n    window.addEventListener('afterprint', onAfterPrint);\n\n    // Trigger print\n    window.print();\n\n    // Fallback timeout in case afterprint doesn't fire (some browsers)\n    setTimeout(() => {\n      window.removeEventListener('afterprint', onAfterPrint);\n      document.getElementById(ISOLATION_STYLE_ID)?.remove();\n      resolve();\n    }, 5000);\n  });\n}\n","import type { RowPosition } from './internal/virtualization';\nimport type { PluginQuery } from './plugin/base-plugin';\nimport type { AfterCellRenderContext, AfterRowRenderContext, CellMouseEvent } from './plugin/types';\n\n/**\n * Position entry for a single row in the position cache.\n * Part of variable row height virtualization.\n *\n * Re-exported from position-cache.ts for public API consistency.\n *\n * @see VirtualState.positionCache\n * @category Plugin Development\n */\nexport type RowPositionEntry = RowPosition;\n\n// #region DataGridElement Interface\n/**\n * The compiled web component interface for DataGrid.\n *\n * This interface represents the `<tbw-grid>` custom element, combining\n * the public grid API with standard HTMLElement functionality.\n *\n * @example\n * ```typescript\n * // Query existing grid\n * const grid = document.querySelector('tbw-grid') as DataGridElement<Employee>;\n * grid.rows = employees;\n * grid.addEventListener('cell-click', (e) => console.log(e.detail));\n *\n * // Create grid programmatically\n * import { createGrid } from '@toolbox-web/grid';\n * const grid = createGrid<Employee>({\n *   columns: [{ field: 'name' }, { field: 'email' }],\n * });\n * document.body.appendChild(grid);\n * ```\n *\n * @see {@link PublicGrid} for the public API methods and properties\n * @see {@link createGrid} for typed grid creation\n * @see {@link queryGrid} for typed grid querying\n */\nexport interface DataGridElement extends PublicGrid, HTMLElement {}\n// #endregion\n\n// #region PublicGrid Interface\n/**\n * Public API interface for DataGrid component.\n *\n * **Property Getters vs Setters:**\n *\n * Property getters return the EFFECTIVE (resolved) value after merging all config sources.\n * This is the \"current situation\" - what consumers and plugins need to know.\n *\n * Property setters accept input values which are merged into the effective config.\n * Multiple sources can contribute (gridConfig, columns prop, light DOM, individual props).\n *\n * For example:\n * - `grid.fitMode` returns the resolved fitMode (e.g., 'stretch' even if you set undefined)\n * - `grid.columns` returns the effective columns after merging\n * - `grid.gridConfig` returns the full effective config\n */\nexport interface PublicGrid<T = any> {\n  /**\n   * Full config object. Setter merges with other inputs per precedence rules.\n   * Getter returns the effective (resolved) config.\n   */\n  gridConfig?: GridConfig<T>;\n  /**\n   * Column definitions.\n   * Getter returns effective columns (after merging config, light DOM, inference).\n   */\n  columns?: ColumnConfig<T>[];\n  /** Current row data (after plugin processing like grouping, filtering). */\n  rows?: T[];\n  /** Insert a row at a visible index, bypassing the sort/filter pipeline. Auto-animates by default. */\n  insertRow?(index: number, row: T, animate?: boolean): Promise<void>;\n  /** Remove a row at a visible index, bypassing the sort/filter pipeline. Auto-animates by default. */\n  removeRow?(index: number, animate?: boolean): Promise<T | undefined>;\n  /** Resolves once the component has finished initial work (layout, inference). */\n  ready?: () => Promise<void>;\n  /** Force a layout / measurement pass (e.g. after container resize). */\n  forceLayout?: () => Promise<void>;\n  /** Return effective resolved config (after inference & precedence). */\n  getConfig?: () => Promise<Readonly<GridConfig<T>>>;\n  /** Toggle expansion state of a group row by its generated key. */\n  toggleGroup?: (key: string) => Promise<void>;\n\n  // Custom Styles API\n  /**\n   * Register custom CSS styles to be injected into the grid.\n   * Use this to style custom cell renderers, editors, or detail panels.\n   * @param id - Unique identifier for the style block (for removal/updates)\n   * @param css - CSS string to inject\n   */\n  registerStyles?: (id: string, css: string) => void;\n  /**\n   * Remove previously registered custom styles.\n   * @param id - The ID used when registering the styles\n   */\n  unregisterStyles?: (id: string) => void;\n  /**\n   * Get list of registered custom style IDs.\n   */\n  getRegisteredStyles?: () => string[];\n\n  // Plugin API\n  /**\n   * Get a plugin instance by its class.\n   *\n   * @example\n   * ```typescript\n   * const selection = grid.getPlugin(SelectionPlugin);\n   * if (selection) {\n   *   selection.selectAll();\n   * }\n   * ```\n   */\n  getPlugin?<P>(PluginClass: new (...args: any[]) => P): P | undefined;\n  /**\n   * Get a plugin instance by its name.\n   * Prefer `getPlugin(PluginClass)` for type safety.\n   */\n  getPluginByName?(name: string): GridPlugin | undefined;\n\n  // Shell API\n  /**\n   * Re-render the shell header (title, column groups, toolbar).\n   * Call this after dynamically adding/removing tool panels or toolbar buttons.\n   */\n  refreshShellHeader?(): void;\n  /**\n   * Register a custom tool panel in the sidebar.\n   *\n   * @example\n   * ```typescript\n   * grid.registerToolPanel({\n   *   id: 'analytics',\n   *   title: 'Analytics',\n   *   icon: '📊',\n   *   render: (container) => {\n   *     container.innerHTML = '<div>Charts here...</div>';\n   *   }\n   * });\n   * ```\n   */\n  registerToolPanel?(panel: ToolPanelDefinition): void;\n  /**\n   * Unregister a previously registered tool panel.\n   */\n  unregisterToolPanel?(panelId: string): void;\n  /**\n   * Open the tool panel sidebar.\n   */\n  openToolPanel?(): void;\n  /**\n   * Close the tool panel sidebar.\n   */\n  closeToolPanel?(): void;\n  /**\n   * Toggle the tool panel sidebar open or closed.\n   */\n  toggleToolPanel?(): void;\n  /**\n   * Toggle an accordion section expanded or collapsed within the tool panel.\n   * @param sectionId - The ID of the section to toggle\n   */\n  toggleToolPanelSection?(sectionId: string): void;\n\n  // State Persistence API\n  /**\n   * Get the current column state including order, width, visibility, and sort.\n   * Use for persisting user preferences to localStorage or a backend.\n   *\n   * @example\n   * ```typescript\n   * const state = grid.getColumnState();\n   * localStorage.setItem('gridState', JSON.stringify(state));\n   * ```\n   */\n  getColumnState?(): GridColumnState;\n  /**\n   * Set/restore the column state.\n   * Can be set before or after grid initialization.\n   *\n   * @example\n   * ```typescript\n   * const saved = localStorage.getItem('gridState');\n   * if (saved) {\n   *   grid.columnState = JSON.parse(saved);\n   * }\n   * ```\n   */\n  columnState?: GridColumnState;\n\n  // Loading API\n  /**\n   * Whether the grid is currently in a loading state.\n   * When true, displays a loading overlay with spinner.\n   *\n   * Can also be set via the `loading` HTML attribute.\n   *\n   * @example\n   * ```typescript\n   * // Show loading overlay\n   * grid.loading = true;\n   * const data = await fetchData();\n   * grid.rows = data;\n   * grid.loading = false;\n   * ```\n   */\n  loading?: boolean;\n\n  /**\n   * Set loading state for a specific row.\n   * Displays a small spinner indicator on the row.\n   *\n   * Use when persisting row data or performing row-level async operations.\n   *\n   * @param rowId - The row's unique identifier (from getRowId)\n   * @param loading - Whether the row is loading\n   *\n   * @example\n   * ```typescript\n   * // Show loading while saving row\n   * grid.setRowLoading('emp-123', true);\n   * await saveRow(row);\n   * grid.setRowLoading('emp-123', false);\n   * ```\n   */\n  setRowLoading?(rowId: string, loading: boolean): void;\n\n  /**\n   * Set loading state for a specific cell.\n   * Displays a small spinner indicator on the cell.\n   *\n   * Use when performing cell-level async operations (e.g., validation, lookup).\n   *\n   * @param rowId - The row's unique identifier (from getRowId)\n   * @param field - The column field\n   * @param loading - Whether the cell is loading\n   *\n   * @example\n   * ```typescript\n   * // Show loading while validating cell\n   * grid.setCellLoading('emp-123', 'email', true);\n   * const isValid = await validateEmail(email);\n   * grid.setCellLoading('emp-123', 'email', false);\n   * ```\n   */\n  setCellLoading?(rowId: string, field: string, loading: boolean): void;\n\n  /**\n   * Check if a row is currently in loading state.\n   * @param rowId - The row's unique identifier\n   */\n  isRowLoading?(rowId: string): boolean;\n\n  /**\n   * Check if a cell is currently in loading state.\n   * @param rowId - The row's unique identifier\n   * @param field - The column field\n   */\n  isCellLoading?(rowId: string, field: string): boolean;\n\n  /**\n   * Clear all row and cell loading states.\n   */\n  clearAllLoading?(): void;\n}\n// #endregion\n\n// #region InternalGrid Interface\n/**\n * Internal-only augmented interface for DataGrid component.\n *\n * Member prefixes indicate accessibility:\n * - `_underscore` = protected members - private outside core, accessible to plugins. Marked with @internal.\n * - `__doubleUnderscore` = deeply internal members - private outside core, only for internal functions.\n *\n * @category Plugin Development\n */\nexport interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {\n  // Element methods available because DataGridElement extends HTMLElement\n  querySelector<K extends keyof HTMLElementTagNameMap>(selectors: K): HTMLElementTagNameMap[K] | null;\n  querySelector<E extends Element = Element>(selectors: string): E | null;\n  querySelectorAll<K extends keyof HTMLElementTagNameMap>(selectors: K): NodeListOf<HTMLElementTagNameMap[K]>;\n  querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>;\n  _rows: T[];\n  _columns: ColumnInternal<T>[];\n  /** Visible columns only (excludes hidden). Use for rendering. */\n  _visibleColumns: ColumnInternal<T>[];\n  _headerRowEl: HTMLElement;\n  _bodyEl: HTMLElement;\n  _rowPool: RowElementInternal[];\n  _resizeController: ResizeController;\n  _sortState: { field: string; direction: 1 | -1 } | null;\n  /** Original unfiltered/unprocessed rows. @internal */\n  sourceRows: T[];\n  /** Framework adapter instance (set by Grid directives). @internal */\n  __frameworkAdapter?: FrameworkAdapter;\n  __originalOrder: T[];\n  __rowRenderEpoch: number;\n  __didInitialAutoSize?: boolean;\n  __lightDomColumnsCache?: ColumnInternal[];\n  __originalColumnNodes?: HTMLElement[];\n  /** Cell display value cache. @internal */\n  __cellDisplayCache?: Map<number, string[]>;\n  /** Cache epoch for cell display values. @internal */\n  __cellCacheEpoch?: number;\n  /** Cached header row count for virtualization. @internal */\n  __cachedHeaderRowCount?: number;\n  /** Cached flag for whether grid has special columns (custom renderers, etc.). @internal */\n  __hasSpecialColumns?: boolean;\n  /** Cached flag for whether any plugin has renderRow hooks. @internal */\n  __hasRenderRowPlugins?: boolean;\n  _gridTemplate: string;\n  _virtualization: VirtualState;\n  _focusRow: number;\n  _focusCol: number;\n  /** Currently active edit row index. Injected by EditingPlugin. @internal */\n  _activeEditRows?: number;\n  /** Whether the grid is in 'grid' editing mode (all rows editable). Injected by EditingPlugin. @internal */\n  _isGridEditMode?: boolean;\n  /** Snapshots of row data before editing. Injected by EditingPlugin. @internal */\n  _rowEditSnapshots?: Map<number, T>;\n  /** Get all changed rows. Injected by EditingPlugin. */\n  changedRows?: T[];\n  /** Get IDs of all changed rows. Injected by EditingPlugin. */\n  changedRowIds?: string[];\n  effectiveConfig?: GridConfig<T>;\n  findHeaderRow?: () => HTMLElement;\n  refreshVirtualWindow: (full: boolean, skipAfterRender?: boolean) => boolean;\n  updateTemplate?: () => void;\n  findRenderedRowElement?: (rowIndex: number) => HTMLElement | null;\n  /** Get a row by its ID. Implemented in grid.ts */\n  getRow?: (id: string) => T | undefined;\n  /** Get a row and its current index by ID. Returns undefined if not found. @internal */\n  _getRowEntry: (id: string) => { row: T; index: number } | undefined;\n  /** Get the unique ID for a row. Implemented in grid.ts */\n  getRowId?: (row: T) => string;\n  /** Update a row by ID. Implemented in grid.ts */\n  updateRow?: (id: string, changes: Partial<T>, source?: UpdateSource) => void;\n  /** Animate a single row. Returns Promise that resolves when animation completes. Implemented in grid.ts */\n  animateRow?: (rowIndex: number, type: RowAnimationType) => Promise<boolean>;\n  /** Animate multiple rows. Returns Promise that resolves when all animations complete. Implemented in grid.ts */\n  animateRows?: (rowIndices: number[], type: RowAnimationType) => Promise<number>;\n  /** Animate a row by its ID. Returns Promise that resolves when animation completes. Implemented in grid.ts */\n  animateRowById?: (rowId: string, type: RowAnimationType) => Promise<boolean>;\n  /** Begin bulk edit on a row. Injected by EditingPlugin. */\n  beginBulkEdit?: (rowIndex: number) => void;\n  /** Commit active row edit. Injected by EditingPlugin. */\n  commitActiveRowEdit?: () => void;\n  /** Dispatch cell click to plugin system, returns true if handled */\n  _dispatchCellClick?: (event: MouseEvent, rowIndex: number, colIndex: number, cellEl: HTMLElement) => boolean;\n  /** Dispatch row click to plugin system, returns true if handled */\n  _dispatchRowClick?: (event: MouseEvent, rowIndex: number, row: any, rowEl: HTMLElement) => boolean;\n  /** Dispatch header click to plugin system, returns true if handled */\n  _dispatchHeaderClick?: (event: MouseEvent, col: ColumnConfig, headerEl: HTMLElement) => boolean;\n  /** Dispatch keydown to plugin system, returns true if handled */\n  _dispatchKeyDown?: (event: KeyboardEvent) => boolean;\n  /** Dispatch cell mouse events for drag operations. Returns true if any plugin started a drag. */\n  _dispatchCellMouseDown?: (event: CellMouseEvent) => boolean;\n  /** Dispatch cell mouse move during drag. */\n  _dispatchCellMouseMove?: (event: CellMouseEvent) => void;\n  /** Dispatch cell mouse up to end drag. */\n  _dispatchCellMouseUp?: (event: CellMouseEvent) => void;\n  /** Call afterCellRender hook on all plugins. Called from rows.ts after each cell is rendered. @internal */\n  _afterCellRender?: (context: AfterCellRenderContext<T>) => void;\n  /** Check if any plugin has registered an afterCellRender hook. Used to skip hook call for performance. @internal */\n  _hasAfterCellRenderHook?: () => boolean;\n  /** Call afterRowRender hook on all plugins. Called from rows.ts after each row is rendered. @internal */\n  _afterRowRender?: (context: AfterRowRenderContext<T>) => void;\n  /** Check if any plugin has registered an afterRowRender hook. Used to skip hook call for performance. @internal */\n  _hasAfterRowRenderHook?: () => boolean;\n  /** Get horizontal scroll boundary offsets from plugins */\n  _getHorizontalScrollOffsets?: (\n    rowEl?: HTMLElement,\n    focusedCell?: HTMLElement,\n  ) => { left: number; right: number; skipScroll?: boolean };\n  /** Query all plugins with a generic query and collect responses */\n  queryPlugins?: <T>(query: PluginQuery) => T[];\n  /** Request emission of column-state-change event (debounced) */\n  requestStateChange?: () => void;\n}\n// #endregion\n\n// #region Column Types\n/**\n * Built-in primitive column types with automatic formatting and editing support.\n *\n * - `'string'` - Text content, default text input editor\n * - `'number'` - Numeric content, right-aligned, number input editor\n * - `'date'` - Date content, formatted display, date picker editor\n * - `'boolean'` - True/false, rendered as checkbox\n * - `'select'` - Dropdown selection from `options` array\n *\n * @example\n * ```typescript\n * columns: [\n *   { field: 'name', type: 'string' },\n *   { field: 'age', type: 'number' },\n *   { field: 'hireDate', type: 'date' },\n *   { field: 'active', type: 'boolean' },\n *   { field: 'department', type: 'select', options: [\n *     { label: 'Engineering', value: 'eng' },\n *     { label: 'Sales', value: 'sales' },\n *   ]},\n * ]\n * ```\n *\n * @see {@link ColumnType} for custom type support\n * @see {@link TypeDefault} for type-level defaults\n */\nexport type PrimitiveColumnType = 'number' | 'string' | 'date' | 'boolean' | 'select';\n\n/**\n * Column type - built-in primitives or custom type strings.\n *\n * Use built-in types for automatic formatting, or define custom types\n * (e.g., 'currency', 'country') with type-level defaults via `typeDefaults`.\n *\n * @example\n * ```typescript\n * // Built-in types\n * { field: 'name', type: 'string' }\n * { field: 'salary', type: 'number' }\n *\n * // Custom types with defaults\n * grid.gridConfig = {\n *   columns: [\n *     { field: 'salary', type: 'currency' },\n *     { field: 'birthCountry', type: 'country' },\n *   ],\n *   typeDefaults: {\n *     currency: {\n *       format: (v) => `$${Number(v).toFixed(2)}`,\n *     },\n *     country: {\n *       renderer: (ctx) => `🌍 ${ctx.value}`,\n *     },\n *   },\n * };\n * ```\n *\n * @see {@link PrimitiveColumnType} for built-in types\n * @see {@link TypeDefault} for defining custom type defaults\n */\nexport type ColumnType = PrimitiveColumnType | (string & {});\n// #endregion\n\n// #region TypeDefault Interface\n/**\n * Type-level defaults for formatters and renderers.\n * Applied to all columns of a given type unless overridden at column level.\n *\n * Note: `editor` and `editorParams` are added via module augmentation when\n * EditingPlugin is imported. `filterPanelRenderer` is added by FilteringPlugin.\n *\n * @example\n * ```typescript\n * typeDefaults: {\n *   currency: {\n *     format: (value) => new Intl.NumberFormat('en-US', {\n *       style: 'currency',\n *       currency: 'USD',\n *     }).format(value as number),\n *   },\n *   country: {\n *     renderer: (ctx) => {\n *       const span = document.createElement('span');\n *       span.innerHTML = `<img src=\"/flags/${ctx.value}.svg\" /> ${ctx.value}`;\n *       return span;\n *     }\n *   }\n * }\n * ```\n *\n * @see {@link ColumnViewRenderer} for custom renderer function signature\n * @see {@link ColumnType} for type strings that can have defaults\n * @see {@link GridConfig.typeDefaults} for registering type defaults\n */\nexport interface TypeDefault<TRow = unknown> {\n  /**\n   * Default formatter for all columns of this type.\n   *\n   * Transforms the raw cell value into a display string. Use when you need\n   * consistent formatting across columns without custom DOM (e.g., currency,\n   * percentages, dates with specific locale).\n   *\n   * **Resolution Priority**: Column `format` → Type `format` → Built-in\n   *\n   * @example\n   * ```typescript\n   * typeDefaults: {\n   *   currency: {\n   *     format: (value) => new Intl.NumberFormat('en-US', {\n   *       style: 'currency',\n   *       currency: 'USD',\n   *     }).format(value as number),\n   *   },\n   *   percentage: {\n   *     format: (value) => `${(value as number * 100).toFixed(1)}%`,\n   *   }\n   * }\n   * ```\n   */\n  format?: (value: unknown, row: TRow) => string;\n\n  /**\n   * Default renderer for all columns of this type.\n   *\n   * Creates custom DOM for the cell content. Use when you need more than\n   * text formatting (e.g., icons, badges, interactive elements).\n   *\n   * **Resolution Priority**: Column `renderer` → Type `renderer` → App-level (adapter) → Built-in\n   *\n   * @example\n   * ```typescript\n   * typeDefaults: {\n   *   status: {\n   *     renderer: (ctx) => {\n   *       const badge = document.createElement('span');\n   *       badge.className = `badge badge-${ctx.value}`;\n   *       badge.textContent = ctx.value as string;\n   *       return badge;\n   *     }\n   *   },\n   *   country: {\n   *     renderer: (ctx) => {\n   *       const span = document.createElement('span');\n   *       span.innerHTML = `<img src=\"/flags/${ctx.value}.svg\" /> ${ctx.value}`;\n   *       return span;\n   *     }\n   *   }\n   * }\n   * ```\n   */\n  renderer?: ColumnViewRenderer<TRow, unknown>;\n}\n// #endregion\n\n// #region BaseColumnConfig Interface\n/**\n * Base contract for a column configuration.\n *\n * Defines the fundamental properties all columns share. Extended by {@link ColumnConfig}\n * with additional features like custom renderers and grouping.\n *\n * @example\n * ```typescript\n * // Basic column with common properties\n * const columns: BaseColumnConfig<Employee>[] = [\n *   {\n *     field: 'name',\n *     header: 'Full Name',\n *     sortable: true,\n *     resizable: true,\n *   },\n *   {\n *     field: 'salary',\n *     type: 'number',\n *     width: 120,\n *     format: (value) => `$${value.toLocaleString()}`,\n *     sortComparator: (a, b) => a - b,\n *   },\n *   {\n *     field: 'department',\n *     type: 'select',\n *     options: [\n *       { label: 'Engineering', value: 'eng' },\n *       { label: 'Sales', value: 'sales' },\n *     ],\n *   },\n * ];\n * ```\n *\n * @see {@link ColumnConfig} for full column configuration with renderers\n * @see {@link ColumnType} for type options\n */\nexport interface BaseColumnConfig<TRow = any, TValue = any> {\n  /** Unique field key referencing property in row objects */\n  field: keyof TRow & string;\n  /** Visible header label; defaults to capitalized field */\n  header?: string;\n  /**\n   * Column data type.\n   *\n   * Built-in types: `'string'`, `'number'`, `'date'`, `'boolean'`, `'select'`\n   *\n   * Custom types (e.g., `'currency'`, `'country'`) can have type-level defaults\n   * via `gridConfig.typeDefaults` or framework adapter registries.\n   *\n   * @default Inferred from first row data\n   */\n  type?: ColumnType;\n  /** Column width in pixels; fixed size (no flexibility) */\n  width?: string | number;\n  /** Minimum column width in pixels (stretch mode only); when set, column uses minmax(minWidth, 1fr) */\n  minWidth?: number;\n  /** Whether column can be sorted */\n  sortable?: boolean;\n  /** Whether column can be resized by user */\n  resizable?: boolean;\n  /** Optional custom comparator for sorting (a,b) -> number */\n  sortComparator?: (a: TValue, b: TValue, rowA: TRow, rowB: TRow) => number;\n  /** For select type - available options */\n  options?: Array<{ label: string; value: unknown }> | (() => Array<{ label: string; value: unknown }>);\n  /** For select - allow multi select */\n  multi?: boolean;\n  /**\n   * Formats the raw cell value into a display string.\n   *\n   * Used both for **cell rendering** and the **built-in filter panel**:\n   * - In cells, the formatted value replaces the raw value as text content.\n   * - In the filter panel (set filter), checkbox labels show the formatted value\n   *   instead of the raw value, and search matches against the formatted text.\n   *\n   * The `row` parameter is available during cell rendering but is `undefined`\n   * when called from the filter panel (standalone value formatting). Avoid\n   * accessing `row` properties in format functions intended for filter display.\n   *\n   * @example\n   * ```typescript\n   * // Currency formatter — works in both cells and filter panel\n   * {\n   *   field: 'price',\n   *   format: (value) => `$${Number(value).toFixed(2)}`,\n   * }\n   *\n   * // ID-to-name lookup — filter panel shows names, not IDs\n   * {\n   *   field: 'departmentId',\n   *   format: (value) => departmentMap.get(value as string) ?? String(value),\n   * }\n   * ```\n   */\n  format?: (value: TValue, row: TRow) => string;\n  /** Arbitrary extra metadata */\n  meta?: Record<string, unknown>;\n}\n// #endregion\n\n// #region ColumnConfig Interface\n/**\n * Full column configuration including custom renderers, editors, and grouping metadata.\n *\n * Extends {@link BaseColumnConfig} with additional features for customizing\n * how cells are displayed and edited.\n *\n * @example\n * ```typescript\n * const columns: ColumnConfig<Employee>[] = [\n *   // Basic sortable column\n *   { field: 'id', header: 'ID', width: 60, sortable: true },\n *\n *   // Column with custom renderer\n *   {\n *     field: 'name',\n *     header: 'Employee',\n *     renderer: (ctx) => {\n *       const div = document.createElement('div');\n *       div.innerHTML = `<img src=\"${ctx.row.avatar}\" /><span>${ctx.value}</span>`;\n *       return div;\n *     },\n *   },\n *\n *   // Column with custom header\n *   {\n *     field: 'email',\n *     headerLabelRenderer: (ctx) => `${ctx.value} 📧`,\n *   },\n *\n *   // Editable column (requires EditingPlugin)\n *   {\n *     field: 'status',\n *     editable: true,\n *     editor: (ctx) => {\n *       const select = document.createElement('select');\n *       // ... editor implementation\n *       return select;\n *     },\n *   },\n *\n *   // Hidden column (can be shown via VisibilityPlugin)\n *   { field: 'internalNotes', hidden: true },\n * ];\n * ```\n *\n * @see {@link BaseColumnConfig} for basic column properties\n * @see {@link ColumnViewRenderer} for custom cell renderers\n * @see {@link ColumnEditorSpec} for custom cell editors\n * @see {@link HeaderRenderer} for custom header renderers\n */\nexport interface ColumnConfig<TRow = any> extends BaseColumnConfig<TRow, any> {\n  /**\n   * Optional custom cell renderer function. Alias for `viewRenderer`.\n   * Can return an HTMLElement, a Node, or an HTML string (which will be sanitized).\n   *\n   * @example\n   * ```typescript\n   * // Simple string template\n   * renderer: (ctx) => `<span class=\"badge\">${ctx.value}</span>`\n   *\n   * // DOM element\n   * renderer: (ctx) => {\n   *   const el = document.createElement('span');\n   *   el.textContent = ctx.value;\n   *   return el;\n   * }\n   * ```\n   */\n  renderer?: ColumnViewRenderer<TRow, any>;\n  /** Optional custom view renderer used instead of default text rendering */\n  viewRenderer?: ColumnViewRenderer<TRow, any>;\n  /** External view spec (lets host app mount any framework component) */\n  externalView?: {\n    component: unknown;\n    props?: Record<string, unknown>;\n    mount?: (options: {\n      placeholder: HTMLElement;\n      context: CellRenderContext<TRow, unknown>;\n      spec: unknown;\n    }) => void | { dispose?: () => void };\n  };\n  /** Whether the column is initially hidden */\n  hidden?: boolean;\n  /** Prevent this column from being hidden programmatically */\n  lockVisible?: boolean;\n  /**\n   * Dynamic CSS class(es) for cells in this column.\n   * Called for each cell during rendering. Return class names to add to the cell element.\n   *\n   * @example\n   * ```typescript\n   * // Highlight negative values\n   * cellClass: (value, row, column) => value < 0 ? ['negative', 'text-red'] : []\n   *\n   * // Status-based styling\n   * cellClass: (value) => [`status-${value}`]\n   * ```\n   */\n  cellClass?: (value: unknown, row: TRow, column: ColumnConfig<TRow>) => string[];\n\n  /**\n   * Custom header label renderer. Customize the label content while the grid\n   * handles sort icons, filter buttons, resize handles, and click interactions.\n   *\n   * Use this for simple customizations like adding icons, badges, or units.\n   *\n   * @example\n   * ```typescript\n   * // Add required field indicator\n   * headerLabelRenderer: (ctx) => `${ctx.value} <span class=\"required\">*</span>`\n   *\n   * // Add unit to header\n   * headerLabelRenderer: (ctx) => {\n   *   const span = document.createElement('span');\n   *   span.innerHTML = `${ctx.value}<br/><small>(kg)</small>`;\n   *   return span;\n   * }\n   * ```\n   */\n  headerLabelRenderer?: HeaderLabelRenderer<TRow>;\n\n  /**\n   * Custom header cell renderer. Complete control over the entire header cell.\n   * Resize handles are added automatically for resizable columns.\n   *\n   * The context provides helper functions to include standard elements:\n   * - `renderSortIcon()` - Returns sort indicator element (null if not sortable)\n   * - `renderFilterButton()` - Returns filter button (null if not filterable)\n   *\n   * **Precedence**: `headerRenderer` > `headerLabelRenderer` > `header` > `field`\n   *\n   * @example\n   * ```typescript\n   * headerRenderer: (ctx) => {\n   *   const div = document.createElement('div');\n   *   div.className = 'custom-header';\n   *   div.innerHTML = `<span>${ctx.value}</span>`;\n   *   const sortIcon = ctx.renderSortIcon();\n   *   if (sortIcon) div.appendChild(sortIcon);\n   *   return div;\n   * }\n   * ```\n   */\n  headerRenderer?: HeaderRenderer<TRow>;\n}\n// #endregion\n\n// #region ColumnConfigMap Type\n/**\n * Array of column configurations.\n * Convenience type alias for `ColumnConfig<TRow>[]`.\n *\n * @example\n * ```typescript\n * const columns: ColumnConfigMap<Employee> = [\n *   { field: 'name', header: 'Full Name', sortable: true },\n *   { field: 'email', header: 'Email Address' },\n *   { field: 'department', type: 'select', options: deptOptions },\n * ];\n *\n * grid.columns = columns;\n * ```\n *\n * @see {@link ColumnConfig} for individual column options\n * @see {@link GridConfig.columns} for setting columns on the grid\n */\nexport type ColumnConfigMap<TRow = any> = ColumnConfig<TRow>[];\n// #endregion\n\n// #region Editor Types\n/**\n * Editor specification for inline cell editing.\n * Supports multiple formats for maximum flexibility.\n *\n * **Format Options:**\n * - `string` - Custom element tag name (e.g., 'my-date-picker')\n * - `function` - Factory function returning an editor element\n * - `object` - External component spec for framework integration\n *\n * @example\n * ```typescript\n * // 1. Custom element tag name\n * columns: [\n *   { field: 'date', editor: 'my-date-picker' }\n * ]\n *\n * // 2. Factory function (full control)\n * columns: [\n *   {\n *     field: 'status',\n *     editor: (ctx) => {\n *       const select = document.createElement('select');\n *       select.innerHTML = `\n *         <option value=\"active\">Active</option>\n *         <option value=\"inactive\">Inactive</option>\n *       `;\n *       select.value = ctx.value;\n *       select.onchange = () => ctx.commit(select.value);\n *       select.onkeydown = (e) => {\n *         if (e.key === 'Escape') ctx.cancel();\n *       };\n *       return select;\n *     }\n *   }\n * ]\n *\n * // 3. External component (React, Angular, Vue)\n * columns: [\n *   {\n *     field: 'country',\n *     editor: {\n *       component: CountrySelect,\n *       props: { showFlags: true }\n *     }\n *   }\n * ]\n * ```\n *\n * @see {@link ColumnEditorContext} for the context passed to factory functions\n */\nexport type ColumnEditorSpec<TRow = unknown, TValue = unknown> =\n  | string // custom element tag name\n  | ((context: ColumnEditorContext<TRow, TValue>) => HTMLElement | string)\n  | {\n      /** Arbitrary component reference (class, function, token) */\n      component: unknown;\n      /** Optional static props passed to mount */\n      props?: Record<string, unknown>;\n      /** Optional custom mount function; if provided we call it directly instead of emitting an event */\n      mount?: (options: {\n        placeholder: HTMLElement;\n        context: ColumnEditorContext<TRow, TValue>;\n        spec: unknown;\n      }) => void | { dispose?: () => void };\n    };\n\n/**\n * Context object provided to editor factories allowing mutation (commit/cancel) of a cell value.\n *\n * The `commit` and `cancel` functions control the editing lifecycle:\n * - Call `commit(newValue)` to save changes and exit edit mode\n * - Call `cancel()` to discard changes and exit edit mode\n *\n * @example\n * ```typescript\n * const myEditor: ColumnEditorSpec = (ctx: ColumnEditorContext) => {\n *   const input = document.createElement('input');\n *   input.value = ctx.value;\n *   input.className = 'my-editor';\n *\n *   // Save on Enter, cancel on Escape\n *   input.onkeydown = (e) => {\n *     if (e.key === 'Enter') {\n *       ctx.commit(input.value);\n *     } else if (e.key === 'Escape') {\n *       ctx.cancel();\n *     }\n *   };\n *\n *   // Access row data for validation\n *   if (ctx.row.locked) {\n *     input.disabled = true;\n *   }\n *\n *   return input;\n * };\n * ```\n *\n * @see {@link ColumnEditorSpec} for editor specification options\n */\nexport interface ColumnEditorContext<TRow = any, TValue = any> {\n  /** Underlying full row object for the active edit. */\n  row: TRow;\n  /** Current cell value (mutable only via commit). */\n  value: TValue;\n  /** Field name being edited. */\n  field: keyof TRow & string;\n  /** Column configuration reference. */\n  column: ColumnConfig<TRow>;\n  /**\n   * Stable row identifier (from `getRowId`).\n   * Empty string if no `getRowId` is configured.\n   */\n  rowId: string;\n  /** Accept the edit; triggers change tracking + rerender. */\n  commit: (newValue: TValue) => void;\n  /** Abort edit without persisting changes. */\n  cancel: () => void;\n  /**\n   * Update other fields in this row while the editor is open.\n   * Changes are committed with source `'cascade'`, triggering\n   * `cell-change` events and `onValueChange` pushes to sibling editors.\n   *\n   * Useful for editors that affect multiple fields (e.g., an address\n   * lookup that sets city + zip + state).\n   *\n   * @example\n   * ```typescript\n   * // In a cell-commit listener:\n   * grid.addEventListener('cell-commit', (e) => {\n   *   if (e.detail.field === 'quantity') {\n   *     e.detail.updateRow({ total: e.detail.row.price * e.detail.value });\n   *   }\n   * });\n   * ```\n   */\n  updateRow: (changes: Partial<TRow>) => void;\n  /**\n   * Register a callback invoked when the cell's underlying value changes\n   * while the editor is open (e.g., via `updateRow()` from another cell's commit).\n   *\n   * Built-in editors auto-update their input values. Custom/framework editors\n   * should use this to stay in sync with external mutations.\n   *\n   * @example\n   * ```typescript\n   * const editor = (ctx: ColumnEditorContext) => {\n   *   const input = document.createElement('input');\n   *   input.value = String(ctx.value);\n   *   ctx.onValueChange?.((newValue) => {\n   *     input.value = String(newValue);\n   *   });\n   *   return input;\n   * };\n   * ```\n   */\n  onValueChange?: (callback: (newValue: TValue) => void) => void;\n}\n// #endregion\n\n// #region Renderer Types\n/**\n * Context passed to custom view renderers (pure display – no commit helpers).\n *\n * Used by `viewRenderer` and `renderer` column properties to create\n * custom cell content. Return a DOM node or HTML string.\n *\n * @example\n * ```typescript\n * // Status badge renderer\n * const statusRenderer: ColumnViewRenderer = (ctx: CellRenderContext) => {\n *   const badge = document.createElement('span');\n *   badge.className = `badge badge-${ctx.value}`;\n *   badge.textContent = ctx.value;\n *   return badge;\n * };\n *\n * // Progress bar using row data\n * const progressRenderer: ColumnViewRenderer = (ctx) => {\n *   const bar = document.createElement('div');\n *   bar.className = 'progress-bar';\n *   bar.style.width = `${ctx.value}%`;\n *   bar.title = `${ctx.row.taskName}: ${ctx.value}%`;\n *   return bar;\n * };\n *\n * // Return HTML string (simpler, less performant)\n * const htmlRenderer: ColumnViewRenderer = (ctx) => {\n *   return `<strong>${ctx.value}</strong>`;\n * };\n * ```\n *\n * @see {@link ColumnViewRenderer} for the renderer function signature\n */\nexport interface CellRenderContext<TRow = any, TValue = any> {\n  /** Row object for the cell being rendered. */\n  row: TRow;\n  /** Value at field. */\n  value: TValue;\n  /** Field key. */\n  field: keyof TRow & string;\n  /** Column configuration reference. */\n  column: ColumnConfig<TRow>;\n  /**\n   * The cell DOM element being rendered into.\n   * Framework adapters can use this to cache per-cell state (e.g., React roots).\n   * @internal\n   */\n  cellEl?: HTMLElement;\n}\n\n/**\n * Custom view renderer function for cell content.\n *\n * Returns one of:\n * - `Node` - DOM element to display in the cell\n * - `string` - HTML string (parsed and inserted)\n * - `void | null` - Use default text rendering\n *\n * @example\n * ```typescript\n * // DOM element (recommended for interactivity)\n * const avatarRenderer: ColumnViewRenderer<Employee> = (ctx) => {\n *   const img = document.createElement('img');\n *   img.src = ctx.row.avatarUrl;\n *   img.alt = ctx.row.name;\n *   img.className = 'avatar';\n *   return img;\n * };\n *\n * // HTML string (simpler, good for static content)\n * const emailRenderer: ColumnViewRenderer = (ctx) => {\n *   return `<a href=\"mailto:${ctx.value}\">${ctx.value}</a>`;\n * };\n *\n * // Conditional rendering\n * const conditionalRenderer: ColumnViewRenderer = (ctx) => {\n *   if (!ctx.value) return null; // Use default\n *   return `<em>${ctx.value}</em>`;\n * };\n * ```\n *\n * @see {@link CellRenderContext} for available context properties\n */\nexport type ColumnViewRenderer<TRow = unknown, TValue = unknown> = (\n  ctx: CellRenderContext<TRow, TValue>,\n) => Node | string | void | null;\n// #endregion\n\n// #region Header Renderer Types\n/**\n * Context passed to `headerLabelRenderer` for customizing header label content.\n * The framework handles sort icons, filter buttons, resize handles, and click interactions.\n *\n * @example\n * ```typescript\n * headerLabelRenderer: (ctx) => {\n *   const span = document.createElement('span');\n *   span.innerHTML = `${ctx.value} <span class=\"required\">*</span>`;\n *   return span;\n * }\n * ```\n */\nexport interface HeaderLabelContext<TRow = unknown> {\n  /** Column configuration reference. */\n  column: ColumnConfig<TRow>;\n  /** The header text (from column.header or column.field). */\n  value: string;\n}\n\n/**\n * Context passed to `headerRenderer` for complete control over header cell content.\n * When using this, you control the header content. Resize handles are added automatically\n * for resizable columns.\n *\n * @example\n * ```typescript\n * headerRenderer: (ctx) => {\n *   const div = document.createElement('div');\n *   div.className = 'custom-header';\n *   div.innerHTML = `<span>${ctx.value}</span>`;\n *   // Optionally include sort icon\n *   const sortIcon = ctx.renderSortIcon();\n *   if (sortIcon) div.appendChild(sortIcon);\n *   return div;\n * }\n * ```\n */\nexport interface HeaderCellContext<TRow = unknown> {\n  /** Column configuration reference. */\n  column: ColumnConfig<TRow>;\n  /** The header text (from column.header or column.field). */\n  value: string;\n  /** Current sort state for this column. */\n  sortState: 'asc' | 'desc' | null;\n  /** Whether the column has an active filter. */\n  filterActive: boolean;\n  /** The header cell DOM element being rendered into. */\n  cellEl: HTMLElement;\n  /**\n   * Render the standard sort indicator icon.\n   * Returns null if column is not sortable.\n   */\n  renderSortIcon: () => HTMLElement | null;\n  /**\n   * Render the standard filter button.\n   * Returns null if FilteringPlugin is not active or column is not filterable.\n   * Note: The actual button is added by FilteringPlugin's afterRender hook.\n   */\n  renderFilterButton: () => HTMLElement | null;\n}\n\n/**\n * Header label renderer function type.\n * Customize the label while framework handles sort icons, filter buttons, resize handles.\n *\n * Use this for simple label customizations without taking over the entire header.\n * The grid automatically appends sort icons, filter buttons, and resize handles.\n *\n * @example\n * ```typescript\n * // Add required indicator\n * const requiredHeader: HeaderLabelRenderer = (ctx) => {\n *   return `${ctx.value} <span style=\"color: red;\">*</span>`;\n * };\n *\n * // Add unit suffix\n * const priceHeader: HeaderLabelRenderer = (ctx) => {\n *   const span = document.createElement('span');\n *   span.innerHTML = `${ctx.value} <small>(USD)</small>`;\n *   return span;\n * };\n *\n * // Column config usage\n * columns: [\n *   { field: 'name', headerLabelRenderer: requiredHeader },\n *   { field: 'price', headerLabelRenderer: priceHeader },\n * ]\n * ```\n *\n * @see {@link HeaderLabelContext} for context properties\n * @see {@link HeaderRenderer} for full header control\n */\nexport type HeaderLabelRenderer<TRow = unknown> = (ctx: HeaderLabelContext<TRow>) => Node | string | void | null;\n\n/**\n * Header cell renderer function type.\n * Full control over header cell content. User is responsible for all content and interactions.\n *\n * When using this, you have complete control but must manually include\n * sort icons, filter buttons, and resize handles using the helper functions.\n *\n * @example\n * ```typescript\n * // Custom header with all standard elements\n * const customHeader: HeaderRenderer = (ctx) => {\n *   const div = document.createElement('div');\n *   div.className = 'custom-header';\n *   div.innerHTML = `<span class=\"label\">${ctx.value}</span>`;\n *\n *   // Add sort icon (returns null if not sortable)\n *   const sortIcon = ctx.renderSortIcon();\n *   if (sortIcon) div.appendChild(sortIcon);\n *\n *   // Add filter button (returns null if not filterable)\n *   const filterBtn = ctx.renderFilterButton();\n *   if (filterBtn) div.appendChild(filterBtn);\n *\n *   // Resize handles are added automatically for resizable columns\n *   return div;\n * };\n *\n * // Minimal header (no sort/resize)\n * const minimalHeader: HeaderRenderer = (ctx) => {\n *   return `<div class=\"minimal\">${ctx.value}</div>`;\n * };\n *\n * // Column config usage\n * columns: [\n *   { field: 'name', headerRenderer: customHeader },\n * ]\n * ```\n *\n * @see {@link HeaderCellContext} for context properties and helper functions\n * @see {@link HeaderLabelRenderer} for simpler label-only customization\n */\nexport type HeaderRenderer<TRow = unknown> = (ctx: HeaderCellContext<TRow>) => Node | string | void | null;\n// #endregion\n\n// #region Framework Adapter Interface\n/**\n * Framework adapter interface for handling framework-specific component instantiation.\n * Allows framework libraries (Angular, React, Vue) to register handlers that convert\n * declarative light DOM elements into functional renderers/editors.\n *\n * @example\n * ```typescript\n * // In @toolbox-web/grid-angular\n * class AngularGridAdapter implements FrameworkAdapter {\n *   canHandle(element: HTMLElement): boolean {\n *     return element.tagName.startsWith('APP-');\n *   }\n *   createRenderer(element: HTMLElement): ColumnViewRenderer {\n *     return (ctx) => {\n *       // Angular-specific instantiation logic\n *       const componentRef = createComponent(...);\n *       componentRef.setInput('value', ctx.value);\n *       return componentRef.location.nativeElement;\n *     };\n *   }\n *   createEditor(element: HTMLElement): ColumnEditorSpec {\n *     return (ctx) => {\n *       // Angular-specific editor with commit/cancel\n *       const componentRef = createComponent(...);\n *       componentRef.setInput('value', ctx.value);\n *       // Subscribe to commit/cancel outputs\n *       return componentRef.location.nativeElement;\n *     };\n *   }\n * }\n *\n * // User registers adapter once in their app\n * GridElement.registerAdapter(new AngularGridAdapter(injector, appRef));\n * ```\n * @category Framework Adapters\n */\nexport interface FrameworkAdapter {\n  /**\n   * Determines if this adapter can handle the given element.\n   * Typically checks tag name, attributes, or other conventions.\n   */\n  canHandle(element: HTMLElement): boolean;\n\n  /**\n   * Creates a view renderer function from a light DOM element.\n   * The renderer receives cell context and returns DOM or string.\n   */\n  createRenderer<TRow = unknown, TValue = unknown>(element: HTMLElement): ColumnViewRenderer<TRow, TValue>;\n\n  /**\n   * Creates an editor spec from a light DOM element.\n   * The editor receives context with commit/cancel and returns DOM.\n   * Returns undefined if no editor template is registered, allowing the grid\n   * to use its default built-in editors.\n   */\n  createEditor<TRow = unknown, TValue = unknown>(element: HTMLElement): ColumnEditorSpec<TRow, TValue> | undefined;\n\n  /**\n   * Creates a tool panel renderer from a light DOM element.\n   * The renderer receives a container element and optionally returns a cleanup function.\n   */\n  createToolPanelRenderer?(element: HTMLElement): ((container: HTMLElement) => void | (() => void)) | undefined;\n\n  /**\n   * Gets type-level defaults from an application-level registry.\n   * Used by Angular's `GridTypeRegistry` and React's `GridTypeProvider`.\n   *\n   * @param type - The column type (e.g., 'date', 'currency', 'country')\n   * @returns Type defaults for renderer/editor, or undefined if not registered\n   */\n  getTypeDefault?<TRow = unknown>(type: string): TypeDefault<TRow> | undefined;\n\n  /**\n   * Called when a cell's content is about to be wiped (e.g., when exiting edit mode,\n   * scroll-recycling a row, or rebuilding a row).\n   *\n   * Framework adapters should use this to properly destroy cached views/components\n   * associated with the cell to prevent memory leaks.\n   *\n   * @param cellEl - The cell element whose content is being released\n   */\n  releaseCell?(cellEl: HTMLElement): void;\n\n  /**\n   * Unmount a specific framework container and free its resources.\n   *\n   * Called by the grid core (e.g., MasterDetailPlugin) when a container\n   * created by the adapter is about to be removed from the DOM.\n   * The adapter should destroy the associated framework instance\n   * (React root, Vue app, Angular view) and remove it from tracking arrays.\n   *\n   * @param container - The container element returned by a create* method\n   */\n  unmount?(container: HTMLElement): void;\n}\n// #endregion\n\n// #region Internal Types\n\n/**\n * Column internal properties used during light DOM parsing.\n * Stores attribute-based names before they're resolved to actual functions.\n * @internal\n */\nexport interface ColumnParsedAttributes {\n  /** Editor name from `editor` attribute (resolved later) */\n  __editorName?: string;\n  /** Renderer name from `renderer` attribute (resolved later) */\n  __rendererName?: string;\n}\n\n/**\n * Extended column config used internally.\n * Includes all internal properties needed during grid lifecycle.\n *\n * Plugin developers may need to access these when working with\n * column caching and compiled templates.\n *\n * @example\n * ```typescript\n * import type { ColumnInternal } from '@toolbox-web/grid';\n *\n * class MyPlugin extends BaseGridPlugin {\n *   afterRender(): void {\n *     // Access internal column properties\n *     const columns = this.columns as ColumnInternal[];\n *     for (const col of columns) {\n *       // Check if column was auto-sized\n *       if (col.__autoSized) {\n *         console.log(`${col.field} was auto-sized`);\n *       }\n *     }\n *   }\n * }\n * ```\n *\n * @see {@link ColumnConfig} for public column properties\n * @category Plugin Development\n * @internal\n */\nexport interface ColumnInternal<T = any> extends ColumnConfig<T>, ColumnParsedAttributes {\n  __autoSized?: boolean;\n  __userResized?: boolean;\n  __renderedWidth?: number;\n  /** Original configured width (for reset on double-click) */\n  __originalWidth?: number;\n  __viewTemplate?: HTMLElement;\n  __editorTemplate?: HTMLElement;\n  __headerTemplate?: HTMLElement;\n  __compiledView?: CompiledViewFunction<T>;\n  __compiledEditor?: (ctx: EditorExecContext<T>) => string;\n}\n\n/**\n * Row element with internal tracking properties.\n * Used during virtualization and row pooling.\n *\n * @category Plugin Development\n * @internal\n */\nexport interface RowElementInternal extends HTMLElement {\n  /** Epoch marker for row render invalidation */\n  __epoch?: number;\n  /** Reference to the row data object for change detection */\n  __rowDataRef?: unknown;\n  /** Count of cells currently in edit mode */\n  __editingCellCount?: number;\n  /** Flag indicating this is a custom-rendered row (group row, etc.) */\n  __isCustomRow?: boolean;\n}\n\n/**\n * Type-safe access to element.part API (DOMTokenList-like).\n * Used for CSS ::part styling support.\n * @internal\n */\nexport interface ElementWithPart {\n  part?: DOMTokenList;\n}\n\n/**\n * Compiled view function type with optional blocked flag.\n * The __blocked flag is set when a template contains unsafe expressions.\n *\n * @category Plugin Development\n * @internal\n */\nexport interface CompiledViewFunction<T = any> {\n  (ctx: CellContext<T>): string;\n  /** Set to true when template was blocked due to unsafe expressions */\n  __blocked?: boolean;\n}\n\n/**\n * Runtime cell context used internally for compiled template execution.\n *\n * Contains the minimal context needed to render a cell: the row data,\n * cell value, field name, and column configuration.\n *\n * @example\n * ```typescript\n * import type { CellContext, ColumnInternal } from '@toolbox-web/grid';\n *\n * // Used internally by compiled templates\n * const renderCell = (ctx: CellContext) => {\n *   return `<span title=\"${ctx.field}\">${ctx.value}</span>`;\n * };\n * ```\n *\n * @see {@link CellRenderContext} for public cell render context\n * @see {@link EditorExecContext} for editor context with commit/cancel\n * @category Plugin Development\n */\nexport interface CellContext<T = any> {\n  row: T;\n  value: unknown;\n  field: string;\n  column: ColumnInternal<T>;\n}\n\n/**\n * Internal editor execution context extending the generic cell context with commit helpers.\n *\n * Used internally by the editing system. For public editor APIs,\n * prefer using {@link ColumnEditorContext}.\n *\n * @example\n * ```typescript\n * import type { EditorExecContext } from '@toolbox-web/grid';\n *\n * // Internal editor template execution\n * const execEditor = (ctx: EditorExecContext) => {\n *   const input = document.createElement('input');\n *   input.value = String(ctx.value);\n *   input.onkeydown = (e) => {\n *     if (e.key === 'Enter') ctx.commit(input.value);\n *     if (e.key === 'Escape') ctx.cancel();\n *   };\n *   return input;\n * };\n * ```\n *\n * @see {@link ColumnEditorContext} for public editor context\n * @see {@link CellContext} for base cell context\n * @category Plugin Development\n */\nexport interface EditorExecContext<T = any> extends CellContext<T> {\n  commit: (newValue: unknown) => void;\n  cancel: () => void;\n}\n\n/**\n * Controller managing drag-based column resize lifecycle.\n *\n * Exposed internally for plugins that need to interact with resize behavior.\n *\n * @example\n * ```typescript\n * import type { ResizeController, InternalGrid } from '@toolbox-web/grid';\n *\n * class MyPlugin extends BaseGridPlugin {\n *   handleColumnAction(colIndex: number): void {\n *     const grid = this.grid as InternalGrid;\n *     const resizeCtrl = grid._resizeController;\n *\n *     // Check if resize is in progress\n *     if (resizeCtrl?.isResizing) {\n *       return; // Don't interfere\n *     }\n *\n *     // Reset column to configured width\n *     resizeCtrl?.resetColumn(colIndex);\n *   }\n * }\n * ```\n *\n * @see {@link ColumnResizeDetail} for resize event details\n * @category Plugin Development\n */\nexport interface ResizeController {\n  start: (e: MouseEvent, colIndex: number, cell: HTMLElement) => void;\n  /** Reset a column to its configured width (or auto-size if none configured). */\n  resetColumn: (colIndex: number) => void;\n  dispose: () => void;\n  /** True while a resize drag is in progress (used to suppress header click/sort). */\n  isResizing: boolean;\n}\n\n/**\n * Virtual window bookkeeping; modified in-place as scroll position changes.\n *\n * Tracks virtualization state for row rendering. The grid only renders\n * rows within the visible viewport window (start to end) plus overscan.\n *\n * @example\n * ```typescript\n * import type { VirtualState, InternalGrid } from '@toolbox-web/grid';\n *\n * class MyPlugin extends BaseGridPlugin {\n *   logVirtualWindow(): void {\n *     const grid = this.grid as InternalGrid;\n *     const vs = grid.virtualization;\n *\n *     console.log(`Row height: ${vs.rowHeight}px`);\n *     console.log(`Visible rows: ${vs.start} to ${vs.end}`);\n *     console.log(`Virtualization: ${vs.enabled ? 'on' : 'off'}`);\n *   }\n * }\n * ```\n *\n * @see {@link GridConfig.rowHeight} for configuring row height\n * @category Plugin Development\n */\nexport interface VirtualState {\n  enabled: boolean;\n  rowHeight: number;\n  /** Threshold for bypassing virtualization (renders all rows if totalRows <= bypassThreshold) */\n  bypassThreshold: number;\n  start: number;\n  end: number;\n  /** Faux scrollbar element that provides scroll events (AG Grid pattern) */\n  container: HTMLElement | null;\n  /** Rows viewport element for measuring visible area height */\n  viewportEl: HTMLElement | null;\n  /** Spacer element inside faux scrollbar for setting virtual height */\n  totalHeightEl: HTMLElement | null;\n\n  // --- Variable Row Height Support (Phase 1) ---\n\n  /**\n   * Position cache for variable row heights.\n   * Index-based array mapping row index → {offset, height, measured}.\n   * Rebuilt when row count changes (expand/collapse, filter).\n   * `null` when using uniform row heights (default).\n   */\n  positionCache: RowPositionEntry[] | null;\n\n  /**\n   * Height cache by row identity.\n   * Persists row heights across position cache rebuilds.\n   * Uses dual storage: Map for string keys (rowId, __rowCacheKey) and WeakMap for object refs.\n   */\n  heightCache: {\n    /** Heights keyed by string (synthetic rows with __rowCacheKey, or rowId-keyed rows) */\n    byKey: Map<string, number>;\n    /** Heights keyed by object reference (data rows without rowId) */\n    byRef: WeakMap<object, number>;\n  };\n\n  /** Running average of measured row heights. Used for estimating unmeasured rows. */\n  averageHeight: number;\n\n  /** Number of rows that have been measured. */\n  measuredCount: number;\n\n  /** Whether variable row height mode is active (rowHeight is a function). */\n  variableHeights: boolean;\n\n  // --- Cached Geometry (avoid forced layout reads on scroll hot path) ---\n\n  /** Cached viewport element height. Updated by ResizeObserver and force-refresh only. */\n  cachedViewportHeight: number;\n\n  /** Cached faux scrollbar element height. Updated alongside viewport height. */\n  cachedFauxHeight: number;\n\n  /** Cached scroll-area element height. Updated alongside viewport/faux heights. */\n  cachedScrollAreaHeight: number;\n\n  /** Cached reference to .tbw-scroll-area element. Set during scroll listener setup. */\n  scrollAreaEl: HTMLElement | null;\n}\n\n// RowElementInternal is now defined earlier in the file with all internal properties\n\n/**\n * Union type for input-like elements that have a `value` property.\n * Covers standard form elements and custom elements with value semantics.\n *\n * @category Plugin Development\n * @internal\n */\nexport type InputLikeElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | { value: unknown };\n// #endregion\n\n// #region Grouping & Footer Public Types\n/**\n * Group row rendering customization options.\n * Controls how group header rows are displayed in the GroupingRowsPlugin.\n *\n * @example\n * ```typescript\n * import { GroupingRowsPlugin } from '@toolbox-web/grid/all';\n *\n * new GroupingRowsPlugin({\n *   groupBy: ['department', 'team'],\n *   render: {\n *     // Group row spans all columns\n *     fullWidth: true,\n *\n *     // Custom label format\n *     formatLabel: (value, depth, key) => {\n *       if (depth === 0) return `Department: ${value}`;\n *       return `Team: ${value}`;\n *     },\n *\n *     // Show aggregates in group rows (when not fullWidth)\n *     aggregators: {\n *       salary: 'sum',\n *       age: 'avg',\n *     },\n *\n *     // Custom CSS class\n *     class: 'my-group-row',\n *   },\n * });\n * ```\n *\n * @see {@link AggregatorRef} for aggregation options\n */\nexport interface RowGroupRenderConfig {\n  /** If true, group rows span all columns (single full-width cell). Default false. */\n  fullWidth?: boolean;\n  /** Optional label formatter override. Receives raw group value + depth. */\n  formatLabel?: (value: unknown, depth: number, key: string) => string;\n  /** Optional aggregate overrides per field for group summary cells (only when not fullWidth). */\n  aggregators?: Record<string, AggregatorRef>;\n  /** Additional CSS class applied to each group row root element. */\n  class?: string;\n}\n\n/**\n * Reference to an aggregation function for footer/group summaries.\n *\n * Can be either:\n * - A built-in aggregator name: `'sum'`, `'avg'`, `'min'`, `'max'`, `'count'`\n * - A custom function that calculates the aggregate value\n *\n * @example\n * ```typescript\n * // Built-in aggregator\n * { field: 'amount', aggregator: 'sum' }\n *\n * // Custom aggregator function\n * { field: 'price', aggregator: (rows, field) => {\n *   const values = rows.map(r => r[field]).filter(v => v != null);\n *   return values.length ? Math.max(...values) : null;\n * }}\n * ```\n *\n * @see {@link RowGroupRenderConfig} for using aggregators in group rows\n */\nexport type AggregatorRef = string | ((rows: unknown[], field: string, column?: unknown) => unknown);\n\n/**\n * Result of automatic column inference from sample rows.\n *\n * When no columns are configured, the grid analyzes the first row of data\n * to automatically generate column definitions with inferred types.\n *\n * @example\n * ```typescript\n * // Automatic inference (no columns configured)\n * grid.rows = [\n *   { name: 'Alice', age: 30, active: true, hireDate: new Date() },\n * ];\n * // Grid infers:\n * // - name: type 'string'\n * // - age: type 'number'\n * // - active: type 'boolean'\n * // - hireDate: type 'date'\n *\n * // Access inferred result programmatically\n * const config = await grid.getConfig();\n * console.log(config.columns); // Inferred columns\n * ```\n *\n * @see {@link ColumnConfig} for column configuration options\n * @see {@link ColumnType} for type inference rules\n */\nexport interface InferredColumnResult<TRow = unknown> {\n  /** Generated column configurations based on data analysis */\n  columns: ColumnConfigMap<TRow>;\n  /** Map of field names to their inferred types */\n  typeMap: Record<string, ColumnType>;\n}\n\n/**\n * Column sizing mode.\n *\n * - `'fixed'` - Columns use their configured widths. Horizontal scrolling if content overflows.\n * - `'stretch'` - Columns stretch proportionally to fill available width. No horizontal scrolling.\n *\n * @example\n * ```typescript\n * // Fixed widths - good for many columns\n * grid.fitMode = 'fixed';\n *\n * // Stretch to fill - good for few columns\n * grid.fitMode = 'stretch';\n *\n * // Via gridConfig\n * grid.gridConfig = { fitMode: 'stretch' };\n * ```\n */\nexport const FitModeEnum = {\n  STRETCH: 'stretch',\n  FIXED: 'fixed',\n} as const;\nexport type FitMode = (typeof FitModeEnum)[keyof typeof FitModeEnum]; // evaluates to 'stretch' | 'fixed'\n// #endregion\n\n// #region Plugin Interface\n/**\n * Minimal plugin interface for type-checking.\n * This interface is defined here to avoid circular imports with BaseGridPlugin.\n * All plugins must satisfy this shape (BaseGridPlugin implements it).\n *\n * @example\n * ```typescript\n * // Using plugins in grid config\n * import { SelectionPlugin, FilteringPlugin } from '@toolbox-web/grid/all';\n *\n * grid.gridConfig = {\n *   plugins: [\n *     new SelectionPlugin({ mode: 'row' }),\n *     new FilteringPlugin({ debounceMs: 200 }),\n *   ],\n * };\n *\n * // Accessing plugin instance at runtime\n * const selection = grid.getPlugin(SelectionPlugin);\n * if (selection) {\n *   selection.selectAll();\n * }\n * ```\n *\n * @category Plugin Development\n */\nexport interface GridPlugin {\n  /** Unique plugin identifier */\n  readonly name: string;\n  /** Plugin version */\n  readonly version: string;\n  /** CSS styles to inject into the grid */\n  readonly styles?: string;\n}\n// #endregion\n\n// #region Grid Config\n/**\n * Grid configuration object - the **single source of truth** for grid behavior.\n *\n * Users can configure the grid via multiple input methods, all of which converge\n * into an effective `GridConfig` internally:\n *\n * **Configuration Input Methods:**\n * - `gridConfig` property - direct assignment of this object\n * - `columns` property - shorthand for `gridConfig.columns`\n * - `fitMode` property - shorthand for `gridConfig.fitMode`\n * - Light DOM `<tbw-grid-column>` - declarative columns (merged into `columns`)\n * - Light DOM `<tbw-grid-header>` - declarative shell header (merged into `shell.header`)\n *\n * **Precedence (when same property set multiple ways):**\n * Individual props (`fitMode`) > `columns` prop > Light DOM > `gridConfig`\n *\n * @example\n * ```ts\n * // Via gridConfig (recommended for complex setups)\n * grid.gridConfig = {\n *   columns: [{ field: 'name' }, { field: 'age' }],\n *   fitMode: 'stretch',\n *   plugins: [new SelectionPlugin()],\n *   shell: { header: { title: 'My Grid' } }\n * };\n *\n * // Via individual props (convenience for simple cases)\n * grid.columns = [{ field: 'name' }, { field: 'age' }];\n * grid.fitMode = 'stretch';\n * ```\n */\nexport interface GridConfig<TRow = any> {\n  /**\n   * Column definitions. Can also be set via `columns` prop or `<tbw-grid-column>` light DOM.\n   * @see {@link ColumnConfig} for column options\n   * @see {@link ColumnConfigMap}\n   */\n  columns?: ColumnConfigMap<TRow>;\n  /**\n   * Dynamic CSS class(es) for data rows.\n   * Called for each row during rendering. Return class names to add to the row element.\n   *\n   * @example\n   * ```typescript\n   * // Highlight inactive rows\n   * rowClass: (row) => row.active ? [] : ['inactive', 'dimmed']\n   *\n   * // Status-based row styling\n   * rowClass: (row) => [`priority-${row.priority}`]\n   * ```\n   */\n  rowClass?: (row: TRow) => string[];\n  /** Sizing mode for columns. Can also be set via `fitMode` prop. */\n  fitMode?: FitMode;\n\n  /**\n   * Grid-wide sorting toggle.\n   * When false, disables sorting for all columns regardless of their individual `sortable` setting.\n   * When true (default), columns with `sortable: true` can be sorted.\n   *\n   * This affects:\n   * - Header click handlers for sorting\n   * - Sort indicator visibility\n   * - Multi-sort plugin behavior (if loaded)\n   *\n   * @default true\n   *\n   * @example\n   * ```typescript\n   * // Disable all sorting\n   * gridConfig = { sortable: false };\n   *\n   * // Enable sorting (default) - individual columns still need sortable: true\n   * gridConfig = { sortable: true };\n   * ```\n   */\n  sortable?: boolean;\n\n  /**\n   * Grid-wide resizing toggle.\n   * When false, disables column resizing for all columns regardless of their individual `resizable` setting.\n   * When true (default), columns with `resizable: true` (or resizable not set, since it defaults to true) can be resized.\n   *\n   * This affects:\n   * - Resize handle visibility in header cells\n   * - Double-click to auto-size behavior\n   *\n   * @default true\n   *\n   * @example\n   * ```typescript\n   * // Disable all column resizing\n   * gridConfig = { resizable: false };\n   *\n   * // Enable resizing (default) - individual columns can opt out with resizable: false\n   * gridConfig = { resizable: true };\n   * ```\n   */\n  resizable?: boolean;\n\n  /**\n   * Row height in pixels for virtualization calculations.\n   * The virtualization system assumes uniform row heights for performance.\n   *\n   * If not specified, the grid measures the first rendered row's height,\n   * which respects the CSS variable `--tbw-row-height` set by themes.\n   *\n   * Set this explicitly when:\n   * - Row content may wrap to multiple lines (also set `--tbw-cell-white-space: normal`)\n   * - Using custom row templates with variable content\n   * - You want to override theme-defined row height\n   * - Rows have different heights based on content (use function form)\n   *\n   * **Variable Row Heights**: When a function is provided, the grid enables variable height\n   * virtualization. Heights are measured on first render and cached by row identity.\n   *\n   * @default Auto-measured from first row (respects --tbw-row-height CSS variable)\n   *\n   * @example\n   * ```ts\n   * // Fixed height for all rows\n   * gridConfig = { rowHeight: 56 };\n   *\n   * // Variable height based on content\n   * gridConfig = {\n   *   rowHeight: (row, index) => row.hasDetails ? 80 : 40,\n   * };\n   *\n   * // Return undefined to trigger DOM auto-measurement\n   * gridConfig = {\n   *   rowHeight: (row) => row.isExpanded ? undefined : 40,\n   * };\n   * ```\n   */\n  rowHeight?: number | ((row: TRow, index: number) => number | undefined);\n  /**\n   * Array of plugin instances.\n   * Each plugin is instantiated with its configuration and attached to this grid.\n   *\n   * @example\n   * ```ts\n   * plugins: [\n   *   new SelectionPlugin({ mode: 'range' }),\n   *   new MultiSortPlugin(),\n   *   new FilteringPlugin({ debounceMs: 150 }),\n   * ]\n   * ```\n   */\n  plugins?: GridPlugin[];\n\n  /**\n   * Saved column state to restore on initialization.\n   * Includes order, width, visibility, sort, and plugin-contributed state.\n   */\n  columnState?: GridColumnState;\n\n  /**\n   * Shell configuration for header bar and tool panels.\n   * When configured, adds an optional wrapper with title, toolbar, and collapsible side panels.\n   */\n  shell?: ShellConfig;\n\n  /**\n   * Grid-wide icon configuration.\n   * Provides consistent icons across all plugins (tree, grouping, sorting, etc.).\n   * Plugins will use these by default but can override with their own config.\n   */\n  icons?: GridIcons;\n\n  /**\n   * Grid-wide animation configuration.\n   * Controls animations for expand/collapse, reordering, and other visual transitions.\n   * Individual plugins can override these defaults in their own config.\n   */\n  animation?: AnimationConfig;\n\n  /**\n   * Custom sort handler for full control over sorting behavior.\n   *\n   * When provided, this handler is called instead of the built-in sorting logic.\n   * Enables custom sorting algorithms, server-side sorting, or plugin-specific sorting.\n   *\n   * The handler receives:\n   * - `rows`: Current row array to sort\n   * - `sortState`: Sort field and direction (1 = asc, -1 = desc)\n   * - `columns`: Column configurations (for accessing sortComparator)\n   *\n   * Return the sorted array (sync) or a Promise that resolves to the sorted array (async).\n   * For server-side sorting, return a Promise that resolves when data is fetched.\n   *\n   * @example\n   * ```ts\n   * // Custom stable sort\n   * sortHandler: (rows, state, cols) => {\n   *   return stableSort(rows, (a, b) => compare(a[state.field], b[state.field]) * state.direction);\n   * }\n   *\n   * // Server-side sorting\n   * sortHandler: async (rows, state) => {\n   *   const response = await fetch(`/api/data?sort=${state.field}&dir=${state.direction}`);\n   *   return response.json();\n   * }\n   * ```\n   */\n  sortHandler?: SortHandler<TRow>;\n\n  /**\n   * Function to extract a unique identifier from a row.\n   * Used by `updateRow()`, `getRow()`, and ID-based tracking.\n   *\n   * If not provided, falls back to `row.id` or `row._id` if present.\n   * Rows without IDs are silently skipped during map building.\n   * Only throws when explicitly calling `getRowId()` or `updateRow()` on a row without an ID.\n   *\n   * @example\n   * ```ts\n   * // Simple field\n   * getRowId: (row) => row.id\n   *\n   * // Composite key\n   * getRowId: (row) => `${row.voyageId}-${row.legNumber}`\n   *\n   * // UUID field\n   * getRowId: (row) => row.uuid\n   * ```\n   */\n  getRowId?: (row: TRow) => string;\n\n  /**\n   * Type-level renderer and editor defaults.\n   *\n   * Keys can be:\n   * - Built-in types: `'string'`, `'number'`, `'date'`, `'boolean'`, `'select'`\n   * - Custom types: `'currency'`, `'country'`, `'status'`, etc.\n   *\n   * Resolution order (highest priority first):\n   * 1. Column-level (`column.renderer` / `column.editor`)\n   * 2. Grid-level (`gridConfig.typeDefaults[column.type]`)\n   * 3. App-level (Angular `GridTypeRegistry`, React `GridTypeProvider`)\n   * 4. Built-in (checkbox for boolean, select for select, etc.)\n   * 5. Fallback (plain text / text input)\n   *\n   * @example\n   * ```typescript\n   * typeDefaults: {\n   *   date: { editor: myDatePickerEditor },\n   *   country: {\n   *     renderer: (ctx) => {\n   *       const span = document.createElement('span');\n   *       span.innerHTML = `<img src=\"/flags/${ctx.value}.svg\" /> ${ctx.value}`;\n   *       return span;\n   *     },\n   *     editor: (ctx) => createCountrySelect(ctx)\n   *   }\n   * }\n   * ```\n   */\n  typeDefaults?: Record<string, TypeDefault<TRow>>;\n\n  // #region Accessibility\n\n  /**\n   * Accessible label for the grid.\n   * Sets `aria-label` on the grid's internal table element for screen readers.\n   *\n   * If not provided and `shell.header.title` is set, the title is used automatically.\n   *\n   * @example\n   * ```ts\n   * gridConfig = { gridAriaLabel: 'Employee data' };\n   * ```\n   */\n  gridAriaLabel?: string;\n\n  /**\n   * ID of an element that describes the grid.\n   * Sets `aria-describedby` on the grid's internal table element.\n   *\n   * @example\n   * ```html\n   * <p id=\"grid-desc\">This table shows all active employees.</p>\n   * <tbw-grid></tbw-grid>\n   * ```\n   * ```ts\n   * gridConfig = { gridAriaDescribedBy: 'grid-desc' };\n   * ```\n   */\n  gridAriaDescribedBy?: string;\n\n  // #endregion\n\n  // #region Loading\n\n  /**\n   * Custom renderer for the loading overlay.\n   *\n   * When provided, replaces the default spinner with custom content.\n   * Receives a context object with the current loading size.\n   *\n   * @example\n   * ```typescript\n   * // Simple text loading indicator\n   * loadingRenderer: () => {\n   *   const el = document.createElement('div');\n   *   el.textContent = 'Loading...';\n   *   return el;\n   * }\n   *\n   * // Custom spinner component\n   * loadingRenderer: (ctx) => {\n   *   const spinner = document.createElement('my-spinner');\n   *   spinner.size = ctx.size === 'large' ? 48 : 24;\n   *   return spinner;\n   * }\n   * ```\n   */\n  loadingRenderer?: LoadingRenderer;\n\n  // #endregion\n}\n// #endregion\n\n// #region Animation\n\n/**\n * Sort state passed to custom sort handlers.\n * Represents the current sorting configuration for a column.\n *\n * @example\n * ```typescript\n * // In a custom sort handler\n * const sortHandler: SortHandler = (rows, sortState, columns) => {\n *   const { field, direction } = sortState;\n *   console.log(`Sorting by ${field} ${direction === 1 ? 'ASC' : 'DESC'}`);\n *\n *   return [...rows].sort((a, b) => {\n *     const aVal = a[field];\n *     const bVal = b[field];\n *     return (aVal < bVal ? -1 : aVal > bVal ? 1 : 0) * direction;\n *   });\n * };\n * ```\n *\n * @see {@link SortHandler} for custom sort handler signature\n * @see {@link SortChangeDetail} for sort change events\n */\nexport interface SortState {\n  /** Field to sort by */\n  field: string;\n  /** Sort direction: 1 = ascending, -1 = descending */\n  direction: 1 | -1;\n}\n\n/**\n * Custom sort handler function signature.\n *\n * Enables full control over sorting behavior including server-side sorting,\n * custom algorithms, or multi-column sorting.\n *\n * @param rows - Current row array to sort\n * @param sortState - Sort field and direction\n * @param columns - Column configurations (for accessing sortComparator)\n * @returns Sorted array (sync) or Promise resolving to sorted array (async)\n *\n * @example\n * ```typescript\n * // Custom client-side sort with locale awareness\n * const localeSortHandler: SortHandler<Employee> = (rows, state, cols) => {\n *   const col = cols.find(c => c.field === state.field);\n *   return [...rows].sort((a, b) => {\n *     const aVal = String(a[state.field] ?? '');\n *     const bVal = String(b[state.field] ?? '');\n *     return aVal.localeCompare(bVal) * state.direction;\n *   });\n * };\n *\n * // Server-side sorting\n * const serverSortHandler: SortHandler<Employee> = async (rows, state) => {\n *   const response = await fetch(\n *     `/api/employees?sortBy=${state.field}&dir=${state.direction}`\n *   );\n *   return response.json();\n * };\n *\n * grid.gridConfig = {\n *   sortHandler: localeSortHandler,\n * };\n * ```\n *\n * @see {@link SortState} for the sort state object\n * @see {@link GridConfig.sortHandler} for configuring the handler\n * @see {@link BaseColumnConfig.sortComparator} for column-level comparators\n */\nexport type SortHandler<TRow = any> = (\n  rows: TRow[],\n  sortState: SortState,\n  columns: ColumnConfig<TRow>[],\n) => TRow[] | Promise<TRow[]>;\n\n// #region Loading\n\n/**\n * Loading indicator size variant.\n *\n * - `'large'`: 48x48px max - used for grid-level loading overlay (`grid.loading = true`)\n * - `'small'`: Follows row height - used for row/cell loading states\n *\n * @example\n * ```typescript\n * // Custom loading renderer adapting to size\n * const myLoader: LoadingRenderer = (ctx) => {\n *   if (ctx.size === 'large') {\n *     // Full overlay spinner\n *     return '<div class=\"spinner-lg\"></div>';\n *   }\n *   // Inline row/cell spinner\n *   return '<span class=\"spinner-sm\"></span>';\n * };\n * ```\n *\n * @see {@link LoadingRenderer} for custom loading renderer\n * @see {@link LoadingContext} for context passed to renderers\n */\nexport type LoadingSize = 'large' | 'small';\n\n/**\n * Context passed to custom loading renderers.\n *\n * Provides information about the loading indicator being rendered,\n * allowing the renderer to adapt its appearance based on the size variant.\n *\n * @example\n * ```typescript\n * const myLoadingRenderer: LoadingRenderer = (ctx: LoadingContext) => {\n *   if (ctx.size === 'large') {\n *     // Full-size spinner for grid-level loading\n *     return '<div class=\"large-spinner\"></div>';\n *   } else {\n *     // Compact spinner for row/cell loading\n *     return '<div class=\"small-spinner\"></div>';\n *   }\n * };\n * ```\n *\n * @see {@link LoadingRenderer} for the renderer function signature\n * @see {@link LoadingSize} for available size variants\n */\nexport interface LoadingContext {\n  /** The size variant being rendered: 'large' for grid-level, 'small' for row/cell */\n  size: LoadingSize;\n}\n\n/**\n * Custom loading renderer function.\n * Returns an element or HTML string to display as the loading indicator.\n *\n * Used with the `loadingRenderer` property in {@link GridConfig} to replace\n * the default spinner with custom content.\n *\n * @param context - Context containing size information\n * @returns HTMLElement or HTML string\n *\n * @example\n * ```typescript\n * // Simple text loading indicator\n * const textLoader: LoadingRenderer = () => {\n *   const el = document.createElement('div');\n *   el.textContent = 'Loading...';\n *   return el;\n * };\n *\n * // Custom spinner with size awareness\n * const customSpinner: LoadingRenderer = (ctx) => {\n *   const spinner = document.createElement('my-spinner');\n *   spinner.size = ctx.size === 'large' ? 48 : 24;\n *   return spinner;\n * };\n *\n * // Material Design-style progress bar\n * const progressBar: LoadingRenderer = () => {\n *   const container = document.createElement('div');\n *   container.className = 'progress-bar-container';\n *   container.innerHTML = '<div class=\"progress-bar\"></div>';\n *   return container;\n * };\n *\n * grid.gridConfig = {\n *   loadingRenderer: customSpinner,\n * };\n * ```\n *\n * @see {@link LoadingContext} for the context object passed to the renderer\n * @see {@link LoadingSize} for size variants ('large' | 'small')\n */\nexport type LoadingRenderer = (context: LoadingContext) => HTMLElement | string;\n\n// #endregion\n\n// #region Data Update Management\n\n/**\n * Indicates the origin of a data change.\n * Used to prevent infinite loops in cascade update handlers.\n *\n * - `'user'`: Direct user interaction via EditingPlugin (typing, selecting)\n * - `'cascade'`: Triggered by `updateRow()` in an event handler\n * - `'api'`: External programmatic update via `grid.updateRow()`\n *\n * @example\n * ```typescript\n * grid.addEventListener('cell-change', (e) => {\n *   const { source, field, newValue } = e.detail;\n *\n *   // Only cascade updates for user edits\n *   if (source === 'user' && field === 'price') {\n *     // Update calculated field (marked as 'cascade')\n *     grid.updateRow(e.detail.rowId, {\n *       total: newValue * e.detail.row.quantity,\n *     });\n *   }\n *\n *   // Ignore cascade updates to prevent infinite loops\n *   if (source === 'cascade') return;\n * });\n * ```\n *\n * @see {@link CellChangeDetail} for the event detail containing source\n * @category Data Management\n */\nexport type UpdateSource = 'user' | 'cascade' | 'api';\n\n/**\n * Detail for cell-change event (emitted by core after mutation).\n * This is an informational event that fires for ALL data mutations.\n *\n * Use this event for:\n * - Logging/auditing changes\n * - Cascading updates (updating other fields based on a change)\n * - Syncing changes to external state\n *\n * @example\n * ```typescript\n * grid.addEventListener('cell-change', (e: CustomEvent<CellChangeDetail>) => {\n *   const { row, rowId, field, oldValue, newValue, source } = e.detail;\n *\n *   console.log(`${field} changed from ${oldValue} to ${newValue}`);\n *   console.log(`Change source: ${source}`);\n *\n *   // Cascade: update total when price changes\n *   if (source === 'user' && field === 'price') {\n *     grid.updateRow(rowId, { total: newValue * row.quantity });\n *   }\n * });\n * ```\n *\n * @see {@link UpdateSource} for understanding change origins\n * @see {@link CellCommitDetail} for the commit event (editing lifecycle)\n * @category Events\n */\nexport interface CellChangeDetail<TRow = unknown> {\n  /** The row object (after mutation) */\n  row: TRow;\n  /** Stable row identifier */\n  rowId: string;\n  /** Current index in rows array */\n  rowIndex: number;\n  /** Field that changed */\n  field: string;\n  /** Value before change */\n  oldValue: unknown;\n  /** Value after change */\n  newValue: unknown;\n  /** All changes passed to updateRow/updateRows (for context) */\n  changes: Partial<TRow>;\n  /** Origin of this change */\n  source: UpdateSource;\n}\n\n/**\n * Batch update specification for updateRows().\n *\n * Used when you need to update multiple rows at once efficiently.\n * The grid will batch all updates and trigger a single re-render.\n *\n * @example\n * ```typescript\n * // Update multiple rows in a single batch\n * const updates: RowUpdate<Employee>[] = [\n *   { id: 'emp-1', changes: { status: 'active', updatedAt: new Date() } },\n *   { id: 'emp-2', changes: { status: 'inactive' } },\n *   { id: 'emp-3', changes: { salary: 75000 } },\n * ];\n *\n * grid.updateRows(updates);\n * ```\n *\n * @see {@link CellChangeDetail} for individual change events\n * @see {@link GridConfig.getRowId} for row identification\n * @category Data Management\n */\nexport interface RowUpdate<TRow = unknown> {\n  /** Row identifier (from getRowId) */\n  id: string;\n  /** Fields to update */\n  changes: Partial<TRow>;\n}\n\n// #endregion\n\n/**\n * Animation behavior mode.\n * - `true` or `'on'`: Animations always enabled\n * - `false` or `'off'`: Animations always disabled\n * - `'reduced-motion'`: Respects `prefers-reduced-motion` media query (default)\n *\n * @example\n * ```typescript\n * // Force animations on (ignore system preference)\n * grid.gridConfig = { animation: { mode: 'on' } };\n *\n * // Disable all animations\n * grid.gridConfig = { animation: { mode: false } };\n *\n * // Respect user's accessibility settings (default)\n * grid.gridConfig = { animation: { mode: 'reduced-motion' } };\n * ```\n *\n * @see {@link AnimationConfig} for full animation configuration\n */\nexport type AnimationMode = boolean | 'on' | 'off' | 'reduced-motion';\n\n/**\n * Animation style for visual transitions.\n * - `'slide'`: Slide/transform animation (e.g., expand down, slide left/right)\n * - `'fade'`: Opacity fade animation\n * - `'flip'`: FLIP technique for position changes (First, Last, Invert, Play)\n * - `false`: No animation for this specific feature\n *\n * @example\n * ```typescript\n * // Plugin-specific animation styles\n * new TreePlugin({\n *   expandAnimation: 'slide', // Slide children down when expanding\n * });\n *\n * new ReorderPlugin({\n *   animation: 'flip', // FLIP animation for column reordering\n * });\n * ```\n *\n * @see {@link AnimationConfig} for grid-wide animation settings\n * @see {@link ExpandCollapseAnimation} for expand/collapse-specific styles\n */\nexport type AnimationStyle = 'slide' | 'fade' | 'flip' | false;\n\n/**\n * Animation style for expand/collapse operations.\n * Subset of AnimationStyle - excludes 'flip' which is for position changes.\n * - `'slide'`: Slide down/up animation for expanding/collapsing content\n * - `'fade'`: Fade in/out animation\n * - `false`: No animation\n *\n * @example\n * ```typescript\n * // Tree rows slide down when expanding\n * new TreePlugin({ expandAnimation: 'slide' });\n *\n * // Row groups fade in/out\n * new GroupingRowsPlugin({ expandAnimation: 'fade' });\n *\n * // Master-detail panels with no animation\n * new MasterDetailPlugin({ expandAnimation: false });\n * ```\n *\n * @see {@link AnimationStyle} for all animation styles\n * @see {@link AnimationConfig} for grid-wide settings\n */\nexport type ExpandCollapseAnimation = 'slide' | 'fade' | false;\n\n/**\n * Type of row animation.\n * - `'change'`: Flash highlight when row data changes (e.g., after cell edit)\n * - `'insert'`: Slide-in animation for newly added rows\n * - `'remove'`: Fade-out animation for rows being removed\n *\n * @example\n * ```typescript\n * // Internal usage - row animation is triggered automatically:\n * // - 'change' after cell-commit event\n * // - 'insert' when rows are added to the grid\n * // - 'remove' when rows are deleted\n *\n * // The animation respects AnimationConfig.mode\n * grid.gridConfig = {\n *   animation: { mode: 'on', duration: 300 },\n * };\n * ```\n *\n * @see {@link AnimationConfig} for animation configuration\n */\nexport type RowAnimationType = 'change' | 'insert' | 'remove';\n\n/**\n * Grid-wide animation configuration.\n * Controls global animation behavior - individual plugins define their own animation styles.\n * Duration and easing values set corresponding CSS variables on the grid element.\n *\n * @example\n * ```typescript\n * // Enable animations regardless of system preferences\n * grid.gridConfig = {\n *   animation: {\n *     mode: 'on',\n *     duration: 300,\n *     easing: 'cubic-bezier(0.4, 0, 0.2, 1)',\n *   },\n * };\n *\n * // Disable all animations\n * grid.gridConfig = {\n *   animation: { mode: 'off' },\n * };\n *\n * // Respect user's reduced-motion preference (default)\n * grid.gridConfig = {\n *   animation: { mode: 'reduced-motion' },\n * };\n * ```\n *\n * @see {@link AnimationMode} for mode options\n */\nexport interface AnimationConfig {\n  /**\n   * Global animation mode.\n   * @default 'reduced-motion'\n   */\n  mode?: AnimationMode;\n\n  /**\n   * Default animation duration in milliseconds.\n   * Sets `--tbw-animation-duration` CSS variable.\n   * @default 200\n   */\n  duration?: number;\n\n  /**\n   * Default easing function.\n   * Sets `--tbw-animation-easing` CSS variable.\n   * @default 'ease-out'\n   */\n  easing?: string;\n}\n\n/** Default animation configuration */\nexport const DEFAULT_ANIMATION_CONFIG: Required<Omit<AnimationConfig, 'sort'>> = {\n  mode: 'reduced-motion',\n  duration: 200,\n  easing: 'ease-out',\n};\n\n// #endregion\n\n// #region Grid Icons\n\n/** Icon value - can be a string (text/HTML) or HTMLElement */\nexport type IconValue = string | HTMLElement;\n\n/**\n * Grid-wide icon configuration.\n * All icons are optional - sensible defaults are used when not specified.\n *\n * Icons can be text (including emoji), HTML strings (for SVG), or HTMLElement instances.\n *\n * @example\n * ```typescript\n * grid.gridConfig = {\n *   icons: {\n *     // Emoji icons\n *     expand: '➕',\n *     collapse: '➖',\n *\n *     // Custom SVG icon\n *     sortAsc: '<svg viewBox=\"0 0 16 16\"><path d=\"M8 4l4 8H4z\"/></svg>',\n *\n *     // Font icon class (wrap in span)\n *     filter: '<span class=\"icon icon-filter\"></span>',\n *   },\n * };\n * ```\n *\n * @see {@link IconValue} for allowed icon formats\n */\nexport interface GridIcons {\n  /** Expand icon for collapsed items (trees, groups, details). Default: '▶' */\n  expand?: IconValue;\n  /** Collapse icon for expanded items (trees, groups, details). Default: '▼' */\n  collapse?: IconValue;\n  /** Sort ascending indicator. Default: '▲' */\n  sortAsc?: IconValue;\n  /** Sort descending indicator. Default: '▼' */\n  sortDesc?: IconValue;\n  /** Sort neutral/unsorted indicator. Default: '⇅' */\n  sortNone?: IconValue;\n  /** Submenu arrow for context menus. Default: '▶' */\n  submenuArrow?: IconValue;\n  /** Drag handle icon for reordering. Default: '⋮⋮' */\n  dragHandle?: IconValue;\n  /** Tool panel toggle icon in toolbar. Default: '☰' */\n  toolPanel?: IconValue;\n  /** Filter icon in column headers. Default: SVG funnel icon */\n  filter?: IconValue;\n  /** Filter icon when filter is active. Default: same as filter with accent color */\n  filterActive?: IconValue;\n  /** Print icon for print button. Default: '🖨️' */\n  print?: IconValue;\n}\n\n/** Default filter icon SVG */\nconst DEFAULT_FILTER_ICON =\n  '<svg viewBox=\"0 0 16 16\" width=\"12\" height=\"12\"><path fill=\"currentColor\" d=\"M6 10.5a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5zm-2-3a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zm-2-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5z\"/></svg>';\n\n/** Default icons used when not overridden */\nexport const DEFAULT_GRID_ICONS: Required<GridIcons> = {\n  expand: '▶',\n  collapse: '▼',\n  sortAsc: '▲',\n  sortDesc: '▼',\n  sortNone: '⇅',\n  submenuArrow: '▶',\n  dragHandle: '⋮⋮',\n  toolPanel: '☰',\n  filter: DEFAULT_FILTER_ICON,\n  filterActive: DEFAULT_FILTER_ICON,\n  print: '🖨️',\n};\n// #endregion\n\n// #region Shell Configuration\n\n/**\n * Shell configuration for the grid's optional header bar and tool panels.\n *\n * The shell provides a wrapper around the grid with:\n * - Header bar with title, toolbar buttons, and custom content\n * - Collapsible side panel for filters, column visibility, settings, etc.\n *\n * @example\n * ```typescript\n * grid.gridConfig = {\n *   shell: {\n *     header: {\n *       title: 'Employee Directory',\n *     },\n *     toolPanel: {\n *       position: 'right',\n *       defaultOpen: 'columns', // Open by default\n *     },\n *   },\n *   plugins: [new VisibilityPlugin()], // Adds \"Columns\" panel\n * };\n *\n * // Register custom tool panels\n * grid.registerToolPanel({\n *   id: 'filters',\n *   title: 'Filters',\n *   icon: '🔍',\n *   render: (container) => {\n *     container.innerHTML = '<div>Filter controls...</div>';\n *   },\n * });\n * ```\n *\n * @see {@link ShellHeaderConfig} for header options\n * @see {@link ToolPanelConfig} for tool panel options\n */\nexport interface ShellConfig {\n  /** Shell header bar configuration */\n  header?: ShellHeaderConfig;\n  /** Tool panel configuration */\n  toolPanel?: ToolPanelConfig;\n  /**\n   * Registered tool panels (from plugins, API, or Light DOM).\n   * These are the actual panel definitions that can be opened.\n   * @internal Set by ConfigManager during merge\n   */\n  toolPanels?: ToolPanelDefinition[];\n  /**\n   * Registered header content sections (from plugins or API).\n   * Content rendered in the center of the shell header.\n   * @internal Set by ConfigManager during merge\n   */\n  headerContents?: HeaderContentDefinition[];\n}\n\n/**\n * Shell header bar configuration\n */\nexport interface ShellHeaderConfig {\n  /** Grid title displayed on the left (optional) */\n  title?: string;\n  /** Custom toolbar content (rendered before tool panel toggle) */\n  toolbarContents?: ToolbarContentDefinition[];\n  /**\n   * Light DOM header content elements (parsed from <tbw-grid-header> children).\n   * @internal Set by ConfigManager during merge\n   */\n  lightDomContent?: HTMLElement[];\n  /**\n   * Whether a tool buttons container was found in light DOM.\n   * @internal Set by ConfigManager during merge\n   */\n  hasToolButtonsContainer?: boolean;\n}\n\n/**\n * Tool panel configuration\n */\nexport interface ToolPanelConfig {\n  /** Panel position: 'left' | 'right' (default: 'right') */\n  position?: 'left' | 'right';\n  /** Default panel width in pixels (default: 280) */\n  width?: number;\n  /** Panel ID to open by default on load */\n  defaultOpen?: string;\n  /** Whether to persist open/closed state (requires Column State Events) */\n  persistState?: boolean;\n  /**\n   * Close the tool panel when clicking outside of it.\n   * When `true`, clicking anywhere outside the tool panel (but inside the grid)\n   * will close the panel automatically.\n   * @default false\n   */\n  closeOnClickOutside?: boolean;\n}\n\n/**\n * Toolbar content definition for the shell header toolbar area.\n * Register via `registerToolbarContent()` or use light DOM `<tbw-grid-tool-buttons>`.\n *\n * @example\n * ```typescript\n * grid.registerToolbarContent({\n *   id: 'my-toolbar',\n *   order: 10,\n *   render: (container) => {\n *     const btn = document.createElement('button');\n *     btn.textContent = 'Refresh';\n *     btn.onclick = () => console.log('clicked');\n *     container.appendChild(btn);\n *     return () => btn.remove();\n *   },\n * });\n * ```\n */\nexport interface ToolbarContentDefinition {\n  /** Unique content ID */\n  id: string;\n  /** Content factory - called once when shell header renders */\n  render: (container: HTMLElement) => void | (() => void);\n  /** Called when content is removed (for cleanup) */\n  onDestroy?: () => void;\n  /** Order priority (lower = first, default: 100) */\n  order?: number;\n}\n\n/**\n * Tool panel definition registered by plugins or consumers.\n *\n * Register via `grid.registerToolPanel()` to add panels to the sidebar.\n * Panels appear as collapsible sections with icons and titles.\n *\n * @example\n * ```typescript\n * grid.registerToolPanel({\n *   id: 'filters',\n *   title: 'Filters',\n *   icon: '🔍',\n *   tooltip: 'Filter grid data',\n *   order: 10, // Lower = appears first\n *   render: (container) => {\n *     container.innerHTML = `\n *       <div class=\"filter-panel\">\n *         <input type=\"text\" placeholder=\"Search...\" />\n *       </div>\n *     `;\n *     // Return cleanup function\n *     return () => container.innerHTML = '';\n *   },\n *   onClose: () => {\n *     console.log('Filter panel closed');\n *   },\n * });\n * ```\n *\n * @see {@link ShellConfig} for shell configuration\n */\nexport interface ToolPanelDefinition {\n  /** Unique panel ID */\n  id: string;\n  /** Panel title shown in accordion header */\n  title: string;\n  /** Icon for accordion section header (optional, emoji or SVG) */\n  icon?: string;\n  /** Tooltip for accordion section header */\n  tooltip?: string;\n  /** Panel content factory - called when panel section opens */\n  render: (container: HTMLElement) => void | (() => void);\n  /** Called when panel closes (for cleanup) */\n  onClose?: () => void;\n  /** Panel order priority (lower = first, default: 100) */\n  order?: number;\n}\n\n/**\n * Header content definition for plugins contributing to shell header center section.\n *\n * Register via `grid.registerHeaderContent()` to add content between\n * the title and toolbar buttons.\n *\n * @example\n * ```typescript\n * grid.registerHeaderContent({\n *   id: 'row-count',\n *   order: 10,\n *   render: (container) => {\n *     const span = document.createElement('span');\n *     span.className = 'row-count';\n *     span.textContent = `${grid.rows.length} rows`;\n *     container.appendChild(span);\n *\n *     // Update on data changes\n *     const update = () => span.textContent = `${grid.rows.length} rows`;\n *     grid.addEventListener('data-change', update);\n *\n *     return () => {\n *       grid.removeEventListener('data-change', update);\n *     };\n *   },\n * });\n * ```\n *\n * @see {@link ShellConfig} for shell configuration\n */\nexport interface HeaderContentDefinition {\n  /** Unique content ID */\n  id: string;\n  /** Content factory - called once when shell header renders */\n  render: (container: HTMLElement) => void | (() => void);\n  /** Called when content is removed (for cleanup) */\n  onDestroy?: () => void;\n  /** Order priority (lower = first, default: 100) */\n  order?: number;\n}\n// #endregion\n\n// #region Column State (Persistence)\n\n/**\n * State for a single column. Captures user-driven changes at runtime.\n * Plugins can extend this interface via module augmentation to add their own state.\n *\n * Used with `grid.getColumnState()` and `grid.columnState` for persisting\n * user customizations (column widths, order, visibility, sort).\n *\n * @example\n * ```typescript\n * // Save column state to localStorage\n * const state = grid.getColumnState();\n * localStorage.setItem('gridState', JSON.stringify(state));\n *\n * // Restore on page load\n * const saved = localStorage.getItem('gridState');\n * if (saved) {\n *   grid.columnState = JSON.parse(saved);\n * }\n *\n * // Example column state structure\n * const state: GridColumnState = {\n *   columns: [\n *     { field: 'name', order: 0, width: 200, hidden: false },\n *     { field: 'email', order: 1, width: 300, hidden: false },\n *     { field: 'phone', order: 2, hidden: true }, // Hidden column\n *   ],\n *   sort: { field: 'name', direction: 1 },\n * };\n * ```\n *\n * @example\n * ```typescript\n * // Plugin augmentation example (in filtering plugin)\n * declare module '@toolbox-web/grid' {\n *   interface ColumnState {\n *     filter?: FilterValue;\n *   }\n * }\n * ```\n *\n * @see {@link GridColumnState} for the full state object\n */\nexport interface ColumnState {\n  /** Column field identifier */\n  field: string;\n  /** Position index after reordering (0-based) */\n  order: number;\n  /** Width in pixels (undefined = use default) */\n  width?: number;\n  /** Visibility state */\n  visible: boolean;\n  /** Sort state (undefined = not sorted). */\n  sort?: ColumnSortState;\n}\n\n/**\n * Sort state for a column.\n * Used within {@link ColumnState} to track sort direction and priority.\n *\n * @see {@link ColumnState} for column state persistence\n * @see {@link SortChangeDetail} for sort change events\n */\nexport interface ColumnSortState {\n  /** Sort direction */\n  direction: 'asc' | 'desc';\n  /** Priority for multi-sort (0 = primary, 1 = secondary, etc.) */\n  priority: number;\n}\n\n/**\n * Complete grid column state for persistence.\n * Contains state for all columns, including plugin-contributed properties.\n *\n * @example\n * ```typescript\n * // Save state\n * const state = grid.getColumnState();\n * localStorage.setItem('grid-state', JSON.stringify(state));\n *\n * // Restore state\n * grid.columnState = JSON.parse(localStorage.getItem('grid-state'));\n * ```\n *\n * @see {@link ColumnState} for individual column state\n * @see {@link PublicGrid.getColumnState} for retrieving state\n */\nexport interface GridColumnState {\n  /** Array of column states. */\n  columns: ColumnState[];\n}\n// #endregion\n\n// #region Public Event Detail Interfaces\n/**\n * Detail for a cell click event.\n * Provides full context about the clicked cell including row data.\n *\n * @example\n * ```typescript\n * grid.addEventListener('cell-click', (e: CustomEvent<CellClickDetail>) => {\n *   const { row, field, value, rowIndex, colIndex } = e.detail;\n *   console.log(`Clicked ${field} = ${value} in row ${rowIndex}`);\\n *\n *   // Access the full row data\n *   if (row.status === 'pending') {\n *     showApprovalDialog(row);\n *   }\n * });\n * ```\n *\n * @category Events\n */\nexport interface CellClickDetail<TRow = unknown> {\n  /** Zero-based row index of the clicked cell. */\n  rowIndex: number;\n  /** Zero-based column index of the clicked cell. */\n  colIndex: number;\n  /** Column configuration object for the clicked cell. */\n  column: ColumnConfig<TRow>;\n  /** Field name of the clicked column. */\n  field: string;\n  /** Cell value at the clicked position. */\n  value: unknown;\n  /** Full row data object. */\n  row: TRow;\n  /** The clicked cell element. */\n  cellEl: HTMLElement;\n  /** The original mouse event. */\n  originalEvent: MouseEvent;\n}\n\n/**\n * Detail for a row click event.\n * Provides context about the clicked row.\n *\n * @example\n * ```typescript\n * grid.addEventListener('row-click', (e: CustomEvent<RowClickDetail>) => {\n *   const { row, rowIndex, rowEl } = e.detail;\n *   console.log(`Clicked row ${rowIndex}: ${row.name}`);\n *\n *   // Highlight the row\n *   rowEl.classList.add('selected');\n *\n *   // Open detail panel\n *   showDetailPanel(row);\n * });\n * ```\n *\n * @category Events\n */\nexport interface RowClickDetail<TRow = unknown> {\n  /** Zero-based row index of the clicked row. */\n  rowIndex: number;\n  /** Full row data object. */\n  row: TRow;\n  /** The clicked row element. */\n  rowEl: HTMLElement;\n  /** The original mouse event. */\n  originalEvent: MouseEvent;\n}\n\n/**\n * Detail for a sort change (direction 0 indicates cleared sort).\n *\n * @example\n * ```typescript\n * grid.addEventListener('sort-change', (e: CustomEvent<SortChangeDetail>) => {\n *   const { field, direction } = e.detail;\n *\n *   if (direction === 0) {\n *     console.log(`Sort cleared on ${field}`);\n *   } else {\n *     const dir = direction === 1 ? 'ascending' : 'descending';\n *     console.log(`Sorted by ${field} ${dir}`);\n *   }\n *\n *   // Fetch sorted data from server\n *   fetchData({ sortBy: field, sortDir: direction });\n * });\n * ```\n *\n * @see {@link SortState} for the sort state object\n * @see {@link SortHandler} for custom sort handlers\n * @category Events\n */\nexport interface SortChangeDetail {\n  /** Sorted field key. */\n  field: string;\n  /** Direction: 1 ascending, -1 descending, 0 cleared. */\n  direction: 1 | -1 | 0;\n}\n\n/**\n * Column resize event detail containing final pixel width.\n *\n * @example\n * ```typescript\n * grid.addEventListener('column-resize', (e: CustomEvent<ColumnResizeDetail>) => {\n *   const { field, width } = e.detail;\n *   console.log(`Column ${field} resized to ${width}px`);\n *\n *   // Persist to user preferences\n *   saveColumnWidth(field, width);\n * });\n * ```\n *\n * @see {@link ColumnState} for persisting column state\n * @see {@link ResizeController} for resize implementation\n * @category Events\n */\nexport interface ColumnResizeDetail {\n  /** Resized column field key. */\n  field: string;\n  /** New width in pixels. */\n  width: number;\n}\n\n/**\n * Trigger type for cell activation.\n * - `'keyboard'`: Enter key pressed on focused cell\n * - `'pointer'`: Mouse/touch/pen click on cell\n *\n * @see {@link CellActivateDetail} for the activation event detail\n * @category Events\n */\nexport type CellActivateTrigger = 'keyboard' | 'pointer';\n\n/**\n * Fired when a cell is activated by user interaction (Enter key or click).\n * Unified event for both keyboard and pointer activation.\n *\n * @example\n * ```typescript\n * grid.addEventListener('cell-activate', (e: CustomEvent<CellActivateDetail>) => {\n *   const { row, field, value, trigger, cellEl } = e.detail;\n *\n *   if (trigger === 'keyboard') {\n *     console.log('Activated via Enter key');\n *   } else {\n *     console.log('Activated via click/tap');\n *   }\n *\n *   // Start custom editing for specific columns\n *   if (field === 'notes') {\n *     openNotesEditor(row, cellEl);\n *     e.preventDefault(); // Prevent default editing\n *   }\n * });\n * ```\n *\n * @see {@link CellClickDetail} for click-only events\n * @see {@link CellActivateTrigger} for trigger types\n * @category Events\n */\nexport interface CellActivateDetail<TRow = unknown> {\n  /** Zero-based row index of the activated cell. */\n  rowIndex: number;\n  /** Zero-based column index of the activated cell. */\n  colIndex: number;\n  /** Field name of the activated column. */\n  field: string;\n  /** Cell value at the activated position. */\n  value: unknown;\n  /** Full row data object. */\n  row: TRow;\n  /** The activated cell element. */\n  cellEl: HTMLElement;\n  /** What triggered the activation. */\n  trigger: CellActivateTrigger;\n  /** The original event (KeyboardEvent for keyboard, MouseEvent/PointerEvent for pointer). */\n  originalEvent: KeyboardEvent | MouseEvent | PointerEvent;\n}\n\n/**\n * @deprecated Use `CellActivateDetail` instead. Will be removed in next major version.\n * Kept for backwards compatibility.\n *\n * @category Events\n */\nexport interface ActivateCellDetail {\n  /** Zero-based row index now focused. */\n  row: number;\n  /** Zero-based column index now focused. */\n  col: number;\n}\n\n/**\n * Event detail for mounting external view renderers.\n *\n * Emitted when a cell uses an external component spec (React, Angular, Vue)\n * and needs the framework adapter to mount the component.\n *\n * @example\n * ```typescript\n * // Framework adapter listens for this event\n * grid.addEventListener('mount-external-view', (e: CustomEvent<ExternalMountViewDetail>) => {\n *   const { placeholder, spec, context } = e.detail;\n *   // Mount framework component into placeholder\n *   mountComponent(spec.component, placeholder, context);\n * });\n * ```\n *\n * @see {@link ColumnConfig.externalView} for external view spec\n * @see {@link FrameworkAdapter} for adapter interface\n * @category Framework Adapters\n */\nexport interface ExternalMountViewDetail<TRow = unknown> {\n  placeholder: HTMLElement;\n  spec: unknown;\n  context: { row: TRow; value: unknown; field: string; column: unknown };\n}\n\n/**\n * Event detail for mounting external editor renderers.\n *\n * Emitted when a cell uses an external editor component spec and needs\n * the framework adapter to mount the editor with commit/cancel bindings.\n *\n * @example\n * ```typescript\n * // Framework adapter listens for this event\n * grid.addEventListener('mount-external-editor', (e: CustomEvent<ExternalMountEditorDetail>) => {\n *   const { placeholder, spec, context } = e.detail;\n *   // Mount framework editor with commit/cancel wired\n *   mountEditor(spec.component, placeholder, {\n *     value: context.value,\n *     onCommit: context.commit,\n *     onCancel: context.cancel,\n *   });\n * });\n * ```\n *\n * @see {@link ColumnEditorSpec} for external editor spec\n * @see {@link FrameworkAdapter} for adapter interface\n * @category Framework Adapters\n */\nexport interface ExternalMountEditorDetail<TRow = unknown> {\n  placeholder: HTMLElement;\n  spec: unknown;\n  context: {\n    row: TRow;\n    value: unknown;\n    field: string;\n    column: unknown;\n    commit: (v: unknown) => void;\n    cancel: () => void;\n  };\n}\n\n/**\n * Maps event names to their detail payload types.\n *\n * Use this interface for strongly typed event handling.\n *\n * @example\n * ```typescript\n * // Type-safe event listener\n * function handleEvent<K extends keyof DataGridEventMap>(\n *   grid: DataGridElement,\n *   event: K,\n *   handler: (detail: DataGridEventMap[K]) => void,\n * ): void {\n *   grid.addEventListener(event, (e: CustomEvent) => handler(e.detail));\n * }\n *\n * handleEvent(grid, 'cell-click', (detail) => {\n *   console.log(detail.field); // Type-safe access\n * });\n * ```\n *\n * @see {@link DataGridCustomEvent} for typed CustomEvent wrapper\n * @see {@link DGEvents} for event name constants\n * @category Events\n */\nexport interface DataGridEventMap<TRow = unknown> {\n  'cell-click': CellClickDetail<TRow>;\n  'row-click': RowClickDetail<TRow>;\n  'cell-activate': CellActivateDetail<TRow>;\n  'cell-change': CellChangeDetail<TRow>;\n  'mount-external-view': ExternalMountViewDetail<TRow>;\n  'mount-external-editor': ExternalMountEditorDetail<TRow>;\n  'sort-change': SortChangeDetail;\n  'column-resize': ColumnResizeDetail;\n  /** @deprecated Use 'cell-activate' instead */\n  'activate-cell': ActivateCellDetail;\n  'column-state-change': GridColumnState;\n  // Note: 'cell-commit', 'row-commit', 'changed-rows-reset' are added via\n  // module augmentation by EditingPlugin when imported\n}\n\n/**\n * Extracts the event detail type for a given event name.\n *\n * Utility type for getting the detail payload type of a specific event.\n *\n * @example\n * ```typescript\n * // Extract detail type for specific event\n * type ClickDetail = DataGridEventDetail<'cell-click', Employee>;\n * // Equivalent to: CellClickDetail<Employee>\n *\n * // Use in generic handler\n * function logDetail<K extends keyof DataGridEventMap>(\n *   eventName: K,\n *   detail: DataGridEventDetail<K>,\n * ): void {\n *   console.log(`${eventName}:`, detail);\n * }\n * ```\n *\n * @see {@link DataGridEventMap} for all event types\n * @category Events\n */\nexport type DataGridEventDetail<K extends keyof DataGridEventMap<unknown>, TRow = unknown> = DataGridEventMap<TRow>[K];\n\n/**\n * Custom event type for DataGrid events with typed detail payload.\n *\n * Use this type when you need to cast or declare event handler parameters.\n *\n * @example\n * ```typescript\n * // Strongly typed event handler\n * function onCellClick(e: DataGridCustomEvent<'cell-click', Employee>): void {\n *   const { row, field, value } = e.detail;\n *   console.log(`Clicked ${field} = ${value} on ${row.name}`);\n * }\n *\n * grid.addEventListener('cell-click', onCellClick);\n * ```\n *\n * @see {@link DataGridEventMap} for all event types\n * @see {@link DataGridEventDetail} for extracting detail type only\n * @category Events\n */\nexport type DataGridCustomEvent<K extends keyof DataGridEventMap<unknown>, TRow = unknown> = CustomEvent<\n  DataGridEventMap<TRow>[K]\n>;\n\n/**\n * Template evaluation context for dynamic templates.\n *\n * @category Plugin Development\n */\nexport interface EvalContext {\n  value: unknown;\n  row: Record<string, unknown> | null;\n}\n// #endregion\n","/**\n * Base Grid Plugin Class\n *\n * All plugins extend this abstract class.\n * Plugins are instantiated per-grid and manage their own state.\n */\n\n// Injected by Vite at build time from package.json (same as grid.ts)\ndeclare const __GRID_VERSION__: string;\n\nimport type {\n  ColumnConfig,\n  ColumnState,\n  GridPlugin,\n  HeaderContentDefinition,\n  IconValue,\n  ToolPanelDefinition,\n} from '../types';\nimport { DEFAULT_GRID_ICONS } from '../types';\n\n// Re-export shared plugin types for convenience\nexport { PLUGIN_QUERIES } from './types';\nexport type {\n  AfterCellRenderContext,\n  AfterRowRenderContext,\n  CellClickEvent,\n  CellCoords,\n  CellEditor,\n  CellMouseEvent,\n  CellRenderer,\n  ContextMenuItem,\n  ContextMenuParams,\n  GridElementRef,\n  HeaderClickEvent,\n  HeaderRenderer,\n  KeyboardModifiers,\n  PluginCellRenderContext,\n  PluginQuery,\n  RowClickEvent,\n  ScrollEvent,\n} from './types';\n\nimport type {\n  AfterCellRenderContext,\n  AfterRowRenderContext,\n  CellClickEvent,\n  CellEditor,\n  CellMouseEvent,\n  CellRenderer,\n  GridElementRef,\n  HeaderClickEvent,\n  HeaderRenderer,\n  PluginQuery,\n  RowClickEvent,\n  ScrollEvent,\n} from './types';\n\n/**\n * Grid element interface for plugins.\n * Extends GridElementRef with plugin-specific methods.\n * Note: effectiveConfig is already available from GridElementRef.\n */\nexport interface GridElement extends GridElementRef {\n  getPlugin<T extends BaseGridPlugin>(PluginClass: new (...args: any[]) => T): T | undefined;\n  getPluginByName(name: string): BaseGridPlugin | undefined;\n  /**\n   * Get a plugin's state by plugin name.\n   * This is a loose-coupling method for plugins to access other plugins' state\n   * without importing the plugin class directly.\n   * @internal Plugin API\n   */\n  getPluginState?(name: string): unknown;\n}\n\n/**\n * Header render context for plugin header renderers.\n */\nexport interface PluginHeaderRenderContext {\n  /** Column configuration */\n  column: ColumnConfig;\n  /** Column index */\n  colIndex: number;\n}\n\n// ============================================================================\n// Plugin Dependency Types\n// ============================================================================\n\n/**\n * Declares a dependency on another plugin.\n *\n * @category Plugin Development\n * @example\n * ```typescript\n * export class UndoRedoPlugin extends BaseGridPlugin {\n *   static readonly dependencies: PluginDependency[] = [\n *     { name: 'editing', required: true },\n *   ];\n * }\n * ```\n */\nexport interface PluginDependency {\n  /**\n   * The name of the required plugin (matches the plugin's `name` property).\n   * Use string names for loose coupling - avoids static imports.\n   */\n  name: string;\n\n  /**\n   * Whether this dependency is required (hard) or optional (soft).\n   * - `true`: Plugin cannot function without it. Throws error if missing.\n   * - `false`: Plugin works with reduced functionality. Logs info if missing.\n   * @default true\n   */\n  required?: boolean;\n\n  /**\n   * Human-readable reason for this dependency.\n   * Shown in error/info messages to help users understand why.\n   * @example \"UndoRedoPlugin needs EditingPlugin to track cell edits\"\n   */\n  reason?: string;\n}\n\n/**\n * Declares an incompatibility between plugins.\n * When both plugins are loaded, a warning is logged to help users understand the conflict.\n *\n * @category Plugin Development\n */\nexport interface PluginIncompatibility {\n  /**\n   * The name of the incompatible plugin (matches the plugin's `name` property).\n   */\n  name: string;\n\n  /**\n   * Human-readable reason for the incompatibility.\n   * Should explain why the plugins conflict and any workarounds.\n   * @example \"Responsive card layout does not support row grouping yet\"\n   */\n  reason: string;\n}\n\n// ============================================================================\n// Plugin Query & Event Definitions\n// ============================================================================\n\n/**\n * Defines a query that a plugin can handle.\n * Other plugins or the grid can send this query type to retrieve data.\n *\n * @category Plugin Development\n *\n * @example\n * ```typescript\n * // In manifest\n * queries: [\n *   {\n *     type: 'canMoveColumn',\n *     description: 'Check if a column can be moved/reordered',\n *   },\n * ]\n *\n * // In plugin class\n * handleQuery(query: PluginQuery): unknown {\n *   if (query.type === 'canMoveColumn') {\n *     return this.canMoveColumn(query.context);\n *   }\n * }\n * ```\n */\nexport interface QueryDefinition {\n  /**\n   * The query type identifier (e.g., 'canMoveColumn', 'getContextMenuItems').\n   * Should be unique across all plugins.\n   */\n  type: string;\n\n  /**\n   * Human-readable description of what the query does.\n   */\n  description?: string;\n}\n\n/**\n * Defines an event that a plugin can emit.\n * Other plugins can subscribe to these events via the Event Bus.\n *\n * @category Plugin Development\n *\n * @example\n * ```typescript\n * // In manifest\n * events: [\n *   {\n *     type: 'filter-change',\n *     description: 'Emitted when filter criteria change',\n *   },\n * ]\n *\n * // In plugin class - emit\n * this.emitPluginEvent('filter-change', { field: 'name', value: 'Alice' });\n *\n * // In another plugin - subscribe\n * this.on('filter-change', (detail) => console.log('Filter changed:', detail));\n * ```\n */\nexport interface EventDefinition {\n  /**\n   * The event type identifier (e.g., 'filter-change', 'selection-change').\n   * Used when emitting and subscribing to events.\n   */\n  type: string;\n\n  /**\n   * Human-readable description of what the event represents.\n   */\n  description?: string;\n\n  /**\n   * Whether this event is cancelable via `event.preventDefault()`.\n   * @default false\n   */\n  cancelable?: boolean;\n}\n\n// ============================================================================\n// Plugin Manifest Types\n// ============================================================================\n\n/**\n * Defines a property that a plugin \"owns\" - used for configuration validation.\n * When this property is used without the owning plugin loaded, an error is thrown.\n *\n * @category Plugin Development\n */\nexport interface PluginPropertyDefinition {\n  /** The property name on column or grid config */\n  property: string;\n  /** Whether this is a column-level or config-level property */\n  level: 'column' | 'config';\n  /** Human-readable description for error messages (e.g., 'the \"editable\" column property') */\n  description: string;\n  /** Import path hint for error messages (e.g., \"import { EditingPlugin } from '@toolbox-web/grid/plugins/editing';\") */\n  importHint?: string;\n  /** Custom check for whether property is considered \"used\" (default: truthy value check) */\n  isUsed?: (value: unknown) => boolean;\n}\n\n/**\n * A configuration validation rule for detecting invalid/conflicting settings.\n * Plugins declare rules in their manifest; the validator executes them during grid initialization.\n *\n * @category Plugin Development\n * @template TConfig - The plugin's configuration type\n */\nexport interface PluginConfigRule<TConfig = unknown> {\n  /** Rule identifier for debugging (e.g., 'selection/range-dblclick') */\n  id: string;\n  /** Severity: 'error' throws, 'warn' logs warning */\n  severity: 'error' | 'warn';\n  /** Human-readable message shown when rule is violated */\n  message: string;\n  /** Predicate returning true if the rule is VIOLATED (i.e., config is invalid) */\n  check: (pluginConfig: TConfig) => boolean;\n}\n\n/**\n * Hook names that can have execution priority configured.\n *\n * @category Plugin Development\n */\nexport type HookName =\n  | 'processColumns'\n  | 'processRows'\n  | 'afterRender'\n  | 'afterCellRender'\n  | 'afterRowRender'\n  | 'onCellClick'\n  | 'onCellMouseDown'\n  | 'onCellMouseMove'\n  | 'onCellMouseUp'\n  | 'onKeyDown'\n  | 'onScroll'\n  | 'onScrollRender';\n\n/**\n * Static metadata about a plugin's capabilities and requirements.\n * Declared as a static property on plugin classes.\n *\n * @category Plugin Development\n * @template TConfig - The plugin's configuration type\n *\n * @example\n * ```typescript\n * export class MyPlugin extends BaseGridPlugin<MyConfig> {\n *   static override readonly manifest: PluginManifest<MyConfig> = {\n *     ownedProperties: [\n *       { property: 'myProp', level: 'column', description: 'the \"myProp\" column property' },\n *     ],\n *     configRules: [\n *       { id: 'my-plugin/invalid-combo', severity: 'warn', message: '...', check: (c) => c.a && c.b },\n *     ],\n *   };\n *   readonly name = 'myPlugin';\n * }\n * ```\n */\nexport interface PluginManifest<TConfig = unknown> {\n  /**\n   * Properties this plugin owns - validated by validate-config.ts.\n   * If a user uses one of these properties without loading the plugin, an error is thrown.\n   */\n  ownedProperties?: PluginPropertyDefinition[];\n\n  /**\n   * Hook execution priority (higher = later, default 0).\n   * Use negative values to run earlier, positive to run later.\n   */\n  hookPriority?: Partial<Record<HookName, number>>;\n\n  /**\n   * Configuration validation rules - checked during grid initialization.\n   * Rules with severity 'error' throw, 'warn' logs to console.\n   */\n  configRules?: PluginConfigRule<TConfig>[];\n\n  /**\n   * Plugins that are incompatible with this plugin.\n   * When both plugins are loaded together, a warning is shown.\n   *\n   * @example\n   * ```typescript\n   * incompatibleWith: [\n   *   { name: 'groupingRows', reason: 'Responsive card layout does not support row grouping yet' },\n   * ],\n   * ```\n   */\n  incompatibleWith?: PluginIncompatibility[];\n\n  /**\n   * Queries this plugin can handle.\n   * Declares what query types this plugin responds to via `handleQuery()`.\n   * This replaces the centralized PLUGIN_QUERIES approach with manifest-declared queries.\n   *\n   * @example\n   * ```typescript\n   * queries: [\n   *   { type: 'canMoveColumn', description: 'Check if a column can be moved' },\n   * ],\n   * ```\n   */\n  queries?: QueryDefinition[];\n\n  /**\n   * Events this plugin can emit.\n   * Declares what event types other plugins can subscribe to via `on()`.\n   *\n   * @example\n   * ```typescript\n   * events: [\n   *   { type: 'filter-change', description: 'Emitted when filter criteria change' },\n   * ],\n   * ```\n   */\n  events?: EventDefinition[];\n}\n\n/**\n * Abstract base class for all grid plugins.\n *\n * @category Plugin Development\n * @template TConfig - Configuration type for the plugin\n */\nexport abstract class BaseGridPlugin<TConfig = unknown> implements GridPlugin {\n  /**\n   * Plugin dependencies - declare other plugins this one requires.\n   *\n   * Dependencies are validated when the plugin is attached.\n   * Required dependencies throw an error if missing.\n   * Optional dependencies log an info message if missing.\n   *\n   * @example\n   * ```typescript\n   * static readonly dependencies: PluginDependency[] = [\n   *   { name: 'editing', required: true, reason: 'Tracks cell edits for undo/redo' },\n   *   { name: 'selection', required: false, reason: 'Enables selection-based undo' },\n   * ];\n   * ```\n   */\n  static readonly dependencies?: PluginDependency[];\n\n  /**\n   * Plugin manifest - declares owned properties, config rules, and hook priorities.\n   *\n   * This is read by the configuration validator to:\n   * - Validate that required plugins are loaded when their properties are used\n   * - Execute configRules to detect invalid/conflicting settings\n   * - Order hook execution based on priority\n   *\n   * @example\n   * ```typescript\n   * static override readonly manifest: PluginManifest<MyConfig> = {\n   *   ownedProperties: [\n   *     { property: 'myProp', level: 'column', description: 'the \"myProp\" column property' },\n   *   ],\n   *   configRules: [\n   *     { id: 'myPlugin/conflict', severity: 'warn', message: '...', check: (c) => c.a && c.b },\n   *   ],\n   * };\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  static readonly manifest?: PluginManifest<any>;\n\n  /** Unique plugin identifier (derived from class name by default) */\n  abstract readonly name: string;\n\n  /**\n   * Plugin version - defaults to grid version for built-in plugins.\n   * Third-party plugins can override with their own semver.\n   */\n  readonly version: string = typeof __GRID_VERSION__ !== 'undefined' ? __GRID_VERSION__ : 'dev';\n\n  /** CSS styles to inject into the grid's shadow DOM */\n  readonly styles?: string;\n\n  /** Custom cell renderers keyed by type name */\n  readonly cellRenderers?: Record<string, CellRenderer>;\n\n  /** Custom header renderers keyed by type name */\n  readonly headerRenderers?: Record<string, HeaderRenderer>;\n\n  /** Custom cell editors keyed by type name */\n  readonly cellEditors?: Record<string, CellEditor>;\n\n  /** The grid instance this plugin is attached to */\n  protected grid!: GridElement;\n\n  /** Plugin configuration - merged with defaults in attach() */\n  protected config!: TConfig;\n\n  /** User-provided configuration from constructor */\n  protected readonly userConfig: Partial<TConfig>;\n\n  /**\n   * Plugin-level AbortController for event listener cleanup.\n   * Created fresh in attach(), aborted in detach().\n   * This ensures event listeners are properly cleaned up when plugins are re-attached.\n   */\n  #abortController?: AbortController;\n\n  /**\n   * Default configuration - subclasses should override this getter.\n   * Note: This must be a getter (not property initializer) for proper inheritance\n   * since property initializers run after parent constructor.\n   */\n  protected get defaultConfig(): Partial<TConfig> {\n    return {};\n  }\n\n  constructor(config: Partial<TConfig> = {}) {\n    this.userConfig = config;\n  }\n\n  /**\n   * Called when the plugin is attached to a grid.\n   * Override to set up event listeners, initialize state, etc.\n   *\n   * @example\n   * ```ts\n   * attach(grid: GridElement): void {\n   *   super.attach(grid);\n   *   // Set up document-level listeners with auto-cleanup\n   *   document.addEventListener('keydown', this.handleEscape, {\n   *     signal: this.disconnectSignal\n   *   });\n   * }\n   * ```\n   */\n  attach(grid: GridElement): void {\n    // Abort any previous abort controller (in case of re-attach without detach)\n    this.#abortController?.abort();\n    // Create fresh abort controller for this attachment\n    this.#abortController = new AbortController();\n\n    this.grid = grid;\n    // Merge config here (after subclass construction is complete)\n    this.config = { ...this.defaultConfig, ...this.userConfig } as TConfig;\n  }\n\n  /**\n   * Called when the plugin is detached from a grid.\n   * Override to clean up event listeners, timers, etc.\n   *\n   * @example\n   * ```ts\n   * detach(): void {\n   *   // Clean up any state not handled by disconnectSignal\n   *   this.selectedRows.clear();\n   *   this.cache = null;\n   * }\n   * ```\n   */\n  detach(): void {\n    // Abort the plugin's abort controller to clean up all event listeners\n    // registered with { signal: this.disconnectSignal }\n    this.#abortController?.abort();\n    this.#abortController = undefined;\n    // Override in subclass for additional cleanup\n  }\n\n  /**\n   * Called when another plugin is attached to the same grid.\n   * Use for inter-plugin coordination, e.g., to integrate with new plugins.\n   *\n   * @param name - The name of the plugin that was attached\n   * @param plugin - The plugin instance (for direct access if needed)\n   *\n   * @example\n   * ```ts\n   * onPluginAttached(name: string, plugin: BaseGridPlugin): void {\n   *   if (name === 'selection') {\n   *     // Integrate with selection plugin\n   *     this.selectionPlugin = plugin as SelectionPlugin;\n   *   }\n   * }\n   * ```\n   */\n  onPluginAttached?(name: string, plugin: BaseGridPlugin): void;\n\n  /**\n   * Called when another plugin is detached from the same grid.\n   * Use to clean up inter-plugin references.\n   *\n   * @param name - The name of the plugin that was detached\n   *\n   * @example\n   * ```ts\n   * onPluginDetached(name: string): void {\n   *   if (name === 'selection') {\n   *     this.selectionPlugin = undefined;\n   *   }\n   * }\n   * ```\n   */\n  onPluginDetached?(name: string): void;\n\n  /**\n   * Get another plugin instance from the same grid.\n   * Use for inter-plugin communication.\n   *\n   * @example\n   * ```ts\n   * const selection = this.getPlugin(SelectionPlugin);\n   * if (selection) {\n   *   const selectedRows = selection.getSelectedRows();\n   * }\n   * ```\n   */\n  protected getPlugin<T extends BaseGridPlugin>(PluginClass: new (...args: any[]) => T): T | undefined {\n    return this.grid?.getPlugin(PluginClass);\n  }\n\n  /**\n   * Emit a custom event from the grid.\n   */\n  protected emit<T>(eventName: string, detail: T): void {\n    this.grid?.dispatchEvent?.(new CustomEvent(eventName, { detail, bubbles: true }));\n  }\n\n  /**\n   * Emit a cancelable custom event from the grid.\n   * @returns `true` if the event was cancelled (preventDefault called), `false` otherwise\n   */\n  protected emitCancelable<T>(eventName: string, detail: T): boolean {\n    const event = new CustomEvent(eventName, { detail, bubbles: true, cancelable: true });\n    this.grid?.dispatchEvent?.(event);\n    return event.defaultPrevented;\n  }\n\n  // =========================================================================\n  // Event Bus - Plugin-to-Plugin Communication\n  // =========================================================================\n\n  /**\n   * Subscribe to an event from another plugin.\n   * The subscription is automatically cleaned up when this plugin is detached.\n   *\n   * @category Plugin Development\n   * @param eventType - The event type to listen for (e.g., 'filter-change')\n   * @param callback - The callback to invoke when the event is emitted\n   *\n   * @example\n   * ```typescript\n   * // In attach() or other initialization\n   * this.on('filter-change', (detail) => {\n   *   console.log('Filter changed:', detail);\n   * });\n   * ```\n   */\n  protected on<T = unknown>(eventType: string, callback: (detail: T) => void): void {\n    this.grid?._pluginManager?.subscribe(this, eventType, callback as (detail: unknown) => void);\n  }\n\n  /**\n   * Unsubscribe from a plugin event.\n   *\n   * @category Plugin Development\n   * @param eventType - The event type to stop listening for\n   *\n   * @example\n   * ```typescript\n   * this.off('filter-change');\n   * ```\n   */\n  protected off(eventType: string): void {\n    this.grid?._pluginManager?.unsubscribe(this, eventType);\n  }\n\n  /**\n   * Emit an event to other plugins via the Event Bus.\n   * This is for inter-plugin communication only; it does NOT dispatch DOM events.\n   * Use `emit()` to dispatch DOM events that external consumers can listen to.\n   *\n   * @category Plugin Development\n   * @param eventType - The event type to emit (should be declared in manifest.events)\n   * @param detail - The event payload\n   *\n   * @example\n   * ```typescript\n   * // Emit to other plugins (not DOM)\n   * this.emitPluginEvent('filter-change', { field: 'name', value: 'Alice' });\n   *\n   * // For DOM events that consumers can addEventListener to:\n   * this.emit('filter-change', { field: 'name', value: 'Alice' });\n   * ```\n   */\n  protected emitPluginEvent<T>(eventType: string, detail: T): void {\n    this.grid?._pluginManager?.emitPluginEvent(eventType, detail);\n  }\n\n  /**\n   * Request a re-render of the grid.\n   * Uses ROWS phase - does NOT trigger processColumns hooks.\n   */\n  protected requestRender(): void {\n    this.grid?.requestRender?.();\n  }\n\n  /**\n   * Request a columns re-render of the grid.\n   * Uses COLUMNS phase - triggers processColumns hooks.\n   * Use this when your plugin needs to reprocess column configuration.\n   */\n  protected requestColumnsRender(): void {\n    (this.grid as { requestColumnsRender?: () => void })?.requestColumnsRender?.();\n  }\n\n  /**\n   * Request a re-render and restore focus styling afterward.\n   * Use this when a plugin action (like expand/collapse) triggers a render\n   * but needs to maintain keyboard navigation focus.\n   */\n  protected requestRenderWithFocus(): void {\n    this.grid?.requestRenderWithFocus?.();\n  }\n\n  /**\n   * Request a lightweight style update without rebuilding DOM.\n   * Use this instead of requestRender() when only CSS classes need updating.\n   */\n  protected requestAfterRender(): void {\n    this.grid?.requestAfterRender?.();\n  }\n\n  /**\n   * Get the current rows from the grid.\n   */\n  protected get rows(): any[] {\n    return this.grid?.rows ?? [];\n  }\n\n  /**\n   * Get the original unfiltered/unprocessed rows from the grid.\n   * Use this when you need all source data regardless of active filters.\n   */\n  protected get sourceRows(): any[] {\n    return this.grid?.sourceRows ?? [];\n  }\n\n  /**\n   * Get the current columns from the grid.\n   */\n  protected get columns(): ColumnConfig[] {\n    return this.grid?.columns ?? [];\n  }\n\n  /**\n   * Get only visible columns from the grid (excludes hidden).\n   * Use this for rendering that needs to match the grid template.\n   */\n  protected get visibleColumns(): ColumnConfig[] {\n    return this.grid?._visibleColumns ?? [];\n  }\n\n  /**\n   * Get the grid as an HTMLElement for direct DOM operations.\n   * Use sparingly - prefer the typed GridElementRef API when possible.\n   *\n   * @example\n   * ```ts\n   * const width = this.gridElement.clientWidth;\n   * this.gridElement.classList.add('my-plugin-active');\n   * ```\n   */\n  protected get gridElement(): HTMLElement {\n    return this.grid as unknown as HTMLElement;\n  }\n\n  /**\n   * Get the disconnect signal for event listener cleanup.\n   * This signal is aborted when the grid disconnects from the DOM.\n   * Use this when adding event listeners that should be cleaned up automatically.\n   *\n   * Best for:\n   * - Document/window-level listeners added in attach()\n   * - Listeners on the grid element itself\n   * - Any listener that should persist across renders\n   *\n   * Not needed for:\n   * - Listeners on elements created in afterRender() (removed with element)\n   *\n   * @example\n   * element.addEventListener('click', handler, { signal: this.disconnectSignal });\n   * document.addEventListener('keydown', handler, { signal: this.disconnectSignal });\n   */\n  protected get disconnectSignal(): AbortSignal {\n    // Return the plugin's own abort signal for proper cleanup on detach/re-attach\n    // Falls back to grid's signal if plugin's controller not yet created\n    return this.#abortController?.signal ?? this.grid?.disconnectSignal;\n  }\n\n  /**\n   * Get the grid-level icons configuration.\n   * Returns merged icons (user config + defaults).\n   */\n  protected get gridIcons(): typeof DEFAULT_GRID_ICONS {\n    const userIcons = this.grid?.gridConfig?.icons ?? {};\n    return { ...DEFAULT_GRID_ICONS, ...userIcons };\n  }\n\n  // #region Animation Helpers\n\n  /**\n   * Check if animations are enabled at the grid level.\n   * Respects gridConfig.animation.mode and the CSS variable set by the grid.\n   *\n   * Plugins should use this to skip animations when:\n   * - Animation mode is 'off' or `false`\n   * - User prefers reduced motion and mode is 'reduced-motion' (default)\n   *\n   * @example\n   * ```ts\n   * private get animationStyle(): 'slide' | 'fade' | false {\n   *   if (!this.isAnimationEnabled) return false;\n   *   return this.config.animation ?? 'slide';\n   * }\n   * ```\n   */\n  protected get isAnimationEnabled(): boolean {\n    const mode = this.grid?.effectiveConfig?.animation?.mode ?? 'reduced-motion';\n\n    // Explicit off = disabled\n    if (mode === false || mode === 'off') return false;\n\n    // Explicit on = always enabled\n    if (mode === true || mode === 'on') return true;\n\n    // reduced-motion: check CSS variable (set by grid based on media query)\n    const host = this.gridElement;\n    if (host) {\n      const enabled = getComputedStyle(host).getPropertyValue('--tbw-animation-enabled').trim();\n      return enabled !== '0';\n    }\n\n    return true; // Default to enabled\n  }\n\n  /**\n   * Get the animation duration in milliseconds from CSS variable.\n   * Falls back to 200ms if not set.\n   *\n   * Plugins can use this for their animation timing to stay consistent\n   * with the grid-level animation.duration setting.\n   *\n   * @example\n   * ```ts\n   * element.animate(keyframes, { duration: this.animationDuration });\n   * ```\n   */\n  protected get animationDuration(): number {\n    const host = this.gridElement;\n    if (host) {\n      const durationStr = getComputedStyle(host).getPropertyValue('--tbw-animation-duration').trim();\n      const parsed = parseInt(durationStr, 10);\n      if (!isNaN(parsed)) return parsed;\n    }\n    return 200; // Default\n  }\n\n  // #endregion\n\n  /**\n   * Resolve an icon value to string or HTMLElement.\n   * Checks plugin config first, then grid-level icons, then defaults.\n   *\n   * @param iconKey - The icon key in GridIcons (e.g., 'expand', 'collapse')\n   * @param pluginOverride - Optional plugin-level override\n   * @returns The resolved icon value\n   */\n  protected resolveIcon(iconKey: keyof typeof DEFAULT_GRID_ICONS, pluginOverride?: IconValue): IconValue {\n    // Plugin override takes precedence\n    if (pluginOverride !== undefined) {\n      return pluginOverride;\n    }\n    // Then grid-level config\n    return this.gridIcons[iconKey];\n  }\n\n  /**\n   * Set an icon value on an element.\n   * Handles both string (text/HTML) and HTMLElement values.\n   *\n   * @param element - The element to set the icon on\n   * @param icon - The icon value (string or HTMLElement)\n   */\n  protected setIcon(element: HTMLElement, icon: IconValue): void {\n    if (typeof icon === 'string') {\n      element.innerHTML = icon;\n    } else if (icon instanceof HTMLElement) {\n      element.innerHTML = '';\n      element.appendChild(icon.cloneNode(true));\n    }\n  }\n\n  /**\n   * Log a warning message.\n   */\n  protected warn(message: string): void {\n    console.warn(`[tbw-grid:${this.name}] ${message}`);\n  }\n\n  // #region Lifecycle Hooks\n\n  /**\n   * Transform rows before rendering.\n   * Called during each render cycle before rows are rendered to the DOM.\n   * Use this to filter, sort, or add computed properties to rows.\n   *\n   * @param rows - The current rows array (readonly to encourage returning a new array)\n   * @returns The modified rows array to render\n   *\n   * @example\n   * ```ts\n   * processRows(rows: readonly any[]): any[] {\n   *   // Filter out hidden rows\n   *   return rows.filter(row => !row._hidden);\n   * }\n   * ```\n   *\n   * @example\n   * ```ts\n   * processRows(rows: readonly any[]): any[] {\n   *   // Add computed properties\n   *   return rows.map(row => ({\n   *     ...row,\n   *     _fullName: `${row.firstName} ${row.lastName}`\n   *   }));\n   * }\n   * ```\n   */\n  processRows?(rows: readonly any[]): any[];\n\n  /**\n   * Transform columns before rendering.\n   * Called during each render cycle before column headers and cells are rendered.\n   * Use this to add, remove, or modify column definitions.\n   *\n   * @param columns - The current columns array (readonly to encourage returning a new array)\n   * @returns The modified columns array to render\n   *\n   * @example\n   * ```ts\n   * processColumns(columns: readonly ColumnConfig[]): ColumnConfig[] {\n   *   // Add a selection checkbox column\n   *   return [\n   *     { field: '_select', header: '', width: 40 },\n   *     ...columns\n   *   ];\n   * }\n   * ```\n   */\n  processColumns?(columns: readonly ColumnConfig[]): ColumnConfig[];\n\n  /**\n   * Called before each render cycle begins.\n   * Use this to prepare state or cache values needed during rendering.\n   *\n   * **Note:** This hook is currently a placeholder for future implementation.\n   * It is defined in the interface but not yet invoked by the grid's render pipeline.\n   * If you need this functionality, please open an issue or contribute an implementation.\n   *\n   * @example\n   * ```ts\n   * beforeRender(): void {\n   *   this.visibleRowCount = this.calculateVisibleRows();\n   * }\n   * ```\n   */\n  beforeRender?(): void;\n\n  /**\n   * Called after each render cycle completes.\n   * Use this for DOM manipulation, adding event listeners to rendered elements,\n   * or applying visual effects like selection highlights.\n   *\n   * @example\n   * ```ts\n   * afterRender(): void {\n   *   // Apply selection styling to rendered rows\n   *   const rows = this.gridElement?.querySelectorAll('.data-row');\n   *   rows?.forEach((row, i) => {\n   *     row.classList.toggle('selected', this.selectedRows.has(i));\n   *   });\n   * }\n   * ```\n   */\n  afterRender?(): void;\n\n  /**\n   * Called after each cell is rendered.\n   * This hook is more efficient than `afterRender()` for cell-level modifications\n   * because you receive the cell context directly - no DOM queries needed.\n   *\n   * Use cases:\n   * - Adding selection/highlight classes to specific cells\n   * - Injecting badges or decorations\n   * - Applying conditional styling based on cell value\n   *\n   * Performance note: Called for every visible cell during render. Keep implementation fast.\n   * This hook is also called during scroll when cells are recycled.\n   *\n   * @param context - The cell render context with row, column, value, and elements\n   *\n   * @example\n   * ```ts\n   * afterCellRender(context: AfterCellRenderContext): void {\n   *   // Add selection class without DOM queries\n   *   if (this.isSelected(context.rowIndex, context.colIndex)) {\n   *     context.cellElement.classList.add('selected');\n   *   }\n   *\n   *   // Add validation error styling\n   *   if (this.hasError(context.row, context.column.field)) {\n   *     context.cellElement.classList.add('has-error');\n   *   }\n   * }\n   * ```\n   */\n  afterCellRender?(context: AfterCellRenderContext): void;\n\n  /**\n   * Called after a row is fully rendered (all cells complete).\n   * Use this for row-level decorations, styling, or ARIA attributes.\n   *\n   * Common use cases:\n   * - Adding selection classes to entire rows (row-focus, selected)\n   * - Setting row-level ARIA attributes\n   * - Applying row validation highlighting\n   * - Tree indentation styling\n   *\n   * Performance note: Called for every visible row during render. Keep implementation fast.\n   * This hook is also called during scroll when rows are recycled.\n   *\n   * @param context - The row render context with row data and element\n   *\n   * @example\n   * ```ts\n   * afterRowRender(context: AfterRowRenderContext): void {\n   *   // Add row selection class without DOM queries\n   *   if (this.isRowSelected(context.rowIndex)) {\n   *     context.rowElement.classList.add('selected', 'row-focus');\n   *   }\n   *\n   *   // Add validation error styling\n   *   if (this.rowHasErrors(context.row)) {\n   *     context.rowElement.classList.add('has-errors');\n   *   }\n   * }\n   * ```\n   */\n  afterRowRender?(context: AfterRowRenderContext): void;\n\n  /**\n   * Called after scroll-triggered row rendering completes.\n   * This is a lightweight hook for applying visual state to recycled DOM elements.\n   * Use this instead of afterRender when you need to reapply styling during scroll.\n   *\n   * Performance note: This is called frequently during scroll. Keep implementation fast.\n   *\n   * @example\n   * ```ts\n   * onScrollRender(): void {\n   *   // Reapply selection state to visible cells\n   *   this.applySelectionToVisibleCells();\n   * }\n   * ```\n   */\n  onScrollRender?(): void;\n\n  /**\n   * Return extra height contributed by this plugin (e.g., expanded detail rows).\n   * Used to adjust scrollbar height calculations for virtualization.\n   *\n   * @returns Total extra height in pixels\n   *\n   * @deprecated Use {@link getRowHeight} instead. This hook will be removed in v3.0.\n   * The new `getRowHeight(row, index)` hook provides per-row height information which\n   * enables better position caching and variable row height support.\n   *\n   * @example\n   * ```ts\n   * // OLD (deprecated):\n   * getExtraHeight(): number {\n   *   return this.expandedRows.size * this.detailHeight;\n   * }\n   *\n   * // NEW (preferred):\n   * getRowHeight(row: unknown, index: number): number | undefined {\n   *   if (this.isExpanded(row)) {\n   *     return this.baseRowHeight + this.getDetailHeight(row);\n   *   }\n   *   return undefined;\n   * }\n   * ```\n   */\n  getExtraHeight?(): number;\n\n  /**\n   * Return extra height that appears before a given row index.\n   * Used by virtualization to correctly calculate scroll positions when\n   * there's variable height content (like expanded detail rows) above the viewport.\n   *\n   * @param beforeRowIndex - The row index to calculate extra height before\n   * @returns Extra height in pixels that appears before this row\n   *\n   * @deprecated Use {@link getRowHeight} instead. This hook will be removed in v3.0.\n   * The new `getRowHeight(row, index)` hook provides per-row height information which\n   * enables better position caching and variable row height support.\n   *\n   * @example\n   * ```ts\n   * // OLD (deprecated):\n   * getExtraHeightBefore(beforeRowIndex: number): number {\n   *   let height = 0;\n   *   for (const expandedRowIndex of this.expandedRowIndices) {\n   *     if (expandedRowIndex < beforeRowIndex) {\n   *       height += this.getDetailHeight(expandedRowIndex);\n   *     }\n   *   }\n   *   return height;\n   * }\n   *\n   * // NEW (preferred):\n   * getRowHeight(row: unknown, index: number): number | undefined {\n   *   if (this.isExpanded(row)) {\n   *     return this.baseRowHeight + this.getDetailHeight(row);\n   *   }\n   *   return undefined;\n   * }\n   * ```\n   */\n  getExtraHeightBefore?(beforeRowIndex: number): number;\n\n  /**\n   * Get the height of a specific row.\n   * Used for synthetic rows (group headers, detail panels, etc.) that have fixed heights.\n   * Return undefined if this plugin does not manage the height for this row.\n   *\n   * This hook is called during position cache rebuilds for variable row height virtualization.\n   * Plugins that create synthetic rows should implement this to provide accurate heights.\n   *\n   * @param row - The row data\n   * @param index - The row index in the processed rows array\n   * @returns The row height in pixels, or undefined if not managed by this plugin\n   *\n   * @example\n   * ```ts\n   * getRowHeight(row: unknown, index: number): number | undefined {\n   *   // Group headers have a fixed height\n   *   if (this.isGroupHeader(row)) {\n   *     return 32;\n   *   }\n   *   return undefined; // Let grid use default/measured height\n   * }\n   * ```\n   */\n  getRowHeight?(row: unknown, index: number): number | undefined;\n\n  /**\n   * Adjust the virtualization start index to render additional rows before the visible range.\n   * Use this when expanded content (like detail rows) needs its parent row to remain rendered\n   * even when the parent row itself has scrolled above the viewport.\n   *\n   * @param start - The calculated start row index\n   * @param scrollTop - The current scroll position\n   * @param rowHeight - The height of a single row\n   * @returns The adjusted start index (lower than or equal to original start)\n   *\n   * @example\n   * ```ts\n   * adjustVirtualStart(start: number, scrollTop: number, rowHeight: number): number {\n   *   // If row 5 is expanded and scrolled partially, keep it rendered\n   *   for (const expandedRowIndex of this.expandedRowIndices) {\n   *     const expandedRowTop = expandedRowIndex * rowHeight;\n   *     const expandedRowBottom = expandedRowTop + rowHeight + this.detailHeight;\n   *     if (expandedRowBottom > scrollTop && expandedRowIndex < start) {\n   *       return expandedRowIndex;\n   *     }\n   *   }\n   *   return start;\n   * }\n   * ```\n   */\n  adjustVirtualStart?(start: number, scrollTop: number, rowHeight: number): number;\n\n  /**\n   * Render a custom row, bypassing the default row rendering.\n   * Use this for special row types like group headers, detail rows, or footers.\n   *\n   * @param row - The row data object\n   * @param rowEl - The row DOM element to render into\n   * @param rowIndex - The index of the row in the data array\n   * @returns `true` if the plugin handled rendering (prevents default), `false`/`void` for default rendering\n   *\n   * @example\n   * ```ts\n   * renderRow(row: any, rowEl: HTMLElement, rowIndex: number): boolean | void {\n   *   if (row._isGroupHeader) {\n   *     rowEl.innerHTML = `<div class=\"group-header\">${row._groupLabel}</div>`;\n   *     return true; // Handled - skip default rendering\n   *   }\n   *   // Return void to let default rendering proceed\n   * }\n   * ```\n   */\n  renderRow?(row: any, rowEl: HTMLElement, rowIndex: number): boolean | void;\n\n  // #endregion\n\n  // #region Inter-Plugin Communication\n\n  /**\n   * Handle queries from other plugins.\n   * This is the generic mechanism for inter-plugin communication.\n   * Plugins can respond to well-known query types or define their own.\n   *\n   * **Prefer `handleQuery` for new plugins** - it has the same signature but\n   * a clearer name. `onPluginQuery` is kept for backwards compatibility.\n   *\n   * @category Plugin Development\n   * @param query - The query object with type and context\n   * @returns Query-specific response, or undefined if not handling this query\n   *\n   * @example\n   * ```ts\n   * onPluginQuery(query: PluginQuery): unknown {\n   *   switch (query.type) {\n   *     case PLUGIN_QUERIES.CAN_MOVE_COLUMN:\n   *       // Prevent moving pinned columns\n   *       const column = query.context as ColumnConfig;\n   *       if (column.sticky === 'left' || column.sticky === 'right') {\n   *         return false;\n   *       }\n   *       break;\n   *     case PLUGIN_QUERIES.GET_CONTEXT_MENU_ITEMS:\n   *       const params = query.context as ContextMenuParams;\n   *       return [{ id: 'my-action', label: 'My Action', action: () => {} }];\n   *   }\n   * }\n   * ```\n   * @deprecated Use `handleQuery` instead for new plugins.\n   */\n  onPluginQuery?(query: PluginQuery): unknown;\n\n  /**\n   * Handle queries from other plugins or the grid.\n   *\n   * Queries are declared in `manifest.queries` and dispatched via `grid.query()`.\n   * This enables type-safe, discoverable inter-plugin communication.\n   *\n   * @category Plugin Development\n   * @param query - The query object with type and context\n   * @returns Query-specific response, or undefined if not handling this query\n   *\n   * @example\n   * ```ts\n   * // In manifest\n   * static override readonly manifest: PluginManifest = {\n   *   queries: [\n   *     { type: 'canMoveColumn', description: 'Check if a column can be moved' },\n   *   ],\n   * };\n   *\n   * // In plugin class\n   * handleQuery(query: PluginQuery): unknown {\n   *   if (query.type === 'canMoveColumn') {\n   *     const column = query.context as ColumnConfig;\n   *     return !column.sticky; // Can't move sticky columns\n   *   }\n   * }\n   * ```\n   */\n  handleQuery?(query: PluginQuery): unknown;\n\n  // #endregion\n\n  // #region Interaction Hooks\n\n  /**\n   * Handle keyboard events on the grid.\n   * Called when a key is pressed while the grid or a cell has focus.\n   *\n   * @param event - The native KeyboardEvent\n   * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default\n   *\n   * @example\n   * ```ts\n   * onKeyDown(event: KeyboardEvent): boolean | void {\n   *   // Handle Ctrl+A for select all\n   *   if (event.ctrlKey && event.key === 'a') {\n   *     this.selectAllRows();\n   *     return true; // Prevent default browser select-all\n   *   }\n   * }\n   * ```\n   */\n  onKeyDown?(event: KeyboardEvent): boolean | void;\n\n  /**\n   * Handle cell click events.\n   * Called when a data cell is clicked (not headers).\n   *\n   * @param event - Cell click event with row/column context\n   * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default\n   *\n   * @example\n   * ```ts\n   * onCellClick(event: CellClickEvent): boolean | void {\n   *   if (event.field === '_select') {\n   *     this.toggleRowSelection(event.rowIndex);\n   *     return true; // Handled\n   *   }\n   * }\n   * ```\n   */\n  onCellClick?(event: CellClickEvent): boolean | void;\n\n  /**\n   * Handle row click events.\n   * Called when any part of a data row is clicked.\n   * Note: This is called in addition to onCellClick, not instead of.\n   *\n   * @param event - Row click event with row context\n   * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default\n   *\n   * @example\n   * ```ts\n   * onRowClick(event: RowClickEvent): boolean | void {\n   *   if (this.config.mode === 'row') {\n   *     this.selectRow(event.rowIndex, event.originalEvent);\n   *     return true;\n   *   }\n   * }\n   * ```\n   */\n  onRowClick?(event: RowClickEvent): boolean | void;\n\n  /**\n   * Handle header click events.\n   * Called when a column header is clicked. Commonly used for sorting.\n   *\n   * @param event - Header click event with column context\n   * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default\n   *\n   * @example\n   * ```ts\n   * onHeaderClick(event: HeaderClickEvent): boolean | void {\n   *   if (event.column.sortable !== false) {\n   *     this.toggleSort(event.field);\n   *     return true;\n   *   }\n   * }\n   * ```\n   */\n  onHeaderClick?(event: HeaderClickEvent): boolean | void;\n\n  /**\n   * Handle scroll events on the grid viewport.\n   * Called during scrolling. Note: This may be called frequently; debounce if needed.\n   *\n   * @param event - Scroll event with scroll position and viewport dimensions\n   *\n   * @example\n   * ```ts\n   * onScroll(event: ScrollEvent): void {\n   *   // Update sticky column positions\n   *   this.updateStickyPositions(event.scrollLeft);\n   * }\n   * ```\n   */\n  onScroll?(event: ScrollEvent): void;\n\n  /**\n   * Handle cell mousedown events.\n   * Used for initiating drag operations like range selection or column resize.\n   *\n   * @param event - Mouse event with cell context\n   * @returns `true` to indicate drag started (prevents text selection), `false`/`void` otherwise\n   *\n   * @example\n   * ```ts\n   * onCellMouseDown(event: CellMouseEvent): boolean | void {\n   *   if (event.rowIndex !== undefined && this.config.mode === 'range') {\n   *     this.startDragSelection(event.rowIndex, event.colIndex);\n   *     return true; // Prevent text selection\n   *   }\n   * }\n   * ```\n   */\n  onCellMouseDown?(event: CellMouseEvent): boolean | void;\n\n  /**\n   * Handle cell mousemove events during drag operations.\n   * Only called when a drag is in progress (after mousedown returned true).\n   *\n   * @param event - Mouse event with current cell context\n   * @returns `true` to continue handling the drag, `false`/`void` otherwise\n   *\n   * @example\n   * ```ts\n   * onCellMouseMove(event: CellMouseEvent): boolean | void {\n   *   if (this.isDragging && event.rowIndex !== undefined) {\n   *     this.extendSelection(event.rowIndex, event.colIndex);\n   *     return true;\n   *   }\n   * }\n   * ```\n   */\n  onCellMouseMove?(event: CellMouseEvent): boolean | void;\n\n  /**\n   * Handle cell mouseup events to end drag operations.\n   *\n   * @param event - Mouse event with final cell context\n   * @returns `true` if drag was finalized, `false`/`void` otherwise\n   *\n   * @example\n   * ```ts\n   * onCellMouseUp(event: CellMouseEvent): boolean | void {\n   *   if (this.isDragging) {\n   *     this.finalizeDragSelection();\n   *     this.isDragging = false;\n   *     return true;\n   *   }\n   * }\n   * ```\n   */\n  onCellMouseUp?(event: CellMouseEvent): boolean | void;\n\n  // Note: Context menu items are provided via handleQuery('getContextMenuItems').\n  // This keeps the core decoupled from the context-menu plugin specifics.\n\n  // #endregion\n\n  // #region Column State Hooks\n\n  /**\n   * Contribute plugin-specific state for a column.\n   * Called by the grid when collecting column state for serialization.\n   * Plugins can add their own properties to the column state.\n   *\n   * @param field - The field name of the column\n   * @returns Partial column state with plugin-specific properties, or undefined if no state to contribute\n   *\n   * @example\n   * ```ts\n   * getColumnState(field: string): Partial<ColumnState> | undefined {\n   *   const filterModel = this.filterModels.get(field);\n   *   if (filterModel) {\n   *     // Uses module augmentation to add filter property to ColumnState\n   *     return { filter: filterModel } as Partial<ColumnState>;\n   *   }\n   *   return undefined;\n   * }\n   * ```\n   */\n  getColumnState?(field: string): Partial<ColumnState> | undefined;\n\n  /**\n   * Apply plugin-specific state to a column.\n   * Called by the grid when restoring column state from serialized data.\n   * Plugins should restore their internal state based on the provided state.\n   *\n   * @param field - The field name of the column\n   * @param state - The column state to apply (may contain plugin-specific properties)\n   *\n   * @example\n   * ```ts\n   * applyColumnState(field: string, state: ColumnState): void {\n   *   // Check for filter property added via module augmentation\n   *   const filter = (state as any).filter;\n   *   if (filter) {\n   *     this.filterModels.set(field, filter);\n   *     this.applyFilter();\n   *   }\n   * }\n   * ```\n   */\n  applyColumnState?(field: string, state: ColumnState): void;\n\n  // #endregion\n\n  // #region Scroll Boundary Hooks\n\n  /**\n   * Report horizontal scroll boundary offsets for this plugin.\n   * Plugins that obscure part of the scroll area (e.g., pinned/sticky columns)\n   * should return how much space they occupy on each side.\n   * The keyboard navigation uses this to ensure focused cells are fully visible.\n   *\n   * @param rowEl - The row element (optional, for calculating widths from rendered cells)\n   * @param focusedCell - The currently focused cell element (optional, to determine if scrolling should be skipped)\n   * @returns Object with left/right pixel offsets and optional skipScroll flag, or undefined if plugin has no offsets\n   *\n   * @example\n   * ```ts\n   * getHorizontalScrollOffsets(rowEl?: HTMLElement, focusedCell?: HTMLElement): { left: number; right: number; skipScroll?: boolean } | undefined {\n   *   // Calculate total width of left-pinned columns\n   *   const leftCells = rowEl?.querySelectorAll('.sticky-left') ?? [];\n   *   let left = 0;\n   *   leftCells.forEach(el => { left += (el as HTMLElement).offsetWidth; });\n   *   // Skip scroll if focused cell is pinned (always visible)\n   *   const skipScroll = focusedCell?.classList.contains('sticky-left');\n   *   return { left, right: 0, skipScroll };\n   * }\n   * ```\n   */\n  getHorizontalScrollOffsets?(\n    rowEl?: HTMLElement,\n    focusedCell?: HTMLElement,\n  ): { left: number; right: number; skipScroll?: boolean } | undefined;\n\n  // #endregion\n\n  // #region Shell Integration Hooks\n\n  /**\n   * Register a tool panel for this plugin.\n   * Return undefined if plugin has no tool panel.\n   * The shell will create a toolbar toggle button and render the panel content\n   * when the user opens the panel.\n   *\n   * @returns Tool panel definition, or undefined if plugin has no panel\n   *\n   * @example\n   * ```ts\n   * getToolPanel(): ToolPanelDefinition | undefined {\n   *   return {\n   *     id: 'columns',\n   *     title: 'Columns',\n   *     icon: '☰',\n   *     tooltip: 'Show/hide columns',\n   *     order: 10,\n   *     render: (container) => {\n   *       this.renderColumnList(container);\n   *       return () => this.cleanup();\n   *     },\n   *   };\n   * }\n   * ```\n   */\n  getToolPanel?(): ToolPanelDefinition | undefined;\n\n  /**\n   * Register content for the shell header center section.\n   * Return undefined if plugin has no header content.\n   * Examples: search input, selection summary, status indicators.\n   *\n   * @returns Header content definition, or undefined if plugin has no header content\n   *\n   * @example\n   * ```ts\n   * getHeaderContent(): HeaderContentDefinition | undefined {\n   *   return {\n   *     id: 'quick-filter',\n   *     order: 10,\n   *     render: (container) => {\n   *       const input = document.createElement('input');\n   *       input.type = 'text';\n   *       input.placeholder = 'Search...';\n   *       input.addEventListener('input', this.handleInput);\n   *       container.appendChild(input);\n   *       return () => input.removeEventListener('input', this.handleInput);\n   *     },\n   *   };\n   * }\n   * ```\n   */\n  getHeaderContent?(): HeaderContentDefinition | undefined;\n\n  // #endregion\n}\n","/**\n * Print Plugin (Class-based)\n *\n * Provides print layout functionality for tbw-grid.\n * Temporarily disables virtualization to render all rows and uses\n * @media print CSS for print-optimized styling.\n */\n\nimport { BaseGridPlugin } from '../../core/plugin/base-plugin';\nimport type { InternalGrid, ToolbarContentDefinition } from '../../core/types';\nimport { printGridIsolated } from './print-isolated';\nimport styles from './print.css?inline';\nimport type { PrintCompleteDetail, PrintConfig, PrintParams, PrintStartDetail } from './types';\n\n/**\n * Extended grid interface for PrintPlugin internal access.\n * Includes registerToolbarContent which is available on the grid class\n * but not exposed in the standard plugin API.\n */\ninterface PrintGridRef extends InternalGrid {\n  registerToolbarContent?(content: ToolbarContentDefinition): void;\n  unregisterToolbarContent?(contentId: string): void;\n}\n\n/** Default configuration */\nconst DEFAULT_CONFIG: Required<PrintConfig> = {\n  button: false,\n  orientation: 'landscape',\n  warnThreshold: 500,\n  maxRows: 0,\n  includeTitle: true,\n  includeTimestamp: true,\n  title: '',\n  isolate: false,\n};\n\n/**\n * Print Plugin for tbw-grid\n *\n * Enables printing the full grid content by temporarily disabling virtualization\n * and applying print-optimized styles. Handles large datasets gracefully with\n * configurable row limits.\n *\n * ## Installation\n *\n * ```ts\n * import { PrintPlugin } from '@toolbox-web/grid/plugins/print';\n * ```\n *\n * ## Configuration Options\n *\n * | Option | Type | Default | Description |\n * |--------|------|---------|-------------|\n * | `button` | `boolean` | `false` | Show print button in toolbar |\n * | `orientation` | `'portrait' \\| 'landscape'` | `'landscape'` | Page orientation |\n * | `warnThreshold` | `number` | `500` | Show confirmation dialog when rows exceed this (0 = no warning) |\n * | `maxRows` | `number` | `0` | Hard limit on printed rows (0 = unlimited) |\n * | `includeTitle` | `boolean` | `true` | Include grid title in print |\n * | `includeTimestamp` | `boolean` | `true` | Include timestamp in footer |\n * | `title` | `string` | `''` | Custom print title |\n *\n * ## Programmatic API\n *\n * | Method | Signature | Description |\n * |--------|-----------|-------------|\n * | `print` | `(params?) => Promise<void>` | Trigger print dialog |\n * | `isPrinting` | `() => boolean` | Check if print is in progress |\n *\n * ## Events\n *\n * | Event | Detail | Description |\n * |-------|--------|-------------|\n * | `print-start` | `PrintStartDetail` | Fired when print begins |\n * | `print-complete` | `PrintCompleteDetail` | Fired when print completes |\n *\n * @example Basic Print\n * ```ts\n * import { PrintPlugin } from '@toolbox-web/grid/plugins/print';\n *\n * const grid = document.querySelector('tbw-grid');\n * grid.gridConfig = {\n *   plugins: [new PrintPlugin()],\n * };\n *\n * // Trigger print\n * const printPlugin = grid.getPlugin(PrintPlugin);\n * await printPlugin.print();\n * ```\n *\n * @example With Toolbar Button\n * ```ts\n * grid.gridConfig = {\n *   plugins: [new PrintPlugin({ button: true, orientation: 'landscape' })],\n * };\n * ```\n *\n * @see {@link PrintConfig} for all configuration options\n */\nexport class PrintPlugin extends BaseGridPlugin<PrintConfig> {\n  /** @internal */\n  readonly name = 'print';\n\n  /** @internal */\n  override readonly version = '1.0.0';\n\n  /** CSS styles for print mode */\n  override readonly styles = styles;\n\n  /** Current print state */\n  #printing = false;\n\n  /** Saved column visibility state */\n  #savedHiddenColumns: Map<string, boolean> | null = null;\n\n  /** Saved virtualization state */\n  #savedVirtualization: { bypassThreshold: number } | null = null;\n\n  /** Saved rows when maxRows limit is applied */\n  #savedRows: unknown[] | null = null;\n\n  /** Print header element */\n  #printHeader: HTMLElement | null = null;\n\n  /** Print footer element */\n  #printFooter: HTMLElement | null = null;\n\n  /** Applied scale factor (legacy, used for cleanup) */\n  #appliedScale: number | null = null;\n\n  /**\n   * Get the grid typed as PrintGridRef for internal access.\n   */\n  get #internalGrid(): PrintGridRef {\n    return this.grid as unknown as PrintGridRef;\n  }\n\n  /**\n   * Check if print is currently in progress\n   */\n  isPrinting(): boolean {\n    return this.#printing;\n  }\n\n  /**\n   * Trigger the browser print dialog\n   *\n   * This method:\n   * 1. Validates row count against maxRows limit\n   * 2. Disables virtualization to render all rows\n   * 3. Applies print-specific CSS classes\n   * 4. Opens the browser print dialog (or isolated window if `isolate: true`)\n   * 5. Restores normal state after printing\n   *\n   * @param params - Optional parameters to override config for this print\n   * @param params.isolate - If true, prints in an isolated window containing only the grid\n   * @returns Promise that resolves when print dialog closes\n   */\n  async print(params?: PrintParams): Promise<void> {\n    if (this.#printing) {\n      console.warn('[PrintPlugin] Print already in progress');\n      return;\n    }\n\n    const grid = this.gridElement;\n    if (!grid) {\n      console.warn('[PrintPlugin] Grid not available');\n      return;\n    }\n\n    const config = { ...DEFAULT_CONFIG, ...this.config, ...params };\n    const rows = this.rows;\n    const originalRowCount = rows.length;\n    let rowCount = originalRowCount;\n    let limitApplied = false;\n\n    // Check if we should warn about large datasets\n    if (config.warnThreshold > 0 && originalRowCount > config.warnThreshold) {\n      const limitInfo =\n        config.maxRows > 0 ? `\\n\\nNote: Output will be limited to ${config.maxRows.toLocaleString()} rows.` : '';\n      const proceed = confirm(\n        `This grid has ${originalRowCount.toLocaleString()} rows. ` +\n          `Printing large datasets may cause performance issues or browser slowdowns.${limitInfo}\\n\\n` +\n          `Click OK to continue, or Cancel to abort.`,\n      );\n      if (!proceed) {\n        return;\n      }\n    }\n\n    // Apply hard row limit if configured\n    if (config.maxRows > 0 && originalRowCount > config.maxRows) {\n      rowCount = config.maxRows;\n      limitApplied = true;\n    }\n\n    this.#printing = true;\n\n    // Track timing for duration reporting\n    const startTime = performance.now();\n\n    // Emit print-start event\n    this.emit<PrintStartDetail>('print-start', {\n      rowCount,\n      limitApplied,\n      originalRowCount,\n    });\n\n    try {\n      // Save current virtualization state\n      const internalGrid = this.#internalGrid;\n      this.#savedVirtualization = {\n        bypassThreshold: internalGrid._virtualization?.bypassThreshold ?? 24,\n      };\n\n      // Hide columns marked with printHidden\n      this.#hidePrintColumns();\n\n      // Apply row limit if configured\n      if (limitApplied) {\n        this.#savedRows = this.sourceRows;\n        // Set limited rows on the grid\n        (this.grid as unknown as { rows: unknown[] }).rows = this.sourceRows.slice(0, rowCount);\n        // Wait for grid to process new rows\n        await new Promise((resolve) => setTimeout(resolve, 50));\n      }\n\n      // Add print header if configured\n      if (config.includeTitle || config.includeTimestamp) {\n        this.#addPrintHeader(config);\n      }\n\n      // Disable virtualization to render all rows\n      // This forces the grid to render all rows in the DOM\n      await this.#disableVirtualization();\n\n      // Wait for next frame to ensure DOM is updated\n      await new Promise((resolve) => requestAnimationFrame(resolve));\n      await new Promise((resolve) => requestAnimationFrame(resolve));\n\n      // Add orientation class for @page rules\n      grid.classList.add(`print-${config.orientation}`);\n\n      // Wait for next frame to ensure DOM is updated\n      await new Promise((resolve) => requestAnimationFrame(resolve));\n      await new Promise((resolve) => requestAnimationFrame(resolve));\n\n      // Trigger browser print dialog (isolated or inline)\n      if (config.isolate) {\n        await this.#printInIsolatedWindow(config);\n      } else {\n        await this.#triggerPrint();\n      }\n\n      // Emit print-complete event\n      this.emit<PrintCompleteDetail>('print-complete', {\n        success: true,\n        rowCount,\n        duration: Math.round(performance.now() - startTime),\n      });\n    } catch (error) {\n      console.error('[PrintPlugin] Print failed:', error);\n      this.emit<PrintCompleteDetail>('print-complete', {\n        success: false,\n        rowCount: 0,\n        duration: Math.round(performance.now() - startTime),\n      });\n    } finally {\n      // Restore normal state\n      this.#cleanup();\n      this.#printing = false;\n    }\n  }\n\n  /**\n   * Add print header with title and timestamp\n   */\n  #addPrintHeader(config: Required<PrintConfig>): void {\n    const grid = this.gridElement;\n    if (!grid) return;\n\n    // Create print header\n    this.#printHeader = document.createElement('div');\n    this.#printHeader.className = 'tbw-print-header';\n\n    // Title\n    if (config.includeTitle) {\n      const title = config.title || this.grid.effectiveConfig?.shell?.header?.title || 'Grid Data';\n      const titleEl = document.createElement('div');\n      titleEl.className = 'tbw-print-header-title';\n      titleEl.textContent = title;\n      this.#printHeader.appendChild(titleEl);\n    }\n\n    // Timestamp\n    if (config.includeTimestamp) {\n      const timestampEl = document.createElement('div');\n      timestampEl.className = 'tbw-print-header-timestamp';\n      timestampEl.textContent = `Printed: ${new Date().toLocaleString()}`;\n      this.#printHeader.appendChild(timestampEl);\n    }\n\n    // Insert at the beginning of the grid\n    grid.insertBefore(this.#printHeader, grid.firstChild);\n\n    // Create print footer\n    this.#printFooter = document.createElement('div');\n    this.#printFooter.className = 'tbw-print-footer';\n    this.#printFooter.textContent = `Page generated from ${window.location.hostname}`;\n    grid.appendChild(this.#printFooter);\n  }\n\n  /**\n   * Disable virtualization to render all rows\n   */\n  async #disableVirtualization(): Promise<void> {\n    const internalGrid = this.#internalGrid;\n    if (!internalGrid._virtualization) return;\n\n    // Set bypass threshold higher than total row count to disable virtualization\n    // This makes the grid render all rows (up to maxRows) instead of just visible ones\n    const totalRows = this.rows.length;\n    internalGrid._virtualization.bypassThreshold = totalRows + 100;\n\n    // Force a full refresh to re-render with virtualization disabled\n    internalGrid.refreshVirtualWindow(true);\n\n    // Wait for render to complete\n    await new Promise((resolve) => setTimeout(resolve, 100));\n  }\n\n  /**\n   * Trigger the browser print dialog\n   */\n  async #triggerPrint(): Promise<void> {\n    return new Promise((resolve) => {\n      // Listen for afterprint event\n      const onAfterPrint = () => {\n        window.removeEventListener('afterprint', onAfterPrint);\n        resolve();\n      };\n      window.addEventListener('afterprint', onAfterPrint);\n\n      // Trigger print\n      window.print();\n\n      // Fallback timeout in case afterprint doesn't fire (some browsers)\n      setTimeout(() => {\n        // Guard against test environment teardown where window may be undefined\n        if (typeof window !== 'undefined') {\n          window.removeEventListener('afterprint', onAfterPrint);\n        }\n        resolve();\n      }, 1000);\n    });\n  }\n\n  /**\n   * Print in isolation by hiding all other page content.\n   * This excludes navigation, sidebars, etc. while keeping the grid in place.\n   */\n  async #printInIsolatedWindow(config: Required<PrintConfig>): Promise<void> {\n    const grid = this.gridElement;\n    if (!grid) return;\n\n    await printGridIsolated(grid, {\n      orientation: config.orientation,\n    });\n  }\n\n  /**\n   * Hide columns marked with printHidden: true\n   */\n  #hidePrintColumns(): void {\n    const columns = this.columns;\n    if (!columns) return;\n\n    // Save current hidden state and hide print columns\n    this.#savedHiddenColumns = new Map();\n\n    for (const col of columns) {\n      if (col.printHidden && col.field) {\n        // Save current visibility state (true = visible, false = hidden)\n        this.#savedHiddenColumns.set(col.field, !col.hidden);\n        // Hide the column for printing\n        this.grid.setColumnVisible(col.field, false);\n      }\n    }\n  }\n\n  /**\n   * Restore columns that were hidden for printing\n   */\n  #restorePrintColumns(): void {\n    if (!this.#savedHiddenColumns) return;\n\n    for (const [field, wasVisible] of this.#savedHiddenColumns) {\n      // Restore original visibility\n      this.grid.setColumnVisible(field, wasVisible);\n    }\n\n    this.#savedHiddenColumns = null;\n  }\n\n  /**\n   * Cleanup after printing\n   */\n  #cleanup(): void {\n    const grid = this.gridElement;\n    if (!grid) return;\n\n    // Restore columns that were hidden for printing\n    this.#restorePrintColumns();\n\n    // Remove orientation classes (both original and possibly switched)\n    grid.classList.remove('print-portrait', 'print-landscape');\n\n    // Remove scaling transform if applied (legacy)\n    if (this.#appliedScale !== null) {\n      grid.style.transform = '';\n      grid.style.transformOrigin = '';\n      grid.style.width = '';\n      this.#appliedScale = null;\n    }\n\n    // Remove print header/footer\n    if (this.#printHeader) {\n      this.#printHeader.remove();\n      this.#printHeader = null;\n    }\n    if (this.#printFooter) {\n      this.#printFooter.remove();\n      this.#printFooter = null;\n    }\n\n    // Restore virtualization\n    const internalGrid = this.#internalGrid;\n    if (this.#savedVirtualization && internalGrid._virtualization) {\n      internalGrid._virtualization.bypassThreshold = this.#savedVirtualization.bypassThreshold;\n      internalGrid.refreshVirtualWindow(true);\n      this.#savedVirtualization = null;\n    }\n\n    // Restore original rows if they were limited\n    if (this.#savedRows !== null) {\n      (this.grid as unknown as { rows: unknown[] }).rows = this.#savedRows;\n      this.#savedRows = null;\n    }\n  }\n\n  /**\n   * Register toolbar button if configured\n   * @internal\n   */\n  override afterRender(): void {\n    // Register toolbar on first render when button is enabled\n    if (this.config?.button && !this.#toolbarRegistered) {\n      this.#registerToolbarButton();\n      this.#toolbarRegistered = true;\n    }\n  }\n\n  /** Track if toolbar button is registered */\n  #toolbarRegistered = false;\n\n  /**\n   * Register print button in toolbar\n   */\n  #registerToolbarButton(): void {\n    const grid = this.#internalGrid;\n\n    // Register toolbar content\n    grid.registerToolbarContent?.({\n      id: 'print-button',\n      order: 900, // High order to appear at the end\n      render: (container: HTMLElement) => {\n        const button = document.createElement('button');\n        button.className = 'tbw-toolbar-btn tbw-print-btn';\n        button.title = 'Print grid';\n        button.type = 'button';\n\n        // Use print icon\n        const icon = this.resolveIcon('print') || '🖨️';\n        this.setIcon(button, icon);\n\n        button.addEventListener(\n          'click',\n          () => {\n            this.print();\n          },\n          { signal: this.disconnectSignal },\n        );\n\n        container.appendChild(button);\n      },\n    });\n  }\n}\n"],"names":["ISOLATION_STYLE_ID","async","printGridIsolated","gridElement","options","orientation","gridId","id","document","querySelectorAll","CSS","escape","length","console","warn","getElementById","remove","isolationStyle","style","createElement","textContent","createIsolationStylesheet","head","appendChild","Promise","resolve","onAfterPrint","window","removeEventListener","addEventListener","print","setTimeout","DEFAULT_FILTER_ICON","DEFAULT_GRID_ICONS","expand","collapse","sortAsc","sortDesc","sortNone","submenuArrow","dragHandle","toolPanel","filter","filterActive","BaseGridPlugin","static","version","__GRID_VERSION__","styles","cellRenderers","headerRenderers","cellEditors","grid","config","userConfig","abortController","defaultConfig","constructor","this","attach","abort","AbortController","detach","getPlugin","PluginClass","emit","eventName","detail","dispatchEvent","CustomEvent","bubbles","emitCancelable","event","cancelable","defaultPrevented","on","eventType","callback","_pluginManager","subscribe","off","unsubscribe","emitPluginEvent","requestRender","requestColumnsRender","requestRenderWithFocus","requestAfterRender","rows","sourceRows","columns","visibleColumns","_visibleColumns","disconnectSignal","signal","gridIcons","userIcons","gridConfig","icons","isAnimationEnabled","mode","effectiveConfig","animation","host","getComputedStyle","getPropertyValue","trim","animationDuration","durationStr","parsed","parseInt","isNaN","resolveIcon","iconKey","pluginOverride","setIcon","element","icon","innerHTML","HTMLElement","cloneNode","message","name","DEFAULT_CONFIG","button","warnThreshold","maxRows","includeTitle","includeTimestamp","title","isolate","PrintPlugin","printing","savedHiddenColumns","savedVirtualization","savedRows","printHeader","printFooter","appliedScale","internalGrid","isPrinting","params","originalRowCount","rowCount","limitApplied","limitInfo","toLocaleString","confirm","startTime","performance","now","bypassThreshold","_virtualization","hidePrintColumns","slice","addPrintHeader","disableVirtualization","requestAnimationFrame","classList","add","printInIsolatedWindow","triggerPrint","success","duration","Math","round","error","cleanup","className","shell","header","titleEl","timestampEl","Date","insertBefore","firstChild","location","hostname","totalRows","refreshVirtualWindow","Map","col","printHidden","field","set","hidden","setColumnVisible","restorePrintColumns","wasVisible","transform","transformOrigin","width","afterRender","toolbarRegistered","registerToolbarButton","registerToolbarContent","order","render","container","type"],"mappings":"AAeA,MAAMA,EAAqB,4BAsG3BC,eAAsBC,EAAkBC,EAA0BC,EAAgC,IAChG,MAAMC,YAAEA,EAAc,aAAgBD,EAEhCE,EAASH,EAAYI,GAGJC,SAASC,iBAAiB,IAAIC,IAAIC,OAAOL,MAC7CM,OAAS,GAC1BC,QAAQC,KACN,qDAAqDR,iFAMzDE,SAASO,eAAef,IAAqBgB,SAG7C,MAAMC,EAlHR,SAAmCX,EAAgBD,GACjD,MAAMa,EAAQV,SAASW,cAAc,SAyErC,OAxEAD,EAAMX,GAAKP,EACXkB,EAAME,YAAc,+JAIAd,0IAKbA,meAeAA,cACAA,kJAKaA,0BACFA,6gBAeAA,oBAAyBA,YAAiBA,+GAM9CD,yeAmBPa,CACT,CAuCyBG,CAA0Bf,EAAQD,GAGzD,OAFAG,SAASc,KAAKC,YAAYN,GAEnB,IAAIO,QAASC,IAElB,MAAMC,EAAe,KACnBC,OAAOC,oBAAoB,aAAcF,GAEzClB,SAASO,eAAef,IAAqBgB,SAC7CS,KAEFE,OAAOE,iBAAiB,aAAcH,GAGtCC,OAAOG,QAGPC,WAAW,KACTJ,OAAOC,oBAAoB,aAAcF,GACzClB,SAASO,eAAef,IAAqBgB,SAC7CS,KACC,MAEP,CC62EA,MAAMO,EACJ,iRAGWC,EAA0C,CACrDC,OAAQ,IACRC,SAAU,IACVC,QAAS,IACTC,SAAU,IACVC,SAAU,IACVC,aAAc,IACdC,WAAY,KACZC,UAAW,IACXC,OAAQV,EACRW,aAAcX,EACdF,MAAO,OCnqEF,MAAec,EAgBpBC,oBAuBAA,gBASSC,QAA8C,oBAArBC,iBAAmCA,iBAAmB,MAG/EC,OAGAC,cAGAC,gBAGAC,YAGCC,KAGAC,OAGSC,WAOnBC,GAOA,iBAAcC,GACZ,MAAO,CAAA,CACT,CAEA,WAAAC,CAAYJ,EAA2B,IACrCK,KAAKJ,WAAaD,CACpB,CAiBA,MAAAM,CAAOP,GAELM,MAAKH,GAAkBK,QAEvBF,MAAKH,EAAmB,IAAIM,gBAE5BH,KAAKN,KAAOA,EAEZM,KAAKL,OAAS,IAAKK,KAAKF,iBAAkBE,KAAKJ,WACjD,CAeA,MAAAQ,GAGEJ,MAAKH,GAAkBK,QACvBF,MAAKH,OAAmB,CAE1B,CAkDU,SAAAQ,CAAoCC,GAC5C,OAAON,KAAKN,MAAMW,UAAUC,EAC9B,CAKU,IAAAC,CAAQC,EAAmBC,GACnCT,KAAKN,MAAMgB,gBAAgB,IAAIC,YAAYH,EAAW,CAAEC,SAAQG,SAAS,IAC3E,CAMU,cAAAC,CAAkBL,EAAmBC,GAC7C,MAAMK,EAAQ,IAAIH,YAAYH,EAAW,CAAEC,SAAQG,SAAS,EAAMG,YAAY,IAE9E,OADAf,KAAKN,MAAMgB,gBAAgBI,GACpBA,EAAME,gBACf,CAsBU,EAAAC,CAAgBC,EAAmBC,GAC3CnB,KAAKN,MAAM0B,gBAAgBC,UAAUrB,KAAMkB,EAAWC,EACxD,CAaU,GAAAG,CAAIJ,GACZlB,KAAKN,MAAM0B,gBAAgBG,YAAYvB,KAAMkB,EAC/C,CAoBU,eAAAM,CAAmBN,EAAmBT,GAC9CT,KAAKN,MAAM0B,gBAAgBI,gBAAgBN,EAAWT,EACxD,CAMU,aAAAgB,GACRzB,KAAKN,MAAM+B,iBACb,CAOU,oBAAAC,GACP1B,KAAKN,MAAgDgC,wBACxD,CAOU,sBAAAC,GACR3B,KAAKN,MAAMiC,0BACb,CAMU,kBAAAC,GACR5B,KAAKN,MAAMkC,sBACb,CAKA,QAAcC,GACZ,OAAO7B,KAAKN,MAAMmC,MAAQ,EAC5B,CAMA,cAAcC,GACZ,OAAO9B,KAAKN,MAAMoC,YAAc,EAClC,CAKA,WAAcC,GACZ,OAAO/B,KAAKN,MAAMqC,SAAW,EAC/B,CAMA,kBAAcC,GACZ,OAAOhC,KAAKN,MAAMuC,iBAAmB,EACvC,CAYA,eAAcxF,GACZ,OAAOuD,KAAKN,IACd,CAmBA,oBAAcwC,GAGZ,OAAOlC,MAAKH,GAAkBsC,QAAUnC,KAAKN,MAAMwC,gBACrD,CAMA,aAAcE,GACZ,MAAMC,EAAYrC,KAAKN,MAAM4C,YAAYC,OAAS,CAAA,EAClD,MAAO,IAAKhE,KAAuB8D,EACrC,CAoBA,sBAAcG,GACZ,MAAMC,EAAOzC,KAAKN,MAAMgD,iBAAiBC,WAAWF,MAAQ,iBAG5D,IAAa,IAATA,GAA2B,QAATA,EAAgB,OAAO,EAG7C,IAAa,IAATA,GAA0B,OAATA,EAAe,OAAO,EAG3C,MAAMG,EAAO5C,KAAKvD,YAClB,GAAImG,EAAM,CAER,MAAmB,MADHC,iBAAiBD,GAAME,iBAAiB,2BAA2BC,MAErF,CAEA,OAAO,CACT,CAcA,qBAAcC,GACZ,MAAMJ,EAAO5C,KAAKvD,YAClB,GAAImG,EAAM,CACR,MAAMK,EAAcJ,iBAAiBD,GAAME,iBAAiB,4BAA4BC,OAClFG,EAASC,SAASF,EAAa,IACrC,IAAKG,MAAMF,GAAS,OAAOA,CAC7B,CACA,OAAO,GACT,CAYU,WAAAG,CAAYC,EAA0CC,GAE9D,YAAuB,IAAnBA,EACKA,EAGFvD,KAAKoC,UAAUkB,EACxB,CASU,OAAAE,CAAQC,EAAsBC,GAClB,iBAATA,EACTD,EAAQE,UAAYD,EACXA,aAAgBE,cACzBH,EAAQE,UAAY,GACpBF,EAAQ5F,YAAY6F,EAAKG,WAAU,IAEvC,CAKU,IAAAzG,CAAK0G,GACb3G,QAAQC,KAAK,aAAa4C,KAAK+D,SAASD,IAC1C,QC3zBIE,EAAwC,CAC5CC,QAAQ,EACRtH,YAAa,YACbuH,cAAe,IACfC,QAAS,EACTC,cAAc,EACdC,kBAAkB,EAClBC,MAAO,GACPC,SAAS,GAiEJ,MAAMC,UAAoBtF,EAEtB6E,KAAO,QAGE3E,QAAU,QAGVE,kwEAGlBmF,IAAY,EAGZC,GAAmD,KAGnDC,GAA2D,KAG3DC,GAA+B,KAG/BC,GAAmC,KAGnCC,GAAmC,KAGnCC,GAA+B,KAK/B,KAAIC,GACF,OAAOhF,KAAKN,IACd,CAKA,UAAAuF,GACE,OAAOjF,MAAKyE,CACd,CAgBA,WAAMrG,CAAM8G,GACV,GAAIlF,MAAKyE,EAEP,YADAtH,QAAQC,KAAK,2CAIf,MAAMsC,EAAOM,KAAKvD,YAClB,IAAKiD,EAEH,YADAvC,QAAQC,KAAK,oCAIf,MAAMuC,EAAS,IAAKqE,KAAmBhE,KAAKL,UAAWuF,GAEjDC,EADOnF,KAAK6B,KACY3E,OAC9B,IAAIkI,EAAWD,EACXE,GAAe,EAGnB,GAAI1F,EAAOuE,cAAgB,GAAKiB,EAAmBxF,EAAOuE,cAAe,CACvE,MAAMoB,EACJ3F,EAAOwE,QAAU,EAAI,uCAAuCxE,EAAOwE,QAAQoB,yBAA2B,GAMxG,IALgBC,QACd,iBAAiBL,EAAiBI,oGAC6CD,kDAI/E,MAEJ,CAGI3F,EAAOwE,QAAU,GAAKgB,EAAmBxF,EAAOwE,UAClDiB,EAAWzF,EAAOwE,QAClBkB,GAAe,GAGjBrF,MAAKyE,GAAY,EAGjB,MAAMgB,EAAYC,YAAYC,MAG9B3F,KAAKO,KAAuB,cAAe,CACzC6E,WACAC,eACAF,qBAGF,IAEE,MAAMH,EAAehF,MAAKgF,EAC1BhF,MAAK2E,EAAuB,CAC1BiB,gBAAiBZ,EAAaa,iBAAiBD,iBAAmB,IAIpE5F,MAAK8F,IAGDT,IACFrF,MAAK4E,EAAa5E,KAAK8B,WAEtB9B,KAAKN,KAAwCmC,KAAO7B,KAAK8B,WAAWiE,MAAM,EAAGX,SAExE,IAAItH,QAASC,GAAYM,WAAWN,EAAS,OAIjD4B,EAAOyE,cAAgBzE,EAAO0E,mBAChCrE,MAAKgG,EAAgBrG,SAKjBK,MAAKiG,UAGL,IAAInI,QAASC,GAAYmI,sBAAsBnI,UAC/C,IAAID,QAASC,GAAYmI,sBAAsBnI,IAGrD2B,EAAKyG,UAAUC,IAAI,SAASzG,EAAOhD,qBAG7B,IAAImB,QAASC,GAAYmI,sBAAsBnI,UAC/C,IAAID,QAASC,GAAYmI,sBAAsBnI,IAGjD4B,EAAO4E,cACHvE,MAAKqG,EAAuB1G,SAE5BK,MAAKsG,IAIbtG,KAAKO,KAA0B,iBAAkB,CAC/CgG,SAAS,EACTnB,WACAoB,SAAUC,KAAKC,MAAMhB,YAAYC,MAAQF,IAE7C,OAASkB,GACPxJ,QAAQwJ,MAAM,8BAA+BA,GAC7C3G,KAAKO,KAA0B,iBAAkB,CAC/CgG,SAAS,EACTnB,SAAU,EACVoB,SAAUC,KAAKC,MAAMhB,YAAYC,MAAQF,IAE7C,CAAA,QAEEzF,MAAK4G,IACL5G,MAAKyE,GAAY,CACnB,CACF,CAKA,EAAAuB,CAAgBrG,GACd,MAAMD,EAAOM,KAAKvD,YAClB,GAAKiD,EAAL,CAOA,GAJAM,MAAK6E,EAAe/H,SAASW,cAAc,OAC3CuC,MAAK6E,EAAagC,UAAY,mBAG1BlH,EAAOyE,aAAc,CACvB,MAAME,EAAQ3E,EAAO2E,OAAStE,KAAKN,KAAKgD,iBAAiBoE,OAAOC,QAAQzC,OAAS,YAC3E0C,EAAUlK,SAASW,cAAc,OACvCuJ,EAAQH,UAAY,yBACpBG,EAAQtJ,YAAc4G,EACtBtE,MAAK6E,EAAahH,YAAYmJ,EAChC,CAGA,GAAIrH,EAAO0E,iBAAkB,CAC3B,MAAM4C,EAAcnK,SAASW,cAAc,OAC3CwJ,EAAYJ,UAAY,6BACxBI,EAAYvJ,YAAc,4BAAA,IAAgBwJ,MAAO3B,mBACjDvF,MAAK6E,EAAahH,YAAYoJ,EAChC,CAGAvH,EAAKyH,aAAanH,MAAK6E,EAAcnF,EAAK0H,YAG1CpH,MAAK8E,EAAehI,SAASW,cAAc,OAC3CuC,MAAK8E,EAAa+B,UAAY,mBAC9B7G,MAAK8E,EAAapH,YAAc,uBAAuBO,OAAOoJ,SAASC,WACvE5H,EAAK7B,YAAYmC,MAAK8E,EA9BX,CA+Bb,CAKA,OAAMmB,GACJ,MAAMjB,EAAehF,MAAKgF,EAC1B,IAAKA,EAAaa,gBAAiB,OAInC,MAAM0B,EAAYvH,KAAK6B,KAAK3E,OAC5B8H,EAAaa,gBAAgBD,gBAAkB2B,EAAY,IAG3DvC,EAAawC,sBAAqB,SAG5B,IAAI1J,QAASC,GAAYM,WAAWN,EAAS,KACrD,CAKA,OAAMuI,GACJ,OAAO,IAAIxI,QAASC,IAElB,MAAMC,EAAe,KACnBC,OAAOC,oBAAoB,aAAcF,GACzCD,KAEFE,OAAOE,iBAAiB,aAAcH,GAGtCC,OAAOG,QAGPC,WAAW,KAEa,oBAAXJ,QACTA,OAAOC,oBAAoB,aAAcF,GAE3CD,KACC,MAEP,CAMA,OAAMsI,CAAuB1G,GAC3B,MAAMD,EAAOM,KAAKvD,YACbiD,SAEClD,EAAkBkD,EAAM,CAC5B/C,YAAagD,EAAOhD,aAExB,CAKA,EAAAmJ,GACE,MAAM/D,EAAU/B,KAAK+B,QACrB,GAAKA,EAAL,CAGA/B,MAAK0E,qBAA0B+C,IAE/B,IAAA,MAAWC,KAAO3F,EACZ2F,EAAIC,aAAeD,EAAIE,QAEzB5H,MAAK0E,EAAoBmD,IAAIH,EAAIE,OAAQF,EAAII,QAE7C9H,KAAKN,KAAKqI,iBAAiBL,EAAIE,OAAO,GAV5B,CAahB,CAKA,EAAAI,GACE,GAAKhI,MAAK0E,EAAV,CAEA,IAAA,MAAYkD,EAAOK,KAAejI,MAAK0E,EAErC1E,KAAKN,KAAKqI,iBAAiBH,EAAOK,GAGpCjI,MAAK0E,EAAsB,IAPI,CAQjC,CAKA,EAAAkC,GACE,MAAMlH,EAAOM,KAAKvD,YAClB,IAAKiD,EAAM,OAGXM,MAAKgI,IAGLtI,EAAKyG,UAAU7I,OAAO,iBAAkB,mBAGb,OAAvB0C,MAAK+E,IACPrF,EAAKlC,MAAM0K,UAAY,GACvBxI,EAAKlC,MAAM2K,gBAAkB,GAC7BzI,EAAKlC,MAAM4K,MAAQ,GACnBpI,MAAK+E,EAAgB,MAInB/E,MAAK6E,IACP7E,MAAK6E,EAAavH,SAClB0C,MAAK6E,EAAe,MAElB7E,MAAK8E,IACP9E,MAAK8E,EAAaxH,SAClB0C,MAAK8E,EAAe,MAItB,MAAME,EAAehF,MAAKgF,EACtBhF,MAAK2E,GAAwBK,EAAaa,kBAC5Cb,EAAaa,gBAAgBD,gBAAkB5F,MAAK2E,EAAqBiB,gBACzEZ,EAAawC,sBAAqB,GAClCxH,MAAK2E,EAAuB,MAIN,OAApB3E,MAAK4E,IACN5E,KAAKN,KAAwCmC,KAAO7B,MAAK4E,EAC1D5E,MAAK4E,EAAa,KAEtB,CAMS,WAAAyD,GAEHrI,KAAKL,QAAQsE,SAAWjE,MAAKsI,IAC/BtI,MAAKuI,IACLvI,MAAKsI,GAAqB,EAE9B,CAGAA,IAAqB,EAKrB,EAAAC,GACE,MAAM7I,EAAOM,MAAKgF,EAGlBtF,EAAK8I,yBAAyB,CAC5B3L,GAAI,eACJ4L,MAAO,IACPC,OAASC,IACP,MAAM1E,EAASnH,SAASW,cAAc,UACtCwG,EAAO4C,UAAY,gCACnB5C,EAAOK,MAAQ,aACfL,EAAO2E,KAAO,SAGd,MAAMlF,EAAO1D,KAAKqD,YAAY,UAAY,MAC1CrD,KAAKwD,QAAQS,EAAQP,GAErBO,EAAO9F,iBACL,QACA,KACE6B,KAAK5B,SAEP,CAAE+D,OAAQnC,KAAKkC,mBAGjByG,EAAU9K,YAAYoG,KAG5B"}
+{"version":3,"file":"index.js","sources":["../../../../../../libs/grid/src/lib/plugins/print/print-isolated.ts","../../../../../../libs/grid/src/lib/core/types.ts","../../../../../../libs/grid/src/lib/core/plugin/base-plugin.ts","../../../../../../libs/grid/src/lib/plugins/print/PrintPlugin.ts"],"sourcesContent":["/**\n * Utility for printing a grid in isolation by hiding all other page content.\n *\n * This approach keeps the grid in place (with virtualization disabled by PrintPlugin)\n * and uses CSS to hide everything else on the page during printing.\n */\n\nimport type { PrintOrientation } from './types';\n\nexport interface PrintIsolatedOptions {\n  /** Page orientation hint */\n  orientation?: PrintOrientation;\n}\n\n/** ID for the isolation stylesheet */\nconst ISOLATION_STYLE_ID = 'tbw-print-isolation-style';\n\n/**\n * Create a stylesheet that hides everything except the target grid.\n * Uses the grid's ID to target it specifically.\n */\nfunction createIsolationStylesheet(gridId: string, orientation: PrintOrientation): HTMLStyleElement {\n  const style = document.createElement('style');\n  style.id = ISOLATION_STYLE_ID;\n  style.textContent = `\n    /* Print isolation: hide everything except the target grid */\n    @media print {\n      /* Hide all body children by default */\n      body > *:not(#${gridId}) {\n        display: none !important;\n      }\n\n      /* But show the grid and ensure it's not hidden by ancestor rules */\n      #${gridId} {\n        display: block !important;\n        position: static !important;\n        visibility: visible !important;\n        opacity: 1 !important;\n        overflow: visible !important;\n        height: auto !important;\n        width: 100% !important;\n        max-height: none !important;\n        margin: 0 !important;\n        padding: 0 !important;\n        transform: none !important;\n      }\n\n      /* If grid is nested, we need to show its ancestors too */\n      #${gridId},\n      #${gridId} * {\n        visibility: visible !important;\n      }\n\n      /* Walk up the DOM and show all ancestors of the grid */\n      body *:has(> #${gridId}),\n      body *:has(#${gridId}) {\n        display: block !important;\n        visibility: visible !important;\n        opacity: 1 !important;\n        overflow: visible !important;\n        height: auto !important;\n        position: static !important;\n        transform: none !important;\n        background: transparent !important;\n        border: none !important;\n        padding: 0 !important;\n        margin: 0 !important;\n      }\n\n      /* Hide siblings of ancestors (everything that's not in the path to the grid) */\n      body *:has(#${gridId}) > *:not(:has(#${gridId})):not(#${gridId}) {\n        display: none !important;\n      }\n\n      /* Page settings */\n      @page {\n        size: ${orientation};\n        margin: 1cm;\n      }\n\n      /* Ensure proper print styling */\n      body {\n        margin: 0 !important;\n        padding: 0 !important;\n        background: white !important;\n        color-scheme: light !important;\n      }\n    }\n\n    /* Screen: also apply isolation for print preview */\n    @media screen {\n      /* When this stylesheet is active, we're about to print */\n      /* No screen-specific rules needed - isolation only applies to print */\n    }\n  `;\n  return style;\n}\n\n/**\n * Print a grid in isolation by hiding all other page content.\n *\n * This function adds a temporary stylesheet that uses CSS to hide everything\n * on the page except the target grid during printing. The grid stays in place\n * with all its data (virtualization should be disabled separately).\n *\n * @param gridElement - The tbw-grid element to print (must have an ID)\n * @param options - Optional configuration\n * @returns Promise that resolves when the print dialog closes\n *\n * @example\n * ```typescript\n * import { printGridIsolated } from '@toolbox-web/grid/plugins/print';\n *\n * const grid = document.querySelector('tbw-grid');\n * await printGridIsolated(grid, { orientation: 'landscape' });\n * ```\n */\nexport async function printGridIsolated(gridElement: HTMLElement, options: PrintIsolatedOptions = {}): Promise<void> {\n  const { orientation = 'landscape' } = options;\n\n  const gridId = gridElement.id;\n\n  // Warn if multiple elements share this ID (user-set IDs could collide)\n  const elementsWithId = document.querySelectorAll(`#${CSS.escape(gridId)}`);\n  if (elementsWithId.length > 1) {\n    console.warn(\n      `[tbw-grid:print] Multiple elements found with id=\"${gridId}\". ` +\n        `Print isolation may not work correctly. Ensure each grid has a unique ID.`,\n    );\n  }\n\n  // Remove any existing isolation stylesheet\n  document.getElementById(ISOLATION_STYLE_ID)?.remove();\n\n  // Add the isolation stylesheet\n  const isolationStyle = createIsolationStylesheet(gridId, orientation);\n  document.head.appendChild(isolationStyle);\n\n  return new Promise((resolve) => {\n    // Listen for afterprint event to cleanup\n    const onAfterPrint = () => {\n      window.removeEventListener('afterprint', onAfterPrint);\n      // Remove isolation stylesheet\n      document.getElementById(ISOLATION_STYLE_ID)?.remove();\n      resolve();\n    };\n    window.addEventListener('afterprint', onAfterPrint);\n\n    // Trigger print\n    window.print();\n\n    // Fallback timeout in case afterprint doesn't fire (some browsers)\n    setTimeout(() => {\n      window.removeEventListener('afterprint', onAfterPrint);\n      document.getElementById(ISOLATION_STYLE_ID)?.remove();\n      resolve();\n    }, 5000);\n  });\n}\n","import type { RowPosition } from './internal/virtualization';\nimport type { PluginQuery } from './plugin/base-plugin';\nimport type { AfterCellRenderContext, AfterRowRenderContext, CellMouseEvent } from './plugin/types';\n\n/**\n * Position entry for a single row in the position cache.\n * Part of variable row height virtualization.\n *\n * Re-exported from position-cache.ts for public API consistency.\n *\n * @see VirtualState.positionCache\n * @category Plugin Development\n */\nexport type RowPositionEntry = RowPosition;\n\n// #region DataGridElement Interface\n/**\n * The compiled web component interface for DataGrid.\n *\n * This interface represents the `<tbw-grid>` custom element, combining\n * the public grid API with standard HTMLElement functionality.\n *\n * @example\n * ```typescript\n * // Query existing grid\n * const grid = document.querySelector('tbw-grid') as DataGridElement<Employee>;\n * grid.rows = employees;\n * grid.addEventListener('cell-click', (e) => console.log(e.detail));\n *\n * // Create grid programmatically\n * import { createGrid } from '@toolbox-web/grid';\n * const grid = createGrid<Employee>({\n *   columns: [{ field: 'name' }, { field: 'email' }],\n * });\n * document.body.appendChild(grid);\n * ```\n *\n * @see {@link PublicGrid} for the public API methods and properties\n * @see {@link createGrid} for typed grid creation\n * @see {@link queryGrid} for typed grid querying\n */\nexport interface DataGridElement extends PublicGrid, HTMLElement {}\n// #endregion\n\n// #region PublicGrid Interface\n/**\n * Public API interface for DataGrid component.\n *\n * **Property Getters vs Setters:**\n *\n * Property getters return the EFFECTIVE (resolved) value after merging all config sources.\n * This is the \"current situation\" - what consumers and plugins need to know.\n *\n * Property setters accept input values which are merged into the effective config.\n * Multiple sources can contribute (gridConfig, columns prop, light DOM, individual props).\n *\n * For example:\n * - `grid.fitMode` returns the resolved fitMode (e.g., 'stretch' even if you set undefined)\n * - `grid.columns` returns the effective columns after merging\n * - `grid.gridConfig` returns the full effective config\n */\nexport interface PublicGrid<T = any> {\n  /**\n   * Full config object. Setter merges with other inputs per precedence rules.\n   * Getter returns the effective (resolved) config.\n   */\n  gridConfig?: GridConfig<T>;\n  /**\n   * Column definitions.\n   * Getter returns effective columns (after merging config, light DOM, inference).\n   */\n  columns?: ColumnConfig<T>[];\n  /** Current row data (after plugin processing like grouping, filtering). */\n  rows?: T[];\n  /** Insert a row at a visible index, bypassing the sort/filter pipeline. Auto-animates by default. */\n  insertRow?(index: number, row: T, animate?: boolean): Promise<void>;\n  /** Remove a row at a visible index, bypassing the sort/filter pipeline. Auto-animates by default. */\n  removeRow?(index: number, animate?: boolean): Promise<T | undefined>;\n  /** Resolves once the component has finished initial work (layout, inference). */\n  ready?: () => Promise<void>;\n  /** Force a layout / measurement pass (e.g. after container resize). */\n  forceLayout?: () => Promise<void>;\n  /** Return effective resolved config (after inference & precedence). */\n  getConfig?: () => Promise<Readonly<GridConfig<T>>>;\n  /** Toggle expansion state of a group row by its generated key. */\n  toggleGroup?: (key: string) => Promise<void>;\n\n  // Custom Styles API\n  /**\n   * Register custom CSS styles to be injected into the grid.\n   * Use this to style custom cell renderers, editors, or detail panels.\n   * @param id - Unique identifier for the style block (for removal/updates)\n   * @param css - CSS string to inject\n   */\n  registerStyles?: (id: string, css: string) => void;\n  /**\n   * Remove previously registered custom styles.\n   * @param id - The ID used when registering the styles\n   */\n  unregisterStyles?: (id: string) => void;\n  /**\n   * Get list of registered custom style IDs.\n   */\n  getRegisteredStyles?: () => string[];\n\n  // Plugin API\n  /**\n   * Get a plugin instance by its class.\n   *\n   * @example\n   * ```typescript\n   * const selection = grid.getPlugin(SelectionPlugin);\n   * if (selection) {\n   *   selection.selectAll();\n   * }\n   * ```\n   */\n  getPlugin?<P>(PluginClass: new (...args: any[]) => P): P | undefined;\n  /**\n   * Get a plugin instance by its name.\n   *\n   * When a plugin augments the {@link PluginNameMap} interface, the return\n   * type is narrowed automatically:\n   *\n   * ```typescript\n   * const editing = grid.getPluginByName('editing');\n   * editing?.beginBulkEdit(0); // ✅ typed as EditingPlugin\n   * ```\n   *\n   * For unknown names the return type falls back to `GridPlugin | undefined`.\n   */\n  getPluginByName?<K extends string>(\n    name: K,\n  ): (K extends keyof PluginNameMap ? PluginNameMap[K] : GridPlugin) | undefined;\n\n  // Shell API\n  /**\n   * Re-render the shell header (title, column groups, toolbar).\n   * Call this after dynamically adding/removing tool panels or toolbar buttons.\n   */\n  refreshShellHeader?(): void;\n  /**\n   * Register a custom tool panel in the sidebar.\n   *\n   * @example\n   * ```typescript\n   * grid.registerToolPanel({\n   *   id: 'analytics',\n   *   title: 'Analytics',\n   *   icon: '📊',\n   *   render: (container) => {\n   *     container.innerHTML = '<div>Charts here...</div>';\n   *   }\n   * });\n   * ```\n   */\n  registerToolPanel?(panel: ToolPanelDefinition): void;\n  /**\n   * Unregister a previously registered tool panel.\n   */\n  unregisterToolPanel?(panelId: string): void;\n  /**\n   * Open the tool panel sidebar.\n   */\n  openToolPanel?(): void;\n  /**\n   * Close the tool panel sidebar.\n   */\n  closeToolPanel?(): void;\n  /**\n   * Toggle the tool panel sidebar open or closed.\n   */\n  toggleToolPanel?(): void;\n  /**\n   * Toggle an accordion section expanded or collapsed within the tool panel.\n   * @param sectionId - The ID of the section to toggle\n   */\n  toggleToolPanelSection?(sectionId: string): void;\n\n  // State Persistence API\n  /**\n   * Get the current column state including order, width, visibility, and sort.\n   * Use for persisting user preferences to localStorage or a backend.\n   *\n   * @example\n   * ```typescript\n   * const state = grid.getColumnState();\n   * localStorage.setItem('gridState', JSON.stringify(state));\n   * ```\n   */\n  getColumnState?(): GridColumnState;\n  /**\n   * Set/restore the column state.\n   * Can be set before or after grid initialization.\n   *\n   * @example\n   * ```typescript\n   * const saved = localStorage.getItem('gridState');\n   * if (saved) {\n   *   grid.columnState = JSON.parse(saved);\n   * }\n   * ```\n   */\n  columnState?: GridColumnState;\n\n  // Loading API\n  /**\n   * Whether the grid is currently in a loading state.\n   * When true, displays a loading overlay with spinner.\n   *\n   * Can also be set via the `loading` HTML attribute.\n   *\n   * @example\n   * ```typescript\n   * // Show loading overlay\n   * grid.loading = true;\n   * const data = await fetchData();\n   * grid.rows = data;\n   * grid.loading = false;\n   * ```\n   */\n  loading?: boolean;\n\n  /**\n   * Set loading state for a specific row.\n   * Displays a small spinner indicator on the row.\n   *\n   * Use when persisting row data or performing row-level async operations.\n   *\n   * @param rowId - The row's unique identifier (from getRowId)\n   * @param loading - Whether the row is loading\n   *\n   * @example\n   * ```typescript\n   * // Show loading while saving row\n   * grid.setRowLoading('emp-123', true);\n   * await saveRow(row);\n   * grid.setRowLoading('emp-123', false);\n   * ```\n   */\n  setRowLoading?(rowId: string, loading: boolean): void;\n\n  /**\n   * Set loading state for a specific cell.\n   * Displays a small spinner indicator on the cell.\n   *\n   * Use when performing cell-level async operations (e.g., validation, lookup).\n   *\n   * @param rowId - The row's unique identifier (from getRowId)\n   * @param field - The column field\n   * @param loading - Whether the cell is loading\n   *\n   * @example\n   * ```typescript\n   * // Show loading while validating cell\n   * grid.setCellLoading('emp-123', 'email', true);\n   * const isValid = await validateEmail(email);\n   * grid.setCellLoading('emp-123', 'email', false);\n   * ```\n   */\n  setCellLoading?(rowId: string, field: string, loading: boolean): void;\n\n  /**\n   * Check if a row is currently in loading state.\n   * @param rowId - The row's unique identifier\n   */\n  isRowLoading?(rowId: string): boolean;\n\n  /**\n   * Check if a cell is currently in loading state.\n   * @param rowId - The row's unique identifier\n   * @param field - The column field\n   */\n  isCellLoading?(rowId: string, field: string): boolean;\n\n  /**\n   * Clear all row and cell loading states.\n   */\n  clearAllLoading?(): void;\n\n  // Focus Management API\n  /**\n   * Register an external DOM element as a logical focus container of this grid.\n   *\n   * Focus moving into a registered container is treated as if it stayed inside\n   * the grid: `data-has-focus` is preserved, click-outside commit is suppressed,\n   * and the editing focus trap (when enabled) won't reclaim focus.\n   *\n   * Typical use case: overlay panels (datepickers, dropdowns, autocompletes)\n   * that render at `<body>` level to escape grid overflow clipping.\n   *\n   * @param el - The external element to register\n   *\n   * @example\n   * ```typescript\n   * const overlay = document.createElement('div');\n   * document.body.appendChild(overlay);\n   *\n   * // Tell the grid this overlay is \"part of\" the grid\n   * grid.registerExternalFocusContainer(overlay);\n   *\n   * // Later, when overlay is removed\n   * grid.unregisterExternalFocusContainer(overlay);\n   * ```\n   */\n  registerExternalFocusContainer?(el: Element): void;\n\n  /**\n   * Unregister a previously registered external focus container.\n   *\n   * @param el - The element to unregister\n   */\n  unregisterExternalFocusContainer?(el: Element): void;\n\n  /**\n   * Check whether focus is logically inside this grid.\n   *\n   * Returns `true` when `document.activeElement` (or the given node) is\n   * inside the grid's own DOM **or** inside any element registered via\n   * {@link registerExternalFocusContainer}.\n   *\n   * @param node - Optional node to test. Defaults to `document.activeElement`.\n   *\n   * @example\n   * ```typescript\n   * if (grid.containsFocus()) {\n   *   console.log('Grid or one of its overlays has focus');\n   * }\n   * ```\n   */\n  containsFocus?(node?: Node | null): boolean;\n}\n// #endregion\n\n// #region InternalGrid Interface\n/**\n * Internal-only augmented interface for DataGrid component.\n *\n * Member prefixes indicate accessibility:\n * - `_underscore` = protected members - private outside core, accessible to plugins. Marked with @internal.\n * - `__doubleUnderscore` = deeply internal members - private outside core, only for internal functions.\n *\n * @category Plugin Development\n */\nexport interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {\n  // Element methods available because DataGridElement extends HTMLElement\n  querySelector<K extends keyof HTMLElementTagNameMap>(selectors: K): HTMLElementTagNameMap[K] | null;\n  querySelector<E extends Element = Element>(selectors: string): E | null;\n  querySelectorAll<K extends keyof HTMLElementTagNameMap>(selectors: K): NodeListOf<HTMLElementTagNameMap[K]>;\n  querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>;\n  _rows: T[];\n  _columns: ColumnInternal<T>[];\n  /** Visible columns only (excludes hidden). Use for rendering. */\n  _visibleColumns: ColumnInternal<T>[];\n  _headerRowEl: HTMLElement;\n  _bodyEl: HTMLElement;\n  _rowPool: RowElementInternal[];\n  _resizeController: ResizeController;\n  _sortState: { field: string; direction: 1 | -1 } | null;\n  /** Original unfiltered/unprocessed rows. @internal */\n  sourceRows: T[];\n  /** Framework adapter instance (set by Grid directives). @internal */\n  __frameworkAdapter?: FrameworkAdapter;\n  __originalOrder: T[];\n  __rowRenderEpoch: number;\n  __didInitialAutoSize?: boolean;\n  __lightDomColumnsCache?: ColumnInternal[];\n  __originalColumnNodes?: HTMLElement[];\n  /** Cell display value cache. @internal */\n  __cellDisplayCache?: Map<number, string[]>;\n  /** Cache epoch for cell display values. @internal */\n  __cellCacheEpoch?: number;\n  /** Cached header row count for virtualization. @internal */\n  __cachedHeaderRowCount?: number;\n  /** Cached flag for whether grid has special columns (custom renderers, etc.). @internal */\n  __hasSpecialColumns?: boolean;\n  /** Cached flag for whether any plugin has renderRow hooks. @internal */\n  __hasRenderRowPlugins?: boolean;\n  _gridTemplate: string;\n  _virtualization: VirtualState;\n  _focusRow: number;\n  _focusCol: number;\n  /** Currently active edit row index. Injected by EditingPlugin. @internal */\n  _activeEditRows?: number;\n  /** Whether the grid is in 'grid' editing mode (all rows editable). Injected by EditingPlugin. @internal */\n  _isGridEditMode?: boolean;\n  /** Snapshots of row data before editing. Injected by EditingPlugin. @internal */\n  _rowEditSnapshots?: Map<number, T>;\n  /** Get all changed rows. Injected by EditingPlugin. */\n  changedRows?: T[];\n  /** Get IDs of all changed rows. Injected by EditingPlugin. */\n  changedRowIds?: string[];\n  effectiveConfig?: GridConfig<T>;\n  findHeaderRow?: () => HTMLElement;\n  refreshVirtualWindow: (full: boolean, skipAfterRender?: boolean) => boolean;\n  updateTemplate?: () => void;\n  findRenderedRowElement?: (rowIndex: number) => HTMLElement | null;\n  /** Get a row by its ID. Implemented in grid.ts */\n  getRow?: (id: string) => T | undefined;\n  /** Get a row and its current index by ID. Returns undefined if not found. @internal */\n  _getRowEntry: (id: string) => { row: T; index: number } | undefined;\n  /** Get the unique ID for a row. Implemented in grid.ts */\n  getRowId?: (row: T) => string;\n  /** Update a row by ID. Implemented in grid.ts */\n  updateRow?: (id: string, changes: Partial<T>, source?: UpdateSource) => void;\n  /** Animate a single row. Returns Promise that resolves when animation completes. Implemented in grid.ts */\n  animateRow?: (rowIndex: number, type: RowAnimationType) => Promise<boolean>;\n  /** Animate multiple rows. Returns Promise that resolves when all animations complete. Implemented in grid.ts */\n  animateRows?: (rowIndices: number[], type: RowAnimationType) => Promise<number>;\n  /** Animate a row by its ID. Returns Promise that resolves when animation completes. Implemented in grid.ts */\n  animateRowById?: (rowId: string, type: RowAnimationType) => Promise<boolean>;\n  /** Begin bulk edit on a row. Injected by EditingPlugin. */\n  beginBulkEdit?: (rowIndex: number) => void;\n  /** Commit active row edit. Injected by EditingPlugin. */\n  commitActiveRowEdit?: () => void;\n  /** Dispatch cell click to plugin system, returns true if handled */\n  _dispatchCellClick?: (event: MouseEvent, rowIndex: number, colIndex: number, cellEl: HTMLElement) => boolean;\n  /** Dispatch row click to plugin system, returns true if handled */\n  _dispatchRowClick?: (event: MouseEvent, rowIndex: number, row: any, rowEl: HTMLElement) => boolean;\n  /** Dispatch header click to plugin system, returns true if handled */\n  _dispatchHeaderClick?: (event: MouseEvent, col: ColumnConfig, headerEl: HTMLElement) => boolean;\n  /** Dispatch keydown to plugin system, returns true if handled */\n  _dispatchKeyDown?: (event: KeyboardEvent) => boolean;\n  /** Dispatch cell mouse events for drag operations. Returns true if any plugin started a drag. */\n  _dispatchCellMouseDown?: (event: CellMouseEvent) => boolean;\n  /** Dispatch cell mouse move during drag. */\n  _dispatchCellMouseMove?: (event: CellMouseEvent) => void;\n  /** Dispatch cell mouse up to end drag. */\n  _dispatchCellMouseUp?: (event: CellMouseEvent) => void;\n  /** Call afterCellRender hook on all plugins. Called from rows.ts after each cell is rendered. @internal */\n  _afterCellRender?: (context: AfterCellRenderContext<T>) => void;\n  /** Check if any plugin has registered an afterCellRender hook. Used to skip hook call for performance. @internal */\n  _hasAfterCellRenderHook?: () => boolean;\n  /** Call afterRowRender hook on all plugins. Called from rows.ts after each row is rendered. @internal */\n  _afterRowRender?: (context: AfterRowRenderContext<T>) => void;\n  /** Check if any plugin has registered an afterRowRender hook. Used to skip hook call for performance. @internal */\n  _hasAfterRowRenderHook?: () => boolean;\n  /** Get horizontal scroll boundary offsets from plugins */\n  _getHorizontalScrollOffsets?: (\n    rowEl?: HTMLElement,\n    focusedCell?: HTMLElement,\n  ) => { left: number; right: number; skipScroll?: boolean };\n  /** Query all plugins with a generic query and collect responses */\n  queryPlugins?: <T>(query: PluginQuery) => T[];\n  /** Request emission of column-state-change event (debounced) */\n  requestStateChange?: () => void;\n}\n// #endregion\n\n// #region Column Types\n/**\n * Built-in primitive column types with automatic formatting and editing support.\n *\n * - `'string'` - Text content, default text input editor\n * - `'number'` - Numeric content, right-aligned, number input editor\n * - `'date'` - Date content, formatted display, date picker editor\n * - `'boolean'` - True/false, rendered as checkbox\n * - `'select'` - Dropdown selection from `options` array\n *\n * @example\n * ```typescript\n * columns: [\n *   { field: 'name', type: 'string' },\n *   { field: 'age', type: 'number' },\n *   { field: 'hireDate', type: 'date' },\n *   { field: 'active', type: 'boolean' },\n *   { field: 'department', type: 'select', options: [\n *     { label: 'Engineering', value: 'eng' },\n *     { label: 'Sales', value: 'sales' },\n *   ]},\n * ]\n * ```\n *\n * @see {@link ColumnType} for custom type support\n * @see {@link TypeDefault} for type-level defaults\n */\nexport type PrimitiveColumnType = 'number' | 'string' | 'date' | 'boolean' | 'select';\n\n/**\n * Column type - built-in primitives or custom type strings.\n *\n * Use built-in types for automatic formatting, or define custom types\n * (e.g., 'currency', 'country') with type-level defaults via `typeDefaults`.\n *\n * @example\n * ```typescript\n * // Built-in types\n * { field: 'name', type: 'string' }\n * { field: 'salary', type: 'number' }\n *\n * // Custom types with defaults\n * grid.gridConfig = {\n *   columns: [\n *     { field: 'salary', type: 'currency' },\n *     { field: 'birthCountry', type: 'country' },\n *   ],\n *   typeDefaults: {\n *     currency: {\n *       format: (v) => `$${Number(v).toFixed(2)}`,\n *     },\n *     country: {\n *       renderer: (ctx) => `🌍 ${ctx.value}`,\n *     },\n *   },\n * };\n * ```\n *\n * @see {@link PrimitiveColumnType} for built-in types\n * @see {@link TypeDefault} for defining custom type defaults\n */\nexport type ColumnType = PrimitiveColumnType | (string & {});\n// #endregion\n\n// #region TypeDefault Interface\n/**\n * Type-level defaults for formatters and renderers.\n * Applied to all columns of a given type unless overridden at column level.\n *\n * Note: `editor` and `editorParams` are added via module augmentation when\n * EditingPlugin is imported. `filterPanelRenderer` is added by FilteringPlugin.\n *\n * @example\n * ```typescript\n * typeDefaults: {\n *   currency: {\n *     format: (value) => new Intl.NumberFormat('en-US', {\n *       style: 'currency',\n *       currency: 'USD',\n *     }).format(value as number),\n *   },\n *   country: {\n *     renderer: (ctx) => {\n *       const span = document.createElement('span');\n *       span.innerHTML = `<img src=\"/flags/${ctx.value}.svg\" /> ${ctx.value}`;\n *       return span;\n *     }\n *   }\n * }\n * ```\n *\n * @see {@link ColumnViewRenderer} for custom renderer function signature\n * @see {@link ColumnType} for type strings that can have defaults\n * @see {@link GridConfig.typeDefaults} for registering type defaults\n */\nexport interface TypeDefault<TRow = unknown> {\n  /**\n   * Default formatter for all columns of this type.\n   *\n   * Transforms the raw cell value into a display string. Use when you need\n   * consistent formatting across columns without custom DOM (e.g., currency,\n   * percentages, dates with specific locale).\n   *\n   * **Resolution Priority**: Column `format` → Type `format` → Built-in\n   *\n   * @example\n   * ```typescript\n   * typeDefaults: {\n   *   currency: {\n   *     format: (value) => new Intl.NumberFormat('en-US', {\n   *       style: 'currency',\n   *       currency: 'USD',\n   *     }).format(value as number),\n   *   },\n   *   percentage: {\n   *     format: (value) => `${(value as number * 100).toFixed(1)}%`,\n   *   }\n   * }\n   * ```\n   */\n  format?: (value: unknown, row: TRow) => string;\n\n  /**\n   * Default renderer for all columns of this type.\n   *\n   * Creates custom DOM for the cell content. Use when you need more than\n   * text formatting (e.g., icons, badges, interactive elements).\n   *\n   * **Resolution Priority**: Column `renderer` → Type `renderer` → App-level (adapter) → Built-in\n   *\n   * @example\n   * ```typescript\n   * typeDefaults: {\n   *   status: {\n   *     renderer: (ctx) => {\n   *       const badge = document.createElement('span');\n   *       badge.className = `badge badge-${ctx.value}`;\n   *       badge.textContent = ctx.value as string;\n   *       return badge;\n   *     }\n   *   },\n   *   country: {\n   *     renderer: (ctx) => {\n   *       const span = document.createElement('span');\n   *       span.innerHTML = `<img src=\"/flags/${ctx.value}.svg\" /> ${ctx.value}`;\n   *       return span;\n   *     }\n   *   }\n   * }\n   * ```\n   */\n  renderer?: ColumnViewRenderer<TRow, unknown>;\n}\n// #endregion\n\n// #region BaseColumnConfig Interface\n/**\n * Base contract for a column configuration.\n *\n * Defines the fundamental properties all columns share. Extended by {@link ColumnConfig}\n * with additional features like custom renderers and grouping.\n *\n * @example\n * ```typescript\n * // Basic column with common properties\n * const columns: BaseColumnConfig<Employee>[] = [\n *   {\n *     field: 'name',\n *     header: 'Full Name',\n *     sortable: true,\n *     resizable: true,\n *   },\n *   {\n *     field: 'salary',\n *     type: 'number',\n *     width: 120,\n *     format: (value) => `$${value.toLocaleString()}`,\n *     sortComparator: (a, b) => a - b,\n *   },\n *   {\n *     field: 'department',\n *     type: 'select',\n *     options: [\n *       { label: 'Engineering', value: 'eng' },\n *       { label: 'Sales', value: 'sales' },\n *     ],\n *   },\n * ];\n * ```\n *\n * @see {@link ColumnConfig} for full column configuration with renderers\n * @see {@link ColumnType} for type options\n */\nexport interface BaseColumnConfig<TRow = any, TValue = any> {\n  /** Unique field key referencing property in row objects */\n  field: keyof TRow & string;\n  /** Visible header label; defaults to capitalized field */\n  header?: string;\n  /**\n   * Column data type.\n   *\n   * Built-in types: `'string'`, `'number'`, `'date'`, `'boolean'`, `'select'`\n   *\n   * Custom types (e.g., `'currency'`, `'country'`) can have type-level defaults\n   * via `gridConfig.typeDefaults` or framework adapter registries.\n   *\n   * @default Inferred from first row data\n   */\n  type?: ColumnType;\n  /** Column width in pixels; fixed size (no flexibility) */\n  width?: string | number;\n  /** Minimum column width in pixels (stretch mode only); when set, column uses minmax(minWidth, 1fr) */\n  minWidth?: number;\n  /** Whether column can be sorted */\n  sortable?: boolean;\n  /** Whether column can be resized by user */\n  resizable?: boolean;\n  /** Optional custom comparator for sorting (a,b) -> number */\n  sortComparator?: (a: TValue, b: TValue, rowA: TRow, rowB: TRow) => number;\n  /** For select type - available options */\n  options?: Array<{ label: string; value: unknown }> | (() => Array<{ label: string; value: unknown }>);\n  /** For select - allow multi select */\n  multi?: boolean;\n  /**\n   * Formats the raw cell value into a display string.\n   *\n   * Used both for **cell rendering** and the **built-in filter panel**:\n   * - In cells, the formatted value replaces the raw value as text content.\n   * - In the filter panel (set filter), checkbox labels show the formatted value\n   *   instead of the raw value, and search matches against the formatted text.\n   *\n   * The `row` parameter is available during cell rendering but is `undefined`\n   * when called from the filter panel (standalone value formatting). Avoid\n   * accessing `row` properties in format functions intended for filter display.\n   *\n   * @example\n   * ```typescript\n   * // Currency formatter — works in both cells and filter panel\n   * {\n   *   field: 'price',\n   *   format: (value) => `$${Number(value).toFixed(2)}`,\n   * }\n   *\n   * // ID-to-name lookup — filter panel shows names, not IDs\n   * {\n   *   field: 'departmentId',\n   *   format: (value) => departmentMap.get(value as string) ?? String(value),\n   * }\n   * ```\n   */\n  format?: (value: TValue, row: TRow) => string;\n  /** Arbitrary extra metadata */\n  meta?: Record<string, unknown>;\n}\n// #endregion\n\n// #region ColumnConfig Interface\n/**\n * Full column configuration including custom renderers, editors, and grouping metadata.\n *\n * Extends {@link BaseColumnConfig} with additional features for customizing\n * how cells are displayed and edited.\n *\n * @example\n * ```typescript\n * const columns: ColumnConfig<Employee>[] = [\n *   // Basic sortable column\n *   { field: 'id', header: 'ID', width: 60, sortable: true },\n *\n *   // Column with custom renderer\n *   {\n *     field: 'name',\n *     header: 'Employee',\n *     renderer: (ctx) => {\n *       const div = document.createElement('div');\n *       div.innerHTML = `<img src=\"${ctx.row.avatar}\" /><span>${ctx.value}</span>`;\n *       return div;\n *     },\n *   },\n *\n *   // Column with custom header\n *   {\n *     field: 'email',\n *     headerLabelRenderer: (ctx) => `${ctx.value} 📧`,\n *   },\n *\n *   // Editable column (requires EditingPlugin)\n *   {\n *     field: 'status',\n *     editable: true,\n *     editor: (ctx) => {\n *       const select = document.createElement('select');\n *       // ... editor implementation\n *       return select;\n *     },\n *   },\n *\n *   // Hidden column (can be shown via VisibilityPlugin)\n *   { field: 'internalNotes', hidden: true },\n * ];\n * ```\n *\n * @see {@link BaseColumnConfig} for basic column properties\n * @see {@link ColumnViewRenderer} for custom cell renderers\n * @see {@link ColumnEditorSpec} for custom cell editors\n * @see {@link HeaderRenderer} for custom header renderers\n */\nexport interface ColumnConfig<TRow = any> extends BaseColumnConfig<TRow, any> {\n  /**\n   * Optional custom cell renderer function. Alias for `viewRenderer`.\n   * Can return an HTMLElement, a Node, or an HTML string (which will be sanitized).\n   *\n   * @example\n   * ```typescript\n   * // Simple string template\n   * renderer: (ctx) => `<span class=\"badge\">${ctx.value}</span>`\n   *\n   * // DOM element\n   * renderer: (ctx) => {\n   *   const el = document.createElement('span');\n   *   el.textContent = ctx.value;\n   *   return el;\n   * }\n   * ```\n   */\n  renderer?: ColumnViewRenderer<TRow, any>;\n  /** Optional custom view renderer used instead of default text rendering */\n  viewRenderer?: ColumnViewRenderer<TRow, any>;\n  /** External view spec (lets host app mount any framework component) */\n  externalView?: {\n    component: unknown;\n    props?: Record<string, unknown>;\n    mount?: (options: {\n      placeholder: HTMLElement;\n      context: CellRenderContext<TRow, unknown>;\n      spec: unknown;\n    }) => void | { dispose?: () => void };\n  };\n  /** Whether the column is initially hidden */\n  hidden?: boolean;\n  /** Prevent this column from being hidden programmatically */\n  lockVisible?: boolean;\n  /**\n   * Dynamic CSS class(es) for cells in this column.\n   * Called for each cell during rendering. Return class names to add to the cell element.\n   *\n   * @example\n   * ```typescript\n   * // Highlight negative values\n   * cellClass: (value, row, column) => value < 0 ? ['negative', 'text-red'] : []\n   *\n   * // Status-based styling\n   * cellClass: (value) => [`status-${value}`]\n   * ```\n   */\n  cellClass?: (value: unknown, row: TRow, column: ColumnConfig<TRow>) => string[];\n\n  /**\n   * Custom header label renderer. Customize the label content while the grid\n   * handles sort icons, filter buttons, resize handles, and click interactions.\n   *\n   * Use this for simple customizations like adding icons, badges, or units.\n   *\n   * @example\n   * ```typescript\n   * // Add required field indicator\n   * headerLabelRenderer: (ctx) => `${ctx.value} <span class=\"required\">*</span>`\n   *\n   * // Add unit to header\n   * headerLabelRenderer: (ctx) => {\n   *   const span = document.createElement('span');\n   *   span.innerHTML = `${ctx.value}<br/><small>(kg)</small>`;\n   *   return span;\n   * }\n   * ```\n   */\n  headerLabelRenderer?: HeaderLabelRenderer<TRow>;\n\n  /**\n   * Custom header cell renderer. Complete control over the entire header cell.\n   * Resize handles are added automatically for resizable columns.\n   *\n   * The context provides helper functions to include standard elements:\n   * - `renderSortIcon()` - Returns sort indicator element (null if not sortable)\n   * - `renderFilterButton()` - Returns filter button (null if not filterable)\n   *\n   * **Precedence**: `headerRenderer` > `headerLabelRenderer` > `header` > `field`\n   *\n   * @example\n   * ```typescript\n   * headerRenderer: (ctx) => {\n   *   const div = document.createElement('div');\n   *   div.className = 'custom-header';\n   *   div.innerHTML = `<span>${ctx.value}</span>`;\n   *   const sortIcon = ctx.renderSortIcon();\n   *   if (sortIcon) div.appendChild(sortIcon);\n   *   return div;\n   * }\n   * ```\n   */\n  headerRenderer?: HeaderRenderer<TRow>;\n}\n// #endregion\n\n// #region ColumnConfigMap Type\n/**\n * Array of column configurations.\n * Convenience type alias for `ColumnConfig<TRow>[]`.\n *\n * @example\n * ```typescript\n * const columns: ColumnConfigMap<Employee> = [\n *   { field: 'name', header: 'Full Name', sortable: true },\n *   { field: 'email', header: 'Email Address' },\n *   { field: 'department', type: 'select', options: deptOptions },\n * ];\n *\n * grid.columns = columns;\n * ```\n *\n * @see {@link ColumnConfig} for individual column options\n * @see {@link GridConfig.columns} for setting columns on the grid\n */\nexport type ColumnConfigMap<TRow = any> = ColumnConfig<TRow>[];\n// #endregion\n\n// #region Editor Types\n/**\n * Editor specification for inline cell editing.\n * Supports multiple formats for maximum flexibility.\n *\n * **Format Options:**\n * - `string` - Custom element tag name (e.g., 'my-date-picker')\n * - `function` - Factory function returning an editor element\n * - `object` - External component spec for framework integration\n *\n * @example\n * ```typescript\n * // 1. Custom element tag name\n * columns: [\n *   { field: 'date', editor: 'my-date-picker' }\n * ]\n *\n * // 2. Factory function (full control)\n * columns: [\n *   {\n *     field: 'status',\n *     editor: (ctx) => {\n *       const select = document.createElement('select');\n *       select.innerHTML = `\n *         <option value=\"active\">Active</option>\n *         <option value=\"inactive\">Inactive</option>\n *       `;\n *       select.value = ctx.value;\n *       select.onchange = () => ctx.commit(select.value);\n *       select.onkeydown = (e) => {\n *         if (e.key === 'Escape') ctx.cancel();\n *       };\n *       return select;\n *     }\n *   }\n * ]\n *\n * // 3. External component (React, Angular, Vue)\n * columns: [\n *   {\n *     field: 'country',\n *     editor: {\n *       component: CountrySelect,\n *       props: { showFlags: true }\n *     }\n *   }\n * ]\n * ```\n *\n * @see {@link ColumnEditorContext} for the context passed to factory functions\n */\nexport type ColumnEditorSpec<TRow = unknown, TValue = unknown> =\n  | string // custom element tag name\n  | ((context: ColumnEditorContext<TRow, TValue>) => HTMLElement | string)\n  | {\n      /** Arbitrary component reference (class, function, token) */\n      component: unknown;\n      /** Optional static props passed to mount */\n      props?: Record<string, unknown>;\n      /** Optional custom mount function; if provided we call it directly instead of emitting an event */\n      mount?: (options: {\n        placeholder: HTMLElement;\n        context: ColumnEditorContext<TRow, TValue>;\n        spec: unknown;\n      }) => void | { dispose?: () => void };\n    };\n\n/**\n * Context object provided to editor factories allowing mutation (commit/cancel) of a cell value.\n *\n * The `commit` and `cancel` functions control the editing lifecycle:\n * - Call `commit(newValue)` to save changes and exit edit mode\n * - Call `cancel()` to discard changes and exit edit mode\n *\n * @example\n * ```typescript\n * const myEditor: ColumnEditorSpec = (ctx: ColumnEditorContext) => {\n *   const input = document.createElement('input');\n *   input.value = ctx.value;\n *   input.className = 'my-editor';\n *\n *   // Save on Enter, cancel on Escape\n *   input.onkeydown = (e) => {\n *     if (e.key === 'Enter') {\n *       ctx.commit(input.value);\n *     } else if (e.key === 'Escape') {\n *       ctx.cancel();\n *     }\n *   };\n *\n *   // Access row data for validation\n *   if (ctx.row.locked) {\n *     input.disabled = true;\n *   }\n *\n *   return input;\n * };\n * ```\n *\n * @see {@link ColumnEditorSpec} for editor specification options\n */\nexport interface ColumnEditorContext<TRow = any, TValue = any> {\n  /** Underlying full row object for the active edit. */\n  row: TRow;\n  /** Current cell value (mutable only via commit). */\n  value: TValue;\n  /** Field name being edited. */\n  field: keyof TRow & string;\n  /** Column configuration reference. */\n  column: ColumnConfig<TRow>;\n  /**\n   * Stable row identifier (from `getRowId`).\n   * Empty string if no `getRowId` is configured.\n   */\n  rowId: string;\n  /** Accept the edit; triggers change tracking + rerender. */\n  commit: (newValue: TValue) => void;\n  /** Abort edit without persisting changes. */\n  cancel: () => void;\n  /**\n   * Update other fields in this row while the editor is open.\n   * Changes are committed with source `'cascade'`, triggering\n   * `cell-change` events and `onValueChange` pushes to sibling editors.\n   *\n   * Useful for editors that affect multiple fields (e.g., an address\n   * lookup that sets city + zip + state).\n   *\n   * @example\n   * ```typescript\n   * // In a cell-commit listener:\n   * grid.addEventListener('cell-commit', (e) => {\n   *   if (e.detail.field === 'quantity') {\n   *     e.detail.updateRow({ total: e.detail.row.price * e.detail.value });\n   *   }\n   * });\n   * ```\n   */\n  updateRow: (changes: Partial<TRow>) => void;\n  /**\n   * Register a callback invoked when the cell's underlying value changes\n   * while the editor is open (e.g., via `updateRow()` from another cell's commit).\n   *\n   * Built-in editors auto-update their input values. Custom/framework editors\n   * should use this to stay in sync with external mutations.\n   *\n   * @example\n   * ```typescript\n   * const editor = (ctx: ColumnEditorContext) => {\n   *   const input = document.createElement('input');\n   *   input.value = String(ctx.value);\n   *   ctx.onValueChange?.((newValue) => {\n   *     input.value = String(newValue);\n   *   });\n   *   return input;\n   * };\n   * ```\n   */\n  onValueChange?: (callback: (newValue: TValue) => void) => void;\n}\n// #endregion\n\n// #region Renderer Types\n/**\n * Context passed to custom view renderers (pure display – no commit helpers).\n *\n * Used by `viewRenderer` and `renderer` column properties to create\n * custom cell content. Return a DOM node or HTML string.\n *\n * @example\n * ```typescript\n * // Status badge renderer\n * const statusRenderer: ColumnViewRenderer = (ctx: CellRenderContext) => {\n *   const badge = document.createElement('span');\n *   badge.className = `badge badge-${ctx.value}`;\n *   badge.textContent = ctx.value;\n *   return badge;\n * };\n *\n * // Progress bar using row data\n * const progressRenderer: ColumnViewRenderer = (ctx) => {\n *   const bar = document.createElement('div');\n *   bar.className = 'progress-bar';\n *   bar.style.width = `${ctx.value}%`;\n *   bar.title = `${ctx.row.taskName}: ${ctx.value}%`;\n *   return bar;\n * };\n *\n * // Return HTML string (simpler, less performant)\n * const htmlRenderer: ColumnViewRenderer = (ctx) => {\n *   return `<strong>${ctx.value}</strong>`;\n * };\n * ```\n *\n * @see {@link ColumnViewRenderer} for the renderer function signature\n */\nexport interface CellRenderContext<TRow = any, TValue = any> {\n  /** Row object for the cell being rendered. */\n  row: TRow;\n  /** Value at field. */\n  value: TValue;\n  /** Field key. */\n  field: keyof TRow & string;\n  /** Column configuration reference. */\n  column: ColumnConfig<TRow>;\n  /**\n   * The cell DOM element being rendered into.\n   * Framework adapters can use this to cache per-cell state (e.g., React roots).\n   * @internal\n   */\n  cellEl?: HTMLElement;\n}\n\n/**\n * Custom view renderer function for cell content.\n *\n * Returns one of:\n * - `Node` - DOM element to display in the cell\n * - `string` - HTML string (parsed and inserted)\n * - `void | null` - Use default text rendering\n *\n * @example\n * ```typescript\n * // DOM element (recommended for interactivity)\n * const avatarRenderer: ColumnViewRenderer<Employee> = (ctx) => {\n *   const img = document.createElement('img');\n *   img.src = ctx.row.avatarUrl;\n *   img.alt = ctx.row.name;\n *   img.className = 'avatar';\n *   return img;\n * };\n *\n * // HTML string (simpler, good for static content)\n * const emailRenderer: ColumnViewRenderer = (ctx) => {\n *   return `<a href=\"mailto:${ctx.value}\">${ctx.value}</a>`;\n * };\n *\n * // Conditional rendering\n * const conditionalRenderer: ColumnViewRenderer = (ctx) => {\n *   if (!ctx.value) return null; // Use default\n *   return `<em>${ctx.value}</em>`;\n * };\n * ```\n *\n * @see {@link CellRenderContext} for available context properties\n */\nexport type ColumnViewRenderer<TRow = unknown, TValue = unknown> = (\n  ctx: CellRenderContext<TRow, TValue>,\n) => Node | string | void | null;\n// #endregion\n\n// #region Header Renderer Types\n/**\n * Context passed to `headerLabelRenderer` for customizing header label content.\n * The framework handles sort icons, filter buttons, resize handles, and click interactions.\n *\n * @example\n * ```typescript\n * headerLabelRenderer: (ctx) => {\n *   const span = document.createElement('span');\n *   span.innerHTML = `${ctx.value} <span class=\"required\">*</span>`;\n *   return span;\n * }\n * ```\n */\nexport interface HeaderLabelContext<TRow = unknown> {\n  /** Column configuration reference. */\n  column: ColumnConfig<TRow>;\n  /** The header text (from column.header or column.field). */\n  value: string;\n}\n\n/**\n * Context passed to `headerRenderer` for complete control over header cell content.\n * When using this, you control the header content. Resize handles are added automatically\n * for resizable columns.\n *\n * @example\n * ```typescript\n * headerRenderer: (ctx) => {\n *   const div = document.createElement('div');\n *   div.className = 'custom-header';\n *   div.innerHTML = `<span>${ctx.value}</span>`;\n *   // Optionally include sort icon\n *   const sortIcon = ctx.renderSortIcon();\n *   if (sortIcon) div.appendChild(sortIcon);\n *   return div;\n * }\n * ```\n */\nexport interface HeaderCellContext<TRow = unknown> {\n  /** Column configuration reference. */\n  column: ColumnConfig<TRow>;\n  /** The header text (from column.header or column.field). */\n  value: string;\n  /** Current sort state for this column. */\n  sortState: 'asc' | 'desc' | null;\n  /** Whether the column has an active filter. */\n  filterActive: boolean;\n  /** The header cell DOM element being rendered into. */\n  cellEl: HTMLElement;\n  /**\n   * Render the standard sort indicator icon.\n   * Returns null if column is not sortable.\n   */\n  renderSortIcon: () => HTMLElement | null;\n  /**\n   * Render the standard filter button.\n   * Returns null if FilteringPlugin is not active or column is not filterable.\n   * Note: The actual button is added by FilteringPlugin's afterRender hook.\n   */\n  renderFilterButton: () => HTMLElement | null;\n}\n\n/**\n * Header label renderer function type.\n * Customize the label while framework handles sort icons, filter buttons, resize handles.\n *\n * Use this for simple label customizations without taking over the entire header.\n * The grid automatically appends sort icons, filter buttons, and resize handles.\n *\n * @example\n * ```typescript\n * // Add required indicator\n * const requiredHeader: HeaderLabelRenderer = (ctx) => {\n *   return `${ctx.value} <span style=\"color: red;\">*</span>`;\n * };\n *\n * // Add unit suffix\n * const priceHeader: HeaderLabelRenderer = (ctx) => {\n *   const span = document.createElement('span');\n *   span.innerHTML = `${ctx.value} <small>(USD)</small>`;\n *   return span;\n * };\n *\n * // Column config usage\n * columns: [\n *   { field: 'name', headerLabelRenderer: requiredHeader },\n *   { field: 'price', headerLabelRenderer: priceHeader },\n * ]\n * ```\n *\n * @see {@link HeaderLabelContext} for context properties\n * @see {@link HeaderRenderer} for full header control\n */\nexport type HeaderLabelRenderer<TRow = unknown> = (ctx: HeaderLabelContext<TRow>) => Node | string | void | null;\n\n/**\n * Header cell renderer function type.\n * Full control over header cell content. User is responsible for all content and interactions.\n *\n * When using this, you have complete control but must manually include\n * sort icons, filter buttons, and resize handles using the helper functions.\n *\n * @example\n * ```typescript\n * // Custom header with all standard elements\n * const customHeader: HeaderRenderer = (ctx) => {\n *   const div = document.createElement('div');\n *   div.className = 'custom-header';\n *   div.innerHTML = `<span class=\"label\">${ctx.value}</span>`;\n *\n *   // Add sort icon (returns null if not sortable)\n *   const sortIcon = ctx.renderSortIcon();\n *   if (sortIcon) div.appendChild(sortIcon);\n *\n *   // Add filter button (returns null if not filterable)\n *   const filterBtn = ctx.renderFilterButton();\n *   if (filterBtn) div.appendChild(filterBtn);\n *\n *   // Resize handles are added automatically for resizable columns\n *   return div;\n * };\n *\n * // Minimal header (no sort/resize)\n * const minimalHeader: HeaderRenderer = (ctx) => {\n *   return `<div class=\"minimal\">${ctx.value}</div>`;\n * };\n *\n * // Column config usage\n * columns: [\n *   { field: 'name', headerRenderer: customHeader },\n * ]\n * ```\n *\n * @see {@link HeaderCellContext} for context properties and helper functions\n * @see {@link HeaderLabelRenderer} for simpler label-only customization\n */\nexport type HeaderRenderer<TRow = unknown> = (ctx: HeaderCellContext<TRow>) => Node | string | void | null;\n// #endregion\n\n// #region Framework Adapter Interface\n/**\n * Framework adapter interface for handling framework-specific component instantiation.\n * Allows framework libraries (Angular, React, Vue) to register handlers that convert\n * declarative light DOM elements into functional renderers/editors.\n *\n * @example\n * ```typescript\n * // In @toolbox-web/grid-angular\n * class AngularGridAdapter implements FrameworkAdapter {\n *   canHandle(element: HTMLElement): boolean {\n *     return element.tagName.startsWith('APP-');\n *   }\n *   createRenderer(element: HTMLElement): ColumnViewRenderer {\n *     return (ctx) => {\n *       // Angular-specific instantiation logic\n *       const componentRef = createComponent(...);\n *       componentRef.setInput('value', ctx.value);\n *       return componentRef.location.nativeElement;\n *     };\n *   }\n *   createEditor(element: HTMLElement): ColumnEditorSpec {\n *     return (ctx) => {\n *       // Angular-specific editor with commit/cancel\n *       const componentRef = createComponent(...);\n *       componentRef.setInput('value', ctx.value);\n *       // Subscribe to commit/cancel outputs\n *       return componentRef.location.nativeElement;\n *     };\n *   }\n * }\n *\n * // User registers adapter once in their app\n * GridElement.registerAdapter(new AngularGridAdapter(injector, appRef));\n * ```\n * @category Framework Adapters\n */\nexport interface FrameworkAdapter {\n  /**\n   * Determines if this adapter can handle the given element.\n   * Typically checks tag name, attributes, or other conventions.\n   */\n  canHandle(element: HTMLElement): boolean;\n\n  /**\n   * Creates a view renderer function from a light DOM element.\n   * The renderer receives cell context and returns DOM or string.\n   */\n  createRenderer<TRow = unknown, TValue = unknown>(element: HTMLElement): ColumnViewRenderer<TRow, TValue>;\n\n  /**\n   * Creates an editor spec from a light DOM element.\n   * The editor receives context with commit/cancel and returns DOM.\n   * Returns undefined if no editor template is registered, allowing the grid\n   * to use its default built-in editors.\n   */\n  createEditor<TRow = unknown, TValue = unknown>(element: HTMLElement): ColumnEditorSpec<TRow, TValue> | undefined;\n\n  /**\n   * Creates a tool panel renderer from a light DOM element.\n   * The renderer receives a container element and optionally returns a cleanup function.\n   */\n  createToolPanelRenderer?(element: HTMLElement): ((container: HTMLElement) => void | (() => void)) | undefined;\n\n  /**\n   * Gets type-level defaults from an application-level registry.\n   * Used by Angular's `GridTypeRegistry` and React's `GridTypeProvider`.\n   *\n   * @param type - The column type (e.g., 'date', 'currency', 'country')\n   * @returns Type defaults for renderer/editor, or undefined if not registered\n   */\n  getTypeDefault?<TRow = unknown>(type: string): TypeDefault<TRow> | undefined;\n\n  /**\n   * Called when a cell's content is about to be wiped (e.g., when exiting edit mode,\n   * scroll-recycling a row, or rebuilding a row).\n   *\n   * Framework adapters should use this to properly destroy cached views/components\n   * associated with the cell to prevent memory leaks.\n   *\n   * @param cellEl - The cell element whose content is being released\n   */\n  releaseCell?(cellEl: HTMLElement): void;\n\n  /**\n   * Unmount a specific framework container and free its resources.\n   *\n   * Called by the grid core (e.g., MasterDetailPlugin) when a container\n   * created by the adapter is about to be removed from the DOM.\n   * The adapter should destroy the associated framework instance\n   * (React root, Vue app, Angular view) and remove it from tracking arrays.\n   *\n   * @param container - The container element returned by a create* method\n   */\n  unmount?(container: HTMLElement): void;\n}\n// #endregion\n\n// #region Internal Types\n\n/**\n * Column internal properties used during light DOM parsing.\n * Stores attribute-based names before they're resolved to actual functions.\n * @internal\n */\nexport interface ColumnParsedAttributes {\n  /** Editor name from `editor` attribute (resolved later) */\n  __editorName?: string;\n  /** Renderer name from `renderer` attribute (resolved later) */\n  __rendererName?: string;\n}\n\n/**\n * Extended column config used internally.\n * Includes all internal properties needed during grid lifecycle.\n *\n * Plugin developers may need to access these when working with\n * column caching and compiled templates.\n *\n * @example\n * ```typescript\n * import type { ColumnInternal } from '@toolbox-web/grid';\n *\n * class MyPlugin extends BaseGridPlugin {\n *   afterRender(): void {\n *     // Access internal column properties\n *     const columns = this.columns as ColumnInternal[];\n *     for (const col of columns) {\n *       // Check if column was auto-sized\n *       if (col.__autoSized) {\n *         console.log(`${col.field} was auto-sized`);\n *       }\n *     }\n *   }\n * }\n * ```\n *\n * @see {@link ColumnConfig} for public column properties\n * @category Plugin Development\n * @internal\n */\nexport interface ColumnInternal<T = any> extends ColumnConfig<T>, ColumnParsedAttributes {\n  __autoSized?: boolean;\n  __userResized?: boolean;\n  __renderedWidth?: number;\n  /** Original configured width (for reset on double-click) */\n  __originalWidth?: number;\n  __viewTemplate?: HTMLElement;\n  __editorTemplate?: HTMLElement;\n  __headerTemplate?: HTMLElement;\n  __compiledView?: CompiledViewFunction<T>;\n  __compiledEditor?: (ctx: EditorExecContext<T>) => string;\n}\n\n/**\n * Row element with internal tracking properties.\n * Used during virtualization and row pooling.\n *\n * @category Plugin Development\n * @internal\n */\nexport interface RowElementInternal extends HTMLElement {\n  /** Epoch marker for row render invalidation */\n  __epoch?: number;\n  /** Reference to the row data object for change detection */\n  __rowDataRef?: unknown;\n  /** Count of cells currently in edit mode */\n  __editingCellCount?: number;\n  /** Flag indicating this is a custom-rendered row (group row, etc.) */\n  __isCustomRow?: boolean;\n}\n\n/**\n * Type-safe access to element.part API (DOMTokenList-like).\n * Used for CSS ::part styling support.\n * @internal\n */\nexport interface ElementWithPart {\n  part?: DOMTokenList;\n}\n\n/**\n * Compiled view function type with optional blocked flag.\n * The __blocked flag is set when a template contains unsafe expressions.\n *\n * @category Plugin Development\n * @internal\n */\nexport interface CompiledViewFunction<T = any> {\n  (ctx: CellContext<T>): string;\n  /** Set to true when template was blocked due to unsafe expressions */\n  __blocked?: boolean;\n}\n\n/**\n * Runtime cell context used internally for compiled template execution.\n *\n * Contains the minimal context needed to render a cell: the row data,\n * cell value, field name, and column configuration.\n *\n * @example\n * ```typescript\n * import type { CellContext, ColumnInternal } from '@toolbox-web/grid';\n *\n * // Used internally by compiled templates\n * const renderCell = (ctx: CellContext) => {\n *   return `<span title=\"${ctx.field}\">${ctx.value}</span>`;\n * };\n * ```\n *\n * @see {@link CellRenderContext} for public cell render context\n * @see {@link EditorExecContext} for editor context with commit/cancel\n * @category Plugin Development\n */\nexport interface CellContext<T = any> {\n  row: T;\n  value: unknown;\n  field: string;\n  column: ColumnInternal<T>;\n}\n\n/**\n * Internal editor execution context extending the generic cell context with commit helpers.\n *\n * Used internally by the editing system. For public editor APIs,\n * prefer using {@link ColumnEditorContext}.\n *\n * @example\n * ```typescript\n * import type { EditorExecContext } from '@toolbox-web/grid';\n *\n * // Internal editor template execution\n * const execEditor = (ctx: EditorExecContext) => {\n *   const input = document.createElement('input');\n *   input.value = String(ctx.value);\n *   input.onkeydown = (e) => {\n *     if (e.key === 'Enter') ctx.commit(input.value);\n *     if (e.key === 'Escape') ctx.cancel();\n *   };\n *   return input;\n * };\n * ```\n *\n * @see {@link ColumnEditorContext} for public editor context\n * @see {@link CellContext} for base cell context\n * @category Plugin Development\n */\nexport interface EditorExecContext<T = any> extends CellContext<T> {\n  commit: (newValue: unknown) => void;\n  cancel: () => void;\n}\n\n/**\n * Controller managing drag-based column resize lifecycle.\n *\n * Exposed internally for plugins that need to interact with resize behavior.\n *\n * @example\n * ```typescript\n * import type { ResizeController, InternalGrid } from '@toolbox-web/grid';\n *\n * class MyPlugin extends BaseGridPlugin {\n *   handleColumnAction(colIndex: number): void {\n *     const grid = this.grid as InternalGrid;\n *     const resizeCtrl = grid._resizeController;\n *\n *     // Check if resize is in progress\n *     if (resizeCtrl?.isResizing) {\n *       return; // Don't interfere\n *     }\n *\n *     // Reset column to configured width\n *     resizeCtrl?.resetColumn(colIndex);\n *   }\n * }\n * ```\n *\n * @see {@link ColumnResizeDetail} for resize event details\n * @category Plugin Development\n */\nexport interface ResizeController {\n  start: (e: MouseEvent, colIndex: number, cell: HTMLElement) => void;\n  /** Reset a column to its configured width (or auto-size if none configured). */\n  resetColumn: (colIndex: number) => void;\n  dispose: () => void;\n  /** True while a resize drag is in progress (used to suppress header click/sort). */\n  isResizing: boolean;\n}\n\n/**\n * Virtual window bookkeeping; modified in-place as scroll position changes.\n *\n * Tracks virtualization state for row rendering. The grid only renders\n * rows within the visible viewport window (start to end) plus overscan.\n *\n * @example\n * ```typescript\n * import type { VirtualState, InternalGrid } from '@toolbox-web/grid';\n *\n * class MyPlugin extends BaseGridPlugin {\n *   logVirtualWindow(): void {\n *     const grid = this.grid as InternalGrid;\n *     const vs = grid.virtualization;\n *\n *     console.log(`Row height: ${vs.rowHeight}px`);\n *     console.log(`Visible rows: ${vs.start} to ${vs.end}`);\n *     console.log(`Virtualization: ${vs.enabled ? 'on' : 'off'}`);\n *   }\n * }\n * ```\n *\n * @see {@link GridConfig.rowHeight} for configuring row height\n * @category Plugin Development\n */\nexport interface VirtualState {\n  enabled: boolean;\n  rowHeight: number;\n  /** Threshold for bypassing virtualization (renders all rows if totalRows <= bypassThreshold) */\n  bypassThreshold: number;\n  start: number;\n  end: number;\n  /** Faux scrollbar element that provides scroll events (AG Grid pattern) */\n  container: HTMLElement | null;\n  /** Rows viewport element for measuring visible area height */\n  viewportEl: HTMLElement | null;\n  /** Spacer element inside faux scrollbar for setting virtual height */\n  totalHeightEl: HTMLElement | null;\n\n  // --- Variable Row Height Support (Phase 1) ---\n\n  /**\n   * Position cache for variable row heights.\n   * Index-based array mapping row index → {offset, height, measured}.\n   * Rebuilt when row count changes (expand/collapse, filter).\n   * `null` when using uniform row heights (default).\n   */\n  positionCache: RowPositionEntry[] | null;\n\n  /**\n   * Height cache by row identity.\n   * Persists row heights across position cache rebuilds.\n   * Uses dual storage: Map for string keys (rowId, __rowCacheKey) and WeakMap for object refs.\n   */\n  heightCache: {\n    /** Heights keyed by string (synthetic rows with __rowCacheKey, or rowId-keyed rows) */\n    byKey: Map<string, number>;\n    /** Heights keyed by object reference (data rows without rowId) */\n    byRef: WeakMap<object, number>;\n  };\n\n  /** Running average of measured row heights. Used for estimating unmeasured rows. */\n  averageHeight: number;\n\n  /** Number of rows that have been measured. */\n  measuredCount: number;\n\n  /** Whether variable row height mode is active (rowHeight is a function). */\n  variableHeights: boolean;\n\n  // --- Cached Geometry (avoid forced layout reads on scroll hot path) ---\n\n  /** Cached viewport element height. Updated by ResizeObserver and force-refresh only. */\n  cachedViewportHeight: number;\n\n  /** Cached faux scrollbar element height. Updated alongside viewport height. */\n  cachedFauxHeight: number;\n\n  /** Cached scroll-area element height. Updated alongside viewport/faux heights. */\n  cachedScrollAreaHeight: number;\n\n  /** Cached reference to .tbw-scroll-area element. Set during scroll listener setup. */\n  scrollAreaEl: HTMLElement | null;\n}\n\n// RowElementInternal is now defined earlier in the file with all internal properties\n\n/**\n * Union type for input-like elements that have a `value` property.\n * Covers standard form elements and custom elements with value semantics.\n *\n * @category Plugin Development\n * @internal\n */\nexport type InputLikeElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | { value: unknown };\n// #endregion\n\n// #region Grouping & Footer Public Types\n/**\n * Group row rendering customization options.\n * Controls how group header rows are displayed in the GroupingRowsPlugin.\n *\n * @example\n * ```typescript\n * import { GroupingRowsPlugin } from '@toolbox-web/grid/all';\n *\n * new GroupingRowsPlugin({\n *   groupBy: ['department', 'team'],\n *   render: {\n *     // Group row spans all columns\n *     fullWidth: true,\n *\n *     // Custom label format\n *     formatLabel: (value, depth, key) => {\n *       if (depth === 0) return `Department: ${value}`;\n *       return `Team: ${value}`;\n *     },\n *\n *     // Show aggregates in group rows (when not fullWidth)\n *     aggregators: {\n *       salary: 'sum',\n *       age: 'avg',\n *     },\n *\n *     // Custom CSS class\n *     class: 'my-group-row',\n *   },\n * });\n * ```\n *\n * @see {@link AggregatorRef} for aggregation options\n */\nexport interface RowGroupRenderConfig {\n  /** If true, group rows span all columns (single full-width cell). Default false. */\n  fullWidth?: boolean;\n  /** Optional label formatter override. Receives raw group value + depth. */\n  formatLabel?: (value: unknown, depth: number, key: string) => string;\n  /** Optional aggregate overrides per field for group summary cells (only when not fullWidth). */\n  aggregators?: Record<string, AggregatorRef>;\n  /** Additional CSS class applied to each group row root element. */\n  class?: string;\n}\n\n/**\n * Reference to an aggregation function for footer/group summaries.\n *\n * Can be either:\n * - A built-in aggregator name: `'sum'`, `'avg'`, `'min'`, `'max'`, `'count'`\n * - A custom function that calculates the aggregate value\n *\n * @example\n * ```typescript\n * // Built-in aggregator\n * { field: 'amount', aggregator: 'sum' }\n *\n * // Custom aggregator function\n * { field: 'price', aggregator: (rows, field) => {\n *   const values = rows.map(r => r[field]).filter(v => v != null);\n *   return values.length ? Math.max(...values) : null;\n * }}\n * ```\n *\n * @see {@link RowGroupRenderConfig} for using aggregators in group rows\n */\nexport type AggregatorRef = string | ((rows: unknown[], field: string, column?: unknown) => unknown);\n\n/**\n * Result of automatic column inference from sample rows.\n *\n * When no columns are configured, the grid analyzes the first row of data\n * to automatically generate column definitions with inferred types.\n *\n * @example\n * ```typescript\n * // Automatic inference (no columns configured)\n * grid.rows = [\n *   { name: 'Alice', age: 30, active: true, hireDate: new Date() },\n * ];\n * // Grid infers:\n * // - name: type 'string'\n * // - age: type 'number'\n * // - active: type 'boolean'\n * // - hireDate: type 'date'\n *\n * // Access inferred result programmatically\n * const config = await grid.getConfig();\n * console.log(config.columns); // Inferred columns\n * ```\n *\n * @see {@link ColumnConfig} for column configuration options\n * @see {@link ColumnType} for type inference rules\n */\nexport interface InferredColumnResult<TRow = unknown> {\n  /** Generated column configurations based on data analysis */\n  columns: ColumnConfigMap<TRow>;\n  /** Map of field names to their inferred types */\n  typeMap: Record<string, ColumnType>;\n}\n\n/**\n * Column sizing mode.\n *\n * - `'fixed'` - Columns use their configured widths. Horizontal scrolling if content overflows.\n * - `'stretch'` - Columns stretch proportionally to fill available width. No horizontal scrolling.\n *\n * @example\n * ```typescript\n * // Fixed widths - good for many columns\n * grid.fitMode = 'fixed';\n *\n * // Stretch to fill - good for few columns\n * grid.fitMode = 'stretch';\n *\n * // Via gridConfig\n * grid.gridConfig = { fitMode: 'stretch' };\n * ```\n */\nexport const FitModeEnum = {\n  STRETCH: 'stretch',\n  FIXED: 'fixed',\n} as const;\nexport type FitMode = (typeof FitModeEnum)[keyof typeof FitModeEnum]; // evaluates to 'stretch' | 'fixed'\n// #endregion\n\n// #region Plugin Interface\n/**\n * Minimal plugin interface for type-checking.\n * This interface is defined here to avoid circular imports with BaseGridPlugin.\n * All plugins must satisfy this shape (BaseGridPlugin implements it).\n *\n * @example\n * ```typescript\n * // Using plugins in grid config\n * import { SelectionPlugin, FilteringPlugin } from '@toolbox-web/grid/all';\n *\n * grid.gridConfig = {\n *   plugins: [\n *     new SelectionPlugin({ mode: 'row' }),\n *     new FilteringPlugin({ debounceMs: 200 }),\n *   ],\n * };\n *\n * // Accessing plugin instance at runtime\n * const selection = grid.getPlugin(SelectionPlugin);\n * if (selection) {\n *   selection.selectAll();\n * }\n * ```\n *\n * @category Plugin Development\n */\nexport interface GridPlugin {\n  /** Unique plugin identifier */\n  readonly name: string;\n  /** Plugin version */\n  readonly version: string;\n  /** CSS styles to inject into the grid */\n  readonly styles?: string;\n}\n\n/**\n * Plugin name-to-type registry for type-safe `getPluginByName()`.\n *\n * Plugins augment this interface via `declare module` so that\n * `grid.getPluginByName('editing')` returns `EditingPlugin | undefined`\n * instead of `GridPlugin | undefined`.\n *\n * @example\n * ```typescript\n * // Plugin augmentation (done automatically when you import a plugin):\n * declare module '../../core/types' {\n *   interface PluginNameMap {\n *     editing: EditingPlugin;\n *   }\n * }\n *\n * // Consumer usage — fully typed:\n * const editing = grid.getPluginByName('editing');\n * editing?.beginBulkEdit(0); // ✅ No cast needed\n * ```\n *\n * @category Plugin Development\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/no-empty-interface\nexport interface PluginNameMap {}\n// #endregion\n\n// #region Grid Config\n/**\n * Grid configuration object - the **single source of truth** for grid behavior.\n *\n * Users can configure the grid via multiple input methods, all of which converge\n * into an effective `GridConfig` internally:\n *\n * **Configuration Input Methods:**\n * - `gridConfig` property - direct assignment of this object\n * - `columns` property - shorthand for `gridConfig.columns`\n * - `fitMode` property - shorthand for `gridConfig.fitMode`\n * - Light DOM `<tbw-grid-column>` - declarative columns (merged into `columns`)\n * - Light DOM `<tbw-grid-header>` - declarative shell header (merged into `shell.header`)\n *\n * **Precedence (when same property set multiple ways):**\n * Individual props (`fitMode`) > `columns` prop > Light DOM > `gridConfig`\n *\n * @example\n * ```ts\n * // Via gridConfig (recommended for complex setups)\n * grid.gridConfig = {\n *   columns: [{ field: 'name' }, { field: 'age' }],\n *   fitMode: 'stretch',\n *   plugins: [new SelectionPlugin()],\n *   shell: { header: { title: 'My Grid' } }\n * };\n *\n * // Via individual props (convenience for simple cases)\n * grid.columns = [{ field: 'name' }, { field: 'age' }];\n * grid.fitMode = 'stretch';\n * ```\n */\nexport interface GridConfig<TRow = any> {\n  /**\n   * Column definitions. Can also be set via `columns` prop or `<tbw-grid-column>` light DOM.\n   * @see {@link ColumnConfig} for column options\n   * @see {@link ColumnConfigMap}\n   */\n  columns?: ColumnConfigMap<TRow>;\n  /**\n   * Dynamic CSS class(es) for data rows.\n   * Called for each row during rendering. Return class names to add to the row element.\n   *\n   * @example\n   * ```typescript\n   * // Highlight inactive rows\n   * rowClass: (row) => row.active ? [] : ['inactive', 'dimmed']\n   *\n   * // Status-based row styling\n   * rowClass: (row) => [`priority-${row.priority}`]\n   * ```\n   */\n  rowClass?: (row: TRow) => string[];\n  /** Sizing mode for columns. Can also be set via `fitMode` prop. */\n  fitMode?: FitMode;\n\n  /**\n   * Grid-wide sorting toggle.\n   * When false, disables sorting for all columns regardless of their individual `sortable` setting.\n   * When true (default), columns with `sortable: true` can be sorted.\n   *\n   * This affects:\n   * - Header click handlers for sorting\n   * - Sort indicator visibility\n   * - Multi-sort plugin behavior (if loaded)\n   *\n   * @default true\n   *\n   * @example\n   * ```typescript\n   * // Disable all sorting\n   * gridConfig = { sortable: false };\n   *\n   * // Enable sorting (default) - individual columns still need sortable: true\n   * gridConfig = { sortable: true };\n   * ```\n   */\n  sortable?: boolean;\n\n  /**\n   * Grid-wide resizing toggle.\n   * When false, disables column resizing for all columns regardless of their individual `resizable` setting.\n   * When true (default), columns with `resizable: true` (or resizable not set, since it defaults to true) can be resized.\n   *\n   * This affects:\n   * - Resize handle visibility in header cells\n   * - Double-click to auto-size behavior\n   *\n   * @default true\n   *\n   * @example\n   * ```typescript\n   * // Disable all column resizing\n   * gridConfig = { resizable: false };\n   *\n   * // Enable resizing (default) - individual columns can opt out with resizable: false\n   * gridConfig = { resizable: true };\n   * ```\n   */\n  resizable?: boolean;\n\n  /**\n   * Row height in pixels for virtualization calculations.\n   * The virtualization system assumes uniform row heights for performance.\n   *\n   * If not specified, the grid measures the first rendered row's height,\n   * which respects the CSS variable `--tbw-row-height` set by themes.\n   *\n   * Set this explicitly when:\n   * - Row content may wrap to multiple lines (also set `--tbw-cell-white-space: normal`)\n   * - Using custom row templates with variable content\n   * - You want to override theme-defined row height\n   * - Rows have different heights based on content (use function form)\n   *\n   * **Variable Row Heights**: When a function is provided, the grid enables variable height\n   * virtualization. Heights are measured on first render and cached by row identity.\n   *\n   * @default Auto-measured from first row (respects --tbw-row-height CSS variable)\n   *\n   * @example\n   * ```ts\n   * // Fixed height for all rows\n   * gridConfig = { rowHeight: 56 };\n   *\n   * // Variable height based on content\n   * gridConfig = {\n   *   rowHeight: (row, index) => row.hasDetails ? 80 : 40,\n   * };\n   *\n   * // Return undefined to trigger DOM auto-measurement\n   * gridConfig = {\n   *   rowHeight: (row) => row.isExpanded ? undefined : 40,\n   * };\n   * ```\n   */\n  rowHeight?: number | ((row: TRow, index: number) => number | undefined);\n  /**\n   * Array of plugin instances.\n   * Each plugin is instantiated with its configuration and attached to this grid.\n   *\n   * @example\n   * ```ts\n   * plugins: [\n   *   new SelectionPlugin({ mode: 'range' }),\n   *   new MultiSortPlugin(),\n   *   new FilteringPlugin({ debounceMs: 150 }),\n   * ]\n   * ```\n   */\n  plugins?: GridPlugin[];\n\n  /**\n   * Saved column state to restore on initialization.\n   * Includes order, width, visibility, sort, and plugin-contributed state.\n   */\n  columnState?: GridColumnState;\n\n  /**\n   * Shell configuration for header bar and tool panels.\n   * When configured, adds an optional wrapper with title, toolbar, and collapsible side panels.\n   */\n  shell?: ShellConfig;\n\n  /**\n   * Grid-wide icon configuration.\n   * Provides consistent icons across all plugins (tree, grouping, sorting, etc.).\n   * Plugins will use these by default but can override with their own config.\n   */\n  icons?: GridIcons;\n\n  /**\n   * Grid-wide animation configuration.\n   * Controls animations for expand/collapse, reordering, and other visual transitions.\n   * Individual plugins can override these defaults in their own config.\n   */\n  animation?: AnimationConfig;\n\n  /**\n   * Custom sort handler for full control over sorting behavior.\n   *\n   * When provided, this handler is called instead of the built-in sorting logic.\n   * Enables custom sorting algorithms, server-side sorting, or plugin-specific sorting.\n   *\n   * The handler receives:\n   * - `rows`: Current row array to sort\n   * - `sortState`: Sort field and direction (1 = asc, -1 = desc)\n   * - `columns`: Column configurations (for accessing sortComparator)\n   *\n   * Return the sorted array (sync) or a Promise that resolves to the sorted array (async).\n   * For server-side sorting, return a Promise that resolves when data is fetched.\n   *\n   * @example\n   * ```ts\n   * // Custom stable sort\n   * sortHandler: (rows, state, cols) => {\n   *   return stableSort(rows, (a, b) => compare(a[state.field], b[state.field]) * state.direction);\n   * }\n   *\n   * // Server-side sorting\n   * sortHandler: async (rows, state) => {\n   *   const response = await fetch(`/api/data?sort=${state.field}&dir=${state.direction}`);\n   *   return response.json();\n   * }\n   * ```\n   */\n  sortHandler?: SortHandler<TRow>;\n\n  /**\n   * Function to extract a unique identifier from a row.\n   * Used by `updateRow()`, `getRow()`, and ID-based tracking.\n   *\n   * If not provided, falls back to `row.id` or `row._id` if present.\n   * Rows without IDs are silently skipped during map building.\n   * Only throws when explicitly calling `getRowId()` or `updateRow()` on a row without an ID.\n   *\n   * @example\n   * ```ts\n   * // Simple field\n   * getRowId: (row) => row.id\n   *\n   * // Composite key\n   * getRowId: (row) => `${row.voyageId}-${row.legNumber}`\n   *\n   * // UUID field\n   * getRowId: (row) => row.uuid\n   * ```\n   */\n  getRowId?: (row: TRow) => string;\n\n  /**\n   * Type-level renderer and editor defaults.\n   *\n   * Keys can be:\n   * - Built-in types: `'string'`, `'number'`, `'date'`, `'boolean'`, `'select'`\n   * - Custom types: `'currency'`, `'country'`, `'status'`, etc.\n   *\n   * Resolution order (highest priority first):\n   * 1. Column-level (`column.renderer` / `column.editor`)\n   * 2. Grid-level (`gridConfig.typeDefaults[column.type]`)\n   * 3. App-level (Angular `GridTypeRegistry`, React `GridTypeProvider`)\n   * 4. Built-in (checkbox for boolean, select for select, etc.)\n   * 5. Fallback (plain text / text input)\n   *\n   * @example\n   * ```typescript\n   * typeDefaults: {\n   *   date: { editor: myDatePickerEditor },\n   *   country: {\n   *     renderer: (ctx) => {\n   *       const span = document.createElement('span');\n   *       span.innerHTML = `<img src=\"/flags/${ctx.value}.svg\" /> ${ctx.value}`;\n   *       return span;\n   *     },\n   *     editor: (ctx) => createCountrySelect(ctx)\n   *   }\n   * }\n   * ```\n   */\n  typeDefaults?: Record<string, TypeDefault<TRow>>;\n\n  // #region Accessibility\n\n  /**\n   * Accessible label for the grid.\n   * Sets `aria-label` on the grid's internal table element for screen readers.\n   *\n   * If not provided and `shell.header.title` is set, the title is used automatically.\n   *\n   * @example\n   * ```ts\n   * gridConfig = { gridAriaLabel: 'Employee data' };\n   * ```\n   */\n  gridAriaLabel?: string;\n\n  /**\n   * ID of an element that describes the grid.\n   * Sets `aria-describedby` on the grid's internal table element.\n   *\n   * @example\n   * ```html\n   * <p id=\"grid-desc\">This table shows all active employees.</p>\n   * <tbw-grid></tbw-grid>\n   * ```\n   * ```ts\n   * gridConfig = { gridAriaDescribedBy: 'grid-desc' };\n   * ```\n   */\n  gridAriaDescribedBy?: string;\n\n  // #endregion\n\n  // #region Loading\n\n  /**\n   * Custom renderer for the loading overlay.\n   *\n   * When provided, replaces the default spinner with custom content.\n   * Receives a context object with the current loading size.\n   *\n   * @example\n   * ```typescript\n   * // Simple text loading indicator\n   * loadingRenderer: () => {\n   *   const el = document.createElement('div');\n   *   el.textContent = 'Loading...';\n   *   return el;\n   * }\n   *\n   * // Custom spinner component\n   * loadingRenderer: (ctx) => {\n   *   const spinner = document.createElement('my-spinner');\n   *   spinner.size = ctx.size === 'large' ? 48 : 24;\n   *   return spinner;\n   * }\n   * ```\n   */\n  loadingRenderer?: LoadingRenderer;\n\n  // #endregion\n}\n// #endregion\n\n// #region Animation\n\n/**\n * Sort state passed to custom sort handlers.\n * Represents the current sorting configuration for a column.\n *\n * @example\n * ```typescript\n * // In a custom sort handler\n * const sortHandler: SortHandler = (rows, sortState, columns) => {\n *   const { field, direction } = sortState;\n *   console.log(`Sorting by ${field} ${direction === 1 ? 'ASC' : 'DESC'}`);\n *\n *   return [...rows].sort((a, b) => {\n *     const aVal = a[field];\n *     const bVal = b[field];\n *     return (aVal < bVal ? -1 : aVal > bVal ? 1 : 0) * direction;\n *   });\n * };\n * ```\n *\n * @see {@link SortHandler} for custom sort handler signature\n * @see {@link SortChangeDetail} for sort change events\n */\nexport interface SortState {\n  /** Field to sort by */\n  field: string;\n  /** Sort direction: 1 = ascending, -1 = descending */\n  direction: 1 | -1;\n}\n\n/**\n * Custom sort handler function signature.\n *\n * Enables full control over sorting behavior including server-side sorting,\n * custom algorithms, or multi-column sorting.\n *\n * @param rows - Current row array to sort\n * @param sortState - Sort field and direction\n * @param columns - Column configurations (for accessing sortComparator)\n * @returns Sorted array (sync) or Promise resolving to sorted array (async)\n *\n * @example\n * ```typescript\n * // Custom client-side sort with locale awareness\n * const localeSortHandler: SortHandler<Employee> = (rows, state, cols) => {\n *   const col = cols.find(c => c.field === state.field);\n *   return [...rows].sort((a, b) => {\n *     const aVal = String(a[state.field] ?? '');\n *     const bVal = String(b[state.field] ?? '');\n *     return aVal.localeCompare(bVal) * state.direction;\n *   });\n * };\n *\n * // Server-side sorting\n * const serverSortHandler: SortHandler<Employee> = async (rows, state) => {\n *   const response = await fetch(\n *     `/api/employees?sortBy=${state.field}&dir=${state.direction}`\n *   );\n *   return response.json();\n * };\n *\n * grid.gridConfig = {\n *   sortHandler: localeSortHandler,\n * };\n * ```\n *\n * @see {@link SortState} for the sort state object\n * @see {@link GridConfig.sortHandler} for configuring the handler\n * @see {@link BaseColumnConfig.sortComparator} for column-level comparators\n */\nexport type SortHandler<TRow = any> = (\n  rows: TRow[],\n  sortState: SortState,\n  columns: ColumnConfig<TRow>[],\n) => TRow[] | Promise<TRow[]>;\n\n// #region Loading\n\n/**\n * Loading indicator size variant.\n *\n * - `'large'`: 48x48px max - used for grid-level loading overlay (`grid.loading = true`)\n * - `'small'`: Follows row height - used for row/cell loading states\n *\n * @example\n * ```typescript\n * // Custom loading renderer adapting to size\n * const myLoader: LoadingRenderer = (ctx) => {\n *   if (ctx.size === 'large') {\n *     // Full overlay spinner\n *     return '<div class=\"spinner-lg\"></div>';\n *   }\n *   // Inline row/cell spinner\n *   return '<span class=\"spinner-sm\"></span>';\n * };\n * ```\n *\n * @see {@link LoadingRenderer} for custom loading renderer\n * @see {@link LoadingContext} for context passed to renderers\n */\nexport type LoadingSize = 'large' | 'small';\n\n/**\n * Context passed to custom loading renderers.\n *\n * Provides information about the loading indicator being rendered,\n * allowing the renderer to adapt its appearance based on the size variant.\n *\n * @example\n * ```typescript\n * const myLoadingRenderer: LoadingRenderer = (ctx: LoadingContext) => {\n *   if (ctx.size === 'large') {\n *     // Full-size spinner for grid-level loading\n *     return '<div class=\"large-spinner\"></div>';\n *   } else {\n *     // Compact spinner for row/cell loading\n *     return '<div class=\"small-spinner\"></div>';\n *   }\n * };\n * ```\n *\n * @see {@link LoadingRenderer} for the renderer function signature\n * @see {@link LoadingSize} for available size variants\n */\nexport interface LoadingContext {\n  /** The size variant being rendered: 'large' for grid-level, 'small' for row/cell */\n  size: LoadingSize;\n}\n\n/**\n * Custom loading renderer function.\n * Returns an element or HTML string to display as the loading indicator.\n *\n * Used with the `loadingRenderer` property in {@link GridConfig} to replace\n * the default spinner with custom content.\n *\n * @param context - Context containing size information\n * @returns HTMLElement or HTML string\n *\n * @example\n * ```typescript\n * // Simple text loading indicator\n * const textLoader: LoadingRenderer = () => {\n *   const el = document.createElement('div');\n *   el.textContent = 'Loading...';\n *   return el;\n * };\n *\n * // Custom spinner with size awareness\n * const customSpinner: LoadingRenderer = (ctx) => {\n *   const spinner = document.createElement('my-spinner');\n *   spinner.size = ctx.size === 'large' ? 48 : 24;\n *   return spinner;\n * };\n *\n * // Material Design-style progress bar\n * const progressBar: LoadingRenderer = () => {\n *   const container = document.createElement('div');\n *   container.className = 'progress-bar-container';\n *   container.innerHTML = '<div class=\"progress-bar\"></div>';\n *   return container;\n * };\n *\n * grid.gridConfig = {\n *   loadingRenderer: customSpinner,\n * };\n * ```\n *\n * @see {@link LoadingContext} for the context object passed to the renderer\n * @see {@link LoadingSize} for size variants ('large' | 'small')\n */\nexport type LoadingRenderer = (context: LoadingContext) => HTMLElement | string;\n\n// #endregion\n\n// #region Data Update Management\n\n/**\n * Indicates the origin of a data change.\n * Used to prevent infinite loops in cascade update handlers.\n *\n * - `'user'`: Direct user interaction via EditingPlugin (typing, selecting)\n * - `'cascade'`: Triggered by `updateRow()` in an event handler\n * - `'api'`: External programmatic update via `grid.updateRow()`\n *\n * @example\n * ```typescript\n * grid.addEventListener('cell-change', (e) => {\n *   const { source, field, newValue } = e.detail;\n *\n *   // Only cascade updates for user edits\n *   if (source === 'user' && field === 'price') {\n *     // Update calculated field (marked as 'cascade')\n *     grid.updateRow(e.detail.rowId, {\n *       total: newValue * e.detail.row.quantity,\n *     });\n *   }\n *\n *   // Ignore cascade updates to prevent infinite loops\n *   if (source === 'cascade') return;\n * });\n * ```\n *\n * @see {@link CellChangeDetail} for the event detail containing source\n * @category Data Management\n */\nexport type UpdateSource = 'user' | 'cascade' | 'api';\n\n/**\n * Detail for cell-change event (emitted by core after mutation).\n * This is an informational event that fires for ALL data mutations.\n *\n * Use this event for:\n * - Logging/auditing changes\n * - Cascading updates (updating other fields based on a change)\n * - Syncing changes to external state\n *\n * @example\n * ```typescript\n * grid.addEventListener('cell-change', (e: CustomEvent<CellChangeDetail>) => {\n *   const { row, rowId, field, oldValue, newValue, source } = e.detail;\n *\n *   console.log(`${field} changed from ${oldValue} to ${newValue}`);\n *   console.log(`Change source: ${source}`);\n *\n *   // Cascade: update total when price changes\n *   if (source === 'user' && field === 'price') {\n *     grid.updateRow(rowId, { total: newValue * row.quantity });\n *   }\n * });\n * ```\n *\n * @see {@link UpdateSource} for understanding change origins\n * @see {@link CellCommitDetail} for the commit event (editing lifecycle)\n * @category Events\n */\nexport interface CellChangeDetail<TRow = unknown> {\n  /** The row object (after mutation) */\n  row: TRow;\n  /** Stable row identifier */\n  rowId: string;\n  /** Current index in rows array */\n  rowIndex: number;\n  /** Field that changed */\n  field: string;\n  /** Value before change */\n  oldValue: unknown;\n  /** Value after change */\n  newValue: unknown;\n  /** All changes passed to updateRow/updateRows (for context) */\n  changes: Partial<TRow>;\n  /** Origin of this change */\n  source: UpdateSource;\n}\n\n/**\n * Batch update specification for updateRows().\n *\n * Used when you need to update multiple rows at once efficiently.\n * The grid will batch all updates and trigger a single re-render.\n *\n * @example\n * ```typescript\n * // Update multiple rows in a single batch\n * const updates: RowUpdate<Employee>[] = [\n *   { id: 'emp-1', changes: { status: 'active', updatedAt: new Date() } },\n *   { id: 'emp-2', changes: { status: 'inactive' } },\n *   { id: 'emp-3', changes: { salary: 75000 } },\n * ];\n *\n * grid.updateRows(updates);\n * ```\n *\n * @see {@link CellChangeDetail} for individual change events\n * @see {@link GridConfig.getRowId} for row identification\n * @category Data Management\n */\nexport interface RowUpdate<TRow = unknown> {\n  /** Row identifier (from getRowId) */\n  id: string;\n  /** Fields to update */\n  changes: Partial<TRow>;\n}\n\n// #endregion\n\n/**\n * Animation behavior mode.\n * - `true` or `'on'`: Animations always enabled\n * - `false` or `'off'`: Animations always disabled\n * - `'reduced-motion'`: Respects `prefers-reduced-motion` media query (default)\n *\n * @example\n * ```typescript\n * // Force animations on (ignore system preference)\n * grid.gridConfig = { animation: { mode: 'on' } };\n *\n * // Disable all animations\n * grid.gridConfig = { animation: { mode: false } };\n *\n * // Respect user's accessibility settings (default)\n * grid.gridConfig = { animation: { mode: 'reduced-motion' } };\n * ```\n *\n * @see {@link AnimationConfig} for full animation configuration\n */\nexport type AnimationMode = boolean | 'on' | 'off' | 'reduced-motion';\n\n/**\n * Animation style for visual transitions.\n * - `'slide'`: Slide/transform animation (e.g., expand down, slide left/right)\n * - `'fade'`: Opacity fade animation\n * - `'flip'`: FLIP technique for position changes (First, Last, Invert, Play)\n * - `false`: No animation for this specific feature\n *\n * @example\n * ```typescript\n * // Plugin-specific animation styles\n * new TreePlugin({\n *   expandAnimation: 'slide', // Slide children down when expanding\n * });\n *\n * new ReorderPlugin({\n *   animation: 'flip', // FLIP animation for column reordering\n * });\n * ```\n *\n * @see {@link AnimationConfig} for grid-wide animation settings\n * @see {@link ExpandCollapseAnimation} for expand/collapse-specific styles\n */\nexport type AnimationStyle = 'slide' | 'fade' | 'flip' | false;\n\n/**\n * Animation style for expand/collapse operations.\n * Subset of AnimationStyle - excludes 'flip' which is for position changes.\n * - `'slide'`: Slide down/up animation for expanding/collapsing content\n * - `'fade'`: Fade in/out animation\n * - `false`: No animation\n *\n * @example\n * ```typescript\n * // Tree rows slide down when expanding\n * new TreePlugin({ expandAnimation: 'slide' });\n *\n * // Row groups fade in/out\n * new GroupingRowsPlugin({ expandAnimation: 'fade' });\n *\n * // Master-detail panels with no animation\n * new MasterDetailPlugin({ expandAnimation: false });\n * ```\n *\n * @see {@link AnimationStyle} for all animation styles\n * @see {@link AnimationConfig} for grid-wide settings\n */\nexport type ExpandCollapseAnimation = 'slide' | 'fade' | false;\n\n/**\n * Type of row animation.\n * - `'change'`: Flash highlight when row data changes (e.g., after cell edit)\n * - `'insert'`: Slide-in animation for newly added rows\n * - `'remove'`: Fade-out animation for rows being removed\n *\n * @example\n * ```typescript\n * // Internal usage - row animation is triggered automatically:\n * // - 'change' after cell-commit event\n * // - 'insert' when rows are added to the grid\n * // - 'remove' when rows are deleted\n *\n * // The animation respects AnimationConfig.mode\n * grid.gridConfig = {\n *   animation: { mode: 'on', duration: 300 },\n * };\n * ```\n *\n * @see {@link AnimationConfig} for animation configuration\n */\nexport type RowAnimationType = 'change' | 'insert' | 'remove';\n\n/**\n * Grid-wide animation configuration.\n * Controls global animation behavior - individual plugins define their own animation styles.\n * Duration and easing values set corresponding CSS variables on the grid element.\n *\n * @example\n * ```typescript\n * // Enable animations regardless of system preferences\n * grid.gridConfig = {\n *   animation: {\n *     mode: 'on',\n *     duration: 300,\n *     easing: 'cubic-bezier(0.4, 0, 0.2, 1)',\n *   },\n * };\n *\n * // Disable all animations\n * grid.gridConfig = {\n *   animation: { mode: 'off' },\n * };\n *\n * // Respect user's reduced-motion preference (default)\n * grid.gridConfig = {\n *   animation: { mode: 'reduced-motion' },\n * };\n * ```\n *\n * @see {@link AnimationMode} for mode options\n */\nexport interface AnimationConfig {\n  /**\n   * Global animation mode.\n   * @default 'reduced-motion'\n   */\n  mode?: AnimationMode;\n\n  /**\n   * Default animation duration in milliseconds.\n   * Sets `--tbw-animation-duration` CSS variable.\n   * @default 200\n   */\n  duration?: number;\n\n  /**\n   * Default easing function.\n   * Sets `--tbw-animation-easing` CSS variable.\n   * @default 'ease-out'\n   */\n  easing?: string;\n}\n\n/** Default animation configuration */\nexport const DEFAULT_ANIMATION_CONFIG: Required<Omit<AnimationConfig, 'sort'>> = {\n  mode: 'reduced-motion',\n  duration: 200,\n  easing: 'ease-out',\n};\n\n// #endregion\n\n// #region Grid Icons\n\n/** Icon value - can be a string (text/HTML) or HTMLElement */\nexport type IconValue = string | HTMLElement;\n\n/**\n * Grid-wide icon configuration.\n * All icons are optional - sensible defaults are used when not specified.\n *\n * Icons can be text (including emoji), HTML strings (for SVG), or HTMLElement instances.\n *\n * @example\n * ```typescript\n * grid.gridConfig = {\n *   icons: {\n *     // Emoji icons\n *     expand: '➕',\n *     collapse: '➖',\n *\n *     // Custom SVG icon\n *     sortAsc: '<svg viewBox=\"0 0 16 16\"><path d=\"M8 4l4 8H4z\"/></svg>',\n *\n *     // Font icon class (wrap in span)\n *     filter: '<span class=\"icon icon-filter\"></span>',\n *   },\n * };\n * ```\n *\n * @see {@link IconValue} for allowed icon formats\n */\nexport interface GridIcons {\n  /** Expand icon for collapsed items (trees, groups, details). Default: '▶' */\n  expand?: IconValue;\n  /** Collapse icon for expanded items (trees, groups, details). Default: '▼' */\n  collapse?: IconValue;\n  /** Sort ascending indicator. Default: '▲' */\n  sortAsc?: IconValue;\n  /** Sort descending indicator. Default: '▼' */\n  sortDesc?: IconValue;\n  /** Sort neutral/unsorted indicator. Default: '⇅' */\n  sortNone?: IconValue;\n  /** Submenu arrow for context menus. Default: '▶' */\n  submenuArrow?: IconValue;\n  /** Drag handle icon for reordering. Default: '⋮⋮' */\n  dragHandle?: IconValue;\n  /** Tool panel toggle icon in toolbar. Default: '☰' */\n  toolPanel?: IconValue;\n  /** Filter icon in column headers. Default: SVG funnel icon */\n  filter?: IconValue;\n  /** Filter icon when filter is active. Default: same as filter with accent color */\n  filterActive?: IconValue;\n  /** Print icon for print button. Default: '🖨️' */\n  print?: IconValue;\n}\n\n/** Default filter icon SVG */\nconst DEFAULT_FILTER_ICON =\n  '<svg viewBox=\"0 0 16 16\" width=\"12\" height=\"12\"><path fill=\"currentColor\" d=\"M6 10.5a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5zm-2-3a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zm-2-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5z\"/></svg>';\n\n/** Default icons used when not overridden */\nexport const DEFAULT_GRID_ICONS: Required<GridIcons> = {\n  expand: '▶',\n  collapse: '▼',\n  sortAsc: '▲',\n  sortDesc: '▼',\n  sortNone: '⇅',\n  submenuArrow: '▶',\n  dragHandle: '⋮⋮',\n  toolPanel: '☰',\n  filter: DEFAULT_FILTER_ICON,\n  filterActive: DEFAULT_FILTER_ICON,\n  print: '🖨️',\n};\n// #endregion\n\n// #region Shell Configuration\n\n/**\n * Shell configuration for the grid's optional header bar and tool panels.\n *\n * The shell provides a wrapper around the grid with:\n * - Header bar with title, toolbar buttons, and custom content\n * - Collapsible side panel for filters, column visibility, settings, etc.\n *\n * @example\n * ```typescript\n * grid.gridConfig = {\n *   shell: {\n *     header: {\n *       title: 'Employee Directory',\n *     },\n *     toolPanel: {\n *       position: 'right',\n *       defaultOpen: 'columns', // Open by default\n *     },\n *   },\n *   plugins: [new VisibilityPlugin()], // Adds \"Columns\" panel\n * };\n *\n * // Register custom tool panels\n * grid.registerToolPanel({\n *   id: 'filters',\n *   title: 'Filters',\n *   icon: '🔍',\n *   render: (container) => {\n *     container.innerHTML = '<div>Filter controls...</div>';\n *   },\n * });\n * ```\n *\n * @see {@link ShellHeaderConfig} for header options\n * @see {@link ToolPanelConfig} for tool panel options\n */\nexport interface ShellConfig {\n  /** Shell header bar configuration */\n  header?: ShellHeaderConfig;\n  /** Tool panel configuration */\n  toolPanel?: ToolPanelConfig;\n  /**\n   * Registered tool panels (from plugins, API, or Light DOM).\n   * These are the actual panel definitions that can be opened.\n   * @internal Set by ConfigManager during merge\n   */\n  toolPanels?: ToolPanelDefinition[];\n  /**\n   * Registered header content sections (from plugins or API).\n   * Content rendered in the center of the shell header.\n   * @internal Set by ConfigManager during merge\n   */\n  headerContents?: HeaderContentDefinition[];\n}\n\n/**\n * Shell header bar configuration\n */\nexport interface ShellHeaderConfig {\n  /** Grid title displayed on the left (optional) */\n  title?: string;\n  /** Custom toolbar content (rendered before tool panel toggle) */\n  toolbarContents?: ToolbarContentDefinition[];\n  /**\n   * Light DOM header content elements (parsed from <tbw-grid-header> children).\n   * @internal Set by ConfigManager during merge\n   */\n  lightDomContent?: HTMLElement[];\n  /**\n   * Whether a tool buttons container was found in light DOM.\n   * @internal Set by ConfigManager during merge\n   */\n  hasToolButtonsContainer?: boolean;\n}\n\n/**\n * Tool panel configuration\n */\nexport interface ToolPanelConfig {\n  /** Panel position: 'left' | 'right' (default: 'right') */\n  position?: 'left' | 'right';\n  /** Default panel width in pixels (default: 280) */\n  width?: number;\n  /** Panel ID to open by default on load */\n  defaultOpen?: string;\n  /** Whether to persist open/closed state (requires Column State Events) */\n  persistState?: boolean;\n  /**\n   * Close the tool panel when clicking outside of it.\n   * When `true`, clicking anywhere outside the tool panel (but inside the grid)\n   * will close the panel automatically.\n   * @default false\n   */\n  closeOnClickOutside?: boolean;\n}\n\n/**\n * Toolbar content definition for the shell header toolbar area.\n * Register via `registerToolbarContent()` or use light DOM `<tbw-grid-tool-buttons>`.\n *\n * @example\n * ```typescript\n * grid.registerToolbarContent({\n *   id: 'my-toolbar',\n *   order: 10,\n *   render: (container) => {\n *     const btn = document.createElement('button');\n *     btn.textContent = 'Refresh';\n *     btn.onclick = () => console.log('clicked');\n *     container.appendChild(btn);\n *     return () => btn.remove();\n *   },\n * });\n * ```\n */\nexport interface ToolbarContentDefinition {\n  /** Unique content ID */\n  id: string;\n  /** Content factory - called once when shell header renders */\n  render: (container: HTMLElement) => void | (() => void);\n  /** Called when content is removed (for cleanup) */\n  onDestroy?: () => void;\n  /** Order priority (lower = first, default: 100) */\n  order?: number;\n}\n\n/**\n * Tool panel definition registered by plugins or consumers.\n *\n * Register via `grid.registerToolPanel()` to add panels to the sidebar.\n * Panels appear as collapsible sections with icons and titles.\n *\n * @example\n * ```typescript\n * grid.registerToolPanel({\n *   id: 'filters',\n *   title: 'Filters',\n *   icon: '🔍',\n *   tooltip: 'Filter grid data',\n *   order: 10, // Lower = appears first\n *   render: (container) => {\n *     container.innerHTML = `\n *       <div class=\"filter-panel\">\n *         <input type=\"text\" placeholder=\"Search...\" />\n *       </div>\n *     `;\n *     // Return cleanup function\n *     return () => container.innerHTML = '';\n *   },\n *   onClose: () => {\n *     console.log('Filter panel closed');\n *   },\n * });\n * ```\n *\n * @see {@link ShellConfig} for shell configuration\n */\nexport interface ToolPanelDefinition {\n  /** Unique panel ID */\n  id: string;\n  /** Panel title shown in accordion header */\n  title: string;\n  /** Icon for accordion section header (optional, emoji or SVG) */\n  icon?: string;\n  /** Tooltip for accordion section header */\n  tooltip?: string;\n  /** Panel content factory - called when panel section opens */\n  render: (container: HTMLElement) => void | (() => void);\n  /** Called when panel closes (for cleanup) */\n  onClose?: () => void;\n  /** Panel order priority (lower = first, default: 100) */\n  order?: number;\n}\n\n/**\n * Header content definition for plugins contributing to shell header center section.\n *\n * Register via `grid.registerHeaderContent()` to add content between\n * the title and toolbar buttons.\n *\n * @example\n * ```typescript\n * grid.registerHeaderContent({\n *   id: 'row-count',\n *   order: 10,\n *   render: (container) => {\n *     const span = document.createElement('span');\n *     span.className = 'row-count';\n *     span.textContent = `${grid.rows.length} rows`;\n *     container.appendChild(span);\n *\n *     // Update on data changes\n *     const update = () => span.textContent = `${grid.rows.length} rows`;\n *     grid.addEventListener('data-change', update);\n *\n *     return () => {\n *       grid.removeEventListener('data-change', update);\n *     };\n *   },\n * });\n * ```\n *\n * @see {@link ShellConfig} for shell configuration\n */\nexport interface HeaderContentDefinition {\n  /** Unique content ID */\n  id: string;\n  /** Content factory - called once when shell header renders */\n  render: (container: HTMLElement) => void | (() => void);\n  /** Called when content is removed (for cleanup) */\n  onDestroy?: () => void;\n  /** Order priority (lower = first, default: 100) */\n  order?: number;\n}\n// #endregion\n\n// #region Column State (Persistence)\n\n/**\n * State for a single column. Captures user-driven changes at runtime.\n * Plugins can extend this interface via module augmentation to add their own state.\n *\n * Used with `grid.getColumnState()` and `grid.columnState` for persisting\n * user customizations (column widths, order, visibility, sort).\n *\n * @example\n * ```typescript\n * // Save column state to localStorage\n * const state = grid.getColumnState();\n * localStorage.setItem('gridState', JSON.stringify(state));\n *\n * // Restore on page load\n * const saved = localStorage.getItem('gridState');\n * if (saved) {\n *   grid.columnState = JSON.parse(saved);\n * }\n *\n * // Example column state structure\n * const state: GridColumnState = {\n *   columns: [\n *     { field: 'name', order: 0, width: 200, hidden: false },\n *     { field: 'email', order: 1, width: 300, hidden: false },\n *     { field: 'phone', order: 2, hidden: true }, // Hidden column\n *   ],\n *   sort: { field: 'name', direction: 1 },\n * };\n * ```\n *\n * @example\n * ```typescript\n * // Plugin augmentation example (in filtering plugin)\n * declare module '@toolbox-web/grid' {\n *   interface ColumnState {\n *     filter?: FilterValue;\n *   }\n * }\n * ```\n *\n * @see {@link GridColumnState} for the full state object\n */\nexport interface ColumnState {\n  /** Column field identifier */\n  field: string;\n  /** Position index after reordering (0-based) */\n  order: number;\n  /** Width in pixels (undefined = use default) */\n  width?: number;\n  /** Visibility state */\n  visible: boolean;\n  /** Sort state (undefined = not sorted). */\n  sort?: ColumnSortState;\n}\n\n/**\n * Sort state for a column.\n * Used within {@link ColumnState} to track sort direction and priority.\n *\n * @see {@link ColumnState} for column state persistence\n * @see {@link SortChangeDetail} for sort change events\n */\nexport interface ColumnSortState {\n  /** Sort direction */\n  direction: 'asc' | 'desc';\n  /** Priority for multi-sort (0 = primary, 1 = secondary, etc.) */\n  priority: number;\n}\n\n/**\n * Complete grid column state for persistence.\n * Contains state for all columns, including plugin-contributed properties.\n *\n * @example\n * ```typescript\n * // Save state\n * const state = grid.getColumnState();\n * localStorage.setItem('grid-state', JSON.stringify(state));\n *\n * // Restore state\n * grid.columnState = JSON.parse(localStorage.getItem('grid-state'));\n * ```\n *\n * @see {@link ColumnState} for individual column state\n * @see {@link PublicGrid.getColumnState} for retrieving state\n */\nexport interface GridColumnState {\n  /** Array of column states. */\n  columns: ColumnState[];\n}\n// #endregion\n\n// #region Public Event Detail Interfaces\n/**\n * Detail for a cell click event.\n * Provides full context about the clicked cell including row data.\n *\n * @example\n * ```typescript\n * grid.addEventListener('cell-click', (e: CustomEvent<CellClickDetail>) => {\n *   const { row, field, value, rowIndex, colIndex } = e.detail;\n *   console.log(`Clicked ${field} = ${value} in row ${rowIndex}`);\\n *\n *   // Access the full row data\n *   if (row.status === 'pending') {\n *     showApprovalDialog(row);\n *   }\n * });\n * ```\n *\n * @category Events\n */\nexport interface CellClickDetail<TRow = unknown> {\n  /** Zero-based row index of the clicked cell. */\n  rowIndex: number;\n  /** Zero-based column index of the clicked cell. */\n  colIndex: number;\n  /** Column configuration object for the clicked cell. */\n  column: ColumnConfig<TRow>;\n  /** Field name of the clicked column. */\n  field: string;\n  /** Cell value at the clicked position. */\n  value: unknown;\n  /** Full row data object. */\n  row: TRow;\n  /** The clicked cell element. */\n  cellEl: HTMLElement;\n  /** The original mouse event. */\n  originalEvent: MouseEvent;\n}\n\n/**\n * Detail for a row click event.\n * Provides context about the clicked row.\n *\n * @example\n * ```typescript\n * grid.addEventListener('row-click', (e: CustomEvent<RowClickDetail>) => {\n *   const { row, rowIndex, rowEl } = e.detail;\n *   console.log(`Clicked row ${rowIndex}: ${row.name}`);\n *\n *   // Highlight the row\n *   rowEl.classList.add('selected');\n *\n *   // Open detail panel\n *   showDetailPanel(row);\n * });\n * ```\n *\n * @category Events\n */\nexport interface RowClickDetail<TRow = unknown> {\n  /** Zero-based row index of the clicked row. */\n  rowIndex: number;\n  /** Full row data object. */\n  row: TRow;\n  /** The clicked row element. */\n  rowEl: HTMLElement;\n  /** The original mouse event. */\n  originalEvent: MouseEvent;\n}\n\n/**\n * Detail for a sort change (direction 0 indicates cleared sort).\n *\n * @example\n * ```typescript\n * grid.addEventListener('sort-change', (e: CustomEvent<SortChangeDetail>) => {\n *   const { field, direction } = e.detail;\n *\n *   if (direction === 0) {\n *     console.log(`Sort cleared on ${field}`);\n *   } else {\n *     const dir = direction === 1 ? 'ascending' : 'descending';\n *     console.log(`Sorted by ${field} ${dir}`);\n *   }\n *\n *   // Fetch sorted data from server\n *   fetchData({ sortBy: field, sortDir: direction });\n * });\n * ```\n *\n * @see {@link SortState} for the sort state object\n * @see {@link SortHandler} for custom sort handlers\n * @category Events\n */\nexport interface SortChangeDetail {\n  /** Sorted field key. */\n  field: string;\n  /** Direction: 1 ascending, -1 descending, 0 cleared. */\n  direction: 1 | -1 | 0;\n}\n\n/**\n * Column resize event detail containing final pixel width.\n *\n * @example\n * ```typescript\n * grid.addEventListener('column-resize', (e: CustomEvent<ColumnResizeDetail>) => {\n *   const { field, width } = e.detail;\n *   console.log(`Column ${field} resized to ${width}px`);\n *\n *   // Persist to user preferences\n *   saveColumnWidth(field, width);\n * });\n * ```\n *\n * @see {@link ColumnState} for persisting column state\n * @see {@link ResizeController} for resize implementation\n * @category Events\n */\nexport interface ColumnResizeDetail {\n  /** Resized column field key. */\n  field: string;\n  /** New width in pixels. */\n  width: number;\n}\n\n/**\n * Trigger type for cell activation.\n * - `'keyboard'`: Enter key pressed on focused cell\n * - `'pointer'`: Mouse/touch/pen click on cell\n *\n * @see {@link CellActivateDetail} for the activation event detail\n * @category Events\n */\nexport type CellActivateTrigger = 'keyboard' | 'pointer';\n\n/**\n * Fired when a cell is activated by user interaction (Enter key or click).\n * Unified event for both keyboard and pointer activation.\n *\n * @example\n * ```typescript\n * grid.addEventListener('cell-activate', (e: CustomEvent<CellActivateDetail>) => {\n *   const { row, field, value, trigger, cellEl } = e.detail;\n *\n *   if (trigger === 'keyboard') {\n *     console.log('Activated via Enter key');\n *   } else {\n *     console.log('Activated via click/tap');\n *   }\n *\n *   // Start custom editing for specific columns\n *   if (field === 'notes') {\n *     openNotesEditor(row, cellEl);\n *     e.preventDefault(); // Prevent default editing\n *   }\n * });\n * ```\n *\n * @see {@link CellClickDetail} for click-only events\n * @see {@link CellActivateTrigger} for trigger types\n * @category Events\n */\nexport interface CellActivateDetail<TRow = unknown> {\n  /** Zero-based row index of the activated cell. */\n  rowIndex: number;\n  /** Zero-based column index of the activated cell. */\n  colIndex: number;\n  /** Field name of the activated column. */\n  field: string;\n  /** Cell value at the activated position. */\n  value: unknown;\n  /** Full row data object. */\n  row: TRow;\n  /** The activated cell element. */\n  cellEl: HTMLElement;\n  /** What triggered the activation. */\n  trigger: CellActivateTrigger;\n  /** The original event (KeyboardEvent for keyboard, MouseEvent/PointerEvent for pointer). */\n  originalEvent: KeyboardEvent | MouseEvent | PointerEvent;\n}\n\n/**\n * @deprecated Use `CellActivateDetail` instead. Will be removed in next major version.\n * Kept for backwards compatibility.\n *\n * @category Events\n */\nexport interface ActivateCellDetail {\n  /** Zero-based row index now focused. */\n  row: number;\n  /** Zero-based column index now focused. */\n  col: number;\n}\n\n/**\n * Event detail for mounting external view renderers.\n *\n * Emitted when a cell uses an external component spec (React, Angular, Vue)\n * and needs the framework adapter to mount the component.\n *\n * @example\n * ```typescript\n * // Framework adapter listens for this event\n * grid.addEventListener('mount-external-view', (e: CustomEvent<ExternalMountViewDetail>) => {\n *   const { placeholder, spec, context } = e.detail;\n *   // Mount framework component into placeholder\n *   mountComponent(spec.component, placeholder, context);\n * });\n * ```\n *\n * @see {@link ColumnConfig.externalView} for external view spec\n * @see {@link FrameworkAdapter} for adapter interface\n * @category Framework Adapters\n */\nexport interface ExternalMountViewDetail<TRow = unknown> {\n  placeholder: HTMLElement;\n  spec: unknown;\n  context: { row: TRow; value: unknown; field: string; column: unknown };\n}\n\n/**\n * Event detail for mounting external editor renderers.\n *\n * Emitted when a cell uses an external editor component spec and needs\n * the framework adapter to mount the editor with commit/cancel bindings.\n *\n * @example\n * ```typescript\n * // Framework adapter listens for this event\n * grid.addEventListener('mount-external-editor', (e: CustomEvent<ExternalMountEditorDetail>) => {\n *   const { placeholder, spec, context } = e.detail;\n *   // Mount framework editor with commit/cancel wired\n *   mountEditor(spec.component, placeholder, {\n *     value: context.value,\n *     onCommit: context.commit,\n *     onCancel: context.cancel,\n *   });\n * });\n * ```\n *\n * @see {@link ColumnEditorSpec} for external editor spec\n * @see {@link FrameworkAdapter} for adapter interface\n * @category Framework Adapters\n */\nexport interface ExternalMountEditorDetail<TRow = unknown> {\n  placeholder: HTMLElement;\n  spec: unknown;\n  context: {\n    row: TRow;\n    value: unknown;\n    field: string;\n    column: unknown;\n    commit: (v: unknown) => void;\n    cancel: () => void;\n  };\n}\n\n/**\n * Maps event names to their detail payload types.\n *\n * Use this interface for strongly typed event handling.\n *\n * @example\n * ```typescript\n * // Type-safe event listener\n * function handleEvent<K extends keyof DataGridEventMap>(\n *   grid: DataGridElement,\n *   event: K,\n *   handler: (detail: DataGridEventMap[K]) => void,\n * ): void {\n *   grid.addEventListener(event, (e: CustomEvent) => handler(e.detail));\n * }\n *\n * handleEvent(grid, 'cell-click', (detail) => {\n *   console.log(detail.field); // Type-safe access\n * });\n * ```\n *\n * @see {@link DataGridCustomEvent} for typed CustomEvent wrapper\n * @see {@link DGEvents} for event name constants\n * @category Events\n */\nexport interface DataGridEventMap<TRow = unknown> {\n  'cell-click': CellClickDetail<TRow>;\n  'row-click': RowClickDetail<TRow>;\n  'cell-activate': CellActivateDetail<TRow>;\n  'cell-change': CellChangeDetail<TRow>;\n  'mount-external-view': ExternalMountViewDetail<TRow>;\n  'mount-external-editor': ExternalMountEditorDetail<TRow>;\n  'sort-change': SortChangeDetail;\n  'column-resize': ColumnResizeDetail;\n  /** @deprecated Use 'cell-activate' instead */\n  'activate-cell': ActivateCellDetail;\n  'column-state-change': GridColumnState;\n  // Note: 'cell-commit', 'row-commit', 'changed-rows-reset' are added via\n  // module augmentation by EditingPlugin when imported\n}\n\n/**\n * Extracts the event detail type for a given event name.\n *\n * Utility type for getting the detail payload type of a specific event.\n *\n * @example\n * ```typescript\n * // Extract detail type for specific event\n * type ClickDetail = DataGridEventDetail<'cell-click', Employee>;\n * // Equivalent to: CellClickDetail<Employee>\n *\n * // Use in generic handler\n * function logDetail<K extends keyof DataGridEventMap>(\n *   eventName: K,\n *   detail: DataGridEventDetail<K>,\n * ): void {\n *   console.log(`${eventName}:`, detail);\n * }\n * ```\n *\n * @see {@link DataGridEventMap} for all event types\n * @category Events\n */\nexport type DataGridEventDetail<K extends keyof DataGridEventMap<unknown>, TRow = unknown> = DataGridEventMap<TRow>[K];\n\n/**\n * Custom event type for DataGrid events with typed detail payload.\n *\n * Use this type when you need to cast or declare event handler parameters.\n *\n * @example\n * ```typescript\n * // Strongly typed event handler\n * function onCellClick(e: DataGridCustomEvent<'cell-click', Employee>): void {\n *   const { row, field, value } = e.detail;\n *   console.log(`Clicked ${field} = ${value} on ${row.name}`);\n * }\n *\n * grid.addEventListener('cell-click', onCellClick);\n * ```\n *\n * @see {@link DataGridEventMap} for all event types\n * @see {@link DataGridEventDetail} for extracting detail type only\n * @category Events\n */\nexport type DataGridCustomEvent<K extends keyof DataGridEventMap<unknown>, TRow = unknown> = CustomEvent<\n  DataGridEventMap<TRow>[K]\n>;\n\n/**\n * Template evaluation context for dynamic templates.\n *\n * @category Plugin Development\n */\nexport interface EvalContext {\n  value: unknown;\n  row: Record<string, unknown> | null;\n}\n// #endregion\n","/**\n * Base Grid Plugin Class\n *\n * All plugins extend this abstract class.\n * Plugins are instantiated per-grid and manage their own state.\n */\n\n// Injected by Vite at build time from package.json (same as grid.ts)\ndeclare const __GRID_VERSION__: string;\n\nimport type {\n  ColumnConfig,\n  ColumnState,\n  GridPlugin,\n  HeaderContentDefinition,\n  IconValue,\n  PluginNameMap,\n  ToolPanelDefinition,\n} from '../types';\nimport { DEFAULT_GRID_ICONS } from '../types';\n\n// Re-export shared plugin types for convenience\nexport { PLUGIN_QUERIES } from './types';\nexport type {\n  AfterCellRenderContext,\n  AfterRowRenderContext,\n  CellClickEvent,\n  CellCoords,\n  CellEditor,\n  CellMouseEvent,\n  CellRenderer,\n  ContextMenuItem,\n  ContextMenuParams,\n  GridElementRef,\n  HeaderClickEvent,\n  HeaderRenderer,\n  KeyboardModifiers,\n  PluginCellRenderContext,\n  PluginQuery,\n  RowClickEvent,\n  ScrollEvent,\n} from './types';\n\nimport type {\n  AfterCellRenderContext,\n  AfterRowRenderContext,\n  CellClickEvent,\n  CellEditor,\n  CellMouseEvent,\n  CellRenderer,\n  GridElementRef,\n  HeaderClickEvent,\n  HeaderRenderer,\n  PluginQuery,\n  RowClickEvent,\n  ScrollEvent,\n} from './types';\n\n/**\n * Grid element interface for plugins.\n * Extends GridElementRef with plugin-specific methods.\n * Note: effectiveConfig is already available from GridElementRef.\n */\nexport interface GridElement extends GridElementRef {\n  getPlugin<T extends BaseGridPlugin>(PluginClass: new (...args: any[]) => T): T | undefined;\n  getPluginByName<K extends string>(\n    name: K,\n  ): (K extends keyof PluginNameMap ? PluginNameMap[K] : BaseGridPlugin) | undefined;\n  /**\n   * Get a plugin's state by plugin name.\n   * This is a loose-coupling method for plugins to access other plugins' state\n   * without importing the plugin class directly.\n   * @internal Plugin API\n   */\n  getPluginState?(name: string): unknown;\n\n  // Focus Management\n  /** Register an external DOM element as a logical focus container. @internal Plugin API */\n  registerExternalFocusContainer?(el: Element): void;\n  /** Unregister a previously registered external focus container. @internal Plugin API */\n  unregisterExternalFocusContainer?(el: Element): void;\n  /** Check whether focus is logically inside this grid (own DOM + external containers). @internal Plugin API */\n  containsFocus?(node?: Node | null): boolean;\n}\n\n/**\n * Header render context for plugin header renderers.\n */\nexport interface PluginHeaderRenderContext {\n  /** Column configuration */\n  column: ColumnConfig;\n  /** Column index */\n  colIndex: number;\n}\n\n// ============================================================================\n// Plugin Dependency Types\n// ============================================================================\n\n/**\n * Declares a dependency on another plugin.\n *\n * @category Plugin Development\n * @example\n * ```typescript\n * export class UndoRedoPlugin extends BaseGridPlugin {\n *   static readonly dependencies: PluginDependency[] = [\n *     { name: 'editing', required: true },\n *   ];\n * }\n * ```\n */\nexport interface PluginDependency {\n  /**\n   * The name of the required plugin (matches the plugin's `name` property).\n   * Use string names for loose coupling - avoids static imports.\n   */\n  name: string;\n\n  /**\n   * Whether this dependency is required (hard) or optional (soft).\n   * - `true`: Plugin cannot function without it. Throws error if missing.\n   * - `false`: Plugin works with reduced functionality. Logs info if missing.\n   * @default true\n   */\n  required?: boolean;\n\n  /**\n   * Human-readable reason for this dependency.\n   * Shown in error/info messages to help users understand why.\n   * @example \"UndoRedoPlugin needs EditingPlugin to track cell edits\"\n   */\n  reason?: string;\n}\n\n/**\n * Declares an incompatibility between plugins.\n * When both plugins are loaded, a warning is logged to help users understand the conflict.\n *\n * @category Plugin Development\n */\nexport interface PluginIncompatibility {\n  /**\n   * The name of the incompatible plugin (matches the plugin's `name` property).\n   */\n  name: string;\n\n  /**\n   * Human-readable reason for the incompatibility.\n   * Should explain why the plugins conflict and any workarounds.\n   * @example \"Responsive card layout does not support row grouping yet\"\n   */\n  reason: string;\n}\n\n// ============================================================================\n// Plugin Query & Event Definitions\n// ============================================================================\n\n/**\n * Defines a query that a plugin can handle.\n * Other plugins or the grid can send this query type to retrieve data.\n *\n * @category Plugin Development\n *\n * @example\n * ```typescript\n * // In manifest\n * queries: [\n *   {\n *     type: 'canMoveColumn',\n *     description: 'Check if a column can be moved/reordered',\n *   },\n * ]\n *\n * // In plugin class\n * handleQuery(query: PluginQuery): unknown {\n *   if (query.type === 'canMoveColumn') {\n *     return this.canMoveColumn(query.context);\n *   }\n * }\n * ```\n */\nexport interface QueryDefinition {\n  /**\n   * The query type identifier (e.g., 'canMoveColumn', 'getContextMenuItems').\n   * Should be unique across all plugins.\n   */\n  type: string;\n\n  /**\n   * Human-readable description of what the query does.\n   */\n  description?: string;\n}\n\n/**\n * Defines an event that a plugin can emit.\n * Other plugins can subscribe to these events via the Event Bus.\n *\n * @category Plugin Development\n *\n * @example\n * ```typescript\n * // In manifest\n * events: [\n *   {\n *     type: 'filter-change',\n *     description: 'Emitted when filter criteria change',\n *   },\n * ]\n *\n * // In plugin class - emit\n * this.emitPluginEvent('filter-change', { field: 'name', value: 'Alice' });\n *\n * // In another plugin - subscribe\n * this.on('filter-change', (detail) => console.log('Filter changed:', detail));\n * ```\n */\nexport interface EventDefinition {\n  /**\n   * The event type identifier (e.g., 'filter-change', 'selection-change').\n   * Used when emitting and subscribing to events.\n   */\n  type: string;\n\n  /**\n   * Human-readable description of what the event represents.\n   */\n  description?: string;\n\n  /**\n   * Whether this event is cancelable via `event.preventDefault()`.\n   * @default false\n   */\n  cancelable?: boolean;\n}\n\n// ============================================================================\n// Plugin Manifest Types\n// ============================================================================\n\n/**\n * Defines a property that a plugin \"owns\" - used for configuration validation.\n * When this property is used without the owning plugin loaded, an error is thrown.\n *\n * @category Plugin Development\n */\nexport interface PluginPropertyDefinition {\n  /** The property name on column or grid config */\n  property: string;\n  /** Whether this is a column-level or config-level property */\n  level: 'column' | 'config';\n  /** Human-readable description for error messages (e.g., 'the \"editable\" column property') */\n  description: string;\n  /** Import path hint for error messages (e.g., \"import { EditingPlugin } from '@toolbox-web/grid/plugins/editing';\") */\n  importHint?: string;\n  /** Custom check for whether property is considered \"used\" (default: truthy value check) */\n  isUsed?: (value: unknown) => boolean;\n}\n\n/**\n * A configuration validation rule for detecting invalid/conflicting settings.\n * Plugins declare rules in their manifest; the validator executes them during grid initialization.\n *\n * @category Plugin Development\n * @template TConfig - The plugin's configuration type\n */\nexport interface PluginConfigRule<TConfig = unknown> {\n  /** Rule identifier for debugging (e.g., 'selection/range-dblclick') */\n  id: string;\n  /** Severity: 'error' throws, 'warn' logs warning */\n  severity: 'error' | 'warn';\n  /** Human-readable message shown when rule is violated */\n  message: string;\n  /** Predicate returning true if the rule is VIOLATED (i.e., config is invalid) */\n  check: (pluginConfig: TConfig) => boolean;\n}\n\n/**\n * Hook names that can have execution priority configured.\n *\n * @category Plugin Development\n */\nexport type HookName =\n  | 'processColumns'\n  | 'processRows'\n  | 'afterRender'\n  | 'afterCellRender'\n  | 'afterRowRender'\n  | 'onCellClick'\n  | 'onCellMouseDown'\n  | 'onCellMouseMove'\n  | 'onCellMouseUp'\n  | 'onKeyDown'\n  | 'onScroll'\n  | 'onScrollRender';\n\n/**\n * Static metadata about a plugin's capabilities and requirements.\n * Declared as a static property on plugin classes.\n *\n * @category Plugin Development\n * @template TConfig - The plugin's configuration type\n *\n * @example\n * ```typescript\n * export class MyPlugin extends BaseGridPlugin<MyConfig> {\n *   static override readonly manifest: PluginManifest<MyConfig> = {\n *     ownedProperties: [\n *       { property: 'myProp', level: 'column', description: 'the \"myProp\" column property' },\n *     ],\n *     configRules: [\n *       { id: 'my-plugin/invalid-combo', severity: 'warn', message: '...', check: (c) => c.a && c.b },\n *     ],\n *   };\n *   readonly name = 'myPlugin';\n * }\n * ```\n */\nexport interface PluginManifest<TConfig = unknown> {\n  /**\n   * Properties this plugin owns - validated by validate-config.ts.\n   * If a user uses one of these properties without loading the plugin, an error is thrown.\n   */\n  ownedProperties?: PluginPropertyDefinition[];\n\n  /**\n   * Hook execution priority (higher = later, default 0).\n   * Use negative values to run earlier, positive to run later.\n   */\n  hookPriority?: Partial<Record<HookName, number>>;\n\n  /**\n   * Configuration validation rules - checked during grid initialization.\n   * Rules with severity 'error' throw, 'warn' logs to console.\n   */\n  configRules?: PluginConfigRule<TConfig>[];\n\n  /**\n   * Plugins that are incompatible with this plugin.\n   * When both plugins are loaded together, a warning is shown.\n   *\n   * @example\n   * ```typescript\n   * incompatibleWith: [\n   *   { name: 'groupingRows', reason: 'Responsive card layout does not support row grouping yet' },\n   * ],\n   * ```\n   */\n  incompatibleWith?: PluginIncompatibility[];\n\n  /**\n   * Queries this plugin can handle.\n   * Declares what query types this plugin responds to via `handleQuery()`.\n   * This replaces the centralized PLUGIN_QUERIES approach with manifest-declared queries.\n   *\n   * @example\n   * ```typescript\n   * queries: [\n   *   { type: 'canMoveColumn', description: 'Check if a column can be moved' },\n   * ],\n   * ```\n   */\n  queries?: QueryDefinition[];\n\n  /**\n   * Events this plugin can emit.\n   * Declares what event types other plugins can subscribe to via `on()`.\n   *\n   * @example\n   * ```typescript\n   * events: [\n   *   { type: 'filter-change', description: 'Emitted when filter criteria change' },\n   * ],\n   * ```\n   */\n  events?: EventDefinition[];\n}\n\n/**\n * Abstract base class for all grid plugins.\n *\n * @category Plugin Development\n * @template TConfig - Configuration type for the plugin\n */\nexport abstract class BaseGridPlugin<TConfig = unknown> implements GridPlugin {\n  /**\n   * Plugin dependencies - declare other plugins this one requires.\n   *\n   * Dependencies are validated when the plugin is attached.\n   * Required dependencies throw an error if missing.\n   * Optional dependencies log an info message if missing.\n   *\n   * @example\n   * ```typescript\n   * static readonly dependencies: PluginDependency[] = [\n   *   { name: 'editing', required: true, reason: 'Tracks cell edits for undo/redo' },\n   *   { name: 'selection', required: false, reason: 'Enables selection-based undo' },\n   * ];\n   * ```\n   */\n  static readonly dependencies?: PluginDependency[];\n\n  /**\n   * Plugin manifest - declares owned properties, config rules, and hook priorities.\n   *\n   * This is read by the configuration validator to:\n   * - Validate that required plugins are loaded when their properties are used\n   * - Execute configRules to detect invalid/conflicting settings\n   * - Order hook execution based on priority\n   *\n   * @example\n   * ```typescript\n   * static override readonly manifest: PluginManifest<MyConfig> = {\n   *   ownedProperties: [\n   *     { property: 'myProp', level: 'column', description: 'the \"myProp\" column property' },\n   *   ],\n   *   configRules: [\n   *     { id: 'myPlugin/conflict', severity: 'warn', message: '...', check: (c) => c.a && c.b },\n   *   ],\n   * };\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  static readonly manifest?: PluginManifest<any>;\n\n  /** Unique plugin identifier (derived from class name by default) */\n  abstract readonly name: string;\n\n  /**\n   * Plugin version - defaults to grid version for built-in plugins.\n   * Third-party plugins can override with their own semver.\n   */\n  readonly version: string = typeof __GRID_VERSION__ !== 'undefined' ? __GRID_VERSION__ : 'dev';\n\n  /** CSS styles to inject into the grid's shadow DOM */\n  readonly styles?: string;\n\n  /** Custom cell renderers keyed by type name */\n  readonly cellRenderers?: Record<string, CellRenderer>;\n\n  /** Custom header renderers keyed by type name */\n  readonly headerRenderers?: Record<string, HeaderRenderer>;\n\n  /** Custom cell editors keyed by type name */\n  readonly cellEditors?: Record<string, CellEditor>;\n\n  /** The grid instance this plugin is attached to */\n  protected grid!: GridElement;\n\n  /** Plugin configuration - merged with defaults in attach() */\n  protected config!: TConfig;\n\n  /** User-provided configuration from constructor */\n  protected readonly userConfig: Partial<TConfig>;\n\n  /**\n   * Plugin-level AbortController for event listener cleanup.\n   * Created fresh in attach(), aborted in detach().\n   * This ensures event listeners are properly cleaned up when plugins are re-attached.\n   */\n  #abortController?: AbortController;\n\n  /**\n   * Default configuration - subclasses should override this getter.\n   * Note: This must be a getter (not property initializer) for proper inheritance\n   * since property initializers run after parent constructor.\n   */\n  protected get defaultConfig(): Partial<TConfig> {\n    return {};\n  }\n\n  constructor(config: Partial<TConfig> = {}) {\n    this.userConfig = config;\n  }\n\n  /**\n   * Called when the plugin is attached to a grid.\n   * Override to set up event listeners, initialize state, etc.\n   *\n   * @example\n   * ```ts\n   * attach(grid: GridElement): void {\n   *   super.attach(grid);\n   *   // Set up document-level listeners with auto-cleanup\n   *   document.addEventListener('keydown', this.handleEscape, {\n   *     signal: this.disconnectSignal\n   *   });\n   * }\n   * ```\n   */\n  attach(grid: GridElement): void {\n    // Abort any previous abort controller (in case of re-attach without detach)\n    this.#abortController?.abort();\n    // Create fresh abort controller for this attachment\n    this.#abortController = new AbortController();\n\n    this.grid = grid;\n    // Merge config here (after subclass construction is complete)\n    this.config = { ...this.defaultConfig, ...this.userConfig } as TConfig;\n  }\n\n  /**\n   * Called when the plugin is detached from a grid.\n   * Override to clean up event listeners, timers, etc.\n   *\n   * @example\n   * ```ts\n   * detach(): void {\n   *   // Clean up any state not handled by disconnectSignal\n   *   this.selectedRows.clear();\n   *   this.cache = null;\n   * }\n   * ```\n   */\n  detach(): void {\n    // Abort the plugin's abort controller to clean up all event listeners\n    // registered with { signal: this.disconnectSignal }\n    this.#abortController?.abort();\n    this.#abortController = undefined;\n    // Override in subclass for additional cleanup\n  }\n\n  /**\n   * Called when another plugin is attached to the same grid.\n   * Use for inter-plugin coordination, e.g., to integrate with new plugins.\n   *\n   * @param name - The name of the plugin that was attached\n   * @param plugin - The plugin instance (for direct access if needed)\n   *\n   * @example\n   * ```ts\n   * onPluginAttached(name: string, plugin: BaseGridPlugin): void {\n   *   if (name === 'selection') {\n   *     // Integrate with selection plugin\n   *     this.selectionPlugin = plugin as SelectionPlugin;\n   *   }\n   * }\n   * ```\n   */\n  onPluginAttached?(name: string, plugin: BaseGridPlugin): void;\n\n  /**\n   * Called when another plugin is detached from the same grid.\n   * Use to clean up inter-plugin references.\n   *\n   * @param name - The name of the plugin that was detached\n   *\n   * @example\n   * ```ts\n   * onPluginDetached(name: string): void {\n   *   if (name === 'selection') {\n   *     this.selectionPlugin = undefined;\n   *   }\n   * }\n   * ```\n   */\n  onPluginDetached?(name: string): void;\n\n  /**\n   * Get another plugin instance from the same grid.\n   * Use for inter-plugin communication.\n   *\n   * @example\n   * ```ts\n   * const selection = this.getPlugin(SelectionPlugin);\n   * if (selection) {\n   *   const selectedRows = selection.getSelectedRows();\n   * }\n   * ```\n   */\n  protected getPlugin<T extends BaseGridPlugin>(PluginClass: new (...args: any[]) => T): T | undefined {\n    return this.grid?.getPlugin(PluginClass);\n  }\n\n  /**\n   * Emit a custom event from the grid.\n   */\n  protected emit<T>(eventName: string, detail: T): void {\n    this.grid?.dispatchEvent?.(new CustomEvent(eventName, { detail, bubbles: true }));\n  }\n\n  /**\n   * Emit a cancelable custom event from the grid.\n   * @returns `true` if the event was cancelled (preventDefault called), `false` otherwise\n   */\n  protected emitCancelable<T>(eventName: string, detail: T): boolean {\n    const event = new CustomEvent(eventName, { detail, bubbles: true, cancelable: true });\n    this.grid?.dispatchEvent?.(event);\n    return event.defaultPrevented;\n  }\n\n  // =========================================================================\n  // Event Bus - Plugin-to-Plugin Communication\n  // =========================================================================\n\n  /**\n   * Subscribe to an event from another plugin.\n   * The subscription is automatically cleaned up when this plugin is detached.\n   *\n   * @category Plugin Development\n   * @param eventType - The event type to listen for (e.g., 'filter-change')\n   * @param callback - The callback to invoke when the event is emitted\n   *\n   * @example\n   * ```typescript\n   * // In attach() or other initialization\n   * this.on('filter-change', (detail) => {\n   *   console.log('Filter changed:', detail);\n   * });\n   * ```\n   */\n  protected on<T = unknown>(eventType: string, callback: (detail: T) => void): void {\n    this.grid?._pluginManager?.subscribe(this, eventType, callback as (detail: unknown) => void);\n  }\n\n  /**\n   * Unsubscribe from a plugin event.\n   *\n   * @category Plugin Development\n   * @param eventType - The event type to stop listening for\n   *\n   * @example\n   * ```typescript\n   * this.off('filter-change');\n   * ```\n   */\n  protected off(eventType: string): void {\n    this.grid?._pluginManager?.unsubscribe(this, eventType);\n  }\n\n  /**\n   * Emit an event to other plugins via the Event Bus.\n   * This is for inter-plugin communication only; it does NOT dispatch DOM events.\n   * Use `emit()` to dispatch DOM events that external consumers can listen to.\n   *\n   * @category Plugin Development\n   * @param eventType - The event type to emit (should be declared in manifest.events)\n   * @param detail - The event payload\n   *\n   * @example\n   * ```typescript\n   * // Emit to other plugins (not DOM)\n   * this.emitPluginEvent('filter-change', { field: 'name', value: 'Alice' });\n   *\n   * // For DOM events that consumers can addEventListener to:\n   * this.emit('filter-change', { field: 'name', value: 'Alice' });\n   * ```\n   */\n  protected emitPluginEvent<T>(eventType: string, detail: T): void {\n    this.grid?._pluginManager?.emitPluginEvent(eventType, detail);\n  }\n\n  /**\n   * Request a re-render of the grid.\n   * Uses ROWS phase - does NOT trigger processColumns hooks.\n   */\n  protected requestRender(): void {\n    this.grid?.requestRender?.();\n  }\n\n  /**\n   * Request a columns re-render of the grid.\n   * Uses COLUMNS phase - triggers processColumns hooks.\n   * Use this when your plugin needs to reprocess column configuration.\n   */\n  protected requestColumnsRender(): void {\n    (this.grid as { requestColumnsRender?: () => void })?.requestColumnsRender?.();\n  }\n\n  /**\n   * Request a re-render and restore focus styling afterward.\n   * Use this when a plugin action (like expand/collapse) triggers a render\n   * but needs to maintain keyboard navigation focus.\n   */\n  protected requestRenderWithFocus(): void {\n    this.grid?.requestRenderWithFocus?.();\n  }\n\n  /**\n   * Request a lightweight style update without rebuilding DOM.\n   * Use this instead of requestRender() when only CSS classes need updating.\n   */\n  protected requestAfterRender(): void {\n    this.grid?.requestAfterRender?.();\n  }\n\n  /**\n   * Get the current rows from the grid.\n   */\n  protected get rows(): any[] {\n    return this.grid?.rows ?? [];\n  }\n\n  /**\n   * Get the original unfiltered/unprocessed rows from the grid.\n   * Use this when you need all source data regardless of active filters.\n   */\n  protected get sourceRows(): any[] {\n    return this.grid?.sourceRows ?? [];\n  }\n\n  /**\n   * Get the current columns from the grid.\n   */\n  protected get columns(): ColumnConfig[] {\n    return this.grid?.columns ?? [];\n  }\n\n  /**\n   * Get only visible columns from the grid (excludes hidden).\n   * Use this for rendering that needs to match the grid template.\n   */\n  protected get visibleColumns(): ColumnConfig[] {\n    return this.grid?._visibleColumns ?? [];\n  }\n\n  /**\n   * Get the grid as an HTMLElement for direct DOM operations.\n   * Use sparingly - prefer the typed GridElementRef API when possible.\n   *\n   * @example\n   * ```ts\n   * const width = this.gridElement.clientWidth;\n   * this.gridElement.classList.add('my-plugin-active');\n   * ```\n   */\n  protected get gridElement(): HTMLElement {\n    return this.grid as unknown as HTMLElement;\n  }\n\n  /**\n   * Get the disconnect signal for event listener cleanup.\n   * This signal is aborted when the grid disconnects from the DOM.\n   * Use this when adding event listeners that should be cleaned up automatically.\n   *\n   * Best for:\n   * - Document/window-level listeners added in attach()\n   * - Listeners on the grid element itself\n   * - Any listener that should persist across renders\n   *\n   * Not needed for:\n   * - Listeners on elements created in afterRender() (removed with element)\n   *\n   * @example\n   * element.addEventListener('click', handler, { signal: this.disconnectSignal });\n   * document.addEventListener('keydown', handler, { signal: this.disconnectSignal });\n   */\n  protected get disconnectSignal(): AbortSignal {\n    // Return the plugin's own abort signal for proper cleanup on detach/re-attach\n    // Falls back to grid's signal if plugin's controller not yet created\n    return this.#abortController?.signal ?? this.grid?.disconnectSignal;\n  }\n\n  /**\n   * Get the grid-level icons configuration.\n   * Returns merged icons (user config + defaults).\n   */\n  protected get gridIcons(): typeof DEFAULT_GRID_ICONS {\n    const userIcons = this.grid?.gridConfig?.icons ?? {};\n    return { ...DEFAULT_GRID_ICONS, ...userIcons };\n  }\n\n  // #region Animation Helpers\n\n  /**\n   * Check if animations are enabled at the grid level.\n   * Respects gridConfig.animation.mode and the CSS variable set by the grid.\n   *\n   * Plugins should use this to skip animations when:\n   * - Animation mode is 'off' or `false`\n   * - User prefers reduced motion and mode is 'reduced-motion' (default)\n   *\n   * @example\n   * ```ts\n   * private get animationStyle(): 'slide' | 'fade' | false {\n   *   if (!this.isAnimationEnabled) return false;\n   *   return this.config.animation ?? 'slide';\n   * }\n   * ```\n   */\n  protected get isAnimationEnabled(): boolean {\n    const mode = this.grid?.effectiveConfig?.animation?.mode ?? 'reduced-motion';\n\n    // Explicit off = disabled\n    if (mode === false || mode === 'off') return false;\n\n    // Explicit on = always enabled\n    if (mode === true || mode === 'on') return true;\n\n    // reduced-motion: check CSS variable (set by grid based on media query)\n    const host = this.gridElement;\n    if (host) {\n      const enabled = getComputedStyle(host).getPropertyValue('--tbw-animation-enabled').trim();\n      return enabled !== '0';\n    }\n\n    return true; // Default to enabled\n  }\n\n  /**\n   * Get the animation duration in milliseconds from CSS variable.\n   * Falls back to 200ms if not set.\n   *\n   * Plugins can use this for their animation timing to stay consistent\n   * with the grid-level animation.duration setting.\n   *\n   * @example\n   * ```ts\n   * element.animate(keyframes, { duration: this.animationDuration });\n   * ```\n   */\n  protected get animationDuration(): number {\n    const host = this.gridElement;\n    if (host) {\n      const durationStr = getComputedStyle(host).getPropertyValue('--tbw-animation-duration').trim();\n      const parsed = parseInt(durationStr, 10);\n      if (!isNaN(parsed)) return parsed;\n    }\n    return 200; // Default\n  }\n\n  // #endregion\n\n  /**\n   * Resolve an icon value to string or HTMLElement.\n   * Checks plugin config first, then grid-level icons, then defaults.\n   *\n   * @param iconKey - The icon key in GridIcons (e.g., 'expand', 'collapse')\n   * @param pluginOverride - Optional plugin-level override\n   * @returns The resolved icon value\n   */\n  protected resolveIcon(iconKey: keyof typeof DEFAULT_GRID_ICONS, pluginOverride?: IconValue): IconValue {\n    // Plugin override takes precedence\n    if (pluginOverride !== undefined) {\n      return pluginOverride;\n    }\n    // Then grid-level config\n    return this.gridIcons[iconKey];\n  }\n\n  /**\n   * Set an icon value on an element.\n   * Handles both string (text/HTML) and HTMLElement values.\n   *\n   * @param element - The element to set the icon on\n   * @param icon - The icon value (string or HTMLElement)\n   */\n  protected setIcon(element: HTMLElement, icon: IconValue): void {\n    if (typeof icon === 'string') {\n      element.innerHTML = icon;\n    } else if (icon instanceof HTMLElement) {\n      element.innerHTML = '';\n      element.appendChild(icon.cloneNode(true));\n    }\n  }\n\n  /**\n   * Log a warning message.\n   */\n  protected warn(message: string): void {\n    console.warn(`[tbw-grid:${this.name}] ${message}`);\n  }\n\n  // #region Lifecycle Hooks\n\n  /**\n   * Transform rows before rendering.\n   * Called during each render cycle before rows are rendered to the DOM.\n   * Use this to filter, sort, or add computed properties to rows.\n   *\n   * @param rows - The current rows array (readonly to encourage returning a new array)\n   * @returns The modified rows array to render\n   *\n   * @example\n   * ```ts\n   * processRows(rows: readonly any[]): any[] {\n   *   // Filter out hidden rows\n   *   return rows.filter(row => !row._hidden);\n   * }\n   * ```\n   *\n   * @example\n   * ```ts\n   * processRows(rows: readonly any[]): any[] {\n   *   // Add computed properties\n   *   return rows.map(row => ({\n   *     ...row,\n   *     _fullName: `${row.firstName} ${row.lastName}`\n   *   }));\n   * }\n   * ```\n   */\n  processRows?(rows: readonly any[]): any[];\n\n  /**\n   * Transform columns before rendering.\n   * Called during each render cycle before column headers and cells are rendered.\n   * Use this to add, remove, or modify column definitions.\n   *\n   * @param columns - The current columns array (readonly to encourage returning a new array)\n   * @returns The modified columns array to render\n   *\n   * @example\n   * ```ts\n   * processColumns(columns: readonly ColumnConfig[]): ColumnConfig[] {\n   *   // Add a selection checkbox column\n   *   return [\n   *     { field: '_select', header: '', width: 40 },\n   *     ...columns\n   *   ];\n   * }\n   * ```\n   */\n  processColumns?(columns: readonly ColumnConfig[]): ColumnConfig[];\n\n  /**\n   * Called before each render cycle begins.\n   * Use this to prepare state or cache values needed during rendering.\n   *\n   * **Note:** This hook is currently a placeholder for future implementation.\n   * It is defined in the interface but not yet invoked by the grid's render pipeline.\n   * If you need this functionality, please open an issue or contribute an implementation.\n   *\n   * @example\n   * ```ts\n   * beforeRender(): void {\n   *   this.visibleRowCount = this.calculateVisibleRows();\n   * }\n   * ```\n   */\n  beforeRender?(): void;\n\n  /**\n   * Called after each render cycle completes.\n   * Use this for DOM manipulation, adding event listeners to rendered elements,\n   * or applying visual effects like selection highlights.\n   *\n   * @example\n   * ```ts\n   * afterRender(): void {\n   *   // Apply selection styling to rendered rows\n   *   const rows = this.gridElement?.querySelectorAll('.data-row');\n   *   rows?.forEach((row, i) => {\n   *     row.classList.toggle('selected', this.selectedRows.has(i));\n   *   });\n   * }\n   * ```\n   */\n  afterRender?(): void;\n\n  /**\n   * Called after each cell is rendered.\n   * This hook is more efficient than `afterRender()` for cell-level modifications\n   * because you receive the cell context directly - no DOM queries needed.\n   *\n   * Use cases:\n   * - Adding selection/highlight classes to specific cells\n   * - Injecting badges or decorations\n   * - Applying conditional styling based on cell value\n   *\n   * Performance note: Called for every visible cell during render. Keep implementation fast.\n   * This hook is also called during scroll when cells are recycled.\n   *\n   * @param context - The cell render context with row, column, value, and elements\n   *\n   * @example\n   * ```ts\n   * afterCellRender(context: AfterCellRenderContext): void {\n   *   // Add selection class without DOM queries\n   *   if (this.isSelected(context.rowIndex, context.colIndex)) {\n   *     context.cellElement.classList.add('selected');\n   *   }\n   *\n   *   // Add validation error styling\n   *   if (this.hasError(context.row, context.column.field)) {\n   *     context.cellElement.classList.add('has-error');\n   *   }\n   * }\n   * ```\n   */\n  afterCellRender?(context: AfterCellRenderContext): void;\n\n  /**\n   * Called after a row is fully rendered (all cells complete).\n   * Use this for row-level decorations, styling, or ARIA attributes.\n   *\n   * Common use cases:\n   * - Adding selection classes to entire rows (row-focus, selected)\n   * - Setting row-level ARIA attributes\n   * - Applying row validation highlighting\n   * - Tree indentation styling\n   *\n   * Performance note: Called for every visible row during render. Keep implementation fast.\n   * This hook is also called during scroll when rows are recycled.\n   *\n   * @param context - The row render context with row data and element\n   *\n   * @example\n   * ```ts\n   * afterRowRender(context: AfterRowRenderContext): void {\n   *   // Add row selection class without DOM queries\n   *   if (this.isRowSelected(context.rowIndex)) {\n   *     context.rowElement.classList.add('selected', 'row-focus');\n   *   }\n   *\n   *   // Add validation error styling\n   *   if (this.rowHasErrors(context.row)) {\n   *     context.rowElement.classList.add('has-errors');\n   *   }\n   * }\n   * ```\n   */\n  afterRowRender?(context: AfterRowRenderContext): void;\n\n  /**\n   * Called after scroll-triggered row rendering completes.\n   * This is a lightweight hook for applying visual state to recycled DOM elements.\n   * Use this instead of afterRender when you need to reapply styling during scroll.\n   *\n   * Performance note: This is called frequently during scroll. Keep implementation fast.\n   *\n   * @example\n   * ```ts\n   * onScrollRender(): void {\n   *   // Reapply selection state to visible cells\n   *   this.applySelectionToVisibleCells();\n   * }\n   * ```\n   */\n  onScrollRender?(): void;\n\n  /**\n   * Return extra height contributed by this plugin (e.g., expanded detail rows).\n   * Used to adjust scrollbar height calculations for virtualization.\n   *\n   * @returns Total extra height in pixels\n   *\n   * @deprecated Use {@link getRowHeight} instead. This hook will be removed in v3.0.\n   * The new `getRowHeight(row, index)` hook provides per-row height information which\n   * enables better position caching and variable row height support.\n   *\n   * @example\n   * ```ts\n   * // OLD (deprecated):\n   * getExtraHeight(): number {\n   *   return this.expandedRows.size * this.detailHeight;\n   * }\n   *\n   * // NEW (preferred):\n   * getRowHeight(row: unknown, index: number): number | undefined {\n   *   if (this.isExpanded(row)) {\n   *     return this.baseRowHeight + this.getDetailHeight(row);\n   *   }\n   *   return undefined;\n   * }\n   * ```\n   */\n  getExtraHeight?(): number;\n\n  /**\n   * Return extra height that appears before a given row index.\n   * Used by virtualization to correctly calculate scroll positions when\n   * there's variable height content (like expanded detail rows) above the viewport.\n   *\n   * @param beforeRowIndex - The row index to calculate extra height before\n   * @returns Extra height in pixels that appears before this row\n   *\n   * @deprecated Use {@link getRowHeight} instead. This hook will be removed in v3.0.\n   * The new `getRowHeight(row, index)` hook provides per-row height information which\n   * enables better position caching and variable row height support.\n   *\n   * @example\n   * ```ts\n   * // OLD (deprecated):\n   * getExtraHeightBefore(beforeRowIndex: number): number {\n   *   let height = 0;\n   *   for (const expandedRowIndex of this.expandedRowIndices) {\n   *     if (expandedRowIndex < beforeRowIndex) {\n   *       height += this.getDetailHeight(expandedRowIndex);\n   *     }\n   *   }\n   *   return height;\n   * }\n   *\n   * // NEW (preferred):\n   * getRowHeight(row: unknown, index: number): number | undefined {\n   *   if (this.isExpanded(row)) {\n   *     return this.baseRowHeight + this.getDetailHeight(row);\n   *   }\n   *   return undefined;\n   * }\n   * ```\n   */\n  getExtraHeightBefore?(beforeRowIndex: number): number;\n\n  /**\n   * Get the height of a specific row.\n   * Used for synthetic rows (group headers, detail panels, etc.) that have fixed heights.\n   * Return undefined if this plugin does not manage the height for this row.\n   *\n   * This hook is called during position cache rebuilds for variable row height virtualization.\n   * Plugins that create synthetic rows should implement this to provide accurate heights.\n   *\n   * @param row - The row data\n   * @param index - The row index in the processed rows array\n   * @returns The row height in pixels, or undefined if not managed by this plugin\n   *\n   * @example\n   * ```ts\n   * getRowHeight(row: unknown, index: number): number | undefined {\n   *   // Group headers have a fixed height\n   *   if (this.isGroupHeader(row)) {\n   *     return 32;\n   *   }\n   *   return undefined; // Let grid use default/measured height\n   * }\n   * ```\n   */\n  getRowHeight?(row: unknown, index: number): number | undefined;\n\n  /**\n   * Adjust the virtualization start index to render additional rows before the visible range.\n   * Use this when expanded content (like detail rows) needs its parent row to remain rendered\n   * even when the parent row itself has scrolled above the viewport.\n   *\n   * @param start - The calculated start row index\n   * @param scrollTop - The current scroll position\n   * @param rowHeight - The height of a single row\n   * @returns The adjusted start index (lower than or equal to original start)\n   *\n   * @example\n   * ```ts\n   * adjustVirtualStart(start: number, scrollTop: number, rowHeight: number): number {\n   *   // If row 5 is expanded and scrolled partially, keep it rendered\n   *   for (const expandedRowIndex of this.expandedRowIndices) {\n   *     const expandedRowTop = expandedRowIndex * rowHeight;\n   *     const expandedRowBottom = expandedRowTop + rowHeight + this.detailHeight;\n   *     if (expandedRowBottom > scrollTop && expandedRowIndex < start) {\n   *       return expandedRowIndex;\n   *     }\n   *   }\n   *   return start;\n   * }\n   * ```\n   */\n  adjustVirtualStart?(start: number, scrollTop: number, rowHeight: number): number;\n\n  /**\n   * Render a custom row, bypassing the default row rendering.\n   * Use this for special row types like group headers, detail rows, or footers.\n   *\n   * @param row - The row data object\n   * @param rowEl - The row DOM element to render into\n   * @param rowIndex - The index of the row in the data array\n   * @returns `true` if the plugin handled rendering (prevents default), `false`/`void` for default rendering\n   *\n   * @example\n   * ```ts\n   * renderRow(row: any, rowEl: HTMLElement, rowIndex: number): boolean | void {\n   *   if (row._isGroupHeader) {\n   *     rowEl.innerHTML = `<div class=\"group-header\">${row._groupLabel}</div>`;\n   *     return true; // Handled - skip default rendering\n   *   }\n   *   // Return void to let default rendering proceed\n   * }\n   * ```\n   */\n  renderRow?(row: any, rowEl: HTMLElement, rowIndex: number): boolean | void;\n\n  // #endregion\n\n  // #region Inter-Plugin Communication\n\n  /**\n   * Handle queries from other plugins.\n   * This is the generic mechanism for inter-plugin communication.\n   * Plugins can respond to well-known query types or define their own.\n   *\n   * **Prefer `handleQuery` for new plugins** - it has the same signature but\n   * a clearer name. `onPluginQuery` is kept for backwards compatibility.\n   *\n   * @category Plugin Development\n   * @param query - The query object with type and context\n   * @returns Query-specific response, or undefined if not handling this query\n   *\n   * @example\n   * ```ts\n   * onPluginQuery(query: PluginQuery): unknown {\n   *   switch (query.type) {\n   *     case PLUGIN_QUERIES.CAN_MOVE_COLUMN:\n   *       // Prevent moving pinned columns\n   *       const column = query.context as ColumnConfig;\n   *       if (column.sticky === 'left' || column.sticky === 'right') {\n   *         return false;\n   *       }\n   *       break;\n   *     case PLUGIN_QUERIES.GET_CONTEXT_MENU_ITEMS:\n   *       const params = query.context as ContextMenuParams;\n   *       return [{ id: 'my-action', label: 'My Action', action: () => {} }];\n   *   }\n   * }\n   * ```\n   * @deprecated Use `handleQuery` instead for new plugins.\n   */\n  onPluginQuery?(query: PluginQuery): unknown;\n\n  /**\n   * Handle queries from other plugins or the grid.\n   *\n   * Queries are declared in `manifest.queries` and dispatched via `grid.query()`.\n   * This enables type-safe, discoverable inter-plugin communication.\n   *\n   * @category Plugin Development\n   * @param query - The query object with type and context\n   * @returns Query-specific response, or undefined if not handling this query\n   *\n   * @example\n   * ```ts\n   * // In manifest\n   * static override readonly manifest: PluginManifest = {\n   *   queries: [\n   *     { type: 'canMoveColumn', description: 'Check if a column can be moved' },\n   *   ],\n   * };\n   *\n   * // In plugin class\n   * handleQuery(query: PluginQuery): unknown {\n   *   if (query.type === 'canMoveColumn') {\n   *     const column = query.context as ColumnConfig;\n   *     return !column.sticky; // Can't move sticky columns\n   *   }\n   * }\n   * ```\n   */\n  handleQuery?(query: PluginQuery): unknown;\n\n  // #endregion\n\n  // #region Interaction Hooks\n\n  /**\n   * Handle keyboard events on the grid.\n   * Called when a key is pressed while the grid or a cell has focus.\n   *\n   * @param event - The native KeyboardEvent\n   * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default\n   *\n   * @example\n   * ```ts\n   * onKeyDown(event: KeyboardEvent): boolean | void {\n   *   // Handle Ctrl+A for select all\n   *   if (event.ctrlKey && event.key === 'a') {\n   *     this.selectAllRows();\n   *     return true; // Prevent default browser select-all\n   *   }\n   * }\n   * ```\n   */\n  onKeyDown?(event: KeyboardEvent): boolean | void;\n\n  /**\n   * Handle cell click events.\n   * Called when a data cell is clicked (not headers).\n   *\n   * @param event - Cell click event with row/column context\n   * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default\n   *\n   * @example\n   * ```ts\n   * onCellClick(event: CellClickEvent): boolean | void {\n   *   if (event.field === '_select') {\n   *     this.toggleRowSelection(event.rowIndex);\n   *     return true; // Handled\n   *   }\n   * }\n   * ```\n   */\n  onCellClick?(event: CellClickEvent): boolean | void;\n\n  /**\n   * Handle row click events.\n   * Called when any part of a data row is clicked.\n   * Note: This is called in addition to onCellClick, not instead of.\n   *\n   * @param event - Row click event with row context\n   * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default\n   *\n   * @example\n   * ```ts\n   * onRowClick(event: RowClickEvent): boolean | void {\n   *   if (this.config.mode === 'row') {\n   *     this.selectRow(event.rowIndex, event.originalEvent);\n   *     return true;\n   *   }\n   * }\n   * ```\n   */\n  onRowClick?(event: RowClickEvent): boolean | void;\n\n  /**\n   * Handle header click events.\n   * Called when a column header is clicked. Commonly used for sorting.\n   *\n   * @param event - Header click event with column context\n   * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default\n   *\n   * @example\n   * ```ts\n   * onHeaderClick(event: HeaderClickEvent): boolean | void {\n   *   if (event.column.sortable !== false) {\n   *     this.toggleSort(event.field);\n   *     return true;\n   *   }\n   * }\n   * ```\n   */\n  onHeaderClick?(event: HeaderClickEvent): boolean | void;\n\n  /**\n   * Handle scroll events on the grid viewport.\n   * Called during scrolling. Note: This may be called frequently; debounce if needed.\n   *\n   * @param event - Scroll event with scroll position and viewport dimensions\n   *\n   * @example\n   * ```ts\n   * onScroll(event: ScrollEvent): void {\n   *   // Update sticky column positions\n   *   this.updateStickyPositions(event.scrollLeft);\n   * }\n   * ```\n   */\n  onScroll?(event: ScrollEvent): void;\n\n  /**\n   * Handle cell mousedown events.\n   * Used for initiating drag operations like range selection or column resize.\n   *\n   * @param event - Mouse event with cell context\n   * @returns `true` to indicate drag started (prevents text selection), `false`/`void` otherwise\n   *\n   * @example\n   * ```ts\n   * onCellMouseDown(event: CellMouseEvent): boolean | void {\n   *   if (event.rowIndex !== undefined && this.config.mode === 'range') {\n   *     this.startDragSelection(event.rowIndex, event.colIndex);\n   *     return true; // Prevent text selection\n   *   }\n   * }\n   * ```\n   */\n  onCellMouseDown?(event: CellMouseEvent): boolean | void;\n\n  /**\n   * Handle cell mousemove events during drag operations.\n   * Only called when a drag is in progress (after mousedown returned true).\n   *\n   * @param event - Mouse event with current cell context\n   * @returns `true` to continue handling the drag, `false`/`void` otherwise\n   *\n   * @example\n   * ```ts\n   * onCellMouseMove(event: CellMouseEvent): boolean | void {\n   *   if (this.isDragging && event.rowIndex !== undefined) {\n   *     this.extendSelection(event.rowIndex, event.colIndex);\n   *     return true;\n   *   }\n   * }\n   * ```\n   */\n  onCellMouseMove?(event: CellMouseEvent): boolean | void;\n\n  /**\n   * Handle cell mouseup events to end drag operations.\n   *\n   * @param event - Mouse event with final cell context\n   * @returns `true` if drag was finalized, `false`/`void` otherwise\n   *\n   * @example\n   * ```ts\n   * onCellMouseUp(event: CellMouseEvent): boolean | void {\n   *   if (this.isDragging) {\n   *     this.finalizeDragSelection();\n   *     this.isDragging = false;\n   *     return true;\n   *   }\n   * }\n   * ```\n   */\n  onCellMouseUp?(event: CellMouseEvent): boolean | void;\n\n  // Note: Context menu items are provided via handleQuery('getContextMenuItems').\n  // This keeps the core decoupled from the context-menu plugin specifics.\n\n  // #endregion\n\n  // #region Column State Hooks\n\n  /**\n   * Contribute plugin-specific state for a column.\n   * Called by the grid when collecting column state for serialization.\n   * Plugins can add their own properties to the column state.\n   *\n   * @param field - The field name of the column\n   * @returns Partial column state with plugin-specific properties, or undefined if no state to contribute\n   *\n   * @example\n   * ```ts\n   * getColumnState(field: string): Partial<ColumnState> | undefined {\n   *   const filterModel = this.filterModels.get(field);\n   *   if (filterModel) {\n   *     // Uses module augmentation to add filter property to ColumnState\n   *     return { filter: filterModel } as Partial<ColumnState>;\n   *   }\n   *   return undefined;\n   * }\n   * ```\n   */\n  getColumnState?(field: string): Partial<ColumnState> | undefined;\n\n  /**\n   * Apply plugin-specific state to a column.\n   * Called by the grid when restoring column state from serialized data.\n   * Plugins should restore their internal state based on the provided state.\n   *\n   * @param field - The field name of the column\n   * @param state - The column state to apply (may contain plugin-specific properties)\n   *\n   * @example\n   * ```ts\n   * applyColumnState(field: string, state: ColumnState): void {\n   *   // Check for filter property added via module augmentation\n   *   const filter = (state as any).filter;\n   *   if (filter) {\n   *     this.filterModels.set(field, filter);\n   *     this.applyFilter();\n   *   }\n   * }\n   * ```\n   */\n  applyColumnState?(field: string, state: ColumnState): void;\n\n  // #endregion\n\n  // #region Scroll Boundary Hooks\n\n  /**\n   * Report horizontal scroll boundary offsets for this plugin.\n   * Plugins that obscure part of the scroll area (e.g., pinned/sticky columns)\n   * should return how much space they occupy on each side.\n   * The keyboard navigation uses this to ensure focused cells are fully visible.\n   *\n   * @param rowEl - The row element (optional, for calculating widths from rendered cells)\n   * @param focusedCell - The currently focused cell element (optional, to determine if scrolling should be skipped)\n   * @returns Object with left/right pixel offsets and optional skipScroll flag, or undefined if plugin has no offsets\n   *\n   * @example\n   * ```ts\n   * getHorizontalScrollOffsets(rowEl?: HTMLElement, focusedCell?: HTMLElement): { left: number; right: number; skipScroll?: boolean } | undefined {\n   *   // Calculate total width of left-pinned columns\n   *   const leftCells = rowEl?.querySelectorAll('.sticky-left') ?? [];\n   *   let left = 0;\n   *   leftCells.forEach(el => { left += (el as HTMLElement).offsetWidth; });\n   *   // Skip scroll if focused cell is pinned (always visible)\n   *   const skipScroll = focusedCell?.classList.contains('sticky-left');\n   *   return { left, right: 0, skipScroll };\n   * }\n   * ```\n   */\n  getHorizontalScrollOffsets?(\n    rowEl?: HTMLElement,\n    focusedCell?: HTMLElement,\n  ): { left: number; right: number; skipScroll?: boolean } | undefined;\n\n  // #endregion\n\n  // #region Shell Integration Hooks\n\n  /**\n   * Register a tool panel for this plugin.\n   * Return undefined if plugin has no tool panel.\n   * The shell will create a toolbar toggle button and render the panel content\n   * when the user opens the panel.\n   *\n   * @returns Tool panel definition, or undefined if plugin has no panel\n   *\n   * @example\n   * ```ts\n   * getToolPanel(): ToolPanelDefinition | undefined {\n   *   return {\n   *     id: 'columns',\n   *     title: 'Columns',\n   *     icon: '☰',\n   *     tooltip: 'Show/hide columns',\n   *     order: 10,\n   *     render: (container) => {\n   *       this.renderColumnList(container);\n   *       return () => this.cleanup();\n   *     },\n   *   };\n   * }\n   * ```\n   */\n  getToolPanel?(): ToolPanelDefinition | undefined;\n\n  /**\n   * Register content for the shell header center section.\n   * Return undefined if plugin has no header content.\n   * Examples: search input, selection summary, status indicators.\n   *\n   * @returns Header content definition, or undefined if plugin has no header content\n   *\n   * @example\n   * ```ts\n   * getHeaderContent(): HeaderContentDefinition | undefined {\n   *   return {\n   *     id: 'quick-filter',\n   *     order: 10,\n   *     render: (container) => {\n   *       const input = document.createElement('input');\n   *       input.type = 'text';\n   *       input.placeholder = 'Search...';\n   *       input.addEventListener('input', this.handleInput);\n   *       container.appendChild(input);\n   *       return () => input.removeEventListener('input', this.handleInput);\n   *     },\n   *   };\n   * }\n   * ```\n   */\n  getHeaderContent?(): HeaderContentDefinition | undefined;\n\n  // #endregion\n}\n","/**\n * Print Plugin (Class-based)\n *\n * Provides print layout functionality for tbw-grid.\n * Temporarily disables virtualization to render all rows and uses\n * @media print CSS for print-optimized styling.\n */\n\nimport { BaseGridPlugin } from '../../core/plugin/base-plugin';\nimport type { InternalGrid, ToolbarContentDefinition } from '../../core/types';\nimport { printGridIsolated } from './print-isolated';\nimport styles from './print.css?inline';\nimport type { PrintCompleteDetail, PrintConfig, PrintParams, PrintStartDetail } from './types';\n\n/**\n * Extended grid interface for PrintPlugin internal access.\n * Includes registerToolbarContent which is available on the grid class\n * but not exposed in the standard plugin API.\n */\ninterface PrintGridRef extends InternalGrid {\n  registerToolbarContent?(content: ToolbarContentDefinition): void;\n  unregisterToolbarContent?(contentId: string): void;\n}\n\n/** Default configuration */\nconst DEFAULT_CONFIG: Required<PrintConfig> = {\n  button: false,\n  orientation: 'landscape',\n  warnThreshold: 500,\n  maxRows: 0,\n  includeTitle: true,\n  includeTimestamp: true,\n  title: '',\n  isolate: false,\n};\n\n/**\n * Print Plugin for tbw-grid\n *\n * Enables printing the full grid content by temporarily disabling virtualization\n * and applying print-optimized styles. Handles large datasets gracefully with\n * configurable row limits.\n *\n * ## Installation\n *\n * ```ts\n * import { PrintPlugin } from '@toolbox-web/grid/plugins/print';\n * ```\n *\n * ## Configuration Options\n *\n * | Option | Type | Default | Description |\n * |--------|------|---------|-------------|\n * | `button` | `boolean` | `false` | Show print button in toolbar |\n * | `orientation` | `'portrait' \\| 'landscape'` | `'landscape'` | Page orientation |\n * | `warnThreshold` | `number` | `500` | Show confirmation dialog when rows exceed this (0 = no warning) |\n * | `maxRows` | `number` | `0` | Hard limit on printed rows (0 = unlimited) |\n * | `includeTitle` | `boolean` | `true` | Include grid title in print |\n * | `includeTimestamp` | `boolean` | `true` | Include timestamp in footer |\n * | `title` | `string` | `''` | Custom print title |\n *\n * ## Programmatic API\n *\n * | Method | Signature | Description |\n * |--------|-----------|-------------|\n * | `print` | `(params?) => Promise<void>` | Trigger print dialog |\n * | `isPrinting` | `() => boolean` | Check if print is in progress |\n *\n * ## Events\n *\n * | Event | Detail | Description |\n * |-------|--------|-------------|\n * | `print-start` | `PrintStartDetail` | Fired when print begins |\n * | `print-complete` | `PrintCompleteDetail` | Fired when print completes |\n *\n * @example Basic Print\n * ```ts\n * import { PrintPlugin } from '@toolbox-web/grid/plugins/print';\n *\n * const grid = document.querySelector('tbw-grid');\n * grid.gridConfig = {\n *   plugins: [new PrintPlugin()],\n * };\n *\n * // Trigger print\n * const printPlugin = grid.getPlugin(PrintPlugin);\n * await printPlugin.print();\n * ```\n *\n * @example With Toolbar Button\n * ```ts\n * grid.gridConfig = {\n *   plugins: [new PrintPlugin({ button: true, orientation: 'landscape' })],\n * };\n * ```\n *\n * @see {@link PrintConfig} for all configuration options\n */\nexport class PrintPlugin extends BaseGridPlugin<PrintConfig> {\n  /** @internal */\n  readonly name = 'print';\n\n  /** @internal */\n  override readonly version = '1.0.0';\n\n  /** CSS styles for print mode */\n  override readonly styles = styles;\n\n  /** Current print state */\n  #printing = false;\n\n  /** Saved column visibility state */\n  #savedHiddenColumns: Map<string, boolean> | null = null;\n\n  /** Saved virtualization state */\n  #savedVirtualization: { bypassThreshold: number } | null = null;\n\n  /** Saved rows when maxRows limit is applied */\n  #savedRows: unknown[] | null = null;\n\n  /** Print header element */\n  #printHeader: HTMLElement | null = null;\n\n  /** Print footer element */\n  #printFooter: HTMLElement | null = null;\n\n  /** Applied scale factor (legacy, used for cleanup) */\n  #appliedScale: number | null = null;\n\n  /**\n   * Get the grid typed as PrintGridRef for internal access.\n   */\n  get #internalGrid(): PrintGridRef {\n    return this.grid as unknown as PrintGridRef;\n  }\n\n  /**\n   * Check if print is currently in progress\n   */\n  isPrinting(): boolean {\n    return this.#printing;\n  }\n\n  /**\n   * Trigger the browser print dialog\n   *\n   * This method:\n   * 1. Validates row count against maxRows limit\n   * 2. Disables virtualization to render all rows\n   * 3. Applies print-specific CSS classes\n   * 4. Opens the browser print dialog (or isolated window if `isolate: true`)\n   * 5. Restores normal state after printing\n   *\n   * @param params - Optional parameters to override config for this print\n   * @param params.isolate - If true, prints in an isolated window containing only the grid\n   * @returns Promise that resolves when print dialog closes\n   */\n  async print(params?: PrintParams): Promise<void> {\n    if (this.#printing) {\n      console.warn('[PrintPlugin] Print already in progress');\n      return;\n    }\n\n    const grid = this.gridElement;\n    if (!grid) {\n      console.warn('[PrintPlugin] Grid not available');\n      return;\n    }\n\n    const config = { ...DEFAULT_CONFIG, ...this.config, ...params };\n    const rows = this.rows;\n    const originalRowCount = rows.length;\n    let rowCount = originalRowCount;\n    let limitApplied = false;\n\n    // Check if we should warn about large datasets\n    if (config.warnThreshold > 0 && originalRowCount > config.warnThreshold) {\n      const limitInfo =\n        config.maxRows > 0 ? `\\n\\nNote: Output will be limited to ${config.maxRows.toLocaleString()} rows.` : '';\n      const proceed = confirm(\n        `This grid has ${originalRowCount.toLocaleString()} rows. ` +\n          `Printing large datasets may cause performance issues or browser slowdowns.${limitInfo}\\n\\n` +\n          `Click OK to continue, or Cancel to abort.`,\n      );\n      if (!proceed) {\n        return;\n      }\n    }\n\n    // Apply hard row limit if configured\n    if (config.maxRows > 0 && originalRowCount > config.maxRows) {\n      rowCount = config.maxRows;\n      limitApplied = true;\n    }\n\n    this.#printing = true;\n\n    // Track timing for duration reporting\n    const startTime = performance.now();\n\n    // Emit print-start event\n    this.emit<PrintStartDetail>('print-start', {\n      rowCount,\n      limitApplied,\n      originalRowCount,\n    });\n\n    try {\n      // Save current virtualization state\n      const internalGrid = this.#internalGrid;\n      this.#savedVirtualization = {\n        bypassThreshold: internalGrid._virtualization?.bypassThreshold ?? 24,\n      };\n\n      // Hide columns marked with printHidden\n      this.#hidePrintColumns();\n\n      // Apply row limit if configured\n      if (limitApplied) {\n        this.#savedRows = this.sourceRows;\n        // Set limited rows on the grid\n        (this.grid as unknown as { rows: unknown[] }).rows = this.sourceRows.slice(0, rowCount);\n        // Wait for grid to process new rows\n        await new Promise((resolve) => setTimeout(resolve, 50));\n      }\n\n      // Add print header if configured\n      if (config.includeTitle || config.includeTimestamp) {\n        this.#addPrintHeader(config);\n      }\n\n      // Disable virtualization to render all rows\n      // This forces the grid to render all rows in the DOM\n      await this.#disableVirtualization();\n\n      // Wait for next frame to ensure DOM is updated\n      await new Promise((resolve) => requestAnimationFrame(resolve));\n      await new Promise((resolve) => requestAnimationFrame(resolve));\n\n      // Add orientation class for @page rules\n      grid.classList.add(`print-${config.orientation}`);\n\n      // Wait for next frame to ensure DOM is updated\n      await new Promise((resolve) => requestAnimationFrame(resolve));\n      await new Promise((resolve) => requestAnimationFrame(resolve));\n\n      // Trigger browser print dialog (isolated or inline)\n      if (config.isolate) {\n        await this.#printInIsolatedWindow(config);\n      } else {\n        await this.#triggerPrint();\n      }\n\n      // Emit print-complete event\n      this.emit<PrintCompleteDetail>('print-complete', {\n        success: true,\n        rowCount,\n        duration: Math.round(performance.now() - startTime),\n      });\n    } catch (error) {\n      console.error('[PrintPlugin] Print failed:', error);\n      this.emit<PrintCompleteDetail>('print-complete', {\n        success: false,\n        rowCount: 0,\n        duration: Math.round(performance.now() - startTime),\n      });\n    } finally {\n      // Restore normal state\n      this.#cleanup();\n      this.#printing = false;\n    }\n  }\n\n  /**\n   * Add print header with title and timestamp\n   */\n  #addPrintHeader(config: Required<PrintConfig>): void {\n    const grid = this.gridElement;\n    if (!grid) return;\n\n    // Create print header\n    this.#printHeader = document.createElement('div');\n    this.#printHeader.className = 'tbw-print-header';\n\n    // Title\n    if (config.includeTitle) {\n      const title = config.title || this.grid.effectiveConfig?.shell?.header?.title || 'Grid Data';\n      const titleEl = document.createElement('div');\n      titleEl.className = 'tbw-print-header-title';\n      titleEl.textContent = title;\n      this.#printHeader.appendChild(titleEl);\n    }\n\n    // Timestamp\n    if (config.includeTimestamp) {\n      const timestampEl = document.createElement('div');\n      timestampEl.className = 'tbw-print-header-timestamp';\n      timestampEl.textContent = `Printed: ${new Date().toLocaleString()}`;\n      this.#printHeader.appendChild(timestampEl);\n    }\n\n    // Insert at the beginning of the grid\n    grid.insertBefore(this.#printHeader, grid.firstChild);\n\n    // Create print footer\n    this.#printFooter = document.createElement('div');\n    this.#printFooter.className = 'tbw-print-footer';\n    this.#printFooter.textContent = `Page generated from ${window.location.hostname}`;\n    grid.appendChild(this.#printFooter);\n  }\n\n  /**\n   * Disable virtualization to render all rows\n   */\n  async #disableVirtualization(): Promise<void> {\n    const internalGrid = this.#internalGrid;\n    if (!internalGrid._virtualization) return;\n\n    // Set bypass threshold higher than total row count to disable virtualization\n    // This makes the grid render all rows (up to maxRows) instead of just visible ones\n    const totalRows = this.rows.length;\n    internalGrid._virtualization.bypassThreshold = totalRows + 100;\n\n    // Force a full refresh to re-render with virtualization disabled\n    internalGrid.refreshVirtualWindow(true);\n\n    // Wait for render to complete\n    await new Promise((resolve) => setTimeout(resolve, 100));\n  }\n\n  /**\n   * Trigger the browser print dialog\n   */\n  async #triggerPrint(): Promise<void> {\n    return new Promise((resolve) => {\n      // Listen for afterprint event\n      const onAfterPrint = () => {\n        window.removeEventListener('afterprint', onAfterPrint);\n        resolve();\n      };\n      window.addEventListener('afterprint', onAfterPrint);\n\n      // Trigger print\n      window.print();\n\n      // Fallback timeout in case afterprint doesn't fire (some browsers)\n      setTimeout(() => {\n        // Guard against test environment teardown where window may be undefined\n        if (typeof window !== 'undefined') {\n          window.removeEventListener('afterprint', onAfterPrint);\n        }\n        resolve();\n      }, 1000);\n    });\n  }\n\n  /**\n   * Print in isolation by hiding all other page content.\n   * This excludes navigation, sidebars, etc. while keeping the grid in place.\n   */\n  async #printInIsolatedWindow(config: Required<PrintConfig>): Promise<void> {\n    const grid = this.gridElement;\n    if (!grid) return;\n\n    await printGridIsolated(grid, {\n      orientation: config.orientation,\n    });\n  }\n\n  /**\n   * Hide columns marked with printHidden: true\n   */\n  #hidePrintColumns(): void {\n    const columns = this.columns;\n    if (!columns) return;\n\n    // Save current hidden state and hide print columns\n    this.#savedHiddenColumns = new Map();\n\n    for (const col of columns) {\n      if (col.printHidden && col.field) {\n        // Save current visibility state (true = visible, false = hidden)\n        this.#savedHiddenColumns.set(col.field, !col.hidden);\n        // Hide the column for printing\n        this.grid.setColumnVisible(col.field, false);\n      }\n    }\n  }\n\n  /**\n   * Restore columns that were hidden for printing\n   */\n  #restorePrintColumns(): void {\n    if (!this.#savedHiddenColumns) return;\n\n    for (const [field, wasVisible] of this.#savedHiddenColumns) {\n      // Restore original visibility\n      this.grid.setColumnVisible(field, wasVisible);\n    }\n\n    this.#savedHiddenColumns = null;\n  }\n\n  /**\n   * Cleanup after printing\n   */\n  #cleanup(): void {\n    const grid = this.gridElement;\n    if (!grid) return;\n\n    // Restore columns that were hidden for printing\n    this.#restorePrintColumns();\n\n    // Remove orientation classes (both original and possibly switched)\n    grid.classList.remove('print-portrait', 'print-landscape');\n\n    // Remove scaling transform if applied (legacy)\n    if (this.#appliedScale !== null) {\n      grid.style.transform = '';\n      grid.style.transformOrigin = '';\n      grid.style.width = '';\n      this.#appliedScale = null;\n    }\n\n    // Remove print header/footer\n    if (this.#printHeader) {\n      this.#printHeader.remove();\n      this.#printHeader = null;\n    }\n    if (this.#printFooter) {\n      this.#printFooter.remove();\n      this.#printFooter = null;\n    }\n\n    // Restore virtualization\n    const internalGrid = this.#internalGrid;\n    if (this.#savedVirtualization && internalGrid._virtualization) {\n      internalGrid._virtualization.bypassThreshold = this.#savedVirtualization.bypassThreshold;\n      internalGrid.refreshVirtualWindow(true);\n      this.#savedVirtualization = null;\n    }\n\n    // Restore original rows if they were limited\n    if (this.#savedRows !== null) {\n      (this.grid as unknown as { rows: unknown[] }).rows = this.#savedRows;\n      this.#savedRows = null;\n    }\n  }\n\n  /**\n   * Register toolbar button if configured\n   * @internal\n   */\n  override afterRender(): void {\n    // Register toolbar on first render when button is enabled\n    if (this.config?.button && !this.#toolbarRegistered) {\n      this.#registerToolbarButton();\n      this.#toolbarRegistered = true;\n    }\n  }\n\n  /** Track if toolbar button is registered */\n  #toolbarRegistered = false;\n\n  /**\n   * Register print button in toolbar\n   */\n  #registerToolbarButton(): void {\n    const grid = this.#internalGrid;\n\n    // Register toolbar content\n    grid.registerToolbarContent?.({\n      id: 'print-button',\n      order: 900, // High order to appear at the end\n      render: (container: HTMLElement) => {\n        const button = document.createElement('button');\n        button.className = 'tbw-toolbar-btn tbw-print-btn';\n        button.title = 'Print grid';\n        button.type = 'button';\n\n        // Use print icon\n        const icon = this.resolveIcon('print') || '🖨️';\n        this.setIcon(button, icon);\n\n        button.addEventListener(\n          'click',\n          () => {\n            this.print();\n          },\n          { signal: this.disconnectSignal },\n        );\n\n        container.appendChild(button);\n      },\n    });\n  }\n}\n"],"names":["ISOLATION_STYLE_ID","async","printGridIsolated","gridElement","options","orientation","gridId","id","document","querySelectorAll","CSS","escape","length","console","warn","getElementById","remove","isolationStyle","style","createElement","textContent","createIsolationStylesheet","head","appendChild","Promise","resolve","onAfterPrint","window","removeEventListener","addEventListener","print","setTimeout","DEFAULT_FILTER_ICON","DEFAULT_GRID_ICONS","expand","collapse","sortAsc","sortDesc","sortNone","submenuArrow","dragHandle","toolPanel","filter","filterActive","BaseGridPlugin","static","version","__GRID_VERSION__","styles","cellRenderers","headerRenderers","cellEditors","grid","config","userConfig","abortController","defaultConfig","constructor","this","attach","abort","AbortController","detach","getPlugin","PluginClass","emit","eventName","detail","dispatchEvent","CustomEvent","bubbles","emitCancelable","event","cancelable","defaultPrevented","on","eventType","callback","_pluginManager","subscribe","off","unsubscribe","emitPluginEvent","requestRender","requestColumnsRender","requestRenderWithFocus","requestAfterRender","rows","sourceRows","columns","visibleColumns","_visibleColumns","disconnectSignal","signal","gridIcons","userIcons","gridConfig","icons","isAnimationEnabled","mode","effectiveConfig","animation","host","getComputedStyle","getPropertyValue","trim","animationDuration","durationStr","parsed","parseInt","isNaN","resolveIcon","iconKey","pluginOverride","setIcon","element","icon","innerHTML","HTMLElement","cloneNode","message","name","DEFAULT_CONFIG","button","warnThreshold","maxRows","includeTitle","includeTimestamp","title","isolate","PrintPlugin","printing","savedHiddenColumns","savedVirtualization","savedRows","printHeader","printFooter","appliedScale","internalGrid","isPrinting","params","originalRowCount","rowCount","limitApplied","limitInfo","toLocaleString","confirm","startTime","performance","now","bypassThreshold","_virtualization","hidePrintColumns","slice","addPrintHeader","disableVirtualization","requestAnimationFrame","classList","add","printInIsolatedWindow","triggerPrint","success","duration","Math","round","error","cleanup","className","shell","header","titleEl","timestampEl","Date","insertBefore","firstChild","location","hostname","totalRows","refreshVirtualWindow","Map","col","printHidden","field","set","hidden","setColumnVisible","restorePrintColumns","wasVisible","transform","transformOrigin","width","afterRender","toolbarRegistered","registerToolbarButton","registerToolbarContent","order","render","container","type"],"mappings":"AAeA,MAAMA,EAAqB,4BAsG3BC,eAAsBC,EAAkBC,EAA0BC,EAAgC,IAChG,MAAMC,YAAEA,EAAc,aAAgBD,EAEhCE,EAASH,EAAYI,GAGJC,SAASC,iBAAiB,IAAIC,IAAIC,OAAOL,MAC7CM,OAAS,GAC1BC,QAAQC,KACN,qDAAqDR,iFAMzDE,SAASO,eAAef,IAAqBgB,SAG7C,MAAMC,EAlHR,SAAmCX,EAAgBD,GACjD,MAAMa,EAAQV,SAASW,cAAc,SAyErC,OAxEAD,EAAMX,GAAKP,EACXkB,EAAME,YAAc,+JAIAd,0IAKbA,meAeAA,cACAA,kJAKaA,0BACFA,6gBAeAA,oBAAyBA,YAAiBA,+GAM9CD,yeAmBPa,CACT,CAuCyBG,CAA0Bf,EAAQD,GAGzD,OAFAG,SAASc,KAAKC,YAAYN,GAEnB,IAAIO,QAASC,IAElB,MAAMC,EAAe,KACnBC,OAAOC,oBAAoB,aAAcF,GAEzClB,SAASO,eAAef,IAAqBgB,SAC7CS,KAEFE,OAAOE,iBAAiB,aAAcH,GAGtCC,OAAOG,QAGPC,WAAW,KACTJ,OAAOC,oBAAoB,aAAcF,GACzClB,SAASO,eAAef,IAAqBgB,SAC7CS,KACC,MAEP,CCs8EA,MAAMO,EACJ,iRAGWC,EAA0C,CACrDC,OAAQ,IACRC,SAAU,IACVC,QAAS,IACTC,SAAU,IACVC,SAAU,IACVC,aAAc,IACdC,WAAY,KACZC,UAAW,IACXC,OAAQV,EACRW,aAAcX,EACdF,MAAO,OCjvEF,MAAec,EAgBpBC,oBAuBAA,gBASSC,QAA8C,oBAArBC,iBAAmCA,iBAAmB,MAG/EC,OAGAC,cAGAC,gBAGAC,YAGCC,KAGAC,OAGSC,WAOnBC,GAOA,iBAAcC,GACZ,MAAO,CAAA,CACT,CAEA,WAAAC,CAAYJ,EAA2B,IACrCK,KAAKJ,WAAaD,CACpB,CAiBA,MAAAM,CAAOP,GAELM,MAAKH,GAAkBK,QAEvBF,MAAKH,EAAmB,IAAIM,gBAE5BH,KAAKN,KAAOA,EAEZM,KAAKL,OAAS,IAAKK,KAAKF,iBAAkBE,KAAKJ,WACjD,CAeA,MAAAQ,GAGEJ,MAAKH,GAAkBK,QACvBF,MAAKH,OAAmB,CAE1B,CAkDU,SAAAQ,CAAoCC,GAC5C,OAAON,KAAKN,MAAMW,UAAUC,EAC9B,CAKU,IAAAC,CAAQC,EAAmBC,GACnCT,KAAKN,MAAMgB,gBAAgB,IAAIC,YAAYH,EAAW,CAAEC,SAAQG,SAAS,IAC3E,CAMU,cAAAC,CAAkBL,EAAmBC,GAC7C,MAAMK,EAAQ,IAAIH,YAAYH,EAAW,CAAEC,SAAQG,SAAS,EAAMG,YAAY,IAE9E,OADAf,KAAKN,MAAMgB,gBAAgBI,GACpBA,EAAME,gBACf,CAsBU,EAAAC,CAAgBC,EAAmBC,GAC3CnB,KAAKN,MAAM0B,gBAAgBC,UAAUrB,KAAMkB,EAAWC,EACxD,CAaU,GAAAG,CAAIJ,GACZlB,KAAKN,MAAM0B,gBAAgBG,YAAYvB,KAAMkB,EAC/C,CAoBU,eAAAM,CAAmBN,EAAmBT,GAC9CT,KAAKN,MAAM0B,gBAAgBI,gBAAgBN,EAAWT,EACxD,CAMU,aAAAgB,GACRzB,KAAKN,MAAM+B,iBACb,CAOU,oBAAAC,GACP1B,KAAKN,MAAgDgC,wBACxD,CAOU,sBAAAC,GACR3B,KAAKN,MAAMiC,0BACb,CAMU,kBAAAC,GACR5B,KAAKN,MAAMkC,sBACb,CAKA,QAAcC,GACZ,OAAO7B,KAAKN,MAAMmC,MAAQ,EAC5B,CAMA,cAAcC,GACZ,OAAO9B,KAAKN,MAAMoC,YAAc,EAClC,CAKA,WAAcC,GACZ,OAAO/B,KAAKN,MAAMqC,SAAW,EAC/B,CAMA,kBAAcC,GACZ,OAAOhC,KAAKN,MAAMuC,iBAAmB,EACvC,CAYA,eAAcxF,GACZ,OAAOuD,KAAKN,IACd,CAmBA,oBAAcwC,GAGZ,OAAOlC,MAAKH,GAAkBsC,QAAUnC,KAAKN,MAAMwC,gBACrD,CAMA,aAAcE,GACZ,MAAMC,EAAYrC,KAAKN,MAAM4C,YAAYC,OAAS,CAAA,EAClD,MAAO,IAAKhE,KAAuB8D,EACrC,CAoBA,sBAAcG,GACZ,MAAMC,EAAOzC,KAAKN,MAAMgD,iBAAiBC,WAAWF,MAAQ,iBAG5D,IAAa,IAATA,GAA2B,QAATA,EAAgB,OAAO,EAG7C,IAAa,IAATA,GAA0B,OAATA,EAAe,OAAO,EAG3C,MAAMG,EAAO5C,KAAKvD,YAClB,GAAImG,EAAM,CAER,MAAmB,MADHC,iBAAiBD,GAAME,iBAAiB,2BAA2BC,MAErF,CAEA,OAAO,CACT,CAcA,qBAAcC,GACZ,MAAMJ,EAAO5C,KAAKvD,YAClB,GAAImG,EAAM,CACR,MAAMK,EAAcJ,iBAAiBD,GAAME,iBAAiB,4BAA4BC,OAClFG,EAASC,SAASF,EAAa,IACrC,IAAKG,MAAMF,GAAS,OAAOA,CAC7B,CACA,OAAO,GACT,CAYU,WAAAG,CAAYC,EAA0CC,GAE9D,YAAuB,IAAnBA,EACKA,EAGFvD,KAAKoC,UAAUkB,EACxB,CASU,OAAAE,CAAQC,EAAsBC,GAClB,iBAATA,EACTD,EAAQE,UAAYD,EACXA,aAAgBE,cACzBH,EAAQE,UAAY,GACpBF,EAAQ5F,YAAY6F,EAAKG,WAAU,IAEvC,CAKU,IAAAzG,CAAK0G,GACb3G,QAAQC,KAAK,aAAa4C,KAAK+D,SAASD,IAC1C,QCt0BIE,EAAwC,CAC5CC,QAAQ,EACRtH,YAAa,YACbuH,cAAe,IACfC,QAAS,EACTC,cAAc,EACdC,kBAAkB,EAClBC,MAAO,GACPC,SAAS,GAiEJ,MAAMC,UAAoBtF,EAEtB6E,KAAO,QAGE3E,QAAU,QAGVE,kwEAGlBmF,IAAY,EAGZC,GAAmD,KAGnDC,GAA2D,KAG3DC,GAA+B,KAG/BC,GAAmC,KAGnCC,GAAmC,KAGnCC,GAA+B,KAK/B,KAAIC,GACF,OAAOhF,KAAKN,IACd,CAKA,UAAAuF,GACE,OAAOjF,MAAKyE,CACd,CAgBA,WAAMrG,CAAM8G,GACV,GAAIlF,MAAKyE,EAEP,YADAtH,QAAQC,KAAK,2CAIf,MAAMsC,EAAOM,KAAKvD,YAClB,IAAKiD,EAEH,YADAvC,QAAQC,KAAK,oCAIf,MAAMuC,EAAS,IAAKqE,KAAmBhE,KAAKL,UAAWuF,GAEjDC,EADOnF,KAAK6B,KACY3E,OAC9B,IAAIkI,EAAWD,EACXE,GAAe,EAGnB,GAAI1F,EAAOuE,cAAgB,GAAKiB,EAAmBxF,EAAOuE,cAAe,CACvE,MAAMoB,EACJ3F,EAAOwE,QAAU,EAAI,uCAAuCxE,EAAOwE,QAAQoB,yBAA2B,GAMxG,IALgBC,QACd,iBAAiBL,EAAiBI,oGAC6CD,kDAI/E,MAEJ,CAGI3F,EAAOwE,QAAU,GAAKgB,EAAmBxF,EAAOwE,UAClDiB,EAAWzF,EAAOwE,QAClBkB,GAAe,GAGjBrF,MAAKyE,GAAY,EAGjB,MAAMgB,EAAYC,YAAYC,MAG9B3F,KAAKO,KAAuB,cAAe,CACzC6E,WACAC,eACAF,qBAGF,IAEE,MAAMH,EAAehF,MAAKgF,EAC1BhF,MAAK2E,EAAuB,CAC1BiB,gBAAiBZ,EAAaa,iBAAiBD,iBAAmB,IAIpE5F,MAAK8F,IAGDT,IACFrF,MAAK4E,EAAa5E,KAAK8B,WAEtB9B,KAAKN,KAAwCmC,KAAO7B,KAAK8B,WAAWiE,MAAM,EAAGX,SAExE,IAAItH,QAASC,GAAYM,WAAWN,EAAS,OAIjD4B,EAAOyE,cAAgBzE,EAAO0E,mBAChCrE,MAAKgG,EAAgBrG,SAKjBK,MAAKiG,UAGL,IAAInI,QAASC,GAAYmI,sBAAsBnI,UAC/C,IAAID,QAASC,GAAYmI,sBAAsBnI,IAGrD2B,EAAKyG,UAAUC,IAAI,SAASzG,EAAOhD,qBAG7B,IAAImB,QAASC,GAAYmI,sBAAsBnI,UAC/C,IAAID,QAASC,GAAYmI,sBAAsBnI,IAGjD4B,EAAO4E,cACHvE,MAAKqG,EAAuB1G,SAE5BK,MAAKsG,IAIbtG,KAAKO,KAA0B,iBAAkB,CAC/CgG,SAAS,EACTnB,WACAoB,SAAUC,KAAKC,MAAMhB,YAAYC,MAAQF,IAE7C,OAASkB,GACPxJ,QAAQwJ,MAAM,8BAA+BA,GAC7C3G,KAAKO,KAA0B,iBAAkB,CAC/CgG,SAAS,EACTnB,SAAU,EACVoB,SAAUC,KAAKC,MAAMhB,YAAYC,MAAQF,IAE7C,CAAA,QAEEzF,MAAK4G,IACL5G,MAAKyE,GAAY,CACnB,CACF,CAKA,EAAAuB,CAAgBrG,GACd,MAAMD,EAAOM,KAAKvD,YAClB,GAAKiD,EAAL,CAOA,GAJAM,MAAK6E,EAAe/H,SAASW,cAAc,OAC3CuC,MAAK6E,EAAagC,UAAY,mBAG1BlH,EAAOyE,aAAc,CACvB,MAAME,EAAQ3E,EAAO2E,OAAStE,KAAKN,KAAKgD,iBAAiBoE,OAAOC,QAAQzC,OAAS,YAC3E0C,EAAUlK,SAASW,cAAc,OACvCuJ,EAAQH,UAAY,yBACpBG,EAAQtJ,YAAc4G,EACtBtE,MAAK6E,EAAahH,YAAYmJ,EAChC,CAGA,GAAIrH,EAAO0E,iBAAkB,CAC3B,MAAM4C,EAAcnK,SAASW,cAAc,OAC3CwJ,EAAYJ,UAAY,6BACxBI,EAAYvJ,YAAc,4BAAA,IAAgBwJ,MAAO3B,mBACjDvF,MAAK6E,EAAahH,YAAYoJ,EAChC,CAGAvH,EAAKyH,aAAanH,MAAK6E,EAAcnF,EAAK0H,YAG1CpH,MAAK8E,EAAehI,SAASW,cAAc,OAC3CuC,MAAK8E,EAAa+B,UAAY,mBAC9B7G,MAAK8E,EAAapH,YAAc,uBAAuBO,OAAOoJ,SAASC,WACvE5H,EAAK7B,YAAYmC,MAAK8E,EA9BX,CA+Bb,CAKA,OAAMmB,GACJ,MAAMjB,EAAehF,MAAKgF,EAC1B,IAAKA,EAAaa,gBAAiB,OAInC,MAAM0B,EAAYvH,KAAK6B,KAAK3E,OAC5B8H,EAAaa,gBAAgBD,gBAAkB2B,EAAY,IAG3DvC,EAAawC,sBAAqB,SAG5B,IAAI1J,QAASC,GAAYM,WAAWN,EAAS,KACrD,CAKA,OAAMuI,GACJ,OAAO,IAAIxI,QAASC,IAElB,MAAMC,EAAe,KACnBC,OAAOC,oBAAoB,aAAcF,GACzCD,KAEFE,OAAOE,iBAAiB,aAAcH,GAGtCC,OAAOG,QAGPC,WAAW,KAEa,oBAAXJ,QACTA,OAAOC,oBAAoB,aAAcF,GAE3CD,KACC,MAEP,CAMA,OAAMsI,CAAuB1G,GAC3B,MAAMD,EAAOM,KAAKvD,YACbiD,SAEClD,EAAkBkD,EAAM,CAC5B/C,YAAagD,EAAOhD,aAExB,CAKA,EAAAmJ,GACE,MAAM/D,EAAU/B,KAAK+B,QACrB,GAAKA,EAAL,CAGA/B,MAAK0E,qBAA0B+C,IAE/B,IAAA,MAAWC,KAAO3F,EACZ2F,EAAIC,aAAeD,EAAIE,QAEzB5H,MAAK0E,EAAoBmD,IAAIH,EAAIE,OAAQF,EAAII,QAE7C9H,KAAKN,KAAKqI,iBAAiBL,EAAIE,OAAO,GAV5B,CAahB,CAKA,EAAAI,GACE,GAAKhI,MAAK0E,EAAV,CAEA,IAAA,MAAYkD,EAAOK,KAAejI,MAAK0E,EAErC1E,KAAKN,KAAKqI,iBAAiBH,EAAOK,GAGpCjI,MAAK0E,EAAsB,IAPI,CAQjC,CAKA,EAAAkC,GACE,MAAMlH,EAAOM,KAAKvD,YAClB,IAAKiD,EAAM,OAGXM,MAAKgI,IAGLtI,EAAKyG,UAAU7I,OAAO,iBAAkB,mBAGb,OAAvB0C,MAAK+E,IACPrF,EAAKlC,MAAM0K,UAAY,GACvBxI,EAAKlC,MAAM2K,gBAAkB,GAC7BzI,EAAKlC,MAAM4K,MAAQ,GACnBpI,MAAK+E,EAAgB,MAInB/E,MAAK6E,IACP7E,MAAK6E,EAAavH,SAClB0C,MAAK6E,EAAe,MAElB7E,MAAK8E,IACP9E,MAAK8E,EAAaxH,SAClB0C,MAAK8E,EAAe,MAItB,MAAME,EAAehF,MAAKgF,EACtBhF,MAAK2E,GAAwBK,EAAaa,kBAC5Cb,EAAaa,gBAAgBD,gBAAkB5F,MAAK2E,EAAqBiB,gBACzEZ,EAAawC,sBAAqB,GAClCxH,MAAK2E,EAAuB,MAIN,OAApB3E,MAAK4E,IACN5E,KAAKN,KAAwCmC,KAAO7B,MAAK4E,EAC1D5E,MAAK4E,EAAa,KAEtB,CAMS,WAAAyD,GAEHrI,KAAKL,QAAQsE,SAAWjE,MAAKsI,IAC/BtI,MAAKuI,IACLvI,MAAKsI,GAAqB,EAE9B,CAGAA,IAAqB,EAKrB,EAAAC,GACE,MAAM7I,EAAOM,MAAKgF,EAGlBtF,EAAK8I,yBAAyB,CAC5B3L,GAAI,eACJ4L,MAAO,IACPC,OAASC,IACP,MAAM1E,EAASnH,SAASW,cAAc,UACtCwG,EAAO4C,UAAY,gCACnB5C,EAAOK,MAAQ,aACfL,EAAO2E,KAAO,SAGd,MAAMlF,EAAO1D,KAAKqD,YAAY,UAAY,MAC1CrD,KAAKwD,QAAQS,EAAQP,GAErBO,EAAO9F,iBACL,QACA,KACE6B,KAAK5B,SAEP,CAAE+D,OAAQnC,KAAKkC,mBAGjByG,EAAU9K,YAAYoG,KAG5B"}