@cosmicdrift/kumiko-renderer 0.366.0 → 0.368.0

package/dist/app/kumiko-screen.d.ts

@@ -19,6 +19,13 @@ export { qualifyScreenId };
 export declare function qualifyNavId(featureName: string, navId: string): string;
 export { screenAccessAllows };
 export declare function KumikoScreen({ schema, qn, translate, entityId, onRowClick, onCopyLink, }: KumikoScreenProps): ReactNode;
+/** Empty state for a screen QN that is not in the schema (feature disabled for
+ *  the tenant, stale link, miswired screen). The QN only goes to the console. */
+export declare function ScreenMissingState({ screenQn, homeScreenId, testId, }: {
+    readonly screenQn: string;
+    readonly homeScreenId?: string;
+    readonly testId?: string;
+}): ReactNode;
 export declare function buildInitialValues(fields: Readonly<Record<string, unknown>>, defaultCurrency?: string, moneyCurrencyOverrides?: Readonly<Record<string, string>>): FormValues;
 export declare function tenantCurrencyMoneyFieldNames(fields: Readonly<Record<string, unknown>>): readonly string[];
 export declare function literalCurrencyOverrides(fields: Readonly<Record<string, unknown>>): Readonly<Record<string, string>>;

package/dist/app/kumiko-screen.js

