@cosmicdrift/kumiko-headless 0.1.0

package/src/view-model/edit.ts

@@ -0,0 +1,164 @@
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+  FieldCondition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { normalizeEditField, parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
+import { buildOptionLabels, fieldLabelKey } from "./list";
+import type { EditFieldViewModel, EditSectionViewModel, EditViewModel, Translate } from "./types";
+
+export type ComputeEditViewModelInput<
+  TValues extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
+  TCtx = unknown,
+> = {
+  readonly screen: EntityEditScreenDefinition;
+  readonly entity: EntityDefinition;
+  readonly values: TValues;
+  readonly translate: Translate;
+  readonly featureName: string;
+  // Optional condition context — forwarded to field visible/readonly/required
+  // predicates. Normally the host app passes `{ user, config, ... }`.
+  readonly ctx?: TCtx;
+};
+
+// Pure transform from screen-def + entity-def + row-values to the flat
+// section/field tree the renderer draws. Conditional predicates are
+// evaluated here so the renderer never re-runs them during React render.
+//
+// TValues / TCtx are propagated through evalCondition so call-sites can
+// `computeEditViewModel<OrderRow, AdminCtx>(...)` and get typed data/ctx
+// inside their predicates. Default `unknown` keeps unannotated call-sites
+// working unchanged.
+export function computeEditViewModel<
+  TValues extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
+  TCtx = unknown,
+>(input: ComputeEditViewModelInput<TValues, TCtx>): EditViewModel {
+  const { screen, entity, values, translate, featureName, ctx } = input;
+
+  const sections: EditSectionViewModel[] = screen.layout.sections.map((sectionSpec) => {
+    const fields: EditFieldViewModel[] = sectionSpec.fields.map((fieldSpec) => {
+      const normalized = normalizeEditField(fieldSpec);
+      const fieldDef = entity.fields[normalized.field];
+      if (!fieldDef) {
+        throw new Error(
+          `computeEditViewModel: screen "${screen.id}" references unknown field "${normalized.field}" on entity "${screen.entity}"`,
+        );
+      }
+      const label = translate(fieldLabelKey(featureName, screen.entity, normalized.field));
+      const visible = evalCondition<TValues, TCtx>(normalized.visible, true, values, ctx);
+      // `readOnly` (camelCase) is the name on both sides: EditFieldSpec
+      // in the engine, and the view-model emitted here. One convention
+      // through the stack beats translating at the boundary.
+      const readOnly = evalCondition<TValues, TCtx>(normalized.readOnly, false, values, ctx);
+      // `required` on the field-spec overrides the entity-default. A
+      // field that's required at the entity-level but marked required:
+      // false on the screen (e.g. a soft-onboarding wizard that
+      // collects less up-front) respects the screen override.
+      const entityRequired = (fieldDef as unknown as { required?: boolean }).required === true;
+      const required = evalCondition<TValues, TCtx>(
+        normalized.required,
+        entityRequired,
+        values,
+        ctx,
+      );
+      // Select-Optionen bei `type: "select"` mitnehmen — der Renderer
+      // braucht sie für das Dropdown ohne nochmal die EntityDefinition
+      // zu reichen. Plus translated Labels (gleiche Convention wie der
+      // List-Builder), damit Form-Selects und List-Cells dieselbe
+      // i18n-Quelle teilen.
+      const options =
+        fieldDef.type === "select"
+          ? ((fieldDef as unknown as { options?: readonly string[] }).options ?? [])
+          : undefined;
+      const optionLabels =
+        options !== undefined
+          ? buildOptionLabels(translate, featureName, screen.entity, normalized.field, options)
+          : undefined;
+      // Multiline-Hint bei `type: "text"` — der Renderer wechselt
+      // dann auf textarea. ViewModel hält die Form-Render-Decision
+      // damit der Renderer nicht selbst auf die FieldDefinition greift.
+      const multiline =
+        fieldDef.type === "text"
+          ? (fieldDef as unknown as { multiline?: boolean | { rows?: number } }).multiline
+          : undefined;
+      // Tier 2.7e-3: Reference-Field — refEntity + refLabelField in
+      // das ViewModel reichen damit der Renderer die Lookup-Query
+      // bauen kann ohne noch an EntityDefinition zu greifen.
+      // Tier 2.7e-3: Reference-Field — entity-String kann same-feature
+      // ("user") oder cross-feature ("users:user") sein. parseRefTarget
+      // splittet das, der Renderer baut die Lookup-QN aus
+      // (refFeature, refEntity).
+      const refRaw =
+        fieldDef.type === "reference"
+          ? (fieldDef as unknown as { entity?: string }).entity
+          : undefined;
+      const refTarget = refRaw !== undefined ? parseRefTarget(refRaw, featureName) : undefined;
+      const refEntity = refTarget?.entityName;
+      const refFeature = refTarget?.featureName;
+      const refLabelField =
+        fieldDef.type === "reference"
+          ? ((fieldDef as unknown as { labelField?: string }).labelField ?? "id")
+          : undefined;
+      const refMultiple =
+        fieldDef.type === "reference"
+          ? ((fieldDef as unknown as { multiple?: boolean }).multiple ?? false)
+          : undefined;
+      const view: EditFieldViewModel = {
+        field: normalized.field,
+        label,
+        type: fieldDef.type,
+        value: values[normalized.field],
+        visible,
+        readOnly,
+        required,
+        ...(normalized.span !== undefined && { span: normalized.span }),
+        ...(normalized.renderer !== undefined && { renderer: normalized.renderer }),
+        ...(options !== undefined && { options }),
+        ...(optionLabels !== undefined && { optionLabels }),
+        ...(multiline !== undefined && { multiline }),
+        ...(refEntity !== undefined && { refEntity }),
+        ...(refFeature !== undefined && { refFeature }),
+        ...(refLabelField !== undefined && { refLabelField }),
+        ...(refMultiple !== undefined && { refMultiple }),
+      };
+      return view;
+    });
+    return {
+      title: translate(sectionSpec.title),
+      columns: sectionSpec.columns ?? 1,
+      fields,
+    };
+  });
+
+  const id = (values["id"] as string | undefined) ?? null;
+
+  return {
+    screenId: screen.id,
+    entityName: screen.entity,
+    id,
+    sections,
+    ...(screen.slots && { slots: screen.slots }),
+  };
+}
+
+// Resolves a FieldCondition (undefined | predicate) into its boolean
+// value against the current row values + ctx. `undefined` means "not
+// declared" — caller substitutes the entity-level default.
+//
+// TValues / TCtx mirror the generics on FieldCondition. EditFieldSpec
+// stores predicates as FieldCondition<unknown, unknown>, which is
+// assignable to FieldCondition<TValues, TCtx> for any TValues/TCtx by
+// parameter contravariance (a predicate that accepts `unknown` accepts
+// anything). The cast on ctx is the one rough edge: input.ctx is
+// optional, so at runtime we may pass undefined to a predicate that
+// declared a concrete TCtx — the caller is responsible for not doing
+// that when they narrow TCtx away from `unknown`.
+function evalCondition<TValues, TCtx>(
+  condition: FieldCondition<TValues, TCtx> | undefined,
+  fallback: boolean,
+  values: TValues,
+  ctx: TCtx | undefined,
+): boolean {
+  if (condition === undefined) return fallback;
+  return condition(values, ctx as TCtx);
+}

package/src/view-model/index.ts

@@ -0,0 +1,19 @@
+export type { ComputeEditViewModelInput } from "./edit";
+export { computeEditViewModel } from "./edit";
+export type { ComputeListViewModelInput } from "./list";
+export { computeListViewModel, fieldLabelKey } from "./list";
+export type {
+  EditFieldSpec,
+  EditFieldViewModel,
+  EditSectionSpec,
+  EditSectionViewModel,
+  EditViewModel,
+  FieldConditionCtx,
+  FieldRenderer,
+  ListColumnSpec,
+  ListColumnViewModel,
+  ListRowViewModel,
+  ListViewModel,
+  ScreenSlots,
+  Translate,
+} from "./types";

package/src/view-model/list.ts

@@ -0,0 +1,158 @@
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+  FieldDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { normalizeListColumn, parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ListColumnViewModel, ListRowViewModel, ListViewModel, Translate } from "./types";
+
+export type ComputeListViewModelInput = {
+  readonly screen: EntityListScreenDefinition;
+  readonly entity: EntityDefinition;
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  // Translate callback — normally LocaleResolver.translate. Labels use the
+  // i18n convention "{feature}:entity:{entityName}:field:{fieldName}"; if
+  // the key is absent from the active bundle, i18next falls back to the
+  // key itself, which is fine for dev.
+  readonly translate: Translate;
+  // Feature + entity name are required for i18n key composition —
+  // ScreenDefinition carries `entity: string` but not the feature scope,
+  // and i18n keys are prefixed by feature. Passed in by the caller (the
+  // renderer knows its host-feature context).
+  readonly featureName: string;
+};
+
+// Pure transform: takes the declared screen + entity + incoming rows, spits
+// out the flat shape the renderer draws. No conditions, no access-checks —
+// those are list-level decisions that the caller makes BEFORE calling
+// here (e.g. filtering rows by ownership on the server / before query).
+// Field-level read-access (Level 3 of UI-architecture.md §Permission) is a
+// follow-up; this v1 assumes the caller passed a row-filter that drops any
+// field the user may not see.
+export function computeListViewModel(input: ComputeListViewModelInput): ListViewModel {
+  const { screen, entity, rows, translate, featureName } = input;
+
+  const columns: ListColumnViewModel[] = [];
+  for (const spec of screen.columns) {
+    const normalized = normalizeListColumn(spec);
+    const fieldDef = entity.fields[normalized.field];
+    if (!fieldDef) {
+      // Screen references a field that's not on the entity. Fail loud —
+      // the boot-validator (r.screen) should catch this, but a stale
+      // field-rename would leave the screen referring to a ghost column
+      // until ops re-runs boot. We throw so the renderer sees the error
+      // instead of drawing an empty column.
+      throw new Error(
+        `computeListViewModel: screen "${screen.id}" references unknown field "${normalized.field}" on entity "${screen.entity}"`,
+      );
+    }
+    const label = translate(fieldLabelKey(featureName, screen.entity, normalized.field));
+    // Tier 2.7e-3 + Cross-Feature: Reference-Field — entity-String
+    // kann same-feature ("user") oder cross-feature ("users:user")
+    // sein. parseRefTarget gibt (featureName, entityName), der
+    // Renderer baut die Lookup-QN als
+    // `<refFeature>:query:<refEntity>:list`.
+    const refRaw =
+      fieldDef.type === "reference"
+        ? (fieldDef as unknown as { entity?: string }).entity
+        : undefined;
+    const refTarget = refRaw !== undefined ? parseRefTarget(refRaw, featureName) : undefined;
+    const refEntity = refTarget?.entityName;
+    const refFeature = refTarget?.featureName;
+    const refLabelField =
+      fieldDef.type === "reference"
+        ? ((fieldDef as unknown as { labelField?: string }).labelField ?? "id")
+        : undefined;
+    // Bei select-Feldern: translated Option-Labels einbacken. Convention
+    // matcht den Form-Path → eine Translation-Quelle für List + Form.
+    // Missing-Key returnt convention-gemäß den Key zurück; Renderer hat
+    // dann humanizeSlug-Fallback.
+    const optionLabels =
+      fieldDef.type === "select"
+        ? buildOptionLabels(
+            translate,
+            featureName,
+            screen.entity,
+            normalized.field,
+            (fieldDef as unknown as { options?: readonly string[] }).options ?? [],
+          )
+        : undefined;
+    const column: ListColumnViewModel = {
+      field: normalized.field,
+      label,
+      type: fieldDef.type,
+      sortable: fieldIsSortable(fieldDef),
+      ...(normalized.renderer !== undefined && { renderer: normalized.renderer }),
+      ...(optionLabels !== undefined && { optionLabels }),
+      ...(refEntity !== undefined && { refEntity }),
+      ...(refFeature !== undefined && { refFeature }),
+      ...(refLabelField !== undefined && { refLabelField }),
+    };
+    columns.push(column);
+  }
+
+  const listRows: ListRowViewModel[] = rows.map((row) => ({
+    id: String(row["id"] ?? ""),
+    values: row,
+  }));
+
+  return {
+    screenId: screen.id,
+    entityName: screen.entity,
+    columns,
+    rows: listRows,
+    ...(screen.slots && { slots: screen.slots }),
+    isEmpty: listRows.length === 0,
+  };
+}
+
+// Field-i18n-key convention matches what features register translations
+// under (see packages/framework/src/i18n/ for the pattern). Duplicated
+// here as a plain function — the ui-core boundary forbids depending on
+// the i18n module directly.
+export function fieldLabelKey(featureName: string, entityName: string, fieldName: string): string {
+  return `${featureName}:entity:${entityName}:field:${fieldName}`;
+}
+
+export function fieldOptionLabelKey(
+  featureName: string,
+  entityName: string,
+  fieldName: string,
+  value: string,
+): string {
+  return `${featureName}:entity:${entityName}:field:${fieldName}:option:${value}`;
+}
+
+// Build a value→label map for a select-field's options. Convention:
+// translate() returns the input key when the lookup misses (i18next
+// default + LocaleResolver convention) — we surface the *raw value* in
+// that case so the renderer's humanizeSlug fallback can take over.
+// Without that fallback, an unlabeled option would render as the full
+// `feature:entity:field:option:value`-key.
+//
+// Shared between list-VM and edit-VM so both builders produce
+// identical option-translations.
+export function buildOptionLabels(
+  translate: (key: string, params?: Readonly<Record<string, unknown>>) => string,
+  featureName: string,
+  entityName: string,
+  fieldName: string,
+  options: readonly string[],
+): Readonly<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const value of options) {
+    const key = fieldOptionLabelKey(featureName, entityName, fieldName, value);
+    const translated = translate(key);
+    out[value] = translated === key ? value : translated;
+  }
+  return out;
+}
+
+// A field can declare `sortable: true` on the FieldDefinition. This is
+// framework-level metadata used both by the server's list-query builder
+// (ORDER BY safety) and by the UI (column header click indicator). All
+// field types can bear the flag; it's off by default.
+function fieldIsSortable(field: FieldDefinition): boolean {
+  const flag = (field as unknown as { sortable?: boolean }).sortable;
+  return flag === true;
+}

