@cosmicdrift/kumiko-renderer 0.389.0 → 0.390.0

package/dist/components/use-render-edit-draft-save.js

@@ -0,0 +1,141 @@
+import { useCallback, useEffect, useRef } from "react";
+import { buildControlsFor, deriveChangeState, flushPendingDraftSave, } from "./render-edit-draft-save-helpers.js";
+import { PATCH_DRAFT_SAVE_DEBOUNCE_MS } from "./use-wizard-form-draft.js";
+export function useRenderEditDraftSave(props, state, form) {
+    const { controller, snapshot } = form;
+    const { disabled, schema } = props;
+    const { isSubmitting, draftEnabled, dispatcher } = state;
+    // Controlled mode. Both callbacks live in refs so a
+    // re-rendering caller (identity-unstable `onChange`/`onControlsReady`
+    // closures, e.g. inline arrows) doesn't retrigger these effects — only a
+    // real snapshot mutation (typing, patch()) does. Without this, a caller
+    // whose onChange calls patch() to fill other fields (the VIN-decode use
+    // case) would loop: patch → new snapshot → effect
+    // re-subscribes with a "new" onChange → refires.
+    const onChangeRef = useRef(props.onChange);
+    onChangeRef.current = props.onChange;
+    // Guards against redelivering to the SAME callback identity on every
+    // render (an inline-arrow onControlsReady would otherwise refire the
+    // effect below on every render since the callback itself is now a dep).
+    // Tracks the actual prop, not a ref snapshot, so a caller that swaps in a
+    // real handler after mount (e.g. `onControlsReady={ready ? cb : undefined}`)
+    // gets delivered to for THIS mount instead of never.
+    const deliveredControlsToRef = useRef(undefined);
+    const onControlsReadyRef = useRef(props.onControlsReady);
+    onControlsReadyRef.current = props.onControlsReady;
+    const hasNavigatedRef = useRef(false);
+    const submittedRef = useRef(false);
+    const isSubmittingRef = useRef(false);
+    const scopeFieldNamesRef = useRef(form.scopeFieldNames);
+    scopeFieldNamesRef.current = form.scopeFieldNames;
+    const scopedValidate = useCallback(() => controller.validate(scopeFieldNamesRef.current), [controller]);
+    // The extension dirty flag aggregates every section; each section clears its
+    // own part, so a host-side markSaved must not reset it.
+    const markSaved = useCallback((fields) => {
+        if (fields === undefined)
+            controller.rebase();
+        else
+            controller.rebaseFields(fields);
+    }, [controller]);
+    // `saveDraft` (defined below) is a fresh closure every render, over that
+    // render's `draftKey`/`draftId` — the ref lets the debounce timer below
+    // always call the CURRENT one even though the timer was scheduled by an
+    // earlier render's patch() call. `currentStepRef` gives it the current
+    // wizard step without depending on `currentStep` (computed further down,
+    // from `filteredSections`) at the point patchAndScheduleDraftSave itself
+    // is defined — kept fresh where `currentStep` is computed below.
+    const saveDraftRef = useRef(() => { });
+    // `handleSubmit` (defined below) is a fresh closure over this render's
+    // snapshot/extensionDirty, while the onControlsReady effect fires once per
+    // mount — the ref lets controls.submit() always reach the current one.
+    const handleSubmitRef = useRef(async () => { });
+    const wizardNextRef = useRef(() => { });
+    const wizardBackRef = useRef(() => { });
+    const currentStepRef = useRef(0);
+    const draftSaveTimerRef = useRef(null);
+    const refs = {
+        onChangeRef,
+        deliveredControlsToRef,
+        onControlsReadyRef,
+        hasNavigatedRef,
+        submittedRef,
+        isSubmittingRef,
+        scopeFieldNamesRef,
+        saveDraftRef,
+        handleSubmitRef,
+        wizardNextRef,
+        wizardBackRef,
+        currentStepRef,
+        draftSaveTimerRef,
+    };
+    useEffect(() => {
+        return () => flushPendingDraftSave(draftSaveTimerRef, saveDraftRef, currentStepRef);
+    }, []);
+    // patch() (controlled mode, extension sections) applies immediately —
+    // only the resulting draft save is debounced, so a patch() burst
+    // (VIN-decode filling several fields, or onChange fanning a keystroke out
+    // through patch(), see the VIN-decode test above) collapses into one save.
+    const patchAndScheduleDraftSave = useCallback((partial) => {
+        controller.setValues(partial);
+        // skip: no draft screen, locked, or already submitted
+        if (!draftEnabled || dispatcher === undefined || disabled || submittedRef.current)
+            return;
+        if (draftSaveTimerRef.current !== null)
+            clearTimeout(draftSaveTimerRef.current);
+        draftSaveTimerRef.current = setTimeout(() => {
+            draftSaveTimerRef.current = null;
+            // skip: locked or submitted since the timer was set
+            if (disabled || submittedRef.current)
+                return;
+            saveDraftRef.current(currentStepRef.current);
+        }, PATCH_DRAFT_SAVE_DEBOUNCE_MS);
+    }, [controller, draftEnabled, dispatcher, disabled]);
+    // Runs before the onChange effect below (declaration order = React
+    // execution order) so that an onChange fired on mount always sees
+    // `controls !== undefined` — both effects depend only on mount-stable
+    // values (controller/scopedValidate/patchAndScheduleDraftSave), so the
+    // swap is otherwise a no-op. See the VIN-decode test: an initial
+    // value that should derive dependent fields on mount needs controls.patch
+    // available on the very first onChange call, not just from the second
+    // keystroke onward.
+    const hasControlsReady = props.onControlsReady !== undefined;
+    useEffect(() => {
+        // skip: caller registered no onControlsReady
+        if (!hasControlsReady)
+            return;
+        const ready = onControlsReadyRef.current;
+        // skip: callback vanished before this effect ran
+        if (ready === undefined)
+            return;
+        // skip: this callback already received the controls
+        if (deliveredControlsToRef.current === ready)
+            return;
+        deliveredControlsToRef.current = ready;
+        ready(buildControlsFor({
+            controller,
+            patch: patchAndScheduleDraftSave,
+            validate: scopedValidate,
+            handleSubmitRef,
+            wizardNextRef,
+            wizardBackRef,
+        }));
+        // Dep on boolean presence only — inline-arrow identity must not redeliver.
+    }, [hasControlsReady, controller, scopedValidate, patchAndScheduleDraftSave]);
+    // `schema` is typically an inline caller prop (`schema={z.object({...})}`)
+    // with unstable identity across renders — as an effect dep it would refire
+    // on every parent render, not just on a snapshot change, risking a loop if
+    // the caller's onChange triggers a parent re-render. Held in a ref like
+    // onChangeRef so only a real snapshot mutation retriggers this effect.
+    const schemaRef = useRef(schema);
+    schemaRef.current = schema;
+    // Controls are guaranteed ready by the time this fires (see the
+    // onControlsReady effect above, which is declared first on purpose).
+    useEffect(() => {
+        const cb = onChangeRef.current;
+        // skip: caller registered no onChange
+        if (cb === undefined)
+            return;
+        cb(deriveChangeState(snapshot, schemaRef.current, scopeFieldNamesRef.current, isSubmitting));
+    }, [snapshot, isSubmitting]);
+    return { refs, scopedValidate, markSaved, patchAndScheduleDraftSave };
+}

