npm - @toolbox-web/grid - Versions diffs - 2.12.0 → 2.13.0 - Mend

@toolbox-web/grid 2.12.0 → 2.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (63) hide show

package/all.js +2 -2
package/all.js.map +1 -1
package/custom-elements.json +20 -1
package/index.js +1 -1
package/index.js.map +1 -1
package/lib/core/grid.d.ts +23 -1
package/lib/core/internal/empty.d.ts +9 -2
package/lib/core/internal/focus-manager.d.ts +17 -0
package/lib/core/internal/shell.d.ts +1 -1
package/lib/core/internal/virtualization.d.ts +103 -1
package/lib/core/types.d.ts +18 -7
package/lib/features/pinned-columns.js.map +1 -1
package/lib/plugins/clipboard/index.js.map +1 -1
package/lib/plugins/column-virtualization/index.js.map +1 -1
package/lib/plugins/context-menu/index.js.map +1 -1
package/lib/plugins/editing/EditingPlugin.d.ts +1 -1
package/lib/plugins/editing/index.js +1 -1
package/lib/plugins/editing/index.js.map +1 -1
package/lib/plugins/editing/types.d.ts +9 -1
package/lib/plugins/export/index.js.map +1 -1
package/lib/plugins/filtering/index.js +1 -1
package/lib/plugins/filtering/index.js.map +1 -1
package/lib/plugins/grouping-columns/index.js.map +1 -1
package/lib/plugins/grouping-rows/index.js.map +1 -1
package/lib/plugins/master-detail/index.js.map +1 -1
package/lib/plugins/multi-sort/index.js.map +1 -1
package/lib/plugins/pinned-columns/index.js +1 -1
package/lib/plugins/pinned-columns/index.js.map +1 -1
package/lib/plugins/pinned-rows/index.js.map +1 -1
package/lib/plugins/pivot/index.js.map +1 -1
package/lib/plugins/print/index.js.map +1 -1
package/lib/plugins/reorder-columns/index.js +1 -1
package/lib/plugins/reorder-columns/index.js.map +1 -1
package/lib/plugins/reorder-rows/index.js +1 -1
package/lib/plugins/reorder-rows/index.js.map +1 -1
package/lib/plugins/responsive/index.js +1 -1
package/lib/plugins/responsive/index.js.map +1 -1
package/lib/plugins/row-drag-drop/RowDragDropPlugin.d.ts +1 -1
package/lib/plugins/row-drag-drop/index.js +1 -1
package/lib/plugins/row-drag-drop/index.js.map +1 -1
package/lib/plugins/selection/SelectionPlugin.d.ts +1 -1
package/lib/plugins/selection/index.d.ts +1 -1
package/lib/plugins/selection/index.js.map +1 -1
package/lib/plugins/server-side/ServerSidePlugin.d.ts +1 -1
package/lib/plugins/server-side/index.js.map +1 -1
package/lib/plugins/sticky-rows/index.js.map +1 -1
package/lib/plugins/tooltip/index.js.map +1 -1
package/lib/plugins/tree/index.js.map +1 -1
package/lib/plugins/undo-redo/index.js.map +1 -1
package/lib/plugins/visibility/index.js.map +1 -1
package/package.json +1 -1
package/public.d.ts +9 -0
package/umd/grid.all.umd.js +1 -1
package/umd/grid.all.umd.js.map +1 -1
package/umd/grid.umd.js +1 -1
package/umd/grid.umd.js.map +1 -1
package/umd/plugins/editing.umd.js.map +1 -1
package/umd/plugins/pinned-columns.umd.js +1 -1
package/umd/plugins/pinned-columns.umd.js.map +1 -1
package/umd/plugins/reorder-rows.umd.js.map +1 -1
package/umd/plugins/row-drag-drop.umd.js.map +1 -1
package/umd/plugins/selection.umd.js.map +1 -1
package/umd/plugins/server-side.umd.js.map +1 -1

package/lib/core/grid.d.ts CHANGED Viewed

