react-semaphor 0.1.541 → 0.1.542

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.541",
+  "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",