@mongodb-js/charts-embed-dom/dist/types/types.d.ts

JavaScript library for embedding MongoDB Charts

export declare enum THEME {
    DARK = "dark",
    LIGHT = "light"
}
export type Theme = `${THEME}`;
export declare enum SCALING {
    FIXED = "fixed",
    SCALE = "scale"
}
export type Scaling = `${SCALING}`;
export declare enum ENCODING {
    BASE64 = "base64",
    BINARY = "binary"
}
export type EncodingType = `${ENCODING}`;
export type PlainObject = Record<string, unknown>;
export type DashboardChartOption = {
    chartId: string;
    filter: PlainObject;
};
/**
 * Shared options for embedding
 */
export interface SharedEmbedOptions {
    /**
     * The background color to use for the embedded object.
     *
     * If no background is provided, it will set a default background color based on the theme.
     *
     * To control the background color using CSS and classes, set to `transparent`.
     **/
    background?: string;
    /**
     * The base url for your MongoDB {@link EmbedSDK} instance.
     *
     * This should look something like: `https://charts.mongodb.com/charts-example-url-zdvkh`
     */
    baseUrl: string;
    /**
     * The height of the embedded object.
     *
     * If no height is provided, it will default to stretching to the height of it's container. If a value is provided without units, it will be assumed to be pixels (px).
     */
    height?: string | number;
    /**
     * The width of the embedded object.
     *
     * If no width is provided, it will default to stretching to the width of it's container. If a value is provided without units, it will be assumed to be pixels (px).
     */
    width?: string | number;
    /**
     * Whether the embedded object should be automatically refreshed.
     */
    autoRefresh?: boolean;
    /**
     * How long in seconds data is considered fresh.
     *
     * By default, staleness tolerance is 1 hour.
     */
    maxDataAge?: number;
    /**
     * Whether to show the MongoDB attribution logo.
     *
     * By default, this is set to `true`
     */
    showAttribution?: boolean;
    /**
     * The color scheme to apply.
     *
     * If the theme is set to 'dark' and you have specified a custom background color, you should ensure that your background color has appropriate contrast.
     */
    theme?: Theme;
    /**
     * A function that returns a valid JWT that will be used to authenticate the user.
     *
     * This function will be called when the embedded object is first rendered, and then successively when the SDK needs to refresh an invalid token.
     *
     * See also {@link getRealmUserToken}
     */
    getUserToken?: () => string | Promise<string>;
    /**
     * The filter to apply to the embedded chart or dashboard.
     *
     * This expects an object that contains a valid [query operators](https://docs.mongodb.com/manual/reference/operator/query/#query-selectors).
     * Any fields referenced in this filter are expected to be allowed for filtering in the "Embed Chart" for each chart you wish to filter on or in the "Embed Dashboard" dialog if you are applying a filter on a dashboard.
     */
    filter?: PlainObject;
    /**
     * The filter to apply as the first stage on the Data Source.
     *
     * This expects an object that contains a valid [query operators](https://docs.mongodb.com/manual/reference/operator/query/#query-selectors).
     * Any fields referenced in this filter are expected to be allowed for filtering in the "Embed Chart" for each chart you wish to filter on or in the "Embed Dashboard" dialog if you are applying a filter on a dashboard.
     *
     * If filtering is required on a dynamic field defined via a Lookup, Calculated or Query Bar, then `filter` is appropriate property to set.
     */
    preFilter?: PlainObject;
}
/**
 * The set of options that you can use when both creating an {@link EmbedSDK} object or using {@link EmbedSDK.createChart}.
 */
export interface EmbedChartOptions extends SharedEmbedOptions {
    /**
     * The id for the chart you want to embed.
     *
     * This can be found in the "Embed Chart" dialog when viewing a chart on a dashboard.
     */
    chartId: string;
    /**
     * How frequently a chart should refresh once it has been embedded.
     *
     * The minimum refreshInterval is 10 seconds. By default, a chart will never refresh once rendered.
     *
     * @deprecated This option is deprecated. Please use the autoRefresh option with the maxDataAge option to configure how often the chart refreshes.
     */
    refreshInterval?: number;
    /**
     * Customisation settings to apply to an embedded chart.
     * This should contain the version of the rendering spec plus any number of valid customisation settings.
     */
    renderingSpec?: RenderingSpec;
}
/**
 * The set of options that you can use when both creating an {@link EmbedSDK} object or using {@link EmbedSDK.createDashboard}.
 */
