@jini-ai/admin 0.4.2 → 0.4.3

package/dist/forms/react/hooks/use-form-editor.hooks.d.ts

@@ -0,0 +1,118 @@
+import type { AdminFormsPort } from "../../../core/ports/forms.js";
+import { type FormAnswerColumn } from "../../html-rules.js";
+import type { AdminFormDefinition, AdminFormField } from "../../models.js";
+/**
+ * @file Everything the FormEditor SCREEN does — load, save, status toggle, and the Fields/
+ * Submissions tab strip's roving-tabindex focus management — so `FormEditor`'s exported component
+ * in `FormEditor.tsx` is only markup.
+ *
+ * Moved from the host — same load effect, same save/status-toggle error strings, same "later failure
+ * keeps the editor on screen" guard (the audit-blocker fix this screen's file header describes —
+ * see `FormEditor.tsx`'s own header for the full rationale, which stays with the guard in the view
+ * since it describes render behaviour, not this hook's state).
+ *
+ * `tab` (ADR-063, 2026-08-31): no longer local state — it is `props.tab`, derived from the route
+ * (`/forms/:formId` vs `/forms/:formId/submissions`) by `panels.tsx`/`FormEditor.tsx`. Switching
+ * tabs calls the injected `navigate` (real app router), the same idiom `Deployment.tsx`'s tab strip
+ * uses, rather than a local `setTab` — Submissions has its own independent fetch, so a tab switch
+ * is a genuine route change, not a display-layer filter over data already in hand.
+ *
+ * `tabRefs` moves here too, per Pattern 1 (every `useRef` moves with state/effects, not just
+ * `useState`) — the view still attaches each button via its own `ref` callback (an unavoidably
+ * DOM-side operation), but the ref array itself and the keydown-to-focus-change logic
+ * (`onTabsKeyDown`) are behaviour, not markup.
+ *
+ * Naming follows `hooks/use-settings-slice.hooks.ts`: `use-<thing>.hooks.ts`. Feature-local because
+ * nothing outside `features/forms` needs it.
+ *
+ * `port`/`navigate` are injected — see `core/ports/forms.ts` (shared with `use-forms-list.hooks.ts`,
+ * since both read/write the same `AdminFormDefinition` resource) — rather than reaching `lib/api`/
+ * `lib/router` directly, so a test can describe load/save outcomes against `the memory adapter`
+ * instead of stubbing global `fetch`. `useWiredFormEditor` below is the zero-argument pair
+ * `FormEditor.tsx` actually mounts.
+ *
+ * `t` (standing i18n rule — a component with a hook gets a BOUND `t` from that hook, not its own
+ * `useAdminLocale()`/dictionary import, same shape `use-post-editor.hooks.ts` established for this
+ * conversion): injected alongside `port`/`navigate` because `FormEditor.tsx` itself (the copy
+ * around this hook's own state — tab labels, Save button, etc.) DOES need translated strings, even
+ * though this hook's own error messages don't. Pre-bound to `(key: string) => string`.
+ * `useAdminLocale()` and `FORMS_DICT` are called/read only inside {@link useWiredFormEditor}.
+ *
+ * `@jini-ai/ui/fetch-query` migration (2026-08-12): the load is one `useFetchQuery` keyed on
+ * `KEYS.form(formId)` (disabled for `isNew`, matching the original `if (isNew) return;` early-out).
+ * `form`/`name`/`slug`/`fields`/`notify` live in the section controller — the operator edits `name`/`slug`/
+ * `fields`; `notify` has no UI of its own (owner ask 2026-09-22 removed the notify checkbox/
+ * recipients input — see this file's own `notify` state comment) and is only ever carried through
+ * unchanged. All are seeded from `list.data` exactly once per `formId` via `seededFormIdRef`, the
+ * same shape `collections/hooks/use-collection-entry-editor.hooks.ts`'s `seededIdentityRef`
+ * establishes (see that file's header for the regression it guards against: a background refetch of
+ * the SAME identity must not clobber in-progress edits). `handleSave`/`handleStatusToggle` set `form`
+ * (and, for save, the rest of the seeded fields) directly from each MUTATION's own response, and
+ * neither mutation invalidates this hook's OWN `KEYS.form(formId)` read (only the sibling
+ * `KEYS.list`) — mirroring `save()`/`toggleLifecycle()` in that same collections hook, which
+ * invalidate only the sibling `KEYS.entries(...)`, never their own `KEYS.entry(...)`, for the
+ * identical reason: a response already in hand needs no redundant background refetch of itself. This
+ * eliminates the load race an external audit flagged at this file's old line 117 (`useEffect(load,
+ * [props.formId, port])` with no cancellation guard, so a formId change mid-flight could commit a
+ * stale response): a keyed query cannot commit a response belonging to a prior key, by construction.
+ */
+export interface FormEditorController {
+    isNew: boolean;
+    /** `null` until the initial load settles (or always, for `isNew`) — the caller renders a loading
+     *  state or the empty create form accordingly. */
+    form: AdminFormDefinition | null;
+    name: string;
+    setName: (value: string) => void;
+    slug: string;
+    setSlug: (value: string) => void;
+    mode: "builder" | "html";
+    onModeChange: (mode: "builder" | "html") => void;
+    html: string;
+    setHtml: (html: string) => void;
+    copyEmbed: () => void;
+    copyFeedback: string | null;
+    answerColumns: FormAnswerColumn[];
+    fields: AdminFormField[];
+    setFields: (fields: AdminFormField[]) => void;
+    tab: "fields" | "submissions";
+    /** Navigates to this form's Fields or Submissions route — real `navigate()`, not local state
+     *  (ADR-063: Submissions has its own independent fetch, so a tab switch is a genuine route
+     *  change, the same idiom `Deployment.tsx`'s tab strip uses). Pushes a history entry (no
+     *  `replace`) so browser back/forward move naturally between the two routes, unlike the
+     *  `?tab=` screens' `replace: true` view-filter switches. */
+    onTabChange: (tab: "fields" | "submissions") => void;
+    error: string | null;
+    saving: boolean;
+    /** Already-persisted field ids on the loaded form — see `existingFieldIdsOf`. */
+    existingFieldIds: string[];
+    /** Tabs render only for an existing, loaded form — never for `isNew`, and never before `form`
+     *  has loaded. */
+    showTabs: boolean;
+    /** Per-tab-button refs, indexed the same as `FORM_TABS` — attach via each button's own `ref`
+     *  callback in the view. */
+    tabRefs: React.MutableRefObject<Array<HTMLButtonElement | null>>;
+    /** Roving-tabindex keydown handler for the tablist `<div>` — ArrowLeft/ArrowRight/Home/End move
+     *  both the selected tab and DOM focus together. */
+    onTabsKeyDown: (e: React.KeyboardEvent) => void;
+    handleSave: () => void;
+    handleStatusToggle: () => void;
+    /** Bound translator — see this file's own header for why it arrives via the hook rather than
+     *  `FormEditor.tsx` calling `useAdminLocale()`/`FORMS_DICT` directly. */
+    t: (key: string) => string;
+}
+export declare function useFormEditor(props: {
+    formId: string;
+    tab: "fields" | "submissions";
+    port: AdminFormsPort;
+    navigate: (path: string) => void;
+    t: (key: string) => string;
+}, { clipboard }?: {
+    clipboard?: {
+        writeText: (text: string) => Promise<void>;
+    };
+}): FormEditorController;
+export declare function useWiredFormEditor(props: {
+    formId: string;
+    tab: "fields" | "submissions";
+}, _optional?: {}): FormEditorController;
+//# sourceMappingURL=use-form-editor.hooks.d.ts.map

