react-semaphor 0.1.449 → 0.1.454

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

@@ -54,6 +54,8 @@ export declare function arrayToCSV(rows: (string | number | null | undefined)[][
  */
 export declare function arrayToCSVRow(values: (string | number | null | undefined)[], delimiter?: string): string;
 
+export declare function assertRawTemporalChunkClassificationAgreement(inputs: readonly unknown[]): void;
+
 export declare function buildFlatTableExportTotalsFooter(params: {
     totalsByColumnId: FlatTableExportTotalsByColumnId;
     visibleColumns: readonly string[];
@@ -75,7 +77,7 @@ declare type CalendarContext = {
 
 export declare type CanonicalDurationUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
 
-export declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | DurationCanonicalFormat | StringCanonicalFormat | TemporalBucketFormat;
+export declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | RawTemporalFormat | DurationCanonicalFormat | StringCanonicalFormat | TemporalBucketFormat;
 
 declare type CanonicalPivotResultBase = {
     columns: SemaphorResultColumn[];
@@ -95,6 +97,11 @@ export declare type CanonicalPivotResultState = 'loaded_empty' | 'loaded_valid';
 
 export declare type CanonicalPivotResultTransport = LoadedEmptyPivotResult | LoadedValidPivotResult;
 
+export declare function classifyDeclaredSqlTemporalColumn(input: {
+    columnKey: string;
+    values: readonly (string | null)[];
+}): SqlTemporalColumnClassification;
+
 export declare interface ColorRange {
     min: number;
     max: number;
@@ -163,6 +170,13 @@ export declare function createCanonicalPivotResultTransport(input: {
     columnMetadata?: Readonly<Record<string, PivotResultColumnClassification | undefined>>;
 }): CanonicalPivotResultTransport;
 
+export declare function createPresentationExecutionSnapshot(input: {
+    reportContext: ReportRuntimeContext;
+    resolvedFormats: readonly ResolvedPresentationEntry[];
+}): PresentationExecutionSnapshot;
+
+export declare function createRawTemporalChunkClassificationEvidence(classifications: ReadonlyMap<string, SqlTemporalColumnClassification>): RawTemporalChunkClassificationEvidence;
+
 export declare interface CSVExportOptions {
     delimiter: ',' | ';' | '\t';
     includeHeaders: boolean;
@@ -197,6 +211,8 @@ export declare interface DateFormatOptions {
     locale?: string;
 }
 
+export declare const DEFAULT_RESOLVED_TEMPORAL_STYLE_SET: ResolvedTemporalStyleSet;
+
 /**
  * Derives the authored identity expectations stored in a canonical pivot
  * lifecycle contract. Producers and cache-compatibility consumers must use
@@ -278,6 +294,12 @@ export declare function findResolvedNumericFormat(input: {
     target: NumericPresentationTarget;
 }): NumericCanonicalFormat | undefined;
 
+export declare function findResolvedRawTemporalFormat(input: {
+    snapshot: PresentationExecutionSnapshot;
+    scope: PresentationScope;
+    target: RawTemporalPresentationTarget;
+}): ResolvedRawTemporalFormat | undefined;
+
 export declare function findResolvedTemporalBucketFormat(input: {
     snapshot: PresentationExecutionSnapshot;
     scope: PresentationScope;
@@ -426,6 +448,13 @@ export declare function formatPivotDataRow(row: PivotRowData, pivotConfig: Pivot
  */
 export declare function formatPivotTableForCSV(data: PivotRowData[], pivotConfig: PivotExportConfig, formattingConfig: ExportFormattingConfig): string[];
 
+/** Strict one-off convenience; row loops should prepare once per column. */
+export declare function formatRawTemporalValue(input: {
+    value: string | null;
+    metadata: RawTemporalValueMetadata;
+    format: ResolvedRawTemporalFormat;
+}): RawTemporalFormatResult;
+
 /**
  * Format relative time using date-fns (e.g., "2 days ago")
  *
@@ -555,6 +584,12 @@ declare type MetricResultAliasInput = {
     expression?: string;
 };
 
+export declare class MissingResolvedRawTemporalFormatError extends Error {
+    readonly code = "missing_resolved_raw_temporal_format";
+    readonly deliveryBlocking = true;
+    constructor(columnKey: string);
+}
+
 declare type MonthAlignedFiscalCalendar = {
     kind: 'month_aligned';
     yearStartMonth: number;
@@ -650,10 +685,17 @@ export declare function parsePresentationExecutionSnapshot(input: unknown): Pres
 
 export declare function parsePresentationScope(input: unknown, path?: string): PresentationScope;
 
+export declare function parseRawTemporalChunkClassificationEvidence(input: unknown): RawTemporalChunkClassificationEvidence;
+
+/** Strictly parses one raw temporal descriptor at a result boundary. */
+export declare function parseRawTemporalValueMetadata(input: unknown): RawTemporalValueMetadata;
+
 export declare function parseResolvedNumericCanonicalFormat(input: unknown): NumericCanonicalFormatParseResult;
 
 export declare function parseResolvedPresentationEntries(input: unknown): ResolvedPresentationEntry[];
 
+export declare function parseResolvedRawTemporalFormat(input: unknown): ResolvedRawTemporalFormat;
+
 export declare function parseResolvedTemporalBucketFormat(input: unknown): ResolvedTemporalBucketFormatParseResult;
 
 export declare function parseTemporalBucketValue(value: TemporalBucketValue, metadata: TemporalBucketMetadata): TemporalBucketValueParseResult;
@@ -753,6 +795,14 @@ export declare interface PivotRowData {
     isGrandTotal?: boolean;
 }
 
+/** Strictly prepared per-column formatter for repeated cell rendering. */
+export declare type PreparedRawTemporalFormatter = (value: string | null) => RawTemporalFormatResult;
+
+export declare function prepareRawTemporalFormatter(input: {
+    metadata: RawTemporalValueMetadata;
+    format: ResolvedRawTemporalFormat;
+}): PreparedRawTemporalFormatter;
+
 /**
  * Formats one physical aggregate group cell. Row metadata alone determines
  * subtotal/grand-total ownership; null is always passed to the value formatter
@@ -766,10 +816,17 @@ export declare function presentAggregateGroupRow<T = string>(input: {
 }): AggregateGroupRowPresentation<T>;
 
 export declare type PresentationExecutionSnapshot = {
+    version: 1;
     reportContext: ReportRuntimeContext;
     resolvedFormats: ResolvedPresentationEntry[];
 };
 
+export declare class PresentationExecutionSnapshotError extends Error {
+    readonly code = "invalid_presentation_execution_snapshot";
+    readonly deliveryBlocking = true;
+    constructor(message: string);
+}
+
 export declare type PresentationScope = {
     dashboardId: string;
     cardId?: string;
@@ -804,6 +861,66 @@ export declare interface QueryColumnKeyMapEntry {
 
 export declare type QueryColumnKeyRole = 'groupby' | 'metric' | 'pivotby' | 'detail';
 
+export declare type RawTemporalChunkClassificationEvidence = {
+    version: 1;
+    columns: Record<string, RawTemporalChunkClassificationStatus>;
+};
+
+export declare type RawTemporalChunkClassificationStatus = 'empty' | 'invalid_only' | RawTemporalValueKind;
+
+/** Normalized authored input for an ungrouped temporal result column. */
+export declare type RawTemporalFormat = {
+    type: 'raw_temporal';
+    /** Authored display timezone; `auto` uses the resolved calendar timezone. */
+    timezone?: string;
+    /** Authored source timezone; `auto` means UTC for timezone-less values. */
+    sourceTimezone?: string;
+    presentation: {
+        mode: 'auto';
+    } | {
+        mode: 'pattern';
+        dialect: RawTemporalPatternDialect;
+        pattern: string;
+    };
+};
+
+export declare class RawTemporalFormatContractError extends Error {
+    readonly code: 'invalid_raw_temporal_format' | 'mixed_sql_temporal_semantics';
+    constructor(code: RawTemporalFormatContractError['code'], message: string);
+}
+
+export declare type RawTemporalFormatResult = {
+    ok: true;
+    text: string;
+    status: 'formatted' | 'empty';
+} | {
+    ok: false;
+    text: string;
+    diagnostic: {
+        code: 'invalid_raw_temporal_value' | 'out_of_range_raw_temporal_value';
+        message: string;
+    };
+};
+
+export declare type RawTemporalPatternDialect = 'semaphor_tokens' | 'date_fns';
+
+export declare type RawTemporalPresentationTarget = {
+    kind: 'column';
+    columnKey: string;
+};
+
+/** Authoritative meaning of one ungrouped temporal result column. */
+export declare type RawTemporalValueKind = 'date' | 'wall_datetime' | 'instant';
+
+/**
+ * Result-column metadata for an ungrouped temporal value. This descriptor is
+ * mutually exclusive with grouped `temporalBucket` metadata.
+ */
+export declare type RawTemporalValueMetadata = {
+    kind: 'raw_temporal';
+    valueKind: RawTemporalValueKind;
+};
+
 declare const REPORT_PREFERENCE_SOURCES: readonly ["viewer_user", "viewer_tenant_user", "session_initial", "viewer_tenant", "viewer_organization", "system_default"];
 
 declare type ReportPreferenceSource = (typeof REPORT_PREFERENCE_SOURCES)[number];
@@ -873,10 +990,47 @@ export declare type ResolvedNumericPresentationEntry = {
     format: NumericCanonicalFormat;
 };
 
-export declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry;
+export declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry;
 
-export declare type ResolvedTemporalBucketFormat = TemporalBucketFormat & {
+export declare type ResolvedRawTemporalFormat = {
+    type: 'raw_temporal';
     locale: string;
+    calendarTimezone: string;
+    /** Resolved source timezone for timezone-less wall datetimes, when authored. */
+    sourceTimezone?: string;
+    presentation: {
+        mode: 'auto';
+        styles: ResolvedTemporalStyleSet;
+    } | {
+        mode: 'pattern';
+        dialect: RawTemporalPatternDialect;
+        pattern: string;
+    };
+};
+
+export declare type ResolvedRawTemporalPresentationEntry = {
+    scope: PresentationScope;
+    target: RawTemporalPresentationTarget;
+    format: ResolvedRawTemporalFormat;
+};
+
+export declare type ResolvedTemporalBucketFormat = {
+    type: 'temporal_bucket';
+    locale: string;
+    presentation: {
+        mode: 'auto';
+        styles: ResolvedTemporalStyleSet;
+    };
+} | {
+    type: 'temporal_bucket';
+    locale: string;
+    presentation: {
+        mode: 'preset';
+        preset: TemporalBucketPreset;
+    } | {
+        mode: 'pattern';
+        pattern: string;
+    };
 };
 
 export declare type ResolvedTemporalBucketFormatParseResult = {
@@ -901,6 +1055,14 @@ export declare type ResolvedTemporalBucketPresentationEntry = {
     format: ResolvedTemporalBucketFormat;
 };
 
+export declare type ResolvedTemporalStyleSet = {
+    dateStyle: LocaleStyle;
+    dateTime: {
+        dateStyle: LocaleStyle;
+        timeStyle: LocaleStyle;
+    };
+};
+
 declare type ResolvedValueFormatPreferences = {
     locale: string;
     dateStyle: LocaleStyle;
@@ -928,6 +1090,12 @@ export declare function resolveNumericPresentation(authored: NumericCanonicalFor
 
 export declare function resolveQueryColumnKeyMapEntry(columnKeyMap: QueryColumnKeyMap | undefined, fieldId: string, role: QueryColumnKeyRole): QueryColumnKeyMapEntry | undefined;
 
+export declare function resolveRawTemporalFormat(input: {
+    format?: RawTemporalFormat;
+    preferences: ResolvedValueFormatPreferences;
+    calendar: Pick<CalendarContext, 'tz'>;
+}): ResolvedRawTemporalFormat;
+
 export declare function resolveTemporalBucketPresentation(input: ResolveTemporalBucketPresentationInput): ResolvedTemporalBucketPresentation;
 
 export declare type ResolveTemporalBucketPresentationInput = {
@@ -938,6 +1106,7 @@ export declare type ResolveTemporalBucketPresentationInput = {
     };
     cardFormat?: TemporalBucketFormat;
     locale: string;
+    styles?: ResolvedTemporalStyleSet;
 };
 
 /**
@@ -1054,6 +1223,7 @@ declare type SemaphorResultColumn = {
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
     temporalBucket?: TemporalBucketMetadata;
+    rawTemporal?: RawTemporalValueMetadata;
     pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };
 
@@ -1119,6 +1289,15 @@ declare type SemaphorSourceRef = {
 
 declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
+export declare type SqlTemporalColumnClassification = {
+    status: 'empty';
+} | {
+    status: 'invalid_only';
+} | {
+    status: 'classified';
+    metadata: RawTemporalValueMetadata;
+};
+
 export declare type StringCanonicalFormat = {
     type: 'string';
     prefix?: string;
@@ -1240,6 +1419,14 @@ export declare function validateCardExportPresentationSnapshot(input: {
     useFormattedValues: boolean;
 }): void;
 
+/**
+ * Validates descriptor exclusivity and datatype compatibility without
+ * inferring temporal meaning from a value or display label.
+ */
+export declare function validateRawTemporalResultColumn(column: Pick<SemaphorResultColumn, 'dataType' | 'rawTemporal' | 'temporalBucket'>, options: {
+    metadataRequired: boolean;
+}): RawTemporalValueMetadata | undefined;
+
 export declare function validateTemporalBucketFormatApplicability(format: TemporalBucketFormat, granularity: SemaphorTimeGrain): TemporalBucketFormatApplicabilityResult;
 
 declare type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;

package/dist/types/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../chunks/common-types-CQ6SHfLk.cjs"),l=require("../chunks/token-types-BdQ8kHBm.cjs"),t=require("../chunks/pivot-result-identity-CDLRT-YG.cjs"),E=require("../chunks/report-runtime-context-C8LZFsqV.cjs");exports.CALCULATED_FIELD_ENTITY_MARKER=e.CALCULATED_FIELD_ENTITY_MARKER;exports.CONTROL_CARD_DEFAULT_VALUE=e.CONTROL_CARD_DEFAULT_VALUE;exports.DATE_FORMAT_VALUES=e.DATE_FORMAT_VALUES;exports.EMPTY_SELECTION=e.EMPTY_SELECTION;exports.PivotMarkerEnum=e.PivotMarkerEnum;exports.getFieldRuntimeColumnName=e.getFieldRuntimeColumnName;exports.hasCalculatedFieldMarker=e.hasCalculatedFieldMarker;exports.hasCalculatedFormulaInputs=e.hasCalculatedFormulaInputs;exports.isCalculatedDimension=e.isCalculatedDimension;exports.isCalculatedField=e.isCalculatedField;exports.isCalculatedMetric=e.isCalculatedMetric;exports.DEFAULT_SEMANTIC_DOMAIN_ACCESS=l.DEFAULT_SEMANTIC_DOMAIN_ACCESS;exports.resolveQueryColumnKeyMapEntry=t.resolveQueryColumnKeyMapEntry;exports.resolveUniqueQueryColumnKeyMapEntry=t.resolveUniqueQueryColumnKeyMapEntry;exports.DEFAULT_CALENDAR_CONTEXT=E.DEFAULT_CALENDAR_CONTEXT;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../chunks/common-types-C57kJ59w.cjs"),l=require("../chunks/token-types-D7CaaI80.cjs"),t=require("../chunks/pivot-result-identity-Bb4EixVN.cjs"),E=require("../chunks/report-runtime-context-DqxS4wbi.cjs");exports.CALCULATED_FIELD_ENTITY_MARKER=e.CALCULATED_FIELD_ENTITY_MARKER;exports.CONTROL_CARD_DEFAULT_VALUE=e.CONTROL_CARD_DEFAULT_VALUE;exports.DATE_FORMAT_VALUES=e.DATE_FORMAT_VALUES;exports.EMPTY_SELECTION=e.EMPTY_SELECTION;exports.PivotMarkerEnum=e.PivotMarkerEnum;exports.getFieldRuntimeColumnName=e.getFieldRuntimeColumnName;exports.hasCalculatedFieldMarker=e.hasCalculatedFieldMarker;exports.hasCalculatedFormulaInputs=e.hasCalculatedFormulaInputs;exports.isCalculatedDimension=e.isCalculatedDimension;exports.isCalculatedField=e.isCalculatedField;exports.isCalculatedMetric=e.isCalculatedMetric;exports.DEFAULT_SEMANTIC_DOMAIN_ACCESS=l.DEFAULT_SEMANTIC_DOMAIN_ACCESS;exports.resolveQueryColumnKeyMapEntry=t.resolveQueryColumnKeyMapEntry;exports.resolveUniqueQueryColumnKeyMapEntry=t.resolveUniqueQueryColumnKeyMapEntry;exports.DEFAULT_CALENDAR_CONTEXT=E.DEFAULT_CALENDAR_CONTEXT;

package/dist/types/index.js

@@ -1,7 +1,7 @@
-import { a as s, C as r, D as E, E as l, P as C, g as o, d as t, h as A, b as u, c as T, i as _ } from "../chunks/common-types-B7Jk3Rtj.js";
-import { D } from "../chunks/token-types-BHR58aTy.js";
-import { r as n, a as L } from "../chunks/pivot-result-identity-CwJWpKI7.js";
-import { D as d } from "../chunks/report-runtime-context-bCy3CVzK.js";
+import { a as s, C as r, D as E, E as l, P as C, g as o, d as t, h as A, b as u, c as T, i as _ } from "../chunks/common-types-H51FLKB7.js";
+import { D } from "../chunks/token-types-GbxRUozo.js";
+import { r as n, a as L } from "../chunks/pivot-result-identity-DU1v-5Xk.js";
+import { D as d } from "../chunks/report-runtime-context-SM6YO61_.js";
 export {
   s as CALCULATED_FIELD_ENTITY_MARKER,
   r as CONTROL_CARD_DEFAULT_VALUE,