react-semaphor 0.1.504 → 0.1.506

package/dist/types/lib/filter-values/build-filter-values-request-payload.d.ts

@@ -0,0 +1,116 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+import { ControlBinding, ControlDefinition } from '../types/common-types.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { DashboardFilterOptionSource, DashboardOptionContext } from '../../shared/dashboard-authoring/index.js';
+import { SemaphorFieldRef, SemaphorInputBinding, SemaphorSourceRef, NativePredicateSemanticsCandidate } from '../../shared/analytics-protocol/index.js';
+type FilterValuesSearchPayload = {
+    query: string;
+    mode: string;
+};
+type FilterValuesControlPayload = {
+    controlValues: Record<string, unknown>;
+    controlDefinitions: ControlDefinition[];
+    cardControlDefinitions: ControlDefinition[];
+    controlBindings: ControlBinding[];
+};
+type BuildFilterValuesRequestPayloadParams = {
+    filter: TFilter;
+    activeFilters?: TFilterValue[];
+    cacheConfig?: unknown;
+    search?: FilterValuesSearchPayload;
+    /** Defaults to the label field for author-entered search. */
+    optionSearchField?: 'label' | 'value';
+    /** Exact raw values used only to resolve presentation labels. */
+    optionValueLookup?: readonly unknown[];
+    dashboardControlValues?: Record<string, unknown>;
+    dashboardControlDefinitions?: ControlDefinition[];
+    optionSource?: DashboardFilterOptionSource;
+    /**
+     * Explicit dependency policy and peer bindings from Dashboard Inputs.
+     * Standard requests carry it as `optionContext`; governed requests express
+     * it through intent dependencies. Absent for SQL and custom renderers.
+     */
+    optionContext?: DashboardOptionContext;
+    calendarContext: CalendarContext;
+    /**
+     * Exact-value relevance check for retained selections. Sent under the
+     * authored dependency context with no search or paging; see
+     * `SemaphorInputOptionsIntent.matchValues`.
+     */
+    matchValues?: readonly unknown[];
+};
+/**
+ * One active peer on the governed dashboard transport. The shared snapshot
+ * fields describe identity for grounding; `predicate` carries the native
+ * operation and values so null checks and temporal predicates survive, and
+ * so a peer without resolvable source identity still reaches the server for
+ * classification instead of being dropped client-side.
+ */
+type DashboardOptionActiveInput = SemaphorInputBinding & {
+    value: unknown;
+    isActive: true;
+    /** Allowlisted native semantics, unvalidated: the server alone decides
+     * whether they execute, so nothing is dropped on the client. */
+    predicate?: NativePredicateSemanticsCandidate;
+    /** Bounded capability declaration. It can only narrow what the server
+     * will execute: a calculated peer is skipped or rejected, never grounded
+     * as a column. Column-only option sources cannot execute calculated peers. */
+    candidateKind?: 'column' | 'calculated';
+};
+type FilterValuesResponse = {
+    records: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+};
+export declare function normalizeDashboardInputOptionsResponse(response: unknown, optionSource: DashboardFilterOptionSource): FilterValuesResponse;
+export declare function buildFilterValuesControlPayload(params: {
+    filter: TFilter;
+    activeFilters?: TFilterValue[];
+    dashboardControlValues?: Record<string, unknown>;
+    dashboardControlDefinitions?: ControlDefinition[];
+}): FilterValuesControlPayload | undefined;
+export declare function buildFilterValuesRequestPayload(params: BuildFilterValuesRequestPayloadParams): {
+    activeInputs?: DashboardOptionActiveInput[] | undefined;
+    requestKind: "dashboardInputOptions";
+    intent: {
+        dependencies?: import('../../shared/analytics-protocol/index.js').SemaphorOptionDependencies | undefined;
+        inputs?: SemaphorInputBinding[] | undefined;
+        limit: number;
+        matchValues?: unknown[] | undefined;
+        searchField?: SemaphorFieldRef;
+        search?: string | undefined;
+        population?: import('../../shared/analytics-protocol/index.js').SemaphorOptionPopulation | undefined;
+        source: Extract<SemaphorSourceRef, {
+            kind: "semantic" | "physical";
+        }>;
+        labelField: SemaphorFieldRef;
+        valueField: SemaphorFieldRef;
+        disambiguationFields?: SemaphorFieldRef[];
+        kind: "inputOptions";
+        inputId: string;
+    };
+} | {
+    controlValues?: Record<string, unknown> | undefined;
+    controlDefinitions?: ControlDefinition[] | undefined;
+    cardControlDefinitions?: ControlDefinition[] | undefined;
+    controlBindings?: ControlBinding[] | undefined;
+    cache_config: unknown;
+    calendarContext: CalendarContext;
+    optionContext?: DashboardOptionContext | undefined;
+    active_filters: TFilterValue[] | undefined;
+    match_values?: unknown[] | undefined;
+    search?: FilterValuesSearchPayload | undefined;
+    filter: {
+        sql: string;
+        fieldMeta: import('../../components/surfboard/filter/types.js').FilterFieldMeta | undefined;
+        semanticContext: import('../../components/surfboard/filter/types.js').FilterSemanticContext | undefined;
+        nativeDataType?: string | undefined;
+        id: string;
+        connectionId: string;
+        column: string;
+        table: string | undefined;
+        database: string | undefined;
+        qualifiedTableName: string | undefined;
+        dataType: string;
+    };
+};
+export {};

