@toolbox-web/grid 2.9.0 → 2.11.0

package/lib/core/grid.d.ts

@@ -1372,15 +1372,26 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * Each section can be expanded/collapsed independently.
      *
      * @group Tool Panel
+     * @param panelId - Optional ID of the section to expand on open. When provided,
+     *   takes precedence over `shell.toolPanel.defaultOpen`. If the panel is already
+     *   open with a different section expanded, switches to the requested section.
+     *   If the panel ID is not registered, a warning is emitted and the call falls
+     *   back to default behavior (auto-expand `defaultOpen` or first registered panel).
+     *
      * @example
      * ```typescript
-     * // Open the tool panel when a toolbar button is clicked
+     * // Open the tool panel with the default / first section expanded.
      * settingsButton.addEventListener('click', () => {
      *   grid.openToolPanel();
      * });
+     *
+     * // Open the tool panel and jump straight to a specific section.
+     * filtersButton.addEventListener('click', () => {
+     *   grid.openToolPanel('filters');
+     * });
      * ```
      */
-    openToolPanel(): void;
+    openToolPanel(panelId?: string): void;
     /**
      * Close the tool panel sidebar.
      *

package/lib/core/internal/shell-controller.d.ts

@@ -12,8 +12,15 @@ export interface ShellController {
     readonly isPanelOpen: boolean;
     /** Get IDs of expanded accordion sections */
     readonly expandedSections: string[];
-    /** Open the tool panel */
-    openToolPanel(): void;
+    /**
+     * Open the tool panel.
+     * @param panelId - Optional ID of the section to expand on open. When provided,
+     *   takes precedence over `shell.toolPanel.defaultOpen`. If the panel is already
+     *   open with a different section expanded, switches to the requested section.
+     *   If the panel ID is not registered, a `TBW072` warning is emitted and the
+     *   call falls back to default behavior (auto-expand `defaultOpen` or first by order).
+     */
+    openToolPanel(panelId?: string): void;
     /** Close the tool panel */
     closeToolPanel(): void;
     /** Toggle the tool panel */

package/lib/core/internal/shell.d.ts

@@ -21,6 +21,16 @@ export interface ShellState {
     lightDomTitle: string | null;
     /** IDs of tool panels registered from light DOM (to avoid re-parsing) */
     lightDomToolPanelIds: Set<string>;
+    /**
+     * IDs of light DOM tool panels whose `render` has already been bound to a
+     * framework-adapter renderer. Used by `parseLightDomToolPanels` to detect
+     * the FIRST adapter attach (which legitimately needs to swap the vanilla
+     * fallback for the real adapter renderer and tear down any in-progress
+     * render) vs. subsequent re-parses (which must NOT tear down — doing so
+     * unmounts the user's React/Vue/Angular component, losing local state and
+     * resetting scroll position inside the panel).
+     */
+    adapterBoundToolPanelIds: Set<string>;
     /** IDs of toolbar content registered from light DOM (to avoid re-parsing) */
     lightDomToolbarContentIds: Set<string>;
     /** IDs of tool panels registered via registerToolPanel API */

package/lib/core/plugin/index.d.ts

@@ -6,6 +6,7 @@
  */
 export { BaseGridPlugin } from './base-plugin';
 export type { AfterCellRenderContext, AfterRowRenderContext, CellClickEvent, CellCoords, CellEditor, CellMouseEvent, CellRenderer, ContextMenuItem, ContextMenuParams, GridElement, HeaderClickEvent, HeaderRenderer, KeyboardModifiers, PluginCellRenderContext, PluginHeaderRenderContext, PluginQuery, RowClickEvent, ScrollEvent, } from './base-plugin';
+export type { CollectHeaderRowsContext, HeaderRowCell, HeaderRowContribution } from './types';
 export { PluginManager } from './plugin-manager';
 export type { EventDefinition, HookName, PluginConfigRule, PluginDependency, PluginIncompatibility, PluginManifest, PluginPropertyDefinition, QueryDefinition, } from './base-plugin';
 export type { ColumnConfig } from '../types';

package/lib/core/plugin/types.d.ts

@@ -194,6 +194,67 @@ export interface PluginQuery<T = unknown> {
     /** Query-specific context/parameters */
     context: T;
 }
+/**
+ * Context passed in {@link PluginQuery.context} for the `'collectHeaderRows'`
+ * query — used by consumers (e.g. the export plugin) to collect extra header
+ * rows that should sit **above** the leaf column-header row.
+ *
+ * Plugins that contribute header rows (e.g. `GroupingColumnsPlugin`) declare
+ * `{ type: 'collectHeaderRows' }` in their manifest and respond from
+ * `handleQuery` with a {@link HeaderRowContribution} — or an array of them
+ * for multi-row contributions (e.g. multi-level grouping). The consumer
+ * flattens array replies.
+ *
+ * The reply shape is intentionally generic — "here are some cells, each
+ * spanning N leaf columns" — so consumers don't need to know which plugin
+ * produced them. Responding plugins MUST align their contribution to the
+ * `columns` array on this context — `span` values are indices into it.
+ *
+ * @category Plugin Development
+ * @since 2.10.0
+ */
+export interface CollectHeaderRowsContext {
+    /** Resolved leaf columns (in display order) the consumer is about to emit. */
+    columns: ColumnConfig[];
+}
+/**
+ * Single cell in a contributed header row. `span` is the number of leaf
+ * columns this cell covers (always `>= 1`). The sum of `span` across all
+ * cells in a row MUST equal `context.columns.length`.
+ *
+ * `label === ''` is treated as a blank/dropped cell — consumers may still
+ * emit it (to preserve span alignment) or skip the entire row if every
+ * cell is blank.
+ *
+ * @category Plugin Development
+ * @since 2.10.0
+ */
+export interface HeaderRowCell {
+    /** Display label for this cell. Empty string = blank cell (span preserved). */
+    label: string;
+    /** Number of leaf columns covered. Always `>= 1`. */
+    span: number;
+    /** Optional plugin name (for debugging / `processHeaderRow` filtering). */
+    source?: string;
+    /** Optional opaque payload for consumers that need plugin-specific data. */
+    meta?: unknown;
+}
+/**
+ * A single header row contributed by a plugin. Sits **above** the leaf
+ * column-header row in the visual / export output.
+ *
+ * Each contribution represents **one row**. A plugin needing multiple rows
+ * (e.g. multi-level grouping) returns `HeaderRowContribution[]` from
+ * `handleQuery`; the consumer flattens. Within each row, `cells` MUST
+ * independently sum to `context.columns.length`.
+ *
+ * @category Plugin Development
+ * @since 2.10.0
+ */
+export interface HeaderRowContribution {
+    /** Cells in this row, in left-to-right column order. */
+    cells: HeaderRowCell[];
+}
 /**
  * Cell render context for plugin cell renderers.
  * Provides full context including position and editing state.
@@ -414,8 +475,11 @@ export interface GridElementRef {
     readonly expandedToolPanelSections: string[];
     /**
      * Open the tool panel sidebar (accordion view with all registered panels).
+     * @param panelId - Optional ID of the section to expand on open. Takes precedence
+     *   over `shell.toolPanel.defaultOpen`. If the panel ID is unknown, the call
+     *   falls back to default behavior with a `TBW072` warning.
      */
-    openToolPanel(): void;
+    openToolPanel(panelId?: string): void;
     /**
      * Close the tool panel sidebar.
      */

package/lib/core/types.d.ts

@@ -167,8 +167,11 @@ export interface PublicGrid<T = any> {
     unregisterToolPanel?(panelId: string): void;
     /**
      * Open the tool panel sidebar.
+     * @param panelId - Optional ID of the section to expand on open. Takes precedence
+     *   over `shell.toolPanel.defaultOpen`. Falls back to default behavior with a
+     *   warning if the ID is not registered.
      */
-    openToolPanel?(): void;
+    openToolPanel?(panelId?: string): void;
     /**
      * Close the tool panel sidebar.
      */
@@ -3261,7 +3264,8 @@ export declare const DEFAULT_GRID_ICONS: Required<GridIcons>;
  *     },
  *     toolPanel: {
  *       position: 'right',
- *       defaultOpen: 'columns', // Open by default
+ *       initialState: 'open',     // Sidebar open on load
+ *       defaultOpen: 'columns',   // Auto-expand the "Columns" section
  *     },
  *   },
  *   plugins: [new VisibilityPlugin()], // Adds "Columns" panel
