@cosmicdrift/kumiko-framework 0.384.0 → 0.386.0

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

@@ -0,0 +1,319 @@
+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";
+// 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();
+function navTargetScreenQns(nav) {
+    return [nav.screen, nav.createAction?.screen, ...(nav.actions ?? []).map((a) => a.screen)].filter((qn) => qn !== undefined);
+}
+function getNavAreaIndex(featureMap) {
+    const cached = navAreaIndexByFeatureMap.get(featureMap);
+    if (cached !== undefined)
+        return cached;
+    const navTargetQns = new Set();
+    const allScreens = [];
+    let anyNavRegistered = false;
+    for (const f of featureMap.values()) {
+        allScreens.push(...Object.values(f.screens));
+        for (const nav of Object.values(f.navs)) {
+            anyNavRegistered = true;
+            for (const qn of navTargetScreenQns(nav))
+                navTargetQns.add(qn);
+        }
+    }
+    const index = { anyNavRegistered, navTargetQns, allScreens };
+    navAreaIndexByFeatureMap.set(featureMap, index);
+    return index;
+}
+// resolveNavParentScreen falls back to a heuristic when the explicit
+// listScreenId matches no screen, so a typo would silently get the guess.
+export function validateExplicitListScreenExists(featureName, screenId, screen, screensByShortId) {
+    const listScreenId = explicitListScreenId(screen);
+    // skip: no explicit listScreenId, the nav heuristic applies and there is nothing to validate
+    if (listScreenId === undefined)
+        return;
+    const shortId = listScreenId.slice(listScreenId.lastIndexOf(":") + 1);
+    // skip: the explicit listScreenId resolves to a mounted screen
+    if (screensByShortId.has(shortId))
+        return;
+    throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screen.type}) listScreenId "${listScreenId}" ` +
+        `matches no mounted screen — fix the id or mount the list screen.`);
+}
+// Every screen must resolve nav via `nav`, `r.nav()`, a parent list, or
+// `dormant: true`. Skipped when the composed set has no nav entries at all.
+export function validateScreenHasNavArea(feature, screenId, screen, featureMap) {
+    // skip: the screen already declares its own nav entry.
+    if (screen.nav !== undefined)
+        return;
+    // skip: explicitly opted out via `dormant: true`.
+    if (screen.dormant === true)
+        return;
+    const { anyNavRegistered, navTargetQns, allScreens } = getNavAreaIndex(featureMap);
+    // skip: no nav entries exist anywhere in the composed set — a feature/
+    // recipe/test fixture booted without an app shell, not an omission.
+    if (!anyNavRegistered)
+        return;
+    const targetQn = qualifyEntityName(feature.name, "screen", screenId);
+    // skip: a standalone r.nav() elsewhere already points at this screen.
+    if (navTargetQns.has(targetQn))
+        return;
+    // skip: resolves to a parent list via listScreenId/rowAction-target/same-entity.
+    if (resolveNavParentScreen(allScreens, screen, (s) => s.id) !== undefined)
+        return;
+    throw new Error(`[Feature ${feature.name}] Screen "${targetQn}" has no nav entry and no resolvable list — ` +
+        `declare listScreenId (or a rowAction/toolbarAction navigate target from a list screen), add ` +
+        `a standalone r.nav() pointing at it, or set dormant: true if it's intentionally reachable ` +
+        `only via a direct link/redirect or a consuming app's own r.nav().`);
+}
+// Shared by projectionDetail relatedList sections and entityList.expandableRow:
+// both render a relatedList whose rows come from an arbitrary query.
+export function validateRelatedListSection(args) {
+    const { featureName, featureMap, where, section } = args;
+    if (!section.query || typeof section.query !== "string") {
+        throw new Error(`[Feature ${featureName}] ${where} has empty or non-string query. Set query to a registered query name.`);
+    }
+    if (section.entity !== undefined) {
+        assertRefTargetRegistered(`[Feature ${featureName}] ${where}`, "entity", section.entity, featureName, featureMap);
+    }
+    for (const col of section.columns) {
+        const normalizedCol = normalizeListColumn(col);
+        if (normalizedCol.refEntity !== undefined) {
+            assertRefTargetRegistered(`[Feature ${featureName}] ${where}`, `column "${normalizedCol.field}" (refEntity)`, normalizedCol.refEntity, featureName, featureMap);
+        }
+    }
+    if (section.rowClick !== undefined) {
+        const targetEntity = section.rowClick.entity;
+        const hasDetailScreen = [...featureMap.values()].some((f) => Object.values(f.screens).some((s) => s.detailFor === targetEntity));
+        if (!hasDetailScreen) {
+            throw new Error(`[Feature ${featureName}] ${where} ` +
+                `rowClick targets entity "${targetEntity}", but no screen declares ` +
+                `detailFor: "${targetEntity}". Add detailFor: "${targetEntity}" to the screen that shows it.`);
+        }
+    }
+    if (section.rowActions !== undefined)
+        validateRelatedListRowActions(args, section.rowActions);
+    if (section.defaultSort !== undefined)
+        validateRelatedListDefaultSort(args, section.defaultSort);
+    if (section.facets !== undefined) {
+        validateListFacets(`[Feature ${featureName}] ${where}`, section.facets, section.columns, featureName, featureMap);
+    }
+    if (section.toolbarActions !== undefined) {
+        validateRelatedListToolbarActions(args, section.toolbarActions);
+    }
+}
+// An empty list has no row, so params resolve against an empty record.
+function rejectEmptyStateActionParams(ctx, actionLabel, action) {
+    const params = action.kind === "navigate" || action.kind === "drawer" ? action.params : undefined;
+    if (params !== undefined) {
+        throw new Error(`[Feature ${ctx.featureName}] ${ctx.where} ${actionLabel} "${action.id}" sets params — an empty list ` +
+            `has no row to read them from, so they would resolve against an empty record. Remove the params.`);
+    }
+}
+// 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);
+    if (actionLabel === "emptyState action")
+        rejectEmptyStateActionParams(ctx, actionLabel, action);
+    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);
+    }
+    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}" ` +
+            `is not a registered write-handler. Check the QN spelling (expected ` +
+            `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
+    }
+}
+function validateRelatedListRowActions(args, rowActions) {
+    const { featureName, screenId, screenType, where, section, screens, allWriteHandlerQns, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens, } = args;
+    for (const action of rowActions) {
+        validateListActionTargets({
+            featureName,
+            screenId,
+            screenType,
+            screenEntity: undefined,
+            where,
+            screens,
+            allWriteHandlerQns,
+            allScreenQns,
+            navTargetShortIds,
+            screensByShortId,
+            detailForScreens,
+        }, "rowAction", action);
+    }
+    // section.rowClick (legacy, navigate-only) and a rowActions entry
+    // 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(isRowClickAction).length;
+    const legacyRowClickCount = section.rowClick !== undefined ? 1 : 0;
+    if (rowClickActionCount + legacyRowClickCount > 1) {
+        throw new Error(`[Feature ${featureName}] ${where} ` +
+            `has both a rowClick and ${rowClickActionCount} rowActions marked ` +
+            `rowClick:true — at most one may fire on a row-body click.`);
+    }
+}
+function validateRelatedListDefaultSort(args, defaultSort) {
+    const { featureName, where, section } = args;
+    const sortField = defaultSort.field;
+    const col = section.columns.find((c) => normalizeListColumn(c).field === sortField);
+    if (col === undefined) {
+        throw new Error(`[Feature ${featureName}] ${where} ` +
+            `defaultSort.field "${sortField}" is not a listed column. Use a listed column as defaultSort.field.`);
+    }
+    if (normalizeListColumn(col).sortable !== true) {
+        throw new Error(`[Feature ${featureName}] ${where} ` +
+            `defaultSort.field "${sortField}" is not sortable. Set sortable: true on ` +
+            `the column or pick another field.`);
+    }
+}
+// Only drawer-kind and navigate actions that set tab are validated here;
+// plain navigate (no tab) and writeHandler toolbarActions have no boot check yet.
+function validateRelatedListToolbarActions(args, toolbarActions) {
+    const { featureName, screenId, screenType, screens, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens, } = args;
+    for (const action of toolbarActions) {
+        if (action.kind === "drawer") {
+            validateDrawerTargetAction(featureName, screenId, screenType, "toolbarAction", action, screens);
+        }
+        if (action.kind === "navigate" && action.tab !== undefined) {
+            resolveRowActionNavigateTarget(featureName, screenId, screenType, "toolbarAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
+        }
+    }
+}
+// Column-level sortable: true only enables relatedList headers. On entityList
+// the entity field's flag wins; on projectionList sortable comes from the
+// query schema and a column can only opt OUT with sortable: false.
+export function rejectInertColumnSortable(featureName, screenId, screenType, column) {
+    const isInert = screenType === "entityList" ? column.sortable !== undefined : column.sortable === true;
+    // skip: the sortable flag is meaningful for this screen type
+    if (!isInert)
+        return;
+    const source = screenType === "entityList"
+        ? "set sortable: true on the entity field instead"
+        : "sorting is derived from the query's Zod schema; only sortable: false is honored";
+    throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) column "${column.field}" sets sortable — ` +
+        `it is ignored here; ${source}. Remove sortable from this column.`);
+}
+// Form check for ListColumn renderers in the PlatformComponent form
+// (`{ react: { __component: "Name" } }`). The server does not know the
+// client-side columnRenderers map, so it only checks that the structure is
+// right: if `react` is set as an object, `__component` MUST be a non-empty
+// string. A key omitted on the client only triggers a warning, not a boot
+// failure.
+export function validateColumnRendererForm(featureName, screenId, column) {
+    const renderer = column.renderer;
+    // skip: only the PlatformComponent form ({ react: { __component: "..." } })
+    // is validated structurally. Function, string-QN and null/undefined
+    // renderers are all valid other forms — not a form error.
+    if (renderer === null || typeof renderer !== "object")
+        return;
+    // @cast-boundary schema-walk — feature-config renderer-shape introspection
+    const react = renderer.react;
+    // skip: no react branch → either native-only or not a PlatformComponent —
+    // both outside this check.
+    if (react === undefined || react === null)
+        return;
+    if (typeof react !== "object") {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" column "${column.field}" has a renderer with ` +
+            `a non-object \`react\` branch — expected \`{ react: { __component: "Name" } }\`.`);
+    }
+    // @cast-boundary schema-walk — feature-config react-branch introspection
+    const component = react.__component;
+    // skip: without a __component key this is not the string-key form
+    // (e.g. a future direct component ref); not our domain.
+    if (component === undefined)
+        return;
+    if (typeof component !== "string" || component.length === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" column "${column.field}" has a renderer with ` +
+            `\`react.__component\` = ${JSON.stringify(component)} — expected a non-empty string identifying ` +
+            `a client-side columnRenderers entry.`);
+    }
+}
+// Shared entity-target resolution for reference facets, refEntity columns
+// (projectionList/relatedList) and refEntity fields (projectionDetail).
+export function assertRefTargetRegistered(prefix, subject, refTarget, currentFeatureName, featureMap) {
+    const target = parseRefTarget(refTarget, currentFeatureName);
+    const targetFeature = featureMap.get(target.featureName);
+    if (targetFeature === undefined) {
+        throw new Error(`${prefix} ${subject} targets entity "${refTarget}", but feature "${target.featureName}" is not ` +
+            `mounted — mount it and declare r.requires({ features: ["${target.featureName}"] }).`);
+    }
+    if (targetFeature.entities?.[target.entityName] === undefined) {
+        throw new Error(`${prefix} ${subject} targets entity "${refTarget}", which does not resolve to a ` +
+            `registered entity. Known entities in feature "${target.featureName}": ` +
+            `${Object.keys(targetFeature.entities ?? {})
+                .sort()
+                .join(", ") || "(none)"}.`);
+    }
+}
+// Facets (fw#2224) — 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.
+//
+// `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.
+export function validateListFacets(prefix, facets, columns, currentFeatureName, featureMap) {
+    const columnFieldNames = new Set(columns.map((col) => normalizeListColumn(col).field));
+    const seenFacetFields = new Set();
+    for (const facet of facets) {
+        if (seenFacetFields.has(facet.field)) {
+            throw new Error(`${prefix} declares facet "${facet.field}" more than once. Declare each facet field once.`);
+        }
+        seenFacetFields.add(facet.field);
+        if (facet.type !== "reference" && !columnFieldNames.has(facet.field)) {
+            throw new Error(`${prefix} facet references field "${facet.field}" which is not a declared column. ` +
+                `Known columns: ${[...columnFieldNames].sort().join(", ")}`);
+        }
+        if (facet.type === "select" && facet.options.length === 0) {
+            throw new Error(`${prefix} facet "${facet.field}" (type "select") has an empty options list — ` +
+                `declare at least one option.`);
+        }
+        if (facet.type === "reference") {
+            assertRefTargetRegistered(prefix, `facet "${facet.field}" (type "reference")`, facet.entity, currentFeatureName, featureMap);
+            assertReferenceListHandlerRegistered(prefix, `facet "${facet.field}" (type "reference")`, facet.entity, currentFeatureName, featureMap);
+        }
+    }
+}
+// The facet's options are loaded at render time by dispatching the target's
+// list query (renderer useReferenceLookup, incl. its REFERENCE_LOOKUP_SOURCES
+// override); a missing or unregistered handler is swallowed there and leaves
+// a permanently empty dropdown, so it has to fail at boot instead.
+function assertReferenceListHandlerRegistered(prefix, subject, refTarget, currentFeatureName, featureMap) {
+    const target = parseRefTarget(refTarget, currentFeatureName);
+    const override = REFERENCE_LOOKUP_SOURCES[`${target.featureName}:${target.entityName}`];
+    const expectedQn = override?.queryQn ??
+        qualifyEntityName(target.featureName, "query", `${target.entityName}:list`);
+    for (const feature of featureMap.values()) {
+        for (const handlerName of Object.keys(feature.queryHandlers ?? {})) {
+            // skip: expected list handler found
+            if (qualifyEntityName(feature.name, "query", handlerName) === expectedQn)
+                return;
+        }
+    }
+    throw new Error(`${prefix} ${subject} loads its options from query "${expectedQn}", which is not a registered ` +
+        `query handler — register the entity's list handler (defineEntityListHandler) or the facet renders an empty dropdown.`);
+}

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

