@reforgium/data-grid 2.1.1 → 2.2.0

package/README.md

@@ -18,7 +18,7 @@ Designed for **real-world datasets**, not demo tables.
 - Virtual row rendering (smooth, no jumps)
 - Infinity scroll (loads data when reaching the bottom)
 - Jitter-free fixed (sticky) columns
-- Two-line headers max, with ellipsis and tooltip
+- Two-line text clamp (header + body) with ellipsis
 - Declarative column DSL (`<re-dg-column>`) *[NEW in 2.0.0]*
 - Column expanders (hidden columns via toggler)
 - Scrollable overlay scrollbar
@@ -61,12 +61,6 @@ export class SomeComponent {
 ```
 ---
 
-## Migration notes (1.1.0 -> 2.0.0)
-
-- **Column tooltips are now explicit.** Use `tooltip` on a column (string / function / `TemplateRef`) to show a popover on hover.
-- **New column manager entrypoint.** Import it from `@reforgium/data-grid/column-manager` and wire `columns` + `columnsChange`.
-- **Sticky columns use sides.** Prefer `sticky="left"` / `sticky="right"`; legacy `true` still maps to left.
-
 ## Configuration
 
 ### Global defaults provider
@@ -115,8 +109,9 @@ Supported default fields:
 | headerGroups       | `GridHeaderGroup<T>[]`                           | `[]`               | Optional top header row groups (`from`..`to`) for 2-level headers                               | *[NEW in 2.0.0]* |
 | pinnedRows         | `GridPinnedRow<T>[]`                             | `[]`               | Top / bottom pinned rows                                                                        |                  |
 | isRowSticky        | `(row: T, index: number) => boolean`             | `undefined`        | Predicate that marks rows as sticky at the top                                                  |                  |
+| isRowDisabled      | `(row: T, index: number) => boolean`             | `undefined`        | Predicate that marks rows as disabled (no select/click/context/double-click interactions)       |                  |
 | getRowTemplate     | `(row: T, index: number) => TemplateRef \| null` | `undefined`        | Optional resolver for custom row template                                                       |                  |
-| mode               | `'none' \| 'pagination' \| 'infinity'`           | `'pagination'`     | Grid operation mode                                                                             |                  |
+| sortMode           | 'single' \| 'multi'                              | 'single'           | Sorting mode for header clicks                                                                  |                  |
 | pageSize           | `number`                                         | `20`               | Number of items per page (pagination/infinity modes)                                            |                  |
 | pageStartFromZero  | `boolean`                                        | `true`             | If true, page indexing starts from 0, otherwise from 1                                          |                  |
 | hasIndexColumn     | `boolean`                                        | `false`            | If true, an index column will be shown                                                          |                  |
@@ -135,6 +130,13 @@ Supported default fields:
 
 When selection mode is `'single'` or `'multi'`, provide a `key` (data property) and optionally `defaultSelected`.
 
+Feature lazy-loading behavior (runtime `import()`):
+
+- Selection feature is loaded when `selection.mode !== 'none'`.
+- Sticky feature is loaded when `isRowSticky` is provided.
+- Tooltip feature is loaded when at least one column has `tooltip`.
+- Overlay-scroll feature is loaded on first scroll lifecycle usage.
+
 Loading behavior:
 
 - `loadingMode="spinner"`: shows centered spinner over grid content.
@@ -179,7 +181,8 @@ Row templates:
 | rowClick        | `GridRowClickEvent<T>`        | Emitted when a row is clicked (includes native event)  | *[UPD in 2.0.0]* |
 | rowContext      | `GridRowContextEvent<T>`      | Emitted on row context menu                            | *[NEW in 2.0.0]* |
 | rowDoubleClick  | `GridRowDoubleClickEvent<T>`  | Emitted when a row is double-clicked                   | *[NEW in 2.0.0]* |
-| sortChange      | `GridSortEvent<T>`            | Emitted when sort order changes                        |                  |
+| sortChange      | `GridSortEvent<T>`            | Emitted when single-sort order changes                 |                  |
+| multiSortChange | `GridMultiSortEvent<T>`       | Emitted when multi-sort order changes                  | *[NEW in 2.2.0]* |
 | pageChange      | `GridPageChangeEvent`         | Emitted when requesting data for a new page            |                  |
 | selectChange    | `GridSelectEvent<T>`          | Emitted when selected rows change                      |                  |
 
@@ -187,6 +190,16 @@ Notes:
 
 - A cell click also triggers the row click event (bubbling), so listen to one or stop propagation if needed.
 
+### Public API methods
+
+`DataGrid` exposes imperative helpers via component instance (e.g. `@ViewChild(DataGrid)`):
+
+- `clearSelection()` - clears current selection and emits `selectChange`
+- `selectAllLoaded()` - selects currently loaded rows (multi mode) and emits `selectChange`
+- `resetSort()` - resets sort state and emits sort events
+- `setSort(event)` - applies single-sort state and emits sort events
+- `setMultiSort(items)` - applies multi-sort state and emits sort events
+
 ### GridColumn<T> reference
 
 `columns` accepts `GridColumn<T>[]`, where `GridColumn<T>` is a union of three column variants:
@@ -197,15 +210,15 @@ Notes:
 
 Common (base) fields:
 
-| Field                   | Type                                                                | Description                                                                     |
-|-------------------------|---------------------------------------------------------------------|---------------------------------------------------------------------------------|
-| `sortKey`               | `string`                                                            | Alternative key used for sorting when display `key` differs from sortable data. |
-| `sticky`                | `'left' \| 'right' \| true`                                         | Keeps the column fixed while horizontally scrolling. `true` pins to the left.   |
-| `expandBy`              | `DataKey<T>`                                                        | Data key that controls expand/collapse behavior for the column.                 |
-| `flex`                  | `number`                                                            | Flex grow factor for width distribution in flexible layouts.                    |
-| `minWidth` / `maxWidth` | `number`                                                            | Column width limits in pixels.                                                  |
-| `cellClass`             | `string \| ((row: T) => string)`                                    | Static CSS class or resolver per row.                                           |
-| `tooltip`               | `string \| ((row: T) => string) \| TemplateRef<GridTooltipContext>` | Popover tooltip content shown on cell hover.                                    |
+| Field                   | Type                                                                        | Description                                                                            |                  |
+|-------------------------|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------|
+| `sortKey`               | `string`                                                                    | Alternative key used for sorting when display `key` differs from sortable data.        |                  |
+| `sticky`                | `'left' \| 'right' \| true`                                                 | Keeps the column fixed while horizontally scrolling. `true` pins to the left.          |                  |
+| `expandBy`              | `DataKey<T>`                                                                | Data key that controls expand/collapse behavior for the column.                        |                  |
+| `flex`                  | `number`                                                                    | Flex grow factor for width distribution in flexible layouts.                           |                  |
+| `minWidth` / `maxWidth` | `number`                                                                    | Column width limits in pixels.                                                         |                  |
+| `cellClass`             | `string \| ((row: T) => string)`                                            | Static CSS class or resolver per row.                                                  |                  |
+| `tooltip`               | `true \| string \| ((row: T) => string) \| TemplateRef<GridTooltipContext>` | Popover tooltip content shown on cell hover. `true` uses the cell value automatically. | *[NEW in 2.2.0]* |
 
 Renderer-specific fields:
 
@@ -215,6 +228,11 @@ Renderer-specific fields:
 | Value renderer    | `value: (row: T) => string \| number`, `track: (row: T) => string`                                        | `track` is required for stable row identity and efficient updates.                                    |
 | Template renderer | `renderTemplate: TemplateRef<...>`, `track: (row: T) => string`                                           | `track` is required when rendering through Angular templates.                                         |
 
+Cell text wrapping/clamp behavior:
+
+- Default header text and default body renderers (`plain`, `date`, `number`, `index`) are limited to 2 lines with ellipsis.
+- Template-based renderers (`renderTemplate`, `reDataGridCell`, `reDataGridTypeCell`, etc.) are not clamped by default and are fully controlled by your template styles.
+
 ### Declarative columns *[NEW in 2.0.0]*
 
 You can define columns directly in markup via `<re-dg-column>`, then the grid will normalize them to `GridColumn<T>` internally.
@@ -254,6 +272,7 @@ Notes:
 
 ```ts
 columns = [
+  { key: 'name', header: 'Name', tooltip: true }, // auto tooltip from cell value
   { key: 'email', header: 'Email', tooltip: (row) => row.email },
   { key: 'status', header: 'Status', tooltip: 'User status' },
 ];
@@ -362,14 +381,14 @@ Scrollbar:
 
 Header:
 
-- `--re-data-grid-header-rounded` - header corner radius (`var(--re-data-grid-rounded)`)
-- `--re-data-grid-header-surface` - header area background (`#fff`)
-- `--re-data-grid-header-body-gap` - gap between header and body (`0px`)
-- `--re-data-grid-header-row-height` - main header row height (`40px`)
-- `--re-data-grid-header-row-separator-color` - main header separator color (`#ccc`)
-- `--re-data-grid-header-row-separator` - main header separator (`1px solid var(--re-data-grid-header-row-separator-color)`)
-- `--re-data-grid-header-group-row-height` - group header row height (`var(--re-data-grid-header-row-height)`)
-- `--re-data-grid-header-group-row-separator-color` - group header separator color (`var(--re-data-grid-header-row-separator-color)`)
+- `--re-data-grid-header-rounded` - header corner radius (`var(--re-data-grid-rounded)`)
+- `--re-data-grid-header-surface` - header area background (`#fff`)
+- `--re-data-grid-header-body-gap` - gap between header and body (`0px`)
+- `--re-data-grid-header-row-height` - main header row height (`40px`)
+- `--re-data-grid-header-row-separator-color` - main header separator color (`#ccc`)
+- `--re-data-grid-header-row-separator` - main header separator (`1px solid var(--re-data-grid-header-row-separator-color)`)
+- `--re-data-grid-header-group-row-height` - group header row height (`var(--re-data-grid-header-row-height)`)
+- `--re-data-grid-header-group-row-separator-color` - group header separator color (`var(--re-data-grid-header-row-separator-color)`)
 - `--re-data-grid-header-group-row-separator` - group header separator (`1px solid var(--re-data-grid-header-group-row-separator-color)`)
 
 Header Cells:
@@ -378,6 +397,8 @@ Header Cells:
 - `--re-data-grid-header-cell-font-size` - font size (`0.8rem`)
 - `--re-data-grid-header-cell-color` - text color (`#000`)
 - `--re-data-grid-header-cell-surface` - cell background (`#fafafa`)
+- `--re-data-grid-header-cell-line-height` - header text line-height for clamp (`1.2`)
+- `--re-data-grid-header-cell-max-lines` - header max text lines (`2`)
 - `--re-data-grid-header-group-cell-font-weight` - group font weight (`var(--re-data-grid-header-cell-font-weight)`)
 - `--re-data-grid-header-group-cell-font-size` - group font size (`var(--re-data-grid-header-cell-font-size)`)
 - `--re-data-grid-header-group-cell-color` - group text color (`var(--re-data-grid-header-cell-color)`)
@@ -391,12 +412,12 @@ Footer:
 
 Rows:
 
-- `--re-data-grid-row-separator-color` - row separator color (`#bbb`)
-- `--re-data-grid-row-separator` - separator line (`1px solid var(--re-data-grid-row-separator-color)`)
-- `--re-data-grid-row-odd-surface` - odd rows background (`var(--re-data-grid-cell-surface)`)
-- `--re-data-grid-row-hover-surface` - hover rows background (`var(--re-data-grid-cell-surface)`)
-- `--re-data-grid-row-hover-color` - hover rows text color (`var(--re-data-grid-cell-color)`)
-- `--re-data-grid-row-hover-rounded` - hover row corner radius (`0px`)
+- `--re-data-grid-row-separator-color` - row separator color (`#bbb`)
+- `--re-data-grid-row-separator` - separator line (`1px solid var(--re-data-grid-row-separator-color)`)
+- `--re-data-grid-row-odd-surface` - odd rows background (`var(--re-data-grid-cell-surface)`)
+- `--re-data-grid-row-hover-surface` - hover rows background (`var(--re-data-grid-cell-surface)`)
+- `--re-data-grid-row-hover-color` - hover rows text color (`var(--re-data-grid-cell-color)`)
+- `--re-data-grid-row-hover-rounded` - hover row corner radius (`0px`)
 
 Columns:
 
@@ -411,6 +432,8 @@ Cells:
 - `--re-data-grid-cell-font-size` - font size (`0.75rem`)
 - `--re-data-grid-cell-color` - text color (`#000`)
 - `--re-data-grid-cell-surface` - cell background (`#fff`)
+- `--re-data-grid-cell-line-height` - body text line-height for clamp (`1.2`)
+- `--re-data-grid-cell-max-lines` - body max text lines (`2`)
 
 Checkbox:
 
@@ -421,6 +444,12 @@ Checkbox:
 - `--re-data-grid-checkbox-surface` - checkbox background (`var(--surface-neutral, #fff)`)
 - `--re-data-grid-checkbox-active-color` - checkbox active color (`var(--primary-color, #2563eb)`)
 
+Focus Ring:
+
+- `--re-data-grid-focus-ring-color` - keyboard focus outline color (`color-mix(in srgb, var(--primary-color, #2a90f4) 55%, transparent)`)
+- `--re-data-grid-focus-ring-width` - keyboard focus outline width (`2px`)
+- `--re-data-grid-focus-ring-offset` - keyboard focus outline offset (`-2px`)
+
 Sticky Cells:
 
 - `--re-data-grid-sticky-header-cell-surface` - sticky header cell background (`#fff`)

package/fesm2022/reforgium-data-grid-grid-overlay-scroll.feature-DRUc6eDp.mjs

@@ -0,0 +1,79 @@
+import { c as computeScrollbarState, a as clampThumbTop, m as mapThumbTopToScrollTop } from './reforgium-data-grid-reforgium-data-grid-Dn9s4YO5.mjs';
+
+function createGridOverlayScrollFeature(ctx) {
+    const showScrollbar = () => {
+        ctx.setScrollbarVisible(true);
+        clearTimeout(ctx.getHideTimeout());
+    };
+    const hideScrollbarSoon = (delay = 1200) => {
+        if (ctx.isDragging()) {
+            return;
+        }
+        clearTimeout(ctx.getHideTimeout());
+        ctx.setHideTimeout(setTimeout(() => ctx.setScrollbarVisible(false), delay));
+    };
+    const onThumbDown = (event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        const scrollEl = ctx.getScrollElement();
+        if (!scrollEl) {
+            return;
+        }
+        ctx.setDragging(true);
+        showScrollbar();
+        const startY = event.clientY;
+        const startTop = ctx.getThumbTop();
+        const state = computeScrollbarState(scrollEl.scrollHeight || 1, scrollEl.clientHeight || 1, scrollEl.scrollTop || 0);
+        const maxThumbTop = state.maxThumbTop || 1;
+        const maxScrollTop = state.maxScrollTop || 1;
+        const onMove = (moveEvent) => {
+            const delta = moveEvent.clientY - startY;
+            const newTop = clampThumbTop(startTop + delta, maxThumbTop);
+            ctx.setThumbTop(newTop);
+            scrollEl.scrollTop = mapThumbTopToScrollTop(newTop, maxThumbTop, maxScrollTop);
+            ctx.calcScrollbar();
+            showScrollbar();
+        };
+        const onUp = () => {
+            window.removeEventListener('mousemove', onMove);
+            window.removeEventListener('mouseup', onUp);
+            ctx.setDragging(false);
+            hideScrollbarSoon();
+        };
+        window.addEventListener('mousemove', onMove);
+        window.addEventListener('mouseup', onUp);
+    };
+    const scheduleScrollbarUpdate = () => {
+        if (ctx.getScrollbarRafId() !== null) {
+            return;
+        }
+        ctx.setScrollbarRafId(requestAnimationFrame(() => {
+            ctx.setScrollbarRafId(null);
+            ctx.calcScrollbar();
+        }));
+    };
+    const clearScrollbarRaf = () => {
+        const rafId = ctx.getScrollbarRafId();
+        if (rafId === null) {
+            return;
+        }
+        cancelAnimationFrame(rafId);
+        ctx.setScrollbarRafId(null);
+    };
+    const finalizeScroll = () => {
+        scheduleScrollbarUpdate();
+        showScrollbar();
+        hideScrollbarSoon();
+    };
+    return {
+        onThumbDown,
+        showScrollbar,
+        hideScrollbarSoon,
+        scheduleScrollbarUpdate,
+        clearScrollbarRaf,
+        finalizeScroll,
+    };
+}
+
+export { createGridOverlayScrollFeature };
+//# sourceMappingURL=reforgium-data-grid-grid-overlay-scroll.feature-DRUc6eDp.mjs.map

package/fesm2022/reforgium-data-grid-grid-selection.feature-CGRNpMeD.mjs

@@ -0,0 +1,54 @@
+// noinspection ES6PreferShortImport
+function createGridSelectionFeature(ctx) {
+    const clearSelection = () => {
+        ctx.clearSelectedKeys();
+        ctx.emitSelectChange([]);
+    };
+    const selectAllLoaded = () => {
+        if (ctx.getSelectionMode() !== 'multi') {
+            return;
+        }
+        ctx.emitSelectChange(ctx.selectAll());
+    };
+    const onSelectAll = (event) => {
+        event?.preventDefault();
+        event?.stopPropagation();
+        selectAllLoaded();
+    };
+    const onCheckboxToggle = (row, index, event) => {
+        event?.preventDefault();
+        event?.stopPropagation();
+        if (ctx.isRowDisabled(row, index)) {
+            return;
+        }
+        if (ctx.getSelectionMode() === 'none') {
+            return;
+        }
+        ctx.emitSelectChange(ctx.selectRow(row));
+    };
+    const onSelectAllKeydown = (event) => {
+        const key = event.key;
+        if (key !== 'Enter' && key !== ' ') {
+            return;
+        }
+        onSelectAll(event);
+    };
+    const onCheckboxKeydown = (row, index, event) => {
+        const key = event.key;
+        if (key !== 'Enter' && key !== ' ') {
+            return;
+        }
+        onCheckboxToggle(row, index, event);
+    };
+    return {
+        clearSelection,
+        selectAllLoaded,
+        onSelectAll,
+        onCheckboxToggle,
+        onSelectAllKeydown,
+        onCheckboxKeydown,
+    };
+}
+
+export { createGridSelectionFeature };
+//# sourceMappingURL=reforgium-data-grid-grid-selection.feature-CGRNpMeD.mjs.map

package/fesm2022/reforgium-data-grid-grid-sticky.feature-DBpn_6R8.mjs

@@ -0,0 +1,86 @@
+function createGridStickyFeature(ctx) {
+    const isStickyRowIndex = (index) => {
+        return ctx.getStickyRowIndex() === index;
+    };
+    const findStickyIndexBefore = (indexes, index) => {
+        let low = 0;
+        let high = indexes.length - 1;
+        let result = -1;
+        while (low <= high) {
+            const mid = (low + high) >>> 1;
+            const value = indexes[mid];
+            if (value <= index) {
+                result = value;
+                low = mid + 1;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        return result === -1 ? null : result;
+    };
+    const updateStickyRow = (scrollTop, rowHeight, pinnedTopH) => {
+        const indexes = ctx.getStickyIndexes();
+        if (!indexes.length) {
+            ctx.setStickyRowIndex(null);
+            return;
+        }
+        const scrollRowIndex = Math.max(0, Math.floor(scrollTop / rowHeight));
+        const currentIndex = findStickyIndexBefore(indexes, scrollRowIndex);
+        if (currentIndex === null) {
+            ctx.setStickyRowIndex(null);
+            return;
+        }
+        let activeIndex = currentIndex;
+        const prevIndex = ctx.getStickyRowIndex();
+        const hysteresisPx = Math.max(1, rowHeight * 0.5);
+        if (prevIndex !== null && prevIndex !== currentIndex) {
+            const boundaryPx = currentIndex * rowHeight;
+            const delta = Math.abs(scrollTop - boundaryPx);
+            if (delta < hysteresisPx) {
+                activeIndex = prevIndex;
+            }
+        }
+        const stickyTop = ctx.getHeaderHeight() + pinnedTopH;
+        const topPx = scrollTop + stickyTop;
+        ctx.setStickyRowIndex(activeIndex);
+        ctx.setStickyRowTopPx(topPx);
+    };
+    const updateStickyFromScroll = () => {
+        const el = ctx.getScrollElement();
+        if (!el) {
+            return;
+        }
+        const scrollTop = el.scrollTop ?? 0;
+        const rowHeight = Math.max(1, ctx.getRowHeight());
+        const pinnedTopH = ctx.getPinnedTopCount() * rowHeight;
+        updateStickyRow(scrollTop, rowHeight, pinnedTopH);
+    };
+    const scheduleStickyUpdate = () => {
+        if (ctx.getStickyRafId() !== null) {
+            return;
+        }
+        ctx.setStickyRafId(requestAnimationFrame(() => {
+            ctx.setStickyRafId(null);
+            ctx.runInAngular(() => updateStickyFromScroll());
+        }));
+    };
+    const clearStickyRaf = () => {
+        const rafId = ctx.getStickyRafId();
+        if (rafId === null) {
+            return;
+        }
+        cancelAnimationFrame(rafId);
+        ctx.setStickyRafId(null);
+    };
+    return {
+        isStickyRowIndex,
+        updateStickyRow,
+        updateStickyFromScroll,
+        scheduleStickyUpdate,
+        clearStickyRaf,
+    };
+}
+
+export { createGridStickyFeature };
+//# sourceMappingURL=reforgium-data-grid-grid-sticky.feature-DBpn_6R8.mjs.map

package/fesm2022/reforgium-data-grid-grid-tooltip.feature-CMo88m8o.mjs

@@ -0,0 +1,89 @@
+function createGridTooltipFeature(ctx) {
+    const resolveCellValue = (row, col) => {
+        return 'value' in col ? col.value(row) : row[col.key];
+    };
+    const resolveTooltip = (row, col) => {
+        const tooltip = col.tooltip;
+        if (!tooltip) {
+            return null;
+        }
+        if (tooltip === true) {
+            const baseValue = resolveCellValue(row, col);
+            if (baseValue === null || baseValue === undefined || baseValue === '') {
+                return null;
+            }
+            return String(baseValue);
+        }
+        if (typeof tooltip === 'function') {
+            const value = tooltip(row);
+            if (value === null || value === undefined || value === '') {
+                return null;
+            }
+            return String(value);
+        }
+        if (typeof tooltip === 'string') {
+            return tooltip === '' ? null : tooltip;
+        }
+        return tooltip;
+    };
+    const showTooltip = (event, row, col, index) => {
+        const resolved = resolveTooltip(row, col);
+        if (!resolved) {
+            return;
+        }
+        const baseValue = resolveCellValue(row, col);
+        const context = {
+            $implicit: row,
+            row,
+            col: col,
+            index,
+            value: baseValue,
+        };
+        const offset = 12;
+        const x = event.clientX + offset;
+        const y = event.clientY + offset;
+        if (typeof resolved === 'string') {
+            ctx.setTooltipState({ text: resolved, x, y, visible: true });
+        }
+        else {
+            ctx.setTooltipState({ tpl: resolved, ctx: context, x, y, visible: true });
+        }
+        ctx.requestPositioning();
+    };
+    const hideTooltip = () => {
+        if (!ctx.getTooltipState().visible) {
+            return;
+        }
+        ctx.patchTooltipState({ visible: false });
+    };
+    const positionTooltip = (tooltipEl) => {
+        const state = ctx.getTooltipState();
+        if (!tooltipEl || !state.visible) {
+            return;
+        }
+        const rect = tooltipEl.getBoundingClientRect();
+        const padding = 8;
+        const vw = window.innerWidth;
+        const vh = window.innerHeight;
+        let x = state.x;
+        let y = state.y;
+        if (x + rect.width + padding > vw) {
+            x = Math.max(padding, vw - rect.width - padding);
+        }
+        if (y + rect.height + padding > vh) {
+            y = Math.max(padding, vh - rect.height - padding);
+        }
+        if (x !== state.x || y !== state.y) {
+            ctx.patchTooltipState({ x, y });
+        }
+    };
+    return {
+        resolveTooltip,
+        showTooltip,
+        hideTooltip,
+        positionTooltip,
+    };
+}
+
+export { createGridTooltipFeature };
+//# sourceMappingURL=reforgium-data-grid-grid-tooltip.feature-CMo88m8o.mjs.map