@cosmicdrift/kumiko-framework 0.388.0 → 0.389.0

package/dist/engine/boot-validator/entity-list-aggregate-options.js

@@ -0,0 +1,23 @@
+import { isListFilterAllowed } from "../../db/entity-field-encryption.js";
+import { isFieldFilterable } from "../screen-filter-ops.js";
+import { entityAggregateFieldLookup, validateListTableAggregateFieldTypes, } from "./list-table-aggregate-options.js";
+const RANGE_FACET_TYPES = ["number", "decimal", "money", "bigInt"];
+function validateRangeFacets(where, facets, entity) {
+    for (const [field, config] of Object.entries(facets ?? {})) {
+        if (config === false || config.display !== "range")
+            continue;
+        const def = Object.hasOwn(entity.fields, field) ? entity.fields[field] : undefined;
+        if (def === undefined || !RANGE_FACET_TYPES.includes(def.type)) {
+            throw new Error(`${where} facets.${field}: display "range" needs a number, decimal, money or bigInt field.`);
+        }
+        if (!isFieldFilterable(def) || !isListFilterAllowed(entity, field, { op: "gte", value: 0 })) {
+            throw new Error(`${where} facets.${field}: display "range" needs filterable: true on a field that is not encrypted, personal or secret.`);
+        }
+    }
+}
+export function validateEntityListAggregateOptions(where, screen, entity) {
+    if (screen.table !== undefined) {
+        validateListTableAggregateFieldTypes(where, screen.table, entityAggregateFieldLookup(entity), true);
+    }
+    validateRangeFacets(where, screen.facets, entity);
+}

package/dist/engine/boot-validator/list-bulk-actions.d.ts

@@ -0,0 +1,3 @@
+import { type RowAction } from "../types/screen.ts";
+/** `where` is the full message prefix, e.g. `[Feature x] Screen "y" (entityList)`. */
+export declare function validateListBulkActions(where: string, bulkActions: unknown, rowActions: readonly RowAction[] | undefined): void;

package/dist/engine/boot-validator/list-bulk-actions.js

@@ -0,0 +1,49 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { isKebabSegment } from "../qualified-name.js";
+import { LIST_BULK_ACTION_KEYS } from "../types/screen.js";
+function validateBulkActionTarget(where, bulkId, target, rowActions) {
+    if (typeof target !== "string" || target === "") {
+        throw new Error(`${where} bulk action "${bulkId}" needs rowAction: the id of a row action.`);
+    }
+    const rowAction = rowActions.find((action) => action.id === target);
+    if (rowAction === undefined) {
+        const known = rowActions.map((action) => action.id).join(", ") || "(none)";
+        throw new Error(`${where} bulk action "${bulkId}" points at rowAction "${target}", which is not declared ` +
+            `in rowActions. Declared row actions: ${known}.`);
+    }
+    if (rowAction.kind !== undefined && rowAction.kind !== "writeHandler") {
+        throw new Error(`${where} bulk action "${bulkId}" points at rowAction "${target}" of kind "${rowAction.kind}". ` +
+            `Bulk actions run one server write per row, so only writeHandler row actions are allowed.`);
+    }
+}
+/** `where` is the full message prefix, e.g. `[Feature x] Screen "y" (entityList)`. */
+export function validateListBulkActions(where, bulkActions, rowActions) {
+    // skip: no bulk actions declared
+    if (bulkActions === undefined)
+        return;
+    if (!Array.isArray(bulkActions) || bulkActions.length === 0) {
+        throw new Error(`${where} bulkActions must be a non-empty array like [{ id: "archive", rowAction: "archive" }].`);
+    }
+    const seen = new Set();
+    for (const entry of bulkActions) {
+        if (!isPlainObject(entry)) {
+            throw new Error(`${where} bulkActions entries must be objects with id and rowAction.`);
+        }
+        const id = entry["id"];
+        if (typeof id !== "string" || !isKebabSegment(id)) {
+            throw new Error(`${where} bulk action id ${JSON.stringify(id)} must be a kebab-case string.`);
+        }
+        if (seen.has(id))
+            throw new Error(`${where} declares bulk action "${id}" twice.`);
+        seen.add(id);
+        const unknown = Object.keys(entry).filter((key) => !isOneOfBulkKeys(key));
+        if (unknown.length > 0) {
+            throw new Error(`${where} bulk action "${id}" has unknown key(s) ${unknown.map((k) => `"${k}"`).join(", ")}. ` +
+                `Allowed keys: ${LIST_BULK_ACTION_KEYS.join(", ")}.`);
+        }
+        validateBulkActionTarget(where, id, entry["rowAction"], rowActions ?? []);
+    }
+}
+function isOneOfBulkKeys(key) {
+    return LIST_BULK_ACTION_KEYS.some((allowed) => allowed === key);
+}

