react-semaphor 0.1.540 → 0.1.542

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

@@ -1,6 +1,12 @@
 import { z } from 'zod';
 /** Transport budget, independent of total export bytes and analytical tile budgets. */
 export declare const MATRIX_EXPORT_TRANSFER_BYTES: number;
+/**
+ * Largest decoded Excel data part of one batch. Excel rows travel gzipped
+ * (their markup is several times the CSV text), so the transfer budget bounds
+ * them compressed; this bounds what the worker decodes and stores.
+ */
+export declare const MATRIX_EXPORT_DECODED_PART_BYTES: number;
 export declare const matrixExportDeadlineSchema: z.ZodNumber;
 export declare function parseMatrixAttemptKey(jobId: string, key: string): {
     attemptId: string;
@@ -37,27 +43,27 @@ export declare const matrixBatchResponseSchema: z.ZodDiscriminatedUnion<"kind",
     objects: z.ZodArray<z.ZodEffects<z.ZodObject<{
         key: z.ZodString;
         content: z.ZodString;
-        contentType: z.ZodEnum<["text/csv", "application/json"]>;
+        contentType: z.ZodEnum<[string, ...string[]]>;
         encoding: z.ZodOptional<z.ZodLiteral<"gzip-base64">>;
     }, "strip", z.ZodTypeAny, {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }, {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }>, {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }, {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }>, "many">;
     deadlineAt: z.ZodNumber;
@@ -69,7 +75,7 @@ export declare const matrixBatchResponseSchema: z.ZodDiscriminatedUnion<"kind",
     objects: {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }[];
 }, {
@@ -80,7 +86,7 @@ export declare const matrixBatchResponseSchema: z.ZodDiscriminatedUnion<"kind",
     objects: {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }[];
 }>, z.ZodObject<{
@@ -110,7 +116,7 @@ export declare function parseMatrixBatchResponse(value: unknown, input: MatrixBa
     objects: {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }[];
 } | {
@@ -119,7 +125,7 @@ export declare function parseMatrixBatchResponse(value: unknown, input: MatrixBa
     done: boolean;
     deadlineAt: number;
 };
-export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
+export declare const matrixManifestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     acquisition: z.ZodLiteral<"continuation">;
     deadlineAt: z.ZodNumber;
     chunks: z.ZodArray<z.ZodObject<{
@@ -136,6 +142,10 @@ export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
     totalBytes: z.ZodNumber;
     fileKey: z.ZodOptional<z.ZodString>;
     fileSize: z.ZodOptional<z.ZodNumber>;
+    /** The file the job writes; absent means CSV (manifests from before Excel). */
+    format: z.ZodOptional<z.ZodEnum<["csv", "xlsx"]>>;
+    /** Excel only: the sheet layout the layout batch stored, which compaction wraps the rows in. */
+    sheetKey: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     acquisition: "continuation";
     deadlineAt: number;
@@ -145,8 +155,10 @@ export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
     }[];
     totalRows: number;
     totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
     fileKey?: string | undefined;
     fileSize?: number | undefined;
+    sheetKey?: string | undefined;
 }, {
     acquisition: "continuation";
     deadlineAt: number;
@@ -156,8 +168,10 @@ export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
     }[];
     totalRows: number;
     totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
     fileKey?: string | undefined;
     fileSize?: number | undefined;
+    sheetKey?: string | undefined;
 }>, {
     acquisition: "continuation";
     deadlineAt: number;
@@ -167,8 +181,10 @@ export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
     }[];
     totalRows: number;
     totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
     fileKey?: string | undefined;
     fileSize?: number | undefined;
+    sheetKey?: string | undefined;
 }, {
     acquisition: "continuation";
     deadlineAt: number;
@@ -178,8 +194,36 @@ export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
     }[];
     totalRows: number;
     totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
     fileKey?: string | undefined;
     fileSize?: number | undefined;
