react-semaphor 0.1.444 → 0.1.445

package/dist/surfboard/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../chunks/dashboard-DxZuqe8t.js"),r=require("../chunks/common-types-C73-Ud1-.js"),o=require("../chunks/report-preferences-dialog-D5sIaFnb.js");exports.DisplayFormatPreferencesFields=e.DisplayFormatPreferencesFields;exports.Surfboard=e.DashboardPlus;exports.CONTROL_CARD_DEFAULT_VALUE=r.CONTROL_CARD_DEFAULT_VALUE;exports.EMPTY_SELECTION=r.EMPTY_SELECTION;exports.ReportPreferencesDialog=o.ReportPreferencesDialog;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../chunks/dashboard-CAiwJW3L.cjs"),r=require("../chunks/common-types-CQ6SHfLk.cjs"),o=require("../chunks/report-preferences-dialog-r8QzOSFb.cjs");exports.DisplayFormatPreferencesFields=e.DisplayFormatPreferencesFields;exports.Surfboard=e.DashboardPlus;exports.CONTROL_CARD_DEFAULT_VALUE=r.CONTROL_CARD_DEFAULT_VALUE;exports.EMPTY_SELECTION=r.EMPTY_SELECTION;exports.ReportPreferencesDialog=o.ReportPreferencesDialog;

package/dist/surfboard/index.js

