@cosmicdrift/kumiko-renderer 0.421.0 → 0.424.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]);
@@ -62,5 +64,5 @@ export function ActionFormPreviewPanel({ preview, fields, values, translate, loc
62
64
  }
63
65
  if (query.data === null)
64
66
  return query.loading ? _jsx(QueryLoadingBanner, {}) : null;
65
- return (_jsx(Banner, { variant: "hint", testId: "action-form-preview", ...(preview.title !== undefined && { title: translate(preview.title) }), children: _jsxs(Grid, { columns: 1, children: [_jsx(ActionFormFacts, { facts: facts, testIdPrefix: "action-form-preview-fact" }), preview.list !== undefined && _jsx(DataTable, { columns: columns, rows: rows })] }) }));
67
+ return (_jsx(Banner, { variant: "hint", testId: "action-form-preview", ...(preview.title !== undefined && { title: translate(preview.title) }), children: _jsxs(Grid, { columns: 1, children: [_jsx(ActionFormFacts, { facts: facts, testIdPrefix: "action-form-preview-fact" }), preview.list !== undefined && (rows.length > 0 || facts.length === 0) && (_jsx(DataTable, { columns: columns, rows: rows }))] }) }));
66
68
  }
@@ -0,0 +1,9 @@
1
+ import { type ReactNode } from "react";
2
+ /** Short screen id of the app's start page, for components that sit outside
3
+ * the screen resolution (the "page not available" state offers it as the way
4
+ * back). `createKumikoApp` mounts it; `undefined` = no known start page. */
5
+ export declare function HomeScreenProvider({ homeScreenId, children, }: {
6
+ readonly homeScreenId: string | undefined;
7
+ readonly children: ReactNode;
8
+ }): ReactNode;
9
+ export declare function useHomeScreenId(): string | undefined;
@@ -0,0 +1,12 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { createContext, useContext } from "react";
3
+ const HomeScreenContext = createContext(undefined);
4
+ /** Short screen id of the app's start page, for components that sit outside
5
+ * the screen resolution (the "page not available" state offers it as the way
6
+ * back). `createKumikoApp` mounts it; `undefined` = no known start page. */
7
+ export function HomeScreenProvider({ homeScreenId, children, }) {
8
+ return _jsx(HomeScreenContext.Provider, { value: homeScreenId, children: children });
9
+ }
10
+ export function useHomeScreenId() {
11
+ return useContext(HomeScreenContext);
12
+ }
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. */
@@ -6,7 +6,9 @@ import type { ResolvedSuccessItem, ResolvedSuccessLink } from "./action-form-sup
6
6
  import type { FeatureSchema } from "./feature-schema.ts";
7
7
  import { type NavApi, type ScreenTarget } from "./nav.tsx";
