@svgrid/grid 1.0.2 → 1.1.1

package/dist/cell-render.js

@@ -0,0 +1,246 @@
+// cell-render handlers extracted from the controller. Imperative event handlers
+// reading/writing controller state via the `ctx` handle; the reactive core
+// ($state/$derived/$effect) stays in the controller.
+import { normalizeEditorOptions, } from "./index";
+import "./sv-grid-scrollbar";
+import { formatNumericWithConfig, getDateFormatter, resolveDatePattern, } from "./cell-formatting";
+import { resolveCellFormat, } from "./conditional-formatting";
+import { resolveClassList, getOptionLabel, asDate, } from "./SvGrid.helpers";
+import { getPinnedCellValue, } from "./cell-values";
+export function createCellRender(ctx) {
+    function cellConditionalFormat(row, column, value) {
+        const formats = ctx.props.conditionalFormats;
+        if (!formats?.length)
+            return null;
+        return resolveCellFormat(value, row.original, column.id, formats, ctx.conditionalColumnStats.get(column.id) ?? null);
+    }
+    /** Compute the consumer-supplied row class for one rendered row. */
+    function computeRowClass(row, rowIndex) {
+        if (!ctx.props.rowClass)
+            return "";
+        return resolveClassList(ctx.props.rowClass({ row: row.original, rowIndex }));
+    }
+    /** Compute the consumer-supplied cell class for one rendered cell. */
+    function computeCellClass(row, column) {
+        const raw = column.columnDef.cellClass;
+        if (raw == null)
+            return "";
+        if (typeof raw === "string" || Array.isArray(raw)) {
+            return resolveClassList(raw);
+        }
+        if (typeof raw === "function") {
+            // Build a minimal CellContext - the only fields the wrapper-side
+            // cellClass author needs are `row` and `column`. Callers can read
+            // `ctx.row.original` and `ctx.column.id` exactly like in a `cell`
+            // renderer. The other fields are stubbed for compatibility.
+            const cellCtx = {
+                row,
+                column,
+                cell: undefined,
+                table: undefined,
+                getValue: () => row.getCellValueByColumnId(column.id),
+            };
+            return resolveClassList(raw(cellCtx));
+        }
+        return "";
+    }
+    /**
+     * Resolve the per-cell tooltip. Column-level `tooltip` field can be a
+     * plain string (rendered as `title=`) or a `(ctx) => string` callback
+     * for value-dependent text. Returning empty / nullish means no
+     * tooltip - the renderer omits the `title=` attribute entirely.
+     */
+    function computeCellTooltip(row, column) {
+        const raw = column.columnDef.tooltip;
+        if (raw == null)
+            return null;
+        if (typeof raw === "string")
+            return raw || null;
+        if (typeof raw === "function") {
+            const ctx = {
+                row,
+                column,
+                cell: undefined,
+                table: undefined,
+                getValue: () => row.getCellValueByColumnId(column.id),
+            };
+            const out = raw(ctx);
+            return out ? String(out) : null;
+        }
+        return null;
+    }
+    /**
+     * Resolve a per-cell note (a longer comment / annotation). Notes
+     * come from the grid's `notes` prop - a `{ [rowId]: { [columnId]: string } }`
+     * map - so the consumer keeps note storage. Returning non-empty
+     * paints a corner indicator AND becomes the cell's tooltip text.
+     */
+    function computeCellNote(row, column) {
+        // Internal overlay (from the comment editor) wins over props.notes so
+        // edits show immediately even when `notes` is controlled. An empty
+        // overlay entry means "removed".
+        const ov = ctx.noteOverrides?.[row.id]?.[column.id];
+        if (ov !== undefined)
+            return ov.trim() ? ov : null;
+        const map = ctx.props.notes;
+        if (!map)
+            return null;
+        const byCol = map[row.id];
+        if (!byCol)
+            return null;
+        const v = byCol[column.id];
+        return v && v.trim() ? v : null;
+    }
+    function getColumnEditorOptions(column, row) {
+        const def = column.columnDef.editorOptions;
+        if (typeof def === "function") {
+            // Dynamic per-row: must be re-evaluated because the row's other
+            // cells may have just changed (cascade).
+            if (!row?.original)
+                return [];
+            return normalizeEditorOptions(def(row.original));
+        }
+        const id = column.id;
+        if (!ctx.editorOptionsCache[id] ||
+            ctx.editorOptionsCache[id + "__src"] !== def) {
+            ctx.editorOptionsCache[id] = normalizeEditorOptions(def);
+            ctx.editorOptionsCache[id + "__src"] = def;
+        }
+        return ctx.editorOptionsCache[id];
+    }
+    /** Joined display string for list/chips cells. */
+    function formatListCellValue(column, value, row) {
+        const options = getColumnEditorOptions(column, row);
+        const sep = column.columnDef.editorSeparator ?? ", ";
+        if (Array.isArray(value)) {
+            return value.map((v) => getOptionLabel(options, v)).join(sep);
+        }
+        if (value == null || value === "")
+            return "";
+        return getOptionLabel(options, value);
+    }
+    function formatCellValue(column, value, row) {
+        const formatter = column.columnDef.formatter;
+        if (typeof formatter === "function") {
+            const formatted = formatter({ value, row, column, table: ctx.grid });
+            return String(formatted ?? "");
+        }
+        // Password columns: mask the stored value with bullets when the cell
+        // is in read-only mode. The editor still receives the real string.
+        if (column.columnDef.editorType === "password") {
+            const s = String(value ?? "");
+            return s.length > 0 ? "•".repeat(Math.min(s.length, 12)) : "";
+        }
+        const formatConfig = column.columnDef.format;
+        if (!formatConfig)
+            return String(value ?? "");
+        if (formatConfig.type === "number" ||
+            formatConfig.type === "currency" ||
+            formatConfig.type === "percent") {
+            return formatNumericWithConfig(value, {
+                type: formatConfig.type,
+                locales: formatConfig.locales,
+                currency: formatConfig.type === "currency"
+                    ? (formatConfig.currency ?? "USD")
+                    : undefined,
+                valueIsPercentPoints: formatConfig.type === "percent"
+                    ? formatConfig.valueIsPercentPoints
+                    : undefined,
+                options: formatConfig.options,
+            });
+        }
+        if (formatConfig.type === "date" || formatConfig.type === "datetime") {
+            const parsedDate = asDate(value);
+            if (parsedDate) {
+                const preset = resolveDatePattern(formatConfig.pattern, formatConfig.type);
+                const merged = preset || formatConfig.options
+                    ? { ...preset, ...formatConfig.options }
+                    : formatConfig.type === "date"
+                        ? { year: "numeric", month: "2-digit", day: "2-digit" }
+                        : {
+                            year: "numeric",
+                            month: "2-digit",
+                            day: "2-digit",
+                            hour: "2-digit",
+                            minute: "2-digit",
+                        };
+                return getDateFormatter(formatConfig.locales, merged).format(parsedDate);
+            }
+        }
+        return String(value ?? "");
+    }
+    /**
+     * Format a cell value for a PINNED row. Same surface as
+     * `formatCellValue` but doesn't depend on Row<TData>. Custom
+     * `formatter` callbacks are invoked with a `row` of `null` (their
+     * type allows it; most don't read it).
+     */
+    function formatPinnedValue(column, value) {
+        const def = column.columnDef;
+        const formatter = def.formatter;
+        if (typeof formatter === "function") {
+            return String(formatter({ value, row: null, column, table: ctx.grid }) ?? "");
+        }
+        if (def.editorType === "password") {
+            const s = String(value ?? "");
+            return s.length > 0 ? "•".repeat(Math.min(s.length, 12)) : "";
+        }
+        const formatConfig = def.format;
+        if (!formatConfig)
+            return String(value ?? "");
+        if (formatConfig.type === "number" ||
+            formatConfig.type === "currency" ||
+            formatConfig.type === "percent") {
+            return formatNumericWithConfig(value, {
+                type: formatConfig.type,
+                locales: formatConfig.locales,
+                currency: formatConfig.type === "currency"
+                    ? (formatConfig.currency ?? "USD")
+                    : undefined,
+                valueIsPercentPoints: formatConfig.type === "percent"
+                    ? formatConfig.valueIsPercentPoints
+                    : undefined,
+                options: formatConfig.options,
+            });
+        }
+        if (formatConfig.type === "date" || formatConfig.type === "datetime") {
+            const parsedDate = asDate(value);
+            if (parsedDate) {
+                const preset = resolveDatePattern(formatConfig.pattern, formatConfig.type);
+                const merged = preset || formatConfig.options
+                    ? { ...preset, ...formatConfig.options }
+                    : formatConfig.type === "date"
+                        ? { year: "numeric", month: "2-digit", day: "2-digit" }
+                        : { year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit" };
+                return getDateFormatter(formatConfig.locales, merged).format(parsedDate);
+            }
+        }
+        return String(value ?? "");
+    }
+    /**
+     * Resolve `cellClass` for a pinned row. We synthesise a minimal
+     * context `{ getValue, value, row: null, column }`; cell-class
+     * callbacks that read only the value (the common case) work
+     * unchanged.
+     */
+    function computePinnedCellClass(rowData, column) {
+        const cellClass = column.columnDef.cellClass;
+        if (typeof cellClass !== "function")
+            return "";
+        const value = getPinnedCellValue(rowData, column);
+        const out = cellClass({ getValue: () => value, value, row: null, column });
+        return out ? String(out) : "";
+    }
+    return {
+        cellConditionalFormat,
+        computeRowClass,
+        computeCellClass,
+        computeCellTooltip,
+        computeCellNote,
+        getColumnEditorOptions,
+        formatListCellValue,
+        formatCellValue,
+        formatPinnedValue,
+        computePinnedCellClass,
+    };
+}

package/dist/cell-render.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cell-render.test.js

@@ -0,0 +1,338 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createCellRender } from './cell-render';
+function makeRow(id, data) {
+    return {
+        id,
+        original: data,
+        getCellValueByColumnId: (colId) => data[colId],
+    };
+}
+function makeColumn(id, def = {}) {
+    return { id, columnDef: { ...def } };
+}
+function makeCtx(overrides = {}) {
+    return {
+        props: {},
+        grid: { id: 'grid' },
+        conditionalColumnStats: new Map(),
+        noteOverrides: {},
+        editorOptionsCache: {},
+        ...overrides,
+    };
+}
+describe('createCellRender / cellConditionalFormat', () => {
+    it('returns null when no conditionalFormats are configured', () => {
+        const cr = createCellRender(makeCtx());
+        const out = cr.cellConditionalFormat(makeRow('r1', { amt: 5 }), makeColumn('amt'), 5);
+        expect(out).toBeNull();
+    });
+    it('returns null when conditionalFormats is an empty array', () => {
+        const cr = createCellRender(makeCtx({ props: { conditionalFormats: [] } }));
+        expect(cr.cellConditionalFormat(makeRow('r', {}), makeColumn('amt'), 1)).toBeNull();
+    });
+    it('resolves a rule format against the value', () => {
+        const formats = [
+            {
+                type: 'rule',
+                columns: ['amt'],
+                when: ({ value }) => Number(value) > 10,
+                background: '#ff0000',
+                fontWeight: 700,
+            },
+        ];
+        const cr = createCellRender(makeCtx({ props: { conditionalFormats: formats } }));
+        const hit = cr.cellConditionalFormat(makeRow('r', { amt: 20 }), makeColumn('amt'), 20);
+        expect(hit?.background).toBe('#ff0000');
+        expect(hit?.fontWeight).toBe(700);
+        const miss = cr.cellConditionalFormat(makeRow('r', { amt: 1 }), makeColumn('amt'), 1);
+        expect(miss).toEqual({});
+    });
+    it('passes the precomputed column stat through to colorScale formats', () => {
+        const formats = [{ type: 'colorScale', min: '#fff', max: '#000' }];
+        const stats = new Map([['amt', { min: 0, max: 100 }]]);
+        const cr = createCellRender(makeCtx({ props: { conditionalFormats: formats }, conditionalColumnStats: stats }));
+        const out = cr.cellConditionalFormat(makeRow('r', { amt: 50 }), makeColumn('amt'), 50);
+        expect(out).not.toBeNull();
+        expect(out?.background).toBeDefined();
+    });
+});
+describe('createCellRender / computeRowClass', () => {
+    it('returns empty string when no rowClass configured', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computeRowClass(makeRow('r', {}), 0)).toBe('');
+    });
+    it('resolves a string rowClass', () => {
+        const rowClass = vi.fn(() => 'highlight');
+        const cr = createCellRender(makeCtx({ props: { rowClass } }));
+        const row = makeRow('r', { a: 1 });
+        expect(cr.computeRowClass(row, 3)).toBe('highlight');
+        expect(rowClass).toHaveBeenCalledWith({ row: row.original, rowIndex: 3 });
+    });
+    it('resolves an array / object rowClass', () => {
+        const cr = createCellRender(makeCtx({ props: { rowClass: () => ['a', '', 'b'] } }));
+        expect(cr.computeRowClass(makeRow('r', {}), 0)).toBe('a b');
+        const cr2 = createCellRender(makeCtx({ props: { rowClass: () => ({ on: true, off: false }) } }));
+        expect(cr2.computeRowClass(makeRow('r', {}), 0)).toBe('on');
+    });
+});
+describe('createCellRender / computeCellClass', () => {
+    it('returns empty string when cellClass is null/undefined', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computeCellClass(makeRow('r', {}), makeColumn('a'))).toBe('');
+    });
+    it('resolves a string cellClass', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computeCellClass(makeRow('r', {}), makeColumn('a', { cellClass: 'red' }))).toBe('red');
+    });
+    it('resolves an array cellClass', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computeCellClass(makeRow('r', {}), makeColumn('a', { cellClass: ['x', 'y'] }))).toBe('x y');
+    });
+    it('invokes a function cellClass with a minimal cell context', () => {
+        const cellClass = vi.fn((c) => (c.getValue() > 5 ? 'big' : 'small'));
+        const cr = createCellRender(makeCtx());
+        const row = makeRow('r', { score: 9 });
+        expect(cr.computeCellClass(row, makeColumn('score', { cellClass }))).toBe('big');
+        expect(cellClass).toHaveBeenCalledTimes(1);
+        const passed = cellClass.mock.calls[0][0];
+        expect(passed.row).toBe(row);
+        expect(passed.getValue()).toBe(9);
+    });
+    it('returns empty string for an unsupported cellClass type (number)', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computeCellClass(makeRow('r', {}), makeColumn('a', { cellClass: 123 }))).toBe('');
+    });
+});
+describe('createCellRender / computeCellTooltip', () => {
+    it('returns null when no tooltip configured', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computeCellTooltip(makeRow('r', {}), makeColumn('a'))).toBeNull();
+    });
+    it('returns a static string tooltip, but null for empty string', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computeCellTooltip(makeRow('r', {}), makeColumn('a', { tooltip: 'help' }))).toBe('help');
+        expect(cr.computeCellTooltip(makeRow('r', {}), makeColumn('a', { tooltip: '' }))).toBeNull();
+    });
+    it('invokes a function tooltip and stringifies the result', () => {
+        const tooltip = (c) => `val=${c.getValue()}`;
+        const cr = createCellRender(makeCtx());
+        const row = makeRow('r', { a: 42 });
+        expect(cr.computeCellTooltip(row, makeColumn('a', { tooltip }))).toBe('val=42');
+    });
+    it('returns null when the function tooltip returns a falsy value', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computeCellTooltip(makeRow('r', {}), makeColumn('a', { tooltip: () => '' }))).toBeNull();
+    });
+    it('returns null for an unsupported tooltip type', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computeCellTooltip(makeRow('r', {}), makeColumn('a', { tooltip: 5 }))).toBeNull();
+    });
+});
+describe('createCellRender / computeCellNote', () => {
+    it('returns null when neither overrides nor notes have an entry', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computeCellNote(makeRow('r', {}), makeColumn('a'))).toBeNull();
+    });
+    it('prefers the internal note override over props.notes', () => {
+        const cr = createCellRender(makeCtx({
+            noteOverrides: { r: { a: 'overlay' } },
+            props: { notes: { r: { a: 'stored' } } },
+        }));
+        expect(cr.computeCellNote(makeRow('r', {}), makeColumn('a'))).toBe('overlay');
+    });
+    it('treats a blank override as a removal (null)', () => {
+        const cr = createCellRender(makeCtx({
+            noteOverrides: { r: { a: '   ' } },
+            props: { notes: { r: { a: 'stored' } } },
+        }));
+        expect(cr.computeCellNote(makeRow('r', {}), makeColumn('a'))).toBeNull();
+    });
+    it('falls back to props.notes when no override exists', () => {
+        const cr = createCellRender(makeCtx({ props: { notes: { r: { a: 'stored note' } } } }));
+        expect(cr.computeCellNote(makeRow('r', {}), makeColumn('a'))).toBe('stored note');
+    });
+    it('returns null for a whitespace-only stored note', () => {
+        const cr = createCellRender(makeCtx({ props: { notes: { r: { a: '  ' } } } }));
+        expect(cr.computeCellNote(makeRow('r', {}), makeColumn('a'))).toBeNull();
+    });
+    it('returns null when the row or column is absent in the notes map', () => {
+        const cr = createCellRender(makeCtx({ props: { notes: { other: { a: 'x' } } } }));
+        expect(cr.computeCellNote(makeRow('r', {}), makeColumn('a'))).toBeNull();
+        const cr2 = createCellRender(makeCtx({ props: { notes: { r: { b: 'x' } } } }));
+        expect(cr2.computeCellNote(makeRow('r', {}), makeColumn('a'))).toBeNull();
+    });
+});
+describe('createCellRender / getColumnEditorOptions', () => {
+    it('returns [] for a function editorOptions when row has no original', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', { editorOptions: () => [{ value: 1, label: 'one' }] });
+        expect(cr.getColumnEditorOptions(col, null)).toEqual([]);
+    });
+    it('evaluates a function editorOptions per row', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', {
+            editorOptions: (data) => [{ value: data.code, label: data.name }],
+        });
+        const row = makeRow('r', { code: 'x', name: 'X' });
+        const opts = cr.getColumnEditorOptions(col, row);
+        expect(opts).toEqual([{ value: 'x', label: 'X' }]);
+    });
+    it('caches normalized static editorOptions and reuses them', () => {
+        const ctx = makeCtx();
+        const cr = createCellRender(ctx);
+        const src = ['a', 'b'];
+        const col = makeColumn('a', { editorOptions: src });
+        const first = cr.getColumnEditorOptions(col);
+        const second = cr.getColumnEditorOptions(col);
+        expect(first).toBe(second); // same cached array reference
+        expect(ctx.editorOptionsCache['a']).toBe(first);
+    });
+    it('re-normalizes when the editorOptions source changes', () => {
+        const ctx = makeCtx();
+        const cr = createCellRender(ctx);
+        const first = cr.getColumnEditorOptions(makeColumn('a', { editorOptions: ['a'] }));
+        const second = cr.getColumnEditorOptions(makeColumn('a', { editorOptions: ['b'] }));
+        expect(first).not.toBe(second);
+    });
+});
+describe('createCellRender / formatListCellValue', () => {
+    it('joins an array of values using the default separator', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', {
+            editorOptions: [
+                { value: 1, label: 'One' },
+                { value: 2, label: 'Two' },
+            ],
+        });
+        expect(cr.formatListCellValue(col, [1, 2])).toBe('One, Two');
+    });
+    it('honors a custom editorSeparator', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', {
+            editorSeparator: ' | ',
+            editorOptions: [
+                { value: 1, label: 'One' },
+                { value: 2, label: 'Two' },
+            ],
+        });
+        expect(cr.formatListCellValue(col, [1, 2])).toBe('One | Two');
+    });
+    it('returns empty string for null / empty scalar values', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', { editorOptions: [] });
+        expect(cr.formatListCellValue(col, null)).toBe('');
+        expect(cr.formatListCellValue(col, '')).toBe('');
+    });
+    it('maps a single scalar value to its label', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', {
+            editorOptions: [{ value: 'k', label: 'Known' }],
+        });
+        expect(cr.formatListCellValue(col, 'k')).toBe('Known');
+        // unknown value falls back to its string form
+        expect(cr.formatListCellValue(col, 'z')).toBe('z');
+    });
+});
+describe('createCellRender / formatCellValue', () => {
+    const row = makeRow('r', {});
+    it('uses a custom formatter callback when present', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', {
+            formatter: ({ value }) => `<<${value}>>`,
+        });
+        expect(cr.formatCellValue(col, 7, row)).toBe('<<7>>');
+    });
+    it('coerces a nullish formatter result to empty string', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', { formatter: () => null });
+        expect(cr.formatCellValue(col, 1, row)).toBe('');
+    });
+    it('masks password columns with bullets, capped at 12', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', { editorType: 'password' });
+        expect(cr.formatCellValue(col, 'abc', row)).toBe('•••');
+        expect(cr.formatCellValue(col, '', row)).toBe('');
+        expect(cr.formatCellValue(col, 'x'.repeat(50), row)).toBe('•'.repeat(12));
+    });
+    it('stringifies plain values when there is no format config', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a');
+        expect(cr.formatCellValue(col, 'hello', row)).toBe('hello');
+        expect(cr.formatCellValue(col, null, row)).toBe('');
+    });
+    it('applies numeric / currency / percent format configs', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.formatCellValue(makeColumn('a', { format: { type: 'number' } }), 1234.5, row)).toContain('1,234');
+        const cur = cr.formatCellValue(makeColumn('a', { format: { type: 'currency', currency: 'USD' } }), 1000, row);
+        expect(cur).toContain('$');
+        const pct = cr.formatCellValue(makeColumn('a', { format: { type: 'percent' } }), 0.25, row);
+        expect(pct).toContain('%');
+    });
+    it('formats date configs and falls back when the value is not a date', () => {
+        const cr = createCellRender(makeCtx());
+        const dateCol = makeColumn('a', { format: { type: 'date' } });
+        const out = cr.formatCellValue(dateCol, '2024-01-15T00:00:00Z', row);
+        expect(out).toMatch(/2024/);
+        // Unparseable -> returns String(value)
+        expect(cr.formatCellValue(dateCol, 'not-a-date', row)).toBe('not-a-date');
+    });
+    it('formats datetime configs with merged default options', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', { format: { type: 'datetime' } });
+        const out = cr.formatCellValue(col, '2024-03-10T13:45:00Z', row);
+        expect(out).toMatch(/2024/);
+    });
+});
+describe('createCellRender / formatPinnedValue', () => {
+    it('invokes a formatter with a null row', () => {
+        const cr = createCellRender(makeCtx());
+        const formatter = vi.fn(({ value, row }) => `${value}:${row}`);
+        const col = makeColumn('a', { formatter });
+        expect(cr.formatPinnedValue(col, 5)).toBe('5:null');
+        expect(formatter.mock.calls[0][0].row).toBeNull();
+    });
+    it('masks password pinned values', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.formatPinnedValue(makeColumn('a', { editorType: 'password' }), 'pw')).toBe('••');
+        expect(cr.formatPinnedValue(makeColumn('a', { editorType: 'password' }), '')).toBe('');
+    });
+    it('stringifies when no format config', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.formatPinnedValue(makeColumn('a'), 'total')).toBe('total');
+        expect(cr.formatPinnedValue(makeColumn('a'), null)).toBe('');
+    });
+    it('applies numeric and date format configs', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.formatPinnedValue(makeColumn('a', { format: { type: 'number' } }), 9999)).toContain('9,999');
+        const d = cr.formatPinnedValue(makeColumn('a', { format: { type: 'date' } }), '2022-06-01T00:00:00Z');
+        expect(d).toMatch(/2022/);
+        // unparseable date falls through to String()
+        expect(cr.formatPinnedValue(makeColumn('a', { format: { type: 'date' } }), 'xyz')).toBe('xyz');
+    });
+    it('formats datetime pinned configs', () => {
+        const cr = createCellRender(makeCtx());
+        const out = cr.formatPinnedValue(makeColumn('a', { format: { type: 'datetime' } }), '2021-12-31T08:00:00Z');
+        expect(out).toMatch(/2021/);
+    });
+});
+describe('createCellRender / computePinnedCellClass', () => {
+    it('returns empty string when cellClass is not a function', () => {
+        const cr = createCellRender(makeCtx());
+        expect(cr.computePinnedCellClass({ a: 1 }, makeColumn('a', { cellClass: 'x' }))).toBe('');
+    });
+    it('invokes a function cellClass with a null row and the pinned value', () => {
+        const cr = createCellRender(makeCtx());
+        const cellClass = vi.fn((c) => (c.value > 0 ? 'pos' : 'neg'));
+        const col = makeColumn('a', {
+            cellClass,
+            field: 'a',
+        });
+        expect(cr.computePinnedCellClass({ a: 3 }, col)).toBe('pos');
+        expect(cellClass.mock.calls[0][0].row).toBeNull();
+    });
+    it('coerces a falsy cellClass result to empty string', () => {
+        const cr = createCellRender(makeCtx());
+        const col = makeColumn('a', { cellClass: () => undefined, field: 'a' });
+        expect(cr.computePinnedCellClass({ a: 1 }, col)).toBe('');
+    });
+});

