semaphor 0.0.102 → 0.0.104

package/dist/types/surfboard.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;
@@ -210,7 +272,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];
 
@@ -224,6 +286,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 = {
@@ -386,12 +492,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;
@@ -491,7 +606,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;
@@ -628,6 +743,7 @@ export declare type TBaseQuery = {
 };
 
 export declare type TCard = {
+    mode?: CardMode;
     id: string;
     title: string;
     tabTitle?: string;
@@ -641,6 +757,7 @@ export declare type TCard = {
     python?: string;
     dataSource?: DataSource;
     config?: CardConfig;
+    interactionConfig?: CardInteractionConfig;
     queryConfig?: QueryConfig;
     customCfg?: any;
     preferences?: TCardPreferences;
@@ -695,6 +812,7 @@ export declare type TCardPreferences = {
     };
     kpiVisualOptions?: {
         lowerIsBetter?: boolean;
+        countryLogoId?: string;
     };
 };
 
@@ -838,6 +956,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/types.d.ts

@@ -61,8 +61,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;
@@ -81,6 +116,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;
@@ -204,7 +266,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];
 
@@ -218,6 +280,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 = {
@@ -380,12 +486,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;
@@ -485,7 +600,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;
@@ -620,6 +735,7 @@ export declare type TBaseQuery = {
 };
 
 export declare type TCard = {
+    mode?: CardMode;
     id: string;
     title: string;
     tabTitle?: string;
@@ -633,6 +749,7 @@ export declare type TCard = {
     python?: string;
     dataSource?: DataSource;
     config?: CardConfig;
+    interactionConfig?: CardInteractionConfig;
     queryConfig?: QueryConfig;
     customCfg?: any;
     preferences?: TCardPreferences;
@@ -687,6 +804,7 @@ export declare type TCardPreferences = {
     };
     kpiVisualOptions?: {
         lowerIsBetter?: boolean;
+        countryLogoId?: string;
     };
 };
 
@@ -830,6 +948,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/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.0.102",
+  "version": "0.0.104",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -57,6 +57,7 @@
     "@radix-ui/react-alert-dialog": "^1.1.4",
     "@radix-ui/react-checkbox": "^1.1.3",
     "@radix-ui/react-collapsible": "^1.1.2",
+    "@radix-ui/react-context-menu": "^2.2.15",
     "@radix-ui/react-dialog": "^1.1.14",
     "@radix-ui/react-dropdown-menu": "^2.1.4",
     "@radix-ui/react-hover-card": "^1.1.4",