@cosmicdrift/kumiko-types 0.306.0 → 0.308.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.306.0",
+  "version": "0.308.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>",
@@ -174,6 +174,10 @@
       "types": "./src/nav-icon.ts",
       "default": "./src/nav-icon.ts"
     },
+    "./action-icon": {
+      "types": "./src/action-icon.ts",
+      "default": "./src/action-icon.ts"
+    },
     "./field-icon": {
       "types": "./src/field-icon.ts",
       "default": "./src/field-icon.ts"

package/src/action-icon.ts

@@ -0,0 +1,57 @@
+import type { IconKey } from "./nav-icon";
+
+// Part B (fw-ui-defaults): id-derived default icon for actions that never
+// declared one — a screen author still gets a recognizable glyph instead of
+// a bare label. Checked against the actually registered IconKey vocabulary
+// (nav-icon.ts) — no entry for verbs without a matching icon (e.g. "start",
+// "pause").
+export const ACTION_ICON_BY_ID: Readonly<Partial<Record<string, IconKey>>> = {
+  delete: "trash",
+  deletion: "trash",
+  edit: "pencil",
+  create: "plus",
+  new: "plus",
+  add: "plus",
+  view: "eye",
+  open: "eye",
+  cancel: "x",
+  reject: "x",
+  complete: "check",
+  resolve: "check",
+  approve: "check",
+  archive: "archive",
+  publish: "upload",
+  duplicate: "copy",
+  copy: "copy",
+  download: "download",
+  refresh: "refresh",
+  retry: "refresh",
+  settings: "settings",
+  share: "share",
+  send: "send",
+};
+
+// Ids are kebab-case (RowAction.id doc): aggregate-object-verb
+// ("order-ship") or verb-prefix ("add-item").
+function kebabLastSegment(id: string): string {
+  const idx = id.lastIndexOf("-");
+  return idx === -1 ? id : id.slice(idx + 1);
+}
+
+function kebabFirstSegment(id: string): string {
+  const idx = id.indexOf("-");
+  return idx === -1 ? id : id.slice(0, idx);
+}
+
+// Resolution order: author-declared `icon` wins, then the id-derived
+// default (full id, then its last kebab segment, then its first kebab
+// segment). `declared` is `undefined` for ToolbarAction, which has no
+// author-facing icon field.
+export function resolveActionIcon(id: string, declared?: IconKey): IconKey | undefined {
+  if (declared !== undefined) return declared;
+  return (
+    ACTION_ICON_BY_ID[id] ??
+    ACTION_ICON_BY_ID[kebabLastSegment(id)] ??
+    ACTION_ICON_BY_ID[kebabFirstSegment(id)]
+  );
+}

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.308.0",
+    "type": "improvement",
+    "title": "EditFieldsSection/EditExtensionSection/EditRelatedListSection/EditWriteFormSection gain actions; EditRelatedListSection gains emptyState; number fields gain grouping (fw#3234)",
+    "detail": "All four Edit*Section spec types accept an optional `actions?: readonly RowAction[]`, resolved and rendered in that section's own title row. EditRelatedListSection additionally accepts `emptyState?: { title, description?, action? }` for its zero-rows state. A number field spec accepts `grouping?: boolean` (default true) — false renders without thousands separators. Every projectionDetail/entityEdit-tabs screen/section/emptyState action must resolve an icon (declared `icon`, or the framework's id-derived default via resolveActionIcon) — checked by the boot validator (see @cosmicdrift/kumiko-framework's changes.json).",
+    "migration": "Additive — every field is optional. An existing screen/section/emptyState action on a projectionDetail (or entityEdit's section-level actions) whose id resolves no icon and declares none itself now fails boot; give it an explicit `icon` or an id the shared action-icon map already resolves."
+  },
   {
     "version": "0.290.0",
     "type": "improvement",

package/src/define-handler.ts

@@ -1,4 +1,5 @@
-import type { ZodType, z } from "zod";
+import type * as z from "zod";
+import type { ZodType } from "zod";
 import type { KumikoEventTypeMap } from "./event-type-map";
 import type {
   AccessRule,

package/src/event-store-types.ts

@@ -45,8 +45,23 @@ export type EventMetadata = {
   // every new row carries both, falling back to UNATTRIBUTED_ORIGIN.
   readonly feature?: string;
   readonly handler?: string;
+  // Only set under an anonymous root without public-intake, so event-triggered
+  // jobs keep the personal-data gate.
+  readonly writeOrigin?: WriteOrigin;
 };
 
+export type WriteOrigin = {
+  readonly rootHandler: string;
+  readonly anonymousRoot: boolean;
+  // Only a write-handler root can declare public-intake; a query/stream root never does.
+  readonly publicIntake: boolean;
+  readonly viaJob?: string;
+};
+
+export function isPersonalDataGated(origin: WriteOrigin): boolean {
+  return origin.anonymousRoot && !origin.publicIntake;
+}
+
 // Stamped when an append runs outside any attributed scope (seed scripts,
 // tests, direct event-store use). A distinct value, not an omission —
 // omitted would be indistinguishable from a pre-#3043 row.

package/src/feature.ts

@@ -1,4 +1,5 @@
-import type { ZodType, z } from "zod";
+import type * as z from "zod";
+import type { ZodType } from "zod";
 import type {
   ConfigKeyDefinition,
   ConfigKeyHandle,

package/src/fields.ts

@@ -395,6 +395,10 @@ export type NumberFieldDef = {
   /** Display-only suffix: a static string, or a sibling field name whose
    *  value supplies it. Never converts the stored number. */
   readonly unit?: string | { readonly field: string };
+  /** Thousands-grouping in the rendered display (Intl `useGrouping`).
+   *  Default `true`. Set `false` for values that read wrong grouped (e.g. a
+   *  model year: "2021", not "2.021"). Never affects the stored value. */
+  readonly grouping?: boolean;
 } & ResolvedPiiFlags;
 
 /**

package/src/handlers.ts

@@ -4,6 +4,7 @@ import type { ConfigAccessor, ConfigAccessorFactory, ConfigResolver } from "./co
 import type { DbConnection } from "./db-connection";
 import type { DerivativesContext } from "./derivatives-types";
 import type { EntityCache } from "./entity-cache";
+import type { WriteOrigin } from "./event-store-types";
 import type { KumikoEventTypeMap } from "./event-type-map";
 import type { FileContext } from "./file-handle-types";
 import type { FileProviderResolver } from "./file-provider-resolver-types";
@@ -260,8 +261,20 @@ export type JobRunnerRef = {
 // singleton, not bound to one caller's identity. Only write+queryAs — no
 // .query/.stream/.command/.batch/.resolveAuthClaims, that stays Dispatcher-only.
 export type DispatchWriteRef = {
-  readonly write: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
-  readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+  // A job under a gated anonymous origin passes it, else the target would
+  // reset to the job's own non-anonymous root.
+  readonly write: (
+    user: SessionUser,
+    qn: string,
+    payload: unknown,
+    inheritedOrigin?: WriteOrigin,
+  ) => Promise<WriteResult>;
+  readonly queryAs: (
+    user: SessionUser,
+    qn: string,
+    payload: unknown,
+    inheritedOrigin?: WriteOrigin,
+  ) => Promise<unknown>;
   // Builds a tenant-scoped MemberReader — one per JobContext.queryAsMember
   // caller (job-runner.ts lazily creates one per job run).
   readonly createMemberReader: (tenantId: TenantId) => MemberReader;

package/src/nav-icon.ts

@@ -8,88 +8,97 @@
 // 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 NavIconKey =
-  | "dashboard"
-  | "layout-grid"
-  | "book-open"
-  | "clipboard-list"
-  | "package"
-  | "gauge"
-  | "list"
-  | "table"
-  | "layers"
-  | "building"
-  | "calculator"
-  | "wallet"
-  | "coins"
-  | "credit-card"
-  | "piggy-bank"
-  | "receipt"
-  | "chart"
-  | "bar-chart"
-  | "trending"
-  | "sparkles"
-  | "wand"
-  | "calendar"
-  | "file"
-  | "folder"
-  | "folder-open"
-  | "home"
-  | "bell"
-  | "shield"
-  | "shield-check"
-  | "send"
-  | "settings"
-  | "users"
-  | "user"
-  | "search"
-  | "tag"
-  | "key"
-  | "link"
-  | "palette"
-  | "share"
-  | "server"
-  | "mail"
-  | "lock"
-  | "hash"
-  | "download"
-  | "upload"
-  | "rocket"
-  | "plus"
-  | "languages"
-  | "trash"
-  | "x"
-  | "check"
-  | "arrow-left"
-  | "arrow-right"
-  | "copy"
-  | "pencil"
-  | "eye"
-  | "eye-off"
-  | "filter"
-  | "refresh"
-  | "more-horizontal"
-  | "more-vertical"
-  | "external-link"
-  | "chevron-down"
-  | "chevron-right"
-  | "save"
-  | "undo"
-  | "archive"
-  | "star"
-  | "flag"
-  | "clock"
-  | "map-pin"
-  | "phone"
-  | "printer"
-  | "alert-triangle"
-  | "info"
-  | "check-circle"
-  | "x-circle"
-  | "loader"
-  | "mic"
-  | "circle-stop"
-  | "image";
+//
+// Declared as a runtime tuple (not just a type) so callers that sit outside
+// this repo's `tsc --build` project graph (e.g. samples, external consumers
+// resolving from a stale published type) still get a runtime-checkable
+// vocabulary — the boot-validator's validateActionHasIcon checks a declared
+// icon against NAV_ICON_KEYS instead of trusting "not undefined".
+export const NAV_ICON_KEYS = [
+  "dashboard",
+  "layout-grid",
+  "book-open",
+  "clipboard-list",
+  "package",
+  "gauge",
+  "list",
+  "table",
+  "layers",
+  "building",
+  "calculator",
+  "wallet",
+  "coins",
+  "credit-card",
+  "piggy-bank",
+  "receipt",
+  "chart",
+  "bar-chart",
+  "trending",
+  "sparkles",
+  "wand",
+  "calendar",
+  "file",
+  "folder",
+  "folder-open",
+  "home",
+  "bell",
+  "shield",
+  "shield-check",
+  "send",
+  "settings",
+  "users",
+  "user",
+  "search",
+  "tag",
+  "key",
+  "link",
+  "palette",
+  "share",
+  "server",
+  "mail",
+  "lock",
+  "hash",
+  "download",
+  "upload",
+  "rocket",
+  "plus",
+  "languages",
+  "trash",
+  "x",
+  "check",
+  "arrow-left",
+  "arrow-right",
+  "copy",
+  "pencil",
+  "eye",
+  "eye-off",
+  "filter",
+  "refresh",
+  "more-horizontal",
+  "more-vertical",
+  "external-link",
+  "chevron-down",
+  "chevron-right",
+  "save",
+  "undo",
+  "archive",
+  "star",
+  "flag",
+  "clock",
+  "map-pin",
+  "phone",
+  "printer",
+  "alert-triangle",
+  "info",
+  "check-circle",
+  "x-circle",
+  "loader",
+  "mic",
+  "circle-stop",
+  "image",
+] as const;
+
+export type NavIconKey = (typeof NAV_ICON_KEYS)[number];
 
 // Alias kept because the union stopped being nav-only — actions and fields
 // (added on this branch) also key their icons against it.

package/src/screen.ts

@@ -55,9 +55,11 @@ export interface FieldFormatRegistry {
   boolean: { readonly trueLabel?: string; readonly falseLabel?: string };
   currency: { readonly symbol?: string };
   priority: { readonly emptyLabel?: string; readonly prefix?: string };
-  number: { readonly locale?: string };
-  decimal: { readonly locale?: string };
-  bigInt: { readonly locale?: string };
+  /** `grouping: false` renders without thousands-separators (e.g. a model
+   *  year: "2021", not "2.021"). Default `true`. */
+  number: { readonly locale?: string; readonly grouping?: boolean };
+  decimal: { readonly locale?: string; readonly grouping?: boolean };
+  bigInt: { readonly locale?: string; readonly grouping?: boolean };
   // 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: {
@@ -925,6 +927,11 @@ export type EditFieldsSection = {
    *  Ignored outside tabs mode or when the field's value is not a finite
    *  number. */
   readonly countField?: string;
+  /** Rendered top-right in the section's Card title row — same
+   *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
+   *  evaluated against the same record. Every action must resolve an icon
+   *  (declared or id-derived); the boot-validator rejects one that doesn't. */
+  readonly actions?: readonly RowAction[];
 };
 
 export type EditExtensionSection = {
@@ -951,6 +958,11 @@ export type EditExtensionSection = {
    *  Ignored outside tabs mode or when the field's value is not a finite
    *  number. */
   readonly countField?: string;
+  /** Rendered top-right in the section's Card title row — same
+   *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
+   *  evaluated against the same record. Every action must resolve an icon
+   *  (declared or id-derived); the boot-validator rejects one that doesn't. */
+  readonly actions?: readonly RowAction[];
 };
 
 // Read-only list of related records, driven by its own query — for a
@@ -1019,6 +1031,22 @@ export type EditRelatedListSection = {
    *  Ignored outside tabs mode or when the field's value is not a finite
    *  number. */
   readonly countField?: string;
+  /** Rendered top-right in the section's Card title row — same
+   *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
+   *  evaluated against the parent record. Every action must resolve an icon
+   *  (declared or id-derived); the boot-validator rejects one that doesn't.
+   *  Distinct from `toolbarActions` (rendered inside the DataTable toolbar) —
+   *  this is the Card-level title-row action. */
+  readonly actions?: readonly RowAction[];
+  /** Rendered inside the section's Card in place of the table when this
+   *  section's query returns zero rows. Omitted: the DataTable default
+   *  ("kumiko.list.no-entries") applies. `action`'s icon must resolve, same
+   *  as `actions` above. */
+  readonly emptyState?: {
+    readonly title: string;
+    readonly description?: string;
+    readonly action?: RowAction;
+  };
 };
 
 // A declarative, self-persisting form section for `projectionDetail`
@@ -1057,6 +1085,11 @@ export type EditWriteFormSection = {
   readonly handler: string;
   /** i18n-key for the submit button. Default: "kumiko.actions.save". */
   readonly submitLabel?: string;
+  /** Rendered top-right in the section's Card title row — same
+   *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
+   *  evaluated against the same record. Every action must resolve an icon
+   *  (declared or id-derived); the boot-validator rejects one that doesn't. */
+  readonly actions?: readonly RowAction[];
 };
 
 // Max width of the form container (see FormScreenShell in renderer-web).

package/src/search-adapter.ts

@@ -24,6 +24,12 @@ export type SearchOptions = {
 
 export type SearchAdapter = {
   configure(tenantId: TenantId, config: SearchAdapterConfig): Promise<void>;
+  // The adapter is built before the registry exists (app boot order), so it
+  // can't derive this itself. The framework hands it the registry-derived
+  // config once the registry is available; the adapter uses it to configure
+  // each tenant index lazily on that tenant's first access instead of
+  // requiring every app to call `configure` per tenant up front.
+  setDefaultConfig?(config: SearchAdapterConfig): void;
   index(tenantId: TenantId, doc: SearchDocument): Promise<void>;
   search(tenantId: TenantId, query: string, options?: SearchOptions): Promise<SearchResult[]>;
   remove(tenantId: TenantId, entityType: string, entityId: EntityId): Promise<void>;