react-semaphor 0.1.503 → 0.1.505

package/dist/types/shared/analytics-protocol/scalar-value.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+export { canonicalizeExactNumericText, normalizeNumericLiteral } from './exact-decimal.js';
+export declare const exactNumericValueSchema: z.ZodEffects<z.ZodObject<{
+    kind: z.ZodLiteral<"exact_number">;
+    type: z.ZodEnum<["integer", "decimal"]>;
+    value: z.ZodEffects<z.ZodString, string, string>;
+}, "strict", z.ZodTypeAny, {
+    value: string;
+    type: "integer" | "decimal";
+    kind: "exact_number";
+}, {
+    value: string;
+    type: "integer" | "decimal";
+    kind: "exact_number";
+}>, {
+    value: string;
+    type: "integer" | "decimal";
+    kind: "exact_number";
+}, {
+    value: string;
+    type: "integer" | "decimal";
+    kind: "exact_number";
+}>;
+export type ExactNumericValue = z.infer<typeof exactNumericValueSchema>;
+export declare const semaphorScalarValueSchema: z.ZodUnion<[z.ZodNull, z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodEffects<z.ZodObject<{
+    kind: z.ZodLiteral<"exact_number">;
+    type: z.ZodEnum<["integer", "decimal"]>;
+    value: z.ZodEffects<z.ZodString, string, string>;
+}, "strict", z.ZodTypeAny, {
+    value: string;
+    type: "integer" | "decimal";
+    kind: "exact_number";
+}, {
+    value: string;
+    type: "integer" | "decimal";
+    kind: "exact_number";
+}>, {
+    value: string;
+    type: "integer" | "decimal";
+    kind: "exact_number";
+}, {
+    value: string;
+    type: "integer" | "decimal";
+    kind: "exact_number";
+}>]>;
+export type SemaphorScalarValue = z.infer<typeof semaphorScalarValueSchema>;
+export declare function createExactNumericValue(value: string, type: ExactNumericValue['type']): ExactNumericValue;
+/** Discriminate already-validated values; use the schema at untrusted boundaries. */
+export declare function isExactNumericValue(value: unknown): value is ExactNumericValue;
+/** Decode a numeric result column; the caller supplies its result-native type. */
+export declare function decodeNumericResultValue(input: {
+    nativeDataType: string;
+    value: unknown;
+    exactText?: string;
+}): ExactNumericValue | number | null;

package/dist/types/shared/analytics-protocol/source-capabilities.d.ts

