@benjosivo/table-query 1.0.4 → 1.2.0

package/dist/react/useFormattingRules.js

@@ -0,0 +1,121 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { newRuleId, sanitizeFormattingRules } from './formatting.js';
+/** Namespaced so a storage key can't collide with the host app's own localStorage entries. */
+const STORAGE_PREFIX = 'tableQuery:formatting:';
+const STORAGE_VERSION = 1;
+function serialize(rules, disabled) {
+    return JSON.stringify({ v: STORAGE_VERSION, rules, disabled });
+}
+/** Inherited rules need a stable id even when the source didn't give them one. */
+function withFallbackIds(rules, source) {
+    if (!rules || rules.length === 0)
+        return [];
+    return rules.map((r, i) => (r.id ? r : { ...r, id: `${source}:${i}` }));
+}
+/**
+ * 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 function useFormattingRules({ propsRules, serverRules, storageKey, initialUserRules, onChange, }) {
+    const [userRules, setUserRules] = useState(() => (initialUserRules ? sanitizeFormattingRules(initialUserRules) : []));
+    const [disabledIds, setDisabledIds] = useState([]);
+    const fullKey = storageKey ? `${STORAGE_PREFIX}${storageKey}` : undefined;
+    // Hydration is STATE, not a ref: both effects run in the same commit on mount, so a ref
+    // flipped by the read effect would already read true in the write effect below — which
+    // would rewrite [] over the rules just loaded and fire a spurious onChange([]).
+    const [hydrated, setHydrated] = useState(false);
+    // What is already in storage, so an unchanged value never triggers a write or an onChange.
+    const lastWritten = useRef(null);
+    // Read post-mount, never in the useState initializer: with SSR the server renders no user
+    // rules, so reading during the first render would cause a hydration mismatch on the styles.
+    useEffect(() => {
+        // Baseline = the state as it stands before hydration, so the first write-effect pass is
+        // a no-op. Without it, mounting with nothing stored would fire onChange([]) and wipe the
+        // rules of a host that persists them server-side.
+        lastWritten.current = serialize(userRules, disabledIds);
+        if (initialUserRules || !fullKey || typeof window === 'undefined') {
+            setHydrated(true);
+            return;
+        }
+        try {
+            const raw = window.localStorage.getItem(fullKey);
+            if (raw) {
+                const parsed = JSON.parse(raw);
+                // An unknown version is ignored rather than migrated; the next write replaces it.
+                if (parsed && parsed.v === STORAGE_VERSION) {
+                    const rules = sanitizeFormattingRules(parsed.rules);
+                    const disabled = Array.isArray(parsed.disabled) ? parsed.disabled.filter((x) => typeof x === 'string') : [];
+                    setUserRules(rules);
+                    setDisabledIds(disabled);
+                    lastWritten.current = serialize(rules, disabled);
+                }
+            }
+        }
+        catch {
+            // SSR, Safari private mode, blocked storage, corrupted JSON — all non-fatal.
+        }
+        setHydrated(true);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [fullKey]);
+    useEffect(() => {
+        if (!hydrated)
+            return;
+        const serialized = serialize(userRules, disabledIds);
+        // Nothing actually changed (the mount pass, or a re-render): don't write, don't notify.
+        if (lastWritten.current === serialized)
+            return;
+        lastWritten.current = serialized;
+        if (fullKey && typeof window !== 'undefined') {
+            try {
+                window.localStorage.setItem(fullKey, serialized);
+            }
+            catch {
+                // Quota exceeded or storage blocked: the rules still work for this session.
+            }
+        }
+        onChange?.(userRules);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [userRules, disabledIds, fullKey, hydrated]);
+    const inherited = useMemo(() => [...withFallbackIds(propsRules, 'props'), ...withFallbackIds(serverRules, 'server')], [propsRules, serverRules]);
+    /**
+     * Precedence: props -> server -> user. Evaluation order IS precedence order, so a later
+     * rule wins per CSS property and an earlier `stopIfTrue` can block a later layer.
+     */
+    const rules = useMemo(() => {
+        const disabled = new Set(disabledIds);
+        return [...inherited, ...userRules].filter((r) => r.enabled !== false && !(r.id && disabled.has(r.id)));
+    }, [inherited, userRules, disabledIds]);
+    const addRule = useCallback((rule) => {
+        setUserRules((prev) => [...prev, { ...rule, id: rule.id || newRuleId() }]);
+    }, []);
+    const updateRule = useCallback((id, patch) => {
+        setUserRules((prev) => prev.map((r) => (r.id === id ? { ...r, ...patch } : r)));
+    }, []);
+    const removeRule = useCallback((id) => {
+        setUserRules((prev) => prev.filter((r) => r.id !== id));
+    }, []);
+    const moveRule = useCallback((id, delta) => {
+        setUserRules((prev) => {
+            const i = prev.findIndex((r) => r.id === id);
+            const j = i + delta;
+            if (i < 0 || j < 0 || j >= prev.length)
+                return prev;
+            const next = [...prev];
+            [next[i], next[j]] = [next[j], next[i]];
+            return next;
+        });
+    }, []);
+    const setRuleDisabled = useCallback((id, disabled) => {
+        setDisabledIds((prev) => {
+            const has = prev.includes(id);
+            if (disabled === has)
+                return prev;
+            return disabled ? [...prev, id] : prev.filter((x) => x !== id);
+        });
+    }, []);
+    const resetUserRules = useCallback(() => {
+        setUserRules([]);
+        setDisabledIds([]);
+    }, []);
+    return { rules, userRules, inherited, disabledIds, addRule, updateRule, removeRule, moveRule, setRuleDisabled, resetUserRules };
+}

