@toolbox-web/grid 2.8.1 → 2.10.0

package/lib/core/internal/dom-builder.d.ts

@@ -42,6 +42,14 @@ export interface ShellHeaderOptions {
     hasPanels: boolean;
     isPanelOpen: boolean;
     toolPanelIcon?: string;
+    /**
+     * Whether to render the built-in tool panel toggle button and the
+     * adjacent separator. Independent of `hasPanels` so panels can remain
+     * registered (and openable via the public API) while the consumer
+     * supplies their own toggle button.
+     * @default true when hasPanels is true
+     */
+    showToggle?: boolean;
     /** Config toolbar contents with render function (pre-sorted by order) */
     configButtons: Array<{
         id: string;

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.

package/lib/core/types.d.ts

@@ -3261,7 +3261,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
@@ -3309,6 +3310,20 @@ export interface ShellHeaderConfig {
     title?: string;
     /** Custom toolbar content (rendered before tool panel toggle) */
     toolbarContents?: ToolbarContentDefinition[];
+    /**
+     * Whether the grid renders its built-in tool panel toggle button
+     * (`button.tbw-toolbar-btn[data-panel-toggle]`) and the auto-inserted
+     * `.tbw-toolbar-separator` between custom toolbar contents and the toggle.
+     *
+     * Set to `false` when you want to provide your own toggle button (e.g. a
+     * design-system button styled to match your application). Wire your button
+     * to call {@link Grid.toggleToolPanel} (or `toggleToolPanelSection(id)` for
+     * a specific section). All tool panels remain functional; only the
+     * built-in toggle button and adjacent separator are suppressed.
+     *
+     * @default true
+     */
+    toolPanelToggle?: boolean;
     /**
      * Light DOM header content elements (parsed from <tbw-grid-header> children).
      * @internal Set by ConfigManager during merge
@@ -3329,8 +3344,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;
     /**