@cosmicdrift/kumiko-renderer 0.328.0 → 0.328.1

package/src/app/content-preview.tsx

@@ -1,67 +0,0 @@
-// Read-only render of a content editor's format with the collection's
-// example variableSchema values substituted in for `{{name}}` — reuses the
-// same registered editor the collection edits with (readOnly), so "rich"
-// renders formatted HTML and "plain"/"markdown" render as text through the
-// exact same component, no separate render path per format.
-
-import type { ContentEditorFormat } from "@cosmicdrift/kumiko-types/nav";
-import { type ReactNode, useId } from "react";
-import { useContentEditor } from "./content-editors";
-
-const VARIABLE_PATTERN = /\{\{\s*(\w+)\s*\}\}/g;
-
-const noop = (): void => {};
-
-/** A name with no example value (or not in the schema at all) stays as the
- *  literal `{{name}}` placeholder — there is nothing else to show for it. */
-export function substituteVariables(
-  content: string,
-  variables: Readonly<Record<string, string>>,
-): string {
-  return content.replace(VARIABLE_PATTERN, (match, name: string) =>
-    Object.hasOwn(variables, name) ? (variables[name] ?? match) : match,
-  );
-}
-
-function escapeHtml(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&#39;");
-}
-
-export type ContentPreviewProps = {
-  readonly content: string;
-  readonly variables: Readonly<Record<string, string>>;
-  readonly contentFormat?: ContentEditorFormat;
-};
-
-export function ContentPreview({
-  content,
-  variables,
-  contentFormat,
-}: ContentPreviewProps): ReactNode {
-  const Editor = useContentEditor(contentFormat);
-  const id = useId();
-  // "rich" content is HTML (see ContentCollectionDefinition.contentFormat) —
-  // an example value substituted in raw could break the markup (`<`) or
-  // render as an unescaped entity (`&`). "plain"/"markdown" content is text,
-  // no escaping wanted there.
-  const safeVariables =
-    contentFormat === "rich"
-      ? Object.fromEntries(
-          Object.entries(variables).map(([name, value]) => [name, escapeHtml(value)]),
-        )
-      : variables;
-  return (
-    <Editor
-      id={id}
-      value={substituteVariables(content, safeVariables)}
-      onChange={noop}
-      variables={[]}
-      readOnly
-    />
-  );
-}

package/src/app/custom-screens.tsx

@@ -1,29 +0,0 @@
-// Custom-Screen-Components-Map: client-side Lookup für Screens vom Typ
-// `custom`. KumikoScreen schaut hier nach `screen.id` (oder qn) und
-// rendert die passende Component. createKumikoApp im renderer-web sammelt
-// alle clientFeatures.components und mountet den Provider; Tests die
-// einzelne Custom-Screens prüfen wollen, mounten den Provider direkt.
-
-import { type ComponentType, createContext, type ReactNode, useContext } from "react";
-
-export type CustomScreensMap = Readonly<Record<string, ComponentType>>;
-
-const CustomScreensContext = createContext<CustomScreensMap | undefined>(undefined);
-
-export type CustomScreensProviderProps = {
-  readonly children: ReactNode;
-  readonly value: CustomScreensMap;
-};
-
-export function CustomScreensProvider({ children, value }: CustomScreensProviderProps): ReactNode {
-  return <CustomScreensContext.Provider value={value}>{children}</CustomScreensContext.Provider>;
-}
-
-/** Schaut die Component für ein Custom-Screen nach. Returnt undefined
- *  wenn weder Provider gemounted noch screenId in der Map ist — der
- *  Caller (KumikoScreen) zeigt dann seinen Placeholder-Banner. */
-export function useCustomScreenComponent(screenId: string): ComponentType | undefined {
-  const map = useContext(CustomScreensContext);
-  if (map === undefined) return undefined;
-  return map[screenId];
-}

package/src/app/dashboard-body.tsx

