@cosmicdrift/kumiko-renderer 0.421.0 → 0.422.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -18,7 +18,7 @@ import { ActionFormLoadStatus, ActionFormSuccessBanner, DEFAULT_LOAD_ID_PARAM, i
18
18
  import { useAppFeatures } from "./app-features-context.js";
19
19
  import { mergeSearchParamsIntoInitial, tenantCurrencyMoneyFieldNames, useMoneyCurrencyOverrides, } from "./entity-edit-prefill.js";
20
20
  import { hiddenRequiredFieldsFilled, layoutFieldNames } from "./layout-fields.js";
21
- import { useInitialValuesHandoff, useNav } from "./nav.js";
21
+ import { useHandoffForScreen, useNav } from "./nav.js";
22
22
  import { lastSegment } from "./qn.js";
23
23
  import { qualifyScreenId } from "./qualify-screen-id.js";
24
24
  import { QueryLoadingBanner } from "./query-state-banners.js";
@@ -126,9 +126,14 @@ export function ActionFormBody({ schema, screen, translate, entityId, initialOve
126
126
  const submittableFields = useMemo(() => actionFormSubmittableFields(screen), [screen]);
127
127
  const synthEntity = useMemo(() => synthesizeActionFormEntity(submittableFields), [submittableFields]);
128
128
  const synthScreen = useMemo(() => synthesizeActionFormScreen(screen), [screen]);
129
- const pendingHandoff = useInitialValuesHandoff(screen.id);
129
+ const pendingHandoff = useHandoffForScreen(screen.id);
130
130
  // A drawer-hosted form is not a navigation target, so it never takes a handoff.
131
- const handoffValues = onSuccess === undefined ? pendingHandoff : undefined;
131
+ const handoff = onSuccess === undefined ? pendingHandoff : undefined;
132
+ const handoffValues = handoff?.values;
133
+ const submitThrough = handoff?.submitThrough;
134
+ const buildSubmitThroughPayload = useCallback((_snapshot, shapedValues) => submitThrough === undefined
135
+ ? undefined
136
+ : { ...submitThrough.wrap, [submitThrough.valuesKey]: shapedValues }, [submitThrough]);
132
137
  // This screen has no entity, so a money field here declares its own currency
133
138
  // source (boot-enforced) — without one the form would seed a bare
134
139
  // `0` the handler's schema rejects. When a tenant-declared field's config
@@ -322,7 +327,10 @@ export function ActionFormBody({ schema, screen, translate, entityId, initialOve
322
327
  return undefined;
323
328
  return (_jsx(StatusBadge, { value: effectiveTranslate(badge.label), tone: statusToneForOptionTone(badge.tone) ?? "muted", testId: `field-badge-${fieldName}` }));
324
329
  },
325
- }), writeCommand: screen.handler, payloadMode: "values", onSubmit: handleSubmitted, ...(handleCancel !== undefined && { onCancel: handleCancel }), onDirtyChange: handleDirtyChange, ...((insideDrawer || screenFillsHeight(screen)) && { fillScreenHeight: true }), ...((screen.submitLabel ?? submitLabelFallback) !== undefined && {
330
+ }), writeCommand: submitThrough?.handler ?? screen.handler, payloadMode: "values", ...(submitThrough !== undefined && {
331
+ buildPayload: buildSubmitThroughPayload,
332
+ serverFieldPathPrefix: `${submitThrough.valuesKey}.`,
333
+ }), onSubmit: handleSubmitted, ...(handleCancel !== undefined && { onCancel: handleCancel }), onDirtyChange: handleDirtyChange, ...((insideDrawer || screenFillsHeight(screen)) && { fillScreenHeight: true }), ...((screen.submitLabel ?? submitLabelFallback) !== undefined && {
326
334
  submitLabel: screen.submitLabel ?? submitLabelFallback,
327
335
  }), ...(screen.submitStyle !== undefined && { submitVariant: screen.submitStyle }), ...(screen.footerActions !== undefined && { footerActions: screen.footerActions }), formErrorOnTop: true, ...(screen.fieldDescriptions !== undefined && {
328
336
  fieldDescription: (fieldName, values) => {
@@ -51,7 +51,9 @@ export function ActionFormPreviewPanel({ preview, fields, values, translate, loc
51
51
  const columns = useMemo(() => (preview.list?.columns ?? []).map((column) => ({
52
52
  field: column.field,
53
53
  label: translate(column.label),
54
- type: column.type ?? "text",
54
+ ...(column.type === "file"
55
+ ? { type: "text", fileDisplay: { kind: "file" } }
56
+ : { type: column.type ?? "text" }),
55
57
  sortable: false,
56
58
  })), [preview.list, translate]);
57
59
  const rows = useMemo(() => (preview.list === undefined ? [] : previewRows(query.data, preview.list.field)), [preview.list, query.data]);
package/dist/app/nav.d.ts CHANGED
@@ -67,10 +67,30 @@ export type NavProviderProps = {
67
67
  readonly children: ReactNode;
68
68
  readonly value: NavApi;
69
69
  };
70
+ /** Routes an actionForm's submit through another write handler: the form's
71
+ * values are sent as `{ ...wrap, [valuesKey]: values }` to `handler`. Plain data
72
+ * so it can travel with the handoff. The wrapper handler must return the inner
73
+ * handler's response data unchanged (extra fields allowed): the screen's
74
+ * `redirect.idField` and `successFacts` are read from `result.data`. */
75
+ export type SubmitThrough = {
76
+ readonly handler: string;
77
+ readonly wrap: Readonly<Record<string, unknown>>;
78
+ readonly valuesKey: string;
79
+ };
80
+ export type NavigateWithInitialValuesOptions = {
81
+ readonly submitThrough?: SubmitThrough;
82
+ };
83
+ type InitialValuesHandoff = {
84
+ readonly screenId: string;
85
+ readonly values: Readonly<Record<string, unknown>>;
86
+ readonly submitThrough?: SubmitThrough;
87
+ };
70
88
  export declare function NavProvider({ children, value }: NavProviderProps): ReactNode;
71
- export declare function useNavigateWithInitialValues(): (target: ScreenTarget, initialValues: Readonly<Record<string, unknown>>) => void;
89
+ export declare function useNavigateWithInitialValues(): (target: ScreenTarget, initialValues: Readonly<Record<string, unknown>>, options?: NavigateWithInitialValuesOptions) => void;
90
+ export declare function useHandoffForScreen(screenId: string): InitialValuesHandoff | undefined;
72
91
  export declare function useInitialValuesHandoff(screenId: string): Readonly<Record<string, unknown>> | undefined;
73
92
  /** Like useNav, but undefined without a provider, for views that only offer
74
93
  * links when navigation exists. */
75
94
  export declare function useOptionalNav(): NavApi | undefined;
76
95
  export declare function useNav(): NavApi;
96
+ export {};
package/dist/app/nav.js CHANGED
@@ -117,32 +117,38 @@ export function NavProvider({ children, value }) {
117
117
  // initial values carried in memory — never in the URL, so a link cannot
118
118
  // forge them and they are not limited to the screen's urlPrefillFields.
119
119
  // sensitive and password fields are still never prefilled.
120
+ // `options.submitThrough` (actionForm only) sends the submit to another handler.
120
121
  export function useNavigateWithInitialValues() {
121
122
  const nav = useNav();
122
123
  const handoffSlot = useContext(InitialValuesHandoffContext);
123
- return useCallback((target, initialValues) => {
124
+ return useCallback((target, initialValues, options) => {
124
125
  if (handoffSlot !== undefined) {
125
- handoffSlot.current = { screenId: lastSegment(target.screenId), values: initialValues };
126
+ handoffSlot.current = {
127
+ screenId: lastSegment(target.screenId),
128
+ values: initialValues,
129
+ ...(options?.submitThrough !== undefined && { submitThrough: options.submitThrough }),
130
+ };
126
131
  }
127
132
  nav.navigate(target);
128
133
  }, [nav, handoffSlot]);
129
134
  }
130
- export function useInitialValuesHandoff(screenId) {
135
+ export function useHandoffForScreen(screenId) {
131
136
  const handoffSlot = useContext(InitialValuesHandoffContext);
132
- const [values] = useState(() => {
137
+ const [handoff] = useState(() => {
133
138
  const pending = handoffSlot?.current;
134
139
  return pending !== undefined && pending.screenId === lastSegment(screenId)
135
- ? pending.values
140
+ ? pending
136
141
  : undefined;
137
142
  });
138
143
  useEffect(() => {
139
- if (handoffSlot !== undefined &&
140
- values !== undefined &&
141
- handoffSlot.current?.values === values) {
144
+ if (handoffSlot !== undefined && handoff !== undefined && handoffSlot.current === handoff) {
142
145
  handoffSlot.current = undefined;
143
146
  }
144
- }, [handoffSlot, values]);
145
- return values;
147
+ }, [handoffSlot, handoff]);
148
+ return handoff;
149
+ }
150
+ export function useInitialValuesHandoff(screenId) {
151
+ return useHandoffForScreen(screenId)?.values;
146
152
  }
147
153
  /** Like useNav, but undefined without a provider, for views that only offer
148
154
  * links when navigation exists. */
@@ -1,4 +1,4 @@
1
- import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
1
+ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { ExtensionFormRegistryProvider } from "../app/extension-form-submit.js";
3
3
  import { FormUploadTrackerProvider } from "./form-pending-uploads.js";
4
4
  import { renderActionErrorBanner, renderAllRequiredHint, renderDeleteDialog, renderDraftPicker, renderExtensionErrorBanner, renderFormErrorBanner, renderRootIssueBanners, renderTabStrip, renderWizardProgress, } from "./render-edit-banners.js";
@@ -30,6 +30,22 @@ function renderWizardSideRail(model) {
30
30
  total: steps.lastStepIndex + 1,
31
31
  }), ...(description !== undefined && { description }), subtitles: subtitles, ...(upNext !== undefined && { upNext }), testId: "render-edit-wizard-steps", compactTestId: "render-edit-wizard-step-label" }));
32
32
  }
33
+ // With the title in the shell header the subtitle is the form's intro. As a bare muted line it
34
+ // read like a leftover, so it gets a box of its own, required hint included.
35
+ function showsIntroBox({ engine: { state }, layout, titles, }) {
36
+ return (layout.titleInShell &&
37
+ !state.insideDrawer &&
38
+ titles.formSubtitle !== undefined &&
39
+ !titles.stepRail);
40
+ }
41
+ function renderIntroBox(model) {
42
+ const { Banner } = model.engine.state.primitives;
43
+ return (_jsxs(Banner, { variant: "primary", icon: "info", testId: "render-edit-intro", children: [model.titles.formSubtitle, model.engine.sections.showsAllRequiredHint && _jsxs(_Fragment, { children: [" ", renderAllRequiredHint(model)] })] }));
44
+ }
45
+ function showsSubtitleUnderTitle(model) {
46
+ const { titles } = model;
47
+ return !titles.stepRail && !titles.titleInSettingsHeader && !showsIntroBox(model);
48
+ }
33
49
  function buildFormHeadingProps(model) {
34
50
  const { props } = model.engine;
35
51
  const { layout, footer, titles } = model;
@@ -40,8 +56,7 @@ function buildFormHeadingProps(model) {
40
56
  !titles.titleInSettingsHeader &&
41
57
  !titles.titleInHeaderRegion && { title: titles.formTitle }),
42
58
  ...(titles.formSubtitle !== undefined &&
43
- !titles.stepRail &&
44
- !titles.titleInSettingsHeader && { subtitle: titles.formSubtitle }),
59
+ showsSubtitleUnderTitle(model) && { subtitle: titles.formSubtitle }),
45
60
  ...(layout.isScreenForm && { screenForm: true }),
46
61
  ...(unsavedCount !== undefined && (unsavedCount > 0 || hasDirtyFooter) && { unsavedCount }),
47
62
  ...(titles.sectionNavItems.length > 0 && { sectionNav: titles.sectionNavItems }),
@@ -74,5 +89,8 @@ export function renderEditLayout(model) {
74
89
  const { props, state, sections, form, handleSubmit } = model.engine;
75
90
  const header = buildHeaderActions(model);
76
91
  const { Form } = state.primitives;
77
- return (_jsx(ExtensionFormRegistryProvider, { value: state.extensionFormRegistry, children: _jsxs(FormUploadTrackerProvider, { value: state.trackUpload, 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 || props.screen.layout.hideRequiredMarker === true, children: [props.leadContent, sections.showsAllRequiredHint && !state.insideDrawer && renderAllRequiredHint(model), renderDraftPicker(model), renderWizardProgress(model), state.isTabs && state.isStepped && renderTabStrip(model), renderEditSections(model), props.belowSections?.(form.snapshot.values), renderAfterFormSlot(model), props.formErrorOnTop !== true && renderFormErrorBanner(model), renderRootIssueBanners(model), renderExtensionErrorBanner(model), renderActionErrorBanner(model), renderDeleteDialog(model)] }) })] }) }));
92
+ return (_jsx(ExtensionFormRegistryProvider, { value: state.extensionFormRegistry, children: _jsxs(FormUploadTrackerProvider, { value: state.trackUpload, 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 || props.screen.layout.hideRequiredMarker === true, children: [showsIntroBox(model) && renderIntroBox(model), props.leadContent, sections.showsAllRequiredHint &&
93
+ !state.insideDrawer &&
94
+ !showsIntroBox(model) &&
95
+ renderAllRequiredHint(model), renderDraftPicker(model), renderWizardProgress(model), state.isTabs && state.isStepped && renderTabStrip(model), renderEditSections(model), props.belowSections?.(form.snapshot.values), renderAfterFormSlot(model), props.formErrorOnTop !== true && renderFormErrorBanner(model), renderRootIssueBanners(model), renderExtensionErrorBanner(model), renderActionErrorBanner(model), renderDeleteDialog(model)] }) })] }) }));
78
96
  }