@@ -333,7 +333,7 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * const editing = grid.getPluginByName('editing');
      * ```
      *
-     * @param name - The plugin name (matches {@link BaseGridPlugin.name}).
+     * @param name - The plugin name (matches `BaseGridPlugin.name`).
      * @returns The plugin instance, or `undefined` if not registered.
      * @group Plugin Communication
      */
@@ -1728,6 +1728,28 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * ```
      */
     containsFocus(node?: Node | null): boolean;
+    /**
+     * The last meaningful element inside the grid host's light-DOM subtree
+     * that received user focus. Excludes the grid host itself (synthetic
+     * `tabindex=0` focus during keyboard navigation), bare `.cell` elements
+     * (whose focus is virtual), and descendants of registered external focus
+     * containers (overlays/datepickers/dropdowns). Returns `null` when the
+     * user has not yet interacted with any tracked descendant.
+     *
+     * @group Focus Management
+     */
+    get lastFocusedElement(): HTMLElement | null;
+    /**
+     * Restore focus to the last meaningful user-focused element inside the
+     * grid (see {@link lastFocusedElement} for what counts as "meaningful").
+     * The grid invokes this automatically whenever focus is bounced to
+     * `<body>` (e.g. when a body-level overlay is removed). Exposed publicly
+     * so application code can re-anchor focus on demand.
+     *
+     * @group Focus Management
+     * @returns `true` if a tracked element existed and was refocused; `false` otherwise.
+     */
+    restoreLastFocus(): boolean;
     /**
      * Re-parse light DOM column elements and refresh the grid.
      * Call this after framework adapters have registered their templates.

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

@@ -47,12 +47,19 @@ export declare function shouldShowEmpty(loading: boolean, renderedRowCount: numb
  * 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.
+ *
+ * `sourceRows` is the array reference (not just its length): reassigning
+ * `grid.rows` produces a new reference and busts the cache, even when the
+ * length is unchanged (e.g. `grid.rows = []` after a previous `grid.rows = []`).
+ * That is the user's explicit "something changed" signal, and it lets custom
+ * renderers that close over external state (e.g. an `errorMessage` variable)
+ * re-render without forcing them to mint a new renderer function.
  */
 export interface EmptyOverlayState {
     el?: HTMLElement;
     renderer?: GridConfig['emptyRenderer'];
     target?: EmptyOverlay;
-    sourceRowCount?: number;
+    sourceRows?: readonly unknown[];
     filteredOut?: boolean;
 }
 /**
@@ -63,4 +70,4 @@ export interface EmptyOverlayState {
  * 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;
+export declare function updateEmptyOverlay(gridRoot: Element | null, loading: boolean, renderedRowCount: number, sourceRows: readonly unknown[], renderer: GridConfig['emptyRenderer'] | undefined, target: EmptyOverlay, state: EmptyOverlayState): void;

package/lib/core/internal/focus-manager.d.ts CHANGED Viewed

@@ -41,6 +41,23 @@ export declare class FocusManager<T = any> {
      * Check whether a node is inside any registered external focus container.
      */
     isInExternalFocusContainer(node: Node): boolean;
+    /**
+     * Restore focus to the last tracked user-focused element if it is still
+     * connected and focusable. Returns `true` on success.
+     *
+     * Stale references (element removed from DOM during a re-render) are
+     * silently dropped so callers can fall back to their own restoration logic.
+     */
+    restoreLastFocus(): boolean;
+    /**
+     * Currently tracked last-user-focused element inside the grid host's
+     * light-DOM subtree, if any. Excludes the grid host itself, bare `.cell`
+     * elements, and descendants of registered external focus containers.
+     * Exposed so plugins (notably EditingPlugin) can defer to the unified
+     * trap before falling back to plugin-specific restoration logic.
+     * @internal
+     */
+    get lastFocusedElement(): HTMLElement | null;
     /**
      * Clean up all external focus container listeners.
      * Called when the grid disconnects.

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

@@ -204,7 +204,7 @@ export declare function renderHeaderContent(renderRoot: Element, state: ShellSta
  * Render content for expanded accordion sections.
  * @param icons - Optional icons for expand/collapse chevrons (from grid config)
  */
