@cosmicdrift/kumiko-renderer 0.389.0 → 0.390.1

package/dist/components/render-edit-layout.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ExtensionFormRegistryProvider } from "../app/extension-form-submit.js";
+import { renderActionErrorBanner, renderAllRequiredHint, renderDeleteDialog, renderDraftPicker, renderExtensionErrorBanner, renderFormErrorBanner, renderRootIssueBanners, renderTabStrip, renderWizardProgress, } from "./render-edit-banners.js";
+import { renderFormActions } from "./render-edit-form-actions.js";
+import { buildHeaderActions } from "./render-edit-header-actions.js";
+import { renderEditSections } from "./render-edit-section-kinds.js";
+import { AllFieldsRequiredProvider } from "./render-field.js";
+function renderPageHeader({ engine: { state }, layout, titles }, { headerMenuItems }) {
+    const { PageHeader, ActionOverflowMenu } = state.primitives;
+    const { pageHeaderCompact } = state;
+    return (layout.titleInShell &&
+        PageHeader !== undefined && (_jsx(PageHeader, { title: titles.formTitle, ...(titles.recordTitle !== undefined && { recordTitle: titles.recordTitle }), ...(headerMenuItems.length > 0 && pageHeaderCompact && { overflowItems: headerMenuItems }), ...(headerMenuItems.length > 0 &&
+            !pageHeaderCompact &&
+            ActionOverflowMenu !== undefined && {
+            actions: (_jsx(ActionOverflowMenu, { label: state.translate("kumiko.list.row-actions.more"), items: headerMenuItems, testId: "render-edit-header-menu" })),
+        }) })));
+}
+function renderWizardSideRail({ engine: { state, steps, sections, nav }, titles, }) {
+    const { StepBar } = state.primitives;
+    const { translate } = state;
+    const { upNextSection, formSubtitle } = titles;
+    if (StepBar === undefined)
+        return undefined;
+    return (_jsx(StepBar, { steps: sections.filteredSections.map((section) => section.title ?? ""), currentIndex: steps.currentStep, compactLabel: titles.compactStepLabel, onStepSelect: nav.handleWizardStepSelect, ...steps.updateModeStepBarProps, orientation: "vertical", heading: translate("kumiko.wizard.step", {
+            current: steps.currentStep + 1,
+            total: steps.lastStepIndex + 1,
+        }), ...(formSubtitle !== undefined && { description: formSubtitle }), subtitles: sections.filteredSections.map((section) => section.kind === "fields" ? section.subtitle : undefined), ...(upNextSection !== undefined && {
+            upNext: {
+                heading: translate("kumiko.wizard.up-next"),
+                title: upNextSection.title ?? "",
+                ...(upNextSection.kind === "fields" &&
+                    upNextSection.subtitle !== undefined && { subtitle: upNextSection.subtitle }),
+            },
+        }), testId: "render-edit-wizard-steps", compactTestId: "render-edit-wizard-step-label" }));
+}
+function buildFormHeadingProps(model) {
+    const { props } = model.engine;
+    const { layout, footer, titles } = model;
+    const { unsavedCount, hasDirtyFooter } = footer;
+    return {
+        ...(props.hideSectionTitles !== true &&
+            !layout.titleInShell &&
+            !titles.titleInSettingsHeader &&
+            !titles.recordTitleInHeaderRegion && { title: titles.formTitle }),
+        ...(titles.formSubtitle !== undefined &&
+            !titles.stepRail &&
+            !titles.titleInSettingsHeader && { subtitle: titles.formSubtitle }),
+        ...(layout.isScreenForm && { screenForm: true }),
+        ...(unsavedCount !== undefined && (unsavedCount > 0 || hasDirtyFooter) && { unsavedCount }),
+        ...(titles.sectionNavItems.length > 0 && { sectionNav: titles.sectionNavItems }),
+        ...(titles.stepRail && { sideRail: renderWizardSideRail(model) }),
+    };
+}
+function buildFormActionProps(model, header) {
+    const { hideActions } = model.engine.props;
+    const { footer, layout } = model;
+    return {
+        ...(hideActions !== true && footer.hasFormActions && { actions: renderFormActions(model) }),
+        ...(hideActions !== true &&
+            layout.hasSecondaryFormActions && { secondaryActions: header.secondaryFormActions }),
+    };
+}
+function buildFormChromeProps({ engine: { props, sections } }, { formHeaderRegion, titleActionMount }) {
+    const { summary } = props;
+    return {
+        ...(props.screen.layout.width !== undefined && { width: props.screen.layout.width }),
+        ...(formHeaderRegion !== undefined && { headerRegion: formHeaderRegion }),
+        ...(titleActionMount !== undefined && { titleAction: titleActionMount }),
+        ...(sections.fillHeight && { fillHeight: sections.fillHeight }),
+        ...(props.hideSectionTitles === true && { chromeless: true }),
+        ...(summary !== undefined && { summary }),
+    };
+}
+export function renderEditLayout(model) {
+    const { props, state, sections, handleSubmit } = model.engine;
+    const header = buildHeaderActions(model);
+    const { Form } = state.primitives;
+    return (_jsxs(ExtensionFormRegistryProvider, { value: state.extensionFormRegistry, children: [state.menuActionConfirmDialog, renderPageHeader(model, header), _jsx(Form, { onSubmit: () => void handleSubmit(), ...(state.focusFirstErrorKey > 0 && { focusFirstErrorKey: state.focusFirstErrorKey }), ...buildFormHeadingProps(model), ...buildFormActionProps(model, header), testId: "render-edit-form", stickyActions: state.isWizard || props.fillScreenHeight === true, ...buildFormChromeProps(model, header), children: _jsxs(AllFieldsRequiredProvider, { value: sections.showsAllRequiredHint, children: [props.leadContent, sections.showsAllRequiredHint && !state.insideDrawer && renderAllRequiredHint(model), renderDraftPicker(model), renderWizardProgress(model), state.isTabs && state.isStepped && renderTabStrip(model), renderEditSections(model), renderFormErrorBanner(model), renderRootIssueBanners(model), renderExtensionErrorBanner(model), renderActionErrorBanner(model), renderDeleteDialog(model)] }) })] }));
+}

