@cosmicdrift/kumiko-renderer 0.377.0 → 0.379.0

package/dist/flow-diagram/index.js

@@ -0,0 +1 @@
+export { renderFlow } from "./render.js";

package/dist/flow-diagram/render.d.ts

@@ -0,0 +1,3 @@
+import type { FlowSpec } from "./types.ts";
+/** Renders a FlowSpec (a small acyclic node/edge graph) to a self-contained, animated SVG diagram string for embedding in docs pages. */
+export declare function renderFlow(spec: FlowSpec): string;

package/dist/flow-diagram/render.js

@@ -0,0 +1,234 @@
+import { escapeHtml } from "../headless/index.js";
+import { ICONS } from "./icons.js";
+const BADGE = 24;
+const ICON_SIZE = 13;
+const PAD_X = 9.6;
+const GAP_BADGE_TEXT = 8;
+const GAP_RIGHT = 11.2;
+const ROW_GAP = 35;
+const COL_GAP = 22;
+const MIN_CARD_WIDTH = 120;
+const TITLE_SIZE = 11.2;
+const SUB_SIZE = 9.2;
+const STEP_SECONDS = 1.2;
+function textWidth(text, fontSize, bold) {
+    return text.length * fontSize * (bold ? 0.62 : 0.56);
+}
+function cardSize(node) {
+    const titleWidth = textWidth(node.title, TITLE_SIZE, true);
+    const subWidth = node.sub ? textWidth(node.sub, SUB_SIZE, false) : 0;
+    const content = Math.max(titleWidth, subWidth);
+    const width = Math.max(MIN_CARD_WIDTH, BADGE + GAP_BADGE_TEXT + content + PAD_X + GAP_RIGHT);
+    const height = node.sub ? 42 : 32;
+    return { width, height };
+}
+function assertEdgesReferenceKnownNodes(spec) {
+    const ids = new Set(spec.nodes.map((n) => n.id));
+    for (const edge of spec.edges) {
+        if (!ids.has(edge.from))
+            throw new Error(`FlowSpec: edge references unknown node "${edge.from}"`);
+        if (!ids.has(edge.to))
+            throw new Error(`FlowSpec: edge references unknown node "${edge.to}"`);
+    }
+}
+function buildAdjacency(spec) {
+    const children = new Map();
+    const inDegree = new Map();
+    for (const node of spec.nodes)
+        inDegree.set(node.id, 0);
+    for (const edge of spec.edges) {
+        children.set(edge.from, [...(children.get(edge.from) ?? []), edge]);
+        inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+    }
+    return { children, inDegree };
+}
+/** Longest-path depth per node via Kahn's algorithm; throws if the graph has no root or contains a cycle. */
+function longestPathDepths(spec, children, inDegree) {
+    const depth = new Map();
+    const queue = spec.nodes.filter((n) => inDegree.get(n.id) === 0).map((n) => n.id);
+    if (queue.length === 0 && spec.nodes.length > 0) {
+        throw new Error("FlowSpec: no root node found (every node has an incoming edge — check for a cycle)");
+    }
+    for (const id of queue)
+        depth.set(id, 0);
+    const remaining = new Map(inDegree);
+    let visited = 0;
+    for (const id of queue) {
+        visited += 1;
+        for (const edge of children.get(id) ?? []) {
+            const next = Math.max(depth.get(edge.to) ?? 0, (depth.get(id) ?? 0) + 1);
+            depth.set(edge.to, next);
+            const left = (remaining.get(edge.to) ?? 0) - 1;
+            remaining.set(edge.to, left);
+            if (left === 0)
+                queue.push(edge.to);
+        }
+    }
+    if (visited < spec.nodes.length) {
+        throw new Error("FlowSpec: graph has a cycle — a flow diagram must be acyclic");
+    }
+    return depth;
+}
+function computeDepths(spec) {
+    assertEdgesReferenceKnownNodes(spec);
+    const { children, inDegree } = buildAdjacency(spec);
+    return longestPathDepths(spec, children, inDegree);
+}
+function layout(spec) {
+    const depthById = computeDepths(spec);
+    const maxDepth = Math.max(0, ...[...depthById.values()]);
+    const rows = Array.from({ length: maxDepth + 1 }, () => []);
+    for (const node of spec.nodes)
+        rows[depthById.get(node.id) ?? 0]?.push(node);
+    // Siblings in the same row share one card size (the row's largest), so a
+    // row of 3+ always lands symmetrically under its parent — an odd sibling
+    // count with mismatched widths otherwise throws the middle card off-center.
+    const sizedRows = rows.map((row) => {
+        const sizes = row.map((n) => cardSize(n));
+        return {
+            row,
+            width: Math.max(MIN_CARD_WIDTH, ...sizes.map((s) => s.width)),
+            height: Math.max(0, ...sizes.map((s) => s.height)),
+        };
+    });
+    const rowWidths = sizedRows.map(({ row, width }) => row.length * width + COL_GAP * Math.max(0, row.length - 1));
+    const canvasWidth = Math.max(...rowWidths, MIN_CARD_WIDTH) + 40;
+    const centerX = canvasWidth / 2;
+    const placed = new Map();
+    let y = 20;
+    for (const { row, width, height } of sizedRows) {
+        const rowWidth = row.length * width + COL_GAP * Math.max(0, row.length - 1);
+        let x = centerX - rowWidth / 2;
+        for (const node of row) {
+            placed.set(node.id, { node, depth: depthById.get(node.id) ?? 0, x, y, width, height });
+            x += width + COL_GAP;
+        }
+        y += height + ROW_GAP;
+    }
+    const canvasHeight = y - ROW_GAP + 20;
+    return { placed, width: canvasWidth, height: canvasHeight, maxDepth };
+}
+function computeTiming(placed, spec, maxDepth) {
+    const totalSeconds = STEP_SECONDS * (maxDepth + 1) + STEP_SECONDS * 0.5;
+    const timingByEdge = new Map();
+    const arrivalByNode = new Map();
+    for (const edge of spec.edges) {
+        const from = placed.get(edge.from);
+        const to = placed.get(edge.to);
+        if (!from || !to)
+            continue;
+        const span = Math.max(1, to.depth - from.depth);
+        const startT = from.depth * STEP_SECONDS;
+        const travelT = STEP_SECONDS * 0.75 * span;
+        const startFrac = startT / totalSeconds;
+        const endFrac = Math.min(0.98, (startT + travelT) / totalSeconds);
+        timingByEdge.set(edge, { startFrac, endFrac });
+        arrivalByNode.set(edge.to, Math.max(arrivalByNode.get(edge.to) ?? 0, endFrac));
+    }
+    return { totalSeconds, timingByEdge, arrivalByNode };
+}
+const CORNER_RADIUS = 8; // 10 * 0.8
+function edgePath(from, to) {
+    const x1 = from.x + from.width / 2;
+    const y1 = from.y + from.height;
+    const x2 = to.x + to.width / 2;
+    const y2 = to.y;
+    if (Math.abs(x1 - x2) < 1) {
+        return { d: `M ${x1} ${y1} L ${x2} ${y2}`, midX: x1, midY: (y1 + y2) / 2 };
+    }
+    const midY = (y1 + y2) / 2;
+    const dir = x2 > x1 ? 1 : -1;
+    const r = Math.min(CORNER_RADIUS, Math.abs(x2 - x1) / 2, midY - y1, y2 - midY);
+    const d = `M ${x1} ${y1} L ${x1} ${midY - r} ` +
+        `Q ${x1} ${midY} ${x1 + dir * r} ${midY} ` +
+        `L ${x2 - dir * r} ${midY} ` +
+        `Q ${x2} ${midY} ${x2} ${midY + r} ` +
+        `L ${x2} ${y2}`;
+    return { d, midX: (x1 + x2) / 2, midY };
+}
+/** Renders a FlowSpec (a small acyclic node/edge graph) to a self-contained, animated SVG diagram string for embedding in docs pages. */
+export function renderFlow(spec) {
+    const { placed, width, height, maxDepth } = layout(spec);
+    const { totalSeconds, timingByEdge, arrivalByNode } = computeTiming(placed, spec, maxDepth);
+    const wires = [];
+    const dots = [];
+    const labels = [];
+    for (const edge of spec.edges) {
+        const from = placed.get(edge.from);
+        const to = placed.get(edge.to);
+        if (!from || !to)
+            continue;
+        const { d, midX, midY } = edgePath(from, to);
+        // html-ok: d is built in edgePath() from numeric coordinates only, never user input
+        wires.push(`<path class="wire" d="${d}"/>`);
+        if (edge.label) {
+            labels.push(`<text class="edge-label" x="${midX}" y="${midY - 6}" text-anchor="middle">${escapeHtml(edge.label)}</text>`);
+        }
+        const timing = timingByEdge.get(edge);
+        if (!timing)
+            continue;
+        const { startFrac, endFrac } = timing;
+        const fadeIn = Math.min(startFrac + 0.02, endFrac);
+        const fadeOut = Math.min(endFrac + 0.02, 1);
+        dots.push(`<circle r="3.2" class="dot">` +
+            `<animateMotion dur="${totalSeconds}s" repeatCount="indefinite" calcMode="linear" ` +
+            `keyPoints="0;0;1;1" keyTimes="0;${startFrac};${endFrac};1" path="${d}"/>` +
+            `<animate attributeName="opacity" dur="${totalSeconds}s" repeatCount="indefinite" ` +
+            `values="0;0;1;1;0;0" keyTimes="0;${startFrac};${fadeIn};${endFrac};${fadeOut};1"/>` +
+            `</circle>`);
+    }
+    const cards = spec.nodes.map((node) => {
+        const p = placed.get(node.id);
+        if (!p)
+            return "";
+        const arrival = arrivalByNode.get(node.id) ?? 0.02;
+        const pulseEnd = Math.min(arrival + 0.05, 1);
+        const badgeX = p.x + PAD_X;
+        const badgeY = p.y + (p.height - BADGE) / 2;
+        const textX = badgeX + BADGE + GAP_BADGE_TEXT;
+        const isTerminal = node.kind === "terminal";
+        const badgeFill = isTerminal
+            ? "var(--flow-card)"
+            : node.icon === "check"
+                ? "var(--flow-green)"
+                : "var(--flow-badge)";
+        const badgeClass = isTerminal ? "flow-badge flow-badge-terminal" : "flow-badge";
+        const iconGroupClass = isTerminal ? "flow-icon-terminal" : "";
+        const iconInset = (BADGE - ICON_SIZE) / 2;
+        const iconInner = node.icon === "ai"
+            ? `<text class="flow-ai-label" x="${BADGE / 2}" y="${BADGE / 2 + 3}" text-anchor="middle">AI</text>`
+            : // html-ok: ICONS is a static internal map keyed by the FlowIcon union, not user input
+                `<svg class="${iconGroupClass}" x="${iconInset}" y="${iconInset}" width="${ICON_SIZE}" height="${ICON_SIZE}" viewBox="0 0 24 24">${ICONS[node.icon ?? "box"]}</svg>`;
+        return `<g>
+      <rect class="flow-card" x="${p.x}" y="${p.y}" width="${p.width}" height="${p.height}" rx="9">
+        <animate attributeName="stroke" dur="${totalSeconds}s" repeatCount="indefinite"
+          values="var(--flow-card-border);var(--flow-card-border);var(--flow-violet);var(--flow-card-border);var(--flow-card-border)"
+          keyTimes="0;${Math.max(0, arrival - 0.02)};${arrival};${pulseEnd};1"/>
+      </rect>
+      <g transform="translate(${badgeX}, ${badgeY})">
+        <rect class="${badgeClass}" width="${BADGE}" height="${BADGE}" rx="6" fill="${badgeFill}"/>
+        ${iconInner}
+      </g>
+      <text class="flow-title" x="${textX}" y="${node.sub ? p.y + p.height / 2 - 2 : p.y + p.height / 2 + 3.5}">${escapeHtml(node.title)}</text>
+      ${node.sub ? `<text class="flow-sub" x="${textX}" y="${p.y + p.height / 2 + 11}">${escapeHtml(node.sub)}</text>` : ""}
+    </g>`;
+    });
+    // html-ok: wires/dots/labels/cards hold only fragments built from numeric
+    // coordinates or already-escaped text (escapeHtml above), never raw user input
+    return `<div class="kumiko-flow">
+  <svg width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Flow diagram">
+    ${
+    // html-ok: see comment above return
+    wires.join("\n    ")}
+    ${
+    // html-ok: see comment above return
+    dots.join("\n    ")}
+    ${
+    // html-ok: see comment above return
+    labels.join("\n    ")}
+    ${
+    // html-ok: see comment above return
+    cards.join("\n    ")}
+  </svg>
+</div>`;
+}