@@ -1,33 +0,0 @@
-// Dashboard-Body-Injection: der KumikoScreen-Switch ist plattform-agnostisch,
-// die Dashboard-Panels (StatCard, Charts) sind es nicht — die Implementierung
-// kommt vom Platform-Package (renderer-web registriert seine Web-Variante in
-// createKumikoApp). Gleiches Muster wie CustomScreensProvider.
-
-import type { DashboardScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
-import type { Translate } from "@cosmicdrift/kumiko-headless";
-import { type ComponentType, createContext, type ReactNode, useContext } from "react";
-
-export type DashboardBodyProps = {
-  readonly featureName: string;
-  readonly screen: DashboardScreenDefinition;
-  readonly translate?: Translate;
-};
-
-const DashboardBodyContext = createContext<ComponentType<DashboardBodyProps> | undefined>(
-  undefined,
-);
-
-export type DashboardBodyProviderProps = {
-  readonly children: ReactNode;
-  readonly value: ComponentType<DashboardBodyProps>;
-};
-
-export function DashboardBodyProvider({ children, value }: DashboardBodyProviderProps): ReactNode {
-  return <DashboardBodyContext.Provider value={value}>{children}</DashboardBodyContext.Provider>;
-}
-
-/** Undefined wenn kein Platform-Package einen Dashboard-Body registriert
- *  hat — KumikoScreen zeigt dann seinen Placeholder-Banner. */
-export function useDashboardBody(): ComponentType<DashboardBodyProps> | undefined {
-  return useContext(DashboardBodyContext);
-}

package/src/app/extension-form-submit.tsx

@@ -1,123 +0,0 @@
-// @runtime client
-// Extension-Form-Submit-Registry — erlaubt einer Extension-Section (z.B.
-// Custom-Fields), beim Submit des umgebenden entityEdit-Forms mitzuschreiben,
-// statt einen eigenen Save-Button zu führen ("composed form, ein Save",
-// Bug-Bash 3 #1). Die Section meldet (a) einen Submit-Handler und (b) ihren
-// dirty-State an die Form; die Form aktiviert ihren Save-Button auch wenn nur
-// eine Section dirty ist und ruft nach dem Entity-Write alle Section-Handler
-// mit der entityId.
-//
-// Ohne umgebende Form (Context === null) fällt die Section auf ihren eigenen
-// Save-Button zurück (Standalone-Backward-Compat).
-
-import { createContext, useContext, useEffect, useId, useMemo, useRef } from "react";
-
-export type ExtensionSubmitContext = { readonly entityId: string };
-
-export type ExtensionSubmitResult = {
-  readonly isSuccess: boolean;
-  /** i18n-Key für die Fehlermeldung, die die Form als Banner zeigt. */
-  readonly errorKey?: string;
-};
-
-export type ExtensionFormSubmitHandler = (
-  ctx: ExtensionSubmitContext,
-) => Promise<ExtensionSubmitResult>;
-
-type Registration = {
-  readonly key: string;
-  readonly dirty: boolean;
-  readonly handler: ExtensionFormSubmitHandler;
-};
-
-export type ExtensionFormRegistry = {
-  readonly upsert: (reg: Registration) => void;
-  readonly remove: (key: string) => void;
-};
-
-const ExtensionFormRegistryContext = createContext<ExtensionFormRegistry | null>(null);
-
-export const ExtensionFormRegistryProvider = ExtensionFormRegistryContext.Provider;
-
-// Host-Seite (render-edit): hält die Registrierungen in einem ref, meldet den
-// aggregierten dirty-State via onDirtyChange hoch (damit der Save-Button
-// re-rendert) und liefert runAll() zum Ausführen aller Handler beim Submit.
-export type ExtensionFormHostStatus = {
-  readonly anyDirty: boolean;
-  readonly hasRegistrations: boolean;
-};
-
-export function useExtensionFormHost(onStatusChange: (status: ExtensionFormHostStatus) => void): {
-  readonly registry: ExtensionFormRegistry;
-  readonly runAll: (ctx: ExtensionSubmitContext) => Promise<readonly ExtensionSubmitResult[]>;
-} {
-  const regsRef = useRef<Map<string, Registration>>(new Map());
-  const onStatusRef = useRef(onStatusChange);
-  onStatusRef.current = onStatusChange;
-
-  const registry = useMemo<ExtensionFormRegistry>(() => {
-    const emitDirty = (): void => {
-      let any = false;
-      for (const r of regsRef.current.values()) {
-        if (r.dirty) {
-          any = true;
-          break;
-        }
-      }
-      onStatusRef.current({ anyDirty: any, hasRegistrations: regsRef.current.size > 0 });
-    };
-    return {
-      upsert: (reg) => {
-        regsRef.current.set(reg.key, reg);
-        emitDirty();
-      },
-      remove: (key) => {
-        regsRef.current.delete(key);
-        emitDirty();
-      },
-    };
-  }, []);
-
-  const runAll = useMemo(
-    () =>
-      async (ctx: ExtensionSubmitContext): Promise<readonly ExtensionSubmitResult[]> => {
-        const results: ExtensionSubmitResult[] = [];
-        // Insertion-Order (Map) = Section-Reihenfolge im Form.
-        for (const reg of regsRef.current.values()) {
-          results.push(await reg.handler(ctx));
-        }
-        return results;
-      },
-    [],
-  );
-
-  return { registry, runAll };
-}
-
-// Section-Seite: meldet Handler + dirty an die umgebende Form. Returnt true
-// wenn eine composed-Form vorhanden ist (Section blendet dann ihren eigenen
-// Save-Button aus); false = standalone (eigener Save-Button bleibt).
-export function useExtensionFormSubmit(opts: {
-  readonly dirty: boolean;
-  readonly onSubmit: ExtensionFormSubmitHandler;
-}): boolean {
-  const registry = useContext(ExtensionFormRegistryContext);
-  const key = useId();
-  // Handler über ref, damit das Re-Registrieren NICHT an jeder Handler-
-  // Identity hängt (nur an dirty); der Handler liest immer den frischen
-  // Closure-State (pending) zur Aufruf-Zeit.
-  const handlerRef = useRef(opts.onSubmit);
-  handlerRef.current = opts.onSubmit;
-
-  useEffect(() => {
-    if (registry === null) return;
-    registry.upsert({
-      key,
-      dirty: opts.dirty,
-      handler: (ctx) => handlerRef.current(ctx),
-    });
-    return () => registry.remove(key);
-  }, [registry, key, opts.dirty]);
-
-  return registry !== null;
-}

package/src/app/extension-sections.tsx

@@ -1,111 +0,0 @@
-// Extension-Section-Components-Map: client-side Lookup für entityEdit
-// sections vom Type `extension`, List-Header-Slots UND Dashboard-`custom`-
-// Panels. Jeder Mount-Ort löst den `__component`-Namen aus einer
-// PlatformComponent über dieselbe Registry auf und mountet die passende
-// Component — die Bundled-Feature-/App-Component lädt + persistiert dann
-// ihre eigenen Daten (z.B. custom-fields, oder ein eigenständiger Chart).
-// The entityEdit footer slot (`screen.slots.footer`) mounts through it too.
-//
-// Mounting analog zu CustomScreensProvider — createKumikoApp im
-// renderer-web sammelt alle clientFeatures.extensionSectionComponents und
-// mountet den Provider; Tests die einzelne Sections prüfen wollen
-// mounten den Provider direkt.
-
-import type { PlatformComponent } from "@cosmicdrift/kumiko-framework/ui-types";
-import { type ComponentType, createContext, type ReactNode, useContext } from "react";
-
-/** Extrahiert den `__component`-Namen aus einer PlatformComponent. Liest
- *  react- und native-Branch (die App-Author registriert beide unter dem
- *  gleichen Namen); returnt den ersten gefundenen string. Pure narrowing
- *  via `in` — kein cast, kein assertion. */
-export function extensionSectionName(component: PlatformComponent): string | undefined {
-  for (const branch of [component.react, component.native]) {
-    if (branch !== null && typeof branch === "object" && "__component" in branch) {
-      const candidate = branch.__component;
-      if (typeof candidate === "string") return candidate;
-    }
-  }
-  return undefined;
-}
-
-export type ExtensionSectionProps = {
-  readonly entityName: string;
-  readonly entityId: string | null;
-  /** Bereits gespeicherte Extension-Werte der Entity (aus der geladenen
-   *  detail-row durchgereicht). `undefined` im Create-Mode oder wenn der
-   *  Host-Screen keine Werte liefert. Erlaubt der Section, den Bestand
-   *  beim Edit anzuzeigen statt write-only zu sein. */
-  readonly initialValues?: Readonly<Record<string, unknown>>;
-  /** Nur im List-Header-Slot gesetzt (entityId ist dort null): die screen.id
-   *  der Liste, damit ein Header-Control den per-Screen URL-Filter-State
-   *  (useListUrlState) ansprechen kann — z.B. ein Tag-Filter der die Liste auf
-   *  eine id-Menge narrowed. In entityEdit-Sections undefined. */
-  readonly screenId?: string;
-  /** Nur im Dashboard-`custom`-Panel gesetzt: der aktuell gewählte Wert des
-   *  Screen-Filters (siehe DashboardFilterDefinition), gemerged wie bei jeder
-   *  anderen Panel-Query. In allen anderen Mount-Orten undefined. Dashboard-
-   *  Panels haben keine Entity — entityName/entityId tragen dort die
-   *  screen.id bzw. null, siehe CustomPanelBody in dashboard-body.tsx. */
-  readonly filterParams?: Readonly<Record<string, unknown>>;
-  /** Current form values of the host RenderEdit (controlled mode,
-   *  issue #1887/#1888) — same snapshot reference as
-   *  `RenderEditChangeState.values`. Lets the section read the host
-   *  form's live state (e.g. for a review step). Only set in
-   *  entityEdit sections; undefined in list-header and dashboard
-   *  mounts, where no host form exists. */
-  readonly values?: Readonly<Record<string, unknown>>;
-  /** Sets host RenderEdit form values from outside (e.g. a VIN-decode
-   *  roundtrip that fills other fields) — same function as
-   *  `RenderEditControls.patch`, merges only the given keys. `patch` must
-   *  converge: `setValues` is a no-op only when the merged result is
-   *  reference-equal to the current values, so an unconditional
-   *  `patch(...)` from a `values`-dependent effect loops. Undefined outside
-   *  entityEdit sections. */
-  readonly patch?: (partial: Readonly<Record<string, unknown>>) => void;
-  /** Validates the host form without writing — same function as
-   *  `RenderEditControls.validate`; field errors land in
-   *  `snapshot.errors` on the field instead of a collective message.
-   *  Undefined outside entityEdit sections. */
-  readonly validate?: () => boolean;
-  /** Whether the host form has unsaved changes. Only set in the entityEdit
-   *  footer slot (`screen.slots.footer`); undefined in all other mounts. */
-  readonly hasUnsavedChanges?: boolean;
-  /** Current wizard step, only set for `layout.mode === "wizard"` forms.
-   *  Only set in the entityEdit footer slot (`screen.slots.footer`);
-   *  undefined in all other mounts, and undefined there too for a
-   *  non-wizard form. */
-  readonly wizardStep?: { readonly index: number; readonly isLast: boolean };
-};
-
-export type ExtensionSectionComponent = ComponentType<ExtensionSectionProps>;
-
-export type ExtensionSectionsMap = Readonly<Record<string, ExtensionSectionComponent>>;
-
-const ExtensionSectionsContext = createContext<ExtensionSectionsMap | undefined>(undefined);
-
-export type ExtensionSectionsProviderProps = {
-  readonly children: ReactNode;
-  readonly value: ExtensionSectionsMap;
-};
-
-export function ExtensionSectionsProvider({
-  children,
-  value,
-}: ExtensionSectionsProviderProps): ReactNode {
-  return (
-    <ExtensionSectionsContext.Provider value={value}>{children}</ExtensionSectionsContext.Provider>
-  );
-}
-
-/** Schaut die Component für einen extension-section-Namen nach. Returnt
- *  undefined wenn weder Provider gemounted noch der Name in der Map
- *  registriert ist — der Caller (RenderEdit) zeigt dann seinen
- *  Placeholder-Banner. `name` ist optional damit Caller den Hook
- *  unkonditional aufrufen können (Rules-of-Hooks), ohne einen Stub-Key
- *  wie `""` reichen zu müssen — analog `useColumnRenderer`. */
-export function useExtensionSectionComponent(name?: string): ExtensionSectionComponent | undefined {
-  const map = useContext(ExtensionSectionsContext);
-  if (name === undefined || name === "") return undefined;
-  if (map === undefined) return undefined;
-  return map[name];
-}

package/src/app/form-schema.ts

@@ -1,91 +0,0 @@
-import type {
-  EntityDefinition,
-  EntityEditScreenDefinition,
-  FieldDefinition,
-} from "@cosmicdrift/kumiko-framework/ui-types";
-import { evalFieldCondition, NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-framework/ui-types";
-import { I18N_KEY_PARAM } from "@cosmicdrift/kumiko-headless";
-import * as z from "zod";
-import { layoutEditFields } from "./layout-fields";
-
-// `required` means "has a value", not "is truthy" — `false` and `0` count
-// as present, only the actually-empty representations don't.
-function isPresent(value: unknown): boolean {
-  if (value === undefined || value === null || value === "") return false;
-  if (Array.isArray(value) && value.length === 0) return false;
-  return true;
-}
-
-function isEmbeddedListField(field: FieldDefinition): boolean {
-  return field.type === "embedded" && field.multiple === true;
-}
-
-// Renders raw to the user without a de+en default in i18n-defaults.ts.
-export const REQUIRED_FIELD_I18N_KEY = "kumiko.validation.required";
-
-// Client-side presence validation for the auto-wired entityEdit path —
-// checks that every rendered required field HAS a value, not that the
-// value has the right shape. Format/range/type validation stays server-
-// authoritative (buildInsertSchema/buildUpdateSchema): the form-state
-// representation of a value can diverge from the server-payload shape (e.g.
-// money is `{amount,currency}`, not a bare number), so a format check here
-// would either reject valid values or need per-representation branches that
-// rot the moment either side changes.
-//
-// One `superRefine` instead of a per-field shape: a field-level `.refine()`
-// wouldn't run at all for a key that's simply absent from `values` —
-// `superRefine` sees the whole object and catches that case too.
-// `.passthrough()` is load-bearing: the default `z.object({})` STRIPS every
-// key (there's no declared shape), so `superRefine` would see an empty
-// object regardless of what was actually submitted — every required field
-// would misreport as missing.
-//
-// Iterates the screen's layout field specs, not `entity.fields` — `required`
-// and `readOnly` are per-spec, evaluated against the current values the
-// same way `view-model/edit.ts` resolves them for the rendered form. Not
-// checked here: `visible`. `runValidate` already filters issues on hidden
-// fields via `computeFieldStates(options.fields, …)` (form-controller.ts:163,181),
-// fed by `deriveFormFields(screen)` in render-edit.tsx.
-export function buildFormSchema(
-  entity: EntityDefinition,
-  screen: EntityEditScreenDefinition,
-): z.ZodType {
-  const fields = layoutEditFields(screen);
-  return z
-    .object({})
-    .passthrough()
-    .superRefine((values, ctx) => {
-      // `.passthrough()` types `values` as a plain object but doesn't declare
-      // its keys — the runtime object always carries every form field.
-      // @cast-boundary form-values
-      const record = values as Record<string, unknown>;
-      for (const spec of fields) {
-        const field = entity.fields[spec.field];
-        if (!field) continue;
-        // Not operable by the user — a presence error would be unresolvable,
-        // same reason as the NO_WIDGET_FIELD_TYPES check below.
-        if (spec.readOnly !== undefined && evalFieldCondition(spec.readOnly, record)) continue;
-        // Screen-spec `required` overrides the entity default, mirroring
-        // `view-model/edit.ts` — the rendered form is the reference, and a
-        // presence check stricter than the form blocks the user for nothing.
-        const entityRequired = "required" in field && field.required === true;
-        const isRequired =
-          spec.required === undefined ? entityRequired : evalFieldCondition(spec.required, record);
-        if (!isRequired) continue;
-        // Embedded LIST fields get their own EmbeddedListField grid widget
-        // (#1838) — they're fillable, so NO_WIDGET_FIELD_TYPES's "embedded"
-        // entry must not exempt them. A statically-`required: true` field
-        // with no bound widget is also caught at boot
-        // (validateNoWidgetRequiredField in boot-validator/screens.ts).
-        if (NO_WIDGET_FIELD_TYPES.includes(field.type) && !isEmbeddedListField(field)) continue;
-        if (isPresent(record[spec.field])) continue;
-        ctx.addIssue({
-          code: "custom",
-          path: [spec.field],
-          message: `"${spec.field}" is required.`,
-          // I18N_KEY_PARAM override, see packages/headless/src/form/zod-bridge.ts.
-          params: { [I18N_KEY_PARAM]: REQUIRED_FIELD_I18N_KEY },
-        });
-      }
-    });
-}