react-semaphor 0.1.449 → 0.1.453

package/dist/types/dashboard-assistant.d.ts

@@ -351,6 +351,11 @@ declare type DateFormatValue = (typeof DATE_FORMAT_VALUES)[number];
  */
 declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
     role: 'detail';
+    /**
+     * Query transport policy for ungrouped temporal values. This marker is
+     * projected into executable config and is never persisted authoring state.
+     */
+    dateValueMode?: 'canonical' | 'formatted';
     dateFormat?: DateFormatValue;
     customFormat?: string;
     /**
@@ -973,6 +978,18 @@ declare interface QueryColumnKeyMapEntry {
 
 declare type QueryColumnKeyRole = 'groupby' | 'metric' | 'pivotby' | 'detail';
 
+/** Authoritative meaning of one ungrouped temporal result column. */
+declare type RawTemporalValueKind = 'date' | 'wall_datetime' | 'instant';
+
+/**
+ * Result-column metadata for an ungrouped temporal value. This descriptor is
+ * mutually exclusive with grouped `temporalBucket` metadata.
+ */
+declare type RawTemporalValueMetadata = {
+    kind: 'raw_temporal';
+    valueKind: RawTemporalValueKind;
+};
+
 declare type SelectedEntities = SelectedEntity[];
 
 declare type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
@@ -1633,6 +1650,7 @@ declare type SemaphorResultColumn = {
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
     temporalBucket?: TemporalBucketMetadata;
+    rawTemporal?: RawTemporalValueMetadata;
     pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };
 

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

@@ -140,6 +140,18 @@ declare type CalendarContext = {
     fiscalCalendar?: MonthAlignedFiscalCalendar;
 };
 