package/dist/engine/boot-validator/list-column-layout.d.ts

@@ -0,0 +1,8 @@
+import { type ListColumnSpec } from "../types/screen.ts";
+type ColumnLayoutFlags = {
+    readonly pinning: boolean;
+    readonly resizing: boolean;
+};
+/** Checks `pinned`, `width` and `minWidth` of every column against the table's opt-in flags. */
+export declare function validateColumnLayout(where: string, flags: ColumnLayoutFlags, columns: readonly ListColumnSpec[]): void;
+export {};

package/dist/engine/boot-validator/list-column-layout.js

@@ -0,0 +1,41 @@
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { normalizeListColumn } from "../screen-helpers.js";
+import { LIST_COLUMN_PINS } from "../types/screen.js";
+function isPositiveFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function validatePixelWidth(where, field, key, value) {
+    if (!isPositiveFiniteNumber(value)) {
+        throw new Error(`${where} column "${field}" has ${key} ${JSON.stringify(value)} — ` +
+            `must be a finite number of pixels greater than 0.`);
+    }
+}
+/** Checks `pinned`, `width` and `minWidth` of every column against the table's opt-in flags. */
+export function validateColumnLayout(where, flags, columns) {
+    for (const col of columns.map(normalizeListColumn)) {
+        if (col.pinned !== undefined) {
+            if (!isOneOf(LIST_COLUMN_PINS, col.pinned)) {
+                throw new Error(`${where} column "${col.field}" has pinned ${JSON.stringify(col.pinned)} — ` +
+                    `must be one of ${LIST_COLUMN_PINS.map((pin) => `"${pin}"`).join(", ")}.`);
+            }
+            if (!flags.pinning) {
+                throw new Error(`${where} column "${col.field}" is pinned but table.pinning is not enabled, ` +
+                    `so the pin would have no effect. Set table: { pinning: true } or remove "pinned".`);
+            }
+        }
+        for (const key of ["width", "minWidth"]) {
+            const value = col[key];
+            if (value === undefined)
+                continue;
+            validatePixelWidth(where, col.field, key, value);
+            if (!flags.resizing) {
+                throw new Error(`${where} column "${col.field}" sets ${key} but table.resizing is not enabled, ` +
+                    `so it would have no effect. Set table: { resizing: true } or remove "${key}".`);
+            }
+        }
+        if (col.width !== undefined && col.minWidth !== undefined && col.minWidth > col.width) {
+            throw new Error(`${where} column "${col.field}" has minWidth ${col.minWidth} greater than width ${col.width}. ` +
+                `Lower minWidth or raise width.`);
+        }
+    }
+}

package/dist/engine/boot-validator/list-table-aggregate-options.d.ts

@@ -0,0 +1,24 @@
+import type { EntityDefinition, FieldDefinition } from "../types/index.ts";
+import { type ListColumnSpec, type ListTableGrouping, type ListTableTotal } from "../types/screen.ts";
+type FieldType = FieldDefinition["type"];
+export type AggregateFieldInfo = {
+    readonly type: FieldType;
+    readonly multiple: boolean;
+    readonly secret: boolean;
+};
+export declare function groupingFieldsOf(grouping: {
+    readonly field?: unknown;
+    readonly fields?: unknown;
+}): string[];
+/** Structure and column membership; field types are checked where the entity is known. */
+export declare function validateListTableAggregateShape(where: string, table: Readonly<Record<string, unknown>>, columns: readonly ListColumnSpec[]): void;
+/**
+ * `lookup` answers undefined for a field it does not know. With `strict` (an entity
+ * stands behind the list) that is an error; otherwise the field is left to the server.
+ */
+export declare function validateListTableAggregateFieldTypes(where: string, table: {
+    readonly grouping?: ListTableGrouping;
+    readonly totals?: readonly ListTableTotal[];
+}, lookup: (field: string) => AggregateFieldInfo | undefined, strict: boolean): void;
+export declare function entityAggregateFieldLookup(entity: EntityDefinition): (field: string) => AggregateFieldInfo | undefined;
+export {};