package/dist/forms/react/hooks/use-form-editor.hooks.js

@@ -0,0 +1,208 @@
+import { formView } from "../../models.js";
+import { useFormsPorts, useFormsOptions } from "./FormsPorts.hooks.js";
+import { useController } from "../../../core/react/use-controller.js";
+import { createFormEditorController, initialFormEditorState } from "../../controllers/form-editor.controller.js";
+import { formHtmlEmbed, formAnswerColumns } from "../../html-rules.js";
+import { useEffect, useRef } from "react";
+import { useFetchMutation, useFetchQuery } from "@jini-ai/ui/fetch-query";
+import { FORM_TABS, KEYS, existingFieldIdsOf, nextTabIndex, visibleFormEditorError } from "../../rules.js";
+export function useFormEditor(props, { clipboard } = {}) {
+    const { port, navigate, t } = props;
+    const { tab } = props;
+    const isNew = props.formId === "new";
+    const { controller: stateController, snapshot: stateSnapshot } = useController({ create: () => createFormEditorController({}), dependencies: [] });
+    const state = stateSnapshot ?? initialFormEditorState({});
+    const form = state.form;
+    const setForm = (value) => stateController?.update({ key: "form", value });
+    const mode = state.mode;
+    const html = state.html;
+    const setHtml = (value) => stateController?.update({ key: "html", value });
+    const copyFeedback = state.copyFeedback;
+    const setCopyFeedback = (value) => stateController?.update({ key: "copyFeedback", value });
+    const name = state.name;
+    const setName = (value) => stateController?.update({ key: "name", value });
+    const slug = state.slug;
+    const setSlug = (value) => stateController?.update({ key: "slug", value });
+    const fields = state.fields;
+    const setFields = (value) => stateController?.update({ key: "fields", value });
+    // No UI edits this (owner ask 2026-09-22 removed the notify checkbox/recipients input from the
+    // Fields tab — a future outside mail integration will design its own way to set it). Seeded from
+    // the loaded form and carried through unchanged on every save, so an operator saving a form never
+    // wipes out a `notify` setting that predates this UI removal. Lives in the section controller, not a
+    // `const`, only so `handleSave`'s existing-form branch can resync it from the write's own response
+    // exactly like `form`/`name`/`slug`/`fields` already do below.
+    const notify = state.notify;
+    // Roving-tabindex focus targets for the tab strip below, indexed the same as `FORM_TABS` — see
+    // `nextTabIndex`'s doc comment for why the index math itself lives outside the component.
+    const tabRefs = useRef([]);
+    const list = useFetchQuery({ key: KEYS.form(props.formId), fetch: () => port.getFormDefinition({ id: props.formId }).then(form => ({ data: formView({ form }) })) }, { enabled: !isNew });
+    // Seeds `form`/`name`/`slug`/`fields`/`notify` from `list.data` exactly once per `formId` — see
+    // this file's own header for the regression this guards against (a background refetch of the SAME
+    // formId must not clobber in-progress edits).
+    const seededFormIdRef = useRef(null);
+    const seededControllerRef = useRef(null);
+    useEffect(() => {
+        if (seededControllerRef.current !== stateController) {
+            seededControllerRef.current = stateController;
+            seededFormIdRef.current = null;
+        }
+        if (seededFormIdRef.current !== props.formId)
+            seededFormIdRef.current = null;
+        if (!stateController)
+            return;
+        if (isNew || list.status === "loading" || !list.data)
+            return;
+        if (seededFormIdRef.current === props.formId)
+            return;
+        seededFormIdRef.current = props.formId;
+        const loaded = list.data.data;
+        stateController.seed({ form: loaded });
+    }, [props.formId, isNew, list.status, list.data, stateController]);
+    // None of these invalidate `KEYS.form(props.formId)` — only `KEYS.list`. `handleSave`/
+    // `handleStatusToggle` below already set `form` (and, for save, the rest of the seeded fields)
+    // directly from each mutation's own response, so invalidating this hook's OWN read key would only
+    // buy a redundant background refetch of data already in hand — the same reasoning
+    // `use-collection-entry-editor.hooks.ts`'s `save()`/`toggleLifecycle()` document for why THEIR
+    // `invalidates` names only the sibling `KEYS.entries(...)`, never their own `KEYS.entry(...)`.
+    const updateMutation = useFetchMutation({
+        run: ({ input }) => 
+        // Targets the loaded record's real id, never `props.formId` directly — the admin URL now
+        // carries the form's slug when one resolves (ui-fixes-backlog.md #8), so `props.formId` may
+        // itself BE that slug. `form.id` is always the real id regardless of which one the URL held,
+        // which is what lets the PUT route stay id-only (no matching slug support needed — see
+        // `get-by-id.ts`'s own comment on why only the GET route resolves either). The `?? props
+        // .formId` fallback only matters if this ever fired before `form` loaded, which it can't:
+        // `FormEditor.tsx`'s `!isNew && !form` guards keep the whole editor (Save button included)
+        // off-screen until `form` is set.
+        port.updateFormDefinition({ id: form?.id ?? props.formId }, input),
+    }, {
+        invalidates: [KEYS.list],
+    });
+    const createMutation = useFetchMutation({
+        run: ({ input }) => port.createFormDefinition({ name: input.name, slug: input.slug, fields: input.fields, ...(input.mode ? { mode: input.mode, html: input.html } : {}) }, { notify: input.notify }),
+    }, {
+        invalidates: [KEYS.list],
+    });
+    const statusMutation = useFetchMutation({
+        run: ({ input }) => port.updateFormDefinition({ id: input.id }, { status: input.status }),
+    }, {
+        invalidates: [KEYS.list],
+    });
+    function onModeChange(next) {
+        stateController?.changeMode({ mode: next }, { submitLabel: t("Send") });
+    }
+    async function copyEmbed() {
+        if (!form)
+            return;
+        try {
+            await (clipboard ?? navigator.clipboard).writeText(formHtmlEmbed({ slug: form.slug }));
+            setCopyFeedback(t("Copied!"));
+        }
+        catch {
+            setCopyFeedback(t("Could not copy embed"));
+        }
+    }
+    async function handleSave() {
+        // Ordinary Builder saves keep their existing endpoint/permissions. A mode change is explicit.
+        const authoring = mode === "html" ? { mode, html } : form?.mode === "html" ? { mode } : {};
+        try {
+            if (isNew) {
+                // `notify` here is always this hook's own blank default — a new form has no earlier value
+                // to carry through, and there is no UI on this screen to set one instead.
+                const created = await createMutation.mutate({ input: { name, slug, fields, notify, ...authoring } });
+                // Slug, not id — see this hook's own file header / `get-by-id.ts` for the id-or-slug
+                // resolution this now lands on (ui-fixes-backlog.md #8).
+                navigate(`/forms/${created.slug}`);
+            }
+            else {
+                // `notify` is the value this hook seeded from the loaded form and has never changed since —
+                // sent back unchanged so saving name/slug/field edits can never wipe a stored notify setting
+                // (see this hook's own `notify` state comment).
+                // Set directly from the write's own response — `updateMutation` doesn't invalidate this
+                // hook's own `KEYS.form(id)` read (see the mutations' own comment above), so there is no
+                // background refetch to wait for or to accidentally clobber an in-progress edit with.
+                // Mirrors `use-collection-entry-editor.hooks.ts`'s `save()`.
+                const updatedCore = await updateMutation.mutate({ input: { name, fields, notify, ...authoring } });
+                const updated = formView({ form: updatedCore });
+                stateController?.seed({ form: updated });
+            }
+        }
+        catch {
+            // already surfaced through updateMutation.error/createMutation.error -> error below
+        }
+    }
+    async function handleStatusToggle() {
+        if (!form)
+            return;
+        try {
+            const updatedCore = await statusMutation.mutate({ input: {
+                    id: form.id,
+                    status: form.status === "active" ? "disabled" : "active",
+                } });
+            setForm(formView({ form: updatedCore }));
+        }
+        catch {
+            // already surfaced through statusMutation.error -> error below
+        }
+    }
+    const saving = updateMutation.status === "pending" || createMutation.status === "pending" || statusMutation.status === "pending";
+    const error = visibleFormEditorError({
+        updateError: updateMutation.error,
+        createError: createMutation.error,
+        statusError: statusMutation.error,
+        listError: list.error,
+        hasForm: form !== null,
+        saveFallback: t("save failed"),
+        statusUpdateFallback: t("status update failed"),
+        loadFormFallback: t("failed to load form"),
+    });
+    // Navigates to `/forms/:formId` or `/forms/:formId/submissions` (ADR-063) — `panels.tsx`'s
+    // `forms` panel keys `FormEditor` off `ctx.params.formId` on BOTH routes, so this is a route
+    // change, not a remount: in-progress Fields edits survive a trip to Submissions and back.
+    function onTabChange(nextTab) {
+        navigate(nextTab === "submissions" ? `/forms/${props.formId}/submissions` : `/forms/${props.formId}`);
+    }
+    function onTabsKeyDown(e) {
+        const currentIndex = FORM_TABS.findIndex((t) => t.id === tab);
+        const index = nextTabIndex({ key: e.key, currentIndex });
+        if (index === null)
+            return;
+        e.preventDefault();
+        onTabChange(FORM_TABS[index].id);
+        tabRefs.current[index]?.focus();
+    }
+    return {
+        isNew,
+        form,
+        mode, onModeChange, html, setHtml, copyEmbed, copyFeedback,
+        answerColumns: formAnswerColumns({ fields: form?.fields ?? [] }),
+        name,
+        setName,
+        slug,
+        setSlug,
+        fields,
+        setFields,
+        tab,
+        onTabChange,
+        error,
+        saving,
+        existingFieldIds: existingFieldIdsOf({ form }),
+        showTabs: !isNew && form !== null,
+        tabRefs,
+        onTabsKeyDown,
+        handleSave,
+        handleStatusToggle,
+        t,
+    };
+}
+export function useWiredFormEditor(props, _optional = {}) {
+    const { formsApi, formsNavigation } = useFormsPorts();
+    const { t, clipboard, adminBase } = useFormsOptions();
+    const navigate = (routePath) => {
+        if (!formsNavigation)
+            throw new Error('Missing forms navigation port');
+        formsNavigation.navigate({ base: adminBase, routePath });
+    };
+    return useFormEditor({ ...props, port: formsApi, navigate, t }, clipboard ? { clipboard } : {});
+}
+//# sourceMappingURL=use-form-editor.hooks.js.map