@@ -3343,8 +3347,59 @@ export interface ToolPanelConfig {
     position?: 'left' | 'right';
     /** Default panel width in pixels (default: 280) */
     width?: number;
-    /** Panel ID to open by default on load */
+    /**
+     * Accordion section to auto-expand the first time the tool panel opens.
+     *
+     * @deprecated **Behavior change planned for v3.0.0** — see [issue #259](https://github.com/OysteinAmundsen/toolbox/issues/259).
+     *
+     * Today (v2.x, kept for backward compatibility): setting `defaultOpen` also
+     * **opens the sidebar** on grid load. This conflates "which section is
+     * pre-selected" with "is the sidebar open", and there is no way to
+     * pre-select a section without also forcing the sidebar open.
+     *
+     * In v3.0.0 (#259): `defaultOpen` will only pre-select which accordion
+     * section auto-expands the first time the sidebar opens, and will no
+     * longer open the sidebar by itself. Migrate by combining `defaultOpen`
+     * with `initialState: 'open'` (or `locked: true`) when you want both
+     * effects.
+     *
+     * Callers that want forward-compatible behavior today: prefer
+     * `initialState` / `locked` for sidebar open state, and use `defaultOpen`
+     * purely for section selection.
+     *
+     * @since 0.1.1
+     */
     defaultOpen?: string;
+    /**
+     * Initial open state of the tool panel sidebar on grid load.
+     *
+     * - `'closed'` (default) — sidebar starts collapsed; user opens it via the
+     *   built-in toggle button or `grid.openToolPanel()`.
+     * - `'open'` — sidebar starts open; the section named by {@link defaultOpen}
+     *   (or the first registered panel) is expanded.
+     *
+     * Takes precedence over the legacy v2 behavior of {@link defaultOpen}: if
+     * `initialState` is set explicitly, it wins.
+     *
+     * @default 'closed'
+     * @since 2.9.0
+     */
+    initialState?: 'open' | 'closed';
+    /**
+     * When `true`, lock the tool panel sidebar in its open state.
+     *
+     * Effects:
+     * - Implies `initialState: 'open'` — the sidebar is forced open on load.
+     * - `grid.closeToolPanel()` / `grid.toggleToolPanel()` become no-ops while
+     *   locked (the panel cannot be closed by user or programmatic actions).
+     * - Suppresses the built-in toolbar toggle button (same effect as
+     *   `shell.header.toolPanelToggle: false`) since toggling is disabled.
+     * - Accordion sections inside the panel can still be expanded/collapsed.
+     *
+     * @default false
+     * @since 2.9.0
+     */
+    locked?: boolean;
     /** Whether to persist open/closed state (requires Column State Events) */
     persistState?: boolean;
     /**