react-semaphor 0.1.503 → 0.1.505

package/dist/types/lib/utils/field-availability-context.d.ts

@@ -0,0 +1,25 @@
+import { TCard } from '../types/common-types.js';
+import { AutoJoinMetadata } from '../types/query-types.js';
+import { JoinabilityMapResponse } from '../types/semantic-types.js';
+import { FieldStateContext } from './field-state-calculator.js';
+/**
+ * Everything `calculateFieldState` needs about a visual, except the
+ * selected fields (which differ per call). Built by ONE function so the
+ * field list, the click gate, the drop gate, and the matrix editor judge
+ * the same card from the same facts: the same join plan (the authored
+ * one, which is also right for matrix cards), the same auto-resolved
+ * base, the same relationship map, aliases, labels, mode, and data-source
+ * anchor. A caller that assembles these by hand will eventually disagree
+ * with the others; do not.
+ */
+export type FieldAvailabilityContext = Omit<FieldStateContext, 'selectedFields'> & {
+    /** The semantic domain the card reads, when any. */
+    semanticDomainId?: string;
+};
+export declare function buildFieldAvailabilityContext(input: {
+    card: Pick<TCard, 'type' | 'config' | 'dataSource'> | null | undefined;
+    joinabilityData?: JoinabilityMapResponse | null;
+    autoJoinMetadata?: AutoJoinMetadata;
+    /** Labels the caller knows from elsewhere (entity groups); catalog labels win. */
+    extraDatasetLabels?: Record<string, string>;
+}): FieldAvailabilityContext;

package/dist/types/lib/utils/field-dependencies.d.ts

@@ -0,0 +1,87 @@
+import { Field, FilterGroup, GroupByField, MetricField } from '../types/explorer-types.js';
+/**
+ * Field dependency resolution (shared by server planning and client UX)
+ * =====================================================================
+ *
+ * One question, answered in one place for every field representation:
+ *
+ *   "Which datasets does this field read from?"
+ *
+ * Consumers:
+ *   - semaphor-app query planning (join resolution, filter applicability,
+ *     fan-out analysis) via the `collect*` functions, which keep the
+ *     original server API and semantics.
+ *   - react-semaphor field availability ("usable in this chart") via
+ *     `resolveFieldDatasetDependencies`, which returns full dependency
+ *     objects with qualified identity.
+ *
+ * Representations handled, in order, by ONE walker:
+ *   1. A field owned by a real dataset is a leaf on that dataset, even when
+ *      it carries an expression (inline domain expressions, query-local
+ *      aliases). Synthetic owners (the calculated-field markers, the
+ *      `calculated_fields` group, or no owner) are never leaves.
+ *   2. `calculatedFormula.inputFields`: full Field objects, walked
+ *      recursively.
+ *   3. `derivedField.inputs[*].field.source`: the shared analytics contract,
+ *      used only when there are no formula inputs (both encode the same
+ *      inputs). Semantic sources resolve to the dataset name; physical
+ *      sources keep database/schema/table so `public.orders` and
+ *      `archive.orders` stay distinct. This is the only representation
+ *      Matrix-authored calculations may carry.
+ *   4. Metric filter conditions (`parameters.filters`), when requested.
+ *
+ * Adding a representation means adding it here, once.
+ */
+type ExplorerField = Field | GroupByField | MetricField;
+export type FieldDatasetDependency = {
+    /**
+     * Dataset name as the catalog knows it (entityName / datasetName / table).
+     * Empty string when the source carried only a qualified name.
+     */
+    entityName: string;
+    entityId?: string;
+    /** Qualified identity when known (`schema.table`, `db.schema.table`, or the field's qualifiedEntityName). */
+    qualifiedEntityName?: string;
+    /** Human label when the source carried one. */
+    label?: string;
+};
+export type FieldDependencyResolution = {
+    /** Unique datasets, in first-seen order. */
+    datasets: FieldDatasetDependency[];
+    /**
+     * False when at least one input could not be traced to a dataset (for
+     * example a metric-to-metric reference that was not expanded into input
+     * fields). Callers must not claim the field is available in that case.
+     */
+    complete: boolean;
+};
+export type DatasetCollectionOptions = {
+    /** Include datasets referenced by metric filter conditions. Default true. */
+    includeMetricFilterDatasets?: boolean;
+    /** Emit `qualifiedEntityName` when it is dotted, otherwise `entityName`. Default false. */
+    preferQualifiedIdentity?: boolean;
+};
+/**
+ * The dataset a shared analytics `source` ref names. Semantic sources are
+ * the dataset name; physical sources keep database/schema/table so distinct
+ * tables stay distinct. The single mapping for both the walker and the
+ * calculator's identity resolver.
+ */
+export declare function datasetRefFromSource(source: Field['source'] | undefined): FieldDatasetDependency | undefined;
+/** Best available identity for a dependency: name, else qualified name. */
+export declare function dependencyDisplayIdentity(dep: FieldDatasetDependency): string;
+/**
+ * Resolve the datasets a field reads from, with qualified identity.
+ * Base fields resolve to their own dataset; calculated fields resolve
+ * through their inputs. Metric filter datasets are not included: they do
+ * not affect whether the field itself can be added.
+ */
+export declare function resolveFieldDatasetDependencies(field: Field): FieldDependencyResolution;
+export declare function collectDatasetNamesFromExplorerField(field: ExplorerField | null | undefined, datasets: Set<string>, visitedFields?: Set<string>, visitedGroups?: Set<string>, options?: DatasetCollectionOptions): void;
+export declare function collectPreferredDatasetNamesFromExplorerField(field: ExplorerField | null | undefined, datasets: Set<string>): void;
+export declare function collectQualifiedDatasetNamesFromExplorerField(field: ExplorerField | null | undefined, datasets: Set<string>, visitedFields?: Set<string>, visitedGroups?: Set<string>): void;
+export declare function collectExecutionDatasetNamesFromExplorerField(field: ExplorerField | null | undefined, datasets: Set<string>, visitedFields?: Set<string>, visitedGroups?: Set<string>): void;
+export declare function collectDatasetNamesFromFilterGroup(filters: FilterGroup | null | undefined, datasets: Set<string>, visitedFields?: Set<string>, visitedGroups?: Set<string>, options?: DatasetCollectionOptions): void;
+/** Humanize a catalog dataset name for customer-facing copy. */
+export declare function humanizeDatasetName(name: string, labels?: Record<string, string>): string;
+export {};

