portal-mojo 0.1.0

package/src/ui/FormFields.tsx

@@ -0,0 +1,77 @@
+// Mini FormBuilder — the field-definition language ported as data → JSX.
+import { useEffect, useState, type ReactNode } from 'react';
+import type { Field, FormData } from '../client/types';
+import { modal } from './modal';
+import { SchemaFieldGrid, useSchemaFormState } from './schema-form-core';
+
+export type { Field, FormData } from '../client/types';
+export { SchemaSelect } from './schema-form-core';
+
+export function SchemaForm({ fields, initial = {}, submitText = 'Save', onSubmit, onCancel, onBusyChange }: {
+    fields: Field[];
+    initial?: FormData;
+    submitText?: string;
+    /** Return the authoritative saved owner row when the form contains File relations. */
+    onSubmit: (data: FormData) => unknown | Promise<unknown>;
+    onCancel?: () => void;
+    onBusyChange?: (busy: boolean) => void;
+}) {
+    const form = useSchemaFormState({ fields, initial, profile: 'schema-form' });
+    const [busy, setBusy] = useState(false);
+    useEffect(() => onBusyChange?.(busy || form.uploadPending), [busy, form.uploadPending, onBusyChange]);
+
+    const submit = async (event: React.FormEvent) => {
+        event.preventDefault();
+        const errors = form.validate();
+        if (Object.keys(errors).length) {
+            const first = form.visibleFields.find((field) => errors[field.name]);
+            if (first) form.focusField(first.name);
+            return;
+        }
+        if (form.uploadPending) return;
+        setBusy(true);
+        form.setFormError('');
+        const requested = form.payload();
+        try {
+            const row = await onSubmit(form.payload());
+            form.settleOwnerSave(row, false, requested);
+        } catch (error) {
+            form.settleOwnerSave(undefined, true, requested);
+            form.setFormError(error instanceof Error ? error.message : 'Save failed');
+        } finally {
+            setBusy(false);
+        }
+    };
+
+    return (
+        <form onSubmit={submit} noValidate>
+            {form.formError && <div className="form-alert">{form.formError}</div>}
+            <SchemaFieldGrid fields={fields} state={form} disabled={busy} />
+            <div className="modal-actions">
+                {onCancel && <button type="button" className="btn" disabled={busy || form.uploadPending} onClick={onCancel}>Cancel</button>}
+                <button type="submit" className="btn btn-primary" disabled={busy || form.uploadPending}>
+                    {busy ? 'Saving…' : submitText}
+                </button>
+            </div>
+        </form>
+    );
+}
+
+/** Awaitable form dialog: resolves the submitted data, or null on cancel. */
+export function formModal(opts: { title: string; fields: Field[]; initial?: FormData; submitText?: string; intro?: ReactNode }): Promise<FormData | null> {
+    let pending = false;
+    return modal.open<FormData>((close) => (
+        <div className="modal-pad">
+            <h2 className="modal-title">{opts.title}</h2>
+            {opts.intro && <div className="modal-message">{opts.intro}</div>}
+            <SchemaForm
+                fields={opts.fields}
+                initial={opts.initial}
+                submitText={opts.submitText}
+                onBusyChange={(busy) => { pending = busy; }}
+                onCancel={() => close(null as unknown as FormData)}
+                onSubmit={(data) => close(data)}
+            />
+        </div>
+    ), { canDismiss: () => !pending });
+}

package/src/ui/FormView.tsx

