react-semaphor 0.1.444 → 0.1.445

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

@@ -25,7 +25,7 @@ declare type MatrixAxisLevelDescriptor = {
     fieldKey: string;
     label: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     subtotal?: SemaphorMatrixSubtotalOptions;
 };
 
@@ -207,7 +207,7 @@ declare type MatrixMeasureDescriptor = {
     label: string;
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -221,7 +221,7 @@ declare type MatrixMeasureSemantics = {
 } | {
     kind: 'semiAdditive';
     aggregate?: SemaphorAggregateFunction;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
 } | {
     kind: 'nonAdditive';
     aggregate?: SemaphorAggregateFunction;
@@ -367,6 +367,10 @@ export declare const semaphor: {
     matrix(spec: SemaphorMatrixQuerySpec): SemaphorMatrixQueryDefinition;
 };
 
+declare const SEMAPHOR_MATRIX_TIME_GRAINS: ["hour", "day", "week", "month", "quarter", "year"];
+
+declare const SEMAPHOR_TIME_GRAINS: readonly ["second", "minute", "hour", "day", "week", "month", "quarter", "year"];
+
 declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -861,7 +865,7 @@ export declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -1054,7 +1058,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 export declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -1205,6 +1209,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -1240,7 +1246,7 @@ export declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -1373,6 +1379,30 @@ export declare type SemaphorPaginationRequest = {
     pageSize: number;
 };
 
+declare type SemaphorPivotResultColumnIdentity = {
+    metricId: string;
+    /** Collision-safe identity for this configured metric instance. */
+    metricAlias: string;
+    /**
+     * Sole transported tuple identity in configured pivot-axis order. A leaf
+     * carries the complete tuple, a subtotal carries its explicit prefix, and a
+     * metric-only or grand-total column carries an empty tuple.
+     */
+    members: SemaphorPivotResultMember[];
+};
+
+declare type SemaphorPivotResultMember = {
+    /** Stable identity of the configured pivot field. */
+    fieldId: string;
+    /** Canonical pivot member value; labels are resolved only at presentation. */
+    value: SemaphorPivotValue;
+    /** Present when this member is an activated governed temporal bucket. */
+    temporalBucket?: TemporalBucketMetadata;
+};
+
+/** Stable canonical scalar transported for one physical pivot member. */
+declare type SemaphorPivotValue = string | null;
+
 declare type SemaphorProtocolIssue = {
     code: string;
     message: string;
@@ -1568,7 +1598,7 @@ declare type SemaphorRelationshipHint = {
 
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
-    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    unit: SemaphorTimeGrain;
     value: number;
     anchor?: 'now' | 'latest_available';
     completeness?: 'include_partial' | 'complete_periods';
@@ -1593,12 +1623,51 @@ export declare type SemaphorResultColumn = {
     aggregate?: SemaphorFieldRef['aggregate'];
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
+    temporalBucket?: TemporalBucketMetadata;
+    pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };
 
 export declare type SemaphorRowsQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorRecordsQueryResult<TRecord> | SemaphorSqlQueryResult<TRecord>;
 
 export declare type SemaphorScalar = string | number | boolean | null;
 
+declare type SemaphorScalarValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
 export declare type SemaphorSemanticSourceBuilderSpec = {
     domainId: string;
     datasetName: string;
@@ -1711,53 +1780,22 @@ export declare type SemaphorSqlSourceSpec = {
     }>;
 };
 
-declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 export declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
-declare type SemaphorValueFormat = {
-    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
-    minimumFractionDigits?: number;
-    maximumFractionDigits?: number;
-    useGrouping?: boolean;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-    compact?: boolean;
-    scale?: number;
-    currency?: string;
-    percentValueMode?: 'fraction' | 'whole';
-} | {
-    type: 'date' | 'datetime';
-    locale?: string;
-    pattern?: string;
-    relative?: boolean;
-    timezone?: string;
-    sourceTimezone?: string;
-    prefix?: string;
-    suffix?: string;
-} | {
-    type: 'duration';
-    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    outputStyle?: 'compact' | 'digital' | 'long';
-    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    maxUnits?: number;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-} | {
-    type: 'string';
-    prefix?: string;
-    suffix?: string;
-};
-
 export declare function SemaphorViewBoundary({ id, title, children, }: {
     id: string;
     title?: string;
     children: ReactNode;
 }): ReactElement;
 
+declare type TemporalBucketMetadata = {
+    kind: 'temporal_bucket';
+    granularity: SemaphorTimeGrain;
+    calendar: Pick<CalendarContext, 'tz' | 'weekStart' | 'fiscalCalendar'>;
+};
+
 export declare function useClearInvalidSemaphorInputValue(input: SemaphorInputHandle, optionsResult: Pick<SemaphorInputOptionsQueryResult, 'options' | 'status'> | undefined): void;
 
 export declare function useSemaphorDevtools(): SemaphorDataAppDevtoolsState;