package/dist/components/render-edit-render-model.d.ts

@@ -0,0 +1,63 @@
+import type { ReactNode } from "react";
+import type { EditSectionViewModel, EditViewModel, FormValues } from "../headless/index.ts";
+import type { FooterFlags, LayoutFlags } from "./render-edit-layout-flags.ts";
+import type { TitleModel } from "./render-edit-titles.ts";
+import type { RenderEditProps } from "./render-edit-types.ts";
+import type { WizardNavigation } from "./render-edit-wizard-navigation.ts";
+import type { RenderEditDraft } from "./use-render-edit-draft-save.ts";
+import type { RenderEditForm } from "./use-render-edit-form.ts";
+import type { RenderEditSections } from "./use-render-edit-sections.ts";
+import type { RenderEditState } from "./use-render-edit-state.ts";
+import type { RenderEditSteps } from "./use-render-edit-steps.ts";
+import type { buildWizardDraftActions } from "./use-wizard-form-draft.ts";
+type ResolvedKeys = "payloadMode" | "markChangedFields" | "disabled" | "viewMode" | "valueDisplay" | "submitBlocked" | "i18nScreenId";
+export type ResolvedRenderEditProps<TValues extends FormValues, TCtx = unknown> = Omit<RenderEditProps<TValues, TCtx>, ResolvedKeys> & {
+    readonly payloadMode: "values" | "changes";
+    readonly markChangedFields: boolean;
+    readonly disabled: boolean;
+    readonly viewMode: boolean;
+    readonly valueDisplay: "form" | "text";
+    readonly submitBlocked: boolean;
+    readonly i18nScreenId: string;
+};
+export declare function resolveRenderEditProps<TValues extends FormValues, TCtx>(props: RenderEditProps<TValues, TCtx>): ResolvedRenderEditProps<TValues, TCtx>;
+export type RenderEditCore<TValues extends FormValues, TCtx = unknown> = {
+    readonly props: ResolvedRenderEditProps<TValues, TCtx>;
+    readonly state: RenderEditState;
+    readonly form: RenderEditForm<TValues>;
+    readonly draft: RenderEditDraft<TValues>;
+};
+export type RenderEditSectioned<TValues extends FormValues, TCtx = unknown> = RenderEditCore<TValues, TCtx> & {
+    readonly sections: RenderEditSections;
+};
+export type RenderEditSteppedCore<TValues extends FormValues, TCtx = unknown> = RenderEditSectioned<TValues, TCtx> & {
+    readonly steps: RenderEditSteps;
+};
+export type WizardDraftActions<TValues extends FormValues> = ReturnType<typeof buildWizardDraftActions<TValues>>;
+export type RenderEditEngineBase<TValues extends FormValues, TCtx = unknown> = RenderEditSteppedCore<TValues, TCtx> & {
+    readonly draftActions: WizardDraftActions<TValues>;
+    readonly nav: WizardNavigation;
+};
+export type RenderEditEngine<TValues extends FormValues, TCtx = unknown> = RenderEditEngineBase<TValues, TCtx> & {
+    readonly handleSubmit: (options?: {
+        readonly saveNow?: boolean;
+    }) => Promise<void>;
+};
+export type { EditSectionViewModel, EditViewModel };
+export type RenderEditModel<TValues extends FormValues, TCtx = unknown> = {
+    readonly engine: RenderEditEngine<TValues, TCtx>;
+    readonly layout: LayoutFlags;
+    readonly footer: FooterFlags;
+    readonly titles: TitleModel;
+    readonly setFieldUntyped: (k: string, v: unknown) => void;
+    readonly patchForExtension: (partial: Readonly<Record<string, unknown>>) => void;
+};
+export type SectionRenderContext<TValues extends FormValues, TCtx = unknown> = {
+    readonly model: RenderEditModel<TValues, TCtx>;
+    readonly sectionIndex: number;
+    readonly sectionActionsEl: ReactNode;
+    readonly wrapWizardStep: (key: string, el: ReactNode) => ReactNode;
+};
+export type FieldsSection = Extract<EditSectionViewModel, {
+    readonly kind: "fields";
+}>;

