react-semaphor 0.1.526 → 0.1.527

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

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/** Calendar units a relative date can count in. */
+export type DateUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
+/** Sub-day units, used only by rolling `last` windows. */
+export type SubDayDateUnit = 'minute' | 'hour';
+export type RelativeDateUnit = DateUnit | SubDayDateUnit;
+/**
+ * A date window stated relative to an anchor ("now" or a pinned instant).
+ * Dashboard filters carry it as `TFilterValue.relativeMeta` and card filters as
+ * `FilterCondition.relativeMeta`; the server resolves it on every run in the
+ * governed calendar.
+ */
+export type RelativeDateFilter = {
+    mode: 'last';
+    n: number;
+    unit: SubDayDateUnit;
+    complete?: false;
+    relativeTo?: RelativeDateAnchor;
+} | {
+    mode: 'last';
+    n: number;
+    unit: DateUnit;
+    complete?: boolean;
+    relativeTo?: RelativeDateAnchor;
+} | {
+    mode: 'this';
+    unit: DateUnit;
+    toDate?: boolean;
+    /** Only used with unit=month for single-day month-boundary presets. */
+    boundary?: 'first_day' | 'last_day';
+} | {
+    mode: 'previous';
+    unit: DateUnit;
+} | {
+    mode: 'between';
+    unit: DateUnit;
+    from: number;
+    to: number;
+};
+/**
+ * What a `last` window counts back from. Omitted means now (or a pinned
+ * instant); `'latest_data'` means the latest value of the window's own field
+ * in its lookup scope (analytics kernel K11). Only agents author it.
+ */
+export type RelativeDateAnchor = 'latest_data';
+/** A `last` window that counts back from the latest data (K11). */
+export type DataRelativeDateFilter = Extract<RelativeDateFilter, {
+    mode: 'last';
+}> & {
+    relativeTo: 'latest_data';
+};
+/**
+ * A window that counts back from the latest data instead of from now (K11):
+ * the one test every reader uses. It reads any value, so callers can pass a
+ * field they have not validated.
+ */
+export declare function isDataRelativeDateFilter(meta: unknown): meta is DataRelativeDateFilter;
+/** A relative date belongs only on a range condition (plan D3). */
+export declare function allowsRelativeDate(operator: string): boolean;
+/** Strict schema for a persisted `RelativeDateFilter`. */
+export declare const relativeDateFilterSchema: z.ZodType<RelativeDateFilter>;

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

@@ -0,0 +1,20 @@
+import { RelativeDateFilter } from './relative-date-filter.js';
+/** The preset a relative date is, or null when it isn't one. */
+export declare function findPresetLabel(meta: RelativeDateFilter | undefined): string | null;
+/** One offset as an option label: "Today", "Last month", "6 days ago". */
+export declare function getRelativeOffsetLabel(offset: number, unit: RelativeDateFilter['unit']): string;
+/**
+ * Format a `RelativeDateFilter` meta into a human-readable label.
+ *
+ * 1. First tries to reverse-match against `presetMetadata` so canonical
+ *    presets (Today, Last 7 days, This week, …) round-trip back to the
+ *    same wording the user originally clicked.
+ * 2. Falls back to a generated label for ad-hoc relative ranges that
+ *    aren't in the preset list (e.g., from the Relative tab's custom
+ *    From/To dropdowns).
+ *
+ * Returns null if the meta can't be sensibly labelled.
+ */
+export declare function getRelativeDateLabel(meta: RelativeDateFilter | undefined): string | null;
+export declare function relativeMetaEquals(a: RelativeDateFilter, b: RelativeDateFilter): boolean;
+export declare const presetMetadata: Record<string, RelativeDateFilter>;

package/dist/types/shared/analytics-protocol/runtime-schemas.d.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 import { SemaphorAnalyzeResult } from './analyze-result-types.js';
 import { SemaphorAnalyticsDiagnosticFeedback, SemaphorAnalyticsExecutionResult, SemaphorAnalyticsPopulation, SemaphorAnalyticsResult, SemaphorRelationshipDiagnostics } from './contracts.js';
-import { SemaphorDataAppCodegenSummary } from './data-app-codegen-summary.js';
 export * from './analytics-base-schemas.js';
 export { matrixResultSchema as semaphorMatrixResultSchema } from './matrix-window-contract.js';
 export declare const semaphorAnalyticsResultSchema: z.ZodType<SemaphorAnalyticsResult>;