@@ -0,0 +1,64 @@
+import { SemaphorConnectionCapabilities, SemaphorDialect } from './contracts.js';
+export type SemaphorSourceCoordinateInput = {
+    databaseName?: string;
+    schemaName?: string;
+    tableName?: string;
+};
+/**
+ * Canonicalizes a persisted metadata path. This does not parse authored SQL;
+ * it only unwraps the segment-level double quotes produced by dashboard filter
+ * persistence while preserving identifier case.
+ */
+export declare function canonicalizeSemaphorQualifiedSourcePath(value: string | undefined): string | undefined;
+export declare function parseSemaphorQualifiedSourcePath(input: {
+    qualifiedName: string | undefined;
+    capabilities: Pick<SemaphorConnectionCapabilities, 'prefixLevels'>;
+}): SemaphorSourceCoordinateInput;
+export declare function semaphorPhysicalSourceCoordinatesAreCompatible(input: {
+    left: SemaphorSourceCoordinateInput;
+    right: SemaphorSourceCoordinateInput;
+    capabilities: Pick<SemaphorConnectionCapabilities, 'prefixLevels'>;
+}): boolean;
+/**
+ * Returns whether an allowed physical source contains every coordinate named
+ * by the requested source. Unlike symmetric compatibility, a missing allowed
+ * coordinate cannot satisfy a more-qualified request.
+ */
+export declare function semaphorPhysicalSourceCoordinatesCover(input: {
+    requested: SemaphorSourceCoordinateInput;
+    allowed: SemaphorSourceCoordinateInput;
+    capabilities: Pick<SemaphorConnectionCapabilities, 'prefixLevels'>;
+}): boolean;
+export declare function getSemaphorConnectionCapabilities(connectionType: string | undefined, options?: {
+    connectionId?: string;
+}): SemaphorConnectionCapabilities;
+/**
+ * Resolves only connector types or normalized dialects whose coordinate
+ * grammar is known. Callers that parse persisted identities must not inherit
+ * PostgreSQL defaults for absent or unknown capability evidence.
+ */
+export declare function resolveSemaphorConnectionCapabilities(connectionTypeOrDialect: string | undefined, options?: {
+    connectionId?: string;
+}): SemaphorConnectionCapabilities | undefined;
+/**
+ * Returns the normalized connector/dialect family used to distinguish true
+ * aliases from distinct connectors that happen to share one grammar.
+ */
+export declare function resolveSemaphorConnectionCapabilityIdentity(connectionTypeOrDialect: string | undefined): string | undefined;
+export declare function normalizeSemaphorDialect(input: string | undefined): SemaphorDialect;
+export declare function semaphorSourceHasRequiredCoordinates(input: {
+    capabilities: Pick<SemaphorConnectionCapabilities, 'prefixLevels'>;
+    source: SemaphorSourceCoordinateInput;
+}): boolean;
+export declare function buildSemaphorQualifiedSourcePath(input: {
+    capabilities: Pick<SemaphorConnectionCapabilities, 'prefixLevels' | 'dialect'>;
+    source: SemaphorSourceCoordinateInput;
+    quoteIdentifier?: (value: string, dialect: SemaphorDialect) => string;
+}): string;
+/**
+ * The unqualified, unquoted leaf of a persisted identifier path such as
+ * `schema.table.column`, `"Column Name"`, `` `col` `` or `[col]`. Persisted
+ * filter names and columns carry dialect quoting; consumers that need the
+ * bare column name use this instead of hand-rolled string surgery.
+ */
+export declare function persistedIdentifierLeafName(value: string | null | undefined): string;

package/dist/types/shared/analytics-protocol/source-entity-resolution.d.ts

@@ -0,0 +1,80 @@
+import { SemaphorConnectionCapabilities, SemaphorDialect, SemaphorSourceRef } from './contracts.js';
+import { SemaphorPhysicalSourceResolutionBasis } from './physical-source-resolution.js';
+import { SemaphorSourceCoordinateInput } from './source-capabilities.js';
+export type SemaphorResolvedEntitySource = Extract<SemaphorSourceRef, {
+    kind: 'semantic' | 'physical';
+}>;
+export type SemaphorSourceEntityResolutionBasis = SemaphorPhysicalSourceResolutionBasis | 'historical';
+export type SemaphorSourceEntityResolution<T> = {
+    kind: 'resolved';
+    basis: SemaphorSourceEntityResolutionBasis;
+    source: SemaphorResolvedEntitySource;
+    entity?: T;
+} | {
+    kind: 'unqualified';
+} | {
+    kind: 'malformed';
+} | {
+    kind: 'conflicting';
+} | {
+    kind: 'ambiguous';
+    basis: Exclude<SemaphorSourceEntityResolutionBasis, 'unqualified'>;
+} | {
+    kind: 'not_found';
+    basis: Exclude<SemaphorSourceEntityResolutionBasis, 'unqualified'>;
+} | {
+    kind: 'candidate';
+    basis: 'qualified';
+    source: SemaphorResolvedEntitySource;
+} | {
+    kind: 'incompatible_capabilities';
+} | {
+    kind: 'missing_connection';
+};
+export type SemaphorSourceEntityResolutionInput<T> = {
+    entities: readonly T[];
+    semanticDomainId?: string;
+    connectionId?: string;
+    connectionType?: string;
+    dialect?: SemaphorDialect;
+    capabilities?: Pick<SemaphorConnectionCapabilities, 'dialect' | 'prefixLevels'>;
+    fieldEntityType?: string;
+    entityId?: string;
+    entityName?: string;
+    qualifiedHints?: ReadonlyArray<string | undefined>;
+    bareHints?: ReadonlyArray<string | undefined>;
+    fallbackCoordinateHint?: SemaphorSourceCoordinateInput;
+};
+export type SemaphorSemanticDatasetEntityResolution<T> = {
+    kind: 'resolved';
+    basis: 'bare' | 'unqualified';
+    entity: T;
+    source: Extract<SemaphorSourceRef, {
+        kind: 'semantic';
+    }>;
+    matchedById: boolean;
+} | {
+    kind: 'ambiguous';
+    basis: 'bare';
+} | {
+    kind: 'not_found';
+    basis: 'bare';
+} | {
+    kind: 'unqualified';
+};
+export declare function isSemaphorSemanticSourceEntity(value: unknown): boolean;
+/**
+ * Resolves logical semantic identity from dataset metadata. Physical datasets
+ * are excluded by default because the general source resolver must preserve
+ * their execution coordinates. Mapping callers operating inside an explicit
+ * semantic-domain context may opt into projecting those datasets to their
+ * domain/dataset identity.
+ */
+export declare function resolveSemaphorSemanticDatasetEntity<T>(input: SemaphorSourceEntityResolutionInput<T>, options?: {
+    includePhysicalDatasets?: boolean;
+}): SemaphorSemanticDatasetEntityResolution<T>;
+/**
+ * Resolves one persisted selected source without conflating a dataset's
+ * container type with its semantic/physical execution kind.
+ */
+export declare function resolveSemaphorSourceEntity<T>(input: SemaphorSourceEntityResolutionInput<T>): SemaphorSourceEntityResolution<T>;

