@cosmicdrift/kumiko-framework 0.373.0 → 0.377.0

package/dist/engine/boot-validator/screens.js

@@ -6,6 +6,7 @@
 import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
 import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs, SELECT_OPTION_TONES, } from "@cosmicdrift/kumiko-types/fields";
 import { NAV_ICON_KEYS } from "@cosmicdrift/kumiko-types/nav-icon";
+import { DASHBOARD_MIN_REFRESH_SECONDS } from "@cosmicdrift/kumiko-types/screen";
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { isListFilterAllowed } from "../../db/entity-field-encryption.js";
 import { rowMetaFieldNames } from "../../db/table-builder.js";
@@ -18,11 +19,14 @@ import { explicitListScreenId, isExtensionEditSection, isFieldsEditSection, isWr
 import { metricField } from "../types/index.js";
 import { LIST_ROW_META_COLUMN_NAMES } from "./entity-list-screens.js";
 import { isSelectOptionTone } from "./select-option-tone.js";
+function isRowClickAction(action) {
+    return (action.kind === "navigate" || action.kind === "drawer") && action.rowClick === true;
+}
 // entityList and projectionList both allow a rowAction to double as the
 // row-body click target (rowClick: true, fw#1708/#2164) — at most one per
 // screen, or the renderer can't tell which one should fire.
 function validateAtMostOneRowClick(featureName, screenId, screenType, rowActions) {
-    const rowClickActions = rowActions.filter((a) => a.kind === "navigate" && a.rowClick === true);
+    const rowClickActions = rowActions.filter(isRowClickAction);
     if (rowClickActions.length > 1) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has ${rowClickActions.length} ` +
             "rowActions marked rowClick:true — at most one may fire on a row-body click. Mark at most one rowAction with rowClick: true.");
@@ -72,6 +76,48 @@ function validateEditFieldExtras(featureName, screenId, entityDef, fieldSpec) {
             `"${fieldDef.type}" (displayName and email need text; id needs text or a reference). Use a fitting field type or a different prefill property.`);
     }
 }
+// `{ field }` affixes and fillAction params read live form values, so every
+// name must be a field of the same form — a typo would otherwise render no
+// affix or send an undefined param without a hint.
+function validateFieldFormRefs(where, fieldSpec, formFieldNames) {
+    const affixes = [
+        ["prefix", fieldSpec.prefix],
+        ["suffix", fieldSpec.suffix],
+    ];
+    for (const [prop, affix] of affixes) {
+        if (affix === undefined || typeof affix === "string")
+            continue;
+        if (!formFieldNames.has(affix.field)) {
+            throw new Error(`${where} ${prop} references unknown field "${affix.field}" — it must be another field of the same form.`);
+        }
+    }
+    const params = fieldSpec.fillAction?.params;
+    // skip: no fill-action params to cross-check
+    if (params === undefined)
+        return;
+    const sourceFields = "pick" in params ? params.pick : Object.values(params.map);
+    for (const sourceField of sourceFields) {
+        if (!formFieldNames.has(sourceField)) {
+            throw new Error(`${where} fillAction.params reads unknown field "${sourceField}" — it must be a field of the same form.`);
+        }
+    }
+}
+const FILL_ACTION_FIELD_TYPES = ["text", "number", "decimal", "bigInt"];
+// The fill button writes a plain text or numeric query result into the field;
+// a secret value must never be filled from a query response.
+function validateFillActionTarget(where, fieldSpec, fieldDef) {
+    // skip: no fill action, or the field is unknown (reported elsewhere)
+    if (fieldSpec.fillAction === undefined || fieldDef === undefined)
+        return;
+    if (!FILL_ACTION_FIELD_TYPES.includes(fieldDef.type)) {
+        throw new Error(`${where} fillAction needs a ${FILL_ACTION_FIELD_TYPES.join(", ")} field, not "${fieldDef.type}". ` +
+            `Remove fillAction or use a fitting field type.`);
+    }
+    if (isSensitiveOrPasswordField(fieldDef)) {
+        throw new Error(`${where} fillAction targets a sensitive, writeOnly or password field — a query result is ` +
+            `never written into those. Remove fillAction.`);
+    }
+}
 function validateNoWidgetRequiredField(featureName, screenId, entityDef, fieldSpec) {
     const fieldDef = entityDef.fields[fieldSpec.field];
     // skip: field doesn't exist or its type already has a widget — nothing to validate.
@@ -273,7 +319,7 @@ function validateWizardLayout(featureName, screenId, screenType, layout, feature
 // typed IconKey, a closed union — but that only protects call sites this
 // repo's own `tsc --build` actually covers (samples and external consumers
 // aren't in that project graph). The renderer's actionIconFor
-// (renderer-web/src/primitives/index.tsx) already falls back to "no icon"
+// (renderer/src/web/primitives/index.tsx) already falls back to "no icon"
 // for an unregistered key instead of crashing — this check makes the same
 // gap fail loudly at boot instead of silently at render.
 function isRegisteredIcon(icon) {
@@ -400,25 +446,34 @@ function validateDrawerTargetAction(featureName, screenId, screenKind, actionLab
         return;
     validateDrawerPrefillKeys(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}"`, "drawer-target", action.screen, target, action.params);
 }
