react-semaphor 0.1.503 → 0.1.505

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

@@ -0,0 +1,46 @@
+import { ControlDefinition, TDashboard } from '../types/common-types.js';
+export declare function shouldUseSavedDefault(control: ControlDefinition): boolean;
+export type RuntimeControlHydration = {
+    dashboardControlValues: Record<string, unknown>;
+    cardControlValuesMap: Record<string, Record<string, unknown>>;
+};
+export declare function flattenRuntimeControlValues(params: {
+    dashboardValues?: Record<string, unknown>;
+    cardValuesMap?: Record<string, Record<string, unknown>>;
+}): Record<string, unknown>;
+export declare function computeDashboardControlDefaults(dashboard: TDashboard): Record<string, unknown>;
+export declare function computePersistedDashboardDefaultValues(params: {
+    controls: ControlDefinition[] | undefined;
+    dashboardDefaultValues?: Record<string, unknown>;
+}): Record<string, unknown>;
+export declare function syncDashboardDefaultValuesIntoControls(params: {
+    controls: ControlDefinition[] | undefined;
+    dashboardDefaultValues?: Record<string, unknown>;
+}): ControlDefinition[];
+export declare function resolveSavedDefaultValue(control: ControlDefinition, dashboardDefaultValues?: Record<string, unknown>): unknown;
+export declare function computeCardControlDefaults(dashboard: TDashboard): Record<string, Record<string, unknown>>;
+export declare function computeRuntimeControlHydration(dashboard: TDashboard, runtimeOverrides?: Record<string, unknown>, options?: {
+    hasExplicitRuntimeOverrides?: boolean;
+}): RuntimeControlHydration;
+export declare function mergeRelevantControlValues(params: {
+    relevantControlIds: Iterable<string>;
+    dashboardValues?: Record<string, unknown>;
+    cardValues?: Record<string, unknown>;
+}): Record<string, unknown>;
+export declare function reconcileDashboardControlRuntimeValues(params: {
+    previousValues: Record<string, unknown>;
+    nextControls: ControlDefinition[];
+    nextDefaultValues?: Record<string, unknown>;
+    renamed?: {
+        oldId: string;
+        newId: string;
+    };
+}): Record<string, unknown>;
+export declare function reconcileCardControlRuntimeValues(params: {
+    previousValues: Record<string, unknown> | undefined;
+    nextControls: ControlDefinition[];
+    renamed?: {
+        oldId: string;
+        newId: string;
+    };
+}): Record<string, unknown>;

package/dist/types/lib/utils/control-placeholder-utils.d.ts

@@ -0,0 +1,14 @@
+import { ControlBinding } from '../types/common-types.js';
+export type SqlParamReference = {
+    paramId: string;
+    controlId: string;
+};
+export declare function extractParamControlIdsFromSql(sql?: string): string[];
+export declare function extractReferencedControlIds(params: {
+    sql?: string;
+    controlBindings?: ControlBinding[];
+}): string[];
+export declare function extractSqlParamReferences(params: {
+    sql?: string;
+    controlBindings?: ControlBinding[];
+}): SqlParamReference[];

package/dist/types/lib/utils/control-reference-utils.d.ts

@@ -0,0 +1,18 @@
+import { ControlBinding, TCard, TDashboard } from '../types/common-types.js';
+type ControlMutation = {
+    type: 'rename';
+    oldId: string;
+    newId: string;
+} | {
+    type: 'remove';
+    controlId: string;
+};
+export declare function renameControlBindings(bindings: ControlBinding[] | undefined, oldId: string, newId: string): ControlBinding[] | undefined;
+export declare function removeControlBindings(bindings: ControlBinding[] | undefined, controlId: string): ControlBinding[] | undefined;
+export declare function renameDirectSqlControlReferences(sql: string | undefined, oldId: string, newId: string): string | undefined;
+export declare function applyControlMutationToCard(card: TCard, mutation: ControlMutation): TCard;
+export declare function applyControlMutationToDashboard(dashboard: TDashboard, mutation: ControlMutation): TDashboard;
+export declare function applyControlBindingsToDashboardCards(dashboard: TDashboard, cardBindingsById: Record<string, ControlBinding[] | undefined>, options?: {
+    affectedControlIds?: string[];
+}): TDashboard;
+export {};

