react-semaphor 0.1.504 → 0.1.506

package/dist/types/shared/dashboard-authoring/protocol-adapter.d.ts

@@ -0,0 +1,7 @@
+import { SemaphorDashboardIntent } from '../analytics-protocol/index.js';
+import { DashboardPlan, DashboardPlanWarning } from './contracts.js';
+export type DashboardPlanFromProtocolResult = {
+    plan: DashboardPlan;
+    warnings: DashboardPlanWarning[];
+};
+export declare function dashboardPlanFromSemaphorDashboardIntent(intent: SemaphorDashboardIntent): DashboardPlanFromProtocolResult;

package/dist/types/shared/dashboard-authoring/source-matching.d.ts

@@ -0,0 +1,34 @@
+import { SemaphorFieldRef, SemaphorSourceRef } from '../analytics-protocol/index.js';
+import { DashboardPlanCard } from './contracts.js';
+export type DashboardAuthoringDatasetScopeIssue = 'invalid_dataset_count' | 'invalid_multi_dataset_scope';
+export type DashboardAuthoringDatasetScopeResult = {
+    ok: true;
+} | {
+    ok: false;
+    issue: DashboardAuthoringDatasetScopeIssue;
+};
+export type MaterializableDashboardAuthoringSource = Extract<SemaphorSourceRef, {
+    kind: 'semantic' | 'physical';
+}>;
+export declare function isSemaphorSourceRef(value: unknown): value is SemaphorSourceRef;
+export declare function isMaterializableDashboardAuthoringSource(value: unknown): value is MaterializableDashboardAuthoringSource;
+export declare function dashboardAuthoringSourceKey(source: SemaphorSourceRef): string;
+export declare function dashboardAuthoringSourcesReferToSameDataset(left: SemaphorSourceRef, right: SemaphorSourceRef): boolean;
+export declare function preferDashboardAuthoringSourceMetadata(current: SemaphorSourceRef, next: SemaphorSourceRef): SemaphorSourceRef;
+export declare function mergeDashboardAuthoringSources(sources: readonly SemaphorSourceRef[]): SemaphorSourceRef[];
+export declare function preferredDashboardAuthoringSource(sources: readonly SemaphorSourceRef[]): SemaphorSourceRef | undefined;
+export declare function dashboardAuthoringSourceFromField(field: SemaphorFieldRef | undefined, fallback?: SemaphorSourceRef): MaterializableDashboardAuthoringSource | undefined;
+export declare function resolveDashboardAuthoringSource({ explicitSource, field, defaultSource, fallbackSources, }: {
+    explicitSource?: unknown;
+    field?: SemaphorFieldRef;
+    defaultSource?: SemaphorSourceRef;
+    fallbackSources?: readonly SemaphorSourceRef[];
+}): MaterializableDashboardAuthoringSource | undefined;
+export declare function dashboardAuthoringFieldsReferToSameTarget(left: SemaphorFieldRef | undefined, right: SemaphorFieldRef | undefined): boolean;
+export declare function getDashboardAuthoringCardSource(card: Pick<DashboardPlanCard, 'analyticsIntent'>): SemaphorSourceRef | undefined;
+export declare function validateDashboardAuthoringDatasetScope({ datasets, requireAtLeastOne, }: {
+    datasets: readonly unknown[];
+    requireAtLeastOne: boolean;
+}): DashboardAuthoringDatasetScopeResult;
+export declare function dashboardAuthoringDatasetMatchesSource(dataset: unknown, source: SemaphorSourceRef | undefined): boolean;
+export declare function findDashboardAuthoringDatasetForSource(datasets: readonly SemaphorSourceRef[], source: SemaphorSourceRef | undefined): SemaphorSourceRef | undefined;

package/dist/types/shared/dashboard-authoring/temporal-bucket-authoring.d.ts