@@ -1,6 +1,6 @@
-import { a, b as o } from "../chunks/dashboard-CJNVq8XI.js";
-import { C as f, E } from "../chunks/common-types-ClkOI-3O.js";
-import { R as t } from "../chunks/report-preferences-dialog-Dq7rmN93.js";
+import { a, b as o } from "../chunks/dashboard-u61yfU6u.js";
+import { C as f, E } from "../chunks/common-types-DFsDdpH7.js";
+import { R as t } from "../chunks/report-preferences-dialog-D_NJu2wU.js";
 export {
   f as CONTROL_CARD_DEFAULT_VALUE,
   a as DisplayFormatPreferencesFields,

package/dist/types/analytics-protocol.d.ts

@@ -56,6 +56,21 @@ export declare function buildSemaphorQualifiedSourcePath(input: {
     quoteIdentifier?: (value: string, dialect: SemaphorDialect) => string;
 }): string;
 
+declare type CalendarContext = {
+    tz: string;
+    weekStart: WeekStart;
+    anchor: 'now' | {
+        iso: string;
+    };
+    fiscalCalendar?: MonthAlignedFiscalCalendar;
+};
+
+export declare type CanonicalDashboardRecordsPayload = DashboardRecordsPayload & {
+    columns: SemaphorResultColumn[];
+};
+
+export declare const canonicalDashboardRecordsPayloadSchema: z.ZodType<CanonicalDashboardRecordsPayload>;
+
 export declare const COMPARISON_PRESENTATION_DEFAULTS: {
     readonly displayMode: "difference";
     readonly showComparison: true;
@@ -124,6 +139,14 @@ export declare type DashboardDateComparisonOwner = {
     label: string;
 };
 
+export declare type DashboardRecordsPayload = {
+    records: Array<Record<string, unknown>>;
+    columns?: SemaphorResultColumn[];
+    [key: string]: unknown;
+};
+
+export declare const dashboardRecordsPayloadSchema: z.ZodType<DashboardRecordsPayload>;
+
 export declare const DEFAULT_METRIC_COMPARISON_POLARITY: "higher_is_better";
 
 export declare function evaluateMetricComparison(input: {
@@ -169,6 +192,17 @@ export declare type GlobalDateComparisonSelection = {
     spec: ViewerPeriodComparisonSpec;
 };
 
+/**
+ * Authoring boundary for a dashboard field that is known to be grouped by a
+ * temporal grain. The broad persisted field types remain intentionally
+ * compatible with unmigrated/non-temporal fields; new temporal writers use
+ * this boundary instead.
+ */
+export declare type GroupedTemporalAuthoringInput<TBase extends object> = Omit<TBase, 'granularity' | 'format'> & {
+    granularity: SemaphorTimeGrain;
+    format?: TemporalBucketFormat;
+};
+
 export declare function hasCompleteSemaphorSourceIdentity(source: SemaphorSourceRef | undefined): boolean;
 
 export declare function isAnalyticsCatalogDateField(field: AnalyticsCatalogField): boolean;
@@ -191,12 +225,16 @@ export declare function isSemaphorAnalyzeResultFieldName(value: string): value i
 
 export declare function isSemaphorDataAppCodegenSummary(value: unknown): value is SemaphorDataAppCodegenSummary;
 
+export declare function isSemaphorMatrixTimeGrain(value: unknown): value is SemaphorMatrixTimeGrain;
+
+export declare function isSemaphorTimeGrain(value: unknown): value is SemaphorTimeGrain;
+
 export declare type MatrixAxisLevelDescriptor = {
     instanceId: string;
     fieldKey: string;
     label: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     subtotal?: SemaphorMatrixSubtotalOptions;
 };
 
@@ -378,7 +416,7 @@ export declare type MatrixMeasureDescriptor = {
     label: string;
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -392,7 +430,7 @@ export declare type MatrixMeasureSemantics = {
 } | {
     kind: 'semiAdditive';
     aggregate?: SemaphorAggregateFunction;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
 } | {
     kind: 'nonAdditive';
     aggregate?: SemaphorAggregateFunction;
@@ -596,7 +634,7 @@ export declare type MetricComparisonSpec = {
     targetValue: number;
 };
 
-export declare type MetricComparisonWindowGrain = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+export declare type MetricComparisonWindowGrain = SemaphorTimeGrain;
 
 export declare type MetricResultAliasInput = {
     alias?: string;
@@ -607,10 +645,24 @@ export declare type MetricResultAliasInput = {
     expression?: string;
 };
 
+declare type MonthAlignedFiscalCalendar = {
+    kind: 'month_aligned';
+    yearStartMonth: number;
+};
+
 export declare function normalizeAnalyticsCatalogDataType(value: unknown): AnalyticsCatalogDataType;
 
 export declare function normalizeAnalyticsCatalogName(value: unknown): string;
 
+/**
+ * Downstream normalized grouped fields always carry explicit presentation;
+ * an omitted authored format is materialized as `auto` by the Phase B adapter.
+ */
+export declare type NormalizedGroupedTemporalField<TBase extends object> = Omit<TBase, 'granularity' | 'format'> & {
+    granularity: SemaphorTimeGrain;
+    format: TemporalBucketFormat;
+};
+
 export declare function normalizeSemaphorAnalyticsFilterOperator(value: SemaphorAnalyticsFilterOperator | string | null | undefined): SemaphorAnalyticsFilterOperator | undefined;
 
 export declare function normalizeSemaphorDialect(input: string | undefined): SemaphorDialect;
@@ -646,6 +698,29 @@ export declare type ResolvedMetricComparisonRequest = {
     owner?: DashboardDateComparisonOwner;
 };
 
+export declare type ResolvedPrimaryDateField = (ResolvedPrimaryDateFieldBase & ({
+    defaultGranularity?: SemaphorTimeGrain;
+    format?: undefined;
+} | {
+    defaultGranularity: SemaphorTimeGrain;
+    format: TemporalBucketFormat;
+})) | null;
+
+declare type ResolvedPrimaryDateFieldBase = {
+    sourceDataset: string;
+    sourceField: string;
+    name: string;
+    qualifiedFieldName: string;
+    qualifiedEntityName?: string;
+    entityId: string;
+    entityName: string;
+    entityType: string;
+    dataType: string;
+    /** Canonical dataset coordinates stamped by the semantic grounding boundary. */
+    source?: SemaphorSourceRef;
+    supportedGranularities?: SemaphorTimeGrain[];
+};
+
 export declare type ResolvedTemporalContext = {
     status: 'resolved';
     field: SourceBearingTemporalField;
@@ -686,6 +761,15 @@ export declare function semanticDatasetMatchesFieldCoordinates(dataset: {
     entityName?: unknown;
 }): boolean;
 
+/**
+ * Semantic temporal input permits total omission, but a format can only exist
+ * in the branch that declares its grain.
+ */
+export declare type SemanticGroupedTemporalInput<TBase extends object> = (Omit<TBase, 'granularity' | 'format'> & {
+    granularity?: undefined;
+    format?: undefined;
+}) | GroupedTemporalAuthoringInput<TBase>;
+
 export declare const SEMAPHOR_ANALYTICS_INTENT_FIXTURES: {
     revenueKpi: {
         version: 1;
@@ -946,6 +1030,13 @@ export declare const SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_SCHEMA_VERSION: "semaphor
 
 export declare const SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_VALIDATOR_VERSION: "semaphor-data-app-codegen-summary-validator/v2";
 
+/** Stable field identity for the query builder's generated Count measure. */
+export declare const SEMAPHOR_GENERATED_COUNT_METRIC_ID: "__auto_count__";
+
+export declare const SEMAPHOR_MATRIX_TIME_GRAINS: ["hour", "day", "week", "month", "quarter", "year"];
+
+export declare const SEMAPHOR_TIME_GRAINS: readonly ["second", "minute", "hour", "day", "week", "month", "quarter", "year"];
+
 export declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -2521,7 +2612,7 @@ export declare type SemaphorDataAppCodegenMatrixIntent = {
     rows: Array<{
         id?: string;
         field?: SemaphorDataAppCodegenFieldRef;
-        grain?: SemaphorTimeGrain;
+        grain?: SemaphorMatrixTimeGrain;
         label?: string;
         subtotal?: boolean | {
             enabled?: boolean;
@@ -2531,7 +2622,7 @@ export declare type SemaphorDataAppCodegenMatrixIntent = {
     columns?: Array<{
         id?: string;
         field?: SemaphorDataAppCodegenFieldRef;
-        grain?: SemaphorTimeGrain;
+        grain?: SemaphorMatrixTimeGrain;
         label?: string;
         subtotal?: boolean | {
             enabled?: boolean;
@@ -2912,7 +3003,7 @@ export declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -3124,7 +3215,7 @@ export declare type SemaphorMatrixAxisExpansionOptions = {
 export declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -3242,6 +3333,8 @@ export declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+export declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 export declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -3277,7 +3370,7 @@ export declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -3563,6 +3656,30 @@ export declare const semaphorPhysicalSourceRefSchema: z.ZodObject<{
     dialect: z.ZodOptional<z.ZodEnum<["postgres", "mysql", "mssql", "snowflake", "clickhouse", "bigquery", "redshift", "duckdb", "sqlite", "unknown"]>>;
 }, z.ZodTypeAny, "passthrough">>;
 
+export 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[];
+};
+
+export 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. */
+export declare type SemaphorPivotValue = string | null;
+
 export declare type SemaphorProtocolIssue = {
     code: string;
     message: string;
@@ -3798,7 +3915,7 @@ export declare type SemaphorRelationshipHint = {
 
 export 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';
@@ -3839,7 +3956,7 @@ export declare type SemaphorResultCalculationOutput = {
     key: string;
     label?: string;
     dataType?: SemaphorFieldRef['dataType'];
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
 };
 
 export declare type SemaphorResultColumn = {
@@ -3861,6 +3978,8 @@ export declare type SemaphorResultColumn = {
     aggregate?: SemaphorFieldRef['aggregate'];
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
+    temporalBucket?: TemporalBucketMetadata;
+    pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };
 
 export declare type SemaphorResultColumnRef = {
@@ -3871,6 +3990,43 @@ export declare type SemaphorResultColumnRef = {
 
 export declare const semaphorResultColumnSchema: z.ZodType<SemaphorResultColumn>;
 
+export 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 SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
     kind: 'semantic';
 }>;
@@ -4123,7 +4279,9 @@ export declare const semaphorSqlSourceRefSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
 }, z.ZodTypeAny, "passthrough">>;
 
-export declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+export declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
+
+export declare const semaphorTimeGrainSchema: z.ZodEnum<["second", "minute", "hour", "day", "week", "month", "quarter", "year"]>;
 
 export declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
@@ -4133,42 +4291,7 @@ export declare type SemaphorValidationResult = {
     warnings: SemaphorProtocolIssue[];
 };
 
-export 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 type SemaphorValueFormat = SemaphorScalarValueFormat | TemporalBucketFormat;
 
 export declare type SemaphorViewPresentation = {
     kind: 'kpi';
@@ -4191,6 +4314,14 @@ export declare type SourceBearingTemporalField = SemaphorFieldRef & {
     source: SemaphorSourceRef;
 };
 
+export declare const TEMPORAL_BUCKET_CONTRACT_ERROR_CODES: {
+    readonly missingMetadata: "missing_temporal_bucket_metadata";
+    readonly invalidMetadata: "invalid_temporal_bucket_metadata";
+    readonly invalidValue: "invalid_temporal_bucket_value";
+};
+
+export declare const TEMPORAL_BUCKET_PRESETS: readonly ["week_of_short", "week_of_long", "quarter_short", "quarter_long", "fiscal_quarter_short", "fiscal_year"];
+
 export declare const TEMPORAL_CONTEXT_ADAPTER_PARITY_FIXTURES: {
     readonly visibleAxis: {
         readonly source: {
@@ -4232,6 +4363,64 @@ export declare type TemporalBindingCandidate = {
     field: SourceBearingTemporalField;
 };
 
+export declare type TemporalBucketContractError = {
+    code: TemporalBucketContractErrorCode;
+    message: string;
+    path?: string;
+};
+
+export declare type TemporalBucketContractErrorCode = (typeof TEMPORAL_BUCKET_CONTRACT_ERROR_CODES)[keyof typeof TEMPORAL_BUCKET_CONTRACT_ERROR_CODES];
+
+export declare function temporalBucketDataTypeForGrain(granularity: SemaphorTimeGrain): 'date' | 'datetime';
+
+export declare type TemporalBucketFormat = {
+    type: 'temporal_bucket';
+    presentation: TemporalBucketPresentation;
+};
+
+export declare const temporalBucketFormatSchema: z.ZodType<TemporalBucketFormat>;
+
+export declare type TemporalBucketMetadata = {
+    kind: 'temporal_bucket';
+    granularity: SemaphorTimeGrain;
+    calendar: Pick<CalendarContext, 'tz' | 'weekStart' | 'fiscalCalendar'>;
+};
+
+export declare const temporalBucketMetadataSchema: z.ZodType<TemporalBucketMetadata>;
+
+export declare type TemporalBucketMetadataValidationResult = {
+    ok: true;
+    value?: TemporalBucketMetadata;
+} | {
+    ok: false;
+    error: TemporalBucketContractError;
+};
+
+export declare type TemporalBucketPresentation = {
+    mode: 'auto';
+} | {
+    mode: 'preset';
+    preset: TemporalBucketPreset;
+} | {
+    mode: 'pattern';
+    pattern: string;
+};
+
+export declare type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
+
+export declare type TemporalBucketResultColumnExpectation = {
+    key: string;
+    metadata: TemporalBucketMetadata;
+};
+
+export declare type TemporalBucketResultColumnsValidationResult = {
+    ok: true;
+    value: SemaphorResultColumn[];
+} | {
+    ok: false;
+    error: TemporalBucketContractError;
+};
+
 export declare type TemporalRangeCandidate = {
     id: string;
     source: 'global_date' | 'card';
@@ -4239,6 +4428,13 @@ export declare type TemporalRangeCandidate = {
     window: ResolvedDateWindow;
 };
 
+/**
+ * Validates the atomic column boundary for an activated canonical producer.
+ * Expected keys come from the producer's typed field/output mapping; this
+ * function never infers temporal meaning from row values or labels.
+ */
+export declare function validateActivatedTemporalBucketResultColumns(columns: SemaphorResultColumn[], expectedColumns: TemporalBucketResultColumnExpectation[]): TemporalBucketResultColumnsValidationResult;
+
 export declare function validateComparisonPresentationSpec(value: unknown, path?: string): SemaphorValidationResult;
 
 export declare function validateGlobalDateComparisonContext(value: unknown, path?: string): SemaphorValidationResult;
@@ -4268,8 +4464,21 @@ export declare function validateSemaphorOperationIntent(intent: SemaphorOperatio
 
 export declare function validateSemaphorResultCalculation(calculation: SemaphorResultCalculation): SemaphorValidationResult;
 
+export declare function validateTemporalBucketMetadata(metadata: unknown): TemporalBucketMetadataValidationResult;
+
+/**
+ * Validates the temporal descriptor at an activated result-column boundary.
+ * Callers must state whether that producer is expected to return a bucket;
+ * this function never infers temporal meaning from values or labels.
+ */
+export declare function validateTemporalBucketResultColumn(column: Pick<SemaphorResultColumn, 'dataType' | 'temporalBucket'>, options: {
+    metadataRequired: boolean;
+}): TemporalBucketMetadataValidationResult;
+
 export declare type ViewerPeriodComparisonSpec = Extract<MetricComparisonSpec, {
     kind: 'previous_period' | 'previous_year';
 }>;
 
+declare type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
 export { }