react-semaphor 0.1.449 → 0.1.454

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;
     /**
@@ -533,11 +538,6 @@ declare type FormatSpec = {
 declare interface GroupByField extends Field {
     role: 'groupby';
     granularity?: TimeGranularity;
-    /**
-     * Query transport policy for grouped temporal values. This is projected
-     * into executable card config and is not persisted authoring state.
-     */
-    dateValueMode?: 'canonical' | 'formatted';
     /**
      * Optional SQL expression for grouping (e.g., DATE_TRUNC('month', order_date)).
      * If present, used in SELECT and GROUP BY instead of just the column name.
@@ -624,6 +624,7 @@ declare type MatrixAxisLevelDescriptor = {
     label: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    temporalBucket?: TemporalBucketMetadata;
     subtotal?: SemaphorMatrixSubtotalOptions;
 };
 
@@ -698,7 +699,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;
@@ -707,7 +709,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;
@@ -769,7 +772,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 = {
@@ -777,7 +781,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;
@@ -929,11 +934,6 @@ declare interface PivotByField extends Field {
      * so existing cards need no migration.
      */
     memberOrder?: PivotMemberOrder;
-    /**
-     * Query transport policy for grouped temporal pivot members. This is
-     * projected into executable config and is never persisted authoring state.
-     */
-    dateValueMode?: 'canonical' | 'formatted';
 }
 
 /**
@@ -973,6 +973,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;
@@ -1272,6 +1284,8 @@ declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    format?: TemporalBucketFormat;
+    semanticTemporalPresentation?: SemaphorMatrixSemanticTemporalPresentation;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -1280,7 +1294,7 @@ declare type SemaphorMatrixAxisLevel = {
 declare type SemaphorMatrixAxisSortRule = {
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -1337,7 +1351,7 @@ declare type SemaphorMatrixMemberPathSegment = {
 
 declare type SemaphorMatrixResult = SemaphorAnalyticsResultBase & {
     kind: 'matrix';
-    schemaVersion: 1;
+    schemaVersion: 2;
     intent?: SemaphorMatrixIntent;
     shape: MatrixShape;
     capabilities: MatrixCapability[];
@@ -1359,12 +1373,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;
@@ -1633,6 +1652,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;
 
@@ -1633,11 +1650,6 @@ declare interface GroupByColumn extends BaseColumn {
 declare interface GroupByField extends Field {
     role: 'groupby';
     granularity?: TimeGranularity;
-    /**
-     * Query transport policy for grouped temporal values. This is projected
-     * into executable card config and is not persisted authoring state.
-     */
-    dateValueMode?: 'canonical' | 'formatted';
     /**
      * Optional SQL expression for grouping (e.g., DATE_TRUNC('month', order_date)).
      * If present, used in SELECT and GROUP BY instead of just the column name.
@@ -1769,6 +1781,8 @@ declare interface LinkFormat {
     openInNewTab: boolean;
 }
 
+declare type LocaleStyle = 'short' | 'medium' | 'long';
+
 declare type LogicalOperator = 'AND' | 'OR';
 
 export declare type MaterializableDashboardAuthoringSource = Extract<SemaphorSourceRef, {
@@ -1947,11 +1961,6 @@ declare interface PivotByField extends Field {
      * so existing cards need no migration.
      */
     memberOrder?: PivotMemberOrder;
-    /**
-     * Query transport policy for grouped temporal pivot members. This is
-     * projected into executable config and is never persisted authoring state.
-     */
-    dateValueMode?: 'canonical' | 'formatted';
 }
 
 /**
@@ -1967,7 +1976,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 +2026,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 +2051,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;
 
 /**
@@ -2230,6 +2270,8 @@ declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    format?: TemporalBucketFormat;
+    semanticTemporalPresentation?: SemaphorMatrixSemanticTemporalPresentation;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -2238,7 +2280,7 @@ declare type SemaphorMatrixAxisLevel = {
 declare type SemaphorMatrixAxisSortRule = {
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -2293,12 +2335,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;

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;
     /**
@@ -1756,11 +1763,6 @@ declare interface GroupByColumn extends BaseColumn {
 declare interface GroupByField extends Field {
     role: 'groupby';
     granularity?: TimeGranularity;
-    /**
-     * Query transport policy for grouped temporal values. This is projected
-     * into executable card config and is not persisted authoring state.
-     */
-    dateValueMode?: 'canonical' | 'formatted';
     /**
      * Optional SQL expression for grouping (e.g., DATE_TRUNC('month', order_date)).
      * If present, used in SELECT and GROUP BY instead of just the column name.
@@ -2088,6 +2090,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';
@@ -2136,11 +2164,6 @@ declare interface PivotByField extends Field {
      * so existing cards need no migration.
      */
     memberOrder?: PivotMemberOrder;
-    /**
-     * Query transport policy for grouped temporal pivot members. This is
-     * projected into executable config and is never persisted authoring state.
-     */
-    dateValueMode?: 'canonical' | 'formatted';
 }
 
 /**
@@ -2165,6 +2188,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 +2222,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 +2330,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 +2361,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;
@@ -2459,6 +2564,8 @@ declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    format?: TemporalBucketFormat;
+    semanticTemporalPresentation?: SemaphorMatrixSemanticTemporalPresentation;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -2467,7 +2574,7 @@ declare type SemaphorMatrixAxisLevel = {
 declare type SemaphorMatrixAxisSortRule = {
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -2522,12 +2629,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;
@@ -3403,6 +3515,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-builder.d.ts

@@ -675,6 +675,8 @@ declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    format?: TemporalBucketFormat;
+    semanticTemporalPresentation?: SemaphorMatrixSemanticTemporalPresentation;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -683,7 +685,7 @@ declare type SemaphorMatrixAxisLevel = {
 declare type SemaphorMatrixAxisSortRule = {
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -738,12 +740,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;
@@ -990,6 +997,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 type WorkspaceContext = {
     projectRoot?: string;
     framework?: string;

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

@@ -307,7 +307,7 @@ declare type SemaphorDataAppCodegenMatrixIntent = {
 
 declare type SemaphorDataAppCodegenMatrixSortRule = Omit<SemaphorMatrixSortRule, 'by'> & {
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorDataAppCodegenFieldRef;
@@ -825,6 +825,8 @@ declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
     grain?: SemaphorMatrixTimeGrain;
+    format?: TemporalBucketFormat;
+    semanticTemporalPresentation?: SemaphorMatrixSemanticTemporalPresentation;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -833,7 +835,7 @@ declare type SemaphorMatrixAxisLevel = {
 declare type SemaphorMatrixAxisSortRule = {
     direction: 'asc' | 'desc';
     by: {
-        kind: 'label';
+        kind: 'member';
     } | {
         kind: 'field';
         field: SemaphorFieldRef;
@@ -888,12 +890,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;
@@ -1142,6 +1149,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): {