@@ -3370,4 +3369,3 @@ export declare const analyticsExecutionEnvelopeSchema: z.ZodObject<{
 export declare const semaphorAnalyticsExecutionResultSchema: z.ZodType<SemaphorAnalyticsExecutionResult>;
 export declare const semaphorAnalyzeResultShape: z.ZodRawShape;
 export declare const semaphorAnalyzeResultSchema: z.ZodType<SemaphorAnalyzeResult>;
-export declare const semaphorDataAppCodegenSummarySchema: z.ZodType<SemaphorDataAppCodegenSummary>;

package/dist/types/shared/analytics-protocol/time-window-schema.d.ts

@@ -0,0 +1,314 @@
+import { z } from 'zod';
+/**
+ * Zod schemas for `SemaphorTimeWindow`, built from the shared rules in
+ * `time-window.ts`. `strict: true` rejects unknown keys; otherwise they are
+ * dropped, as tool argument parsing expects.
+ */
+export declare function semaphorTimeWindowSchemas(options?: {
+    strict?: boolean;
+}): {
+    relative: z.ZodEffects<z.ZodObject<{
+        kind: z.ZodOptional<z.ZodLiteral<"relative">>;
+        unit: z.ZodEnum<["second", "minute", "hour", "day", "week", "month", "quarter", "year"]>;
+        value: z.ZodNumber;
+        anchor: z.ZodOptional<z.ZodEnum<["now", "latest_available"]>>;
+        completeness: z.ZodOptional<z.ZodEnum<["include_partial", "complete_periods"]>>;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }>, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }> | z.ZodEffects<z.ZodObject<{
+        kind: z.ZodOptional<z.ZodLiteral<"relative">>;
+        unit: z.ZodEnum<["second", "minute", "hour", "day", "week", "month", "quarter", "year"]>;
+        value: z.ZodNumber;
+        anchor: z.ZodOptional<z.ZodEnum<["now", "latest_available"]>>;
+        completeness: z.ZodOptional<z.ZodEnum<["include_partial", "complete_periods"]>>;
+    }, "strict", z.ZodTypeAny, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }>, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }>;
+    calendar: z.ZodEffects<z.ZodObject<{
+        kind: z.ZodLiteral<"calendar">;
+        unit: z.ZodEnum<["day", "week", "month", "quarter", "year"]>;
+        period: z.ZodEnum<["this", "previous"]>;
+        toDate: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }>, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }> | z.ZodEffects<z.ZodObject<{
+        kind: z.ZodLiteral<"calendar">;
+        unit: z.ZodEnum<["day", "week", "month", "quarter", "year"]>;
+        period: z.ZodEnum<["this", "previous"]>;
+        toDate: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }>, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }>;
+    absolute: z.ZodEffects<z.ZodObject<{
+        kind: z.ZodLiteral<"absolute">;
+        start: z.ZodString;
+        end: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }>, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }> | z.ZodEffects<z.ZodObject<{
+        kind: z.ZodLiteral<"absolute">;
+        start: z.ZodString;
+        end: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }>, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }>;
+    timeWindow: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
+        kind: z.ZodOptional<z.ZodLiteral<"relative">>;
+        unit: z.ZodEnum<["second", "minute", "hour", "day", "week", "month", "quarter", "year"]>;
+        value: z.ZodNumber;
+        anchor: z.ZodOptional<z.ZodEnum<["now", "latest_available"]>>;
+        completeness: z.ZodOptional<z.ZodEnum<["include_partial", "complete_periods"]>>;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }>, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }> | z.ZodEffects<z.ZodObject<{
+        kind: z.ZodOptional<z.ZodLiteral<"relative">>;
+        unit: z.ZodEnum<["second", "minute", "hour", "day", "week", "month", "quarter", "year"]>;
+        value: z.ZodNumber;
+        anchor: z.ZodOptional<z.ZodEnum<["now", "latest_available"]>>;
+        completeness: z.ZodOptional<z.ZodEnum<["include_partial", "complete_periods"]>>;
+    }, "strict", z.ZodTypeAny, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }>, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }, {
+        value: number;
+        unit: "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+        kind?: "relative" | undefined;
+        anchor?: "now" | "latest_available" | undefined;
+        completeness?: "include_partial" | "complete_periods" | undefined;
+    }>, z.ZodEffects<z.ZodObject<{
+        kind: z.ZodLiteral<"calendar">;
+        unit: z.ZodEnum<["day", "week", "month", "quarter", "year"]>;
+        period: z.ZodEnum<["this", "previous"]>;
+        toDate: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }>, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }> | z.ZodEffects<z.ZodObject<{
+        kind: z.ZodLiteral<"calendar">;
+        unit: z.ZodEnum<["day", "week", "month", "quarter", "year"]>;
+        period: z.ZodEnum<["this", "previous"]>;
+        toDate: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }>, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }, {
+        kind: "calendar";
+        unit: "day" | "week" | "month" | "quarter" | "year";
+        period: "this" | "previous";
+        toDate?: boolean | undefined;
+    }>, z.ZodEffects<z.ZodObject<{
+        kind: z.ZodLiteral<"absolute">;
+        start: z.ZodString;
+        end: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }>, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }> | z.ZodEffects<z.ZodObject<{
+        kind: z.ZodLiteral<"absolute">;
+        start: z.ZodString;
+        end: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }>, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }, {
+        kind: "absolute";
+        start: string;
+        end: string;
+    }>]>;
+};