-export function validateDrawerPrefillKeys(where, targetLabel, targetScreenId, target, params) {
-    const renderedFieldNames = new Set();
-    for (const section of target.layout.sections) {
+function renderedEditFieldNames(sections) {
+    const names = new Set();
+    for (const section of sections) {
         if (!isFieldsEditSection(section))
             continue;
         for (const spec of sectionFieldSpecs(section))
-            renderedFieldNames.add(normalizeEditField(spec).field);
+            names.add(normalizeEditField(spec).field);
     }
+    return names;
+}
+function isSensitiveOrPasswordField(field) {
+    return (field !== undefined &&
+        (("sensitive" in field && field.sensitive === true) ||
+            ("writeOnly" in field && field.writeOnly === true) ||
+            ("format" in field && field.format === "password")));
+}
+export function validateDrawerPrefillKeys(where, targetLabel, targetScreenId, target, params) {
+    const renderedFieldNames = renderedEditFieldNames(target.layout.sections);
     for (const fieldName of rowFieldExtractorKeys(params)) {
+        // A `load` form reads only the record id from these params, never a value.
+        if (fieldName === "id" && target.type === "actionForm" && target.load !== undefined)
+            continue;
         if (!Object.hasOwn(target.fields, fieldName)) {
             throw new Error(`${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" does not declare as a ` +
                 `field — the renderer would drop it and leave the form empty. Target fields: ` +
                 `${Object.keys(target.fields).sort().join(", ") || "(none)"}.`);
         }
-        const targetField = target.fields[fieldName];
-        const isSensitiveOrPassword = targetField !== undefined &&
-            (("sensitive" in targetField && targetField.sensitive === true) ||
-                ("format" in targetField && targetField.format === "password"));
-        if (isSensitiveOrPassword) {
+        if (isSensitiveOrPasswordField(target.fields[fieldName])) {
             throw new Error(`${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" marks as ` +
                 `sensitive or password — the renderer never prefills those fields and would leave the form empty. Remove that param or prefill a non-sensitive field.`);
         }
@@ -668,7 +723,7 @@ function validateFieldsXorGroups(errorPrefix, section) {
             `fields (or groups) to it.`);
     }
 }
-function validateFormLayoutSections(featureName, screenId, context, layout, fieldNames, allowEmptySections) {
+function validateFormLayoutSections(featureName, screenId, context, layout, fieldNames, fieldDefs, allowEmptySections) {
     if (layout.sections.length === 0) {
         // skip: an input-less secretMint declares fields: {} and sections: [] together — no sections to validate.
         if (allowEmptySections)
@@ -700,6 +755,9 @@ function validateFormLayoutSections(featureName, screenId, context, layout, fiel
                 throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) layout references unknown field ` +
                     `"${normalized.field}". Known fields: ${[...fieldNames].sort().join(", ")}`);
             }
+            const fieldWhere = `[Feature ${featureName}] Screen "${screenId}" (${context}) field "${normalized.field}"`;
+            validateFieldFormRefs(fieldWhere, normalized, fieldNames);
+            validateFillActionTarget(fieldWhere, normalized, fieldDefs[normalized.field]);
         }
     }
 }
@@ -710,22 +768,24 @@ function validateFormLayoutSections(featureName, screenId, context, layout, fiel
 // form (fw#2670) carries the same target under `screen` plus the payload
 // field `idFrom`. Shared by actionForm/secretMint (validateInlineFormNavTargets)
 // and entityEdit — same rule, same error message, one place to keep them in sync.
-function validateRedirectTarget(feature, screenId, screenKind, redirect, lookups) {
+function validateRedirectTarget(feature, screenId, screenKind, redirect, lookups, 
+// Property name used in error messages (`successLinks[0]` for a success link).
+propertyPath = "redirect") {
     const { allScreenQns } = lookups;
     const redirectTarget = typeof redirect === "string" ? redirect : redirect.screen;
     if (typeof redirect !== "string" &&
         (typeof redirect.idFrom !== "string" || redirect.idFrom.trim() === "")) {
-        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) redirect.idFrom is empty or not a string — ` +
+        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom is empty or not a string — ` +
             `name the success-payload field carrying the navigation id, or use the plain string ` +
             `redirect form to navigate with the handler's own "id".`);
     }
     // The renderer reads idFrom verbatim (Object.hasOwn), so stray whitespace
     // never matches and the navigation silently lands without an entityId.
     if (typeof redirect !== "string" && redirect.idFrom !== redirect.idFrom.trim()) {
-        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) redirect.idFrom "${redirect.idFrom}" ` +
+        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom "${redirect.idFrom}" ` +
             `has leading/trailing whitespace — it would never match a payload field. Remove the whitespace from idFrom.`);
     }
-    validateScreenNavTarget(feature.name, screenId, screenKind, "redirect", redirectTarget, allScreenQns, feature.screens);
+    validateScreenNavTarget(feature.name, screenId, screenKind, propertyPath, redirectTarget, allScreenQns, feature.screens);
     // idFrom only means something to a target that carries a record id; the
     // renderer drops it silently otherwise. Cross-feature QN targets can't be
     // typed from here and stay unchecked.
@@ -734,21 +794,58 @@ function validateRedirectTarget(feature, screenId, screenKind, redirect, lookups
         sameFeatureTarget !== undefined &&
         sameFeatureTarget.type !== "entityEdit" &&
         sameFeatureTarget.type !== "projectionDetail") {
-        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) redirect.idFrom is set but target screen ` +
+        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom is set but target screen ` +
             `"${redirectTarget}" (${sameFeatureTarget.type}) carries no id — use the plain string form.`);
     }
     if (typeof redirect !== "string" && redirect.tab !== undefined) {
-        const targetQn = resolveScreenTargetQn(feature.name, redirectTarget);
-        const target = lookups.screensByShortId
-            .get(targetQn.slice(targetQn.lastIndexOf(":") + 1))
-            ?.find((entry) => qualifyEntityName(entry.featureName, "screen", entry.screen.id) === targetQn);
-        validateRowActionNavigateTab(feature.name, screenId, screenKind, "redirect", { kind: "navigate", id: redirectTarget, label: redirectTarget, tab: redirect.tab }, target);
-    }
+        validateRowActionNavigateTab(feature.name, screenId, screenKind, propertyPath, { kind: "navigate", id: redirectTarget, label: redirectTarget, tab: redirect.tab }, findNavTargetEntry(feature, redirectTarget, lookups));
+    }
+}
+function findNavTargetEntry(feature, target, lookups) {
+    const targetQn = resolveScreenTargetQn(feature.name, target);
+    return lookups.screensByShortId
+        .get(targetQn.slice(targetQn.lastIndexOf(":") + 1))
+        ?.find((entry) => qualifyEntityName(entry.featureName, "screen", entry.screen.id) === targetQn);
+}
+// A success link without idFrom navigates without an id, so its target must not
+// be a record screen (entityEdit/projectionDetail need one).
+function validateIdlessSuccessLink(feature, screenId, screenKind, link, lookups, propertyPath) {
+    validateScreenNavTarget(feature.name, screenId, screenKind, propertyPath, link.screen, lookups.allScreenQns, feature.screens);
+    const target = findNavTargetEntry(feature, link.screen, lookups);
+    const targetType = target?.screen.type;
+    if (targetType === "entityEdit" || targetType === "projectionDetail") {
+        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath} targets "${link.screen}" ` +
+            `(${targetType}), a record screen — set ${propertyPath}.idFrom to the success-payload field carrying the record id.`);
+    }
+    if (link.tab !== undefined) {
+        validateRowActionNavigateTab(feature.name, screenId, screenKind, propertyPath, { kind: "navigate", id: link.screen, label: link.screen, tab: link.tab }, target);
+    }
+}
+// A clientAction names a handler a client feature registers
+// (ClientFeatureDefinition.clientActions). Nothing server-side can confirm the
+// registration, so the shape is the only boot-time check.
+function validateClientActionName(featureName, screenId, screenKind, actionLabel, action) {
+    const segments = action.action.split(":");
+    const [scope, name] = segments;
+    const wellFormed = segments.length === 2 &&
+        scope !== undefined &&
+        name !== undefined &&
+        isKebabSegment(scope) &&
+        isKebabSegment(name);
+    // skip: well-formed name, nothing to reject
+    if (wellFormed)
+        return;
+    throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
+        `action "${action.action}" is not a client action name — expected "<feature>:<kebab-name>", ` +
+        `e.g. "auth-email-password:request-password-reset".`);
 }
 // redirect is only honored on record actions; on list/related-list row
 // actions it would be silently dropped, so the author would believe it works.
 function rejectRedirectOnListRowAction(featureName, screenId, screenKind, action) {
-    if (action.kind !== "navigate" && action.kind !== "drawer" && action.redirect !== undefined) {
+    if (action.kind !== "navigate" &&
+        action.kind !== "drawer" &&
+        action.kind !== "clientAction" &&
+        action.redirect !== undefined) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) rowAction "${action.id}" sets redirect — ` +
             `redirect is only honored on record actions (projectionDetail/entityEdit header and section ` +
             `actions) and is ignored on list row actions. Remove it.`);
