@olenbetong/appframe-core 2.11.10 → 2.13.0

package/src/report/report.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+
+import { parseRecordSource } from "./recordSource.js";
+import { getReportFormats, toReport } from "./report.js";
+
+const recordSource = `<?xml version="1.0" encoding="utf-16"?>
+<afRecordSource>
+  <ViewName>aviw_Personnel_PersonsReportingToMe</ViewName>
+  <SelectColumns>
+    <afSelectColumn><Name>PersonID</Name></afSelectColumn>
+    <afSelectColumn><Name>Name</Name></afSelectColumn>
+  </SelectColumns>
+  <WhereClause />
+  <FilterString>[Level] = 1</FilterString>
+  <MaxRecords>0</MaxRecords>
+</afRecordSource>`;
+
+describe("parseRecordSource", () => {
+	it("reads the view, columns and design-time filter", () => {
+		expect(parseRecordSource(recordSource)).toEqual({
+			viewName: "aviw_Personnel_PersonsReportingToMe",
+			columns: [
+				{ name: "PersonID", type: "string" },
+				{ name: "Name", type: "string" },
+			],
+			whereClause: null,
+			filterString: "[Level] = 1",
+			maxRecords: null,
+		});
+	});
+
+	it("maps the CLR type of a column onto a field type", () => {
+		let xml = recordSource.replace(
+			"<afSelectColumn><Name>Name</Name></afSelectColumn>",
+			"<afSelectColumn><Name>Level</Name><DataType>Int32</DataType></afSelectColumn>",
+		);
+
+		expect(parseRecordSource(xml)?.columns).toEqual([
+			{ name: "PersonID", type: "string" },
+			{ name: "Level", type: "number" },
+		]);
+	});
+
+	it("decodes entities", () => {
+		let xml = recordSource.replace("[Level] = 1", "[Name] Like &apos;%a &amp; b%&apos;");
+
+		expect(parseRecordSource(xml)?.filterString).toBe("[Name] Like '%a & b%'");
+	});
+
+	it("returns nothing for anything that is not a record source", () => {
+		expect(parseRecordSource(null)).toBeNull();
+		expect(parseRecordSource("")).toBeNull();
+		expect(parseRecordSource("<afRecordSource></afRecordSource>")).toBeNull();
+	});
+});
+
+describe("getReportFormats", () => {
+	it("offers the spreadsheet formats from the CSV flag", () => {
+		expect(getReportFormats({ FormatPDF: true, FormatCSV: true })).toEqual(["PDF", "XLSX", "XLS", "CSV"]);
+	});
+
+	it("accepts bits as numbers", () => {
+		expect(getReportFormats({ FormatPDF: 1, FormatHTML: 0 })).toEqual(["PDF"]);
+	});
+
+	it("offers nothing for a report with no formats", () => {
+		expect(getReportFormats({})).toEqual([]);
+	});
+});
+
+describe("toReport", () => {
+	it("resolves the view and the initial filter from the record source", () => {
+		let report = toReport({
+			ReportID: "arpt_Personnel_Persons",
+			ShortID: 1234,
+			Title: "  Persons  ",
+			RecordSource: recordSource,
+			FormatPDF: true,
+			HasTitle: 1,
+			HasHeader: 0,
+		});
+
+		expect(report).toEqual({
+			reportId: "arpt_Personnel_Persons",
+			shortId: 1234,
+			title: "Persons",
+			description: null,
+			viewName: "aviw_Personnel_PersonsReportingToMe",
+			initialFilter: "[Level] = 1",
+			hasTitle: true,
+			hasHeader: false,
+			formats: ["PDF"],
+			timeout: null,
+		});
+	});
+
+	it("survives a report without a record source", () => {
+		let report = toReport({ ReportID: "arpt_Test" });
+
+		expect(report.viewName).toBeNull();
+		expect(report.initialFilter).toBeNull();
+		expect(report.shortId).toBeNull();
+	});
+});

package/src/report/report.ts

@@ -0,0 +1,51 @@
+/**
+ * Mapping a `sviw_WinClient_MyReports` record onto the report model, including
+ * which output formats the report offers.
+ */
+
+import { parseRecordSource } from "./recordSource.js";
+import type { Report, ReportFormat, ReportRecord } from "./types.js";
+
+function isSet(value: boolean | number | null | undefined) {
+	return value === true || value === 1;
+}
+
+/**
+ * The formats a report may be rendered to, in the order the launcher offers
+ * them.
+ *
+ * `FormatCSV` covers the whole spreadsheet family: the Windows launcher enables
+ * "save as XLS" and "save as XLSX" from the same flag, because they all come out
+ * of the same DevExpress export.
+ */
+export function getReportFormats(record: ReportRecord): ReportFormat[] {
+	let formats: ReportFormat[] = [];
+
+	if (isSet(record.FormatPDF)) formats.push("PDF");
+	if (isSet(record.FormatCSV)) formats.push("XLSX", "XLS", "CSV");
+	if (isSet(record.FormatHTML)) formats.push("HTML");
+	if (isSet(record.FormatRTF)) formats.push("RTF");
+	if (isSet(record.FormatMHT)) formats.push("MHT");
+	if (isSet(record.FormatTEXT)) formats.push("TEXT");
+	if (isSet(record.FormatIMAGE)) formats.push("IMAGE");
+
+	return formats;
+}
+
+/** Maps a report record onto the model the launcher renders. */
+export function toReport(record: ReportRecord): Report {
+	let recordSource = parseRecordSource(record.RecordSource);
+
+	return {
+		reportId: record.ReportID ?? "",
+		shortId: record.ShortID ?? null,
+		title: record.Title?.trim() || null,
+		description: record.Description?.trim() || null,
+		viewName: recordSource?.viewName ?? null,
+		initialFilter: recordSource?.filterString ?? null,
+		hasTitle: isSet(record.HasTitle),
+		hasHeader: isSet(record.HasHeader),
+		formats: getReportFormats(record),
+		timeout: record.Timeout ?? null,
+	};
+}

package/src/report/types.ts

@@ -0,0 +1,135 @@
+/**
+ * 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>;