package/dist/react/utils.d.ts

@@ -8,3 +8,11 @@ export declare function truncatedJSON(value: unknown, maxLen?: number): string;
 export declare function getRowId(row: Record<string, any> | undefined): any;
 /** Ids come from the data (numbers, strings, ...) and can be compared to values given by the parent, so normalize them. */
 export declare function selectionKey(id: any): string;
+/**
+ * Column names of a table: the keys of the first row, falling back to the filter
+ * definitions when there is no data. Shared by `Table` and the formatting editor so the
+ * two can't drift apart.
+ */
+export declare function columnNamesOf(items: Record<string, any>[], paramFilter?: {
+    nom: string;
+}[]): string[];

package/dist/react/utils.js

@@ -49,3 +49,13 @@ export function getRowId(row) {
 export function selectionKey(id) {
     return String(id);
 }
+/**
+ * Column names of a table: the keys of the first row, falling back to the filter
+ * definitions when there is no data. Shared by `Table` and the formatting editor so the
+ * two can't drift apart.
+ */
+export function columnNamesOf(items, paramFilter) {
+    if (items[0])
+        return Object.keys(items[0]);
+    return paramFilter && paramFilter.length > 0 ? paramFilter.map((el) => el.nom) : [];
+}

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
 import type { CacheDeps, ParamFilterType, ReqTableQueryOptions, TableQueryDeps } from './types.js';
-export type { CacheDeps, ParamFilterType, ReqTableQueryOptions, TableQueryDeps } from './types.js';
+export type { CacheDeps, FormattingRuleInput, ParamFilterType, ReqTableQueryOptions, TableQueryDeps } from './types.js';
 /**
  * Creates the table-query module (router + query helpers) bound to this project's own
  * date formatting / route-wrapping / cache implementations. Nothing here is hardcoded to
@@ -11,8 +11,8 @@ export type { CacheDeps, ParamFilterType, ReqTableQueryOptions, TableQueryDeps }
 export declare function createTableQueryModule(deps: TableQueryDeps): {
     router: import("express-serve-static-core").Router;
     reqTableQuery: (opt: ReqTableQueryOptions) => Promise<{
-        error: string;
-        status: number;
+        error: string | undefined;
+        status: number | undefined;
         empty?: undefined;
         data?: undefined;
     } | {

package/dist/server/index.js

@@ -52,7 +52,7 @@ export function createTableQueryModule(deps) {
         sendFiltres();
     }
     async function reqTableQuery(opt) {
-        const { query, req, paramFilter, sort, argsQuery, keepCache = 5 * 60 * 1000 } = opt;
+        const { query, req, paramFilter, sort, argsQuery, formattingRules, keepCache = 5 * 60 * 1000 } = opt;
         if (!req.body && !req.query) {
             return { error: `req.query or req.body is missing`, status: 400 };
         }
@@ -69,11 +69,27 @@ export function createTableQueryModule(deps) {
         // ── Paginated items ────────────────────────────────────────────────
         const itemsSql = `${query} ${whereClause} ORDER BY ${sorting} LIMIT ${limit < 0 ? 0 : limit} OFFSET ${offset < 0 ? 0 : offset}`;
         let { payload, status, error, empty } = await getDataFromQuery(itemsSql, argsQuery, cache ? keepCache : 0, cache);
+        // getDataFromQuery returns { status, error } with no payload when the query fails.
+        if (!payload)
+            return { error, status };
         payload.paramFilter = paramFilter
             ? paramFilter.map((param, i) => {
                 return { nom: payload.fieldsType[i].fieldName, type: param };
             })
             : [];
+        // Forwarded untouched — formatting is presentation, it never reaches the SQL.
+        // Resolved by column NAME against the very same source `paramFilter` is zipped against,
+        // so the two can't drift. Sent on every request (a few hundred bytes), not gated behind
+        // setFilter, so the client needs no extra round-trip.
+        if (formattingRules?.length) {
+            const names = new Set((payload.fieldsType ?? []).map((f) => f.fieldName));
+            const kept = formattingRules.filter((r) => r && typeof r.column === 'string' && names.has(r.column));
+            const dropped = formattingRules.length - kept.length;
+            // A bad column name is a presentation mistake: warn, don't take the table down.
+            if (dropped)
+                console.warn(`[table-query] ${dropped} règle(s) de mise en forme ignorée(s) : colonne inconnue.`);
+            payload.formattingRules = kept;
+        }
         if (empty)
             return { empty, data: payload };
         if (error && status)

package/dist/server/types.d.ts

@@ -1,5 +1,24 @@
 import type { Request, Response } from 'express';
 export type ParamFilterType = 'HIDE' | 'SLIDER' | 'DATE' | 'DATETIME' | 'UNGROUP_MULTISELECT' | 'MULTISELECT' | null | 'JSON' | 'FILE';
+/**
+ * Same shape as the React-side `FormattingRule`, but with no dependency on @types/react:
+ * the server only ever forwards these rules, it never evaluates them, and a server-only
+ * consumer must not be forced to install React's types to compile.
+ */
+export interface FormattingRuleInput {
+    id?: string;
+    label?: string;
+    /** Name of the tested column, matched against the query's own column names. */
+    column: string;
+    operator: string;
+    value?: unknown;
+    valueType?: 'auto' | 'string' | 'number' | 'date' | 'boolean';
+    target?: 'row' | 'cell' | string[];
+    style?: Record<string, string | number>;
+    className?: string;
+    stopIfTrue?: boolean;
+    enabled?: boolean;
+}
 export interface CacheDeps {
     getSQLCache: (key: string) => Promise<any>;
     setSQLCache: (key: string, value: any) => Promise<any>;
@@ -20,6 +39,9 @@ export interface ReqTableQueryOptions {
     argsQuery?: any[];
     /** How long (ms) a cached result stays valid. Only used when `useCache` resolves to true. */
     keepCache?: number;
+    /** Conditional formatting rules forwarded as-is to the client in `payload.formattingRules`.
+     *  Rules whose `column` matches no column of the query are dropped. */
+    formattingRules?: FormattingRuleInput[];
     /** Use the Redis cache for this call. Defaults to true if `deps.cache` was provided at
      * module creation, false otherwise. Pass `false` explicitly to always force a fresh query
      * even when the module has a cache configured (e.g. for a "live" screen). */

package/package.json

@@ -1,61 +1,61 @@
-{
-    "name": "@benjosivo/table-query",
-    "version": "1.0.4",
-    "description": "Table triable/filtrable/paginée : hook + composants React d'un côté (`/react`), logique SQL de pagination/tri/filtres côté serveur de l'autre (`/server`). Un projet peut n'utiliser qu'un des deux côtés.",
-    "keywords": [],
-    "homepage": "https://github.com/benjosivo/table-query#readme",
-    "bugs": {
-        "url": "https://github.com/benjosivo/table-query/issues"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/benjosivo/table-query.git"
-    },
-    "license": "ISC",
-    "author": "benjosivo",
-    "type": "module",
-    "exports": {
-        "./react": {
-            "types": "./dist/react/index.d.ts",
-            "default": "./dist/react/index.js"
-        },
-        "./server": {
-            "types": "./dist/server/index.d.ts",
-            "default": "./dist/server/index.js"
-        }
-    },
-    "main": "index.js",
-    "files": [
-        "dist"
-    ],
-    "scripts": {
-        "build": "tsc",
-        "prepublishOnly": "npm run build"
-    },
-    "dependencies": {
-        "@benjosivo/mysql": "^1.3.2",
-        "express": "^5.2.1"
-    },
-    "devDependencies": {
-        "@types/express": "^5.0.6",
-        "@types/react": "^18.0.0",
-        "typescript": "^5.4.0"
-    },
-    "peerDependencies": {
-        "react": "^18.0.0 || ^19.0.0"
-    },
-    "peerDependenciesMeta": {
-        "express": {
-            "optional": true
-        },
-        "react": {
-            "optional": true
-        },
-        "@benjosivo/mysql": {
-            "optional": true
-        }
-    },
-    "publishConfig": {
-        "registry": "https://registry.npmjs.org"
-    }
-}
+{
+    "name": "@benjosivo/table-query",
+    "version": "1.2.0",
+    "description": "Table triable/filtrable/paginée : hook + composants React d'un côté (`/react`), logique SQL de pagination/tri/filtres côté serveur de l'autre (`/server`). Un projet peut n'utiliser qu'un des deux côtés.",
+    "keywords": [],
+    "homepage": "https://github.com/benjosivo/table-query#readme",
+    "bugs": {
+        "url": "https://github.com/benjosivo/table-query/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/benjosivo/table-query.git"
+    },
+    "license": "ISC",
+    "author": "benjosivo",
+    "type": "module",
+    "exports": {
+        "./react": {
+            "types": "./dist/react/index.d.ts",
+            "default": "./dist/react/index.js"
+        },
+        "./server": {
+            "types": "./dist/server/index.d.ts",
+            "default": "./dist/server/index.js"
+        }
+    },
+    "main": "index.js",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "dependencies": {
+        "@benjosivo/mysql": "^1.3.2",
+        "express": "^5.2.1"
+    },
+    "devDependencies": {
+        "@types/express": "^5.0.6",
+        "@types/react": "^18.0.0",
+        "typescript": "^5.4.0"
+    },
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0"
+    },
+    "peerDependenciesMeta": {
+        "express": {
+            "optional": true
+        },
+        "react": {
+            "optional": true
+        },
+        "@benjosivo/mysql": {
+            "optional": true
+        }
+    },
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org"
+    }
+}