package/dist/forms/react/hooks/use-form-fields-editor.hooks.d.ts

@@ -0,0 +1,34 @@
+import type { AdminFormField } from "../../models.js";
+/**
+ * @file `FormFieldsEditor`'s own state (which row's attributes modal is open, plus the per-row
+ * kebab-trigger refs for WCAG focus-return), so the fields table in `FormEditor.tsx` is only
+ * markup.
+ *
+ * Extracted verbatim, including the `useRef` array — `Pattern 1` moves every `useRef` out of the
+ * component along with state/effects, not just `useState`. The field-list edits themselves
+ * (`updateField`/`addField`/`removeField`) are thin wrappers around `rules.ts`'s pure array
+ * transforms, applied through the parent-owned `onChange` (this component does not own `fields`
+ * itself — `FormEditor`'s own `fields` state does).
+ *
+ * Naming follows `hooks/use-settings-slice.hooks.ts`: `use-<thing>.hooks.ts`. Feature-local because
+ * nothing outside `features/forms` needs it.
+ */
+export interface FormFieldsEditorController {
+    /** Which field's `FieldAttributesDialog` is open, by index — `null` when none is. */
+    editingAttrsIndex: number | null;
+    openAttrsDialog: (index: number) => void;
+    /** Closes the attributes dialog and returns focus to the kebab trigger that opened it (WCAG 2.1
+     *  AA "focus returns to trigger element when modal closes"). */
+    closeAttrsDialog: () => void;
+    /** Per-row kebab-trigger refs, indexed the same as `fields` — attach via each row's own `ref`
+     *  callback in the view. */
+    kebabRefs: React.MutableRefObject<Array<HTMLButtonElement | null>>;
+    updateField: (index: number, patch: Partial<AdminFormField>) => void;
+    addField: () => void;
+    removeField: (index: number) => void;
+}
+export declare function useFormFieldsEditor(props: {
+    fields: AdminFormField[];
+    onChange: (fields: AdminFormField[]) => void;
+}, _optional?: Record<string, never>): FormFieldsEditorController;
+//# sourceMappingURL=use-form-fields-editor.hooks.d.ts.map