@@ -0,0 +1,19 @@
+import { SemaphorTimeGrain, TemporalBucketFormat } from '../analytics-protocol/contracts.js';
+import { ResolvedTemporalValueFormatPreferences } from '../value-format-preferences/index.js';
+export declare const AUTOMATIC_TEMPORAL_BUCKET_FORMAT: TemporalBucketFormat;
+export type TemporalBucketAuthoringOption = {
+    value: string;
+    label: string;
+    format?: TemporalBucketFormat;
+    custom?: true;
+};
+export type TemporalBucketAuthoringSelection = {
+    value: string;
+    customPattern: string;
+    format: TemporalBucketFormat;
+};
+export declare function previewTemporalBucketAuthoringFormat(format: TemporalBucketFormat, granularity: SemaphorTimeGrain, preferences?: ResolvedTemporalValueFormatPreferences): string;
+export declare function getTemporalBucketAuthoringOptions(granularity: SemaphorTimeGrain, preservedFormat?: TemporalBucketFormat, preferences?: ResolvedTemporalValueFormatPreferences): readonly TemporalBucketAuthoringOption[];
+export declare function getTemporalBucketAuthoringSelection(format: TemporalBucketFormat, granularity: SemaphorTimeGrain): TemporalBucketAuthoringSelection;
+export declare function resolveTemporalBucketAuthoringFormat(granularity: SemaphorTimeGrain, value: string, customPattern?: string): TemporalBucketFormat;
+export declare function reconcileTemporalBucketAuthoringFormat(format: TemporalBucketFormat, granularity: SemaphorTimeGrain): TemporalBucketFormat;

package/dist/types/shared/dashboard-authoring/temporal-result-owner.d.ts

@@ -0,0 +1,25 @@
+export type TemporalResultOwner = 'config' | 'freeform' | 'none';
+export declare const SEMAPHOR_CARTESIAN_CHART_TYPES: readonly ["bar", "horizontalBar", "line", "area", "stackedArea", "combo", "stackedBar", "stackedLine"];
+export type SemaphorCartesianChartType = (typeof SEMAPHOR_CARTESIAN_CHART_TYPES)[number];
+export declare function isSemaphorCartesianChartType(value: string | null | undefined): value is SemaphorCartesianChartType;
+export declare function supportsCanonicalDashboardTemporalResult(value: string | null | undefined): boolean;
+export type TemporalResultOwnerInput = {
+    /**
+     * Result of the runtime's executable-config validation. The ownership
+     * module deliberately does not reinterpret card-config structure.
+     */
+    hasExecutableConfig: boolean;
+    sql?: string | null;
+    /**
+     * Python after the existing execution normalizer has converted the inert
+     * editor template to an empty string. This module treats non-empty Python as
+     * opaque free-form execution and never parses its contents.
+     */
+    normalizedPython?: string | null;
+};
+/**
+ * Selects the only result owner eligible for canonical temporal metadata.
+ * Active SQL or normalized Python always owns the result, even when a card
+ * retains config from a prior authoring mode.
+ */
+export declare function resolveTemporalResultOwner(input: TemporalResultOwnerInput): TemporalResultOwner;

package/dist/types/shared/dashboard-authoring/validators.d.ts

@@ -0,0 +1,3 @@
+import { DashboardAuthoringValidationResult, DashboardChangePlan, DashboardPlan } from './contracts.js';
+export declare function validateDashboardPlan(plan: DashboardPlan): DashboardAuthoringValidationResult;
+export declare function validateDashboardChangePlan(plan: DashboardChangePlan): DashboardAuthoringValidationResult;

package/dist/types/shared/dirty-check/index.d.ts

@@ -0,0 +1,2 @@
+export { useDebouncedDirtyCheck } from '../../lib/hooks/use-debounced-dirty-check.js';
+export { normalizeDashboardForDirtyCheck, serializeDashboardForDirtyCheck, } from '../../lib/dashboard/normalize-dashboard-for-dirty-check.js';

package/dist/types/shared/filter-native-data-type.d.ts