package/dist/types/lib/filter-values/filter-option-dependency-feedback.d.ts

@@ -0,0 +1,43 @@
+import { SemaphorOptionDependencies, SemaphorOptionDependencyOutcome, SemaphorOptionDependencyOutcomeReason } from '../../shared/analytics-protocol/index.js';
+import { DashboardInputTargetExclusion } from '../dashboard-inputs/dashboard-input-target-context.js';
+/**
+ * Viewer-facing reading of the server's dependency outcomes for one option
+ * list. Pure: outcomes and the request error come from the response, labels
+ * come from the dashboard. Nothing here decides applicability; the server
+ * already did. It only says what was applied, what was skipped and why, what
+ * the viewer is browsing around, and whether a classified failure may be
+ * browsed around at all.
+ */
+export type FilterOptionDependencyPeer = {
+    inputId: string;
+    label: string;
+};
+export type FilterOptionDependencyFailure = {
+    peer: FilterOptionDependencyPeer;
+    reason?: SemaphorOptionDependencyOutcomeReason;
+    /** Viewer-safe explanation built from the reason, never raw server text. */
+    message: string;
+    /** Explicit mode and an overridable, classified reason. */
+    canOverride: boolean;
+};
+export type FilterOptionDependencyFeedback = {
+    applied: FilterOptionDependencyPeer[];
+    skipped: Array<FilterOptionDependencyPeer & {
+        reason?: SemaphorOptionDependencyOutcomeReason;
+    }>;
+    overridden: Array<FilterOptionDependencyPeer & {
+        reason?: SemaphorOptionDependencyOutcomeReason;
+    }>;
+    failure?: FilterOptionDependencyFailure;
+};
+/** Author-facing reason an Input in scope could not take part in narrowing. */
+export declare function describeOptionDependencyExclusion(exclusion: Pick<DashboardInputTargetExclusion, 'reason'>): string;
+export declare function describeOptionDependencyReason(reason: SemaphorOptionDependencyOutcomeReason | undefined): string;
+/** Outcomes a failed request carried, at the top level or under details. */
+export declare function readFailureDependencyOutcomes(error: unknown): SemaphorOptionDependencyOutcome[];
+export declare function buildFilterOptionDependencyFeedback({ outcomes, error, labels, dependencies, }: {
+    outcomes: readonly SemaphorOptionDependencyOutcome[] | undefined;
+    error: unknown;
+    labels: ReadonlyMap<string, string>;
+    dependencies: SemaphorOptionDependencies | undefined;
+}): FilterOptionDependencyFeedback;

package/dist/types/lib/filter-values/filter-option-identity.d.ts

@@ -0,0 +1,10 @@
+import { FilterOptionValue } from '../../components/surfboard/filter/types.js';
+/**
+ * Stable identity for raw filter-option values.
+ *
+ * Values that render alike can still have different predicate semantics, so
+ * identity retains the runtime scalar type. Numeric `1` and string `"1"` are
+ * therefore different options throughout hydration, selection, and rendering.
+ */
+export declare function getFilterOptionValueIdentity(value: FilterOptionValue): string;
+export declare function filterOptionValuesEqual(left: FilterOptionValue, right: FilterOptionValue): boolean;

