react-semaphor 0.1.532 → 0.1.534

package/dist/types/lib/types/index.d.ts

@@ -9,3 +9,4 @@ export type { TChartType } from '../charts/types.js';
 export type { CanonicalFormatSpec } from '../formatters/canonical-format-adapter.js';
 export type { DateUnit, DateSelectionMode, FilterFieldMeta, FilterLocation, FilterSemanticContext, Operation, RelativeDateFilter, RelativeDateUnit, SubDayDateUnit, TFilter, TFilterValue, } from '../../components/surfboard/filter/types.js';
 export type DateComparisonOperation = Extract<import('../../components/surfboard/filter/types.js').Operation, '=' | '!=' | '>' | '>=' | '<' | '<=' | 'between' | 'not between' | 'is null' | 'is not null'>;
+export * from '../../shared/dashboard-viewer/index.js';

package/dist/types/lib/utils/filter-default-value-utils.d.ts

@@ -1,11 +1,11 @@
+import { DefaultDateCalendar } from '../../components/ui-custom/date-range-presets.js';
 import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
 import { TInlineFilter } from '../types/common-types.js';
-import { CalendarContext } from '../../shared/report-runtime-context/index.js';
 /**
- * The report calendar defaults resolve in: its timezone, or the calendar
- * with its week start too, so a week default matches the server's week.
+ * The report calendar defaults resolve in. A timezone alone uses the live
+ * clock and Monday weeks; a calendar carries its anchor and fiscal periods.
  */
-export type DefaultsCalendar = string | Pick<CalendarContext, 'tz' | 'weekStart'>;
+export type DefaultsCalendar = string | DefaultDateCalendar;
 type DefaultBackedFilter = Pick<TFilter, 'id' | 'column' | 'operation' | 'dataType' | 'nativeDataType' | 'dateSelectionMode' | 'defaultValues' | 'defaultDateFilter' | 'fieldMeta' | 'semanticContext'> & Partial<Pick<TInlineFilter, 'id' | 'column' | 'operation' | 'dataType' | 'nativeDataType' | 'dateSelectionMode' | 'defaultValues' | 'defaultDateFilter' | 'fieldMeta' | 'semanticContext'>>;
 /**
  * Converts a filter's default configuration into an active runtime filter value.
@@ -13,6 +13,13 @@ type DefaultBackedFilter = Pick<TFilter, 'id' | 'column' | 'operation' | 'dataTy
  */
 export declare function buildFilterValueFromDefaults(filter: DefaultBackedFilter, calendar?: DefaultsCalendar | null): TFilterValue | undefined;
 export declare function buildFilterValuesFromDefaults(filters: DefaultBackedFilter[] | undefined, calendar?: DefaultsCalendar): TFilterValue[];
+/**
+ * The window a saved relative date names at the report calendar's anchor, by the
+ * same rule a relative default resolves with. Undefined when `meta` is not a
+ * relative date or names no window, and for a window counted from the latest
+ * data: only the server's data anchor names that one (analytics kernel K12).
+ */
+export declare function resolveRelativeDateWindow(meta: unknown, calendar?: DefaultsCalendar | null): [Date, Date] | undefined;
 export declare function isCompatibleFilterValue(filter: Pick<TFilter, 'id' | 'operation' | 'dataType'>, filterValue: TFilterValue): boolean;
 export declare function filterCompatibleFilterValues(filters: TFilter[] | undefined, filterValues: TFilterValue[] | undefined): TFilterValue[];
 export declare function mergeFilterValueLayers(baseValues: TFilterValue[], overrideValues: TFilterValue[]): TFilterValue[];

package/dist/types/lib/utils.d.ts

@@ -47,6 +47,7 @@ export declare function getDashboard(apiServiceUrl: string, accessToken: string
     assistantProfileId?: string;
     semanticExecutionPayload: import('./types/semantic-runtime-types.js').SemanticExecutionPayload;
     organizationAppearance?: import('./types/index.js').AppearanceSpec | null;
+    viewer?: import('./types/index.js').DashboardViewerPayload;
 } | null>;
 export declare function getPlugins(apiServiceUrl: string, accessToken: string | undefined): Promise<GetPluginsResponse | null>;
 export declare const getDataType: (dbType: unknown) => "string" | "number" | "boolean" | "date" | "json" | "geo";

package/dist/types/shared/analytics-protocol/index.d.ts

@@ -13,6 +13,7 @@ export * from './physical-source-resolution.js';
 export * from './source-entity-resolution.js';
 export * from './fixtures.js';
 export * from './metric-comparison.js';
