react-semaphor 0.1.540 → 0.1.542

package/dist/types/shared/dashboard-authoring/card-export-request.d.ts

@@ -0,0 +1,173 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DashboardCardQueryRequestPayloadBase } from '../../lib/query-context/build-dashboard-card-query-contract.js';
+import { ControlBinding, ControlDefinition, TCard } from '../../lib/types/common-types.js';
+import { DataSource, TableTotalsRequest, CardConfig, QueryColumnKeyMap } from '../../lib/types/explorer-types.js';
+import { ResolvedPrimaryDateField } from '../../lib/types/semantic-runtime-types.js';
+import { ComparisonMetadataMap } from '../../lib/types/query-types.js';
+import { ComparisonPresentationSpec, GlobalDateComparisonContext, SemaphorResultColumn } from '../analytics-protocol/index.js';
+import { ReportRuntimeContext } from '../report-runtime-context/index.js';
+import { CanonicalPivotResultTransport, CsvDelimiter, CsvEncoding, ExportFileFormat, PresentationExecutionSnapshot } from '../format-utils/index.js';
+import { TemporalResultOwner } from './temporal-result-owner.js';
+import { ExportViewerTable } from '../../lib/dashboard-viewer/export-table-view.js';
+/** Formatting configuration passed to the export job */
+export interface ExportFormattingConfig {
+    useFormattedValues: boolean;
+    timezone: string;
+    browserTimezone?: string;
+    isSqlCard?: boolean;
+    delimiter: CsvDelimiter;
+    /** Resolved by the caller: the person's or attachment's choice, else the dashboard's setting. */
+    csvEncoding: CsvEncoding;
+    includeHeaders: boolean;
+    columnSettings?: Record<string, unknown>;
+    visibleColumns?: string[];
+    columnLabels?: Record<string, string>;
+    tableTotalsLabelColumnKey?: string;
+    presentationExecutionSnapshot?: PresentationExecutionSnapshot;
+    comparisonPresentation?: ComparisonPresentationSpec;
+}
+export type AuthoritativeExportFormattingConfig = ExportFormattingConfig & {
+    comparisonPresentation: ComparisonPresentationSpec;
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
+};
+/** Request to create a new export job */
+export interface CreateExportRequest {
+    type: 'visual' | 'card';
+    dashboardId: string;
+    visualId?: string;
+    cardId: string;
+    title?: string;
+    connection_id: string;
+    cardType: string;
+    sql: string;
+    python: string;
+    resultOwner: TemporalResultOwner;
+    cardConfig: CardConfig;
+    cardDataSource: DataSource;
+    active_filters: TFilterValue[];
+    controlValues?: Record<string, unknown>;
+    controlDefinitions?: ControlDefinition[];
+    cardControlDefinitions?: ControlDefinition[];
+    controlBindings?: ControlBinding[];
+    resolvedPrimaryDateField?: ResolvedPrimaryDateField;
+    globalDateComparison?: GlobalDateComparisonContext;
+    tableTotalsRequest?: TableTotalsRequest;
+    totalRows: number;
+    /** The file the job writes: CSV, or Excel for Table and Detail Table. */
+    format: ExportFileFormat;
+    formatOptions: AuthoritativeExportFormattingConfig;
+}
+/** The facts a result gives an export: a viewer's loaded result, or the server's sizing query. */
+export type CardResultFacts = {
+    totalRows: number;
+    resultColumns: readonly SemaphorResultColumn[];
+    columnKeyMap?: QueryColumnKeyMap;
+    comparisonMetadata?: ComparisonMetadataMap;
+};
+/** File options a viewer or an attachment chose. */
+export type CardExportFileOptions = {
+    format: ExportFileFormat;
+    /** False writes stored values. */
+    useFormattedValues: boolean;
+    includeHeaders: boolean;
+    /** CSV only; ignored for Excel. */
+    delimiter: CsvDelimiter;
+    /** CSV only; ignored for Excel. */
+    csvEncoding: CsvEncoding;
+    /** The viewer's table settings at the click; absent for a scheduled attachment (the author's view). */
+    viewerTable?: ExportViewerTable;
+};
+/**
+ * The `formatOptions` a table export request carries, from the result: the
+ * visible columns, order and labels of the one table view resolver, and the
+ * card's saved column settings. The background export and the browser file
+ * both start here. Null when the columns cannot be resolved.
+ */
+export declare function buildTableExportFormatOptions(input: {
+    card: TCard;
+    effectiveCardConfig?: CardConfig;
+    rows: readonly Record<string, unknown>[];
+    /**
+     * The output keys when no row is loaded: a scheduled export's sizing page
+     * that a cleanup step emptied names its columns from the result's columns.
+     */
+    resultKeys?: readonly string[];
+    result: Pick<CardResultFacts, 'resultColumns' | 'columnKeyMap' | 'comparisonMetadata'>;
+    reportContext: ReportRuntimeContext;
+    file: CardExportFileOptions;
+}): {
+    view: import('../../lib/dashboard-viewer/table-view.js').TableView;
+    formatOptions: {
+        useFormattedValues: boolean;
+        timezone: string;
+        delimiter: "," | ";" | "\t";
+        csvEncoding: "utf-8-bom" | "utf-8";
+        includeHeaders: boolean;
+        columnSettings: Record<string, unknown> | undefined;
+        visibleColumns: string[];
+        columnLabels: {
+            [k: string]: string;
+        };
+    };
+} | null;
+export { buildCardServerRequest as buildCardExportQueryContext, type CardServerRequest as CardExportQueryContext, } from '../../lib/query-context/card-server-request.js';
+type CardExportPresentationParams = {
+    card: TCard;
+    dashboardId: string;
+    reportContext: ReportRuntimeContext;
+    totalRows: number;
+    formatOptions: ExportFormattingConfig;
+    comparisonMetadata?: ComparisonMetadataMap;
+    requestPayloadBase: DashboardCardQueryRequestPayloadBase;
+    resultColumns?: SemaphorResultColumn[];
+    columnKeyMap?: QueryColumnKeyMap;
+    canonicalPivotResult?: CanonicalPivotResultTransport;
+    effectiveCardConfig?: CardConfig;
+};
+/**
+ * The presentation half of a card export request: `formatOptions` with the
+ * captured presentation snapshot, the totals label column and the totals
+ * request. A browser download formats with exactly this; a background export
+ * sends it with the card's query context (`buildCardExportRequest`).
+ */
+export declare function buildCardExportFormatOptions(params: CardExportPresentationParams): {
+    formatOptions: CreateExportRequest['formatOptions'];
+    tableTotalsRequest?: CreateExportRequest['tableTotalsRequest'];
+};
+/** The request from formatOptions already built: the dialog's request, and tests of the presentation half. */
+export declare function buildCardExportRequestFromOptions(params: CardExportPresentationParams & {
+    title: string;
+    format: ExportFileFormat;
+}): CreateExportRequest;
+/** Why a card has no export request. */
+export type CardExportRequestRefusal = 
+/** Comparison columns without their metadata (SPEC §3.0 case 28). */
+'comparison_metadata_missing'
+/** Only Table and Detail Table export through this request. */
+ | 'not_a_table'
+/** No visible column could be resolved from the result. */
+ | 'columns_unresolved';
+/**
+ * A Table or Detail Table background export request (SPEC §3.5): the card's
+ * query, the columns and presentation its result gives, and the file the
+ * viewer or attachment chose. The dialog's "Export full dataset" and a
+ * scheduled attachment the server starts call exactly this (XL-SI-14).
+ */
+export declare function buildCardExportRequest(input: {
+    card: TCard;
+    dashboardId: string;
+    title: string;
+    query: DashboardCardQueryRequestPayloadBase;
+    effectiveCardConfig?: CardConfig;
+    result: CardResultFacts;
+    /** The rows the columns are read from: the viewer's loaded rows, or the server's sizing page. */
+    rows: readonly Record<string, unknown>[];
+    reportContext: ReportRuntimeContext;
+    file: CardExportFileOptions;
+}): {
+    status: 'ready';
+    request: CreateExportRequest;
+} | {
+    status: 'refused';
+    reason: CardExportRequestRefusal;
+};