package/dist/types/lib/filter-values/filter-option-selection-relevance.d.ts

@@ -0,0 +1,27 @@
+import { SemaphorOptionMatchValue } from '../../shared/analytics-protocol/index.js';
+/**
+ * Per-value relevance of a retained selection under the authored dependency
+ * context. Only a successful, complete exact-value check may say
+ * `no_match`; everything else (pending, failed, unsupported, truncated,
+ * beyond the bounded batch) stays `unknown`, so a stale or partial answer can
+ * never mark a current selection wrong.
+ */
+export type OptionSelectionRelevanceStatus = 'matches' | 'no_match' | 'unknown';
+export type OptionSelectionRelevance = {
+    byIdentity: ReadonlyMap<string, OptionSelectionRelevanceStatus>;
+    noMatchIdentities: ReadonlySet<string>;
+    isPending: boolean;
+};
+export declare const EMPTY_OPTION_SELECTION_RELEVANCE: OptionSelectionRelevance;
+/** The bounded batch a relevance request submits: scalar values only, up to
+ * the contract bound. Null and non-scalar selections are never submitted and
+ * therefore stay unknown, as does the remainder beyond the bound. */
+export declare function boundedRelevanceValues(values: readonly unknown[]): SemaphorOptionMatchValue[];
+export declare function deriveOptionSelectionRelevance({ values, checked, matchedIdentities, complete, status, }: {
+    values: readonly unknown[];
+    /** The values actually submitted (bounded). */
+    checked: readonly unknown[];
+    matchedIdentities: ReadonlySet<string>;
+    complete: boolean;
+    status: 'idle' | 'pending' | 'error' | 'success';
+}): OptionSelectionRelevance;

package/dist/types/lib/filter-values/filter-record-value.d.ts

@@ -0,0 +1,9 @@
+import { TFilter, TSelectedRecord } from '../../components/surfboard/filter/types.js';
+/**
+ * Resolve the option value from a filter-values record.
+ *
+ * Shared by the viewer option hooks and authoring default-value pickers so
+ * both read records with identical column-name fallbacks (quoted, lower-case,
+ * semantic field, title, generic `value` / `label`).
+ */
+export declare function getFilterRecordValue(record: Record<string, unknown>, filter: TFilter, preferredFieldName?: string): TSelectedRecord['value'] | undefined;

package/dist/types/lib/filter-values/merge-additional-filter-values.d.ts

@@ -0,0 +1,12 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+/**
+ * Fold surface-supplied sibling values (editor draft inline values) into the
+ * context's values. A supplied value replaces the context's value for the
+ * same filter so a draft edit wins over the last saved state; the target's
+ * own value never arrives through this channel.
+ */
+export declare function mergeAdditionalFilterValues(params: {
+    base: readonly TFilterValue[];
+    additional: readonly TFilterValue[] | undefined;
+    excludeFilterId: string;
+}): TFilterValue[];

package/dist/types/lib/formatters/active-numeric-presentation.d.ts

@@ -0,0 +1,25 @@
+import { CurrencyPresentationTarget, TCard } from '../types/common-types.js';
+import { PersistedColumnSettings } from '../../components/visual/data-table/types/data-table.js';
+import { DetailField, MetricField } from '../types/explorer-types.js';
+import { CanonicalFormatSpec } from '../../shared/format-utils/types/index.js';
+export type ActiveKpiNumericPresentation = {
+    target?: CurrencyPresentationTarget;
+    authoredFormat?: CanonicalFormatSpec;
+    currencyBindable: boolean;
+};
+export type ActiveFieldNumericPresentation = {
+    authoredFormat?: CanonicalFormatSpec;
+    currencyBindable: boolean;
+};
+export type ActiveChartMetricNumericPresentation = ActiveFieldNumericPresentation & {
+    source?: 'semantic' | 'number_axis' | 'legacy' | 'inferred';
+};
+export declare function isCurrencyBindableCanonicalFormat(format: CanonicalFormatSpec | undefined): boolean;
+export declare function hasExplicitSqlNumericIntent(settings: PersistedColumnSettings | undefined): boolean;
+export declare function isSqlColumnCurrencyBindable(settings: PersistedColumnSettings | undefined): boolean;
+export declare function resolveActiveFieldNumericPresentation(field: Pick<MetricField | DetailField, 'dataType' | 'format'>, settings: PersistedColumnSettings | undefined): ActiveFieldNumericPresentation;
+export declare function resolveActiveChartMetricNumericPresentation(card: TCard, metric: Pick<MetricField, 'dataType' | 'format'>): ActiveChartMetricNumericPresentation;
+export declare function resolveActiveKpiNumericPresentation(card: TCard, options?: {
+    metricIndex?: number;
+    resultColumnKey?: string;
+}): ActiveKpiNumericPresentation;

