@jini-ai/admin 0.4.2 → 0.4.3

package/dist/forms/react/pages/FormsList.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ConfirmDialog } from '../../../react/components/ConfirmDialog/ConfirmDialog.js';
+import { DataTable } from '../../../react/components/DataTable.js';
+import { RowMenu } from '../../../react/components/RowMenu/RowMenu.js';
+import { agentHandle } from '@jini-ai/agentic';
+import { useWiredFormsList } from '../hooks/use-forms-list.hooks.js';
+import { useFormsListView } from '../hooks/forms-view.hooks.js';
+export function FormsList({ useFormsListHook = useWiredFormsList } = {}, _optional = {}) {
+    const { forms, formatFormDates, error, rowSavingId, toggleStatus, pendingDelete, setPendingDelete, removeForm, t } = useFormsListHook();
+    const { rows, cancelDelete, RecipientLabel, headerActions } = useFormsListView({ forms, t, formatFormDates, toggleStatus, setPendingDelete });
+    if (error && !forms)
+        return _jsx("div", { className: "notice error", children: error });
+    if (!forms)
+        return _jsx("div", { className: "notice", children: t("Loading forms…") });
+    // Form ids are stable and unique, so they disambiguate one row's edit link from another's —
+    // same reasoning as every other list on this workstream. Each row's "Actions" menu (Edit/Disable/
+    // Enable via `RowMenu`) shares this same per-row base (`${form.rowHandle}-menu`) now that
+    // `RowMenu` (`@jini-ai/admin/react`) accepts an `agentHandle` prop — before this session it
+    // published none, so its trigger and dropdown items were invisible to `page.find_elements`
+    // regardless of what this file did. The Disable/Enable action also stays reachable another way:
+    // `FormEditor.tsx`'s own status toggle (`form-editor-status-toggle`) does the identical
+    // `api.updateForm({ status })` call.
+    return (_jsxs("div", { className: "page", children: [_jsxs("div", { className: "page-header", ...agentHandle({ handle: "forms-header" }, { role: "region", label: "Forms list header — page title and the New form button" }), children: [_jsxs("div", { className: "page-header-text", children: [_jsx("p", { className: "page-kicker", children: t("Content") }), _jsx("h1", { className: "page-title", children: t("Forms") }), _jsx("p", { className: "page-description", children: t("Manage the forms embedded across the site and their submissions.") })] }), _jsxs("div", { className: "page-actions", children: [headerActions, _jsx("a", { className: "btn-primary", href: "/admin/forms/new", ...agentHandle({ handle: "forms-new" }, { role: "link", label: "Create a new form" }), children: t("New form") })] })] }), error ? _jsx("div", { className: "notice error", children: error }) : null, _jsx(DataTable, { rows: rows, rowKey: (form) => form.id, empty: _jsx("div", { className: "card", children: _jsxs("div", { className: "empty-state", children: [_jsx("p", { children: t("No forms yet.") }), _jsx("p", { className: "page-description", children: t("Create your first form to start collecting submissions.") })] }) }), columns: [
+                    {
+                        key: "name",
+                        header: t("Name"),
+                        cell: (form, index) => (_jsx("a", { href: `/admin/forms/${form.slug}`, ...agentHandle({ handle: `${form.rowHandle}-edit` }, {
+                                role: "link",
+                                label: "Open this form's editor",
+                            }), children: form.name })),
+                    },
+                    { key: "slug", header: t("Slug"), cell: (form) => form.slug },
+                    {
+                        key: "dates",
+                        header: t("Created / Updated"),
+                        // One `<time>` per line (created, then updated — or one line when never edited). The
+                        // visible text is the bare short date; the event word lives in the hover title and the
+                        // screen-reader text only, since the header already names both events.
+                        cell: (form) => (_jsx("span", { className: "forms-dates", children: form.dates.map((line) => (_jsxs("time", { className: "forms-dates-line", dateTime: line.dateTime, title: line.label, children: [_jsx("span", { "aria-hidden": "true", children: line.text }), _jsx("span", { className: "visually-hidden", children: line.label })] }, line.kind))) })),
+                    },
+                    { key: "fields", header: t("Fields"), cell: (form) => form.fields.length },
+                    {
+                        key: "notify",
+                        header: t("Notify"),
+                        cell: (form) => (form.notify.enabled ? _jsxs(_Fragment, { children: [form.notify.recipients.length, " ", _jsx(RecipientLabel, { count: form.notify.recipients.length })] }) : t("off")),
+                    },
+                    {
+                        key: "actions",
+                        header: t("More"),
+                        cell: (form, index) => (_jsx(RowMenu, { triggerLabel: form.menuLabel, agentHandle: `${form.rowHandle}-menu`, items: form.menuItems })),
+                    },
+                ] }), _jsx(ConfirmDialog, { open: pendingDelete !== null, agentHandle: "forms-delete", title: t("Move to trash?"), body: pendingDelete ? (_jsxs("p", { children: [t("Move"), " \"", pendingDelete.name, "\" ", t("to trash? It will disappear from the site and from this list.")] })) : null, confirmLabel: t("Move to trash"), destructive: true, pending: pendingDelete !== null && rowSavingId === pendingDelete.id, onConfirm: removeForm, onCancel: cancelDelete })] }));
+}
+export default FormsList;
+//# sourceMappingURL=FormsList.js.map