package/dist/flow-diagram/types.d.ts

@@ -0,0 +1,18 @@
+export type FlowIcon = "ui" | "api" | "handler" | "event-store" | "database" | "broadcast" | "ai" | "inbox" | "person" | "check" | "stop" | "box";
+export type FlowNodeKind = "process" | "decision" | "terminal";
+export interface FlowNode {
+    id: string;
+    title: string;
+    sub?: string;
+    icon?: FlowIcon;
+    kind?: FlowNodeKind;
+}
+export interface FlowEdge {
+    from: string;
+    to: string;
+    label?: string;
+}
+export interface FlowSpec {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+}

package/dist/flow-diagram/types.js

@@ -0,0 +1 @@
+export {};

package/dist/headless/dispatcher/index.d.ts

@@ -1,2 +1,3 @@
+export { generateRequestId } from "./request-id.ts";
 export type { BatchResult, Command, Dispatcher, DispatcherError, DispatcherStatus, FieldIssue, PendingFile, PendingWrite, QueryOpts, QueryResult, StreamOpts, WriteOpts, WriteResult, } from "./types.ts";
 export { StreamFrame, type StreamFrameEvent } from "./types.ts";

package/dist/headless/dispatcher/index.js

@@ -1 +1,2 @@
+export { generateRequestId } from "./request-id.js";
 export { StreamFrame } from "./types.js";