package/dist/types/lib/formatters/canonical-format-adapter.d.ts

@@ -0,0 +1,34 @@
+import { NumberAxisFormat, TFormatOptions } from '../types/common-types.js';
+import { FormatSpec } from '../types/explorer-types.js';
+import { ColumnSettings } from '../../components/visual/data-table/types/data-table.js';
+import { AdaptedCanonicalFormatSpec, CanonicalAdapterOptions } from '../../shared/format-utils/semantic-format.js';
+export type { CanonicalFormatSpec } from '../../shared/format-utils/types/index.js';
+export type LegacyFormatNumber = {
+    decimalPlaces?: number;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    currency?: string;
+    locale?: string;
+    prefix?: string;
+    suffix?: string;
+    useGrouping?: boolean;
+    percentValueMode?: 'fraction' | 'whole';
+    enabled?: boolean | string;
+};
+export declare function fromTFormatOptions(format?: TFormatOptions | null, options?: CanonicalAdapterOptions): AdaptedCanonicalFormatSpec | undefined;
+export declare function fromPersistedKpiFormatOptions(format?: TFormatOptions): AdaptedCanonicalFormatSpec | undefined;
+export declare function fromLegacyFormatNumber(format?: LegacyFormatNumber | null): AdaptedCanonicalFormatSpec | undefined;
+export declare function fromNumberAxisFormat(format?: NumberAxisFormat | null): AdaptedCanonicalFormatSpec | undefined;
+export declare function fromColumnNumberFormat(format?: Partial<ColumnSettings['numberFormat']> | null, options?: CanonicalAdapterOptions): AdaptedCanonicalFormatSpec | undefined;
+export declare function isHistoricalPersistedColumnNumberFormat(format?: Partial<ColumnSettings['numberFormat']> | null): boolean;
+/**
+ * Reads the persisted table-column contract. The old settings editor seeded
+ * currency, locale, and data-bar leaves together; that bounded legacy shape
+ * rendered omitted precision with the table formatter's 0-2 fallback. Newly
+ * sparse formats do not match it and retain currency-minor-unit precision.
+ */
+export declare function fromPersistedColumnNumberFormat(format?: Partial<ColumnSettings['numberFormat']> | null): AdaptedCanonicalFormatSpec | undefined;
+export declare function toSemanticFormat(format?: AdaptedCanonicalFormatSpec | null): FormatSpec | undefined;
+export declare function toTFormatOptions(format?: AdaptedCanonicalFormatSpec | null, options?: CanonicalAdapterOptions): TFormatOptions | undefined;
+export declare function toColumnNumberFormat(format?: AdaptedCanonicalFormatSpec | null, options?: CanonicalAdapterOptions): ColumnSettings['numberFormat'] | undefined;
+export declare function toLegacyFormatNumber(format?: AdaptedCanonicalFormatSpec | null): LegacyFormatNumber | undefined;

package/dist/types/lib/formatters/card-format-context.d.ts

@@ -0,0 +1,14 @@
+import { TCard } from '../types/common-types.js';
+import { CanonicalFormatSpec } from './canonical-format-adapter.js';
+import { ResolvedValueFormatPreferences } from '../../shared/value-format-preferences/index.js';
+export type CardFormatContext = {
+    currency?: string;
+    locale: string;
+    canonicalPrimaryFormat?: CanonicalFormatSpec;
+    isFormattingDisabled: boolean;
+};
+export declare function resolveCardFormatContext({ card, preferences, boundCurrency, }: {
+    card?: TCard;
+    preferences?: ResolvedValueFormatPreferences | null;
+    boundCurrency?: string;
+}): CardFormatContext;

package/dist/types/lib/formatters/cartesian-temporal-presentation.d.ts

@@ -0,0 +1,75 @@
+import { TCard } from '../types/common-types.js';
+import { CardConfig, QueryColumnKeyMap } from '../types/explorer-types.js';
+import { SemaphorPivotValue, SemaphorPivotResultColumnIdentity, SemaphorResultColumn } from '../../shared/analytics-protocol/index.js';
+import { PresentationExecutionSnapshot } from '../../shared/format-utils/index.js';
+import { GroupedTemporalPresentation, GroupedTemporalViewerPreferences } from './grouped-temporal-presentation.js';
+export type CartesianTemporalPresentation = GroupedTemporalPresentation & {
+    /** Exact output key for the first grouped field. */
+    axisColumnKey?: string;
+    /** Exact output key for the second grouped field when it becomes a series. */
+    seriesColumnKey?: string;
+    /** Physical wide-pivot columns keyed by their exact result accessor. */
+    pivotSeriesByColumnKey: ReadonlyMap<string, SemaphorPivotResultColumnIdentity>;
+};
+export type CartesianTemporalSeriesValue = string | number | null;
+export type CartesianTemporalDatasetIdentity = {
+    /** Canonical category values aligned with the rendered dataset's points. */
+    semaphorCanonicalAxisValues?: readonly unknown[];
+    /** Canonical grouped-series value behind a presentation-only legend label. */
+    semaphorCanonicalSeriesKey?: unknown;
+    /** Exact physical result accessor used to build this dataset. */
+    semaphorResultColumnKey?: string;
+    /** Stable metric owner for a physical wide-pivot result column. */
+    semaphorMetricId?: string;
+    /** Collision-safe configured metric instance behind the result column. */
+    semaphorMetricAlias?: string;
+    /** Canonical values ordered by the configured pivot fields. */
+    semaphorPivotValues?: readonly SemaphorPivotValue[];
+};
+/**
+ * Decorates one dataset while its exact physical result key is still known.
+ * Labels may be prettified later; analytical identity never depends on them.
+ */
+export declare function attachCartesianPivotResultIdentity<T extends object>(input: {
+    dataset: T;
+    resultColumnKey: string;
+    presentation?: CartesianTemporalPresentation;
+}): T & CartesianTemporalDatasetIdentity;
+/**
+ * Resolves Cartesian grouped presentation once from authoritative field/output
+ * identity. Chart builders receive this result and never reinterpret saved
+ * formats, result values, or Calendar policy.
+ */
+export declare function resolveCartesianTemporalPresentation(input: {
+    card: TCard;
+    cardConfig?: CardConfig;
+    columns?: readonly SemaphorResultColumn[];
+    columnKeyMap?: QueryColumnKeyMap;
+    executionSnapshot?: PresentationExecutionSnapshot | null;
+    dashboardId?: string;
+    attachmentIndex?: number;
+    valueFormatPreferences?: GroupedTemporalViewerPreferences | null;
+}): CartesianTemporalPresentation;
+export declare function orderCartesianChartKeys(keys: readonly string[], presentation?: CartesianTemporalPresentation, explicitAxisColumnKey?: string): string[];
+export declare function formatCartesianTemporalValue(input: {
+    value: unknown;
+    columnKey: string;
+    presentation?: CartesianTemporalPresentation;
+}): string | undefined;
+/**
+ * Carries canonical category/series identity through chart reshaping and
+ * sorting. Click consumers read this metadata instead of indexing the raw
+ * pre-pivot records or reversing a formatted label.
+ */
+export declare function attachCartesianTemporalDatasetIdentity<T extends {
+    label?: unknown;
+}>(input: {
+    datasets: readonly T[];
+    records?: readonly Record<string, unknown>[];
+    axisColumnKey?: string;
+    seriesColumnKey?: string;
+    seriesKeys?: readonly string[];
+    seriesValueByKey?: ReadonlyMap<string, CartesianTemporalSeriesValue>;
+    presentation?: CartesianTemporalPresentation;
+}): Array<T & CartesianTemporalDatasetIdentity>;
+export declare function readCartesianCanonicalAxisValue(dataset: CartesianTemporalDatasetIdentity | undefined, index: number): unknown;

package/dist/types/lib/formatters/chart-numeric-presentation.d.ts

@@ -0,0 +1,25 @@
+import { CurrencyPresentationTarget, TCard, TFormatOptions } from '../types/common-types.js';
+import { MetricField } from '../types/explorer-types.js';
+import { ResolvedTemporalValueFormatPreferences, ResolvedValueFormatPreferences } from '../../shared/value-format-preferences/index.js';
+export type ChartNumericPresentationContext = {
+    preferences: ResolvedValueFormatPreferences | null;
+    temporalPreferences?: ResolvedTemporalValueFormatPreferences | null;
+    resolveBoundCurrency: (target: CurrencyPresentationTarget) => string | undefined;
+};
+export declare function getSqlChartPresentationMetricKeys(params: {
+    card: TCard;
+    records: readonly Record<string, unknown>[];
+    resultKeys: readonly string[];
+    renderedMetricKeys?: readonly string[];
+}): string[];
+export declare function projectChartNumericPresentation(params: {
+    card: TCard;
+    resultMetricKeys: readonly string[];
+    context?: ChartNumericPresentationContext;
+}): TCard;
+export declare function resolveChartSlotNumericPresentation(params: {
+    card: TCard | undefined;
+    metrics: Array<Pick<MetricField, 'id' | 'format'> | null | undefined>;
+    formatOptions: TFormatOptions | undefined;
+    context?: ChartNumericPresentationContext;
+}): TFormatOptions | undefined;

package/dist/types/lib/formatters/currency-presentation-binding.d.ts

@@ -0,0 +1,72 @@
+import { ControlBinding, ControlDefinition, CurrencyPresentationTarget, SqlQueryControlSource, TCard, TDashboard } from '../types/common-types.js';
+import { MatrixConfig } from '../../shared/analytics-protocol/index.js';
+import { MatrixCardCatalog } from '../matrix-table/matrix-card-adapter.js';
+import { DetailField, MetricField } from '../types/explorer-types.js';
+export type CurrencyBindingDiagnosticCode = 'invalid_binding_shape' | 'missing_control' | 'invalid_control_type' | 'invalid_currency_option' | 'invalid_control_default' | 'missing_target' | 'stale_target' | 'inapplicable_target';
+export type CurrencyBindingDiagnostic = {
+    code: CurrencyBindingDiagnosticCode;
+    controlId?: string;
+};
+export declare function getCardCurrencyPresentationFields(card: TCard): Array<MetricField | DetailField>;
+export declare function getDashboardPresentationCurrencyControlIds(dashboard: Pick<TDashboard, 'sheets'>): Set<string>;
+export declare function getCardCurrencyPresentationTargets(card: TCard, resultColumnKeys?: readonly string[], matrixCatalog?: MatrixCardCatalog): {
+    knownTargets: CurrencyPresentationTarget[];
+    eligibleTargets: CurrencyPresentationTarget[];
+};
+export declare function getPrimaryKpiCurrencyPresentationTarget(card: TCard, resultColumnKey?: string): CurrencyPresentationTarget | undefined;
+export declare function getTableCurrencyPresentationTarget(params: {
+    card: TCard;
+    columnKey: string;
+    metricId?: string;
+}): CurrencyPresentationTarget | undefined;
+export declare function currencyPresentationTargetKey(target: CurrencyPresentationTarget): string;
+export declare function isPresentationCurrencyBinding(binding: ControlBinding): binding is Extract<ControlBinding, {
+    target: 'presentation_currency';
+}>;
+export declare function isStructuralControlBinding(binding: ControlBinding): binding is Exclude<ControlBinding, {
+    target: 'sql_param' | 'presentation_currency';
+}>;
+type ValidCurrencyPresentationControl = ControlDefinition & {
+    source: Extract<ControlDefinition['source'], {
+        kind: 'manual';
+    }>;
+};
+export declare function isCurrencyPresentationControl(control: ControlDefinition): control is ValidCurrencyPresentationControl;
+type QueryRelevantDashboardControlContextParams = {
+    dashboard: Pick<TDashboard, 'sheets'>;
+    definitions?: ControlDefinition[];
+    values?: Record<string, unknown>;
+};
+type QueryRelevantDashboardControlContext = {
+    definitions: ControlDefinition[];
+    values: Record<string, unknown>;
+};
+export declare function getFilterQueryRelevantDashboardControlContext(params: QueryRelevantDashboardControlContextParams & {
+    filterSql?: string;
+}): QueryRelevantDashboardControlContext;
+export declare function getControlSourceQueryRelevantDashboardControlContext(params: QueryRelevantDashboardControlContextParams & {
+    source?: Pick<SqlQueryControlSource, 'sql'>;
+}): QueryRelevantDashboardControlContext;
+export declare function diagnoseCurrencyPresentationBindings(params: {
+    bindings?: ControlBinding[];
+    controls?: ControlDefinition[];
+    knownTargets: CurrencyPresentationTarget[];
+    eligibleTargets: CurrencyPresentationTarget[];
+}): CurrencyBindingDiagnostic[];
+export declare function resolveBoundPresentationCurrency(params: {
+    bindings?: ControlBinding[];
+    controls?: ControlDefinition[];
+    values?: Record<string, unknown>;
+    target: CurrencyPresentationTarget;
+    knownTargets: CurrencyPresentationTarget[];
+    eligibleTargets: CurrencyPresentationTarget[];
+}): {
+    currency?: string;
+    diagnostics: CurrencyBindingDiagnostic[];
+};
+/** Materialize presentation-only choices before query projection removes them. */
+export declare function resolveMatrixCurrencyPresentation(card: TCard, config: MatrixConfig, context: {
+    controls: ControlDefinition[];
+    values: Record<string, unknown>;
+}, catalog: MatrixCardCatalog): MatrixConfig['presentation'];
+export {};