package/dist/types/lib/utils/copy-control-bindings.d.ts

@@ -0,0 +1,3 @@
+import { ControlBinding, TCard } from '../types/common-types.js';
+/** Preserve the query's parameter names when its backing controls are copied. */
+export declare function copyControlBindings(card: Pick<TCard, 'sql' | 'controlBindings'>, copiedControlIds: ReadonlyMap<string, string>): ControlBinding[] | undefined;

package/dist/types/lib/utils/custom-visual-inputs.d.ts

@@ -0,0 +1,43 @@
+import { TCard, TFrame } from '../types/common-types.js';
+import { CustomVisualInputResult, SlotDefinition } from '../../components/visual/custom-visual/custom-visual-types.js';
+import { TChartType } from '../charts/types.js';
+type ManifestVisualMeta = {
+    visualType?: 'single' | 'multiple';
+    slots?: unknown[];
+    minInputs?: number;
+    maxInputs?: number;
+    dataInputs?: string[];
+};
+type GetInputCardsOptions = {
+    frame: TFrame;
+    configCard?: TCard | null;
+    isMultiInputVisual?: boolean;
+};
+type MultiInputVisualConfig = {
+    url: string;
+    name: string;
+    icon?: string;
+    chartType?: string;
+    minInputs?: number;
+    maxInputs?: number;
+    dataInputs?: string[];
+    visualType?: 'single' | 'multiple';
+    slots?: SlotDefinition[];
+};
+export declare function getSlotExpectedChartType(slot?: SlotDefinition): TChartType;
+export declare function getConfigSlotDefinition(slots?: SlotDefinition[]): SlotDefinition | undefined;
+export declare function getSlotDefinitionForIndex(slots: SlotDefinition[] | undefined, index: number): SlotDefinition | undefined;
+export declare function getSlotExpectedTypeForIndex(slots: SlotDefinition[] | undefined, index: number): TChartType | undefined;
+export declare function getSlotIndexForCard(card: TCard | null | undefined, fallbackIndex: number): number;
+export declare function isCustomVisualConfigCard(card: TCard | null | undefined, frameCards?: TCard[]): boolean;
+export declare function buildSlotOrderedCards(cards: Array<TCard | null>): Array<TCard | null>;
+export declare function reindexSlotCards(cards: TCard[]): TCard[];
+export declare function getConfigSlotExpectedType(slots?: SlotDefinition[]): TChartType | undefined;
+export declare function getEffectiveCardTypeForSlot(inputCard: TCard | null | undefined, slotIndex: number, slots: SlotDefinition[] | undefined): TChartType | undefined;
+export declare function createCardsFromSlots(slots: SlotDefinition[], visual: MultiInputVisualConfig, baseCard: TCard): TCard[];
+export declare function getCustomVisualInputCards({ frame, configCard, isMultiInputVisual, }: GetInputCardsOptions): Array<TCard | null>;
+export declare function findCustomVisualConfigCard(frame: TFrame, activeCard?: TCard | null): TCard | null;
+export declare function resolveMultiInputType(configCard: TCard | null, manifestComponent?: ManifestVisualMeta): 'single' | 'multiple' | null;
+export declare function resolveMultiInputTypeFromVisual(visual: MultiInputVisualConfig): 'single' | 'multiple';
+export declare function normalizeMultiInputPayload(data: CustomVisualInputResult | Record<string, unknown>[]): CustomVisualInputResult;
+export {};

package/dist/types/lib/utils/dashboard-controls-visibility.d.ts

@@ -0,0 +1,24 @@
+import { UIConfig } from '../types/token-types.js';
+type DashboardControlsVisibilityConfig = Pick<UIConfig, 'showDashboardHub' | 'showDashboardSharing' | 'showGroupManagement'>;
+export type DashboardControlsVisibility = {
+    showDashboardHub: boolean;
+    showDashboardSharing: boolean;
+    showGroupManagement: boolean;
+};
+export declare function isDashboardSharingVisible(config?: Pick<UIConfig, 'showDashboardSharing'>): boolean;
+export declare function resolveDashboardTitleEditability({ isDashboardEditing, canEditDashboard, hasCurrentLens, }: {
+    isDashboardEditing: boolean;
+    canEditDashboard: boolean;
+    hasCurrentLens: boolean;
+}): boolean;
+/**
+ * Resolves token-scoped dashboard chrome without weakening authorization.
+ * Token flags can hide a permitted capability, but can never grant one.
+ */
+export declare function resolveDashboardControlsVisibility({ config, canNavigateDashboardHub, canShareDashboard, canManageGroups, }: {
+    config?: DashboardControlsVisibilityConfig;
+    canNavigateDashboardHub: boolean;
+    canShareDashboard: boolean;
+    canManageGroups: boolean;
+}): DashboardControlsVisibility;
+export {};