package/dist/components/render-edit-render-model.js

@@ -0,0 +1,14 @@
+// View mode is a locked form, so everything keyed on `disabled` follows.
+export function resolveRenderEditProps(props) {
+    const viewMode = props.viewMode ?? false;
+    return {
+        ...props,
+        payloadMode: props.payloadMode ?? "values",
+        markChangedFields: props.markChangedFields ?? false,
+        viewMode,
+        disabled: (props.disabled ?? false) || viewMode,
+        valueDisplay: props.valueDisplay ?? "form",
+        submitBlocked: props.submitBlocked ?? false,
+        i18nScreenId: props.i18nScreenId ?? props.screen.id,
+    };
+}

package/dist/components/render-edit-section-kinds.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from "react";
+import type { FormValues } from "../headless/index.ts";
+import type { RenderEditModel } from "./render-edit-render-model.ts";
+export declare function renderEditSections<TValues extends FormValues, TCtx>(model: RenderEditModel<TValues, TCtx>): ReactNode;

package/dist/components/render-edit-section-kinds.js

@@ -0,0 +1,115 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ExtensionSectionMount } from "./edit-mounts.js";
+import { RelatedListSection } from "./related-list-section.js";
+import { RenderEditActionButton } from "./render-edit-action-button.js";
+import { renderFieldsSection } from "./render-edit-fields-section.js";
+import { wizardStepKey } from "./render-edit-helpers.js";
+import { resolveExtensionEntityId } from "./render-edit-logic.js";
+import { WriteFormSection } from "./write-form-section.js";
+function renderExtensionSection({ model, sectionIndex, sectionActionsEl, wrapWizardStep }, section) {
+    const { props, state, form, draft, sections } = model.engine;
+    const { hideSectionTitles } = props;
+    const { Card } = state.primitives;
+    const mount = (_jsx(ExtensionSectionMount, { section: section, entityName: sections.vm.entityName, entityId: resolveExtensionEntityId(props.entityId, sections.vm.id), initialValues: props.extensionInitialValues, values: form.snapshot.values, patch: model.patchForExtension, validate: draft.scopedValidate, markSaved: draft.markSaved, hideTitle: hideSectionTitles, ...(state.isWizard &&
+            !state.isCreateMode && {
+            stepKey: wizardStepKey(section, sectionIndex),
+            onReportStepComplete: state.reportExtensionStepComplete,
+        }), ...(hideSectionTitles !== true &&
+            sectionActionsEl !== undefined && { actions: sectionActionsEl }) }, section.title));
+    // Tabs mode: an unframed padded panel (the tab panel is the
+    // surface), so extension content neither sits flush at the shell
+    // edge nor touches the tab strip. testId stays only on the inner
+    // Section — giving the wrapper the same one would register two
+    // elements under one id.
+    const wrapped = hideSectionTitles !== true ? (mount) : (_jsx(Card, { options: { framed: false }, ...(sectionActionsEl !== undefined && {
+            slots: { headerActions: sectionActionsEl },
+        }), children: mount }, section.title));
+    return wrapWizardStep(section.title, wrapped);
+}
+function renderRelatedListSection({ model, sectionActionsEl }, section) {
+    const { props, form, sections } = model.engine;
+    const { hideSectionTitles, fillScreenHeight, refreshToken, onRelatedListDrawerAction } = props;
+    // parentId is the displayed record's id — without it there's no
+    // parent row whose related rows could be queried.
+    // Rejected at boot in wizard layouts, so no WizardStepGroup here.
+    const parentId = resolveExtensionEntityId(props.entityId, sections.vm.id);
+    if (parentId === null)
+        return null;
+    const mount = (_jsx(RelatedListSection, { section: section, parentId: parentId, 
+        // @cast-boundary form-values: TValues is structurally a Record.
+        record: form.snapshot.values, featureName: props.featureName, translate: model.engine.state.translate, hideTitle: hideSectionTitles, ...(refreshToken !== undefined && { refreshToken }), ...(fillScreenHeight === true && { grow: true }), ...(hideSectionTitles !== true &&
+            sectionActionsEl !== undefined && { actions: sectionActionsEl }), ...(onRelatedListDrawerAction !== undefined && {
+            onOpenDrawer: onRelatedListDrawerAction,
+        }) }, section.title));
+    // Tabs mode: the table runs full-bleed under the tab strip (board
+    // layout); the toolbar buttons live in the list's own toolbar.
+    return hideSectionTitles === true ? (_jsx("div", { className: fillScreenHeight === true ? "flex min-h-0 flex-1 flex-col" : undefined, children: mount }, section.title)) : (mount);
+}
+function renderWriteFormSection({ model, sectionIndex, sectionActionsEl }, section) {
+    const { props, state, sections } = model.engine;
+    // Own submit button + dispatcher call, entirely independent of
+    // this screen's (nonexistent, on projectionDetail) form submit —
+    // rejected at boot in wizard layouts, so no WizardStepGroup here.
+    return (_jsx(WriteFormSection, { section: section, featureName: props.featureName, translate: state.translate, hideTitle: props.hideSectionTitles, onSubmitted: () => props.onReload?.(), ...(sections.isLoneWriteFormTab && { onFooterAction: sections.setWriteFormFooterAction }), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }) }, section.title ?? `write-form-${sectionIndex}`));
+}
+function renderSectionByKind(rc, section) {
+    switch (section.kind) {
+        case "extension":
+            return renderExtensionSection(rc, section);
+        case "relatedList":
+            return renderRelatedListSection(rc, section);
+        case "writeForm":
+            return renderWriteFormSection(rc, section);
+        case "fields":
+            return renderFieldsSection(rc, section);
+    }
+}
+// turns this section's own `actions` (RowAction[]) into
+// already-bound buttons via the caller-supplied builder, rendered
+// through the same RenderEditActionButton the top-level `actions`
+// prop uses (same style/confirm/icon/error handling).
+function renderSectionActions({ engine: { props, state } }, section) {
+    const sectionActions = section.actions;
+    if (sectionActions === undefined || sectionActions.length === 0)
+        return undefined;
+    const { Button, Dialog } = state.primitives;
+    return props
+        .buildSectionActions?.(sectionActions)
+        ?.map((action) => (_jsx(RenderEditActionButton, { action: action, Button: Button, Dialog: Dialog, onError: state.setActionError }, action.id)));
+}
+// Wizard steps and tabs stay mounted while off-screen (native
+// `hidden`, not unmounted) so an extension section's submit-registry
+// entry (useExtensionFormSubmit → registry.remove on unmount)
+// survives navigating past its step — otherwise Finish only ran the
+// last mounted step's handler and silently dropped earlier steps'
+// writes. For tabs this is also what makes ONE submit cover every
+// tab, including tabs the user never opened.
+// Off-screen wizard steps stay mounted (see comment above) but must
+// not participate in native constraint validation, or the Next
+// button's `type="submit"` triggers the browser's full-form check
+// — including required fields on unvisited steps, which are not
+// focusable while hidden, so the wizard silently stops navigating
+// (only a console warning, no visible error). A plain `hidden`
+// attribute does NOT bar descendants from constraint validation on
+// web — see WizardStepGroupProps for what implementations must
+// guarantee.
+function createWizardStepWrapper({ engine: { props, state, steps } }, sectionIndex) {
+    const { WizardStepGroup } = state.primitives;
+    const stepHidden = state.isStepped && sectionIndex !== steps.currentStep;
+    return (key, el) => {
+        if (!state.isStepped)
+            return el;
+        if (WizardStepGroup === undefined) {
+            throw new Error(`RenderEdit: ${props.screen.layout.mode} layout requires primitives.WizardStepGroup, but none is registered.`);
+        }
+        return (_jsx(WizardStepGroup, { hidden: stepHidden, ...(props.hideSectionTitles === true && { inset: true }), children: el }, key));
+    };
+}
+export function renderEditSections(model) {
+    return model.engine.sections.filteredSections.map((section, sectionIndex) => renderSectionByKind({
+        model,
+        sectionIndex,
+        sectionActionsEl: renderSectionActions(model, section),
+        wrapWizardStep: createWizardStepWrapper(model, sectionIndex),
+    }, section));
+}