package/dist/types/lib/formatters/dashboard-temporal-presentation.d.ts

@@ -0,0 +1,10 @@
+import { resolveDashboardTemporalActivation } from './grouped-temporal-activation.js';
+import { resolveGroupedTemporalPresentation } from './grouped-temporal-presentation.js';
+import { TemporalResultOwner } from '../../shared/dashboard-authoring/index.js';
+export declare function resolveDashboardTemporalPresentation(input: Omit<Parameters<typeof resolveGroupedTemporalPresentation>[0], 'activation'>): import('./grouped-temporal-presentation.js').GroupedTemporalPresentation;
+export declare function isDashboardTemporalResultCompatible(input: {
+    card: Parameters<typeof resolveDashboardTemporalActivation>[0]['card'];
+    cardConfig?: Parameters<typeof resolveDashboardTemporalActivation>[0]['cardConfig'];
+    result: unknown;
+    expectedResultOwner?: TemporalResultOwner;
+}): boolean;

package/dist/types/lib/formatters/dashboard-temporal-snapshot.d.ts

@@ -0,0 +1,28 @@
+import { TCard, TDashboard } from '../types/common-types.js';
+import { CardConfig } from '../types/explorer-types.js';
+import { ResolvedPresentationEntry } from '../../shared/format-utils/index.js';
+import { ResolvedValueFormatPreferences } from '../../shared/value-format-preferences/index.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+export type DashboardTemporalSnapshotSelection = {
+    dashboardId: string;
+    sheetId?: string;
+    cardId?: string;
+    attachmentIndex?: number;
+};
+export declare class TemporalSnapshotSelectionError extends Error {
+    readonly code = "temporal_snapshot_target_not_found";
+    readonly selection: DashboardTemporalSnapshotSelection;
+    constructor(selection: DashboardTemporalSnapshotSelection);
+}
+/**
+ * Captures resolved temporal presentation at a one-time export click or a
+ * recurring-rule save. Targets use stable field IDs; result-column keys are
+ * resolved later from the executing query's authoritative column map.
+ */
+export declare function buildDashboardTemporalSnapshotEntries(input: {
+    dashboard: TDashboard;
+    selections: readonly DashboardTemporalSnapshotSelection[];
+    resolveCardConfig?: (card: TCard) => CardConfig;
+    valueFormatPreferences: ResolvedValueFormatPreferences;
+    calendar: Pick<CalendarContext, 'tz'>;
+}): ResolvedPresentationEntry[];

package/dist/types/lib/formatters/grouped-temporal-activation.d.ts

