@cosmicdrift/kumiko-types 0.359.0 → 0.361.0

package/dist/config.d.ts

@@ -145,6 +145,7 @@ export type JobTrigger = {
     readonly where?: Readonly<Record<string, string | number | boolean>>;
 } | {
     readonly cron: string;
+    readonly tz?: string;
 } | {
     readonly manual: true;
 };

package/dist/event-store-executor-types.d.ts

@@ -12,6 +12,15 @@ export type PreSaveRunner = (changes: Record<string, unknown>, previous: Readonl
 export type StreamTenantOption = {
     readonly streamTenantId?: TenantId | undefined;
 };
+export declare const WritePurposes: {
+    readonly retention: "retention";
+    readonly erasure: "erasure";
+};
+export type WritePurpose = (typeof WritePurposes)[keyof typeof WritePurposes];
+export type LockGuardOption = {
+    readonly unsafeSkipLockGuard?: boolean;
+    readonly writePurpose?: WritePurpose;
+};
 export type EventStoreExecutor = {
     create: (payload: Record<string, unknown>, user: SessionUser, db: TenantDb, options?: StreamTenantOption & {
         preSave?: PreSaveRunner;
@@ -20,7 +29,7 @@ export type EventStoreExecutor = {
         id: EntityId;
         version?: number | undefined;
         changes: Record<string, unknown>;
-    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & {
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & LockGuardOption & {
         skipOptimisticLock?: boolean;
         skipUnchanged?: boolean;
         includeDeleted?: boolean;
@@ -29,7 +38,7 @@ export type EventStoreExecutor = {
     }) => Promise<WriteResult<SaveContext>>;
     delete: (payload: {
         id: EntityId;
-    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption) => Promise<WriteResult<DeleteContext>>;
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & LockGuardOption) => Promise<WriteResult<DeleteContext>>;
     forget: (payload: {
         id: EntityId;
     }, user: SessionUser, db: TenantDb, options?: StreamTenantOption) => Promise<WriteResult<DeleteContext>>;

package/dist/event-store-executor-types.js

@@ -1 +1,3 @@
-export {};
+// Why a framework system-user write may reach a locked row. Statutory deletion (retention)
+// and Art. 17 erasure must succeed on locked rows; any other system write stays blocked.
+export const WritePurposes = { retention: "retention", erasure: "erasure" };

package/dist/fields.d.ts

@@ -472,6 +472,9 @@ export type EmbeddedSubFieldDef = (EmbeddedSubFieldBase & {
 }) | (EmbeddedSubFieldBase & {
     readonly type: "select";
     readonly options: readonly string[];
+    /** Same contract as `SelectFieldDef.display`; in a table cell the
+     *  default stays a dropdown. */
+    readonly display?: "radio" | "dropdown";
 }) | (EmbeddedSubFieldBase & {
     readonly type: "reference";
     readonly entity: string;
@@ -641,6 +644,9 @@ export type ImagesFieldDef = {
     readonly accept?: readonly string[];
     readonly maxCount?: number;
     readonly variants?: Readonly<Record<string, VariantSpec>>;
+    /** Forwarded to the file input's `capture` attribute so a phone opens the
+     *  camera instead of the file picker. */
+    readonly capture?: "environment" | "user";
     readonly access?: FieldAccess;
 } & ResolvedPiiFlags;
 export type FieldDefinition = TextFieldDef | LongTextFieldDef | BooleanFieldDef | SelectFieldDef | MultiSelectFieldDef | NumberFieldDef | BigIntFieldDef | DecimalFieldDef | MoneyFieldDef | ReferenceFieldDef | EmbeddedFieldDef | JsonbFieldDef | DateFieldDef | TimestampFieldDef | TzFieldDef | LocatedTimestampFieldDef | FileFieldDef | ImageFieldDef | FilesFieldDef | ImagesFieldDef;
@@ -748,6 +754,15 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
     readonly eventMigrations?: readonly EntityEventMigration[];
     readonly searchWeight?: number;
     readonly defaultCurrency?: string;
+    /** Rows whose stored state meets this condition are read-only: every executor
+     *  update and delete on them is rejected with a 409 (`errors.recordLocked`), whatever
+     *  handler or job calls it. The write that sets the lock passes, because the check reads the
+     *  state before the write. Forget is exempt, and so are framework system-user writes that name
+     *  a `writePurpose` (retention, erasure); a system user without one is blocked like anyone else.
+     *  A call site that must unlock a row passes `{ unsafeSkipLockGuard: true }` to that one executor call. The entityEdit
+     *  screen shows such rows in view mode. The condition field must be a plaintext text, select,
+     *  boolean, number or reference field. */
+    readonly lockedWhen?: FieldCondition;
     /** Allowed state transitions per field. Boot validates against select options. */
     readonly transitions?: Readonly<Record<string, TransitionMap>>;
     /** Composite-Indices über mehrere Felder. Single-column FK-Indices und

package/dist/fields.js

@@ -52,9 +52,4 @@ export const FIELD_TYPE_NAMES = Object.keys(FIELD_TYPE_NAME_FLAGS);
 // A plain array, not a Set: kumiko-types stays free of module-scope runtime
 // identity (guard-types-class-free.test.ts) since a consumer may resolve two
 // copies of this package.
-export const NO_WIDGET_FIELD_TYPES = [
-    "jsonb",
-    "embedded",
-    "files",
-    "images",
-];
+export const NO_WIDGET_FIELD_TYPES = ["jsonb", "embedded"];

package/dist/screen.d.ts

@@ -55,6 +55,15 @@ export interface FieldFormatRegistry {
     json: {
         readonly indent?: number;
     };
+    /** List cell: FileRef id (or id array) as a thumbnail. `variant` names an
+     *  image variant to request (falls back to the original if it is not served).
+     *  Outside list cells the raw value is shown. */
+    image: {
+        readonly variant?: string;
+    };
+    /** List cell: FileRef id (or id array) as a download link with the file name.
+     *  Outside list cells the raw value is shown. */
+    file: object;
 }
 export type FormatSpec = {
     [K in keyof FieldFormatRegistry]: {
@@ -440,6 +449,8 @@ export type EntityListScreenDefinition = {
      *  through `defaultFilters` and the URL). Fields without an entry keep the
      *  default dropdown. */
     readonly facets?: Readonly<Record<string, EntityListFacetConfig | false>>;
+    /** Replaces the default empty-list title/hint; the create button stays when the list can create. */
+    readonly emptyState?: ListEmptyStateSpec;
     /** i18n key for the primary create button label (default `kumiko.actions.create`). */
     readonly createLabel?: string;
     /** i18n key for the search field placeholder (default `kumiko.list.search-placeholder`). */
@@ -519,6 +530,8 @@ export type ProjectionListScreenDefinition = {
     readonly pagination?: ListPaginationMode;
     readonly pageSize?: number;
     readonly defaultSort?: ListSortSpec;
+    /** Replaces the default empty-list title/hint; the create button stays when the list can create. */
+    readonly emptyState?: ListEmptyStateSpec;
     /** i18n key for the primary create button label (default `kumiko.actions.create`). */
     readonly createLabel?: string;
     /** i18n key for the search field placeholder (default `kumiko.list.search-placeholder`). */
@@ -562,7 +575,10 @@ export type RecordHeaderSpec = {
      *  (`target="_blank"`) instead of plain text. Only valid with the string
      *  form of `subtitle`. */
     readonly subtitleHref?: string;
-    /** Badge tone per `status` field value; unlisted values fall back to the value heuristic. */
+    /** Record field whose value selects the `statusTones` entry, for a badge text that
+     *  carries more than the state (e.g. "Terminated on 31.03.2027"). Defaults to `status`. */
+    readonly statusToneField?: string;
+    /** Badge tone per `statusToneField` value (default: the `status` value); unlisted values fall back to the value heuristic. */
     readonly statusTones?: {
         readonly [statusValue: string]: SelectOptionTone;
     };
@@ -642,6 +658,12 @@ export type ProjectionDetailScreenDefinition = {
      *  `rowClick` has no target here (there is no row to click) and is
      *  rejected by the boot-validator. */
     readonly actions?: readonly RowAction[];
+    /** Id of the action that stays the visible header button when the actions
+     *  collapse into a menu (and the one that keeps the phone icon slot when it
+     *  has an icon and no confirm). An `actions` id or `"edit"` (the default edit
+     *  action); default precedence is `edit`, then `style: "primary"`, then the
+     *  first action. */
+    readonly primaryAction?: string;
     /** How head fields render. Default "text" — plain text instead of a
      *  disabled Input, since every field on this screen type is forced
      *  readOnly anyway (there is no write path, see the shim doc above).
@@ -934,6 +956,25 @@ export type EditFieldSpec = string | {
     /** Row field on the referenced entity shown as the label (default
      *  "id"). Only meaningful together with `refEntity`. */
     readonly refLabelField?: string;
+    /** Embedded-list fields only (`createEmbeddedListField`). */
+    readonly embeddedList?: EmbeddedListEditSpec;
+    /** Fills an empty value when the create form opens; the update form and
+     *  values from URL params or a handoff are never touched. Unlike a
+     *  field `default`, it is not applied server-side. */
+    readonly prefill?: EditFieldPrefill;
+};
+export type EmbeddedListEditSpec = {
+    /** Sub-fields shown as read-only cells; every other cell stays editable. */
+    readonly readOnlyCells?: readonly string[];
+    /** `true` keeps the rows as they are: no add, remove, duplicate, move or
+     *  paste-appended rows. Cells stay editable (unless in `readOnlyCells`). */
+    readonly fixedRows?: boolean;
+};
+export type EditFieldPrefill = {
+    readonly kind: "today";
+} | {
+    readonly kind: "currentUser";
+    readonly property: "displayName" | "email" | "id";
 };
 export type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection;
 export type EditFieldsSection = {
@@ -1037,6 +1078,16 @@ export declare function relatedListGroupHeaderLabel(groupBy: RelatedListGroupBy,
 export type RelatedListRowTone = Exclude<FieldCondition, boolean> & {
     readonly tone: SelectOptionTone;
 };
+/** Replacement for the default "no rows" box of a list. `title`/`description`
+ *  are i18n keys. `action` is a record action evaluated against an empty
+ *  record on list screens (the parent record on a relatedList); its icon must
+ *  resolve, same as `ProjectionDetailScreenDefinition.actions`. A narrowed list
+ *  (search term or changed filters) shows the neutral "no matches" text instead. */
+export type ListEmptyStateSpec = {
+    readonly title: string;
+    readonly description?: string;
+    readonly action?: RowAction;
+};
 export type EditRelatedListSection = {
     /** Kebab-case tab id, used as the `?tab=` value. Required by the
      *  boot-validator when the enclosing `EditLayout.mode` is "tabs". */
@@ -1137,11 +1188,7 @@ export type EditRelatedListSection = {
      *  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;
-    };
+    readonly emptyState?: ListEmptyStateSpec;
 };
 export type EditWriteFormSection = {
     /** Kebab-case tab id, used as the `?tab=` value. Required by the
@@ -1246,6 +1293,14 @@ export type EntityEditScreenDefinition = {
      *  wizard: "Add {make} {model}"). Falls back to the plain title while the
      *  placeholders are still empty. */
     readonly titleTemplate?: string;
+    /** Shows a saved record read-only while the condition holds for the loaded
+     *  record (not for unsaved form values): all fields disabled, no save, discard
+     *  or delete button; record `actions` stay. The title uses
+     *  `screen:<id>.view.title`, then `screen:<id>.title`. Never applies to create.
+     *  The entity's `lockedWhen` always applies as well; set this only to add a
+     *  UI-only condition (either one shows the view).
+     *  UI only: the update handler still has to enforce access. */
+    readonly readOnly?: FieldCondition;
     readonly layout: EditLayout;
     /** Optionaler i18n-Key (oder Roh-String) für den Submit-Button. Default
      *  `kumiko.actions.save`. Lässt den Auto-Edit-Screen domain-spezifische
@@ -1449,6 +1504,10 @@ export type ActionFormRedirect = {
      *  `projectionDetail`); a non-string or missing value navigates without
      *  an id, same as a payload without `id` does today. */
     readonly idFrom: string;
+    /** Section id to open on the target `projectionDetail` with `layout.mode:
+     *  "tabs"` (the `tab` search param, same as `ToolbarAction` navigate `tab`).
+     *  Boot rejects other targets and unknown section ids. */
+    readonly tab?: string;
 };
 /** Author-declared field shown once after a mint-form submit — API token,
  *  recovery codes, similar one-time secrets. */

package/dist/session-cookies.d.ts

@@ -0,0 +1,20 @@
+export declare const AUTH_COOKIE_BASE = "kumiko_auth";
+export declare const CSRF_COOKIE_BASE = "kumiko_csrf";
+export declare const TENANT_COOKIE_BASE = "kumiko_tenant";
+export declare const HOST_COOKIE_PREFIX = "__Host-";
+export type SessionCookieBase = typeof AUTH_COOKIE_BASE | typeof CSRF_COOKIE_BASE | typeof TENANT_COOKIE_BASE;
+export type SessionCookieNames = {
+    readonly auth: string;
+    readonly csrf: string;
+    readonly tenant: string;
+};
+export declare function sessionCookieName(base: SessionCookieBase, options: {
+    readonly secure: boolean;
+    readonly domain?: string | undefined;
+}): string;
+export declare function isHostPrefixedCookieName(name: string): boolean;
+export declare function resolveSessionCookieNames(options: {
+    readonly secure: boolean;
+    readonly domain?: string | undefined;
+}): SessionCookieNames;
+export declare function sessionCookieNameCandidates(base: SessionCookieBase): readonly string[];

package/dist/session-cookies.js

@@ -0,0 +1,31 @@
+// Single source of the session cookie names, shared by the server and by
+// browser/native clients (this package has no server dependencies).
+//
+// A cookie gets the `__Host-` prefix exactly when it is written Secure and
+// without a Domain attribute: the browser then refuses any Set-Cookie for that
+// name that is not Secure, Path=/ and host-only, so a sibling subdomain cannot
+// set or shadow it.
+export const AUTH_COOKIE_BASE = "kumiko_auth";
+export const CSRF_COOKIE_BASE = "kumiko_csrf";
+export const TENANT_COOKIE_BASE = "kumiko_tenant";
+export const HOST_COOKIE_PREFIX = "__Host-";
+export function sessionCookieName(base, options) {
+    return options.secure && options.domain === undefined ? `${HOST_COOKIE_PREFIX}${base}` : base;
+}
+export function isHostPrefixedCookieName(name) {
+    return name.startsWith(HOST_COOKIE_PREFIX);
+}
+// The tenant cookie is always host-only, so a cookieDomain only affects the
+// auth and csrf names.
+export function resolveSessionCookieNames(options) {
+    return {
+        auth: sessionCookieName(AUTH_COOKIE_BASE, options),
+        csrf: sessionCookieName(CSRF_COOKIE_BASE, options),
+        tenant: sessionCookieName(TENANT_COOKIE_BASE, { secure: options.secure }),
+    };
+}
+// Browser-side candidates, preferred first. The client cannot know the server
+// config; when both cookies exist the prefixed one is the trustworthy one.
+export function sessionCookieNameCandidates(base) {
+    return [sessionCookieName(base, { secure: true }), sessionCookieName(base, { secure: false })];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.359.0",
+  "version": "0.361.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>",
@@ -26,6 +26,10 @@
       "types": "./dist/identifiers.d.ts",
       "default": "./dist/identifiers.js"
     },
+    "./session-cookies": {
+      "types": "./dist/session-cookies.d.ts",
+      "default": "./dist/session-cookies.js"
+    },
     "./target-ref": {
       "types": "./dist/target-ref.d.ts",
       "default": "./dist/target-ref.js"
@@ -293,6 +297,10 @@
         "types": "./dist/identifiers.d.ts",
         "default": "./dist/identifiers.js"
       },
+      "./session-cookies": {
+        "types": "./dist/session-cookies.d.ts",
+        "default": "./dist/session-cookies.js"
+      },
       "./target-ref": {
         "types": "./dist/target-ref.d.ts",
         "default": "./dist/target-ref.js"

package/src/changes.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "EditFieldSpec.prefill",
+    "detail": "New EditFieldPrefill, today or currentUser with displayName, email or id, on the object form of EditFieldSpec."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "entityEdit screens accept a readOnly condition",
+    "detail": "EntityEditScreenDefinition.readOnly is a FieldCondition evaluated against the loaded record. UI only, the server is not affected."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "EditFieldSpec.embeddedList for read-only cells and fixed rows",
+    "detail": "New EmbeddedListEditSpec with readOnlyCells and fixedRows on the object form of EditFieldSpec."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "display on embedded select sub-fields",
+    "detail": "The select variant of EmbeddedSubFieldDef accepts display radio or dropdown."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "EntityDefinition.lockedWhen and the executor options unsafeSkipLockGuard and writePurpose",
+    "detail": "lockedWhen is a FieldCondition evaluated against the stored row. update and delete on the EventStoreExecutor take unsafeSkipLockGuard to opt one call out, and writePurpose (WritePurposes.retention or erasure) lets the framework system user through. EntityEditScreenDefinition.readOnly is combined with the entity's lockedWhen (either shows the view)."
+  },
   {
     "version": "0.357.0",
     "type": "improvement",