package/dist/engine/boot-validator/list-table-aggregate-options.js

@@ -0,0 +1,145 @@
+import { LIST_AGGREGATE_MEASURE_KINDS } from "@cosmicdrift/kumiko-types/list-aggregate-types";
+import { isOneOf, isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { isListAggregateGroupable, isListAggregateMeasureSupported, } from "../../db/aggregate-sql.js";
+import { holdsCiphertextOrSecret } from "../../db/entity-field-encryption.js";
+import { normalizeListColumn } from "../screen-helpers.js";
+import { LIST_TABLE_GROUPING_KEYS, LIST_TABLE_TOTAL_KEYS, } from "../types/screen.js";
+import { rejectUnknownKeys } from "./list-table-reject-unknown-keys.js";
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isStringRecord(value) {
+    return isPlainObject(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+function isGroupKeyScalar(value) {
+    return value === null || ["string", "number", "boolean"].includes(typeof value);
+}
+function requireScreenColumn(where, path, field, columnFields) {
+    // skip: the field is a column, nothing to report
+    if (columnFields.has(field))
+        return;
+    throw new Error(`${where} ${path} "${field}" is not a column of this screen. ` +
+        `Columns: ${[...columnFields].join(", ")}.`);
+}
+const GROUPING_VALUE_CHECKS = [
+    { key: "field", isValid: (v) => typeof v === "string", expected: "must be a string" },
+    { key: "fields", isValid: isStringArray, expected: "must be an array of field names" },
+    { key: "userChoice", isValid: (v) => typeof v === "boolean", expected: "must be a boolean" },
+    { key: "label", isValid: (v) => typeof v === "string", expected: "must be an i18n key" },
+    { key: "labels", isValid: isStringRecord, expected: "must map group keys to i18n keys" },
+    {
+        key: "collapsedWhen",
+        isValid: isGroupKeyScalar,
+        expected: "must be a string, number, boolean or null",
+    },
+];
+function validateGroupingValueTypes(where, grouping) {
+    for (const check of GROUPING_VALUE_CHECKS) {
+        const value = grouping[check.key];
+        if (value !== undefined && !check.isValid(value)) {
+            throw new Error(`${where} table.grouping.${check.key} ${check.expected}.`);
+        }
+    }
+}
+function validateGroupingFieldChoice(where, grouping) {
+    const { field, fields, userChoice } = grouping;
+    const offered = isStringArray(fields) ? fields : [];
+    if (field === undefined && (userChoice !== true || offered.length === 0)) {
+        throw new Error(`${where} table.grouping has no field. Set field, or userChoice: true with at least one entry in fields.`);
+    }
+    if (fields !== undefined && userChoice !== true) {
+        throw new Error(`${where} table.grouping.fields needs userChoice: true, or the user could never pick them.`);
+    }
+}
+function validateGroupingShape(where, grouping, columnFields) {
+    if (!isPlainObject(grouping)) {
+        throw new Error(`${where} table.grouping must be an object like { field: "status" }.`);
+    }
+    rejectUnknownKeys(where, "table.grouping", grouping, LIST_TABLE_GROUPING_KEYS);
+    validateGroupingValueTypes(where, grouping);
+    validateGroupingFieldChoice(where, grouping);
+    for (const name of groupingFieldsOf(grouping)) {
+        requireScreenColumn(where, "table.grouping field", name, columnFields);
+    }
+}
+function validateTotalsShape(where, totals, columnFields) {
+    if (!Array.isArray(totals) || totals.length === 0) {
+        throw new Error(`${where} table.totals must be a non-empty array like [{ field: "amount", kind: "sum" }].`);
+    }
+    for (const [i, entry] of totals.entries()) {
+        if (!isPlainObject(entry))
+            throw new Error(`${where} table.totals[${i}] must be an object.`);
+        rejectUnknownKeys(where, `table.totals[${i}]`, entry, LIST_TABLE_TOTAL_KEYS);
+        if (typeof entry["field"] !== "string") {
+            throw new Error(`${where} table.totals[${i}].field must be a field name.`);
+        }
+        if (!isOneOf(LIST_AGGREGATE_MEASURE_KINDS, entry["kind"])) {
+            throw new Error(`${where} table.totals[${i}].kind must be one of ${LIST_AGGREGATE_MEASURE_KINDS.join(", ")}.`);
+        }
+        requireScreenColumn(where, `table.totals[${i}].field`, entry["field"], columnFields);
+    }
+}
+export function groupingFieldsOf(grouping) {
+    const named = typeof grouping.field === "string" ? [grouping.field] : [];
+    const offered = isStringArray(grouping.fields) ? grouping.fields : [];
+    return [...new Set([...named, ...offered])];
+}
+/** Structure and column membership; field types are checked where the entity is known. */
+export function validateListTableAggregateShape(where, table, columns) {
+    const columnFields = new Set(columns.map((col) => normalizeListColumn(col).field));
+    if (table["grouping"] !== undefined)
+        validateGroupingShape(where, table["grouping"], columnFields);
+    if (table["totals"] !== undefined)
+        validateTotalsShape(where, table["totals"], columnFields);
+}
+function rejectSecret(where, path, field, info) {
+    // skip: only secret fields are rejected here
+    if (!info.secret)
+        return;
+    throw new Error(`${where} ${path} "${field}" is encrypted, personal or secret and cannot be grouped or summed.`);
+}
+/**
+ * `lookup` answers undefined for a field it does not know. With `strict` (an entity
+ * stands behind the list) that is an error; otherwise the field is left to the server.
+ */
+export function validateListTableAggregateFieldTypes(where, table, lookup, strict) {
+    const resolve = (path, field) => {
+        const info = lookup(field);
+        if (info === undefined && strict) {
+            throw new Error(`${where} ${path} "${field}" is not a field of the entity behind this list.`);
+        }
+        return info;
+    };
+    for (const field of groupingFieldsOf(table.grouping ?? {})) {
+        const info = resolve("table.grouping field", field);
+        if (info === undefined)
+            continue;
+        rejectSecret(where, "table.grouping field", field, info);
+        if (!isListAggregateGroupable(info.type, info.multiple)) {
+            throw new Error(`${where} table.grouping field "${field}" (${info.type}) cannot be grouped by.`);
+        }
+    }
+    for (const [i, total] of (table.totals ?? []).entries()) {
+        const path = `table.totals[${i}]`;
+        const info = resolve(`${path}.field`, total.field);
+        if (info === undefined)
+            continue;
+        rejectSecret(where, `${path}.field`, total.field, info);
+        if (!isListAggregateMeasureSupported(total.kind, info.type)) {
+            throw new Error(`${where} ${path}: "${total.kind}" is not supported on ${info.type} field "${total.field}". ` +
+                `sum and avg need number, decimal, money or bigInt; min and max also take date and timestamp.`);
+        }
+    }
+}
+export function entityAggregateFieldLookup(entity) {
+    return (field) => {
+        const def = Object.hasOwn(entity.fields, field) ? entity.fields[field] : undefined;
+        if (def === undefined)
+            return undefined;
+        return {
+            type: def.type,
+            multiple: def.type === "reference" && def.multiple === true,
+            secret: holdsCiphertextOrSecret(entity, field),
+        };
+    };
+}

package/dist/engine/boot-validator/list-table-aggregate-query.d.ts

@@ -0,0 +1,10 @@
+import type { FeatureDefinition, QueryHandlerDef } from "../types/index.ts";
+import type { ListColumnSpec, ListTableOptions } from "../types/screen.ts";
+export declare function validateListTableAggregateQuery(args: {
+    readonly prefix: string;
+    readonly query: string;
+    readonly table?: ListTableOptions | undefined;
+    readonly columns: readonly ListColumnSpec[];
+    readonly handler: QueryHandlerDef | undefined;
+    readonly featureMap: ReadonlyMap<string, FeatureDefinition>;
+}): void;

package/dist/engine/boot-validator/list-table-aggregate-query.js

@@ -0,0 +1,31 @@
+import { resolveEntityBehindListQuery } from "../entity-list-searchability.js";
+import { normalizeListColumn } from "../screen-helpers.js";
+import { entityAggregateFieldLookup, validateListTableAggregateFieldTypes, } from "./list-table-aggregate-options.js";
+import { findEntity } from "./parent-ref.js";
+import { getZodObjectShape } from "./zod-shape.js";
+function columnValueTypeLookup(columns) {
+    const valueTypes = new Map(columns
+        .map(normalizeListColumn)
+        .flatMap((col) => (col.valueType === undefined ? [] : [[col.field, col.valueType]])));
+    return (field) => {
+        const type = valueTypes.get(field);
+        return type === undefined ? undefined : { type, multiple: false, secret: false };
+    };
+}
+// Same pattern as searchable vs search: grouping and totals send `aggregate`,
+// which a query without it in its Zod schema would reject on every load.
+export function validateListTableAggregateQuery(args) {
+    const { prefix, query, table, handler } = args;
+    // skip: neither grouping nor totals declared, nothing travels via aggregate
+    if (table?.grouping === undefined && table?.totals === undefined)
+        return;
+    const shape = getZodObjectShape(handler?.schema);
+    if (shape === undefined || !("aggregate" in shape)) {
+        throw new Error(`${prefix}: table.grouping/table.totals need query "${query}" to accept "aggregate" — ` +
+            `reuse entityListSchema (or listAggregatePayloadSchema) in the handler's schema and answer it ` +
+            `with answerListAggregate, or remove grouping and totals.`);
+    }
+    const entity = resolveEntityBehindListQuery(query, handler, (name) => findEntity(args.featureMap, name));
+    const lookup = entity === undefined ? columnValueTypeLookup(args.columns) : entityAggregateFieldLookup(entity);
+    validateListTableAggregateFieldTypes(prefix, table, lookup, entity !== undefined);
+}

package/dist/engine/boot-validator/list-table-export-options.d.ts

@@ -0,0 +1 @@
+export declare function validateExportOptions(where: string, value: unknown, allowed: boolean): void;

package/dist/engine/boot-validator/list-table-export-options.js

@@ -0,0 +1,27 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { LIST_TABLE_EXPORT_KEYS, MAX_EXPORT_MAX_ROWS } from "../types/screen.js";
+import { rejectUnknownKeys } from "./list-table-reject-unknown-keys.js";
+export function validateExportOptions(where, value, allowed) {
+    if (!allowed) {
+        throw new Error(`${where} table.export is only available on entityList and projectionList screens. Remove it here.`);
+    }
+    if (!isPlainObject(value)) {
+        throw new Error(`${where} table.export must be an object like { xlsx: true, maxRows: 5000 }.`);
+    }
+    rejectUnknownKeys(where, "table.export", value, LIST_TABLE_EXPORT_KEYS);
+    if (value["xlsx"] !== true) {
+        throw new Error(`${where} table.export.xlsx must be true (the only export format).`);
+    }
+    if (value["maxRows"] !== undefined)
+        validateMaxRows(where, value["maxRows"]);
+}
+function validateMaxRows(where, maxRows) {
+    if (typeof maxRows !== "number" || !Number.isInteger(maxRows) || maxRows < 1) {
+        throw new Error(`${where} table.export.maxRows is ${JSON.stringify(maxRows)} — must be an integer >= 1. ` +
+            `Set a positive row limit or remove maxRows to use the default.`);
+    }
+    if (maxRows > MAX_EXPORT_MAX_ROWS) {
+        throw new Error(`${where} table.export.maxRows is ${maxRows} — must be at most ${MAX_EXPORT_MAX_ROWS} ` +
+            `(the workbook is built in memory). Lower maxRows.`);
+    }
+}

package/dist/engine/boot-validator/list-table-options.d.ts

@@ -0,0 +1,3 @@
+import { type ListColumnSpec } from "../types/screen.ts";
+/** `where` is the full message prefix, e.g. `[Feature x] Screen "y" (entityList)`. */
+export declare function validateListTableOptions(where: string, table: unknown, columns: readonly ListColumnSpec[], exportAllowed?: boolean): void;

package/dist/engine/boot-validator/list-table-options.js

@@ -0,0 +1,77 @@
+import { isOneOf, isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { normalizeListColumn } from "../screen-helpers.js";
+import { LIST_TABLE_DENSITIES, LIST_TABLE_DENSITY_KEYS, LIST_TABLE_OPTION_KEYS, } from "../types/screen.js";
+import { validateColumnLayout } from "./list-column-layout.js";
+import { validateListTableAggregateShape } from "./list-table-aggregate-options.js";
+import { validateExportOptions } from "./list-table-export-options.js";
+import { rejectUnknownKeys } from "./list-table-reject-unknown-keys.js";
+const BOOLEAN_OPTION_KEYS = [
+    "rememberState",
+    "resetAll",
+    "columnPicker",
+    "pinning",
+    "resizing",
+    "keyboardNavigation",
+];
+function validateDensity(where, density) {
+    if (!isPlainObject(density)) {
+        throw new Error(`${where} table.density must be an object like { default: "compact", userChoice: true }.`);
+    }
+    rejectUnknownKeys(where, "table.density", density, LIST_TABLE_DENSITY_KEYS);
+    if (Object.keys(density).length === 0) {
+        throw new Error(`${where} table.density is empty. Set default (${LIST_TABLE_DENSITIES.join(" | ")}) ` +
+            `and/or userChoice, or remove table.density.`);
+    }
+    if (density["default"] !== undefined && !isOneOf(LIST_TABLE_DENSITIES, density["default"])) {
+        throw new Error(`${where} table.density.default is ${JSON.stringify(density["default"])} — ` +
+            `must be one of ${LIST_TABLE_DENSITIES.map((d) => `"${d}"`).join(", ")}.`);
+    }
+    if (density["userChoice"] !== undefined && typeof density["userChoice"] !== "boolean") {
+        throw new Error(`${where} table.density.userChoice must be a boolean.`);
+    }
+}
+function validateHiddenColumns(where, columnPickerOn, columns) {
+    const normalized = columns.map(normalizeListColumn);
+    for (const col of normalized) {
+        if (col.hidden !== undefined && typeof col.hidden !== "boolean") {
+            throw new Error(`${where} column "${col.field}" has a non-boolean "hidden".`);
+        }
+    }
+    const hidden = normalized.filter((col) => col.hidden === true);
+    // skip: no hidden columns, nothing to validate
+    if (hidden.length === 0)
+        return;
+    if (!columnPickerOn) {
+        throw new Error(`${where} column "${hidden[0]?.field}" is hidden but table.columnPicker is not enabled, ` +
+            `so the user could never show it. Set table: { columnPicker: true } or remove "hidden".`);
+    }
+    if (hidden.length === normalized.length) {
+        throw new Error(`${where} hides every column. At least one column must start visible — remove "hidden" from one.`);
+    }
+}
+/** `where` is the full message prefix, e.g. `[Feature x] Screen "y" (entityList)`. */
+export function validateListTableOptions(where, table, columns, exportAllowed = false) {
+    if (table === undefined) {
+        validateHiddenColumns(where, false, columns);
+        validateColumnLayout(where, { pinning: false, resizing: false }, columns);
+        // skip: no table block: nothing else to check
+        return;
+    }
+    if (!isPlainObject(table)) {
+        throw new Error(`${where} table must be an object like { rememberState: true }. ` +
+            `Allowed keys: ${LIST_TABLE_OPTION_KEYS.join(", ")}.`);
+    }
+    rejectUnknownKeys(where, "table", table, LIST_TABLE_OPTION_KEYS);
+    for (const key of BOOLEAN_OPTION_KEYS) {
+        if (table[key] !== undefined && typeof table[key] !== "boolean") {
+            throw new Error(`${where} table.${key} must be a boolean, got ${typeof table[key]}.`);
+        }
+    }
+    if (table["density"] !== undefined)
+        validateDensity(where, table["density"]);
+    if (table["export"] !== undefined)
+        validateExportOptions(where, table["export"], exportAllowed);
+    validateListTableAggregateShape(where, table, columns);
+    validateHiddenColumns(where, table["columnPicker"] === true, columns);
+    validateColumnLayout(where, { pinning: table["pinning"] === true, resizing: table["resizing"] === true }, columns);
+}

package/dist/engine/boot-validator/list-table-reject-unknown-keys.d.ts

@@ -0,0 +1 @@
+export declare function rejectUnknownKeys(where: string, block: string, value: Record<string, unknown>, allowed: readonly string[]): void;

package/dist/engine/boot-validator/list-table-reject-unknown-keys.js

@@ -0,0 +1,7 @@
+export function rejectUnknownKeys(where, block, value, allowed) {
+    const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (unknown.length > 0) {
+        throw new Error(`${where} ${block} has unknown key(s) ${unknown.map((k) => `"${k}"`).join(", ")}. ` +
+            `Allowed keys: ${allowed.join(", ")}.`);
+    }
+}

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

@@ -1,4 +1,4 @@
-import { type FeatureDefinition, type QueryHandlerDef } from "../types/index.ts";
+import type { FeatureDefinition, QueryHandlerDef } from "../types/index.ts";
 export declare function buildQueryHandlerMap(features: readonly FeatureDefinition[]): ReadonlyMap<string, QueryHandlerDef>;
 export declare function validateProjectionListScreens(features: readonly FeatureDefinition[]): void;
 export declare function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void;

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

@@ -1,8 +1,8 @@
 import { isListQueryWithoutSearchableFields, resolveEntityBehindListQuery, } from "../entity-list-searchability.js";
 import { QnTypes, qualifyEntityName } from "../qualified-name.js";
 import { isEditLayoutScreen } from "../screen-helpers.js";
-import { relatedListGroupHeaderLabel, relatedListGroupKey, } from "../types/index.js";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
+import { validateListTableAggregateQuery } from "./list-table-aggregate-query.js";
 import { findEntity } from "./parent-ref.js";
 import { getZodObjectShape } from "./zod-shape.js";
 // Sibling to entity-list-screens.ts rather than an extension of it:
@@ -66,6 +66,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers, feature
     }
     validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
     validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
+    validateListTableAggregateQuery({ prefix, ...screen, handler, featureMap });
 }
 // filter sends `payload.filter` — same 422 footgun as facets below
 // if the handler's schema doesn't accept it.
@@ -190,17 +191,6 @@ function validateRelatedListParentFilter(prefix, section, schema, handler, featu
             `entity behind query "${section.query}". Known fields: ${Object.keys(entity.fields).sort().join(", ")}.`);
     }
 }
