react-semaphor 0.1.541 → 0.1.543

package/dist/types/lib/api/exports-api.d.ts

@@ -1,62 +1,8 @@
-import { TFilterValue } from '../../components/surfboard/filter/types.js';
-import { CsvEncoding } from '../../shared/format-utils/exporters/csv-utils.js';
-import { CardConfig, DataSource, TableTotalsRequest } from '../types/explorer-types.js';
-import { ControlBinding, ControlDefinition } from '../types/common-types.js';
-import { ResolvedPrimaryDateField } from '../types/semantic-runtime-types.js';
-import { ComparisonPresentationSpec, GlobalDateComparisonContext } from '../../shared/analytics-protocol/index.js';
-import { TemporalResultOwner } from '../../shared/dashboard-authoring/index.js';
-import { PresentationExecutionSnapshot } from '../../shared/format-utils/index.js';
-import { MatrixCsvExportRequest } from '../matrix-table/matrix-delivery.js';
+import { ExportFileFormat } from '../../shared/format-utils/index.js';
+import { MatrixFileExportRequest } from '../matrix-table/matrix-delivery.js';
+import { CreateExportRequest } from '../../shared/dashboard-authoring/card-export-request.js';
 export type ExportStatus = 'pending' | 'processing' | 'chunking' | 'compacting' | 'completed' | 'failed' | 'cancelled';
-export type ExportFormat = 'csv';
 export type CardType = 'table' | 'aggregateTable' | 'pivotTable' | 'detailTable';