package/dist/headless/dispatcher/request-id.d.ts

@@ -0,0 +1 @@
+export declare function generateRequestId(): string;

package/dist/headless/dispatcher/request-id.js

@@ -0,0 +1,15 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+// crypto.randomUUID where available (browser, Bun, Node); Math.random
+// fallback for React-Native runtimes without the WebCrypto polyfill.
+// Uniqueness only needs to hold per user within the server's dedup window —
+// this is an idempotency key, not a security token.
+export function generateRequestId() {
+    const webCrypto = propertyOf(globalThis, "crypto");
+    const randomUUID = propertyOf(webCrypto, "randomUUID");
+    if (typeof randomUUID === "function") {
+        const id = Reflect.apply(randomUUID, webCrypto, []);
+        if (typeof id === "string")
+            return id;
+    }
+    return `req-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}

package/dist/headless/form/form-controller.js

@@ -1,3 +1,4 @@
+import { generateRequestId } from "../dispatcher/index.js";
 import { createStore } from "../store/index.js";
 import { groupIssuesByPath, relevantFieldIssues, zodErrorToFieldIssues } from "./zod-bridge.js";
 // Paths without the prefix (hook-level errors, "(root)") pass through unchanged.
@@ -91,6 +92,11 @@ function omitPayloadFields(payload, omitFields) {
         return payload;
     return Object.fromEntries(Object.entries(payload).filter(([key]) => !omitFields.includes(key)));
 }
+function isTransportFailure(result) {
+    return (!result.isSuccess &&
+        result.error.httpStatus === 0 &&
+        (result.error.code === "network_error" || result.error.code === "aborted"));
+}
 export function createFormController(options) {
     // Shallow copy so mutating the input after creation doesn't bleed into
     // the controller's internal state. `initial` stays fixed across the
@@ -115,6 +121,10 @@ export function createFormController(options) {
     // coherent (rebasing twice in quick succession would mis-align the
     // baseline with what the server actually saw).
     let submitInFlight = null;
+    // Idempotency key of the last attempt that got no server answer. The server
+    // caches every answer (errors too) under the requestId, so the key may only
+    // be reused for an identical retry after a transport failure.
+    let unansweredAttempt = null;
     function buildSnapshot() {
         const changes = valuesDiff(values, initial);
         const isDirty = Object.keys(changes).length > 0;
@@ -365,7 +375,12 @@ export function createFormController(options) {
                 };
             }
             const runWrite = async () => {
-                const result = await dispatcher.write(submitCfg.type, payload);
+                const fingerprint = JSON.stringify([submitCfg.type, payload]);
+                const requestId = unansweredAttempt?.fingerprint === fingerprint
+                    ? unansweredAttempt.requestId
+                    : generateRequestId();
+                const result = await dispatcher.write(submitCfg.type, payload, { requestId });
+                unansweredAttempt = isTransportFailure(result) ? { requestId, fingerprint } : null;
                 if (result.isSuccess) {
                     // Remember intentional empty clears so post-rebase submits keep them (#1858).
                     if (payload && typeof payload === "object" && !Array.isArray(payload)) {

package/dist/headless/form/zod-bridge.js

@@ -84,6 +84,13 @@ function extractIssueParams(issue) {
         if (bag[key] !== undefined)
             out[key] = bag[key];
     }
+    // A custom issue that overrides its i18n key also carries the values the text interpolates.
+    if (issue.code === "custom" && typeof issue.params?.[I18N_KEY_PARAM] === "string") {
+        for (const [key, value] of Object.entries(issue.params)) {
+            if (key !== I18N_KEY_PARAM && value !== undefined)
+                out[key] = value;
+        }
+    }
     return Object.keys(out).length > 0 ? out : undefined;
 }
 // Groups a flat FieldIssue list into the `errors` map carried by a

package/dist/headless/index.d.ts

@@ -2,12 +2,13 @@ export type { ParsedRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
 export { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
 export type { AssetResolution, AssetResolveContext, AssetResolver, BadgeProps, ButtonProps, CardProps, DatePickerProps, IconProps, LocaleResolver, ModalProps, NumberInputProps, PrimitiveCommonProps, PrimitivesContract, SelectOption, SelectProps, TextInputProps, ToastIntent, ToastProps, ToggleProps, } from "./contracts/index.ts";
 export type { BatchResult, Command, Dispatcher, DispatcherError, DispatcherStatus, FieldIssue, PendingFile, PendingWrite, QueryOpts, QueryResult, StreamOpts, WriteOpts, WriteResult, } from "./dispatcher/index.ts";
-export { StreamFrame, type StreamFrameEvent } from "./dispatcher/index.ts";
+export { generateRequestId, StreamFrame, type StreamFrameEvent } from "./dispatcher/index.ts";
 export type { FieldConditionPredicate, FieldConditions, FieldConditionValue, FieldState, FormController, FormControllerOptions, FormSnapshot, FormValues, SubmitConfig, SubmitPayloadMode, SubmitResult, } from "./form/index.ts";
 export { createFormController, groupIssuesByPath, I18N_KEY_PARAM, relevantFieldIssues, zodErrorToFieldIssues, } from "./form/index.ts";
 export { applyFormatSpec, currencyDecimals, DOCUMENT_FALLBACK_CURRENCY, EMPTY_VALUE_PLACEHOLDER, escapeHtml, escapeHtmlAttr, escapeXml, formatDocumentDate, formatDocumentMoney, formatDocumentPercent, formatMoney, type HtmlValue, html, isSafeHref, RawHtml, raw, resolveSafeMoneyLocale, stripControlChars, toInstant, } from "./format/index.ts";
 export type { NavDefinition, NavNode, NavRegistrySlice, NavTree, ResolveNavigationOptions, } from "./nav/index.ts";
 export { resolveNavigation } from "./nav/index.ts";
+export { pluralKey } from "./plural-key.ts";
 export type { Store, WritableStore } from "./store/index.ts";
 export { createStore, shallowEqual } from "./store/index.ts";
 export type { CellLink, CellLinkItem, ComputeEditViewModelInput, ComputeListViewModelInput, DerivedCellRoundingTarget, EditExtensionSectionViewModel, EditFieldSpec, EditFieldsSectionViewModel, EditFieldViewModel, EditFormMode, EditRelatedListSectionViewModel, EditSectionSpec, EditSectionViewModel, EditViewModel, EditWriteFormSectionViewModel, EmbeddedDerivedOp, EmbeddedListCellViewModel, EmbeddedListIssueGroups, FieldConditionCtx, FieldRenderer, ListColumnFileDisplay, ListColumnSpec, ListColumnViewModel, ListRowViewModel, ListViewModel, RuntimeCellLink, RuntimeCellLinkItems, RuntimeRenderer, ScreenSlots, Translate, } from "./view-model/index.ts";

package/dist/headless/index.js

@@ -1,9 +1,10 @@
 // Re-Export aus framework/ui-types damit Renderer-Code denselben
 // Parser nutzt wie der Server-Boot-Validator (Cross-Feature-Refs).
 export { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
-export { StreamFrame } from "./dispatcher/index.js";
+export { generateRequestId, StreamFrame } from "./dispatcher/index.js";
 export { createFormController, groupIssuesByPath, I18N_KEY_PARAM, relevantFieldIssues, zodErrorToFieldIssues, } from "./form/index.js";
 export { applyFormatSpec, currencyDecimals, DOCUMENT_FALLBACK_CURRENCY, EMPTY_VALUE_PLACEHOLDER, escapeHtml, escapeHtmlAttr, escapeXml, formatDocumentDate, formatDocumentMoney, formatDocumentPercent, formatMoney, html, isSafeHref, RawHtml, raw, resolveSafeMoneyLocale, stripControlChars, toInstant, } from "./format/index.js";
 export { resolveNavigation } from "./nav/index.js";
+export { pluralKey } from "./plural-key.js";
 export { createStore, shallowEqual } from "./store/index.js";
 export { buildOptionLabels, computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./view-model/index.js";

package/dist/headless/plural-key.d.ts

@@ -0,0 +1 @@
+export declare function pluralKey(baseKey: string, count: number): string;

package/dist/headless/plural-key.js

@@ -0,0 +1,5 @@
+// Manual plural convention for locale bundles that hold plain strings: `<base>.one` for a
+// count of exactly 1, `<base>.other` for everything else (0 included).
+export function pluralKey(baseKey, count) {
+    return `${baseKey}.${count === 1 ? "one" : "other"}`;
+}

package/dist/headless/view-model/edit.d.ts

@@ -1,4 +1,4 @@
-import type { EditRelatedListSection, EntityDefinition, EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { EditRelatedListSection, EntityDefinition, EntityEditScreenDefinition, FormDerivationScreen } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { EditRelatedListSectionViewModel, EditViewModel, Translate } from "./types.ts";
 export type ComputeEditViewModelInput<TValues extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> = {
     readonly screen: EntityEditScreenDefinition;
@@ -12,6 +12,13 @@ export type ComputeEditViewModelInput<TValues extends Readonly<Record<string, un
     readonly mode?: EditFormMode;
     /** The record being edited; omitted on create. */
     readonly entityId?: string;
+    /** actionForm `derive`: computed fields render read-only (and never block submit
+     *  as required) unless their derivation currently leaves them to the user. */
+    readonly derivation?: FormDerivationScreen;
+    /** Qualified name of the actionForm screen this form belongs to. File fields then upload
+     *  as pending for that screen (`uploadActionForm`) instead of for an entity. Set explicitly:
+     *  secretMint and confirm forms share the pseudo-entity but cannot take uploads. */
+    readonly actionFormScreenQn?: string;
 };
 export type EditFormMode = "create" | "update";
 export declare function computeRelatedListSectionViewModel(sectionSpec: EditRelatedListSection, translate: Translate): EditRelatedListSectionViewModel;

package/dist/headless/view-model/edit.js

@@ -1,4 +1,4 @@
-import { availableSelectOptions, evalFieldCondition, isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, parseRefTarget, sectionFieldSpecs, WRITE_FORM_SECTION_ENTITY, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { availableSelectOptions, evalFieldCondition, isExtensionEditSection, isFieldsEditSection, isFormDerivationInputMode, isUnusedFallbackOperand, isWriteFormEditSection, normalizeEditField, parseRefTarget, sectionFieldSpecs, WRITE_FORM_SECTION_ENTITY, } from "@cosmicdrift/kumiko-framework/ui-types";
 import { buildOptionLabels, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, } from "./list.js";
 // Resolves a writeForm section's own fieldDefs/fields through the same
 // per-field pipeline as a plain fields section, by reusing the pipeline
@@ -254,15 +254,20 @@ function deriveImageHints(fieldDef) {
         ...(fieldDef.capture !== undefined && { capture: fieldDef.capture }),
     };
 }
-function deriveFileFieldHints(fieldDef, entityName, fieldName, entityId) {
+function deriveFileFieldHints(fieldDef, entityName, fieldName, entityId, actionFormScreenQn) {
     if (!isFileFieldType(fieldDef))
         return {};
-    const maxCount = fieldDef.type === "files" || fieldDef.type === "images" ? fieldDef.maxCount : undefined;
+    const isList = fieldDef.type === "files" || fieldDef.type === "images";
+    const maxCount = isList ? fieldDef.maxCount : undefined;
+    const fileDisplay = isList ? fieldDef.display : undefined;
     return {
+        ...(fileDisplay !== undefined && { fileDisplay }),
         ...(fieldDef.accept !== undefined && { accept: fieldDef.accept }),
         ...(fieldDef.maxSize !== undefined && { maxSize: fieldDef.maxSize }),
         ...(maxCount !== undefined && { maxCount }),
-        entityType: entityName,
+        ...(actionFormScreenQn !== undefined
+            ? { uploadActionForm: actionFormScreenQn }
+            : { entityType: entityName }),
         fieldName,
         ...(entityId !== undefined && { entityId }),
         ...deriveImageHints(fieldDef),
@@ -354,8 +359,17 @@ function buildExtensionSectionViewModel(sectionSpec, translate) {
 // Pure transform from screen-def + entity-def + row-values to the flat
 // section/field tree the renderer draws. FieldConditions are evaluated here
 // so the renderer never re-runs them during React render.
+// A computed field the user can't currently type into, or a fallback operand
+// that the list rows make irrelevant: read-only and never blocking as required.
+function isLockedByDerivation(derivation, values, field) {
+    if (derivation === undefined)
+        return false;
+    const isDerivedAndLocked = derivation.derive?.[field] !== undefined &&
+        !isFormDerivationInputMode(derivation, values, field);
+    return isDerivedAndLocked || isUnusedFallbackOperand(derivation, values, field);
+}
 export function computeEditViewModel(input) {
-    const { screen, entity, values, translate, featureName, mode, entityId } = input;
+    const { screen, entity, values, translate, featureName, mode, entityId, derivation, actionFormScreenQn, } = input;
     const excludedFields = new Set(mode === undefined ? [] : screen.writeExcludedFields?.[mode]);
     const isHiddenByExclusion = (fieldSpec) => mode === "create" && excludedFields.has(normalizeEditField(fieldSpec).field);
     const sections = screen.layout.sections.map((sectionSpec) => {
@@ -399,14 +413,16 @@ export function computeEditViewModel(input) {
             // `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 lockedByDerivation = isLockedByDerivation(derivation, values, normalized.field);
             const readOnly = (mode === "update" && excludedFields.has(normalized.field)) ||
+                lockedByDerivation ||
                 evalCondition(normalized.readOnly, false, values);
             // `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.required === true;
-            const required = evalCondition(normalized.required, entityRequired, values);
+            const required = !lockedByDerivation && evalCondition(normalized.required, entityRequired, values);
             // ponytail: "EUR" mirrors DEFAULT_CURRENCIES[0] from
             // framework/src/engine/field-helpers.ts — headless has no dependency
             // on that module, so the literal is duplicated here instead of
@@ -417,7 +433,7 @@ export function computeEditViewModel(input) {
             const dateHints = deriveDateFieldHints(fieldDef);
             const numericHints = deriveNumericFieldHints(fieldDef, resolvedCurrency);
             const referenceHints = deriveReferenceFieldHints(fieldDef, normalized, declaredRefTarget, featureName);
-            const fileHints = deriveFileFieldHints(fieldDef, screen.entity, normalized.field, entityId);
+            const fileHints = deriveFileFieldHints(fieldDef, screen.entity, normalized.field, entityId, actionFormScreenQn);
             const embeddedListHints = deriveEmbeddedListHints(fieldDef, translate, featureName, screen.entity, normalized.field, resolvedCurrency, normalized.embeddedList);
             const view = {
                 field: normalized.field,

package/dist/headless/view-model/types.d.ts

@@ -210,7 +210,12 @@ export type EditFieldViewModel = {
      *  upload POST (`/api/files`), so the endpoint can check maxSize/accept
      *  against the right field def. */
     readonly entityType?: string;
+    /** Only for file fields of an actionForm — the screen QN the upload POST names as
+     *  `actionForm` instead of `entityType`; the server resolves the field through that screen. */
+    readonly uploadActionForm?: string;
     readonly fieldName?: string;
+    /** Only for `type: "files" | "images"` — how the field is shown. Absent = list. */
+    readonly fileDisplay?: "list" | "dropzone";
     /** Record being edited (update mode only). Sent with the upload so the
      *  FileRef is attached to the record. */
     readonly entityId?: string;
@@ -245,11 +250,14 @@ export type EditFieldViewModel = {
     /** Sub-field name → how to compute its cell from other sub-fields of the
      *  same row. From EmbeddedFieldDef.derived. */
     readonly embeddedListDerived?: Readonly<Record<string, {
-        readonly op: "multiply" | "sum" | "subtract";
+        readonly op: "multiply" | "sum" | "subtract" | "percent";
         readonly from: readonly string[];
     }>>;
-    /** Numeric sub-field names to sum in a totals row. From EmbeddedFieldDef.totals. */
-    readonly embeddedListTotals?: readonly string[];
+    /** Footer totals: a sub-field name, or a labelled sum of several. From EmbeddedFieldDef.totals. */
+    readonly embeddedListTotals?: readonly (string | {
+        readonly label: string;
+        readonly from: readonly string[];
+    })[];
     /** No add, remove, duplicate or move; cells stay editable. From
      *  EditFieldSpec.embeddedList.fixedRows. */
     readonly embeddedListFixedRows?: boolean;

package/dist/hooks/live-refetch-scheduler.d.ts

@@ -0,0 +1,6 @@
+export declare const LIVE_REFETCH_COALESCE_MS = 250;
+export type LiveRefetchScheduler = {
+    readonly trigger: () => void;
+    readonly dispose: () => void;
+};
+export declare function createLiveRefetchScheduler(run: () => Promise<void> | void, windowMs?: number): LiveRefetchScheduler;

package/dist/hooks/live-refetch-scheduler.js

@@ -0,0 +1,45 @@
+export const LIVE_REFETCH_COALESCE_MS = 250;
+// A burst of live events collapses into one trailing run. An event that lands
+// while a run is still in flight queues exactly one follow-up after it.
+export function createLiveRefetchScheduler(run, windowMs = LIVE_REFETCH_COALESCE_MS) {
+    let timer;
+    let inFlight = false;
+    let rerunQueued = false;
+    let disposed = false;
+    const fire = async () => {
+        timer = undefined;
+        inFlight = true;
+        try {
+            await run();
+        }
+        finally {
+            inFlight = false;
+        }
+        if (rerunQueued && !disposed) {
+            rerunQueued = false;
+            await fire();
+        }
+    };
+    return {
+        trigger: () => {
+            // skip: the subscriber is gone
+            if (disposed)
+                return;
+            if (inFlight) {
+                rerunQueued = true;
+                // skip: the queued follow-up run covers this event
+                return;
+            }
+            // skip: a trailing run is already scheduled and will cover this event
+            if (timer !== undefined)
+                return;
+            timer = setTimeout(() => void fire(), windowMs);
+        },
+        dispose: () => {
+            disposed = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+        },
+    };
+}

package/dist/hooks/use-query.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useDispatcher, useOptionalQueryPools } from "../context/dispatcher-context.js";
 import { useLiveEvents } from "../sse/live-events.js";
+import { createLiveRefetchScheduler } from "./live-refetch-scheduler.js";
 // Extract the entity-name from a standard Kumiko query type. Returns
 // undefined for non-conforming types so the live-mode silently skips
 // them instead of subscribing to a channel no event will ever match.
@@ -125,9 +126,12 @@ export function useQuery(type, payload, options = {}) {
         // skip: query type has no mapped entity, nothing to subscribe to
         if (entity === undefined)
             return;
-        return subscribeLive(entity, () => {
-            void run();
-        });
-    }, [live, enabled, type, run, subscribeLive]);
+        const scheduler = createLiveRefetchScheduler(() => runFetch(true));
+        const unsubscribe = subscribeLive(entity, scheduler.trigger);
+        return () => {
+            unsubscribe();
+            scheduler.dispose();
+        };
+    }, [live, enabled, type, runFetch, subscribeLive]);
     return { data, error, loading, refetch: run };
 }

package/dist/hooks/use-reference-lookup.d.ts

@@ -18,4 +18,5 @@ export declare function referenceOptionSource(field: {
 export declare function useReferenceLookup(featureName: string, refEntity: string, labelField: string): {
     readonly map: ReferenceLookupMap;
     readonly loading: boolean;
+    readonly failed: boolean;
 };

package/dist/hooks/use-reference-lookup.js

@@ -66,9 +66,12 @@ export function useReferenceLookup(featureName, refEntity, labelField) {
         }
         // System-scope ids (e.g. SYSTEM_TENANT_ID) never have a backing row, so
         // the bulk lookup above never covers them — inject the label directly.
-        if (systemLabel !== undefined)
-            out.set(systemLabel.id, translate(systemLabel.labelKey));
+        if (systemLabel !== undefined) {
+            for (const id of [systemLabel.id, ...(systemLabel.aliases ?? [])]) {
+                out.set(id, translate(systemLabel.labelKey));
+            }
+        }
         return out;
     }, [result.data, labelKey, systemLabel, translate]);
-    return { map, loading: result.loading };
+    return { map, loading: result.loading, failed: result.error !== null };
 }