@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

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(", ")}.`);
+    }
+}