package/dist/types/shared/dashboard-authoring/card-query-request.d.ts

@@ -70,7 +70,27 @@ export type CardQueryRequestExtras = {
         pageSize: number;
     };
     tableTotalsRequest?: TableTotalsRequest;
+    /** Strict table print only; never sent with `pagination`. */
+    sourceRowProbe?: CardQuerySourceRowProbe;
 };
+/**
+ * Ask acquisition whether the source had more rows than `limit`, counted
+ * before any Python step or pivot (report attachment delivery RA-D15, RA-D17).
+ */
+export type CardQuerySourceRowProbe = {
+    limit: number;
+};
+/**
+ * What acquisition reports for a `CardQuerySourceRowProbe`: `true` when the
+ * source had more rows than the limit, `false` when not. Absent when nobody
+ * asked or the answer is unknown, and never read as `false`.
+ */
+export type CardQuerySourceRowEvidence = {
+    sourceRowOverflow?: boolean;
+};
+type DecidedExtrasField = 'pagination' | 'tableTotalsRequest' | 'sourceRowProbe';
+/** Every extras field is parsed here and built by `resolveCardRequestExtras`. */
+export type CardQueryRequestExtrasDecided = AssertNever<Exclude<keyof CardQueryRequestExtras, DecidedExtrasField>>;
 /** The context fields any query body may carry, checked the same way for every reader. */
 export type CardQueryRequestContext = Pick<CardQueryRequest, 'calendarContext' | 'resolvedPrimaryDateField' | 'globalDateComparison'>;
 /**

package/dist/types/shared/dashboard-authoring/index.d.ts

@@ -28,6 +28,7 @@ export * from './control-value-resolution.js';
 export * from './control-execution-contract.js';
 export * from './resolved-primary-date-field-validation.js';
 export * from './card-query-request.js';
+export * from './card-export-request.js';
 export * from './calculated-field-identity.js';
 export * from './calculated-field-placement.js';
 export * from './matrix-control-resolution.js';

package/dist/types/shared/dashboard-authoring/matrix-delivery.d.ts

@@ -7,7 +7,8 @@ export declare function captureMatrixExport(input: {
     config: MatrixConfig;
     session?: MatrixViewState;
     content: MatrixExportContent;
-    format: 'csv' | 'pdf';
+    /** A data file (CSV or Excel) or a PDF; Flat content is a data file only. */
+    format: 'csv' | 'xlsx' | 'pdf';
     purpose: 'manual' | 'schedule';
 }): {
     mode: "layout";
@@ -585,7 +586,7 @@ export declare function captureMatrixExport(input: {
             }[];
         } | undefined;
     };
