@siyahi/ui 0.0.0-stage → 0.1.0-next.3

package/dist/components/registry/niko-table/lib/filter-functions.js

@@ -0,0 +1,309 @@
+import { FILTER_OPERATORS, FILTER_VARIANTS, JOIN_OPERATORS } from "./constants.js";
+//#region src/components/registry/niko-table/lib/filter-functions.ts
+const regexCache = /* @__PURE__ */ new Map();
+const MAX_REGEX_CACHE_SIZE = 100;
+function getOrCreateRegex(pattern, flags) {
+	const key = `${pattern}:${flags}`;
+	if (regexCache.has(key)) {
+		const cachedRegex = regexCache.get(key);
+		if (cachedRegex !== void 0) return cachedRegex;
+	}
+	if (regexCache.size >= MAX_REGEX_CACHE_SIZE) {
+		const firstKey = regexCache.keys().next().value;
+		if (firstKey !== void 0) regexCache.delete(firstKey);
+	}
+	try {
+		const regex = new RegExp(pattern, flags);
+		regexCache.set(key, regex);
+		return regex;
+	} catch {
+		const fallbackRegex = /(?!)/;
+		regexCache.set(key, fallbackRegex);
+		return fallbackRegex;
+	}
+}
+/**
+* Custom filter function that handles our extended filter operators
+*/
+const extendedFilter = (row, columnId, filterValue, _addMeta) => {
+	if (!filterValue) return true;
+	if (typeof filterValue === "object" && filterValue.operator && filterValue.value !== void 0) {
+		const filter = filterValue;
+		return applyFilterOperator(row.getValue(columnId), filter.operator, filter.value);
+	}
+	if (Array.isArray(filterValue)) {
+		const cellValue = row.getValue(columnId);
+		if (cellValue == null) return false;
+		if (filterValue.length === 2 && typeof filterValue[0] === "number" && typeof filterValue[1] === "number") {
+			const [min, max] = filterValue;
+			const value = Number(cellValue);
+			if (isNaN(value)) return false;
+			return value >= min && value <= max;
+		}
+		if (typeof cellValue === "string") {
+			const cellLower = cellValue.toLowerCase();
+			return filterValue.some((val) => typeof val === "string" ? val.toLowerCase() === cellLower : String(val) === cellValue);
+		}
+		return filterValue.some((val) => String(val) === String(cellValue));
+	}
+	const cellValue = row.getValue(columnId);
+	if (cellValue == null) return false;
+	try {
+		const cellStr = String(cellValue).toLowerCase();
+		return getOrCreateRegex(String(filterValue).toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(cellStr);
+	} catch {
+		return String(cellValue).toLowerCase().includes(String(filterValue).toLowerCase());
+	}
+};
+/**
+* Global filter with operator precedence. Supports plain string search,
+* pure OR, and mixed AND/OR (AND has higher precedence than OR — splits
+* filters into OR-separated AND-groups).
+*/
+/**
+* Whether a `globalFilter` value represents a search the reader actually made.
+*
+* A whitespace-only string does not: it is invisible in the search input, so
+* treating it as active makes the UI insist something is filtered while showing
+* nothing that could be. The advanced filter payload is an object and always
+* counts.
+*/
+function isGlobalFilterActive(value) {
+	if (typeof value === "string") return value.trim().length > 0;
+	return Boolean(value);
+}
+const globalFilter = (row, _columnId, filterValue, _addMeta) => {
+	if (!filterValue) return true;
+	if (typeof filterValue === "object" && filterValue.filters && Array.isArray(filterValue.filters)) {
+		const filters = filterValue.filters;
+		if (filterValue.joinOperator === "or") return filters.some((filter) => {
+			return applyFilterOperator(row.getValue(filter.id), filter.operator, filter.value);
+		});
+		else if (filterValue.joinOperator === JOIN_OPERATORS.MIXED) {
+			if (filters.length === 0) return true;
+			if (filters.length === 1) {
+				const filter = filters[0];
+				return applyFilterOperator(row.getValue(filter.id), filter.operator, filter.value);
+			}
+			const orGroups = [];
+			let currentAndGroup = [];
+			currentAndGroup.push(filters[0]);
+			for (let i = 1; i < filters.length; i++) {
+				const filter = filters[i];
+				if (filter.joinOperator === JOIN_OPERATORS.OR) {
+					orGroups.push(currentAndGroup);
+					currentAndGroup = [filter];
+				} else currentAndGroup.push(filter);
+			}
+			orGroups.push(currentAndGroup);
+			return orGroups.map((andGroup) => {
+				return andGroup.every((filter) => {
+					return applyFilterOperator(row.getValue(filter.id), filter.operator, filter.value);
+				});
+			}).some((result) => result);
+		}
+		return filters.every((filter) => {
+			return applyFilterOperator(row.getValue(filter.id), filter.operator, filter.value);
+		});
+	}
+	const searchValue = String(filterValue).trim().toLowerCase();
+	if (searchValue === "") return true;
+	return row.getAllCells().some((cell) => {
+		if (cell.column.getCanFilter() === false) return false;
+		const cellValue = cell.getValue();
+		if (cellValue == null) return false;
+		try {
+			const cellStr = String(cellValue).toLowerCase();
+			return getOrCreateRegex(searchValue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(cellStr);
+		} catch {
+			return String(cellValue).toLowerCase().includes(searchValue);
+		}
+	});
+};
+/**
+* Apply filter operator to a cell value
+*/
+function applyFilterOperator(cellValue, operator, filterValue) {
+	if (cellValue == null) switch (operator) {
+		case FILTER_OPERATORS.EMPTY: return true;
+		case FILTER_OPERATORS.NOT_EMPTY: return false;
+		default: return false;
+	}
+	const cellStr = String(cellValue).toLowerCase();
+	const filterStr = String(filterValue).toLowerCase();
+	switch (operator) {
+		case FILTER_OPERATORS.ILIKE: try {
+			return getOrCreateRegex(filterStr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(cellStr);
+		} catch {
+			return cellStr.includes(filterStr);
+		}
+		case FILTER_OPERATORS.NOT_ILIKE: try {
+			return !getOrCreateRegex(filterStr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(cellStr);
+		} catch {
+			return !cellStr.includes(filterStr);
+		}
+		case FILTER_OPERATORS.EQ:
+			if (typeof cellValue === "string" && typeof filterValue === "string") return cellStr === filterStr;
+			if (typeof cellValue === "boolean") return String(cellValue) === String(filterValue);
+			if (typeof filterValue === "boolean") return String(filterValue) === String(cellValue);
+			if (typeof cellValue === "object" && cellValue !== null && "getTime" in cellValue) {
+				const dateCell = cellValue.getTime();
+				const dateFilter = Number(filterValue);
+				if (!isNaN(dateCell) && !isNaN(dateFilter)) return new Date(dateCell).setHours(0, 0, 0, 0) === new Date(dateFilter).setHours(0, 0, 0, 0);
+			}
+			if (typeof cellValue === "number" || typeof filterValue === "number") {
+				const numCell = Number(cellValue);
+				const numFilter = Number(filterValue);
+				if (!isNaN(numCell) && !isNaN(numFilter)) return numCell === numFilter;
+			}
+			return cellValue === filterValue;
+		case FILTER_OPERATORS.NEQ:
+			if (typeof cellValue === "string" && typeof filterValue === "string") return cellStr !== filterStr;
+			if (typeof cellValue === "object" && cellValue !== null && "getTime" in cellValue) {
+				const dateCell = cellValue.getTime();
+				const dateFilter = Number(filterValue);
+				if (!isNaN(dateCell) && !isNaN(dateFilter)) return new Date(dateCell).setHours(0, 0, 0, 0) !== new Date(dateFilter).setHours(0, 0, 0, 0);
+			}
+			if (typeof cellValue === "number" || typeof filterValue === "number") {
+				const numCell = Number(cellValue);
+				const numFilter = Number(filterValue);
+				if (!isNaN(numCell) && !isNaN(numFilter)) return numCell !== numFilter;
+			}
+			return cellValue !== filterValue;
+		case FILTER_OPERATORS.EMPTY:
+			if (typeof cellValue === "string") return cellValue.trim() === "";
+			return cellValue == null;
+		case FILTER_OPERATORS.NOT_EMPTY:
+			if (typeof cellValue === "string") return cellValue.trim() !== "";
+			return cellValue != null;
+		case FILTER_OPERATORS.LT: {
+			const numCell = Number(cellValue);
+			const numFilter = Number(filterValue);
+			if (isNaN(numCell) || isNaN(numFilter)) return false;
+			return numCell < numFilter;
+		}
+		case FILTER_OPERATORS.LTE: {
+			const numCell = Number(cellValue);
+			const numFilter = Number(filterValue);
+			if (isNaN(numCell) || isNaN(numFilter)) return false;
+			return numCell <= numFilter;
+		}
+		case FILTER_OPERATORS.GT: {
+			const numCell = Number(cellValue);
+			const numFilter = Number(filterValue);
+			if (isNaN(numCell) || isNaN(numFilter)) return false;
+			return numCell > numFilter;
+		}
+		case FILTER_OPERATORS.GTE: {
+			const numCell = Number(cellValue);
+			const numFilter = Number(filterValue);
+			if (isNaN(numCell) || isNaN(numFilter)) return false;
+			return numCell >= numFilter;
+		}
+		case FILTER_OPERATORS.BETWEEN:
+			if (Array.isArray(filterValue) && filterValue.length === 2) {
+				const [min, max] = filterValue;
+				const numValue = Number(cellValue);
+				const numMin = Number(min);
+				const numMax = Number(max);
+				if (isNaN(numValue) || isNaN(numMin) || isNaN(numMax)) return false;
+				return numValue >= numMin && numValue <= numMax;
+			}
+			return false;
+		case FILTER_OPERATORS.IN:
+			if (Array.isArray(filterValue)) {
+				if (typeof cellValue === "string") {
+					const cellLower = cellValue.toLowerCase();
+					return filterValue.some((val) => typeof val === "string" ? val.toLowerCase() === cellLower : val === cellValue);
+				}
+				return filterValue.some((val) => String(val) === String(cellValue));
+			}
+			return false;
+		case FILTER_OPERATORS.NOT_IN:
+			if (Array.isArray(filterValue)) {
+				if (typeof cellValue === "string") {
+					const cellLower = cellValue.toLowerCase();
+					return !filterValue.some((val) => typeof val === "string" ? val.toLowerCase() === cellLower : val === cellValue);
+				}
+				return !filterValue.some((val) => String(val) === String(cellValue));
+			}
+			return true;
+		case FILTER_OPERATORS.RELATIVE: throw new Error("FILTER_OPERATORS.RELATIVE is not yet implemented. Either remove the 'Is relative to today' option from the date filter UI or implement this case.");
+		default: try {
+			return getOrCreateRegex(filterStr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(cellStr);
+		} catch {
+			return cellStr.includes(filterStr);
+		}
+	}
+}
+/**
+* Filter function for number range (slider) filters
+* Handles array values [min, max] for range filtering
+*/
+const numberRangeFilter = (row, columnId, filterValue, addMeta) => {
+	if (!filterValue) return true;
+	if (typeof filterValue === "object" && filterValue.operator && filterValue.value !== void 0) {
+		const filter = filterValue;
+		return applyFilterOperator(row.getValue(columnId), filter.operator, filter.value);
+	}
+	if (Array.isArray(filterValue) && filterValue.length === 2) {
+		const [min, max] = filterValue;
+		const value = Number(row.getValue(columnId));
+		if (isNaN(value)) return false;
+		const numMin = Number(min);
+		const numMax = Number(max);
+		if (isNaN(numMin) || isNaN(numMax)) return false;
+		return value >= numMin && value <= numMax;
+	}
+	return extendedFilter(row, columnId, filterValue, addMeta);
+};
+/**
+* Filter function for date range filters
+* Handles both single date (timestamp) and date range [from, to] (timestamps)
+*/
+const dateRangeFilter = (row, columnId, filterValue, addMeta) => {
+	if (!filterValue) return true;
+	if (typeof filterValue === "object" && filterValue.operator && filterValue.value !== void 0) {
+		const filter = filterValue;
+		return applyFilterOperator(row.getValue(columnId), filter.operator, filter.value);
+	}
+	const rowValue = row.getValue(columnId);
+	if (!rowValue) return false;
+	const rowTimestamp = rowValue instanceof Date ? rowValue.getTime() : typeof rowValue === "number" ? rowValue : new Date(rowValue).getTime();
+	if (isNaN(rowTimestamp)) return false;
+	if (Array.isArray(filterValue)) {
+		if (filterValue.length === 2) {
+			const [from, to] = filterValue;
+			const fromTime = Number(from);
+			const toTime = Number(to);
+			if (isNaN(fromTime) || isNaN(toTime)) return false;
+			return rowTimestamp >= fromTime && rowTimestamp <= toTime;
+		}
+		if (filterValue.length === 1) {
+			const dateTime = Number(filterValue[0]);
+			if (isNaN(dateTime)) return false;
+			return new Date(rowTimestamp).setHours(0, 0, 0, 0) === new Date(dateTime).setHours(0, 0, 0, 0);
+		}
+	}
+	if (typeof filterValue === "number") return new Date(rowTimestamp).setHours(0, 0, 0, 0) === new Date(filterValue).setHours(0, 0, 0, 0);
+	return extendedFilter(row, columnId, filterValue, addMeta);
+};
+/**
+* Helper function to create filter value with operator
+*
+* @param operator - The filter operator to apply
+* @param value - The value to filter by
+* @returns ExtendedColumnFilter object with default properties
+*/
+const createFilterValue = (operator, value) => {
+	return {
+		id: "",
+		filterId: "",
+		operator,
+		value,
+		variant: FILTER_VARIANTS.TEXT,
+		joinOperator: JOIN_OPERATORS.AND
+	};
+};
+//#endregion
+export { createFilterValue, dateRangeFilter, extendedFilter, globalFilter, isGlobalFilterActive, numberRangeFilter };

package/dist/components/registry/niko-table/lib/filter-rows.d.ts

@@ -0,0 +1,14 @@
+import { DataTableInstance, DataTableRow } from "../types/index.js";
+import { RowData } from "@tanstack/react-table";
+//#region src/components/registry/niko-table/lib/filter-rows.d.ts
+/**
+ * Get filtered rows excluding a specific column's filter.
+ * This is useful when generating options for a column - we want to see
+ * options that exist in the filtered dataset (from other filters) but
+ * not be limited by the current column's own filter.
+ */
+export declare function getFilteredRowsExcludingColumn<TData extends RowData>(table: DataTableInstance<TData>, coreRows: DataTableRow<TData>[], excludeColumnId: string, columnFilters: Array<{
+  id: string;
+  value: unknown;
+}>, globalFilter: unknown): DataTableRow<TData>[];
+//#endregion

package/dist/components/registry/niko-table/lib/filter-rows.js

@@ -0,0 +1,28 @@
+//#region src/components/registry/niko-table/lib/filter-rows.ts
+/**
+* Get filtered rows excluding a specific column's filter.
+* This is useful when generating options for a column - we want to see
+* options that exist in the filtered dataset (from other filters) but
+* not be limited by the current column's own filter.
+*/
+function getFilteredRowsExcludingColumn(table, coreRows, excludeColumnId, columnFilters, globalFilter) {
+	const otherFilters = columnFilters.filter((filter) => filter.id !== excludeColumnId);
+	if (otherFilters.length === 0 && !globalFilter) return coreRows;
+	const columnIds = new Set(table.getAllLeafColumns().map((c) => c.id));
+	return coreRows.filter((row) => {
+		for (const filter of otherFilters) {
+			if (!columnIds.has(filter.id)) continue;
+			const column = table.getColumn(filter.id);
+			if (!column) continue;
+			const filterFn = column.getFilterFn();
+			if (filterFn && !filterFn(row, filter.id, filter.value, () => {})) return false;
+		}
+		if (globalFilter) {
+			const globalFilterFn = table.getGlobalFilterFn();
+			if (globalFilterFn && !globalFilterFn(row, "global", globalFilter, () => {})) return false;
+		}
+		return true;
+	});
+}
+//#endregion
+export { getFilteredRowsExcludingColumn };

package/dist/components/registry/niko-table/lib/flex-columns.d.ts

@@ -0,0 +1,48 @@
+import { DataTableColumn, DataTableInstance } from "../types/index.js";
+import { ColumnSizingState, RowData } from "@tanstack/react-table";
+//#region src/components/registry/niko-table/lib/flex-columns.d.ts
+/**
+ * Resolve which column(s) should flex to fill the leftover row width.
+ *
+ * Flex fill is ON BY DEFAULT for resizable tables. A flex column renders with
+ * no explicit width, so under `table-layout: fixed` it soaks up the surplus:
+ * the table fills its container and a trailing actions column pins to the right
+ * edge instead of leaving dead space. It's pure layout — never writes
+ * `columnSizing`, so no persistence side effects.
+ *
+ * Selection: when no column opts in explicitly, the DEFAULT is the first
+ * non-pinned, resizable column (the primary text column). Selection / expand /
+ * actions columns are non-resizable (`enableResizing: false`), so they're
+ * skipped automatically; the default lands on the first real data column.
+ *
+ * Overrides:
+ * - `meta: { flex: true }` on a column flexes THAT column instead of the
+ *   default — use it when the primary column isn't the first one (e.g. a table
+ *   whose first columns are narrow codes/dates and a later column should grow).
+ * - `meta: { flex: false }` opts a column out of ever being auto-picked.
+ * - `meta: { disableFlexFill: true }` on the table (TableMeta) turns fill off
+ *   entirely — for a wide table meant to scroll horizontally rather than fill.
+ *
+ * Returns the set of column ids to render widthless (empty when fill is off or
+ * no eligible column exists — the table then sizes to its columns as before).
+ */
+export declare function resolveFlexColumnIds<TData extends RowData>(table: DataTableInstance<TData>): ReadonlySet<string>;
+/**
+ * The width to render for a single column. Centralizes the flex + header-fit
+ * rules so the header, body cells, and the min-width lock all agree.
+ *
+ * - Off (no resizing): the declared `size` (or auto when unset).
+ * - Flex column: no width — it fills the leftover row width.
+ * - Resized by the user: exactly `getSize()` — their choice wins, even if it's
+ *   narrower than the header (matches how spreadsheet grids let you shrink).
+ * - Otherwise: floored at the header's natural width (`headerMinWidths`) so the
+ *   label never truncates on load. Pure layout — `headerMinWidths` is measured,
+ *   never written back into `columnSizing`, so nothing persists or goes stale.
+ */
+export declare function resolveColumnWidth<TData extends RowData>(column: DataTableColumn<TData>, params: {
+  resizing: boolean;
+  isFlex: boolean;
+  columnSizing: ColumnSizingState;
+  headerMinWidths: ReadonlyMap<string, number>;
+}): number | string | undefined;
+//#endregion

package/dist/components/registry/niko-table/lib/flex-columns.js

@@ -0,0 +1,65 @@
+//#region src/components/registry/niko-table/lib/flex-columns.ts
+/**
+* Resolve which column(s) should flex to fill the leftover row width.
+*
+* Flex fill is ON BY DEFAULT for resizable tables. A flex column renders with
+* no explicit width, so under `table-layout: fixed` it soaks up the surplus:
+* the table fills its container and a trailing actions column pins to the right
+* edge instead of leaving dead space. It's pure layout — never writes
+* `columnSizing`, so no persistence side effects.
+*
+* Selection: when no column opts in explicitly, the DEFAULT is the first
+* non-pinned, resizable column (the primary text column). Selection / expand /
+* actions columns are non-resizable (`enableResizing: false`), so they're
+* skipped automatically; the default lands on the first real data column.
+*
+* Overrides:
+* - `meta: { flex: true }` on a column flexes THAT column instead of the
+*   default — use it when the primary column isn't the first one (e.g. a table
+*   whose first columns are narrow codes/dates and a later column should grow).
+* - `meta: { flex: false }` opts a column out of ever being auto-picked.
+* - `meta: { disableFlexFill: true }` on the table (TableMeta) turns fill off
+*   entirely — for a wide table meant to scroll horizontally rather than fill.
+*
+* Returns the set of column ids to render widthless (empty when fill is off or
+* no eligible column exists — the table then sizes to its columns as before).
+*/
+function resolveFlexColumnIds(table) {
+	const ids = /* @__PURE__ */ new Set();
+	if (!table.options.enableColumnResizing) return ids;
+	if (table.options.meta?.disableFlexFill) return ids;
+	const leafColumns = table.getVisibleLeafColumns();
+	const columnSizing = table.state.columnSizing;
+	let hasExplicit = false;
+	for (const column of leafColumns) if (column.columnDef.meta?.flex === true && !column.getIsPinned() && columnSizing[column.id] == null) {
+		ids.add(column.id);
+		hasExplicit = true;
+	}
+	if (hasExplicit) return ids;
+	const auto = leafColumns.find((column) => column.getCanResize() && !column.getIsPinned() && column.columnDef.meta?.flex !== false && columnSizing[column.id] == null);
+	if (auto) ids.add(auto.id);
+	return ids;
+}
+/**
+* The width to render for a single column. Centralizes the flex + header-fit
+* rules so the header, body cells, and the min-width lock all agree.
+*
+* - Off (no resizing): the declared `size` (or auto when unset).
+* - Flex column: no width — it fills the leftover row width.
+* - Resized by the user: exactly `getSize()` — their choice wins, even if it's
+*   narrower than the header (matches how spreadsheet grids let you shrink).
+* - Otherwise: floored at the header's natural width (`headerMinWidths`) so the
+*   label never truncates on load. Pure layout — `headerMinWidths` is measured,
+*   never written back into `columnSizing`, so nothing persists or goes stale.
+*/
+function resolveColumnWidth(column, params) {
+	const size = column.columnDef.size;
+	if (!params.resizing) return size ? `${size}px` : void 0;
+	if (params.isFlex) return void 0;
+	const base = column.getSize();
+	if (params.columnSizing[column.id] != null) return base;
+	const headerMin = params.headerMinWidths.get(column.id) ?? 0;
+	return headerMin > base ? headerMin : base;
+}
+//#endregion
+export { resolveColumnWidth, resolveFlexColumnIds };

package/dist/components/registry/niko-table/lib/format.d.ts

@@ -0,0 +1,33 @@
+//#region src/components/registry/niko-table/lib/format.d.ts
+export declare function formatDate(date: Date | string | number | undefined, opts?: Intl.DateTimeFormatOptions): string;
+/**
+ * Format a value into a human-readable label.
+ * Capitalizes first letter of each word and replaces hyphens/underscores with spaces.
+ *
+ * @example
+ * formatLabel("firstName") // "FirstName"
+ * formatLabel("first-name") // "First Name"
+ * formatLabel("first_name") // "First Name"
+ * formatLabel("true") // "Yes"
+ * formatLabel("false") // "No"
+ */
+export declare function formatLabel(value: string): string;
+export declare function daysAgo(days: number): Date;
+/**
+ * Format URL query parameters into a human-readable query string for display.
+ * Decodes URL-encoded values and formats JSON objects in a readable way.
+ *
+ * @param urlParams - The parsed URL parameters object
+ * @param urlKeys - Mapping of parameter keys to URL query keys
+ * @returns Formatted query string (e.g., `?search=i&global={"filters":[...]}`)
+ *
+ * @example
+ * ```ts
+ * const urlParams = { search: "i", globalFilter: { filters: [...], joinOperator: "mixed" } }
+ * const urlKeys = { search: "search", globalFilter: "global" }
+ * formatQueryString(urlParams, urlKeys)
+ * // Returns: "?search=i&global={"filters":[...], "joinOperator":"mixed"}"
+ * ```
+ */
+export declare function formatQueryString(urlParams: Record<string, unknown>, urlKeys: Record<string, string>): string;
+//#endregion

package/dist/components/registry/niko-table/lib/format.js

@@ -0,0 +1,99 @@
+//#region src/components/registry/niko-table/lib/format.ts
+function formatDate(date, opts = {}) {
+	if (!date) return "";
+	try {
+		return new Intl.DateTimeFormat("en-US", {
+			month: opts.month ?? "long",
+			day: opts.day ?? "numeric",
+			year: opts.year ?? "numeric",
+			...opts
+		}).format(new Date(date));
+	} catch {
+		return "";
+	}
+}
+/**
+* Format a value into a human-readable label.
+* Capitalizes first letter of each word and replaces hyphens/underscores with spaces.
+*
+* @example
+* formatLabel("firstName") // "FirstName"
+* formatLabel("first-name") // "First Name"
+* formatLabel("first_name") // "First Name"
+* formatLabel("true") // "Yes"
+* formatLabel("false") // "No"
+*/
+function formatLabel(value) {
+	if (value === "true") return "Yes";
+	if (value === "false") return "No";
+	return value.replace(/[-_]/g, " ").split(" ").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+/**
+* Create a date relative to a fixed epoch by subtracting days.
+* Deterministic — safe for mock data / SSR hydration (no `Date.now()`).
+*
+* @param days - Number of days to subtract from the mock epoch
+* @returns Date object representing the date N days before the epoch
+*
+* @example
+* daysAgo(7)   // 7 days before 2026-07-15
+* daysAgo(30)  // 30 days before 2026-07-15
+*/
+const MOCK_EPOCH = /* @__PURE__ */ new Date("2026-07-15T12:00:00.000Z");
+function daysAgo(days) {
+	const date = new Date(MOCK_EPOCH);
+	date.setUTCDate(date.getUTCDate() - days);
+	return date;
+}
+/**
+* Format URL query parameters into a human-readable query string for display.
+* Decodes URL-encoded values and formats JSON objects in a readable way.
+*
+* @param urlParams - The parsed URL parameters object
+* @param urlKeys - Mapping of parameter keys to URL query keys
+* @returns Formatted query string (e.g., `?search=i&global={"filters":[...]}`)
+*
+* @example
+* ```ts
+* const urlParams = { search: "i", globalFilter: { filters: [...], joinOperator: "mixed" } }
+* const urlKeys = { search: "search", globalFilter: "global" }
+* formatQueryString(urlParams, urlKeys)
+* // Returns: "?search=i&global={"filters":[...], "joinOperator":"mixed"}"
+* ```
+*/
+function formatQueryString(urlParams, urlKeys) {
+	const parts = [];
+	const formatJson = (obj, showFull = false) => {
+		try {
+			if (showFull) return JSON.stringify(obj);
+			const str = JSON.stringify(obj);
+			if (str.length <= 80) return str;
+			if (Array.isArray(obj) && obj.length > 0) return `[{...}] (${obj.length} items)`;
+			if (typeof obj === "object" && obj !== null) {
+				const keys = Object.keys(obj);
+				if (keys.length > 0) {
+					const firstKey = keys[0] ?? "";
+					const firstValue = obj[firstKey];
+					if (Array.isArray(firstValue)) return `{${firstKey}: [...], ...}`;
+					if (typeof firstValue === "object" && firstValue !== null) return `{${firstKey}: {...}, ...}`;
+					return `{${firstKey}: ${String(firstValue)}, ...}`;
+				}
+			}
+			return str.length > 100 ? `${str.slice(0, 100)}...` : str;
+		} catch {
+			return String(obj);
+		}
+	};
+	if (urlParams.pageIndex !== void 0 && urlParams.pageIndex !== 0) parts.push(`${urlKeys.pageIndex}=${urlParams.pageIndex}`);
+	if (urlParams.pageSize !== void 0 && urlParams.pageSize !== 10) parts.push(`${urlKeys.pageSize}=${urlParams.pageSize}`);
+	if (urlParams.sort && Array.isArray(urlParams.sort) && urlParams.sort.length > 0) parts.push(`${urlKeys.sort}=${formatJson(urlParams.sort)}`);
+	if (urlParams.filters && Array.isArray(urlParams.filters) && urlParams.filters.length > 0) parts.push(`${urlKeys.filters}=${formatJson(urlParams.filters, true)}`);
+	if (urlParams.search && typeof urlParams.search === "string") parts.push(`${urlKeys.search}=${urlParams.search}`);
+	if (urlParams.globalFilter && typeof urlParams.globalFilter === "object" && urlParams.globalFilter !== null && "filters" in urlParams.globalFilter) parts.push(`${urlKeys.globalFilter}=${formatJson(urlParams.globalFilter, true)}`);
+	if (urlParams.columnVisibility && typeof urlParams.columnVisibility === "object" && urlParams.columnVisibility !== null && Object.keys(urlParams.columnVisibility).length > 0) parts.push(`${urlKeys.columnVisibility}=${formatJson(urlParams.columnVisibility)}`);
+	if (urlParams.inlineFilters && Array.isArray(urlParams.inlineFilters) && urlParams.inlineFilters.length > 0) parts.push(`${urlKeys.inlineFilters}=${formatJson(urlParams.inlineFilters)}`);
+	if (urlParams.filterMode && urlParams.filterMode !== "standard") parts.push(`${urlKeys.filterMode}=${urlParams.filterMode}`);
+	return parts.length > 0 ? `?${parts.join("&")}` : "No query params";
+}
+//#endregion
+export { daysAgo, formatDate, formatLabel, formatQueryString };

package/dist/components/registry/niko-table/lib/render-cell-content.d.ts

@@ -0,0 +1,17 @@
+import { DataTableCell } from "../types/index.js";
+import { ReactNode } from "react";
+import { RowData } from "@tanstack/react-table";
+//#region src/components/registry/niko-table/lib/render-cell-content.d.ts
+/**
+ * Renders a body cell with TanStack grouping / aggregation awareness.
+ *
+ * - Grouped column cell: expand/collapse control + value + leaf count
+ * - Aggregated cell: `aggregatedCell` (falls back to `cell`)
+ * - Placeholder cell: empty (grouped columns leave gaps on leaf rows)
+ * - Otherwise: normal `cell` render
+ *
+ * Used by every body structure so grouping works the same for regular,
+ * virtualized, and DnD tables.
+ */
+export declare function renderCellContent<TData extends RowData, TValue>(cell: DataTableCell<TData, TValue>): ReactNode;
+//#endregion