@@ -38,7 +38,7 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
38
38
  /** `values` are the form values at the moment the submit succeeded. */
39
39
  readonly onSubmit?: (result: SubmitResult<unknown>, values: TValues) => void;
40
40
  readonly payloadMode?: "values" | "changes";
41
- readonly buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
41
+ readonly buildPayload?: (snapshot: FormSnapshot<TValues>, shapedValues: unknown) => unknown;
42
42
  /** Prefix to strip from server validation issue paths before mapping them
43
43
  * onto form fields — see SubmitConfig.serverFieldPathPrefix. Only needed
44
44
  * when buildPayload nests the form values under a key. */
@@ -361,7 +361,10 @@ export function createFormController(options) {
361
361
  // buildPayload wins over payloadMode when both are set.
362
362
  let payload;
363
363
  if (submitCfg.buildPayload) {
364
- payload = submitCfg.buildPayload(submittedSnapshot);
364
+ const shapedValues = omitPayloadFields(submitCfg.stripEmptySeeds === false
365
+ ? submittedValues
366
+ : stripUntouchedEmptyStrings(submittedValues, submittedSnapshot.initial, forceIncludeEmpty), submitCfg.omitFields);
367
+ payload = submitCfg.buildPayload(submittedSnapshot, shapedValues);
365
368
  }
366
369
  else if (payloadMode === "changes") {
367
370
  if (submittedSnapshot.isUnchanged) {
@@ -380,7 +383,11 @@ export function createFormController(options) {
380
383
  else {
381
384
  payload = stripUntouchedEmptyStrings(submittedValues, submittedSnapshot.initial, forceIncludeEmpty);
382
385
  }
383
- payload = omitPayloadFields(payload, submitCfg.omitFields);
386
+ // A prefix means the builder nested the values under a key, so a
387
+ // top-level omit would hit wrapper keys instead of form fields.
388
+ if (submitCfg.serverFieldPathPrefix === undefined) {
389
+ payload = omitPayloadFields(payload, submitCfg.omitFields);
390
+ }
384
391
  // Only enforced here, right before the write actually happens — a
385
392
  // form that never reaches this point (blocked by validation, or a
386
393
  // clean payloadMode "changes" no-op) must not throw just because no
@@ -58,9 +58,10 @@ export type SubmitConfig<TValues extends FormValues = FormValues> = {
58
58
  readonly stripEmptySeeds?: boolean;
59
59
  /** Top-level payload keys removed right before dispatch, for fields that
60
60
  * are shown or validated but must not reach the write handler. Applied
61
- * to the built payload only when it is a plain object. */
61
+ * to the built payload only when it is a plain object; skipped when
62
+ * serverFieldPathPrefix is set (builder nests values, see buildPayload). */
62
63
  readonly omitFields?: readonly string[];
63
- readonly buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
64
+ readonly buildPayload?: (snapshot: FormSnapshot<TValues>, shapedValues: unknown) => unknown;
64
65
  readonly serverFieldPathPrefix?: string;
65
66
  /** Restricts submit()'s internal validate() call to these field names —
66
67
  * same contract as validate()'s `scope` param. Set by RenderEdit when the
package/dist/index.d.ts CHANGED
@@ -31,7 +31,7 @@ export type { KumikoScreenProps } from "./app/kumiko-screen.tsx";
31
31
  export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen.tsx";
32
32
  export type { DateRangeBound, DateRangeValue, ResolvedDateRangeFacet } from "./app/list-facets.ts";
33
33
  export { buildDateRangePayload, clampDateRange, readDateRange, resolveDateRangeFacets, } from "./app/list-facets.ts";
34
- export type { NavApi, NavigateOptions, NavProviderProps, NavRoute, NavTarget, ObjectTarget, ScreenTarget, } from "./app/nav.tsx";
34
+ export type { NavApi, NavigateOptions, NavigateWithInitialValuesOptions, NavProviderProps, NavRoute, NavTarget, ObjectTarget, ScreenTarget, SubmitThrough, } from "./app/nav.tsx";
35
35
  export { formatPath, hasDetailScreen, NavProvider, parsePath, resolveTarget, useNav, useNavigateWithInitialValues, useOptionalNav, } from "./app/nav.tsx";
36
36
  export { lastSegment } from "./app/qn.ts";
37
37
  export type { ReturnHost, ReturnTo } from "./app/return-to.tsx";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-renderer",
3
- "version": "0.421.0",
3
+ "version": "0.422.0",
4
4
  "description": "React renderer for Kumiko screens. The root export holds the platform-agnostic logic (primitives contract, hooks, KumikoScreen, navigation and SSE abstractions); ./headless the DOM-free UI logic, ./live the HTTP dispatcher, ./web the browser bindings (HTML primitives, history navigation, EventSource live events, createKumikoApp).",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -48,8 +48,8 @@
48
48
  }
49
49
  },
50
50
  "dependencies": {
51
- "@cosmicdrift/kumiko-framework": "0.421.0",
52
- "@cosmicdrift/kumiko-types": "0.421.0",
51
+ "@cosmicdrift/kumiko-framework": "0.422.0",
52
+ "@cosmicdrift/kumiko-types": "0.422.0",
53
53
  "@types/qrcode": "^1.5.6",
54
54
  "class-variance-authority": "^0.7.1",
55
55
  "clsx": "^2.1.1",
@@ -79,8 +79,8 @@
79
79
  }
80
80
  },
81
81
  "devDependencies": {
82
- "@cosmicdrift/kumiko-locale-de": "0.421.0",
83
- "@cosmicdrift/kumiko-testing": "0.421.0",
82
+ "@cosmicdrift/kumiko-locale-de": "0.422.0",
83
+ "@cosmicdrift/kumiko-testing": "0.422.0",
84
84
  "@tailwindcss/cli": "^4.3.3",
85
85
  "@testing-library/react": "^16.3.3",
86
86
  "@testing-library/user-event": "^14.6.8",
package/src/changes.json CHANGED
@@ -1,4 +1,16 @@
1
1
  [
2
+ {
3
+ "version": "0.422.0",
4
+ "type": "improvement",
5
+ "title": "Form intro as an info banner",
6
+ "detail": "With the title in the shell header, the form subtitle shows as a primary info banner at the top of the form, with the all-fields-required hint inside it. Other layouts are unchanged."
7
+ },
8
+ {
9
+ "version": "0.422.0",
10
+ "type": "improvement",
11
+ "title": "Submit an actionForm through another write handler",
12
+ "detail": "`useNavigateWithInitialValues(target, values, { submitThrough: { handler, wrap, valuesKey } })` opens the prefilled actionForm as usual but submits `{ ...wrap, [valuesKey]: values }` to `handler`. Server field errors under `<valuesKey>.<field>` appear at the field. entityEdit and secretMint ignore the option. A preview list column may have `type: \"file\"` (FileRef id shown with name and download link)."
13
+ },
2
14
  {
3
15
  "version": "0.420.0",
4
16
  "type": "improvement",