@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/engine/boot-validator/screens-kind-projection-detail.js

@@ -0,0 +1,235 @@
+import { SELECT_OPTION_TONES } from "@cosmicdrift/kumiko-types/fields";
+import { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
+import { assertWriteHandlerRegistered, resolveRowActionNavigateTarget, validateActionHasIcon, validatePrimaryActionTarget, } from "./screens-actions.js";
+import { rejectWriteOnlyFormField, validateFieldsXorGroups, validateFormSelectOptions, validateTabSections, } from "./screens-forms.js";
+import { assertExtensionSectionHasComponent, editSectionLabel, listActionContext, navigateActionFromLink, rejectEmptySections, rejectMissingQuery, validateRecordHeaderAction, validateRecordSectionActions, } from "./screens-kind-shared.js";
+import { assertRefTargetRegistered, validateListActionTargets, validateRelatedListSection, } from "./screens-lists.js";
+import { isSelectOptionTone } from "./select-option-tone.js";
+function validateProjectionDetailFlags(featureName, screenId, screen) {
+    if (screen.singleton === true && screen.idParam !== undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) sets both singleton: true ` +
+            `and idParam — singleton means the server picks the row from the caller's context, so there ` +
+            `is no row id to send under idParam. Remove idParam.`);
+    }
+    // singleton has no row id in the path, but the auto-generated "Edit"
+    // action (defaultEditAction in kumiko-screen.tsx) navigates
+    // to the detailFor entity's entityEdit screen using that path id —
+    // under singleton it would silently open that screen in CREATE mode
+    // instead of editing the singleton row. Reject rather than let that
+    // win silently, same as the idParam check above.
+    if (screen.singleton === true && screen.detailFor !== undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) sets both singleton: true ` +
+            `and detailFor — the auto-generated "Edit" action navigates using the path's row id, which a ` +
+            `singleton screen never has. Remove detailFor, or declare an explicit "edit" action instead.`);
+    }
+    if (screen.recordTitleField !== undefined && screen.header !== undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) sets both header and ` +
+            `recordTitleField — header.title already names the record, so drop recordTitleField.`);
+    }
+}
+function validateProjectionDetailTabs(featureName, screenId, screen) {
+    if (screen.layout.mode === "tabs") {
+        validateTabSections(featureName, screenId, "projectionDetail", screen.layout.sections);
+        for (const section of screen.layout.sections) {
+            if (isFieldsEditSection(section) && "groups" in section && section.actions !== undefined) {
+                throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) section "${section.id}" ` +
+                    `declares both groups and actions in tabs mode — actions has no single group's Card to sit ` +
+                    `in, and an extra title-less Card around the group cards would nest a Card inside a Card. ` +
+                    `Move the actions onto one group's title, or drop groups for a flat fields grid.`);
+            }
+        }
+    }
+}
+function validateProjectionDetailMetricNavigate(ctx, screenId, screen, field, navigate) {
+    const featureName = ctx.feature.name;
+    if (navigate.screen === undefined && navigate.entity === undefined) {
+        if (navigate.tab !== undefined &&
+            !screen.layout.sections.some((section) => section.id === navigate.tab)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) metric "${field}" ` +
+                `navigates to tab "${navigate.tab}", which is not a section id on this screen. Navigate to an existing section id or remove navigate.tab.`);
+        }
+    }
+    else {
+        // Also runs without `tab`: a typo'd screen/entity or an entity
+        // target without entityId would otherwise render a clickable
+        // metric that silently does nothing.
+        resolveRowActionNavigateTarget(featureName, screenId, "projectionDetail", "metric", navigateActionFromLink(field, navigate), ctx.allScreenQns, ctx.navTargetShortIds, ctx.screensByShortId, ctx.detailForScreens);
+    }
+}
+function validateProjectionDetailMetric(ctx, screenId, screen, metric) {
+    if (typeof metric.label !== "string" || metric.label.length === 0) {
+        throw new Error(`[Feature ${ctx.feature.name}] Screen "${screenId}" (projectionDetail) metric "${metric.field}" has ` +
+            `no "label" — every metric needs an i18n label key, ` +
+            `there is no fallback to the raw column name.`);
+    }
+    if (metric.navigate !== undefined) {
+        validateProjectionDetailMetricNavigate(ctx, screenId, screen, metric.field, metric.navigate);
+    }
+}
+function validateProjectionDetailStatusTones(featureName, screenId, screen) {
+    for (const [statusValue, tone] of Object.entries(screen.header?.statusTones ?? {})) {
+        if (!isSelectOptionTone(tone)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) header.statusTones["${statusValue}"] ` +
+                `is "${String(tone)}" — expected one of ${SELECT_OPTION_TONES.join(", ")}.`);
+        }
+    }
+}
+function validateProjectionDetailSubtitleParts(ctx, screenId, subtitleHref, parts) {
+    const featureName = ctx.feature.name;
+    if (subtitleHref !== undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) sets header.subtitleHref ` +
+            `together with a multi-part header.subtitle — subtitleHref only works with the string form. Use a single-field subtitle or remove subtitleHref.`);
+    }
+    const seenPartFields = new Set();
+    for (const part of parts) {
+        const partField = typeof part === "string" ? part : part.field;
+        if (seenPartFields.has(partField)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) header.subtitle ` +
+                `lists field "${partField}" twice. List each field once.`);
+        }
+        seenPartFields.add(partField);
+        const navigate = typeof part === "string" ? undefined : part.navigate;
+        if (navigate === undefined)
+            continue;
+        if (navigate.screen === undefined && navigate.entity === undefined) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) header.subtitle part ` +
+                `"${partField}" navigates with neither "screen" nor "entity" — a tab-only navigate has no link target.`);
+        }
+        resolveRowActionNavigateTarget(featureName, screenId, "projectionDetail", "subtitle part", navigateActionFromLink(partField, navigate), ctx.allScreenQns, ctx.navTargetShortIds, ctx.screensByShortId, ctx.detailForScreens);
+    }
+}
+function validateProjectionDetailSubtitle(ctx, screenId, screen) {
+    const header = screen.header;
+    if (header !== undefined && Array.isArray(header.subtitle)) {
+        validateProjectionDetailSubtitleParts(ctx, screenId, header.subtitleHref, header.subtitle);
+    }
+}
+function validateProjectionDetailExtensionSection(featureName, screenId, section) {
+    // projectionDetail is read-only (no composed form submit) — an
+    // extension that persists through the host's Save button has
+    // nothing to save against. Extensions that persist themselves
+    // (e.g. notes-history NotesSection, via their own dispatcher
+    // writes) are fine.
+    if (section.contributesToFormSubmit === true) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) extension section ` +
+            `"${section.title}" sets contributesToFormSubmit: true, but projectionDetail has no ` +
+            `form submit to contribute to (read-only screen). Omit contributesToFormSubmit and ` +
+            `persist through the extension's own dispatcher writes instead.`);
+    }
+    assertExtensionSectionHasComponent(featureName, screenId, "projectionDetail", section);
+    // The host-derived entity name on projectionDetail is an internal
+    // placeholder (no real entity backs this screen) — a self-
+    // persisting extension needs the real domain entity name declared
+    // explicitly, or it silently reads/writes against the wrong type.
+    if (section.entityName === undefined || section.entityName.trim().length === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) extension section ` +
+            `"${section.title}" has no entityName — projectionDetail has no real entity, so the ` +
+            `extension must declare entityName explicitly (the domain entity it persists against).`);
+    }
+}
+function validateProjectionDetailRelatedList(ctx, screenId, screen, section) {
+    if (screen.layout.mode === "wizard") {
+        throw new Error(`[Feature ${ctx.feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+            `is kind "relatedList" in a wizard layout — a read-only list is not supported in a ` +
+            `stepped form. Remove mode: "wizard" or drop the relatedList section.`);
+    }
+    validateRelatedListSection({
+        featureName: ctx.feature.name,
+        featureMap: ctx.featureMap,
+        screenId,
+        screenType: "projectionDetail",
+        where: `Screen "${screenId}" (projectionDetail) section "${section.title}" (relatedList)`,
+        section,
+        screens: ctx.feature.screens,
+        allWriteHandlerQns: ctx.allWriteHandlerQns,
+        allScreenQns: ctx.allScreenQns,
+        navTargetShortIds: ctx.navTargetShortIds,
+        screensByShortId: ctx.screensByShortId,
+        detailForScreens: ctx.detailForScreens,
+    });
+}
+function validateProjectionDetailWriteForm(ctx, screenId, screen, section) {
+    const featureName = ctx.feature.name;
+    if (Object.keys(section.fieldDefs).length === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+            `(writeForm) has an empty fieldDefs map — declare at least one field type.`);
+    }
+    if (section.fields.length === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+            `(writeForm) has zero fields — drop the section or add fields to it.`);
+    }
+    // A ref to a fieldDef the form never renders would never resolve.
+    const writeFormFieldNames = new Set(section.fields.map((f) => normalizeEditField(f).field));
+    for (const [defName, fdef] of Object.entries(section.fieldDefs)) {
+        validateFormSelectOptions(featureName, screenId, `projectionDetail section "${section.title}" writeForm`, defName, fdef, writeFormFieldNames);
+        rejectWriteOnlyFormField(featureName, screenId, `projectionDetail section "${section.title}" writeForm`, defName, fdef);
+    }
+    for (const f of section.fields) {
+        const fieldName = normalizeEditField(f).field;
+        if (section.fieldDefs[fieldName] === undefined) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) field "${fieldName}" has no entry in fieldDefs — every rendered field needs ` +
+                `a type declared there. Add the field to fieldDefs.`);
+        }
+    }
+    if (screen.layout.mode === "wizard") {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+            `is kind "writeForm" in a wizard layout — a self-persisting form is not supported in a ` +
+            `stepped form. Remove mode: "wizard" or drop the writeForm section.`);
+    }
+    assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (projectionDetail) section "${section.title}" (writeForm)`, section.handler, ctx.allWriteHandlerQns);
+}
+function validateProjectionDetailFieldsSection(ctx, screenId, section) {
+    const featureName = ctx.feature.name;
+    validateFieldsXorGroups(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`, section);
+    for (const fieldSpec of sectionFieldSpecs(section)) {
+        const normalizedField = normalizeEditField(fieldSpec);
+        if (normalizedField.refEntity !== undefined) {
+            assertRefTargetRegistered(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`, `field "${normalizedField.field}" (refEntity)`, normalizedField.refEntity, featureName, ctx.featureMap);
+        }
+    }
+}
+function validateProjectionDetailSection(ctx, screenId, screen, section) {
+    const featureName = ctx.feature.name;
+    validateRecordSectionActions(ctx, screenId, "projectionDetail", section);
+    if (section.kind === "relatedList" && section.emptyState?.action !== undefined) {
+        const sectionLabel = editSectionLabel(section);
+        validateActionHasIcon(featureName, screenId, "projectionDetail", `section "${sectionLabel}" emptyState action`, section.emptyState.action);
+        validateListActionTargets(listActionContext(ctx, screenId, "projectionDetail", undefined, `Screen "${screenId}" (projectionDetail) section "${sectionLabel}"`), "emptyState action", section.emptyState.action);
+    }
+    if (isExtensionEditSection(section)) {
+        validateProjectionDetailExtensionSection(featureName, screenId, section);
+    }
+    else if (section.kind === "relatedList") {
+        validateProjectionDetailRelatedList(ctx, screenId, screen, section);
+    }
+    else if (isWriteFormEditSection(section)) {
+        validateProjectionDetailWriteForm(ctx, screenId, screen, section);
+    }
+    else {
+        validateProjectionDetailFieldsSection(ctx, screenId, section);
+    }
+}
+// Query-driven like projectionList, but a single row plus layout instead of
+// columns. No entity check is possible: fields resolve against the query
+// response at render time, not against an entity.
+export function validateProjectionDetailScreen(ctx, screenId, screen) {
+    const featureName = ctx.feature.name;
+    rejectMissingQuery(featureName, screenId, "projectionDetail", screen.query);
+    validateProjectionDetailFlags(featureName, screenId, screen);
+    rejectEmptySections(featureName, screenId, "projectionDetail", screen.layout.sections.length);
+    validateProjectionDetailTabs(featureName, screenId, screen);
+    for (const metric of screen.metrics ?? []) {
+        validateProjectionDetailMetric(ctx, screenId, screen, metric);
+    }
+    validateProjectionDetailStatusTones(featureName, screenId, screen);
+    validateProjectionDetailSubtitle(ctx, screenId, screen);
+    for (const section of screen.layout.sections) {
+        validateProjectionDetailSection(ctx, screenId, screen, section);
+    }
+    validatePrimaryActionTarget(featureName, screenId, screen);
+    for (const action of screen.actions ?? []) {
+        validateActionHasIcon(featureName, screenId, "projectionDetail", "action", action);
+        validateRecordHeaderAction(ctx, screenId, "projectionDetail", screen.detailFor, action);
+    }
+}

