@toolbox-web/grid 2.14.1 → 2.15.0

package/lib/core/constants.d.ts

@@ -30,9 +30,9 @@ export declare const GridClasses: {
     readonly ROWS_VIEWPORT: "rows-viewport";
     readonly ROWS_SPACER: "rows-spacer";
     readonly ROWS_CONTAINER: "rows";
-    readonly DATA_ROW: "data-row";
+    readonly DATA_ROW: "data-grid-row";
     readonly GROUP_ROW: "group-row";
-    readonly DATA_CELL: "data-cell";
+    readonly DATA_CELL: "cell";
     readonly SELECTED: "selected";
     readonly FOCUSED: "focused";
     readonly EDITING: "editing";
@@ -81,12 +81,12 @@ export declare const GridSelectors: {
     readonly HEADER_CELL: ".header-cell";
     readonly ROWS_VIEWPORT: ".rows-viewport";
     readonly ROWS_CONTAINER: ".rows";
-    readonly DATA_ROW: ".data-row";
-    readonly DATA_CELL: ".data-cell";
+    readonly DATA_ROW: ".data-grid-row";
+    readonly DATA_CELL: ".cell";
     readonly GROUP_ROW: ".group-row";
     readonly CELL_BY_FIELD: (field: string) => string;
-    readonly SELECTED_ROWS: ".data-row.selected";
-    readonly EDITING_CELL: ".data-cell.editing";
+    readonly SELECTED_ROWS: ".data-grid-row.selected";
+    readonly EDITING_CELL: ".cell.editing";
 };
 /**
  * CSS custom property names for theming.

package/lib/core/plugin/base-plugin.d.ts

@@ -785,7 +785,7 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> implements GridP
      * ```ts
      * afterRender(): void {
      *   // Apply selection styling to rendered rows
-     *   const rows = this.gridElement?.querySelectorAll('.data-row');
+     *   const rows = this.gridElement?.querySelectorAll('.data-grid-row');
      *   rows?.forEach((row, i) => {
      *     row.classList.toggle('selected', this.selectedRows.has(i));
      *   });

package/lib/core/types.d.ts

@@ -1568,6 +1568,41 @@ export interface FrameworkAdapter {
      * to use its default built-in editors.
      */
     createEditor<TRow = unknown, TValue = unknown>(element: HTMLElement): ColumnEditorSpec<TRow, TValue> | undefined;
+    /**
+     * Creates a header cell renderer from a light DOM element (e.g. a slot or
+     * template on a `<tbw-grid-column>`). Receives `HeaderCellContext` and
+     * returns DOM / string for the entire header cell — the user is
+     * responsible for sort icons and filter buttons (use
+     * `ctx.renderSortIcon()` / `ctx.renderFilterButton()` helpers).
+     *
+     * Resize handles are appended automatically by the grid for resizable
+     * columns regardless of which renderer path is active; do not render one
+     * yourself.
+     *
+     * Returns undefined when the adapter has no header renderer registered
+     * for this element, letting the grid fall back to its built-in header.
+     *
+     * Mirrors `headerRenderer` from `BaseColumnConfig`. Optional on the
+     * adapter — adapters that don't expose a slot/template surface for
+     * full-header customization can omit it; callers must null-check.
+     *
+     * @since 2.15.0
+     */
+    createHeaderRenderer?<TRow = unknown>(element: HTMLElement): HeaderRenderer<TRow> | undefined;
+    /**
+     * Creates a header *label* renderer from a light DOM element. The grid
+     * keeps ownership of the sort icon, filter button, and resize handle;
+     * the returned function only customizes the label content.
+     *
+     * Returns undefined when the adapter has no header label renderer
+     * registered for this element.
+     *
+     * Mirrors `headerLabelRenderer` from `BaseColumnConfig`. Optional on
+     * the adapter — see `createHeaderRenderer` for rationale.
+     *
+     * @since 2.15.0
+     */
+    createHeaderLabelRenderer?<TRow = unknown>(element: HTMLElement): HeaderLabelRenderer<TRow> | undefined;
     /**
      * Creates a tool panel renderer from a light DOM element.
      * The renderer receives a container element and optionally returns a cleanup function.
@@ -3766,6 +3801,62 @@ export interface GridColumnState {
     /** Array of column states. */
     columns: ColumnState[];
 }
+/**
+ * Detail for the {@link DataGridEventMap.render | `render`} event.
+ *
+ * Fired once at the end of every render cycle (the single RAF flush in the
+ * render scheduler), after all plugin `afterRender` hooks have run and after
+ * `grid.ready()` has resolved.
+ *
+ * Use this when you need to act on the rendered DOM (e.g. focus the first
+ * input of a freshly added row when `editing.mode === 'grid'`) without
+ * resorting to `setTimeout` or double-`requestAnimationFrame` hacks.
+ *
+ * @example
+ * ```typescript
+ * // Focus the first cell's input after adding a row in full-grid edit mode
+ * function addEmployee() {
+ *   grid.addRow({ id: crypto.randomUUID(), name: '', email: '' });
+ *   grid.addEventListener(
+ *     'render',
+ *     () => {
+ *       const input = grid.querySelector<HTMLInputElement>(
+ *         '[data-row="0"][data-col="0"] input',
+ *       );
+ *       input?.focus();
+ *     },
+ *     { once: true },
+ *   );
+ * }
+ * ```
+ *
+ * @category Events
+ * @since 2.15.0
+ */
+export interface RenderDetail {
+    /**
+     * The highest render phase that executed this cycle (see {@link RenderPhase}).
+     * Use this to skip cheap scroll-only renders (`phase < RenderPhase.ROWS`)
+     * if you only care about row/column model changes.
+     */
+    phase: RenderPhase;
+    /** `true` only for the very first render after the grid was connected. */
+    initial: boolean;
+    /** Number of rows in the effective row model after plugin `processRows` hooks ran. */
+    rowCount: number;
+    /**
+     * The visible virtual window — `start` inclusive, `end` exclusive — or `null`
+     * when virtualization is disabled (small datasets below the bypass threshold).
+     *
+     * When virtualization is enabled but no rows are visible (e.g. empty dataset)
+     * this is `{ start: 0, end: 0 }`, NOT `null` — that lets consumers distinguish
+     * "virtualization disabled" from "enabled but currently empty".
+     */
+    visibleRange: {
+        start: number;
+        end: number;
+    } | null;
+}
 /**
  * Detail for a cell click event.
  * Provides full context about the clicked cell including row data.
@@ -4313,6 +4404,40 @@ export interface DataGridEventMap<TRow = unknown> {
      * @group Core Events
      */
     'column-state-change': GridColumnState;
+    /**
+     * Fired once at the end of every render cycle, after all plugin
+     * `afterRender` hooks have run and `ready()` has resolved.
+     *
+     * This is the canonical post-render hook for consumers. Use it instead of
+     * `setTimeout` / double-`requestAnimationFrame` to act on the rendered DOM
+     * after a programmatic mutation.
+     *
+     * Note: `ready()` only resolves once (after the first render). The `render`
+     * event fires on every flush — including scroll-driven virtual-window
+     * updates — so prefer `{ once: true }` (or check `detail.phase`) when you
+     * want to act on a specific mutation.
+     *
+     * @example
+     * ```typescript
+     * // Focus the first cell's input after addRow in full-grid edit mode
+     * grid.addRow({ id: crypto.randomUUID(), name: '', email: '' });
+     * grid.addEventListener(
+     *   'render',
+     *   () => {
+     *     const input = grid.querySelector<HTMLInputElement>(
+     *       '[data-row="0"][data-col="0"] input',
+     *     );
+     *     input?.focus();
+     *   },
+     *   { once: true },
+     * );
+     * ```
+     *
+     * @see {@link RenderDetail}
+     * @group Core Events
+     * @since 2.15.0
+     */
+    render: RenderDetail;
 }
 /**
  * Extracts the event detail type for a given event name.