+    sheetKey?: string | undefined;
+}>, {
+    acquisition: "continuation";
+    deadlineAt: number;
+    chunks: {
+        chunkNumber: number;
+        dataKey: string;
+    }[];
+    totalRows: number;
+    totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
+    fileKey?: string | undefined;
+    fileSize?: number | undefined;
+    sheetKey?: string | undefined;
+}, {
+    acquisition: "continuation";
+    deadlineAt: number;
+    chunks: {
+        chunkNumber: number;
+        dataKey: string;
+    }[];
+    totalRows: number;
+    totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
+    fileKey?: string | undefined;
+    fileSize?: number | undefined;
+    sheetKey?: string | undefined;
 }>;
 export declare function parseMatrixManifest(value: unknown, jobId: string, deadlineAt: number): {
     acquisition: "continuation";
@@ -190,6 +234,8 @@ export declare function parseMatrixManifest(value: unknown, jobId: string, deadl
     }[];
     totalRows: number;
     totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
     fileKey?: string | undefined;
     fileSize?: number | undefined;
+    sheetKey?: string | undefined;
 };

package/dist/types/shared/format-utils/matrix-export-presentation.d.ts

@@ -18,6 +18,20 @@ export declare function prepareMatrixExportPresentation(layout: MatrixExportLayo
     headers: string[];
     headerBands: string[][];
     numericColumns: boolean[];
+    /** The card's prepared formats this presentation formats with (the Excel form reads its measure formats). */
+    formatting: {
+        levels: Map<string, (value: import('../analytics-protocol/index.js').SemaphorScalarValue) => string>;
+        measures: Map<string, (value: import('../analytics-protocol/index.js').SemaphorScalarValue) => string>;
+        measureSemantics: Map<string, {
+            isNumeric: boolean;
+            hasTextAffixes: boolean;
+        }>;
+        measureFormats: Map<string, import('./types/index.js').MeasureCanonicalFormat>;
+        absence: {
+            emptyText: string;
+            nullText: string;
+        };
+    };
     /** A row's cells; after `previous`, a tabular layout prints each label once. */
     row: (data: MatrixExportRow, previous?: MatrixExportRow) => string[];
     /**
@@ -45,6 +59,12 @@ export declare function matrixFlatCsvHeaders(layout: MatrixExportLayout): string
  * CSV. Prepare `formatting` once per batch with `prepareMatrixFormatting`.
  */
 export declare function matrixFlatCsvRow(data: MatrixExportRow, layout: MatrixExportLayout, formatting: MatrixFormatting): string[];
+/**
+ * One Flat row's display text, unguarded: what the Excel form writes and the
+ * CSV form protects. Level values as the screen and Layout label members
+ * (`(Blank)` for a null member); measures through the card's formatter.
+ */
+export declare function matrixFlatRowText(data: MatrixExportRow, layout: MatrixExportLayout, formatting: MatrixFormatting): string[];
 /** Bounded physical projection only; values and totals have already been acquired. */
 export declare function buildMatrixTableStructure(input: {
     layout: MatrixExportLayout;
@@ -647,7 +667,7 @@ export declare function buildMatrixPrintTable(input: {
             } | undefined;
         };
         mode: "flat";
-        format: "csv";
+        format: "csv" | "xlsx";
         spec: {
             source: {
                 kind: "semantic";

package/dist/types/shared/format-utils/matrix-export-xlsx.d.ts

@@ -0,0 +1,27 @@
+import { MatrixExportLayout, MatrixExportRequest, MatrixExportRow } from '../analytics-protocol/index.js';
+import { ReportRuntimeContext } from '../report-runtime-context/index.js';
+import { XlsxRow, XlsxSheet } from './exporters/xlsx-file.js';
+import { MatrixFormatting } from './formatters/matrix-formatter.js';
+/** Prepared once per batch, like the CSV presentation it reads. */
+export declare function prepareMatrixXlsxPresentation(layout: MatrixExportLayout, request: MatrixExportRequest, report: ReportRuntimeContext): {
+    /** Header bands as header rows (XL-D16), with merges from identity (XL-D34). */
+    xlsxSheet: (input: {
+        title: string;
+        includeHeaders: boolean;
+    }) => XlsxSheet;
+    /** Every row label repeated; subtotal and grand-total rows are 'total' (bold). */
+    xlsxRows: (rows: readonly MatrixExportRow[]) => XlsxRow[];
+};
+/**
+ * The Flat form, prepared once per batch like the layout form: its columns
+ * (and their number formats) are built once, never per row.
+ */
+export declare function prepareMatrixFlatXlsxPresentation(layout: MatrixExportLayout, formatting: MatrixFormatting): {
+    /** One header row of the layout's column labels. */
+    xlsxSheet: (input: {
+        title: string;
+        includeHeaders: boolean;
+    }) => XlsxSheet;
+    /** Flat rows with the card's formats (MX-D10) and typed measure cells. */
+    xlsxRows: (rows: readonly MatrixExportRow[]) => XlsxRow[];
+};

package/dist/types/shared/format-utils/pdf-export-policy.d.ts

@@ -12,6 +12,15 @@ export declare const FAST_PDF_POLICY: Readonly<{
     maxOutputBytes: 52428800;
 }>;
 export declare const PDF_SAFETY_LIMIT_EXCEEDED: "PDF_SAFETY_LIMIT_EXCEEDED";
+/**
+ * Card types a PDF prints as a table, across pages, in table mode. The one
+ * list every reader uses: the interactive download and export dialog, the
+ * fast path, the print views and scheduled attachments (report attachment
+ * delivery RA-D1).
+ */
+export declare const PDF_TABLE_CARD_TYPES: readonly ["table", "detailTable", "aggregateTable", "pivotTable"];
+export type PdfTableCardType = (typeof PDF_TABLE_CARD_TYPES)[number];
+export declare function isPdfTableCardType(cardType: unknown): cardType is PdfTableCardType;
 /** Exact UTF-8 bytes used by the structured POST body. */
 export declare function getUtf8ByteLength(value: string): number;
 export declare function isFastPdfRowCountEligible(rowCount: number): boolean;

package/dist/types/shared/format-utils/presentation-execution.d.ts

@@ -2,7 +2,7 @@ import { ResolvedRawTemporalFormat } from './raw-temporal.js';
 import { ReportRuntimeContext } from '../report-runtime-context/index.js';
 import { NumericPresentationTarget } from './numeric-presentation.js';
 import { ResolvedTemporalBucketFormat } from './temporal-bucket.js';
-import { DurationCanonicalFormat, MeasureCanonicalFormat, NumericCanonicalFormat } from './types/index.js';
+import { DateCanonicalFormat, DurationCanonicalFormat, MeasureCanonicalFormat, NumericCanonicalFormat } from './types/index.js';
 export type PresentationScope = {
     dashboardId: string;
     cardId?: string;
@@ -30,6 +30,22 @@ export type ResolvedDurationPresentationEntry = {
     target: NumericPresentationTarget;
     format: DurationCanonicalFormat;
 };
+/**
+ * A date presentation on a numeric (epoch milliseconds) column: a semantic
+ * date format the dashboard shows as a date (Excel exports plan XL-D27).
+ * Column targets only; `locale` is resolved at capture.
+ */
+export type ResolvedDatePresentationEntry = {
+    scope: PresentationScope;
+    target: {
+        kind: 'column';
+        columnKey: string;
+    };
+    format: ResolvedDateFormat;
+};
+export type ResolvedDateFormat = Pick<DateCanonicalFormat, 'type' | 'pattern' | 'timezone' | 'sourceTimezone'> & {
+    locale: string;
+};
 export type ResolvedTemporalBucketPresentationEntry = {
     scope: PresentationScope;
     target: TemporalBucketPresentationTarget;
@@ -44,7 +60,7 @@ export type ResolvedRawTemporalPresentationEntry = {
     target: RawTemporalPresentationTarget;
     format: ResolvedRawTemporalFormat;
 };
-export type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedDurationPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry;
+export type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedDurationPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry | ResolvedDatePresentationEntry;
 export type PresentationExecutionSnapshot = {
     version: 1;
     reportContext: ReportRuntimeContext;
@@ -82,6 +98,15 @@ export declare function findResolvedMeasureFormat(input: {
     scope: PresentationScope;
     target: NumericPresentationTarget;
 }): MeasureCanonicalFormat | undefined;
+/** The date presentation captured for an epoch column (XL-D27), if any. */
+export declare function findResolvedDateFormat(input: {
+    snapshot: PresentationExecutionSnapshot;
+    scope: PresentationScope;
+    target: {
+        kind: 'column';
+        columnKey: string;
+    };
+}): ResolvedDateFormat | undefined;
 export declare function findResolvedRawTemporalFormat(input: {
     snapshot: PresentationExecutionSnapshot;
     scope: PresentationScope;

package/dist/types/shared/format-utils/raw-temporal.d.ts

@@ -1,3 +1,4 @@
+import { ExportWallClock } from './exporters/export-cells.js';
 import { CalendarContext } from '../report-runtime-context/report-runtime-context.js';
 import { RawTemporalValueKind, RawTemporalValueMetadata } from '../analytics-protocol/contracts.js';
 import { parseRawTemporalValueMetadata, validateRawTemporalResultColumn } from '../analytics-protocol/raw-temporal-contract.js';
@@ -31,6 +32,13 @@ export type RawTemporalFormatResult = {
     ok: true;
     text: string;
     status: 'formatted' | 'empty';
+    /**
+     * The calendar date and time `text` shows, with no zone: the same
+     * interpretation (date-only, wall clock, instant, source zone) that made
+     * the text. Present when `status` is 'formatted'. Excel exports write it
+     * as a date serial (Excel exports plan XL-D35).
+     */
+    wallClock?: ExportWallClock;
 } | {
     ok: false;
     text: string;

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

@@ -0,0 +1,8 @@
+export { prepareTableExport } from './prepare-table-export.js';
+export type { PreparedTableColumn, TableExportContent, TableExportFormatter, } from './prepare-table-export.js';
+export { parseTableExportFormatting, tableExportFormattingFromOptions } from './table-export-formatting.js';
+export type { TableExportFormatting } from './table-export-formatting.js';
+export type { TableExportResult, TableExportResultColumn } from './table-export-result.js';
+export { requiresRawTemporalSqlChunkEvidence } from './table-export-raw-temporal.js';
+export { TABLE_EXPORT_SHEET_SAMPLE_ROWS, defineTableExportSheet, tableExportXlsxRows, encodeTableExportWorkbook, tableExportSheetColumns, serializeTableExportSheetColumns, parseTableExportSheetColumns, tableExportJobSheet, } from './table-export-sheet.js';
+export type { TableExportSheetColumns } from './table-export-sheet.js';

package/dist/types/shared/format-utils/table-export/prepare-table-export.d.ts

@@ -0,0 +1,50 @@
+import { ExportCell, ExportDataType, XlsxColumn, XlsxColumnPresentation } from '../exporters/export-cells.js';
+import { RawTemporalChunkClassificationEvidence } from '../raw-temporal.js';
+import { TableExportFormatting } from './table-export-formatting.js';
+import { TableExportResult } from './table-export-result.js';
+/** One visible column, prepared once. Data type, identity and presentation stay separate. */
+export type PreparedTableColumn = {
+    /** Result key (identity). */
+    key: string;
+    /** Header label. */
+    label: string;
+    /** Authoritative, from `resultColumns`; decides Excel cell type and whether strings may be numbers. */
+    dataType: ExportDataType;
+    /** What made the display text; decides the Excel number format. */
+    presentation?: XlsxColumnPresentation;
+    /** resolveXlsxColumn of the above. */
+    xlsx: XlsxColumn;
+    /**
+     * These values could not type the Excel column: a declared SQL date column
+     * whose values here are all empty or invalid (its raw temporal evidence is
+     * inconclusive), so `xlsx` is text. A background job takes the column's
+     * type from the chunks that could (`tableExportJobSheet`).
+     */
+    xlsxPending?: true;
+};
+/** The rows of one table export, ready for any encoder. */
+export type TableExportContent = {
+    /** Header labels in visible order; undefined when headers are off. */
+    header?: string[];
+    /** One prepared column per visible column. */
+    columns: PreparedTableColumn[];
+    /** Typed cells; `exportCellText` of each is the display text. */
+    rows: ExportCell[][];
+    /** Raw temporal evidence the compactor's chunk-agreement check needs (unchanged). */
+    rawTemporalClassification?: RawTemporalChunkClassificationEvidence;
+};
+/** Prepared once per export (browser) or per chunk (Lambda). */
+export type TableExportFormatter = {
+    /** Header, columns and typed cells for these records. `withHeader` false skips the header (chunks after the first). */
+    format(result: TableExportResult, options?: {
+        withHeader?: boolean;
+    }): TableExportContent;
+    /** The totals row: 'Total' in the label column, '' in other dimensions, formatted metric totals. Undefined when totalRows is 0. */
+    totals(totalsByColumnId: Record<string, unknown>, totalRows: number): ExportCell[] | undefined;
+};
+export declare function prepareTableExport(input: {
+    formatting: TableExportFormatting;
+    cardType: 'table' | 'detailTable' | 'pivotTable' | 'aggregateTable';
+    /** The /api/v1/query body the rows came from (a background job's `queryPayload`). Read for the effective card config, result owner, SQL and Python flags. */
+    queryPayload: Record<string, unknown>;
+}): TableExportFormatter;

package/dist/types/shared/format-utils/table-export/table-export-formatting.d.ts

@@ -0,0 +1,47 @@
+import { CsvDelimiter, CsvEncoding } from '../exporters/csv-utils.js';
+import { ExportFileFormat } from '../exporters/export-file-format.js';
+import { PresentationExecutionSnapshot } from '../presentation-execution.js';
+/** The formatting contract a table export carries (same keys and checks as the scheduler's former contract, plus `fileFormat`). */
+export type TableExportFormatting = {
+    scope: {
+        dashboardId: string;
+        cardId: string;
+    };
+    useFormattedValues: boolean;
+    /** Must equal presentationExecutionSnapshot.reportContext.calendar.tz. */
+    timezone: string;
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
+    delimiter: CsvDelimiter;
+    csvEncoding: CsvEncoding;
+    includeHeaders: boolean;
+    /** The card's persisted column settings. Only `type: 'date'` and `dateFormat` are read. */
+    columnSettings?: Record<string, unknown>;
+    /** Required when values are formatted; a stored-value export may omit it (columns then come from the result). */
+    visibleColumns?: string[];
+    columnLabels?: Record<string, string>;
+    tableTotalsLabelColumnKey?: string;
+    /** The file format the workers write. Absent means 'csv', so jobs dispatched before this field existed still run. */
+    fileFormat?: ExportFileFormat;
+    /** The export's title. Names the Excel sheet, as the browser download does; CSV ignores it. */
+    title?: string;
+};
+/** Checks a table export's formatting contract. Unknown keys and retired keys are rejected. */
+export declare function parseTableExportFormatting(input: unknown): TableExportFormatting;
+/**
+ * The formatting contract for a table export job, assembled field by field
+ * from the export request's `formatOptions`: what the app's export executor
+ * dispatches to the workers and what the browser download formats with, so
+ * the two never differ. Fields the workers do not read (browser timezone,
+ * comparison presentation) are dropped here. Check the result with
+ * `parseTableExportFormatting`.
+ */
+export declare function tableExportFormattingFromOptions(input: {
+    dashboardId: string;
+    cardId: string;
+    formatOptions: Record<string, unknown> & {
+        presentationExecutionSnapshot: PresentationExecutionSnapshot;
+    };
+    fileFormat?: ExportFileFormat;
+    /** The export's title (names the Excel sheet). */
+    title?: string | null;
+}): Record<string, unknown>;

package/dist/types/shared/format-utils/table-export/table-export-raw-temporal.d.ts

@@ -0,0 +1,40 @@
+import { prepareRawTemporalFormatter, RawTemporalChunkClassificationEvidence, RawTemporalValueMetadata, ResolvedRawTemporalFormat } from '../raw-temporal.js';
+import { ExportWallClock } from '../exporters/export-cells.js';
+import { TableExportFormatting } from './table-export-formatting.js';
+import { TableExportResultColumn } from './table-export-result.js';
+type PreparedRawTemporalColumn = {
+    metadata: RawTemporalValueMetadata;
+    format: ResolvedRawTemporalFormat;
+    formatValue: ReturnType<typeof prepareRawTemporalFormatter>;
+};
+export type RawTemporalExportResolution = {
+    activatedColumnKeys: ReadonlySet<string>;
+    byColumnKey: ReadonlyMap<string, PreparedRawTemporalColumn>;
+    sqlChunkEvidence?: RawTemporalChunkClassificationEvidence;
+};
+export declare function requiresRawTemporalSqlChunkEvidence(input: {
+    formatting: TableExportFormatting;
+    queryPayload?: Record<string, unknown>;
+}): boolean;
+export declare function resolveRawTemporalExportPresentation(input: {
+    records: readonly Record<string, unknown>[];
+    columns: readonly TableExportResultColumn[];
+    formatting: TableExportFormatting;
+    queryPayload?: Record<string, unknown>;
+}): RawTemporalExportResolution;
+/**
+ * One raw temporal cell. Undefined when the column is not activated (other
+ * rules apply). A missing key in an activated column is a broken result and
+ * fails, whoever owns the result (SPEC §3.0 case 4).
+ */
+export declare function formatRawTemporalExportValue(input: {
+    value: unknown;
+    columnKey: string;
+    rowIndex: number;
+    resolution: RawTemporalExportResolution;
+}): {
+    text: string;
+    wallClock?: ExportWallClock;
+} | undefined;
+export declare function rawTemporalColumnIsDateOnly(resolution: RawTemporalExportResolution, columnKey: string): boolean | undefined;
+export {};

package/dist/types/shared/format-utils/table-export/table-export-result.d.ts

@@ -0,0 +1,31 @@
+import { RawTemporalValueMetadata, SemaphorResultColumn, TemporalBucketMetadata } from '../../analytics-protocol/contracts.js';
+import { QueryColumnKeyMap } from '../pivot-result-identity.js';
+/** A result column as the response describes it (`columns`). */
+export type TableExportResultColumn = {
+    key?: string;
+    field?: string;
+    label?: string;
+    headerName?: string;
+    temporalBucket?: TemporalBucketMetadata;
+    rawTemporal?: RawTemporalValueMetadata;
+    pivotIdentity?: {
+        metricId: string;
+        metricAlias: string;
+        members?: Array<{
+            fieldId: string;
+            value: string | null;
+            temporalBucket?: TemporalBucketMetadata;
+        }>;
+    };
+};
+export type TableExportResult = {
+    records: readonly Record<string, unknown>[];
+    columns: readonly TableExportResultColumn[];
+    /** Authoritative data types (SemaphorResultColumn.dataType), from the same response. Missing columns are 'unknown'. */
+    resultColumns: readonly Pick<SemaphorResultColumn, 'key' | 'dataType'>[];
+    columnKeyMap?: QueryColumnKeyMap;
+    /** Pivot column classifications (deprecated pivot results only). */
+    columnMetadata?: unknown;
+    /** 'not_pivot' for Table and Detail Table; the other values only for deprecated pivot results. */
+    pivotResultKind: 'not_pivot' | 'canonical' | 'legacy_raw';
+};

package/dist/types/shared/format-utils/table-export/table-export-sheet.d.ts

@@ -0,0 +1,38 @@
+import { ExportCell, XlsxColumn } from '../exporters/export-cells.js';
+import { XlsxRow, XlsxSheet } from '../exporters/xlsx-file.js';
+import { TableExportContent } from './prepare-table-export.js';
+/** Rows a sheet reads to size its columns (SPEC XL-SI-10). */
+export declare const TABLE_EXPORT_SHEET_SAMPLE_ROWS = 200;
+/**
+ * The sheet a table export writes: the title names it, the header is its one
+ * header row, and the first rows size its columns. The background job calls
+ * this with its first chunk's content; that chunk holds the same first rows.
+ */
+export declare function defineTableExportSheet(title: string | null | undefined, content: Pick<TableExportContent, 'columns' | 'header' | 'rows'>): XlsxSheet;
+/** A table export's rows as sheet rows: body rows, then the totals row when there is one. */
+export declare function tableExportXlsxRows(rows: readonly ExportCell[][], totals?: readonly ExportCell[]): XlsxRow[];
+/** The whole workbook of a table export (the browser download). An Excel limit throws XlsxLimitError. */
+export declare function encodeTableExportWorkbook(title: string | null | undefined, content: Pick<TableExportContent, 'columns' | 'header' | 'rows'>, totals?: readonly ExportCell[]): Uint8Array;
+/**
+ * One chunk's Excel columns, as a background job compares them: each column,
+ * and whether this chunk's values could type it (`pending` when they could
+ * not, `PreparedTableColumn.xlsxPending`). Stored beside the chunk before it
+ * is completed (XL-D37).
+ */
+export type TableExportSheetColumns = {
+    columns: readonly XlsxColumn[];
+    pending: readonly boolean[];
+};
+export declare function tableExportSheetColumns(content: Pick<TableExportContent, 'columns'>): TableExportSheetColumns;
+export declare function serializeTableExportSheetColumns(value: TableExportSheetColumns): string;
+export declare function parseTableExportSheetColumns(json: string): TableExportSheetColumns;
+/**
+ * The sheet a background job writes: the first chunk's sheet, with each
+ * column's type settled across the chunks. Every chunk has the same columns
+ * (key and label); at each position the chunks that could type it agree, and
+ * a chunk that could not (all its dates empty, for example) is no evidence.
+ * When no chunk could, the first chunk's column stands (its cells are empty
+ * or text). Chunks that disagree, or a sheet that is not the first chunk's,
+ * are a fault and throw: the job fails rather than mislabel dates.
+ */
+export declare function tableExportJobSheet(sheet: XlsxSheet, chunks: readonly TableExportSheetColumns[]): XlsxSheet;

package/dist/types/shared/format-utils/temporal-bucket.d.ts

@@ -1,3 +1,4 @@
+import { ExportWallClock } from './exporters/export-cells.js';
 import { SemaphorTimeGrain, TemporalBucketFormat, TemporalBucketMetadata, TemporalBucketPreset } from '../analytics-protocol/contracts.js';
 import { ResolvedTemporalStyleSet } from './raw-temporal.js';
 export type { TemporalBucketMetadata } from '../analytics-protocol/contracts.js';
@@ -77,6 +78,14 @@ export declare function parseTemporalBucketValue(value: TemporalBucketValue, met
 export declare function describeTemporalBucketCalendar(metadata: TemporalBucketMetadata): string;
 export declare function parseResolvedTemporalBucketFormat(input: unknown): ResolvedTemporalBucketFormatParseResult;
 export declare function resolveTemporalBucketPresentation(input: ResolveTemporalBucketPresentationInput): ResolvedTemporalBucketPresentation;
+/**
+ * The start of a bucket as a calendar date and time with no zone, for the
+ * grains Excel shows as dates (second to month); undefined for week, quarter
+ * and year buckets, blanks and invalid values. Bucket values are already wall
+ * clock in the governed calendar, so this is the value `formatTemporalBucket`
+ * presents (Excel exports plan XL-D35).
+ */
+export declare function temporalBucketWallClock(value: TemporalBucketValue, metadata: TemporalBucketMetadata): ExportWallClock | undefined;
 export declare function formatTemporalBucket(input: {
     value: TemporalBucketValue;
     metadata: TemporalBucketMetadata;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.540",
+  "version": "0.1.542",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -204,6 +204,7 @@
     "date-fns-tz": "^3.2.0",
     "dompurify": "^3.4.2",
     "fast-deep-equal": "^3.1.3",
+    "fflate": "^0.8.3",
     "immer": "^10.0.3",
     "jwt-decode": "^4.0.0",
     "lexical": "^0.43.0",