-export declare function renderPanelContent(renderRoot: Element, state: ShellState, icons?: {
+export declare function renderPanelContent(renderRoot: Element, state: ShellState, _icons?: {
     expand?: IconValue;
     collapse?: IconValue;
 }): void;

package/lib/core/internal/virtualization.d.ts CHANGED Viewed

@@ -173,6 +173,84 @@ export declare function computeAverageExcludingPluginRows<T>(cache: RowPosition[
     measuredCount: number;
     averageHeight: number;
 };
+/**
+ * Maximum spacer element height (px) before browsers cap the rendered height.
+ *
+ * Chromium's hard cap is `2^25 = 33,554,432` px; Firefox/Safari are similar or larger.
+ * We pick `33,500,000` — ~54 KB of headroom under Chromium's cap so that floating-point
+ * drift in the fractional mapping math (`scrollTop * rMax / sMax`) cannot push a computed
+ * spacer position past the engine cap and silently truncate.
+ *
+ * For datasets where `totalRows * rowHeight` exceeds this value, the faux-vscroll
+ * spacer would silently truncate, making the tail of the dataset unreachable via
+ * the native scrollbar / `Ctrl+End`. The grid switches to fractional scroll mapping
+ * above this threshold — see {@link computeScrollMapping}.
+ *
+ * @category Plugin Development
+ * @since 2.13.0
+ */
+export declare const MAX_ELEMENT_HEIGHT_PX = 33500000;
+/**
+ * Mapping between native `scrollTop` (clamped spacer space) and "virtual" scroll
+ * position (raw row-content space). See {@link computeScrollMapping}.
+ *
+ * @category Plugin Development
+ * @since 2.13.0
+ */
+export interface ScrollMapping {
+    /** Raw row-content height in pixels (totalRows * rowHeight or sum of variable heights). */
+    rawContentHeight: number;
+    /** Effective spacer DOM height — `min(rawContentHeight, maxSpacerHeight)`. */
+    spacerHeight: number;
+    /** Viewport height used for computing scrollable extents. */
+    viewportHeight: number;
+    /** True when `rawContentHeight > maxSpacerHeight` — fractional mapping is active. */
+    capped: boolean;
+}
+/**
+ * Compute a mapping between the spacer's native scrollTop and the virtual
+ * row-content scroll offset.
+ *
+ * For datasets within `maxSpacerHeight`, mapping is identity (no transform).
+ * Above the cap, the spacer is clamped and `scrollTop` units no longer equal
+ * row-content units — call {@link toVirtualScrollTop} / {@link fromVirtualScrollTop}
+ * to translate between the two coordinate spaces.
+ *
+ * @category Plugin Development
+ * @since 2.13.0
+ */
+export declare function computeScrollMapping(rawContentHeight: number, viewportHeight: number, maxSpacerHeight?: number): ScrollMapping;
+/**
+ * Translate a native `scrollTop` (spacer space) into a virtual scroll offset
+ * in raw row-content space. Identity when the mapping is not capped.
+ *
+ * The result is clamped to `[0, rawContentHeight - viewportHeight]` so callers
+ * never index past the dataset, even when the spacer's actual scrollable extent
+ * slightly exceeds `spacerHeight - viewportHeight` (e.g. when a horizontal scrollbar
+ * adds bottom padding to the faux spacer).
+ *
+ * @category Plugin Development
+ * @since 2.13.0
+ */
+export declare function toVirtualScrollTop(scrollTop: number, mapping: ScrollMapping): number;
+/**
+ * Translate a virtual scroll offset (raw row-content space) into a native
+ * `scrollTop` value (spacer space). Identity when the mapping is not capped.
+ *
+ * @category Plugin Development
+ * @since 2.13.0
+ */
+export declare function fromVirtualScrollTop(virtualTop: number, mapping: ScrollMapping): number;
+/**
+ * Identity scroll mapping (no cap applied). Useful as a default in places that
+ * don't yet know the dataset extents. `viewportHeight` is `0` until the first
+ * `calculateTotalSpacerHeight` call populates the real extents — safe because
+ * `capped: false` short-circuits both translation helpers before they read it.
+ *
+ * @category Plugin Development
+ * @since 2.13.0
+ */
+export declare function createIdentityScrollMapping(): ScrollMapping;
 /**
  * Result of computing a virtual window for fixed-height rows.
  * Used by plugins like FilteringPlugin for virtualized dropdowns.
@@ -184,8 +262,19 @@ export interface VirtualWindow {
     end: number;
     /** Pixel offset to apply to the rows container (translateY) */
     offsetY: number;
-    /** Total height of the scrollable content */
+    /**
+     * Effective spacer DOM height — use this for the scrollable spacer element.
+     * Equal to `min(totalRows * rowHeight, maxSpacerHeight)`. Above the cap this
+     * is clamped; use {@link VirtualWindow.rawContentHeight} for the un-clamped value.
+     */
     totalHeight: number;
+    /**
+     * Raw, un-clamped row-content height (`totalRows * rowHeight`). Equal to
+     * `totalHeight` when the dataset is below `maxSpacerHeight`.
+     *
+     * @since 2.13.0
+     */
+    rawContentHeight: number;
 }
 /** Parameters for computing the virtual window */
 export interface VirtualWindowParams {
@@ -199,11 +288,24 @@ export interface VirtualWindowParams {
     rowHeight: number;
     /** Number of extra rows to render above/below viewport */
     overscan: number;
+    /**
+     * Optional cap on the spacer's DOM height. When `totalRows * rowHeight` exceeds
+     * this value, `scrollTop` is treated as a spacer-space position and translated
+     * to virtual row-content space via fractional mapping. Defaults to {@link MAX_ELEMENT_HEIGHT_PX}.
+     * Pass `Infinity` to disable.
+     *
+     * @since 2.13.0
+     */
+    maxSpacerHeight?: number;
 }
 /**
  * Compute the virtual row window based on scroll position and viewport.
  * Simple fixed-height implementation for plugins needing basic virtualization.
  *
+ * For datasets where `totalRows * rowHeight > maxSpacerHeight`, scroll position
+ * is mapped fractionally so the entire dataset stays reachable past the browser's
+ * single-element height cap (Chromium ~33.5M px). See {@link computeScrollMapping}.
+ *
  * @param params - Parameters for computing the window
  * @returns VirtualWindow with start/end indices and transforms
  */

package/lib/core/types.d.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 import { RenderPhase } from './internal/render-scheduler';
 import { ShellState } from './internal/shell';
-import { RowPosition } from './internal/virtualization';
+import { RowPosition, ScrollMapping } from './internal/virtualization';
 import { AfterCellRenderContext, AfterRowRenderContext, CellMouseEvent } from './plugin/types';
 /**
  * Position entry for a single row in the position cache.
@@ -1887,6 +1887,17 @@ export interface VirtualState {
     cachedScrollAreaHeight: number;
     /** Cached reference to .tbw-scroll-area element. Set during scroll listener setup. */
     scrollAreaEl: HTMLElement | null;
+    /**
+     * Active scroll mapping between native `scrollTop` (clamped spacer space) and
+     * "virtual" row-content space. Identity (`capped: false`) for datasets within
+     * the browser's max-element-height cap (Chromium ~33.5M px). For larger datasets,
+     * the spacer height is clamped and `scrollTop` must be translated via this
+     * mapping before computing the visible window. Updated by `calculateTotalSpacerHeight`.
+     *
+     * @see {@link computeScrollMapping}
+     * @since 2.13.0
+     */
+    scrollMapping: ScrollMapping;
 }
 /**
  * Union type for input-like elements that have a `value` property.
@@ -2438,7 +2449,7 @@ export interface GridConfig<TRow = any> {
      * instead. It is honored by every sort code path in the grid (core, multi-sort,
      * tree, server-side) and is composable across columns.
      *
-     * For server-side sort, prefer {@link ServerSideConfig.dataSource} — the
+     * For server-side sort, prefer `ServerSideConfig.dataSource` — the
      * `sortModel` is shipped to your `getRows` handler so the backend can return
      * pre-sorted blocks.
      * :::
@@ -2461,7 +2472,7 @@ export interface GridConfig<TRow = any> {
      * ```
      *
      * @see {@link BaseColumnConfig.sortComparator} — recommended per-column override
-     * @see {@link ServerSideConfig.dataSource} — recommended server-side sort path
+     * @see `ServerSideConfig.dataSource` — recommended server-side sort path
      */
     sortHandler?: SortHandler<TRow>;
     /**
@@ -2477,8 +2488,8 @@ export interface GridConfig<TRow = any> {
      * };
      * ```
      *
-     * @see {@link DataGrid.sort} for runtime sorting
-     * @see {@link DataGrid.sortModel} for reading current sort state
+     * @see {@link DataGridElement.sort} for runtime sorting
+     * @see {@link DataGridElement.sortModel} for reading current sort state
      */
     initialSort?: {
         field: string;
@@ -2776,7 +2787,7 @@ export interface SortState {
  * active sort field. For per-column custom sort logic that survives every
  * sort code path (core, multi-sort, tree, server-side), set `sortComparator`
  * on the relevant columns instead. For server-side sort, use
- * {@link ServerSideConfig.dataSource}.
+ * `ServerSideConfig.dataSource`.
  * :::
  *
  * Use `SortHandler` only when you need to replace the grid's sort engine
@@ -3405,7 +3416,7 @@ export interface ShellHeaderConfig {
      *
      * 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
+     * to call {@link DataGridElement.toggleToolPanel} (or `toggleToolPanelSection(id)` for
      * a specific section). All tool panels remain functional; only the
      * built-in toggle button and adjacent separator are suppressed.
      *

package/lib/features/pinned-columns.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"pinned-columns.js","sources":["../../../../../libs/grid/src/lib/features/pinned-columns.ts"],"sourcesContent":["/*\n Pinned Columns feature for @toolbox-web/grid\n \n @example\n * ```typescript\n * import '@toolbox-web/grid/features/pinned-columns';\n \n grid.gridConfig = { features: { pinnedColumns: true } };\n * ```\n /\n\nimport { PinnedColumnsPlugin } from '../plugins/pinned-columns';\nimport { registerFeature } from './registry';\n\ndeclare module '../core/types' {\n interface FeatureConfig {\n /* Enable column pinning (left/right). /\n pinnedColumns?: boolean;\n }\n}\n\nregisterFeature('pinnedColumns', (~~config~~) => {\n return new PinnedColumnsPlugin();\n});\n\n/* @internal Type anchor — forces bundlers to preserve this module's FeatureConfig augmentation when re-exported. */\nexport type _Augmentation = true;\n"],"names":["registerFeature","~~config~~","PinnedColumnsPlugin"],"mappings":"qJAqBAA,EAAgB,gBAAkBC,GACzB,IAAIC"}
1	+ {"version":3,"file":"pinned-columns.js","sources":["../../../../../libs/grid/src/lib/features/pinned-columns.ts"],"sourcesContent":["/*\n Pinned Columns feature for @toolbox-web/grid\n \n @example\n * ```typescript\n * import '@toolbox-web/grid/features/pinned-columns';\n \n grid.gridConfig = { features: { pinnedColumns: true } };\n * ```\n /\n\nimport { PinnedColumnsPlugin } from '../plugins/pinned-columns';\nimport { registerFeature } from './registry';\n\ndeclare module '../core/types' {\n interface FeatureConfig {\n /* Enable column pinning (left/right). /\n pinnedColumns?: boolean;\n }\n}\n\nregisterFeature('pinnedColumns', (_config) => {\n return new PinnedColumnsPlugin();\n});\n\n/* @internal Type anchor — forces bundlers to preserve this module's FeatureConfig augmentation when re-exported. */\nexport type _Augmentation = true;\n"],"names":["registerFeature","_config","PinnedColumnsPlugin"],"mappings":"qJAqBAA,EAAgB,gBAAkBC,GACzB,IAAIC"}