portal-mojo 0.1.0

package/src/client/model.ts

@@ -0,0 +1,227 @@
+// defineModel — the definition layer that replaces web-mojo's Model/Collection
+// classes (src/core/Model.js, Collection.js, models/*.js).
+//
+// A model is a typed, STATELESS definition: endpoint + forms + permissions +
+// actions, plus hooks bound to that endpoint. TanStack Query owns every byte
+// of fetched data and all reactivity — the attribute stores, change events,
+// dirty tracking, request dedup/abort/rate-limiting that Model/Collection
+// implemented by hand are exactly the machinery Query already provides.
+// Nothing here holds row data; there is ONE ownership system.
+//
+// Cache keys deliberately match the generic hooks (hooks.ts):
+//   list  → [endpoint, params]        (useModelList)
+//   one   → [endpoint, 'one', id]     (useModel)
+// so ModelTable, GroupSwitcher and model-defined hooks share one cache and
+// one invalidation root ([endpoint]).
+//
+// POST_SAVE_ACTIONS (django-mojo mojo/models/rest.py on_rest_save): an action
+// is a key in the save body — `POST <endpoint>/<id>` `{disable: {...}}` — the
+// backend saves any plain fields first, then runs `on_action_<key>(value)`.
+// The response is either the refreshed record (handler returned nothing) or
+// an action-specific payload (e.g. User.revoke_sessions → {status, message}).
+// Which one is DECLARED per action (`response: 'row' | 'payload'`), never
+// sniffed from the body — the resp.data heuristics class ends at this layer.
+import { useMutation, useQueryClient, type QueryClient } from '@tanstack/react-query';
+import { mojoCall, mojoDelete, mojoGet, mojoSave, type Envelope } from './client';
+import { withFreshAuth } from './auth';
+import { useModel, useModelList } from './hooks';
+import type { ModelForm, Params } from './types';
+
+/** Permission spec as useCan/Guarded/hasPermission accept: one name, or any-of list. */
+export type PermSpec = string | string[];
+
+export interface ModelActionDef {
+    /** Save-body key for the POST; defaults to the action's name in the map. */
+    key?: string;
+    /** UI gate for offering the action (useCan). The server stays authoritative. */
+    permissions?: PermSpec;
+    /**
+     * 'row' (default): the backend answers with the refreshed record → written
+     * through to the one-record cache. 'payload': the backend answers with an
+     * action-specific body → returned verbatim, caches invalidated only.
+     */
+    response?: 'row' | 'payload';
+}
+
+export interface ModelConfig<T> {
+    /** Singular slug ('user') — labels, export filenames, devtools. */
+    name: string;
+    /** REST collection endpoint ('/api/account/user'). */
+    endpoint: string;
+    /**
+     * UI permission gates by convention: view / manage / create / delete.
+     * Carried metadata — consumers fold them through useCan; the backend
+     * remains the authority on every request.
+     */
+    permissions?: Record<string, PermSpec>;
+    /** Named form configs (ADD_FORM/EDIT_FORM heritage) — plain data for ui. */
+    forms?: Record<string, ModelForm>;
+    /** The POST_SAVE_ACTIONS the backend RestMeta declares for this model. */
+    actions?: Record<string, ModelActionDef>;
+    /** Normalize/allowlist list params before they become a query key or request. */
+    normalizeListParams?: (params: Params) => Params;
+    /** Strip fields that must never enter Query or Mutation cache. */
+    sanitizeRow?(row: T): T;
+}
+
+export interface SaveVars {
+    /** null → create (POST collection); id → update (POST detail). */
+    id: number | string | null;
+    changes: Record<string, unknown>;
+}
+
+export interface ActionVars {
+    id: number | string;
+    /**
+     * The action's argument body — `{reason, note}` for disable, omitted for
+     * argument-less actions ({} is sent; handlers treat value as a dict).
+     */
+    payload?: unknown;
+}
+
+export interface ActionOutcome<T> {
+    /** The refreshed record, for `response: 'row'` actions; null otherwise. */
+    row: T | null;
+    /** The unwrapped envelope — message + any action-specific fields. */
+    body: Envelope;
+}
+
+export interface ModelDef<T extends { id: number | string }> {
+    name: string;
+    endpoint: string;
+    permissions: Record<string, PermSpec>;
+    forms: Record<string, ModelForm>;
+    actions: Record<string, ModelActionDef>;
+    normalizeListParams?: (params: Params) => Params;
+    sanitizeRow?(row: T): T;
+    /** Query-key builders — for targeted setQueryData/invalidate in app code. */
+    keys: {
+        root: readonly [string];
+        list: (params: Params) => readonly [string, Params];
+        one: (id: number | string) => readonly [string, 'one', number | string];
+    };
+    /** Server-driven list under the shared cache key (keepPreviousData). */
+    useList: (params?: Params, opts?: { enabled?: boolean }) => ReturnType<typeof useModelList<T>>;
+    /** One record; disabled while id is null. */
+    useOne: (id: number | string | null) => ReturnType<typeof useModel<T>>;
+    /** Create/update mutation. Write-through + invalidate. Rejects on failure. */
+    useSave: () => ReturnType<typeof useMutation<T, Error, SaveVars>>;
+    /** DELETE mutation; drops the one-record cache and invalidates lists. */
+    useDelete: () => ReturnType<typeof useMutation<void, Error, { id: number | string }>>;
+    /** Mutation for one declared POST_SAVE_ACTION. Throws on an undeclared name. */
+    useAction: (action: string) => ReturnType<typeof useMutation<ActionOutcome<T>, Error, ActionVars>>;
+    /**
+     * Imperative fetch through the query cache (Collection.fetchOne heritage):
+     * same key + fn as useOne, so it dedupes with mounted hooks and warms the
+     * cache for them. Rejects on failure (fetchOne's null-swallow is gone).
+     */
+    fetchOne: (qc: QueryClient, id: number | string) => Promise<T>;
+    /** Invalidate everything cached under this model's endpoint. */
+    invalidate: (qc: QueryClient) => Promise<void>;
+}
+
+export function defineModel<T extends { id: number | string }>(config: ModelConfig<T>): ModelDef<T> {
+    const { endpoint } = config;
+    const actions = config.actions ?? {};
+    const normalizeListParams = config.normalizeListParams;
+    const sanitizeRow = config.sanitizeRow;
+
+    const keys = {
+        root: [endpoint] as const,
+        list: (params: Params) => [
+            endpoint,
+            normalizeListParams ? normalizeListParams(params) : params,
+        ] as const,
+        one: (id: number | string) => [endpoint, 'one', id] as const,
+    };
+
+    return {
+        name: config.name,
+        endpoint,
+        permissions: config.permissions ?? {},
+        forms: config.forms ?? {},
+        actions,
+        normalizeListParams,
+        sanitizeRow,
+        keys,
+
+        useList: (params: Params = {}, opts: { enabled?: boolean } = {}) => {
+            const safeParams = normalizeListParams ? normalizeListParams(params) : params;
+            return useModelList<T>(endpoint, safeParams, { ...opts, sanitizeRow });
+        },
+
+        useOne: (id: number | string | null) => useModel<T>(endpoint, id, sanitizeRow),
+
+        useSave: () => {
+            const qc = useQueryClient();
+            return useMutation({
+                mutationFn: async ({ id, changes }: SaveVars) => {
+                    const row = await withFreshAuth(() => mojoSave<T>(endpoint, id, changes));
+                    return sanitizeRow ? sanitizeRow(row) : row;
+                },
+                onSuccess: (row) => {
+                    // The response body is the server-authoritative record —
+                    // paint it immediately, then let invalidation re-sort and
+                    // re-filter the lists.
+                    qc.setQueryData(keys.one(row.id), row);
+                    void qc.invalidateQueries({ queryKey: keys.root });
+                },
+            });
+        },
+
+        useDelete: () => {
+            const qc = useQueryClient();
+            return useMutation({
+                mutationFn: ({ id }: { id: number | string }) => mojoDelete(endpoint, id),
+                onSuccess: (_res, { id }) => {
+                    qc.removeQueries({ queryKey: keys.one(id) });
+                    void qc.invalidateQueries({ queryKey: keys.root });
+                },
+            });
+        },
+
+        useAction: (action: string) => {
+            const def = actions[action];
+            if (!def) {
+                // Programmer error — fail loud at the call site, not with a
+                // request the backend will ignore (dev-throw policy).
+                throw new Error(`defineModel(${config.name}): unknown action "${action}" — declare it in the model's actions map`);
+            }
+            const bodyKey = def.key ?? action;
+            const returnsRow = (def.response ?? 'row') === 'row';
+            const qc = useQueryClient();
+            return useMutation({
+                mutationFn: async ({ id, payload = {} }: ActionVars): Promise<ActionOutcome<T>> => {
+                    const body = await withFreshAuth(() => mojoCall(`${endpoint}/${id}`, {
+                        method: 'POST',
+                        body: { [bodyKey]: payload },
+                    }));
+                    const row = returnsRow ? (body.data as T) : null;
+                    const safeRow = row && sanitizeRow ? sanitizeRow(row) : row;
+                    // MutationCache retains the entire outcome. Keep its two
+                    // row representations consistent so body.data cannot hold
+                    // the original unsanitized record beside `row`.
+                    const safeBody = safeRow && sanitizeRow
+                        ? { ...body, data: safeRow }
+                        : body;
+                    return { row: safeRow, body: safeBody };
+                },
+                onSuccess: (outcome, { id }) => {
+                    if (outcome.row) qc.setQueryData(keys.one(id), outcome.row);
+                    void qc.invalidateQueries({ queryKey: keys.root });
+                },
+            });
+        },
+
+        fetchOne: (qc: QueryClient, id: number | string) =>
+            qc.fetchQuery({
+                queryKey: keys.one(id),
+                queryFn: async () => {
+                    const row = await mojoGet<T>(endpoint, id);
+                    return sanitizeRow ? sanitizeRow(row) : row;
+                },
+            }),
+
+        invalidate: (qc: QueryClient) => qc.invalidateQueries({ queryKey: keys.root }),
+    };
+}