@@ -61,7 +61,6 @@ export function qualifyNavId(featureName, navId) {
 }
 export { screenAccessAllows };
 export function KumikoScreen({ schema, qn, translate, entityId, onRowClick, onCopyLink, }) {
-    const { Banner, Text } = usePrimitives();
     const userRoles = useUserRoles();
     const outerHost = useReturnHost();
     const screen = useMemo(() => schema.screens.find((s) => qualifyScreenId(schema.featureName, s.id) === qn), [schema.featureName, schema.screens, qn]);
@@ -71,10 +70,10 @@ export function KumikoScreen({ schema, qn, translate, entityId, onRowClick, onCo
         ...(entityId !== undefined && { entityId }),
     }), [screen, entityId]);
     if (!screen) {
-        return (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-screen-not-found", children: ["Screen not found: ", _jsx(Text, { variant: "code", children: qn })] }));
+        return _jsx(ScreenMissingState, { screenQn: qn });
     }
     if (!screenAccessAllows(screen.access, userRoles)) {
-        return (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-screen-access-denied", children: ["Access denied: ", _jsx(Text, { variant: "code", children: qn })] }));
+        return _jsx(ScreenAccessDeniedBanner, { screenQn: qn, testId: "kumiko-screen-access-denied" });
     }
     const screenBody = renderScreenBody({
         schema,
@@ -94,8 +93,7 @@ export function KumikoScreen({ schema, qn, translate, entityId, onRowClick, onCo
     return _jsx(ReturnHostProvider, { value: ownHost, children: body });
 }
 function ScreenVisibilityGate({ featureName, visibleWhen, fallback, translate, children, }) {
-    const { Banner, PageHeader } = usePrimitives();
-    const pageHeaderSlotAvailable = usePageHeaderSlotAvailable();
+    const { Banner } = usePrimitives();
     const result = useQuery(visibleWhen.query, {}, { live: true });
     const wasShown = useRef(false);
     const verdict = evalVisibleWhenAfterShown(visibleWhen, result, wasShown.current);
@@ -108,9 +106,43 @@ function ScreenVisibilityGate({ featureName, visibleWhen, fallback, translate, c
     if (verdict === "loading") {
         return (_jsx(Banner, { padded: true, variant: "loading", testId: "kumiko-screen-loading", children: "Loading\u2026" }));
     }
-    // The route still names the locked screen; its breadcrumb must not label what stands in for it.
-    const hideLockedBreadcrumb = PageHeader !== undefined && pageHeaderSlotAvailable ? _jsx(PageHeader, { hideBreadcrumb: true }) : null;
-    return (_jsxs(_Fragment, { children: [hideLockedBreadcrumb, fallback !== undefined ? (_jsx(FallbackScreen, { featureName: featureName, fallback: fallback, translate: translate })) : (_jsx(ScreenUnavailableBanner, {}))] }));
+    if (fallback !== undefined) {
+        return _jsx(FallbackScreen, { featureName: featureName, fallback: fallback, translate: translate });
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(LockedScreenHeader, {}), _jsx(ScreenUnavailableBanner, {})] }));
+}
+// The route still names the locked screen; its breadcrumb must not label what stands in for it.
+// With a stand-in the header is labelled with that screen instead, none if it has no title.
+function LockedScreenHeader({ standInScreenId }) {
+    const { PageHeader } = usePrimitives();
+    const pageHeaderSlotAvailable = usePageHeaderSlotAvailable();
+    if (PageHeader === undefined || !pageHeaderSlotAvailable)
+        return null;
+    return standInScreenId !== undefined ? (_jsx(PageHeader, { hideBreadcrumb: true, breadcrumbScreenId: standInScreenId })) : (_jsx(PageHeader, { hideBreadcrumb: true }));
+}
+function ScreenMissingHomeButton({ homeScreenId, testId, }) {
+    const { Button } = usePrimitives();
+    const t = useTranslation();
+    const nav = useNav();
+    return (_jsx(Button, { variant: "secondary", onClick: () => nav.navigate({ screenId: homeScreenId }), testId: testId, children: t("kumiko.screen-missing.home") }));
+}
+/** Empty state for a screen QN that is not in the schema (feature disabled for
+ *  the tenant, stale link, miswired screen). The QN only goes to the console. */
+export function ScreenMissingState({ screenQn, homeScreenId, testId = "kumiko-screen-not-found", }) {
+    const { Card, Text } = usePrimitives();
+    const t = useTranslation();
+    useEffect(() => {
+        console.warn(`[kumiko] screen "${screenQn}" is not in the schema (feature disabled, stale link or miswired screen).`);
+    }, [screenQn]);
+    return (_jsxs(Card, { options: { padded: true }, testId: testId, children: [_jsx(Text, { testId: `${testId}-title`, children: t("kumiko.screen-missing.title") }), _jsx(Text, { variant: "muted", children: t("kumiko.screen-missing.hint") }), homeScreenId !== undefined && (_jsx(ScreenMissingHomeButton, { homeScreenId: homeScreenId, testId: `${testId}-home` }))] }));
+}
+function ScreenAccessDeniedBanner({ screenQn, testId, }) {
+    const { Banner } = usePrimitives();
+    const t = useTranslation();
+    useEffect(() => {
+        console.warn(`[kumiko] access to screen "${screenQn}" denied for the current roles.`);
+    }, [screenQn]);
+    return (_jsx(Banner, { padded: true, variant: "error", testId: testId, children: t("kumiko.screen-access-denied.title") }));
 }
 function ScreenUnavailableBanner() {
     const { Banner } = usePrimitives();
@@ -121,9 +153,10 @@ function FallbackScreen({ featureName, fallback, translate, }) {
     const target = useEmbeddedScreen(featureName, fallback);
     // Also undefined when the user lacks access to the fallback screen, which is
     // not a framework error.
-    if (target === undefined)
-        return _jsx(ScreenUnavailableBanner, {});
-    return _jsx(KumikoScreen, { schema: target.schema, qn: target.qn, translate: translate });
+    if (target === undefined) {
+        return (_jsxs(_Fragment, { children: [_jsx(LockedScreenHeader, {}), _jsx(ScreenUnavailableBanner, {})] }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(LockedScreenHeader, { standInScreenId: lastSegment(target.qn) }), _jsx(KumikoScreen, { schema: target.schema, qn: target.qn, translate: translate })] }));
 }
 function renderScreenBody({ schema, screen, translate, entityId, onRowClick, onCopyLink, }) {
     switch (screen.type) {
@@ -1143,7 +1176,7 @@ function useDrawerAction(schema) {
     };
 }
 function DrawerHost({ schema, drawerAction, drawerScreen, drawerInitialValues, userRoles, translate, onClose, onSuccess, }) {
-    const { Drawer, Banner, Text, Dialog } = usePrimitives();
+    const { Drawer, Dialog } = usePrimitives();
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
     const locale = useLocale().locale();
@@ -1185,7 +1218,7 @@ function DrawerHost({ schema, drawerAction, drawerScreen, drawerInitialValues, u
                         requestClose();
                 }, title: effectiveTranslate(drawerAction.title ?? drawerAction.label, titleParams), ...(drawerAction.subtitle !== undefined && {
                     subtitle: effectiveTranslate(drawerAction.subtitle, titleParams),
-                }), testId: `toolbar-drawer-${drawerAction.id}`, children: _jsx(PageHeaderSlotAvailableProvider, { value: false, children: _jsx(InsideDrawerProvider, { value: true, children: drawerScreen === undefined ? (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-toolbar-drawer-not-found", children: ["Screen not found: ", _jsx(Text, { variant: "code", children: drawerAction.screen })] })) : !allowed ? (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-toolbar-drawer-access-denied", children: ["Access denied: ", _jsx(Text, { variant: "code", children: drawerAction.screen })] })) : (_jsx(ActionFormBody, { schema: schema, screen: drawerScreen, ...(translate !== undefined && { translate }), ...(drawerInitialValues !== undefined && {
+                }), testId: `toolbar-drawer-${drawerAction.id}`, children: _jsx(PageHeaderSlotAvailableProvider, { value: false, children: _jsx(InsideDrawerProvider, { value: true, children: drawerScreen === undefined ? (_jsx(ScreenMissingState, { screenQn: drawerAction.screen, testId: "kumiko-toolbar-drawer-not-found" })) : !allowed ? (_jsx(ScreenAccessDeniedBanner, { screenQn: drawerAction.screen, testId: "kumiko-toolbar-drawer-access-denied" })) : (_jsx(ActionFormBody, { schema: schema, screen: drawerScreen, ...(translate !== undefined && { translate }), ...(drawerInitialValues !== undefined && {
                                 initialOverrides: drawerInitialValues,
                             }), onSuccess: () => {
                                 setHasUnsavedInput(false);

package/dist/app/projection-detail-shim.js

@@ -63,6 +63,7 @@ export function synthesizeProjectionDetailScreen(screen) {
         allowCreate: false,
         allowDelete: false,
         ...(screen.description !== undefined && { description: screen.description }),
+        ...(screen.recordTitleField !== undefined && { recordTitleField: screen.recordTitleField }),
         ...(screen.fieldLabels !== undefined && { fieldLabels: screen.fieldLabels }),
         ...(screen.slots !== undefined && { slots: screen.slots }),
         ...(screen.access !== undefined && { access: screen.access }),

package/dist/components/render-edit.js

@@ -1240,6 +1240,12 @@ export function RenderEdit(props) {
     // floating as a heading above the band.
     const titleInSettingsHeader = isSettingsList && !titleInShell;
     const usesFieldFlow = isScreenForm || 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.
+    const recordTitleInHeaderRegion = headerRegion !== undefined &&
+        recordTitle !== undefined &&
+        PageHeader !== undefined &&
+        pageHeaderSlotAvailable;
     const allRequiredHint = (_jsx(Text, { variant: "muted", testId: "render-edit-all-required-hint", children: translate("kumiko.form.all-required") }));
     const stepRail = isWizard && isScreenForm && StepBar !== undefined;
     const upNextSection = screen.layout.wizard?.aside?.upNext === true ? filteredSections[currentStep + 1] : undefined;
@@ -1270,7 +1276,8 @@ export function RenderEdit(props) {
                     actions: (_jsx(ActionOverflowMenu, { label: translate("kumiko.list.row-actions.more"), items: headerMenuItems, testId: "render-edit-header-menu" })),
                 }) })), _jsx(Form, { onSubmit: () => void handleSubmit(), ...(hideSectionTitles !== true &&
                     !titleInShell &&
-                    !titleInSettingsHeader && { title: formTitle }), ...(formSubtitle !== undefined &&
+                    !titleInSettingsHeader &&
+                    !recordTitleInHeaderRegion && { title: formTitle }), ...(formSubtitle !== undefined &&
                     !stepRail &&
                     !titleInSettingsHeader && { subtitle: formSubtitle }), ...(isScreenForm && { screenForm: true }), ...(unsavedCount !== undefined &&
                     (unsavedCount > 0 || hasDirtyFooter) && { unsavedCount }), ...(sectionNavItems.length > 0 && { sectionNav: sectionNavItems }), ...(stepRail && {

package/dist/i18n-defaults.js

@@ -135,6 +135,10 @@ export const kumikoDefaultTranslations = {
         "kumiko.app-boot.no-open-screen": "This app has no screen that's accessible without a role restriction.",
         "kumiko.widget.loading": "Loading…",
         "kumiko.widget.error.title": "Couldn't load.",
+        "kumiko.screen-missing.title": "This page is not available",
+        "kumiko.screen-missing.hint": "It is not enabled for your account or no longer exists.",
+        "kumiko.screen-access-denied.title": "You do not have access to this page.",
+        "kumiko.screen-missing.home": "Go to start page",
         "kumiko.screen-error.title": "This screen failed to render.",
         "kumiko.screen-error.detail": "Screen: {screen}. {message}",
         "kumiko.screen-error.screen": "Screen: {screen}",

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export { ExtensionSectionsProvider, extensionSectionName, useExtensionSectionCom
 export type { AppSchema, FeatureSchema, QualifiedContentCollection, WorkspaceSchema, } from "./app/feature-schema.js";
 export { isAppSchema, toAppSchema } from "./app/feature-schema.js";
 export type { KumikoScreenProps } from "./app/kumiko-screen.js";
-export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen.js";
+export { KumikoScreen, qualifyNavId, qualifyScreenId, ScreenMissingState, } from "./app/kumiko-screen.js";
 export type { DateRangeBound, DateRangeValue, ResolvedDateRangeFacet } from "./app/list-facets.js";
 export { buildDateRangePayload, clampDateRange, readDateRange, resolveDateRangeFacets, } from "./app/list-facets.js";
 export type { NavApi, NavigateOptions, NavProviderProps, NavRoute, NavTarget, ObjectTarget, ScreenTarget, } from "./app/nav.js";
@@ -75,7 +75,7 @@ export { createStaticLocaleResolver, FormalityProvider, LocaleProvider, mergeTra
 export { kumikoDefaultTranslations } from "./i18n-defaults.js";
 export { InsideDrawerProvider, useInsideDrawer } from "./inside-drawer.js";
 export { PageHeaderCompactProvider, PageHeaderSlotAvailableProvider, usePageHeaderCompact, usePageHeaderSlotAvailable, } from "./page-header-slot.js";
-export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableRowGrouping, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FillContainerProps, FooterActionMarker, FooterActionRole, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputProps, JsonViewProps, LightboxImage, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, TrailingInputAction, WizardStepGroupProps, } from "./primitives.js";
+export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableRowGrouping, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FillContainerProps, FooterActionMarker, FooterActionRole, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputProps, JsonViewProps, LightboxImage, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PickedFile, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, TrailingInputAction, WizardStepGroupProps, } from "./primitives.js";
 export { FOOTER_ACTION_ROLE_PROP, NARROW_LABEL_PROP, PrimitivesProvider, STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, statusToneForOptionTone, statusToneForValue, useOptionalPrimitives, usePrimitives, } from "./primitives.js";
 export type { SessionEndedSignal, SessionEndedSignalProviderProps, } from "./session/session-ended.js";
 export { createSessionEndedSignal, isSessionEndedError, SESSION_ENDED_ERROR_CODES, SessionEndedSignalProvider, useSessionEndedSignal, withSessionEndedDetection, } from "./session/session-ended.js";

package/dist/index.js

@@ -19,7 +19,7 @@ export { DashboardBodyProvider, useDashboardBody } from "./app/dashboard-body.js
 export { ExtensionFormRegistryProvider, useExtensionFormSubmit, } from "./app/extension-form-submit.js";
 export { ExtensionSectionsProvider, extensionSectionName, useExtensionSectionComponent, } from "./app/extension-sections.js";
 export { isAppSchema, toAppSchema } from "./app/feature-schema.js";
-export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen.js";
+export { KumikoScreen, qualifyNavId, qualifyScreenId, ScreenMissingState, } from "./app/kumiko-screen.js";
 export { buildDateRangePayload, clampDateRange, readDateRange, resolveDateRangeFacets, } from "./app/list-facets.js";
 export { formatPath, hasDetailScreen, NavProvider, parsePath, resolveTarget, useNav, useNavigateWithInitialValues, } from "./app/nav.js";
 export { lastSegment } from "./app/qn.js";

package/dist/primitives.d.ts

@@ -180,6 +180,14 @@ export type TrailingInputAction = {
     readonly onPress: () => void;
     readonly testId?: string;
 };
+/** Platform-neutral view of a picked file; the DOM `File` satisfies it. */
+export type PickedFile = {
+    readonly name: string;
+    readonly size: number;
+    readonly type: string;
+    readonly webkitRelativePath: string;
+    readonly arrayBuffer: () => Promise<ArrayBuffer>;
+};
 export type InputProps = {
     readonly kind: "text";
     readonly id: string;
@@ -318,6 +326,14 @@ export type InputProps = {
     /** Only for kind:"image" — forwarded to the file input's `capture`
      *  attribute so a phone opens the camera instead of the file picker. */
     readonly capture?: "environment" | "user";
+    /** Web-only folder picker: the picked files (with `webkitRelativePath`)
+     *  go to `onFilesPicked` and nothing is uploaded. Native impls ignore it. */
+    readonly directory?: boolean;
+    readonly onFilesPicked?: (files: readonly PickedFile[]) => void;
+    /** Translated label of the pick button; absent → the upload/change default. */
+    readonly pickLabel?: string;
+    /** Hidden file input gets `${testId}-input`, the pick button `${testId}-pick`. */
+    readonly testId?: string;
 } | {
     readonly kind: "date";
     readonly id: string;
@@ -1337,6 +1353,9 @@ export type PageHeaderProps = {
     /** Hide the shell header's breadcrumb while mounted, for a screen that stands in
      *  for the one the route names (a locked screen's fallback). */
     readonly hideBreadcrumb?: boolean;
+    /** Label the breadcrumb with this screen (id as in the route) instead of the one
+     *  the route names, for a locked screen's fallback. Wins over `hideBreadcrumb`. */
+    readonly breadcrumbScreenId?: string;
 };
 /** One item in an `ActionOverflowMenu` (A7: header/row actions beyond the
  *  primary one collapse into this menu instead of a wall of buttons). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.366.0",
+  "version": "0.368.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,9 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.366.0",
-    "@cosmicdrift/kumiko-headless": "0.366.0",
-    "@cosmicdrift/kumiko-types": "0.366.0",
+    "@cosmicdrift/kumiko-framework": "0.368.0",
+    "@cosmicdrift/kumiko-headless": "0.368.0",
+    "@cosmicdrift/kumiko-types": "0.368.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.366.0"
+    "@cosmicdrift/kumiko-locale-de": "0.368.0"
   },
   "repository": {
     "type": "git",

package/src/changes.json

@@ -1,4 +1,29 @@
 [
+  {
+    "version": "0.368.0",
+    "type": "fix",
+    "title": "A screen that falls back via visibleWhen shows the fallback's title",
+    "detail": "When visibleWhen locks a screen and its fallback renders instead, the header no longer stays empty. It shows the title of the fallback screen (resolved like any other screen title, from its nav label), never the locked screen's. A fallback without a title still leaves the header empty. PageHeader takes a new breadcrumbScreenId prop for this."
+  },
+  {
+    "version": "0.367.0",
+    "type": "fix",
+    "title": "projectionDetail no longer shows an empty type-title block above the record",
+    "detail": "The projectionDetail shim dropped recordTitleField, so the duplicate-title fix never applied to real projectionDetail screens. The synthesized edit screen now carries it, and the page header shows the record title once."
+  },
+  {
+    "version": "0.367.0",
+    "type": "fix",
+    "title": "A route to a screen missing from the schema shows an empty state",
+    "detail": "A tenant-disabled feature, stale link or typo no longer falls back to the first feature or shows \"Screen not found: <qn>\". The app renders \"This page is not available\" with a button to the landing screen; the qualified name only goes to the console. New i18n keys kumiko.screen-missing.title, .hint and .home (en, de, es). The access-denied banner of KumikoScreen and the toolbar drawer is now translated too (kumiko.screen-access-denied.title) and no longer prints the qualified name.",
+    "migration": "e2e checks on the text \"Screen not found\" should use the testId kumiko-screen-not-found; the testIds are unchanged."
+  },
+  {
+    "version": "0.367.0",
+    "type": "fix",
+    "title": "projectionDetail drops the duplicate title block",
+    "detail": "A screen with recordTitleField no longer repeats the screen title above the form when the page header already shows the record title."
+  },
   {
     "version": "0.365.0",
     "type": "fix",