@jini-ai/admin 0.4.2 → 0.4.4

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

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

@@ -0,0 +1,110 @@
+import { submissionView } from "../../models.js";
+import { useFormsPorts } from "./FormsPorts.hooks.js";
+import { useController } from "../../../core/react/use-controller.js";
+import { createFormSubmissionsController, initialFormSubmissionsState } from "../../controllers/form-submissions.controller.js";
+import { useCallback, useEffect, useRef } from "react";
+import { describeApiError as describeCoreApiError } from "../../../core/transport/errors.js";
+const describeApiError = (e, fallback) => describeCoreApiError({ e, fallback });
+import { useFetchQuery, useInvalidate } from "@jini-ai/ui/fetch-query";
+import { useSettlementGeneration } from "@jini-ai/ui/panel-kit";
+import { KEYS } from "../../rules.js";
+export function useFormSubmissions(props, _optional = {}) {
+    const { port } = props;
+    const invalidate = useInvalidate();
+    const firstPage = useFetchQuery({
+        key: KEYS.submissionsList(props.formId),
+        fetch: () => port.listFormSubmissions({ formId: props.formId }, {}).then(page => ({ data: page.items.map(submission => submissionView({ submission })), nextCursor: page.nextCursor })),
+    });
+    const { controller: stateController, snapshot: stateSnapshot } = useController({ create: () => createFormSubmissionsController({}), dependencies: [] });
+    const state = stateSnapshot ?? initialFormSubmissionsState({});
+    const morePages = state.morePages;
+    const setMorePages = (value) => stateController?.update({ key: "morePages", value });
+    const moreCursor = state.moreCursor;
+    const setMoreCursor = (value) => stateController?.update({ key: "moreCursor", value });
+    const moreError = state.moreError;
+    const setMoreError = (value) => stateController?.update({ key: "moreError", value });
+    const selectedId = state.selectedId;
+    const setSelectedId = (value) => stateController?.update({ key: "selectedId", value });
+    const loadingMore = state.loadingMore;
+    const setLoadingMore = (value) => stateController?.update({ key: "loadingMore", value });
+    // The "latest call wins" guard for accumulated pages — see the file header. `loadingMoreRef` is
+    // the synchronous half (blocks a same-tick double `loadMore`); `pageSettlement` is the async half
+    // (a superseded fetch's response must not land once a reset or a form switch has moved on).
+    const loadingMoreRef = useRef(false);
+    const pageSettlement = useSettlementGeneration();
+    // Supersedes any in-flight "Load more" fetch and clears the accumulated pages/cursor/error back
+    // to "just the first page" — called wherever the previous code did a bare `setMorePages([])`, so
+    // there is one reset path instead of three ad hoc ones.
+    const resetMorePages = useCallback(() => {
+        pageSettlement.next();
+        loadingMoreRef.current = false;
+        setLoadingMore(false);
+        setMorePages([]);
+        setMoreError(null);
+    }, [pageSettlement, stateController]);
+    // One effect, not two: the identity reset below fixes the audit's data-loss finding at this
+    // file — `selectedId` used to survive 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. `resetMorePages()` drops accumulated "more" pages, which belong to the previous form's
+    // cursor walk, and supersedes any of that form's `loadMore` still in flight.
+    useEffect(() => {
+        setSelectedId(null);
+        resetMorePages();
+        setMoreCursor(null);
+    }, [props.formId, resetMorePages]);
+    // S2 fix: a refetched first page (e.g. S5's delete invalidating the list) must drop the "more"
+    // pages it used to leave stale — they are always a continuation of the CURRENT first page, not
+    // whichever first page was on screen when they were fetched. `resetMorePages()` also supersedes
+    // any `loadMore` already in flight when the refetch lands, so its page can't append afterward.
+    useEffect(() => {
+        resetMorePages();
+        setMoreCursor(firstPage.data?.nextCursor ?? null);
+    }, [firstPage.data, resetMorePages]);
+    async function loadMore(cursor) {
+        if (loadingMoreRef.current)
+            return; // #3: a same-tick double click sends only one request
+        loadingMoreRef.current = true;
+        const generation = pageSettlement.next();
+        setLoadingMore(true);
+        setMoreError(null); // #5: a retry clears the previous failure
+        try {
+            const r = await port.listFormSubmissions({ formId: props.formId }, { cursor });
+            if (!pageSettlement.isCurrent({ generation }))
+                return; // superseded by a reset or a form switch
+            setMorePages((prev) => [...prev, ...r.items.map(submission => submissionView({ submission }))]);
+            setMoreCursor(r.nextCursor);
+        }
+        catch (e) {
+            if (!pageSettlement.isCurrent({ generation }))
+                return;
+            setMoreError(e instanceof Error ? e.message : "failed to load submissions");
+        }
+        finally {
+            // A superseded call's lock was already released by `resetMorePages`; only the still-current
+            // call releases it here.
+            if (pageSettlement.isCurrent({ generation })) {
+                loadingMoreRef.current = false;
+                setLoadingMore(false);
+            }
+        }
+    }
+    /** Passing a cursor appends via `loadMore`; omitting it re-reads the first page from scratch
+     *  (used after a submission delete, so the list reflects the removal) and drops accumulated pages,
+     *  matching the pre-migration `load()`'s own "no cursor replaces everything" behavior. */
+    function load(cursor) {
+        if (cursor) {
+            void loadMore(cursor);
+            return;
+        }
+        resetMorePages();
+        invalidate({ key: KEYS.submissionsList(props.formId) });
+    }
+    const submissions = firstPage.data ? [...firstPage.data.data, ...morePages] : null;
+    const error = moreError ?? (firstPage.error ? describeApiError(firstPage.error, "failed to load submissions") : null);
+    return { submissions, nextCursor: moreCursor, error, selectedId, setSelectedId, load, loadingMore };
+}
+export function useWiredFormSubmissions(props, _optional = {}) {
+    const { formsApi } = useFormsPorts();
+    return useFormSubmissions({ ...props, port: formsApi });
+}
+//# sourceMappingURL=use-form-submissions.hooks.js.map