package/dist/forms/react/hooks/use-form-fields-editor.hooks.js

@@ -0,0 +1,36 @@
+import { useController } from "../../../core/react/use-controller.js";
+import { createFormFieldsEditorController, initialFormFieldsEditorState } from "../../controllers/form-fields-editor.controller.js";
+import { useRef } from "react";
+import { addFormField, removeFormField, updateFormField } from "../../rules.js";
+export function useFormFieldsEditor(props, _optional = {}) {
+    const { controller: stateController, snapshot: stateSnapshot } = useController({ create: () => createFormFieldsEditorController({}), dependencies: [] });
+    const state = stateSnapshot ?? initialFormFieldsEditorState({});
+    const editingAttrsIndex = state.editingAttrsIndex;
+    const setEditingAttrsIndex = (value) => stateController?.update({ key: "editingAttrsIndex", value });
+    const kebabRefs = useRef([]);
+    function closeAttrsDialog() {
+        const index = editingAttrsIndex;
+        setEditingAttrsIndex(null);
+        if (index !== null)
+            kebabRefs.current[index]?.focus();
+    }
+    function updateField(index, patch) {
+        props.onChange(updateFormField({ fields: props.fields, index, patch }));
+    }
+    function addField() {
+        props.onChange(addFormField({ fields: props.fields }));
+    }
+    function removeField(index) {
+        props.onChange(removeFormField({ fields: props.fields, index }));
+    }
+    return {
+        editingAttrsIndex,
+        openAttrsDialog: setEditingAttrsIndex,
+        closeAttrsDialog,
+        kebabRefs,
+        updateField,
+        addField,
+        removeField,
+    };
+}
+//# sourceMappingURL=use-form-fields-editor.hooks.js.map