@@ -757,7 +854,10 @@ function rejectRedirectOnListRowAction(featureName, screenId, screenKind, action
 // A writeHandler record action's redirect (projectionDetail/entityEdit
 // header and section actions) follows the entityEdit.redirect rule.
 function validateRecordActionRedirect(feature, screenId, screenKind, action, lookups) {
-    if (action.kind !== "navigate" && action.kind !== "drawer" && action.redirect !== undefined) {
+    if (action.kind !== "navigate" &&
+        action.kind !== "drawer" &&
+        action.kind !== "clientAction" &&
+        action.redirect !== undefined) {
         validateRedirectTarget(feature, screenId, screenKind, action.redirect, lookups);
     }
 }
@@ -809,6 +909,27 @@ function validateInlineFormNavTargets(feature, screenId, screen, kind, lookups)
     if (screen.redirect !== undefined) {
         validateRedirectTarget(feature, screenId, kind, screen.redirect, lookups);
     }
+    if (screen.type === "actionForm" &&
+        screen.successFacts !== undefined &&
+        screen.redirect !== undefined) {
+        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both redirect and successFacts — ` +
+            `redirect leaves the screen, successFacts are shown on it. Use one of them.`);
+    }
+    if (screen.type === "actionForm" && screen.successLinks !== undefined) {
+        if (screen.redirect !== undefined) {
+            throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both redirect and successLinks — ` +
+                `redirect leaves the screen, successLinks keep it open. Use one of them.`);
+        }
+        screen.successLinks.forEach((link, index) => {
+            const propertyPath = `successLinks[${index}]`;
+            if (link.idFrom === undefined) {
+                validateIdlessSuccessLink(feature, screenId, "actionForm", link, lookups, propertyPath);
+            }
+            else {
+                validateRedirectTarget(feature, screenId, kind, { ...link, idFrom: link.idFrom }, lookups, propertyPath);
+            }
+        });
+    }
     if (typeof screen.cancelTarget === "string") {
         // Same rule as redirect — `false` (no Cancel button) needs no validation.
         validateScreenNavTarget(feature.name, screenId, kind, "cancelTarget", screen.cancelTarget, allScreenQns, feature.screens);
@@ -822,7 +943,7 @@ function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandl
     // (input-less mint, fw#2838) — actionForm always needs at least one field.
     const allowEmptyMintForm = kind === "secretMint";
     const fieldNames = validateFormFieldsMap(feature.name, screenId, kind, screen.fields, allowEmptyMintForm);
-    validateFormLayoutSections(feature.name, screenId, kind, screen.layout, fieldNames, allowEmptyMintForm && fieldNames.size === 0);
+    validateFormLayoutSections(feature.name, screenId, kind, screen.layout, fieldNames, screen.fields, allowEmptyMintForm && fieldNames.size === 0);
     validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap);
     validateInlineFormNavTargets(feature, screenId, screen, kind, lookups);
 }