package/dist/components/render-edit-submit-result.d.ts

@@ -0,0 +1,8 @@
+import type { FormValues, SubmitResult } from "../headless/index.ts";
+import type { RenderEditEngineBase } from "./render-edit-render-model.ts";
+export declare function createSubmitResultHandlers<TValues extends FormValues, TCtx>({ props, state, form, draft, sections, draftActions, nav, }: RenderEditEngineBase<TValues, TCtx>): {
+    handleSubmitSuccess: (isNoOp: boolean) => Promise<boolean>;
+    applySubmitFailure: (result: Exclude<SubmitResult<unknown>, {
+        isSuccess: true;
+    }>) => void;
+};

package/dist/components/render-edit-submit-result.js

@@ -0,0 +1,77 @@
+import { groupIssuesByPath } from "../headless/index.js";
+import { hasIssueWithoutRenderedField } from "./render-edit-logic.js";
+export function createSubmitResultHandlers({ props, state, form, draft, sections, draftActions, nav, }) {
+    const { controller } = form;
+    const { customSubmit } = props;
+    const { submittedRef } = draft.refs;
+    // `isNoOp: true` (payloadMode "changes", pre-filled form submitted
+    // untouched) means controller.submit() never called dispatcher.write
+    // — nothing to discard, and discarding here would delete a draft the
+    // form never persisted. Awaited, not fire-and-forget:
+    // `onSubmit` typically navigates away and unmounts this form, which
+    // would abort an in-flight discard and leave the draft behind after
+    // a successful submit.
+    // Resolves to whether the extension sections persisted (true when none ran).
+    async function handleSubmitSuccess(isNoOp) {
+        state.setFormError(null);
+        state.setExtraDeleteIssues([]);
+        if (!isNoOp) {
+            submittedRef.current = true;
+            await draftActions.discardDraft();
+        }
+        const extensionsPersisted = await nav.persistExtensions();
+        if (extensionsPersisted)
+            state.extensionDirtyRef.current = false;
+        return extensionsPersisted;
+    }
+    function jumpToFirstErroringStep(fieldPaths) {
+        // skip: unstepped layouts have no step to jump to
+        if (!state.isStepped)
+            return;
+        const step = nav.findFirstErroringStep(fieldPaths);
+        if (step !== undefined)
+            nav.jumpToStep(step);
+    }
+    // Root-level `.refine()`/cross-field issues from controller.validate()
+    // — same "jump to the erroring step" treatment as a server field
+    // error below, sourced from the freshly-validated snapshot.
+    function handleValidationBlocked() {
+        state.setFocusFirstErrorKey((key) => key + 1);
+        jumpToFirstErroringStep(Object.keys(controller.getSnapshot().errors));
+    }
+    function handleSubmitError(error) {
+        const fieldIssues = error.details?.fields ?? [];
+        const issuePaths = fieldIssues.map((i) => i.path);
+        if (fieldIssues.length > 0)
+            state.setFocusFirstErrorKey((key) => key + 1);
+        // controller.submit() writes server issues into the controller itself;
+        // customSubmit bypasses it, so push them here to reach the fields.
+        if (customSubmit !== undefined && fieldIssues.length > 0) {
+            controller.setErrors(groupIssuesByPath(fieldIssues));
+        }
+        // A server field error on a step the form isn't currently showing is
+        // otherwise invisible — jump to the first step that contains one of
+        // the errored fields. For tabs this is what keeps the submit from
+        // blocking in silence, the failure mode the boot-validator used to
+        // prevent by rejecting the layout outright. An issue no
+        // rendered field can show (`version`, `id`, a root-level refine, a
+        // hidden field) keeps the banner, jump or not.
+        jumpToFirstErroringStep(issuePaths);
+        state.setExtraDeleteIssues([]);
+        state.setFormErrorSource("submit");
+        state.setFormError(hasIssueWithoutRenderedField(issuePaths, sections.filteredSections, new Set(Object.keys(props.formDerivation?.derive ?? {})))
+            ? error
+            : null);
+    }
+    // Form-level errors (without field-level details) go to the banner.
+    // Field errors flow via snapshot.errors into the individual fields.
+    // Synchronous on purpose: awaiting here would defer the state updates by a
+    // microtask and let React render intermediate states.
+    function applySubmitFailure(result) {
+        if (result.validationBlocked)
+            handleValidationBlocked();
+        else
+            handleSubmitError(result.error);
+    }
+    return { handleSubmitSuccess, applySubmitFailure };
+}