-/** Formatting configuration passed to the export job */
-export interface ExportFormattingConfig {
-    useFormattedValues: boolean;
-    timezone: string;
-    browserTimezone?: string;
-    isSqlCard?: boolean;
-    delimiter: ',' | ';' | '\t';
-    /** Resolved by the dialog: the person'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;
-    format: ExportFormat;
-    formatOptions: AuthoritativeExportFormattingConfig;
-}
 /** Response from creating an export job */
 export interface CreateExportResponse {
     exportId: string;
@@ -68,7 +14,7 @@ export interface CreateExportResponse {
     originalRows?: number;
     maxRows?: number;
 }
-export type CardExportRequest = CreateExportRequest | MatrixCsvExportRequest;
+export type CardExportRequest = CreateExportRequest | MatrixFileExportRequest;
 /** Export job status response */
 export interface ExportJobStatus {
     id: string;
@@ -125,6 +71,7 @@ export type MatrixDirectExportResult = {
     kind: 'file';
     file: Blob;
     fileName: string;
+    format: ExportFileFormat;
 } | {
     kind: 'background';
     exportId: string;
@@ -132,14 +79,13 @@ export type MatrixDirectExportResult = {
     deadlineAt: string | null;
 };
 /**
- * A Matrix CSV a user downloads: built in the request when it fits the direct
- * limits, otherwise moved to a background export by the server. The file is
- * read as bytes, so its BOM survives. Errors carry the server's catalog
- * reason in `details.message`.
+ * A Matrix CSV or Excel file a user downloads: built in the request when it
+ * fits the direct limits, otherwise moved to a background export by the
+ * server. The file is read as bytes, so a CSV's BOM survives; its format is
+ * the response's content type. Errors carry the server's catalog reason in
+ * `details.message` (an Excel limit answers 422 `excel_limit`).
  */
-export declare function createMatrixDirectExport(apiServiceUrl: string, token: string, params: MatrixCsvExportRequest & {
-    format: 'csv';
-}): Promise<MatrixDirectExportResult>;
+export declare function createMatrixDirectExport(apiServiceUrl: string, token: string, params: MatrixFileExportRequest): Promise<MatrixDirectExportResult>;
 /**
  * Get list of user's exports
  */

package/dist/types/lib/dashboard-inputs/control-contract-overrides.d.ts

@@ -0,0 +1,17 @@
+import { ControlBinding, ControlDefinition, TDashboard } from '../types/common-types.js';
+/** A saved control contract a host replays: a card attachment's controls and bindings. */
+export type ControlContractOverrides = {
+    controlDefinitions?: ControlDefinition[];
+    cardControlDefinitions?: ControlDefinition[];
+    controlBindings?: ControlBinding[];
+};
+/**
+ * Puts a saved control contract on the dashboard (and on one card) before it
+ * hydrates. Mutates and returns `dashboard`: callers pass a copy. The
+ * dashboard's hydration (`useDashboard`) and a saved card's request on the
+ * server (`buildSavedCardRequest`) both apply it here.
+ */
+export declare function applyControlContractOverrides(dashboard: TDashboard, params: {
+    cardId?: string;
+    controlContractOverrides?: ControlContractOverrides | undefined;
+}): TDashboard;

package/dist/types/lib/dashboard-viewer/export-table-view.d.ts

@@ -34,6 +34,8 @@ export declare function readExportViewerTable(state: {
 export declare function resolveExportTableView(input: {
     readonly card: TCard;
     readonly records: readonly Record<string, unknown>[];
+    /** The result's output keys when it has no row to read them from; else the rows' keys. */
+    readonly keys?: readonly string[];
     readonly columnKeyMap?: QueryColumnKeyMap;
     readonly resultColumns?: readonly SemaphorResultColumn[];
     readonly comparisonMetadata?: ComparisonMetadataMap;

package/dist/types/lib/hooks/use-dashboard.d.ts

@@ -1,6 +1,7 @@
-import { AuthToken, ControlBinding, ControlDefinition, CustomCard, DashboardLifecycleEvent, DashboardInputExecutionSnapshot, TDashboard, TEvent, TStyle } from '../types/common-types.js';
+import { AuthToken, CustomCard, DashboardLifecycleEvent, DashboardInputExecutionSnapshot, TDashboard, TEvent, TStyle } from '../types/common-types.js';
 import { PresentationExecutionSnapshot } from '../../shared/format-utils/index.js';
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { ControlContractOverrides } from '../dashboard-inputs/control-contract-overrides.js';
 import { ViewerTableSettings } from '../../shared/dashboard-viewer/index.js';
 type UseDashboardProps = {
     id?: string;
@@ -11,11 +12,7 @@ type UseDashboardProps = {
         values: string[] | number[];
     }[] | TFilterValue[];
     defaultControlValues?: Record<string, unknown>;
-    controlContractOverrides?: {
-        controlDefinitions?: ControlDefinition[];
-        cardControlDefinitions?: ControlDefinition[];
-        controlBindings?: ControlBinding[];
-    };
+    controlContractOverrides?: ControlContractOverrides;
     dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot;
     /** Untrusted per-sheet input capture of a Full dashboard PDF; see resolvePrintInputs. */
     printInputCapture?: unknown;

package/dist/types/lib/matrix-table/matrix-delivery-policy.d.ts

@@ -8,8 +8,14 @@ export declare const MATRIX_EXPORT_CONTENT: readonly [{
     readonly label: "Matrix layout: All detail levels";
 }, {
     readonly value: "flat";
-    readonly label: "Flat aggregate CSV";
+    readonly label: "Flat aggregate table";
 }];
+/**
+ * What a Matrix download or attachment may be: PDF, CSV and Excel for the
+ * layout, CSV and Excel for Flat content, which is a data file only
+ * (XL-D16). Downloads off leaves PDF of the layout. One policy for the export
+ * dialog and Briefing attachments.
+ */
 export declare function matrixDeliveryOptions(allowDownload?: boolean, content?: MatrixExportContent): {
     contents: ({
         readonly value: "current";
@@ -19,7 +25,7 @@ export declare function matrixDeliveryOptions(allowDownload?: boolean, content?:
         readonly label: "Matrix layout: All detail levels";
     } | {
         readonly value: "flat";
-        readonly label: "Flat aggregate CSV";
+        readonly label: "Flat aggregate table";
     })[];
     formats: import('../types/index.js').BriefingAttachmentFormat[];
 };

package/dist/types/lib/matrix-table/matrix-delivery.d.ts

@@ -1,10 +1,11 @@
 import { MatrixConfig, MatrixViewState } from '../../shared/analytics-protocol/index.js';
 import { CsvEncoding } from '../../shared/format-utils/exporters/csv-utils.js';
+import { ExportFileFormat } from '../../shared/format-utils/exporters/export-file-format.js';
 import { MatrixExportContent } from '../../shared/dashboard-authoring/matrix-delivery.js';
 import { ReportRuntimeContext } from '../../shared/report-runtime-context/index.js';
 import { CompiledCardQueryContext } from '../query-context/build-card-query-context.js';
 import { DataSource } from '../types/explorer-types.js';
-import { BriefingAttachment } from '../../briefings.js';
+import { BriefingAttachment, BriefingAttachmentFormat } from '../../briefings.js';
 export { captureMatrixExport, type MatrixExportContent } from '../../shared/dashboard-authoring/matrix-delivery.js';
 /** Schedule authoring shares the query snapshot but explicitly excludes session state. */
 export declare function buildMatrixBriefingAttachment(input: {
@@ -13,7 +14,7 @@ export declare function buildMatrixBriefingAttachment(input: {
     cardId: string;
     title: string;
     content: MatrixExportContent;
-    format: 'csv' | 'pdf';
+    format: BriefingAttachmentFormat;
 }): BriefingAttachment;
 export { MATRIX_EXPORT_CONTENT } from './matrix-delivery-policy.js';
 /** Supplied by the mounted Matrix host, never inferred from resident cells. */
@@ -33,7 +34,7 @@ export declare function buildMatrixDeliveryPayload(input: {
     title: string;
     reportContext: ReportRuntimeContext;
     content: MatrixExportContent;
-    format: 'csv' | 'pdf';
+    format: 'csv' | 'xlsx' | 'pdf';
     delimiter: ',' | ';' | '\t';
     /** CSV only; absent lets the app resolve the dashboard's setting. */
     csvEncoding?: CsvEncoding;
@@ -662,7 +663,7 @@ export declare function buildMatrixDeliveryPayload(input: {
                     }[];
                 } | undefined;
             };
-            format: "csv";
+            format: "csv" | "xlsx";
             spec: {
                 source: {
                     kind: "semantic";
@@ -754,6 +755,7 @@ export declare function buildMatrixDeliveryPayload(input: {
         acquisition?: "continuation" | undefined;
     };
 };
-export type MatrixCsvExportRequest = ReturnType<typeof buildMatrixDeliveryPayload> & {
-    format: 'csv';
+/** A Matrix data file request (CSV or Excel) for the direct path or a job. */
+export type MatrixFileExportRequest = ReturnType<typeof buildMatrixDeliveryPayload> & {
+    format: ExportFileFormat;
 };

package/dist/types/lib/query-context/build-dashboard-card-query-contract.d.ts

@@ -0,0 +1,50 @@
+import { TCard, TDashboard } from '../types/common-types.js';
+import { PaginationConfig } from '../types/explorer-types.js';
+import { ResolvedPrimaryDateField } from '../types/semantic-runtime-types.js';
+import { TableConfig } from '../types/query-types.js';
+import { CardQueryContext, CompiledCardQueryContext } from './build-card-query-context.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { DashboardCardQueryRequestPayloadBase } from '../../shared/dashboard-authoring/card-query-request.js';
+import { CompiledDashboardCardFilters, CompileDashboardCardFiltersParams } from './compile-dashboard-card-filters.js';
+export type { DashboardCardQueryRequestPayloadBase } from '../../shared/dashboard-authoring/card-query-request.js';
+export type DashboardCardQueryContract = {
+    status: 'ready';
+    queryKey: string[];
+    queryInputIdentity: string;
+    paginationConfig?: PaginationConfig;
+    requestPayloadBase: DashboardCardQueryRequestPayloadBase;
+    tableConfig: TableConfig;
+    compiledFilters: CompiledDashboardCardFilters;
+};
+export type DashboardCardQueryContractResult = DashboardCardQueryContract | {
+    status: 'blocked';
+    cardId: string;
+    mappingDispositions: CompiledDashboardCardFilters['mappingDispositions'];
+    tableConfig: TableConfig;
+};
+/** Test/invariant helper for fixtures that cannot contain mapped inputs. */
+export declare function requireReadyDashboardCardQueryContract(result: DashboardCardQueryContractResult): DashboardCardQueryContract;
+export type DashboardCardQueryExecutionOptions = {
+    resolvedPrimaryDateField?: ResolvedPrimaryDateField;
+    calendarContext: CalendarContext;
+    allowGlobalDateMinutePrecision?: boolean;
+    /**
+     * The cache settings of the dashboard the card belongs to (ledger P1-01).
+     * Required so that every caller decides; never read from the store.
+     */
+    globalCacheConfig: TDashboard['globalCacheConfig'];
+    resolvePaginationConfig?: (queryInputIdentity: string) => PaginationConfig | undefined;
+};
+/** One final compilation for interactive requests and immutable input captures. */
+export declare function compileDashboardCardQueryContext(card: TCard, context: CardQueryContext, execution: Omit<CompileDashboardCardFiltersParams, 'card' | 'cardConfig' | 'input'>): {
+    status: "blocked";
+    cardId: string;
+    mappingDispositions: import('./dashboard-filter-mapping-resolution.js').DashboardFilterMappingDisposition[];
+} | {
+    status: "ready";
+    queryContext: CompiledCardQueryContext;
+    compiledFilters: CompiledDashboardCardFilters & {
+        status: "ready";
+    };
+};
+export declare function buildDashboardCardQueryContract(card: TCard, context: CardQueryContext, execution: DashboardCardQueryExecutionOptions): DashboardCardQueryContractResult;

package/dist/types/lib/types/explorer-types.d.ts

@@ -700,6 +700,12 @@ export interface PaginationMetadata {
     totalCount: number;
     hasNextPage: boolean;
     hasPrevPage: boolean;
+    /**
+     * `verified` only when the count query returned its row; `unavailable` when
+     * it failed (the count shown is then today's fallback, never a fact). A
+     * server export sizes itself only from a verified count (Excel exports XL-D21).
+     */
+    totalCountStatus?: 'verified' | 'unavailable';
 }
 export { resolveQueryColumnKeyMapEntry, resolveUniqueQueryColumnKeyMapEntry, type QueryColumnKeyMapByRole, type QueryColumnKeyMapEntry, type QueryColumnKeyRole, } from '../../shared/format-utils/pivot-result-identity.js';
 export type QueryColumnKeyMap = SharedQueryColumnKeyMap;

package/dist/types/shared/analytics-protocol/matrix-definition-contract.d.ts

@@ -6861,7 +6861,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
     presentation: MatrixPresentationSchema;
 } & {
     mode: z.ZodLiteral<"flat">;
-    format: z.ZodLiteral<"csv">;
+    format: z.ZodEnum<["csv", "xlsx"]>;
 }, "strict", z.ZodTypeAny, {
     mode: "flat";
     presentation: {
@@ -7086,7 +7086,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
             }[];
         } | undefined;
     };
-    format: "csv";
+    format: "csv" | "xlsx";
     spec: {
         source: {
             kind: "semantic";
@@ -7379,7 +7379,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
             }[];
         } | undefined;
     };
-    format: "csv";
+    format: "csv" | "xlsx";
     spec: {
         source: {
             kind: "semantic";

package/dist/types/shared/assistant-context/index.d.ts

@@ -6,4 +6,4 @@
  * case's context from a saved dashboard with `projectSavedDashboardContext`.
  */
 export { AssistantContextSourceError, projectAssistantContext, type AssistantContextSource, type AssistantContextSourceIssue, } from './project-context.js';
-export { assistantCardReplayFields, buildSavedCardRequest, cardReplayOf, projectSavedDashboardContext, projectSavedDashboardTurn, type AssistantCardReplayFields, type SavedCardRequestRefusal, type SavedDashboardPlace, } from './saved-dashboard-context.js';
+export { assistantCardReplayFields, buildSavedCardRequest, cardReplayOf, projectSavedDashboardContext, projectSavedDashboardTurn, type AssistantCardReplayFields, type SavedCardHost, type SavedCardRequestRefusal, type SavedDashboardPlace, } from './saved-dashboard-context.js';

package/dist/types/shared/assistant-context/saved-dashboard-context.d.ts

@@ -1,5 +1,7 @@
-import { TCard, TDashboard } from '../../lib/types/common-types.js';
+import { DashboardInputExecutionSnapshot, TCard, TDashboard } from '../../lib/types/common-types.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
 import { CardViewStateMap } from '../../lib/dashboard-view-state/index.js';
+import { ControlContractOverrides } from '../../lib/dashboard-inputs/control-contract-overrides.js';
 import { SemanticExecutionPayload } from '../../lib/types/semantic-runtime-types.js';
 import { CalendarContext } from '../report-runtime-context/index.js';
 import { ViewerStoreInputValues } from '../../lib/dashboard-viewer/compatibility-input-storage.js';
@@ -108,11 +110,25 @@ export declare function cardReplayOf(input: {
     message?: string;
 };
 /**
- * A saved card's request as a fresh viewer opens it (saved defaults, no
- * bookmark, no drill), for an external client's `fromCard` replay
- * (analytics agent Plan 1, Phase 3b, D3b-2). The same owners as the context:
- * the viewer baseline, the store's input values, the card's snapshot with its
- * request, and the server-request owner CSV export shares. Pure; the caller
+ * What a host opens a saved dashboard with, as a scheduled card attachment's
+ * print view gets it: default filter and control values, a saved control
+ * contract, and a saved input snapshot. Every field is optional; none at all
+ * is a fresh viewer (saved defaults).
+ */
+export type SavedCardHost = {
+    filterValues?: readonly TFilterValue[];
+    controlValues?: Readonly<Record<string, unknown>>;
+    controlContract?: ControlContractOverrides;
+    dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot;
+};
+/**
+ * A saved card's request as a host opens it: by default a fresh viewer
+ * (saved defaults, no bookmark, no drill), for an external client's
+ * `fromCard` replay (analytics agent Plan 1, Phase 3b, D3b-2); with `host`,
+ * a scheduled card attachment's saved values, the values its print view
+ * opens with (Excel exports Phase 6). The same owners as the context: the
+ * viewer baseline, the store's input values, the card's snapshot with its
+ * request, and the server-request owner exports share. Pure; the caller
  * loads the dashboard, its semantic payload and calendar, and checks access.
  */
 export declare function buildSavedCardRequest(input: {
@@ -120,6 +136,7 @@ export declare function buildSavedCardRequest(input: {
     cardId: string;
     semanticExecutionPayload: SemanticExecutionPayload | undefined;
     calendar: CalendarContext;
+    host?: SavedCardHost;
 }): {
     status: 'ready';
     request: AssistantCardRequest;

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/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";