@toolbox-web/grid 2.11.0 → 2.12.0

package/lib/core/grid.d.ts

@@ -566,7 +566,7 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
     /** @internal Run grid setup (DOM rebuild). */
     _setup(): void;
     /** @internal Apply animation configuration to host element. */
-    _applyAnimationConfig(config: GridConfig<T>): void;
+    _applyAnimationConfig(gridConfig: GridConfig<T>): void;
     /**
      * Find the header row element.
      * Used by plugins that need to access header cells for styling or measurement.

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

@@ -0,0 +1,66 @@
+import { EmptyContext, EmptyOverlay, EmptyRenderer, GridConfig } from '../types';
+/** Default messages used when no `emptyRenderer` is configured. */
+export declare const DEFAULT_EMPTY_MESSAGE = "No data to display";
+export declare const DEFAULT_FILTERED_OUT_MESSAGE = "No matching rows";
+/**
+ * Default empty-state renderer.
+ * Produces a non-interactive `<div>` carrying a translatable message.
+ */
+export declare function defaultEmptyRenderer(ctx: EmptyContext): HTMLElement;
+/**
+ * Create the rendered content for the empty overlay.
+ * If a custom renderer is provided, use it; otherwise fall back to the default
+ * message. Strings returned by user renderers are sanitized through
+ * `sanitizeHTML()` before being assigned to `innerHTML` — mirroring the cell
+ * render path — so consumers can safely embed values from API responses
+ * (e.g. `Failed to load deals: ${error.message}`) without opening an XSS sink.
+ */
+export declare function createEmptyContent(ctx: EmptyContext, renderer?: EmptyRenderer): HTMLElement;
+/**
+ * Create the empty-state overlay element.
+ * Always carries `role="status"` + `aria-live="polite"` so screen readers
+ * announce the state on transition; the `data-overlay-target` attribute is
+ * informational only. CSS positions absolutely against the closest positioned
+ * ancestor — `.tbw-grid-root` is positioned by `base.css`, and `.rows-container`
+ * is given `position: relative` for `target='rows'` for the same reason.
+ */
+export declare function createEmptyOverlay(ctx: EmptyContext, renderer?: EmptyRenderer, target?: EmptyOverlay): HTMLElement;
+/**
+ * Mount the overlay into the chosen target element.
+ * Caller resolves the actual element (`.rows-container` for `'rows'`, the
+ * `.tbw-grid-root` for `'grid'`).
+ */
+export declare function showEmptyOverlay(target: Element, overlayEl: HTMLElement): void;
+/** Detach the overlay from the DOM. */
+export declare function hideEmptyOverlay(overlayEl: HTMLElement | undefined): void;
+/**
+ * Decide whether the empty overlay should be visible.
+ * The overlay is shown only when:
+ *  - the grid is not currently in a loading state (loading takes precedence);
+ *  - the rendered row count is zero (after all plugin processing);
+ *  - the renderer has not been explicitly disabled by setting it to `null`.
+ */
+export declare function shouldShowEmpty(loading: boolean, renderedRowCount: number, renderer: GridConfig['emptyRenderer'] | undefined): boolean;
+/**
+ * Per-grid mutable state cached between overlay updates so the hot path
+ * (`_schedulerAfterRender` fires on every render phase, including
+ * VIRTUALIZATION during scroll) can skip the recreate when nothing observable
+ * has changed. Without this guard we'd churn DOM and could leak
+ * framework-adapter portals returned from user renderers.
+ */
+export interface EmptyOverlayState {
+    el?: HTMLElement;
+    renderer?: GridConfig['emptyRenderer'];
+    target?: EmptyOverlay;
+    sourceRowCount?: number;
+    filteredOut?: boolean;
+}
+/**
+ * Compute, mount, or tear down the empty-state overlay in a single call.
+ * Encapsulates show/hide decision, change detection, mount-point resolution,
+ * and the `filteredOut` derivation so the grid host can stay a one-liner.
+ *
+ * The `state` object is mutated in place — callers store a single reference
+ * and pass it back on every tick.
+ */
+export declare function updateEmptyOverlay(gridRoot: Element | null, loading: boolean, renderedRowCount: number, sourceRowCount: number, renderer: GridConfig['emptyRenderer'] | undefined, target: EmptyOverlay, state: EmptyOverlayState): void;

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