package/dist/types/shared/analytics-protocol/source-identity.d.ts

@@ -0,0 +1,36 @@
+import { SemaphorAnalyticsIntent, SemaphorFieldRef, SemaphorSourceRef } from './contracts.js';
+/** Matrix identity is definition-bound; optional authored IDs belong to other intents. */
+export declare function getAnalyticsIntentId(intent: SemaphorAnalyticsIntent | undefined): string | undefined;
+type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+/**
+ * Returns the semantic discovery identity carried by a selected dataset.
+ *
+ * Historical selected entities sometimes stored the underlying physical table
+ * in `id`. That coordinate identifies execution, not the semantic dataset, and
+ * must not be promoted into the stronger `datasetId` contract.
+ */
+export declare function getSemaphorDatasetEntityId(entity: {
+    id?: unknown;
+    name?: unknown;
+    table?: unknown;
+}): string | undefined;
+/**
+ * Returns only an identity-strengthening dataset id. Some discovery adapters
+ * use the canonical dataset name as a UI entity id; echoing that same value as
+ * datasetId must not turn name-only identity into a stronger id contract.
+ */
+export declare function getSemaphorNonRedundantDatasetId(source: SemaphorSemanticSourceRef): string | undefined;
+export declare function canonicalizeSemaphorSourceIdentity(source: SemaphorSemanticSourceRef): SemaphorSemanticSourceRef;
+export declare function canonicalizeSemaphorSourceIdentity(source: SemaphorSourceRef): SemaphorSourceRef;
+export declare function hasCompleteSemaphorSourceIdentity(source: SemaphorSourceRef | undefined): boolean;
+export declare function semaphorSourceIdentityKey(source: SemaphorSourceRef | undefined): string;
+export declare function semaphorSourcesReferToSameDataset(left: SemaphorSourceRef | undefined, right: SemaphorSourceRef | undefined): boolean;
+export declare function preferSemaphorSourceMetadata(current: SemaphorSourceRef, next: SemaphorSourceRef): SemaphorSourceRef;
+export declare function mergeSemaphorSourcesByIdentity<TSource extends SemaphorSourceRef>(sources: readonly TSource[]): TSource[];
+export declare function semaphorFieldRefsMatch(left: SemaphorFieldRef, right: SemaphorFieldRef): boolean;
+export declare function semaphorMetricMeasureBindingKey(field: SemaphorFieldRef): string;
+export declare function semaphorMetricAggregate(field: Pick<SemaphorFieldRef, 'aggregate'>): string;
+export declare function preferSemaphorFieldRefMetadata(current: SemaphorFieldRef, next: SemaphorFieldRef): SemaphorFieldRef;
+export {};

package/dist/types/shared/analytics-protocol/temporal-bucket-contract.d.ts