@@ -1,19 +1,8 @@
-import type { IconKey } from "@cosmicdrift/kumiko-types/nav-icon";
 import type { ConfigKeyDefinition, FeatureDefinition } from "../types/index.ts";
-import type { ActionFormScreenDefinition, DashboardCustomPanel, DashboardScreenPanel, RelatedListToolbarAction, RowAction, RowFieldExtractor, ScreenDefinition, SecretMintScreenDefinition, ToolbarAction } from "../types/screen.ts";
-export declare function rowFieldExtractorKeys(params: RowFieldExtractor): readonly string[];
-export declare function readsNavigateParamsAsFormPrefill(target: ScreenDefinition, explicitEntityId: string | undefined, sourceScreenEntity: string | undefined): boolean;
-export declare function validateActionHasIcon(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit" | "entityList" | "projectionList" | "dashboard", context: string, action: {
-    readonly id: string;
-    readonly icon?: IconKey;
-}): void;
-export declare function validateActionFieldRefs(featureName: string, screenId: string, actionKind: "rowAction" | "toolbarAction", actionId: string, action: RowAction | ToolbarAction | RelatedListToolbarAction, fieldNames: ReadonlySet<string>, rowMeta: ReadonlySet<string>): void;
-export declare function validateScreenShortIdCollisions(screensByShortId: ReadonlyMap<string, ReadonlyArray<{
-    readonly featureName: string;
-    readonly screen: ScreenDefinition;
-}>>): void;
-export declare function resolveScreenTargetQn(featureName: string, target: string): string;
-export declare function validateDrawerPrefillKeys(where: string, targetLabel: "drawer-target" | "navigate-target", targetScreenId: string, target: ActionFormScreenDefinition | SecretMintScreenDefinition, params: RowFieldExtractor): void;
+import type { ScreenDefinition } from "../types/screen.ts";
+export { readsNavigateParamsAsFormPrefill, resolveScreenTargetQn, rowFieldExtractorKeys, validateActionFieldRefs, validateActionHasIcon, validateDrawerPrefillKeys, validateScreenShortIdCollisions, } from "./screens-actions.ts";
+export { validateDashboardCustomPanel, validateDashboardScreenPanel } from "./screens-dashboard.ts";
+export { validateColumnRendererForm } from "./screens-lists.ts";
 export declare function validateScreens(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, allWriteHandlerQns: ReadonlySet<string>, allScreenQns: ReadonlySet<string>, configKeyDefsByQn: ReadonlyMap<string, ConfigKeyDefinition>, screensByShortId: ReadonlyMap<string, ReadonlyArray<{
     readonly featureName: string;
     readonly screen: ScreenDefinition;
@@ -21,12 +10,6 @@ export declare function validateScreens(feature: FeatureDefinition, featureMap:
     readonly featureName: string;
     readonly screen: ScreenDefinition;
 }>): void;
-export declare function validateDashboardScreenPanel(featureName: string, screenId: string, panel: DashboardScreenPanel, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
-export declare function validateDashboardCustomPanel(featureName: string, screenId: string, panel: DashboardCustomPanel): void;
-export declare function validateColumnRendererForm(featureName: string, screenId: string, column: {
-    readonly field: string;
-    readonly renderer?: unknown;
-}): 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>;