package/dist/forms/react/hooks/use-form-submission-date.hooks.d.ts

@@ -0,0 +1,12 @@
+/** Bind submission timestamps to the same operator locale and local time as the Forms list. */
+export declare function useFormSubmissionDate(_required: Record<string, never>, { locale: localeOverride, timeZone }?: {
+    locale?: string;
+    timeZone?: string;
+}): ({ iso }: {
+    iso: string;
+}, _optional?: Record<string, never>) => {
+    text: string;
+    full: string;
+    dateTime: string | undefined;
+};
+//# sourceMappingURL=use-form-submission-date.hooks.d.ts.map

package/dist/forms/react/hooks/use-form-submission-date.hooks.js

@@ -0,0 +1,9 @@
+import { useFormsOptions } from "./FormsPorts.hooks.js";
+import { formDateDisplay } from "../../rules.js";
+/** Bind submission timestamps to the same operator locale and local time as the Forms list. */
+export function useFormSubmissionDate(_required, { locale: localeOverride, timeZone } = {}) {
+    const { locale } = useFormsOptions();
+    // One locale subscription per submissions panel, rather than one per timestamp cell.
+    return ({ iso }, _optional = {}) => formDateDisplay({ iso, locale: localeOverride ?? locale }, timeZone === undefined ? {} : { timeZone });
+}
+//# sourceMappingURL=use-form-submission-date.hooks.js.map