package/dist/components/use-render-edit-form.d.ts

@@ -0,0 +1,10 @@
+import type { FormValues } from "../headless/index.ts";
+import { type UseFormResult } from "../hooks/use-form.ts";
+import type { ResolvedRenderEditProps } from "./render-edit-render-model.ts";
+import type { RenderEditState } from "./use-render-edit-state.ts";
+export type RenderEditForm<TValues extends FormValues> = UseFormResult<TValues> & {
+    readonly scopeFieldNames: readonly string[] | undefined;
+    readonly writeVerb: "create" | "update";
+    readonly clearErrorsOnInput: (changedField: string) => void;
+};
+export declare function useRenderEditForm<TValues extends FormValues, TCtx>(props: ResolvedRenderEditProps<TValues, TCtx>, state: RenderEditState): RenderEditForm<TValues>;

package/dist/components/use-render-edit-form.js

@@ -0,0 +1,101 @@
+import { useEffect, useMemo, useRef } from "react";
+import { layoutEditFields } from "../app/layout-fields.js";
+import { useForm } from "../hooks/use-form.js";
+import { changedDerivedValues } from "./form-derivation-patch.js";
+import { deriveFormFields } from "./render-edit-helpers.js";
+import { issuesAfterEdit } from "./render-edit-logic.js";
+// Must be computed before submitConfig/useForm bakes it in (the controller
+// freezes it on first render). This is the unfiltered field-name set from
+// `fieldsFilter` ∩ `fields` — not the value-dependent `filteredSections`
+// (which also drops `section.visible === false`). Hidden fields still fall
+// out via form-controller's `hiddenFields` path. undefined = unscoped, since
+// scoping would silently drop root-level .refine() issues.
+// A `fieldsFilter` that matches nothing in `fields` (typo, renamed field)
+// must fall back to unscoped too — an empty scope array would filter out
+// ALL validation issues, letting submit() through
+// unvalidated on a form that also renders no sections.
+function useScopeFieldNames(fieldsFilter, fields) {
+    return useMemo(() => {
+        if (fieldsFilter === undefined)
+            return undefined;
+        const matched = fieldsFilter.filter((f) => Object.hasOwn(fields, f));
+        return matched.length === 0 ? undefined : matched;
+    }, [fieldsFilter, fields]);
+}
+// A write-excluded field must never reach the payload: the handler schema is
+// z.never() for it, so even an unchanged read-only value would be rejected.
+function useOmitFields(screen, writeVerb) {
+    return useMemo(() => [
+        ...layoutEditFields(screen)
+            .filter((spec) => spec.submit === false)
+            .map((spec) => spec.field),
+        ...(screen.writeExcludedFields?.[writeVerb] ?? []),
+    ], [screen, writeVerb]);
+}
+function buildSubmitConfig(props, omitFields, scopeFieldNames) {
+    const { writeCommand, payloadMode, buildPayload, serverFieldPathPrefix } = props;
+    return writeCommand !== undefined
+        ? {
+            type: writeCommand,
+            payloadMode,
+            ...(buildPayload !== undefined && { buildPayload }),
+            ...(omitFields.length > 0 && { omitFields }),
+            ...(serverFieldPathPrefix !== undefined && { serverFieldPathPrefix }),
+            ...(scopeFieldNames !== undefined && { validateScope: scopeFieldNames }),
+        }
+        : undefined;
+}
+export function useRenderEditForm(props, state) {
+    const { screen, initial, schema, ctx, formDerivation, refreshToken } = props;
+    const fields = useMemo(() => deriveFormFields(screen), [screen]);
+    const scopeFieldNames = useScopeFieldNames(props.fields, fields);
+    // Configure submission only when the caller provides a writeCommand; with
+    // customSubmit, the form controller has no submit wiring because
+    // controller.submit() is not called.
+    const writeVerb = state.isCreateMode ? "create" : "update";
+    const omitFields = useOmitFields(screen, writeVerb);
+    const submitConfig = buildSubmitConfig(props, omitFields, scopeFieldNames);
+    const { controller, snapshot } = useForm({
+        initial,
+        fields,
+        ...(schema !== undefined && { schema }),
+        ...(ctx !== undefined && { ctx }),
+        ...(submitConfig !== undefined && { submit: submitConfig }),
+    });
+    // Derived fields are written into form state (not only displayed) so required
+    // validation and the submit payload carry them; only a real change is set, which
+    // keeps this from looping.
+    useEffect(() => {
+        // skip: screen has no derived fields
+        if (formDerivation === undefined)
+            return;
+        const patch = changedDerivedValues(snapshot.values, formDerivation);
+        if (patch !== undefined)
+            controller.setValues(patch); // @cast-boundary form-values
+    }, [snapshot.values, formDerivation, controller]);
+    // Wired at the user-input boundary, not in controller.setField: computed
+    // fields, prefill, draft restore and action patches also call setValues
+    // after a failed submit and must not wipe the errors.
+    const clearErrorsOnInput = (changedField) => {
+        const errors = controller.getSnapshot().errors;
+        const remaining = issuesAfterEdit(errors, changedField);
+        if (remaining !== errors)
+            controller.setErrors(remaining);
+        if (state.formErrorSource === "submit" && state.formError?.code !== "version_conflict") {
+            state.setFormError(null);
+        }
+    };
+    const lastRefreshTokenRef = useRef(refreshToken);
+    useEffect(() => {
+        // skip: refreshToken unchanged
+        if (lastRefreshTokenRef.current === refreshToken)
+            return;
+        lastRefreshTokenRef.current = refreshToken;
+        // skip: never overwrite user input, a dirty form keeps its values.
+        if (controller.getSnapshot().isDirty)
+            return;
+        controller.setValues(initial);
+        controller.rebase();
+    }, [refreshToken, controller, initial]);
+    return { controller, snapshot, scopeFieldNames, writeVerb, clearErrorsOnInput };
+}

