@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

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) {

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<{