package/src/client/params.ts

@@ -0,0 +1,292 @@
+// The table params store — THE architecture rule from the port extraction:
+// one flat params object is the single source of truth for search, sort,
+// filters, and paging. It drives the server query, the URL, the pills, and
+// preset matching. Components read it; nothing else owns table state.
+//
+// Two wire shapes carried over from web-mojo:
+//   · multi-value filters collapse to `field__in=a,b` (single value → `field`)
+//   · a daterange is the TRIPLE `dr_field` / `dr_start` / `dr_end`, so only
+//     one range can be active at a time — by construction, not by convention.
+import { useCallback, useMemo, useRef } from 'react';
+import { useSearchParams } from 'react-router-dom';
+import type { Params } from './types';
+
+export interface ActiveFilter {
+    /** Pill identity: the param key for plain filters, the field for ranges. */
+    id: string;
+    kind: 'plain' | 'daterange';
+    value?: string;
+    start?: string;
+    end?: string;
+}
+
+export interface TableParams {
+    search: string;
+    sort: string; // 'field' | '-field' | ''
+    page: number; // 1-based
+    size: number;
+}
+
+export interface TableParamsApi extends TableParams {
+    wire: Params;
+    activeFilters: ActiveFilter[];
+    filterValue(key: string): string | undefined;
+    dateRange(): { field: string; start: string; end: string } | null;
+    setSearch(term: string): void;
+    cycleSort(field: string): void;
+    setFilter(key: string, value: string | string[] | null): void;
+    setDateRange(field: string, start: string, end: string): void;
+    removeFilter(f: ActiveFilter): void;
+    applyPreset(params: Record<string, string>): void;
+    presetActive(params: Record<string, string>): boolean;
+    clearFilters(): void;
+    setPage(page: number): void;
+    setSize(size: number): void;
+    /**
+     * One-shot rehydrate from a persisted view blob. Precedence is URL >
+     * saved (a shared link always wins) — except `size`, a per-user viewing
+     * preference the URL merely echoes, where saved wins. `sort: ''` (sort
+     * deliberately off) is not persisted, so it can't be restored — the
+     * default reappears; documented trade for clean URLs.
+     */
+    applySaved(saved: { sort?: string; size?: number; search?: string; filters?: Record<string, string> }): void;
+}
+
+const RESERVED = new Set(['search', 'sort', 'page', 'size']);
+const RANGE_KEYS = new Set(['dr_field', 'dr_start', 'dr_end']);
+export const PAGE_SIZES = [5, 10, 25, 50, 100];
+const DEFAULT_SIZE = 10;
+
+// ── Host-page params (not filters) ────────────────────────────────────
+// Every non-reserved URL key is treated as a Django lookup — that is what
+// lets any `field__lookup=` filter deep-link without a client-side schema.
+// But the PAGE around a table can own query params too (the component
+// playground's `?demo=`, a tab id, a wizard step). Those are not filters:
+// they must never reach the wire (`?demo=filters` on /api/group is a lookup
+// on a field that does not exist — django-mojo raises, the mock returns zero
+// rows), never render as a pill, and never break preset matching — yet they
+// MUST survive every params write, since each write rebuilds the whole query
+// string. Apps declare them once, at module load, before any table renders.
+const NON_FILTER = new Set<string>();
+
+/** Declare URL params the host page owns, so tables carry them without filtering on them. */
+export function registerNonFilterParams(...keys: string[]): void {
+    for (const key of keys) NON_FILTER.add(key);
+}
+
+// ── View persistence (WM-035 port) ────────────────────────────────────
+// One localStorage blob per table remembers how each user likes it — sort,
+// page size, search + filters (field__in / dr_* triples verbatim), hidden
+// columns. Versioned; anything unparseable or from another schema version is
+// discarded AND cleared. Storage access always degrades to a no-op (privacy
+// mode / SSR). Precedence on restore is URL > saved > defaults — except
+// `size`, a per-user viewing preference the URL merely echoes, where saved
+// wins (web-mojo's documented rule).
+
+export interface PersistedTableState {
+    v: 2;
+    sort?: string;
+    size?: number;
+    search?: string;
+    filters?: Record<string, string>;
+    hidden?: string[];
+}
+
+const PERSIST_PREFIX = 'mojo:tableview:';
+
+function persistStorage(): Storage | null {
+    try {
+        const ls = globalThis.localStorage;
+        if (ls && typeof ls.getItem === 'function') return ls;
+    } catch { /* access denied */ }
+    return null;
+}
+
+export function readTableState(key: string): PersistedTableState | null {
+    const store = persistStorage();
+    if (!store) return null;
+    let raw: string | null;
+    try { raw = store.getItem(PERSIST_PREFIX + key); } catch { return null; }
+    if (!raw) return null;
+    let parsed: unknown;
+    try { parsed = JSON.parse(raw); } catch { clearTableState(key); return null; }
+    if (!parsed || typeof parsed !== 'object' || (parsed as PersistedTableState).v !== 2) {
+        clearTableState(key);
+        return null;
+    }
+    return parsed as PersistedTableState;
+}
+
+export function writeTableState(key: string, state: PersistedTableState): void {
+    const store = persistStorage();
+    if (!store) return;
+    try { store.setItem(PERSIST_PREFIX + key, JSON.stringify(state)); } catch { /* quota / denied */ }
+}
+
+export function clearTableState(key: string): void {
+    const store = persistStorage();
+    if (!store) return;
+    try { store.removeItem(PERSIST_PREFIX + key); } catch { /* denied */ }
+}
+
+export function useTableParams(
+    defaults: Partial<TableParams> = {},
+    defaultFilters: Readonly<Record<string, string>> = {},
+): TableParamsApi {
+    const [sp, setSp] = useSearchParams();
+    // Defaults seed only the untouched route. Once this table writes params,
+    // an intentionally empty filter set must stay empty ("Clear all" must
+    // not immediately resurrect a route default).
+    const wroteParams = useRef(false);
+
+    const filters = useMemo(() => {
+        // Defaults are real params-store state: shared URLs override them,
+        // and applySaved() overwrites them when no URL key is present.
+        // This is the same URL > persisted > defaults precedence as sort.
+        const out: Record<string, string> = wroteParams.current ? {} : { ...defaultFilters };
+        for (const [key, value] of sp.entries()) {
+            if (!RESERVED.has(key) && !NON_FILTER.has(key)) out[key] = value;
+        }
+        return out;
+    }, [sp, defaultFilters]);
+
+    const state = useMemo<TableParams>(() => ({
+        search: sp.get('search') ?? defaults.search ?? '',
+        sort: sp.get('sort') ?? defaults.sort ?? '-created',
+        page: Math.max(1, Number(sp.get('page') ?? 1)),
+        size: Number(sp.get('size') ?? defaults.size ?? DEFAULT_SIZE),
+    }), [sp, defaults.search, defaults.sort, defaults.size]);
+
+    const write = useCallback((next: TableParams, nextFilters: Record<string, string>) => {
+        wroteParams.current = true;
+        const out = new URLSearchParams();
+        if (next.search) out.set('search', next.search);
+        if (next.sort) out.set('sort', next.sort);
+        if (next.page > 1) out.set('page', String(next.page));
+        if (next.size !== DEFAULT_SIZE) out.set('size', String(next.size));
+        for (const [key, value] of Object.entries(nextFilters)) {
+            if (value !== '') out.set(key, value);
+        }
+        // Host-page params ride through untouched — not ours to filter on,
+        // not ours to drop either.
+        for (const key of NON_FILTER) {
+            const carried = sp.get(key);
+            if (carried != null) out.set(key, carried);
+        }
+        setSp(out, { replace: true });
+    }, [setSp, sp]);
+
+    const wire = useMemo<Params>(() => ({
+        start: (state.page - 1) * state.size,
+        size: state.size,
+        sort: state.sort || undefined,
+        search: state.search || undefined,
+        ...filters,
+    }), [state, filters]);
+
+    /** Collapse the daterange triple back into one pill entry. */
+    const activeFilters = useMemo<ActiveFilter[]>(() => {
+        const out: ActiveFilter[] = [];
+        if (filters.dr_field) {
+            out.push({
+                id: filters.dr_field,
+                kind: 'daterange',
+                start: filters.dr_start ?? '',
+                end: filters.dr_end ?? '',
+            });
+        }
+        for (const [key, value] of Object.entries(filters)) {
+            if (RANGE_KEYS.has(key)) continue;
+            out.push({ id: key, kind: 'plain', value });
+        }
+        return out;
+    }, [filters]);
+
+    const setFilter = useCallback((key: string, value: string | string[] | null) => {
+        const next = { ...filters };
+        // A field never carries both its plain and its __in form.
+        const field = key.replace(/__in$/, '');
+        delete next[field];
+        delete next[`${field}__in`];
+        delete next[key];
+        if (value == null || value === '' || (Array.isArray(value) && value.length === 0)) {
+            write({ ...state, page: 1 }, next);
+            return;
+        }
+        if (Array.isArray(value)) {
+            if (value.length === 1) next[field] = value[0]!;
+            else next[`${field}__in`] = value.join(',');
+        } else {
+            next[key] = value;
+        }
+        write({ ...state, page: 1 }, next);
+    }, [filters, state, write]);
+
+    return {
+        ...state,
+        wire,
+        activeFilters,
+        filterValue: (key) => filters[key],
+        dateRange: () => filters.dr_field
+            ? { field: filters.dr_field, start: filters.dr_start ?? '', end: filters.dr_end ?? '' }
+            : null,
+        setSearch: (term) => write({ ...state, search: term, page: 1 }, filters),
+        // 3-way header sort: asc → desc → off (web-mojo's explicit cycle).
+        cycleSort: (field) => {
+            const next = state.sort === field ? `-${field}` : state.sort === `-${field}` ? '' : field;
+            write({ ...state, sort: next, page: 1 }, filters);
+        },
+        setFilter,
+        setDateRange: (field, start, end) => {
+            const next = { ...filters };
+            delete next.dr_field; delete next.dr_start; delete next.dr_end;
+            if (field && (start || end)) {
+                next.dr_field = field;
+                if (start) next.dr_start = start;
+                if (end) next.dr_end = end;
+            }
+            write({ ...state, page: 1 }, next);
+        },
+        removeFilter: (f) => {
+            const next = { ...filters };
+            if (f.kind === 'daterange') {
+                delete next.dr_field; delete next.dr_start; delete next.dr_end;
+            } else {
+                delete next[f.id];
+            }
+            write({ ...state, page: 1 }, next);
+        },
+        // Presets are mutually-exclusive bundles; active state is DERIVED by
+        // matching, never stored.
+        applyPreset: (params) => {
+            const active = Object.entries(params).every(([k, v]) => filters[k] === v);
+            write({ ...state, page: 1 }, active ? {} : { ...params });
+        },
+        presetActive: (params) => {
+            const keys = Object.keys(params);
+            if (keys.length === 0) return Object.keys(filters).length === 0;
+            return keys.every((k) => filters[k] === params[k]);
+        },
+        clearFilters: () => write({ ...state, search: '', page: 1 }, {}),
+        setPage: (page) => write({ ...state, page }, filters),
+        setSize: (size) => write({ ...state, size, page: 1 }, filters),
+        applySaved: (saved) => {
+            const urlKeys = new Set(Array.from(sp.keys()));
+            const next = { ...state };
+            // A persisted filter set replaces defaults wholesale; only keys
+            // explicitly present in the URL survive above it. This makes an
+            // intentionally saved "all tickets" view beat a route default.
+            const nextFilters: Record<string, string> = {};
+            for (const [key, value] of Object.entries(filters)) {
+                if (urlKeys.has(key)) nextFilters[key] = value;
+            }
+            if (saved.sort !== undefined && saved.sort !== '' && !urlKeys.has('sort')) next.sort = saved.sort;
+            if (saved.search !== undefined && !urlKeys.has('search')) next.search = saved.search;
+            if (saved.size !== undefined && PAGE_SIZES.includes(saved.size)) next.size = saved.size;
+            for (const [key, value] of Object.entries(saved.filters ?? {})) {
+                if (!urlKeys.has(key)) nextFilters[key] = value;
+            }
+            write(next, nextFilters);
+        },
+    };
+}