package/dist/forms/react/hooks/use-form-submission-detail.hooks.d.ts

@@ -0,0 +1,68 @@
+import type { AdminFormsPort } from "../../../core/ports/forms.js";
+import type { FormsTrashPort } from "../../ports.js";
+import type { AdminFormSubmission } from "../../models.js";
+/**
+ * @file `FormSubmissionDetail`'s own state and delete action, so the detail view in
+ * `FormEditor.tsx` is only markup.
+ *
+ * Permanent delete now confirms through a modal (S5 fix, 2026-09-20), not an inline two-click
+ * button: the old `confirming`/`handleDelete` shape flipped a click's own label to "Confirm
+ * delete", so a real double-click deleted the submission outright with no way to back out — the
+ * same bug widgets' `trashOrPurge` had before its own `pendingPurge`/`ConfirmDialog` fix. This
+ * hook now mirrors that shape one-for-one: `requestDelete` only opens the dialog (no network),
+ * `cancelDelete` closes it with no request, and `confirmDelete` runs the mutation.
+ *
+ * Naming follows `hooks/use-settings-slice.hooks.ts`: `use-<thing>.hooks.ts`. Feature-local because
+ * nothing outside `features/forms` needs it.
+ *
+ * `port` is injected — see `core/ports/forms.ts` (shared with `use-form-
+ * submissions.hooks.ts`, since both read/write the same submissions list for a form) — rather than
+ * importing `lib/api` directly, so a test can describe load/delete outcomes against
+ * `the memory adapter` instead of stubbing global `fetch`.
+ * `useWiredFormSubmissionDetail` below is the zero-argument pair `FormEditor.tsx` actually mounts.
+ *
+ * `@jini-ai/ui/fetch-query` migration (2026-08-12): the load is one `useFetchQuery` keyed on
+ * `KEYS.submissionDetail(formId, submissionId)` — a query cannot commit a response belonging to a
+ * prior key, which eliminates the load race an external audit flagged at this file's old line 48
+ * (a plain `.then()`/`.catch()` effect with no cancellation guard) by construction. `confirmDelete`
+ * is a `useFetchMutation` that `invalidates: [KEYS.submissionsList(formId)]`, so the sibling list
+ * (`use-form-submissions.hooks.ts`) refreshes on its own — `props.onDeleted()` now only needs to
+ * clear the caller's `selectedId` (a UI-navigation concern this hook can't own), not also trigger a
+ * reload, so `FormEditor.tsx`'s `onDeleted` callback drops its own `load()` call.
+ */
+export interface FormSubmissionDetailController {
+    /** `null` until the initial load settles — the caller renders a loading state. */
+    submission: AdminFormSubmission | null;
+    error: string | null;
+    /** True while the "Delete permanently?" confirm dialog should be open — opened by
+     *  {@link FormSubmissionDetailController.requestDelete}, closed by
+     *  {@link FormSubmissionDetailController.cancelDelete} or once
+     *  {@link FormSubmissionDetailController.confirmDelete} settles. */
+    confirmOpen: boolean;
+    deleting: boolean;
+    /** Opens the confirm dialog. No network call — a click alone can never delete. */
+    requestDelete: () => void;
+    /** Closes the confirm dialog with no request. */
+    cancelDelete: () => void;
+    /** Runs the delete. On success, calls `props.onDeleted()`. Closes the dialog in `finally`
+     *  either way, so a failed delete doesn't leave the operator stuck behind it — the failure is
+     *  still visible via `error` below. */
+    confirmDelete: () => Promise<void>;
+}
+export declare function useFormSubmissionDetail(props: {
+    port: AdminFormsPort;
+    trash: FormsTrashPort;
+    formId: string;
+    submissionId: string;
+    onDeleted: () => void;
+    /** Bound translator — see `use-forms-list.hooks.ts`'s own header for why this arrives via
+     *  injection rather than this hook calling `useAdminLocale()` itself. Optional (defaults to
+     *  identity) so existing callers/tests that don't pass one keep seeing the raw English copy. */
+    t?: (key: string) => string;
+}, _optional?: Record<string, never>): FormSubmissionDetailController;
+export declare function useWiredFormSubmissionDetail(props: {
+    formId: string;
+    submissionId: string;
+    onDeleted: () => void;
+}, _optional?: {}): FormSubmissionDetailController;
+//# sourceMappingURL=use-form-submission-detail.hooks.d.ts.map