-    format: "csv";
+    format: "csv" | "xlsx";
     spec: {
         source: {
             kind: "semantic";
@@ -1371,7 +1372,7 @@ export declare function buildMatrixDeliveryEnvelope<TSource extends {
                     }[];
                 } | undefined;
             };
-            format: "csv";
+            format: "csv" | "xlsx";
             spec: {
                 source: {
                     kind: "semantic";

package/dist/types/shared/format-utils/attachment-filter-line.d.ts

@@ -0,0 +1,14 @@
+import { FilterLineValue } from './filter-line.js';
+/**
+ * The filter values a scheduled attachment's filter line is made of, read
+ * from its saved settings: values with a name and a values list, each saved
+ * relative date read through the shared reader (a malformed one is dropped so
+ * the value keeps its fixed dates, as the dashboard's own replay does).
+ *
+ * One owner for the run's PDF header (semaphor-app `buildRunFilterLine`) and
+ * the schedule dialog. It ignores `includeFilters`: that switch only hides the
+ * printed line, and the filters still apply to the data.
+ */
+export declare function readAttachmentFilterLineValues(settings: {
+    filterValues?: readonly unknown[];
+} | undefined): FilterLineValue[];

package/dist/types/shared/format-utils/exporters/export-cells.d.ts

@@ -0,0 +1,90 @@
+import { ExactNumericValue } from '../../analytics-protocol/scalar-value.js';
+import { MeasureCanonicalFormat } from '../types/format-types.js';
+export type ExportDataType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+/** What an export path knows about one column. Input to resolveXlsxColumn. */
+export type XlsxColumnInput = {
+    key: string;
+    /** The column's header label. */
+    label: string;
+    /** "Use formatted values". False means stored values. */
+    formattedValues: boolean;
+    /** Authoritative: from the result's `resultColumns` (SemaphorResultColumn.dataType); 'unknown' when absent. */
+    dataType: ExportDataType;
+    /** The presentation that made this column's display text, if any. */
+    presentation?: XlsxColumnPresentation;
+};
+export type XlsxColumnPresentation = 
+/** A numeric or duration measure format (from the presentation snapshot). */
+{
+    kind: 'measure';
+    format: MeasureCanonicalFormat;
+}
+/** A grouped date. `grain` from the bucket metadata; an unlisted grain is 'custom'. */
+ | {
+    kind: 'temporal_bucket';
+    grain: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'fiscal' | 'custom';
+}
+/** A raw date or datetime column, or a column with date settings. `dateOnly` when its values carry no time. */
+ | {
+    kind: 'datetime';
+    dateOnly: boolean;
+}
+/** Shown as text, including epoch numbers shown as dates. */
+ | {
+    kind: 'text';
+};
+/** A column as the Excel writer needs it. Built only by resolveXlsxColumn. */
+export type XlsxColumn = {
+    readonly key: string;
+    readonly label: string;
+    /** 'by_value' types each value by its JS type: stored-value exports and columns of unknown type. */
+    readonly cellType: 'number' | 'date' | 'boolean' | 'text' | 'by_value';
+    /** Excel number format code for number and date cells; undefined means General. */
+    readonly numberFormat?: string;
+};
+/** One exported cell. `text` is its display text. */
+export type ExportCell = {
+    kind: 'empty';
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'number';
+    text: string;
+    /** A JS number, an exact decimal, or plain decimal text. */
+    value: number | ExactNumericValue | string;
+} | {
+    kind: 'date';
+    text: string;
+    serial: number;
+} | {
+    kind: 'boolean';
+    text: string;
+    value: boolean;
+};
+/** A calendar date and time with no zone, as a temporal owner interpreted it for display. */
+export type ExportWallClock = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+};
+/** Pure. Never throws. The complete rule is the two tables in the Excel exports spec (§2.2). */
+export declare function resolveXlsxColumn(input: XlsxColumnInput): XlsxColumn;
+/** A plain decimal: optional '-', digits, optional '.digits', optional exponent. No grouping separators, no spaces. */
+export declare function parsePlainNumericString(value: string): string | undefined;
+/**
+ * The cell rule. Pure; never throws. `text` is the display text the path made.
+ * `wallClock` is supplied for date columns by the temporal owner that made
+ * `text`; this module never parses dates. First matching rule wins (spec §2.3).
+ */
+export declare function toExportCell(input: {
+    value: unknown;
+    text: string;
+    column: XlsxColumn;
+    wallClock?: ExportWallClock;
+}): ExportCell;
+/** The display text: '' for empty, otherwise `text`. */
+export declare function exportCellText(cell: ExportCell): string;

package/dist/types/shared/format-utils/exporters/export-file-format.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The export file format owner: what a CSV or Excel export file is called,
+ * typed, keyed and stored as. Every export producer (browser downloads, the
+ * app's export routes, the chunk and compaction Lambdas, Briefing
+ * attachments) reads these traits instead of writing its own extension,
+ * content type or storage-key suffix. See "Excel file standard" in the
+ * format-utils README.
+ * IMPORTANT: No React or browser-specific imports allowed
+ */
+/** Data file formats a Table, Detail Table or Matrix export can produce. */
+export declare const EXPORT_FILE_FORMATS: readonly ["csv", "xlsx"];
+export type ExportFileFormat = (typeof EXPORT_FILE_FORMATS)[number];
+/** Content type of every delivered Excel workbook. */
+export declare const XLSX_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+export type ExportFileTraits = {
+    format: ExportFileFormat;
+    /** File name extension without the dot: 'csv' | 'xlsx'. */
+    extension: 'csv' | 'xlsx';
+    /** CSV_CONTENT_TYPE | XLSX_CONTENT_TYPE. */
+    contentType: string;
+    /** Extension of one chunk or Matrix batch object before compaction: 'csv' | 'xml'. */
+    partExtension: 'csv' | 'xml';
+    /** Content type that object is stored with: 'text/csv' (as Matrix attempts have always been stored) | 'application/xml'. */
+    partContentType: 'text/csv' | 'application/xml';
+    /** File name of the compacted background artifact: 'export.csv.gz' | 'export.xlsx'. */
+    compactedFileName: 'export.csv.gz' | 'export.xlsx';
+    /** How the compacted artifact is stored: CSV gzipped, a workbook as is (already a zip). */
+    storedEncoding: 'gzip' | 'identity';
+    /** Stored form: Prisma ExportFormat value and the export job config's `format`. */
+    storedValue: 'CSV' | 'XLSX';
+    /** Customer-facing name: 'CSV' | 'Excel'. */
+    label: 'CSV' | 'Excel';
+};
+export declare function parseExportFileFormat(value: unknown): ExportFileFormat | undefined;
+export declare function exportFileTraits(format: ExportFileFormat): ExportFileTraits;
+export declare function exportFileFormatFromStored(value: 'CSV' | 'XLSX'): ExportFileFormat;
+/** For a client reading a server response: the format whose contentType matches (ignoring parameters), else undefined. */
+export declare function exportFileFormatFromContentType(contentType: string | null): ExportFileFormat | undefined;
+/** `${safeTitle}-${UTC timestamp}.${extension}`. The only export file name builder. */
+export declare function exportFileName(input: {
+    format: ExportFileFormat;
+    title: string | null | undefined;
+    at?: Date;
+}): string;

package/dist/types/shared/format-utils/exporters/index.d.ts

@@ -1,2 +1,8 @@
 export { CSV_ENCODINGS, DEFAULT_CSV_ENCODING, CSV_DELIMITERS, CSV_RECORD_SEPARATOR, CSV_CONTENT_TYPE, parseCsvEncoding, parseCsvDelimiter, resolveCsvEncoding, csvFilePreamble, toCsvCell, escapeCSVValue, protectCSVText, csvRecord, csvRecords, encodeCsvFile, } from './csv-utils.js';
 export type { CsvEncoding, CsvDelimiter, CsvCell } from './csv-utils.js';
+export { EXPORT_FILE_FORMATS, XLSX_CONTENT_TYPE, parseExportFileFormat, exportFileTraits, exportFileFormatFromStored, exportFileFormatFromContentType, exportFileName, } from './export-file-format.js';
+export type { ExportFileFormat, ExportFileTraits } from './export-file-format.js';
+export { resolveXlsxColumn, exportCellText } from './export-cells.js';
+export type { ExportDataType, XlsxColumnInput, XlsxColumnPresentation, XlsxColumn, ExportCell, ExportWallClock, } from './export-cells.js';
+export { XlsxLimitError, isXlsxLimitError, XLSX_LIMIT_FAILURE_REASONS, xlsxLimitFailureReason, assertXlsxColumnCount, defineXlsxSheet, serializeXlsxSheet, parseXlsxSheet, withXlsxSheetColumns, serializeXlsxColumns, parseXlsxColumns, xlsxColumnsFingerprint, encodeXlsxFile, encodeXlsxRows, streamXlsxFile, } from './xlsx-file.js';
+export type { XlsxSheet, XlsxRow, XlsxMerge, XlsxLimitFailureReason } from './xlsx-file.js';

package/dist/types/shared/format-utils/exporters/xlsx-file.d.ts

@@ -0,0 +1,90 @@
+import { ExportCell, XlsxColumn } from './export-cells.js';
+/** The only error the Excel modules throw on purpose. Its message is customer-facing and product-neutral. */
+export declare class XlsxLimitError extends Error {
+    /** `size` counts sheet XML bytes. */
+    readonly limit: 'rows' | 'columns' | 'size';
+    readonly actual: number;
+    readonly max: number;
+    constructor(limit: 'rows' | 'columns' | 'size', actual: number, max: number);
+}
+/**
+ * The export failure catalog reason for each Excel limit (SPEC §2.6). A worker
+ * that hits a limit inside a job reports this reason; the app's catalog holds
+ * the message. Nothing ever recovers a reason from message text.
+ */
+export declare const XLSX_LIMIT_FAILURE_REASONS: readonly ["excel_row_limit", "excel_column_limit", "excel_size_limit"];
+export type XlsxLimitFailureReason = (typeof XLSX_LIMIT_FAILURE_REASONS)[number];
+export declare function xlsxLimitFailureReason(error: XlsxLimitError): XlsxLimitFailureReason;
+/** Throws XlsxLimitError('columns') when a sheet would be wider than Excel allows: for callers that know the width before any rows exist (XL-D33). */
+export declare function assertXlsxColumnCount(count: number): void;
+/** Structural, so an error from another copy of this module still counts. */
+export declare function isXlsxLimitError(error: unknown): error is XlsxLimitError;
+export type XlsxMerge = {
+    row: number;
+    firstColumn: number;
+    lastColumn: number;
+};
+/** A validated sheet layout that every writer of one file shares. Built only by defineXlsxSheet. */
+export type XlsxSheet = {
+    readonly name: string;
+    readonly columns: readonly XlsxColumn[];
+    /** Header rows above the data, top first. Empty when headers are off. */
+    readonly headerRows: readonly (readonly string[])[];
+    /** Horizontal merges inside header rows (Matrix column bands). Zero-based. */
+    readonly merges: readonly XlsxMerge[];
+    /** Column widths in characters, one per column. */
+    readonly widths: readonly number[];
+};
+/**
+ * Validates and freezes a sheet. Throws XlsxLimitError('columns') above 16,384
+ * columns. `sampleRows` only tunes widths.
+ */
+export declare function defineXlsxSheet(input: {
+    title: string;
+    columns: readonly XlsxColumn[];
+    headerRows: readonly (readonly string[])[];
+    /** Explicit header merges. The caller derives them from identity (Matrix: member paths and roles); the writer only validates and writes them. */
+    merges?: readonly XlsxMerge[];
+    sampleRows?: readonly (readonly ExportCell[])[];
+}): XlsxSheet;
+/** JSON form, for workers that share one sheet (the first chunk or layout batch writes it; compaction reads it). */
+export declare function serializeXlsxSheet(sheet: XlsxSheet): string;
+/**
+ * The same sheet with settled columns, one per existing column. A background
+ * job's first chunk writes the sheet; a column its rows could not type takes
+ * the type the other chunks found (row fragments do not depend on it: styles
+ * go by column position).
+ */
+export declare function withXlsxSheetColumns(sheet: XlsxSheet, columns: readonly XlsxColumn[]): XlsxSheet;
+/** A column list as JSON and back, checked as a sheet's columns are. */
+export declare function serializeXlsxColumns(columns: readonly XlsxColumn[]): string;
+export declare function parseXlsxColumns(value: unknown): XlsxColumn[];
+export declare function parseXlsxSheet(json: string): XlsxSheet;
+/** Stable hash of a column list; equal for structurally equal columns. */
+export declare function xlsxColumnsFingerprint(columns: readonly XlsxColumn[]): string;
+export type XlsxRow = {
+    role: 'body' | 'total';
+    cells: readonly ExportCell[];
+};
+/** Joinable sheet XML for some rows (one chunk, one Matrix batch, or a totals row). Pure. */
+export declare function encodeXlsxRows(sheet: XlsxSheet, rows: Iterable<XlsxRow>): string;
+/** A whole workbook in memory: browser downloads and Matrix direct. */
+export declare function encodeXlsxFile(sheet: XlsxSheet, rows: Iterable<XlsxRow>): Uint8Array;
+/**
+ * The whole workbook as zip bytes, from row fragments made by encodeXlsxRows,
+ * in order. A totals row is just a last fragment. `rowCount` counts every
+ * row in the fragments (body and total); `fragmentBytes` is their UTF-8 size
+ * (the stored size of the chunk or batch objects). Backpressure follows the
+ * consumer: the next fragment is read only after the bytes before it were
+ * taken. Throws XlsxLimitError('rows') or ('size') here, before anything is
+ * written. Fragments that turn out larger than `fragmentBytes` fail with
+ * XlsxLimitError('size') before the sheet passes the limit, and any other
+ * mismatch fails with TypeError before the file is finished, so a wrong count
+ * never yields a complete file.
+ */
+export declare function streamXlsxFile(input: {
+    sheet: XlsxSheet;
+    fragments: AsyncIterable<string | Uint8Array>;
+    rowCount: number;
+    fragmentBytes: number;
+}): AsyncIterable<Uint8Array>;

package/dist/types/shared/format-utils/filter-line.d.ts

@@ -13,6 +13,13 @@ export type FilterLineValue = {
 };
 type FormatFilterLineOptions = {
     timezone?: string;
+    /**
+     * 'label': every relative window prints by its label ("Last 7 days"), for a
+     * reader that shows saved values rather than a run's resolved dates (the
+     * schedule dialog). Absent: quarter, year and latest-data windows print by
+     * name and every other window prints its dates, as a run's PDF header does.
+     */
+    relativeDates?: 'label';
 };
 type FormatFilterConditionOptions = FormatFilterLineOptions & {
     /** The filter's display name; defaults to its column name in title case. */

package/dist/types/shared/format-utils/formatters/date-formatter.d.ts

@@ -1,15 +1,4 @@
-/**
- * Date formatting utilities with timezone support
- * IMPORTANT: No React imports allowed in this file
- *
- * Uses date-fns and date-fns-tz for consistent behavior in browser and Node.js
- *
- * This module provides the canonical date formatting functions used by:
- * - data-table component
- * - pivot-table component
- * - aggregated-table component
- * - Lambda CSV export (chunk-processor)
- */
+import { ExportWallClock } from '../exporters/export-cells.js';
 /**
  * Resolve which timezone to use for formatting
  * Priority: column-specific > context timezone
@@ -52,6 +41,13 @@ export declare function parseWithSourceTimezone(dateString: string, sourceTimezo
  * formatDate('2024-01-15T10:30:00Z', 'MM/dd/yyyy HH:mm', 'America/Chicago') // '01/15/2024 04:30'
  */
 export declare const formatDate: (dateString: string | null | undefined, formatPattern: string | undefined, displayTimezone?: string, sourceTimezone?: string) => string;
+/**
+ * The calendar date and time `formatDate` shows for the same inputs, with no
+ * zone: the same source-zone interpretation and display-zone conversion.
+ * Undefined when `formatDate` would return the input unchanged (empty or not
+ * a date). Excel exports write it as a date serial (Excel exports plan XL-D35).
+ */
+export declare function dateWallClock(dateString: string | null | undefined, displayTimezone?: string, sourceTimezone?: string): ExportWallClock | undefined;
 /**
  * Format relative time using date-fns (e.g., "2 days ago")
  *

package/dist/types/shared/format-utils/formatters/index.d.ts

@@ -1,6 +1,6 @@
 export { formatNumber, formatCurrency, formatPercent, formatScientific, formatNumericCanonical, formatMeasureCanonical, formatNumberWithColumnSettings, formatNumberCustom, } from './number-formatter.js';
 export { formatDuration, formatDurationCanonical } from './duration-formatter.js';
 export { formatMetricComparison, type FormattedMetricComparison, type FormattedMetricComparisonPart, type FormatMetricComparisonOptions, type MetricComparisonDisplayMode, } from './metric-comparison-formatter.js';
-export { formatDate, formatRelativeTime, resolveTimezone, getTimezoneAbbreviation, getTimezoneName, parseWithSourceTimezone, } from './date-formatter.js';
+export { formatDate, formatRelativeTime, dateWallClock, resolveTimezone, getTimezoneAbbreviation, getTimezoneName, parseWithSourceTimezone, } from './date-formatter.js';
 export { formatCellValue, formatRowForExport } from './cell-formatter.js';
 export type { CellAbsencePresentation } from './cell-formatter.js';

package/dist/types/shared/format-utils/formatters/matrix-formatter.d.ts

@@ -1,5 +1,6 @@
 import { MatrixPath, MatrixPresentation, MatrixWindow, SemaphorScalarValue, SemaphorValueFormat } from '../../analytics-protocol/index.js';
 import { ReportRuntimeContext } from '../../report-runtime-context/index.js';
+import { MeasureCanonicalFormat } from '../types/index.js';
 /** Null hierarchy members stay identifiable even when null cells render blank. */
 export declare function matrixMemberLabel(path: MatrixPath, levels?: ReadonlyMap<string, (value: SemaphorScalarValue) => string>): string;
 /**
@@ -39,6 +40,7 @@ export declare function prepareMatrixFormatting(descriptors: MatrixWindow['descr
         isNumeric: boolean;
         hasTextAffixes: boolean;
     }>;
+    measureFormats: Map<string, MeasureCanonicalFormat>;
     absence: {
         emptyText: string;
         nullText: string;

package/dist/types/shared/format-utils/index.d.ts

@@ -18,6 +18,7 @@ export * from './exporters/index.js';
 export * from './export-policy.js';
 export * from './matrix-continuation.js';
 export * from './matrix-export-presentation.js';
+export * from './matrix-export-xlsx.js';
 export * from './matrix-print.js';
 export { fromSemanticFormat } from './semantic-format.js';
 export type * from './table-structure.js';
@@ -30,7 +31,9 @@ export * from './temporal-bucket.js';
 export * from './raw-temporal.js';
 export * from './temporal-input-presentation.js';
 export * from './flat-table-export-totals.js';
+export * from './table-export/index.js';
 export * from './filter-line.js';
+export * from './attachment-filter-line.js';
 export { describeFilterValueInFullDetail, type FullDetailFilterValue, } from './filter-value-text.js';
 export { describeConditionInFullDetail, type FilterClauseText } from './filter-detail.js';
 export { formatCanonicalComparisonRange } from '../../lib/utils/comparison-window-caption.js';