@olenbetong/appframe-core 2.11.10 → 2.13.0

package/es/report/render.js

@@ -0,0 +1,219 @@
+/**
+ * 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 } from "../downloadRequest.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 = {
+    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 = {
+    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",
+};
+/** The extension a format is requested with. */
+export function getReportExtension(format) {
+    return REPORT_EXTENSIONS[format];
+}
+/** The media type a format is served as. */
+export function getReportMediaType(format) {
+    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) {
+    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) {
+    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) {
+    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 = {
+        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) {
+    let response = await fetch(getReportRequest(options));
+    let contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        let data = (await response.json());
+        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) {
+    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) {
+    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) {
+    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((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) {
+    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 }));
+}

package/es/report/render.test.d.ts

@@ -0,0 +1 @@
+export {};

package/es/report/render.test.js

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { fetchParameterDefault, resolveParameterDefaults } from "./parameterDefaults.js";
+import { getReportExtension, getReportFileName, getReportRequest, printReport, renderReport, } from "./render.js";
+function options(overrides = {}) {
+    return { format: "PDF", reportId: "arpt_Test_Report", timezone: 2, ...overrides };
+}
+function parameter(overrides) {
+    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/es/report/report.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Mapping a `sviw_WinClient_MyReports` record onto the report model, including
+ * which output formats the report offers.
+ */
+import type { Report, ReportFormat, ReportRecord } from "./types.js";
+/**
+ * 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 declare function getReportFormats(record: ReportRecord): ReportFormat[];
+/** Maps a report record onto the model the launcher renders. */
+export declare function toReport(record: ReportRecord): Report;

package/es/report/report.js

@@ -0,0 +1,50 @@
+/**
+ * Mapping a `sviw_WinClient_MyReports` record onto the report model, including
+ * which output formats the report offers.
+ */
+import { parseRecordSource } from "./recordSource.js";
+function isSet(value) {
+    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) {
+    let formats = [];
+    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) {
+    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/es/report/report.test.d.ts

@@ -0,0 +1 @@
+export {};

package/es/report/report.test.js

@@ -0,0 +1,86 @@
+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/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 {};