package/dist/components/use-render-edit-sections.d.ts

@@ -0,0 +1,15 @@
+import { type Dispatch, type ReactNode, type SetStateAction } from "react";
+import type { EditSectionViewModel, EditViewModel, FormValues } from "../headless/index.ts";
+import type { RenderEditCore } from "./render-edit-render-model.ts";
+export type RenderEditSections = {
+    readonly vm: EditViewModel;
+    readonly filteredSections: readonly EditSectionViewModel[];
+    readonly showsAllRequiredHint: boolean;
+    readonly isFormEditable: boolean;
+    readonly isFieldless: boolean;
+    readonly fillHeight: boolean;
+    readonly isLoneWriteFormTab: boolean;
+    readonly writeFormFooterAction: ReactNode;
+    readonly setWriteFormFooterAction: Dispatch<SetStateAction<ReactNode>>;
+};
+export declare function useRenderEditSections<TValues extends FormValues, TCtx>(core: RenderEditCore<TValues, TCtx>): RenderEditSections;

package/dist/components/use-render-edit-sections.js

@@ -0,0 +1,100 @@
+import { useMemo, useState } from "react";
+import { computeEditViewModel } from "../headless/index.js";
+import { filterEditSections, hasEditableSection } from "./render-edit-logic.js";
+function useEditViewModel({ props, state, form, }) {
+    const { screen, entity, featureName, formDerivation, actionFormScreenQn } = props;
+    const entityIdProp = props.entityId;
+    const { translate, isCreateMode } = state;
+    const { writeVerb } = form;
+    const values = form.snapshot.values;
+    return useMemo(() => computeEditViewModel({
+        screen,
+        entity,
+        values,
+        translate,
+        featureName,
+        mode: writeVerb,
+        ...(!isCreateMode && entityIdProp != null && { entityId: entityIdProp }),
+        ...(formDerivation !== undefined && { derivation: formDerivation }),
+        ...(actionFormScreenQn !== undefined && { actionFormScreenQn }),
+    }), [
+        formDerivation,
+        actionFormScreenQn,
+        screen,
+        entity,
+        values,
+        translate,
+        featureName,
+        writeVerb,
+        isCreateMode,
+        entityIdProp,
+    ]);
+}
+function useFilteredSections(vm, fieldsFilter) {
+    return useMemo(
+    // A fully-hidden "fields" section (every field in it currently
+    // condition-hidden) must not occupy a wizard step; it would render
+    // empty and block Back/Next on nothing. Extension, relatedList and
+    // writeForm sections carry no `visible` (they own their own lifecycle /
+    // run their own query / own submit), so they always pass through. A
+    // section with no fields at all (e.g. a review-only step) has
+    // `visible: fields.some(...)` = false vacuously; that's "no fields to
+    // hide", not "hidden", so it stays too. Unless the create
+    // exclusion emptied it: that would leave an empty wizard step / tab.
+    () => filterEditSections(vm.sections, fieldsFilter).filter((section) => section.kind === "extension" ||
+        section.kind === "relatedList" ||
+        section.kind === "writeForm" ||
+        (section.fields.length === 0 && section.emptiedByWriteExclusion !== true) ||
+        section.visible), [vm.sections, fieldsFilter]);
+}
+function useAllFieldsRequired(filteredSections) {
+    return useMemo(() => {
+        const fillable = filteredSections.flatMap((section) => section.kind === "fields"
+            ? section.fields.filter((field) => field.visible && !field.readOnly && field.type !== "boolean")
+            : []);
+        return fillable.length > 0 && fillable.every((field) => field.required);
+    }, [filteredSections]);
+}
+export function useRenderEditSections(core) {
+    const { props, state } = core;
+    const { hideSectionTitles, fillScreenHeight } = props;
+    const vm = useEditViewModel(core);
+    const filteredSections = useFilteredSections(vm, props.fields);
+    const allFieldsRequired = useAllFieldsRequired(filteredSections);
+    const showsAllRequiredHint = allFieldsRequired && hideSectionTitles !== true && !state.isWizard;
+    // true when editable fields exist or an extension opted into composed submit.
+    const isFormEditable = hasEditableSection(filteredSections);
+    // A fieldless form (input-less secretMint mint — the secret is
+    // server-generated, the mint step is only its submit button) has no
+    // section to gate on: it IS the action, so it always shows the submit
+    // button, and it can never go dirty either.
+    const isFieldless = Object.keys(props.entity.fields).length === 0;
+    // A lone relatedList tab (`hideSectionTitles` is only ever set by
+    // ProjectionDetailBody, which hands this component ONE section — its
+    // synthesized screen drops layout.mode, so an entityEdit tabs layout never
+    // reaches this line and `filteredSections[0]` stays the active section)
+    // needs its own tab panel capped at the available height so its table
+    // scrolls inside the panel instead of the whole page stretching to the
+    // row count — a short table still sizes to its content instead
+    // of stretching the panel to the bottom. Any other layout —
+    // multiple sections, a non-relatedList tab, stacked (non-tabs) forms —
+    // keeps normal document-flow height untouched.
+    const fillHeight = fillScreenHeight === true ||
+        (hideSectionTitles === true && filteredSections[0]?.kind === "relatedList");
+    // A lone writeForm tab is the whole page, so its submit joins this form's
+    // footer (pinned to the window edge like every other screen's save)
+    // instead of sitting in the section's title row.
+    const isLoneWriteFormTab = hideSectionTitles === true && filteredSections[0]?.kind === "writeForm";
+    const [writeFormFooterAction, setWriteFormFooterAction] = useState(undefined);
+    return {
+        vm,
+        filteredSections,
+        showsAllRequiredHint,
+        isFormEditable,
+        isFieldless,
+        fillHeight,
+        isLoneWriteFormTab,
+        writeFormFooterAction,
+        setWriteFormFooterAction,
+    };
+}