package/dist/components/render-edit-submit.d.ts

@@ -0,0 +1,7 @@
+import type { FormValues } from "../headless/index.ts";
+import type { RenderEditEngineBase } from "./render-edit-render-model.ts";
+type SubmitOptions = {
+    readonly saveNow?: boolean;
+};
+export declare function createHandleSubmit<TValues extends FormValues, TCtx>(engine: RenderEditEngineBase<TValues, TCtx>): (options?: SubmitOptions) => Promise<void>;
+export {};

package/dist/components/render-edit-submit.js

@@ -0,0 +1,113 @@
+import { shouldNotifyCaller } from "./render-edit-logic.js";
+import { createSubmitResultHandlers } from "./render-edit-submit-result.js";
+// Rebuilt every render on purpose: the closures read this render's snapshot
+// and extension state, while handleSubmitRef publishes the current one.
+export function createHandleSubmit(engine) {
+    const { props, state, form, draft, steps, draftActions, nav } = engine;
+    const { handleSubmitSuccess, applySubmitFailure } = createSubmitResultHandlers(engine);
+    const { controller, snapshot } = form;
+    const { customSubmit } = props;
+    const { submittedRef, isSubmittingRef } = draft.refs;
+    // Same discard as the main path: an extension-only save is still a
+    // successful submit, so the draft must not survive it.
+    async function submitExtensionsOnly() {
+        // skip: an extension section failed, its error banner is showing
+        if (!(await nav.persistExtensions()))
+            return;
+        state.extensionDirtyRef.current = false;
+        submittedRef.current = true;
+        await draftActions.discardDraft();
+    }
+    // customSubmit path (e.g. configEdit, which performs a separate write per
+    // field). Validate on the client first, then call the caller; on success,
+    // explicitly rebase the form state because controller.submit() normally
+    // does this itself, and the controller otherwise knows nothing about a
+    // successful custom submission (isUnchanged would remain false).
+    //
+    // Read the snapshot directly from the controller rather than React state.
+    // With rapid fill-then-click input, React batching may not have committed
+    // state updates when the submit click fires. handleSubmit's closure could otherwise
+    // see stale snapshot.changes={} and perform no writes, then return success
+    // and rebase the form, making it appear that the data was saved.
+    // controller.getSnapshot() is always current: the controller is the
+    // source of truth, while React state is only a rendering mirror.
+    function blockedCustomSubmitResult() {
+        if (controller.validate(form.scopeFieldNames))
+            return undefined;
+        // Field order matters: validationBlocked:true is its own
+        // variant in the SubmitResult union (NOT mixed with data/error);
+        // TS only narrows cleanly without a discriminator fight.
+        const blocked = {
+            validationBlocked: true,
+            isSuccess: false,
+        };
+        return blocked;
+    }
+    // Enter in the active step triggers the native form submit (Next is
+    // type="submit" for Enter support) — on intermediate steps that means
+    // "Next", not "Save". Checked BEFORE the `disabled` guard below:
+    // `disabled` means "no input/no write", not "no navigation" — a
+    // disabled wizard must still be steppable (handleWizardNext itself
+    // blocks validate()/saveDraft() while disabled). `saveNow` is the explicit
+    // "Save and close" button and skips the step advance.
+    function advancesWizardInsteadOfSaving(options) {
+        return state.isWizard && !steps.isLastWizardStep && options?.saveNow !== true;
+    }
+    // Locked state: the submit button is visibly disabled, but a
+    // native form submit (Enter key) reaches this handler regardless of the
+    // button's disabled attribute — block it here too, not just in the UI.
+    // Sync guard for the in-flight part — React state `isSubmitting` is too late
+    // for double-clicks in the same tick (customSubmit has no submitInFlight of its own).
+    function isSubmitBlocked() {
+        return props.disabled === true || props.submitBlocked === true || isSubmittingRef.current;
+    }
+    // Awaits only where the original did: a validation-blocked customSubmit
+    // must settle in the same tick so setIsSubmitting(true/false) batch.
+    return async function handleSubmit(options) {
+        if (advancesWizardInsteadOfSaving(options)) {
+            nav.handleWizardNext();
+            // skip: handled as a wizard step advance
+            return;
+        }
+        // skip: locked, blocked or a submit is already in flight
+        if (isSubmitBlocked())
+            return;
+        isSubmittingRef.current = true;
+        state.setIsSubmitting(true);
+        state.setExtensionErrorKey(null);
+        try {
+            // Extension-only: only a section is dirty and the main form is unchanged.
+            // Skip the entity write (it would send an empty changes payload) and only
+            // run the section handlers.
+            if (snapshot.isUnchanged && state.extensionDirty) {
+                await submitExtensionsOnly();
+                // skip: extension-only save needs no entity write
+                return;
+            }
+            let result = customSubmit !== undefined ? blockedCustomSubmitResult() : undefined;
+            if (result === undefined && customSubmit !== undefined) {
+                result = await customSubmit(controller.getSnapshot());
+                if (result.isSuccess)
+                    controller.rebase();
+            }
+            else if (result === undefined) {
+                result = await controller.submit();
+            }
+            let extensionsPersisted = true;
+            if (result.isSuccess)
+                extensionsPersisted = await handleSubmitSuccess(result.isNoOp === true);
+            else
+                applySubmitFailure(result);
+            // On entity-success-but-extension-failure the extension-error
+            // banner is showing — don't notify (the caller navigates away on success
+            // and would unmount it before the user sees the failure).
+            if (shouldNotifyCaller(result, extensionsPersisted)) {
+                props.onSubmit?.(result, controller.getSnapshot().values);
+            }
+        }
+        finally {
+            isSubmittingRef.current = false;
+            state.setIsSubmitting(false);
+        }
+    };
+}

