@cosmicdrift/kumiko-renderer 0.170.0 → 0.171.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.170.0",
+  "version": "0.171.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.170.0",
-    "@cosmicdrift/kumiko-headless": "0.170.0",
+    "@cosmicdrift/kumiko-framework": "0.171.0",
+    "@cosmicdrift/kumiko-headless": "0.171.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2"
   },

package/src/__tests__/merge-search-params-into-initial.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import { mergeSearchParamsIntoInitial } from "../app/kumiko-screen";
+
+type FieldDef = { type?: string; default?: unknown; sensitive?: boolean };
+
+describe("mergeSearchParamsIntoInitial", () => {
+  test("raw string param merges in as-is for a text field", () => {
+    const fields: Record<string, FieldDef> = { name: { type: "text" } };
+    const result = mergeSearchParamsIntoInitial(fields, { name: "Alice" });
+    expect(result["name"]).toBe("Alice");
+  });
+
+  test("number-type field coerces a numeric string", () => {
+    const fields: Record<string, FieldDef> = { age: { type: "number" } };
+    const result = mergeSearchParamsIntoInitial(fields, { age: "42" });
+    expect(result["age"]).toBe(42);
+  });
+
+  test("invalid number string falls back to field default", () => {
+    const fields: Record<string, FieldDef> = { count: { type: "number", default: 7 } };
+    const result = mergeSearchParamsIntoInitial(fields, { count: "not-a-number" });
+    expect(result["count"]).toBe(7);
+  });
+
+  test("boolean field coerces 'true' and 'false'", () => {
+    const fields: Record<string, FieldDef> = { active: { type: "boolean" } };
+    expect(mergeSearchParamsIntoInitial(fields, { active: "true" })["active"]).toBe(true);
+    expect(mergeSearchParamsIntoInitial(fields, { active: "false" })["active"]).toBe(false);
+  });
+
+  test("sensitive field is skipped even when a matching searchParam exists", () => {
+    const fields: Record<string, FieldDef> = { password: { type: "text", sensitive: true } };
+    const result = mergeSearchParamsIntoInitial(fields, { password: "secret" });
+    expect(result["password"]).toBe("");
+  });
+
+  test("field with no matching searchParam keeps its buildInitialValues default", () => {
+    const fields: Record<string, FieldDef> = { total: { type: "number", default: 100 } };
+    const result = mergeSearchParamsIntoInitial(fields, {});
+    expect(result["total"]).toBe(100);
+  });
+
+  test("money-type field coerces a numeric string", () => {
+    const fields: Record<string, FieldDef> = { price: { type: "money" } };
+    const result = mergeSearchParamsIntoInitial(fields, { price: "19.99" });
+    expect(result["price"]).toBe(19.99);
+  });
+});

package/src/app/__tests__/entity-edit-create-search-params.test.tsx

