@cosmicdrift/kumiko-renderer 0.377.0 → 0.378.0

package/dist/app/kumiko-screen.js

@@ -5,6 +5,7 @@ import { TENANT_CURRENCY_CONFIG_KEY } from "@cosmicdrift/kumiko-types/fields";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { withDerivedValues } from "../components/form-derivation-patch.js";
 import { QueryOptionLabel, resolveOptionsQueryPayload, } from "../components/query-options-select.js";
 import { extractCreatedId, extractIdField } from "../components/reference-create-dialog.js";
 import { RenderEdit, resolveRecordTitle, } from "../components/render-edit.js";
@@ -2549,6 +2550,7 @@ function ActionFormBody({ schema, screen, translate, entityId, initialOverrides,
         handoffValues,
         loadedValues,
     ]);
+    const derivedInitial = useMemo(() => withDerivedValues(initial, screen.derive !== undefined ? screen : undefined), [initial, screen]);
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
     const summary = useMemo(() => resolveActionFormSummary(screen.summary, initialOverrides, effectiveTranslate, locale), [screen.summary, initialOverrides, effectiveTranslate, locale]);
@@ -2650,7 +2652,7 @@ function ActionFormBody({ schema, screen, translate, entityId, initialOverrides,
     if (loadState !== undefined && loadState.status !== "ready") {
         return (_jsx(ActionFormLoadStatus, { state: loadState, screenId: screen.id, translate: effectiveTranslate }));
     }
-    return (_jsx(RenderEdit, { screen: synthScreen, entity: synthEntity, featureName: schema.featureName, initial: initial, 
+    return (_jsx(RenderEdit, { screen: synthScreen, entity: synthEntity, featureName: schema.featureName, initial: derivedInitial, ...(screen.derive !== undefined && { formDerivation: screen }), 
         // Extension-Sections im actionForm sehen die initialen Form-Values
         // (inkl. searchParams-Prefill, z.B. ?incidentId=…) als initialValues
         // — anders als im entityEdit gibt es hier keinen record, aus dem

package/dist/components/form-derivation-patch.d.ts

@@ -0,0 +1,8 @@
+import type { FormDerivationScreen } from "@cosmicdrift/kumiko-framework/ui-types";
+/** The derived values that differ from the current form values, or undefined
+ *  when everything is already up to date. A derived value that no longer
+ *  resolves is reported as `undefined`. */
+export declare function changedDerivedValues(values: unknown, screen: FormDerivationScreen): Record<string, unknown> | undefined;
+/** `values` with every derived field already resolved, so the form's baseline
+ *  matches what the live recomputation would produce and starts out clean. */
+export declare function withDerivedValues<TValues extends Record<string, unknown>>(values: TValues, screen: FormDerivationScreen | undefined): TValues;

package/dist/components/form-derivation-patch.js

@@ -0,0 +1,24 @@
+import { applyFormDerivations, isUnchangedValue } from "@cosmicdrift/kumiko-framework/ui-types";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+/** The derived values that differ from the current form values, or undefined
+ *  when everything is already up to date. A derived value that no longer
+ *  resolves is reported as `undefined`. */
+export function changedDerivedValues(values, screen) {
+    const next = applyFormDerivations(values, screen);
+    if (!isPlainObject(values) || !isPlainObject(next))
+        return undefined;
+    const patch = {};
+    for (const target of Object.keys(screen.derive ?? {})) {
+        if (!isUnchangedValue(values[target], next[target]))
+            patch[target] = next[target];
+    }
+    return Object.keys(patch).length === 0 ? undefined : patch;
+}
+/** `values` with every derived field already resolved, so the form's baseline
+ *  matches what the live recomputation would produce and starts out clean. */
+export function withDerivedValues(values, screen) {
+    if (screen === undefined)
+        return values;
+    const patch = changedDerivedValues(values, screen);
+    return patch === undefined ? values : { ...values, ...patch };
+}

package/dist/components/form-screen-layout.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+import { type FormWidth } from "../primitives.tsx";
+export type FormScreenLayoutProps = {
+    readonly children: ReactNode;
+    readonly description?: ReactNode;
+    readonly actions?: ReactNode;
+    readonly secondaryActions?: ReactNode;
+    readonly onSubmit?: () => void;
+    readonly width?: FormWidth;
+    readonly testId?: string;
+};
+/** For custom screens: the standard form screen layout; fill it with `Section` (title, icon, subtitle). */
+export declare function FormScreenLayout({ children, description, actions, secondaryActions, onSubmit, width, testId, }: FormScreenLayoutProps): ReactNode;

package/dist/components/form-screen-layout.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { usePrimitives } from "../primitives.js";
+const FORM_SCREEN_LAYOUT_PROPS = {
+    screenForm: true,
+    fillHeight: true,
+    stickyActions: true,
+};
+const NOOP = () => { };
+/** For custom screens: the standard form screen layout; fill it with `Section` (title, icon, subtitle). */
+export function FormScreenLayout({ children, description, actions, secondaryActions, onSubmit = NOOP, width, testId, }) {
+    const { Form } = usePrimitives();
+    return (_jsx(Form, { onSubmit: onSubmit, ...FORM_SCREEN_LAYOUT_PROPS, ...(description !== undefined && { subtitle: description }), ...(actions !== undefined && { actions }), ...(secondaryActions !== undefined && { secondaryActions }), ...(width !== undefined && { width }), ...(testId !== undefined && { testId }), children: children }));
+}

package/dist/components/render-edit-types.d.ts

@@ -1,4 +1,4 @@
-import type { ActionFormFooterAction, EntityDefinition, EntityEditScreenDefinition, IconKey, RowAction, RowActionDrawer } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ActionFormFooterAction, EntityDefinition, EntityEditScreenDefinition, FormDerivationScreen, IconKey, RowAction, RowActionDrawer } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { ReactNode } from "react";
 import type * as z from "zod";
 import type { DispatcherError, FormSnapshot, FormValues, SubmitResult, Translate } from "../headless/index.ts";
@@ -204,6 +204,9 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
      *  `disabled`, which locks the whole form. For a gate the host owns, e.g.
      *  an acknowledgement checkbox in `leadContent`. */
     readonly submitBlocked?: boolean;
+    /** actionForm `derive`: derived fields are recomputed into the form state on every
+     *  change and render read-only. */
+    readonly formDerivation?: FormDerivationScreen;
     /** Show the unsaved-changes footer (count, Discard, "Save changes") even
      *  without an entity id or a screen-height form — for hosts that edit an
      *  existing server-side record through `customSubmit` (configEdit, also when

package/dist/components/render-edit.js

@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { evalFieldCondition, isFieldsEditSection, normalizeEditField, PROJECTION_DETAIL_ENTITY, sectionFieldSpecs, } from "@cosmicdrift/kumiko-framework/ui-types";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { computeEditViewModel, groupIssuesByPath, relevantFieldIssues, zodErrorToFieldIssues, } from "../headless/index.js";
+import { changedDerivedValues } from "./form-derivation-patch.js";
 import { RenderEditActionButton } from "./render-edit-action-button.js";
 import { AllFieldsRequiredProvider } from "./render-field.js";
 import { useActionMenuItems } from "./use-action-menu-items.js";
@@ -229,7 +230,7 @@ function resolveTitleTemplate(template, values, translate, fallback) {
     return translate(template, values);
 }
 export function RenderEdit(props) {
-    const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, refreshToken, onDirtyChange, onCopyLink, actions, menuActions, onRelatedListDrawerAction, submitLabel, submitVariant, submitWithoutChanges, footerActions, summary, labelAppendix, fieldAppendix, fieldAppendixPlacement, fieldDescription, fieldAccent, markChangedFields = false, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled: disabledProp = false, viewMode = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, dirtyFooter, validateOnChange, headerRegion, buildSectionActions, leadContent, submitBlocked = false, } = props;
+    const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, refreshToken, onDirtyChange, onCopyLink, actions, menuActions, onRelatedListDrawerAction, submitLabel, submitVariant, submitWithoutChanges, footerActions, summary, labelAppendix, fieldAppendix, fieldAppendixPlacement, fieldDescription, fieldAccent, markChangedFields = false, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled: disabledProp = false, viewMode = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, dirtyFooter, validateOnChange, headerRegion, buildSectionActions, leadContent, submitBlocked = false, formDerivation, } = props;
     // View mode is a locked form, so everything keyed on `disabled` follows.
     const disabled = disabledProp || viewMode;
     const i18nScreenId = props.i18nScreenId ?? screen.id;
@@ -367,6 +368,16 @@ export function RenderEdit(props) {
         ...(ctx !== undefined && { ctx }),
         ...(submitConfig !== undefined && { submit: submitConfig }),
     });
+    // Derived fields are written into form state (not only displayed) so required
+    // validation and the submit payload carry them; only a real change is set, which
+    // keeps this from looping.
+    useEffect(() => {
+        if (formDerivation === undefined)
+            return;
+        const patch = changedDerivedValues(snapshot.values, formDerivation);
+        if (patch !== undefined)
+            controller.setValues(patch); // @cast-boundary form-values
+    }, [snapshot.values, formDerivation, controller]);
     // Wired at the user-input boundary, not in controller.setField: computed
     // fields, prefill, draft restore and action patches also call setValues
     // after a failed submit and must not wipe the errors.
@@ -654,7 +665,9 @@ export function RenderEdit(props) {
         featureName,
         mode: writeVerb,
         ...(!isCreateMode && entityIdProp != null && { entityId: entityIdProp }),
+        ...(formDerivation !== undefined && { derivation: formDerivation }),
     }), [
+        formDerivation,
         screen,
         entity,
         snapshot.values,

package/dist/components/render-field.js

@@ -11,6 +11,7 @@ import { evalRowExtractor } from "../app/row-actions.js";
 import { screenAccessAllows } from "../app/screen-access.js";
 import { useOptionalDispatcher } from "../context/dispatcher-context.js";
 import { useUserRoles } from "../context/user-roles-context.js";
+import { fileIdsOf } from "../file-ids-of.js";
 import { applyFormatSpec, currencyDecimals, EMPTY_VALUE_PLACEHOLDER, } from "../headless/index.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
@@ -280,7 +281,7 @@ function inputId(field) {
 // Doesn't resolve the `string` (cross-feature QN) FieldRenderer variant — the
 // list-column path (DataTableCell) doesn't either, so this stays in parity.
 function FieldRendererOutput({ field, renderer, row, appLocale, }) {
-    const { Text, JsonView } = usePrimitives();
+    const { Text, JsonView, FileValueList } = usePrimitives();
     const t = useTranslation();
     const componentName = !isFormatSpec(renderer) && typeof renderer === "object" && renderer !== null
         ? extensionSectionName(renderer)
@@ -293,6 +294,12 @@ function FieldRendererOutput({ field, renderer, row, appLocale, }) {
         if (renderer.format === "json" && JsonView !== undefined) {
             return (_jsx(JsonView, { value: field.value, indent: renderer.indent, testId: `field-value-${field.field}` }));
         }
+        if (renderer.format === "file" && FileValueList !== undefined) {
+            const fileIds = fileIdsOf(field.value);
+            if (fileIds.length === 0)
+                return _jsx(Text, { testId: `field-value-${field.field}`, children: EMPTY_VALUE_PLACEHOLDER });
+            return _jsx(FileValueList, { fileIds: fileIds, testId: `field-value-${field.field}` });
+        }
         // App locale as default when the FormatSpec declares none of its own —
         // otherwise locale-sensitive formats (timestamp/date/number/decimal/
         // bigInt/unit) fell back to Intl's runtime default instead of the app

package/dist/file-ids-of.d.ts

@@ -0,0 +1 @@
+export declare function fileIdsOf(value: unknown): readonly string[];

package/dist/file-ids-of.js

@@ -0,0 +1,7 @@
+export function fileIdsOf(value) {
+    if (typeof value === "string")
+        return value === "" ? [] : [value];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "string" && entry !== "");
+}

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

@@ -0,0 +1,3 @@
+import type { FlowIcon } from "./types.ts";
+/** Inner markup for a 24x24 viewBox, stroked via the `.icon` CSS class. "ai" renders as a text badge instead — see render.ts. */
+export declare const ICONS: Record<Exclude<FlowIcon, "ai">, string>;

package/dist/flow-diagram/icons.js

@@ -0,0 +1,14 @@
+/** Inner markup for a 24x24 viewBox, stroked via the `.icon` CSS class. "ai" renders as a text badge instead — see render.ts. */
+export const ICONS = {
+    ui: '<rect class="icon" x="3" y="4" width="18" height="15" rx="1.5"/><path class="icon" d="M3 8h18"/>',
+    api: '<path class="icon" d="M8 6l-5 6 5 6"/><path class="icon" d="M16 6l5 6-5 6"/>',
+    handler: '<path class="icon" d="M8 4l-4 8 4 8"/><path class="icon" d="M16 4l4 8-4 8"/><path class="icon" d="M11 20l2-16"/>',
+    "event-store": '<path class="icon" d="M4 6c0-1.5 3.6-2.5 8-2.5S20 4.5 20 6s-3.6 2.5-8 2.5S4 7.5 4 6z"/><path class="icon" d="M4 6v12c0 1.5 3.6 2.5 8 2.5s8-1 8-2.5V6"/><path class="icon" d="M4 12c0 1.5 3.6 2.5 8 2.5s8-1 8-2.5"/>',
+    database: '<path class="icon" d="M4 6c0-1.5 3.6-2.5 8-2.5S20 4.5 20 6s-3.6 2.5-8 2.5S4 7.5 4 6z"/><path class="icon" d="M4 6v12c0 1.5 3.6 2.5 8 2.5s8-1 8-2.5V6"/>',
+    inbox: '<path class="icon" d="M3 6h18v13H3z"/><path class="icon" d="M3 6l9 7 9-7"/>',
+    broadcast: '<path class="icon" d="M12 20v-1"/><path class="icon" d="M8.5 15.5a5 5 0 017 0"/><path class="icon" d="M5 12a9 9 0 0114 0"/>',
+    person: '<circle class="icon" cx="12" cy="8" r="3.2"/><path class="icon" d="M5 20c0-4 3-6 7-6s7 2 7 6"/>',
+    check: '<path class="icon" d="M5 12l5 5L20 6"/>',
+    stop: '<rect class="icon" x="7" y="7" width="10" height="10" rx="1.5"/>',
+    box: '<rect class="icon" x="4" y="4" width="16" height="16" rx="2"/>',
+};

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

@@ -0,0 +1,2 @@
+export { renderFlow } from "./render.ts";
+export type { FlowEdge, FlowIcon, FlowNode, FlowNodeKind, FlowSpec } from "./types.ts";

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/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,9 @@ 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;
 };
 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
@@ -354,8 +354,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 } = 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 +408,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

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

@@ -245,7 +245,7 @@ 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. */

package/dist/i18n-defaults.js

@@ -40,6 +40,9 @@ export const kumikoDefaultTranslations = {
         "kumiko.field.locatedTzHint": "Time local to the given location",
         "kumiko.field.reference-created-no-id": "Record was created but could not be selected automatically. Please select it manually.",
         "kumiko.field.unsupported": "This field type can't be edited here yet.",
+        "kumiko.field.file-list.download": "Download",
+        "kumiko.field.file-list.hidePreview": "Hide preview",
+        "kumiko.field.file-list.preview": "Preview",
         "kumiko.field.fillAction.failed": "Could not fetch a suggestion.",
         "kumiko.field.writeOnly.remove": "Remove stored value",
         "kumiko.field.writeOnly.set": "Set",
@@ -155,6 +158,9 @@ export const kumikoDefaultTranslations = {
         "kumiko.widget.upload.done": "Uploaded",
         "kumiko.widget.upload.error": "Failed",
         "kumiko.widget.upload.rejected-type": "File type not allowed",
+        "kumiko.widget.pdf-preview.loading": "Loading PDF…",
+        "kumiko.widget.pdf-preview.pageOf": "Page {page} of {pages}",
+        "kumiko.widget.pdf-preview.renderFailed": "The PDF could not be displayed.",
         "kumiko.widget.step-bar.done": "Done",
         "kumiko.widget.drawer.restore": "Restore drawer width",
         "kumiko.widget.drawer.maximize": "Maximize drawer width",

package/dist/index.d.ts

@@ -39,6 +39,8 @@ export { evalVisibleWhen, type VisibleWhenVerdict } from "./app/visible-when.ts"
 export { dispatcherErrorText, WriteFailedError } from "./app/write-failed-error.ts";
 export type { ErrorBoundaryFallbackProps, ErrorBoundaryProps, } from "./components/error-boundary.tsx";
 export { ErrorBoundary } from "./components/error-boundary.tsx";
+export type { FormScreenLayoutProps } from "./components/form-screen-layout.tsx";
+export { FormScreenLayout } from "./components/form-screen-layout.tsx";
 export { RelatedListSection } from "./components/related-list-section.tsx";
 export type { RenderEditAction, RenderEditChangeState, RenderEditControls, RenderEditProps, } from "./components/render-edit.tsx";
 export { RenderEdit } from "./components/render-edit.tsx";
@@ -79,7 +81,7 @@ export { createStaticLocaleResolver, FormalityProvider, LocaleProvider, mergeTra
 export { kumikoDefaultTranslations } from "./i18n-defaults.ts";
 export { InsideDrawerProvider, useInsideDrawer } from "./inside-drawer.ts";
 export { PageHeaderCompactProvider, PageHeaderSlotAvailableProvider, usePageHeaderCompact, usePageHeaderSlotAvailable, } from "./page-header-slot.ts";
-export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableRowGrouping, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FillContainerProps, FooterActionMarker, FooterActionRole, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputFillAction, InputProps, JsonViewProps, LightboxImage, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PickedFile, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, TrailingInputAction, WizardStepGroupProps, } from "./primitives.tsx";
+export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableRowGrouping, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FileValueListProps, FillContainerProps, FooterActionMarker, FooterActionRole, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputFillAction, InputProps, JsonViewProps, LightboxImage, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PickedFile, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, TrailingInputAction, WizardStepGroupProps, } from "./primitives.tsx";
 export { FOOTER_ACTION_ROLE_PROP, NARROW_LABEL_PROP, PrimitivesProvider, STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, statusToneForOptionTone, statusToneForValue, useOptionalPrimitives, usePrimitives, } from "./primitives.tsx";
 export type { SessionEndedSignal, SessionEndedSignalProviderProps, } from "./session/session-ended.tsx";
 export { createSessionEndedSignal, isSessionEndedError, SESSION_ENDED_ERROR_CODES, SessionEndedSignalProvider, useSessionEndedSignal, withSessionEndedDetection, } from "./session/session-ended.tsx";

package/dist/index.js

@@ -32,6 +32,7 @@ export { VariableChips } from "./app/variable-chips.js";
 export { evalVisibleWhen } from "./app/visible-when.js";
 export { dispatcherErrorText, WriteFailedError } from "./app/write-failed-error.js";
 export { ErrorBoundary } from "./components/error-boundary.js";
+export { FormScreenLayout } from "./components/form-screen-layout.js";
 export { RelatedListSection } from "./components/related-list-section.js";
 export { RenderEdit } from "./components/render-edit.js";
 export { needsActionConfirm } from "./components/render-edit-action-button.js";