@@ -0,0 +1,39 @@
+import { SemaphorResultColumn, TemporalBucketContractErrorCode, TemporalBucketMetadata } from './contracts.js';
+export type TemporalBucketContractError = {
+    code: TemporalBucketContractErrorCode;
+    message: string;
+    path?: string;
+};
+export type TemporalBucketMetadataValidationResult = {
+    ok: true;
+    value?: TemporalBucketMetadata;
+} | {
+    ok: false;
+    error: TemporalBucketContractError;
+};
+export type TemporalBucketResultColumnExpectation = {
+    key: string;
+    metadata: TemporalBucketMetadata;
+};
+export type TemporalBucketResultColumnsValidationResult = {
+    ok: true;
+    value: SemaphorResultColumn[];
+} | {
+    ok: false;
+    error: TemporalBucketContractError;
+};
+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;
+/**
+ * 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;

package/dist/types/shared/analytics-protocol/temporal-context.d.ts

@@ -0,0 +1,35 @@
+import { ResolvedDateWindow } from './metric-comparison.js';
+import { SemaphorFieldRef, SemaphorSourceRef } from './contracts.js';
+export type SourceBearingTemporalField = SemaphorFieldRef & {
+    source: SemaphorSourceRef;
+};
+export type TemporalBindingCandidate = {
+    kind: 'visible_axis' | 'explicit_hidden' | 'semantic_primary';
+    field: SourceBearingTemporalField;
+};
+export type TemporalRangeCandidate = {
+    id: string;
+    source: 'global_date' | 'card';
+    field: SourceBearingTemporalField;
+    window: ResolvedDateWindow;
+};
+export type ResolvedTemporalContext = {
+    status: 'resolved';
+    field: SourceBearingTemporalField;
+    bindingSource: TemporalBindingCandidate['kind'];
+    currentWindow?: ResolvedDateWindow;
+    governingWindowSource?: TemporalRangeCandidate['source'];
+    governingRangeId?: string;
+    constraints: TemporalRangeCandidate[];
+} | {
+    status: 'unavailable';
+    reason: 'temporal_binding_missing' | 'temporal_binding_ambiguous' | 'temporal_binding_invalid' | 'unsupported_raw_sql';
+    constraints: TemporalRangeCandidate[];
+};
+export type ResolveTemporalContextInput = {
+    rawSql?: boolean;
+    candidates: TemporalBindingCandidate[];
+    ranges?: TemporalRangeCandidate[];
+    querySources?: SemaphorSourceRef[];
+};
+export declare function resolveTemporalContext(input: ResolveTemporalContextInput): ResolvedTemporalContext;

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

@@ -0,0 +1,21 @@
+import { SemaphorAnalyticsIntent, SemaphorAnalyticsRecoveryPlan, SemaphorAnalyticsValidationResult, SemaphorDashboardIntent, SemaphorOperationIntent, SemaphorResultCalculation, SemaphorValidationResult } from './contracts.js';
+export { validateSemaphorDerivedFieldDefinition } from './field-validation.js';
+export declare function parseSemaphorIsoTimeWindowBoundary(value: unknown): Date | null;
+export declare function parseSemaphorIsoInstant(value: unknown): Date | null;
+export type SemaphorOptionDependencyValidationProfile = 'protocol' | 'dashboard';
+/**
+ * Validates an option dependency policy object. The `protocol` profile is the
+ * SDK contract: omitted mode stays independent and include/exclude lists are
+ * only checked for shape. The `dashboard` profile adds the authored-policy
+ * rules from the dashboard filter option dependencies plan: a mode is
+ * required, independent carries no ID lists, explicit needs at least one
+ * unique included ID and no exclusions, and all_applicable carries no include
+ * list. Dependency ID declarations against `inputs` are validated by the
+ * intent validator, not here.
+ */
+export declare function validateSemaphorOptionDependencies(value: unknown, profile?: SemaphorOptionDependencyValidationProfile): SemaphorValidationResult;
+export declare function validateSemaphorResultCalculation(calculation: SemaphorResultCalculation): SemaphorValidationResult;
+export declare function validateSemaphorAnalyticsIntent(intent: SemaphorAnalyticsIntent): SemaphorAnalyticsValidationResult;
+export declare function validateSemaphorOperationIntent(intent: SemaphorOperationIntent): SemaphorAnalyticsValidationResult;
+export declare function validateSemaphorAnalyticsRecoveryPlan(plan: SemaphorAnalyticsRecoveryPlan): SemaphorAnalyticsValidationResult;
+export declare function validateSemaphorDashboardIntent(intent: SemaphorDashboardIntent): SemaphorValidationResult;

