react-semaphor 0.1.449 → 0.1.454

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

@@ -303,7 +303,7 @@ declare type SemaphorDataAppCodegenMatrixIntent = {
 
 declare type SemaphorDataAppCodegenMatrixSortRule = Omit<SemaphorMatrixSortRule, 'by'> & {
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorDataAppCodegenFieldRef;
@@ -797,6 +797,8 @@ declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    format?: TemporalBucketFormat;
+    semanticTemporalPresentation?: SemaphorMatrixSemanticTemporalPresentation;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -805,7 +807,7 @@ declare type SemaphorMatrixAxisLevel = {
 declare type SemaphorMatrixAxisSortRule = {
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -860,12 +862,17 @@ declare type SemaphorMatrixMemberPathSegment = {
     value: unknown;
 };
 
+declare type SemaphorMatrixSemanticTemporalPresentation = {
+    granularity: SemaphorMatrixTimeGrain;
+    format: TemporalBucketFormat;
+};
+
 declare type SemaphorMatrixSortRule = {
     axis: 'row' | 'column';
     targetId?: string;
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -1114,6 +1121,25 @@ declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
+declare const TEMPORAL_BUCKET_PRESETS: readonly ["week_of_short", "week_of_long", "quarter_short", "quarter_long", "fiscal_quarter_short", "fiscal_year"];
+
+declare type TemporalBucketFormat = {
+    type: 'temporal_bucket';
+    presentation: TemporalBucketPresentation;
+};
+
+declare type TemporalBucketPresentation = {
+    mode: 'auto';
+} | {
+    mode: 'preset';
+    preset: TemporalBucketPreset;
+} | {
+    mode: 'pattern';
+    pattern: string;
+};
+
+declare type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
+
 export declare function validateCodegenSummary(value: unknown): string[];
 
 export declare function validateSemaphorDataAppCodegenSummary(value: unknown): {

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

@@ -264,6 +264,8 @@ declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    format?: TemporalBucketFormat;
+    semanticTemporalPresentation?: SemaphorMatrixSemanticTemporalPresentation;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -274,7 +276,7 @@ declare type SemaphorMatrixAxisLevelInput = SemaphorQueryField | SemaphorMatrixA
 declare type SemaphorMatrixAxisSortRule = {
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -342,12 +344,17 @@ declare type SemaphorMatrixQuerySpec = Omit<SemaphorMatrixIntent, 'kind' | 'vers
     displayLimits?: SemaphorMatrixDisplayLimitOptions;
 };
 
+declare type SemaphorMatrixSemanticTemporalPresentation = {
+    granularity: SemaphorMatrixTimeGrain;
+    format: TemporalBucketFormat;
+};
+
 declare type SemaphorMatrixSortRule = {
     axis: 'row' | 'column';
     targetId?: string;
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -682,6 +689,25 @@ declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
+declare const TEMPORAL_BUCKET_PRESETS: readonly ["week_of_short", "week_of_long", "quarter_short", "quarter_long", "fiscal_quarter_short", "fiscal_year"];
+
+declare type TemporalBucketFormat = {
+    type: 'temporal_bucket';
+    presentation: TemporalBucketPresentation;
+};
+
+declare type TemporalBucketPresentation = {
+    mode: 'auto';
+} | {
+    mode: 'preset';
+    preset: TemporalBucketPreset;
+} | {
+    mode: 'pattern';
+    pattern: string;
+};
+
+declare type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
+
 export declare function toSemaphorActiveInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
 
 export declare function toSemaphorAnalysisIntent(spec: SemaphorAnalysisQuerySpec): SemaphorMetricIntent;

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

@@ -21,6 +21,7 @@ declare type MatrixAxisLevelDescriptor = {
     label: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    temporalBucket?: TemporalBucketMetadata;
     subtotal?: SemaphorMatrixSubtotalOptions;
 };
 
@@ -95,7 +96,8 @@ declare type MatrixFormattingContext = {
 
 declare type MatrixGridColumn = {
     id: string;
-    label: string;
+    /** Present only for measure and explicit total headings. */
+    label?: string;
     columnNodeId?: string;
     columnPath: MatrixMemberPathSegment[];
     measureInstanceId: string;
@@ -104,7 +106,8 @@ declare type MatrixGridColumn = {
 
 declare type MatrixGridHeaderCell = {
     id: string;
-    label: string;
+    /** Present only for non-member headings and explicit total labels. */
+    label?: string;
     role: 'rowHeader' | 'columnHeader' | 'measureHeader' | 'subtotal' | 'grandTotal';
     colSpan: number;
     rowSpan: number;
@@ -166,7 +169,8 @@ declare type MatrixMemberPathSegment = {
     instanceId: string;
     fieldKey: string;
     value: unknown;
-    label: string;
+    /** Display-only source label for non-temporal members. */
+    label?: string;
 };
 
 declare type MatrixNode = {
@@ -174,7 +178,8 @@ declare type MatrixNode = {
     axis: 'row' | 'column';
     path: MatrixMemberPathSegment[];
     level: number;
-    label: string;
+    /** Present only for non-temporal members and explicit total labels. */
+    label?: string;
     value: unknown;
     parentId?: string;
     hasChildren: boolean;
@@ -246,6 +251,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;
@@ -705,6 +722,8 @@ declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    format?: TemporalBucketFormat;
+    semanticTemporalPresentation?: SemaphorMatrixSemanticTemporalPresentation;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -715,7 +734,7 @@ declare type SemaphorMatrixAxisLevelInput = SemaphorQueryField | SemaphorMatrixA
 declare type SemaphorMatrixAxisSortRule = {
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -789,7 +808,7 @@ declare type SemaphorMatrixQuerySpec = Omit<SemaphorMatrixIntent, 'kind' | 'vers
 
 declare type SemaphorMatrixResult = SemaphorAnalyticsResultBase & {
     kind: 'matrix';
-    schemaVersion: 1;
+    schemaVersion: 2;
     intent?: SemaphorMatrixIntent;
     shape: MatrixShape;
     capabilities: MatrixCapability[];
@@ -811,12 +830,17 @@ declare type SemaphorMatrixResult = SemaphorAnalyticsResultBase & {
     expansion?: MatrixExpansionResponseHints;
 };
 
+declare type SemaphorMatrixSemanticTemporalPresentation = {
+    granularity: SemaphorMatrixTimeGrain;
+    format: TemporalBucketFormat;
+};
+
 declare type SemaphorMatrixSortRule = {
     axis: 'row' | 'column';
     targetId?: string;
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -1169,6 +1193,7 @@ declare type SemaphorResultColumn = {
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
     temporalBucket?: TemporalBucketMetadata;
+    rawTemporal?: RawTemporalValueMetadata;
     pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };
 
@@ -1296,12 +1321,31 @@ declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
+declare const TEMPORAL_BUCKET_PRESETS: readonly ["week_of_short", "week_of_long", "quarter_short", "quarter_long", "fiscal_quarter_short", "fiscal_year"];
+
+declare type TemporalBucketFormat = {
+    type: 'temporal_bucket';
+    presentation: TemporalBucketPresentation;
+};
+
 declare type TemporalBucketMetadata = {
     kind: 'temporal_bucket';
     granularity: SemaphorTimeGrain;
     calendar: Pick<CalendarContext, 'tz' | 'weekStart' | 'fiscalCalendar'>;
 };
 
+declare type TemporalBucketPresentation = {
+    mode: 'auto';
+} | {
+    mode: 'preset';
+    preset: TemporalBucketPreset;
+} | {
+    mode: 'pattern';
+    pattern: string;
+};
+
+declare type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
+
 export declare function validateSemaphorDataAppQuerySpecs(input: {
     queries: SemaphorDataAppQuerySpecEnvelope[];
     fieldCatalogs?: SemaphorDataAppFieldCatalog[];

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

@@ -26,6 +26,7 @@ declare type MatrixAxisLevelDescriptor = {
     label: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    temporalBucket?: TemporalBucketMetadata;
     subtotal?: SemaphorMatrixSubtotalOptions;
 };
 
@@ -146,7 +147,8 @@ declare type MatrixGridCell = {
 
 declare type MatrixGridColumn = {
     id: string;
-    label: string;
+    /** Present only for measure and explicit total headings. */
+    label?: string;
     columnNodeId?: string;
     columnPath: MatrixMemberPathSegment[];
     measureInstanceId: string;
@@ -155,7 +157,8 @@ declare type MatrixGridColumn = {
 
 declare type MatrixGridHeaderCell = {
     id: string;
-    label: string;
+    /** Present only for non-member headings and explicit total labels. */
+    label?: string;
     role: 'rowHeader' | 'columnHeader' | 'measureHeader' | 'subtotal' | 'grandTotal';
     colSpan: number;
     rowSpan: number;
@@ -169,7 +172,7 @@ declare type MatrixGridHeaderRow = {
 };
 
 export declare type MatrixGridProjection = {
-    schemaVersion: 1;
+    schemaVersion: 2;
     shape: MatrixShape;
     rowHeaderLevels: MatrixGridRowHeaderLevel[];
     columnHeaderRows: MatrixGridHeaderRow[];
@@ -182,7 +185,8 @@ declare type MatrixGridRow = {
     rowNodeId: string;
     rowPath: MatrixMemberPathSegment[];
     depth: number;
-    label: string;
+    /** Present only for non-temporal members and explicit total labels. */
+    label?: string;
     role: 'value' | 'rowSubtotal' | 'rowGrandTotal';
     isExpanded?: boolean;
     hasChildren?: boolean;
@@ -238,7 +242,8 @@ declare type MatrixMemberPathSegment = {
     instanceId: string;
     fieldKey: string;
     value: unknown;
-    label: string;
+    /** Display-only source label for non-temporal members. */
+    label?: string;
 };
 
 declare type MatrixNode = {
@@ -246,7 +251,8 @@ declare type MatrixNode = {
     axis: 'row' | 'column';
     path: MatrixMemberPathSegment[];
     level: number;
-    label: string;
+    /** Present only for non-temporal members and explicit total labels. */
+    label?: string;
     value: unknown;
     parentId?: string;
     hasChildren: boolean;
@@ -275,7 +281,7 @@ declare type MatrixPageInfo = {
 
 export declare type MatrixPayload = {
     kind: 'matrixPayload';
-    schemaVersion: 1;
+    schemaVersion: 2;
     shape: MatrixShape;
     capabilities: MatrixCapability[];
     executionMetadata: MatrixExecutionMetadata;
@@ -341,6 +347,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;
@@ -1059,6 +1077,8 @@ export declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    format?: TemporalBucketFormat;
+    semanticTemporalPresentation?: SemaphorMatrixSemanticTemporalPresentation;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -1069,7 +1089,7 @@ export declare type SemaphorMatrixAxisLevelInput = SemaphorQueryField | Semaphor
 declare type SemaphorMatrixAxisSortRule = {
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -1159,7 +1179,7 @@ export declare type SemaphorMatrixQuerySpec = Omit<SemaphorMatrixIntent, 'kind'
 
 declare type SemaphorMatrixResult = SemaphorAnalyticsResultBase & {
     kind: 'matrix';
-    schemaVersion: 1;
+    schemaVersion: 2;
     intent?: SemaphorMatrixIntent;
     shape: MatrixShape;
     capabilities: MatrixCapability[];
@@ -1181,12 +1201,17 @@ declare type SemaphorMatrixResult = SemaphorAnalyticsResultBase & {
     expansion?: MatrixExpansionResponseHints;
 };
 
+declare type SemaphorMatrixSemanticTemporalPresentation = {
+    granularity: SemaphorMatrixTimeGrain;
+    format: TemporalBucketFormat;
+};
+
 export declare type SemaphorMatrixSortRule = {
     axis: 'row' | 'column';
     targetId?: string;
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -1624,6 +1649,7 @@ export declare type SemaphorResultColumn = {
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
     temporalBucket?: TemporalBucketMetadata;
+    rawTemporal?: RawTemporalValueMetadata;
     pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };
 
@@ -1790,12 +1816,31 @@ export declare function SemaphorViewBoundary({ id, title, children, }: {
     children: ReactNode;
 }): ReactElement;
 
+declare const TEMPORAL_BUCKET_PRESETS: readonly ["week_of_short", "week_of_long", "quarter_short", "quarter_long", "fiscal_quarter_short", "fiscal_year"];
+
+declare type TemporalBucketFormat = {
+    type: 'temporal_bucket';
+    presentation: TemporalBucketPresentation;
+};
+
 declare type TemporalBucketMetadata = {
     kind: 'temporal_bucket';
     granularity: SemaphorTimeGrain;
     calendar: Pick<CalendarContext, 'tz' | 'weekStart' | 'fiscalCalendar'>;
 };
 
+declare type TemporalBucketPresentation = {
+    mode: 'auto';
+} | {
+    mode: 'preset';
+    preset: TemporalBucketPreset;
+} | {
+    mode: 'pattern';
+    pattern: string;
+};
+
+declare type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
+
 export declare function useClearInvalidSemaphorInputValue(input: SemaphorInputHandle, optionsResult: Pick<SemaphorInputOptionsQueryResult, 'options' | 'status'> | undefined): void;
 
 export declare function useSemaphorDevtools(): SemaphorDataAppDevtoolsState;