package/dist/forms/react/hooks/use-forms-list.hooks.d.ts

@@ -0,0 +1,78 @@
+import type { AdminFormsPort } from "../../../core/ports/forms.js";
+import type { FormsTrashPort, FormsEventsPort } from "../../ports.js";
+import type { AdminFormDefinition } from "../../models.js";
+import { type FormDateLine } from "../../rules.js";
+/**
+ * @file Everything the Forms LIST does, so `FormsList.tsx` is only markup.
+ *
+ * Moved from the host — same state, same order, same effect, same error strings. Naming follows
+ * `hooks/use-settings-slice.hooks.ts` and `hooks/use-dirty-guard.hooks.ts`: `use-<thing>.hooks.ts`.
+ * Feature-local because nothing outside `features/forms` needs it; promote to `src/hooks/` only
+ * when a second feature actually does.
+ *
+ * `port` is injected — see `core/ports/forms.ts` (shared with `use-form-editor.hooks.ts`, since
+ * both read/write the same `AdminFormDefinition` resource) — rather than importing `lib/api`
+ * directly, so a test can describe list/write outcomes against `the memory adapter` instead of
+ * stubbing global `fetch`. `useWiredFormsList` below is the zero-argument pair `FormsList.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` rather than `FormsList.tsx` importing `useAdminLocale`
+ * and `FORMS_DICT` itself. Pre-bound to `(key: string) => string` so a test can inject
+ * `t: (k) => k` and every assertion stays stable against copy changes. `useAdminLocale()` and
+ * `FORMS_DICT` are called/read only inside {@link useWiredFormsList}.
+ *
+ * `@jini-ai/ui/fetch-query` migration (2026-08-12): `toggleStatus` is one `useFetchMutation` that
+ * `invalidates: [KEYS.list]` — same idiom `use-taxonomy.hooks.ts`'s deletes use, so this list stays
+ * in sync with a status change made from `FormEditor.tsx` too (a `KEYS.list`-invalidating write
+ * elsewhere in the app, not just this screen's own toggle). This DOES cost one extra background GET
+ * per toggle that the pre-migration `setForms((prev) => prev.map(...))` optimistic patch avoided —
+ * a deliberate trade for cross-screen consistency (`@jini-ai/ui/fetch-query`'s own header names
+ * this exact "two screens showing the same resource silently drift apart" bug as the reason the
+ * library exists at all); `FormsList.unit.test.tsx`'s old "only one GET" assertion is updated
+ * accordingly, not preserved. `rowSavingId` lives in the section controller rather than reading off the
+ * mutation directly — one shared `useFetchMutation` object has no per-call "which row" of its own,
+ * the exact case this migration's own dispatch brief calls out as the intended `useState` out.
+ *
+ * the scoped formsEvents subscription (staleness-bug generalization pass, see that hook's own header):
+ * `forms_create_definition`/`forms_update_definition`/`forms_set_definition_status`
+ * (`apps/website/src/features/forms/agent-tools.ts`) are agent-callable, so this list re-invalidates
+ * `KEYS.list` on an out-of-band content-refresh notification the same way `use-taxonomy.hooks.ts`
+ * does for its own resource.
+ */
+export interface FormsListController {
+    forms: AdminFormDefinition[] | null;
+    /** The "Created / Updated" cell's one or two lines — see `rules.ts`'s `formDatesLines`. */
+    formatFormDates: (form: AdminFormDefinition) => FormDateLine[];
+    error: string | null;
+    /** In-flight row action (status toggle, or the confirmed delete) — one at a time, same
+     *  `rowSavingId` convention `Posts.tsx`/`Pages.tsx` use for their own row actions. Shared between
+     *  {@link FormsListController.toggleStatus} and {@link FormsListController.removeForm} so a
+     *  Disable click and a Delete confirm on two different rows can never race each other. */
+    rowSavingId: string | null;
+    /** No-op while a previous call is still in flight (`rowSavingId` set) — see this function's own
+     *  comment; the caller never has to guard against a double toggle itself. */
+    toggleStatus: (form: AdminFormDefinition) => Promise<void>;
+    /** The form a `RowMenu` "Delete" selection is asking to confirm; `null` when the `ConfirmDialog`
+     *  is closed. `FormsList.tsx` drives the dialog's `open` prop from this. */
+    pendingDelete: AdminFormDefinition | null;
+    setPendingDelete: (form: AdminFormDefinition | null) => void;
+    /** Runs the trash move for {@link FormsListController.pendingDelete}. No-op with no
+     *  `pendingDelete` (Cancel never reaches the port) or while another row action is already
+     *  in-flight (`rowSavingId` set) — see this function's own comment. */
+    removeForm: () => Promise<void>;
+    /** Bound translator — see this file's own header for why it arrives via the hook rather than
+     *  `FormsList.tsx` calling `useAdminLocale()`/`FORMS_DICT` directly. */
+    t: (key: string) => string;
+}
+export declare function useFormsList(deps: {
+    port: AdminFormsPort;
+    trash: FormsTrashPort;
+    t: (key: string) => string;
+    events?: FormsEventsPort;
+}, { locale }?: {
+    locale?: string;
+}): FormsListController;
+export declare function useWiredFormsList(_required?: Record<string, never>, _optional?: {}): FormsListController;
+//# sourceMappingURL=use-forms-list.hooks.d.ts.map

