pixelize-design-library 2.4.2 → 3.0.0

package/dist/esm/Utils/formatDate.js

@@ -0,0 +1,138 @@
+import { DEFAULT_LOCALE } from "./price.js";
+export const DEFAULT_DATE_FALLBACK = "—";
+const DAY_KEY = /^(\d{4})-(\d{2})-(\d{2})$/;
+const EPOCH_DIGITS = /^-?\d+$/;
+const ENGLISH = /^en(?:-|$)/i;
+const RUNTIME_SPACES = /[\u2009\u202f]/g;
+const ONE_DIGIT = /^\d$/;
+const formatters = new Map();
+const build = (locale, options) => {
+    try {
+        return new Intl.DateTimeFormat(locale, options);
+    }
+    catch {
+        try {
+            return new Intl.DateTimeFormat(DEFAULT_LOCALE, options);
+        }
+        catch {
+            return new Intl.DateTimeFormat(DEFAULT_LOCALE, { ...options, timeZone: undefined });
+        }
+    }
+};
+const formatterFor = (locale, options) => {
+    const key = JSON.stringify([locale, options]);
+    let formatter = formatters.get(key);
+    if (!formatter) {
+        const format = build(locale, options);
+        formatter = { format, english: ENGLISH.test(format.resolvedOptions().locale) };
+        formatters.set(key, formatter);
+    }
+    return formatter;
+};
+const utcNoon = ({ year, month, day }) => {
+    const date = new Date(Date.UTC(2000, month, day, 12));
+    date.setUTCFullYear(year);
+    return date;
+};
+const isValidDay = (day) => {
+    const probe = utcNoon(day);
+    return probe.getUTCFullYear() === day.year && probe.getUTCMonth() === day.month && probe.getUTCDate() === day.day;
+};
+const resolve = (value) => {
+    let date;
+    if (value instanceof Date)
+        date = value;
+    else if (typeof value === "number")
+        date = new Date(value);
+    else if (typeof value === "string") {
+        const text = value.trim();
+        if (!text)
+            return null;
+        const key = DAY_KEY.exec(text);
+        if (key) {
+            const day = { year: Number(key[1]), month: Number(key[2]) - 1, day: Number(key[3]) };
+            return isValidDay(day) ? { kind: "day", day } : null;
+        }
+        date = new Date(EPOCH_DIGITS.test(text) ? Number(text) : text);
+    }
+    else
+        return null;
+    return Number.isNaN(date.getTime()) ? null : { kind: "instant", date };
+};
+const ZONE_PARTS = { year: "numeric", month: "numeric", day: "numeric" };
+const dayIn = (date, timeZone) => {
+    if (timeZone === undefined)
+        return { year: date.getFullYear(), month: date.getMonth(), day: date.getDate() };
+    const read = {};
+    for (const part of formatterFor("en-US", { ...ZONE_PARTS, timeZone }).format.formatToParts(date)) {
+        read[part.type] = Number(part.value);
+    }
+    return { year: read.year, month: read.month - 1, day: read.day };
+};
+const toDay = (resolved, timeZone) => resolved.kind === "day" ? resolved.day : dayIn(resolved.date, timeZone);
+const dayOrdinal = ({ year, month, day }) => year * 10000 + month * 100 + day;
+const dateFields = (options) => ({
+    day: "2-digit",
+    month: "short",
+    ...(options.year === "never" ? {} : { year: "numeric" }),
+});
+const join = (parts, english) => parts
+    .map(({ type, value }) => {
+    if (type === "day" && ONE_DIGIT.test(value))
+        return `0${value}`;
+    if (english && type === "month" && value === "Sept")
+        return "Sep";
+    return value;
+})
+    .join("")
+    .replace(RUNTIME_SPACES, " ");
+const dayFormatter = (options) => { var _a; return formatterFor((_a = options.locale) !== null && _a !== void 0 ? _a : DEFAULT_LOCALE, { ...dateFields(options), timeZone: "UTC" }); };
+const formatDay = (day, options) => {
+    const { format, english } = dayFormatter(options);
+    return join(format.formatToParts(utcNoon(day)), english);
+};
+/** "09 Oct 2026" in en-IN; locale order and month names otherwise. Null or invalid input gives `fallback`. */
+export function formatDate(value, options = {}) {
+    var _a;
+    const resolved = resolve(value);
+    if (!resolved)
+        return (_a = options.fallback) !== null && _a !== void 0 ? _a : DEFAULT_DATE_FALLBACK;
+    return formatDay(toDay(resolved, options.timeZone), options);
+}
+/** "09 Oct 2026, 2:05 pm" in en-IN; a bare `YYYY-MM-DD` has no time, so it prints the date alone. */
+export function formatDateTime(value, options = {}) {
+    var _a, _b;
+    const resolved = resolve(value);
+    if (!resolved)
+        return (_a = options.fallback) !== null && _a !== void 0 ? _a : DEFAULT_DATE_FALLBACK;
+    if (resolved.kind === "day")
+        return formatDay(resolved.day, options);
+    const { format, english } = formatterFor((_b = options.locale) !== null && _b !== void 0 ? _b : DEFAULT_LOCALE, {
+        ...dateFields(options),
+        hour: "numeric",
+        minute: "2-digit",
+        ...(options.time ? { hour12: options.time === "12h" } : {}),
+        ...(options.timeZone ? { timeZone: options.timeZone } : {}),
+    });
+    return join(format.formatToParts(resolved.date), english);
+}
+/** "09 – 24 Oct 2026": what both ends share is written once; reversed ends are reordered, one missing end prints the other. */
+export function formatDateRange(start, end, options = {}) {
+    var _a;
+    const first = resolve(start);
+    const second = resolve(end);
+    if (!first || !second) {
+        const only = first !== null && first !== void 0 ? first : second;
+        return only ? formatDay(toDay(only, options.timeZone), options) : ((_a = options.fallback) !== null && _a !== void 0 ? _a : DEFAULT_DATE_FALLBACK);
+    }
+    const a = toDay(first, options.timeZone);
+    const b = toDay(second, options.timeZone);
+    const [from, to] = dayOrdinal(a) <= dayOrdinal(b) ? [a, b] : [b, a];
+    if (dayOrdinal(from) === dayOrdinal(to))
+        return formatDay(from, options);
+    const { format, english } = dayFormatter(options);
+    if (typeof format.formatRangeToParts !== "function") {
+        return `${formatDay(from, options)} – ${formatDay(to, options)}`;
+    }
+    return join(format.formatRangeToParts(utcNoon(from), utcNoon(to)), english);
+}

package/dist/esm/Utils/functions.js

@@ -1,7 +1,9 @@
+/** `deal_stage` / `nextFollowUp` / `close-date` → `Deal Stage` / `Next Follow Up` / `Close Date`. */
 export function toWords(str) {
     return str
-        .toLowerCase()
-        .split('_')
-        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-        .join(' ');
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[_\-\s]+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join(" ");
 }

package/dist/esm/Utils/humanize.js

@@ -0,0 +1,15 @@
+/** `snake_case` / `kebab-case` → `Snake case` — first letter capitalized, rest untouched. */
+export function humanize(value) {
+    if (!value)
+        return "";
+    const text = value.replace(/[_-]/g, " ");
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+export function createEnumLabelResolver(keyMap) {
+    return (value) => {
+        var _a;
+        if (!value)
+            return "";
+        return (_a = keyMap[value]) !== null && _a !== void 0 ? _a : humanize(value);
+    };
+}

package/dist/esm/Utils/lazyWithRetry.js

@@ -0,0 +1,45 @@
+import { lazy } from "react";
+const RELOAD_GUARD_KEY = "pixelize:chunk-reloaded";
+const CHUNK_ERROR_PATTERNS = [
+    "failed to fetch dynamically imported module",
+    "error loading dynamically imported module",
+    "importing a module script failed",
+];
+export function isChunkLoadError(error) {
+    const message = error instanceof Error ? error.message : String(error !== null && error !== void 0 ? error : "");
+    const lower = message.toLowerCase();
+    return CHUNK_ERROR_PATTERNS.some((pattern) => lower.includes(pattern));
+}
+function reloadOnce() {
+    if (window.sessionStorage.getItem(RELOAD_GUARD_KEY))
+        return false;
+    window.sessionStorage.setItem(RELOAD_GUARD_KEY, "1");
+    window.location.reload();
+    return true;
+}
+/** Clears the one-shot reload guard; call once the app has rendered so a later deploy can reload again. */
+export function clearChunkReloadGuard() {
+    window.sessionStorage.removeItem(RELOAD_GUARD_KEY);
+}
+/** Wraps `React.lazy`; on a stale-chunk 404 it reloads once instead of leaving a broken import. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- mirrors React.lazy's own constraint
+export function lazyWithRetry(factory) {
+    return lazy(async () => {
+        try {
+            return await factory();
+        }
+        catch (error) {
+            if (isChunkLoadError(error) && reloadOnce()) {
+                return await new Promise(() => { });
+            }
+            throw error;
+        }
+    });
+}
+// Vite's vite:preloadError fires before any component renders; lazyWithRetry alone can't see it.
+export function installPreloadErrorReload() {
+    window.addEventListener("vite:preloadError", (event) => {
+        event.preventDefault();
+        reloadOnce();
+    });
+}

package/dist/esm/Utils/mergeRefs.js

@@ -5,11 +5,7 @@ export function setRef(ref, value) {
     else if (ref && typeof ref === "object")
         ref.current = value;
 }
-/**
- * Combine multiple refs into a single callback ref, so a value flows to all of
- * them. Useful when cloning an element to attach an internal ref while
- * preserving a ref the caller already set.
- */
+// Combines multiple refs into one callback ref — for cloning an element while preserving a caller's own ref.
 export function mergeRefs(...refs) {
     return (value) => refs.forEach((r) => setRef(r, value));
 }

package/dist/esm/Utils/planBadge.js

@@ -45,13 +45,7 @@ function daysUntil(expiryDate, now) {
     const startOfDay = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate());
     return Math.round((startOfDay(expiry).getTime() - startOfDay(now).getTime()) / 86400000);
 }