package/dist/types/shared/analytics-protocol/time-window.d.ts

@@ -0,0 +1,13 @@
+import { SemaphorRelativeTimeWindow, SemaphorTimeGrain } from './contracts.js';
+/** Units a calendar window ("this month", "previous quarter") can name. */
+export declare const SEMAPHOR_CALENDAR_TIME_WINDOW_UNITS: readonly ["day", "week", "month", "quarter", "year"];
+export declare const SEMAPHOR_CALENDAR_TIME_WINDOW_PERIODS: readonly ["this", "previous"];
+export declare const SEMAPHOR_TIME_WINDOW_ANCHORS: readonly ["now", "latest_available"];
+export declare const SEMAPHOR_TIME_WINDOW_COMPLETENESS: readonly ["include_partial", "complete_periods"];
+/** The largest rolling window per unit: ten years. */
+export declare const SEMAPHOR_TIME_WINDOW_MAX_VALUE: Readonly<Record<SemaphorTimeGrain, number>>;
+/**
+ * The anchor a rolling window counts back from. An omitted anchor means the
+ * latest available data; a saved card that should keep rolling states "now".
+ */
+export declare function resolveTimeWindowAnchor(timeWindow: Pick<SemaphorRelativeTimeWindow, 'anchor'>): 'now' | 'latest_available';

package/dist/types/shared/dashboard-authoring/matrix-delivery.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { CsvEncoding } from '../format-utils/exporters/csv-utils.js';
 import { MatrixConfig, MatrixExportLayout, MatrixExportRequest, MatrixExportRow, MatrixFailure, MatrixViewState } from '../analytics-protocol/index.js';
 import { ReportRuntimeContext } from '../report-runtime-context/index.js';
 export type MatrixExportContent = 'current' | 'all' | 'flat';