package/dist/types/shared/dashboard-authoring/artifact-compiler.d.ts

@@ -0,0 +1,6 @@
+import { DashboardCompileResult, DashboardPlan, GeneratedDashboardCardArtifact } from './contracts.js';
+export declare function compileDashboardFromPlan(input: {
+    dashboardId: string;
+    plan: DashboardPlan;
+    cardArtifacts: GeneratedDashboardCardArtifact[];
+}): DashboardCompileResult;

package/dist/types/shared/dashboard-authoring/calculated-field-identity.d.ts

@@ -0,0 +1,22 @@
+type CalculatedFieldIdentity = {
+    name: string;
+    role?: string;
+    entityName?: string;
+    qualifiedEntityName?: string;
+};
+export declare function getCalculatedFieldNamespace(field: Pick<CalculatedFieldIdentity, 'entityName' | 'qualifiedEntityName'>): string;
+/** Metadata fetch IDs are ephemeral; domain identity is namespace, role and name. */
+export declare function getStableDomainCalculatedFieldId(field: CalculatedFieldIdentity): string;
+/** Read a saved reference, never treating its current shelf role as authored
+ * identity. Catalog construction continues to use the pure canonical builder. */
+export declare function readExactDomainCalculatedFieldReference(field: CalculatedFieldIdentity & {
+    fieldScope?: string;
+    calculatedFieldOrigin?: {
+        id?: string;
+        role?: string;
+    };
+    derivedField?: {
+        resultRole?: string;
+    };
+}): string | undefined;
+export {};

package/dist/types/shared/dashboard-authoring/calculated-field-placement.d.ts

@@ -0,0 +1,16 @@
+import { Field, MetricField } from '../../lib/types/explorer-types.js';
+export type CalculatedFieldUsage = 'selection' | 'input' | 'predicate';
+/** Aggregation belongs to the use of a definition, not to its authored role. */
+export declare function getCalculatedFieldAggregateOverrides(saved: Field, current: Field, usage: CalculatedFieldUsage): Pick<Field, 'aggregate' | 'aggregateOrigin'>;
+/** Parameter ownership differs by definition scope, never by object spread
+ * order. Domain predicates are authoritative including removal; local metric
+ * attribute filters remain visual-owned. Window transforms are visual-owned. */
+export declare function getCalculatedFieldParameters(saved: MetricField, current: MetricField, ownership: 'domain' | 'local'): MetricField['parameters'];
+/** Exhaustive projection of the saved selection onto a current governed
+ * definition. Anything not returned here comes from the catalog, including
+ * expression, dependencies, stage, identity and definition-owned predicates. */
+export declare function getDomainCalculatedSelectionOverrides(saved: Field, current: Field, usage: CalculatedFieldUsage): Partial<Field>;
+/** Shelf-only authored settings survive definition edits and governed refresh.
+ * Definition properties and metric aggregation/format policy stay with their
+ * respective merge owners; copying an entire saved field would restore stale SQL. */
+export declare function getCalculatedFieldShelfOverrides(field: Field): Partial<Field>;

package/dist/types/shared/dashboard-authoring/canonical-result-keys.d.ts

@@ -0,0 +1,25 @@
+export type CanonicalDetailResultFieldIdentity = {
+    name: string;
+    label?: string;
+    alias?: string;
+    entityName?: string;
+    role?: string;
+    aggregate?: string;
+    expression?: string;
+};
+export type CanonicalResultFieldRole = 'groupby' | 'metric' | 'pivotby' | 'detail';
+/** Role-aware physical key policy used by the canonical query key map. */
+export declare function resolveCanonicalResultRawKey(field: CanonicalDetailResultFieldIdentity, role: CanonicalResultFieldRole, emittedAliasOverride?: string): string;
+/** 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;

package/dist/types/shared/dashboard-authoring/card-reference-remapping.d.ts

@@ -0,0 +1,6 @@
+import { DashboardCardReferenceRemapping, TCard } from '../../lib/types/common-types.js';
+export type { DashboardCardReferenceRemapping } from '../../lib/types/common-types.js';
+/** Compose instance copies without losing the original library-to-instance keys. */
+export declare function composeCardReferenceRemapping(previous: DashboardCardReferenceRemapping | undefined, next: DashboardCardReferenceRemapping): DashboardCardReferenceRemapping;
+/** Apply instance reference overrides to a fresh library card, preserving authored SQL. */
+export declare function applyCardReferenceRemapping(source: TCard, mapping: DashboardCardReferenceRemapping): TCard;