package/dist/forms/react/hooks/use-form-submission-detail.hooks.js

@@ -0,0 +1,81 @@
+import { submissionView } from "../../models.js";
+import { useFormsPorts, useFormsOptions } from "./FormsPorts.hooks.js";
+import { useController } from "../../../core/react/use-controller.js";
+import { createFormSubmissionDetailController, initialFormSubmissionDetailState } from "../../controllers/form-submission-detail.controller.js";
+import { describeApiError as describeCoreApiError } from "../../../core/transport/errors.js";
+const describeApiError = (e, fallback) => describeCoreApiError({ e, fallback });
+import { useFetchMutation, useFetchQuery, useInvalidate } from "@jini-ai/ui/fetch-query";
+import { KEYS, describeTrashError } from "../../rules.js";
+export function useFormSubmissionDetail(props, _optional = {}) {
+    const { port, trash } = props;
+    const t = props.t ?? ((key) => key);
+    const { controller: stateController, snapshot: stateSnapshot } = useController({ create: () => createFormSubmissionDetailController({}), dependencies: [] });
+    const state = stateSnapshot ?? initialFormSubmissionDetailState({});
+    const confirmOpen = state.confirmOpen;
+    const setConfirmOpen = (value) => stateController?.update({ key: "confirmOpen", value });
+    const invalidate = useInvalidate();
+    const list = useFetchQuery({
+        key: KEYS.submissionDetail(props.formId, props.submissionId),
+        fetch: () => port.getFormSubmission({ formId: props.formId, submissionId: props.submissionId }).then(submission => ({ data: submissionView({ submission }) })),
+    });
+    const deleteMutation = useFetchMutation({
+        run: ({ input: _ }) => trash.trash({ type: "form_submission", id: props.submissionId }),
+    }, {
+        invalidates: [KEYS.submissionsList(props.formId)],
+    });
+    function requestDelete() {
+        setConfirmOpen(true);
+    }
+    function cancelDelete() {
+        setConfirmOpen(false);
+    }
+    /** T7a (2026-09-21): the confirmation mutation moves the submission to Trash through the generic
+     *  `POST /trash/items` endpoint — see `adapters/http.ts`'s own doc. A 404
+     *  (`describeTrashError`'s `alreadyGone`) means the submission is already gone: from
+     *  the operator's point of view that's the same outcome as a successful delete, so this still calls
+     *  `onDeleted()` and invalidates the list directly — `deleteMutation`'s own `invalidates` only fires
+     *  on success, and a failed mutation would otherwise leave the sibling list showing a row that's
+     *  already gone. */
+    async function confirmDelete() {
+        try {
+            await deleteMutation.mutate({ input: undefined });
+            props.onDeleted();
+        }
+        catch (e) {
+            if (describeTrashError({ error: e instanceof Error ? e : null, fallback: "delete failed", versionChangedMessage: t("This item changed since you loaded it. Reload and try again.") }).alreadyGone) {
+                invalidate({ key: KEYS.submissionsList(props.formId) });
+                props.onDeleted();
+            }
+            // otherwise: already surfaced through deleteMutation.error -> error below
+        }
+        finally {
+            setConfirmOpen(false);
+        }
+    }
+    const submission = list.data?.data ?? null;
+    // The delete's own failure outranks a background load-refresh failure — flat `if`s rather than a
+    // nested ternary, per `@jini-ai/ui/fetch-query`'s `resolveFetchQueryStatus` doc on why the two carry
+    // a different complexity-gate weight for the same branch count.
+    let error = null;
+    if (deleteMutation.error) {
+        error = describeTrashError({ error: deleteMutation.error, fallback: "delete failed", versionChangedMessage: t("This item changed since you loaded it. Reload and try again.") }).message;
+    }
+    else if (list.error) {
+        error = describeApiError(list.error, "failed to load submission");
+    }
+    return {
+        submission,
+        error,
+        confirmOpen,
+        deleting: deleteMutation.status === "pending",
+        requestDelete,
+        cancelDelete,
+        confirmDelete,
+    };
+}
+export function useWiredFormSubmissionDetail(props, _optional = {}) {
+    const { formsApi, formsTrash } = useFormsPorts();
+    const { t } = useFormsOptions();
+    return useFormSubmissionDetail({ ...props, port: formsApi, trash: formsTrash, t });
+}
+//# sourceMappingURL=use-form-submission-detail.hooks.js.map

