react-semaphor 0.1.504 → 0.1.506

package/dist/types/lib/types/feedback-types.d.ts

@@ -0,0 +1,60 @@
+import { CurrentUser } from '../../components/sharing-and-management/hooks/use-current-user-info.js';
+import { TokenProps } from './token-types.js';
+import { UIMessage } from 'ai';
+import { AIContext } from './assistant-types.js';
+export declare enum FeedbackCategory {
+    QUERY_GENERATION = "query-generation",
+    DASHBOARD_ASSISTANT = "dashboard-assistant",
+    EDITOR_ASSISTANT = "editor-assistant"
+}
+export interface FeedbackSystemState {
+    cardConfig: any;
+    dataSource: any;
+    dashboardFilters: any;
+    errorMessage?: string;
+    errorSql?: string;
+    generatedSql?: string;
+    assistantType?: 'dashboard' | 'editor';
+    toolType?: string;
+    toolInput?: any;
+    toolOutput?: any;
+    userQuery?: string;
+    messages?: UIMessage[];
+    aiContext?: AIContext;
+    systemPrompt?: string;
+}
+export interface FeedbackMetadata {
+    url: string;
+    userAgent: string;
+    timestamp: string;
+    viewport: string;
+}
+export interface FeedbackPayload {
+    category: FeedbackCategory;
+    userMessage?: string;
+    user?: CurrentUser | null;
+    tokenContext?: TokenProps;
+    systemState: FeedbackSystemState;
+    metadata: FeedbackMetadata;
+}
+export interface FeedbackResponse {
+    success: boolean;
+    issueNumber: string;
+    message?: string;
+    error?: string;
+}
+export interface FeedbackEmailData {
+    issueNumber: string;
+    category: FeedbackCategory;
+    timestamp: string;
+    user?: CurrentUser | null;
+    tokenContext?: TokenProps;
+    error: {
+        message?: string;
+        sql?: string;
+        errorSql?: string;
+    };
+    systemState: FeedbackSystemState;
+    environment: FeedbackMetadata;
+    userMessage?: string;
+}

package/dist/types/lib/types/index.d.ts

@@ -0,0 +1,10 @@
+export * from './common-types.js';
+export * from './explorer-types.js';
+export * from '../utils/field-dependencies.js';
+export * from './token-types.js';
+export * from './briefing-types.js';
+export type { AppearanceSpec } from '../appearance/types.js';
+export type { TChartType } from '../charts/types.js';
+export type { CanonicalFormatSpec } from '../formatters/canonical-format-adapter.js';
+export type { DateUnit, DateSelectionMode, FilterFieldMeta, FilterLocation, FilterSemanticContext, Operation, RelativeDateFilter, RelativeDateUnit, SubDayDateUnit, TFilter, TFilterValue, } from '../../components/surfboard/filter/types.js';
+export type DateComparisonOperation = Extract<import('../../components/surfboard/filter/types.js').Operation, '=' | '!=' | '>' | '>=' | '<' | '<=' | 'between' | 'not between' | 'is null' | 'is not null'>;

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