package/dist/types/shared/dashboard-authoring/change-compiler.d.ts

@@ -0,0 +1,7 @@
+import { DashboardChangeCompileResult, DashboardChangePlan, GeneratedDashboardCardArtifact } from './contracts.js';
+import { TDashboard } from '../../lib/types/index.js';
+export declare function applyDashboardChangePlan(input: {
+    dashboard: TDashboard;
+    changePlan: DashboardChangePlan;
+    cardArtifacts: GeneratedDashboardCardArtifact[];
+}): DashboardChangeCompileResult;

package/dist/types/shared/dashboard-authoring/comparison-document-migration.d.ts

@@ -0,0 +1,36 @@
+import { ComparisonPresentationSpec, MetricComparisonConfig, MetricComparisonPolarity } from '../analytics-protocol/index.js';
+export type ComparisonMigrationDiagnostic = {
+    severity: 'warning' | 'error';
+    code: 'invalid_target_value' | 'unsupported_start_vs_end' | 'unsupported_comparison_type' | 'stray_target_value' | 'malformed_metric_columns' | 'conflicting_comparison_contracts' | 'conflicting_comparison_window_transform' | 'conflicting_comparison_presentation_contracts' | 'conflicting_legacy_presentation_namespaces' | 'conflicting_legacy_polarity' | 'invalid_legacy_comparison_presentation' | 'unsupported_comparison_format';
+    path: string;
+    message: string;
+};
+export type ComparisonDocumentChange = {
+    kind: 'metric';
+    path: string;
+    metricId?: string;
+    legacyType: string;
+    comparison?: MetricComparisonConfig;
+    comparisonPolarity?: MetricComparisonPolarity;
+    removedFields: string[];
+} | {
+    kind: 'presentation';
+    path: string;
+    comparisonPresentation?: ComparisonPresentationSpec;
+    metricPairComparisonEnabled?: boolean;
+    comparisonPolarityMetricIds?: string[];
+    intentionallyDiscardedFields?: string[];
+    removedFields: string[];
+};
+export type ComparisonDocumentTransformResult<T> = {
+    document: T;
+    changed: boolean;
+    changes: ComparisonDocumentChange[];
+    diagnostics: ComparisonMigrationDiagnostic[];
+};
+/**
+ * Pure, atomic migration for persisted dashboard-shaped JSON documents.
+ * Documents with neither an active legacy metric comparison nor legacy
+ * comparison presentation are returned by identity.
+ */
+export declare function transformComparisonDocument<T>(document: T): ComparisonDocumentTransformResult<T>;

package/dist/types/shared/dashboard-authoring/contracts.d.ts

