@olenbetong/appframe-core 2.11.10 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olenbetong/appframe-core",
-  "version": "2.11.10",
+  "version": "2.12.0",
   "description": "Javascript libraries to utilize the Appframe framework",
   "type": "module",
   "sideEffects": [
@@ -40,17 +40,17 @@
     "mitt": "^3.0.1"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^15.7.3",
-    "@types/bun": "^1.1.8",
-    "chalk": "^5.3.0"
+    "@happy-dom/global-registrator": "^20.11.2",
+    "@types/bun": "^1.3.14",
+    "chalk": "^5.6.2"
   },
   "peerDependencies": {},
   "optionalDependencies": {},
   "scripts": {
-    "build": "pnpm run build:tsc && pnpm test && pnpm run build:esbuild && pnpm run build:replace-version",
+    "build": "pnpm run build:tsc && pnpm test && pnpm run build:bundle && pnpm run build:replace-version",
     "test": "vitest run --config vitest.node.config.ts",
-    "build:esbuild": "node --no-warnings ../../scripts/packages-esbuild.ts",
+    "build:bundle": "node --no-warnings ../../scripts/packages-bundle.ts",
     "build:replace-version": "node ./scripts/replace-version.js",
-    "build:tsc": "rm -rf ./es tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json"
+    "build:tsc": "node --no-warnings ../../scripts/clean.ts ./es tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json"
   }
 }

package/src/alert.ts

@@ -11,13 +11,28 @@ const template = `
 	</dialog>
 `;
 