package/dist/engine/boot-validator/screens-kind-projection-list.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectionListScreenDefinition } from "../types/screen.ts";
+import { type ScreenValidationContext } from "./screens-kind-shared.ts";
+export declare function validateProjectionListScreen(ctx: ScreenValidationContext, screenId: string, screen: ProjectionListScreenDefinition): void;

package/dist/engine/boot-validator/screens-kind-projection-list.js

@@ -0,0 +1,52 @@
+import { normalizeListColumn } from "../screen-helpers.js";
+import { assertWriteHandlerRegistered, resolveRowActionNavigateTarget, validateAtMostOneRowClick, validateDrawerTargetAction, } from "./screens-actions.js";
+import { listActionContext, rejectEmptyColumns, rejectMissingQuery, rejectNonArrayInFilter, validateListColumnRendering, } from "./screens-kind-shared.js";
+import { validateListActionTargets, validateListFacets } from "./screens-lists.js";
+function validateProjectionListRowActions(ctx, screenId, rowActions) {
+    const listContext = listActionContext(ctx, screenId, "projectionList", undefined, `Screen "${screenId}" (projectionList)`);
+    for (const action of rowActions) {
+        validateListActionTargets(listContext, "rowAction", action);
+    }
+    validateAtMostOneRowClick(ctx.feature.name, screenId, "projectionList", rowActions);
+}
+// Plain navigate toolbarActions (no tab) have no boot check yet.
+function validateProjectionListToolbarActions(ctx, screenId, toolbarActions) {
+    const featureName = ctx.feature.name;
+    for (const action of toolbarActions) {
+        if (action.kind === "drawer") {
+            validateDrawerTargetAction(featureName, screenId, "projectionList", "toolbarAction", action, ctx.feature.screens);
+        }
+        else if (action.kind === "writeHandler") {
+            assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (projectionList) toolbarAction "${action.id}"`, action.handler, ctx.allWriteHandlerQns);
+        }
+        if (action.kind === "navigate" && action.tab !== undefined) {
+            resolveRowActionNavigateTarget(featureName, screenId, "projectionList", "toolbarAction", action, ctx.allScreenQns, ctx.navTargetShortIds, ctx.screensByShortId, ctx.detailForScreens);
+        }
+    }
+}
+// Query-driven, no entity, so only query + columns are checked (the column
+// fields cannot be checked against an entity; they resolve against the
+// projection rows at render time).
+export function validateProjectionListScreen(ctx, screenId, screen) {
+    const featureName = ctx.feature.name;
+    rejectMissingQuery(featureName, screenId, "projectionList", screen.query);
+    rejectEmptyColumns(featureName, screenId, "projectionList", screen.columns.length);
+    for (const col of screen.columns) {
+        validateListColumnRendering(ctx, screenId, "projectionList", normalizeListColumn(col));
+    }
+    // Screen filter: field existence can't be checked without an entity (columns
+    // aren't a complete field inventory of the underlying query), so only the
+    // structure is pinned: "in" requires an array.
+    if (screen.filter !== undefined) {
+        rejectNonArrayInFilter(featureName, screenId, "projectionList", screen.filter);
+    }
+    if (screen.facets !== undefined) {
+        validateListFacets(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen.facets, screen.columns, featureName, ctx.featureMap);
+    }
+    if (screen.rowActions !== undefined) {
+        validateProjectionListRowActions(ctx, screenId, screen.rowActions);
+    }
+    if (screen.toolbarActions !== undefined) {
+        validateProjectionListToolbarActions(ctx, screenId, screen.toolbarActions);
+    }
+}

package/dist/engine/boot-validator/screens-kind-secret-mint.d.ts

@@ -0,0 +1,3 @@
+import type { SecretMintScreenDefinition } from "../types/screen.ts";
+import type { ScreenValidationContext } from "./screens-kind-shared.ts";
+export declare function validateSecretMintScreen(ctx: ScreenValidationContext, screenId: string, screen: SecretMintScreenDefinition): void;

package/dist/engine/boot-validator/screens-kind-secret-mint.js

@@ -0,0 +1,28 @@
+import { validateInlineFormScreen, validateSecretMintConfirm } from "./screens-forms.js";
+function validateSecretMintRevealFields(featureName, screenId, screen) {
+    if (screen.reveal.fields.length === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (secretMint) has an empty reveal.fields ` +
+            `list — declare at least one field to reveal.`);
+    }
+    const revealFieldNames = new Set();
+    for (const revealField of screen.reveal.fields) {
+        if (typeof revealField.field !== "string" || revealField.field.trim() === "") {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (secretMint) has a reveal.fields entry ` +
+                `with an empty or non-string "field". Set field to a non-empty string.`);
+        }
+        if (revealFieldNames.has(revealField.field)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (secretMint) reveal.fields has a ` +
+                `duplicate field "${revealField.field}" — each revealed field must be unique.`);
+        }
+        revealFieldNames.add(revealField.field);
+        if (typeof revealField.label !== "string" || revealField.label.trim() === "") {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (secretMint) reveal.fields entry ` +
+                `"${revealField.field}" has an empty or non-string "label". Set label to a non-empty string.`);
+        }
+    }
+}
+export function validateSecretMintScreen(ctx, screenId, screen) {
+    validateInlineFormScreen(ctx.feature, screenId, screen, "secretMint", ctx.allWriteHandlerQns, ctx, ctx.featureMap);
+    validateSecretMintRevealFields(ctx.feature.name, screenId, screen);
+    validateSecretMintConfirm(ctx.feature, screenId, screen, ctx.allWriteHandlerQns);
+}

package/dist/engine/boot-validator/screens-kind-shared.d.ts

@@ -0,0 +1,37 @@
+import { type normalizeListColumn } from "../screen-helpers.ts";
+import type { ConfigKeyDefinition, EntityDefinition, FeatureDefinition } from "../types/index.ts";
+import type { EditExtensionSection, EditFieldsSection, EditSectionSpec, RowAction } from "../types/screen.ts";
+import type { NavigateSourceScreenType, NavigateTargetLookups } from "./screens-actions.ts";
+import { type resolveRowActionNavigateTarget } from "./screens-actions.ts";
+import type { ListActionTargetContext } from "./screens-lists.ts";
+export type ScreenValidationContext = NavigateTargetLookups & {
+    readonly feature: FeatureDefinition;
+    readonly featureMap: ReadonlyMap<string, FeatureDefinition>;
+    readonly allWriteHandlerQns: ReadonlySet<string>;
+    readonly configKeyDefsByQn: ReadonlyMap<string, ConfigKeyDefinition>;
+};
+export declare function findEntityFeature(entityName: string, featureMap: ReadonlyMap<string, FeatureDefinition>): string | undefined;
+export declare function buildUnknownFieldMessage(featureName: string, screenId: string, fieldName: string, entityName: string, knownFields: ReadonlySet<string>): string;
+export declare function listActionContext(ctx: ScreenValidationContext, screenId: string, screenType: NavigateSourceScreenType, screenEntity: string | undefined, where: string): ListActionTargetContext;
+export declare function resolveScreenEntity(ctx: ScreenValidationContext, screenId: string, entityName: string): EntityDefinition;
+export declare function rejectMissingQuery(featureName: string, screenId: string, kind: "projectionList" | "projectionDetail", query: unknown): void;
+export declare function rejectEmptyColumns(featureName: string, screenId: string, kind: "projectionList" | "entityList", columnCount: number): void;
+export declare function validateListColumnRendering(ctx: ScreenValidationContext, screenId: string, kind: "projectionList" | "entityList", column: ReturnType<typeof normalizeListColumn>): void;
+export declare function rejectNonArrayInFilter(featureName: string, screenId: string, kind: "projectionList" | "entityList", filter: {
+    readonly op: string;
+    readonly value?: unknown;
+}): void;
+export declare function rejectEmptySections(featureName: string, screenId: string, kind: "projectionDetail" | "configEdit" | "entityEdit", sectionCount: number): void;
+export declare function assertExtensionSectionHasComponent(featureName: string, screenId: string, kind: "projectionDetail" | "configEdit" | "entityEdit", section: EditExtensionSection): void;
+export declare function rejectProjectionDetailOnlySection(featureName: string, screenId: string, kind: "configEdit" | "entityEdit", section: Exclude<EditSectionSpec, EditExtensionSection>): asserts section is EditFieldsSection;
+export declare function editSectionLabel(section: EditSectionSpec): string;
+export declare function validateRecordSectionActions(ctx: ScreenValidationContext, screenId: string, kind: "projectionDetail" | "entityEdit", section: EditSectionSpec): void;
+export declare function validateRecordHeaderAction(ctx: ScreenValidationContext, screenId: string, kind: "projectionDetail" | "entityEdit", screenEntity: string | undefined, action: RowAction): void;
+type NavigateLink = {
+    readonly screen?: string;
+    readonly entity?: string;
+    readonly entityId?: string;
+    readonly tab?: string;
+};
+export declare function navigateActionFromLink(id: string, navigate: NavigateLink): Parameters<typeof resolveRowActionNavigateTarget>[4];
+export {};

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

@@ -0,0 +1,142 @@
+// Checks shared by several screen kinds; each helper takes the kind it reports under.
+// Dependencies point one way: screens-kind-*.ts -> here ->
+// screens-dashboard/forms/lists -> screens-actions.
+import { qualifyEntityName } from "../qualified-name.js";
+import { isWriteFormEditSection } from "../screen-helpers.js";
+import { isRowClickAction, validateActionHasIcon, validateNavigateActionTab, validateRecordActionRedirect, } from "./screens-actions.js";
+import { assertRefTargetRegistered, rejectInertColumnSortable, validateColumnRendererForm, validateRowActionTarget, } from "./screens-lists.js";
+export function findEntityFeature(entityName, featureMap) {
+    for (const [name, feature] of featureMap) {
+        if (feature.entities?.[entityName])
+            return name;
+    }
+    return undefined;
+}
+export function buildUnknownFieldMessage(featureName, screenId, fieldName, entityName, knownFields) {
+    const known = [...knownFields].sort().join(", ");
+    return (`[Feature ${featureName}] Screen "${screenId}" references field "${fieldName}" ` +
+        `which does not exist on entity "${entityName}" (known: ${known}).`);
+}
+export function listActionContext(ctx, screenId, screenType, screenEntity, where) {
+    return {
+        featureName: ctx.feature.name,
+        screenId,
+        screenType,
+        screenEntity,
+        where,
+        screens: ctx.feature.screens,
+        allWriteHandlerQns: ctx.allWriteHandlerQns,
+        allScreenQns: ctx.allScreenQns,
+        navTargetShortIds: ctx.navTargetShortIds,
+        screensByShortId: ctx.screensByShortId,
+        detailForScreens: ctx.detailForScreens,
+    };
+}
+// entityList / entityEdit: entity-refs are feature-local.
+export function resolveScreenEntity(ctx, screenId, entityName) {
+    const entityDef = ctx.feature.entities?.[entityName];
+    if (entityDef)
+        return entityDef;
+    const known = Object.keys(ctx.feature.entities ?? {})
+        .sort()
+        .join(", ") || "(none)";
+    const crossFeature = findEntityFeature(entityName, ctx.featureMap);
+    const hint = crossFeature
+        ? ` Entity "${entityName}" is owned by feature "${crossFeature}" — cross-feature screen ownership is not supported.`
+        : "";
+    throw new Error(`[Feature ${ctx.feature.name}] Screen "${screenId}" references entity "${entityName}" ` +
+        `which is not declared in this feature (known: ${known}).${hint}`);
+}
+export function rejectMissingQuery(featureName, screenId, kind, query) {
+    if (!query || typeof query !== "string") {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${kind}) has empty or non-string query. Set query to a registered query name.`);
+    }
+}
+// An empty column list would render a blank table: almost always an
+// in-progress screen the author forgot to fill in.
+export function rejectEmptyColumns(featureName, screenId, kind, columnCount) {
+    if (columnCount === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${kind}) has an empty columns list — ` +
+            `declare at least one column.`);
+    }
+}
+export function validateListColumnRendering(ctx, screenId, kind, column) {
+    const featureName = ctx.feature.name;
+    validateColumnRendererForm(featureName, screenId, column);
+    rejectInertColumnSortable(featureName, screenId, kind, column);
+    if (column.refEntity !== undefined) {
+        assertRefTargetRegistered(`[Feature ${featureName}] Screen "${screenId}" (${kind})`, `column "${column.field}" (refEntity)`, column.refEntity, featureName, ctx.featureMap);
+    }
+}
+export function rejectNonArrayInFilter(featureName, screenId, kind, filter) {
+    if (filter.op === "in" && !Array.isArray(filter.value)) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${kind}) filter.op "in" requires ` +
+            `filter.value to be a readonly array. Pass an array as filter.value.`);
+    }
+}
+// A layout with zero sections renders as nothing: reject at boot so the
+// author sees it before the blank form surprises them.
+export function rejectEmptySections(featureName, screenId, kind, sectionCount) {
+    if (sectionCount === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${kind}) has an empty sections list — ` +
+            `declare at least one section.`);
+    }
+}
+export function assertExtensionSectionHasComponent(featureName, screenId, kind, section) {
+    if (section.component?.react === undefined && section.component?.native === undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${kind}) extension section ` +
+            `"${section.title}" has no component — declare a react/native component marker.`);
+    }
+}
+// relatedList and writeForm sections exist on projectionDetail only; what
+// remains afterwards is a plain fields/groups section.
+export function rejectProjectionDetailOnlySection(featureName, screenId, kind, section) {
+    if (section.kind === "relatedList") {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${kind}) relatedList section ` +
+            `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
+            `primitive (fw#2166). Move the section to a projectionDetail screen or remove it.`);
+    }
+    if (isWriteFormEditSection(section)) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${kind}) writeForm section ` +
+            `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive. Move the section to a projectionDetail screen or remove it.`);
+    }
+}
+export function editSectionLabel(section) {
+    return section.title ?? section.id ?? "(untitled)";
+}
+export function validateRecordSectionActions(ctx, screenId, kind, section) {
+    const actionContext = `section "${editSectionLabel(section)}" action`;
+    for (const action of section.actions ?? []) {
+        validateActionHasIcon(ctx.feature.name, screenId, kind, actionContext, action);
+        validateRecordActionRedirect(ctx.feature, screenId, kind, action, ctx);
+        validateNavigateActionTab(ctx.feature.name, screenId, kind, actionContext, action, ctx);
+    }
+}
+const NO_ROW_SUBJECT = {
+    projectionDetail: "a detail screen",
+    entityEdit: "an edit screen",
+};
+// Header actions reuse RowAction (the displayed record stands in for the row),
+// so the same navigate/writeHandler existence checks as list rowActions apply.
+// `rowClick` is rejected outright: there is no row to click.
+export function validateRecordHeaderAction(ctx, screenId, kind, screenEntity, action) {
+    const featureName = ctx.feature.name;
+    validateRecordActionRedirect(ctx.feature, screenId, kind, action, ctx);
+    if (isRowClickAction(action)) {
+        throw new Error(`[Feature ${featureName}] Screen "${qualifyEntityName(featureName, "screen", screenId)}" ` +
+            `(${kind}) action "${action.id}" sets rowClick: true — there is no row to ` +
+            `click on ${NO_ROW_SUBJECT[kind]}. Remove rowClick.`);
+    }
+    validateRowActionTarget(listActionContext(ctx, screenId, kind, screenEntity, `Screen "${screenId}" (${kind})`), "action", "rowAction", action);
+}
+export function navigateActionFromLink(id, navigate) {
+    return {
+        kind: "navigate",
+        id,
+        label: id,
+        ...(navigate.screen !== undefined ? { screen: navigate.screen } : {}),
+        ...(navigate.entity !== undefined ? { entity: navigate.entity } : {}),
+        ...(navigate.entityId !== undefined ? { entityId: navigate.entityId } : {}),
+        ...(navigate.tab !== undefined ? { tab: navigate.tab } : {}),
+    };
+}

package/dist/engine/boot-validator/screens-lists.d.ts

@@ -24,7 +24,7 @@ type RelatedListSectionValidation = {
     }>;
 };
 export declare function validateRelatedListSection(args: RelatedListSectionValidation): void;
-type ListActionTargetContext = NavigateTargetLookups & {
+export type ListActionTargetContext = NavigateTargetLookups & {
     readonly featureName: string;
     readonly screenId: string;
     readonly screenType: NavigateSourceScreenType;
@@ -34,6 +34,7 @@ type ListActionTargetContext = NavigateTargetLookups & {
     readonly allWriteHandlerQns: ReadonlySet<string>;
 };
 export declare function validateListActionTargets(ctx: ListActionTargetContext, actionLabel: "rowAction" | "emptyState action", action: RowAction): void;
+export declare function validateRowActionTarget(ctx: ListActionTargetContext, actionLabel: "rowAction" | "emptyState action" | "action", paramsLabel: "rowAction" | "emptyState action", action: RowAction): void;
 export declare function rejectInertColumnSortable(featureName: string, screenId: string, screenType: "entityList" | "projectionList", column: {
     readonly field: string;
     readonly sortable?: boolean;

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

@@ -2,7 +2,7 @@ import { REFERENCE_LOOKUP_SOURCES } from "../../ui-types/list-row-meta.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { qualifyEntityName } from "../qualified-name.js";
 import { explicitListScreenId, normalizeListColumn, resolveNavParentScreen, } from "../screen-helpers.js";
-import { isRowClickAction, rejectRedirectOnListRowAction, resolveRowActionNavigateTarget, validateClientActionName, validateDrawerTargetAction, validateRowActionNavigateParams, } from "./screens-actions.js";
+import { assertWriteHandlerRegistered, isRowClickAction, rejectRedirectOnListRowAction, resolveRowActionNavigateTarget, validateClientActionName, validateDrawerTargetAction, validateRowActionNavigateParams, } from "./screens-actions.js";
 // validateScreenHasNavArea runs once per screen; the index is built once per
 // featureMap (immutable during boot) instead of re-scanning every feature each call.
 const navAreaIndexByFeatureMap = new WeakMap();
@@ -115,13 +115,19 @@ function rejectEmptyStateActionParams(ctx, actionLabel, action) {
 // Target checks shared by list/related-list rowActions and emptyState.action:
 // navigate target + params, drawer target, write-handler registration.
 export function validateListActionTargets(ctx, actionLabel, action) {
-    const { featureName, screenId, screenType } = ctx;
-    rejectRedirectOnListRowAction(featureName, screenId, screenType, action);
+    rejectRedirectOnListRowAction(ctx.featureName, ctx.screenId, ctx.screenType, action);
     if (actionLabel === "emptyState action")
         rejectEmptyStateActionParams(ctx, actionLabel, action);
+    validateRowActionTarget(ctx, actionLabel, actionLabel, action);
+}
+// Header actions have always reported navigate-params errors under the
+// "rowAction" label, which validateRowActionNavigateParams only knows in list
+// labels — hence paramsLabel apart from actionLabel.
+export function validateRowActionTarget(ctx, actionLabel, paramsLabel, action) {
+    const { featureName, screenId, screenType } = ctx;
     if (action.kind === "navigate") {
         const target = resolveRowActionNavigateTarget(featureName, screenId, screenType, actionLabel, action, ctx.allScreenQns, ctx.navTargetShortIds, ctx.screensByShortId, ctx.detailForScreens);
-        validateRowActionNavigateParams(featureName, screenId, screenType, ctx.screenEntity, action, target, actionLabel);
+        validateRowActionNavigateParams(featureName, screenId, screenType, ctx.screenEntity, action, target, paramsLabel);
     }
     else if (action.kind === "drawer") {
         validateDrawerTargetAction(featureName, screenId, screenType, actionLabel, action, ctx.screens);
@@ -129,11 +135,8 @@ export function validateListActionTargets(ctx, actionLabel, action) {
     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}" ` +