package/dist/types/lib/utils/field-icon-utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Field Icon Utilities
+ *
+ * Centralized utility for displaying field icons with consistent styling.
+ * Used across the application for field visualization (fields list,
+ * trigger selector, drag overlays, etc.). Delegates to the canonical
+ * monochrome `TypeGlyph` primitive so a single change here propagates
+ * everywhere a field icon is rendered.
+ */
+export declare function getFieldIconComponent(dataType: string | undefined): import("react/jsx-runtime").JSX.Element;

package/dist/types/lib/utils/field-state-calculator.d.ts

@@ -0,0 +1,159 @@
+import { Field, JoinPlan } from '../types/explorer-types.js';
+import { JoinabilityMap } from '../types/semantic-types.js';
+import { AutoJoinMetadata } from '../types/query-types.js';
+import { resolveFieldDatasetDependencies, FieldDatasetDependency } from './field-dependencies.js';
+import { getQualifiedEntityName } from './qualified-entity-name.js';
+export interface DatasetIdentityAlias {
+    name: string;
+    table?: string | null;
+    catalog?: string | null;
+    schema?: string | null;
+}
+/**
+ * Field draggability states for the query builder
+ *
+ * - **base**: Field is from the base dataset (first dataset selected)
+ * - **draggable**: Field has a direct relationship to base dataset (1-hop)
+ * - **indirect**: Field requires a multi-hop join (2-hop via intermediate dataset)
+ * - **setup**: A relationship exists but the engine will not use it on its
+ *   own (not set to auto-join). The user can fix this; until then the field
+ *   is blocked exactly like `unreachable`.
+ * - **unreachable**: No relationship path exists to this field's dataset
+ *
+ * Calculated fields take the worst state among the datasets they read from.
+ */
+export type FieldDraggableState = 'base' | 'draggable' | 'indirect' | 'setup' | 'unreachable'
+/**
+ * Nothing is on the shelves and the dataset is not one of the chart's
+ * data-source datasets. Not a fault to fix: the customer chose their
+ * datasets and this field reads another one. Blocked, with the path to
+ * using it (add the dataset) offered as information.
+ */
+ | 'absent';
+/** Per-dataset availability, attached to calculated-field results. */
+export interface FieldDependencyState {
+    /** Catalog dataset name. */
+    entityName: string;
+    /** Customer-facing dataset label. */
+    label: string;
+    state: FieldDraggableState;
+    /** Customer-facing sentence when the dataset is not simply available. */
+    reason?: string;
+}
+/**
+ * Result of field state calculation
+ */
+export interface FieldStateResult {
+    /** The calculated draggability state */
+    state: FieldDraggableState;
+    /** For indirect joins: the path through intermediate datasets */
+    joinPath?: string[];
+    /** Short tooltip text explaining the state (row `title`). */
+    tooltip?: string;
+    /**
+     * Customer-facing explanation when the field cannot be added as-is.
+     * Precise: names the dataset and the actual problem.
+     */
+    reason?: string;
+    /** The one thing the user can do about `reason`, when there is one. */
+    action?: string;
+    /**
+     * Dataset labels that `reason` mentions, so the UI can set them off from
+     * the surrounding sentence (a chip) without parsing the text.
+     */
+    mentions?: string[];
+    /**
+     * Non-blocking caution from governed catalog metadata, for example a
+     * one-to-many join that can repeat an aggregate. Shown in the preview.
+     */
+    warning?: string;
+    /**
+     * Datasets a calculated field reads from, each with its own state.
+     * Undefined for base fields (their dataset is their group).
+     */
+    dependencies?: FieldDependencyState[];
+    /**
+     * False when availability could not be checked (relationship map still
+     * loading, or a dependency could not be traced). UI must not present
+     * such a field as verified-ready.
+     */
+    verified?: boolean;
+    /** Indicates if this field is already selected/in the query */
+    isSelected?: boolean;
+}
+/** States that block adding the field to the query. */
+export declare function isBlockedFieldState(state: FieldDraggableState | undefined): boolean;
+export interface FieldStateContext {
+    joinabilityMap: JoinabilityMap | null;
+    selectedFields: Field[];
+    joinPlan?: JoinPlan;
+    autoJoinMetadata?: AutoJoinMetadata;
+    baseEntityName?: string;
+    datasetAliases?: DatasetIdentityAlias[];
+    /**
+     * Whether the card reads from a semantic domain. Drives the fallback when
+     * `joinabilityMap` is null:
+     *   - true  -> the map is still loading: report `verified: false`.
+     *   - false -> physical datasets: reachability comes from the join plan.
+     *   - undefined (legacy callers) -> everything draggable, as before.
+     */
+    hasSemanticDomain?: boolean;
+    /** Customer-facing dataset labels keyed by dataset name. */
+    datasetLabels?: Record<string, string>;
+    /**
+     * The datasets the chart's data source lists (`DataSource.selectedEntities`),
+     * in order. When nothing is on the shelves yet, these ARE the chart's
+     * datasets: a calculated field's dependencies are judged against them,
+     * so the card talks about the dataset the customer actually picked
+     * instead of the calculation's own first input.
+     */
+    dataSourceEntities?: DatasetAnchorRef[];
+}
+/** Minimal entity reference the calculator needs to identify a dataset. */
+export type DatasetAnchorRef = Parameters<typeof getQualifiedEntityName>[0];
+/**
+ * Customer-facing words for a state, in one place. The row tag under a
+ * dependency and the title of the refusal toast both read from here.
+ */
+export declare function getFieldStateCopy(state: FieldDraggableState | undefined): {
+    /** Short tag beside a blocking dependency; null when nothing blocks. */
+    tag: string | null;
+    /** Title of the refusal toast. */
+    toastTitle: string;
+};
+/**
+ * Calculate the draggability state for a field in the query builder
+ *
+ * This determines whether a field can be dragged based on:
+ * - Current selected fields (what's already in the query)
+ * - Joinability map (what relationships exist between datasets)
+ * - For calculated fields: the datasets their inputs read from
+ *
+ * **Fallback behavior**:
+ * - No joinability map and no `hasSemanticDomain` flag: all fields draggable
+ *   (legacy callers, no restrictions)
+ * - No fields selected yet: base fields are draggable (first selection
+ *   establishes the base dataset); calculated fields are judged against the
+ *   data source's datasets when there are any, else against their own first
+ *   dataset
+ */
+export declare function calculateFieldState(field: Field, context: FieldStateContext): FieldStateResult;
+/** One data-source dataset's connection to the visual's base, for the Datasets panel. */
+export interface DataSourceConnection {
+    /** Dataset identity (name in semantic mode, qualified table in physical). */
+    entityName: string;
+    label: string;
+    state: FieldDraggableState;
+    reason?: string;
+    action?: string;
+    mentions?: string[];
+}
+/**
+ * How each selected dataset connects to the visual's base dataset, using
+ * the same identity, base cascade, and per-dataset evaluation as the field
+ * list. The Datasets panel shows this at selection time so the customer
+ * learns about an unconnected dataset before the first drag. Order and
+ * verdicts match `calculateFieldState` for a field of that dataset.
+ */
+export declare function describeDataSourceConnections(context: FieldStateContext): DataSourceConnection[];
+export { resolveFieldDatasetDependencies, type FieldDatasetDependency };

