@olenbetong/appframe-core 2.11.9 → 2.12.0

package/es/report/types.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Report metadata — the shape of a report and its parameters, as the Windows
+ * report launcher understands them.
+ *
+ * The loading lives in `useReport` in `@olenbetong/appframe-react`; everything
+ * here is pure.
+ */
+/**
+ * The parameter types `sviw_WinClient_ReportsParameters.DataType` uses. The
+ * Windows launcher creates a text edit, a numeric edit, a date edit or a check
+ * edit from this, unless the parameter has a lookup or a fixed item list.
+ */
+export type ReportParameterType = "String" | "Integer" | "Double" | "Date" | "Boolean";
+/** How a parameter should be edited. Derived from the metadata, not stored. */
+export type ReportParameterEditor = "text" | "number" | "date" | "boolean" | "select" | "lookup";
+/** A column selected by an `afRecordSource`. */
+export type ReportRecordSourceColumn = {
+    name: string;
+    /** The field type the web data API expects, mapped from the CLR type. */
+    type: "string" | "number" | "boolean" | "date";
+};
+/** A lookup source parsed out of a parameter's `afRecordSource` XML. */
+export type ReportRecordSource = {
+    viewName: string;
+    /** The columns the record source selects, in order. */
+    columns: ReportRecordSourceColumn[];
+    whereClause: string | null;
+    filterString: string | null;
+    maxRecords: number | null;
+};
+/** A report parameter, ready to be rendered. */
+export type ReportParameter = {
+    name: string;
+    /** Label shown next to the editor. Falls back to the name. */
+    label: string;
+    /** Help text for the editor. */
+    description: string | null;
+    type: ReportParameterType;
+    editor: ReportParameterEditor;
+    /**
+     * The raw default. A value matching `^[a-z]stp_` names a stored procedure
+     * that produces the default; see `isProcedureDefault`.
+     */
+    defaultValue: string | null;
+    /** Fixed list of choices, one per line in `Items`. */
+    items: string[];
+    /** Lookup source, when the parameter is backed by a view. */
+    recordSource: ReportRecordSource | null;
+    /** The lookup column holding the value to send to the report. */
+    valueMember: string | null;
+    /** The lookup column to show. The first column that is not the value member. */
+    displayMember: string | null;
+    sortOrder: number;
+    /** Preferred size of the lookup popup, in pixels. */
+    lookupWidth: number | null;
+    lookupHeight: number | null;
+};
+/** A raw `sviw_WinClient_ReportsParameters` record. */
+export type ReportParameterRecord = {
+    Name?: string | null;
+    Label?: string | null;
+    Description?: string | null;
+    DataType?: string | null;
+    DefaultValue?: string | null;
+    Items?: string | null;
+    RecordSource?: string | null;
+    ValueMember?: string | null;
+    ValueListViewName?: string | null;
+    SortOrder?: number | null;
+    LookupWidth?: number | null;
+    LookupHeight?: number | null;
+};
+/** Output formats a report can be rendered to. */
+export type ReportFormat = "PDF" | "XLSX" | "XLS" | "CSV" | "HTML" | "RTF" | "MHT" | "TEXT" | "IMAGE";
+/** A report, as the launcher needs it. */
+export type Report = {
+    reportId: string;
+    /**
+     * The report's number, which is what users refer to a report by — it is
+     * printed in the footer of every report.
+     */
+    shortId: number | null;
+    title: string | null;
+    description: string | null;
+    /** The view the report reads, resolved from its record source. */
+    viewName: string | null;
+    /**
+     * The filter the report is designed with. Used unless the launcher is opened
+     * with an explicit filter.
+     */
+    initialFilter: string | null;
+    /** True when the report has a title band the user may override. */
+    hasTitle: boolean;
+    /** True when the report has a header band the user may fill in. */
+    hasHeader: boolean;
+    /** The formats the report may be rendered to, in the order they are offered. */
+    formats: ReportFormat[];
+    timeout: number | null;
+};
+/**
+ * A raw `sviw_WinClient_MyReports` record, optionally merged with the
+ * `HasTitle` / `HasHeader` columns from `sviw_WinClient_ReportsWeb`.
+ */
+export type ReportRecord = {
+    ReportID?: string | null;
+    ShortID?: number | null;
+    Title?: string | null;
+    Description?: string | null;
+    RecordSource?: string | null;
+    FormatPDF?: boolean | number | null;
+    FormatCSV?: boolean | number | null;
+    FormatHTML?: boolean | number | null;
+    FormatRTF?: boolean | number | null;
+    FormatMHT?: boolean | number | null;
+    FormatTEXT?: boolean | number | null;
+    FormatIMAGE?: boolean | number | null;
+    HasTitle?: boolean | number | null;
+    HasHeader?: boolean | number | null;
+    Timeout?: number | null;
+};
+/** A parameter value, as sent to the render endpoint. */
+export type ReportParameterValue = string | number | boolean | null;
+/** Parameter values by parameter name. */
+export type ReportParameterValues = Record<string, ReportParameterValue>;

package/es/report/types.js

@@ -0,0 +1,8 @@
+/**
+ * Report metadata — the shape of a report and its parameters, as the Windows
+ * report launcher understands them.
+ *
+ * The loading lives in `useReport` in `@olenbetong/appframe-react`; everything
+ * here is pure.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olenbetong/appframe-core",
-  "version": "2.11.9",
+  "version": "2.12.0",
   "description": "Javascript libraries to utilize the Appframe framework",
   "type": "module",
   "sideEffects": [
@@ -37,20 +37,20 @@
     ]
   },
   "dependencies": {
-    "@happy-dom/global-registrator": "^15.7.3",
     "mitt": "^3.0.1"
   },
   "devDependencies": {
-    "@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";