-            `is not a registered write-handler. Check the QN spelling (expected ` +
-            `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
+    else {
+        assertWriteHandlerRegistered(featureName, `${ctx.where} ${actionLabel} "${action.id}"`, action.handler, ctx.allWriteHandlerQns);
     }
 }
 function validateRelatedListRowActions(args, rowActions) {
@@ -258,24 +261,23 @@ export function assertRefTargetRegistered(prefix, subject, refTarget, currentFea
                 .join(", ") || "(none)"}.`);
     }
 }
-// Facets (fw#2224) — unlike filter, a field inventory IS available here: the
+// Facets — unlike filter, a field inventory IS available here: the
 // declared columns. A facet on a field with no column is almost always a
 // typo (the user never sees the field anywhere), so this is hard-checked
-// rather than just documented. Shared by projectionList and relatedList
-// (fw#2740) — `prefix` carries the caller's own screen/section message lead-in.
+// rather than just documented. Shared by projectionList and relatedList —
+// `prefix` carries the caller's own screen/section message lead-in.
 //
-// `type: "reference"` is exempt from the same-name-column rule (fw akte-
-// bedienkonzept-2): it filters by an id field (e.g. "propertyId") but
-// displays a different, human-readable column (e.g. "propertyLabel") — a
-// column named after the filter field would almost never exist, and
-// requiring one anyway would force apps to add a column no design calls
-// for just to satisfy this check. Its own `entity` is mandatory on the type
-// (TS, not just this validator) and is resolved below — that explicit,
-// checked declaration is this facet type's field inventory, filling the
-// same "not just a typo" role the column-name check plays for select/
-// boolean facets. select/boolean facets keep the column requirement
-// unchanged: both filter and display the same field, so a facet with no
-// matching column is still almost always a typo.
+// `type: "reference"` is exempt from the same-name-column rule: it filters
+// by an id field (e.g. "propertyId") but displays a different,
+// human-readable column (e.g. "propertyLabel") — a column named after the
+// filter field would almost never exist, and requiring one anyway would
+// force apps to add a column no design calls for just to satisfy this check.
+// Its own `entity` is mandatory on the type (TS, not just this validator) and
+// is resolved below — that explicit, checked declaration is this facet type's
+// field inventory, filling the same "not just a typo" role the column-name
+// check plays for select/boolean facets. select/boolean facets keep the
+// column requirement unchanged: both filter and display the same field, so a
+// facet with no matching column is still almost always a typo.
 export function validateListFacets(prefix, facets, columns, currentFeatureName, featureMap) {
     const columnFieldNames = new Set(columns.map((col) => normalizeListColumn(col).field));
     const seenFacetFields = new Set();

package/dist/engine/boot-validator/screens.d.ts

@@ -10,8 +10,6 @@ export declare function validateScreens(feature: FeatureDefinition, featureMap:
     readonly featureName: string;
     readonly screen: ScreenDefinition;
 }>): void;
-export declare function findEntityFeature(entityName: string, featureMap: ReadonlyMap<string, FeatureDefinition>): string | undefined;
-export declare function buildUnknownFieldMessage(featureName: string, screenId: string, fieldName: string, entityName: string, knownFields: ReadonlySet<string>): string;
 export declare function collectScreenQns(features: readonly FeatureDefinition[]): Set<string>;
 export declare function screenShortIdsFrom(allScreenQns: ReadonlySet<string>): Set<string>;
 export declare function collectScreensByShortId(features: readonly FeatureDefinition[]): Map<string, ReadonlyArray<{