@cosmicdrift/kumiko-renderer 0.275.0 → 0.277.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.275.0",
+  "version": "0.277.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,8 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.275.0",
-    "@cosmicdrift/kumiko-headless": "0.275.0",
+    "@cosmicdrift/kumiko-framework": "0.277.0",
+    "@cosmicdrift/kumiko-headless": "0.277.0",
+    "@cosmicdrift/kumiko-types": "0.277.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -27,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.275.0"
+    "@cosmicdrift/kumiko-locale-de": "0.277.0"
   },
   "repository": {
     "type": "git",

package/src/app/kumiko-screen.tsx

@@ -32,6 +32,7 @@ import type {
   Translate,
 } from "@cosmicdrift/kumiko-headless";
 import { fieldLabelKey, fieldOptionLabelKey, isSafeHref } from "@cosmicdrift/kumiko-headless";
+import { TENANT_CURRENCY_CONFIG_KEY } from "@cosmicdrift/kumiko-types/fields";
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { extractCreatedId, extractIdField } from "../components/reference-create-dialog";
 import {
@@ -48,7 +49,7 @@ import { RenderList } from "../components/render-list";
 import { useDispatcher, useOptionalDispatcher } from "../context/dispatcher-context";
 import { useUserRoles } from "../context/user-roles-context";
 import { type ListSort, useListUrlState } from "../hooks/use-list-url-state";
-import { useQuery } from "../hooks/use-query";
+import { type UseQueryResult, useQuery } from "../hooks/use-query";
 import { useTranslation } from "../i18n";
 import {
   type DataTableFacet,
@@ -404,9 +405,14 @@ function useNavigateToCreateFor(
 
 // `defaultCurrency` is entityEdit-only — it enables the `{amount, currency}`
 // write shape (fw#1923); config-edit's plain-number contract needs bare `0`.
+// `moneyCurrencyOverrides` (fw#2933) replaces `defaultCurrency` per field name
+// — used for a `money` field that declares `currency: { kind: "tenant" }`, so
+// its empty initial value carries the tenant's own currency instead of the
+// entity-wide default.
 export function buildInitialValues(
   fields: Readonly<Record<string, unknown>>,
   defaultCurrency?: string,
+  moneyCurrencyOverrides?: Readonly<Record<string, string>>,
 ): Readonly<Record<string, unknown>> {
   const out: Record<string, unknown> = {};
   for (const [name, def] of Object.entries(fields)) {
@@ -419,9 +425,12 @@ export function buildInitialValues(
       out[name] = [];
       continue;
     }
-    if (shape.type === "money" && defaultCurrency !== undefined) {
-      out[name] = { amount: 0, currency: defaultCurrency };
-      continue;
+    if (shape.type === "money") {
+      const currency = moneyCurrencyOverrides?.[name] ?? defaultCurrency;
+      if (currency !== undefined) {
+        out[name] = { amount: 0, currency };
+        continue;
+      }
     }
     out[name] =
       shape.type === "boolean"
@@ -435,6 +444,49 @@ export function buildInitialValues(
   return out;
 }
 
+// A `money` field opts a currently-empty value into the tenant-settings
+// bundle's per-tenant currency (fw#2933) via `currency: { kind: "tenant" }`
+// on its FieldDefinition. Read structurally — renderer only depends on the
+// client-safe FieldDefinition subset, not the concrete MoneyFieldDef/
+// MoneyCurrencySource types, same idiom as the other field-shape narrowings
+// in this file (PrefillFieldShape etc.).
+function tenantCurrencyMoneyFieldNames(
+  fields: Readonly<Record<string, unknown>>,
+): readonly string[] {
+  const names: string[] = [];
+  for (const [name, def] of Object.entries(fields)) {
+    const shape = def as { readonly type?: string; readonly currency?: { readonly kind?: string } };
+    if (shape.type === "money" && shape.currency?.kind === "tenant") names.push(name);
+  }
+  return names;
+}
+
+type TenantConfigValuesResponse = Readonly<
+  Record<string, { readonly value: string | number | boolean | undefined }>
+>;
+
+type TenantCurrencyResolution =
+  | { readonly status: "not-needed" }
+  | { readonly status: "loading" }
+  | { readonly status: "ready"; readonly currency: string };
+
+// Resolves what a tenant-declared money field's currency should be, from the
+// same `config:query:values` query ConfigEditBody already uses. Never falls
+// back to "EUR" while the query is genuinely still in flight (fw#2933) — a
+// screen with no tenant-declared money field, or a query that errored or
+// returned no value for the key, resolves immediately instead of blocking.
+function resolveTenantCurrency(
+  fieldNames: readonly string[],
+  query: UseQueryResult<TenantConfigValuesResponse>,
+  fallback: string,
+): TenantCurrencyResolution {
+  if (fieldNames.length === 0) return { status: "not-needed" };
+  if (query.error) return { status: "ready", currency: fallback };
+  if (query.data === null) return { status: "loading" };
+  const raw = query.data[TENANT_CURRENCY_CONFIG_KEY]?.value;
+  return { status: "ready", currency: typeof raw === "string" && raw !== "" ? raw : fallback };
+}
+
 function multiSelectOptionValues(shape: {
   readonly options?: readonly (string | { readonly value: string })[];
 }): ReadonlySet<string> | undefined {
@@ -586,6 +638,9 @@ export type InitialValueSources = {
   readonly urlPrefillFields: readonly string[] | undefined;
   readonly renderableFields?: ReadonlySet<string>;
   readonly defaultCurrency?: string;
+  // Per-field override of `defaultCurrency` for money fields declaring
+  // `currency: { kind: "tenant" }` (fw#2933) — see buildInitialValues.
+  readonly moneyCurrencyOverrides?: Readonly<Record<string, string>>;
   // Drawer-kind row actions (fw#2710) prefill from the clicked row's
   // already-typed values; wins over every other source.
   readonly drawerOverrides?: Readonly<Record<string, unknown>>;
@@ -600,13 +655,14 @@ function coercePrefillString(
   shape: PrefillFieldShape,
   fallback: unknown,
   defaultCurrency: string | undefined,
+  moneyCurrencyOverrides: Readonly<Record<string, string>> | undefined,
 ): unknown {
   if (shape.type === "number") {
     const parsed = Number(raw);
     return Number.isNaN(parsed) ? fallback : parsed;
   }
   if (shape.type === "money") {
-    const coerced = coerceMoneyValue(raw, name, defaultCurrency);
+    const coerced = coerceMoneyValue(raw, name, moneyCurrencyOverrides?.[name] ?? defaultCurrency);
     return coerced === undefined ? fallback : coerced;
   }
   if (shape.type === "boolean") return raw === "true";
@@ -648,10 +704,19 @@ export function mergeSearchParamsIntoInitial(
   fields: Readonly<Record<string, unknown>>,
   sources: InitialValueSources,
 ): Record<string, unknown> {
-  const { searchParams, renderableFields, defaultCurrency, drawerOverrides, handoffValues } =
-    sources;
+  const {
+    searchParams,
+    renderableFields,
+    defaultCurrency,
+    moneyCurrencyOverrides,
+    drawerOverrides,
+    handoffValues,
+  } = sources;
   const urlPrefillFields = new Set(sources.urlPrefillFields ?? []);
-  const defaults = buildInitialValues(fields, defaultCurrency) as Record<string, unknown>;
+  const defaults = buildInitialValues(fields, defaultCurrency, moneyCurrencyOverrides) as Record<
+    string,
+    unknown
+  >;
   const merged: Record<string, unknown> = { ...defaults };
   for (const [name, fieldDef] of Object.entries(fields)) {
     if (renderableFields !== undefined && !renderableFields.has(name)) continue;
@@ -670,14 +735,28 @@ export function mergeSearchParamsIntoInitial(
     if (handedOff !== undefined) {
       merged[name] =
         typeof handedOff === "string"
-          ? coercePrefillString(handedOff, name, shape, defaults[name], defaultCurrency)
+          ? coercePrefillString(
+              handedOff,
+              name,
+              shape,
+              defaults[name],
+              defaultCurrency,
+              moneyCurrencyOverrides,
+            )
           : handedOff;
       continue;
     }
     if (!urlPrefillFields.has(name)) continue;
     const raw = searchParams[name];
     if (raw === undefined) continue;
-    merged[name] = coercePrefillString(raw, name, shape, defaults[name], defaultCurrency);
+    merged[name] = coercePrefillString(
+      raw,
+      name,
+      shape,
+      defaults[name],
+      defaultCurrency,
+      moneyCurrencyOverrides,
+    );
   }
   return merged;
 }
@@ -761,6 +840,7 @@ function EntityEditCreateBody({
   // new row.
   readonly onSaved?: () => void;
 }): ReactNode {
+  const { Banner } = usePrimitives();
   const nav = useNav();
   const handoffValues = useInitialValuesHandoff(screen.id);
   const appFeatures = useAppFeatures();
@@ -768,16 +848,53 @@ function EntityEditCreateBody({
   // A singleton stays on its own screen after saving (onSaved/refetch) —
   // returnTo would fight that.
   const returnTarget = screen.singleton === true ? undefined : returnTargetParam;
+  const entityDefaultCurrency = entity.defaultCurrency ?? "EUR";
+  // A money field declaring `currency: { kind: "tenant" }` (fw#2933) resolves
+  // its empty-value currency from the tenant-settings config key instead of
+  // entityDefaultCurrency — `enabled` keeps the query a no-op for entities
+  // without any such field.
+  const tenantCurrencyFieldNames = useMemo(
+    () => tenantCurrencyMoneyFieldNames(entity.fields),
+    [entity.fields],
+  );
+  const needsTenantCurrency = tenantCurrencyFieldNames.length > 0;
+  const tenantCurrencyQuery = useQuery<TenantConfigValuesResponse>(
+    "config:query:values",
+    {},
+    { enabled: needsTenantCurrency },
+  );
+  const tenantCurrencyResolution = resolveTenantCurrency(
+    tenantCurrencyFieldNames,
+    tenantCurrencyQuery,
+    entityDefaultCurrency,
+  );
+  const resolvedTenantCurrency =
+    tenantCurrencyResolution.status === "ready" ? tenantCurrencyResolution.currency : undefined;
+  const moneyCurrencyOverrides = useMemo(
+    () =>
+      resolvedTenantCurrency !== undefined
+        ? Object.fromEntries(tenantCurrencyFieldNames.map((name) => [name, resolvedTenantCurrency]))
+        : undefined,
+    [tenantCurrencyFieldNames, resolvedTenantCurrency],
+  );
   const initial = useMemo(
     () =>
       mergeSearchParamsIntoInitial(entity.fields, {
         searchParams: nav.searchParams,
         urlPrefillFields: screen.urlPrefillFields,
         renderableFields: layoutFieldNames(screen),
-        defaultCurrency: entity.defaultCurrency ?? "EUR",
+        defaultCurrency: entityDefaultCurrency,
+        ...(moneyCurrencyOverrides !== undefined && { moneyCurrencyOverrides }),
         ...(handoffValues !== undefined && { handoffValues }),
       }) as FormValues,
-    [entity.fields, nav.searchParams, screen, entity.defaultCurrency, handoffValues],
+    [
+      entity.fields,
+      nav.searchParams,
+      screen,
+      entityDefaultCurrency,
+      moneyCurrencyOverrides,
+      handoffValues,
+    ],
   );
   const formSchema = useMemo(() => buildFormSchema(entity, screen), [entity, screen]);
   const writeCommand = entityWriteCommand(schema.featureName, screen.entity, "create");
@@ -827,6 +944,15 @@ function EntityEditCreateBody({
     },
     [nav, screen.redirect, schema, appFeatures, navigateToList, onSaved, returnTarget],
   );
+  // Never seed a tenant-declared money field with entityDefaultCurrency while
+  // its real tenant currency is still in flight (fw#2933) — wait instead.
+  if (needsTenantCurrency && tenantCurrencyResolution.status === "loading") {
+    return (
+      <Banner padded variant="loading" testId="kumiko-screen-loading">
+        Loading…
+      </Banner>
+    );
+  }
   // Deliberately no `actions` prop here: `screen.actions` targets an
   // EXISTING record (publish/archive/duplicate and friends), which the
   // create branch has none of yet — see EntityEditUpdateForm for the
@@ -958,6 +1084,7 @@ function EntityEditUpdateForm({
   readonly onSaved?: () => void;
   readonly onDeleted?: () => void;
 }): ReactNode {
+  const { Banner } = usePrimitives();
   // Seed the form with the server values for the entity's declared
   // fields; anything else (id, tenant_id, created_at…) stays out of
   // the form and lives in the closure. The record's `version` is
@@ -965,15 +1092,56 @@ function EntityEditUpdateForm({
   // concurrent writer bumps it, the server returns a version-conflict
   // error and the user reloads.
   const recordVersion = (record as { version?: number }).version ?? 1;
+  const entityDefaultCurrency = entity.defaultCurrency ?? "EUR";
+  // A money field declaring `currency: { kind: "tenant" }` (fw#2933) resolves
+  // its empty-value currency from the tenant-settings config key instead of
+  // entityDefaultCurrency — `enabled` keeps the query a no-op for entities
+  // without any such field. A record's own stored value (below) always wins
+  // over this, regardless of the declaration.
+  //
+  // Only fields the record itself has no value for need the fetch at all —
+  // an already-set tenant-declared field keeps its own stored currency and
+  // must never block the form on this query.
+  const tenantCurrencyFieldNames = useMemo(
+    () =>
+      tenantCurrencyMoneyFieldNames(entity.fields).filter(
+        (name) => record[name] === null || record[name] === undefined,
+      ),
+    [entity.fields, record],
+  );
+  const needsTenantCurrency = tenantCurrencyFieldNames.length > 0;
+  const tenantCurrencyQuery = useQuery<TenantConfigValuesResponse>(
+    "config:query:values",
+    {},
+    { enabled: needsTenantCurrency },
+  );
+  const tenantCurrencyResolution = resolveTenantCurrency(
+    tenantCurrencyFieldNames,
+    tenantCurrencyQuery,
+    entityDefaultCurrency,
+  );
+  const resolvedTenantCurrency =
+    tenantCurrencyResolution.status === "ready" ? tenantCurrencyResolution.currency : undefined;
+  const moneyCurrencyOverrides = useMemo(
+    () =>
+      resolvedTenantCurrency !== undefined
+        ? Object.fromEntries(tenantCurrencyFieldNames.map((name) => [name, resolvedTenantCurrency]))
+        : undefined,
+    [tenantCurrencyFieldNames, resolvedTenantCurrency],
+  );
   const initial = useMemo(() => {
     const out: Record<string, unknown> = {};
-    const defaultCurrency = entity.defaultCurrency ?? "EUR";
     for (const name of Object.keys(entity.fields)) {
       out[name] =
-        record[name] ?? buildInitialValues({ [name]: entity.fields[name] }, defaultCurrency)[name];
+        record[name] ??
+        buildInitialValues(
+          { [name]: entity.fields[name] },
+          entityDefaultCurrency,
+          moneyCurrencyOverrides,
+        )[name];
     }
     return out as FormValues;
-  }, [entity.fields, entity.defaultCurrency, record]);
+  }, [entity.fields, entityDefaultCurrency, moneyCurrencyOverrides, record]);
 
   const formSchema = useMemo(() => buildFormSchema(entity, screen), [entity, screen]);
 
@@ -1186,6 +1354,18 @@ function EntityEditUpdateForm({
     }
   }, [dispatcher, deleteCommand, entityId, navigateToList, onDeleted, returnTarget, nav]);
 
+  // Never seed a tenant-declared money field with entityDefaultCurrency while
+  // its real tenant currency is still in flight (fw#2933) — wait instead. A
+  // stored (non-empty) value is unaffected — it never reaches this branch's
+  // fallback because `initial` above already prefers `record[name]`.
+  if (needsTenantCurrency && tenantCurrencyResolution.status === "loading") {
+    return (
+      <Banner padded variant="loading" testId="kumiko-screen-loading">
+        Loading…
+      </Banner>
+    );
+  }
+
   return (
     <>
       <RenderEdit

package/src/components/__tests__/render-edit-screen-description.test.tsx

@@ -35,6 +35,7 @@ function buildEntity(): EntityDefinition {
 function renderEditCapturingForm(
   screen: EntityEditScreenDefinition,
   extraTranslations?: TranslationsByLocale,
+  hideSectionTitles = false,
 ): {
   captured: FormProps | undefined;
 } {
@@ -78,6 +79,7 @@ function renderEditCapturingForm(
           entity={buildEntity()}
           featureName="widgets"
           initial={{ name: "" }}
+          {...(hideSectionTitles && { hideSectionTitles: true })}
         />
       </PrimitivesProvider>
     </LocaleProvider>,
@@ -129,4 +131,22 @@ describe("RenderEdit — screen.description as form subtitle (fw#2723)", () => {
     expect(captured).toBeDefined();
     expect(captured && "subtitle" in captured).toBe(false);
   });
+
+  test("tabs mode suppresses a description whose key matches the subtitle probe", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "widget-edit",
+      type: "entityEdit",
+      entity: "widget",
+      description: "screen:widget-edit.subtitle",
+      layout: { mode: "tabs", sections: [{ title: "Basics", fields: ["name"] }] },
+    };
+
+    const { captured } = renderEditCapturingForm(
+      screen,
+      { "en-US": { "screen:widget-edit.subtitle": "Widget details." } },
+      true,
+    );
+
+    expect(captured && "subtitle" in captured).toBe(false);
+  });
 });

package/src/components/render-edit.tsx

@@ -208,7 +208,7 @@ function EditSlotMount({
   wizardStep,
 }: {
   readonly slot: PlatformComponent;
-  readonly slotName: "header" | "footer";
+  readonly slotName: "header" | "titleAction" | "footer";
   readonly screenId: string;
   readonly entityName: string;
   readonly entityId: string | null;
@@ -1088,6 +1088,18 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     ) : (
       headerRegion
     );
+  const titleActionSlot = screen.slots?.titleAction;
+  const titleActionMount =
+    titleActionSlot !== undefined ? (
+      <EditSlotMount
+        slot={titleActionSlot}
+        slotName="titleAction"
+        screenId={screen.id}
+        entityName={vm.entityName}
+        entityId={resolveExtensionEntityId(entityIdProp, vm.id)}
+        values={snapshot.values}
+      />
+    ) : undefined;
   const footerSlot = screen.slots?.footer;
   // Mirrors every branch inside formActions below — without this guard
   // DefaultForm renders an empty footer strip (border + padding, no content)
@@ -1181,10 +1193,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // screen.description is head-card copy, not tab content — in tabs mode
   // (hideSectionTitles) the head card already carries title/subtitle/status.
   const formSubtitle =
-    resolveScreenText("subtitle") ??
-    (hideSectionTitles !== true && screen.description !== undefined
-      ? translate(screen.description)
-      : undefined);
+    hideSectionTitles !== true
+      ? (resolveScreenText("subtitle") ??
+        (screen.description !== undefined ? translate(screen.description) : undefined))
+      : undefined;
 
   return (
     <ExtensionFormRegistryProvider value={extensionFormRegistry}>
@@ -1199,6 +1211,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
         stickyActions={isWizard}
         {...(screen.layout.width !== undefined && { width: screen.layout.width })}
         {...(formHeaderRegion !== undefined && { headerRegion: formHeaderRegion })}
+        {...(titleActionMount !== undefined && { titleAction: titleActionMount })}
         {...(fillHeight && { fillHeight })}
         {...(hideSectionTitles === true && { chromeless: true })}
       >

package/src/primitives.tsx

@@ -811,6 +811,10 @@ export type FormProps = {
    *  instead of rendering as unpadded siblings before it. Native impls may
    *  ignore this prop. */
   readonly headerRegion?: ReactNode;
+  /** Compact content on the right of the form title, same row — status
+   *  chips or allowance badges that belong to the screen, not to a field.
+   *  Native impls may ignore this prop. */
+  readonly titleAction?: ReactNode;
   /** Sizes the form to fill its container's height (instead of the page's
    *  natural content height) so a single scrolling child — a lone
    *  relatedList tab's table — can scroll internally instead of stretching