export interface EmbedDashboardOptions extends SharedEmbedOptions {
    /**
     * The id for the dashboard you want to embed.
     *
     * This can be found in the "Embed Dashboard" dialog.
     */
    dashboardId: string;
    /**
     * Assign background colour for all charts in an embedded dashboard.
     */
    chartsBackground?: string;
    /**
     * Width behaviour of charts in an embedded dashboard.
     *
     * - `'fixed'` Width of charts will remain the same as the dashboard.
     *
     * - `'scale'` Width of charts will scale according to the container.
     */
    widthMode?: Scaling;
    /**
     * Height behaviour of charts in an embedded dashboard.
     *
     * - `'fixed'` Height of charts will remain the same as the dashboard.
     * - `'scale'` Height of charts will scale according to the container.
     */
    heightMode?: Scaling;
    /**
     * Display the dashboard title and description.
     */
    showTitleAndDesc?: boolean;
    /**
     * Embedding options to be passed to the embedded charts in the dashboard
     */
    charts?: Array<DashboardChartOption>;
}
export type EmbedOptions = EmbedChartOptions | EmbedDashboardOptions;
export type EventHandlerPayload = Record<string, unknown>;
export type EventHandlerOptions = {
    includes?: object[];
};
export type EmbedChartEvent = 'click' | 'refresh';
export type EventHandler = (payload: EventHandlerPayload) => void;
export type EventSender = new (...args: any[]) => {
    /**
     * Send message to embedded app.
     */
    _send(msgName: string, ...payload: unknown[]): Promise<[unknown]>;
};
export declare type RenderingSpec = {
    title?: string | undefined;
    description?: string | undefined;
    channels?: {
        [x: string]: {
            labelOverride?: string | undefined;
            numberMultiplier?: number | undefined;
            numberDecimals?: number | undefined;
            numberSuffix?: string | undefined;
            numberThousandsSeparators?: boolean | undefined;
            numberPrefix?: string | undefined;
            plotOnSecondaryAxis?: boolean | undefined;
            wrapText?: boolean | undefined;
        };
    } | undefined;
    axes?: {
        [x: string]: {
            labelOverride?: string | undefined;
            labelAngle?: ("vertical" | "horizontal" | "diagonal") | undefined;
            logScale?: boolean | undefined;
            scaleMax?: (false | number) | undefined;
            scaleMin?: (false | number) | undefined;
        };
    } | undefined;
    options?: {
        categoryLabels?: boolean | undefined;
        labelSize?: (number | false) | undefined;
        legendPosition?: ("right" | "bottom" | "top") | undefined;
        markers?: boolean | undefined;
        valueLabels?: (("value" | "percentage") | boolean) | undefined;
        lineSmoothing?: ("linear" | "monotone" | "step-before" | "step-after") | undefined;
        textSize?: (number | false) | undefined;
        totalsColumn?: boolean | undefined;
        totalsRow?: boolean | undefined;
        colorPalette?: (false | {
            type: "discrete";
            value: string[];
        } | {
            type: "discrete";
            value: string[];
            channels: string[];
        } | {
            type: "discrete";
            value: string[];
            marks: string[];
        } | {
            type: "continuous";
            color: "blueorange" | "redblue" | "pinkyellowgreen" | "redyellowgreen" | "brownbluegreen" | "rainbow" | "yellowgreen" | "purpleblue" | "yelloworangered" | "yellowgreenblue" | "viridis" | "inferno" | "magma" | "plasma" | "green" | "blue" | "red" | "grey";
            reverseColor?: boolean | undefined;
        }) | undefined;
    } | undefined;
    conditionalFormatting?: ({
        type: "discrete";
        backgroundColor?: string | undefined;
        textColor?: string | undefined;
        fontStyle?: ("italic" | "normal") | undefined;
        fontWeight?: ("bold" | "normal") | undefined;
        textDecoration?: ("underline" | "line-through" | "'underline line-through'" | "initial") | undefined;
        applyToEntireRow?: boolean | undefined;
        conditions: ({
            operator: "STRING_CONTAINS" | "STRING_EMPTY" | "STRING_EQUAL_TO" | "STRING_NOT_CONTAINS" | "STRING_NOT_EMPTY" | "STRING_NOT_EQUAL_TO" | "STRING_ONE_OF" | "STRING_STARTS_WITH";
            value: string | string[];
            targetType: "CHANNEL" | "ROW_INDEX" | "COLUMN_NAME" | "CELL_VALUE" | "ROW_TOTAL" | "COLUMN_TOTAL" | "COLUMN_ID";
            targetChannel: string;
        } | {
            operator: "STRING_REGEX";
            value: {
                source: string;
                flags: string;
            };
            targetType: "CHANNEL" | "ROW_INDEX" | "COLUMN_NAME" | "CELL_VALUE" | "ROW_TOTAL" | "COLUMN_TOTAL" | "COLUMN_ID";
            targetChannel: string;
        } | ({
            operator: "NUMBER_EQUAL_TO" | "NUMBER_GREATER_THAN" | "NUMBER_GREATER_THAN_OR_EQUAL_TO" | "NUMBER_LESS_THAN" | "NUMBER_LESS_THAN_OR_EQUAL_TO" | "NUMBER_NOT_EQUAL_TO" | "NUMBER_RANKED_IN_BOTTOM" | "NUMBER_RANKED_IN_BOTTOM_PERCENT" | "NUMBER_RANKED_IN_TOP" | "NUMBER_RANKED_IN_TOP_PERCENT";
            value: number;
        } | {
            operator: "NUMBER_EQUAL_TO" | "NUMBER_GREATER_THAN" | "NUMBER_GREATER_THAN_OR_EQUAL_TO" | "NUMBER_LESS_THAN" | "NUMBER_LESS_THAN_OR_EQUAL_TO" | "NUMBER_NOT_EQUAL_TO" | "NUMBER_RANKED_IN_BOTTOM" | "NUMBER_RANKED_IN_BOTTOM_PERCENT" | "NUMBER_RANKED_IN_TOP" | "NUMBER_RANKED_IN_TOP_PERCENT";
            value: number;
            targetType: "CHANNEL";
            targetChannel: string;
        }) | {
            operator: "BINNED_NUMBER_GREATER_THAN" | "BINNED_NUMBER_GREATER_THAN_OR_INCLUDES" | "BINNED_NUMBER_INCLUDES" | "BINNED_NUMBER_LESS_THAN" | "BINNED_NUMBER_LESS_THAN_OR_INCLUDES";
            value: number;
            targetType: "CHANNEL" | "ROW_INDEX" | "COLUMN_NAME" | "CELL_VALUE" | "ROW_TOTAL" | "COLUMN_TOTAL" | "COLUMN_ID";
            targetChannel: string;
        } | {
            operator: ("NUMBER_EQUAL_TO" | "NUMBER_GREATER_THAN" | "NUMBER_GREATER_THAN_OR_EQUAL_TO" | "NUMBER_LESS_THAN" | "NUMBER_LESS_THAN_OR_EQUAL_TO" | "NUMBER_NOT_EQUAL_TO" | "NUMBER_RANKED_IN_BOTTOM" | "NUMBER_RANKED_IN_BOTTOM_PERCENT" | "NUMBER_RANKED_IN_TOP" | "NUMBER_RANKED_IN_TOP_PERCENT") | ("STRING_CONTAINS" | "STRING_EMPTY" | "STRING_EQUAL_TO" | "STRING_NOT_CONTAINS" | "STRING_NOT_EMPTY" | "STRING_NOT_EQUAL_TO" | "STRING_ONE_OF" | "STRING_STARTS_WITH");
            value: number | string;
            targetType: "ROW_INDEX" | "COLUMN_NAME" | "CELL_VALUE" | "ROW_TOTAL" | "COLUMN_TOTAL" | "COLUMN_ID";
        } | {
            operator: "DATE_AFTER" | "DATE_BEFORE" | "DATE_EXACTLY" | "DATE_ON_OR_AFTER" | "DATE_ON_OR_BEFORE";
            value: {
                date: string;
                time: string;
            };
            targetType: "CHANNEL" | "ROW_INDEX" | "COLUMN_NAME" | "CELL_VALUE" | "ROW_TOTAL" | "COLUMN_TOTAL" | "COLUMN_ID";
            targetChannel: string;
        } | {
            operator: "BINNED_DATE_AFTER" | "BINNED_DATE_AFTER_OR_INCLUDES" | "BINNED_DATE_BEFORE" | "BINNED_DATE_BEFORE_OR_INCLUDES" | "BINNED_DATE_INCLUDES";
            value: {
                date: string;
                time: string;
            };
            targetType: "CHANNEL" | "ROW_INDEX" | "COLUMN_NAME" | "CELL_VALUE" | "ROW_TOTAL" | "COLUMN_TOTAL" | "COLUMN_ID";
            targetChannel: string;
        })[];
    } | {
        type: "continuous";
        backgroundColor: "redwhitegreen" | "redwhiteblue" | "yellowgreen" | "redyellowgreen" | "greenwhite" | "bluewhite" | "redwhite";
        reverseColor?: boolean | undefined;
        conditions: {
            targetChannel: string;
        }[];
    })[] | undefined;
    version: 1;
};