pixelize-design-library 3.0.1-beta.1 → 3.1.0

package/dist/Utils/table.d.ts

@@ -1,18 +1,36 @@
+import { useDebouncedCallback } from "../Hooks/useDebounce";
 import React from "react";
 import { DataObject, TableHeaderProps } from "../Components/Table/TableProps";
-export declare function SortMultiColumnData(data: Record<string, string | number>[], sortConfig: {
+import type { CustomThemeProps } from "../Theme/themeProps";
+export declare function compareValues(aRaw: unknown, bRaw: unknown, direction: "asc" | "desc" | "none"): number;
+export declare function SortMultiColumnData(data: DataObject[], sortConfig: {
     column: string | number;
     direction: string;
-}[]): Record<string, string | number>[];
+}[]): DataObject[];
+export type TablePaletteColor = {
+    solid: string;
+    soft: string;
+    text: string;
+    onSolid?: string;
+};
+export type SemanticStatusTone = "info" | "warning" | "success" | "error" | "neutral";
+/** Theme-aware status palette per value — soft fill + semantic ink from `resolveStatusTone`. */
+export declare function buildSemanticStatusPalette(toneByValue: Record<string, SemanticStatusTone>, theme: CustomThemeProps): Record<string, TablePaletteColor>;
+/** Deterministic, theme-aware color palette for groups + status pills. */
+export declare function buildTablePalette(theme: CustomThemeProps): TablePaletteColor[];
+/** Pick a deterministic palette color for a value, with optional consumer override hex. */
+export declare function pickTableColor(value: string | number, palette: TablePaletteColor[], override?: string, theme?: CustomThemeProps): TablePaletteColor;
+export type TableGroup = {
+    value: string | number;
+    label: string;
+    rows: DataObject[];
+};
+export declare function groupRows(data: DataObject[], groupBy: string | number): TableGroup[];
 export declare const calculateLeftOffset: (columns: number[], index: number) => number;
-/**
- * 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.
- */
 export declare function normalizeTableCellValue(value: unknown): React.ReactNode;
 export declare const searchAndSortData: (data: DataObject[], searchValues: Record<string, string>) => DataObject[];