package/dist/types/lib/utils/dashboard-date-filter-utils.d.ts

@@ -0,0 +1,16 @@
+import { Field } from '../types/explorer-types.js';
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+import { getSelectedDateFilterColumn } from './date-filter-column-utils.js';
+import { DashboardInputValues, TCard, TDashboard } from '../types/common-types.js';
+import { DashboardCardFilterCompilationResult } from '../query-context/compile-dashboard-card-filters.js';
+export { getSelectedDateFilterColumn };
+export declare function hasMatchingCompiledDashboardDateFilter(card: TCard, compilation: DashboardCardFilterCompilationResult): boolean;
+export declare function hasMatchingDashboardDateFilter(dashboardFilters: TFilter[], dateGroupByField: Pick<Field, 'name' | 'qualifiedFieldName' | 'qualifiedEntityName'> | null | undefined, filterValues: TFilterValue[] | undefined): boolean;
+export declare function hasMatchingDashboardInputDateFilter({ dashboard, dateGroupByField, dashboardInputValues, sheetId, card, timezone, }: {
+    dashboard: TDashboard | undefined;
+    dateGroupByField: Field | undefined;
+    dashboardInputValues: DashboardInputValues | undefined;
+    sheetId?: string | null;
+    card?: TCard | null;
+    timezone?: string;
+}): boolean;

package/dist/types/lib/utils/dashboard-interaction-mode.d.ts

@@ -0,0 +1,12 @@
+export type DashboardInteractionMode = {
+    canEditDashboard: boolean | undefined;
+    hasInspectionUser: boolean;
+    isInspectionMode: boolean;
+    isInspectionSurface: boolean;
+    inspectionMessage: string | null;
+};
+export declare function resolveDashboardInteractionMode({ canEditDashboard, endUserId, inspection, }: {
+    canEditDashboard: boolean | undefined;
+    endUserId: string | undefined;
+    inspection: boolean | undefined;
+}): DashboardInteractionMode;

package/dist/types/lib/utils/data-source-semantic-domain.d.ts

@@ -0,0 +1,12 @@
+import { DataSource } from '../types/explorer-types.js';
+/**
+ * The semantic domain a card's data source belongs to.
+ *
+ * `DataSource.semanticDomainId` is authoritative when set. Cards whose
+ * datasets were picked from a domain may carry the domain only on the
+ * selected entities, so fall back to the first dataset entity's `domainId`.
+ * Every surface that decides "is this card semantic" (field list, click
+ * and drop gates, column loader) must use this, so none of them can judge
+ * the same card differently.
+ */
+export declare function getDataSourceSemanticDomainId(dataSource: Pick<DataSource, 'semanticDomainId' | 'selectedEntities'> | null | undefined): string | undefined;

package/dist/types/lib/utils/data-source-utils.d.ts

@@ -0,0 +1,22 @@
+import { DataSource } from '../types/explorer-types.js';
+/**
+ * Extract table metadata from the new data source structure
+ * Provides compatibility with legacy SQL generation that expects table/schema/database names
+ */
+export declare function extractTableMetadata(dataSource: DataSource | undefined): {
+    tableName: undefined;
+    schemaName: undefined;
+    databaseName: undefined;
+    connectionId: string | undefined;
+    connectionType: string | undefined;
+} | {
+    tableName: string;
+    schemaName: string | undefined;
+    databaseName: string | undefined;
+    connectionId: string;
+    connectionType: string;
+};
+/**
+ * Check if we have sufficient table metadata for SQL generation
+ */
+export declare function hasTableMetadata(dataSource: DataSource | undefined): boolean;

package/dist/types/lib/utils/date-filter-column-utils.d.ts