package/dist/components/render-edit-titles.d.ts

@@ -0,0 +1,17 @@
+import type { EditSectionViewModel, FormValues } from "../headless/index.ts";
+import type { FormSectionNavItem } from "../primitives.tsx";
+import type { FooterFlags, LayoutFlags } from "./render-edit-layout-flags.ts";
+import type { RenderEditEngine } from "./render-edit-render-model.ts";
+export type TitleModel = {
+    readonly recordTitle: string | undefined;
+    readonly formTitle: string;
+    readonly formSubtitle: string | undefined;
+    readonly titleInSettingsHeader: boolean;
+    readonly usesFieldFlow: boolean;
+    readonly recordTitleInHeaderRegion: boolean;
+    readonly stepRail: boolean;
+    readonly upNextSection: EditSectionViewModel | undefined;
+    readonly sectionNavItems: readonly FormSectionNavItem[];
+    readonly compactStepLabel: string;
+};
+export declare function deriveTitles<TValues extends FormValues, TCtx>(engine: RenderEditEngine<TValues, TCtx>, layout: LayoutFlags, footer: FooterFlags): TitleModel;

package/dist/components/render-edit-titles.js

@@ -0,0 +1,99 @@
+import { formSectionDomId, resolveRecordTitle, resolveTitleTemplate, } from "./render-edit-helpers.js";
+// Title + Subtitle, create/edit-aware. i18n-Keys (mode = "create"|"edit"):
+//   screen:<id>.<mode>.title / .<mode>.subtitle  (mode = "create"|"edit"|"view")
+// Fallback chain: mode-specific → generic (screen:<id>.title/.subtitle).
+// title falls back to screenId; subtitle falls back to screen.description,
+// itself run through translate() so an i18n key (the established
+// convention for description, e.g. bundled-features) resolves instead of
+// showing the raw key — translate() returns the input unchanged for plain
+// prose, same as it does for an unknown key. Same slot
+// section.description already fills for a section. Falls back to
+// undefined (no subtitle) when neither is set.
+function createScreenTextResolver(translate, i18nScreenId, formMode) {
+    return (suffix) => {
+        for (const key of [
+            `screen:${i18nScreenId}.${formMode}.${suffix}`,
+            `screen:${i18nScreenId}.${suffix}`,
+        ]) {
+            const value = translate(key);
+            if (value !== key)
+                return value;
+        }
+        return undefined;
+    };
+}
+// In tabs mode (hideSectionTitles) screen.description is dropped — the head
+// card carries it — but an explicit subtitle i18n override has no other
+// source there, so it stays unless it merely resolves to the description.
+function resolveFormSubtitle(hideSectionTitles, explicitSubtitle, descriptionSubtitle) {
+    if (hideSectionTitles !== true)
+        return explicitSubtitle ?? descriptionSubtitle;
+    return explicitSubtitle !== descriptionSubtitle ? explicitSubtitle : undefined;
+}
+function sectionNavItemsFor(section, index, formTitle) {
+    const isNavigable = section.kind === "fields" &&
+        section.visible &&
+        section.title !== undefined &&
+        section.title !== formTitle;
+    return isNavigable && section.title !== undefined
+        ? [{ id: formSectionDomId(index), title: section.title }]
+        : [];
+}
+function deriveSectionNavItems(filteredSections, formTitle) {
+    return filteredSections.flatMap((section, index) => sectionNavItemsFor(section, index, formTitle));
+}
+function deriveCompactStepLabel(translate, currentTitle, currentStep, lastStepIndex) {
+    return currentTitle !== undefined
+        ? translate("kumiko.wizard.step-with-title", {
+            current: currentStep + 1,
+            total: lastStepIndex + 1,
+            title: currentTitle,
+        })
+        : translate("kumiko.wizard.step", { current: currentStep + 1, total: lastStepIndex + 1 });
+}
+function deriveFormTitleTexts({ props, state, form }, isCreate) {
+    const { screen, hideSectionTitles } = props;
+    const { translate } = state;
+    const formMode = isCreate ? "create" : props.viewMode ? "view" : "edit";
+    const recordTitle = !isCreate && screen.recordTitleField !== undefined
+        ? resolveRecordTitle(props.initial[screen.recordTitleField])
+        : undefined;
+    const resolveScreenText = createScreenTextResolver(translate, props.i18nScreenId, formMode);
+    const plainFormTitle = resolveScreenText("title") ?? props.i18nScreenId;
+    const formTitle = resolveTitleTemplate(screen.titleTemplate, form.snapshot.values, translate, plainFormTitle);
+    const explicitSubtitle = resolveScreenText("subtitle");
+    const descriptionSubtitle = screen.description !== undefined ? translate(screen.description) : undefined;
+    const formSubtitle = resolveFormSubtitle(hideSectionTitles, explicitSubtitle, descriptionSubtitle);
+    return { recordTitle, formTitle, formSubtitle };
+}
+export function deriveTitles(engine, layout, footer) {
+    const { props, state, sections, steps } = engine;
+    const { screen, headerRegion } = props;
+    const { translate } = state;
+    const { filteredSections } = sections;
+    const { currentStep, lastStepIndex } = steps;
+    const { PageHeader, StepBar } = state.primitives;
+    const { recordTitle, formTitle, formSubtitle } = deriveFormTitleTexts(engine, footer.isCreate);
+    return {
+        recordTitle,
+        formTitle,
+        formSubtitle,
+        // Embedded settings-list forms (dashboard panels) have no shell header: the
+        // form title/subtitle move into the first section's header column instead of
+        // floating as a heading above the band.
+        titleInSettingsHeader: footer.isSettingsList && !layout.titleInShell,
+        usesFieldFlow: layout.isScreenForm || state.insideDrawer,
+        // The caller's headerRegion already shows the record title in the shell page
+        // header, so the type title ("Release") above the form would repeat it.
+        recordTitleInHeaderRegion: headerRegion !== undefined &&
+            recordTitle !== undefined &&
+            PageHeader !== undefined &&
+            state.pageHeaderSlotAvailable,
+        stepRail: state.isWizard && layout.isScreenForm && StepBar !== undefined,
+        upNextSection: screen.layout.wizard?.aside?.upNext === true ? filteredSections[currentStep + 1] : undefined,
+        sectionNavItems: layout.isScreenForm && !state.isStepped
+            ? deriveSectionNavItems(filteredSections, formTitle)
+            : [],
+        compactStepLabel: deriveCompactStepLabel(translate, filteredSections[currentStep]?.title, currentStep, lastStepIndex),
+    };
+}

package/dist/components/render-edit-wizard-navigation.d.ts

@@ -0,0 +1,11 @@
+import type { FormValues } from "../headless/index.ts";
+import type { RenderEditSteppedCore } from "./render-edit-render-model.ts";
+export type WizardNavigation = {
+    readonly persistExtensions: () => Promise<boolean>;
+    readonly jumpToStep: (index: number) => void;
+    readonly handleWizardNext: () => void;
+    readonly handleWizardBack: () => void;
+    readonly handleWizardStepSelect: (targetStep: number) => void;
+    readonly findFirstErroringStep: (fieldPaths: readonly string[]) => number | undefined;
+};
+export declare function createWizardNavigation<TValues extends FormValues, TCtx>({ props, state, form, draft, sections, steps }: RenderEditSteppedCore<TValues, TCtx>, saveDraft: (stepIndex: number) => void): WizardNavigation;