8
8
  /** Empty state for a screen QN that is not in the schema (feature disabled for
9
- * the tenant, stale link, miswired screen). The QN only goes to the console. */
9
+ * the tenant, stale link, miswired screen). The QN only goes to the console.
10
+ * The way back is the explicit `homeScreenId` or else the app's start page from
11
+ * `HomeScreenProvider`. */
10
12
  export declare function ScreenMissingState({ screenQn, homeScreenId, testId, }: {
11
13
  readonly screenQn: string;
12
14
  readonly homeScreenId?: string;
@@ -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 { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
3
3
  import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
4
4
  import { useCallback, useEffect, useMemo } from "react";
@@ -11,28 +11,41 @@ import { referenceLookupSource, referenceRowsByIdsPayload } from "../hooks/use-r
11
11
  import { useTranslation } from "../i18n.js";
12
12
  import { usePrimitives } from "../primitives.js";
13
13
  import { ISO_DATE_PATTERN, isMoneyValue } from "./entity-edit-prefill.js";
14
+ import { useHomeScreenId } from "./home-screen-context.js";
14
15
  import { useNav } from "./nav.js";
15
16
  import { lastSegment, toKebab } from "./qn.js";
16
17
  import { featureNameFromQualifiedScreenId } from "./qualify-screen-id.js";
17
18
  import { navigateToReturn, navigateWithReturnTo, useReturnHost } from "./return-to.js";
19
+ // Own component so useNav only runs when a start page is known: KumikoScreen
20
+ // can render this state without a NavProvider.
18
21
  function ScreenMissingHomeButton({ homeScreenId, testId, }) {
19
22
  const { Button } = usePrimitives();
20
23
  const t = useTranslation();
21
24
  const nav = useNav();
22
- return (_jsx(Button, { variant: "secondary", onClick: () => nav.navigate({ screenId: homeScreenId }), testId: testId, children: t("kumiko.screen-missing.home") }));
25
+ return (_jsx(Button, { variant: "primary", onClick: () => nav.navigate({ screenId: homeScreenId }), testId: testId, children: t("kumiko.screen-missing.home") }));
26
+ }
27
+ // EmptyState is an optional primitive: a custom registry without it keeps the
28
+ // plain card, so no page loses its title and way out.
29
+ function NotAvailableState({ icon, title, description, actions, testId, }) {
30
+ const { EmptyState, Card, Text } = usePrimitives();
31
+ if (EmptyState !== undefined) {
32
+ return (_jsx(EmptyState, { icon: icon, title: title, description: description, actions: actions, testId: testId }));
33
+ }
34
+ return (_jsxs(Card, { options: { padded: true }, testId: testId, children: [_jsx(Text, { testId: `${testId}-title`, children: title }), description, actions] }));
23
35
  }
24
36
  /** Empty state for a screen QN that is not in the schema (feature disabled for
25
- * the tenant, stale link, miswired screen). The QN only goes to the console. */
37
+ * the tenant, stale link, miswired screen). The QN only goes to the console.
38
+ * The way back is the explicit `homeScreenId` or else the app's start page from
39
+ * `HomeScreenProvider`. */
26
40
  export function ScreenMissingState({ screenQn, homeScreenId, testId = "kumiko-screen-not-found", }) {
27
- const { Card, Text } = usePrimitives();
41
+ const { Text } = usePrimitives();
28
42
  const t = useTranslation();
43
+ const providedHomeScreenId = useHomeScreenId();
44
+ const homeTarget = homeScreenId ?? providedHomeScreenId;
29
45
  useEffect(() => {
30
46
  rendererWarn(`[kumiko] screen "${screenQn}" is not in the schema (feature disabled, stale link or miswired screen).`);
31
47
  }, [screenQn]);
32
- return (_jsx(Card, { options: { padded: true }, slots: {
33
- title: _jsx(Text, { testId: `${testId}-title`, children: t("kumiko.screen-missing.title") }),
34
- subtitle: _jsx(Text, { variant: "muted", children: t("kumiko.screen-missing.hint") }),
35
- }, testId: testId, children: homeScreenId !== undefined ? (_jsx(ScreenMissingHomeButton, { homeScreenId: homeScreenId, testId: `${testId}-home` })) : null }));
48
+ return (_jsx(NotAvailableState, { icon: "unavailable", title: t("kumiko.screen-missing.title"), description: _jsxs(_Fragment, { children: [_jsx(Text, { variant: "muted", children: t("kumiko.screen-missing.hint") }), _jsx(Text, { variant: "muted", children: t("kumiko.screen-missing.contact") })] }), actions: homeTarget !== undefined ? (_jsx(ScreenMissingHomeButton, { homeScreenId: homeTarget, testId: `${testId}-home` })) : undefined, testId: testId }));
36
49
  }
37
50
  export function ScreenAccessDeniedBanner({ screenQn, testId, }) {
38
51
  const { Banner } = usePrimitives();
@@ -61,8 +74,8 @@ export function findEntityListScreen(schema, entityName) {
61
74
  // instead of a bare error banner. Composed from shared primitives so web and
62
75
  // native render it alike.
63
76
  export function RecordNotFoundState({ translate, onBack, }) {
64
- const { Card, Text, Button } = usePrimitives();
65
- return (_jsxs(Card, { options: { padded: true }, testId: "kumiko-screen-record-missing", children: [_jsx(Text, { testId: "kumiko-screen-record-missing-title", children: translate("kumiko.record.not-found.title") }), _jsx(Text, { variant: "muted", children: translate("kumiko.record.not-found.hint") }), onBack !== undefined && (_jsx(Button, { variant: "secondary", onClick: onBack, testId: "kumiko-screen-record-missing-back", children: translate("kumiko.record.not-found.back") }))] }));
77
+ const { Text, Button } = usePrimitives();
78
+ return (_jsx(NotAvailableState, { icon: "not-found", title: translate("kumiko.record.not-found.title"), description: _jsx(Text, { variant: "muted", children: translate("kumiko.record.not-found.hint") }), actions: onBack !== undefined ? (_jsx(Button, { variant: "secondary", onClick: onBack, testId: "kumiko-screen-record-missing-back", children: translate("kumiko.record.not-found.back") })) : undefined, testId: "kumiko-screen-record-missing" }));
66
79
  }
67
80
  export function useNavigateToListAfter(schema, entityName) {
68
81
  const nav = useNav();
@@ -226,11 +239,18 @@ function findRedirectTargetScreen(redirect, schema, appFeatures) {
226
239
  : schema.screens;
227
240
  return searchSpace.find((s) => lastSegment(s.id) === targetId);
228
241
  }
242
+ // A custom screen reads its record from the route only when the redirect names the id field.
243
+ function redirectCarriesId(redirect, target) {
244
+ if (target === undefined)
245
+ return false;
246
+ if (target.type === "entityEdit" || target.type === "projectionDetail")
247
+ return true;
248
+ return target.type === "custom" && typeof redirect !== "string" && redirect.idFrom !== undefined;
249
+ }
229
250
  // A redirect to a record screen ("show the result") is a deliberate forward
230
251
  // navigation and keeps precedence over returnTo.
231
252
  function redirectTargetsRecord(redirect, schema, appFeatures) {
232
- const target = findRedirectTargetScreen(redirect, schema, appFeatures);
233
- return (target !== undefined && (target.type === "entityEdit" || target.type === "projectionDetail"));
253
+ return redirectCarriesId(redirect, findRedirectTargetScreen(redirect, schema, appFeatures));
234
254
  }
235
255
  // Type-guard form narrows `returnTarget` for the caller's subsequent
236
256
  // navigateToReturn(nav, returnTarget) call.
@@ -252,7 +272,7 @@ export function resolveRedirectTarget(redirect, submittedData, schema, appFeatur
252
272
  const idField = typeof redirect === "string" ? "id" : (redirect.idFrom ?? "id");
253
273
  const targetId = lastSegment(redirectScreen);
254
274
  const target = findRedirectTargetScreen(redirect, schema, appFeatures);
255
- const carriesId = target !== undefined && (target.type === "entityEdit" || target.type === "projectionDetail");
275
+ const carriesId = redirectCarriesId(redirect, target);
256
276
  const searchParams = redirectSearchParams(redirect, submittedData);
257
277
  if (!carriesId)
258
278
  return { screenId: targetId, entityId: undefined, tab: undefined, searchParams };
@@ -294,9 +314,10 @@ export function navigateToRedirectTarget(nav, target) {
294
314
  nav.navigate(navTarget, { searchParams });
295
315
  }
296
316
  // Links of the success box. Targets resolve like `redirect`; a link whose target
297
- // needs a record id (entityEdit, projectionDetail) but whose payload field holds
298
- // no string id is dropped instead of navigating to an id-less record screen.
299
- // A link without idFrom to a non-record screen always navigates id-less.
317
+ // needs a record id (entityEdit, projectionDetail, or custom with an explicit
318
+ // idFrom) but whose payload field holds no string id is dropped instead of
319
+ // navigating to an id-less record screen. A link without idFrom to a custom or
320
+ // other non-record screen always navigates id-less.
300
321
  export function resolveSuccessLinks(links, data, schema, appFeatures, nav, translate) {
301
322
  const resolved = [];
302
323
  (links ?? []).forEach((link, index) => {
@@ -58,7 +58,10 @@ function createFieldCellRenderer(model, section, columns, flows, facts) {
58
58
  model.setFieldUntyped(field.field, v);
59
59
  clearErrorsAndValidate(field.field);
60
60
  }, ...(props.actionFormScreenQn !== undefined && {
61
- onSuggest: (value) => form.controller.seedField(field.field, value),
61
+ onSuggest: (value) => {
62
+ form.controller.seedField(field.field, value);
63
+ form.clearErrorsOnInput(field.field);
64
+ },
62
65
  }), GridCell: GridCell, featureName: props.featureName, ...appendixCellProps(props, field, snapshot.values, state.primitives.StatusBadge), allIssues: snapshot.errors, valueDisplay: props.valueDisplay, row: snapshot.values, ...(disabled && { fillDisabled: true }), ...(props.hideSectionTitles !== true &&
63
66
  section.title !== undefined && { sectionTitle: section.title }), ...(showsChangedMarker && field.field in snapshot.changes && { changed: true }) }, field.field));
64
67
  };
@@ -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
@@ -243,9 +243,10 @@ export const kumikoDefaultTranslations = {
243
243
  "kumiko.widget.loading": "Loading…",
244
244
  "kumiko.widget.error.title": "Couldn't load.",
245
245
  "kumiko.screen-missing.title": "This page is not available",
246
- "kumiko.screen-missing.hint": "It is not enabled for your account or no longer exists.",
246
+ "kumiko.screen-missing.hint": "Either it is not enabled for your account or it no longer exists.",
247
247
  "kumiko.screen-access-denied.title": "You do not have access to this page.",
248
248
  "kumiko.screen-missing.home": "Go to start page",
249
+ "kumiko.screen-missing.contact": "If you need it, ask the person who manages accounts for your organization.",
249
250
  "kumiko.screen-error.title": "This screen failed to render.",
250
251
  "kumiko.error.reference": "Error ID: {id}",
251
252
  "kumiko.error.copyReference": "Copy",
package/dist/index.d.ts CHANGED
@@ -27,11 +27,12 @@ export { ExtensionSectionsProvider, extensionSectionName, useExtensionSectionCom
27
27
  export type { AppSchema, FeatureSchema, QualifiedContentCollection, WorkspaceSchema, } from "./app/feature-schema.ts";
28
28
  export { isAppSchema, toAppSchema } from "./app/feature-schema.ts";
29
29
  export { HeaderActionsBar } from "./app/header-actions-bar.tsx";
30
+ export { HomeScreenProvider, useHomeScreenId } from "./app/home-screen-context.tsx";
30
31
  export type { KumikoScreenProps } from "./app/kumiko-screen.tsx";
31
32
  export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen.tsx";
32
33
  export type { DateRangeBound, DateRangeValue, ResolvedDateRangeFacet } from "./app/list-facets.ts";
33
34
  export { buildDateRangePayload, clampDateRange, readDateRange, resolveDateRangeFacets, } from "./app/list-facets.ts";
34
- export type { NavApi, NavigateOptions, NavProviderProps, NavRoute, NavTarget, ObjectTarget, ScreenTarget, } from "./app/nav.tsx";
35
+ export type { NavApi, NavigateOptions, NavigateWithInitialValuesOptions, NavProviderProps, NavRoute, NavTarget, ObjectTarget, ScreenTarget, SubmitThrough, } from "./app/nav.tsx";
35
36
  export { formatPath, hasDetailScreen, NavProvider, parsePath, resolveTarget, useNav, useNavigateWithInitialValues, useOptionalNav, } from "./app/nav.tsx";
36
37
  export { lastSegment } from "./app/qn.ts";
37
38
  export type { ReturnHost, ReturnTo } from "./app/return-to.tsx";
@@ -94,7 +95,7 @@ export { InsideDrawerProvider, useInsideDrawer } from "./inside-drawer.ts";
94
95
  export { hasUnsavedInput, registerUnsavedInputSource, requestLeave, setLeaveConfirmer, useUnsavedInputSource, } from "./leave-guard.ts";
95
96
  export { LeaveGuardDialog } from "./leave-guard-dialog.tsx";
96
97
  export { PageHeaderCompactProvider, PageHeaderSlotAvailableProvider, usePageHeaderCompact, usePageHeaderSlotAvailable, } from "./page-header-slot.ts";
97
- export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, BulkRowOutcome, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableBulk, DataTableBulkAction, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FileValueListProps, FillContainerProps, FooterActionMarker, FooterActionRole, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputEndAction, InputFillAction, InputProps, JsonViewProps, LightboxImage, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PhotoGridProps, PickedFile, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RecordBreadcrumbProps, RecordStepsProps, RecordSummaryProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StepListProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, TrailingInputAction, WizardStepGroupProps, } from "./primitives.tsx";
98
+ export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, BulkRowOutcome, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableBulk, DataTableBulkAction, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, EmptyStateIcon, EmptyStateProps, FieldCellWidth, FieldProps, FileValueListProps, FillContainerProps, FooterActionMarker, FooterActionRole, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputEndAction, InputFillAction, InputProps, JsonViewProps, LightboxImage, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PhotoGridProps, PickedFile, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RecordBreadcrumbProps, RecordStepsProps, RecordSummaryProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StepListProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, TrailingInputAction, WizardStepGroupProps, } from "./primitives.tsx";
98
99
  export { FOOTER_ACTION_ROLE_PROP, NARROW_LABEL_PROP, PrimitivesProvider, STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, statusToneForOptionTone, statusToneForValue, useOptionalPrimitives, usePrimitives, } from "./primitives.tsx";
99
100
  export type { SessionEndedSignal, SessionEndedSignalProviderProps, } from "./session/session-ended.tsx";
100
101
  export { createSessionEndedSignal, isSessionEndedError, SESSION_ENDED_ERROR_CODES, SessionEndedSignalProvider, useSessionEndedSignal, withSessionEndedDetection, } from "./session/session-ended.tsx";
package/dist/index.js CHANGED
@@ -26,6 +26,7 @@ export { ExtensionFormRegistryProvider, useExtensionFormSubmit, } from "./app/ex
26
26
  export { ExtensionSectionsProvider, extensionSectionName, useExtensionSectionComponent, } from "./app/extension-sections.js";
27
27
  export { isAppSchema, toAppSchema } from "./app/feature-schema.js";
28
28
  export { HeaderActionsBar } from "./app/header-actions-bar.js";
29
+ export { HomeScreenProvider, useHomeScreenId } from "./app/home-screen-context.js";
29
30
  export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen.js";
30
31
  export { buildDateRangePayload, clampDateRange, readDateRange, resolveDateRangeFacets, } from "./app/list-facets.js";
31
32
  export { formatPath, hasDetailScreen, NavProvider, parsePath, resolveTarget, useNav, useNavigateWithInitialValues, useOptionalNav, } from "./app/nav.js";
@@ -80,3 +80,15 @@ export type PromoPanelProps = {
80
80
  readonly action?: PromoPanelAction;
81
81
  readonly testId?: string;
82
82
  };
83
+ /** Semantic picture of an `EmptyState`; each platform maps it to its own icon, so
84
+ * platform-neutral code never imports an icon library. */
85
+ export type EmptyStateIcon = "unavailable" | "not-found";
86
+ /** Calm centered "nothing here" page: icon in a soft circle, title, one explanation and
87
+ * the way out as `actions`. */
88
+ export type EmptyStateProps = {
89
+ readonly icon: EmptyStateIcon;
90
+ readonly title: string;
91
+ readonly description?: ReactNode;
92
+ readonly actions?: ReactNode;
93
+ readonly testId?: string;
94
+ };
@@ -1391,8 +1391,8 @@ export type ActionOverflowMenuProps = {
1391
1391
  readonly triggerLabel?: string;
1392
1392
  readonly testId?: string;
1393
1393
  };
1394
- import type { CopyButtonProps, PromoPanelProps, SecretRevealProps, ShareButtonProps, StickyActionBarProps } from "./primitives-share-types.ts";
1395
- export type { CopyButtonProps, PromoPanelAction, PromoPanelProps, SecretRevealProps, SecretRevealValue, ShareButtonProps, StickyActionBarProps, } from "./primitives-share-types.ts";
1394
+ import type { CopyButtonProps, EmptyStateProps, PromoPanelProps, SecretRevealProps, ShareButtonProps, StickyActionBarProps } from "./primitives-share-types.ts";
1395
+ export type { CopyButtonProps, EmptyStateIcon, EmptyStateProps, PromoPanelAction, PromoPanelProps, SecretRevealProps, SecretRevealValue, ShareButtonProps, StickyActionBarProps, } from "./primitives-share-types.ts";
1396
1396
  export type CorePrimitives = {
1397
1397
  readonly Button: ComponentType<ButtonProps>;
1398
1398
  readonly Banner: ComponentType<BannerProps>;
@@ -1488,6 +1488,9 @@ export type CorePrimitives = {
1488
1488
  readonly ShareButton?: ComponentType<ShareButtonProps>;
1489
1489
  /** Optional — additive rollout, see StickyActionBar. */
1490
1490
  readonly PromoPanel?: ComponentType<PromoPanelProps>;
1491
+ /** Optional — additive rollout, see StickyActionBar. Without it the
1492
+ * "not available" states fall back to a Card. */
1493
+ readonly EmptyState?: ComponentType<EmptyStateProps>;
1491
1494
  };
1492
1495
  /** Extension point for app-owned primitives. Developers extend this
1493
1496
  * interface through TypeScript module augmentation:
@@ -3,7 +3,7 @@ import { isOpenToAllGranted } from "@cosmicdrift/kumiko-framework/ui-types";
3
3
  import { createContext, useContext, useEffect, useMemo, useRef, useState, } from "react";
4
4
  import { createRoot } from "react-dom/client";
5
5
  import { rendererError, rendererWarn } from "../../dev-console.js";
6
- import { AppFeaturesProvider, BasePathProvider, ClientActionsProvider, ColumnRenderersProvider, ContentEditorsProvider, ContentPreviewsProvider, CustomScreensProvider, createSessionEndedSignal, DashboardBodyProvider, DispatcherProvider, DraftStorageProvider, ErrorBoundary, ExtensionSectionsProvider, hasDetailScreen, KumikoScreen, kumikoDefaultTranslations, LeaveGuardDialog, LiveEventsProvider, LocaleProvider, mergeTranslations, NavProvider, navigateWithReturnTo, PrimitivesProvider, qualifyScreenId, ScreenMissingState, SessionEndedSignalProvider, TokensProvider, toAppSchema, translationsByLocaleFromKeys, useBasePath, useNav, usePrimitives, useTranslation, withSessionEndedDetection, } from "../../index.js";
6
+ import { AppFeaturesProvider, BasePathProvider, ClientActionsProvider, ColumnRenderersProvider, ContentEditorsProvider, ContentPreviewsProvider, CustomScreensProvider, createSessionEndedSignal, DashboardBodyProvider, DispatcherProvider, DraftStorageProvider, ErrorBoundary, ExtensionSectionsProvider, HomeScreenProvider, hasDetailScreen, KumikoScreen, kumikoDefaultTranslations, LeaveGuardDialog, LiveEventsProvider, LocaleProvider, mergeTranslations, NavProvider, navigateWithReturnTo, PrimitivesProvider, qualifyScreenId, ScreenMissingState, SessionEndedSignalProvider, TokensProvider, toAppSchema, translationsByLocaleFromKeys, useBasePath, useNav, usePrimitives, useTranslation, withSessionEndedDetection, } from "../../index.js";
7
7
  import { createLiveDispatcher } from "../../live/index.js";
8
8
  import { lastSegment } from "../layout/nav-tree.js";
9
9
  import { ScreenFocus } from "../layout/screen-focus.js";
@@ -384,7 +384,9 @@ function BrowserNavBoot({ app, fallbackQn, useNavApi, hasWorkspaces, translate,
384
384
  const navApi = useNavApi({ hasWorkspaces, features: app.features });
385
385
  const Shell = shell;
386
386
  const screen = (_jsx(RoutedScreen, { app: app, fallbackQn: fallbackQn, ...(translate !== undefined && { translate }), ...(onRowClick !== undefined && { onRowClick }) }));
387
- return (_jsx(NavProvider, { value: navApi, children: Shell !== undefined ? _jsx(Shell, { schema: app, children: screen }) : screen }));
387
+ return (_jsx(NavProvider, { value: navApi, children: _jsx(HomeScreenProvider, { homeScreenId: findOwnerFeature(app.features, fallbackQn) !== undefined
388
+ ? lastSegment(fallbackQn)
389
+ : undefined, children: Shell !== undefined ? _jsx(Shell, { schema: app, children: screen }) : screen }) }));
388
390
  }
389
391
  // Finds the feature that owns a fully qualified ScreenQn.
390
392
  // Returns undefined if the screen isn't declared in any feature schema —
@@ -519,8 +521,7 @@ function RoutedScreen({ app, fallbackQn, translate, onRowClick, }) {
519
521
  };
520
522
  }, [nav]);
521
523
  if (feature === undefined || activeScreen === undefined) {
522
- const landingExists = findOwnerFeature(app.features, fallbackQn) !== undefined;
523
- return (_jsx(ScreenMissingState, { ...(landingExists && { homeScreenId: lastSegment(fallbackQn) }), screenQn: nav.route?.screenId ?? qn }));
524
+ return _jsx(ScreenMissingState, { screenQn: nav.route?.screenId ?? qn });
524
525
  }
525
526
  // KumikoScreen takes a single-feature schema: the feature owning the active screen.
526
527
  const schemaForScreen = feature;
@@ -17,7 +17,7 @@ export function EditorFooter({ testIdPrefix, actionTestIds = DEFAULT_ACTION_TEST
17
17
  const t = useTranslation();
18
18
  const { Banner, Button, Text } = usePrimitives();
19
19
  const tone = message === null ? null : FOOTER_TONE[message.tone];
20
- return (_jsxs("div", { className: "flex items-center gap-4 border-t bg-background px-6 py-3", "data-testid": `${testIdPrefix}-footer`, children: [_jsxs("div", { className: "min-w-0 flex-1 text-sm", children: [saveError !== null ? (_jsx(Banner, { variant: "error", testId: `${testIdPrefix}-save-error`, children: saveError })) : (_jsx("span", { className: cn(tone === null ? "text-muted-foreground" : tone.text), "data-testid": `${testIdPrefix}-footer-message`, "data-tone": message?.tone, children: message === null
20
+ return (_jsxs("div", { className: "flex flex-wrap items-center gap-x-4 gap-y-2 border-t bg-background px-6 py-3", "data-testid": `${testIdPrefix}-footer`, children: [_jsxs("div", { className: "min-w-0 basis-full text-sm sm:flex-1 sm:basis-0", children: [saveError !== null ? (_jsx(Banner, { variant: "error", testId: `${testIdPrefix}-save-error`, children: saveError })) : (_jsx("span", { className: cn(tone === null ? "text-muted-foreground" : tone.text), "data-testid": `${testIdPrefix}-footer-message`, "data-tone": message?.tone, children: message === null
21
21
  ? (pendingMessage ?? t("kumiko.editor.noChanges"))
22
- : `${tone?.glyph ?? ""} ${message.text}` })), modifiedAt !== null && (_jsxs(_Fragment, { children: [" ", _jsx(Text, { variant: "muted", testId: `${testIdPrefix}-saved-at`, children: t("kumiko.editor.savedAt", { when: formatRelativeWhen(modifiedAt) }) })] }))] }), _jsxs("div", { className: "flex shrink-0 items-center gap-3", children: [_jsx(Button, { variant: "ghost", disabled: !dirty, onClick: onDiscard, testId: actionTestIds.discard, children: t("kumiko.editor.discard") }), _jsx(Button, { variant: onPublish === undefined ? "primary" : "secondary", disabled: !canSave, loading: busy, onClick: onSave, testId: actionTestIds.save, children: saveLabel ?? t("kumiko.actions.save") }), onPublish !== undefined && (_jsx(Button, { disabled: canPublish !== true, onClick: onPublish, testId: actionTestIds.publish, children: t("kumiko.editor.publish") }))] })] }));
22
+ : `${tone?.glyph ?? ""} ${message.text}` })), modifiedAt !== null && (_jsxs(_Fragment, { children: [" ", _jsx(Text, { variant: "muted", testId: `${testIdPrefix}-saved-at`, children: t("kumiko.editor.savedAt", { when: formatRelativeWhen(modifiedAt) }) })] }))] }), _jsxs("div", { className: "ml-auto flex shrink-0 items-center gap-3", children: [_jsx(Button, { variant: "ghost", disabled: !dirty, onClick: onDiscard, testId: actionTestIds.discard, children: t("kumiko.editor.discard") }), _jsx(Button, { variant: onPublish === undefined ? "primary" : "secondary", disabled: !canSave, loading: busy, onClick: onSave, testId: actionTestIds.save, children: saveLabel ?? t("kumiko.actions.save") }), onPublish !== undefined && (_jsx(Button, { disabled: canPublish !== true, onClick: onPublish, testId: actionTestIds.publish, children: t("kumiko.editor.publish") }))] })] }));
23
23
  }
@@ -13,9 +13,9 @@ export function EditorInfoBar({ tone, testId, origin, controls, links, overlays,
13
13
  return (_jsxs(_Fragment, { children: [_jsxs("div", { className: cn("flex items-start gap-4 border-b px-6 py-2 text-sm", INFO_BAR_TONE[tone]), "data-testid": testId, "data-variant": tone === "warn" ? "warn" : undefined, children: [_jsxs("span", { className: "min-w-0 flex-1", children: [origin, " ", children] }), controls !== undefined && (_jsx("div", { className: "flex shrink-0 items-center gap-2", children: controls })), links !== undefined && _jsx("div", { className: "flex shrink-0 items-center gap-4", children: links })] }), overlays] }));
14
14
  }
15
15
  export function EditorBody({ left, center, right, testId, }) {
16
- const centerColumn = (_jsx("div", { className: "flex min-h-0 min-w-0 flex-col overflow-hidden bg-muted", children: center }));
16
+ const centerColumn = (_jsx("div", { className: "flex min-h-[70svh] min-w-0 flex-col overflow-hidden bg-muted md:min-h-0", children: center }));
17
17
  if (left === undefined) {
18
- return (_jsxs("div", { className: "grid min-h-0 flex-1 grid-cols-[minmax(0,1fr)_280px]", "data-testid": testId, children: [centerColumn, _jsx("aside", { className: "min-h-0 overflow-y-auto border-l bg-background", children: right })] }));
18
+ return (_jsxs("div", { className: "grid min-h-0 flex-1 grid-cols-1 grid-rows-[auto_auto] content-start overflow-y-auto md:grid-cols-[minmax(0,1fr)_280px] md:grid-rows-1 md:overflow-y-visible", "data-testid": testId, children: [centerColumn, _jsx("aside", { className: "border-t bg-background md:min-h-0 md:overflow-y-auto md:border-t-0 md:border-l", children: right })] }));
19
19
  }
20
20
  // Three columns leave a narrow window (1024px beside the app sidebar) too little room for the
21
21
  // page: there both rails share the left column, one below the other, and the center keeps its width.
@@ -29,7 +29,8 @@ export declare function EditorHeader({ title, status, actions, testIds, children
29
29
  readonly title: string;
30
30
  /** Badge next to the title, e.g. the stored version's state. */
31
31
  readonly status?: ReactNode;
32
- readonly actions: EditorSaveActions;
32
+ /** Without it the header has no save buttons and the footer carries them alone. */
33
+ readonly actions?: EditorSaveActions;
33
34
  readonly testIds?: EditorHeaderTestIds;
34
35
  /** View controls left of the save actions (mode or kind switch). */
35
36
  readonly children: ReactNode;
@@ -25,6 +25,6 @@ export function EditorHeader({ title, status, actions, testIds = DEFAULT_HEADER_
25
25
  const { Button, PageHeader } = usePrimitives();
26
26
  if (PageHeader === undefined)
27
27
  return null;
28
- const { onPublish } = actions;
29
- return (_jsx(PageHeader, { title: title, status: status, actions: _jsxs("span", { className: "flex items-center gap-2 [&_button]:px-2.5 [&_button]:text-sm", children: [children, _jsxs("span", { className: "hidden items-center gap-2 xl:flex", children: [_jsx(Button, { variant: onPublish === undefined ? "primary" : "secondary", size: "sm", disabled: !actions.canSave, loading: actions.busy, onClick: actions.onSave, testId: testIds.save, children: actions.saveLabel ?? t("kumiko.actions.save") }), onPublish !== undefined && (_jsx(Button, { size: "sm", disabled: actions.canPublish !== true, onClick: onPublish, testId: testIds.publish, children: t("kumiko.editor.publish") }))] })] }) }));
28
+ const onPublish = actions?.onPublish;
29
+ return (_jsx(PageHeader, { title: title, status: status, actions: _jsxs("span", { className: "flex items-center gap-2 [&_button]:px-2.5 [&_button]:text-sm", children: [children, actions !== undefined && (_jsxs("span", { className: "hidden items-center gap-2 xl:flex", children: [_jsx(Button, { variant: onPublish === undefined ? "primary" : "secondary", size: "sm", disabled: !actions.canSave, loading: actions.busy, onClick: actions.onSave, testId: testIds.save, children: actions.saveLabel ?? t("kumiko.actions.save") }), onPublish !== undefined && (_jsx(Button, { size: "sm", disabled: actions.canPublish !== true, onClick: onPublish, testId: testIds.publish, children: t("kumiko.editor.publish") }))] }))] }) }));
30
30
  }
@@ -10,10 +10,5 @@ export function EditorWorkbench({ testId, title, status, info, controls, banners
10
10
  const t = useTranslation();
11
11
  const [mode, setMode] = useState("edit");
12
12
  const editing = mode === "edit";
13
- return (_jsxs(EditorFrame, { testId: testId, children: [_jsx(EditorHeader, { title: title, status: status, actions: {
14
- busy: save.busy,
15
- canSave: save.canSave,
16
- onSave: save.onSave,
17
- ...(save.saveLabel !== undefined && { saveLabel: save.saveLabel }),
18
- }, children: _jsx(EditorModeSwitch, { testIdPrefix: testId, mode: mode, onMode: setMode }) }), _jsx(EditorInfoBar, { tone: "muted", testId: `${testId}-info`, controls: controls, children: editing ? info.edit : info.preview }), banners, _jsx(EditorBody, { testId: `${testId}-${mode}`, center: editing ? edit : preview, right: editing ? rail.edit : rail.preview, ...(rail.left !== undefined && { left: rail.left }) }), _jsx(EditorFooter, { testIdPrefix: testId, message: save.dirty ? { tone: "warn", text: t("kumiko.editor.unsavedChanges") } : null, saveError: save.saveError, modifiedAt: save.modifiedAt ?? null, dirty: save.dirty, busy: save.busy, canSave: save.canSave, onDiscard: save.onDiscard, onSave: save.onSave, ...(save.saveLabel !== undefined && { saveLabel: save.saveLabel }) })] }));
13
+ return (_jsxs(EditorFrame, { testId: testId, children: [_jsx(EditorHeader, { title: title, status: status, children: _jsx(EditorModeSwitch, { testIdPrefix: testId, mode: mode, onMode: setMode }) }), _jsx(EditorInfoBar, { tone: "muted", testId: `${testId}-info`, controls: controls, children: editing ? info.edit : info.preview }), banners, _jsx(EditorBody, { testId: `${testId}-${mode}`, center: editing ? edit : preview, right: editing ? rail.edit : rail.preview, ...(rail.left !== undefined && { left: rail.left }) }), _jsx(EditorFooter, { testIdPrefix: testId, message: save.dirty ? { tone: "warn", text: t("kumiko.editor.unsavedChanges") } : null, saveError: save.saveError, modifiedAt: save.modifiedAt ?? null, dirty: save.dirty, busy: save.busy, canSave: save.canSave, onDiscard: save.onDiscard, onSave: save.onSave, ...(save.saveLabel !== undefined && { saveLabel: save.saveLabel }) })] }));
19
14
  }
@@ -0,0 +1,3 @@
1
+ import type { ReactNode } from "react";
2
+ import type { EmptyStateProps } from "../../index.ts";
3
+ export declare function DefaultEmptyState({ icon, title, description, actions, testId, }: EmptyStateProps): ReactNode;
@@ -0,0 +1,10 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { FileQuestion, Lock } from "lucide-react";
3
+ const ICONS = {
4
+ unavailable: Lock,
5
+ "not-found": FileQuestion,
6
+ };
7
+ export function DefaultEmptyState({ icon, title, description, actions, testId, }) {
8
+ const Icon = ICONS[icon];
9
+ return (_jsxs("div", { "data-testid": testId, className: "mx-auto flex max-w-md flex-col items-center gap-3 px-6 py-16 text-center", children: [_jsx("div", { className: "rounded-full bg-muted p-3 text-muted-foreground", children: _jsx(Icon, { className: "size-6", "aria-hidden": "true" }) }), _jsx("h2", { "data-testid": testId !== undefined ? `${testId}-title` : undefined, className: "text-lg font-semibold", children: title }), description !== undefined && (_jsx("div", { className: "flex flex-col gap-1 text-sm text-muted-foreground", children: description })), actions !== undefined && (_jsx("div", { className: "mt-2 flex flex-wrap items-center justify-center gap-2", children: actions }))] }));
10
+ }
@@ -9,6 +9,7 @@ import { applyFormatSpec } from "../../headless/index.js";
9
9
  import { DefaultDialog } from "./dialog.js";
10
10
  import { DefaultDrawer } from "./drawer.js";
11
11
  import { EmbeddedListInput } from "./embedded-list-input.js";
12
+ import { DefaultEmptyState } from "./empty-state.js";
12
13
  import { FileValueList } from "./file-value-list.js";
13
14
  import { DefaultJsonView } from "./json-view.js";
14
15
  import { DefaultLightbox } from "./lightbox.js";
@@ -88,4 +89,5 @@ export const defaultPrimitives = {
88
89
  CopyButton,
89
90
  ShareButton,
90
91
  PromoPanel,
92
+ EmptyState: DefaultEmptyState,
91
93
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-renderer",
3
- "version": "0.421.0",
3
+ "version": "0.424.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.424.0",
52
+ "@cosmicdrift/kumiko-types": "0.424.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.424.0",
83
+ "@cosmicdrift/kumiko-testing": "0.424.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,34 @@
1
1
  [
2
+ {
3
+ "version": "0.424.0",
4
+ "type": "fix",
5
+ "title": "Action-form preview hides an empty list next to facts",
6
+ "detail": "`preview.list` renders only when it has rows or the preview has no `facts`, so a preview with facts and an empty list (for example a contract PDF with no rent steps) no longer shows a dashed \"No entries yet.\" box. `EditorWorkbench` no longer renders save buttons in the page header (they were a second copy of the footer's, shown from 1280px up); `EditorHeader` takes `actions` as optional."
7
+ },
8
+ {
9
+ "version": "0.424.0",
10
+ "type": "fix",
11
+ "title": "Seeding the default row of a required optionsQuery select clears its required error",
12
+ "detail": "Seeding the suggestion (`row.default`) into an empty select now clears that field's issues the same way a typed value does, so a submit before the options query had loaded no longer leaves \"required\" next to a filled field."
13
+ },
14
+ {
15
+ "version": "0.423.0",
16
+ "type": "improvement",
17
+ "title": "The \"page not available\" and \"record not found\" pages are a calm empty state with a way back",
18
+ "detail": "New optional primitive `EmptyState` (`icon` \"unavailable\" or \"not-found\", `title`, `description`, `actions`) renders a centered page with an icon in a soft circle; custom primitive sets without it keep the plain card. \"This page is not available\" now always offers a primary \"Go to start page\" button (start page from the new `HomeScreenProvider`, mounted by `createKumikoApp`, so drawers and `KumikoScreen` get it too) and a line telling the user whom to ask (new i18n key `kumiko.screen-missing.contact`, en/de/fr/es/it). The \"record not found\" page uses the same look."
19
+ },
20
+ {
21
+ "version": "0.422.0",
22
+ "type": "improvement",
23
+ "title": "Form intro as an info banner",
24
+ "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."
25
+ },
26
+ {
27
+ "version": "0.422.0",
28
+ "type": "improvement",
29
+ "title": "Submit an actionForm through another write handler",
30
+ "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)."
31
+ },
2
32
  {
3
33
  "version": "0.420.0",
4
34
  "type": "improvement",