-// A collapsed group without a header has no toggle, so its rows could never be opened.
-function validateRelatedListGroupBy(prefix, section) {
-    const groupBy = section.groupBy;
-    const collapsedKey = groupBy?.collapsedWhen === undefined ? undefined : relatedListGroupKey(groupBy.collapsedWhen);
-    if (groupBy !== undefined &&
-        collapsedKey !== undefined &&
-        relatedListGroupHeaderLabel(groupBy, collapsedKey) === undefined) {
-        throw new Error(`${prefix}: groupBy.collapsedWhen "${collapsedKey}" names a group without a header; ` +
-            `set groupBy.label or groupBy.labels["${collapsedKey}"], or drop collapsedWhen.`);
-    }
-}
 // relatedList sections declare search/facets the same way a projectionList
 // screen does, and hit the same 422 footgun: definePagedQueryHandler doesn't
 // auto-merge params into the handler's own Zod schema, so an
@@ -217,7 +207,7 @@ export function validateRelatedListSectionQueries(features) {
         validateRelatedListSearchable(prefix, section, schema);
         validateRelatedListFacets(prefix, section, schema);
         validateRelatedListParentFilter(prefix, section, schema, handler, featureMap);
-        validateRelatedListGroupBy(prefix, section);
+        validateListTableAggregateQuery({ prefix, ...section, handler, featureMap });
     };
     for (const feature of features) {
         for (const screen of Object.values(feature.screens)) {

package/dist/engine/boot-validator/related-list-table-rules.d.ts

@@ -0,0 +1,4 @@
+/** Grouping rules of a relatedList section or entityList.expandableRow, before the shared table checks. */
+export declare function validateRelatedListGroupingRules(prefix: string, section: {
+    readonly table?: unknown;
+}, isExpandableRow: boolean): void;

package/dist/engine/boot-validator/related-list-table-rules.js

@@ -0,0 +1,42 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+const EXPANDABLE_ROW_TABLE_KEYS = new Set(["grouping"]);
+const EXPANDABLE_ROW_REJECTED_GROUPING_KEYS = ["userChoice", "fields"];
+// `groupBy` grouped the loaded page on the client; it is gone, and a screen
+// still carrying it fails at boot instead of silently losing its groups.
+function rejectRemovedGroupBy(prefix, section) {
+    if (Object.hasOwn(section, "groupBy")) {
+        throw new Error(`${prefix} uses groupBy, which was removed. Use table.grouping: { field, label?, labels?, collapsedWhen? }; ` +
+            `groups and counts come from the server, so the bound query must accept aggregate.`);
+    }
+}
+function rejectExpandableRowTableOptions(prefix, table) {
+    if (isPlainObject(table)) {
+        rejectUnsupportedTableKeys(prefix, table);
+        rejectGroupingChoice(prefix, table["grouping"]);
+    }
+}
+function rejectUnsupportedTableKeys(prefix, table) {
+    const unsupported = Object.keys(table).filter((key) => !EXPANDABLE_ROW_TABLE_KEYS.has(key));
+    if (unsupported.length > 0) {
+        throw new Error(`${prefix} supports only table.grouping, not table.${unsupported.join(", table.")}. ` +
+            `Put the other table options on the entityList screen itself.`);
+    }
+}
+function rejectGroupingChoice(prefix, grouping) {
+    const choiceKey = isPlainObject(grouping)
+        ? EXPANDABLE_ROW_REJECTED_GROUPING_KEYS.find((key) => Object.hasOwn(grouping, key))
+        : undefined;
+    if (choiceKey !== undefined) {
+        throw new Error(`${prefix} does not support table.grouping.${choiceKey}: an expanded row has no view menu. ` +
+            `Set a fixed table.grouping.field.`);
+    }
+}
+/** Grouping rules of a relatedList section or entityList.expandableRow, before the shared table checks. */
+export function validateRelatedListGroupingRules(prefix, section, isExpandableRow) {
+    rejectRemovedGroupBy(prefix, section);
+    if (isExpandableRow && Object.hasOwn(section, "bulkActions")) {
+        throw new Error(`${prefix} does not support bulkActions. Put bulkActions on the entityList screen itself.`);
+    }
+    if (isExpandableRow)
+        rejectExpandableRowTableOptions(prefix, section.table);
+}

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

@@ -3,7 +3,10 @@ import { rowMetaFieldNames } from "../../db/table-builder.js";
 import { qualifyEntityName } from "../qualified-name.js";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops.js";
 import { normalizeListColumn } from "../screen-helpers.js";
+import { validateEntityListAggregateOptions } from "./entity-list-aggregate-options.js";
 import { LIST_ROW_META_COLUMN_NAMES } from "./entity-list-screens.js";
+import { validateListBulkActions } from "./list-bulk-actions.js";
+import { validateListTableOptions } from "./list-table-options.js";
 import { assertWriteHandlerRegistered, rejectRedirectOnListRowAction, resolveRowActionNavigateTarget, validateActionFieldRefs, validateAtMostOneRowClick, validateDrawerTargetAction, validateRowActionNavigateParams, } from "./screens-actions.js";
 import { buildUnknownFieldMessage, listActionContext, rejectEmptyColumns, rejectNonArrayInFilter, resolveScreenEntity, validateListColumnRendering, } from "./screens-kind-shared.js";
 import { validateRelatedListSection, validateRowActionTarget } from "./screens-lists.js";
@@ -201,6 +204,9 @@ export function validateEntityListScreen(ctx, screenId, screen) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) has pageSize=${screen.pageSize} — ` +
             `must be a positive integer.`);
     }
+    const where = `[Feature ${featureName}] Screen "${screenId}" (entityList)`;
+    validateListTableOptions(where, screen.table, screen.columns, true);
+    validateEntityListAggregateOptions(where, screen, fields.entityDef);
     if (screen.defaultSort !== undefined) {
         validateEntityListDefaultSort(featureName, screenId, screen.defaultSort, fields);
     }
@@ -219,6 +225,7 @@ export function validateEntityListScreen(ctx, screenId, screen) {
         }
         validateAtMostOneRowClick(featureName, screenId, "entityList", screen.rowActions);
     }
+    validateListBulkActions(`[Feature ${featureName}] Screen "${screenId}" (entityList)`, screen.bulkActions, screen.rowActions);
     for (const action of screen.toolbarActions ?? []) {
         validateEntityListToolbarAction(ctx, screenId, fields, action);
     }

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

@@ -1,4 +1,6 @@
 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";
@@ -34,6 +36,7 @@ export function validateProjectionListScreen(ctx, screenId, screen) {
     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.
@@ -46,6 +49,7 @@ export function validateProjectionListScreen(ctx, screenId, screen) {
     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);
     }