package/dist/components/use-render-edit-state.d.ts

@@ -0,0 +1,65 @@
+import type { EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ErrorNotice } from "../app/error-reference.tsx";
+import type { DispatcherError, FieldIssue, Translate } from "../headless/index.ts";
+import type { FormErrorSource } from "./render-edit-helpers.tsx";
+export declare function useRenderEditState({ screen, entityId, translate: translateProp, }: {
+    readonly screen: EntityEditScreenDefinition;
+    readonly entityId: string | null | undefined;
+    readonly translate: Translate | undefined;
+}): {
+    confirmDeleteOpen: boolean;
+    setConfirmDeleteOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    linkCopied: boolean;
+    setLinkCopied: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    isSubmitting: boolean;
+    setIsSubmitting: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    focusFirstErrorKey: number;
+    setFocusFirstErrorKey: import("react").Dispatch<import("react").SetStateAction<number>>;
+    formError: DispatcherError | null;
+    setFormError: import("react").Dispatch<import("react").SetStateAction<DispatcherError | null>>;
+    formErrorSource: FormErrorSource;
+    setFormErrorSource: import("react").Dispatch<import("react").SetStateAction<FormErrorSource>>;
+    extraDeleteIssues: readonly FieldIssue[];
+    setExtraDeleteIssues: import("react").Dispatch<import("react").SetStateAction<readonly FieldIssue[]>>;
+    actionError: ErrorNotice | null;
+    setActionError: import("react").Dispatch<import("react").SetStateAction<ErrorNotice | null>>;
+    rawStep: number;
+    setRawStep: import("react").Dispatch<import("react").SetStateAction<number>>;
+    passedStepKeys: ReadonlySet<string>;
+    setPassedStepKeys: import("react").Dispatch<import("react").SetStateAction<ReadonlySet<string>>>;
+    extensionStepComplete: Readonly<Record<string, boolean>>;
+    reportExtensionStepComplete: (stepKey: string, complete: boolean) => void;
+    activeTabId: string | undefined;
+    setActiveTabId: import("react").Dispatch<import("react").SetStateAction<string | undefined>>;
+    extensionDirty: boolean;
+    extensionDirtyRef: import("react").RefObject<boolean>;
+    hasExtensionRegistrations: boolean;
+    extensionErrorKey: string | null;
+    setExtensionErrorKey: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    extensionFormRegistry: import("../app/extension-form-submit.tsx").ExtensionFormRegistry;
+    runExtensionSubmits: (ctx: import("../app/extension-form-submit.tsx").ExtensionSubmitContext) => Promise<readonly import("../app/extension-form-submit.tsx").ExtensionSubmitResult[]>;
+    translate: Translate;
+    dispatcher: import("../headless/index.ts").Dispatcher | undefined;
+    isWizard: boolean;
+    isTabs: boolean;
+    draftEnabled: boolean;
+    isCreateMode: boolean;
+    draftStorage: import("../context/draft-storage-context.tsx").DraftStorage;
+    draftState: {
+        draftId: string | null;
+        setDraftId: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+        draftCandidates: readonly import("./use-wizard-form-draft.ts").DraftCandidate[] | null;
+        setDraftCandidates: import("react").Dispatch<import("react").SetStateAction<readonly import("./use-wizard-form-draft.ts").DraftCandidate[] | null>>;
+        mintedDraftIdRef: import("react").RefObject<string | null>;
+        didListRef: import("react").RefObject<boolean>;
+        draftKey: string | undefined;
+    };
+    primitives: import("../primitives.tsx").PrimitivesRegistry;
+    menuActionToItem: (action: import("./render-edit-types.ts").RenderEditAction) => import("../primitives.tsx").ActionMenuItemSpec;
+    menuActionConfirmDialog: import("react").ReactNode;
+    pageHeaderSlotAvailable: boolean;
+    pageHeaderCompact: boolean;
+    insideDrawer: boolean;
+    isStepped: boolean;
+};
+export type RenderEditState = ReturnType<typeof useRenderEditState>;

