@cosmicdrift/kumiko-types 0.377.0 → 0.379.0

package/dist/config.d.ts

@@ -219,7 +219,10 @@ export type TemplateListVariableDef = TemplateVariableCommon & {
     readonly item: Readonly<Record<string, TemplateScalarVariableDef>>;
     readonly example?: readonly Readonly<Record<string, unknown>>[];
 };
-export type TemplateVariableDef = TemplateScalarVariableDef | TemplateListVariableDef;
+export type TemplateImagesVariableDef = TemplateVariableCommon & {
+    readonly type: "images";
+};
+export type TemplateVariableDef = TemplateScalarVariableDef | TemplateListVariableDef | TemplateImagesVariableDef;
 export type TemplateVariables = Readonly<Record<string, TemplateVariableDef>>;
 export type NotificationTemplateMeta = {
     readonly subject: string;

package/dist/fields.d.ts

@@ -489,7 +489,12 @@ export type EmbeddedSubFieldDef = (EmbeddedSubFieldBase & {
  *  precision its target sub-field in `schema` declares (money → integer,
  *  decimal → `scale`) before it's validated. */
 export type EmbeddedDerivedCellDef = {
-    readonly op: "multiply" | "sum" | "subtract";
+    /** `percent` = `from[0] * from[1] / 100` (exactly two sources, e.g. amount and rate). */
+    readonly op: "multiply" | "sum" | "subtract" | "percent";
+    readonly from: readonly string[];
+};
+export type EmbeddedTotalDef = string | {
+    readonly label: string;
     readonly from: readonly string[];
 };
 export type EmbeddedFieldDef = {
@@ -518,9 +523,12 @@ export type EmbeddedFieldDef = {
      *  sub-fields of the same row, rounded to that sub-field's declared
      *  precision. Only valid with `multiple: true`. */
     readonly derived?: Readonly<Record<string, EmbeddedDerivedCellDef>>;
-    /** Renderer metadata: numeric sub-field names to sum in a totals row. Only
-     *  valid with `multiple: true`. */
-    readonly totals?: readonly string[];
+    /** Renderer metadata: footer totals. A string is the sum of that numeric
+     *  sub-field under the column label; an object shows the sum of all `from`
+     *  sub-fields under its own i18n `label` (e.g. net, VAT, gross). Display
+     *  only; the server derivation is unchanged. Only valid with
+     *  `multiple: true`. */
+    readonly totals?: readonly EmbeddedTotalDef[];
     /** Maps an embedded-list subfield name to a sibling top-level money field
      *  name — the sum of that subfield across all rows must equal the sibling
      *  field's amount. Validated both client- and server-side (schema-builder
@@ -636,6 +644,10 @@ export type FilesFieldDef = {
     readonly maxSize?: string;
     readonly accept?: readonly string[];
     readonly maxCount?: number;
+    /** `"list"` (default) shows the picked files as a list with a file picker; `"dropzone"` shows a
+     *  drag-and-drop zone with one status row per file, a remove action per file and the field's
+     *  `maxCount`/`accept`/`maxSize` as hints. The stored value is the same array of FileRef ids. */
+    readonly display?: "list" | "dropzone";
     readonly access?: FieldAccess;
 } & ResolvedPiiFlags;
 export type ImagesFieldDef = {
@@ -644,6 +656,10 @@ export type ImagesFieldDef = {
     readonly maxSize?: string;
     readonly accept?: readonly string[];
     readonly maxCount?: number;
+    /** `"list"` (default) shows the picked files as a list with a file picker; `"dropzone"` shows a
+     *  drag-and-drop zone with one status row per file, a remove action per file and the field's
+     *  `maxCount`/`accept`/`maxSize` as hints. The stored value is the same array of FileRef ids. */
+    readonly display?: "list" | "dropzone";
     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. */

package/dist/handlers.d.ts

@@ -232,7 +232,7 @@ type SharedContextFields = {
     readonly forTenant?: (tenantId: TenantId) => TenantWriteTarget;
     /** Mints the per-request `ctx.config`; set by the boot (`addConfigAccessorFactory`) from the effective `configResolver`, overriding an app-supplied value. */
     readonly configAccessorFactory?: ConfigAccessorFactory;
-    /** @deprecated Use `configAccessorFactory`; the underscore name is removed in the next major. */
+    /** @deprecated Use `configAccessorFactory`; the underscore name is removed in 0.390.0. */
     readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly configEncryption?: import("./envelope-cipher-types.ts").EnvelopeCipher;
     readonly rateLimit?: import("./rate-limit-types.ts").RateLimitResolver;
@@ -297,15 +297,12 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
      * Same tenant scoping as `db`, but never bound to the handler's tx: writes through it survive
      * a rollback. `undefined` only in the denial phases (member-resolution, before-transaction)
      * and in platform-metering tenant mode; narrow with `hasOutsideTransactionDb(ctx)` or take it
-     * via `requireOutsideTransactionDb(ctx)` (`@cosmicdrift/kumiko-framework/db`). For
+     * via `requireOutsideTransactionDb(ctx)` (`@cosmicdrift/kumiko-framework/db`). For atomic
+     * multi-statement writes outside the tx use `runInOwnTransaction(ctx.dbOutsideTransaction, fn)`; `fn`
+     * must not touch rows the handler's own tx has locked. For
      * r.systemScope() handlers it is a fail-closed Proxy; use `systemDb.outsideTransaction`.
      */
     readonly dbOutsideTransaction: TenantDb | undefined;
-    /**
-     * @deprecated Use `runInOwnTransaction(ctx.dbOutsideTransaction, fn)` from
-     * `@cosmicdrift/kumiko-framework/db`; removed in the next major.
-     */
-    readonly outsideTransaction?: <T>(fn: (db: TenantDb) => Promise<T>) => Promise<T>;
     readonly systemDb?: UncheckedSystemDb;
     readonly registry: Registry;
     /** Aktiver SessionUser des Handler-Aufrufs — Convenience-Alias zu
@@ -460,7 +457,7 @@ export type EventPiiSubject = {
 } | {
     readonly personal: "self";
 } | {
-    /** @deprecated use `{ personal: { of: "<ownerField>" } }` instead. */
+    /** @deprecated use `{ personal: { of: "<ownerField>" } }` instead. Removed in 0.390.0. */
     readonly subjectField: string;
 };
 export type EventPiiFields = Readonly<Record<string, EventPiiSubject>>;

package/dist/screen.d.ts

@@ -63,8 +63,9 @@ export interface FieldFormatRegistry {
     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. */
+    /** FileRef id (or id array) as a download link with the file name. On a
+     *  read-only detail field it renders a file list with download links and an
+     *  inline preview for PDFs; elsewhere the raw value is shown. */
     file: object;
 }
 export type FormatSpec = {
@@ -924,6 +925,15 @@ export type DashboardTextBlock = {
 } | {
     readonly kind: "hint";
     readonly text: string;
+} | {
+    readonly kind: "link";
+    /** Link label (i18n key). */
+    readonly text: string;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>`. */
+    readonly screen: string;
+    /** Show the link only to users holding one of these roles. Display
+     *  gate only: the target screen's own `access` stays the enforcement. */
+    readonly roles?: readonly string[];
 };
 export type DashboardTextPanel = DashboardPanelGate & {
     readonly kind: "text";
@@ -1522,6 +1532,21 @@ export type EntityEditActionPlacement = "inline" | "menu";
 export type EntityEditAction = RowAction & {
     readonly placement?: EntityEditActionPlacement;
 };
+/** A form field computed from other fields of the same form. `listSum` adds one
+ *  numeric cell over all rows of an embedded list field; its `whenEmpty`
+ *  fallback applies while the list has no rows (it must not be a `listSum`). */
+export type FormFieldDerivation = {
+    readonly op: "sum" | "subtract" | "multiply" | "percent";
+    readonly from: readonly string[];
+} | {
+    readonly op: "listSum";
+    readonly list: string;
+    readonly cell: string;
+    readonly whenEmpty?: FormFieldDerivationWithoutList;
+};
+export type FormFieldDerivationWithoutList = Extract<FormFieldDerivation, {
+    from: unknown;
+}>;
 export type ActionFormScreenDefinition = {
     readonly id: string;
     readonly type: "actionForm";
@@ -1560,6 +1585,13 @@ export type ActionFormScreenDefinition = {
      *  A `money` field here must name its own currency source: this screen
      *  has no entity whose `defaultCurrency` it could inherit (fw#2839). */
     readonly fields: Readonly<Record<string, FormFieldDefinition>>;
+    /** Fields computed from other fields, shown read-only and recomputed on every
+     *  change. A `listSum` over an empty list without `whenEmpty` leaves the field
+     *  a normal input, and then the client value counts. Otherwise the client value
+     *  is never trusted: the handler must wrap its schema with
+     *  `withFormDerivations(schema, screen)`, which the boot validator enforces.
+     *  A field read only as `whenEmpty` operand is read-only while every such list has rows. */
+    readonly derive?: Readonly<Record<string, FormFieldDerivation>>;
     /** Layout analog zu EntityEditScreen: sections mit fields aus dem
      *  fields-Map oben. */
     readonly layout: EditLayout;
@@ -1680,6 +1712,11 @@ export type ActionFormLoad = {
     readonly query: string;
     /** Payload key carrying the record id (default "id"). */
     readonly idParam?: string;
+    /** The query picks the row from the caller's tenant/session context, so the
+     *  form loads without a record id and the query is called WITHOUT `idParam`
+     *  (same semantics as `ProjectionDetailScreenDefinition.singleton`). Boot
+     *  rejects declaring `idParam` alongside it. */
+    readonly singleton?: boolean;
 };
 /** One key figure of the success box, read from the handler's success payload. */
 export type ActionFormSuccessFact = {

package/dist/tenant-db-types.d.ts

@@ -46,6 +46,13 @@ export type TenantDb = {
     selectMany<T = Record<string, unknown>>(table: SchemaTable | EntityTableMeta, where?: WhereObject, options?: SelectOptions): Promise<readonly T[]>;
     fetchOne<T = Record<string, unknown>>(table: SchemaTable | EntityTableMeta, where: WhereObject): Promise<T | undefined>;
     count(table: SchemaTable | EntityTableMeta, where?: WhereObject): Promise<number>;
+    /**
+     * Transaction-scoped advisory lock keyed on (namespace, this handle's tenantId + key); released at
+     * commit or rollback. Keys of different tenants never contend. Only serialises inside a transaction.
+     */
+    advisoryXactLock(namespace: number, key: string): Promise<void>;
+    /** Postgres `now()`; inside a transaction this is the transaction start. */
+    databaseNow(): Promise<Date>;
     aggregate(table: SchemaTable | EntityTableMeta, spec: AggregateSpec, where?: WhereObject): Promise<readonly AggregateRow[]>;
     insertOne<T = Record<string, unknown>>(table: WritableTable, values: Record<string, unknown>): Promise<T | undefined>;
     updateMany<T = Record<string, unknown>>(table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly T[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.377.0",
+  "version": "0.379.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>",

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.379.0",
+    "type": "breaking",
+    "title": "HandlerContext.outsideTransaction removed",
+    "detail": "The deprecated outsideTransaction field no longer exists on HandlerContext. ctx.dbOutsideTransaction together with runInOwnTransaction replaces it.",
+    "migration": "Replace ctx.outsideTransaction(fn) with runInOwnTransaction(requireOutsideTransactionDb(ctx), fn); both are exported from @cosmicdrift/kumiko-framework/db and fn keeps its (db) => Promise signature."
+  },
   {
     "version": "0.377.0",
     "type": "improvement",