@@ -0,0 +1,2 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+export declare function getSelectedDateFilterColumn(filter: TFilter, filterValues: TFilterValue[] | undefined): string;

package/dist/types/lib/utils/date-format-utils.d.ts

@@ -0,0 +1,8 @@
+import { DateFormatOption, TimeGranularity } from '../types/explorer-types.js';
+/**
+ * Get available date format options for a specific granularity level
+ *
+ * @param granularity - Time granularity (day, week, month, quarter, year, hour, minute, second)
+ * @returns Array of format options with value and label
+ */
+export declare function getDateFormatOptionsForGranularity(granularity: TimeGranularity): DateFormatOption[];

package/dist/types/lib/utils/date-granularity-utils.d.ts

@@ -0,0 +1,5 @@
+import { TimeGranularity } from '../types/explorer-types.js';
+export declare const DATE_GRANULARITY_OPTIONS: TimeGranularity[];
+export declare const DATE_TIME_GRANULARITY_OPTIONS: TimeGranularity[];
+export declare const supportsSubDayGranularity: (dataType?: string) => boolean;
+export declare const getGranularityOptionsForFieldType: (dataType?: string) => TimeGranularity[];

package/dist/types/lib/utils/date-hierarchy-utils.d.ts

@@ -0,0 +1,73 @@
+import { Field, TimeGranularity } from '../types/explorer-types.js';
+import { DrillHierarchy, DrillHierarchyStep } from '../types/interaction-types.js';
+import { TCard } from '../types/common-types.js';
+/**
+ * Generate a complete date drill hierarchy for a given date field
+ *
+ * Creates a dynamic hierarchy with all granularity levels.
+ * DATE columns stop at day. TIMESTAMP/DATETIME columns continue to hour/minute/second.
+ * The hierarchy uses type 'date' to enable runtime determination of next drill step.
+ *
+ * Each step is configured with:
+ * - Proper granularity
+ * - Human-readable labels
+ * - Appropriate date formats
+ * - Drill-down mode
+ *
+ * The steps serve as a "reference pool" - the actual next step is determined dynamically
+ * at drill time based on the current chart's granularity.
+ *
+ * @param dateField - The date field to create hierarchy for
+ * @returns Complete drill hierarchy with all granularity steps
+ */
+export declare function generateDateHierarchy(dateField: Field): DrillHierarchy;
+/**
+ * Check if a field should have an auto-generated date hierarchy
+ *
+ * Criteria:
+ * - Field must be a date type
+ * - No existing hierarchy for this field
+ *
+ * @param field - Field to check
+ * @param existingHierarchies - Already configured hierarchies
+ * @returns true if hierarchy should be auto-generated
+ */
+export declare function shouldAutoGenerateDateHierarchy(field: Field, existingHierarchies?: DrillHierarchy[]): boolean;
+/**
+ * Find existing date hierarchy for a given field
+ *
+ * Checks both:
+ * - Auto-generated hierarchies (ID pattern: auto_date_{fieldId})
+ * - Manual hierarchies that use this field
+ *
+ * @param fieldId - ID of the field to search for
+ * @param hierarchies - Hierarchies to search
+ * @returns Matching hierarchy or undefined
+ */
+export declare function findDateHierarchyForField(fieldId: string, hierarchies: DrillHierarchy[]): DrillHierarchy | undefined;
+/**
+ * Dynamically determine the next date drill step based on current granularity
+ *
+ * This function enables runtime determination of drill steps, allowing hierarchies
+ * to adapt to the current chart state. For example:
+ * - Chart showing Month → next step is Week
+ * - Chart showing Year → next step is Quarter
+ *
+ * @param hierarchy - The date hierarchy configuration
+ * @param currentGranularity - Current chart granularity level
+ * @returns Next drill step based on current state, or undefined if at most granular level
+ */
+export declare function getNextDateHierarchyStep(hierarchy: DrillHierarchy, currentGranularity: TimeGranularity | undefined): DrillHierarchyStep | undefined;
+/**
+ * Get current date granularity from card config or breadcrumbs
+ *
+ * This utility consolidates the logic for determining the current granularity level
+ * when working with date hierarchies. It checks breadcrumbs first (for drilled state),
+ * then falls back to finding the matching field in the card's groupByColumns.
+ *
+ * @param hierarchy - The date hierarchy configuration
+ * @param card - Card containing field configuration
+ * @param breadcrumbs - Optional breadcrumb trail from drill interactions
+ * @returns Current granularity level or undefined if not found
+ */
+export declare function getCurrentDateGranularity(hierarchy: DrillHierarchy, card: TCard, breadcrumbs?: any[]): TimeGranularity | undefined;

package/dist/types/lib/utils/date-timezone-utils.d.ts

@@ -0,0 +1,99 @@
+import { CalendarContext, WeekStart } from '../types/token-types.js';
+/**
+ * Gets the start of day (00:00:00.000) for a date in the specified timezone.
+ * This ensures that when the Date is serialized to UTC, it represents the correct day boundary.
+ *
+ * @param date - The date to get start of day for
+ * @param timezone - The timezone to use (e.g., 'America/Los_Angeles')
+ * @returns A Date object representing midnight in the specified timezone
+ *
+ * @example
+ * // User in PST selects Nov 18, 2025
+ * startOfDayInTimezone(new Date('2025-11-18'), 'America/Los_Angeles')
+ * // Returns a Date that serializes to: 2025-11-18T08:00:00.000Z (Nov 18 00:00 PST)
+ */
+export declare const startOfDayInTimezone: (date: Date, timezone: string) => Date;
+/**
+ * Gets the end of day (23:59:59.999) for a date in the specified timezone.
+ * This ensures that when the Date is serialized to UTC, it represents the correct day boundary.
+ *
+ * @param date - The date to get end of day for
+ * @param timezone - The timezone to use (e.g., 'America/Los_Angeles')
+ * @returns A Date object representing 23:59:59.999 in the specified timezone
+ *
+ * @example
+ * // User in PST selects Nov 20, 2025
+ * endOfDayInTimezone(new Date('2025-11-20'), 'America/Los_Angeles')
+ * // Returns a Date that serializes to: 2025-11-21T07:59:59.999Z (Nov 20 23:59:59 PST)
+ */
+export declare const endOfDayInTimezone: (date: Date, timezone: string) => Date;
+/**
+ * Gets the start of week (midnight) for a date in the specified timezone.
+ *
+ * @param date - The date to get start of week for
+ * @param timezone - The timezone to use (e.g., 'America/Los_Angeles')
+ * @param weekStartsOn - Day the week starts on (0=Sunday, 1=Monday). Can also pass CalendarContext.
+ * @returns A Date object representing midnight on the first day of the week
+ *
+ * @example
+ * // With weekStartsOn number
+ * startOfWeekInTimezone(new Date(), 'America/Chicago', 0) // Sunday start
+ *
+ * // With CalendarContext
+ * startOfWeekInTimezone(new Date(), 'America/Chicago', { tz: 'America/Chicago', weekStart: 0, anchor: 'now' })
+ */
+export declare const startOfWeekInTimezone: (date: Date, timezone: string, weekStartsOn?: WeekStart | CalendarContext) => Date;
+/**
+ * Gets the end of week (23:59:59.999) for a date in the specified timezone.
+ *
+ * @param date - The date to get end of week for
+ * @param timezone - The timezone to use (e.g., 'America/Los_Angeles')
+ * @param weekStartsOn - Day the week starts on (0=Sunday, 1=Monday). Can also pass CalendarContext.
+ * @returns A Date object representing the last moment of the last day of the week
+ */
+export declare const endOfWeekInTimezone: (date: Date, timezone: string, weekStartsOn?: WeekStart | CalendarContext) => Date;
+export declare const startOfMonthInTimezone: (date: Date, timezone: string) => Date;
+export declare const endOfMonthInTimezone: (date: Date, timezone: string) => Date;
+export declare const startOfQuarterInTimezone: (date: Date, timezone: string) => Date;
+export declare const endOfQuarterInTimezone: (date: Date, timezone: string) => Date;
+export declare const startOfYearInTimezone: (date: Date, timezone: string) => Date;
+export declare const endOfYearInTimezone: (date: Date, timezone: string) => Date;
+export declare const shiftDateByDaysInTimezone: (date: Date, timezone: string, days: number) => Date;
+export declare const shiftDateByWeeksInTimezone: (date: Date, timezone: string, weeks: number) => Date;
+export declare const shiftDateByMonthsInTimezone: (date: Date, timezone: string, months: number) => Date;
+export declare const shiftDateByQuartersInTimezone: (date: Date, timezone: string, quarters: number) => Date;
+export declare const shiftDateByYearsInTimezone: (date: Date, timezone: string, years: number) => Date;
+/**
+ * Resolves the effective timezone.
+ *
+ * Since backend always includes calendarContext in JWT tokens, prefer using
+ * useCalendarContext() hook instead. This function is kept for backward compatibility
+ * and for contexts where hooks are not available.
+ *
+ * Resolution order:
+ * 1. CalendarContext.tz (if CalendarContext provided)
+ * 2. Explicit timezone string
+ * 3. Browser's timezone (fallback)
+ *
+ * @param timezoneOrContext - Optional timezone string or CalendarContext
+ * @returns The effective IANA timezone string
+ *
+ * @example
+ * // With CalendarContext (preferred)
+ * getEffectiveTimezone(calendarContext) // Returns calendarContext.tz
+ *
+ * // With token timezone
+ * getEffectiveTimezone('America/New_York') // Returns 'America/New_York'
+ *
+ * // Without timezone (falls back to browser)
+ * getEffectiveTimezone() // Returns browser's timezone (e.g., 'America/Los_Angeles')
+ */
+export declare const getEffectiveTimezone: (timezoneOrContext?: string | CalendarContext | null) => string;
+/**
+ * Resolves the effective weekStart from CalendarContext.
+ *
+ * @param calendarContext - Optional CalendarContext
+ * @returns The week start day (0=Sunday, 1=Monday)
+ * @default 1 (Monday) for backward compatibility with ISO standard
+ */
+export declare const getEffectiveWeekStart: (calendarContext?: CalendarContext | null) => WeekStart;

package/dist/types/lib/utils/drag-and-drop-utils.d.ts

@@ -0,0 +1,8 @@
+import { ContainerId, GroupByField, MetricField, SortByField, PivotByField, DetailField, Field, AggregateFunction } from '../types/explorer-types.js';
+import { TCard } from '../types/index.js';
+import { ShelfDefinitionCard } from './card-definition.js';
+export declare function getFieldId(containerId: ContainerId, field: Field): string;
+export declare function getAggregationLabel(columnName: string, aggregation: AggregateFunction): string;
+export declare function getSmartContainerForField(field: Field, existingFields: Field[], chartType?: TCard['type']): ContainerId | null;
+export declare function getNewField(activeField: Field, overContainer: ContainerId, existingFields?: Field[]): MetricField | GroupByField | PivotByField | SortByField | DetailField | null;
+export declare function isCardConfigPresent(card: ShelfDefinitionCard): boolean;

package/dist/types/lib/utils/drill-context-utils.d.ts

@@ -0,0 +1,32 @@
+import { ClickFilterCondition } from '../types/interaction-types.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+/**
+ * Convert ClickFilterCondition to TFilterValue format
+ *
+ * Note: This is a temporary solution for drill context. In the long term,
+ * we need a more robust system for cross-dashboard filter passing.
+ */
+export declare function convertClickFilterToFilterValue(condition: ClickFilterCondition): TFilterValue;
+/**
+ * Build combined filters based on contextMode
+ *
+ * @param drillFilters - Filters from the clicked element (drill context)
+ * @param dashboardFilters - Current dashboard filters (optional)
+ * @param contextMode - How to combine filters
+ * @returns Combined filters as TFilterValue[]
+ */
+export declare function buildDrillFilters(drillFilters: ClickFilterCondition[], dashboardFilters?: TFilterValue[], contextMode?: 'interactionFilters' | 'full' | 'none'): TFilterValue[];
+/**
+ * Get display text for drill context breadcrumb
+ *
+ * @param conditions - Filter conditions to display
+ * @returns Human-readable text like "Country = USA, State = CA"
+ */
+export declare function getDrillBreadcrumbText(conditions: ClickFilterCondition[]): string;
+/**
+ * Get source dashboard title for back button
+ *
+ * @param sourceDashboardTitle - Optional dashboard title from drill history
+ * @returns Display text like "Back to Sales Dashboard" or just "Back"
+ */
+export declare function getBackButtonText(sourceDashboardTitle?: string): string;

