semaphor 0.0.102 → 0.0.104

package/dist/types/dashboard.d.ts

@@ -62,8 +62,43 @@ declare interface CardConfig {
     filters?: FilterGroup;
     joinPlan?: JoinPlan;
     rowLimit?: number;
+    /**
+     * One or more hierarchies that define drillable paths through dimensions.
+     */
+    drillHierarchies?: DrillHierarchy[];
+    /**
+     * Optional list of dimensions allowed for dynamic drill-down across this card.
+     * Used only when drill steps contain `mode: 'dynamicDrill'` or `type: 'dynamic'`.
+     */
+    allowedDrillTargets?: Field[];
+    /**
+     * NOT UOptional preload settings for inline drill previews
+     */
+    inlineDrillPreview?: {
+        enabled: boolean;
+        limit: number;
+        mode: 'lazy' | 'preloaded';
+    };
+    /**
+     * Configuration for on-click dashboard filters triggered by this card.
+     */
+    clickFilterInteractions?: ClickFilterInteraction[];
+    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target';
+    targetValue?: number;
+    showTrendline?: boolean;
+    trendlineWindow?: number;
+    trendlineGranularity?: 'day' | 'week' | 'month';
+}
+
+declare interface CardInteractionConfig {
+    allowedDrillTargets?: Field[];
+    drillHierarchies?: DrillHierarchy[];
+    drillInteractions?: DrillInteraction[];
+    clickFilterInteractions?: ClickFilterInteraction[];
 }
 