@@ -0,0 +1,59 @@
+type NativeDataTypeFieldMeta = {
+    name?: string;
+    qualifiedFieldName?: string;
+    nativeDataType?: string;
+};
+type NativeDataTypeCarrier = {
+    nativeDataType?: string;
+    fieldMeta?: NativeDataTypeFieldMeta;
+};
+export type NativeDataTypeDefinition = NativeDataTypeCarrier & {
+    column: string;
+};
+type NativeDataTypeValue = NativeDataTypeCarrier & {
+    name: string;
+};
+type NativeDataTypeFilterDefinition = NativeDataTypeDefinition & {
+    id: string;
+};
+type NativeDataTypeFilterValue = NativeDataTypeValue & {
+    filterId: string;
+};
+/**
+ * Resolves exact database type metadata for one filter field without falling
+ * back to normalized analytics/UI datatypes. Metadata is eligible only when
+ * its carrier names the field being materialized; the authored definition is
+ * authoritative over a matching runtime value.
+ */
+export declare function resolveFilterFieldNativeDataType({ fieldName, definition, value, }: {
+    fieldName: string;
+    definition?: NativeDataTypeDefinition;
+    value?: NativeDataTypeValue;
+}): string | undefined;
+/**
+ * Materializes one coherent native-type projection on a runtime filter value.
+ * The top-level value is canonical transport metadata; when field metadata is
+ * present, its native type is kept in sync for historical consumers.
+ */
+export declare function materializeFilterValueNativeDataType<TFilterValueShape extends NativeDataTypeValue>({ definition, value, sourceValue, }: {
+    definition?: NativeDataTypeDefinition;
+    value: TFilterValueShape;
+    sourceValue?: NativeDataTypeValue;
+}): TFilterValueShape;
+/**
+ * Reconciles runtime filter values with their authored definitions at any
+ * execution or hydration seam. Values without a matching definition remain
+ * untouched, while matching values cross the same single-value materializer
+ * used by interactive and Dashboard Input paths.
+ */
+export declare function materializeFilterValuesNativeDataType<TFilterDefinitionShape extends NativeDataTypeFilterDefinition, TFilterValueShape extends NativeDataTypeFilterValue>({ filterDefinitions, filterValues, }: {
+    filterDefinitions: readonly TFilterDefinitionShape[] | undefined;
+    filterValues: TFilterValueShape[];
+}): TFilterValueShape[];
+/**
+ * Projects one coherent exact-type view for a filter definition before it
+ * crosses a transport or query-identity Adapter. Ineligible nested metadata is
+ * removed without discarding unrelated field metadata.
+ */
+export declare function materializeFilterDefinitionNativeDataType<TDefinitionShape extends NativeDataTypeDefinition>(definition: TDefinitionShape): TDefinitionShape;
+export {};

package/dist/types/shared/format-utils/aggregate-table-row-presentation.d.ts