@@ -0,0 +1,36 @@
+import { TCard } from '../types/common-types.js';
+import { CardConfig, GroupByField, PivotByField } from '../types/explorer-types.js';
+import { ShelfCard } from '../utils/card-definition.js';
+export type GroupedTemporalActivation = {
+    cardType: string;
+    cardConfig: CardConfig;
+    fields: Array<GroupByField | PivotByField>;
+};
+export declare class AmbiguousGroupedTemporalGrainError extends Error {
+    readonly code = "ambiguous_temporal_grain";
+    readonly fieldId: string;
+    constructor(fieldId: string);
+}
+/**
+ * Normalizes the single inventoried legacy exception shared by activated
+ * dashboard families. DATE plus saved presentation and no grain is an
+ * unambiguous day bucket; DATETIME/timestamp remains ambiguous.
+ */
+export declare function normalizeGroupedTemporalField<T extends GroupByField | PivotByField>(field: T): T | undefined;
+export declare function resolveShelfTemporalActivation(input: {
+    card: ShelfCard;
+    cardConfig?: CardConfig;
+    supportsCardType: (cardType: string | undefined) => boolean;
+}): GroupedTemporalActivation | undefined;
+export declare function resolveRegularTableTemporalActivation(input: {
+    card: TCard;
+    cardConfig?: CardConfig;
+}): GroupedTemporalActivation | undefined;
+export declare function resolveCartesianTemporalActivation(input: {
+    card: TCard;
+    cardConfig?: CardConfig;
+}): GroupedTemporalActivation | undefined;
+export declare function resolveDashboardTemporalActivation(input: {
+    card: TCard;
+    cardConfig?: CardConfig;
+}): GroupedTemporalActivation | undefined;

package/dist/types/lib/formatters/grouped-temporal-authoring.d.ts

@@ -0,0 +1,33 @@
+import { SemaphorTimeGrain } from '../../shared/analytics-protocol/index.js';
+import { getTemporalBucketAuthoringSelection } from '../../shared/dashboard-authoring/temporal-bucket-authoring.js';
+import { readSavedTemporalBucketFormat, SavedTemporalFormatInput } from './saved-temporal-bucket-format.js';
+type SemanticTemporalAuthoringPresentation = {
+    granularity?: unknown;
+    format?: unknown;
+};
+export type TemporalBucketAuthoringInput = SavedTemporalFormatInput & {
+    semanticTemporalPresentation?: SemanticTemporalAuthoringPresentation;
+};
+export { AUTOMATIC_TEMPORAL_BUCKET_FORMAT, getTemporalBucketAuthoringOptions, reconcileTemporalBucketAuthoringFormat, resolveTemporalBucketAuthoringFormat, } from '../../shared/dashboard-authoring/temporal-bucket-authoring.js';
+export type { TemporalBucketAuthoringOption, TemporalBucketAuthoringSelection, } from '../../shared/dashboard-authoring/temporal-bucket-authoring.js';
+export type TemporalBucketAuthoringReadState = {
+    ok: true;
+    granularity: SemaphorTimeGrain;
+    selection: ReturnType<typeof getTemporalBucketAuthoringSelection>;
+} | Extract<ReturnType<typeof readSavedTemporalBucketFormat>, {
+    ok: false;
+}>;
+export declare function readTemporalBucketAuthoringState(input: TemporalBucketAuthoringInput): TemporalBucketAuthoringReadState;
+/**
+ * Authoring-only bridge for existing saved dashboard bytes. The shared
+ * registry accepts only structured formats; this is the sole place where
+ * authoring UI reaches the bounded legacy reader.
+ */
+export declare function readTemporalBucketAuthoringSelection(input: TemporalBucketAuthoringInput): import('../../shared/dashboard-authoring/temporal-bucket-authoring.js').TemporalBucketAuthoringSelection;
+type TemporalBucketAuthoringOverride = Pick<SavedTemporalFormatInput, 'format' | 'dateFormat' | 'customFormat'>;
+/**
+ * Applies a saved authoring override atomically. If any override presentation
+ * field is present, the override owns all three fields; otherwise the base
+ * field remains authoritative.
+ */
+export declare function readTemporalBucketAuthoringSelectionWithOverride(input: TemporalBucketAuthoringInput, override?: TemporalBucketAuthoringOverride): import('../../shared/dashboard-authoring/temporal-bucket-authoring.js').TemporalBucketAuthoringSelection;