+declare type CardMode = 'explorer' | 'dev';
+
 declare type CardWithContent = BaseCustomCard & {
     content: React.FC<{
         card: TCard;
@@ -82,6 +117,33 @@ declare type CardWithFooter = BaseCustomCard & {
     }>;
 };
 
+declare interface ClickFilterInteraction {
+    mode: 'clickFilter';
+    /**
+     * 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 declare type ColorRange = {
     start: number;
     end: number;
@@ -207,7 +269,7 @@ declare interface DataSource {
     selectedEntities: SelectedEntities;
 }
 
-declare const DATE_FORMAT_VALUES: readonly ["YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM", "MMMM YYYY", "custom"];
+declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM", "MMMM YYYY", "custom"];
 
 declare type DateFormatValue = (typeof DATE_FORMAT_VALUES)[number];
 
@@ -221,6 +283,50 @@ declare type Dialect = 'mysql' | 'postgresql' | 'bigquery' | 'redshift' | 'snowf
 
 export declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
 
+declare interface DrillHierarchy {
+    id: string;
+    label?: string;
+    type: 'static';
+    steps: DrillHierarchyStep[];
+    default?: boolean;
+}
+
+declare interface DrillHierarchyStep {
+    field: Field;
+    mode: 'drillDown';
+    preferredChartType?: TChartType;
+    breadcrumbLabelTemplate?: string;
+    retainFilters?: boolean;
+    label?: string;
+    linkedInsightId?: string;
+}
+
+declare type DrillInteraction = DrillThroughInteraction | DrillToDetailInteraction | DrillToURLInteraction | InlineDrillInteraction;
+
+declare interface DrillThroughInteraction {
+    mode: 'drillThrough';
+    filterFields: Field[];
+    targetSheetId: string;
+    label?: string;
+}
+
+declare interface DrillToDetailInteraction {
+    mode: 'drillToDetail';
+    filterFields: Field[];
+    detailFields?: Field[];
+    sortBy?: SortByField[];
+    limit?: number;
+    detailTitle?: string;
+    label?: string;
+}
+
+declare interface DrillToURLInteraction {
+    mode: 'drillToURL';
+    filterFields: Field[];
+    urlTemplate: string;
+    label?: string;
+}
+
 export declare type DroppableId = 'droppable-group-by' | 'droppable-metric';
 
 export declare type EmailSettings = {
@@ -383,12 +489,21 @@ declare interface GroupByField extends Field {
      * If present, used in SELECT and GROUP BY instead of just the column name.
      */
     expression?: string;
+    timeDrillPath?: TimeDrillStep[];
 }
 
 export declare type HtmlOptions = {
     html: string;
 };
 
+declare interface InlineDrillInteraction {
+    mode: 'inlineDrill';
+    filterFields: Field[];
+    fetchMode?: 'lazy' | 'preloaded';
+    inlineLimit?: number;
+    label?: string;
+}
+
 declare interface Join {
     id: string;
     source: DatabaseEntityReference;
@@ -488,7 +603,7 @@ declare type OldFilterValue = string | number | null | (string | number)[] | Ran
 
 declare type Operation = '=' | '>' | '<' | '>=' | '<=' | '!=' | 'in' | 'not in' | 'like' | 'not like' | 'between' | 'not between' | 'is null' | 'is not null';
 
-declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'in' | 'not in';
+declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'in' | 'not in' | 'between';
 
 declare type OptionsMap = {
     number: NumberOptions;
@@ -623,6 +738,7 @@ export declare type TBaseQuery = {
 };
 
 export declare type TCard = {
+    mode?: CardMode;
     id: string;
     title: string;
     tabTitle?: string;
@@ -636,6 +752,7 @@ export declare type TCard = {
     python?: string;
     dataSource?: DataSource;
     config?: CardConfig;
+    interactionConfig?: CardInteractionConfig;
     queryConfig?: QueryConfig;
     customCfg?: any;
     preferences?: TCardPreferences;
@@ -690,6 +807,7 @@ export declare type TCardPreferences = {
     };
     kpiVisualOptions?: {
         lowerIsBetter?: boolean;
+        countryLogoId?: string;
     };
 };
 
@@ -833,6 +951,13 @@ export declare type TFrame = {
 
 export declare type Theme = 'dark' | 'light' | 'system';
 
+declare interface TimeDrillStep {
+    granularity: TimeGranularity;
+    next?: TimeGranularity;
+    comparison?: 'previous_year' | 'previous_period';
+    rollingWindow?: number;
+}
+
 declare type TimeGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
 
 export declare type TLegendOptions = {

package/dist/types/main.d.ts

@@ -11,7 +11,10 @@ import { Dialect as Dialect_2 } from '../types/explorer-types';
 import { DropdownItem as DropdownItem_2 } from '../types/dropdown-types';
 import { EmailSettings as EmailSettings_2 } from '..';
 import { FontSpec } from 'chart.js';
+import { GroupByField as GroupByField_2 } from '../types/explorer-types';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { MetricField as MetricField_2 } from '../types/explorer-types';
+import { PivotByField as PivotByField_2 } from '../types/explorer-types';
 import { QueryObserverResult } from '@tanstack/query-core';
 import { RefetchOptions } from '@tanstack/query-core';
 import { StoreApi } from 'zustand';
@@ -67,6 +70,7 @@ declare type Actions = {
     updateFrame: (sheetId: string, frame: TFrame) => void;
     updateCard: (sheetId: string, card: TCard) => void;
     updateFrameCard?: (sheetId: string, frameId: string, card: TCard) => void;
+    updateCurrentDashboardCard: (card: TCard) => void;
     removeFrame: (sheetId: string, frameId: string) => void;
     removeCard: (sheetId: string, card: TCard) => void;
     setIsDashboardEditing: (editing: boolean) => void;
@@ -105,7 +109,8 @@ declare type Actions = {
     setBaseQueries: (baseQueries: TBaseQuery[]) => void;
 };
 
-declare type Actions_2 = TableActions & ExplorerActions & {
+declare type Actions_2 = TableActions & ExplorerActions & DrillActions & {
+    setCardMode: (mode: CardMode) => void;
     setEditorFilterMode: (filterColumnName: string, filterMode: 'include' | 'exclude') => void;
     setLowerIsBetter: (lowerIsBetter: boolean) => void;
     clearEditorFilter: (filterColumn: FilterByColumn) => void;
@@ -117,6 +122,9 @@ declare type Actions_2 = TableActions & ExplorerActions & {
     }) => void;
     clearQueryConfig: () => void;
     setQueryConfig: (queryConfig: QueryConfig | undefined) => void;
+    setCardTitle: (title: string) => void;
+    setCardDescription: (description: string) => void;
+    setCountryLogo: (countryLogoId: string | null) => void;
     setIsDevMode: (isDevMode: boolean) => void;
     setOrderByColumns: (orderByColumns: OrderBy[]) => void;
     addOrderByColumn: (orderByColumn: OrderBy) => void;
@@ -250,8 +258,43 @@ export declare interface CardConfig {
     filters?: FilterGroup;
     joinPlan?: JoinPlan;
     rowLimit?: number;
+    /**
+     * One or more hierarchies that define drillable paths through dimensions.
+     */
+    drillHierarchies?: DrillHierarchy[];
+    /**
+     * Optional list of dimensions allowed for dynamic drill-down across this card.
+     * Used only when drill steps contain `mode: 'dynamicDrill'` or `type: 'dynamic'`.
+     */
+    allowedDrillTargets?: Field[];
+    /**
+     * NOT UOptional preload settings for inline drill previews
+     */
+    inlineDrillPreview?: {
+        enabled: boolean;
+        limit: number;
+        mode: 'lazy' | 'preloaded';
+    };
+    /**
+     * Configuration for on-click dashboard filters triggered by this card.
+     */
+    clickFilterInteractions?: ClickFilterInteraction[];
+    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target';
+    targetValue?: number;
+    showTrendline?: boolean;
+    trendlineWindow?: number;
+    trendlineGranularity?: 'day' | 'week' | 'month';
+}
+
+declare interface CardInteractionConfig {
+    allowedDrillTargets?: Field[];
+    drillHierarchies?: DrillHierarchy[];
+    drillInteractions?: DrillInteraction[];
+    clickFilterInteractions?: ClickFilterInteraction[];
 }
 
+export declare type CardMode = 'explorer' | 'dev';
+
 declare type CardWithContent = BaseCustomCard & {
     content: React.FC<{
         card: TCard;
@@ -272,6 +315,33 @@ declare type CardWithFooter = BaseCustomCard & {
 
 export declare function cleanCard(card: TCard): TCard;
 
+declare interface ClickFilterInteraction {
+    mode: 'clickFilter';
+    /**
+     * 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 declare type ColorRange = {
     start: number;
     end: number;
@@ -463,7 +533,7 @@ export declare interface DataSource {
 
 export declare type DataType = 'string' | 'number' | 'date' | 'datetime' | 'boolean' | 'json' | 'geo';
 
-export declare const DATE_FORMAT_VALUES: readonly ["YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM", "MMMM YYYY", "custom"];
+export declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM", "MMMM YYYY", "custom"];
 
 export declare type DateFormatOption = {
     value: DateFormatValue;
@@ -486,6 +556,75 @@ export declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'n
 
 export declare function downloadPdf(): Promise<void>;
 
+declare interface DrillActions {
+    updateDrillHierarchies: (h: DrillHierarchy[]) => void;
+    addDrillHierarchy: (h: DrillHierarchy) => void;
+    removeDrillHierarchy: (hierarchyId: string) => void;
+    updateDrillHierarchy: (hierarchyId: string, updates: Partial<DrillHierarchy>) => void;
+    setDefaultHierarchy: (hierarchyId: string) => void;
+    updateAllowedDrillTargets: (t: Field[]) => void;
+    addDrillTarget: (t: Field) => void;
+    removeDrillTarget: (targetId: string) => void;
+    updateDrillInteractions: (i: DrillInteraction[]) => void;
+    addDrillInteraction: (i: DrillInteraction) => void;
+    removeDrillInteraction: (index: number) => void;
+    updateClickFilterInteractions: (i: ClickFilterInteraction[]) => void;
+    addClickFilterInteraction: (i: ClickFilterInteraction) => void;
+    removeClickFilterInteraction: (fieldId: string) => void;
+    updateInlineDrillPreview: (s: {
+        enabled: boolean;
+        limit: number;
+        mode: 'lazy' | 'preloaded';
+    }) => void;
+    toggleInlineDrillPreview: (enabled: boolean) => void;
+    updateInteractionConfig: (c: Partial<CardInteractionConfig>) => void;
+    resetDrillConfiguration: () => void;
+}
+
+declare interface DrillHierarchy {
+    id: string;
+    label?: string;
+    type: 'static';
+    steps: DrillHierarchyStep[];
+    default?: boolean;
+}
+
+declare interface DrillHierarchyStep {
+    field: Field;
+    mode: 'drillDown';
+    preferredChartType?: TChartType;
+    breadcrumbLabelTemplate?: string;
+    retainFilters?: boolean;
+    label?: string;
+    linkedInsightId?: string;
+}
+
+declare type DrillInteraction = DrillThroughInteraction | DrillToDetailInteraction | DrillToURLInteraction | InlineDrillInteraction;
+
+declare interface DrillThroughInteraction {
+    mode: 'drillThrough';
+    filterFields: Field[];
+    targetSheetId: string;
+    label?: string;
+}
+
+declare interface DrillToDetailInteraction {
+    mode: 'drillToDetail';
+    filterFields: Field[];
+    detailFields?: Field[];
+    sortBy?: SortByField[];
+    limit?: number;
+    detailTitle?: string;
+    label?: string;
+}
+
+declare interface DrillToURLInteraction {
+    mode: 'drillToURL';
+    filterFields: Field[];
+    urlTemplate: string;
+    label?: string;
+}
+
 export declare type DropdownItem = {
     id: string;
     name: string;
@@ -796,12 +935,21 @@ export declare interface GroupByField extends Field {
      * If present, used in SELECT and GROUP BY instead of just the column name.
      */
     expression?: string;
+    timeDrillPath?: TimeDrillStep[];
 }
 
 export declare type HtmlOptions = {
     html: string;
 };
 
+declare interface InlineDrillInteraction {
+    mode: 'inlineDrill';
+    filterFields: Field[];
+    fetchMode?: 'lazy' | 'preloaded';
+    inlineLimit?: number;
+    label?: string;
+}
+
 export declare function invalidateToken(): Promise<any>;
 
 export declare function isBooleanDataType(dataType: string): boolean;
@@ -915,7 +1063,7 @@ export declare type OldFilterValue = string | number | null | (string | number)[
 
 declare type Operation = '=' | '>' | '<' | '>=' | '<=' | '!=' | 'in' | 'not in' | 'like' | 'not like' | 'between' | 'not between' | 'is null' | 'is not null';
 
-export declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'in' | 'not in';
+export declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'in' | 'not in' | 'between';
 
 declare type OptionsMap = {
     number: NumberOptions;
@@ -1113,6 +1261,7 @@ export declare type TBaseQuery = {
 };
 
 export declare type TCard = {
+    mode?: CardMode;
     id: string;
     title: string;
     tabTitle?: string;
@@ -1126,6 +1275,7 @@ export declare type TCard = {
     python?: string;
     dataSource?: DataSource;
     config?: CardConfig;
+    interactionConfig?: CardInteractionConfig;
     queryConfig?: QueryConfig;
     customCfg?: any;
     preferences?: TCardPreferences;
@@ -1180,6 +1330,7 @@ export declare type TCardPreferences = {
     };
     kpiVisualOptions?: {
         lowerIsBetter?: boolean;
+        countryLogoId?: string;
     };
 };
 
@@ -1325,6 +1476,13 @@ export declare type TFrame = {
 
 export declare type Theme = 'dark' | 'light' | 'system';
 
+declare interface TimeDrillStep {
+    granularity: TimeGranularity;
+    next?: TimeGranularity;
+    comparison?: 'previous_year' | 'previous_period';
+    rollingWindow?: number;
+}
+
 export declare type TimeGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
 
 export declare type TLegendOptions = {
@@ -1342,6 +1500,101 @@ export declare type TLens = {
     shared?: boolean;
 };
 
+/**
+ * Parameters for customizing token behavior and formatting.
+ */
+export declare type TokenParams = {
+    currencyFormat: {
+        /**
+         * Locale identifier (e.g., 'en-US', 'fr-FR').
+         */
+        locale: string;
+        /**
+         * Currency code compliant with ISO 4217 (e.g., 'USD', 'EUR').
+         */
+        currency: string;
+    };
+};
+
+/**
+ * Main payload for generating a secure access token for a dashboard.
+ */
+export declare type TokenRequest = {
+    /**
+     * Identifier of the dashboard to be accessed.
+     */
+    dashboardId: string;
+    /**
+     * Secret key used for validating access to the dashboard.
+     */
+    dashboardSecret: string;
+    /**
+     * Token expiry duration in seconds.
+     */
+    tokenExpiry?: number;
+    /**
+     * Unique identifier of the tenant.
+     */
+    tenantId?: string;
+    /**
+     * Unique identifier of the end user accessing the dashboard.
+     */
+    endUserId?: string;
+    /**
+     * Email of the end user (for personalization, audit, or identification).
+     */
+    endUserEmail?: string;
+    /**
+     * Enables self-service editing and lens creation by the end user.
+     */
+    allowEdit?: boolean;
+    /**
+     * Connection-level security policies.
+     * Can be a single policy or an array of policies.
+     */
+    cls?: TokenSecurityPolicy[] | TokenSecurityPolicy;
+    /**
+     * Row-level security policies.
+     * Can be a single policy or an array of policies.
+     */
+    rcls?: TokenSecurityPolicy[] | TokenSecurityPolicy;
+    /**
+     * Parameter overrides and preferences (e.g., formatting).
+     */
+    params?: TokenParams;
+    /**
+     * UI behavior and feature flags.
+     */
+    config?: UIConfig;
+};
+
+/**
+ * Defines a security policy that can be applied at connection or row level.
+ */
+export declare type TokenSecurityPolicy = {
+    /**
+     * Name of the policy (e.g., 'store_sales_primary', 'region_filter').
+     */
+    name: string;
+    /**
+     * Arbitrary parameters associated with the policy.
+     * Examples:
+     *
+     * // Single value
+     * {
+     *   tenant: 'tenant_abc_123'
+     * }
+     *
+     * // Multiple values
+     * {
+     *   state: ['California', 'Nevada', 'Washington']
+     * }
+     */
+    params: {
+        [key: string]: string | number | string[] | number[];
+    };
+};
+
 export declare type TSelectedRecord = ComboBoxOption;
 
 export declare type TSheet = {
@@ -1362,6 +1615,26 @@ export declare type TStyle = {
     dark?: StyleProps;
 };
 
+/**
+ * UI and behavior configuration for the embedded dashboard.
+ */
+export declare type UIConfig = {
+    /**
+     * Enables self-service editing and lens creation by the end user. Legacy field. Use config.allowEdit instead.
+     */
+    allowEdit?: boolean;
+    /**
+     * Enables advanced mode features in the dashboard.
+     * Defaults to true unless explicitly disabled.
+     */
+    showAdvancedMode?: boolean;
+    /**
+     * Enables the AI-powered dashboard assistant.
+     * Defaults to true unless explicitly disabled.
+     */
+    showDashboardAssistant?: boolean;
+};
+
 export declare function useCard(cardId: string): {
     data: any;
     card: TCard;
@@ -1375,6 +1648,16 @@ export declare function useCard(cardId: string): {
     queryKey: string[];
 };
 
+export declare const useCurrentActiveCard: () => TCard | undefined;
+
+export declare const useCurrentCardConfig: () => {
+    metricFields: MetricField_2[];
+    groupByFields: GroupByField_2[];
+    pivotByFields: PivotByField_2[];
+};
+
+export declare const useCurrentSheetActiveCards: () => TCard[];
+
 export declare const useDashboardActions: () => Actions;
 
 export declare const useDashboardStore: UseBoundStore<Omit<StoreApi<DashboardStore>, "setState"> & {