@@ -0,0 +1,360 @@
+// FormView — the inline-autosave form surface ("no save buttons"), ported
+// from web-mojo src/core/forms/FormView.js at behavior level:
+//   · the SchemaForm field language bound to a server row via defineModel
+//   · edits commit → 300ms batch → ONE save carrying only changed fields
+//   · per-field indicators: pending/saving spinner → saved flash → idle;
+//     errors pin with the server (or zod) message; failed batches revert
+//   · showWhen conditional fields (declarative rule or predicate)
+//   · permission tabsets via a REGISTRY (registerFormTabs) resolved
+//     fail-closed against me + the active-group member — replacing web-mojo's
+//     live-mutated permission arrays (User.js:160-347 / Member.js:80-170
+//     rebuildPermissions), per the do-not-recreate list.
+//
+// The machine itself lives in form-autosave.ts; this file renders it.
+import { useCallback, useMemo, useRef, useState, useSyncExternalStore, useContext } from 'react';
+import type { ReactNode } from 'react';
+import { hasPermission, useMe } from '../client/me';
+import { GroupContext } from '../client/group-context';
+import type { PermSpec, ModelDef, SaveVars } from '../client/model';
+import type { Field } from '../client/types';
+import { SchemaSelect } from './FormFields';
+import { Tabs } from './Tabs';
+import { emptyFieldValue, resolveFieldRenderer } from './field-registry';
+import { getPath } from './form-autosave';
+import type { FileFieldOwnerResult } from './FileField';
+import { toast } from './toast';
+import {
+    useFormAutosave,
+    type AutosaveBatchInfo,
+    type FieldStatus,
+    type FormAutosaveApi,
+} from './form-autosave';
+
+// ── Tabset registry ───────────────────────────────────────────────────
+// web-mojo extended permission tabsets by MUTATING cached arrays in place
+// (`arr.length = 0; arr.push(…)` + rebuildPermissions). Here tabs live in a
+// registry: register under a name once (or again — same-key tabs replace,
+// new keys append, mirroring registerPermissions' additive semantics), and
+// every FormView resolving that name re-renders via the subscription.
+
+export interface FormTab {
+    key: string;
+    label: ReactNode;
+    /** useCan-style gate (any-of array). Fail-closed like <Guarded>. */
+    permissions?: PermSpec;
+    fields: Field[];
+}
+
+const tabRegistry = new Map<string, FormTab[]>();
+let tabsVersion = 0;
+const tabListeners = new Set<() => void>();
+
+function bumpTabs(): void {
+    tabsVersion += 1;
+    for (const cb of tabListeners) cb();
+}
+
+/**
+ * Register (or extend) a named tabset. Tabs with a key already present
+ * REPLACE that tab (idempotent under HMR / re-registration); new keys append
+ * in call order — an app adds its own tab beside the framework's.
+ */
+export function registerFormTabs(name: string, tabs: FormTab[]): void {
+    const current = [...(tabRegistry.get(name) ?? [])];
+    for (const tab of tabs) {
+        const at = current.findIndex((t) => t.key === tab.key);
+        if (at >= 0) current[at] = tab;
+        else current.push(tab);
+    }
+    tabRegistry.set(name, current);
+    bumpTabs();
+}
+
+/** Snapshot copy — callers can never mutate the registry through it. */
+export function getFormTabs(name: string): FormTab[] {
+    return [...(tabRegistry.get(name) ?? [])];
+}
+
+export function subscribeFormTabs(cb: () => void): () => void {
+    tabListeners.add(cb);
+    return () => tabListeners.delete(cb);
+}
+
+export function formTabsVersion(): number {
+    return tabsVersion;
+}
+
+// One warn per unknown (name:type) — a config bug, not a render event.
+const warnedFieldTypes = new Set<string>();
+
+// ── FormView ──────────────────────────────────────────────────────────
+
+export interface FormViewProps<T extends { id: number | string }> {
+    /** The defineModel definition — its useSave carries the batch POST. */
+    model: Pick<ModelDef<T>, 'useSave'>;
+    /** The current server row this form edits. */
+    row: T;
+    /** Flat fields rendered above the tabset. */
+    fields?: Field[];
+    /** Permission tabset: a registry name (live) or inline tab defs. */
+    tabs?: string | FormTab[];
+    /** Batch window after the last commit. Default 300 (web-mojo parity). */
+    debounceMs?: number;
+    /** 'saved' flash duration. Default 1500. */
+    savedFlashMs?: number;
+    onSaved?: (info: AutosaveBatchInfo & { row: T }) => void;
+    onSaveError?: (info: AutosaveBatchInfo & { error: Error }) => void;
+    /** True while any FileField transfer is active. Owners can block dismissal. */
+    onPendingChange?: (pending: boolean) => void;
+    className?: string;
+}
+
+export function FormView<T extends { id: number | string }>(props: FormViewProps<T>) {
+    const { model, row, fields, tabs, debounceMs, savedFlashMs, onSaved, onSaveError, className } = props;
+    const save = model.useSave();
+
+    // Registry-named tabsets re-render on registration; inline defs pass through.
+    const version = useSyncExternalStore(subscribeFormTabs, formTabsVersion, formTabsVersion);
+    const allTabs = useMemo<FormTab[]>(
+        () => (typeof tabs === 'string' ? getFormTabs(tabs) : tabs ?? []),
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- version invalidates registry reads
+        [tabs, version],
+    );
+
+    // Tab permissions resolve fail-closed (Guarded semantics): hidden while
+    // `me` loads, while anonymous, and when the check fails. The member fold
+    // matches useCan — group `admin` never grants sys.*.
+    const { data: me } = useMe();
+    const member = useContext(GroupContext)?.member ?? null;
+    const visibleTabs = useMemo(
+        () => allTabs.filter((t) => !t.permissions || hasPermission(me ?? null, t.permissions, member)),
+        [allTabs, me, member],
+    );
+
+    // The machine spans EVERY field — flat + all tabs (visible or not), so a
+    // batch can carry fields from anywhere and tab switches lose nothing.
+    const allFields = useMemo(
+        () => [...(fields ?? []), ...allTabs.flatMap((t) => t.fields)],
+        [fields, allTabs],
+    );
+    const pendingFields = useRef(new Set<string>());
+    const [ownerResults, setOwnerResults] = useState<Record<string, FileFieldOwnerResult>>({});
+    const ownerGeneration = useRef(0);
+    const setUploadPending = useCallback((name: string, pending: boolean) => {
+        if (pending) pendingFields.current.add(name);
+        else pendingFields.current.delete(name);
+        props.onPendingChange?.(pendingFields.current.size > 0);
+    }, [props.onPendingChange]);
+    const publishOwnerResult = useCallback((names: string[], status: FileFieldOwnerResult['status'], changes: Record<string, unknown>, savedRow?: T) => {
+        const generation = ++ownerGeneration.current;
+        setOwnerResults((current) => ({
+            ...current,
+            ...Object.fromEntries(names.map((name) => [name, {
+                generation,
+                status,
+                requestedValue: getPath(changes, name),
+                ...(status === 'success' ? { authoritativeValue: getPath(savedRow, name) } : {}),
+            }])),
+        }));
+    }, []);
+
+    const form = useFormAutosave<T>({
+        fields: allFields,
+        row,
+        save: (changes) => save.mutateAsync({ id: row.id, changes } satisfies SaveVars),
+        debounceMs,
+        savedFlashMs,
+        onSaved: (info) => {
+            publishOwnerResult(info.fields, 'success', info.changes, info.row);
+            onSaved?.(info);
+        },
+        onSaveError: (info) => {
+            publishOwnerResult(info.fields, 'failed', info.changes);
+            // Unmissable failure (workspec): pinned field error + toast.
+            toast.error(info.error.message);
+            onSaveError?.(info);
+        },
+    });
+
+    return (
+        <div className={className ? `form-view ${className}` : 'form-view'}>
+            {fields && fields.length > 0 && (
+                <div className="form-grid">
+                    {fields.filter(form.visible).map((f) => <FieldRow key={f.name} field={f} form={form} ownerResult={ownerResults[f.name]} onPendingChange={setUploadPending} />)}
+                </div>
+            )}
+
+            {visibleTabs.length > 0 && (
+                <Tabs
+                    className="fv-tabs-shell"
+                    variant="underline-all"
+                    ariaLabel="Form sections"
+                    items={visibleTabs.map((tab) => ({
+                        key: tab.key,
+                        label: (
+                            <>
+                                {tab.label}
+                                {tab.fields.some((field) => form.status[field.name]?.status === 'error') && (
+                                    <span className="fv-tab-err" aria-label="Tab has an error" />
+                                )}
+                            </>
+                        ),
+                        panel: (
+                            <div className="form-grid">
+                                {tab.fields.filter(form.visible).map((field) => <FieldRow key={field.name} field={field} form={form} ownerResult={ownerResults[field.name]} onPendingChange={setUploadPending} />)}
+                            </div>
+                        ),
+                    }))}
+                />
+            )}
+        </div>
+    );
+}
+
+// ── Field row ─────────────────────────────────────────────────────────
+
+/** The label-inline status slot (FieldStatusManager's label-inline strategy). */
+function StatusIcon({ st }: { st: FieldStatus | undefined }) {
+    switch (st?.status) {
+        case 'dirty':
+            return <span className="fv-status"><span className="fv-dot" title="Unsaved edit" /></span>;
+        case 'pending':
+        case 'saving':
+            return <span className="fv-status"><span className="fv-spinner" role="status" aria-label="Saving" /></span>;
+        case 'saved':
+            return <span className="fv-status"><i className="bi bi-check-circle-fill fv-saved" aria-label="Saved" /></span>;
+        case 'error':
+            return <span className="fv-status"><i className="bi bi-exclamation-circle-fill fv-error-ico" title={st.error} /></span>;
+        default:
+            return <span className="fv-status" />;
+    }
+}
+
+function FieldRow({ field, form, ownerResult, onPendingChange }: { field: Field; form: FormAutosaveApi; ownerResult?: FileFieldOwnerResult; onPendingChange: (name: string, pending: boolean) => void }) {
+    const st = form.status[field.name];
+    const error = st?.status === 'error' ? st.error : undefined;
+    const value = form.values[field.name];
+
+    const labelSlot: ReactNode = (
+        <span className="field-label fv-label">
+            <span>{field.label}{field.required && <em> *</em>}</span>
+            <StatusIcon st={st} />
+        </span>
+    );
+    const footSlot: ReactNode = (
+        <>
+            {error && <span className="field-error">{error}</span>}
+            {field.help && !error && <span className="field-help">{field.help}</span>}
+        </>
+    );
+
+    if (field.type === 'switch') {
+        return (
+            <div className={field.columns === 6 ? 'col-6' : 'col-12'}>
+                <label className="switch-row fv-switch-row">
+                    {labelSlot}
+                    <input
+                        type="checkbox"
+                        role="switch"
+                        className="switch"
+                        checked={value === true}
+                        onChange={(e) => form.commit(field.name, e.target.checked)}
+                    />
+                </label>
+                {footSlot}
+            </div>
+        );
+    }
+
+    // Non-builtin types resolve through the field-type registry (B4 #1278).
+    // Every registry control fires on COMMIT, so its one change gesture maps
+    // straight onto form.commit — same batch/indicator lifecycle as builtins.
+    // A <div>, not a <label>: these are composite widgets (triggers,
+    // popovers, chip lists) and label-click forwarding would fight them.
+    if (!['text', 'email', 'tel', 'select', 'textarea'].includes(field.type)) {
+        const Registered = resolveFieldRenderer(field.type);
+        if (Registered) {
+            return (
+                <div className={field.columns === 6 ? 'col-6' : 'col-12'}>
+                    <div className="field">
+                        {labelSlot}
+                        <Registered
+                            field={field}
+                            value={value ?? emptyFieldValue(field)}
+                            invalid={!!error}
+                            commit={(v) => form.commit(field.name, v)}
+                            commitPatch={form.commitPatch}
+                            onPendingChange={(pending) => onPendingChange(field.name, pending)}
+                            ownerResult={ownerResult}
+                        />
+                        {footSlot}
+                    </div>
+                </div>
+            );
+        }
+    }
+
+    let control: ReactNode;
+    const text = String(value ?? '');
+    if (field.type === 'select') {
+        // Selects commit on change (a change IS the commit gesture).
+        control = (
+            <SchemaSelect
+                field={field}
+                value={text}
+                invalid={!!error}
+                onChange={(v) => form.commit(field.name, v)}
+            />
+        );
+    } else if (field.type === 'textarea') {
+        // Textareas commit on blur only — Enter inserts a newline.
+        control = (
+            <textarea
+                className={`input${error ? ' input-invalid' : ''}`}
+                rows={3}
+                placeholder={field.placeholder}
+                value={text}
+                onChange={(e) => form.setValue(field.name, e.target.value)}
+                onBlur={() => form.commit(field.name)}
+            />
+        );
+    } else {
+        // text | email | tel — and the unknown-type fallback (warn + text,
+        // never "render nothing").
+        if (!['text', 'email', 'tel'].includes(field.type)) {
+            const key = `${field.name}:${field.type}`;
+            if (!warnedFieldTypes.has(key)) {
+                warnedFieldTypes.add(key);
+                console.warn(`FormView: unknown field type "${field.type}" on "${field.name}" — rendering a text input`);
+            }
+        }
+        control = (
+            <input
+                className={`input${error ? ' input-invalid' : ''}`}
+                type={['text', 'email', 'tel'].includes(field.type) ? field.type : 'text'}
+                placeholder={field.placeholder}
+                value={text}
+                onChange={(e) => form.setValue(field.name, e.target.value)}
+                onBlur={() => form.commit(field.name)}
+                onKeyDown={(e) => {
+                    // Enter commits (change-on-commit contract) without leaving
+                    // the field.
+                    if (e.key === 'Enter') {
+                        e.preventDefault();
+                        form.commit(field.name);
+                    }
+                }}
+            />
+        );
+    }
+
+    return (
+        <div className={field.columns === 6 ? 'col-6' : 'col-12'}>
+            <label className="field">
+                {labelSlot}
+                {control}
+                {footSlot}
+            </label>
+        </div>
+    );
+}