package/dist/types/lib/utils/filter-default-value-utils.d.ts

@@ -0,0 +1,24 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+import { TInlineFilter } from '../types/common-types.js';
+type DefaultBackedFilter = Pick<TFilter, 'id' | 'column' | 'operation' | 'dataType' | 'nativeDataType' | 'dateSelectionMode' | 'defaultValues' | 'defaultDateFilter' | 'fieldMeta' | 'semanticContext'> & Partial<Pick<TInlineFilter, 'id' | 'column' | 'operation' | 'dataType' | 'nativeDataType' | 'dateSelectionMode' | 'defaultValues' | 'defaultDateFilter' | 'fieldMeta' | 'semanticContext'>>;
+/**
+ * Converts a filter's default configuration into an active runtime filter value.
+ * Returns undefined when no defaults are configured.
+ */
+export declare function buildFilterValueFromDefaults(filter: DefaultBackedFilter, timezone?: string): TFilterValue | undefined;
+export declare function buildFilterValuesFromDefaults(filters: DefaultBackedFilter[] | undefined, timezone?: string): TFilterValue[];
+export declare function isCompatibleFilterValue(filter: Pick<TFilter, 'id' | 'operation' | 'dataType'>, filterValue: TFilterValue): boolean;
+export declare function filterCompatibleFilterValues(filters: TFilter[] | undefined, filterValues: TFilterValue[] | undefined): TFilterValue[];
+export declare function mergeFilterValueLayers(baseValues: TFilterValue[], overrideValues: TFilterValue[]): TFilterValue[];
+export declare function preserveSameDashboardFilterValues(params: {
+    previousFilters: TFilter[] | undefined;
+    nextFilters: TFilter[] | undefined;
+    filterValues: TFilterValue[] | undefined;
+}): TFilterValue[];
+export declare function resolveSameDashboardFilterValues(params: {
+    previousFilters: TFilter[] | undefined;
+    nextFilters: TFilter[] | undefined;
+    currentFilterValues: TFilterValue[] | undefined;
+    defaultFilterValues: TFilterValue[];
+}): TFilterValue[];
+export {};