package/dist/cell-values.d.ts

@@ -0,0 +1,28 @@
+import type { Column, ColumnDef, Row, RowData, TableFeatures } from "./index";
+export declare function getColumnBaseValue<TData extends RowData>(row: Row<TData>, column: Column<TData>): unknown;
+export declare function isGroupRow<TData extends RowData>(row: Row<TData>): boolean;
+export declare function toolPanelHeaderLabel<TData extends RowData>(column: Column<TData>): string;
+/** Apply the column's `format` config to a raw numeric summary value
+ *  (sum / avg / etc.). Mirrors the currency/number/percent branches in
+ *  `formatCellValue` so a totaled salary column shows "$1,234,567" in
+ *  the footer instead of "1234567". Per-row `formatter` functions are
+ *  intentionally NOT invoked here - they may close over row state. */
+export declare function formatSummaryNumeric<TData extends RowData>(column: Column<TData>, value: number): string;
+/**
+ * Effective horizontal alignment for a column. Honors the explicit
+ * `align` prop on the ColumnDef; otherwise picks a sensible default
+ * based on `editorType`:
+ *   number / date / datetime → 'right'
+ *   checkbox                 → 'center'
+ *   everything else          → 'left'
+ */
+export declare function getColumnAlign<TData extends RowData>(column: Column<TData>): "left" | "center" | "right";
+/**
+ * Read a cell value from a PINNED row. Pinned rows aren't bound to a
+ * TanStack Row<TData>, so we resolve the value directly off the raw
+ * TData via `accessorFn` or `field`. Mirrors `getColumnBaseValue`'s
+ * lookup path minus the Row indirection.
+ */
+export declare function getPinnedCellValue<TData extends RowData>(rowData: TData, column: Column<TData>): unknown;
+export declare function getColumnAccessorValue<TData extends RowData>(rowData: TData, column: Column<TData>): unknown;
+export declare function columnDefMatchesId<TFeatures extends TableFeatures, TData extends RowData>(def: ColumnDef<TFeatures, TData>, columnId: string): boolean;