package/src/view-model/types.ts

@@ -0,0 +1,150 @@
+import type {
+  EditFieldSpec,
+  EditSectionSpec,
+  FieldRenderer,
+  ListColumnSpec,
+  ScreenSlots,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+
+// View-Models — plain data structures produced by computeListViewModel and
+// computeEditViewModel. They flatten the combined [screen-def + entity-def
+// + row-data + user] inputs into a shape the renderer draws directly,
+// without re-resolving conditions or re-reading the entity field map.
+//
+// The renderer's render-list.tsx / render-edit.tsx are essentially
+//   (viewModel) => JSX   // on web
+//   (viewModel) => <View/Text>  // on native
+// so everything the renderer needs to render one frame must be in here.
+//
+// Why pre-compute instead of resolving at render-time: predicates
+// (visible/readonly/required) are arbitrary JS closures — running them
+// inside React's render is wasteful (happens on every re-render, even
+// when values haven't changed) and mixes side-effect-free view code
+// with business logic. Computing once on form-state-change gives the
+// renderer pure data and keeps render paths trivial.
+
+// --- list view model ---
+
+// One column, fully resolved. `label` is the localized string the
+// renderer puts in the column header; view-model builder runs it through
+// LocaleResolver.translate() from the i18nKey wired onto the field.
+// `renderer` passes through ScreenDefinition's FieldRenderer verbatim.
+export type ListColumnViewModel = {
+  readonly field: string;
+  readonly label: string;
+  readonly type: string; // field-type ("text", "number", "money", ...)
+  readonly renderer?: FieldRenderer;
+  readonly sortable: boolean;
+  /** Nur bei `type: "select"` — translated Option-Labels keyed nach raw
+   *  value. Renderer rendert `optionLabels[value]` statt humanizeSlug
+   *  wenn vorhanden. Convention-Key: `<feature>:entity:<entity>:field:<field>:option:<value>`. */
+  readonly optionLabels?: Readonly<Record<string, string>>;
+  /** Nur bei `type: "reference"` — referenced Entity-Name für Bulk-
+   *  Lookup im Renderer (`<refFeature>:query:<refEntity>:list`). */
+  readonly refEntity?: string;
+  /** Nur bei `type: "reference"` — Feature-Name in dem die referenced
+   *  Entity wohnt. Default = current feature. Cross-Feature über
+   *  qualifizierte Form ("feature:entity") am ReferenceFieldDef. */
+  readonly refFeature?: string;
+  /** Nur bei `type: "reference"` — Welches Feld der referenced Entity
+   *  als Display-Wert in der Cell erscheint (Default "id"). */
+  readonly refLabelField?: string;
+};
+
+export type ListRowViewModel = {
+  readonly id: string;
+  readonly values: Readonly<Record<string, unknown>>;
+};
+
+export type ListViewModel = {
+  readonly screenId: string;
+  readonly entityName: string;
+  readonly columns: readonly ListColumnViewModel[];
+  readonly rows: readonly ListRowViewModel[];
+  readonly slots?: ScreenSlots;
+  // Flags for the renderer to decide what kind of container to draw.
+  readonly isEmpty: boolean;
+};
+
+// --- edit view model ---
+
+// Resolved field — all predicates evaluated, labels translated. The
+// renderer reads `{ visible, readonly, required }` directly without
+// re-running any predicate.
+export type EditFieldViewModel = {
+  readonly field: string;
+  readonly label: string;
+  readonly type: string;
+  readonly value: unknown;
+  readonly visible: boolean;
+  // `readOnly` (camelCase) matches the spec-side name on EditFieldSpec —
+  // one convention through the stack. The TS property modifier `readonly`
+  // (lowercase) only collides as a key name in type declarations of the
+  // spec; here in the view-model we could have used either, but symmetric
+  // naming beats clever ergonomics. Parallel-agent chose `readOnly` on
+  // the input; we honour it on the output.
+  readonly readOnly: boolean;
+  readonly required: boolean;
+  readonly span?: number;
+  readonly renderer?: FieldRenderer;
+  /** Nur bei `type: "select"` gesetzt — die zugelassenen Werte. Wird
+   *  vom Renderer als Dropdown-Optionen genutzt. Quelle ist
+   *  SelectFieldDef.options aus der EntityDefinition. */
+  readonly options?: readonly string[];
+  /** Nur bei `type: "select"` gesetzt — translated Labels pro Option,
+   *  keyed nach raw value. Renderer zeigt `optionLabels[value]` als
+   *  Dropdown-Label statt raw value. Convention-Key:
+   *  `<feature>:entity:<entity>:field:<field>:option:<value>`. */
+  readonly optionLabels?: Readonly<Record<string, string>>;
+  /** Nur bei `type: "text"` gesetzt wenn TextFieldDef.multiline true
+   *  ist — dann rendert der Renderer textarea statt single-line input.
+   *  `true` = Default-Zeilen, `{ rows }` = explizite Höhe. */
+  readonly multiline?: boolean | { readonly rows?: number };
+  /** Nur bei `type: "reference"` gesetzt — Tier 2.7e-3.
+   *  Die referenced Entity (kurz, ohne feature-prefix). Der Renderer
+   *  baut die Query-QN als `<refFeature>:query:<refEntity>:list`. */
+  readonly refEntity?: string;
+  /** Nur bei `type: "reference"` gesetzt — Feature-Name in dem die
+   *  referenced Entity wohnt. Same-feature default = aktuelles
+   *  Feature. Cross-Feature wird über "feature:entity" am
+   *  ReferenceFieldDef.entity erkannt. */
+  readonly refFeature?: string;
+  /** Nur bei `type: "reference"` gesetzt — Welches Feld der referenced
+   *  Entity als Display-Label im Dropdown erscheint. Default: "id". */
+  readonly refLabelField?: string;
+  /** Nur bei `type: "reference"` — Multi-Mode (Tier 2.7e-Multi):
+   *  Wert ist UUID-Array, Renderer mountet Multi-Combobox mit Tags. */
+  readonly refMultiple?: boolean;
+};
+
+export type EditSectionViewModel = {
+  readonly title: string;
+  readonly columns: number;
+  readonly fields: readonly EditFieldViewModel[];
+};
+
+export type EditViewModel = {
+  readonly screenId: string;
+  readonly entityName: string;
+  readonly id: string | null; // null on create (no existing row)
+  readonly sections: readonly EditSectionViewModel[];
+  readonly slots?: ScreenSlots;
+};
+
+// --- resolver interfaces (host-injected) ---
+
+// The view-model builder calls this to translate i18n keys into strings.
+// Normally the host passes the renderer's LocaleResolver.translate
+// directly — keeping the interface narrow here avoids dragging the full
+// LocaleResolver (with subscribe) into a pure compute path.
+export type Translate = (key: string, params?: Readonly<Record<string, unknown>>) => string;
+
+// Optional condition context forwarded to field visibility/readonly/required
+// predicates. Same ctx the form-controller uses in conditional-fields — so
+// a predicate that gated "admin-only" there keeps working here.
+export type FieldConditionCtx = unknown;
+
+// Re-export the ScreenDef spec halves we don't want ui-core callers to
+// import from @cosmicdrift/kumiko-framework separately. Renderer packages expect a
+// single import surface.
+export type { EditFieldSpec, EditSectionSpec, FieldRenderer, ListColumnSpec, ScreenSlots };