package/dist/types/lib/utils/filter-formatter.d.ts

@@ -0,0 +1,19 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+type FormatFilterLineOptions = {
+    timezone?: string;
+};
+/**
+ * Converts an array of filter values into a human-readable filter line
+ * @param filterValues Array of TFilterValue objects
+ * @returns Human-readable filter description string
+ */
+export declare function formatFilterLine(filterValues: TFilterValue[], options?: FormatFilterLineOptions): string;
+/**
+ * Formats a date range filter into a readable string
+ * @param startDate Start date
+ * @param endDate End date
+ * @param fieldName Name of the date field
+ * @returns Formatted date range string
+ */
+export declare function formatDateRange(startDate: Date | string, endDate: Date | string, fieldName?: string): string;
+export {};

package/dist/types/lib/utils/filter-metadata-utils.d.ts

@@ -0,0 +1,28 @@
+import { DataSource, Field, FilterGroup } from '../types/explorer-types.js';
+import { FilterFieldMeta, FilterSemanticContext, TFilter } from '../../components/surfboard/filter/types.js';
+import { TInlineFilter } from '../types/common-types.js';
+import { NativeDataTypeDefinition } from '../../shared/filter-native-data-type.js';
+export { materializeFilterDefinitionNativeDataType, materializeFilterValueNativeDataType, materializeFilterValuesNativeDataType, resolveFilterFieldNativeDataType, } from '../../shared/filter-native-data-type.js';
+/**
+ * Builds the metadata update for moving a filter definition to another field.
+ * Target columns do not carry exact catalog metadata, so the previous field's
+ * native type must be cleared until the server proves the new field's type.
+ */
+export declare function buildFilterFieldRetarget(definition: NativeDataTypeDefinition, fieldName: string): Pick<TFilter, 'column' | 'nativeDataType'> & {
+    fieldMeta?: FilterFieldMeta;
+};
+export declare function buildFilterFieldMeta(field: Field): FilterFieldMeta;
+export declare function buildFilterSemanticContext(dataSource?: DataSource | null, fallback?: {
+    connectionId?: string;
+    connectionType?: string;
+}, field?: Field): FilterSemanticContext | undefined;
+export declare function getFilterSourceDatabase(dataSource: DataSource | null | undefined, context: FilterSemanticContext | undefined, field: Field): string | undefined;
+type StoredFilterFieldDefinition = {
+    column: string;
+    fieldMeta?: FilterFieldMeta;
+};
+export declare function doesStoredFilterMatchField(storedFilter: StoredFilterFieldDefinition, field: Field): boolean;
+export declare function rewriteStoredFilterForPromotedField<TStoredFilter extends StoredFilterFieldDefinition>(storedFilter: TStoredFilter, promotedField: Field, editingField?: Field): TStoredFilter;
+export declare function rewriteStoredFiltersForPromotedField(filters: TFilter[] | undefined, promotedField: Field, editingField?: Field): TFilter[] | undefined;
+export declare function rewriteInlineFiltersForPromotedField(filters: TInlineFilter[] | undefined, promotedField: Field, editingField?: Field): TInlineFilter[] | undefined;
+export declare function rewriteFilterGroupForPromotedField(group: FilterGroup | null | undefined, promotedField: Field, editingField?: Field): FilterGroup | null | undefined;

package/dist/types/lib/utils/filter-name-utils.d.ts

@@ -0,0 +1,27 @@
+import { Field } from '../types/explorer-types.js';
+export type QualifiedFilterNamesResult = {
+    qualifiedColumnName: string;
+    qualifiedTableName: string;
+    formattedColumnName: string;
+};
+/**
+ * Builds qualified column and table names for filter assignment.
+ * Uses Field's qualifiedFieldName and qualifiedEntityName directly.
+ *
+ * @param field - Field object with qualifiedFieldName, qualifiedEntityName, and name
+ *
+ * @example
+ * buildQualifiedFilterNames(field)
+ * // field = { name: 'event_type', qualifiedFieldName: 'semaphor.telemetry.token_events.event_type', ... }
+ * // => {
+ * //   qualifiedColumnName: 'semaphor.telemetry.token_events.event_type',
+ * //   qualifiedTableName: 'semaphor.telemetry.token_events',
+ * //   formattedColumnName: '"event_type"'
+ * // }
+ *
+ * @example
+ * // Mixed-case identifiers are quoted for PostgreSQL compatibility
+ * // field = { qualifiedEntityName: 'SalesDB.Public.Events', ... }
+ * // => { qualifiedTableName: '"SalesDB"."Public"."Events"' }
+ */
+export declare function buildQualifiedFilterNames(field: Field): QualifiedFilterNamesResult;

package/dist/types/lib/utils/filter-scoping-utils.d.ts