@@ -842,7 +963,7 @@ function validateSecretMintConfirm(feature, screenId, screen, allWriteHandlerQns
     const context = "secretMint confirm";
     validateWriteHandlerRegistered(feature.name, screenId, context, confirm.handler, allWriteHandlerQns);
     const fieldNames = validateFormFieldsMap(feature.name, screenId, context, confirm.fields, false);
-    validateFormLayoutSections(feature.name, screenId, context, confirm.layout, fieldNames, false);
+    validateFormLayoutSections(feature.name, screenId, context, confirm.layout, fieldNames, confirm.fields, false);
     if (confirm.layout.mode !== undefined && confirm.layout.mode !== "single") {
         throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${context}) sets layout.mode: ` +
             `"${confirm.layout.mode}" — a one-time reveal confirm step must stay a single-step form. ` +
@@ -991,6 +1112,9 @@ function validateListActionTargets(ctx, actionLabel, action) {
     else if (action.kind === "drawer") {
         validateDrawerTargetAction(featureName, screenId, screenType, actionLabel, action, ctx.screens);
     }
+    else if (action.kind === "clientAction") {
+        validateClientActionName(featureName, screenId, screenType, actionLabel, action);
+    }
     else if (!ctx.allWriteHandlerQns.has(action.handler)) {
         throw new Error(`[Feature ${featureName}] ${ctx.where} ` +
             `${actionLabel} "${action.id}" handler "${action.handler}" ` +
@@ -1019,7 +1143,7 @@ function validateRelatedListRowActions(args, rowActions) {
     // marked rowClick:true both claim the row-body click — same
     // at-most-one constraint as entityList/projectionList's
     // validateAtMostOneRowClick, just spanning two fields instead of one.
-    const rowClickActionCount = rowActions.filter((a) => a.kind === "navigate" && a.rowClick === true).length;
+    const rowClickActionCount = rowActions.filter(isRowClickAction).length;
     const legacyRowClickCount = section.rowClick !== undefined ? 1 : 0;
     if (rowClickActionCount + legacyRowClickCount > 1) {
         throw new Error(`[Feature ${featureName}] ${where} ` +
@@ -1160,6 +1284,9 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     else if (action.kind === "drawer") {
                         validateDrawerTargetAction(feature.name, screenId, "projectionList", "rowAction", action, feature.screens);
                     }
+                    else if (action.kind === "clientAction") {
+                        validateClientActionName(feature.name, screenId, "projectionList", "rowAction", action);
+                    }
                 }
                 validateAtMostOneRowClick(feature.name, screenId, "projectionList", screen.rowActions);
             }
@@ -1420,7 +1547,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 for (const action of screen.actions) {
                     validateActionHasIcon(feature.name, screenId, "projectionDetail", "action", action);
                     validateRecordActionRedirect(feature, screenId, "projectionDetail", action, navigateLookups);
-                    if (action.kind === "navigate" && action.rowClick === true) {
+                    if (isRowClickAction(action)) {
                         throw new Error(`[Feature ${feature.name}] Screen "${qualifyEntityName(feature.name, "screen", screenId)}" ` +
                             `(projectionDetail) action "${action.id}" sets rowClick: true — there is no row to ` +
                             `click on a detail screen. Remove rowClick.`);
@@ -1432,6 +1559,9 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     else if (action.kind === "drawer") {
                         validateDrawerTargetAction(feature.name, screenId, "projectionDetail", "action", action, feature.screens);
                     }
+                    else if (action.kind === "clientAction") {
+                        validateClientActionName(feature.name, screenId, "projectionDetail", "action", action);
+                    }
                     else {
                         if (!allWriteHandlerQns.has(action.handler)) {
                             throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) action "${action.id}" ` +
@@ -1445,6 +1575,13 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
         }
         if (screen.type === "dashboard") {
             validateDashboardScreen(feature.name, screenId, screen, featureMap);
+            validateDashboardRecordBinding(feature.name, screenId, screen);
+            validateDashboardActions(feature.name, screenId, screen, allWriteHandlerQns, {
+                allScreenQns,
+                navTargetShortIds,
+                screensByShortId,
+                detailForScreens,
+            });
             continue;
         }
         if (screen.type === "configEdit") {
@@ -1744,6 +1881,9 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     else if (action.kind === "drawer") {
                         validateDrawerTargetAction(feature.name, screenId, "entityList", "rowAction", action, feature.screens);
                     }
+                    else if (action.kind === "clientAction") {
+                        validateClientActionName(feature.name, screenId, "entityList", "rowAction", action);
+                    }
                     else {
                         if (!allWriteHandlerQns.has(action.handler)) {
                             throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) rowAction "${action.id}" ` +
@@ -1846,6 +1986,9 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     }
                     validateNoWidgetRequiredField(feature.name, screenId, entityDef, normalized);
                     validateEditFieldExtras(feature.name, screenId, entityDef, normalized);
+                    const fieldWhere = `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) field "${normalized.field}"`;
+                    validateFieldFormRefs(fieldWhere, normalized, fieldNames);
+                    validateFillActionTarget(fieldWhere, normalized, entityDef.fields[normalized.field]);
                 }
             }
             validateWizardLayout(feature.name, screenId, "entityEdit", screen.layout, featureMap);
@@ -1856,7 +1999,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             if (screen.actions !== undefined) {
                 for (const action of screen.actions) {
                     validateRecordActionRedirect(feature, screenId, "entityEdit", action, navigateLookups);
-                    if (action.kind === "navigate" && action.rowClick === true) {
+                    if (isRowClickAction(action)) {
                         throw new Error(`[Feature ${feature.name}] Screen "${qualifyEntityName(feature.name, "screen", screenId)}" ` +
                             `(entityEdit) action "${action.id}" sets rowClick: true — there is no row to click ` +
                             `on an edit screen. Remove rowClick.`);
@@ -1868,6 +2011,9 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     else if (action.kind === "drawer") {
                         validateDrawerTargetAction(feature.name, screenId, "entityEdit", "action", action, feature.screens);
                     }
+                    else if (action.kind === "clientAction") {
+                        validateClientActionName(feature.name, screenId, "entityEdit", "action", action);
+                    }
                     else {
                         if (!allWriteHandlerQns.has(action.handler)) {
                             throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityEdit) action "${action.id}" ` +
@@ -1919,6 +2065,9 @@ function validateDashboardScreen(featureName, screenId, screen, featureMap) {
         else if (panel.kind === "screen") {
             validateDashboardScreenPanel(featureName, screenId, panel, featureMap);
         }
+        else if (panel.kind === "text") {
+            validateDashboardTextPanel(featureName, screenId, panel);
+        }
         else {
             validateDashboardQueryPanel(featureName, screenId, panel, featureMap);
         }
@@ -1930,6 +2079,107 @@ function validateDashboardScreen(featureName, screenId, screen, featureMap) {
         validateDashboardTimeRange(featureName, screenId, screen.timeRange, screen.filter?.id);
     }
 }
+function validateDashboardActions(featureName, screenId, screen, allWriteHandlerQns, lookups) {
+    const { allScreenQns, navTargetShortIds, screensByShortId, detailForScreens } = lookups;
+    // Header actions run on the bound record like projectionDetail's, minus
+    // what needs a drawer host or a record screen to leave.
+    for (const action of screen.actions ?? []) {
+        const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard) action "${action.id}"`;
+        validateActionHasIcon(featureName, screenId, "dashboard", "action", action);
+        if (isRowClickAction(action)) {
+            throw new Error(`${where} sets rowClick: true — a dashboard has no row to click. Remove rowClick.`);
+        }
+        if (action.kind === "drawer") {
+            throw new Error(`${where} is a drawer action — a dashboard has no drawer host. Use a navigate, ` +
+                `writeHandler or clientAction action.`);
+        }
+        if (action.kind === "navigate") {
+            const target = resolveRowActionNavigateTarget(featureName, screenId, "dashboard", "action", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
+            validateRowActionNavigateParams(featureName, screenId, "dashboard", screen.detailFor, action, target);
+        }
+        else if (action.kind === "clientAction") {
+            validateClientActionName(featureName, screenId, "dashboard", "action", action);
+        }
+        else {
+            if (action.redirect !== undefined) {
+                throw new Error(`${where} sets redirect — a dashboard action stays on the dashboard and refetches ` +
+                    `after success. Remove redirect.`);
+            }
+            if (!allWriteHandlerQns.has(action.handler)) {
+                throw new Error(`${where} handler "${action.handler}" is not a registered write-handler. Check the QN ` +
+                    `spelling (expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
+            }
+        }
+    }
+}
+// record / actions / refresh hang together: actions and a field-driven refresh
+// read the record row, and the record id travels in the URL next to the
+// filter and time-range values.
+function validateDashboardRecordBinding(featureName, screenId, screen) {
+    const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard)`;
+    const { record, refresh } = screen;
+    if (record === undefined) {
+        if (screen.actions !== undefined) {
+            throw new Error(`${where} declares actions without a record — the actions run on the bound record. ` +
+                `Add record: { param } or remove actions.`);
+        }
+    }
+    else {
+        validateDashboardRecordShape(where, record, [screen.filter?.id, screen.timeRange?.id]);
+    }
+    // skip: no refresh declared, nothing to validate
+    if (refresh === undefined)
+        return;
+    validateDashboardRefresh(where, refresh, record);
+}
+function validateDashboardRecordShape(where, record, otherUrlParamIds) {
+    if (typeof record.param !== "string" || record.param.length === 0) {
+        throw new Error(`${where} record.param is empty. Name the URL search param carrying the id.`);
+    }
+    if (record.payloadKey !== undefined && record.payloadKey.length === 0) {
+        throw new Error(`${where} record.payloadKey is empty. Omit it to reuse record.param as the payload key.`);
+    }
+    if (record.query !== undefined && record.query.length === 0) {
+        throw new Error(`${where} record.query is empty. Set a registered query name or omit it.`);
+    }
+    if (record.titleField !== undefined && isTitleFieldUnusable(record)) {
+        throw new Error(`${where} record.titleField needs record.query and a field name — the title is read ` +
+            `from the record row.`);
+    }
+    const payloadKey = record.payloadKey ?? record.param;
+    for (const other of otherUrlParamIds) {
+        if (other !== undefined && (other === record.param || other === payloadKey)) {
+            throw new Error(`${where} record.param/payloadKey "${other}" collides with the filter or timeRange id — ` +
+                `all of them live in the URL search params and panel payloads. Use a different name.`);
+        }
+    }
+}
+function isTitleFieldUnusable(record) {
+    return record.query === undefined || record.titleField === "";
+}
+function validateDashboardRefresh(where, refresh, record) {
+    if ("seconds" in refresh && "field" in refresh) {
+        throw new Error(`${where} refresh sets both seconds and field — set exactly one.`);
+    }
+    if ("seconds" in refresh) {
+        if (!isRefreshSecondsAllowed(refresh.seconds)) {
+            throw new Error(`${where} refresh.seconds "${String(refresh.seconds)}" must be a number of at least ` +
+                `${DASHBOARD_MIN_REFRESH_SECONDS} — shorter intervals would hammer every panel query.`);
+        }
+        // skip: seconds validated, field rules below do not apply
+        return;
+    }
+    if (refresh.field.length === 0) {
+        throw new Error(`${where} refresh.field is empty. Name the record field holding the seconds.`);
+    }
+    if (record?.query === undefined) {
+        throw new Error(`${where} refresh.field "${refresh.field}" needs record.query to read the seconds from. ` +
+            `Add record: { param, query } or use refresh: { seconds }.`);
+    }
+}
+function isRefreshSecondsAllowed(seconds) {
+    return Number.isFinite(seconds) && seconds >= DASHBOARD_MIN_REFRESH_SECONDS;
+}
 function validateDashboardTimeRange(featureName, screenId, timeRange, filterId) {
     const prefix = `[Feature ${featureName}] Screen "${screenId}" (dashboard) timeRange`;
     if (timeRange.id.length === 0)
@@ -1961,13 +2211,12 @@ const EMBEDDABLE_SCREEN_TYPES = new Set([
     "configEdit",
     "secretsEdit",
 ]);
-export function validateDashboardScreenPanel(featureName, screenId, panel, featureMap) {
-    const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}"`;
-    const targetQn = resolveScreenTargetQn(featureName, panel.screen);
+function validateEmbeddableScreenRef(context, prop, ref, featureName, featureMap) {
+    const targetQn = resolveScreenTargetQn(featureName, ref);
     const [targetFeatureName = "", , targetShortId = ""] = targetQn.split(":");
     const target = featureMap.get(targetFeatureName)?.screens[targetShortId];
     if (target === undefined) {
-        throw new Error(`${context} screen "${panel.screen}" does not resolve to a registered screen (checked "${targetQn}"). ` +
+        throw new Error(`${context} ${prop} "${ref}" does not resolve to a registered screen (checked "${targetQn}"). ` +
             `Use a same-feature short id or a cross-feature QN "<feature>:screen:<id>".`);
     }
     if (!EMBEDDABLE_SCREEN_TYPES.has(target.type)) {
@@ -1983,7 +2232,36 @@ export function validateDashboardScreenPanel(featureName, screenId, panel, featu
             `navigate away from the dashboard on submit or cancel. Embed a screen without redirect and ` +
             `with cancelTarget: false (or omitted).`);
     }
+    return target;
+}
+export function validateDashboardScreenPanel(featureName, screenId, panel, featureMap) {
+    const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}"`;
+    validateEmbeddableScreenRef(context, "screen", panel.screen, featureName, featureMap);
+    validateDashboardPanelVisibleWhen(context, panel.visibleWhen);
+    // skip: no fallback declared, nothing more to validate
+    if (panel.fallback === undefined)
+        return;
+    if (panel.visibleWhen === undefined) {
+        throw new Error(`${context} declares fallback without visibleWhen. Add visibleWhen or remove fallback.`);
+    }
+    const target = validateEmbeddableScreenRef(context, "fallback", panel.fallback, featureName, featureMap);
+    // A gated fallback could hide in turn; the tile would show nothing where it promised a stand-in.
+    if (target.visibleWhen !== undefined) {
+        throw new Error(`${context} fallback "${panel.fallback}" has its own visibleWhen; a fallback must always render.`);
+    }
+}
+function validateDashboardTextPanel(featureName, screenId, panel) {
+    const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) text-panel "${panel.id}"`;
+    if (panel.blocks.length === 0) {
+        throw new Error(`${context} has an empty blocks list. Add at least one block.`);
+    }
+    validateDashboardPanelSpan(featureName, screenId, panel);
     validateDashboardPanelVisibleWhen(context, panel.visibleWhen);
+    for (const block of panel.blocks) {
+        if (block.kind === "list" && block.items.length === 0) {
+            throw new Error(`${context} has a list block without items. Add items or remove the block.`);
+        }
+    }
 }
 function validateDashboardPanelVisibleWhen(context, visibleWhen) {
     if (visibleWhen !== undefined && (visibleWhen.query === "" || visibleWhen.field === "")) {
@@ -2016,7 +2294,7 @@ function validateDashboardStatGroupPanel(featureName, screenId, panel, addPanelI
         if (stat.valueField.length === 0) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty valueField. Set valueField to a field of the query result.`);
         }