@@ -0,0 +1,483 @@
+import { TChartType } from '../charts/types.js';
+import { Field, Operator, SortByField, TimeGranularity } from './explorer-types.js';
+import { TemporalBucketMetadata } from '../../shared/analytics-protocol/contracts.js';
+/**
+ * Defines what element must be clicked to trigger an interaction.
+ *
+ * The `type` determines filtering behavior:
+ * - 'metric': Captures intersection of ALL dimensions (e.g., country='USA' AND state='CA')
+ * - 'attribute': Captures ONLY the clicked dimension (e.g., country='USA')
+ *
+ * Note: `trigger.type` is different from `field.type`:
+ * - trigger.type = filtering behavior ('metric' | 'attribute')
+ * - field.type = data type ('dimension' | 'metric' | 'measure')
+ */
+export interface InteractionTrigger {
+    /**
+     * Determines filtering behavior when this trigger fires:
+     * - 'metric': Capture intersection of all dimensions
+     * - 'attribute': Capture only this specific dimension
+     */
+    type: 'metric' | 'attribute';
+    /**
+     * The field (metric or attribute) that must be clicked.
+     * For multi-series charts: Use the specific metric Field with unique ID
+     * (e.g., Field with id='count_of_orders')
+     */
+    field: Field;
+}
+export type DrillMode = 'drillDown' | 'dynamicDrill' | 'drillThrough' | 'drillToDetail' | 'drillToURL' | 'inlineDrill';
+export interface DrillHierarchy {
+    id: string;
+    label?: string;
+    type: 'static' | 'date';
+    steps: DrillHierarchyStep[];
+    default?: boolean;
+    baseField?: Field;
+}
+export interface DrillHierarchyStep {
+    field: Field;
+    mode: 'drillDown';
+    preferredChartType?: TChartType;
+    breadcrumbLabelTemplate?: string;
+    retainFilters?: boolean;
+    label?: string;
+    linkedInsightId?: string;
+}
+export interface DrillDownInteraction {
+    mode: 'drillDown';
+    /**
+     * What element must be clicked to trigger this drill-down.
+     * Optional during configuration, but must be defined before execution.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    hierarchyId?: string;
+    label?: string;
+}
+export interface DrillThroughInteraction {
+    mode: 'drillThrough';
+    /**
+     * What element must be clicked to trigger this drill-through.
+     * @migration Optional during migration. Will be required in V2.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    targetDashboardId: string;
+    /**
+     * How to pass context to the target dashboard
+     * @default 'interactionFilters'
+     */
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    label?: string;
+}
+export interface DrillToDetailInteraction {
+    mode: 'drillToDetail';
+    /**
+     * What element must be clicked to trigger this drill to detail.
+     * @migration Optional during migration. Will be required in V2.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    detailFields?: Field[];
+    sortBy?: SortByField[];
+    limit?: number;
+    detailTitle?: string;
+    /**
+     * Target insight ID to navigate to
+     */
+    targetInsightId?: string;
+    /**
+     * How to pass context to the target insight
+     * @default 'interactionFilters'
+     */
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    /**
+     * How to display the insight
+     * @default 'modal'
+     */
+    displayMode?: 'modal' | 'replace-card';
+    label?: string;
+}
+/**
+ * URL Parameter for drill-to-URL interpolation
+ * Represents a placeholder in the URL template (e.g., {{product_id}})
+ */
+export interface URLParameter {
+    /**
+     * Unique identifier for the parameter (e.g., 'product_id', 'card_id')
+     * Used in template as {{id}}
+     */
+    id: string;
+    /**
+     * Display label for the parameter
+     */
+    label: string;
+    /**
+     * Category of the parameter
+     * - attribute: From card dimensions/attributes (e.g., product name, region)
+     * - identifier: System values (card_id, frame_id, sheet_id)
+     */
+    category: 'attribute' | 'identifier';
+    /**
+     * For attribute parameters: the complete field object
+     * Provides access to all field properties (name, qualifiedFieldName, dataType, etc.)
+     */
+    field?: Field;
+}
+export interface DrillToURLInteraction {
+    mode: 'drillToURL';
+    /**
+     * What element must be clicked to trigger this URL drill.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    /**
+     * URL template with placeholders (e.g., 'https://example.com/product/{{product_id}}')
+     */
+    urlTemplate: string;
+    /**
+     * List of parameters used in the URL template
+     */
+    parameters: URLParameter[];
+    /**
+     * Whether to URL-encode parameter values
+     * @default true
+     */
+    encodeParameters?: boolean;
+    /**
+     * Custom label for this interaction in the menu
+     */
+    label?: string;
+}
+export interface InlineDrillInteraction {
+    mode: 'inlineDrill';
+    /**
+     * What element must be clicked to trigger this inline drill.
+     * @migration Optional during migration. Will be required in V2.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    /**
+     * When to fetch the detailed data
+     * @default 'lazy'
+     */
+    fetchMode?: 'lazy' | 'preloaded';
+    /**
+     * Maximum number of records to show (0 for unlimited)
+     * @default 100
+     */
+    inlineLimit?: number;
+    /**
+     * How to display the detailed records
+     * @default 'table'
+     */
+    displayMode?: 'table' | 'list' | 'cards';
+    /**
+     * Whether to show records in a modal overlay
+     * @default false
+     */
+    showInModal?: boolean;
+    /**
+     * Whether to allow exporting the detailed records
+     * @default true
+     */
+    allowExport?: boolean;
+    label?: string;
+}
+export interface DrillUpInteraction {
+    mode: 'drillUp';
+    /**
+     * What element must be clicked to trigger this drill-up.
+     * For synthetic drill-up interactions, this is inherited from the original drill-down.
+     */
+    trigger?: InteractionTrigger;
+    /**
+     * The hierarchy ID to reference for display purposes.
+     * Used to show the parent level name in the interaction menu.
+     */
+    hierarchyId?: string;
+    label?: string;
+}
+export interface DynamicDrillInteraction {
+    mode: 'dynamicDrill';
+    /**
+     * What element must be clicked to trigger this dynamic drill menu.
+     * When this trigger fires, user sees a menu of available fields to explore.
+     */
+    trigger?: InteractionTrigger;
+    /**
+     * List of fields available for dynamic exploration.
+     * User can choose which field to drill into at runtime.
+     * Only drillable fields (string, boolean types) should be included.
+     */
+    availableFields: Field[];
+    /**
+     * Optional label for the menu item.
+     * Defaults to "Explore Fields" if not specified.
+     */
+    label?: string;
+    /**
+     * @internal
+     * Runtime-only field set when user selects a specific field from the menu.
+     * Not part of configuration.
+     */
+    drillField?: Field;
+}
+export type DrillInteraction = DrillThroughInteraction | DrillToDetailInteraction | DrillToURLInteraction | InlineDrillInteraction;
+export interface TimeDrillStep {
+    granularity: TimeGranularity;
+    next?: TimeGranularity;
+    comparison?: 'previous_year' | 'previous_period';
+    rollingWindow?: number;
+}
+export interface TimeComparison {
+    type: 'previous_year' | 'previous_period';
+    offset: number;
+    granularity: TimeGranularity;
+}
+export interface DrillState {
+    hierarchyId?: string;
+    steps: DrillBreadcrumb[];
+}
+export interface ClickFilterInteraction {
+    mode: 'clickFilter';
+    /**
+     * What element must be clicked to trigger this interaction.
+     * Determines both the matching logic and the filtering behavior.
+     *
+     * @migration Optional during migration. Will be required in V2.
+     * Old configs without trigger will apply to any click (legacy behavior).
+     */
+    trigger?: InteractionTrigger;
+    /**
+     * Fields from the chart element that should be used as filters.
+     * e.g., [region, ship_mode] from a stacked bar chart
+     */
+    filterFields: Field[];
+    /**
+     * Should this card visually highlight when clicked?
+     */
+    highlightSelf?: boolean;
+    /**
+     * Cards this filter applies to (inclusive).
+     * If omitted and `excludeCardIds` is also omitted → applies to all cards except self.
+     */
+    applyToCardIds?: string[];
+    /**
+     * Cards to explicitly exclude from receiving this filter.
+     * Takes effect only if `applyToCardIds` is undefined (acts as override).
+     */
+    excludeCardIds?: string[];
+    /**
+     * Optional UI label or tooltip.
+     */
+    label?: string;
+}
+export interface InteractionTargetOverride {
+    applyToCardIds?: string[] | null;
+    excludeCardIds?: string[] | null;
+}
+export interface ClickFilterCondition {
+    field: Field;
+    operator: Operator;
+    value: string | number | null;
+    label?: string;
+    /** Governed meaning for a canonical grouped-temporal scalar. */
+    temporalBucket?: TemporalBucketMetadata;
+}
+export interface ClickFilterConditionGroup {
+    filters: ClickFilterCondition[];
+}
+export interface ClickedMetricValue {
+    field: Field;
+    /** Optional display value. Aggregate-only drill targets must not fabricate a cell value. */
+    value?: number;
+    formattedValue?: string;
+}
+export type InteractionEvent = DrillDownEvent | DynamicDrillEvent | DrillToURLEvent | DrillThroughEvent | DrillToDetailEvent | InlineDrillEvent | ClickFilterEvent;
+export interface BaseInteractionEvent {
+    sourceCardId: string;
+    filterGroups: ClickFilterConditionGroup[];
+    metric?: ClickedMetricValue;
+}
+export interface DrillDownEvent extends BaseInteractionEvent {
+    interactionMode: 'drillDown';
+    hierarchyId: string;
+    filterGroups: ClickFilterConditionGroup[];
+    metric?: ClickedMetricValue;
+    toField: Field;
+    granularity?: TimeGranularity;
+    timeComparison?: TimeComparison;
+}
+export interface DynamicDrillEvent extends BaseInteractionEvent {
+    interactionMode: 'dynamicDrill';
+    filterGroups: ClickFilterConditionGroup[];
+    metric?: ClickedMetricValue;
+    toField: Field;
+    granularity?: TimeGranularity;
+    timeComparison?: TimeComparison;
+}
+export interface DrillToURLEvent extends BaseInteractionEvent {
+    interactionMode: 'drillToURL';
+    url: string;
+}
+export interface DrillThroughEvent extends BaseInteractionEvent {
+    interactionMode: 'drillThrough';
+    targetDashboardId: string;
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+}
+export interface DrillToDetailEvent extends BaseInteractionEvent {
+    interactionMode: 'drillToDetail';
+    detailFields: Field[];
+    sortBy?: SortByField[];
+    limit?: number;
+    detailTitle?: string;
+    targetInsightId?: string;
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    displayMode?: 'modal' | 'replace-card';
+}
+export interface ClickFilterEvent extends BaseInteractionEvent {
+    interactionMode: 'clickFilter';
+    applyToCardIds?: string[];
+    excludeCardIds?: string[];
+    /**
+     * Whether the source card should receive its own filter.
+     * When true, the source card will be filtered (not just blurred).
+     * Used when user selects from multiple interactions popup.
+     * @default false
+     */
+    filterSourceCard?: boolean;
+}
+export interface InlineDrillEvent extends BaseInteractionEvent {
+    interactionMode: 'inlineDrill';
+    fetchMode?: 'lazy' | 'preloaded';
+    inlineLimit?: number;
+}
+export interface InteractionState {
+    /**
+     * If user is in a drill hierarchy (static or dynamic), this tracks which one.
+     * Undefined if not currently in a drill path.
+     */
+    hierarchyId?: string;
+    /**
+     * Breadcrumb trail representing the user's drill path.
+     * Empty if no drill-down steps have occurred.
+     */
+    breadcrumbs: DrillBreadcrumb[];
+    /**
+     * All click filters applied from this card
+     */
+    appliedClickFilters?: ClickFilterEvent[];
+    /**
+     * (Optional) Track last one-off interaction (e.g., drillToDetail, drillToURL).
+     * Useful for things like modals or redirection handling.
+     */
+    lastInteractionEvent?: InteractionEvent;
+    /**
+     * Context mode for drill-to-insight filtering.
+     * Controls whether dashboard filters are applied alongside interaction filters.
+     *
+     * - 'interactionFilters': Only filters from the interaction event (no dashboard filters)
+     * - 'full': Dashboard filters + interaction filters
+     * - 'none': No filters applied
+     *
+     * Undefined for regular cards (not insights).
+     */
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    /**
+     * Source dashboard ID for drill-through navigation.
+     * Used for "Back" button navigation.
+     * Only set for global drill context (interactionStates['__DRILL_CONTEXT__']).
+     */
+    sourceDashboardId?: string;
+    /**
+     * Source dashboard title for drill-through navigation.
+     * Used for "Back to [X]" UI display.
+     * Only set for global drill context (interactionStates['__DRILL_CONTEXT__']).
+     */
+    sourceDashboardTitle?: string;
+    /**
+     * Target dashboard ID for drill-through navigation.
+     * Filters only apply when current dashboard matches this ID.
+     * Prevents filters from applying to source dashboard during navigation.
+     * Only set for global drill context (interactionStates['__DRILL_CONTEXT__']).
+     */
+    targetDashboardId?: string;
+}
+/**
+ * Unified Interaction type (V2)
+ * Combines all interaction types into a single union for the new interactions array.
+ */
+export type Interaction = ClickFilterInteraction | DrillDownInteraction | DrillThroughInteraction | DrillToDetailInteraction | DrillToURLInteraction | InlineDrillInteraction | DrillUpInteraction | DynamicDrillInteraction;
+export type PersistedInteraction = Interaction & {
+    id?: string;
+};
+export interface CardInteractionConfig {
+    /**
+     * V2: Unified interactions array.
+     * Each interaction includes a trigger that specifies what element must be clicked.
+     */
+    interactions?: PersistedInteraction[];
+    allowedDrillTargets?: Field[];
+    drillHierarchies?: DrillHierarchy[];
+}
+export interface DrillBreadcrumb {
+    /**
+     * The user clicked one or more segments. Each group of filters represents
+     * a single segment (i.e., a single click interaction).
+     *
+     * - Filters within a group are AND-ed (e.g., state = 'NY' AND ship_mode = 'Standard').
+     * - Across groups, they are OR-ed (e.g., ... OR state = 'CA' AND ship_mode = 'First Class').
+     */
+    sourceFilterGroups: ClickFilterConditionGroup[];
+    /**
+     * The next (group by) field the user is drilling into (e.g., 'city' after 'state').
+     */
+    toField?: Field;
+    /**
+     * Optional: If the drill target is a time field, this describes the granularity (e.g., month, year).
+     */
+    granularity?: TimeGranularity;
+    /**
+     * Optional: Indicates whether the drill is for time comparison (e.g., YoY).
+     */
+    timeComparison?: TimeComparison;
+    /**
+     * Optional: The metric the user clicked (e.g., '123 Orders'), used for display only.
+     */
+    metric?: ClickedMetricValue;
+}
+export interface DrillState {
+    /**
+     * Which hierarchy (e.g. 'geo', 'product') is currently active
+     * Omitted for single-step interactions (like drill-through)
+     */
+    hierarchyId?: string;
+    /**
+     * Steps taken in a drill-down path
+     */
+    breadcrumbs: DrillBreadcrumb[];
+}
+export interface DrillStore {
+    /**
+     * Per-card drill state
+     */
+    drillStates: Record<string, DrillState>;
+    /**
+     * Update current drill state for a given card
+     */
+    setDrillState: (cardId: string, state: DrillState) => void;
+    /**
+     * Reset drill state for a given card (e.g. user clicks "reset")
+     */
+    resetDrillState: (cardId: string) => void;
+    /**
+     * Push a new breadcrumb (i.e. drill forward one step)
+     */
+    addDrillStep: (cardId: string, step: DrillBreadcrumb) => void;
+    /**
+     * Go back one step (breadcrumb pop)
+     */
+    popDrillStep: (cardId: string) => void;
+}