-if (globalThis.document && !document.querySelector("#AlertDialogTemplate")) {
+/*
+ * The module can be loaded from `<head>`, where there is no body to append to
+ * yet. Waiting for the DOM in that case keeps the whole bundle from throwing on
+ * load — everything else it exports would be lost with it.
+ */
+function addDialogTemplate() {
+	if (document.querySelector("#AlertDialogTemplate")) return;
+
 	let $template = document.createElement("template");
 	$template.id = "AlertDialogTemplate";
 	$template.innerHTML = template;
 	document.body.append($template);
 }
 
+if (globalThis.document) {
+	if (document.body) {
+		addDialogTemplate();
+	} else {
+		document.addEventListener("DOMContentLoaded", addDialogTemplate, { once: true });
+	}
+}
+
 export function waitForDialog(dialog: HTMLDialogElement, cancelValue = "No"): Promise<string> {
 	return new Promise((resolve) => {
 		let controller = new AbortController();

package/src/filter/convertFilter.ts

@@ -0,0 +1,47 @@
+import { toFilterTree } from "./tree.js";
+import type { FilterGroup } from "./types.js";
+
+const CONVERT_URL = "/api/filter/convert";
+
+export type FilterConversionResult = {
+	filterObject: FilterGroup | null;
+	filterString: string;
+	whereClause: string;
+	/** Set when the filter string could not be parsed into a structured filter. */
+	warning?: string;
+};
+
+export type ConvertRequest = {
+	filterObject?: FilterGroup | null;
+	filterString?: string;
+	/** Optional view name, used server-side to validate field names. */
+	viewName?: string;
+};
+
+/**
+ * Converts between a structured filter and a DevExpress filter string.
+ *
+ * The conversion is done server-side by `api/filter/convert`, because the
+ * criteria string grammar is implemented by the licensed DevExpress parser that
+ * the Windows client and the report engine use. Doing it in the browser would
+ * risk producing strings the server cannot parse back.
+ */
+export async function convertFilter(request: ConvertRequest, signal?: AbortSignal): Promise<FilterConversionResult> {
+	let response = await fetch(CONVERT_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(request),
+		signal,
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to convert filter: ${response.status} ${response.statusText}`);
+	}
+
+	let result = (await response.json()) as FilterConversionResult;
+
+	return {
+		...result,
+		filterObject: result.filterObject ? toFilterTree(result.filterObject) : null,
+	};
+}

package/src/filter/describeFilter.test.ts

@@ -0,0 +1,103 @@
+import type { FilterExpression } from "./types.js";
+import { describe, expect, test } from "vitest";
+
+import { describeFilter } from "./describeFilter.js";
+import { createEmptyFilter } from "./tree.js";
+
+const fields = [
+	{ name: "PersonID", caption: "Person ID", type: "string" as const },
+	{ name: "Created", caption: "Created", type: "date" as const },
+	{ name: "Amount", caption: "Amount", type: "number" as const },
+];
+
+function expression(
+	column: string,
+	operator: string,
+	value: FilterExpression["value"],
+	valueType = "string",
+): FilterExpression {
+	return { type: "expression", column, operator, value, valueType };
+}
+
+describe("describeFilter", () => {
+	test("empty filters describe as an empty string", () => {
+		expect(describeFilter(null)).toBe("");
+		expect(describeFilter(createEmptyFilter())).toBe("");
+	});
+
+	test("uses the field caption when available", () => {
+		let filter = expression("PersonID", "contains", "silv");
+
+		expect(describeFilter(filter, { fields })).toBe("[Person ID] Contains 'silv'");
+	});
+
+	test("falls back to the column name when the field is unknown", () => {
+		expect(describeFilter(expression("Unknown", "equals", "x"), { fields })).toBe("[Unknown] Equal to 'x'");
+	});
+
+	test("parameterless operators render without a value", () => {
+		expect(describeFilter(expression("PersonID", "isnull", null, "null"), { fields })).toBe("[Person ID] Is null");
+	});
+
+	test("numbers are not quoted", () => {
+		expect(describeFilter(expression("Amount", "greaterthan", 100, "number"), { fields })).toBe(
+			"[Amount] Greater than 100",
+		);
+	});
+
+	test("date fields use the relative operator wording", () => {
+		expect(describeFilter(expression("Created", "greaterthan", "2026-01-01", "datetime"), { fields })).toBe(
+			"[Created] After '2026-01-01'",
+		);
+	});
+
+	test("dynamic values render as their label", () => {
+		expect(describeFilter(expression("Created", "equals", "ThisMonth", "special"), { fields })).toBe(
+			"[Created] Equal to This month",
+		);
+	});
+
+	test("between renders a range", () => {
+		expect(describeFilter(expression("Amount", "between", ["1", "9"], "number"), { fields })).toBe(
+			"[Amount] Between 1 - 9",
+		);
+	});
+
+	test("in list renders a parenthesised list", () => {
+		expect(describeFilter(expression("PersonID", "inlist", ["a", "b"]), { fields })).toBe(
+			"[Person ID] In list ('a', 'b')",
+		);
+	});
+
+	test("groups are joined by their mode and nested groups are parenthesised", () => {
+		let filter = {
+			type: "group" as const,
+			mode: "or" as const,
+			items: [
+				{
+					type: "group" as const,
+					mode: "and" as const,
+					items: [expression("PersonID", "equals", "a"), expression("Amount", "greaterthan", 5, "number")],
+				},
+				{ type: "group" as const, mode: "and" as const, items: [expression("PersonID", "equals", "b")] },
+			],
+		};
+
+		expect(describeFilter(filter, { fields })).toBe(
+			"([Person ID] Equal to 'a' AND [Amount] Greater than 5) OR [Person ID] Equal to 'b'",
+		);
+	});
+
+	test("empty groups are omitted", () => {
+		let filter = {
+			type: "group" as const,
+			mode: "or" as const,
+			items: [
+				{ type: "group" as const, mode: "and" as const, items: [expression("PersonID", "equals", "a")] },
+				{ type: "group" as const, mode: "and" as const, items: [] },
+			],
+		};
+
+		expect(describeFilter(filter, { fields })).toBe("[Person ID] Equal to 'a'");
+	});
+});

package/src/filter/describeFilter.ts

@@ -0,0 +1,79 @@
+import type { FilterExpression, FilterGroup } from "./types.js";
+import { getDynamicValueLabel, getOperatorArity, getOperatorLabel, normalizeOperator } from "./operators.js";
+import { isExpression } from "./tree.js";
+import type { DynamicValue, FieldMetadata } from "./types.js";
+
+export type DescribeFilterOptions = {
+	/** Field metadata, used to resolve captions and date operator wording. */
+	fields?: FieldMetadata[];
+};
+
+/**
+ * Builds a human-readable description of a filter, without contacting the
+ * server. Use this for read-only summaries; the authoritative filter string is
+ * produced by `api/filter/convert`, since only the server can generate the
+ * DevExpress criteria syntax.
+ */
+export function describeFilter(
+	filter: FilterGroup | FilterExpression | null | undefined,
+	options: DescribeFilterOptions = {},
+): string {
+	if (!filter) return "";
+
+	let fieldsByName = new Map((options.fields ?? []).map((field) => [field.name.toLowerCase(), field]));
+
+	return describe(filter, fieldsByName, 0);
+}
+
+function describe(item: FilterGroup | FilterExpression, fields: Map<string, FieldMetadata>, depth: number): string {
+	if (isExpression(item)) return describeExpression(item, fields);
+
+	let parts = item.items.map((child) => describe(child, fields, depth + 1)).filter((part) => part !== "");
+
+	if (parts.length === 0) return "";
+	if (parts.length === 1) return parts[0] as string;
+
+	let separator = item.mode === "or" ? " OR " : " AND ";
+	let joined = parts.join(separator);
+
+	return depth === 0 ? joined : `(${joined})`;
+}
+
+function describeExpression(expression: FilterExpression, fields: Map<string, FieldMetadata>): string {
+	if (!expression.column || !expression.operator) return "";
+
+	let field = fields.get(expression.column.toLowerCase());
+	let caption = field?.caption ?? expression.column;
+	let operator = normalizeOperator(expression.operator);
+	let label = getOperatorLabel(operator, field?.type);
+	let arity = getOperatorArity(operator);
+
+	if (arity === "none") return `[${caption}] ${label}`;
+
+	return `[${caption}] ${label} ${formatValue(expression, arity)}`;
+}
+
+function formatValue(expression: FilterExpression, arity: ReturnType<typeof getOperatorArity>): string {
+	let { value, valueType } = expression;
+
+	if (valueType === "special" && typeof value === "string") {
+		return getDynamicValueLabel(value as DynamicValue);
+	}
+
+	if (Array.isArray(value)) {
+		let formatted = value.map((item) => formatScalar(item, valueType));
+
+		return arity === "pair" ? formatted.join(" - ") : `(${formatted.join(", ")})`;
+	}
+
+	return formatScalar(value, valueType);
+}
+
+function formatScalar(value: unknown, valueType: string): string {
+	if (value === null || value === undefined) return "";
+	if (value instanceof Date) return value.toISOString().slice(0, 10);
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (valueType === "number" || valueType === "boolean") return String(value);
+
+	return `'${String(value)}'`;
+}

package/src/filter/fields.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "vitest";
+
+import { toFieldMetadata, toFieldMetadataList, toFilterFieldType } from "./fields.js";
+
+describe("toFilterFieldType", () => {
+	test("passes through the types the view normalizes to", () => {
+		expect(toFilterFieldType("boolean")).toBe("boolean");
+		expect(toFilterFieldType("datetime")).toBe("datetime");
+		expect(toFilterFieldType("uniqueidentifier")).toBe("uniqueidentifier");
+	});
+
+	test("an unknown or missing type is filtered as text", () => {
+		expect(toFilterFieldType("geography")).toBe("string");
+		expect(toFilterFieldType(null)).toBe("string");
+	});
+});
+
+describe("toFieldMetadata", () => {
+	test("maps a record", () => {
+		let field = toFieldMetadata({
+			FieldName: "PersonID",
+			DataType: "string",
+			Nullable: true,
+			ExcludeFromFilter: false,
+			ValueListRecordSource: "<afRecordSource />",
+		});
+
+		expect(field).toEqual({
+			name: "PersonID",
+			type: "string",
+			nullable: true,
+			excludeFromFilter: false,
+			valueListRecordSource: "<afRecordSource />",
+		});
+	});
+
+	test("bit columns arrive as numbers", () => {
+		expect(toFieldMetadata({ FieldName: "A", Nullable: 1 }).nullable).toBe(true);
+		expect(toFieldMetadata({ FieldName: "A", Nullable: 0 }).nullable).toBe(false);
+	});
+
+	test("an empty record source is dropped rather than kept as an empty string", () => {
+		expect(toFieldMetadata({ FieldName: "A", ValueListRecordSource: "" }).valueListRecordSource).toBeUndefined();
+	});
+});
+
+describe("toFieldMetadataList", () => {
+	test("sorts by name and drops excluded and unnamed fields", () => {
+		let fields = toFieldMetadataList([
+			{ FieldName: "Name", DataType: "string" },
+			{ FieldName: "Age", DataType: "number" },
+			{ FieldName: "CDL", DataType: "boolean", ExcludeFromFilter: true },
+			{ FieldName: "", DataType: "string" },
+		]);
+
+		expect(fields.map((field) => field.name)).toEqual(["Age", "Name"]);
+	});
+});

package/src/filter/fields.ts

@@ -0,0 +1,56 @@
+/**
+ * Field metadata for the filter builder.
+ *
+ * `sviw_WebSiteCMS_FilterBuilder_ViewFields` normalizes the SQL data types into
+ * the handful of types the builder groups fields by, so the mapping here is
+ * mostly a rename. The loading lives in `useFilterFields` in
+ * `@olenbetong/appframe-react`.
+ */
+
+import type { FieldMetadata, FilterFieldType } from "./types.js";
+
+/** A raw `sviw_WebSiteCMS_FilterBuilder_ViewFields` record. */
+export type ViewFieldRecord = {
+	FieldName?: string | null;
+	/** Already normalized by the view; anything unexpected is treated as text. */
+	DataType?: string | null;
+	DBObjectID?: string | null;
+	Nullable?: boolean | number | null;
+	ExcludeFromFilter?: boolean | number | null;
+	ValueListRecordSource?: string | null;
+};
+
+const FIELD_TYPES: FilterFieldType[] = ["string", "number", "boolean", "date", "datetime", "uniqueidentifier"];
+
+/** The builder type for a normalized `DataType`. Unknown types are filtered as text. */
+export function toFilterFieldType(dataType: string | null | undefined): FilterFieldType {
+	let normalized = dataType?.trim().toLowerCase();
+
+	return FIELD_TYPES.find((type) => type === normalized) ?? "string";
+}
+
+function toBoolean(value: boolean | number | null | undefined) {
+	return value === true || value === 1;
+}
+
+/** Maps a view field record onto the metadata the builder renders. */
+export function toFieldMetadata(record: ViewFieldRecord): FieldMetadata {
+	return {
+		name: record.FieldName ?? "",
+		type: toFilterFieldType(record.DataType),
+		nullable: toBoolean(record.Nullable),
+		excludeFromFilter: toBoolean(record.ExcludeFromFilter),
+		valueListRecordSource: record.ValueListRecordSource || undefined,
+	};
+}
+
+/**
+ * Maps and sorts view field records. Fields the view marks as excluded are
+ * dropped rather than hidden, since nothing else can use them.
+ */
+export function toFieldMetadataList(records: ViewFieldRecord[]): FieldMetadata[] {
+	return records
+		.map(toFieldMetadata)
+		.filter((field) => field.name !== "" && !field.excludeFromFilter)
+		.sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/filter/index.ts

@@ -0,0 +1,62 @@
+export { type ConvertRequest, convertFilter, type FilterConversionResult } from "./convertFilter.js";
+export { describeFilter, type DescribeFilterOptions } from "./describeFilter.js";
+export { toFieldMetadata, toFieldMetadataList, toFilterFieldType, type ViewFieldRecord } from "./fields.js";
+export {
+	getDefaultOperator,
+	getDynamicValueLabel,
+	getDynamicValuesForField,
+	getOperatorArity,
+	getOperatorLabel,
+	getOperatorsForField,
+	getValueType,
+	normalizeOperator,
+	type OperatorArity,
+	RELATIVE_DATE_VALUES,
+} from "./operators.js";
+export { coerceToStandardLayout, isStandardLayout } from "./standardLayout.js";
+export {
+	canDeleteSavedFilter,
+	canEditSavedFilter,
+	canRenameSavedFilter,
+	canSetCrossDomain,
+	canShareSavedFilter,
+	findSavedFilter,
+	NO_FILTER_ID,
+	partitionSavedFilters,
+	type SavedFilter,
+	type SavedFilterRecord,
+	toSavedFilter,
+	toSavedFilters,
+} from "./savedFilters.js";
+export {
+	addGroupAtPath,
+	changeOperator,
+	countExpressions,
+	createEmptyFilter,
+	createEmptyGroup,
+	createExpression,
+	type FilterNode,
+	type FilterPath,
+	getNodeAtPath,
+	insertNodeAtPath,
+	isCompleteExpression,
+	isEmptyFilter,
+	isExpression,
+	isGroup,
+	pruneFilter,
+	removeNodeAtPath,
+	setGroupMode,
+	toFilterTree,
+	updateNodeAtPath,
+} from "./tree.js";
+export type {
+	DynamicValue,
+	FieldMetadata,
+	FilterAccessLevel,
+	FilterExpression,
+	FilterFieldType,
+	FilterGroup,
+	FilterOperator,
+	FilterTree,
+	FilterValueType,
+} from "./types.js";

package/src/filter/operators.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "vitest";
+
+import {
+	getDefaultOperator,
+	getDynamicValuesForField,
+	getOperatorArity,
+	getOperatorLabel,
+	getOperatorsForField,
+	getValueType,
+	normalizeOperator,
+} from "./operators.js";
+
+describe("getOperatorsForField", () => {
+	test("boolean fields only get truth checks", () => {
+		expect(getOperatorsForField({ type: "boolean" })).toEqual(["istrue", "isfalse"]);
+	});
+
+	test("boolean fields never get null checks", () => {
+		expect(getOperatorsForField({ type: "boolean", nullable: true })).toEqual(["istrue", "isfalse"]);
+	});
+
+	test("nullable fields get null checks last", () => {
+		let operators = getOperatorsForField({ type: "number", nullable: true });
+
+		expect(operators.slice(-2)).toEqual(["isnull", "isnotnull"]);
+	});
+
+	test("string fields get the string comparison operators", () => {
+		let operators = getOperatorsForField({ type: "string" });
+
+		expect(operators).toContain("contains");
+		expect(operators).toContain("beginswith");
+		expect(operators).toContain("isblank");
+	});
+
+	test("number fields do not get string comparison operators", () => {
+		let operators = getOperatorsForField({ type: "number" });
+
+		expect(operators).not.toContain("contains");
+		expect(operators).not.toContain("beginswith");
+	});
+
+	test("unknown field types fall back to the string operators", () => {
+		let operators = getOperatorsForField({ type: "something" as never });
+
+		expect(operators).toEqual(getOperatorsForField({ type: "string" }));
+	});
+});
+
+describe("getDefaultOperator", () => {
+	test.each([
+		["string", "beginswith"],
+		["number", "equals"],
+		["date", "equals"],
+		["datetime", "equals"],
+		["boolean", "istrue"],
+	] as const)("%s defaults to %s", (type, expected) => {
+		expect(getDefaultOperator({ type })).toBe(expected);
+	});
+});
+
+describe("getOperatorArity", () => {
+	test.each([
+		["isnull", "none"],
+		["istrue", "none"],
+		["isblank", "none"],
+		["between", "pair"],
+		["datenotbetween", "pair"],
+		["inlist", "list"],
+		["notinlist", "list"],
+		["equals", "single"],
+		["contains", "single"],
+	] as const)("%s has arity %s", (operator, expected) => {
+		expect(getOperatorArity(operator)).toBe(expected);
+	});
+});
+
+describe("getOperatorLabel", () => {
+	test("date fields get the relative wording for comparisons", () => {
+		expect(getOperatorLabel("greaterthan", "date")).toBe("After");
+		expect(getOperatorLabel("lessthanorequal", "datetime")).toBe("Up to");
+	});
+
+	test("number fields get the numeric wording", () => {
+		expect(getOperatorLabel("greaterthan", "number")).toBe("Greater than");
+	});
+
+	test("non-comparison operators are unaffected by the field type", () => {
+		expect(getOperatorLabel("inlist", "date")).toBe("In list");
+		expect(getOperatorLabel("inlist", "number")).toBe("In list");
+	});
+});
+
+describe("getValueType", () => {
+	test("parameterless operators send a null value type", () => {
+		expect(getValueType({ type: "string" }, "isnull")).toBe("null");
+		expect(getValueType({ type: "boolean" }, "istrue")).toBe("null");
+	});
+
+	test.each([
+		["string", "string"],
+		["number", "number"],
+		["date", "datetime"],
+		["datetime", "datetime"],
+		["uniqueidentifier", "uniqueidentifier"],
+	] as const)("%s fields send %s", (type, expected) => {
+		expect(getValueType({ type }, "equals")).toBe(expected);
+	});
+});
+
+describe("normalizeOperator", () => {
+	test.each([
+		["Equals", "equals"],
+		["BeginsWith", "beginswith"],
+		["NotDateEquals", "notdatequals"],
+		["Not", "notequals"],
+		["Tweens", "notbetween"],
+		["Not, Date", "notdatequals"],
+	])("%s normalizes to %s", (input, expected) => {
+		expect(normalizeOperator(input)).toBe(expected);
+	});
+});
+
+describe("getDynamicValuesForField", () => {
+	test("date fields get relative dates", () => {
+		expect(getDynamicValuesForField({ type: "date" })).toContain("ThisMonth");
+	});
+
+	test("string fields only get the current user", () => {
+		expect(getDynamicValuesForField({ type: "string" })).toEqual(["CurrentUser"]);
+	});
+
+	test("number fields get none", () => {
+		expect(getDynamicValuesForField({ type: "number" })).toEqual([]);
+	});
+});