-export declare function debounce<T extends (...args: any[]) => void>(func: T, delay: number): (...args: Parameters<T>) => void;
-export declare function useDebounce<T extends (...args: any[]) => void>(callback: T, delay: number): (...args: Parameters<T>) => void;
+export declare function debounce<T extends (...args: never[]) => void>(func: T, delay: number): (...args: Parameters<T>) => void;
+export declare const useDebounce: typeof useDebouncedCallback;
 export declare const pageSizeCalculation: (records: number) => number[];
 type TableCellCalculationProps = {
     isFrozen?: boolean;
@@ -23,21 +41,14 @@ type TableCellCalculationProps = {
     row: DataObject;
     freezedBgColor?: string;
     index: number;
-    theme: any;
+    theme: CustomThemeProps;
 };
 export declare const TableCellCalculation: ({ isFrozen, columnWidths, headerIndex, isCheckbox, header, row, freezedBgColor, index, theme, }: TableCellCalculationProps) => {
     leftOffset: number;
-    cellBgColor: any;
-    rowBgColor: any;
-    cellTextColor: any;
-    rowTextColor: any;
+    cellBgColor: string | undefined;
+    rowBgColor: string | undefined;
+    cellTextColor: string | undefined;
+    rowTextColor: string | undefined;
 };
-/**
- * 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
- */
-export declare function globalSearchFilter<T extends Record<string, any>>(data: T[], query: string): T[];
+export declare function globalSearchFilter<T extends Record<string, unknown>>(data: T[], query: string): T[];
 export {};

package/dist/Utils/table.js

@@ -1,79 +1,179 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TableCellCalculation = exports.pageSizeCalculation = exports.searchAndSortData = exports.calculateLeftOffset = void 0;
+exports.TableCellCalculation = exports.pageSizeCalculation = exports.useDebounce = exports.searchAndSortData = exports.calculateLeftOffset = void 0;
+exports.compareValues = compareValues;
 exports.SortMultiColumnData = SortMultiColumnData;
+exports.buildSemanticStatusPalette = buildSemanticStatusPalette;
+exports.buildTablePalette = buildTablePalette;
+exports.pickTableColor = pickTableColor;
+exports.groupRows = groupRows;
 exports.normalizeTableCellValue = normalizeTableCellValue;
 exports.debounce = debounce;
-exports.useDebounce = useDebounce;
 exports.globalSearchFilter = globalSearchFilter;
-var react_1 = __importStar(require("react"));
+const useDebounce_1 = require("../Hooks/useDebounce");
+const react_1 = __importDefault(require("react"));
+const accentText_1 = require("../Theme/tokens/builders/accentText");
+const color_1 = require("../Theme/tokens/builders/color");
+const outlineRung_1 = require("../Theme/tokens/builders/outlineRung");
+const filledSurface_1 = require("../Theme/tokens/builders/filledSurface");
+const statusTone_1 = require("../Theme/tokens/builders/statusTone");
+const tone_1 = require("../Theme/tokens/builders/tone");
+// 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: numbers and dates detected, else numeric-aware locale compare.
+function compareValues(aRaw, bRaw, direction) {
+    if (direction === "none")
+        return 0;
+    const dir = direction === "asc" ? 1 : -1;
+    const a = getStringValue(aRaw);
+    const b = getStringValue(bRaw);
+    const aEmpty = a === "";
+    const bEmpty = b === "";
+    if (aEmpty && bEmpty)
+        return 0;
+    if (aEmpty)
+        return 1; // nulls/empties always last
+    if (bEmpty)
+        return -1;
+    const an = Number(a);
+    const bn = Number(b);
+    if (!Number.isNaN(an) && !Number.isNaN(bn))
+        return (an - bn) * dir;
+    // 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);
+        if (!Number.isNaN(ad) && !Number.isNaN(bd))
+            return (ad - bd) * dir;
+    }
+    return COLLATOR.compare(a, b) * dir;
+}
 function SortMultiColumnData(data, sortConfig) {
-    if (!sortConfig.length)
+    const active = sortConfig.filter((s) => s.direction !== "none");
+    if (!active.length)
         return data;
-    return __spreadArray([], data, true).sort(function (a, b) {
-        for (var _i = 0, sortConfig_1 = sortConfig; _i < sortConfig_1.length; _i++) {
-            var _a = sortConfig_1[_i], column = _a.column, direction = _a.direction;
-            if (direction === "none") {
-                continue;
-            }
-            var dirMultiplier = direction === "asc" ? 1 : -1;
-            // Compare values for the current column
-            if (a[column] < b[column])
-                return -1 * dirMultiplier;
-            if (a[column] > b[column])
-                return 1 * dirMultiplier;
-            // If values are equal, continue to the next sorting rule
+    return [...data].sort((a, b) => {
+        for (const { column, direction } of active) {
+            const r = compareValues(a[column], b[column], direction);
+            if (r !== 0)
+                return r;
         }
-        return 0; // Return 0 if all sort conditions are equal
+        return 0;
     });
 }
-var calculateLeftOffset = function (columns, index) {
-    return columns.slice(0, index).reduce(function (sum, width) { return sum + width; }, 0);
+/** Theme-aware status palette per value — soft fill + semantic ink from `resolveStatusTone`. */
+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 = (0, tone_1.resolveSoftTone)(c, scale);
+        const solidRung = (0, filledSurface_1.solidFillRung)(scale, c.white, c.backgroundColor.main);
+        const solid = scale[solidRung];
+        return [
+            value,
+            {
+                solid,
+                soft: tone.bg,
+                text: tone.fg,
+                onSolid: (0, filledSurface_1.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 = (0, statusTone_1.resolveAvatarFill)(fill);
+    return {
+        solid,
+        soft,
+        text: (0, outlineRung_1.liftToContrast)(fill, (0, color_1.compositeOver)(soft, surface), accentText_1.AA_NORMAL_TEXT),
+        onSolid: (0, accentText_1.onFilled)(solid, white, black),
+    };
+};
+/** Deterministic, theme-aware color palette for groups + status pills. */
+function buildTablePalette(theme) {
+    const c = theme.colors;
+    const scales = [
+        c.primary,
+        c.semantic.success,
+        c.semantic.info,
+        c.semantic.warning,
+        c.teal,
+        c.blue,
+        c.pink,
+        c.semantic.error,
+        c.orange,
+        c.purple,
+    ];
+    return scales.map((scale) => {
+        const tone = (0, tone_1.resolveSoftTone)(c, scale);
+        const solidRung = (0, filledSurface_1.solidFillRung)(scale, c.white, c.backgroundColor.main);
+        const solid = scale[solidRung];
+        return {
+            solid,
+            soft: tone.bg,
+            text: tone.fg,
+            onSolid: (0, filledSurface_1.labelOnFill)(solid, c.white, c.black),
+        };
+    });
+}
+const hashKey = (value) => {
+    const s = String(value);
+    let h = 0;
+    for (let i = 0; i < s.length; i++)
+        h = (h * 31 + s.charCodeAt(i)) >>> 0;
+    return h;
+};
+/** Pick a deterministic palette color for a value, with optional consumer override hex. */
+function pickTableColor(value, palette, override, theme) {
+    var _a;
+    const white = theme ? theme.colors.white : accentText_1.DEFAULT_WHITE;
+    const black = theme ? theme.colors.black : accentText_1.DEFAULT_BLACK;
+    if (override) {
+        const surface = (_a = theme === null || theme === void 0 ? void 0 : theme.colors.background[50]) !== null && _a !== void 0 ? _a : accentText_1.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];
+}
+// Partitions rows by a column, preserving first-seen group order; groups by readable text, not object identity.
+function groupRows(data, groupBy) {
+    const order = [];
+    const map = new Map();
+    for (const row of data) {
+        const text = getStringValue(row[groupBy]);
+        const key = text === "" ? "—" : text;
+        if (!map.has(key)) {
+            map.set(key, []);
+            order.push(key);
+        }
+        map.get(key).push(row);
+    }
+    return order.map((value) => ({ value, label: String(value), rows: map.get(value) }));
+}
+const calculateLeftOffset = (columns, index) => {
+    return columns.slice(0, index).reduce((sum, width) => sum + width, 0);
 };
 exports.calculateLeftOffset = calculateLeftOffset;
-var extractTextFromReactNode = function (node) {
+const extractTextFromReactNode = (node) => {
     if (typeof node === "string" || typeof node === "number") {
         return String(node);
     }
@@ -81,33 +181,54 @@ var extractTextFromReactNode = function (node) {
         return node.map(extractTextFromReactNode).join(" ");
     }
     if (react_1.default.isValidElement(node)) {
-        var element = node;
+        const element = node;
         return extractTextFromReactNode(element.props.children);
     }
     return "";
 };
-var getStringValue = function (value) {
-    if (typeof value === "string" || typeof value === "number") {
+/** Best-effort readable text for an entity object (user/relation/option/etc.). */
+const objectToText = (o) => {
+    var _a, _b;
+    if (typeof o.label === "string" || typeof o.label === "number")
+        return String(o.label);
+    if (typeof o.name === "string" || typeof o.name === "number")
+        return String(o.name);
+    const first = (_a = o.first_name) !== null && _a !== void 0 ? _a : o.firstName;
+    const last = (_b = o.last_name) !== null && _b !== void 0 ? _b : o.lastName;
+    if (typeof first === "string" || typeof last === "string") {
+        return `${first !== null && first !== void 0 ? first : ""} ${last !== null && last !== void 0 ? last : ""}`.trim();
+    }
+    if (typeof o.full_name === "string")
+        return o.full_name;
+    if (typeof o.title === "string")
+        return o.title;
+    if (typeof o.company_name === "string")
+        return o.company_name;
+    if (typeof o.email === "string")
+        return o.email;
+    if (typeof o.value === "string" || typeof o.value === "number")
+        return String(o.value);
+    return "";
+};
+// Readable string for any cell value: primitives, React elements, entity objects, or arrays of those.
+const getStringValue = (value) => {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
         return String(value);
     }
     if (react_1.default.isValidElement(value)) {
         return extractTextFromReactNode(value);
     }
-    if (value && typeof value === "object") {
-        var o = value;
-        if (typeof o.label === "string" || typeof o.label === "number") {
-            return String(o.label);
-        }
-        if (typeof o.name === "string" || typeof o.name === "number") {
-            return String(o.name);
-        }
+    if (Array.isArray(value)) {
+        return value.map(getStringValue).filter((s) => s !== "").join(", ");
+    }
+    if (typeof value === "object") {
+        return objectToText(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.
 function normalizeTableCellValue(value) {
     if (value === null || value === undefined)
         return "";
@@ -119,37 +240,23 @@ function normalizeTableCellValue(value) {
     if (react_1.default.isValidElement(value)) {
         return value;
     }
-    if (typeof value === "object") {
-        var o = value;
-        if (typeof o.label === "string" || typeof o.label === "number") {
-            return String(o.label);
-        }
-        if (typeof o.name === "string" || typeof o.name === "number") {
-            return String(o.name);
-        }
-        if (typeof o.title === "string")
-            return o.title;
-        if (typeof o.company_name === "string")
-            return o.company_name;
-        return "";
-    }
-    return String(value);
+    return getStringValue(value);
 }
-var searchAndSortData = function (data, searchValues) {
-    var filteredData = data.filter(function (item) {
-        return Object.keys(searchValues).every(function (key) {
-            var searchValue = searchValues[key].toLowerCase();
-            var itemValue = getStringValue(item[key]).toLowerCase();
+const searchAndSortData = (data, searchValues) => {
+    const filteredData = data.filter((item) => {
+        return Object.keys(searchValues).every((key) => {
+            const searchValue = searchValues[key].toLowerCase();
+            const itemValue = getStringValue(item[key]).toLowerCase();
             return itemValue.includes(searchValue);
         });
     });
-    return filteredData.sort(function (a, b) {
-        var aMatchCount = 0;
-        var bMatchCount = 0;
-        Object.keys(searchValues).forEach(function (key) {
-            var searchValue = searchValues[key].toLowerCase();
-            var aValue = getStringValue(a[key]).toLowerCase();
-            var bValue = getStringValue(b[key]).toLowerCase();
+    return filteredData.sort((a, b) => {
+        let aMatchCount = 0;
+        let bMatchCount = 0;
+        Object.keys(searchValues).forEach((key) => {
+            const searchValue = searchValues[key].toLowerCase();
+            const aValue = getStringValue(a[key]).toLowerCase();
+            const bValue = getStringValue(b[key]).toLowerCase();
             if (aValue === searchValue)
                 aMatchCount++;
             if (bValue === searchValue)
@@ -164,40 +271,17 @@ var searchAndSortData = function (data, searchValues) {
 };
 exports.searchAndSortData = searchAndSortData;
 function debounce(func, delay) {
-    var timer;
-    return function () {
-        var args = [];
-        for (var _i = 0; _i < arguments.length; _i++) {
-            args[_i] = arguments[_i];
-        }
+    let timer;
+    return (...args) => {
         clearTimeout(timer);
-        timer = setTimeout(function () {
-            func.apply(void 0, args);
+        timer = setTimeout(() => {
+            func(...args);
         }, delay);
     };
 }
-function useDebounce(callback, delay) {
-    var callbackRef = (0, react_1.useRef)(callback);
-    var timerRef = (0, react_1.useRef)(null);
-    (0, react_1.useEffect)(function () {
-        callbackRef.current = callback;
-    }, [callback]);
-    var debouncedFn = (0, react_1.useCallback)(function () {
-        var args = [];
-        for (var _i = 0; _i < arguments.length; _i++) {
-            args[_i] = arguments[_i];
-        }
-        if (timerRef.current) {
-            clearTimeout(timerRef.current);
-        }
-        timerRef.current = setTimeout(function () {
-            callbackRef.current.apply(callbackRef, args);
-        }, delay);
-    }, [delay]);
-    return debouncedFn;
-}
-var pageSizeCalculation = function (records) {
-    var pageSize = [5, 10];
+exports.useDebounce = useDebounce_1.useDebouncedCallback;
+const pageSizeCalculation = (records) => {
+    const pageSize = [5, 10];
     if (records > 100) {
         return [25, 50, 100];
     }
@@ -207,18 +291,19 @@ var pageSizeCalculation = function (records) {
     return pageSize;
 };
 exports.pageSizeCalculation = pageSizeCalculation;
-var TableCellCalculation = function (_a) {
-    var _b, _c, _d, _e, _f, _g, _h, _j, _k;
-    var isFrozen = _a.isFrozen, columnWidths = _a.columnWidths, headerIndex = _a.headerIndex, isCheckbox = _a.isCheckbox, header = _a.header, row = _a.row, freezedBgColor = _a.freezedBgColor, index = _a.index, theme = _a.theme;
-    var leftOffset = isFrozen
+const TableCellCalculation = ({ isFrozen, columnWidths, headerIndex, isCheckbox, header, row, freezedBgColor, index, theme, }) => {
+    var _a, _b, _c, _d;
+    const leftOffset = isFrozen
         ? (0, exports.calculateLeftOffset)(columnWidths, headerIndex) + (isCheckbox ? 50 : 0)
         : 0;
-    var cellBgColor = undefined;
-    var cellTextColor = undefined;
-    if ((_b = row.cellStyle) === null || _b === void 0 ? void 0 : _b[header.id]) {
+    const cellStyles = row.cellStyle;
+    const rowStyle = row.rowStyle;
+    let cellBgColor = undefined;
+    let cellTextColor = undefined;
+    if (cellStyles === null || cellStyles === void 0 ? void 0 : cellStyles[header.id]) {
         cellBgColor =
-            (_e = (_d = (_c = row.cellStyle) === null || _c === void 0 ? void 0 : _c[header.id]) === null || _d === void 0 ? void 0 : _d.bg) !== null && _e !== void 0 ? _e : theme.colors.backgroundColor.light;
-        cellTextColor = (_h = (_g = (_f = row.cellStyle) === null || _f === void 0 ? void 0 : _f[header.id]) === null || _g === void 0 ? void 0 : _g.color) !== null && _h !== void 0 ? _h : undefined;
+            (_b = (_a = cellStyles[header.id]) === null || _a === void 0 ? void 0 : _a.bg) !== null && _b !== void 0 ? _b : theme.colors.backgroundColor.light;
+        cellTextColor = (_d = (_c = cellStyles[header.id]) === null || _c === void 0 ? void 0 : _c.color) !== null && _d !== void 0 ? _d : undefined;
     }
     else if (isFrozen) {
         cellBgColor = freezedBgColor !== null && freezedBgColor !== void 0 ? freezedBgColor : undefined;
@@ -227,35 +312,27 @@ var TableCellCalculation = function (_a) {
     else if (index % 2 === 1) {
         cellBgColor = theme.colors.backgroundColor.light;
     }
-    var rowBgColor = undefined;
-    var rowTextColor = undefined;
-    if (row.rowStyle) {
-        rowBgColor = (_j = row.rowStyle) === null || _j === void 0 ? void 0 : _j.bg;
-        rowTextColor = (_k = row.rowStyle) === null || _k === void 0 ? void 0 : _k.color;
+    let rowBgColor = undefined;
+    let rowTextColor = undefined;
+    if (rowStyle) {
+        rowBgColor = rowStyle.bg;
+        rowTextColor = rowStyle.color;
     }
-    return { leftOffset: leftOffset, cellBgColor: cellBgColor, rowBgColor: rowBgColor, cellTextColor: cellTextColor, rowTextColor: rowTextColor };
+    return { leftOffset, cellBgColor, rowBgColor, cellTextColor, rowTextColor };
 };
 exports.TableCellCalculation = TableCellCalculation;
-/**
- * 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.
 function globalSearchFilter(data, query) {
     if (!query.trim())
         return data;
-    var lowerQuery = query.toLowerCase();
-    return data.filter(function (item) {
-        return Object.values(item).some(function (val) {
-            if (val === null ||
-                val === undefined ||
-                typeof val === "object" ||
-                typeof val === "function") {
-                return false;
-            }
-            return String(val).toLowerCase().includes(lowerQuery);
-        });
-    });
+    const lowerQuery = query.toLowerCase();
+    return data.filter((item) => Object.values(item).some((val) => {
+        if (val === null ||
+            val === undefined ||
+            typeof val === "object" ||
+            typeof val === "function") {
+            return false;
+        }
+        return String(val).toLowerCase().includes(lowerQuery);
+    }));
 }

package/dist/Utils/tabular.d.ts

@@ -0,0 +1,30 @@
+/** One spreadsheet cell; `null` and `undefined` write an empty cell. */
+export type TabularCell = string | number | boolean | null | undefined;
+interface TabularColumnBase<Row, K extends keyof Row> {
+    /** Row field the cell reads, the same `key` a table column uses. */
+    readonly key: K;
+    /** Text of the header line. */
+    readonly header: string;
+    /** Turns the field into a cell; required when the field is not a scalar. */
+    readonly format?: (value: Row[K], row: Row) => TabularCell;
+    /** Default true: formula-like text gets a leading `'` so it is shown, not run. */
+    readonly escapeFormulas?: boolean;
+}
+/** One exported column; `format` is required when the field is not a scalar. */
+export type TabularColumn<Row> = {
+    [K in keyof Row & string]: Row[K] extends TabularCell ? TabularColumnBase<Row, K> : TabularColumnBase<Row, K> & {
+        readonly format: (value: Row[K], row: Row) => TabularCell;
+    };
+}[keyof Row & string];
+/** Options for `toCsv`. */
+export interface ToCsvOptions {
+    /** Prepends a UTF-8 byte-order mark so Excel reads non-ASCII. Default false. */
+    readonly bom?: boolean;
+}
+/** RFC 4180 CSV: header line, then one CRLF-separated line per row. */
+export declare function toCsv<Row extends object>(rows: readonly Row[], columns: readonly TabularColumn<Row>[], { bom }?: ToCsvOptions): string;
+/** Replaces path and reserved characters with `-`; caps at 80 characters, keeping the extension. */
+export declare function safeFileName(fileName: string): string;
+/** Saves `blob` as `safeFileName(fileName)`, then revokes its object URL. */
+export declare function downloadBlob(blob: Blob, fileName: string): void;
+export {};

package/dist/Utils/tabular.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCsv = toCsv;
+exports.safeFileName = safeFileName;
+exports.downloadBlob = downloadBlob;
+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. */
+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. */
+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. */
+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);
+}