+export * from './sort-target.js';
 export * from './dashboard-date-comparison-definition.js';
 export * from './dashboard-input-contract.js';
 export * from './selection-contract.js';

package/dist/types/shared/analytics-protocol/relative-date-filter.d.ts

@@ -59,3 +59,10 @@ export declare function isDataRelativeDateFilter(meta: unknown): meta is DataRel
 export declare function allowsRelativeDate(operator: string): boolean;
 /** Strict schema for a persisted `RelativeDateFilter`. */
 export declare const relativeDateFilterSchema: z.ZodType<RelativeDateFilter>;
+/**
+ * The one reader for a stored relative date (a filter's default, a saved or
+ * replayed filter value): the window when every field a resolver needs is
+ * present and valid, with unknown keys dropped; otherwise undefined, so the
+ * caller keeps the value's fixed dates instead of throwing on a bad unit.
+ */
+export declare function readRelativeDateFilter(value: unknown): RelativeDateFilter | undefined;

package/dist/types/shared/analytics-protocol/sort-target.d.ts

@@ -0,0 +1,40 @@
+import { MetricResultAliasInput } from './metric-comparison.js';
+export type SortTargetField = MetricResultAliasInput & {
+    readonly id?: string;
+};
+export type SortTargetRole = 'metric' | 'groupby' | 'detail';
+/** One kind of column in the query, in the order sorts search them. */
+export type SortTargetGroup = {
+    readonly role: SortTargetRole;
+    readonly fields: readonly SortTargetField[];
+};
+export type SortTargetRef = {
+    readonly id?: string;
+    readonly name: string;
+    readonly entityName?: string;
+    readonly alias?: string;
+};
+export type SortTarget = {
+    readonly group: number;
+    readonly index: number;
+};
+/**
+ * The result alias that identifies one column instance: its own alias, else
+ * the generated one (for a metric, with its aggregate). A sort entry carries
+ * it as `alias` to name exactly that column.
+ */
+export declare function sortTargetAlias(field: SortTargetField, role: SortTargetRole): string;
+/**
+ * The column a sort entry names, searched across the query's column groups in
+ * order (for a grouped query: metrics, then group columns). A column instance
+ * is its id plus its result alias: SUM and AVG of one field can share an id,
+ * and so can a group column and a count of it. In order:
+ * 1. the column with the entry's id whose result alias is the entry's alias;
+ * 2. the only column with the entry's id;
+ * 3. group by group, the first column with the entry's name and entity whose
+ *    alias is the entry's, or any alias when the entry has none (the rule
+ *    before sort entries carried ids).
+ * The query builder and the browser resolve sorts only here, so the sort a
+ * viewer sees is the sort the query runs.
+ */
+export declare function findSortTarget(groups: readonly SortTargetGroup[], sort: SortTargetRef): SortTarget | undefined;

package/dist/types/shared/dashboard-authoring/dashboard-filter-value-compatibility.d.ts

@@ -6,4 +6,13 @@ declare const OPERATIONS_BY_DATA_TYPE: {
 };
 export declare function dashboardFilterValueTypeForDataType(dataType: unknown): keyof typeof OPERATIONS_BY_DATA_TYPE;
 export declare function isDashboardFilterOperationCompatible(dataType: unknown, operation: unknown): boolean;
+/** Every filter operation a stored filter value may name. */
+export declare const DASHBOARD_FILTER_OPERATIONS: ReadonlySet<string>;
+export type DashboardFilterScalarType = keyof typeof OPERATIONS_BY_DATA_TYPE;
+/**
+ * The values a filter operation takes: how many, and of which scalar type.
+ * The one rule for stored filter values, in authored defaults and in saved
+ * bookmarks. Appends a message naming `location` for the first problem.
+ */
+export declare function validateDashboardFilterValues(operation: unknown, values: readonly unknown[], valueType: DashboardFilterScalarType | undefined, location: string, errors: string[]): void;
 export {};

package/dist/types/shared/dashboard-viewer/bookmark-state.d.ts