@@ -0,0 +1,85 @@
+/**
+ * React-free aggregate-table row presentation policy shared by browser and
+ * delivery adapters. Canonical tuple values and row metadata remain identity;
+ * this module owns authoritative group keys and group-cell placement.
+ */
+export { PDF_GROUP_CONTINUATION_CLASS as AGGREGATE_PDF_CONTINUATION_CLASS, } from './grouped-table-presentation.js';
+export interface AggregateSubtotalLabelInput {
+    aggregateFunction: string;
+    customLabel?: string;
+    levelValue: unknown;
+    formatValue?: (value: unknown) => string;
+}
+export declare const AGGREGATE_TOTAL_MEMBER_MARKER: "__TOTAL__";
+export interface AggregateTablePresentationContext {
+    groupColumnKeys: string[];
+    rowAggregates: Array<{
+        function: string;
+        groupLevel: string;
+        label?: string;
+    }>;
+}
+export type AggregateGroupCellPlacement = 'value' | 'label' | 'empty';
+export interface AggregateGroupCellPresentation<T = string> {
+    columnKey: string;
+    text: T | string;
+    placement: AggregateGroupCellPlacement;
+    colSpan: number;
+}
+export interface AggregateGroupRowPresentation<T = string> {
+    kind: 'data' | 'subtotal' | 'grand-total';
+    cells: AggregateGroupCellPresentation<T>[];
+}
+export interface AggregateTablePresentationColumnKeyMap {
+    byRole: Readonly<{
+        groupby?: Readonly<Record<string, {
+            rawKey: string;
+            outputKey?: string;
+        }>>;
+    }>;
+}
+export declare function isAggregateTotalMemberMarker(value: unknown): value is typeof AGGREGATE_TOTAL_MEMBER_MARKER;
+/**
+ * Resolves saved field identity into the physical result keys used by rows.
+ * Missing groupByColumns is a valid metric-only aggregate-table shape.
+ */
+export declare function resolveAggregateTablePresentationContext(input: {
+    groupByColumns?: readonly unknown[];
+    rowAggregates?: readonly unknown[];
+    columnKeyMap?: AggregateTablePresentationColumnKeyMap;
+}): AggregateTablePresentationContext;
+export declare function formatAggregateSubtotalLabel(input: AggregateSubtotalLabelInput): string;
+export declare function formatAggregateGrandTotalLabel(aggregateFunction: string, customLabel?: string): string;
+/**
+ * Returns whether an aggregate group value starts a new visible group at its
+ * hierarchy level. A nested value repeats only when its complete parent prefix
+ * also repeats. Subtotals and grand totals are presentation boundaries.
+ */
+export declare function shouldPresentAggregateGroupValue(input: {
+    row: Record<string, unknown>;
+    previousRow?: Record<string, unknown>;
+    context: AggregateTablePresentationContext;
+    columnKey: string;
+}): boolean;
+/**
+ * Formats one physical aggregate group cell. Row metadata alone determines
+ * subtotal/grand-total ownership; null is always passed to the value formatter
+ * as a genuine blank member.
+ */
+export declare function presentAggregateGroupRow<T = string>(input: {
+    row: Record<string, unknown>;
+    context: AggregateTablePresentationContext;
+    formatValue: (value: unknown, columnKey: string) => T;
+    formatLabelValue?: (value: unknown, columnKey: string) => string;
+}): AggregateGroupRowPresentation<T>;
+export declare function formatAggregateGroupCell(input: {
+    row: Record<string, unknown>;
+    context: AggregateTablePresentationContext;
+    columnKey: string;
+    formatValue: (value: unknown, columnKey: string) => string;
+}): string;
+export declare function formatAggregateGroupRow(input: {
+    row: Record<string, unknown>;
+    context: AggregateTablePresentationContext;
+    formatValue: (value: unknown, columnKey: string) => string;
+}): string[];

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

@@ -0,0 +1,19 @@
+/**
+ * Shared CSV export routing and safety policy.
+ *
+ * These values are product policy, not deployment configuration. Keep them in
+ * this React-free module so the dashboard runtime and semaphor-app compile
+ * against the same limits. Workers should import only the policy they enforce.
+ */
+/** Largest complete CSV that may use the direct, immediate export path. */
+export declare const DIRECT_CSV_EXPORT_MAX_ROWS = 10000;
+/** Maximum rows in a requested full-dataset CSV. */
+export declare const FULL_DATASET_CSV_EXPORT_MAX_ROWS = 1000000;
+/** Wide Matrix output, including label/header and blank rectangular positions. */
+export declare const MATRIX_EXPORT_MAX_CELLS = 5000000;
+/** Matrix CSV/XLSX only: cumulative encoded chunks, including headers. */
+export declare const MATRIX_EXPORT_MAX_ENCODED_BYTES: number;
+/** Matrix CSV/XLSX only: the actual finalized artifact size. */
+export declare const MATRIX_EXPORT_MAX_ARTIFACT_BYTES: number;
+/** Return true when a complete CSV must use the asynchronous chunked path. */
+export declare function requiresChunkedCsvExport(totalRows: number): boolean;

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

