react-semaphor 0.1.259 → 0.1.261

package/dist/types/surfboard.d.ts

@@ -316,6 +316,78 @@ export declare type ConnectionPolicy = {
 
 declare type ConnectionType = 'GoogleSheets' | 'FileUpload' | 'MySQL' | 'MSSQL' | 'PostgreSQL' | 'BigQuery' | 'Redshift' | 'Snowflake' | 'S3' | 'clickhouse' | 'S3Tables' | 'API' | 'none';
 
+export declare const CONTROL_CARD_DEFAULT_VALUE: "__card_default__";
+
+export declare type ControlBinding = {
+    controlId: string;
+    target: 'sql_param';
+    paramId: string;
+} | {
+    controlId: string;
+    target: 'config_metric_selector';
+    mapping: Record<string, StructuralMetricSelectorTarget>;
+} | {
+    controlId: string;
+    target: 'config_field_selector';
+    mapping: Record<string, StructuralFieldSelectorTarget>;
+} | {
+    controlId: string;
+    target: 'config_aggregation';
+    mapping: Record<string, string>;
+} | {
+    controlId: string;
+    target: 'config_grain';
+    mapping: Record<string, string>;
+};
+
+export declare type ControlDefinition = {
+    id: string;
+    label: string;
+    scope: ControlScope;
+    type: ControlType;
+    source: ControlSource;
+    initialValueStrategy: ControlInitialValueStrategy;
+    defaultValue?: unknown;
+    requiredAtExecution: boolean;
+    hidden?: boolean;
+    locked?: boolean;
+    helpText?: string;
+    placement?: 'toolbar' | 'card_header' | 'advanced';
+    showLabel?: boolean;
+    toolbarWidth?: number;
+};
+
+export declare type ControlInitialValueStrategy = 'saved_default' | 'builtin' | 'embed_required' | 'schedule_snapshot';
+
+export declare type ControlOption = {
+    value: string;
+    label: string;
+    presentation?: {
+        granularity?: TimeGranularity;
+        dateFormat?: DateFormatValue;
+        customFormat?: string;
+    };
+};
+
+export declare type ControlScope = 'dashboard' | 'card';
+
+export declare type ControlSource = {
+    kind: 'manual';
+    options: ControlOption[];
+} | {
+    kind: 'dataset_values';
+    fieldId: string;
+    connectionId?: string;
+} | {
+    kind: 'field_allowlist';
+    fieldIds: string[];
+} | {
+    kind: 'metric_allowlist';
+    metricIds: string[];
+};
+
+export declare type ControlType = 'enum' | 'multi_enum' | 'text' | 'number' | 'boolean' | 'date' | 'field_selector' | 'metric_selector' | 'aggregation_selector' | 'grain_selector';
+
 export declare type CustomCard = CardWithContent | CardWithFooter;
 
 declare type DashboardAIContext = AIContext & {
@@ -370,6 +442,20 @@ export declare type DashboardProps = {
      * Default filter values for the dashboard. The dashboard will be filtered by these values when the user loads the dashboard.
      */
     defaultFilterValues?: TFilterValue[];
+    /**
+     * Default runtime control values for the dashboard. Used by print/render flows
+     * and other external entry points that need deterministic control state.
+     */
+    defaultControlValues?: Record<string, unknown>;
+    /**
+     * Optional control contract override used by print/replay entry points that
+     * need to execute against a saved card/dashboard control contract snapshot.
+     */
+    controlContractOverrides?: {
+        controlDefinitions?: ControlDefinition[];
+        cardControlDefinitions?: ControlDefinition[];
+        controlBindings?: ControlBinding[];
+    };
     customStyle?: TStyle;
     currentTheme?: Theme;
     version?: string;
@@ -819,6 +905,11 @@ export declare type FilterLayoutSettings = {
      * Useful when embedding Dashboard component without Surfboard's controls
      */
     showDownloadButton?: boolean;
+    /**
+     * Mixed toolbar item order for dashboard-level filter and control chips.
+     * Values use prefixed ids like `filter:<id>` and `control:<id>`.
+     */
+    toolbarItemOrder?: string[];
 };
 
 declare type FilterLocation = 'dashboard' | 'frame' | 'sheet' | undefined;
@@ -1225,6 +1316,10 @@ declare type StringOptions = {
     maxLength?: number;
 };
 
+export declare type StructuralFieldSelectorTarget = GroupByField;
+
+export declare type StructuralMetricSelectorTarget = MetricField;
+
 /**
  * Style propeerites for the dashboard
  */
@@ -1450,6 +1545,14 @@ export declare type TCard = {
      * Configured by editors via the visual editor settings.
      */
     inlineFilters?: TInlineFilter[];
+    /**
+     * Card-scoped control definitions for this card.
+     */
+    controls?: ControlDefinition[];
+    /**
+     * Per-card bindings that connect dashboard or card controls to this card's runtime targets.
+     */
+    controlBindings?: ControlBinding[];
 };
 
 export declare type TCardContext = {
@@ -1666,6 +1769,8 @@ export declare type TDashboard = {
     globalCacheConfig?: CacheConfig;
     emailSettings?: EmailSettings;
     defaultFilterValues?: TFilterValue[];
+    controls?: ControlDefinition[];
+    defaultControlValues?: Record<string, unknown>;
     filterLayout?: FilterLayoutSettings;
 };
 

package/dist/types/types.d.ts

@@ -72,6 +72,10 @@ export declare interface AlertDeliverablePreview {
 
 export declare type AlertDeliveryChannel = 'EMAIL' | 'WEBHOOK' | 'SLACK' | 'IN_APP' | 'TELEGRAM';
 
+export declare type AlertExecutionControlContext = {
+    values: Record<string, unknown>;
+};
+
 export declare type AlertExecutionFilterContext = {
     active_filters: TFilterValue[];
 };
@@ -182,6 +186,10 @@ export declare type AlertSource = {
     executionSnapshot: {
         queryConfig: AlertExecutionQueryConfig;
         filterContext: AlertExecutionFilterContext;
+        controlContext?: AlertExecutionControlContext;
+        controlDefinitions?: ControlDefinition[];
+        cardControlDefinitions?: ControlDefinition[];
+        controlBindings?: ControlBinding[];
         connectionId: string;
         calendarContext?: {
             tz: string;
@@ -545,6 +553,78 @@ export declare type ContextSource = {
     outputAs?: string;
 };
 
+export declare const CONTROL_CARD_DEFAULT_VALUE: "__card_default__";
+
+export declare type ControlBinding = {
+    controlId: string;
+    target: 'sql_param';
+    paramId: string;
+} | {
+    controlId: string;
+    target: 'config_metric_selector';
+    mapping: Record<string, StructuralMetricSelectorTarget>;
+} | {
+    controlId: string;
+    target: 'config_field_selector';
+    mapping: Record<string, StructuralFieldSelectorTarget>;
+} | {
+    controlId: string;
+    target: 'config_aggregation';
+    mapping: Record<string, string>;
+} | {
+    controlId: string;
+    target: 'config_grain';
+    mapping: Record<string, string>;
+};
+
+export declare type ControlDefinition = {
+    id: string;
+    label: string;
+    scope: ControlScope;
+    type: ControlType;
+    source: ControlSource;
+    initialValueStrategy: ControlInitialValueStrategy;
+    defaultValue?: unknown;
+    requiredAtExecution: boolean;
+    hidden?: boolean;
+    locked?: boolean;
+    helpText?: string;
+    placement?: 'toolbar' | 'card_header' | 'advanced';
+    showLabel?: boolean;
+    toolbarWidth?: number;
+};
+
+export declare type ControlInitialValueStrategy = 'saved_default' | 'builtin' | 'embed_required' | 'schedule_snapshot';
+
+export declare type ControlOption = {
+    value: string;
+    label: string;
+    presentation?: {
+        granularity?: TimeGranularity;
+        dateFormat?: DateFormatValue;
+        customFormat?: string;
+    };
+};
+
+export declare type ControlScope = 'dashboard' | 'card';
+
+export declare type ControlSource = {
+    kind: 'manual';
+    options: ControlOption[];
+} | {
+    kind: 'dataset_values';
+    fieldId: string;
+    connectionId?: string;
+} | {
+    kind: 'field_allowlist';
+    fieldIds: string[];
+} | {
+    kind: 'metric_allowlist';
+    metricIds: string[];
+};
+
+export declare type ControlType = 'enum' | 'multi_enum' | 'text' | 'number' | 'boolean' | 'date' | 'field_selector' | 'metric_selector' | 'aggregation_selector' | 'grain_selector';
+
 export declare interface CreateAlertRequest {
     kind?: 'ALERT';
     name: string;
@@ -614,6 +694,20 @@ export declare type DashboardProps = {
      * Default filter values for the dashboard. The dashboard will be filtered by these values when the user loads the dashboard.
      */
     defaultFilterValues?: TFilterValue[];
+    /**
+     * Default runtime control values for the dashboard. Used by print/render flows
+     * and other external entry points that need deterministic control state.
+     */
+    defaultControlValues?: Record<string, unknown>;
+    /**
+     * Optional control contract override used by print/replay entry points that
+     * need to execute against a saved card/dashboard control contract snapshot.
+     */
+    controlContractOverrides?: {
+        controlDefinitions?: ControlDefinition[];
+        cardControlDefinitions?: ControlDefinition[];
+        controlBindings?: ControlBinding[];
+    };
     customStyle?: TStyle;
     currentTheme?: Theme;
     version?: string;
@@ -1080,6 +1174,11 @@ export declare type FilterLayoutSettings = {
      * Useful when embedding Dashboard component without Surfboard's controls
      */
     showDownloadButton?: boolean;
+    /**
+     * Mixed toolbar item order for dashboard-level filter and control chips.
+     * Values use prefixed ids like `filter:<id>` and `control:<id>`.
+     */
+    toolbarItemOrder?: string[];
 };
 
 declare type FilterLocation = 'dashboard' | 'frame' | 'sheet' | undefined;
@@ -1547,6 +1646,10 @@ declare type StringOptions = {
     maxLength?: number;
 };
 
+export declare type StructuralFieldSelectorTarget = GroupByField;
+
+export declare type StructuralMetricSelectorTarget = MetricField;
+
 /**
  * Style propeerites for the dashboard
  */
@@ -1770,6 +1873,14 @@ export declare type TCard = {
      * Configured by editors via the visual editor settings.
      */
     inlineFilters?: TInlineFilter[];
+    /**
+     * Card-scoped control definitions for this card.
+     */
+    controls?: ControlDefinition[];
+    /**
+     * Per-card bindings that connect dashboard or card controls to this card's runtime targets.
+     */
+    controlBindings?: ControlBinding[];
 };
 
 export declare type TCardContext = {
@@ -1986,6 +2097,8 @@ export declare type TDashboard = {
     globalCacheConfig?: CacheConfig;
     emailSettings?: EmailSettings;
     defaultFilterValues?: TFilterValue[];
+    controls?: ControlDefinition[];
+    defaultControlValues?: Record<string, unknown>;
     filterLayout?: FilterLayoutSettings;
 };
 

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.259",
+  "version": "0.1.261",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",