@@ -0,0 +1,64 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+/**
+ * Normalize column name for comparison by stripping quotes.
+ * This ensures backward compatibility if any old filters stored quoted column names.
+ *
+ * @param name - Column name that may contain quotes
+ * @returns Column name with quotes stripped
+ */
+export declare function normalizeColumnName(name: string): string;
+/**
+ * Normalize qualified table name for comparison by stripping quotes.
+ * This keeps legacy filters with quoted table names compatible with new ones.
+ *
+ * @param name - Qualified table name that may contain quotes
+ * @returns Qualified table name with quotes stripped
+ */
+export declare function normalizeQualifiedTableName(name: string): string;
+/**
+ * Apply sheet-level scoping to filters.
+ * Returns filters that apply to the given sheet based on the new scoping system.
+ *
+ * Scoping logic:
+ * 1. Backward compatibility: Checks legacy `sheetId` property first
+ * 2. Checks new `applyToSheetIds` (only specific sheets)
+ * 3. Checks new `excludeSheetIds` (all except specific sheets)
+ * 4. Default: Applies to all sheets if no scope properties are set
+ *
+ * @param filters - Array of filters to scope
+ * @param selectedSheetId - ID of the sheet to scope to
+ * @returns Array of filters that apply to the given sheet
+ */
+export declare function getSheetScopedFilters(filters: TFilter[] | undefined, selectedSheetId: string | null | undefined): TFilter[];
+type GetSheetScopedFilterValuesOptions = {
+    includeCardScoped?: boolean;
+};
+export declare function isSheetScopedAdHocFilter(filterId: string, selectedSheetId: string | null | undefined): boolean;
+export declare function getSheetScopedFilterValues(filters: TFilter[] | undefined, filterValues: TFilterValue[] | undefined, selectedSheetId: string | null | undefined, options?: GetSheetScopedFilterValuesOptions): TFilterValue[];
+/**
+ * Checks if a filter with the given qualified column name exists within a specific sheet's scope.
+ * Used for duplicate detection when creating sheet-local filters.
+ *
+ * This enables the feature where the same column can have multiple filters
+ * across different sheets, while preventing duplicates within the same sheet.
+ *
+ * @param filters - All dashboard filters
+ * @param qualifiedColumnName - Fully qualified column name (e.g., "database.schema.table.column")
+ * @param qualifiedTableName - Fully qualified table name for defensive check (e.g., "database.schema.table")
+ * @param sheetId - Target sheet ID to check within
+ * @returns The conflicting filter, or undefined if no conflict
+ *
+ * @example
+ * // Check if filter for "semaphor.telemetry.token_events.event_type" exists on sheet-1
+ * const conflict = filterExistsInSheet(
+ *   filters,
+ *   "semaphor.telemetry.token_events.event_type",
+ *   "semaphor.telemetry.token_events",
+ *   "sheet-1"
+ * );
+ * if (conflict) {
+ *   console.log("Filter already exists on this sheet");
+ * }
+ */
+export declare function filterExistsInSheet(filters: TFilter[], qualifiedColumnName: string, qualifiedTableName: string, sheetId: string): TFilter | undefined;
+export {};

package/dist/types/lib/utils/filter-search-sql.d.ts

@@ -0,0 +1,17 @@
+import { Dialect } from '../types/explorer-types.js';
+/**
+ * Generates a case-insensitive text search condition for a column
+ * @param column - The column name to search
+ * @param searchTerm - The search term (already SQL-escaped)
+ * @param dialect - The database dialect
+ * @returns SQL condition string for text search
+ */
+export declare function buildTextSearchCondition(column: string, searchTerm: string, dialect?: Dialect): string;
+/**
+ * Parses a numeric operator query and generates SQL condition
+ * @param column - The column name
+ * @param query - The user query (e.g., ">100", "<=50", "=100")
+ * @param dialect - The database dialect (optional, affects casting)
+ * @returns SQL condition string or null if invalid
+ */
+export declare function buildNumericCondition(column: string, query: string, dialect?: Dialect): string | null;

package/dist/types/lib/utils/format-config-extractor.d.ts