@@ -306,7 +307,7 @@ export declare function captureMatrixExport(input: {
             levelId: string;
             axis: "columns" | "rows";
             direction: "asc" | "desc";
-            nulls: "first" | "last";
+            nulls: "last" | "first";
         }[];
         rankings: readonly import('../analytics-protocol/index.js').MatrixRanking[];
         filters?: import('../../components/index.js').FilterGroup | undefined;
@@ -658,7 +659,7 @@ export declare function captureMatrixExport(input: {
             levelId: string;
             axis: "columns" | "rows";
             direction: "asc" | "desc";
-            nulls: "first" | "last";
+            nulls: "last" | "first";
         }[];
         rankings: readonly import('../analytics-protocol/index.js').MatrixRanking[];
         filters?: import('../../components/index.js').FilterGroup | undefined;
@@ -776,6 +777,8 @@ export declare function buildMatrixDeliveryEnvelope<TSource extends {
     reportContext: ReportRuntimeContext;
     delimiter: ',' | ';' | '\t';
     includeHeaders: boolean;
+    /** CSV only; absent lets the app resolve the dashboard's setting. */
+    csvEncoding?: CsvEncoding;
 }): TControls & {
     type: "card";
     dashboardId: string;
@@ -1090,7 +1093,7 @@ export declare function buildMatrixDeliveryEnvelope<TSource extends {
                     levelId: string;
                     axis: "columns" | "rows";
                     direction: "asc" | "desc";
-                    nulls: "first" | "last";
+                    nulls: "last" | "first";
                 }[];
                 rankings: readonly import('../analytics-protocol/index.js').MatrixRanking[];
                 filters?: import('../../components/index.js').FilterGroup | undefined;
@@ -1442,7 +1445,7 @@ export declare function buildMatrixDeliveryEnvelope<TSource extends {
                     levelId: string;
                     axis: "columns" | "rows";
                     direction: "asc" | "desc";
-                    nulls: "first" | "last";
+                    nulls: "last" | "first";
                 }[];
                 rankings: readonly import('../analytics-protocol/index.js').MatrixRanking[];
                 filters?: import('../../components/index.js').FilterGroup | undefined;
@@ -1456,6 +1459,7 @@ export declare function buildMatrixDeliveryEnvelope<TSource extends {
         includeHeaders: boolean;
         timezone: string;
         presentationExecutionSnapshot: import('../format-utils/index.js').PresentationExecutionSnapshot;
+        csvEncoding?: "utf-8-bom" | "utf-8" | undefined;
         acquisition?: "continuation" | undefined;
     };
 };

package/dist/types/shared/format-utils/exporters/csv-utils.d.ts

@@ -1,4 +1,38 @@
-import { CSVExportOptions } from '../types/index.js';
+/**
+ * The CSV file contract: the one place that decides how CSV rows become
+ * bytes. Every CSV file delivered to a person or system (browser downloads,
+ * chunked exports, Matrix exports, rendered Briefing attachments) is written
+ * through these functions. Writers decide which rows to write; this module
+ * decides the BOM, quoting and record separators. See "CSV file standard" in
+ * the format-utils README.
+ * IMPORTANT: No React or browser-specific imports allowed
+ */
+export declare const CSV_ENCODINGS: readonly ["utf-8-bom", "utf-8"];
+export type CsvEncoding = (typeof CSV_ENCODINGS)[number];
+/** Excel garbles non-ASCII text in a UTF-8 file without a BOM, so the BOM is the default. */
+export declare const DEFAULT_CSV_ENCODING: CsvEncoding;
+export declare const CSV_DELIMITERS: readonly [",", ";", "\t"];
+export type CsvDelimiter = (typeof CSV_DELIMITERS)[number];
+/** RFC 4180 record separator. Every record, including the last, ends with it. */
+export declare const CSV_RECORD_SEPARATOR = "\r\n";
+/** Content type of every delivered CSV file. */
+export declare const CSV_CONTENT_TYPE = "text/csv; charset=utf-8";
+export type CsvCell = string | number | null | undefined;
+/** Turn a raw record value into a cell: objects become JSON, not "[object Object]". */
+export declare function toCsvCell(value: unknown): CsvCell;
+export declare function parseCsvEncoding(value: unknown): CsvEncoding | undefined;
+export declare function parseCsvDelimiter(value: unknown): CsvDelimiter | undefined;
+/**
+ * The one precedence rule for a file's encoding: an explicit per-export
+ * choice, then the dashboard's setting, then the default. Boundaries reject
+ * invalid values before resolving; here they fall through.
+ */
+export declare function resolveCsvEncoding(input: {
+    requested?: unknown;
+    dashboardDefault?: unknown;
+}): CsvEncoding;
+/** What a file starts with. Only the writer of a file's first piece adds it. */
+export declare function csvFilePreamble(encoding: CsvEncoding): string;
 /** Protect explicitly textual cells before RFC escaping. Never apply this to
  * numeric operands (including exact numeric text); their sign is meaningful. */
 export declare function protectCSVText(value: string): string;
@@ -6,18 +40,15 @@ export declare function protectCSVText(value: string): string;
  * Escape a value for CSV output (RFC 4180 compliant)
  * Wraps in quotes if value contains delimiter, quotes, or newlines
  */
-export declare function escapeCSVValue(value: string | number | null | undefined, delimiter?: string): string;
-/**
- * Convert an array of values to a CSV row
- */
-export declare function arrayToCSVRow(values: (string | number | null | undefined)[], delimiter?: string): string;
-/**
- * Convert a 2D array to CSV string
- */
-export declare function arrayToCSV(rows: (string | number | null | undefined)[][], options?: Partial<CSVExportOptions>): string;
-/**
- * Convert an array of objects to CSV string
- */
-export declare function objectsToCSV(data: Record<string, unknown>[], options?: Partial<CSVExportOptions> & {
-    columns?: string[];
+export declare function escapeCSVValue(value: CsvCell, delimiter?: CsvDelimiter): string;
+/** One escaped record, ending with CSV_RECORD_SEPARATOR. */
+export declare function csvRecord(values: readonly CsvCell[], delimiter: CsvDelimiter): string;
+/** Escaped records, each ending with CSV_RECORD_SEPARATOR. */
+export declare function csvRecords(rows: readonly (readonly CsvCell[])[], delimiter: CsvDelimiter): string;
+/** A whole CSV file held in memory: preamble, optional header, then rows. */
+export declare function encodeCsvFile(input: {
+    header?: readonly CsvCell[];
+    rows: readonly (readonly CsvCell[])[];
+    delimiter: CsvDelimiter;
+    encoding: CsvEncoding;
 }): string;

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

@@ -1,3 +1,2 @@
-export { escapeCSVValue, protectCSVText, arrayToCSVRow, arrayToCSV, objectsToCSV, } from './csv-utils.js';
-export { formatTableForCSV, generateTableCSV } from './table-exporter.js';
-export { generatePivotHeaders, formatPivotDataRow, formatPivotTableForCSV, } from './pivot-exporter.js';
+export { CSV_ENCODINGS, DEFAULT_CSV_ENCODING, CSV_DELIMITERS, CSV_RECORD_SEPARATOR, CSV_CONTENT_TYPE, parseCsvEncoding, parseCsvDelimiter, resolveCsvEncoding, csvFilePreamble, toCsvCell, escapeCSVValue, protectCSVText, csvRecord, csvRecords, encodeCsvFile, } from './csv-utils.js';
+export type { CsvEncoding, CsvDelimiter, CsvCell } from './csv-utils.js';

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

@@ -1,3 +1,4 @@
+import { CsvDelimiter } from './exporters/csv-utils.js';
 import { PresentationExecutionSnapshot, PresentationScope } from './presentation-execution.js';
 export type FlatTableExportTotalsBehavior = 'sum' | 'avg' | 'count' | 'label';
 export type FlatTableExportTotalsRequest = {
@@ -21,5 +22,5 @@ export declare function buildFlatTableExportTotalsFooter(params: {
     snapshot: PresentationExecutionSnapshot;
     scope: PresentationScope;
     useFormattedValues: boolean;
-    delimiter: string;
+    delimiter: CsvDelimiter;
 }): string;

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

@@ -345,7 +345,7 @@ export declare function buildMatrixPrintTable(input: {
                 levelId: string;
                 axis: "columns" | "rows";
                 direction: "asc" | "desc";
-                nulls: "first" | "last";
+                nulls: "last" | "first";
             }[];
             rankings: readonly import('../analytics-protocol/index.js').MatrixRanking[];
             filters?: import('../../components/index.js').FilterGroup | undefined;
@@ -697,7 +697,7 @@ export declare function buildMatrixPrintTable(input: {
                 levelId: string;
                 axis: "columns" | "rows";
                 direction: "asc" | "desc";
-                nulls: "first" | "last";
+                nulls: "last" | "first";
             }[];
             rankings: readonly import('../analytics-protocol/index.js').MatrixRanking[];
             filters?: import('../../components/index.js').FilterGroup | undefined;

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

@@ -189,53 +189,11 @@ export interface ExportFormattingConfig {
     /** Ordered list of columns to include */
     visibleColumns: string[];
 }
-export interface CSVExportOptions {
-    delimiter: ',' | ';' | '\t';
-    includeHeaders: boolean;
-    lineEnding: '\n' | '\r\n';
-}
 export interface GroupByField {
     name: string;
     alias: string;
     label?: string;
 }
-export interface PivotByColumn {
-    name: string;
-    alias: string;
-    label?: string;
-}
-export interface ColumnHeaderNode {
-    name: string;
-    level: number;
-    colspan: number;
-    children?: ColumnHeaderNode[];
-    columnKey?: string;
-}
-export interface PivotExportConfig {
-    groupByColumns: GroupByField[];
-    pivotByColumns: PivotByColumn[];
-    columnHeadersTree: ColumnHeaderNode[];
-    columnHeaders: string[];
-    columnSubtotalMeta?: ColumnSubtotalMeta[];
-    includeSubtotals: boolean;
-    includeGrandTotal: boolean;
-    showRowTotals: boolean;
-}
-export interface ColumnSubtotalMeta {
-    columnKey: string;
-    label: string;
-    level: number;
-}
-export interface PivotCellData {
-    value: unknown;
-    formatted?: string;
-}
-export interface PivotRowData {
-    fieldValues: string[];
-    cells: Record<string, PivotCellData>;
-    isSubtotal?: boolean;
-    isGrandTotal?: boolean;
-}
 export interface FormatOptions {
     decimalPlaces?: number;
     useSuffix?: boolean;