@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

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

@@ -0,0 +1,56 @@
+import { normalizeListColumn } from "../screen-helpers.js";
+import { validateListBulkActions } from "./list-bulk-actions.js";
+import { validateListTableOptions } from "./list-table-options.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));
+    }
+    validateListTableOptions(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen.table, screen.columns, true);
+    // 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);
+    }
+    validateListBulkActions(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen.bulkActions, 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,10 @@ 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 { validateListBulkActions } from "./list-bulk-actions.js";
+import { validateListTableOptions } from "./list-table-options.js";
+import { validateRelatedListGroupingRules } from "./related-list-table-rules.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();
@@ -70,6 +73,14 @@ export function validateScreenHasNavArea(feature, screenId, screen, featureMap)
 }
 // Shared by projectionDetail relatedList sections and entityList.expandableRow:
 // both render a relatedList whose rows come from an arbitrary query.
+function validateRelatedListTableAndBulk(args) {
+    const { featureName, where, section } = args;
+    validateRelatedListGroupingRules(`[Feature ${featureName}] ${where}`, section, args.screenType === "entityList expandableRow");
+    validateListTableOptions(`[Feature ${featureName}] ${where}`, section.table, section.columns);
+    if (section.rowActions !== undefined)
+        validateRelatedListRowActions(args, section.rowActions);
+    validateListBulkActions(`[Feature ${featureName}] ${where}`, section.bulkActions, section.rowActions);
+}
 export function validateRelatedListSection(args) {
     const { featureName, featureMap, where, section } = args;
     if (!section.query || typeof section.query !== "string") {
@@ -93,8 +104,7 @@ export function validateRelatedListSection(args) {
                 `detailFor: "${targetEntity}". Add detailFor: "${targetEntity}" to the screen that shows it.`);
         }
     }
-    if (section.rowActions !== undefined)
-        validateRelatedListRowActions(args, section.rowActions);
+    validateRelatedListTableAndBulk(args);
     if (section.defaultSort !== undefined)
         validateRelatedListDefaultSort(args, section.defaultSort);
     if (section.facets !== undefined) {
@@ -115,13 +125,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 +145,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<{