@@ -0,0 +1,21 @@
+import { ColorRange, DisplayDataType, NumberAxisFormat, TCard, TColumnSetting, TFormatOptions } from '../types/common-types.js';
+import { TablePreferences } from '../../components/visual/data-table/types/data-table.js';
+import { CustomVisualFormatConfig, LegacyFormatNumber } from '../../components/visual/custom-visual/custom-visual-types.js';
+export type FormatConfig = {
+    kpi?: {
+        primary?: TFormatOptions;
+        colorRanges?: ColorRange[];
+    };
+    dataLabels?: TFormatOptions;
+    yAxis?: TFormatOptions;
+    xAxis?: TFormatOptions;
+    secondaryYAxis?: TFormatOptions;
+    tableColumnSettingsMap?: TablePreferences['columnSettingsMap'];
+    tableColumnSettings?: TColumnSetting<DisplayDataType>[];
+    legacy?: {
+        formatNumber?: LegacyFormatNumber;
+        numberAxisFormat?: NumberAxisFormat;
+    };
+};
+export declare function extractFormatConfig(card: TCard): FormatConfig;
+export declare function buildCustomVisualFormatConfig(card: TCard): CustomVisualFormatConfig;

package/dist/types/lib/utils/frame-utils.d.ts

@@ -0,0 +1,27 @@
+import { TFrame } from '../types/common-types.js';
+/**
+ * Creates a clone of a frame with new unique IDs for the frame and all cards.
+ * This prevents ID collisions when duplicating frames or adding library visuals.
+ *
+ * Preserves the activeCardId reference by tracking the ID mapping from old to new.
+ * If the old activeCardId is not found, defaults to the first card.
+ *
+ * @param sourceFrame - The frame to clone with new IDs
+ * @returns A new frame clone with fresh IDs for frame and all cards
+ *
+ * @example
+ * ```typescript
+ * const libraryFrame = { id: 'frame-1', cards: [{ id: 'card-1' }], activeCardId: 'card-1' };
+ * const clonedFrame = cloneFrameWithNewIds(libraryFrame);
+ * // clonedFrame.id !== 'frame-1'
+ * // clonedFrame.cards[0].id !== 'card-1'
+ * // activeCardId updated to new card ID
+ * ```
+ */
+export declare function cloneFrameWithNewIds(sourceFrame: TFrame): TFrame;
+/**
+ * Creates a linked frame instance from a library frame.
+ * Card IDs are generated once and each instance card keeps a stable mapping
+ * to its library source card ID.
+ */
+export declare function cloneLinkedFrameWithSourceMapping(sourceFrame: TFrame): TFrame;

package/dist/types/lib/utils/inline-expression-utils.d.ts

@@ -0,0 +1,11 @@
+import { Field } from '../types/explorer-types.js';
+export type InlineExpressionAnalysis = {
+    kind: 'inline';
+    entityName: string;
+    entityId: string;
+    qualifiedEntityName?: string;
+} | {
+    kind: 'multi-entity';
+};
+export declare function analyzeInlineExpressionInputs(inputFields: Field[]): InlineExpressionAnalysis;
+export declare function collectLocalCalculatedDependencies(inputFields: Field[]): Field[];

package/dist/types/lib/utils/inline-filter-utils.d.ts

@@ -0,0 +1,15 @@
+import { TDashboard } from '../types/common-types.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+/**
+ * Hydrate inline filter defaults for all cards in the dashboard.
+ * Returns a map of cardId → TFilterValue[] for runtime-only storage.
+ * Values are derived from card.inlineFilters[].defaultValues/defaultDateFilter.
+ *
+ * Dashboard and inline filters share one default-value materializer; this
+ * function only owns traversal and card-scoped runtime storage.
+ *
+ * @param dashboard - The dashboard to extract inline filter defaults from
+ * @param timezone - Optional timezone for date calculations (defaults to browser timezone)
+ * @returns Map of cardId to array of filter values
+ */
+export declare function computeInlineFilterDefaults(dashboard: TDashboard, timezone?: string): Record<string, TFilterValue[]>;

package/dist/types/lib/utils/interaction-display-utils.d.ts