package/dist/components/use-render-edit-state.js

@@ -0,0 +1,158 @@
+import { useCallback, useRef, useState } from "react";
+import { useExtensionFormHost } from "../app/extension-form-submit.js";
+import { useOptionalDispatcher } from "../context/dispatcher-context.js";
+import { useDraftStorage } from "../context/draft-storage-context.js";
+import { useTranslation } from "../i18n.js";
+import { useInsideDrawer } from "../inside-drawer.js";
+import { usePageHeaderCompact, usePageHeaderSlotAvailable } from "../page-header-slot.js";
+import { usePrimitives } from "../primitives.js";
+import { useActionMenuItems } from "./use-action-menu-items.js";
+import { useWizardFormDraftState } from "./use-wizard-form-draft.js";
+function useSubmitFeedbackState() {
+    const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
+    const [linkCopied, setLinkCopied] = useState(false);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [focusFirstErrorKey, setFocusFirstErrorKey] = useState(0);
+    const [formError, setFormError] = useState(null);
+    // Only a submit's validation/server error is cleared by editing; a delete
+    // rejection and a version conflict (reload is the way out) stay put.
+    const [formErrorSource, setFormErrorSource] = useState("submit");
+    // A rejected delete can carry several blocking reasons; the first one is the
+    // banner's headline (formError), the rest are listed beneath it.
+    const [extraDeleteIssues, setExtraDeleteIssues] = useState([]);
+    // One state for all header actions (actions?), not per-button — only one
+    // action can be in flight at a time, and this keeps the error surfaced in
+    // the shared formError-adjacent banner region instead of inside the
+    // button row: a full-width Banner there breaks the
+    // flex justify-end action bar.
+    const [actionError, setActionError] = useState(null);
+    return {
+        confirmDeleteOpen,
+        setConfirmDeleteOpen,
+        linkCopied,
+        setLinkCopied,
+        isSubmitting,
+        setIsSubmitting,
+        focusFirstErrorKey,
+        setFocusFirstErrorKey,
+        formError,
+        setFormError,
+        formErrorSource,
+        setFormErrorSource,
+        extraDeleteIssues,
+        setExtraDeleteIssues,
+        actionError,
+        setActionError,
+    };
+}
+function useStepState() {
+    const [rawStep, setRawStep] = useState(0);
+    const [passedStepKeys, setPassedStepKeys] = useState(() => new Set());
+    const [extensionStepComplete, setExtensionStepComplete] = useState({});
+    const reportExtensionStepComplete = useCallback((stepKey, complete) => {
+        setExtensionStepComplete((prev) => (prev[stepKey] === true) === complete ? prev : { ...prev, [stepKey]: complete });
+    }, []);
+    // Tabs have stable ids, so the active tab follows its id: a field change
+    // that hides an earlier tab must not shift the index onto another tab.
+    const [activeTabId, setActiveTabId] = useState(undefined);
+    return {
+        rawStep,
+        setRawStep,
+        passedStepKeys,
+        setPassedStepKeys,
+        extensionStepComplete,
+        reportExtensionStepComplete,
+        activeTabId,
+        setActiveTabId,
+    };
+}
+// Composed save: extension sections report their dirty state so the Save button
+// activates when only a section changed, and provide a submit handler that runs
+// after the entity write. extensionErrorKey stores the i18n key for a failed
+// section persistence.
+//
+// This is not a second write path for saveDraft()'s data: deriveFormFields
+// skips extension sections entirely, so extension-owned field state never enters
+// `fields` or `controller.getSnapshot().values`; there is no draft-covered state
+// left for persistExtensions() to compete over.
+function useExtensionComposition() {
+    const [extensionDirty, setExtensionDirty] = useState(false);
+    // Mirror for the leave guard: it must see "saved" before React re-renders.
+    const extensionDirtyRef = useRef(false);
+    const [hasExtensionRegistrations, setHasExtensionRegistrations] = useState(false);
+    const [extensionErrorKey, setExtensionErrorKey] = useState(null);
+    const { registry: extensionFormRegistry, runAll: runExtensionSubmits } = useExtensionFormHost(({ anyDirty, hasRegistrations }) => {
+        extensionDirtyRef.current = anyDirty;
+        setExtensionDirty(anyDirty);
+        setHasExtensionRegistrations(hasRegistrations);
+    });
+    return {
+        extensionDirty,
+        extensionDirtyRef,
+        hasExtensionRegistrations,
+        extensionErrorKey,
+        setExtensionErrorKey,
+        extensionFormRegistry,
+        runExtensionSubmits,
+    };
+}
+export function useRenderEditState({ screen, entityId, translate: translateProp, }) {
+    // Translate fallback: when the caller does not provide a translate function,
+    // consume the i18next context directly. Otherwise field labels would remain raw
+    // keys (`feature:entity:foo:field:title`) without caller wiring.
+    // useTranslation throws without a LocaleProvider, which is acceptable because
+    // RenderEdit only runs inside a mounted Kumiko app tree.
+    const t = useTranslation();
+    const translate = translateProp ?? t;
+    const dispatcher = useOptionalDispatcher();
+    const isWizard = screen.layout.mode === "wizard";
+    // Tabs reuse the wizard's step machinery: one section visible at a time,
+    // all of them mounted, `currentStep` as the active index. What they do NOT
+    // share is navigation — a tab form submits from any tab, so every
+    // step-transition path below stays wizard-only.
+    const isTabs = screen.layout.mode === "tabs";
+    const draftEnabled = isWizard && screen.layout.draft === true && dispatcher !== undefined;
+    const isCreateMode = entityId === undefined || entityId === null || entityId === "";
+    const draftStorage = useDraftStorage();
+    const feedback = useSubmitFeedbackState();
+    const stepState = useStepState();
+    const draftState = useWizardFormDraftState({
+        screenId: screen.id,
+        entityId,
+        isCreateMode,
+        draftStorage,
+    });
+    const extensions = useExtensionComposition();
+    const primitives = usePrimitives();
+    const { toMenuItem: menuActionToItem, confirmDialog: menuActionConfirmDialog } = useActionMenuItems({ Dialog: primitives.Dialog, onError: feedback.setActionError });
+    const pageHeaderSlotAvailable = usePageHeaderSlotAvailable();
+    const pageHeaderCompact = usePageHeaderCompact();
+    const insideDrawer = useInsideDrawer();
+    // Both stepped layouts show one section at a time and keep the rest mounted
+    // but inert. A tabs layout on a host without the Tabs primitive has no strip
+    // to switch with, so it falls back to rendering every section stacked rather
+    // than stranding the user on section 0. Same fallback when the
+    // WizardStepGroup wrapper is missing.
+    const isStepped = isWizard ||
+        (isTabs && primitives.Tabs !== undefined && primitives.WizardStepGroup !== undefined);
+    return {
+        translate,
+        dispatcher,
+        isWizard,
+        isTabs,
+        draftEnabled,
+        isCreateMode,
+        draftStorage,
+        ...feedback,
+        ...stepState,
+        draftState,
+        ...extensions,
+        primitives,
+        menuActionToItem,
+        menuActionConfirmDialog,
+        pageHeaderSlotAvailable,
+        pageHeaderCompact,
+        insideDrawer,
+        isStepped,
+    };
+}