@@ -0,0 +1,35 @@
+import { ParseResult } from './table-settings.js';
+import { BookmarkState } from './viewer-contract.js';
+/** A part of a stored bookmark that could not be read; it is left out. */
+export type BookmarkStateIssue = {
+    readonly target: 'input' | 'selection' | 'sheet' | 'card';
+    /**
+     * The input id (a click selection's for `selection`), sheet id or card id;
+     * for a malformed input section, its path (`shared`, `byCardId.<id>`).
+     */
+    readonly id: string;
+};
+export type BookmarkStateRead = {
+    readonly ok: true;
+    readonly value: BookmarkState;
+    /** Parts left out because they could not be read. */
+    readonly issues: readonly BookmarkStateIssue[];
+    /** Keys this version does not define (ignored on read, rejected on write). */
+    readonly unknownKeys: readonly string[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Reads a stored bookmark, keeping every part that parses: a slot, sheet or
+ * table entry that doesn't is left out and reported in `issues`, so one bad
+ * entry never costs the rest of the bookmark. Fails only for another version
+ * or a state that is not an object. Reconciliation against the dashboard
+ * (removed inputs, sheets or cards) happens when it is applied, not here.
+ */
+export declare function readBookmarkState(json: unknown, version: number): BookmarkStateRead;
+/**
+ * The write check: the bookmark must read completely, with no part left out
+ * and no unknown key. Empty table entries are dropped.
+ */
+export declare function parseBookmarkState(json: unknown, version: number): ParseResult<BookmarkState>;

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

@@ -0,0 +1,3 @@
+export * from './bookmark-state.js';
+export * from './table-settings.js';
+export * from './viewer-contract.js';

package/dist/types/shared/dashboard-viewer/table-settings.d.ts

@@ -0,0 +1,89 @@
+import { TCard, TDashboard } from '../../lib/types/common-types.js';
+export declare const VIEWER_LIMITS: {
+    readonly bookmarksPerViewerPerDashboard: 20;
+    readonly bookmarkNameMaxChars: 100;
+    readonly columnLabelMaxChars: 120;
+    readonly tableSettingsMaxBytes: 65536;
+    readonly rememberedTableSettingsMaxBytes: 262144;
+    readonly bookmarkStateMaxBytes: 65536;
+};
+export declare const VIEWER_TABLE_SETTINGS_VERSION: 1;
+export type ParseResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** UTF-8 bytes of `JSON.stringify(value)`: the browser-side size measure. */
+export declare function measureJsonBytes(value: unknown): number;
+export type TableColumnIdentity = {
+    readonly kind: 'dimension';
+    readonly role: 'detail' | 'groupby';
+    readonly fieldId: string;
+} | {
+    readonly kind: 'metric';
+    readonly metricId: string;
+    readonly metricAlias: string;
+} | {
+    readonly kind: 'result';
+    readonly key: string;
+};
+/**
+ * Serialized column identity: "dim:<role>:<fieldId>" | "metric:<metricId>:<metricAlias>"
+ * | "result:<key>", each segment percent-encoded. Branded so an output key can't
+ * be passed where a column id is expected.
+ */
+export type TableColumnId = string & {
+    readonly __brand: 'TableColumnId';
+};
+export declare function toTableColumnId(identity: TableColumnIdentity): TableColumnId;
+/** `undefined` for a malformed or non-canonical id; settings parsers drop those. */
+export declare function parseTableColumnId(value: string): TableColumnIdentity | undefined;
+export type TableSortEntry = {
+    readonly columnId: TableColumnId;
+    readonly direction: 'asc' | 'desc';
+};
+/**
+ * One viewer's choices for one table card. Sparse and normalized: a field that
+ * is empty or equals the author's is omitted, and settings equal to the
+ * author's table are `undefined`, never `{}`.
+ */
+export type ViewerTableSettings = {
+    /** Arrangement of addressable columns. Unlisted columns keep their author-relative position. */
+    readonly order?: readonly TableColumnId[];
+    readonly hidden?: readonly TableColumnId[];
+    /** Display names. Downloads use them too. */
+    readonly labels?: Readonly<Record<TableColumnId, string>>;
+    /** Absent: the author's sort. `[]`: explicitly unsorted. Never saved in `page-only` mode. */
+    readonly sort?: readonly TableSortEntry[];
+};
+/**
+ * Drops empty fields and duplicate or malformed column ids. `sort: []` is kept:
+ * it means "explicitly unsorted". Returns `undefined` when nothing is left.
+ */
+export declare function normalizeViewerTableSettings(settings: ViewerTableSettings | undefined): ViewerTableSettings | undefined;
+export declare function isEmptyViewerTableSettings(settings: ViewerTableSettings | undefined): boolean;
+/**
+ * Strict shape check, then normalization: malformed column ids are dropped,
+ * a structural problem (unknown key, wrong type, a name over 120 characters) is
+ * an error. An empty result parses to `{}`; callers treat it as "no settings".
+ */
+export declare function parseViewerTableSettings(json: unknown, version: number): ParseResult<ViewerTableSettings>;
+/** Parses a `Record<cardId, ViewerTableSettings>`, keeping only `cardIds` and dropping entries that fail. */
+export declare function parseViewerTableSettingsMap(json: unknown, version: number, cardIds: ReadonlySet<string>): Readonly<Record<string, ViewerTableSettings>>;
+/**
+ * True for a `table` or `detailTable` card: a viewer can sort it. With
+ * customization off the sort lasts for the visit and is never saved (PLAN B30).
+ */
+export declare function isTableCardSortable(card: Pick<TCard, 'type'>): boolean;
+/**
+ * True for a `table` or `detailTable` card whose author left customization on
+ * (absent = on): a viewer can hide, reorder and rename its columns, and their
+ * settings are remembered and saved in bookmarks.
+ */
+export declare function isTableCardCustomizable(card: Pick<TCard, 'type' | 'preferences'>): boolean;
+/** Dashboard `table`/`detailTable` cards (not document sections): every table a viewer can sort. */
+export declare function getSortableTableCardIds(dashboard: Pick<TDashboard, 'sheets'>): ReadonlySet<string>;
+/** Dashboard `table`/`detailTable` cards (not document sections) whose author left `allowViewerColumnCustomization` on. */
+export declare function getCustomizableTableCardIds(dashboard: Pick<TDashboard, 'sheets'>): ReadonlySet<string>;

package/dist/types/shared/dashboard-viewer/viewer-contract.d.ts

@@ -0,0 +1,95 @@
+import { DashboardInputValues } from '../../lib/types/common-types.js';
+import { ViewerTableSettings } from './table-settings.js';
+export declare const BOOKMARK_STATE_VERSION: 1;
+/** What a bookmark stores: only the differences from the baseline. */
+export type BookmarkState = {
+    readonly version: 1;
+    /** Omitted when it is the author's first sheet. */
+    readonly selectedSheetId?: string;
+    /** Differing slots only. `{ status: 'cleared' }` = the viewer removed a default. */
+    readonly inputs?: DashboardInputValues;
+    /** Customized cards only, keyed by card id. */
+    readonly tableSettings?: Readonly<Record<string, ViewerTableSettings>>;
+};
+/**
+ * Who can open a bookmark. `TEAM`: the owner's tenant (tenant users) or
+ * organization (org users). `DASHBOARD`: everyone who can open the dashboard;
+ * created by org users who can edit it. A shared bookmark carries its values
+ * as saved; every query runs under the reader's own access (PLAN B31).
+ */
+export declare const BOOKMARK_VISIBILITIES: readonly ["PRIVATE", "TEAM", "DASHBOARD"];
+export type BookmarkVisibility = (typeof BOOKMARK_VISIBILITIES)[number];
+export type Bookmark = {
+    readonly id: string;
+    readonly name: string;
+    readonly revision: number;
+    readonly state: BookmarkState;
+    readonly visibility: BookmarkVisibility;
+    /** Only the owner updates, renames, deletes or changes visibility. */
+    readonly isOwn: boolean;
+    /** The owner's display name, for bookmarks shared by someone else. */
+    readonly ownerName?: string;
+};
+export type BookmarkSummary = {
+    readonly id: string;
+    readonly name: string;
+    readonly revision: number;
+    readonly isDefault: boolean;
+    /** ISO 8601. */
+    readonly updatedAt: string;
+    readonly visibility: BookmarkVisibility;
+    readonly isOwn: boolean;
+    readonly ownerName?: string;
+};
+export type ViewerAccessMode = 'read-write' | 'read-only' | 'session-only';
+export type ViewerAccessReason = 
+/** read-only */
+'impersonating'
+/** session-only: the token names no person (tenant-only or no identity). */
+ | 'no-viewer-identity'
+/** session-only: the token names a tenant user who does not exist. */
+ | 'user-not-provisioned';
+/** `GetDashboardResponse.viewer`. Absent when `openViewerState` fails; the client then acts as session-only. */
+export type DashboardViewerPayload = {
+    readonly access: ViewerAccessMode;
+    readonly accessReason?: ViewerAccessReason;
+    /** Remembered settings, filtered to customizable cards and parsed. `{}` for session-only. */
+    readonly tableSettings: Readonly<Record<string, ViewerTableSettings>>;
+    /** Phase 2. Present only if it exists, is on this dashboard and is visible to the viewer now. */
+    readonly defaultBookmark?: Bookmark;
+    /** Phase 3. Present when the viewer has saved state: who `TEAM` means, and whether they can publish dashboard views. */
+    readonly sharing?: {
+        /** Who "My team" reaches; absent when the viewer has no team (an org user outside any organization). */
+        readonly teamScope?: 'tenant' | 'organization';
+        readonly canPublish: boolean;
+    };
+};
+/**
+ * How many saved bookmarks and remembered table settings reference each part
+ * of a dashboard: counts only, never names or values. Editors only; feeds the
+ * author impact warning (`describeBookmarkImpact`).
+ */
+export type BookmarkUsage = {
+    readonly bookmarks: number;
+    /** Bookmarks with a slot for the input, in any scope. */
+    readonly inputs: Readonly<Record<string, number>>;
+    /** Bookmarks that open on the sheet or keep values for it. */
+    readonly sheets: Readonly<Record<string, number>>;
+    readonly tables: Readonly<Record<string, {
+        readonly bookmarks: number;
+        /** Viewers with remembered settings for the table. */
+        readonly remembered: number;
+        /** Per column: bookmarks and remembered settings that name it. */
+        readonly columns: Readonly<Record<string, {
+            readonly bookmarks: number;
+            readonly remembered: number;
+        }>>;
+    }>>;
+};
+export type ViewerErrorCode = 'not-found' | 'forbidden' | 'read-only' | 'invalid' | 'not-eligible' | 'too-large' | 'limit-reached' | 'revision-conflict';
+export type ViewerErrorBody = {
+    readonly error: string;
+    readonly code: ViewerErrorCode;
+    /** With `revision-conflict`. */
+    readonly currentRevision?: number;
+};

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

@@ -0,0 +1,47 @@
+import { RelativeDateFilter } from '../analytics-protocol/index.js';
+/**
+ * The fields of a filter value the filter line reads. A dashboard filter
+ * value fits it; the server builds a run's line from the same saved values.
+ */
+export type FilterLineValue = {
+    name: string;
+    operation: string;
+    values: readonly unknown[];
+    valueType?: string;
+    temporalPrecision?: string;
+    relativeMeta?: unknown;
+};
+type FormatFilterLineOptions = {
+    timezone?: string;
+};
+type FormatFilterConditionOptions = FormatFilterLineOptions & {
+    /** The filter's display name; defaults to its column name in title case. */
+    label?: string;
+};
+/**
+ * The filter line heads a PDF and travels in export requests, so a long
+ * multi-select is summarized rather than listed in full.
+ */
+export declare const FILTER_LINE_MAX_LISTED_VALUES = 10;
+/**
+ * The relative window a filter line prints by name instead of dates, with its
+ * range operator kept ("Closed On: This year", "Created At not in Last 30
+ * days of data"). Two kinds: a window counted from the latest data, which has
+ * no bounds until a query finds that data (analytics kernel K12), and a
+ * window in quarters or years, whose bounds follow the fiscal year of each
+ * card's data model, so one set of dates could be wrong for some cards. Any
+ * other relative window prints the dates it resolves to.
+ */
+export declare function readNamedRelativeWindow(filter: FilterLineValue): RelativeDateFilter | undefined;
+/**
+ * One filter value as a readable condition, operator included: "Region not in
+ * (West)", "Amount ≥ 100". Empty for a non-null operation with no values.
+ */
+export declare function formatFilterCondition(filter: FilterLineValue, options?: FormatFilterConditionOptions): string;
+/**
+ * Converts an array of filter values into a human-readable filter line
+ * @param filterValues Filter values (dashboard filter values fit)
+ * @returns Human-readable filter description string
+ */
+export declare function formatFilterLine(filterValues: readonly FilterLineValue[], options?: FormatFilterLineOptions): string;
+export {};

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/index.d.ts

@@ -30,6 +30,7 @@ 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 './filter-line.js';
 export * from './aggregate-table-row-presentation.js';
 export { PDF_GROUP_CONTINUATION_CLASS } from './grouped-table-presentation.js';
 export { SEMAPHOR_GENERATED_COUNT_METRIC_ID } from '../analytics-protocol/contracts.js';

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.534",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -115,7 +115,7 @@
     "build": "node scripts/build.mjs",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:regressions": "node scripts/lint-regressions.mjs",
-    "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs",
+    "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs && node scripts/types-entry-imports.mjs",
     "preview": "vite preview",
     "test": "vitest run",
     "test:changed": "vitest run --changed",