@cosmicdrift/kumiko-types 0.220.1 → 0.221.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.220.1",
+  "version": "0.221.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -166,6 +166,10 @@
       "types": "./src/nav-icon.ts",
       "default": "./src/nav-icon.ts"
     },
+    "./field-icon": {
+      "types": "./src/field-icon.ts",
+      "default": "./src/field-icon.ts"
+    },
     "./ownership": {
       "types": "./src/ownership.ts",
       "default": "./src/ownership.ts"

package/src/field-icon.ts

@@ -0,0 +1,23 @@
+// Closed vocabulary of edit-field prefix icon keys. EditFieldSpec.icon,
+// InputProps.icon and EditFieldViewModel.icon are typed against this union,
+// so a typo (`"mial"`) is a compile error at the screen-def / view-model
+// call site instead of a silent missing-icon at runtime.
+//
+// The renderer-web FIELD_ICONS map (packages/renderer-web/src/primitives/
+// index.tsx) is checked against this same union via `satisfies`, so the
+// two can't drift — add a key here only together with its lucide-react
+// entry there, and vice versa.
+export type FieldIconKey =
+  | "mail"
+  | "lock"
+  | "hash"
+  | "search"
+  | "user"
+  | "phone"
+  | "calendar"
+  | "link"
+  | "tag"
+  | "building"
+  | "globe"
+  | "key"
+  | "map-pin";

package/src/nav.ts

@@ -79,6 +79,9 @@ export type NavDefinition = {
 // `parent` may point at another feature's nav QN; the boot validator rejects
 // dangling refs, so a collection mounted under a feature that isn't mounted
 // fails boot instead of silently disappearing from the sidebar.
+/** Client editor format for r.contentCollection() — not template body storage formats. */
+export type ContentEditorFormat = "plain" | "rich" | "markdown";
+
 export type ContentCollectionDefinition = {
   // Feature-local short id, kebab-case. Also becomes the nav entry's id, so
   // it must not collide with an r.nav()/r.screen() id in the same feature.
@@ -104,7 +107,7 @@ export type ContentCollectionDefinition = {
   // the content is stored. "rich" still stores HTML, because mail and PDF
   // rendering want HTML either way. "markdown" stores markdown text, not
   // HTML. Defaults to "plain" (textarea).
-  readonly contentFormat?: "plain" | "rich" | "markdown";
+  readonly contentFormat?: ContentEditorFormat;
   // Fixed variable names the collection's editor offers as insertable chips,
   // mapped to an example value the Preview substitutes in for `{{name}}`
   // (e.g. `{ customerName: "Max Mustermann", orderId: "A-1042" }` for an

package/src/screen.ts

@@ -1,7 +1,10 @@
+import type { FieldIconKey } from "./field-icon";
 import type { FieldDefinition } from "./fields";
 import type { AccessRule } from "./handlers";
 import type { NavIconKey } from "./nav-icon";
 
+export type { FieldIconKey } from "./field-icon";
+
 // Screen definitions describe how a feature surfaces data to the user.
 // Pure data — the engine stores these verbatim and ui-core / the renderer
 // packages decide what to do with them. The framework must not import
@@ -55,6 +58,8 @@ export interface FieldFormatRegistry {
   number: { readonly locale?: string };
   decimal: { readonly locale?: string };
   bigInt: { readonly locale?: string };
+  // Value is percent *points* (12 → "12 %"), not a 0..1 ratio — Intl
+  // style:"unit"/unit:"percent" does NOT multiply by 100 (unlike style:"percent").
   unit: {
     readonly unit: UnitKey;
     readonly locale?: string;
@@ -64,6 +69,8 @@ export interface FieldFormatRegistry {
   // `<feature>:entity:<entity>:field:<field>:option:<value>` — same
   // fallback-to-raw-value rule as buildOptionLabels: an untranslated key
   // renders the raw enum value instead of the literal i18n key.
+  // Prefer fieldOptionLabelKeyPrefix() from @cosmicdrift/kumiko-headless
+  // over hand-typed prefix strings.
   enumOption: { readonly keyPrefix: string };
 }
 
@@ -222,20 +229,10 @@ export type RowActionWriteHandler = {
   readonly style?: "primary" | "secondary" | "danger";
 };
 
-export type RowActionNavigate = {
+export type RowActionNavigateBase = {
   readonly kind: "navigate";
   readonly id: string;
   readonly label: string;
-  /** Screen-id (kurz, unqualified) zu dem navigiert wird. Boot-
-   *  Validator prüft Existenz im selben Feature. Genau eines von
-   *  `screen`/`entity` muss gesetzt sein. */
-  readonly screen?: string;
-  /** Entity-Name statt Screen-Id (fw#2228) — löst zur Boot-Zeit auf den
-   *  Screen auf, der `detailFor: "<entity>"` deklariert (siehe ObjectTarget/
-   *  resolveTarget in @cosmicdrift/kumiko-renderer's nav.tsx), egal in
-   *  welchem Feature dieser liegt. Genau eines von `screen`/`entity` muss
-   *  gesetzt sein. */
-  readonly entity?: string;
   /** Feldname dessen Wert als entityId in den URL-Pfad eingebettet wird
    *  (`/<workspace>/<screen>/<entityId>`). entityEdit liest die Id
    *  AUSSCHLIESSLICH aus dem Pfad. Default: "id" wenn der Ziel-Screen ein
@@ -257,6 +254,25 @@ export type RowActionNavigate = {
   readonly rowClick?: boolean;
 };
 
+/** Exactly one of `screen` / `entity` — mutual exclusivity is type-enforced
+ *  (boot validator still rejects both/neither for untyped schemas). */
+export type RowActionNavigate = RowActionNavigateBase &
+  (
+    | {
+        /** Screen-id (kurz, unqualified). Boot-Validator prüft Existenz im
+         *  selben Feature. */
+        readonly screen: string;
+        readonly entity?: never;
+      }
+    | {
+        /** Entity-Name statt Screen-Id (fw#2228) — löst zur Boot-Zeit auf den
+         *  Screen auf, der `detailFor: "<entity>"` deklariert (siehe ObjectTarget/
+         *  resolveTarget in @cosmicdrift/kumiko-renderer's nav.tsx). */
+        readonly entity: string;
+        readonly screen?: never;
+      }
+  );
+
 // ToolbarAction — button in the list header. Three variants: navigate to
 // another screen (e.g. a full-page actionForm), dispatch a handler directly
 // (e.g. "Sync All" without a form), or mount an actionForm in a Drawer
@@ -354,9 +370,10 @@ export type EntityListScreenDefinition = {
 // User-toggleable facet dropdown on a projectionList screen (fw#2224).
 // entityList derives the same UI from `filterable: true` entity fields plus
 // the `<feature>:entity:<entity>:field:<field>:option:<value>` i18n
-// convention — a projectionList has no entity to derive from, so every
-// label here is explicit instead. Sent to the server as
-// `{field, op:"in", value}` in `payload.filters`, ANDed with `filter`.
+// convention. Labels here (`label`, `options[].label`, `trueLabel`/
+// `falseLabel`) are i18n keys resolved via `translate()` with passthrough
+// for unknown keys (fw#2373) — not raw display strings. Sent to the server
+// as `{field, op:"in", value}` in `payload.filters`, ANDed with `filter`.
 export type ListFacetSpec =
   | {
       readonly field: string;
@@ -609,14 +626,13 @@ export type EditFieldSpec =
       readonly readOnly?: FieldCondition;
       readonly required?: FieldCondition;
       readonly renderer?: FieldRenderer;
-      /** Prefix icon on the input — symbolic key into the FIELD_ICONS
-       *  registry (renderer-web), analogous to `ScreenNavSugar.icon`.
-       *  Unknown key → no icon (clean fallback, no boot-fail). Only takes
-       *  effect for single-line `type: "text"` and `"number"` — a `text`
-       *  field with `multiline` routes to a textarea (no icon slot), and
-       *  other input kinds (select, combobox, date, …) silently ignore
-       *  the key. */
-      readonly icon?: string;
+      /** Prefix icon on the input — closed FieldIconKey vocabulary into
+       *  the FIELD_ICONS registry (renderer-web), analogous to
+       *  `ScreenNavSugar.icon` / NavIconKey. Only takes effect for
+       *  single-line `type: "text"` and `"number"` — a `text` field with
+       *  `multiline` routes to a textarea (no icon slot), and other input
+       *  kinds (select, combobox, date, …) silently ignore the key. */
+      readonly icon?: FieldIconKey;
     };
 
 // A section is a normal field-grid (default — `kind` omitted keeps every