package/dist/components/use-render-edit-steps.d.ts

@@ -0,0 +1,13 @@
+import type { FormValues } from "../headless/index.ts";
+import type { RenderEditSectioned } from "./render-edit-render-model.ts";
+export type RenderEditSteps = {
+    readonly lastStepIndex: number;
+    readonly currentStep: number;
+    readonly isLastWizardStep: boolean;
+    readonly wizardDoneSteps: readonly boolean[] | undefined;
+    readonly updateModeStepBarProps: Record<string, never> | {
+        readonly doneSteps: readonly boolean[];
+        readonly selectableSteps: "all";
+    };
+};
+export declare function useRenderEditSteps<TValues extends FormValues, TCtx>({ props, state, form, draft, sections, }: RenderEditSectioned<TValues, TCtx>): RenderEditSteps;

package/dist/components/use-render-edit-steps.js

@@ -0,0 +1,52 @@
+import { useMemo } from "react";
+import { dryRunParse, isFieldsStepFilled, tabIdAt, wizardStepKey } from "./render-edit-helpers.js";
+function computeCurrentStep(isTabs, activeTabId, rawStep, filteredSections) {
+    const lastStepIndex = Math.max(filteredSections.length - 1, 0);
+    // Clamped on read, not on write: section visibility is value-dependent, so a
+    // stored stepIndex can point past what is currently rendered — that lands on
+    // the last step instead of an empty one.
+    const activeTabIndex = isTabs && activeTabId !== undefined
+        ? filteredSections.findIndex((s, i) => tabIdAt(s, i) === activeTabId)
+        : -1;
+    const currentStep = activeTabIndex !== -1 ? activeTabIndex : Math.min(rawStep, lastStepIndex);
+    return { currentStep, lastStepIndex };
+}
+function isStepDone(section, index, passedStepKeys, extensionStepComplete, parse) {
+    if (passedStepKeys.has(wizardStepKey(section, index)))
+        return true;
+    if (section.kind === "fields")
+        return isFieldsStepFilled(section, parse);
+    return (section.kind === "extension" && extensionStepComplete[wizardStepKey(section, index)] === true);
+}
+export function useRenderEditSteps({ props, state, form, draft, sections, }) {
+    const { filteredSections } = sections;
+    const { schema } = props;
+    const { isWizard, isCreateMode, passedStepKeys, extensionStepComplete } = state;
+    const { currentStep, lastStepIndex } = computeCurrentStep(state.isTabs, state.activeTabId, state.rawStep, filteredSections);
+    // Kept fresh for patchAndScheduleDraftSave's debounce timer above, which
+    // is defined before `currentStep` exists (it depends on `filteredSections`,
+    // computed further up from `vm`) and so cannot close over it directly.
+    draft.refs.currentStepRef.current = currentStep;
+    const isLastWizardStep = currentStep >= lastStepIndex;
+    const wizardDoneSteps = useMemo(() => {
+        if (!isWizard || isCreateMode)
+            return undefined;
+        const parse = schema === undefined
+            ? undefined
+            : dryRunParse(schema, { values: form.snapshot.values, fields: form.snapshot.fields });
+        return filteredSections.map((section, index) => isStepDone(section, index, passedStepKeys, extensionStepComplete, parse));
+    }, [
+        isWizard,
+        isCreateMode,
+        filteredSections,
+        passedStepKeys,
+        extensionStepComplete,
+        schema,
+        form.snapshot.values,
+        form.snapshot.fields,
+    ]);
+    const updateModeStepBarProps = wizardDoneSteps === undefined
+        ? {}
+        : { doneSteps: wizardDoneSteps, selectableSteps: "all" };
+    return { lastStepIndex, currentStep, isLastWizardStep, wizardDoneSteps, updateModeStepBarProps };
+}