package/dist/types/lib/utils/entity-consistency-utils.d.ts

@@ -0,0 +1,48 @@
+import { Field, JoinPlan, MetricField, AggregateFunction, ContainerId, FilterGroup } from '../types/explorer-types.js';
+import { FieldStateResult } from './field-state-calculator.js';
+import { FieldAvailabilityContext } from './field-availability-context.js';
+/**
+ * Check if two entities are joined based on the join plan
+ */
+export declare function areEntitiesJoined(entity1: string, entity2: string, joinPlan: JoinPlan | undefined): boolean;
+/**
+ * Validate whether a field can be added to the query alongside the fields
+ * already on the shelves.
+ *
+ * This is the ONE gate. Drag-drop, row click, keyboard insertion, and the
+ * matrix editor all call it, and it defers entirely to
+ * `calculateFieldState`, so the list, the preview card, and the drop
+ * behaviour can never disagree. Calculated fields are evaluated through
+ * the datasets they read from; they are not exempt.
+ *
+ * Returns the field state so callers can explain a refusal precisely.
+ */
+export declare function validateEntityConsistency(newField: Field, existingFields: Field[], context: FieldAvailabilityContext): {
+    isValid: boolean;
+    showError?: boolean;
+    fieldState?: FieldStateResult;
+};
+/**
+ * Show the "cannot add this field" notification. Uses the precise reason
+ * and action from the field state when available; falls back to the
+ * generic join guidance.
+ */
+export declare function showJoinRequiredNotification(fieldState?: FieldStateResult): void;
+/**
+ * Check if a field already exists in a container
+ * For metric fields, always allow duplicates since users will configure different filters after dropping
+ */
+export declare function fieldAlreadyExists(field: Field, containerFields: Field[]): boolean;
+/**
+ * Generate a descriptive label for a metric field that includes filter information
+ */
+export declare function getMetricDisplayLabel(field: Field): string;
+/**
+ * Generate a unique label for duplicate metric fields
+ * This helps users distinguish between multiple instances of the same field
+ */
+export declare function getUniqueMetricLabel(field: Field, existingFields: Field[], containerId: ContainerId): string;
+/**
+ * Create a metric field with filter parameters
+ */
+export declare function createMetricWithFilter(baseField: Field, aggregate: AggregateFunction, filters?: FilterGroup, customLabel?: string): MetricField;

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

@@ -0,0 +1,17 @@
+import { EntityType } from '../types/explorer-types.js';
+interface GetEntityIconOptions {
+    /**
+     * Size class for the icon (e.g., "h-4 w-4", "h-3 w-3")
+     * @default "h-4 w-4"
+     */
+    size?: string;
+}
+/**
+ * Get entity icon component based on entity type
+ *
+ * @param type - The entity type (table, view, model, dataset, file, etc.)
+ * @param options - Optional configuration for icon appearance
+ * @returns React icon component
+ */
+export declare function getEntityIcon(type: EntityType | string, options?: GetEntityIconOptions): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/lib/utils/explorer-derived-field.d.ts

@@ -0,0 +1,4 @@
+import { Field } from '../types/explorer-types.js';
+import { SemaphorDerivedFieldDefinition, SemaphorFieldRef } from '../../shared/analytics-protocol/index.js';
+/** Adapt the existing formula editor without parsing SQL or guessing aggregate semantics. */
+export declare function explorerDerivedField(field: Field, resolveField: (field: Field) => SemaphorFieldRef | undefined): SemaphorDerivedFieldDefinition | undefined;

package/dist/types/lib/utils/explorer-field-identity.d.ts

@@ -0,0 +1,15 @@
+import { ContainerId, Field } from '../types/explorer-types.js';
+type ShelfFieldIdentity = Pick<Field, 'name'> & Partial<Pick<Field, 'id' | 'entityName' | 'qualifiedEntityName'>>;
+/**
+ * Resolves the identity a shelf uses for a field.
+ *
+ * Saved cards can contain fields with no persisted `id`, so the shelf
+ * synthesizes one to keep drag, selection, and field editing working.
+ */
+export declare function resolveShelfFieldId(field: ShelfFieldIdentity, containerId: ContainerId): string;
+/**
+ * Finds a field by shelf identity. Persisted IDs are authoritative; synthesized
+ * identities are considered only when no stored ID matches.
+ */
+export declare function findShelfFieldIndex(fields: readonly ShelfFieldIdentity[] | undefined, columnId: string, containerId: ContainerId): number;
+export {};