package/dist/types/lib/types/query-types.d.ts

@@ -0,0 +1,81 @@
+import { AggregateFunction, JoinPlan } from './explorer-types.js';
+import { MetricComparisonMetadataEntry, MetricComparisonMetadataMap, SemaphorTimeGrain } from '../../shared/analytics-protocol/index.js';
+export type ColumnType = 'string' | 'number' | 'date';
+export type ColumnRole = 'groupby' | 'trendby' | 'metric' | 'filter';
+interface BaseColumn {
+    id: string;
+    name: string;
+    label?: string;
+    type: ColumnType;
+    table?: string;
+}
+interface GroupByColumn extends BaseColumn {
+    role: 'groupby';
+    granularity?: Granularity;
+    format?: string;
+}
+export type Granularity = SemaphorTimeGrain;
+interface MetricColumn extends BaseColumn {
+    role: 'metric';
+    aggregate: AggregateFunction;
+    aliasTemplate?: string;
+}
+interface FilterByColumn extends BaseColumn {
+    role: 'filter';
+    operators?: string[];
+    mode?: 'include' | 'exclude';
+    sql?: string;
+    fetchValues?: boolean;
+    fetchLimit?: number;
+    valueSource?: 'distinct' | 'static' | 'range';
+    staticValues?: string[];
+}
+type QueryColumn = GroupByColumn | MetricColumn | FilterByColumn;
+export type RangeValue = {
+    gte?: string | number;
+    lte?: string | number;
+    lt?: string | number;
+    gt?: string | number;
+};
+type OldFilterValue = string | number | null | (string | number)[] | RangeValue;
+export interface OrderBy {
+    columnId: string;
+    direction: 'asc' | 'desc';
+}
+export type QueryFilter = {
+    filterColumnName: string;
+    filterValue: OldFilterValue;
+};
+interface QueryConfig {
+    groupByColumns?: GroupByColumn[];
+    pivotColumns?: GroupByColumn[];
+    metricColumns?: MetricColumn[];
+    filterColumns?: FilterByColumn[];
+    filters?: QueryFilter[];
+    limit?: number;
+    orderBy?: OrderBy[];
+}
+export type TableConfig = {
+    databaseName: string;
+    schemaName: string;
+    tableName: string;
+    datamodelId: string;
+};
+/**
+ * Metadata for auto-resolved joins returned by the backend
+ *
+ * When the backend auto-resolves joins using semantic relationships,
+ * it returns this metadata alongside the query results.
+ */
+export interface AutoJoinMetadata {
+    /** The complete join plan that was auto-resolved */
+    resolvedJoinPlan: JoinPlan;
+    /** Flag indicating the joins were auto-resolved (vs manually configured) */
+    autoResolved: boolean;
+    /** Names of the semantic relationships that were used */
+    relationshipsUsed: string[];
+}
+export type ComparisonMetadataEntry = MetricComparisonMetadataEntry;
+/** Keyed by MetricComparisonOutput.outputId, never by a display label. */
+export type ComparisonMetadataMap = MetricComparisonMetadataMap;
+export type { QueryConfig, QueryColumn, GroupByColumn, MetricColumn, FilterByColumn, OldFilterValue, BaseColumn, };

package/dist/types/lib/types/semantic-runtime-types.d.ts

@@ -0,0 +1,14 @@
+import { ResolvedPrimaryDateField } from '../../shared/analytics-protocol/contracts.js';
+export type { ResolvedPrimaryDateField } from '../../shared/analytics-protocol/contracts.js';
+export type ResolvedPrimaryDateFieldError = {
+    code: string;
+    fieldName: string;
+    message: string;
+};
+export type SemanticExecutionPayload = {
+    domainsById: Record<string, {
+        datasetsByName: Record<string, {
+            primaryDateField: ResolvedPrimaryDateField;
+        }>;
+    }>;
+};