package/dist/forms/react/hooks/use-form-submissions.hooks.d.ts

@@ -0,0 +1,67 @@
+import type { AdminFormsPort } from "../../../core/ports/forms.js";
+import type { AdminFormSubmission } from "../../models.js";
+/**
+ * @file `FormSubmissions`'s own state and paginated load, so the submissions list in
+ * `FormEditor.tsx` is only markup.
+ *
+ * Moved from the host — same cursor-append load shape, same error strings. `load` keeps its original
+ * `(cursor?: string) => void` signature rather than being split into separate "load"/"loadMore"
+ * functions, so both call sites (`load(nextCursor)` for "Load more", `load()` after a submission
+ * delete) carry over unchanged.
+ *
+ * Naming follows `hooks/use-settings-slice.hooks.ts`: `use-<thing>.hooks.ts`. Feature-local because
+ * nothing outside `features/forms` needs it.
+ *
+ * `port` is injected — see `core/ports/forms.ts` (shared with `use-form-submission-
+ * detail.hooks.ts`, since both read/write the same submissions list for a form) — rather than
+ * importing `lib/api` directly, so a test can describe list outcomes against
+ * `the memory adapter` instead of stubbing global `fetch`. `useWiredFormSubmissions`
+ * below is the zero-argument pair `FormEditor.tsx` actually mounts.
+ *
+ * `@jini-ai/ui/fetch-query` migration (2026-08-12): the FIRST page is one `useFetchQuery` keyed on
+ * `KEYS.submissionsList(formId)` — a query cannot commit a response belonging to a prior key, which
+ * eliminates the load race an external audit flagged at this file's old line 56 (a plain
+ * `.then()`/`.catch()` effect with no cancellation guard) for that page. Subsequent "Load more"
+ * pages are NOT folded into that same query: `@jini-ai/ui/fetch-query`'s `QueryKey` doc binds one
+ * hook to one FIXED key, and a cursor-appended page list is exactly the "moving-target key" shape
+ * that doc's own Skip precedent (`useSettingsContainer`, see this migration's dispatch brief) warns
+ * against faking — so accumulated pages live in the section controller, fetched directly through `port`
+ * (bypassing the cache, since an appended page is not a cacheable "the current state of X", it's an
+ * accumulating view built by this one screen). `pageSettlement` (`useSettlementGeneration`) guards
+ * that accumulation against the SAME class of race the base query gets for free: a `loadMore` in
+ * flight when `formId` changes, or when a first-page refetch (e.g. a delete's invalidate) resets
+ * the list, must not append its page once it resolves — see `resetMorePages` below, which mints a
+ * fresh generation on every reset so any older in-flight page fetch is superseded. A synchronous
+ * `loadingMoreRef` lock, checked before minting a generation, covers the other half: two `loadMore`
+ * calls issued in the SAME tick (a double click) must send only one request
+ * (2026-09-20, `plan-content2.md` #3/#5/S2).
+ *
+ * The audit's second, more serious finding at this file — `selectedId` surviving a `formId` change
+ * untouched, so a delete could fire against a submission id belonging to the PREVIOUS form while its
+ * stale rows were still on screen — is fixed by the identity-reset effect below, which clears both
+ * `selectedId` and the accumulated "more" pages whenever `formId` changes.
+ */
+export interface FormSubmissionsController {
+    /** `null` until the initial load settles — the caller renders a loading state. */
+    submissions: AdminFormSubmission[] | null;
+    nextCursor: string | null;
+    error: string | null;
+    /** The submission `FormSubmissions` is showing `FormSubmissionDetail` for — `null` shows the
+     *  plain list. */
+    selectedId: string | null;
+    setSelectedId: (id: string | null) => void;
+    /** Re-fetches. Passing a cursor appends to `submissions`; omitting it replaces the list from the
+     *  start (used after a submission is deleted, so the list reflects the removal). */
+    load: (cursor?: string) => void;
+    /** True while a "Load more" page fetch is in flight — drives the button's `disabled` and
+     *  "Loading…" label in `FormEditor.tsx`. */
+    loadingMore: boolean;
+}
+export declare function useFormSubmissions(props: {
+    formId: string;
+    port: AdminFormsPort;
+}, _optional?: {}): FormSubmissionsController;
+export declare function useWiredFormSubmissions(props: {
+    formId: string;
+}, _optional?: {}): FormSubmissionsController;
+//# sourceMappingURL=use-form-submissions.hooks.d.ts.map