+export declare type CanonicalDetailResultFieldIdentity = {
+    name: string;
+    label?: string;
+    alias?: string;
+    entityName?: string;
+    role?: string;
+    aggregate?: string;
+    expression?: string;
+};
+
+export declare type CanonicalResultFieldRole = 'groupby' | 'metric' | 'pivotby' | 'detail';
+
 declare interface CardConfig {
     /**
      * Matrix table is the shared analytics-spine successor for pivot and
@@ -974,6 +986,11 @@ declare type DefaultDateFilter = RelativeDateFilter | FixedMonthDefaultDateFilte
  */
 declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
     role: 'detail';
+    /**
+     * Query transport policy for ungrouped temporal values. This marker is
+     * projected into executable config and is never persisted authoring state.
+     */
+    dateValueMode?: 'canonical' | 'formatted';
     dateFormat?: DateFormatValue;
     customFormat?: string;
     /**
@@ -1611,7 +1628,7 @@ export declare type GeneratedDashboardCardArtifact = {
 
 export declare function getDashboardAuthoringCardSource(card: Pick<DashboardPlanCard, 'analyticsIntent'>): SemaphorSourceRef | undefined;
 
-export declare function getTemporalBucketAuthoringOptions(granularity: SemaphorTimeGrain, preservedFormat?: TemporalBucketFormat): readonly TemporalBucketAuthoringOption[];
+export declare function getTemporalBucketAuthoringOptions(granularity: SemaphorTimeGrain, preservedFormat?: TemporalBucketFormat, preferences?: ResolvedTemporalValueFormatPreferences): readonly TemporalBucketAuthoringOption[];
 
 export declare function getTemporalBucketAuthoringSelection(format: TemporalBucketFormat, granularity: SemaphorTimeGrain): TemporalBucketAuthoringSelection;
 
@@ -1769,6 +1786,8 @@ declare interface LinkFormat {
     openInNewTab: boolean;
 }
 
+declare type LocaleStyle = 'short' | 'medium' | 'long';
+
 declare type LogicalOperator = 'AND' | 'OR';
 
 export declare type MaterializableDashboardAuthoringSource = Extract<SemaphorSourceRef, {
@@ -1967,7 +1986,7 @@ export declare function preferDashboardAuthoringSourceMetadata(current: Semaphor
 
 export declare function preferredDashboardAuthoringSource(sources: readonly SemaphorSourceRef[]): SemaphorSourceRef | undefined;
 
-export declare function previewTemporalBucketAuthoringFormat(format: TemporalBucketFormat, granularity: SemaphorTimeGrain): string;
+export declare function previewTemporalBucketAuthoringFormat(format: TemporalBucketFormat, granularity: SemaphorTimeGrain, preferences?: ResolvedTemporalValueFormatPreferences): string;
 
 declare interface QueryConfig {
     groupByColumns?: GroupByColumn[];
@@ -2017,6 +2036,24 @@ declare type RelativeDateFilter = {
     to: number;
 };
 
+/** Physical SQL/result alias used by config-owned detail projections. */
+export declare function resolveCanonicalDetailResultRawKey(field: CanonicalDetailResultFieldIdentity): string;
+
+/**
+ * Deterministic canonical response-key policy shared by the query producer and
+ * recurring snapshot capture. A unique display label may become the physical
+ * output key only when it cannot hide another raw result key.
+ */
+export declare function resolveCanonicalResultOutputKey(input: {
+    label?: string;
+    labelCount: number;
+    rawKey: string;
+    rawKeys: ReadonlySet<string>;
+}): string;
+
+/** Role-aware physical key policy used by the canonical query key map. */
+export declare function resolveCanonicalResultRawKey(field: CanonicalDetailResultFieldIdentity, role: CanonicalResultFieldRole, emittedAliasOverride?: string): string;
+
 export declare function resolveDashboardAuthoringSource({ explicitSource, field, defaultSource, fallbackSources, }: {
     explicitSource?: unknown;
     field?: SemaphorFieldRef;
@@ -2024,6 +2061,19 @@ export declare function resolveDashboardAuthoringSource({ explicitSource, field,
     fallbackSources?: readonly SemaphorSourceRef[];
 }): MaterializableDashboardAuthoringSource | undefined;
 
+/** Viewer preferences that affect temporal presentation without numeric currency policy. */
+declare type ResolvedTemporalValueFormatPreferences = Pick<ResolvedValueFormatPreferences, 'locale' | 'dateStyle' | 'dateTime'>;
+
+declare type ResolvedValueFormatPreferences = {
+    locale: string;
+    dateStyle: LocaleStyle;
+    dateTime: {
+        dateStyle: LocaleStyle;
+        timeStyle: LocaleStyle;
+    };
+    defaultCurrency: string;
+};
+
 export declare function resolveTemporalBucketAuthoringFormat(granularity: SemaphorTimeGrain, value: string, customPattern?: string): TemporalBucketFormat;
 
 /**

package/dist/types/dashboard.d.ts

@@ -898,6 +898,8 @@ export declare type DashboardProps = {
      * points. Ordinary dashboard consumers should leave this unset.
      */
     interactionExecutionSnapshot?: Record<string, InteractionState>;
+    /** Server-resolved immutable presentation snapshot for internal print views. */
+    presentationExecutionSnapshot?: PresentationExecutionSnapshot;
     /**
      * Render target for print entry points. Generic dashboard PDF exports also
      * use cardDisplay.mode="print"; document-specific print handling must only
@@ -1001,6 +1003,11 @@ declare type DefaultDateFilter = RelativeDateFilter | FixedMonthDefaultDateFilte
  */
 declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
     role: 'detail';
+    /**
+     * Query transport policy for ungrouped temporal values. This marker is
+     * projected into executable config and is never persisted authoring state.
+     */
+    dateValueMode?: 'canonical' | 'formatted';
     dateFormat?: DateFormatValue;
     customFormat?: string;
     /**
@@ -2088,6 +2095,32 @@ export declare type NumberOptions = {
     colorRanges?: ColorRange[];
 };
 
+declare type NumericCanonicalFormat = {
+    type: 'number' | 'currency' | 'percent' | 'scientific';
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+};
+
+declare type NumericPresentationTarget = {
+    kind: 'metric';
+    metricId: string;
+} | {
+    kind: 'column';
+    columnKey: string;
+} | {
+    kind: 'matrix_measure';
+    measureId: string;
+};
+
 declare type OldFilterValue = string | number | null | (string | number)[] | RangeValue;
 
 declare type Operation = '=' | '>' | '<' | '>=' | '<=' | '!=' | 'in' | 'not in' | 'like' | 'not like' | 'between' | 'not between' | 'is null' | 'is not null';
@@ -2165,6 +2198,18 @@ export declare type Placeholders = {
 
 export declare type PluginType = 'custom' | 'standard';
 
+declare type PresentationExecutionSnapshot = {
+    version: 1;
+    reportContext: ReportRuntimeContext;
+    resolvedFormats: ResolvedPresentationEntry[];
+};
+
+declare type PresentationScope = {
+    dashboardId: string;
+    cardId?: string;
+    attachmentIndex?: number;
+};
+
 declare interface QueryConfig {
     groupByColumns?: GroupByColumn[];
     pivotColumns?: GroupByColumn[];
@@ -2187,6 +2232,13 @@ declare type RangeValue = {
     gt?: string | number;
 };
 
+declare type RawTemporalPatternDialect = 'semaphor_tokens' | 'date_fns';
+
+declare type RawTemporalPresentationTarget = {
+    kind: 'column';
+    columnKey: string;
+};
+
 declare type RelativeDateFilter = {
     mode: 'last';
     n: number;
@@ -2288,6 +2340,14 @@ export declare type ResolvedDocumentInput = {
     exports: Record<string, string | number | boolean | null>;
 };
 
+declare type ResolvedNumericPresentationEntry = {
+    scope: PresentationScope;
+    target: NumericPresentationTarget;
+    format: NumericCanonicalFormat;
+};
+
+declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry;
+
 declare type ResolvedPrimaryDateField = (ResolvedPrimaryDateFieldBase & ({
     defaultGranularity?: SemaphorTimeGrain;
     format?: undefined;
@@ -2311,6 +2371,61 @@ declare type ResolvedPrimaryDateFieldBase = {
     supportedGranularities?: SemaphorTimeGrain[];
 };
 
+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;
+    };
+};
+
+declare type ResolvedRawTemporalPresentationEntry = {
+    scope: PresentationScope;
+    target: RawTemporalPresentationTarget;
+    format: ResolvedRawTemporalFormat;
+};
+
+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;
+    };
+};
+
+declare type ResolvedTemporalBucketPresentationEntry = {
+    scope: PresentationScope;
+    target: TemporalBucketPresentationTarget;
+    format: ResolvedTemporalBucketFormat;
+};
+
+declare type ResolvedTemporalStyleSet = {
+    dateStyle: LocaleStyle;
+    dateTime: {
+        dateStyle: LocaleStyle;
+        timeStyle: LocaleStyle;
+    };
+};
+
 declare type ResolvedValueFormatPreferences = {
     locale: string;
     dateStyle: LocaleStyle;
@@ -3403,6 +3518,19 @@ declare type TemporalBucketPresentation = {
     pattern: string;
 };
 
+declare type TemporalBucketPresentationTarget = {
+    kind: 'field';
+    fieldId: string;
+    /** Distinguishes one semantic field used on both pivot axes. */
+    role?: 'groupby' | 'pivotby';
+} | {
+    kind: 'column';
+    columnKey: string;
+} | {
+    kind: 'matrix_axis';
+    axisInstanceId: string;
+};
+
 declare type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
 
 declare type TemporalPrecision = 'minute';

package/dist/types/data-app-sdk-validation.d.ts

@@ -246,6 +246,18 @@ export declare function normalizeSemaphorAnalysisQueryOptions(value: unknown, op
 
 export declare function normalizeSemaphorFieldRole(field: SemaphorFieldRef): SemaphorFieldRef['role'] | undefined;
 
+/** Authoritative meaning of one ungrouped temporal result column. */
+declare type RawTemporalValueKind = 'date' | 'wall_datetime' | 'instant';
+
+/**
+ * Result-column metadata for an ungrouped temporal value. This descriptor is
+ * mutually exclusive with grouped `temporalBucket` metadata.
+ */
+declare type RawTemporalValueMetadata = {
+    kind: 'raw_temporal';
+    valueKind: RawTemporalValueKind;
+};
+
 export declare function relatedProjectionFieldCandidatesForIntent(intent: RelationshipAwareProjectionIntent): SemaphorRelatedProjectionFieldCandidate[];
 
 declare type RelationshipAwareProjectionIntent = SemaphorRecordsIntent | SemaphorMetricIntent | SemaphorMatrixIntent;
@@ -1169,6 +1181,7 @@ declare type SemaphorResultColumn = {
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
     temporalBucket?: TemporalBucketMetadata;
+    rawTemporal?: RawTemporalValueMetadata;
     pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };
 

package/dist/types/data-app-sdk.d.ts

@@ -341,6 +341,18 @@ declare type MonthAlignedFiscalCalendar = {
     yearStartMonth: number;
 };
 
+/** Authoritative meaning of one ungrouped temporal result column. */
+declare type RawTemporalValueKind = 'date' | 'wall_datetime' | 'instant';
+
+/**
+ * Result-column metadata for an ungrouped temporal value. This descriptor is
+ * mutually exclusive with grouped `temporalBucket` metadata.
+ */
+declare type RawTemporalValueMetadata = {
+    kind: 'raw_temporal';
+    valueKind: RawTemporalValueKind;
+};
+
 export declare const semaphor: {
     source: {
         semantic(spec: SemaphorSemanticSourceBuilderSpec): SemaphorSemanticSourceRef;
@@ -1624,6 +1636,7 @@ export declare type SemaphorResultColumn = {
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
     temporalBucket?: TemporalBucketMetadata;
+    rawTemporal?: RawTemporalValueMetadata;
     pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };