@carbon/charts 0.59.0-beta.0 → 1.0.3

package/build/src/interfaces/charts.d.ts

@@ -0,0 +1,474 @@
+import { GaugeTypes, Statuses, ArrowDirections, Alignments, ChartTypes, TreeTypes, DividerStatus, ColorLegendType } from './enums';
+import { LegendOptions, TooltipOptions, GridOptions, AxesOptions, ZoomBarsOptions } from './index';
+import { BarOptions, StackedBarOptions, ToolbarOptions } from './components';
+import { AxisOptions, BinnedAxisOptions, TimeScaleOptions } from './axis-scales';
+/**
+ * Base chart options common to any chart
+ */
+export interface BaseChartOptions {
+    /**
+     * Optionally specify a title for the chart
+     */
+    title?: string;
+    /**
+     * boolean to disable animations (enabled by default)
+     */
+    animations?: boolean;
+    /**
+     * boolean to prevent the container from resizing
+     */
+    resizable?: boolean;
+    /**
+     * Optionally specify a width for the chart
+     */
+    width?: string;
+    /**
+     * Optionally specify a height for the chart
+     */
+    height?: string;
+    /**
+     * tooltip configuration
+     */
+    tooltip?: TooltipOptions;
+    /**
+     * legend configuration
+     */
+    legend?: LegendOptions;
+    /**
+     * toolbar configurations
+     */
+    toolbar?: ToolbarOptions;
+    /**
+     * Optional function to determine whether is filled based on datasetLabel, label, and/or data
+     */
+    getIsFilled?: (datasetLabel: any, label?: any, data?: any, defaultFilled?: boolean) => boolean;
+    /**
+     * Optional function to generate the fill color based on datasetLabel, label, and/or data
+     */
+    getFillColor?: (group: string, label?: string, data?: any, defaultFillColor?: string) => string;
+    /**
+     * Optional function to generate the stroke color based on datasetLabel, label, and/or data
+     * (note) - not all chart types support the stroke color (e.g. wordcloud)
+     */
+    getStrokeColor?: (group: string, label?: any, data?: any, defaultStrokeColor?: string) => string;
+    /**
+     * stylesheet options
+     */
+    style?: {
+        /**
+         * optional prefixing string for css classes (defaults to 'cc')
+         */
+        prefix?: string;
+    };
+    /**
+     * options related to charting data
+     */
+    data?: {
+        /**
+         * identifier for data groups
+         */
+        groupMapsTo?: string;
+        /**
+         * used to simulate data loading in skeleton way
+         */
+        loading?: boolean;
+        /**
+         * options related to pre-selected data groups
+         * Remains empty if every legend item is active or dataset doesn't have the data groups.
+         */
+        selectedGroups?: string[];
+    };
+    /**
+     * options related to color scales
+     */
+    color?: {
+        /**
+         * e.g. { 'Dataset 1': 'blue' }
+         */
+        scale?: object;
+        /**
+         * use a carbon dataviz preset color palette
+         * put the index (selection of which variant)
+         */
+        pairing?: {
+            /**
+             * the number of color variants in the palette (defaults to using the number of data groups in the given data)
+             */
+            numberOfVariants?: number;
+            /**
+             * the option number of the color paring
+             */
+            option?: number;
+        };
+        gradient?: {
+            enabled?: boolean;
+            /**
+             * hex color array
+             * e.g. ['#fff', '#000', ...]
+             */
+            colors?: Array<String>;
+        };
+    };
+}
+/**
+ * Options common to any chart with an axis
+ */
+export interface AxisChartOptions extends BaseChartOptions {
+    axes?: AxesOptions<AxisOptions>;
+    grid?: GridOptions;
+    timeScale?: TimeScaleOptions;
+    /**
+     * zoombar configuration
+     */
+    zoomBar?: ZoomBarsOptions;
+}
+/**
+ * Options common to binned charts with an axis
+ */
+export interface BinnedAxisChartOptions extends AxisChartOptions {
+    axes?: AxesOptions<BinnedAxisOptions>;
+    grid?: GridOptions;
+    timeScale?: TimeScaleOptions;
+    /**
+     * zoombar configuration
+     */
+    zoomBar?: ZoomBarsOptions;
+}
+/**
+ * options specific to boxplot charts
+ */
+export interface BoxplotChartOptions extends AxisChartOptions {
+}
+/**
+ * options specific to bar charts
+ */
+export interface BarChartOptions extends AxisChartOptions {
+    bars?: BarOptions;
+}
+/**
+ * options specific to stacked bar charts
+ */
+export interface StackedBarChartOptions extends BarChartOptions {
+    bars?: StackedBarOptions;
+}
+/**
+ * options specific to scatter charts
+ */
+export interface ScatterChartOptions extends AxisChartOptions {
+    /**
+     * options for the points
+     */
+    points?: {
+        /**
+         * sets the radius of the point
+         */
+        radius: number;
+        fillOpacity?: number;
+        filled?: boolean;
+        enabled?: boolean;
+    };
+}
+/**
+ * options specific to lollipop charts
+ */
+export interface LollipopChartOptions extends ScatterChartOptions {
+}
+/**
+ * options specific to bubble charts
+ */
+export interface BubbleChartOptions extends AxisChartOptions {
+    /**
+     * options for the individual bubbles
+     */
+    bubble?: {
+        /**
+         * the key to lookup in charting data for the bubble radius value
+         */
+        radiusMapsTo?: string;
+        /**
+         * options for what the bubble radius value maps to
+         */
+        radiusLabel?: string;
+        /**
+         * A function that would determine the range of the bubble radius to use
+         * Returns an array with the 1st value being the min and the 2nd value being the max radius
+         */
+        radiusRange?: Function;
+        /**
+         * Opacity of the fills used within each circle
+         */
+        fillOpacity?: number;
+        /**
+         * enabled scatter dot or not
+         */
+        enabled?: boolean;
+    };
+}
+/**
+ * options specific to bullet charts
+ */
+export interface BulletChartOptions extends AxisChartOptions {
+    /**
+     * options for the individual bullets
+     */
+    bullet?: {
+        performanceAreaTitles?: string[];
+    };
+}
+/**
+ * options specific to histogram charts
+ */
+export interface HistogramChartOptions extends AxisChartOptions {
+    /**
+     * options related to bins
+     */
+    bins?: {
+        rangeLabel?: string;
+    };
+}
+/**
+ * options specific to line charts
+ */
+export interface LineChartOptions extends ScatterChartOptions {
+    /**
+     * options for the curve of the line
+     */
+    curve?: string | {
+        name: string;
+    };
+}
+/**
+ * options specific to area charts
+ */
+export interface AreaChartOptions extends AxisChartOptions {
+    /**
+     * options for the curve of the line
+     */
+    curve?: string | {
+        name: string;
+    };
+    /**
+     * options to bound the area of the chart
+     */
+    bounds?: {
+        upperBoundMapsTo?: string;
+        lowerBoundMapsTo?: string;
+    };
+}
+/**
+ * options specific to area charts
+ */
+export interface StackedAreaChartOptions extends ScatterChartOptions {
+    /**
+     * options for the curve of the line
+     */
+    curve?: string | {
+        name: string;
+    };
+}
+/**
+ * options specific to world cloud charts
+ */
+export interface WordCloudChartTooltipOptions extends TooltipOptions {
+    /** the label that shows up by the highlighted word in the tooltip */
+    wordLabel?: string;
+    /** the label that shows up by the value of the highlighted word in the tooltip */
+    valueLabel?: string;
+}
+export interface WorldCloudChartOptions extends BaseChartOptions {
+    wordCloud?: {
+        /** what key in your charting data will the font sizes map to? */
+        fontSizeMapsTo?: string;
+        /** a function (chartSize, data) => {} that'll decide the range of font sizes, e.g. [10, 80] */
+        fontSizeRange?: Function;
+        /** what key in your charting data will the words map to? */
+        wordMapsTo?: string;
+    };
+    /**
+     * tooltip configuration
+     */
+    tooltip?: WordCloudChartTooltipOptions;
+}
+/**
+ * options specific to pie charts
+ */
+export interface PieChartOptions extends BaseChartOptions {
+    pie?: {
+        labels?: {
+            formatter?: Function;
+            enabled?: Boolean;
+        };
+        alignment?: Alignments;
+        /**
+         * identifier for value key in your charting data
+         * defaults to value
+         */
+        valueMapsTo?: string;
+        sortFunction?: (a: any, b: any) => number;
+    };
+}
+/**
+ * options specific to gauge charts
+ */
+export interface GaugeChartOptions extends BaseChartOptions {
+    gauge?: {
+        arcWidth?: number;
+        deltaArrow?: {
+            direction?: ArrowDirections;
+            size?: Function;
+            enabled: Boolean;
+        };
+        showPercentageSymbol?: Boolean;
+        status?: Statuses;
+        deltaFontSize?: Function;
+        numberSpacing?: number;
+        numberFormatter?: Function;
+        valueFontSize?: Function;
+        type?: GaugeTypes;
+        alignment?: Alignments;
+    };
+}
+/**
+ * options specific to donut charts
+ */
+export interface DonutChartOptions extends PieChartOptions {
+    donut?: {
+        center?: {
+            label?: string;
+            number?: number;
+            numberFontSize?: Function;
+            titleFontSize?: Function;
+            titleYPosition?: Function;
+            numberFormatter?: Function;
+        };
+        alignment?: Alignments;
+    };
+}
+export interface MeterChartOptions extends BaseChartOptions {
+    meter?: {
+        showLabels?: boolean;
+        proportional?: {
+            total?: number;
+            unit?: string;
+        };
+        peak?: number;
+        status?: {
+            ranges: Array<{
+                range: [number, number];
+                status: Statuses;
+            }>;
+        };
+        height?: number;
+        title?: {
+            percentageIndicator?: {
+                /**
+                 * rendering of the percentage value relative to the dataset within title
+                 */
+                enabled?: boolean;
+            };
+        };
+    };
+}
+export interface ProportionalMeterChartOptions extends BaseChartOptions {
+    meter?: {
+        proportional?: {
+            total?: number;
+            unit?: string;
+        };
+    };
+}
+/**
+ * options specific to radar charts
+ */
+export interface RadarChartOptions extends BaseChartOptions {
+    radar?: {
+        axes: {
+            angle: string;
+            value: string;
+        };
+        alignment?: Alignments;
+    };
+}
+/**
+ * options specific to combo charts
+ */
+export interface ComboChartOptions extends AxisChartOptions {
+    comboChartTypes: Array<{
+        type: ChartTypes | any;
+        options?: object;
+        correspondingDatasets: Array<string>;
+    }>;
+}
+export interface TreemapChartOptions extends BaseChartOptions {
+}
+export interface TreeChartOptions extends BaseChartOptions {
+    tree?: {
+        type?: TreeTypes;
+        rootTitle?: string;
+    };
+}
+export interface CirclePackChartOptions extends BaseChartOptions {
+    circlePack?: {
+        circles: {
+            fillOpacity: number;
+        };
+        hierachyLevel: number;
+        padding?: {
+            outer?: number;
+            inner?: number;
+        };
+    };
+}
+/**
+ * options specific to Alluvial charts
+ */
+export interface AlluvialChartOptions extends BaseChartOptions {
+    alluvial: {
+        units?: string;
+        /**
+         * List of nodes to draw
+         */
+        nodes: Array<{
+            name: string;
+            category?: string;
+        }>;
+        /**
+         * Node alignment (Default is center)
+         */
+        nodeAlignment?: Alignments;
+        /**
+         * Set the node padding
+         */
+        nodePadding?: number;
+        /**
+         * Enable single color usage for lines
+         */
+        monochrome?: boolean;
+    };
+}
+/**
+ * options specific to Heatmap charts
+ */
+export interface HeatmapChartOptions extends BaseChartOptions {
+    heatmap: {
+        /**
+         * Divider width state - will default to auto
+         * No cell divider for cell dimensions less than 16
+         */
+        divider?: {
+            state?: DividerStatus;
+        };
+        /**
+         * customize color legend
+         * enabled by default on select charts
+         */
+        colorLegend?: {
+            /**
+             * Text to display beside or on top of the legend
+             * Position is determined by text length
+             */
+            title?: string;
+            type: ColorLegendType;
+        };
+    };
+}

package/build/src/interfaces/components.d.ts

@@ -0,0 +1,227 @@
+import { LayoutGrowth, LegendPositions, Alignments, ToolbarControlTypes, ZoomBarTypes } from './enums';
+import { Component } from '../components/component';
+import { TruncationOptions } from './truncation';
+/**
+ * customize the overlay contents
+ */
+export interface LayoutComponentChild {
+    id: string;
+    /**
+     * the component that'll be rendered inside layout child
+     */
+    components: Component[];
+    /**
+     * size of the layout child
+     */
+    size?: number;
+    /**
+     * how the layout child will grow or shrink
+     */
+    growth: LayoutGrowth;
+}
+/**
+ * customize the legend component
+ */
+export interface LegendOptions {
+    enabled?: boolean;
+    position?: LegendPositions;
+    /**
+     * the clickability of legend items
+     */
+    clickable?: boolean;
+    truncation?: TruncationOptions;
+    alignment?: Alignments;
+    order?: string[];
+    /**
+     * customized legend items
+     */
+    additionalItems?: LegendItem[];
+}
+/**
+ * customize the legend item
+ */
+export interface LegendItem {
+    type: string;
+    name: string;
+    fill?: string;
+    stroke?: string;
+}
+export interface TooltipOptions {
+    /**
+     * enable or disable tooltip
+     */
+    enabled?: boolean;
+    /**
+     * a function to format the tooltip values
+     */
+    valueFormatter?: Function;
+    /**
+     * custom function for returning tooltip HTML
+     * passed an array or object with the data, and then the default tooltip markup
+     */
+    customHTML?: Function;
+    /**
+     * customizes the `Group` label shown inside tooltips
+     */
+    groupLabel?: string;
+    /**
+     * show total of items
+     */
+    showTotal?: boolean;
+    /**
+     * customizes the `Total` label shown inside tooltips
+     */
+    totalLabel?: string;
+    truncation?: TruncationOptions;
+}
+/**
+ * Threshold options
+ */
+export interface ThresholdOptions {
+    /**
+     * threshold value
+     */
+    value: number | Date;
+    /**
+     * a function to format the threshold values
+     */
+    valueFormatter?: Function;
+    /**
+     * hex threshold line color
+     */
+    fillColor: string;
+    /**
+     * threshold label
+     */
+    label: string;
+}
+export interface GridOptions {
+    y?: {
+        enabled?: boolean;
+        numberOfTicks?: number;
+        alignWithAxisTicks?: boolean;
+    };
+    x?: {
+        enabled?: boolean;
+        numberOfTicks?: number;
+        alignWithAxisTicks?: boolean;
+    };
+}
+/**
+ * Ruler options
+ */
+export interface RulerOptions {
+    enabled?: boolean;
+}
+export interface BarOptions {
+    width?: number;
+    maxWidth?: number;
+    spacingFactor?: number;
+}
+export interface StackedBarOptions extends BarOptions {
+    dividerSize?: number;
+}
+/**
+ * customize the Toolbar component
+ */
+export interface ToolbarOptions {
+    /**
+     * is the toolbar visible or not
+     */
+    enabled?: boolean;
+    /**
+     * the maximum toolbar controls to be displayed as icons
+     * controls more than this number will appear in the overflow menu
+     * minimum is 1. (all toolbar controls are in overflow menu)
+     */
+    numberOfIcons?: number;
+    /**
+     * toolbar controls which will be displayed following the array order
+     */
+    controls?: ToolbarControl[];
+}
+/**
+ * options for each toolbar control
+ */
+export interface ToolbarControl {
+    /**
+     * the toolbar control type
+     */
+    type: ToolbarControlTypes;
+    /**
+     * the text to display (if this control is displayed in overflow menu)
+     * type value will be displayed if text is not available
+     */
+    text?: string;
+    /**
+     * custom id for button
+     */
+    id?: String;
+    /**
+     * SVG HTML element
+     */
+    iconSVG?: {
+        content?: string;
+        height?: string;
+        width?: string;
+    };
+    shouldBeDisabled?: Function;
+    /**
+     * function to execute on button click
+     * alternatively, users can choose to not pass in a function and can
+     * listen for events to execute asynchronously
+     */
+    clickFunction?: Function;
+}
+/**
+ * customize the ZoomBars in a chart
+ */
+export interface ZoomBarsOptions {
+    /**
+     * a variable to handle default zoom in ratio (0 ~ 1.0)
+     * ex: shift click zoom in ratio
+     */
+    zoomRatio?: number;
+    /**
+     * a variable to define the minimum zoom ratio (0 ~ 1.0)
+     * If  ( zoom domain / max domain ) < minZoomRatio, zoom-in functions will be disabled
+     */
+    minZoomRatio?: number;
+    /**
+     * currently only the top position is supported
+     */
+    top?: ZoomBarOptions;
+    /**
+     * whether keep updating range axis in real time while zoom domain is changing
+     */
+    updateRangeAxis?: boolean;
+}
+/**
+ * customize the ZoomBar component
+ */
+export interface ZoomBarOptions {
+    /**
+     * is the zoom-bar visible or not
+     */
+    enabled?: boolean;
+    /**
+     * is the zoom-bar in loading state
+     */
+    loading?: boolean;
+    /**
+     * is the zoom-bar in locked state
+     */
+    locked?: boolean;
+    /**
+     * whether the zoom bar is showing a slider view or a graph view etc.
+     */
+    type?: ZoomBarTypes;
+    /**
+     * an two element array which represents the initial zoom domain
+     */
+    initialZoomDomain?: Object[];
+    /**
+     * options related to zoom bar data
+     */
+    data?: Object[];
+}