-/**
- * Turns an org's plan state into the label, urgency tone and inset-chip text for
- * a `PlanPill` — the "Upgrade your plan" badge in an app's top bar.
- *
- * Copy and thresholds are centralized here so every app shows the same badge for
- * the same org.
- */
+// Turns an org's plan state into PlanPill's label, urgency tone and inset-chip text; centralized so every app matches.
 export function resolvePlanBadge(input) {
     var _a, _b;
     if (!input.canManageBilling)
@@ -61,14 +55,10 @@ export function resolvePlanBadge(input) {
     const daysLeft = daysUntil(input.expiryDate, now);
     const remaining = formatPlanRemaining(input.expiryDate, now);
     const elapsed = formatPlanElapsed(input.expiryDate, now);
-    // Checked before the expiry branch: a lapsed org is downgraded to free, and
-    // "Free expired" is not a state worth shouting about.
+    // NOTE: checked before expiry — a lapsed org downgrades to free, and "Free expired" isn't worth shouting about.
     if (isFreePlan(input, planName))
         return upgrade("");
     if (input.isExpired || elapsed !== "") {
-        // "<plan> expired" as the label with the elapsed time in the inset chip —
-        // folding both behind "Upgrade your plan" made the pill wide enough to
-        // crowd the header.
         return {
             visible: true,
             label: `${planName || GENERIC_PLAN_NAME} expired`,

package/dist/esm/Utils/planExpiry.js

@@ -15,16 +15,10 @@ function addCalendarMonths(date, months) {
 function daysBetween(from, to) {
     return Math.round((to.getTime() - from.getTime()) / MS_PER_DAY);
 }
-/** Compact units (`2mo`, `5d`) — this reads inside a badge subtitle, where
- * "2 months 5 days left" wraps. */
 function unit(count, suffix) {
     return `${count}${suffix}`;
 }
-/**
- * Calendar months + leftover days between two dates.
- * Anchoring on a real month boundary keeps "1 month" honest across 28/30/31-day
- * months, so Jan 31 → Feb 28 reads as 28 days rather than a whole month.
- */
+// NOTE: anchors on real month boundaries so Jan 31 -> Feb 28 reads as 28 days, not "1 month".
 export function splitMonthsAndDays(from, to) {
     let months = (to.getFullYear() - from.getFullYear()) * 12 +
         (to.getMonth() - from.getMonth());
@@ -34,13 +28,7 @@ export function splitMonthsAndDays(from, to) {
         months = 0;
     return { months, days: daysBetween(addCalendarMonths(from, months), to) };
 }
-/**
- * Time left on a plan, compactly: `"3mo left"` once a whole month remains,
- * `"18d left"` below that. Intended for `UpgradeButton`'s `subtitle`, so it
- * stays one short line. Returns `""` when there is no usable date or the plan
- * has already lapsed — an expired plan is a different message, which the
- * consuming app owns.
- */
+// Compact plan time left, e.g. "3mo left" / "18d left". "" when unusable or already lapsed.
 export function formatPlanExpiry(expiryDate, now) {
     const expiry = toDate(expiryDate);
     if (!expiry)
@@ -55,7 +43,6 @@ export function formatPlanExpiry(expiryDate, now) {
     const { months, days } = splitMonthsAndDays(today, expiryDay);
     return months > 0 ? `${unit(months, "mo")} left` : `${unit(days, "d")} left`;
 }
-/** Never reports `0m`; the final stretch reads `1m`. */
 function formatHoursMinutes(ms, suffix) {
     const totalMinutes = Math.floor(ms / 60000);
     const hours = Math.floor(totalMinutes / 60);
@@ -64,15 +51,7 @@ function formatHoursMinutes(ms, suffix) {
         ? `${unit(hours, "h")} ${unit(minutes, "m")} ${suffix}`
         : `${unit(Math.max(minutes, 1), "m")} ${suffix}`;
 }
-/**
- * Time left on a plan, to the minute in the final day: `"3mo left"`, `"18d left"`,
- * then `"23h 45m left"` down to `"1m left"`. `""` once lapsed.
- *
- * Differs from `formatPlanExpiry` only in that last day: a calendar-day count
- * reads as "Expires today" for the whole day, which goes stale next to a live
- * countdown. Prefer this for a badge that sits on screen; `formatPlanExpiry`
- * stays the cheaper day-granular option.
- */
+// NOTE: like formatPlanExpiry but to the minute in the final day — for a badge staying on screen.
 export function formatPlanRemaining(expiryDate, now) {
     const expiry = toDate(expiryDate);
     if (!expiry)
@@ -87,11 +66,7 @@ export function formatPlanRemaining(expiryDate, now) {
     const { months, days } = splitMonthsAndDays(startOfDay(referenceNow), startOfDay(expiry));
     return months > 0 ? `${unit(months, "mo")} left` : `${unit(days, "d")} left`;
 }
-/**
- * How long ago a plan lapsed: `"1h 10m ago"` under a day, `"2d ago"` / `"1mo ago"`
- * beyond it. `""` while the plan is still live — so a badge can say how stale a
- * lapse is rather than a bare "expired".
- */
+// How long ago a plan lapsed, e.g. "1h 10m ago" / "2d ago". "" while still live.
 export function formatPlanElapsed(expiryDate, now) {
     const expiry = toDate(expiryDate);
     if (!expiry)

package/dist/esm/Utils/price.js

@@ -0,0 +1,32 @@
+export const DEFAULT_CURRENCY = "INR";
+export const DEFAULT_LOCALE = "en-IN";
+const formatters = new Map();
+const formatterFor = (locale, currency, minimum, maximum) => {
+    const key = `${locale}|${currency}|${minimum}|${maximum}`;
+    let formatter = formatters.get(key);
+    if (!formatter) {
+        formatter = new Intl.NumberFormat(locale, { style: "currency", currency, minimumFractionDigits: minimum, maximumFractionDigits: maximum });
+        formatters.set(key, formatter);
+    }
+    return formatter;
+};
+export function formatPrice(value, options = {}) {
+    const { currency = DEFAULT_CURRENCY, locale = DEFAULT_LOCALE, maximumFractionDigits } = options;
+    const whole = Number.isInteger(value);
+    return formatterFor(locale, currency, whole ? 0 : 2, maximumFractionDigits !== null && maximumFractionDigits !== void 0 ? maximumFractionDigits : (whole ? 0 : 2)).format(value);
+}
+export function discountPercent(price, mrp) {
+    if (mrp === undefined || mrp <= price || mrp <= 0)
+        return 0;
+    return Math.round(((mrp - price) / mrp) * 100);
+}
+export function discountAmount(price, mrp) {
+    if (mrp === undefined || mrp <= price)
+        return 0;
+    return mrp - price;
+}
+export function unitPrice(price, quantity, unit, per = 1) {
+    if (!(quantity > 0))
+        return null;
+    return { value: Math.round((price / quantity) * per * 100) / 100, per, unit };
+}

package/dist/esm/Utils/rafThrottle.js

@@ -1,14 +1,4 @@
-/**
- * Coalesces bursts of calls into one per animation frame.
- *
- * Every use in this library is a listener that reads layout (`getBoundingClientRect`) and then
- * writes position state. Unthrottled, a capture-phase `scroll` listener runs once per scrollable
- * ancestor per scroll event — on a low-end device that is a forced reflow several times per frame,
- * which is what makes menus judder while the page moves. One frame is also the fastest rate the
- * screen can show a change, so nothing is lost by dropping the rest.
- *
- * The trailing call wins: the last arguments before the frame fires are the current ones.
- */
+// NOTE: coalesces bursts into one call per animation frame — the trailing call's args win.
 export const rafThrottle = (fn) => {
     let frame = null;
     let latest;

package/dist/esm/Utils/table.js

@@ -1,17 +1,18 @@
-import React, { useCallback, useEffect, useRef } from "react";
-import { DEFAULT_BLACK, DEFAULT_WHITE, isDarkCanvas, onFilled, } from "../Theme/tokens/builders/accentText.js";
-import { resolveStatusTone } from "../Theme/tokens/builders/statusTone.js";
-// Built once, not per comparison: sorting 10k rows runs this ~130k times, and constructing a
-// collator is orders of magnitude dearer than using one.
+import { useDebouncedCallback } from "../Hooks/useDebounce.js";
+import React from "react";
+import { AA_NORMAL_TEXT, DEFAULT_BLACK, DEFAULT_WHITE, onFilled, } from "../Theme/tokens/builders/accentText.js";
+import { compositeOver } from "../Theme/tokens/builders/color.js";
+import { liftToContrast } from "../Theme/tokens/builders/outlineRung.js";
+import { labelOnFill, solidFillRung } from "../Theme/tokens/builders/filledSurface.js";
+import { resolveAvatarFill } from "../Theme/tokens/builders/statusTone.js";
+import { resolveSoftTone } from "../Theme/tokens/builders/tone.js";
+// NOTE: built once — sorting 10k rows runs this ~130k times and a Collator is costly to construct.
 const COLLATOR = new Intl.Collator(undefined, {
     numeric: true,
     sensitivity: "base",
 });
 const HAS_DIGIT = /\d/;
-/**
- * Type-aware, null-safe comparison. Detects numbers and dates; otherwise falls
- * back to a numeric-aware locale string compare. Empty/null values sort last.
- */
+// Type-aware, null-safe comparison: numbers and dates detected, else numeric-aware locale compare.
 export function compareValues(aRaw, bRaw, direction) {
     if (direction === "none")
         return 0;
@@ -30,8 +31,7 @@ export function compareValues(aRaw, bRaw, direction) {
     const bn = Number(b);
     if (!Number.isNaN(an) && !Number.isNaN(bn))
         return (an - bn) * dir;
-    // No digit means no date, so this skips two Date.parse calls per comparison on the common
-    // text columns (names, emails, statuses) without changing which strings parse as dates.
+    // NOTE: skips Date.parse on text columns with no digits — cheap and safe, since no digit means no date.
     if (HAS_DIGIT.test(a) && HAS_DIGIT.test(b)) {
         const ad = Date.parse(a);
         const bd = Date.parse(b);
@@ -53,11 +53,47 @@ export function SortMultiColumnData(data, sortConfig) {
         return 0;
     });
 }
+/** Theme-aware status palette per value — soft fill + semantic ink from `resolveStatusTone`. */
+export function buildSemanticStatusPalette(toneByValue, theme) {
+    const c = theme.colors;
+    const scales = {
+        info: c.semantic.info,
+        warning: c.semantic.warning,
+        success: c.semantic.success,
+        error: c.semantic.error,
+        neutral: c.gray,
+    };
+    return Object.fromEntries(Object.entries(toneByValue).map(([value, key]) => {
+        const scale = scales[key];
+        const tone = resolveSoftTone(c, scale);
+        const solidRung = solidFillRung(scale, c.white, c.backgroundColor.main);
+        const solid = scale[solidRung];
+        return [
+            value,
+            {
+                solid,
+                soft: tone.bg,
+                text: tone.fg,
+                onSolid: labelOnFill(solid, c.white, c.black),
+            },
+        ];
+    }));
+}
 const withAlpha = (hex, aa) => /^#([0-9a-fA-F]{6})$/.test(hex) ? `${hex}${aa}` : hex;
+/** Consumer `statusColors` values are fill seeds — derive bleed + pill ink from them. */
+const resolveStatusOverride = (fill, white, black, surface) => {
+    const soft = withAlpha(fill, "22");
+    const solid = resolveAvatarFill(fill);
+    return {
+        solid,
+        soft,
+        text: liftToContrast(fill, compositeOver(soft, surface), AA_NORMAL_TEXT),
+        onSolid: onFilled(solid, white, black),
+    };
+};
 /** Deterministic, theme-aware color palette for groups + status pills. */
 export function buildTablePalette(theme) {
     const c = theme.colors;
-    const mode = isDarkCanvas(c.backgroundColor.main) ? "dark" : "light";
     const scales = [
         c.primary,
         c.semantic.success,
@@ -71,12 +107,14 @@ export function buildTablePalette(theme) {
         c.purple,
     ];
     return scales.map((scale) => {
-        const tone = resolveStatusTone(scale, mode);
+        const tone = resolveSoftTone(c, scale);
+        const solidRung = solidFillRung(scale, c.white, c.backgroundColor.main);
+        const solid = scale[solidRung];
         return {
-            solid: scale[500],
+            solid,
             soft: tone.bg,
             text: tone.fg,
-            onSolid: onFilled(scale[500], c.white, c.black),
+            onSolid: labelOnFill(solid, c.white, c.black),
         };
     });
 }
@@ -89,22 +127,19 @@ const hashKey = (value) => {
 };
 /** Pick a deterministic palette color for a value, with optional consumer override hex. */
 export function pickTableColor(value, palette, override, theme) {
+    var _a;
     const white = theme ? theme.colors.white : DEFAULT_WHITE;
     const black = theme ? theme.colors.black : DEFAULT_BLACK;
     if (override) {
-        return { solid: override, soft: withAlpha(override, "22"), text: override, onSolid: onFilled(override, white, black) };
+        const surface = (_a = theme === null || theme === void 0 ? void 0 : theme.colors.background[50]) !== null && _a !== void 0 ? _a : DEFAULT_WHITE;
+        return resolveStatusOverride(override, white, black, surface);
     }
     if (!palette.length) {
         throw new Error("pickTableColor: empty palette — build it with buildTablePalette(theme).");
     }
     return palette[hashKey(value) % palette.length];
 }
-/**
- * Partition rows by a column, preserving first-seen group order. The group key is
- * a normalized string so object/array values (e.g. a `user` field that is an object
- * or an array of users) group together by their readable text instead of by object
- * identity.
- */
+// Partitions rows by a column, preserving first-seen group order; groups by readable text, not object identity.
 export function groupRows(data, groupBy) {
     const order = [];
     const map = new Map();
@@ -159,11 +194,7 @@ const objectToText = (o) => {
         return String(o.value);
     return "";
 };
-/**
- * Readable string for any cell value. Handles primitives, React elements, entity
- * objects (e.g. `user`: `{ name }` / `{ first_name, last_name }`), and arrays of
- * any of those (e.g. a multi-user field) by joining their texts.
- */
+// Readable string for any cell value: primitives, React elements, entity objects, or arrays of those.
 const getStringValue = (value) => {
     if (value === null || value === undefined)
         return "";
@@ -181,10 +212,7 @@ const getStringValue = (value) => {
     }
     return "";
 };
-/**
- * When a column has no `node`, raw cell values are rendered; plain objects
- * (e.g. relation/user fields) must not be passed as React children.
- */
+// When a column has no `node`, plain objects (relation/user fields) can't be passed as React children.
 export function normalizeTableCellValue(value) {
     if (value === null || value === undefined)
         return "";
@@ -196,7 +224,6 @@ export function normalizeTableCellValue(value) {
     if (React.isValidElement(value)) {
         return value;
     }
-    // Objects (relation/user) and arrays (multi-user / multi-select) → readable text.
     return getStringValue(value);
 }
 export const searchAndSortData = (data, searchValues) => {
@@ -235,22 +262,7 @@ export function debounce(func, delay) {
         }, delay);
     };
 }
-export function useDebounce(callback, delay) {
-    const callbackRef = useRef(callback);
-    const timerRef = useRef(null);
-    useEffect(() => {
-        callbackRef.current = callback;
-    }, [callback]);
-    const debouncedFn = useCallback((...args) => {
-        if (timerRef.current) {
-            clearTimeout(timerRef.current);
-        }
-        timerRef.current = setTimeout(() => {
-            callbackRef.current(...args);
-        }, delay);
-    }, [delay]);
-    return debouncedFn;
-}
+export const useDebounce = useDebouncedCallback;
 export const pageSizeCalculation = (records) => {
     const pageSize = [5, 10];
     if (records > 100) {
@@ -290,13 +302,7 @@ export const TableCellCalculation = ({ isFrozen, columnWidths, headerIndex, isCh
     }
     return { leftOffset, cellBgColor, rowBgColor, cellTextColor, rowTextColor };
 };
-/**
- * Filters array of objects by checking all property values against the search query.
- *
- * @param data - Array of objects
- * @param query - Search string
- * @returns Filtered data
- */
+// Filters an array of objects by checking all property values against the search query.
 export function globalSearchFilter(data, query) {
     if (!query.trim())
         return data;

package/dist/esm/Utils/tabular.js

@@ -0,0 +1,56 @@
+const NEEDS_QUOTES = /[",\r\n]/;
+const FORMULA_TRIGGER = /^[=+\-@\t\r]/;
+const PLAIN_NUMBER = /^[+-]?(?:\d[\d,]*(?:\.\d*)?|\.\d+)%?$/;
+const BOM = "";
+const RESERVED_FILE_CHARS = /[\\/:*?"<>|\p{Cc}]/gu;
+const MAX_FILE_NAME = 80;
+const REVOKE_DELAY_MS = 1000;
+const quote = (text) => (NEEDS_QUOTES.test(text) ? `"${text.replace(/"/g, '""')}"` : text);
+const looksLikeFormula = (text) => FORMULA_TRIGGER.test(text) && !PLAIN_NUMBER.test(text);
+function cellText(value, escapeFormulas) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : "";
+    const text = String(value);
+    if (typeof value !== "string" || !escapeFormulas)
+        return text;
+    return looksLikeFormula(text) ? `'${text}` : text;
+}
+function readCell(row, column) {
+    const field = row[column.key];
+    const format = column.format;
+    return format === undefined ? field : format(field, row);
+}
+/** RFC 4180 CSV: header line, then one CRLF-separated line per row. */
+export function toCsv(rows, columns, { bom = false } = {}) {
+    if (columns.length === 0)
+        return "";
+    const lines = [columns.map((column) => quote(column.header)).join(",")];
+    for (const row of rows) {
+        lines.push(columns.map((column) => quote(cellText(readCell(row, column), column.escapeFormulas !== false))).join(","));
+    }
+    return (bom ? BOM : "") + lines.join("\r\n");
+}
+/** Replaces path and reserved characters with `-`; caps at 80 characters, keeping the extension. */
+export function safeFileName(fileName) {
+    const cleaned = fileName.replace(RESERVED_FILE_CHARS, "-").trim().replace(/^[.\s]+/, "");
+    if (cleaned === "")
+        return "export";
+    if (cleaned.length <= MAX_FILE_NAME)
+        return cleaned;
+    const dot = cleaned.lastIndexOf(".");
+    const extension = dot > 0 && cleaned.length - dot <= 8 ? cleaned.slice(dot) : "";
+    return cleaned.slice(0, MAX_FILE_NAME - extension.length).replace(/[\uD800-\uDBFF]$/, "") + extension;
+}
+/** Saves `blob` as `safeFileName(fileName)`, then revokes its object URL. */
+export function downloadBlob(blob, fileName) {
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = safeFileName(fileName);
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+    setTimeout(() => URL.revokeObjectURL(url), REVOKE_DELAY_MS);
+}