-        validateDashboardValueFormat(featureName, screenId, stat.id, stat.valueFormat);
+        validateDashboardValueFormat(featureName, screenId, stat.id, stat.valueFormat, STAT_VALUE_FORMATS);
     }
 }
 function validateFromTodayWindowReach(where, panel) {
@@ -2024,15 +2302,21 @@ function validateFromTodayWindowReach(where, panel) {
         throw new Error(`${where}.initialWindow "from-today" needs ranges or brush, otherwise data before today is unreachable.`);
     }
 }
-function validateDashboardChartDisplay(featureName, screenId, panel) {
-    validateDashboardValueFormat(featureName, screenId, panel.id, panel.valueFormat);
-    const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard) chart-panel "${panel.id}"`;
+function validateChartScrollableAndUnit(where, panel) {
     if (panel.scrollable !== undefined && typeof panel.scrollable !== "boolean") {
         throw new Error(`${where} has a non-boolean scrollable. Use true or false.`);
     }
     if (panel.scrollable === true && panel.chart !== "stacked-area") {
         throw new Error(`${where} sets scrollable on chart "${panel.chart}" — only "stacked-area" supports it. Remove scrollable or use chart "stacked-area".`);
     }
+    if (panel.unit !== undefined && panel.chart !== "timeseries") {
+        throw new Error(`${where} sets unit on chart "${panel.chart}" — only "timeseries" supports it. Remove unit or use chart "timeseries".`);
+    }
+}
+function validateDashboardChartDisplay(featureName, screenId, panel) {
+    validateDashboardValueFormat(featureName, screenId, panel.id, panel.valueFormat, CHART_VALUE_FORMATS);
+    const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard) chart-panel "${panel.id}"`;
+    validateChartScrollableAndUnit(where, panel);
     validateStackedAreaOnlyProps(where, panel);
     validateStackedAreaEnumProp(where, "dateFormat", panel.dateFormat, ["day", "month"]);
     validateStackedAreaEnumProp(where, "initialWindow", panel.initialWindow, [
@@ -2125,14 +2409,22 @@ function validateDashboardChartRanges(where, ranges) {
 }
 const CURRENCY_CODE_RE = /^[A-Z]{3}$/;
 const MAX_VALUE_FORMAT_FRACTION_DIGITS = 4;
-function validateDashboardValueFormat(featureName, screenId, panelId, valueFormat) {
+const STAT_VALUE_FORMATS = [
+    "currency",
+    "relativeTime",
+];
+const CHART_VALUE_FORMATS = ["currency"];
+function validateDashboardValueFormat(featureName, screenId, panelId, valueFormat, allowedKinds) {
     // skip: valueFormat is optional, nothing to validate without it
     if (valueFormat === undefined)
         return;
     const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panelId}" valueFormat`;
-    if (valueFormat.kind !== "currency") {
-        throw new Error(`${where}.kind "${String(valueFormat.kind)}" must be "currency".`);
+    if (!allowedKinds.includes(valueFormat.kind)) {
+        throw new Error(`${where}.kind "${String(valueFormat.kind)}" must be ${allowedKinds.map((kind) => `"${kind}"`).join(" or ")}.`);
     }
+    // skip: relativeTime carries no options
+    if (valueFormat.kind === "relativeTime")
+        return;
     if (!CURRENCY_CODE_RE.test(valueFormat.currency)) {
         throw new Error(`${where}.currency "${String(valueFormat.currency)}" must be a 3-letter uppercase ISO currency code.`);
     }
@@ -2157,7 +2449,7 @@ function validateDashboardQueryPanel(featureName, screenId, panel, featureMap) {
         if (panel.valueField.length === 0) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField. Set valueField to a field of the query result.`);
         }
-        validateDashboardValueFormat(featureName, screenId, panel.id, panel.valueFormat);
+        validateDashboardValueFormat(featureName, screenId, panel.id, panel.valueFormat, STAT_VALUE_FORMATS);
     }
     validateDashboardPanelVisibleWhen(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}"`, panel.visibleWhen);
     if (panel.kind === "chart")

package/dist/engine/boot-validator/url-prefill-fields.js

@@ -173,6 +173,9 @@ export function validateSubmitPrefilledHiddenFields(features) {
                 validateDrawerPrefillKeys(source.sourceLabel, "navigate-target", screenId, screen, source.params);
             }
             const seeded = new Set((sources ?? []).flatMap((source) => rowFieldExtractorKeys(source.params)));
+            // A `load` form is seeded from the loaded record, not from navigate params.
+            if (screen.type === "actionForm" && screen.load !== undefined)
+                continue;
             assertHiddenRequiredFieldsSeeded(feature.name, screenId, screen, seeded);
         }
     }