@@ -0,0 +1,153 @@
+import { DashboardInput, DashboardInputScope, DashboardInputValues, TCard, TDashboard, TFilter } from '../../lib/types/index.js';
+import { TChartType } from '../../lib/charts/types.js';
+import { Field } from '../../lib/types/explorer-types.js';
+import { PersistedFrameLayouts } from '../layouts/create-frame-layouts.js';
+import { SemaphorAnalyticsIntent, SemaphorSourceRef } from '../analytics-protocol/index.js';
+export declare const DASHBOARD_AUTHORING_BREAKPOINTS: readonly ["lg", "md", "sm", "xs", "xxs"];
+export declare const DASHBOARD_AUTHORING_MAX_GENERATED_CARDS = 15;
+export type DashboardAuthoringBreakpoint = (typeof DASHBOARD_AUTHORING_BREAKPOINTS)[number];
+export type DashboardCardSizeIntent = 'kpi' | 'chart' | 'table' | 'text';
+export type DashboardPlanCard = {
+    id: string;
+    frameId: string;
+    title: string;
+    description?: string;
+    type: Exclude<TChartType, 'custom'>;
+    role: DashboardCardSizeIntent;
+    priority: number;
+    section?: string;
+    analyticsIntent?: SemaphorAnalyticsIntent;
+    text?: string;
+};
+export type DashboardPlanSheet = {
+    id: string;
+    title: string;
+    description?: string;
+    kind: 'dashboard';
+    cards: DashboardPlanCard[];
+};
+export type DashboardPlanFilterInput = {
+    id: string;
+    label: string;
+    variableName: string;
+    scope?: DashboardInputScope;
+    filter: TFilter;
+    defaultValue?: unknown;
+};
+export type DashboardPlanCalculatedField = {
+    id: string;
+    name: string;
+    scope: 'card' | 'sheet' | 'dashboard' | 'domain';
+    expression?: string;
+    field?: Field;
+    targetCardId?: string;
+    reuseOnly?: boolean;
+};
+export type DashboardPlanWarning = {
+    code: string;
+    message: string;
+    cardId?: string;
+};
+export type DashboardPlan = {
+    version: 1;
+    id: string;
+    title: string;
+    description?: string;
+    datasets: SemaphorSourceRef[];
+    sheets: DashboardPlanSheet[];
+    filterInputs?: DashboardPlanFilterInput[];
+    calculatedFields?: DashboardPlanCalculatedField[];
+    warnings?: DashboardPlanWarning[];
+    unresolvedRequests?: string[];
+    deferredSuggestions?: string[];
+};
+export type DashboardSuggestionPreviewKind = 'kpi' | 'line' | 'bar' | 'donut' | 'table';
+export type DashboardSuggestion = {
+    id: string;
+    title: string;
+    description: string;
+    preview: DashboardSuggestionPreviewKind[];
+    cardCount: number;
+    filterCount: number;
+    prompt: string;
+    datasets?: Array<{
+        name: string;
+        label?: string;
+    }>;
+    relationshipHints?: string[];
+};
+export type GeneratedDashboardCardArtifact = {
+    planCardId: string;
+    frameId: string;
+    card: TCard;
+    queryValidated?: boolean;
+    warnings?: DashboardPlanWarning[];
+};
+export type DashboardAuthoringIdFactory = {
+    dashboardId?: () => string;
+    sheetId?: () => string;
+    frameId: (seed?: string) => string;
+    cardId: (seed?: string) => string;
+};
+export type DashboardCompileResult = {
+    dashboard: TDashboard;
+    warnings: DashboardPlanWarning[];
+    skippedOperations: DashboardPlanWarning[];
+};
+export type DashboardAuthoringValidationResult = {
+    ok: boolean;
+    errors: DashboardPlanWarning[];
+    warnings: DashboardPlanWarning[];
+};
+export type DashboardChangeOperation = {
+    kind: 'addCard';
+    card: DashboardPlanCard;
+} | {
+    kind: 'addFilterInput';
+    input: DashboardPlanFilterInput;
+} | {
+    kind: 'addCalculatedField';
+    field: DashboardPlanCalculatedField;
+} | {
+    kind: 'reuseCalculatedField';
+    fieldId: string;
+    scope: 'sheet' | 'dashboard' | 'domain';
+} | {
+    kind: 'renameCard';
+    cardId: string;
+    title: string;
+    description?: string;
+} | {
+    kind: 'reorderCards';
+    cardIds: string[];
+} | {
+    kind: 'unsupported';
+    requestedAction: string;
+    reason: string;
+};
+export type DashboardChangePlan = {
+    version: 1;
+    id: string;
+    dashboardId: string;
+    title?: string;
+    description?: string;
+    datasets: SemaphorSourceRef[];
+    operations: DashboardChangeOperation[];
+    warnings?: DashboardPlanWarning[];
+    unresolvedRequests?: string[];
+};
+export type DashboardChangeCompileResult = {
+    dashboard: TDashboard;
+    warnings: DashboardPlanWarning[];
+    skippedOperations: DashboardPlanWarning[];
+};
+export type CompiledDashboardInputDefaults = {
+    inputs: DashboardInput[];
+    defaultInputValues?: DashboardInputValues;
+};
+export type DashboardLayoutCompileInput = {
+    frameId: string;
+    role: DashboardCardSizeIntent;
+    priority: number;
+};
+export type DashboardLayoutCompileResult = PersistedFrameLayouts;