react-semaphor 0.1.498 → 0.1.499

package/dist/types/main.d.ts

@@ -4621,6 +4621,8 @@ export declare const CALCULATED_FIELD_ENTITY_MARKER: "SEMAPHOR_CALCULATED_FIELD"
  */
 export declare interface CalculatedFieldFormula {
     operation: CalculatedFieldOperation;
+    /** Evaluation stage of the definition, independent of its selected shelf. */
+    computeStage?: 'row' | 'aggregate';
     /**
      * Array of full MetricField objects used as inputs to the calculated field.
      *
@@ -4648,6 +4650,32 @@ export declare interface CalculatedFieldFormula {
     constant?: number;
 }
 
+/** Metadata surface needed to classify a field without requiring shelf UI fields. */
+export declare type CalculatedFieldInspectable = {
+    calculationRepresentation?: Field['calculationRepresentation'];
+    name?: string;
+    sourceField?: string;
+    role?: Field['role'];
+    entityName?: string;
+    entityId?: string;
+    qualifiedEntityName?: string;
+    fieldScope?: FieldScope;
+    expression?: string;
+    calculatedFormula?: CalculatedFieldFormula;
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    derivedField?: SemaphorDerivedFieldDefinition;
+};
+
+export declare type CalculatedFieldInspection = {
+    representation: 'physical' | 'inline-expression' | 'manual' | 'typed-derived';
+    ownership: 'local' | 'domain';
+    completeness: 'not-calculated' | 'complete' | 'incomplete';
+    computeStage?: 'row' | 'aggregate';
+    runtimeExecutable: boolean;
+    /** Compatibility mode for local runtime fields created before stage metadata. */
+    legacyManual: boolean;
+};
+
 /**
  * Operations supported for calculated fields
  */
@@ -10578,6 +10606,19 @@ export declare interface Field {
      */
     semanticTemporalPresentation?: SemanticTemporalPresentation;
     aggregate?: AggregateFunction;
+    /** Whether this placement aggregate was supplied by the editor or authored. Omitted means unknown. */
+    aggregateOrigin?: 'default' | 'explicit';
+    /** Runtime representation, independent of definition ownership and shelf role. */
+    calculationRepresentation?: 'inline-expression' | 'manual' | 'typed-derived';
+    /** Definition identity survives timestamped shelf IDs and changes of placement role. */
+    calculatedFieldOrigin?: {
+        id: string;
+        role?: Field['role'];
+    };
+    /** Provenance for display metadata on governed fields. Unmarked legacy values are semantic snapshots. */
+    labelOrigin?: 'semantic' | 'override';
+    /** Provenance for display formatting on governed fields. Unmarked legacy values are semantic snapshots. */
+    formatOrigin?: 'semantic' | 'override';
     fieldScope?: FieldScope;
 }
 
@@ -10664,7 +10705,7 @@ export declare type FilterDashboardInputDefinitionUpdateResult = {
  */
 declare type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
 
-declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
+declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope' | 'calculationRepresentation' | 'calculatedFieldOrigin' | 'derivedField'>> & {
     entityName?: Field['entityName'];
     entityType?: string;
     /** Exact database type used by server-side predicate formatting. */
@@ -10908,6 +10949,8 @@ export declare function getBriefingPreviewRun(apiServiceUrl: string, token: stri
 
 export declare function getBriefingRun(apiServiceUrl: string, token: string, briefingId: string, runId: string): Promise<BriefingRun>;
 
+export declare function getCalculatedFieldComputeStage(field: CalculatedFieldInspectable | null | undefined): 'row' | 'aggregate' | undefined;
+
 export declare function getColumnDataType(column: TDataColumn): string;
 
 export declare type GetDashboardResponse = {
@@ -11087,6 +11130,13 @@ export declare type InputReference = {
     dimension: string;
 };
 
+/**
+ * Inspect a runtime field without conflating public typed-derived metadata with
+ * the dashboard-local expression/formula representation. Consumers use this
+ * result for classification and stage; each compiler still owns execution.
+ */
+export declare function inspectCalculatedField(field: CalculatedFieldInspectable | null | undefined): CalculatedFieldInspection;
+
 /**
  * Unified Interaction type (V2)
  * Combines all interaction types into a single union for the new interactions array.
@@ -11220,11 +11270,6 @@ export declare function isCalculatedDimension(field: GroupByField): field is Gro
     expression: string;
 };
 
-/**
- * Generic type guard for any calculated field
- */
-export declare function isCalculatedField(field: Field): boolean;
-
 /**
  * IMPORTANT: Why we store qualifiedFieldNames as strings instead of Field objects
  *
@@ -11252,10 +11297,10 @@ export declare function isDateDataType(dataType: string): boolean;
  * True for every representation of a derived (calculated) field:
  * an expression, formula inputs, the shared-contract `derivedField`
  * (the only shape Matrix-authored calculations may carry), or a synthetic
- * calculated-field owner. Use this, not `isCalculatedField`, wherever the
+ * calculated-field owner. Use this wherever the
  * question is "is this computed rather than stored".
  */
-export declare function isDerivedField(field: Field | null | undefined): boolean;
+export declare function isDerivedField(field: CalculatedFieldInspectable | null | undefined): boolean;
 
 /**
  * Check if an export has completed (successfully or with failure)
@@ -20012,6 +20057,10 @@ declare type MonthAlignedFiscalCalendar = {
 
 declare type NoneOptions = {};
 
+/** Normalize unannotated saved shapes once, before attaching placement/scope
+ * metadata. Never replaces an explicit tag, even if invalid: validation owns it. */
+export declare function normalizeCalculatedFieldRepresentation<T extends CalculatedFieldInspectable>(field: T): T;
+
 /**
  * Normalizes dashboard layout objects into a canonical structure:
  * - strips transient react-grid-layout runtime fields
@@ -22836,6 +22885,9 @@ declare type ShareRole = 'VIEWER' | 'EDITOR' | 'CONTRIBUTOR';
 
 declare type ShareScope = 'specific_tenant_user' | 'all_tenant_users' | 'specific_org_user' | 'all_org_users' | 'org_users_only' | 'all_tenants_only';
 
+/** Only a proven inherited default may be removed for an aggregate-stage definition. */
+export declare function shouldDropInheritedCalculationAggregate(computeStage: 'row' | 'aggregate' | undefined, aggregateOrigin: MetricField['aggregateOrigin']): boolean;
+
 export declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';
@@ -25153,6 +25205,13 @@ export declare type TDataColumn = {
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
     derivedField?: SemaphorDerivedFieldDefinition;
+    fieldScope?: FieldScope;
+    source?: Field['source'];
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    calculationRepresentation?: Field['calculationRepresentation'];
+    aggregateOrigin?: Field['aggregateOrigin'];
+    labelOrigin?: Field['labelOrigin'];
+    formatOrigin?: Field['formatOrigin'];
     format?: FormatSpec;
     granularity?: TimeGranularity;
     sourceField?: string;

package/dist/types/shared.d.ts

@@ -311,6 +311,8 @@ declare type CacheConfig = {
  */
 declare interface CalculatedFieldFormula {
     operation: CalculatedFieldOperation;
+    /** Evaluation stage of the definition, independent of its selected shelf. */
+    computeStage?: 'row' | 'aggregate';
     /**
      * Array of full MetricField objects used as inputs to the calculated field.
      *
@@ -4839,6 +4841,19 @@ declare interface Field {
      */
     semanticTemporalPresentation?: SemanticTemporalPresentation;
     aggregate?: AggregateFunction;
+    /** Whether this placement aggregate was supplied by the editor or authored. Omitted means unknown. */
+    aggregateOrigin?: 'default' | 'explicit';
+    /** Runtime representation, independent of definition ownership and shelf role. */
+    calculationRepresentation?: 'inline-expression' | 'manual' | 'typed-derived';
+    /** Definition identity survives timestamped shelf IDs and changes of placement role. */
+    calculatedFieldOrigin?: {
+        id: string;
+        role?: Field['role'];
+    };
+    /** Provenance for display metadata on governed fields. Unmarked legacy values are semantic snapshots. */
+    labelOrigin?: 'semantic' | 'override';
+    /** Provenance for display formatting on governed fields. Unmarked legacy values are semantic snapshots. */
+    formatOrigin?: 'semantic' | 'override';
     fieldScope?: FieldScope;
 }
 
@@ -4903,7 +4918,7 @@ declare type FilterDashboardInputBase = DashboardInputBase & {
  */
 declare type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
 
-declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
+declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope' | 'calculationRepresentation' | 'calculatedFieldOrigin' | 'derivedField'>> & {
     entityName?: Field['entityName'];
     entityType?: string;
     /** Exact database type used by server-side predicate formatting. */

package/dist/types/surfboard.d.ts

@@ -403,6 +403,8 @@ export declare type CacheConfig = {
  */
 declare interface CalculatedFieldFormula {
     operation: CalculatedFieldOperation;
+    /** Evaluation stage of the definition, independent of its selected shelf. */
+    computeStage?: 'row' | 'aggregate';
     /**
      * Array of full MetricField objects used as inputs to the calculated field.
      *
@@ -5213,6 +5215,19 @@ declare interface Field {
      */
     semanticTemporalPresentation?: SemanticTemporalPresentation;
     aggregate?: AggregateFunction;
+    /** Whether this placement aggregate was supplied by the editor or authored. Omitted means unknown. */
+    aggregateOrigin?: 'default' | 'explicit';
+    /** Runtime representation, independent of definition ownership and shelf role. */
+    calculationRepresentation?: 'inline-expression' | 'manual' | 'typed-derived';
+    /** Definition identity survives timestamped shelf IDs and changes of placement role. */
+    calculatedFieldOrigin?: {
+        id: string;
+        role?: Field['role'];
+    };
+    /** Provenance for display metadata on governed fields. Unmarked legacy values are semantic snapshots. */
+    labelOrigin?: 'semantic' | 'override';
+    /** Provenance for display formatting on governed fields. Unmarked legacy values are semantic snapshots. */
+    formatOrigin?: 'semantic' | 'override';
     fieldScope?: FieldScope;
 }
 
@@ -5277,7 +5292,7 @@ declare type FilterDashboardInputBase = DashboardInputBase & {
  */
 declare type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
 
-declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
+declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope' | 'calculationRepresentation' | 'calculatedFieldOrigin' | 'derivedField'>> & {
     entityName?: Field['entityName'];
     entityType?: string;
     /** Exact database type used by server-side predicate formatting. */
@@ -10306,6 +10321,13 @@ export declare type TDataColumn = {
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
     derivedField?: SemaphorDerivedFieldDefinition;
+    fieldScope?: FieldScope;
+    source?: Field['source'];
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    calculationRepresentation?: Field['calculationRepresentation'];
+    aggregateOrigin?: Field['aggregateOrigin'];
+    labelOrigin?: Field['labelOrigin'];
+    formatOrigin?: Field['formatOrigin'];
     format?: FormatSpec;
     granularity?: TimeGranularity;
     sourceField?: string;

package/dist/types/types.d.ts

@@ -877,6 +877,8 @@ export declare const CALCULATED_FIELD_ENTITY_MARKER: "SEMAPHOR_CALCULATED_FIELD"
  */
 export declare interface CalculatedFieldFormula {
     operation: CalculatedFieldOperation;
+    /** Evaluation stage of the definition, independent of its selected shelf. */
+    computeStage?: 'row' | 'aggregate';
     /**
      * Array of full MetricField objects used as inputs to the calculated field.
      *
@@ -904,6 +906,32 @@ export declare interface CalculatedFieldFormula {
     constant?: number;
 }
 
+/** Metadata surface needed to classify a field without requiring shelf UI fields. */
+export declare type CalculatedFieldInspectable = {
+    calculationRepresentation?: Field['calculationRepresentation'];
+    name?: string;
+    sourceField?: string;
+    role?: Field['role'];
+    entityName?: string;
+    entityId?: string;
+    qualifiedEntityName?: string;
+    fieldScope?: FieldScope;
+    expression?: string;
+    calculatedFormula?: CalculatedFieldFormula;
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    derivedField?: SemaphorDerivedFieldDefinition;
+};
+
+export declare type CalculatedFieldInspection = {
+    representation: 'physical' | 'inline-expression' | 'manual' | 'typed-derived';
+    ownership: 'local' | 'domain';
+    completeness: 'not-calculated' | 'complete' | 'incomplete';
+    computeStage?: 'row' | 'aggregate';
+    runtimeExecutable: boolean;
+    /** Compatibility mode for local runtime fields created before stage metadata. */
+    legacyManual: boolean;
+};
+
 /**
  * Operations supported for calculated fields
  */
@@ -5863,6 +5891,19 @@ export declare interface Field {
      */
     semanticTemporalPresentation?: SemanticTemporalPresentation;
     aggregate?: AggregateFunction;
+    /** Whether this placement aggregate was supplied by the editor or authored. Omitted means unknown. */
+    aggregateOrigin?: 'default' | 'explicit';
+    /** Runtime representation, independent of definition ownership and shelf role. */
+    calculationRepresentation?: 'inline-expression' | 'manual' | 'typed-derived';
+    /** Definition identity survives timestamped shelf IDs and changes of placement role. */
+    calculatedFieldOrigin?: {
+        id: string;
+        role?: Field['role'];
+    };
+    /** Provenance for display metadata on governed fields. Unmarked legacy values are semantic snapshots. */
+    labelOrigin?: 'semantic' | 'override';
+    /** Provenance for display formatting on governed fields. Unmarked legacy values are semantic snapshots. */
+    formatOrigin?: 'semantic' | 'override';
     fieldScope?: FieldScope;
 }
 
@@ -5951,7 +5992,7 @@ declare type FilterDashboardInputBase = DashboardInputBase & {
  */
 declare type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
 
-export declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
+export declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope' | 'calculationRepresentation' | 'calculatedFieldOrigin' | 'derivedField'>> & {
     entityName?: Field['entityName'];
     entityType?: string;
     /** Exact database type used by server-side predicate formatting. */
@@ -6129,6 +6170,8 @@ export declare type FormatSpec = {
     suffix?: string;
 } | TemporalBucketFormat;
 
+export declare function getCalculatedFieldComputeStage(field: CalculatedFieldInspectable | null | undefined): 'row' | 'aggregate' | undefined;
+
 export declare type GetDashboardResponse = {
     dashboard: TDashboard;
     initialReportContext: ReportRuntimeContext;
@@ -6259,6 +6302,13 @@ export declare type InputReference = {
     dimension: string;
 };
 
+/**
+ * Inspect a runtime field without conflating public typed-derived metadata with
+ * the dashboard-local expression/formula representation. Consumers use this
+ * result for classification and stage; each compiler still owns execution.
+ */
+export declare function inspectCalculatedField(field: CalculatedFieldInspectable | null | undefined): CalculatedFieldInspection;
+
 /**
  * Unified Interaction type (V2)
  * Combines all interaction types into a single union for the new interactions array.
@@ -6361,11 +6411,6 @@ export declare function isCalculatedDimension(field: GroupByField): field is Gro
     expression: string;
 };
 
-/**
- * Generic type guard for any calculated field
- */
-export declare function isCalculatedField(field: Field): boolean;
-
 /**
  * IMPORTANT: Why we store qualifiedFieldNames as strings instead of Field objects
  *
@@ -6389,10 +6434,10 @@ export declare function isCalculatedMetric(field: Field): field is MetricField &
  * True for every representation of a derived (calculated) field:
  * an expression, formula inputs, the shared-contract `derivedField`
  * (the only shape Matrix-authored calculations may carry), or a synthetic
- * calculated-field owner. Use this, not `isCalculatedField`, wherever the
+ * calculated-field owner. Use this wherever the
  * question is "is this computed rather than stored".
  */
-export declare function isDerivedField(field: Field | null | undefined): boolean;
+export declare function isDerivedField(field: CalculatedFieldInspectable | null | undefined): boolean;
 
 export declare interface Join {
     id: string;
@@ -6696,6 +6741,10 @@ declare type MonthAlignedFiscalCalendar = {
 
 declare type NoneOptions = {};
 
+/** Normalize unannotated saved shapes once, before attaching placement/scope
+ * metadata. Never replaces an explicit tag, even if invalid: validation owns it. */
+export declare function normalizeCalculatedFieldRepresentation<T extends CalculatedFieldInspectable>(field: T): T;
+
 export declare type NormalizedDashboardInput = NormalizedFilterDashboardInput | ControlDashboardInput;
 
 /** Runtime form after dashboard-filter references are resolved once. */
@@ -9112,6 +9161,9 @@ declare type SemaphorSourceRef = {
 
 declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
+/** Only a proven inherited default may be removed for an aggregate-stage definition. */
+export declare function shouldDropInheritedCalculationAggregate(computeStage: 'row' | 'aggregate' | undefined, aggregateOrigin: MetricField['aggregateOrigin']): boolean;
+
 export declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';
@@ -11338,6 +11390,13 @@ export declare type TDataColumn = {
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
     derivedField?: SemaphorDerivedFieldDefinition;
+    fieldScope?: FieldScope;
+    source?: Field['source'];
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    calculationRepresentation?: Field['calculationRepresentation'];
+    aggregateOrigin?: Field['aggregateOrigin'];
+    labelOrigin?: Field['labelOrigin'];
+    formatOrigin?: Field['formatOrigin'];
     format?: FormatSpec;
     granularity?: TimeGranularity;
     sourceField?: string;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.498",
+  "version": "0.1.499",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",