package/dist/forms/react/hooks/use-forms-list.hooks.js

@@ -0,0 +1,103 @@
+import { formView } from "../../models.js";
+import { useFormsPorts, useFormsOptions } from "./FormsPorts.hooks.js";
+import { useController } from "../../../core/react/use-controller.js";
+import { createFormsListController, initialFormsListState } from "../../controllers/forms-list.controller.js";
+import { useCallback, useEffect, useMemo } from "react";
+import { useFetchMutation, useFetchQuery, useInvalidate } from "@jini-ai/ui/fetch-query";
+import { KEYS, describeTrashError, formDatesLines, formsListError, newestUpdatedForms } from "../../rules.js";
+export function useFormsList(deps, { locale = "en" } = {}) {
+    const { port, trash, t, events } = deps;
+    const list = useFetchQuery({ key: KEYS.list, fetch: () => port.listFormDefinitions({}).then(data => ({ data: data.map(form => formView({ form })) })) });
+    const invalidate = useInvalidate();
+    // Stable identity — see `use-media.hooks.ts`'s identical `invalidateList` for why an inline arrow
+    // here would resubscribe the scoped formsEvents subscription on every render for no benefit.
+    const invalidateList = useCallback(() => invalidate({ key: KEYS.list }), [invalidate]);
+    useEffect(() => events?.subscribe({ onRefresh: invalidateList }), [events, invalidateList]);
+    const { controller: stateController, snapshot: stateSnapshot } = useController({ create: () => createFormsListController({}), dependencies: [] });
+    const state = stateSnapshot ?? initialFormsListState({});
+    const rowSavingId = state.rowSavingId;
+    const setRowSavingId = (value) => stateController?.update({ key: "rowSavingId", value });
+    const toggleMutation = useFetchMutation({
+        run: ({ input: form }) => port.updateFormDefinition({ id: form.id }, { status: form.status === "active" ? "disabled" : "active" }),
+    }, {
+        invalidates: [KEYS.list],
+    });
+    // The form a `RowMenu` "Delete" selection is asking to confirm — `null` when the `ConfirmDialog`
+    // is closed. `ConfirmDialog` stays mounted unconditionally in `FormsList.tsx`; this is what drives
+    // its `open` prop — same shape `use-posts.hooks.ts`'s `pendingDelete` uses for its own row delete.
+    const pendingDelete = state.pendingDelete;
+    const setPendingDelete = (value) => stateController?.update({ key: "pendingDelete", value });
+    const deleteMutation = useFetchMutation({
+        run: ({ input: form }) => trash.trash({ type: "form", id: form.id }),
+    }, {
+        invalidates: [KEYS.list],
+    });
+    // In-flight guard lives here, not in `FormsList.tsx`'s `onToggleStatus` closure — `RowMenu` has no
+    // per-item `disabled`, so this is what stops a second toggle firing while the first is still
+    // saving. Same shape `use-redirects.hooks.ts`'s own `onToggleStatus` uses for its identical
+    // `if (saving) return;` guard (that hook's own comment on why: `disabled={saving}` on the old
+    // inline buttons moved into each handler once `RowMenu` replaced them). Shared `rowSavingId` with
+    // `removeForm` below (T7a) — only clears THIS row's own lock in `finally`, so a Delete confirm on
+    // a DIFFERENT row that lands while this toggle is still in flight doesn't get its own lock wiped,
+    // same guard `use-posts.hooks.ts`'s `togglePostPublish`/`removePost` pair documents.
+    async function toggleStatus(form) {
+        if (rowSavingId)
+            return;
+        setRowSavingId(form.id);
+        try {
+            await toggleMutation.mutate({ input: form });
+        }
+        catch {
+            // already surfaced through toggleMutation.error -> error below
+        }
+        finally {
+            setRowSavingId((cur) => (cur === form.id ? null : cur));
+        }
+    }
+    /** Moves `pendingDelete` to the Trash via `formsTrash.trash` — reached only through the
+     *  `ConfirmDialog`'s Confirm button, never the `RowMenu` selection itself (that only opens the
+     *  dialog via `setPendingDelete`), so a click alone can never delete. A 404 (`describeTrashError`'s
+     *  `alreadyGone`) means the row is already gone: a quiet list refresh instead of an error banner
+     *  blaming the operator for something that already happened — see that function's own doc. Every
+     *  other outcome closes the dialog and leaves the failure (if any) for `error` below to surface. */
+    async function removeForm() {
+        if (!pendingDelete)
+            return;
+        if (rowSavingId)
+            return;
+        const form = pendingDelete;
+        setRowSavingId(form.id);
+        try {
+            await deleteMutation.mutate({ input: form });
+            setPendingDelete(null);
+        }
+        catch (e) {
+            if (describeTrashError({ error: e instanceof Error ? e : null, fallback: t("failed to delete form"), versionChangedMessage: t("This item changed since you loaded it. Reload and try again.") }).alreadyGone) {
+                invalidateList();
+            }
+            setPendingDelete(null);
+        }
+        finally {
+            setRowSavingId((cur) => (cur === form.id ? null : cur));
+        }
+    }
+    const forms = useMemo(() => list.data ? newestUpdatedForms({ forms: list.data.data }) : null, [list.data]);
+    const formatFormDates = (form) => formDatesLines({ form, locale, t });
+    const error = formsListError({
+        toggleError: toggleMutation.error,
+        deleteError: deleteMutation.error,
+        listError: list.error,
+        hasForms: forms !== null,
+        deleteFallback: t("failed to delete form"),
+        statusUpdateFallback: t("failed to update form status"),
+        loadFormsFallback: t("failed to load forms"),
+        versionChangedMessage: t("This item changed since you loaded it. Reload and try again."),
+    });
+    return { forms, formatFormDates, error, rowSavingId, toggleStatus, pendingDelete, setPendingDelete, removeForm, t };
+}
+export function useWiredFormsList(_required = {}, _optional = {}) {
+    const { formsApi, formsTrash, formsEvents } = useFormsPorts();
+    const { t, locale } = useFormsOptions();
+    return useFormsList({ port: formsApi, trash: formsTrash, ...(formsEvents === undefined ? {} : { events: formsEvents }), t }, { locale });
+}
+//# sourceMappingURL=use-forms-list.hooks.js.map