@olenbetong/appframe-core 2.11.10 → 2.13.0

package/src/report/recordSource.ts

@@ -0,0 +1,123 @@
+/**
+ * Reading the `afRecordSource` XML the Windows designer stores on reports and
+ * on report parameters.
+ *
+ * A record source is a serialized .NET object, so the document is machine
+ * generated and its shape is fixed. Only a handful of elements matter here, and
+ * parsing them with a reader rather than `DOMParser` keeps this module usable
+ * outside a browser.
+ */
+
+import type { ReportRecordSource, ReportRecordSourceColumn } from "./types.js";
+
+const XML_ENTITIES: Record<string, string> = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: '"',
+	apos: "'",
+};
+
+/** Resolves the XML entities the .NET serializer emits. */
+export function decodeXml(value: string) {
+	return value.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (match, entity: string) => {
+		if (entity.startsWith("#x") || entity.startsWith("#X")) {
+			return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
+		}
+
+		if (entity.startsWith("#")) {
+			return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
+		}
+
+		return XML_ENTITIES[entity.toLowerCase()] ?? match;
+	});
+}
+
+/** Escapes a value for use as XML text or as an attribute value. */
+export function encodeXml(value: string) {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+/**
+ * The text content of the first `<name>` element, or `null` when the element is
+ * missing or self-closing (`<FilterString />`, which the serializer writes for
+ * an empty value).
+ */
+export function readElement(xml: string, name: string): string | null {
+	let match = new RegExp(`<${name}(?:\\s[^>]*)?>([\\s\\S]*?)</${name}>`).exec(xml);
+
+	if (!match) return null;
+
+	let value = decodeXml(match[1]).trim();
+
+	return value === "" ? null : value;
+}
+
+/** The text content of every `<name>` element, in document order. */
+export function readElements(xml: string, name: string): string[] {
+	let matches = xml.matchAll(new RegExp(`<${name}(?:\\s[^>]*)?>([\\s\\S]*?)</${name}>`, "g"));
+
+	return [...matches].map((match) => decodeXml(match[1]).trim());
+}
+
+/**
+ * The CLR types the designer writes on a select column. Anything else — and a
+ * column with no `DataType` at all, which is what it writes for strings — is
+ * treated as text.
+ */
+const COLUMN_TYPES: Record<string, ReportRecordSourceColumn["type"]> = {
+	Byte: "number",
+	Decimal: "number",
+	Double: "number",
+	Int16: "number",
+	Int32: "number",
+	Int64: "number",
+	Single: "number",
+	Boolean: "boolean",
+	DateTime: "date",
+};
+
+/** The columns of a `<SelectColumns>` block, in document order. */
+function readSelectColumns(xml: string): ReportRecordSourceColumn[] {
+	let block = /<SelectColumns>([\s\S]*?)<\/SelectColumns>/.exec(xml)?.[1] ?? "";
+	let columns: ReportRecordSourceColumn[] = [];
+
+	for (let match of block.matchAll(/<afSelectColumn>([\s\S]*?)<\/afSelectColumn>/g)) {
+		let name = readElement(match[1], "Name");
+		if (!name) continue;
+
+		columns.push({ name, type: COLUMN_TYPES[readElement(match[1], "DataType") ?? ""] ?? "string" });
+	}
+
+	return columns;
+}
+
+/**
+ * Reads the parts of an `afRecordSource` a web client can act on: the view, the
+ * selected columns and the design-time filter.
+ *
+ * Returns `null` for anything that is not a record source, so a missing or
+ * empty `RecordSource` column simply means "no lookup".
+ */
+export function parseRecordSource(xml: string | null | undefined): ReportRecordSource | null {
+	if (!xml || !xml.includes("<afRecordSource")) return null;
+
+	let viewName = readElement(xml, "ViewName");
+	if (!viewName) return null;
+
+	let maxRecords = readElement(xml, "MaxRecords");
+
+	return {
+		viewName,
+		columns: readSelectColumns(xml),
+		whereClause: readElement(xml, "WhereClause"),
+		filterString: readElement(xml, "FilterString"),
+		// The designer writes 0 for "no limit"; the web data API spells that -1.
+		maxRecords: maxRecords === null || maxRecords === "0" ? null : Number(maxRecords),
+	};
+}

package/src/report/render.test.ts

@@ -0,0 +1,230 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { fetchParameterDefault, resolveParameterDefaults } from "./parameterDefaults.js";
+import {
+	getReportExtension,
+	getReportFileName,
+	getReportRequest,
+	printReport,
+	type ReportRenderOptions,
+	renderReport,
+} from "./render.js";
+import type { ReportParameter } from "./types.js";
+
+function options(overrides: Partial<ReportRenderOptions> = {}): ReportRenderOptions {
+	return { format: "PDF", reportId: "arpt_Test_Report", timezone: 2, ...overrides };
+}
+
+function parameter(overrides: Partial<ReportParameter> & Pick<ReportParameter, "name">): ReportParameter {
+	return {
+		label: overrides.name,
+		description: null,
+		type: "String",
+		editor: "text",
+		defaultValue: null,
+		items: [],
+		recordSource: null,
+		valueMember: null,
+		displayMember: null,
+		sortOrder: 0,
+		lookupWidth: null,
+		lookupHeight: null,
+		...overrides,
+	};
+}
+
+afterEach(() => {
+	vi.unstubAllGlobals();
+});
+
+// A `Request` needs an absolute URL, which the route paths are resolved into
+// against the document. There is no document in the node test environment.
+beforeEach(() => {
+	vi.stubGlobal("location", { href: "https://stage.example.com/report" });
+});
+
+describe("getReportExtension", () => {
+	it("uses the extensions the route accepts, not the format names", () => {
+		expect(getReportExtension("TEXT")).toBe("txt");
+		expect(getReportExtension("IMAGE")).toBe("xbm");
+		expect(getReportExtension("XLSX")).toBe("xlsx");
+	});
+});
+
+describe("getReportFileName", () => {
+	it("defaults to the report id", () => {
+		expect(getReportFileName(options())).toBe("arpt_Test_Report.pdf");
+	});
+
+	it("replaces characters that would change the route path", () => {
+		expect(getReportFileName(options({ fileName: "Ordre 12/34?a.b" }))).toBe("Ordre 12-34-a-b.pdf");
+	});
+
+	it("falls back to the report id when nothing usable is left", () => {
+		expect(getReportFileName(options({ fileName: "..." }))).toBe("arpt_Test_Report.pdf");
+	});
+});
+
+describe("getReportRequest", () => {
+	it("is a GET with the filter in the query when there is nothing to post", () => {
+		let request = getReportRequest(options({ filter: "[ID] = 1" }));
+
+		expect(request.method).toBe("GET");
+		expect(request.url).toContain("/api/report/arpt_Test_Report/arpt_Test_Report.pdf");
+		expect(new URL(request.url, "http://x").searchParams.get("Filter")).toBe("[ID] = 1");
+	});
+
+	it("posts parameters as name/value entries, dropping empty ones", async () => {
+		let request = getReportRequest(options({ filter: "[ID] = 1", parameters: { A: 1, B: "", C: null, D: true } }));
+
+		expect(request.method).toBe("POST");
+		await expect(request.json()).resolves.toEqual({
+			filter: "[ID] = 1",
+			parameters: [
+				{ name: "A", value: 1 },
+				{ name: "D", value: "true" },
+			],
+		});
+	});
+
+	it("always sends a filter alongside parameters, because the route reads it unguarded", async () => {
+		let request = getReportRequest(options({ parameters: { A: 1 } }));
+
+		await expect(request.json()).resolves.toMatchObject({ filter: "" });
+	});
+
+	it("sends the header and maps hideFilterString onto the route's misnamed key", async () => {
+		let request = getReportRequest(options({ headerText: "Q1", hideFilterString: true }));
+
+		await expect(request.json()).resolves.toMatchObject({
+			optionalheader: "Q1",
+			showfiltercriteria: "true",
+		});
+	});
+
+	it("passes the domain and timezone in the query", () => {
+		let params = new URL(getReportRequest(options({ domain: "OB" })).url, "http://x").searchParams;
+
+		expect(params.get("Domain")).toBe("OB");
+		expect(params.get("timezone")).toBe("2");
+	});
+});
+
+describe("renderReport", () => {
+	it("turns the route's JSON error body into an error", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(
+				new Response(JSON.stringify({ error: "No permissions" }), {
+					headers: { "Content-Type": "application/json" },
+				}),
+			),
+		);
+
+		await expect(renderReport(options())).rejects.toThrow("No permissions");
+	});
+
+	it("resolves with the rendered file", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(new Response("%PDF-", { headers: { "Content-Type": "application/pdf" } })),
+		);
+
+		await expect(renderReport(options())).resolves.toBeInstanceOf(Blob);
+	});
+});
+
+describe("printReport", () => {
+	it("opens the report when there is no document to print it in", async () => {
+		let openMock = vi.fn().mockReturnValue({});
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(new Response("%PDF-", { headers: { "Content-Type": "application/pdf" } })),
+		);
+		vi.stubGlobal("open", openMock);
+
+		await printReport(options());
+
+		expect(openMock).toHaveBeenCalledWith(expect.stringContaining("blob:"), "_blank", "noopener");
+	});
+});
+
+describe("fetchParameterDefault", () => {
+	it("ignores a literal default", async () => {
+		let fetchMock = vi.fn();
+		vi.stubGlobal("fetch", fetchMock);
+
+		await expect(fetchParameterDefault("r", parameter({ name: "P", defaultValue: "201701" }))).resolves.toBeNull();
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it("reads the first column of the first row of the result set", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(
+				new Response(JSON.stringify({ Table: [{ Period: 202601, Other: 1 }] }), {
+					headers: { "Content-Type": "application/json" },
+				}),
+			),
+		);
+
+		await expect(
+			fetchParameterDefault("r", parameter({ name: "P", defaultValue: "astp_Test_DefaultPeriod" })),
+		).resolves.toBe(202601);
+	});
+
+	it("handles a result set of arrays", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi
+				.fn()
+				.mockResolvedValue(
+					new Response(JSON.stringify([[202601]]), { headers: { "Content-Type": "application/json" } }),
+				),
+		);
+
+		await expect(
+			fetchParameterDefault("r", parameter({ name: "P", defaultValue: "astp_Test_DefaultPeriod" })),
+		).resolves.toBe(202601);
+	});
+});
+
+describe("resolveParameterDefaults", () => {
+	it("returns the literal defaults untouched when nothing is dynamic", async () => {
+		let fetchMock = vi.fn();
+		vi.stubGlobal("fetch", fetchMock);
+		let literal = { P: 1 };
+
+		await expect(resolveParameterDefaults("r", [parameter({ name: "P", defaultValue: "1" })], literal)).resolves.toBe(
+			literal,
+		);
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it("merges resolved values over the literal defaults", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(
+				new Response(JSON.stringify({ Table: [{ Value: 202601 }] }), {
+					headers: { "Content-Type": "application/json" },
+				}),
+			),
+		);
+
+		await expect(
+			resolveParameterDefaults(
+				"r",
+				[parameter({ name: "Period", defaultValue: "astp_Test_DefaultPeriod" }), parameter({ name: "Other" })],
+				{ Other: "x" },
+			),
+		).resolves.toEqual({ Other: "x", Period: 202601 });
+	});
+
+	it("leaves a parameter alone when its procedure fails", async () => {
+		vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("boom")));
+
+		await expect(
+			resolveParameterDefaults("r", [parameter({ name: "Period", defaultValue: "astp_Test_DefaultPeriod" })], {}),
+		).resolves.toEqual({});
+	});
+});