@@ -24,7 +24,8 @@
  * 6. Shell (toolbar, layout)
  * 7. Tool Panel (side panels, accordion)
  * 8. Loading (spinners, overlays)
- * 9. Animations (keyframes, transitions)
- * 10. Media Queries (accessibility, responsive)
+ * 9. Empty state (no-rows overlay)
+ * 10. Animations (keyframes, transitions)
+ * 11. Media Queries (accessibility, responsive)
  */
 export declare const gridStyles: string;

package/lib/core/types.d.ts

@@ -2652,7 +2652,92 @@ export interface GridConfig<TRow = any> {
      * ```
      */
     loadingRenderer?: LoadingRenderer;
+    /**
+     * Custom renderer shown when the grid has no rows to display
+     * (`loading === false` AND the rendered row count is `0`, after all plugin
+     * processing such as filtering / grouping / server-side).
+     *
+     * - When **omitted**, a built-in message is rendered ("No data to display"
+     *   or "No matching rows" when source rows existed but were filtered out).
+     * - When set to a function, the function receives an {@link EmptyContext}
+     *   and returns an `HTMLElement` or HTML string.
+     * - When **explicitly `null`**, the empty overlay is suppressed entirely.
+     *
+     * The empty overlay is mutually exclusive with the loading overlay; if
+     * `loading === true`, the loading overlay always wins.
+     *
+     * @example
+     * ```typescript
+     * // Show a backend error message via a closure over the consumer's state.
+     * gridConfig.emptyRenderer = () =>
+     *   error
+     *     ? `Failed to load deals: ${error.message}`
+     *     : 'No deals to display';
+     * ```
+     *
+     * @see {@link EmptyOverlay} to control where the overlay is mounted.
+     * @since 2.12.0
+     */
+    emptyRenderer?: EmptyRenderer | null;
+    /**
+     * Where the empty-state overlay is mounted.
+     *
+     * - `'rows'` (default) — overlays the `.rows-container`. Headers stay
+     *   visible so users can clear filters or see the column schema.
+     * - `'grid'` — overlays the `.tbw-grid-root`. Hides headers and any
+     *   shell/toolbar content too.
+     *
+     * @defaultValue `'rows'`
+     * @since 2.12.0
+     */
+    emptyOverlay?: EmptyOverlay;
+}
+/**
+ * Where the empty-state overlay is mounted.
+ *
+ * @see {@link GridConfig.emptyOverlay}
+ * @since 2.12.0
+ */
+export type EmptyOverlay = 'rows' | 'grid';
+/**
+ * Context passed to a custom {@link EmptyRenderer}.
+ *
+ * @since 2.12.0
+ */
+export interface EmptyContext {
+    /**
+     * Number of rows in the source data before any plugin processing
+     * (sort / filter / group / server-side). Equivalent to
+     * `grid.sourceRows.length`.
+     */
+    sourceRowCount: number;
+    /**
+     * `true` when the source had rows but all of them were filtered out
+     * (i.e. `sourceRowCount > 0` while the rendered row count is `0`).
+     * The default renderer uses this flag to switch between
+     * "No data to display" and "No matching rows".
+     */
+    filteredOut: boolean;
 }
+/**
+ * Custom renderer for the empty state overlay.
+ *
+ * @param context - {@link EmptyContext} describing why the grid is empty.
+ * @returns An `HTMLElement` or an HTML string.
+ *
+ * @example
+ * ```typescript
+ * const renderer: EmptyRenderer = (ctx) => {
+ *   const div = document.createElement('div');
+ *   div.textContent = ctx.filteredOut ? 'No matches' : 'No data';
+ *   return div;
+ * };
+ * ```
+ *
+ * @see {@link GridConfig.emptyRenderer}
+ * @since 2.12.0
+ */
+export type EmptyRenderer = (context: EmptyContext) => HTMLElement | string;
 /**
  * Sort state passed to custom sort handlers.
  * Represents the current sorting configuration for a column.