@@ -0,0 +1,142 @@
+// Issue #1680: navigate params on entityEdit-create were documented as
+// "will be read" but EntityEditCreateBody never consulted nav.searchParams —
+// only buildInitialValues(entity.fields). A rowAction navigate with params
+// to an entityEdit target therefore opened an empty form with no boot error.
+// This test renders the real create path (KumikoScreen → EntityEditScreen →
+// EntityEditCreateBody → RenderEdit → RenderField) under a NavProvider with
+// searchParams set and asserts the input is prefilled — not just the helper
+// in isolation.
+import { describe, expect, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { render } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { type CorePrimitives, type InputProps, PrimitivesProvider } from "../../primitives";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import { NavProvider } from "../nav";
+
+const captured: Record<string, InputProps> = {};
+const captureInput: ComponentType<InputProps> = (props) => {
+  captured[props.name] = props;
+  return null;
+};
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: passChildren,
+  Field: passChildren,
+  Input: captureInput,
+  DataTable: noop,
+  Form: passChildren,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: passChildren,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+function stubDispatcher(): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function buildSchema(): FeatureSchema {
+  const entity: EntityDefinition = {
+    fields: {
+      name: { type: "text", maxLength: 200, required: false, searchable: false, sortable: false },
+      floorCount: { type: "number", required: false, sortable: false },
+    },
+  };
+  const screen: EntityEditScreenDefinition = {
+    id: "unit-edit",
+    type: "entityEdit",
+    entity: "unit",
+    layout: { sections: [{ columns: 1, fields: ["name", "floorCount"] }] },
+  };
+  return {
+    featureName: "housing",
+    entities: { unit: entity },
+    screens: [screen],
+  } as FeatureSchema;
+}
+
+describe("EntityEditCreateBody — navigate-params als initial values (#1680)", () => {
+  test("URL-searchParams aus rowAction navigate füllen das Create-Form vor", () => {
+    captured["name"] = undefined as unknown as InputProps;
+    captured["floorCount"] = undefined as unknown as InputProps;
+    render(
+      <LocaleProvider resolver={createStaticLocaleResolver({ locale: "de-DE" })}>
+        <DispatcherProvider dispatcher={stubDispatcher()}>
+          <NavProvider
+            value={{
+              route: { screenId: "housing:unit-edit" },
+              navigate: () => {},
+              replace: () => {},
+              hrefFor: () => "",
+              searchParams: { name: "Erdgeschoss", floorCount: "3" },
+              setSearchParams: () => {},
+            }}
+          >
+            <PrimitivesProvider value={testPrimitives}>
+              <KumikoScreen schema={buildSchema()} qn="housing:screen:unit-edit" />
+            </PrimitivesProvider>
+          </NavProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    expect(captured["name"]?.value).toBe("Erdgeschoss");
+    expect(captured["floorCount"]?.value).toBe(3);
+  });
+
+  test("ohne matching searchParam bleibt der Field-Default (leer)", () => {
+    captured["name"] = undefined as unknown as InputProps;
+    render(
+      <LocaleProvider resolver={createStaticLocaleResolver({ locale: "de-DE" })}>
+        <DispatcherProvider dispatcher={stubDispatcher()}>
+          <NavProvider
+            value={{
+              route: { screenId: "housing:unit-edit" },
+              navigate: () => {},
+              replace: () => {},
+              hrefFor: () => "",
+              searchParams: {},
+              setSearchParams: () => {},
+            }}
+          >
+            <PrimitivesProvider value={testPrimitives}>
+              <KumikoScreen schema={buildSchema()} qn="housing:screen:unit-edit" />
+            </PrimitivesProvider>
+          </NavProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    expect(captured["name"]?.value).toBe("");
+  });
+});

package/src/app/app-features-context.tsx

@@ -0,0 +1,25 @@
+// Cross-feature schema access for components that need to resolve a
+// screen owned by a DIFFERENT feature than the one they're rendering
+// under — e.g. a reference field opening the target entity's create
+// screen (kumiko-framework#1681). `createKumikoApp` provides the full
+// `app.features` list; components elsewhere in the render tree default
+// to an empty list (no cross-feature schema known, e.g. outside
+// createKumikoApp or in isolated tests).
+
+import { createContext, type ReactNode, useContext } from "react";
+import type { FeatureSchema } from "./feature-schema";
+
+const AppFeaturesContext = createContext<readonly FeatureSchema[]>([]);
+
+export type AppFeaturesProviderProps = {
+  readonly features: readonly FeatureSchema[];
+  readonly children: ReactNode;
+};
+
+export function AppFeaturesProvider({ features, children }: AppFeaturesProviderProps): ReactNode {
+  return <AppFeaturesContext.Provider value={features}>{children}</AppFeaturesContext.Provider>;
+}
+
+export function useAppFeatures(): readonly FeatureSchema[] {
+  return useContext(AppFeaturesContext);
+}

package/src/app/kumiko-screen.tsx

@@ -320,7 +320,7 @@ function useNavigateToCreateFor(
 // with a `default: true`/`default: 5` would show the form in a state
 // the entity didn't ask for — subtle and easy to miss until a user
 // submits and is surprised.
-function buildInitialValues(
+export function buildInitialValues(
   fields: Readonly<Record<string, unknown>>,
 ): Readonly<Record<string, unknown>> {
   const out: Record<string, unknown> = {};
@@ -336,6 +336,29 @@ function buildInitialValues(
   return out;
 }
 
+export function mergeSearchParamsIntoInitial(
+  fields: Readonly<Record<string, unknown>>,
+  searchParams: Readonly<Record<string, string>>,
+): Record<string, unknown> {
+  const defaults = buildInitialValues(fields) as Record<string, unknown>;
+  const merged: Record<string, unknown> = { ...defaults };
+  for (const [name, fieldDef] of Object.entries(fields)) {
+    const shape = fieldDef as { type?: string; sensitive?: boolean };
+    if (shape.sensitive === true) continue;
+    const raw = searchParams[name];
+    if (raw === undefined) continue;
+    if (shape.type === "number" || shape.type === "money") {
+      const parsed = Number(raw);
+      merged[name] = Number.isNaN(parsed) ? defaults[name] : parsed;
+    } else if (shape.type === "boolean") {
+      merged[name] = raw === "true";
+    } else {
+      merged[name] = raw;
+    }
+  }
+  return merged;
+}
+
 function EntityEditScreen({
   schema,
   screen,
@@ -406,7 +429,11 @@ function EntityEditCreateBody({
   readonly entity: EntityDefinition;
   readonly translate?: Translate;
 }): ReactNode {
-  const initial = useMemo(() => buildInitialValues(entity.fields) as FormValues, [entity.fields]);
+  const nav = useNav();
+  const initial = useMemo(
+    () => mergeSearchParamsIntoInitial(entity.fields, nav.searchParams) as FormValues,
+    [entity.fields, nav.searchParams],
+  );
   const writeCommand = entityWriteCommand(schema.featureName, screen.entity, "create");
   const navigateToList = useNavigateToListAfter(schema, screen.entity);
   const handleSubmitted = useCallback(
@@ -1402,32 +1429,10 @@ function ActionFormBody({
   const nav = useNav();
   const synthEntity = useMemo(() => synthesizeActionFormEntity(screen.fields), [screen.fields]);
   const synthScreen = useMemo(() => synthesizeActionFormScreen(screen), [screen]);
-  // Tier 2.7e-2: URL-Search-Params überschreiben Field-Defaults bei
-  // initial values. Use-case: rowAction kind=navigate setzt
-  // `?customerId=row-uuid` und der actionForm liest das pre-filled.
-  // String-Coercion auf Field-Type: URL kennt nur Strings, aber
-  // ein Field mit type:"number" erwartet eine Zahl. Boolean-Strings
-  // ("true"/"false") und Number-Strings werden hier coerced; sonst
-  // bleibt der String — der Field-Validator beim Submit fängt einen
-  // Type-Mismatch ab.
-  const initial = useMemo(() => {
-    const defaults = buildInitialValues(screen.fields) as Record<string, unknown>; // @cast-boundary render-helper
-    const merged: Record<string, unknown> = { ...defaults };
-    for (const [name, fieldDef] of Object.entries(screen.fields)) {
-      const raw = nav.searchParams[name];
-      if (raw === undefined) continue;
-      const ftype = (fieldDef as { type?: string }).type;
-      if (ftype === "number" || ftype === "money") {
-        const parsed = Number(raw);
-        merged[name] = Number.isNaN(parsed) ? defaults[name] : parsed;
-      } else if (ftype === "boolean") {
-        merged[name] = raw === "true";
-      } else {
-        merged[name] = raw;
-      }
-    }
-    return merged as FormValues;
-  }, [screen.fields, nav.searchParams]);
+  const initial = useMemo(
+    () => mergeSearchParamsIntoInitial(screen.fields, nav.searchParams) as FormValues,
+    [screen.fields, nav.searchParams],
+  );
   const handleSubmitted = useCallback(
     (result: SubmitResult<unknown>) => {
       // Redirect ist optional. Bei isSuccess + redirect → nav.navigate.

package/src/app/projection-detail-shim.ts

@@ -62,7 +62,7 @@ export function synthesizeProjectionDetailScreen(
     id: screen.id,
     type: "entityEdit",
     entity: PROJECTION_DETAIL_PSEUDO_ENTITY,
-    layout: { sections },
+    layout: { sections, ...(screen.layout.width !== undefined && { width: screen.layout.width }) },
     allowCreate: false,
     allowDelete: false,
     ...(screen.fieldLabels !== undefined && { fieldLabels: screen.fieldLabels }),

package/src/components/__tests__/render-edit-logic.test.ts

@@ -122,4 +122,58 @@ describe("hasEditableSection", () => {
     };
     expect(hasEditableSection([hiddenSectionWithEditableField])).toBe(false);
   });
+
+  test("visible section with only a field-hidden editable field → false", () => {
+    const section: EditSectionViewModel = {
+      kind: "fields",
+      columns: 1,
+      visible: true,
+      fields: [
+        {
+          field: "f",
+          label: "F",
+          type: "text",
+          value: "",
+          visible: false,
+          readOnly: false,
+          required: false,
+        },
+      ],
+    };
+    expect(hasEditableSection([section])).toBe(false);
+  });
+
+  // The #1689 regression: the section is visible because field A is visible
+  // (readOnly), but the only editable field B is hidden by its own
+  // FieldCondition. Old code checked section.visible + !readOnly only, so it
+  // saw B's !readOnly and returned true — Save appeared over zero editable
+  // visible fields.
+  test("visible section, visible readOnly field + hidden editable field → false", () => {
+    const section: EditSectionViewModel = {
+      kind: "fields",
+      columns: 1,
+      visible: true,
+      fields: [
+        {
+          field: "a",
+          label: "A",
+          type: "text",
+          value: "",
+          visible: true,
+          readOnly: true,
+          required: false,
+        },
+        {
+          field: "b",
+          label: "B",
+          type: "text",
+          value: "",
+          visible: false,
+          readOnly: false,
+          required: false,
+        },
+      ],
+    };
+    expect(hasEditableSection([section])).toBe(false);
+  });
 });

package/src/components/__tests__/render-field-app-locale.test.tsx

@@ -37,6 +37,7 @@ const testPrimitives: CorePrimitives = {
   Text: noop,
   Heading: noop,
   Dialog: noop,
+  Modal: noop,
   Lightbox: noop,
   ConfigSourceBadge: noop,
   ConfigCascadeView: noop,

package/src/components/reference-create-dialog.tsx

@@ -0,0 +1,80 @@
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { FormValues, SubmitResult, Translate } from "@cosmicdrift/kumiko-headless";
+import { type ReactNode, useMemo } from "react";
+import { buildInitialValues } from "../app/kumiko-screen";
+import { toKebab } from "../app/qn";
+import { useTranslation } from "../i18n";
+import { usePrimitives } from "../primitives";
+import { RenderEdit } from "./render-edit";
+
+// Hosts a target entity's create-form inside a bare Modal so a reference
+// field can create a missing record without leaving the current form
+// (kumiko-framework#1681) — same create wiring as EntityEditCreateBody
+// (kumiko-screen.tsx), but reports the new id back via a callback instead
+// of navigating to the entity's list screen.
+
+function entityWriteCommand(featureName: string, entity: string): string {
+  return `${toKebab(featureName)}:write:${toKebab(entity)}:create`;
+}
+
+// The create handler's success payload is `{ kind: "save", id, ... }`
+// (see event-store-executor-write.ts) but RenderEdit's onSubmit only
+// types it as `unknown` — narrow defensively instead of casting through it.
+function extractCreatedId(data: unknown): string | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const id = (data as Record<string, unknown>)["id"];
+  return typeof id === "string" ? id : undefined;
+}
+
+export type ReferenceCreateDialogProps = {
+  readonly open: boolean;
+  readonly onClose: () => void;
+  readonly onCreated: (id: string) => void;
+  readonly featureName: string;
+  readonly screen: EntityEditScreenDefinition;
+  readonly entity: EntityDefinition;
+  readonly translate?: Translate;
+};
+
+export function ReferenceCreateDialog({
+  open,
+  onClose,
+  onCreated,
+  featureName,
+  screen,
+  entity,
+  translate,
+}: ReferenceCreateDialogProps): ReactNode {
+  const { Modal } = usePrimitives();
+  const t = useTranslation();
+  const initial = useMemo(() => buildInitialValues(entity.fields) as FormValues, [entity.fields]);
+  const writeCommand = entityWriteCommand(featureName, screen.entity);
+  const handleSubmitted = (result: SubmitResult<unknown>): void => {
+    if (result.validationBlocked || !result.isSuccess) return;
+    const id = extractCreatedId(result.data);
+    if (id !== undefined) onCreated(id);
+  };
+  if (!open) return null;
+  return (
+    <Modal
+      open={open}
+      onOpenChange={(next) => !next && onClose()}
+      title={t("kumiko.actions.create")}
+    >
+      <RenderEdit
+        screen={screen}
+        entity={entity}
+        featureName={featureName}
+        initial={initial}
+        writeCommand={writeCommand}
+        onSubmit={handleSubmitted}
+        onCancel={onClose}
+        {...(screen.submitLabel !== undefined && { submitLabel: screen.submitLabel })}
+        {...(translate !== undefined && { translate })}
+      />
+    </Modal>
+  );
+}

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

@@ -9,7 +9,7 @@ export function hasEditableSection(sections: readonly EditSectionViewModel[]): b
   return sections.some(
     (s) =>
       s.kind === "extension" ||
-      (s.kind === "fields" && s.visible && s.fields.some((f) => !f.readOnly)),
+      (s.kind === "fields" && s.visible && s.fields.some((f) => !f.readOnly && f.visible)),
   );
 }
 

package/src/components/render-edit.tsx

@@ -422,6 +422,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
         {...(formSubtitle !== undefined && { subtitle: formSubtitle })}
         actions={formActions}
         testId="render-edit-form"
+        {...(screen.layout.width !== undefined && { width: screen.layout.width })}
       >
         {vm.sections.map((section: EditSectionViewModel, sectionIndex: number) => {
           if (section.kind === "extension") {
@@ -446,6 +447,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
             <Section
               key={sectionKey}
               {...(sectionTitle !== undefined && { title: sectionTitle })}
+              {...(section.description !== undefined && { subtitle: section.description })}
               testId={`section-${sectionKey}`}
             >
               <Grid columns={section.columns}>

package/src/components/render-field.tsx

@@ -1,10 +1,17 @@
+import type {
+  AccessRule,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
 import type { EditFieldViewModel, FieldIssue } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useCallback, useMemo, useState } from "react";
+import { useAppFeatures } from "../app/app-features-context";
 import { toKebab } from "../app/qn";
+import { useUserRoles } from "../context/user-roles-context";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits";
 import { useQuery } from "../hooks/use-query";
-import { useLocale } from "../i18n";
+import { useLocale, useTranslation } from "../i18n";
 import { usePrimitives } from "../primitives";
+import { ReferenceCreateDialog } from "./reference-create-dialog";
 
 // RenderField übersetzt ein EditFieldViewModel → Primitives-Baum.
 // Kein raw HTML mehr; alle Darstellungsentscheidungen (Label-Position,
@@ -82,6 +89,19 @@ export function RenderField({
   );
 }
 
+// Duplicated from kumiko-screen.tsx's screenAccessAllows (not imported —
+// that module imports RenderEdit → RenderField, importing back from here
+// would cycle). Same minimal role-gate logic.
+function createScreenAccessAllows(
+  access: AccessRule | undefined,
+  userRoles: readonly string[] | undefined,
+): boolean {
+  if (!access) return true;
+  if ("openToAll" in access) return access.openToAll;
+  if (userRoles === undefined) return false;
+  return access.roles.some((role) => userRoles.includes(role));
+}
+
 // Tier 2.7e-3 + 2.1c: Reference-Input rendert eine Searchable Combobox
 // gefüllt aus einer Live-Query auf die referenced Entity. Default-
 // Limit: 200 — bei größeren Datasets fehlt der Tail im Dropdown
@@ -120,6 +140,26 @@ function ReferenceInput({
   // (z.B. items.assignee → users:query:user:list). Default ist
   // same-feature, kommt aus dem ViewModel (parseRefTarget).
   const queryQn = `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
+  // Issue #1681: "+ Neu" in der Combobox öffnet den Create-Screen der
+  // referenced entity als Dialog, statt die aktuelle Form zu verlassen.
+  // refFeature kann ein anderes Feature als das aktuell gerenderte sein
+  // — appFeatures (createKumikoApp) kennt alle Feature-Schemas, nicht
+  // nur das der aktiven Screen. Kein Match (Feature/Screen/Entity nicht
+  // registriert, oder allowCreate:false) → onCreate bleibt undefined,
+  // Combobox rendert dann ohne den Footer.
+  const appFeatures = useAppFeatures();
+  const userRoles = useUserRoles();
+  const t = useTranslation();
+  const [createOpen, setCreateOpen] = useState(false);
+  const refTargetSchema = appFeatures.find((f) => f.featureName === refFeature);
+  const refCreateScreen = refTargetSchema?.screens.find(
+    (s): s is EntityEditScreenDefinition =>
+      s.type === "entityEdit" &&
+      s.entity === refEntity &&
+      s.allowCreate !== false &&
+      createScreenAccessAllows(s.access, userRoles),
+  );
+  const refEntityDef = refTargetSchema?.entities[refEntity];
   // Tier 2.7e Remote-Search: User tippt im Combobox → Server filtert
   // via existing list-payload `search`-Param (Tier 2.6c). Combobox
   // debounced den keystroke selbst (300ms) und ruft onSearchChange.
@@ -137,6 +177,20 @@ function ReferenceInput({
     queryPayload,
   );
   const handleSearchChange = useCallback((q: string) => setSearchTerm(q), []);
+  const canCreate = !field.readOnly && refCreateScreen !== undefined && refEntityDef !== undefined;
+  const handleCreated = useCallback(
+    (newId: string) => {
+      setCreateOpen(false);
+      void queryResult.refetch();
+      if (isMultiple) {
+        const current = Array.isArray(field.value) ? (field.value as readonly string[]) : [];
+        onChange([...current, newId]);
+      } else {
+        onChange(newId);
+      }
+    },
+    [isMultiple, field.value, onChange, queryResult.refetch],
+  );
   const options = useMemo(() => {
     const rows = queryResult.data?.rows ?? [];
     return rows.map((row) => {
@@ -158,29 +212,49 @@ function ReferenceInput({
     options,
     onSearchChange: handleSearchChange,
     loading: queryResult.loading,
+    ...(canCreate && {
+      onCreate: () => setCreateOpen(true),
+      createLabel: t("kumiko.actions.create"),
+    }),
   } as const;
+  const createDialog = canCreate && refCreateScreen && refEntityDef && (
+    <ReferenceCreateDialog
+      open={createOpen}
+      onClose={() => setCreateOpen(false)}
+      onCreated={handleCreated}
+      featureName={refFeature}
+      screen={refCreateScreen}
+      entity={refEntityDef}
+    />
+  );
   if (isMultiple) {
     const arrayValue: readonly string[] = Array.isArray(field.value)
       ? (field.value as readonly string[])
       : [];
     return (
-      <Input
-        kind="combobox"
-        {...baseInputProps}
-        multiple
-        value={arrayValue}
-        onChange={(v) => onChange(v)}
-      />
+      <>
+        <Input
+          kind="combobox"
+          {...baseInputProps}
+          multiple
+          value={arrayValue}
+          onChange={(v) => onChange(v)}
+        />
+        {createDialog}
+      </>
     );
   }
   const stringValue = field.value === undefined || field.value === null ? "" : String(field.value);
   return (
-    <Input
-      kind="combobox"
-      {...baseInputProps}
-      value={stringValue}
-      onChange={(v) => onChange(v === "" ? null : v)}
-    />
+    <>
+      <Input
+        kind="combobox"
+        {...baseInputProps}
+        value={stringValue}
+        onChange={(v) => onChange(v === "" ? null : v)}
+      />
+      {createDialog}
+    </>
   );
 }
 
@@ -223,6 +297,7 @@ function renderInput({
           {...common}
           value={numberValue(field.value)}
           onChange={(v) => onChange(v)}
+          {...(field.icon !== undefined && { icon: field.icon })}
         />
       );
     case "money": {
@@ -344,6 +419,7 @@ function renderInput({
           {...common}
           value={stringValue(field.value)}
           onChange={(v) => onChange(v)}
+          {...(field.icon !== undefined && { icon: field.icon })}
         />
       );
     }

package/src/i18n-defaults.ts

@@ -40,6 +40,7 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.list.empty.title": "Noch keine Einträge.",
     "kumiko.list.empty.hint": "Lege den ersten an, um loszulegen.",
     "kumiko.list.no-entries": "Keine Einträge.",
+    "kumiko.list.end-of-list": "— Ende der Liste —",
 
     // Combobox — Tier 2.1c Searchable-Select.
     "kumiko.combobox.search-placeholder": "Suchen…",
@@ -176,6 +177,7 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.list.empty.title": "No entries yet.",
     "kumiko.list.empty.hint": "Create the first one to get started.",
     "kumiko.list.no-entries": "No entries.",
+    "kumiko.list.end-of-list": "— End of list —",
 
     "kumiko.combobox.search-placeholder": "Search…",
     "kumiko.combobox.empty": "No matches.",

package/src/index.ts

@@ -9,6 +9,8 @@
 // eigenen Bootstrap schreiben will. Normale Samples gehen über
 // @cosmicdrift/kumiko-renderer-web/createKumikoApp, das alle Provider verdrahtet.
 
+export type { AppFeaturesProviderProps } from "./app/app-features-context";
+export { AppFeaturesProvider, useAppFeatures } from "./app/app-features-context";
 export type {
   ColumnRendererComponent,
   ColumnRendererProps,
@@ -132,12 +134,14 @@ export type {
   DialogProps,
   FieldProps,
   FormProps,
+  FormWidth,
   GridCellProps,
   GridProps,
   HeadingProps,
   InputProps,
   LightboxProps,
   LinkProps,
+  ModalProps,
   PrimitivesProviderProps,
   PrimitivesRegistry,
   RuntimeRenderer,

package/src/primitives.tsx

@@ -34,6 +34,7 @@ import type {
   ConfigScope,
   ConfigValueSource,
 } from "@cosmicdrift/kumiko-framework/engine";
+import type { FormWidth } from "@cosmicdrift/kumiko-framework/ui-types";
 import type {
   FieldIssue,
   ListColumnViewModel,
@@ -158,6 +159,9 @@ export type InputProps =
       /** Read-only Input (z.B. gewürfelter Free-Tier-Slug). Nicht `disabled`
        *  — bleibt fokussier-/kopierbar. */
       readonly readOnly?: boolean;
+      /** Symbolic icon key (FIELD_ICONS registry, renderer-web) — renders
+       *  as a prefix on the input. Unknown key → no icon (no boot-fail). */
+      readonly icon?: string;
     }
   | {
       readonly kind: "email";
@@ -199,6 +203,9 @@ export type InputProps =
       readonly required?: boolean;
       readonly hasError?: boolean;
       readonly testId?: string;
+      /** Symbolic icon key (FIELD_ICONS registry, renderer-web) — renders
+       *  as a prefix on the input. Unknown key → no icon (no boot-fail). */
+      readonly icon?: string;
     }
   | {
       readonly kind: "range";
@@ -302,6 +309,11 @@ export type InputProps =
        *  debounced an den Caller). */
       readonly onSearchChange?: (q: string) => void;
       readonly loading?: boolean;
+      /** Fixed "+ createLabel" footer row that fires instead of
+       *  selecting an option — omit for the plain select-existing
+       *  combobox (kumiko-framework#1681). */
+      readonly onCreate?: () => void;
+      readonly createLabel?: string;
     } & (
       | {
           readonly multiple?: false;
@@ -521,6 +533,8 @@ export type DataTableProps = {
   readonly testId?: string;
 };
 
+export type { FormWidth };
+
 /** Submit-Wrapper. Web: `<form onSubmit>`, Native: View das einen
  *  onSubmit-Callback via Button-Press triggert. `onSubmit` bekommt
  *  eine abstrakte Signatur (keine FormEvent) damit Native-Impls das
@@ -542,6 +556,10 @@ export type FormProps = {
   readonly subtitle?: ReactNode;
   readonly actions?: ReactNode;
   readonly testId?: string;
+  /** Max width of the form container. Default "3xl" — see FormWidth
+   *  (`packages/types/src/screen.ts`, EditLayout.width, #1676). Native
+   *  impls may ignore this prop (no width constraint there). */
+  readonly width?: FormWidth;
 };
 
 /** Titled Gruppe von Feldern. Web: `<fieldset>` + `<legend>`, Native:
@@ -635,6 +653,21 @@ export type DialogProps = {
   readonly testId?: string;
 };
 
+/** Bare content shell for hosting an existing self-contained form/widget
+ *  (own submit/cancel buttons) inside a modal overlay — unlike `Dialog`,
+ *  it renders no footer buttons of its own. Web renders the same
+ *  focus-trapped Radix overlay as `Dialog`, just without the button row. */
+export type ModalProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  /** Screen-reader-only accessible title (required by the underlying
+   *  dialog primitive) — not shown visually since the hosted content
+   *  is expected to render its own heading. */
+  readonly title: string;
+  readonly children: ReactNode;
+  readonly testId?: string;
+};
+
 /** Image lightbox — full-size preview on click. Web renders Radix overlay;
  *  trigger (thumbnail) and open state live in the app. */
 export type LightboxProps = {
@@ -725,6 +758,7 @@ export type CorePrimitives = {
   readonly Text: ComponentType<TextProps>;
   readonly Heading: ComponentType<HeadingProps>;
   readonly Dialog: ComponentType<DialogProps>;
+  readonly Modal: ComponentType<ModalProps>;
   readonly Lightbox: ComponentType<LightboxProps>;
   readonly ConfigSourceBadge: ComponentType<ConfigSourceBadgeProps>;
   readonly ConfigCascadeView: ComponentType<ConfigCascadeViewProps>;