@@ -0,0 +1,30 @@
+import { Interaction, DrillHierarchy } from '../types/interaction-types.js';
+import { TCard } from '../types/index.js';
+import { getInteractionIcon } from './interaction-icons.js';
+export interface InteractionDisplayInfo {
+    /**
+     * Primary label to display (from interaction.label or default)
+     */
+    label: string;
+    /**
+     * Icon component for this interaction mode
+     */
+    icon: ReturnType<typeof getInteractionIcon>;
+    /**
+     * Secondary information about the target/scope
+     * e.g., "Apply to 3 cards", "Navigate to Dashboard X"
+     */
+    targetInfo: string;
+    /**
+     * Original interaction configuration
+     */
+    interaction: Interaction;
+}
+/**
+ * Get display information for an interaction
+ */
+export declare function getInteractionDisplayInfo(interaction: Interaction, hierarchies?: DrillHierarchy[], currentDrillDepth?: number, card?: TCard, breadcrumbs?: any[]): InteractionDisplayInfo;
+/**
+ * Get all display info for multiple interactions
+ */
+export declare function getAllInteractionDisplayInfo(interactions: Interaction[], hierarchies?: DrillHierarchy[], currentDrillDepth?: number, card?: TCard, breadcrumbs?: any[]): InteractionDisplayInfo[];

package/dist/types/lib/utils/interaction-icons.d.ts

@@ -0,0 +1,10 @@
+import { LucideIcon } from 'lucide-react';
+export type InteractionMode = 'clickFilter' | 'drillToDetail' | 'drillThrough' | 'drillToURL' | 'drillDown' | 'drillUp' | 'dynamicDrill' | 'inlineDrill';
+/**
+ * Get icon component for interaction mode
+ */
+export declare function getInteractionIcon(mode: InteractionMode): LucideIcon;
+/**
+ * Get default label for interaction mode
+ */
+export declare function getDefaultInteractionLabel(mode: InteractionMode): string;

package/dist/types/lib/utils/is-safari-browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Safari UA detection helper.
+ * Excludes Chromium-based and Firefox-based browsers that also include "Safari" in UA.
+ */
+export declare function isSafariUserAgent(userAgent: string): boolean;
+export declare function isSafariBrowser(): boolean;

package/dist/types/lib/utils/join-plan-entity-matching.d.ts

@@ -0,0 +1,26 @@
+import { DatabaseEntityReference, JoinPlan } from '../types/explorer-types.js';
+type JoinEntityLike = DatabaseEntityReference & {
+    id?: string;
+    domainId?: string;
+    alias?: string | null;
+    table?: string | null;
+    catalog?: string | null;
+    databaseName?: string | null;
+    schemaName?: string | null;
+    tableName?: string | null;
+};
+/**
+ * Reconciles persisted join endpoints with the card's selected entities.
+ * Strong identities always win: semantic ID, semantic domain/name, qualified
+ * physical coordinates, then a unique unqualified alias. Every ambiguous tier
+ * fails closed; this function never guesses from list order.
+ */
+export declare function findJoinEntityDataSource(availableDataSources: DatabaseEntityReference[] | undefined, entity: Partial<JoinEntityLike> | undefined): DatabaseEntityReference | undefined;
+export declare function normalizeJoinPlanEntityReferences(joinPlan: JoinPlan, availableDataSources: DatabaseEntityReference[] | undefined): JoinPlan;
+/**
+ * Returns join-plan entities that no longer exist in the card's selected
+ * datasource list. A persisted join can otherwise keep affecting execution
+ * after its table has been removed from the Explorer picker.
+ */
+export declare function findOrphanedJoinPlanEntities(joinPlan: JoinPlan | undefined, availableDataSources: DatabaseEntityReference[] | undefined): DatabaseEntityReference[];
+export {};

package/dist/types/lib/utils/kpi-comparison-utils.d.ts

@@ -0,0 +1,12 @@
+import { MetricComparisonKind } from './metric-comparison-config.js';
+import { ComparisonPresentationSpec } from '../../shared/analytics-protocol/index.js';
+export declare function shouldShowTargetProgress(params: {
+    comparisonKind: MetricComparisonKind;
+    targetValue: number;
+    presentation?: ComparisonPresentationSpec;
+}): boolean;
+export declare function getEffectiveComparisonValue(params: {
+    comparisonKind?: MetricComparisonKind;
+    comparisonValue: number | null;
+    targetValue?: number;
+}): number | null;