@benjosivo/table-query 1.0.4 → 1.2.0

package/dist/react/formatting.js

@@ -0,0 +1,423 @@
+// ==================== CONDITIONAL FORMATTING ====================
+//
+// Pure module: the only React import is a type, so tsc elides it and the compiled
+// `dist/react/formatting.js` runs in plain Node. Keep it that way — it is what makes
+// the evaluator verifiable without a test runner or a DOM.
+/** Operator metadata: the single source of truth for the editor's <select> and its operand inputs. */
+export const FORMATTING_OPERATORS = [
+    { value: '=', label: '= (égal)', arity: 1 },
+    { value: '!=', label: '≠ (différent)', arity: 1 },
+    { value: '>', label: '> (supérieur)', arity: 1 },
+    { value: '>=', label: '≥ (supérieur ou égal)', arity: 1 },
+    { value: '<', label: '< (inférieur)', arity: 1 },
+    { value: '<=', label: '≤ (inférieur ou égal)', arity: 1 },
+    { value: 'between', label: 'Entre (bornes incluses)', arity: 2 },
+    { value: 'in', label: 'Dans la liste', arity: 'n' },
+    { value: 'contains', label: 'Contient', arity: 1 },
+    { value: 'notContains', label: 'Ne contient pas', arity: 1 },
+    { value: 'startsWith', label: 'Commence par', arity: 1 },
+    { value: 'endsWith', label: 'Finit par', arity: 1 },
+    { value: 'isNull', label: 'Est vide (NULL)', arity: 0 },
+    { value: 'isNotNull', label: "N'est pas vide", arity: 0 },
+];
+const OPERATOR_SET = new Set(FORMATTING_OPERATORS.map((o) => o.value));
+export function operatorArity(operator) {
+    return FORMATTING_OPERATORS.find((o) => o.value === operator)?.arity ?? 1;
+}
+// ==================== COERCION ====================
+//
+// Values come straight from MySQL: DECIMAL/BIGINT arrive as strings, DATE/DATETIME as
+// Date objects (or ISO strings with dateStrings: true), TINYINT(1) as 0/1.
+const NUMERIC = /^[+-]?\d+(?:[.,]\d+)?$/;
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ISO_LIKE = /^\d{4}-\d{2}-\d{2}([T ]|$)/;
+function isBlank(v) {
+    return v === null || v === undefined;
+}
+function toNumber(v) {
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? v : null;
+    if (typeof v === 'boolean')
+        return v ? 1 : 0;
+    if (typeof v !== 'string')
+        return null;
+    const s = v.trim();
+    // '' and '12 rue de la Paix' are deliberately NOT numbers.
+    if (!s || !NUMERIC.test(s))
+        return null;
+    return Number(s.replace(',', '.'));
+}
+function toDate(v) {
+    if (v instanceof Date)
+        return Number.isNaN(v.getTime()) ? null : { t: v.getTime(), dayOnly: false };
+    if (typeof v !== 'string')
+        return null;
+    const s = v.trim();
+    const m = DATE_ONLY.exec(s);
+    // 'YYYY-MM-DD' must mean LOCAL midnight: new Date('2024-01-05') is UTC midnight,
+    // which lands on the 4th for anyone west of Greenwich.
+    if (m)
+        return { t: new Date(+m[1], +m[2] - 1, +m[3]).getTime(), dayOnly: true };
+    const t = Date.parse(s);
+    return Number.isNaN(t) ? null : { t, dayOnly: false };
+}
+function toText(v) {
+    return (v instanceof Date ? v.toISOString() : String(v)).trim().toLocaleLowerCase();
+}
+function toBool(v) {
+    if (typeof v === 'boolean')
+        return v;
+    if (typeof v === 'number')
+        return v !== 0;
+    if (typeof v !== 'string')
+        return null;
+    const s = v.trim().toLowerCase();
+    if (['1', 'true', 'oui', 'vrai', 'y', 'o'].includes(s))
+        return true;
+    if (['0', 'false', 'non', 'faux', 'n'].includes(s))
+        return false;
+    return null;
+}
+function startOfDay(t) {
+    const d = new Date(t);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+function sign(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Three-way compare. Returns null when the two operands cannot be compared at all,
+ * which callers treat as "does not match" (except '!=', where it means "different").
+ */
+export function compareValues(cell, operand, valueType = 'auto') {
+    if (valueType === 'number') {
+        const a = toNumber(cell);
+        const b = toNumber(operand);
+        return a === null || b === null ? null : sign(a, b);
+    }
+    if (valueType === 'boolean') {
+        const a = toBool(cell);
+        const b = toBool(operand);
+        return a === null || b === null ? null : sign(Number(a), Number(b));
+    }
+    if (valueType === 'date') {
+        const a = toDate(cell);
+        const b = toDate(operand);
+        if (!a || !b)
+            return null;
+        return b.dayOnly ? sign(startOfDay(a.t), b.t) : sign(a.t, b.t);
+    }
+    if (valueType === 'string') {
+        return toText(cell).localeCompare(toText(operand));
+    }
+    // 'auto', in this exact order.
+    // 1. A real Date on either side wins — that is unambiguous.
+    if (cell instanceof Date || operand instanceof Date) {
+        const a = toDate(cell);
+        const b = toDate(operand);
+        if (a && b)
+            return b.dayOnly ? sign(startOfDay(a.t), b.t) : sign(a.t, b.t);
+    }
+    // 2. Both numeric → numbers. Note this makes '007' equal to '7'; use valueType:'string'
+    //    for reference codes and postcodes.
+    const na = toNumber(cell);
+    const nb = toNumber(operand);
+    if (na !== null && nb !== null)
+        return sign(na, nb);
+    // 3. Both date-parseable and at least one ISO-shaped. Runs after the numeric step,
+    //    so '2024' stays a number rather than becoming a year.
+    if ((typeof cell === 'string' && ISO_LIKE.test(cell.trim())) || (typeof operand === 'string' && ISO_LIKE.test(operand.trim()))) {
+        const a = toDate(cell);
+        const b = toDate(operand);
+        if (a && b)
+            return b.dayOnly ? sign(startOfDay(a.t), b.t) : sign(a.t, b.t);
+    }
+    // 4. Text, case-insensitive.
+    return toText(cell).localeCompare(toText(operand));
+}
+/** 'between' accepts [a, b] and {min, max} — the same vocabulary buildWhereClause already speaks. */
+function asPair(value) {
+    if (Array.isArray(value))
+        return [value[0], value[1]];
+    if (value !== null && typeof value === 'object' && 'min' in value) {
+        return [value.min, value.max];
+    }
+    return [undefined, undefined];
+}
+/** 'in' accepts an array or a comma-separated string (what the editor's input produces). */
+function asList(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === 'string') {
+        return value
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    return [value];
+}
+// ==================== RULE EVALUATION ====================
+export function evaluateRule(rule, row) {
+    // Guard on key presence, NOT on `row[col] === undefined`. A typo'd column must never
+    // match anything — otherwise `isNull` would repaint the entire table.
+    if (!rule || typeof rule.column !== 'string' || !(rule.column in row))
+        return false;
+    const cell = row[rule.column];
+    const vt = rule.valueType ?? 'auto';
+    // Operators with their own null semantics come first.
+    switch (rule.operator) {
+        case 'isNull':
+            return isBlank(cell) || String(cell).trim() === '';
+        case 'isNotNull':
+            return !isBlank(cell) && String(cell).trim() !== '';
+        case 'notContains':
+            return isBlank(cell) ? true : !toText(cell).includes(toText(rule.value));
+        case '!=': {
+            if (isBlank(cell))
+                return !isBlank(rule.value);
+            const c = compareValues(cell, rule.value, vt);
+            return c === null ? true : c !== 0;
+        }
+    }
+    // Every remaining operator is false on a NULL cell.
+    if (isBlank(cell))
+        return false;
+    switch (rule.operator) {
+        case '=': {
+            return compareValues(cell, rule.value, vt) === 0;
+        }
+        case '<': {
+            const c = compareValues(cell, rule.value, vt);
+            return c !== null && c < 0;
+        }
+        case '<=': {
+            const c = compareValues(cell, rule.value, vt);
+            return c !== null && c <= 0;
+        }
+        case '>': {
+            const c = compareValues(cell, rule.value, vt);
+            return c !== null && c > 0;
+        }
+        case '>=': {
+            const c = compareValues(cell, rule.value, vt);
+            return c !== null && c >= 0;
+        }
+        case 'between': {
+            let [lo, hi] = asPair(rule.value);
+            if (lo === undefined || hi === undefined)
+                return false;
+            // Tolerate swapped bounds rather than silently matching nothing.
+            if ((compareValues(lo, hi, vt) ?? 0) > 0)
+                [lo, hi] = [hi, lo];
+            const a = compareValues(cell, lo, vt);
+            const b = compareValues(cell, hi, vt);
+            return a !== null && b !== null && a >= 0 && b <= 0;
+        }
+        case 'in': {
+            return asList(rule.value).some((v) => compareValues(cell, v, vt) === 0);
+        }
+        case 'contains':
+            return toText(cell).includes(toText(rule.value));
+        case 'startsWith':
+            return toText(cell).startsWith(toText(rule.value));
+        case 'endsWith':
+            return toText(cell).endsWith(toText(rule.value));
+    }
+    return false;
+}
+// ==================== MERGE ====================
+function joinClass(a, b) {
+    if (!a)
+        return b || undefined;
+    if (!b)
+        return a;
+    const seen = new Set(a.split(/\s+/).filter(Boolean));
+    for (const c of b.split(/\s+/).filter(Boolean))
+        seen.add(c);
+    return Array.from(seen).join(' ');
+}
+/** null = the "row" bucket; otherwise the column names this rule paints. */
+function resolveTargets(rule, columns) {
+    const target = rule.target ?? 'row';
+    if (target === 'row')
+        return null;
+    if (target === 'cell')
+        return [rule.column];
+    if (Array.isArray(target))
+        return target.filter((c) => columns.has(c));
+    return null;
+}
+export function computeRowFormatting(row, rules, columns, callbacks, rowIndex = 0) {
+    let rowStyle;
+    let rowClassName;
+    const cellStyles = {};
+    const columnSet = new Set(columns);
+    // stopIfTrue freezes exactly the buckets a rule wrote to: a row rule never freezes
+    // cell rules and vice-versa.
+    let rowStopped = false;
+    const stoppedCells = new Set();
+    for (const rule of rules) {
+        if (!rule || rule.enabled === false)
+            continue;
+        const targets = resolveTargets(rule, columnSet);
+        if (targets === null) {
+            if (rowStopped)
+                continue;
+        }
+        else if (targets.length === 0 || targets.every((c) => stoppedCells.has(c))) {
+            continue;
+        }
+        if (!evaluateRule(rule, row))
+            continue;
+        if (targets === null) {
+            // Later rule wins per CSS property.
+            if (rule.style)
+                rowStyle = { ...rowStyle, ...rule.style };
+            rowClassName = joinClass(rowClassName, rule.className);
+            if (rule.stopIfTrue)
+                rowStopped = true;
+        }
+        else {
+            for (const col of targets) {
+                if (stoppedCells.has(col))
+                    continue;
+                const prev = cellStyles[col];
+                cellStyles[col] = {
+                    style: rule.style ? { ...prev?.style, ...rule.style } : prev?.style,
+                    className: joinClass(prev?.className, rule.className),
+                };
+                if (rule.stopIfTrue)
+                    stoppedCells.add(col);
+            }
+        }
+    }
+    // Callbacks get the last word and are deliberately NOT subject to stopIfTrue —
+    // they are the escape hatch, so they must always be able to override.
+    const fromRowCb = callbacks?.getRowFormatting?.(row, rowIndex);
+    if (fromRowCb) {
+        if (fromRowCb.style)
+            rowStyle = { ...rowStyle, ...fromRowCb.style };
+        rowClassName = joinClass(rowClassName, fromRowCb.className);
+    }
+    if (callbacks?.getCellFormatting) {
+        for (const col of columns) {
+            const fromCellCb = callbacks.getCellFormatting(col, row[col], row, rowIndex);
+            if (!fromCellCb)
+                continue;
+            const prev = cellStyles[col];
+            cellStyles[col] = {
+                style: fromCellCb.style ? { ...prev?.style, ...fromCellCb.style } : prev?.style,
+                className: joinClass(prev?.className, fromCellCb.className),
+            };
+        }
+    }
+    return { rowStyle, rowClassName, cellStyles };
+}
+/**
+ * Formatting for a whole page of rows. Returns `null` when there is nothing to do, so the
+ * feature costs one boolean check for everyone who does not use it.
+ */
+export function computeTableFormatting(items, rules, columns, callbacks) {
+    const hasRules = rules.some((r) => r && r.enabled !== false);
+    if (!hasRules && !callbacks?.getRowFormatting && !callbacks?.getCellFormatting)
+        return null;
+    return items.map((row, i) => computeRowFormatting(row, rules, columns, callbacks, i));
+}
+// ==================== SANITIZING ====================
+let idCounter = 0;
+/** Stable-enough id for a rule that arrived without one. randomUUID needs a secure context. */
+export function newRuleId() {
+    const uuid = typeof globalThis.crypto !== 'undefined' ? globalThis.crypto.randomUUID?.() : undefined;
+    return uuid ?? `r${Date.now().toString(36)}${(idCounter++).toString(36)}${Math.random().toString(36).slice(2, 7)}`;
+}
+function sanitizeStyle(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+        if (typeof v === 'string' || typeof v === 'number')
+            out[k] = v;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/**
+ * Coerce an untrusted rule list (an API payload or localStorage) into valid rules.
+ * Anything malformed is dropped, never thrown on — a bad stored rule must not take the
+ * table down.
+ */
+export function sanitizeFormattingRules(input) {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    for (const raw of input) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const r = raw;
+        if (typeof r.column !== 'string' || !r.column)
+            continue;
+        if (typeof r.operator !== 'string' || !OPERATOR_SET.has(r.operator))
+            continue;
+        let target = 'row';
+        if (r.target === 'cell' || r.target === 'row')
+            target = r.target;
+        else if (Array.isArray(r.target))
+            target = r.target.filter((c) => typeof c === 'string');
+        out.push({
+            id: typeof r.id === 'string' && r.id ? r.id : newRuleId(),
+            label: typeof r.label === 'string' ? r.label : undefined,
+            column: r.column,
+            operator: r.operator,
+            value: r.value,
+            valueType: r.valueType === 'string' || r.valueType === 'number' || r.valueType === 'date' || r.valueType === 'boolean'
+                ? r.valueType
+                : 'auto',
+            target,
+            style: sanitizeStyle(r.style),
+            className: typeof r.className === 'string' ? r.className : undefined,
+            stopIfTrue: r.stopIfTrue === true,
+            enabled: r.enabled !== false,
+        });
+    }
+    return out;
+}
+export function styleToEditorState(style) {
+    const { backgroundColor, color, fontWeight, fontStyle, ...rest } = (style ?? {});
+    return {
+        background: typeof backgroundColor === 'string' ? backgroundColor : undefined,
+        color: typeof color === 'string' ? color : undefined,
+        bold: fontWeight === 'bold' || fontWeight === 700 || fontWeight === '700',
+        italic: fontStyle === 'italic',
+        rest: rest,
+    };
+}
+export function editorStateToStyle(state) {
+    const style = { ...state.rest };
+    if (state.background)
+        style.backgroundColor = state.background;
+    if (state.color)
+        style.color = state.color;
+    if (state.bold)
+        style.fontWeight = 'bold';
+    if (state.italic)
+        style.fontStyle = 'italic';
+    return Object.keys(style).length ? style : undefined;
+}
+/** Human-readable one-liner for a rule, used when it carries no explicit label. */
+export function describeRule(rule) {
+    const op = FORMATTING_OPERATORS.find((o) => o.value === rule.operator);
+    const arity = op?.arity ?? 1;
+    let operand = '';
+    if (arity === 2) {
+        const [lo, hi] = asPair(rule.value);
+        operand = ` ${String(lo ?? '')} et ${String(hi ?? '')}`;
+    }
+    else if (arity === 'n') {
+        operand = ` ${asList(rule.value).join(', ')}`;
+    }
+    else if (arity === 1) {
+        operand = ` ${String(rule.value ?? '')}`;
+    }
+    const target = rule.target === 'cell' ? 'cellule' : Array.isArray(rule.target) ? rule.target.join(', ') : 'ligne';
+    return `${rule.column} ${op?.label.split(' ')[0] ?? rule.operator}${operand} → ${target}`;
+}

package/dist/react/index.d.ts

@@ -6,4 +6,11 @@ export type { PaginationProps } from './Pagination.js';
 export { useDataTable } from './useDataTable.js';
 export { FilterModal } from './FilterModal.js';
 export { FilterPanel } from './FilterPanel.js';
-export type { DataTableProps, FetchParams, FetchResult, FieldTypeInfo, FilterConfig, FilterFieldConfig, ParamFilter, SelectionColumnPosition, SortDirection, } from './types.js';
+export { FormattingModal } from './FormattingModal.js';
+export type { FormattingModalProps } from './FormattingModal.js';
+export { FormattingToolbar } from './FormattingToolbar.js';
+export type { FormattingToolbarProps } from './FormattingToolbar.js';
+export { useFormattingRules } from './useFormattingRules.js';
+export type { UseFormattingRulesOptions, UseFormattingRulesResult } from './useFormattingRules.js';
+export { FORMATTING_OPERATORS, compareValues, computeRowFormatting, computeTableFormatting, describeRule, evaluateRule, operatorArity, sanitizeFormattingRules, } from './formatting.js';
+export type { DataTableProps, FetchParams, FetchResult, FieldTypeInfo, CellFormatting, FilterConfig, FilterFieldConfig, FormattingOperator, FormattingRule, FormattingRuleSource, FormattingStyle, FormattingTarget, FormattingValueType, GetCellFormatting, GetRowFormatting, ParamFilter, RowFormatting, SelectionColumnPosition, SortDirection, } from './types.js';

package/dist/react/index.js

@@ -4,3 +4,7 @@ export { Pagination } from './Pagination.js';
 export { useDataTable } from './useDataTable.js';
 export { FilterModal } from './FilterModal.js';
 export { FilterPanel } from './FilterPanel.js';
+export { FormattingModal } from './FormattingModal.js';
+export { FormattingToolbar } from './FormattingToolbar.js';
+export { useFormattingRules } from './useFormattingRules.js';
+export { FORMATTING_OPERATORS, compareValues, computeRowFormatting, computeTableFormatting, describeRule, evaluateRule, operatorArity, sanitizeFormattingRules, } from './formatting.js';

package/dist/react/types.d.ts

@@ -1,3 +1,4 @@
+import type { CSSProperties } from 'react';
 export type SortDirection = 'ASC' | 'DESC';
 /** Matches the "fieldType" info your API already returns per column. */
 export type FieldTypeName = 'DATE' | 'DATETIME' | 'TIMESTAMP' | 'JSON' | 'BLOB' | 'FILE' | string;
@@ -23,6 +24,8 @@ export interface FetchResult<T> {
     filtre?: FilterConfig;
     /** Key to re-fetch filter definitions later via a dedicated endpoint. */
     cleRecupFiltre?: string;
+    /** Conditional formatting rules defined by the API (see FormattingRule). */
+    formattingRules?: FormattingRule[];
 }
 export type FilterFieldType = 'MULTISELECT' | 'UNGROUP_MULTISELECT' | 'SLIDER' | 'DATE' | 'DATETIME' | 'HIDE';
 export interface FilterFieldConfig {
@@ -37,6 +40,47 @@ export type ParamFilter = {
 export type FilterConfig = Record<string, FilterFieldConfig>;
 /** Where the selection (checkbox) column is inserted among the visible columns. */
 export type SelectionColumnPosition = number | 'start' | 'end';
+export type FormattingOperator = '=' | '!=' | '<' | '<=' | '>' | '>=' | 'between' | 'in' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'isNull' | 'isNotNull';
+/** What a rule paints: the whole row (default), the tested column's cell, or a given list of columns. */
+export type FormattingTarget = 'row' | 'cell' | string[];
+/** How the two operands are compared. 'auto' infers it from the values (see README). */
+export type FormattingValueType = 'auto' | 'string' | 'number' | 'date' | 'boolean';
+export interface FormattingStyle {
+    /** Inline style — the package ships no CSS, so this is the path that works with no setup. */
+    style?: CSSProperties;
+    /** Class added to the <tr> (target 'row') or to the <td> (target 'cell' | string[]). */
+    className?: string;
+}
+export interface FormattingRule extends FormattingStyle {
+    /** Stable id, needed by the editor to reorder/disable. Generated when missing. */
+    id?: string;
+    /** Free-form label shown in the editor; a summary is generated when missing. */
+    label?: string;
+    /** Name of the tested column (a key of the row objects), not its position. */
+    column: string;
+    operator: FormattingOperator;
+    /** Operand(s): a scalar, [min, max] or {min, max} for 'between', an array for 'in', unused for isNull/isNotNull. */
+    value?: unknown;
+    valueType?: FormattingValueType;
+    /** Defaults to 'row'. */
+    target?: FormattingTarget;
+    /** Stop evaluating later rules for the targets this rule wrote to. */
+    stopIfTrue?: boolean;
+    /** false keeps the rule in the list without applying it. Defaults to true. */
+    enabled?: boolean;
+}
+export interface CellFormatting extends FormattingStyle {
+}
+export interface RowFormatting {
+    rowStyle?: CSSProperties;
+    rowClassName?: string;
+    /** Keyed by column NAME — never by the positional index of fieldsType/paramFilter. */
+    cellStyles: Record<string, CellFormatting>;
+}
+/** Which layer a rule came from: the app's props, the API payload, or the end user's editor. */
+export type FormattingRuleSource = 'props' | 'server' | 'user';
+export type GetRowFormatting<T> = (row: T, rowIndex: number) => CellFormatting | null | undefined;
+export type GetCellFormatting<T> = (column: string, value: any, row: T, rowIndex: number) => CellFormatting | null | undefined;
 export interface DataTableProps<T extends Record<string, any>> {
     /** Called every time the table needs data (page change, sort, filter, page size). */
     fetchData: (params: FetchParams) => Promise<FetchResult<T> | null>;
@@ -64,4 +108,19 @@ export interface DataTableProps<T extends Record<string, any>> {
     selectedIds?: any[];
     /** Called on every selection change, with the selected ids and the matching rows (same shape as onRowClick). */
     onSelectionChange?: (ids: any[], rows: T[]) => void;
+    /** Conditional formatting rules set by the app — the lowest-priority layer. */
+    formattingRules?: FormattingRule[];
+    /** Escape hatch for logic spanning several columns. Applied last, after every rule. */
+    getRowFormatting?: GetRowFormatting<T>;
+    getCellFormatting?: GetCellFormatting<T>;
+    /** Show the toolbar and its formatting button (the end-user editor). Default false. */
+    formattingEditor?: boolean;
+    /** When set, the user's rules are saved to / reloaded from localStorage under this key. */
+    formattingStorageKey?: string;
+    /** Called on every change to the user's rules, so the host can persist them server-side. */
+    onFormattingRulesChange?: (rules: FormattingRule[]) => void;
+    /** Rehydrate the user's rules from your own backend — takes precedence over localStorage. */
+    initialUserFormattingRules?: FormattingRule[];
+    /** Label of the toolbar button. Default 'Mise en forme'. */
+    formattingButtonLabel?: string;
 }

package/dist/react/useDataTable.d.ts

@@ -1,4 +1,4 @@
-import type { DataTableProps, FieldTypeInfo, FilterConfig, SortDirection, ParamFilter } from './types.js';
+import type { DataTableProps, FieldTypeInfo, FilterConfig, FormattingRule, SortDirection, ParamFilter } from './types.js';
 export declare function useDataTable<T extends Record<string, any>>({ fetchData, advancedFilters, rowsPerPageOptions, defaultRowsPerPage, fetchFilterConfig, selectedIds: controlledSelectedIds, onSelectionChange, }: Pick<DataTableProps<T>, 'fetchData' | 'advancedFilters' | 'rowsPerPageOptions' | 'defaultRowsPerPage' | 'fetchFilterConfig' | 'selectedIds' | 'onSelectionChange'>): {
     items: T[];
     count: number;
@@ -13,6 +13,7 @@ export declare function useDataTable<T extends Record<string, any>>({ fetchData,
     sortDirection: SortDirection;
     filters: Record<string, unknown>;
     filterConfig: FilterConfig | null;
+    serverFormattingRules: FormattingRule[];
     selectedIds: any[];
     selectedRows: T[];
     isRowSelected: (row: T) => boolean;

package/dist/react/useDataTable.js

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { sanitizeFormattingRules } from './formatting.js';
 import { getRowId, selectionKey } from './utils.js';
 export function useDataTable({ fetchData, advancedFilters, rowsPerPageOptions = [10, 25, 50, 100, 250, 500, 1000], defaultRowsPerPage = 100, fetchFilterConfig, selectedIds: controlledSelectedIds, onSelectionChange, }) {
     const [items, setItems] = useState([]);
@@ -13,6 +14,7 @@ export function useDataTable({ fetchData, advancedFilters, rowsPerPageOptions =
     const [filters, setFilters] = useState({});
     const [filterConfig, setFilterConfig] = useState(null);
     const [cleRecupFiltre, setCleRecupFiltre] = useState();
+    const [serverFormattingRules, setServerFormattingRules] = useState([]);
     // Guards against a slow, stale request overwriting a newer one.
     const requestId = useRef(0);
     // Selection is uncontrolled unless the parent passes `selectedIds`.
@@ -59,6 +61,8 @@ export function useDataTable({ fetchData, advancedFilters, rowsPerPageOptions =
                 setFilterConfig(result.filtre);
             if (result.cleRecupFiltre)
                 setCleRecupFiltre(result.cleRecupFiltre);
+            if (result.formattingRules)
+                setServerFormattingRules(sanitizeFormattingRules(result.formattingRules));
         }
         finally {
             if (id === requestId.current)
@@ -183,6 +187,7 @@ export function useDataTable({ fetchData, advancedFilters, rowsPerPageOptions =
         sortDirection,
         filters,
         filterConfig,
+        serverFormattingRules,
         selectedIds,
         selectedRows,
         isRowSelected,

package/dist/react/useFormattingRules.d.ts

@@ -0,0 +1,34 @@
+import type { FormattingRule } from './types.js';
+export interface UseFormattingRulesOptions {
+    /** Rules set by the app (lowest priority). */
+    propsRules?: FormattingRule[];
+    /** Rules sent by the API. */
+    serverRules?: FormattingRule[];
+    /** When set, the user's rules persist in localStorage under this key. */
+    storageKey?: string;
+    /** Rehydrate the user's rules from your own backend — wins over localStorage. */
+    initialUserRules?: FormattingRule[];
+    /** Called on every change to the user's rules. */
+    onChange?: (rules: FormattingRule[]) => void;
+}
+export interface UseFormattingRulesResult {
+    /** Merged and ordered props -> server -> user, ready for <Table formattingRules>. */
+    rules: FormattingRule[];
+    /** The user-editable layer. */
+    userRules: FormattingRule[];
+    /** The props + server layers, read-only in the editor. */
+    inherited: FormattingRule[];
+    /** Ids of inherited rules the user has switched off. */
+    disabledIds: string[];
+    addRule: (rule: FormattingRule) => void;
+    updateRule: (id: string, patch: Partial<FormattingRule>) => void;
+    removeRule: (id: string) => void;
+    moveRule: (id: string, delta: 1 | -1) => void;
+    setRuleDisabled: (id: string, disabled: boolean) => void;
+    resetUserRules: () => void;
+}
+/**
+ * Owns the three formatting layers and their persistence. Lives in a hook rather than in
+ * `DataTable` so that a host composing `useDataTable` + `Table` by hand can reuse it.
+ */
+export declare function useFormattingRules({ propsRules, serverRules, storageKey, initialUserRules, onChange, }: UseFormattingRulesOptions): UseFormattingRulesResult;