package/src/report/render.ts

@@ -0,0 +1,269 @@
+/**
+ * Rendering a report through the framework's report route.
+ *
+ * The route is a CMS code module owned by the Appframe framework
+ * (`WebsiteCMS.Reports`), registered on
+ * `api/report/{ReportID}/{FileName}.{Extension}`. Everything here builds
+ * requests for it — there is no report endpoint of our own.
+ */
+
+import { downloadRequest, type DownloadItem } from "../downloadRequest.js";
+import type { ReportFormat, ReportParameterValues } from "./types.js";
+
+/**
+ * The file extension each format is requested with. The route only accepts
+ * `(pdf|csv|xlsx?|html|xbm|mht|rtf|txt)`, which is why `TEXT` is `txt` and
+ * `IMAGE` is `xbm` rather than the format name.
+ */
+const REPORT_EXTENSIONS: Record<ReportFormat, string> = {
+	CSV: "csv",
+	HTML: "html",
+	IMAGE: "xbm",
+	MHT: "mht",
+	PDF: "pdf",
+	RTF: "rtf",
+	TEXT: "txt",
+	XLS: "xls",
+	XLSX: "xlsx",
+};
+
+/** The media type each format is served as, for previewing a rendered report. */
+const REPORT_MEDIA_TYPES: Record<ReportFormat, string> = {
+	CSV: "text/csv",
+	HTML: "text/html",
+	IMAGE: "image/x-xbitmap",
+	MHT: "message/rfc822",
+	PDF: "application/pdf",
+	RTF: "text/enriched",
+	TEXT: "text/plain",
+	XLS: "application/vnd.ms-excel",
+	XLSX: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+};
+
+export type ReportRenderOptions = {
+	reportId: string;
+	format: ReportFormat;
+	/** File name without an extension. Defaults to the report ID. */
+	fileName?: string;
+	/** The filter string the report is run with. */
+	filter?: string | null;
+	/** Parameter values by name. Only non-empty values are sent. */
+	parameters?: ReportParameterValues | null;
+	/** Text for the report's optional header band. */
+	headerText?: string | null;
+	/** Hides the filter string printed on the report. */
+	hideFilterString?: boolean;
+	/** Runs the report in another domain than the current one. */
+	domain?: string | null;
+	/** Timezone offset in hours or minutes. Defaults to the browser's. */
+	timezone?: number | null;
+	signal?: AbortSignal;
+};
+
+/** The extension a format is requested with. */
+export function getReportExtension(format: ReportFormat): string {
+	return REPORT_EXTENSIONS[format];
+}
+
+/** The media type a format is served as. */
+export function getReportMediaType(format: ReportFormat): string {
+	return REPORT_MEDIA_TYPES[format];
+}
+
+/**
+ * Characters that must not reach the file name, because it is a path segment of
+ * the route: separators, the extension delimiter, the query and fragment
+ * delimiters, and control characters.
+ */
+// oxlint-disable-next-line no-control-regex -- control characters are the point
+const UNSAFE_FILE_NAME_CHARACTERS = /[\\/:*?"<>|.#&+%\u0000-\u001f]/g;
+
+/**
+ * The name a rendered report is downloaded as, including its extension.
+ *
+ * The file name is part of the route rather than a query parameter, so anything
+ * that would change the path is replaced.
+ */
+export function getReportFileName(options: Pick<ReportRenderOptions, "reportId" | "format" | "fileName">): string {
+	let name = (options.fileName ?? options.reportId).trim();
+	let safe = name.replace(UNSAFE_FILE_NAME_CHARACTERS, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "").trim();
+
+	return `${safe === "" ? options.reportId : safe}.${getReportExtension(options.format)}`;
+}
+
+/**
+ * The route is always on the same origin, but a `Request` needs an absolute
+ * URL, so the path is resolved against the document when there is one.
+ */
+function toRequestUrl(path: string): string {
+	let base = globalThis.location?.href;
+
+	return base ? new URL(path, base).toString() : path;
+}
+
+/**
+ * The request that renders a report.
+ *
+ * A report without parameters is a plain `GET`, so it can be opened directly in
+ * a new tab. As soon as there are parameters or a header the options go in a
+ * JSON body, which the route only reads from a `POST`.
+ *
+ * `filter` is always sent alongside `parameters`: the route reads the filter out
+ * of the body *guarded by the presence of `parameters`*, and reads it with an
+ * indexer that throws when the key is missing.
+ */
+export function getReportRequest(options: ReportRenderOptions): Request {
+	let { domain, filter, headerText, hideFilterString, parameters, reportId, signal, timezone } = options;
+	let fileName = getReportFileName(options);
+	let url = `/api/report/${encodeURIComponent(reportId)}/${encodeURIComponent(fileName)}`;
+	let query = new URLSearchParams();
+	let entries = toParameterEntries(parameters);
+	let needsBody = entries.length > 0 || Boolean(headerText) || hideFilterString === true;
+
+	if (domain) query.set("Domain", domain);
+	query.set("timezone", String(timezone ?? -new Date().getTimezoneOffset() / 60));
+
+	if (!needsBody) {
+		if (filter) query.set("Filter", filter);
+
+		return new Request(toRequestUrl(`${url}?${query}`), { credentials: "same-origin", signal });
+	}
+
+	let body: Record<string, unknown> = {
+		filter: filter ?? "",
+		parameters: entries,
+	};
+
+	if (headerText) body.optionalheader = headerText;
+	// The route assigns `showfiltercriteria` straight to the report's
+	// `HideFilterString`, so despite its name it *hides* the filter string.
+	if (hideFilterString === true) body.showfiltercriteria = "true";
+
+	return new Request(toRequestUrl(`${url}?${query}`), {
+		body: JSON.stringify(body),
+		credentials: "same-origin",
+		headers: { "Content-Type": "application/json", "X-Requested-With": "XMLHttpRequest" },
+		method: "POST",
+		signal,
+	});
+}
+
+/**
+ * Renders a report and resolves with the rendered file.
+ *
+ * The route answers with a JSON body carrying an `error` when rendering fails,
+ * rather than with a failing status, so a JSON response is turned into an error
+ * here.
+ */
+export async function renderReport(options: ReportRenderOptions): Promise<Blob> {
+	let response = await fetch(getReportRequest(options));
+	let contentType = response.headers.get("content-type") ?? "";
+
+	if (contentType.includes("application/json")) {
+		let data = (await response.json()) as { error?: string };
+
+		throw new Error(data.error ?? "Failed to render report");
+	}
+
+	if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
+
+	return response.blob();
+}
+
+/** Renders a report and saves it, reporting progress as it downloads. */
+export function downloadReport(
+	options: ReportRenderOptions & { onProgress?: (progress: DownloadItem) => void },
+): Promise<void> {
+	return downloadRequest(getReportRequest(options), {
+		fileName: getReportFileName(options),
+		onProgress: options.onProgress,
+		signal: options.signal,
+	});
+}
+
+/**
+ * Renders a report and opens it in a new tab.
+ *
+ * The blob is rendered first rather than pointing a tab at the route, so a
+ * failure surfaces as an error here instead of as a tab showing JSON, and so
+ * reports with parameters — which have to be posted — can be previewed too.
+ */
+export async function openReport(options: ReportRenderOptions): Promise<void> {
+	let blob = await renderReport(options);
+	// The route serves some formats as types a browser downloads rather than
+	// displays; the format's own media type is what decides how it opens.
+	let url = URL.createObjectURL(blob.type ? blob : new Blob([blob], { type: getReportMediaType(options.format) }));
+	let opened = globalThis.open(url, "_blank", "noopener");
+
+	if (!opened) {
+		URL.revokeObjectURL(url);
+		throw new Error("The report could not be opened. Allow pop-ups for this site and try again.");
+	}
+
+	// Revoking immediately would cancel the load in some browsers, and never
+	// revoking keeps the whole rendered report in memory.
+	globalThis.setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+
+/**
+ * Renders a report and opens the browser's print dialog for it.
+ *
+ * The report is loaded into an offscreen iframe rather than a new tab, so the
+ * print dialog opens over the launcher and the user is not left with a stray
+ * tab afterwards. Browsers that will not print an embedded document fall back
+ * to opening it, which leaves the user one keystroke from printing.
+ */
+export async function printReport(options: ReportRenderOptions): Promise<void> {
+	let document_ = globalThis.document;
+	if (!document_?.body) return openReport(options);
+
+	let blob = await renderReport(options);
+	let url = URL.createObjectURL(blob.type ? blob : new Blob([blob], { type: getReportMediaType(options.format) }));
+	let frame = document_.createElement("iframe");
+	// Hidden with `visibility` rather than `display: none`: a frame that is not
+	// laid out has nothing to print in some browsers.
+	frame.setAttribute("aria-hidden", "true");
+	frame.style.cssText =
+		"position:fixed;inset-block-start:0;inset-inline-start:0;inline-size:1px;block-size:1px;border:0;visibility:hidden";
+
+	let cleanUp = () => {
+		frame.remove();
+		URL.revokeObjectURL(url);
+	};
+
+	try {
+		await new Promise<void>((resolve, reject) => {
+			frame.addEventListener("load", () => resolve(), { once: true });
+			frame.addEventListener("error", () => reject(new Error("The report could not be loaded for printing")), {
+				once: true,
+			});
+			frame.src = url;
+			document_.body.append(frame);
+		});
+
+		frame.contentWindow?.focus();
+		frame.contentWindow?.print();
+	} catch {
+		cleanUp();
+
+		return openReport(options);
+	}
+
+	// The print dialog is modal but not awaitable, and revoking the URL or
+	// removing the frame while it is open cancels the job.
+	globalThis.setTimeout(cleanUp, 60_000);
+}
+
+/**
+ * Parameters in the shape the route expects — `{ name, value }` objects.
+ *
+ * Empty values are dropped: the route skips them anyway, and a report falls back
+ * to its own default when a parameter is not sent.
+ */
+function toParameterEntries(parameters: ReportParameterValues | null | undefined) {
+	if (!parameters) return [];
+
+	return Object.entries(parameters)
+		.filter(([, value]) => value !== null && value !== undefined && value !== "")
+		.map(([name, value]) => ({ name, value: typeof value === "boolean" ? String(value) : value }));
+}