@@ -0,0 +1,23 @@
+import { CSVExportOptions } from '../types/index.js';
+/** 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;
+/**
+ * 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[];
+}): string;

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

@@ -0,0 +1,3 @@
+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';

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

@@ -0,0 +1,13 @@
+import { PivotExportConfig, PivotRowData, ExportFormattingConfig } from '../types/index.js';
+/**
+ * Generate multi-level headers for pivot table
+ */
+export declare function generatePivotHeaders(config: PivotExportConfig): string[][];
+/**
+ * Format a pivot table data row for CSV export
+ */
+export declare function formatPivotDataRow(row: PivotRowData, pivotConfig: PivotExportConfig, formattingConfig: ExportFormattingConfig): string[];
+/**
+ * Format pivot table data for CSV export
+ */
+export declare function formatPivotTableForCSV(data: PivotRowData[], pivotConfig: PivotExportConfig, formattingConfig: ExportFormattingConfig): string[];

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

@@ -0,0 +1,10 @@
+import { ExportFormattingConfig } from '../types/index.js';
+/**
+ * Format table data for CSV export
+ * Returns array of CSV rows (strings)
+ */
+export declare function formatTableForCSV(data: Record<string, unknown>[], config: ExportFormattingConfig): string[];
+/**
+ * Generate complete CSV content for a table
+ */
+export declare function generateTableCSV(data: Record<string, unknown>[], config: ExportFormattingConfig, lineEnding?: '\n' | '\r\n'): string;

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

@@ -0,0 +1,25 @@
+import { PresentationExecutionSnapshot, PresentationScope } from './presentation-execution.js';
+export type FlatTableExportTotalsBehavior = 'sum' | 'avg' | 'count' | 'label';
+export type FlatTableExportTotalsRequest = {
+    source: 'documentFlatTable';
+    columns: Array<{
+        fieldId: string;
+        role: 'detail' | 'groupby' | 'metric';
+        behavior: FlatTableExportTotalsBehavior;
+        /** Stable identity for one authored metric instance. */
+        metricAlias?: string;
+        label?: string;
+    }>;
+};
+export type FlatTableExportTotalsByColumnId = Record<string, string | number | null>;
+export declare function parseFlatTableExportTotalsRequest(input: unknown, path?: string): FlatTableExportTotalsRequest;
+export declare function parseFlatTableExportTotalsByColumnId(input: unknown, path?: string): FlatTableExportTotalsByColumnId;
+export declare function buildFlatTableExportTotalsFooter(params: {
+    totalsByColumnId: FlatTableExportTotalsByColumnId;
+    visibleColumns: readonly string[];
+    labelColumnKey?: string;
+    snapshot: PresentationExecutionSnapshot;
+    scope: PresentationScope;
+    useFormattedValues: boolean;
+    delimiter: string;
+}): string;

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

@@ -0,0 +1,22 @@
+import { ColumnSettings, ExportFormattingConfig } from '../types/index.js';
+export type CellAbsencePresentation = {
+    emptyText: string;
+    nullText: string;
+};
+/**
+ * Format a cell value for export based on column settings
+ * This is the main entry point for formatting individual cells
+ */
+export declare function formatCellValue(value: unknown, columnSettings: ColumnSettings | undefined, config: {
+    useFormattedValues: boolean;
+    timezone: string;
+    locale: string;
+    browserTimezone?: string;
+    isSqlCard?: boolean;
+    absence?: CellAbsencePresentation;
+}): string;
+/**
+ * Format a row of data for export
+ * Returns values in the order specified by visibleColumns
+ */
+export declare function formatRowForExport(row: Record<string, unknown>, config: ExportFormattingConfig): string[];

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

