react-semaphor 0.1.532 → 0.1.533

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

@@ -83,7 +83,12 @@ export interface ExportJobStatus {
     createdAt: string;
     completedAt?: string;
     expiresAt: string;
+    /** Matrix exports: where the export is (the server computes it from committed work). */
+    phase?: MatrixExportPhase;
+    /** When the server stops the export (ISO); the browser gives up a grace period later. */
+    deadlineAt?: string;
 }
+export type MatrixExportPhase = 'preparing' | 'acquiring' | 'finalizing' | 'completed';
 /** Export job from list endpoint */
 export interface ExportJobListItem {
     progress?: number | null;
@@ -102,6 +107,8 @@ export interface ExportJobListItem {
     expiresAt: string;
     dashboardId?: string;
     cardId?: string;
+    phase?: MatrixExportPhase;
+    deadlineAt?: string;
 }
 /** API error response */
 export interface ExportApiError {
@@ -113,25 +120,45 @@ export interface ExportApiError {
  * Create a new export job
  */
 export declare function createExport(apiServiceUrl: string, token: string, params: CardExportRequest): Promise<CreateExportResponse>;
+/** The direct path's answer (MX-D11): the file, or the background export it started. */
+export type MatrixDirectExportResult = {
+    kind: 'file';
+    file: Blob;
+    fileName: string;
+} | {
+    kind: 'background';
+    exportId: string;
+    status: 'pending' | 'processing';
+    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`.
+ */
+export declare function createMatrixDirectExport(apiServiceUrl: string, token: string, params: MatrixCsvExportRequest & {
+    format: 'csv';
+}): Promise<MatrixDirectExportResult>;
 /**
  * Get list of user's exports
  */
 export declare function getExports(apiServiceUrl: string, token: string, options?: {
     status?: ExportStatus[];
     limit?: number;
-}): Promise<{
+}, signal?: AbortSignal): Promise<{
     exports: ExportJobListItem[];
 }>;
 /**
  * Get status of a specific export job
  */
-export declare function getExportStatus(apiServiceUrl: string, token: string, exportId: string): Promise<ExportJobStatus>;
+export declare function getExportStatus(apiServiceUrl: string, token: string, exportId: string, signal?: AbortSignal): Promise<ExportJobStatus>;
 /**
  * Get download URL for a completed export
  *
  * The backend returns a presigned S3 URL in JSON response.
  */
-export declare function getDownloadUrl(apiServiceUrl: string, token: string, exportId: string): Promise<string>;
+export declare function getDownloadUrl(apiServiceUrl: string, token: string, exportId: string, signal?: AbortSignal): Promise<string>;
 /**
  * Cancel/delete an export job
  */

package/dist/types/lib/csv-download.d.ts

@@ -1,9 +1,11 @@
 /**
  * Save a CSV file in the browser. This is the only place react-semaphor
  * creates a CSV Blob; `content` comes from the CSV file contract
- * (`encodeCsvFile`), which owns the BOM, quoting and record separators.
+ * (`encodeCsvFile`), which owns the BOM, quoting and record separators, or is
+ * a file the server built (a direct Matrix CSV), saved byte for byte so its
+ * BOM survives.
  */
 export declare function downloadCsvFile({ content, fileName, }: {
-    content: string;
+    content: string | Blob;
     fileName: string;
 }): void;

package/dist/types/lib/export-messages.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Every export message the export dialog, its toasts and the notification bell
+ * show (MX-D17; PLAN "Customer messages", M1 to M3, M7 and M8 to M18). Plain
+ * sentences that say where the export is and what to do: no internal terms,
+ * never the product name (white label), no em dashes. A failure reason comes
+ * from the server's own catalog.
+ */
+export declare const EXPORT_UI_MESSAGES: {
+    /** M1: a direct Matrix CSV attempt is running (the export button, and the line under it). */
+    readonly preparingFile: "Preparing file...";
+    readonly preparingFileHint: "Large tables can take a few seconds.";
+    /** M2: the direct attempt returned the file. */
+    readonly fileDownloading: "Your file is downloading.";
+    /** M3: the direct attempt moved to a background export. */
+    readonly movedToBackground: "We're preparing your export in the background. We'll notify you when it's ready.";
+    /** M7: `reason` is the server's catalog reason. */
+    readonly directFailed: (reason: string) => string;
+    /** M8 */
+    readonly queued: "Queued...";
+    /** M9: a Matrix export before any rows. */
+    readonly preparing: "Preparing...";
+    /** M10: a Matrix export, with its committed row count. */
+    readonly fetchingRows: (rows: number) => string;
+    /** M11: a table export. */
+    readonly processing: "Processing...";
+    readonly percentComplete: (progress: number) => string;
+    readonly rowsProcessed: (rows: number) => string;
+    /** M12 */
+    readonly finalizing: "Finalizing...";
+    /** Every in-progress row; `elapsed` is a distance such as "5 minutes". */
+    readonly started: (elapsed: string) => string;
+    /** M13: still running 5 minutes after it started. */
+    readonly longRunning: "Large exports can take up to 30 minutes. You can keep working; we'll notify you.";
+    /** M14, M15, M16 */
+    readonly ready: "Ready";
+    readonly failed: "Failed";
+    readonly cancelled: "Cancelled";
+    readonly inProgress: "In progress";
+    /** M15 when an older server stored no reason: never only "Export failed". */
+    readonly failedFallback: "Something went wrong while preparing this export. Try again, and contact support if it keeps happening.";
+    /** M17: no final status by the server's deadline plus the grace period. */
+    readonly unconfirmed: "We couldn't confirm this export's status. Check the notification bell again when your connection returns.";
+    /** M18 */
+    readonly linkExpired: "This link expired. Refresh the tray to sign the file again.";
+};
+/** M13 appears this long after an export started. */
+export declare const EXPORT_LONG_RUNNING_MS: number;

package/dist/types/lib/exports/bounded-request.d.ts

@@ -0,0 +1,12 @@
+/**
+ * One export status, list or download-link request never waits longer than
+ * this (hotspot H-06: every wait that decides something is bounded). A
+ * timed-out request counts as failed, and its fetch is aborted.
+ */
+export declare const EXPORT_STATUS_TIMEOUT_MS = 15000;
+/**
+ * Rejects when `work` outlasts `EXPORT_STATUS_TIMEOUT_MS`, and aborts its
+ * request. `work` must pass `signal` to its fetch, or the timeout releases the
+ * caller while the request stays open (a static test checks every caller).
+ */
+export declare function boundedRequest<T>(work: (signal: AbortSignal) => Promise<T>): Promise<T>;

package/dist/types/lib/exports/export-status.d.ts

@@ -13,5 +13,7 @@ export declare function mapExportStatus(input: ExportJobStatus | ExportJobListIt
     lastUpdatedAt: Date;
     fileSize: number | undefined;
     error: string | undefined;
+    phase: import('../api/index.js').MatrixExportPhase | undefined;
+    deadlineAt: Date | undefined;
     downloadUrl: string | undefined;
 };

package/dist/types/lib/hooks/use-date-filter.d.ts

@@ -1,4 +1,4 @@
-import { TFilter, TFilterValue, RelativeDateFilter, DateComparisonOperation, FilterStorageOptions, TemporalPrecision } from '../../components/surfboard/filter/types.js';
+import { TFilter, TFilterValue, RelativeDateFilter, DateComparisonOperation, FilterStorageOptions, RelativeDateChangeOptions, TemporalPrecision } from '../../components/surfboard/filter/types.js';
 import { DateRange } from 'react-day-picker';
 type UseDateFilterOptions = FilterStorageOptions;
 type DateFilterChangeOptions = {
@@ -15,7 +15,7 @@ export declare function useDateFilterHook(filterId: string): {
     handleClear: () => void;
     handleChange: (date: DateRange | undefined, operation?: DateComparisonOperation, options?: DateFilterChangeOptions) => void;
     handleNullOperation: (operation: "is null" | "is not null") => void;
-    handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateFilter, options?: DateFilterChangeOptions) => void;
+    handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateFilter, options?: RelativeDateChangeOptions) => void;
     handleReset: () => void;
 };
 export declare function useDateFilter(filter: TFilter, options?: UseDateFilterOptions): {
@@ -30,7 +30,7 @@ export declare function useDateFilter(filter: TFilter, options?: UseDateFilterOp
     handleClear: () => void;
     handleChange: (date: DateRange | undefined, operation?: DateComparisonOperation, options?: DateFilterChangeOptions) => void;
     handleNullOperation: (operation: "is null" | "is not null") => void;
-    handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateFilter, options?: DateFilterChangeOptions) => void;
+    handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateFilter, options?: RelativeDateChangeOptions) => void;
     handleReset: () => void;
 };
 export {};

package/dist/types/lib/hooks/use-export-polling.d.ts

@@ -1,3 +1,10 @@
+import { EXPORT_STATUS_TIMEOUT_MS } from '../exports/bounded-request.js';
+/**
+ * The browser follows the server (MX-D9): it gives up on an export this long
+ * after the server's `deadlineAt`, by which the server has settled the export.
+ */
+export declare const EXPORT_POLL_GRACE_MS: number;
+export { EXPORT_STATUS_TIMEOUT_MS };
 /**
  * Hook that manages smart polling for export status updates.
  *
@@ -20,5 +27,6 @@ export declare const POLLING_INTERVALS: {
     LONG: number;
     MEDIUM_THRESHOLD: number;
     LONG_THRESHOLD: number;
-    MAX_POLLING_DURATION: number;
+    EXPORT_POLL_GRACE_MS: number;
+    FALLBACK_POLLING_DURATION: number;
 };

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

@@ -1,7 +1,12 @@
 import { buildMatrixDeliveryPayload } from './matrix-delivery.js';
 import { downloadMatrixPdf } from '../download-pdf.js';
 import { ActiveExport } from '../stores/export-store.js';
-/** Submission policy stays out of the dialog; presentation consumes the outcome. */
+/**
+ * Submission policy stays out of the dialog; presentation consumes the
+ * outcome. A Matrix CSV goes to the direct path first (MX-D11): a file is
+ * saved here, so it still downloads if the dialog closed meanwhile (M6); a
+ * background export comes back to be tracked in the bell.
+ */
 export declare function submitMatrixDelivery(input: Omit<Parameters<typeof buildMatrixDeliveryPayload>[0], 'format'> & {
     format: string;
     apiServiceUrl: string;
@@ -11,9 +16,16 @@ export declare function submitMatrixDelivery(input: Omit<Parameters<typeof build
 }): Promise<{
     kind: "pdf";
     result: import('../download-pdf.js').PdfDownloadResponse;
+    fileName?: undefined;
     export?: undefined;
 } | {
-    kind: "csv";
+    kind: "csv_file";
+    fileName: string;
+    result?: undefined;
+    export?: undefined;
+} | {
+    kind: "csv_background";
     export: ActiveExport;
     result?: undefined;
+    fileName?: undefined;
 }>;

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

@@ -29,6 +29,10 @@ export declare function useMatrix(input: MatrixInput): {
             isNumeric: boolean;
             hasTextAffixes: boolean;
         }>;
+        absence: {
+            emptyText: string;
+            nullText: string;
+        };
     };
     readCell: (coordinate: import('./matrix-runtime-types.js').MatrixCellAddress) => import('./matrix-runtime-types.js').MatrixCellState;
     setViewport: (viewport: import('./matrix-runtime-types.js').MatrixViewport) => void;

package/dist/types/lib/stores/export-store.d.ts

@@ -17,6 +17,10 @@ export interface ActiveExport {
     fileSize?: number;
     error?: string;
     expiresAt: Date;
+    /** Matrix exports: the server's phase, for the bell's stage text (M9, M10, M12). */
+    phase?: 'preparing' | 'acquiring' | 'finalizing' | 'completed';
+    /** When the server stops the export; polling gives up a grace period later (MX-D9). */
+    deadlineAt?: Date;
 }
 type ExportStoreState = {
     /** Map of export ID to export data */
@@ -27,6 +31,13 @@ type ExportStoreActions = {
     addExport: (exportData: ActiveExport) => void;
     /** Update an existing export */
     updateExport: (id: string, updates: Partial<ActiveExport>) => void;
+    /**
+     * Applies a server answer (poll, refresh). An answer never moves an export
+     * that is final here back to in progress: a newer answer already settled it.
+     */
+    applyServerStatus: (id: string, updates: Partial<ActiveExport>) => void;
+    /** Adds a recovered export only if it is not tracked already (checked when adding). */
+    recoverExport: (exportData: ActiveExport) => void;
     /** Remove an export from the store */
     removeExport: (id: string) => void;
     /** Get all in-progress exports */

package/dist/types/lib/temporal-filter/temporal-filter-utils.d.ts

@@ -17,6 +17,15 @@ export declare function getFilterTemporalCapability(filter: {
         dataType?: unknown;
     };
 }): TemporalFilterCapability;
+/**
+ * The range condition a relative date window ("Today", "Last 7 days") runs
+ * under. The window and the condition are independent, as the server treats
+ * them: "not between" excludes the window, anything else keeps it. A
+ * data-anchored window ("the latest day in the data") runs only as
+ * "between", the one form the server resolves. Every builder of a relative
+ * date filter value (defaults, the date filter hook, Global Date) uses this.
+ */
+export declare function resolveRelativeWindowOperation(requested: string | undefined, relativeMeta: unknown): 'between' | 'not between';
 export declare function supportsMinutePrecisionForOperation(operation: DateComparisonOperation | undefined): boolean;
 export declare function isSubDayRelativeDateFilter(meta: RelativeDateFilter | undefined): meta is Extract<RelativeDateFilter, {
     mode: 'last';

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

@@ -30,6 +30,8 @@ export declare function matrixLevelLabels(input: {
 }>;
 /** Shared viewer/export adapter. Arithmetic, precision and temporal rules stay shared. */
 export declare function resolveMatrixValueFormat(override: SemaphorValueFormat | undefined, semantic: SemaphorValueFormat | undefined): import('../semantic-format.js').AdaptedCanonicalFormatSpec | undefined;
+/** One card's prepared formats: every Matrix surface (screen, Layout CSV, Flat CSV, PDF) formats through it. */
+export type MatrixFormatting = ReturnType<typeof prepareMatrixFormatting>;
 export declare function prepareMatrixFormatting(descriptors: MatrixWindow['descriptors'], presentation: MatrixPresentation, report: ReportRuntimeContext): {
     levels: Map<string, (value: SemaphorScalarValue) => string>;
     measures: Map<string, (value: SemaphorScalarValue) => string>;
@@ -37,4 +39,8 @@ export declare function prepareMatrixFormatting(descriptors: MatrixWindow['descr
         isNumeric: boolean;
         hasTextAffixes: boolean;
     }>;
+    absence: {
+        emptyText: string;
+        nullText: string;
+    };
 };

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

@@ -1,6 +1,18 @@
-import { MatrixExportLayout, MatrixExportRequest, MatrixExportRow } from '../analytics-protocol/index.js';
+import { MatrixExportLayout, MatrixExportRequest, MatrixExportRow, MatrixPath } from '../analytics-protocol/index.js';
 import { ReportRuntimeContext } from '../report-runtime-context/index.js';
 import { FastPathTableStructure } from './table-structure.js';
+import { MatrixFormatting } from './formatters/matrix-formatter.js';
+export { prepareMatrixFormatting, type MatrixFormatting } from './formatters/matrix-formatter.js';
+/**
+ * The identity of a Layout row, enough to decide which labels the next row
+ * repeats. A background export carries the last emitted row's identity between
+ * batches (MX-D14), so label suppression is file-wide.
+ */
+export type MatrixExportRowIdentity = {
+    kind: 'layout';
+    rowPath: MatrixPath;
+    role: 'member' | 'subtotal' | 'grand_total';
+};
 /** Same descriptor-based presentation for viewer, layout CSV and print. */
 export declare function prepareMatrixExportPresentation(layout: MatrixExportLayout, request: MatrixExportRequest, report: ReportRuntimeContext): {
     headers: string[];
@@ -16,11 +28,23 @@ export declare function prepareMatrixExportPresentation(layout: MatrixExportLayo
      */
     continuedColumns: (data: MatrixExportRow, previous?: MatrixExportRow) => number[];
     csvRow: (data: MatrixExportRow) => string[];
-    csvRows: (data: readonly MatrixExportRow[]) => string[][];
+    /**
+     * `previousRow` is the row before `data[0]`, carried by the export's
+     * continuation, so a tabular layout prints each label once across the
+     * whole file. Retries are pure: suppression never relies on mutable
+     * formatter state or an earlier worker. Without it, the first row prints
+     * its labels.
+     */
+    csvRows: (data: readonly MatrixExportRow[], previousRow?: MatrixExportRowIdentity | null) => string[][];
 };
-/** Raw CSV intentionally preserves typed values instead of display formats. */
 export declare function matrixFlatCsvHeaders(layout: MatrixExportLayout): string[];
-export declare function matrixFlatCsvRow(data: MatrixExportRow): (string | number | null)[];
+/**
+ * One Flat CSV record, formatted with the card's formats (MX-D10): level
+ * values as the screen and Layout CSV label members (`(Blank)` for a null
+ * member), measures through the same formatter and absence text as Layout
+ * CSV. Prepare `formatting` once per batch with `prepareMatrixFormatting`.
+ */
+export declare function matrixFlatCsvRow(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;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.532",
+  "version": "0.1.533",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",