package/dist/types/lib/utils/export-result-source.d.ts

@@ -0,0 +1,20 @@
+import { FlatTableTotalsByColumnId } from '../table-formatting/table-totals-settings.js';
+import { QueryColumnKeyMap } from '../types/explorer-types.js';
+import { SemaphorResultColumn } from '../../shared/analytics-protocol/index.js';
+type ResolveExportResultSourceParams<T> = {
+    cardType: string;
+    queriedResult: T | null | undefined;
+    suppliedResult: T | null | undefined;
+};
+/**
+ * Select one result snapshot for an export and keep its presentation metadata
+ * attached. Matrix expansion is supplied by the renderer; other cards prefer
+ * the query owned by the export dialog.
+ */
+export declare function resolveExportResultSource<T>({ cardType, queriedResult, suppliedResult, }: ResolveExportResultSourceParams<T>): {
+    resultColumns?: readonly SemaphorResultColumn[];
+    columnKeyMap?: QueryColumnKeyMap;
+    exportData: T | null | undefined;
+    tableTotalsByColumnId: FlatTableTotalsByColumnId | undefined;
+};
+export {};

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

@@ -0,0 +1,26 @@
+/**
+ * Utility functions for determining supported export formats based on card type
+ */
+export type ExportFormat = 'pdf' | 'csv' | 'png';
+/**
+ * Get supported export formats for a given card type
+ * @param cardType - The type of card/visual
+ * @returns Array of supported export formats
+ */
+export declare function getSupportedExportFormats(cardType: string, options?: {
+    allowDownload?: boolean;
+}): ExportFormat[];
+/**
+ * Get the default export format for a given card type
+ * @param cardType - The type of card/visual
+ * @returns Default export format
+ */
+export declare function getDefaultExportFormat(cardType: string, options?: {
+    allowDownload?: boolean;
+}): ExportFormat;
+/**
+ * Check if a card type is a table type
+ * @param cardType - The type of card/visual
+ * @returns True if the card is a table type
+ */
+export declare function isTableType(cardType: string): boolean;

package/dist/types/lib/utils/expression-field-classification.d.ts

@@ -0,0 +1,12 @@
+import { Field } from '../types/explorer-types.js';
+export type ExpressionFieldKind = 'none' | 'inline_expression' | 'domain_calculated' | 'user_calculated';
+export type CalculatedFieldPickerContext = 'editor' | 'filter' | 'inline-filter';
+export declare function isRootCalculatedFieldReference(field: Field): boolean;
+export declare function getExpressionFieldKind(field: Field): ExpressionFieldKind;
+export declare function isCalculatedExpressionField(field: Field): boolean;
+export declare function isManagedCalculatedExpressionField(field: Field): boolean;
+export declare function isSharedManagedCalculatedExpressionField(field: Field): boolean;
+export declare function isInlineExpressionField(field: Field): boolean;
+export declare function isCalculatedFieldVisibleInPicker(field: Field, context: CalculatedFieldPickerContext, options?: {
+    isValuePickSafe?: boolean;
+}): boolean;

package/dist/types/lib/utils/fetch-export-data.d.ts

@@ -0,0 +1,14 @@
+import { DashboardCardQueryRequestPayloadBase } from '../query-context/build-dashboard-card-query-contract.js';
+import { TableTotalsRequest } from '../types/explorer-types.js';
+export type FetchExportDataParams = {
+    apiServiceUrl: string;
+    authToken: string;
+    connectionId: string;
+    requestPayloadBase: DashboardCardQueryRequestPayloadBase;
+    tableTotalsRequest?: TableTotalsRequest;
+};
+/**
+ * Fetch all data for export (up to 10K rows)
+ * Uses the existing /v1/query endpoint with exportMode flag
+ */
+export declare function fetchAllDataForExport({ apiServiceUrl, authToken, connectionId, requestPayloadBase, tableTotalsRequest, }: FetchExportDataParams): Promise<any>;