@@ -0,0 +1,62 @@
+/**
+ * Date formatting utilities with timezone support
+ * IMPORTANT: No React imports allowed in this file
+ *
+ * Uses date-fns and date-fns-tz for consistent behavior in browser and Node.js
+ *
+ * This module provides the canonical date formatting functions used by:
+ * - data-table component
+ * - pivot-table component
+ * - aggregated-table component
+ * - Lambda CSV export (chunk-processor)
+ */
+/**
+ * Resolve which timezone to use for formatting
+ * Priority: column-specific > context timezone
+ */
+export declare function resolveTimezone(columnTimezone: string | undefined, contextTimezone: string): string;
+/**
+ * Get timezone abbreviation (e.g., "EST", "PST")
+ */
+export declare function getTimezoneAbbreviation(timezone: string, date?: Date): string;
+/**
+ * Get friendly timezone name (e.g., "Eastern Time")
+ */
+export declare function getTimezoneName(timezone: string): string;
+/**
+ * Parse a date string with source timezone interpretation
+ *
+ * @param dateString - The date string to parse
+ * @param sourceTimezone - How to interpret the date:
+ *   - 'auto': If date has Z/offset, use it; otherwise assume UTC
+ *   - 'UTC': Always interpret as UTC
+ *   - specific TZ: Use explicit timezone if present, otherwise assume source TZ
+ */
+export declare function parseWithSourceTimezone(dateString: string, sourceTimezone?: string): Date;
+/**
+ * Format a date with custom format and optional timezone
+ * This is the production implementation used by data-table and pivot-table.
+ *
+ * @param dateString - The date string to format
+ * @param formatPattern - The format pattern (e.g., 'MM/dd/yyyy', 'yyyy-MM-dd HH:mm')
+ *   Defaults to MM/dd/yyyy when missing or empty.
+ * @param displayTimezone - Optional timezone to display the date in (e.g., 'America/Chicago')
+ * @param sourceTimezone - How to interpret the input date (default: 'auto')
+ * @returns Formatted date string
+ *
+ * @example
+ * // Basic formatting
+ * formatDate('2024-01-15T10:30:00Z', 'MM/dd/yyyy') // '01/15/2024'
+ *
+ * // With display timezone
+ * formatDate('2024-01-15T10:30:00Z', 'MM/dd/yyyy HH:mm', 'America/Chicago') // '01/15/2024 04:30'
+ */
+export declare const formatDate: (dateString: string | null | undefined, formatPattern: string | undefined, displayTimezone?: string, sourceTimezone?: string) => string;
+/**
+ * Format relative time using date-fns (e.g., "2 days ago")
+ *
+ * @param dateString - The date string to format
+ * @param sourceTimezone - How to interpret the input date (default: 'auto')
+ * @returns Relative time string
+ */
+export declare const formatRelativeTime: (dateString: string | null | undefined, sourceTimezone?: string) => string;

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

@@ -0,0 +1,2 @@
+import { DurationFormatOptions } from '../types/index.js';
+export declare function formatDuration(value: number | string | null | undefined, options?: DurationFormatOptions): string;

package/dist/types/shared/format-utils/formatters/exact-number.d.ts

@@ -0,0 +1 @@
+export declare function formatExactDecimal(value: string, format: Intl.NumberFormat): string;

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

@@ -0,0 +1,6 @@
+export { formatNumber, formatCurrency, formatPercent, formatScientific, formatNumericCanonical, formatNumberWithColumnSettings, formatNumberCustom, } from './number-formatter.js';
+export { formatDuration } from './duration-formatter.js';
+export { formatMetricComparison, type FormattedMetricComparison, type FormattedMetricComparisonPart, type FormatMetricComparisonOptions, type MetricComparisonDisplayMode, } from './metric-comparison-formatter.js';
+export { formatDate, formatRelativeTime, resolveTimezone, getTimezoneAbbreviation, getTimezoneName, parseWithSourceTimezone, } from './date-formatter.js';
+export { formatCellValue, formatRowForExport } from './cell-formatter.js';
+export type { CellAbsencePresentation } from './cell-formatter.js';

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