package/dist/forms/rules.d.ts

@@ -0,0 +1,291 @@
+import type { RowMenuItem } from "../react/components/RowMenu/RowMenu.js";
+import type { AdminFormDefinition, AdminFormField } from "./models.js";
+import type { QueryKey } from "@jini-ai/ui/fetch-query";
+/**
+ * @file Pure logic for the `forms` feature (`FormEditor.tsx` — see `FormsList.tsx`'s own
+ * `rules.ts`/hook for the list screen's extraction) — everything that computes a value rather than
+ * rendering one. Follows the convention `features/posts/rules.ts` establishes: no React, no
+ * hooks, importable and directly testable.
+ *
+ * One deliberate exception to "pure", same as `collections/rules.ts`'s `nextRowId`:
+ * {@link nextAttrRowId} is a module-level counter `attrRowsFromField`/`addAttrRow` advance. Only
+ * `FieldAttributesDialog` (via `use-field-attributes-dialog.hooks.ts`) consumes it today, so it
+ * would be equally correct sitting in that hook file — kept here instead for the same reason
+ * `collections/rules.ts` keeps its row-id counter alongside its other draft-list transforms: one
+ * place for "how draft rows get local keys" per feature, not split by which hook happens to use it
+ * first.
+ *
+ * `KEYS` (fetch-query migration, 2026-08-12): forms and form-submissions are two independent
+ * resources (separate ports, no method overlap — see `core/ports/forms.ts`/`form-submissions-
+ * port.hooks.ts`'s own doc comments), so they get two entirely separate top-level key namespaces
+ * rather than sharing one grandparent. Within each, `list`/`detail(id)` (and `submissionsList(formId)`/
+ * `submissionDetail(formId, id)`) are SIBLINGS, not parent/child — `@jini-ai/ui/fetch-query`'s
+ * `QueryKey` doc warns that invalidation matches by prefix, and `collections/rules.ts`'s own `KEYS`
+ * doc records the regression that bit the predecessor when a detail key nested under its list: every
+ * save silently fired 3 extra background requests because invalidating the list also invalidated the
+ * editor's own currently-open read. Fixed second-array-element ("list" vs "detail") rather than
+ * nesting keeps `KEYS.list`'s invalidation from ever touching an open `KEYS.form(id)`/
+ * `KEYS.submissionDetail(...)` read, regardless of what `id` happens to be.
+ */
+/**
+ * This screen's name on `lib/content-refresh-bus.ts` — see `taxonomy/rules.ts`'s `TAXONOMY_RESOURCE`
+ * for why this is a plain colocated constant rather than a shared registry. `forms_create_definition`/
+ * `forms_update_definition`/`forms_set_definition_status` (`apps/website/src/features/forms/agent-
+ * tools.ts`) are agent-callable, so `FormsList.tsx` needs the same "an assistant write shows up
+ * without a reload" fix `use-taxonomy.hooks.ts` shipped first.
+ */
+export declare const FORMS_LIST_RESOURCE = "forms";
+/** The list has no sort control: recently edited forms belong first. Copy before sorting so
+ * the query cache and injected repository keep their own order; ties retain response order. */
+export declare function newestUpdatedForms({ forms }: {
+    forms: readonly AdminFormDefinition[];
+}, _optional?: Record<string, never>): AdminFormDefinition[];
+/** One line of the Forms list's "Created / Updated" cell. */
+export interface FormDateLine {
+    /** Which event the line shows; `"both"` when the form was never edited after creation. */
+    kind: "created" | "updated" | "both";
+    /** Compact locale date + time (`dateStyle`/`timeStyle` "short"), or "—" for an unparseable date. */
+    text: string;
+    /** ISO instant for `<time dateTime>`; `undefined` when the stored text does not parse. */
+    dateTime: string | undefined;
+    /** Translated event word(s) plus the full date — the hover title and screen-reader text, since
+     *  the visible line carries no "Created"/"Updated" word (the column header already says it). */
+    label: string;
+}
+/** One form event's compact local date and full tooltip. Shared by definitions and submissions;
+ * malformed legacy values stay visible as a dash rather than throwing during table rendering. */
+export declare function formDateDisplay({ iso, locale }: {
+    iso: string;
+    locale: string;
+}, { timeZone }?: {
+    timeZone?: string;
+}): {
+    text: string;
+    full: string;
+    dateTime: string | undefined;
+};
+/** Form-specific date copy. The shared admin timestamp helper intentionally slices ISO text
+ * and its relative helper is English-only; these two events need the operator's locale and
+ * browser time zone. Absolute dates remain accurate while the list stays open without a timer.
+ *
+ * Owner 2026-10-05: line 1 created, line 2 updated, each a compact short date + time with no event
+ * word; one line when updated shows the same date and minute as created. The comparison is on the
+ * displayed short text, so edits within the same minute collapse and the rule follows the locale's
+ * own precision. Intl picks the date order — never a hand-built "M/D/YY".
+ *
+ * @complexity O(1) time and space — two dates, fixed-size formatting.
+ */
+export declare function formDatesLines({ form, locale, t }: {
+    form: Pick<AdminFormDefinition, "createdAt" | "updatedAt">;
+    locale: string;
+    t: (key: string) => string;
+}, options?: {
+    timeZone?: string;
+}): FormDateLine[];
+export declare const KEYS: {
+    list: QueryKey;
+    form: (id: string) => QueryKey;
+    submissionsList: (formId: string) => QueryKey;
+    submissionDetail: (formId: string, submissionId: string) => QueryKey;
+};
+/**
+ * `useFormEditor`'s error banner, extracted out of that hook (`refactor/fetch-query` complexity
+ * pass, 2026-08-12 — same reason `collections/rules.ts`'s `visibleEntryEditorError` was extracted:
+ * the hook's own precedence chain over four sources pushed it past the complexity ceiling).
+ *
+ * Precedence: an active write's own failure (update/create/status, in that order — mirrors
+ * `redirects/rules.ts`'s `firstWriteError` array-order precedence, since `update`/`status` can both
+ * apply to the SAME loaded form) always wins. The list-load failure only surfaces before the form
+ * has ever loaded — once `hasForm` is true, a later BACKGROUND refresh failure must not blank an
+ * editor the operator is actively using (same "a later failure must not erase what already
+ * rendered" guard `FormEditor.tsx`'s own file header already documents at the render layer; this is
+ * its data-layer half).
+ *
+ * @complexity Time/space: O(1) — four fixed checks, no iteration.
+ */
+export declare function visibleFormEditorError(params: {
+    updateError: Error | null;
+    createError: Error | null;
+    statusError: Error | null;
+    listError: Error | null;
+    hasForm: boolean;
+    saveFallback: string;
+    statusUpdateFallback: string;
+    loadFormFallback: string;
+}, _optional?: Record<string, never>): string | null;
+/**
+ * `useFormsList`'s error banner: the row-toggle write's own failure outranks a background
+ * list-refresh failure, same precedence `redirects/rules.ts`'s `visibleRedirectsError` documents.
+ * Two sources only (not the three-plus that pushed `visibleFormEditorError`/`visibleTaxonomyError`
+ * out to `rules.ts`), kept here anyway rather than inlined so the hook body doesn't grow a nested
+ * ternary chain (`@jini-ai/ui/fetch-query`'s `resolveFetchQueryStatus` doc explains why a flat
+ * extraction beats a nested ternary of the same branch count for the complexity gate).
+ *
+ * @complexity Time/space: O(1) — two fixed checks, no iteration.
+ */
+export declare function formsListError(params: {
+    toggleError: Error | null;
+    deleteError: Error | null;
+    listError: Error | null;
+    hasForms: boolean;
+    deleteFallback: string;
+    statusUpdateFallback: string;
+    loadFormsFallback: string;
+    versionChangedMessage: string;
+}, _optional?: Record<string, never>): string | null;
+/**
+ * Classifies a failed `api.trash` call — shared by `useFormsList`'s `removeForm` (forms) and
+ * `useFormSubmissionDetail`'s `confirmDelete` (submissions), since both routes now go through the
+ * same generic `POST /trash/items` (`routes/trash/items.ts`) and its 404/409 contract:
+ *
+ * - 404 (`NOT_FOUND`/`FORMS_SUBMISSION_NOT_FOUND`/…): the row is already gone — another tab,
+ *   another operator, or a prior click that actually succeeded before a flaky response read as a
+ *   failure. `alreadyGone: true`, `message: null` — the caller's job is a quiet list refresh, not
+ *   an error banner blaming the operator for something that already happened.
+ * - 409 `TRASH_VERSION_CHANGED`: the row changed under the operator since this screen last read
+ *   it. Specific reload-and-retry copy, not the generic fallback.
+ * - Anything else (network failure, an unrelated `ApiError`, …): falls through to
+ *   `describeApiError`'s generic fallback message.
+ *
+ * @complexity O(1) — one `instanceof` check plus two fixed comparisons.
+ */
+export declare function describeTrashError({ error: e, fallback, versionChangedMessage }: {
+    error: Error | null;
+    fallback: string;
+    versionChangedMessage: string;
+}, _optional?: Record<string, never>): {
+    alreadyGone: boolean;
+    message: string | null;
+};
+/** The callbacks a form row menu needs. Passed in rather than imported so this module stays free
+ *  of state, mirroring `redirects/rules.ts`'s `RedirectRowMenuHandlers`. `onDelete` opens the
+ *  `ConfirmDialog` in `FormsList.tsx` — see that component's own render for why the actual
+ *  `formsTrash.trash` call waits for the confirm, not this selection. */
+export interface FormRowMenuHandlers {
+    onEdit: (form: AdminFormDefinition) => void;
+    onToggleStatus: (form: AdminFormDefinition) => void;
+    onDelete: (form: AdminFormDefinition) => void;
+}
+/**
+ * The row-action menu for one form. `RowMenu` has no per-item `disabled` — the in-flight guard lives
+ * in `use-forms-list.hooks.ts`'s own `toggleStatus` (a no-op while `rowSavingId` is already set), the
+ * same shape `use-redirects.hooks.ts`'s `onToggleStatus` uses for its identical `if (saving) return;`
+ * guard. (CORRECTED 2026-09-05: this comment previously said the guard "stays in the caller's
+ * `onToggleStatus` closure (`FormsList.tsx`'s own `if (rowSavingId) return;`)" and claimed that was
+ * the same shape `Redirects.tsx` uses — false; `Redirects.tsx` never had such a guard inline, only its
+ * hook does. Flagged by the 2026-09-05 Gemini admin-tooling audit as a standing no-logic-in-`.tsx`
+ * violation; moving the guard into the hook also fixed the comment's own false precedent claim.)
+ *
+ * @complexity Time/space: O(1) — three fixed entries, no iteration.
+ */
+export declare function formRowMenuItems({ form, handlers, t }: {
+    form: AdminFormDefinition;
+    handlers: FormRowMenuHandlers;
+    t: (key: string) => string;
+}, _optional?: Record<string, never>): RowMenuItem[];
+export declare const FIELD_TYPES: readonly ["text", "email", "textarea", "checkbox"];
+/** The two tab-panel views on an existing form's editor (`formId !== "new"`). */
+export declare const FORM_TABS: readonly [{
+    readonly id: "fields";
+    readonly label: "Fields";
+}, {
+    readonly id: "submissions";
+    readonly label: "Submissions";
+}];
+/**
+ * Roving-tabindex arrow-key step for the Fields/Submissions tablist — ArrowLeft/ArrowRight cycle
+ * between the two tabs, Home/End jump to the first/last.
+ *
+ * @complexity O(1) — `FORM_TABS` is a fixed 2-item array.
+ */
+export declare function nextTabIndex({ key, currentIndex }: {
+    key: string;
+    currentIndex: number;
+}, _optional?: Record<string, never>): number | null;
+export declare function blankField(_required?: Record<string, never>, _optional?: Record<string, never>): AdminFormField;
+/** Shared "what do we call this field in a title/label" fallback — a blank draft field has neither
+ *  a label nor an id yet, so both the kebab's `aria-label` and the modal's own `<h2>` need the same
+ *  `label -> id -> "Field N"` chain rather than risking the two drifting apart. */
+export declare function fieldDisplayName({ field, index }: {
+    field: AdminFormField;
+    index: number;
+}, _optional?: Record<string, never>): string;
+/** @complexity O(n) in `fields.length`. */
+export declare function updateFormField({ fields, index, patch }: {
+    fields: AdminFormField[];
+    index: number;
+    patch: Partial<AdminFormField>;
+}, _optional?: Record<string, never>): AdminFormField[];
+/** @complexity O(n) in `fields.length`. */
+export declare function addFormField({ fields }: {
+    fields: AdminFormField[];
+}, _optional?: Record<string, never>): AdminFormField[];
+/** @complexity O(n) in `fields.length`. */
+export declare function removeFormField({ fields, index }: {
+    fields: AdminFormField[];
+    index: number;
+}, _optional?: Record<string, never>): AdminFormField[];
+/** The already-persisted field ids on a form — `FormFieldsEditor` disables the id input and the
+ *  Remove button for these (a saved field's id cannot be changed or removed once created). `null`
+ *  (form not loaded yet, or the "new form" case) has no existing ids. */
+export declare function existingFieldIdsOf({ form }: {
+    form: AdminFormDefinition | null;
+}, _optional?: Record<string, never>): string[];
+/** Mirrors `forms.ts`'s `ATTRIBUTE_NAME_PATTERN` exactly — see `FormEditor.tsx`'s own header
+ *  comment for why this is a fast-reject-only duplicate, not the authoritative check. Keep in sync
+ *  by hand if the server allowlist changes. */
+export declare const ATTRIBUTE_NAME_PATTERN: RegExp;
+/** Same bounds as `forms.ts`'s `MAX_CLASS_NAME_LENGTH`/`MAX_ATTRIBUTES_PER_FIELD` — client-side
+ *  early-reject only, not enforcement (see `ATTRIBUTE_NAME_PATTERN` above). */
+export declare const MAX_CLASS_NAME_LENGTH = 300;
+export declare const MAX_ATTRIBUTES_PER_FIELD = 12;
+/** A handful of the allowlisted names as real, pickable suggestions (the modal's own "here's what
+ *  you can do" surface — an operator has no other way to discover the allowlist) rather than every
+ *  one: `aria-*`/`data-*` are open namespaces, so `aria-label`/`data-testid` stand in for the whole
+ *  prefix family instead of listing every field-specific `aria-*` name that doesn't exist yet. */
+export declare const ATTRIBUTE_NAME_SUGGESTIONS: string[];
+export interface AttrRow {
+    _rowId: number;
+    name: string;
+    value: string;
+}
+export declare function attrRowsFromField({ field }: {
+    field: AdminFormField;
+}, _optional?: Record<string, never>): AttrRow[];
+/** @complexity O(n) in `rows.length`. */
+export declare function updateAttrRow({ rows, rowId, patch }: {
+    rows: AttrRow[];
+    rowId: number;
+    patch: Partial<AttrRow>;
+}, _optional?: Record<string, never>): AttrRow[];
+/** @complexity O(n) in `rows.length`. */
+export declare function removeAttrRow({ rows, rowId }: {
+    rows: AttrRow[];
+    rowId: number;
+}, _optional?: Record<string, never>): AttrRow[];
+/** @complexity O(n) in `rows.length`. */
+export declare function addAttrRow({ rows }: {
+    rows: AttrRow[];
+}, _optional?: Record<string, never>): AttrRow[];
+export type FieldAttributesSubmitResult = {
+    ok: true;
+    patch: Partial<AdminFormField>;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validates + shapes `FieldAttributesDialog`'s draft into the `Partial<AdminFormField>` patch
+ * `onSave` applies: a class-name length cap, then every named attribute row against the allowlist
+ * (blank names are silently skipped — an empty trailing row is not an error), then a total-count
+ * cap on the surviving attributes. The security-relevant check is server-side (`forms.ts`'s
+ * `validateFieldDescriptors`); this is the fast, pre-save rejection only — see this feature's own
+ * `ATTRIBUTE_NAME_PATTERN` doc.
+ *
+ * @complexity O(n) in `rows.length`, short-circuiting on the first disallowed name.
+ */
+export declare function buildFieldAttributesPatch(draft: {
+    className: string;
+    rows: AttrRow[];
+}, _optional?: Record<string, never>): FieldAttributesSubmitResult;
+//# sourceMappingURL=rules.d.ts.map