@cosmicdrift/kumiko-renderer 0.226.0 → 0.228.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.226.0",
+  "version": "0.228.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,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.226.0",
-    "@cosmicdrift/kumiko-headless": "0.226.0",
+    "@cosmicdrift/kumiko-framework": "0.228.0",
+    "@cosmicdrift/kumiko-headless": "0.228.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -25,7 +25,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "jsdom": "^29.1.1",
-    "@cosmicdrift/kumiko-locale-de": "0.226.0"
+    "@cosmicdrift/kumiko-locale-de": "0.228.0"
   },
   "repository": {
     "type": "git",

package/src/app/kumiko-screen.tsx

@@ -178,7 +178,13 @@ export function KumikoScreen({
       );
     case "projectionDetail":
       return (
+        // key on the record identifier alone (never the active tab, see
+        // ProjectionDetailBody's own hideSectionTitles/tab handling) forces
+        // a full remount when navigating from one record to the next —
+        // without it React keeps the RenderEdit form controller alive and
+        // the screen briefly shows the PREVIOUS record's fields (fw#2518).
         <ProjectionDetailBody
+          key={entityId ?? "no-entity"}
           schema={schema}
           screen={screen}
           translate={translate}
@@ -2021,7 +2027,7 @@ function ProjectionDetailBody({
   readonly translate?: Translate;
   readonly entityId?: string;
 }): ReactNode {
-  const { Banner, Text, Heading, Grid, GridCell, Tabs, StatusBadge } = usePrimitives();
+  const { Banner, Text, Heading, Grid, GridCell, Tabs, StatusBadge, Metric } = usePrimitives();
   const t = useTranslation();
   const effectiveTranslate = translate ?? t;
   const nav = useNav();
@@ -2245,52 +2251,64 @@ function ProjectionDetailBody({
       </Banner>
     );
   }
-  return (
+  const hasHeader = screen.header !== undefined;
+  const hasMetrics = screen.metrics !== undefined && screen.metrics.length > 0;
+  const hasTabs = isTabsMode && Tabs !== undefined && activeSection !== undefined;
+  // Rendered as RenderEdit's headerRegion (not as JSX siblings before it) so
+  // this shares the same page padding/width as the record's edit card below
+  // it, instead of sitting flush against the screen edge (fw record-screen
+  // header polish).
+  const header = screen.header;
+  const headerContent = (
     <>
-      {screen.header !== undefined && (
+      {header !== undefined && (
         <>
           <Heading variant="page" testId="kumiko-screen-projection-detail-title">
-            {String(record[screen.header.title] ?? "")}
+            {String(record[header.title] ?? "")}
           </Heading>
-          {screen.header.subtitle !== undefined && (
-            <Text variant="muted" testId="kumiko-screen-projection-detail-subtitle">
-              {String(record[screen.header.subtitle] ?? "")}
-            </Text>
+          {(header.subtitle !== undefined || header.status !== undefined) && (
+            <Grid columns="auto">
+              {header.subtitle !== undefined && (
+                <Text variant="muted" testId="kumiko-screen-projection-detail-subtitle">
+                  {String(record[header.subtitle] ?? "")}
+                </Text>
+              )}
+              {header.status !== undefined &&
+                (StatusBadge !== undefined ? (
+                  <StatusBadge
+                    value={String(record[header.status] ?? "")}
+                    testId="kumiko-screen-projection-detail-status"
+                  />
+                ) : (
+                  <Text testId="kumiko-screen-projection-detail-status">
+                    {String(record[header.status] ?? "")}
+                  </Text>
+                ))}
+            </Grid>
           )}
-          {screen.header.status !== undefined &&
-            (StatusBadge !== undefined ? (
-              <StatusBadge
-                value={String(record[screen.header.status] ?? "")}
-                testId="kumiko-screen-projection-detail-status"
-              />
-            ) : (
-              <Text testId="kumiko-screen-projection-detail-status">
-                {String(record[screen.header.status] ?? "")}
-              </Text>
-            ))}
         </>
       )}
-      {screen.metrics !== undefined && screen.metrics.length > 0 && (
-        <Grid columns={screen.metrics.length} testId="kumiko-screen-projection-detail-metrics">
-          {screen.metrics.map((metric) => {
+      {hasMetrics && (
+        <Grid columns="auto" testId="kumiko-screen-projection-detail-metrics">
+          {screen.metrics?.map((metric) => {
             const labelKey = screen.fieldLabels?.[metric];
-            return (
+            const label = labelKey !== undefined ? effectiveTranslate(labelKey) : metric;
+            const value = String(record[metric] ?? "");
+            const testId = `kumiko-screen-projection-detail-metric-${metric}`;
+            return Metric !== undefined ? (
+              <Metric key={metric} label={label} value={value} testId={testId} />
+            ) : (
               <GridCell key={metric}>
-                <Text
-                  variant="small"
-                  testId={`kumiko-screen-projection-detail-metric-${metric}-label`}
-                >
-                  {labelKey !== undefined ? effectiveTranslate(labelKey) : metric}
-                </Text>
-                <Text testId={`kumiko-screen-projection-detail-metric-${metric}-value`}>
-                  {String(record[metric] ?? "")}
+                <Text variant="small" testId={`${testId}-label`}>
+                  {label}
                 </Text>
+                <Text testId={`${testId}-value`}>{value}</Text>
               </GridCell>
             );
           })}
         </Grid>
       )}
-      {isTabsMode && Tabs !== undefined && activeSection !== undefined && (
+      {hasTabs && activeSection !== undefined && (
         <Tabs
           testId="kumiko-screen-projection-detail-tabs"
           items={screen.layout.sections.map((section) => ({
@@ -2301,20 +2319,23 @@ function ProjectionDetailBody({
           onSelect={(id) => nav.setSearchParams({ tab: id })}
         />
       )}
-      <RenderEdit
-        screen={detailScreen}
-        entity={entity}
-        featureName={schema.featureName}
-        initial={record as FormValues}
-        entityId={entityId}
-        customSubmit={async () => ({ isSuccess: true, validationBlocked: false, data: undefined })}
-        {...(headerActions !== undefined && { actions: headerActions })}
-        {...(translate !== undefined && { translate })}
-        {...(isTabsMode && { hideSectionTitles: true })}
-        valueDisplay={screen.valueDisplay ?? "text"}
-      />
     </>
   );
+  return (
+    <RenderEdit
+      screen={detailScreen}
+      entity={entity}
+      featureName={schema.featureName}
+      initial={record as FormValues}
+      entityId={entityId}
+      customSubmit={async () => ({ isSuccess: true, validationBlocked: false, data: undefined })}
+      {...(headerActions !== undefined && { actions: headerActions })}
+      {...(translate !== undefined && { translate })}
+      {...(isTabsMode && { hideSectionTitles: true })}
+      {...((hasHeader || hasMetrics || hasTabs) && { headerRegion: headerContent })}
+      valueDisplay={screen.valueDisplay ?? "text"}
+    />
+  );
 }
 // ---- actionForm (Tier 2.7d) ----
 

package/src/components/render-edit-types.ts

@@ -133,10 +133,20 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
    *  readOnly fields. */
   readonly valueDisplay?: "form" | "text";
   /** Suppresses every section's own title (fields-section header, relatedList
-   *  Section title) — for a host that already renders the section label
-   *  itself elsewhere (e.g. a tab strip whose label duplicates it).
-   *  Omitting this prop keeps unchanged behavior. */
+   *  Section title) AND the form's own top-level title/subtitle — for a host
+   *  that already renders that label itself elsewhere (e.g. a tab strip
+   *  whose label duplicates it, or a page-level header above RenderEdit).
+   *  Without this, the form's title (`screen:<id>.title` / `screen.id`)
+   *  renders unconditionally regardless of section-level suppression — a
+   *  host relying on this prop to fully own the heading otherwise sees a
+   *  redundant title above its content. Omitting this prop keeps unchanged
+   *  behavior. */
   readonly hideSectionTitles?: boolean;
+  /** Extra content rendered above the card, sharing its left padding and
+   *  width — for a host with its own header region (title/metrics/tabs)
+   *  that would otherwise render as unpadded siblings before RenderEdit.
+   *  Omitting this prop keeps unchanged behavior. */
+  readonly headerRegion?: ReactNode;
 };
 
 export type RenderEditAction = {

package/src/components/render-edit.tsx

@@ -141,7 +141,7 @@ function deriveFormFields<TValues extends FormValues, TCtx>(
 // hooks would punish reordering sections between renders).
 function ExtensionSectionMount({
   section,
-  entityName,
+  entityName: hostEntityName,
   entityId,
   initialValues,
   values,
@@ -179,7 +179,7 @@ function ExtensionSectionMount({
   return (
     <Section title={section.title} testId={`section-extension-${section.title}`}>
       <Component
-        entityName={entityName}
+        entityName={section.entityName ?? hostEntityName}
         entityId={entityId}
         initialValues={initialValues}
         values={values}
@@ -222,6 +222,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     hideActions,
     valueDisplay = "form",
     hideSectionTitles,
+    headerRegion,
   } = props;
   const { customSubmit } = props;
   // Translate-Fallback: wenn der Caller keine Translate-Fn übergibt,
@@ -1017,12 +1018,14 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     <ExtensionFormRegistryProvider value={extensionFormRegistry}>
       <Form
         onSubmit={() => void handleSubmit()}
-        title={formTitle}
-        {...(formSubtitle !== undefined && { subtitle: formSubtitle })}
+        {...(hideSectionTitles !== true && { title: formTitle })}
+        {...(hideSectionTitles !== true &&
+          formSubtitle !== undefined && { subtitle: formSubtitle })}
         {...(hideActions !== true && { actions: formActions })}
         testId="render-edit-form"
         stickyActions={isWizard}
         {...(screen.layout.width !== undefined && { width: screen.layout.width })}
+        {...(headerRegion !== undefined && { headerRegion })}
       >
         {draftCandidates !== null && (
           <Banner

package/src/index.ts

@@ -192,6 +192,7 @@ export type {
   InputProps,
   LightboxProps,
   LinkProps,
+  MetricProps,
   ModalProps,
   PrimitivesProviderProps,
   PrimitivesRegistry,

package/src/primitives.tsx

@@ -707,6 +707,12 @@ export type FormProps = {
    *  unaffected. Native impls may ignore this prop (already bottom-bar by
    *  convention there). */
   readonly stickyActions?: boolean;
+  /** Extra content rendered above the card, inside the same page padding
+   *  the card itself sits in — for a host that needs its own header region
+   *  (title/metrics/tabs) to share the form's left padding and width
+   *  instead of rendering as unpadded siblings before it. Native impls may
+   *  ignore this prop. */
+  readonly headerRegion?: ReactNode;
 };
 
 /** Titled Gruppe von Feldern. Web: `<fieldset>` + `<legend>`, Native:
@@ -734,13 +740,20 @@ export type SectionProps = {
 
 /** Columns-basiertes Layout. Web: CSS grid, Native: Flex-Wrap mit
  *  Width-%, oder react-native-grid. Jedes direkte Child kann eine
- *  `GridCell`-Wrapping bekommen für span-Kontrolle. */
+ *  `GridCell`-Wrapping bekommen für span-Kontrolle.
+ *
+ *  `columns: "auto"` opts out of the N-column stretch layout entirely —
+ *  children keep their own content width and wrap onto new lines (e.g. a
+ *  metrics band of self-sized tiles, or an inline label+badge row) instead
+ *  of being stretched into equal-width tracks. `GridCell` span-wrapping is
+ *  meaningless in this mode and should be skipped. */
 export type GridProps = {
-  readonly columns: number;
+  readonly columns: number | "auto";
   readonly children: ReactNode;
   readonly testId?: string;
   /** Rows visible before the grid becomes vertically scrollable. Omitted =
-   *  the grid grows with its content and never scrolls. */
+   *  the grid grows with its content and never scrolls. Ignored when
+   *  `columns` is "auto". */
   readonly maxRows?: number;
 };
 
@@ -964,6 +977,15 @@ export type StatusBadgeProps = {
   readonly testId?: string;
 };
 
+/** Compact label/value tile (record-detail metrics band). `testId` is the
+ *  tile's own id — the impl derives `${testId}-label`/`${testId}-value` for
+ *  the two rendered nodes, so a caller only ever needs to know the base id. */
+export type MetricProps = {
+  readonly label: string;
+  readonly value: string;
+  readonly testId?: string;
+};
+
 // ---- Core-Registry (Kumiko-eigene Primitives) ----
 
 export type CorePrimitives = {
@@ -1013,6 +1035,10 @@ export type CorePrimitives = {
    *  CorePrimitives mocks in tests keep compiling — additive rollout of
    *  a new primitive shouldn't force every test double to grow a stub. */
   readonly StatusBadge?: ComponentType<StatusBadgeProps>;
+  /** Optional (unlike the other Core-Primitives) so existing partial
+   *  CorePrimitives mocks in tests keep compiling — additive rollout of
+   *  a new primitive shouldn't force every test double to grow a stub. */
+  readonly Metric?: ComponentType<MetricProps>;
 };
 
 /** Offene Extension-Zone für App-eigene Primitives. Devs erweitern