@@ -0,0 +1,35 @@
+import { MatrixPath, MatrixPresentation, MatrixWindow, SemaphorScalarValue, SemaphorValueFormat } from '../../analytics-protocol/index.js';
+import { ReportRuntimeContext } from '../../report-runtime-context/index.js';
+/** Null hierarchy members stay identifiable even when null cells render blank. */
+export declare function matrixMemberLabel(path: MatrixPath, levels?: ReadonlyMap<string, (value: SemaphorScalarValue) => string>): string;
+export declare function matrixTotalLabel(role: 'member' | 'subtotal' | 'grand_total', text: string, authored?: string): string;
+export declare function matrixAxisLabel(path: MatrixPath, role: 'member' | 'subtotal' | 'grand_total', totals: MatrixPresentation['totals']['rows'], levels?: ReadonlyMap<string, (value: SemaphorScalarValue) => string>): string;
+/** Acquired absence is presentation; pending/error states remain the caller's UI. */
+export declare function matrixCellText(cell: {
+    kind: 'value';
+    value: SemaphorScalarValue;
+} | {
+    kind: 'null' | 'empty';
+}, format: ((value: SemaphorScalarValue) => string) | undefined, absence: MatrixPresentation['absence']): string;
+/** Pure hierarchy-column projection. Callers supply their own repetition boundary. */
+export declare function matrixLevelLabels(input: {
+    path: MatrixPath;
+    role: 'member' | 'subtotal' | 'grand_total';
+    levelCount: number;
+    repeatLabels: boolean;
+    previousPath?: MatrixPath;
+}): Array<{
+    path: MatrixPath;
+    visible: boolean;
+    total: boolean;
+}>;
+/** 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;
+export declare function prepareMatrixFormatting(descriptors: MatrixWindow['descriptors'], presentation: MatrixPresentation, report: ReportRuntimeContext): {
+    levels: Map<string, (value: SemaphorScalarValue) => string>;
+    measures: Map<string, (value: SemaphorScalarValue) => string>;
+    measureSemantics: Map<string, {
+        isNumeric: boolean;
+        hasTextAffixes: boolean;
+    }>;
+};

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

@@ -0,0 +1,22 @@
+import { MetricComparisonEvaluation } from '../../analytics-protocol/index.js';
+import { CanonicalFormatSpec } from '../types/index.js';
+export type MetricComparisonDisplayMode = 'difference' | 'percent_change' | 'both' | 'ratio';
+export type FormattedMetricComparisonPart = {
+    value: number | null;
+    text: string | null;
+};
+export type FormattedMetricComparison = {
+    mode: MetricComparisonDisplayMode;
+    current: FormattedMetricComparisonPart;
+    comparison: FormattedMetricComparisonPart;
+    difference?: FormattedMetricComparisonPart;
+    percentChange?: FormattedMetricComparisonPart;
+    ratio?: FormattedMetricComparisonPart;
+};
+export type FormatMetricComparisonOptions = {
+    displayMode: MetricComparisonDisplayMode;
+    metricFormat?: CanonicalFormatSpec;
+    locale?: string;
+    precision?: number;
+};
+export declare function formatMetricComparison(evaluation: MetricComparisonEvaluation, options: FormatMetricComparisonOptions): FormattedMetricComparison;

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

@@ -0,0 +1,47 @@
+import { FormatOptions, NumberFormatOptions, NumericCanonicalFormat } from '../types/index.js';
+import { ExactNumericValue } from '../../analytics-protocol/scalar-value.js';
+type NumericValue = number | ExactNumericValue;
+/**
+ * Format a number with locale-aware formatting
+ */
+export declare function formatNumber(value: NumericValue | null | undefined, options?: NumberFormatOptions): string;
+/**
+ * Format a number as currency
+ */
+export declare function formatCurrency(value: NumericValue | null | undefined, options?: NumberFormatOptions): string;
+/**
+ * Format a number as percentage
+ * Note: Intl.NumberFormat percent style multiplies by 100, so we may need to divide
+ */
+export declare function formatPercent(value: NumericValue | null | undefined, options?: NumberFormatOptions & {
+    alreadyPercent?: boolean;
+}): string;
+/**
+ * Format a number in scientific notation
+ */
+export declare function formatScientific(value: NumericValue | null | undefined, options?: NumberFormatOptions): string;
+export declare function formatNumericCanonical(value: number | ExactNumericValue | null | undefined, format: NumericCanonicalFormat): string;
+/**
+ * Format a number value based on ColumnSettings.numberFormat
+ * Used for export formatting
+ */
+export declare function formatNumberWithColumnSettings(value: number | ExactNumericValue | null | undefined, numberFormat: {
+    style?: 'decimal' | 'currency' | 'percent' | 'scientific';
+    currency?: string;
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    percentValueMode?: 'fraction' | 'whole';
+    scale?: number;
+    compact?: boolean;
+    negativeStyle?: 'minus' | 'parentheses';
+    prefix?: string;
+    suffix?: string;
+} | undefined, defaultLocale?: string): string;
+/**
+ * Legacy wrapper for backward compatibility with existing code
+ * @deprecated Use formatNumber, formatCurrency, or formatPercent directly
+ */
+export declare function formatNumberCustom(value: number, type: 'number' | 'currency' | 'percent' | 'scientific', options?: FormatOptions): string;
+export {};

package/dist/types/shared/format-utils/grouped-table-presentation.d.ts

@@ -0,0 +1,15 @@
+export declare const PDF_GROUP_CONTINUATION_CLASS = "pdf-group-continuation";
+/**
+ * Show a label when its canonical hierarchy prefix changes. Compare only
+ * adjacent rows and never suppress across subtotal or grand-total boundaries.
+ * Adapters supply canonical values, not formatted labels or serialized keys.
+ */
+export declare function shouldPresentGroupedTableValue<T extends {
+    isSubtotal?: unknown;
+    isGrandTotal?: unknown;
+}>(input: {
+    row: T;
+    previousRow?: T;
+    levelIndex: number;
+    getValue: (row: T, index: number) => unknown;
+}): boolean;

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

@@ -0,0 +1,38 @@
+/**
+ * Shared Format Utilities
+ *
+ * IMPORTANT: This module has ZERO React dependencies.
+ * It can be safely imported in:
+ * - Browser (react-semaphor components)
+ * - Node.js (semaphor-app API routes)
+ * - AWS Lambda (export processor)
+ *
+ * Import paths:
+ * - react-semaphor (internal): import { formatNumber } from '@/shared/format-utils'
+ * - semaphor-app: import { formatNumber } from 'react-semaphor'
+ * - Lambda: import { formatNumber } from 'react-semaphor/format-utils'
+ */
+export * from './types/index.js';
+export * from './formatters/index.js';
+export * from './exporters/index.js';
+export * from './export-policy.js';
+export * from './matrix-continuation.js';
+export * from './matrix-export-presentation.js';
+export { fromSemanticFormat } from './semantic-format.js';
+export type * from './table-structure.js';
+export * from './pdf-export-policy.js';
+export * from './pdf-delivery.js';
+export * from './numeric-presentation.js';
+export * from './presentation-execution.js';
+export * from './temporal-bucket-format-policy.js';
+export * from './temporal-bucket.js';
+export * from './raw-temporal.js';
+export * from './flat-table-export-totals.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';
+export { resolveMetricResultAlias } from '../analytics-protocol/metric-comparison.js';
+export * from './pivot-header-presentation.js';
+export * from './pivot-result-identity.js';
+export * from './pivot-result-contract-expectations.js';
+export * from './pivot-result-lifecycle.js';

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

@@ -0,0 +1,6 @@
+/**
+ * Accepts ordinary JSON object records, including records constructed in a
+ * different JavaScript realm. Transport parsers must not compare a foreign
+ * realm's Object.prototype by identity.
+ */
+export declare function isPlainJsonRecord(value: unknown): value is Record<string, unknown>;