@fluentui/react-charts 9.3.11 → 9.3.13

package/dist/index.d.ts

@@ -4421,6 +4421,858 @@ declare interface TitleStyles {
     };
 }
 
+/**
+ * VegaDeclarativeChart - Render Vega-Lite specifications with Fluent UI styling
+ *
+ * Supported chart types:
+ * - Line charts: mark: 'line' or 'point'
+ * - Area charts: mark: 'area'
+ * - Scatter charts: mark: 'point', 'circle', or 'square'
+ * - Vertical bar charts: mark: 'bar' with nominal/ordinal x-axis
+ * - Stacked bar charts: mark: 'bar' with color encoding
+ * - Grouped bar charts: mark: 'bar' with color encoding (via configuration)
+ * - Horizontal bar charts: mark: 'bar' with nominal/ordinal y-axis
+ * - Donut/Pie charts: mark: 'arc' with theta encoding
+ * - Heatmaps: mark: 'rect' with x, y, and color (quantitative) encodings
+ * - Combo charts: Layered specs with bar + line marks render as VerticalStackedBarChart with line overlays
+ *
+ * Multi-plot Support:
+ * - Horizontal concatenation (hconcat): Multiple charts side-by-side
+ * - Vertical concatenation (vconcat): Multiple charts stacked vertically
+ * - Shared data and encoding are merged from parent spec to each subplot
+ *
+ * Limitations:
+ * - Most layered specifications (multiple chart types) are not fully supported
+ * - Bar + Line combinations ARE supported and will render properly
+ * - For other composite charts, only the first layer will be rendered
+ * - Faceting and repeat operators are not yet supported
+ * - Funnel charts are not a native Vega-Lite mark type. The conversion_funnel.json example
+ *   uses a horizontal bar chart (y: nominal, x: quantitative) which is the standard way to
+ *   represent funnel data in Vega-Lite. For specialized funnel visualizations with tapering
+ *   shapes, consider using Plotly's native funnel chart type instead.
+ *
+ * Note: Sankey, Gantt, and Gauge charts are not standard Vega-Lite marks.
+ * These specialized visualizations would require custom extensions or alternative approaches.
+ *
+ * @example Line Chart
+ * ```tsx
+ * import { VegaDeclarativeChart } from '@fluentui/react-charts';
+ *
+ * const spec = {
+ *   mark: 'line',
+ *   data: { values: [{ x: 1, y: 10 }, { x: 2, y: 20 }] },
+ *   encoding: {
+ *     x: { field: 'x', type: 'quantitative' },
+ *     y: { field: 'y', type: 'quantitative' }
+ *   }
+ * };
+ *
+ * <VegaDeclarativeChart chartSchema={{ vegaLiteSpec: spec }} />
+ * ```
+ *
+ * @example Area Chart
+ * ```tsx
+ * const areaSpec = {
+ *   mark: 'area',
+ *   data: { values: [{ date: '2023-01', value: 100 }, { date: '2023-02', value: 150 }] },
+ *   encoding: {
+ *     x: { field: 'date', type: 'temporal' },
+ *     y: { field: 'value', type: 'quantitative' }
+ *   }
+ * };
+ *
+ * <VegaDeclarativeChart chartSchema={{ vegaLiteSpec: areaSpec }} />
+ * ```
+ *
+ * @example Scatter Chart
+ * ```tsx
+ * const scatterSpec = {
+ *   mark: 'point',
+ *   data: { values: [{ x: 10, y: 20, size: 100 }, { x: 15, y: 30, size: 200 }] },
+ *   encoding: {
+ *     x: { field: 'x', type: 'quantitative' },
+ *     y: { field: 'y', type: 'quantitative' },
+ *     size: { field: 'size', type: 'quantitative' }
+ *   }
+ * };
+ *
+ * <VegaDeclarativeChart chartSchema={{ vegaLiteSpec: scatterSpec }} />
+ * ```
+ *
+ * @example Vertical Bar Chart
+ * ```tsx
+ * const barSpec = {
+ *   mark: 'bar',
+ *   data: { values: [{ cat: 'A', val: 28 }, { cat: 'B', val: 55 }] },
+ *   encoding: {
+ *     x: { field: 'cat', type: 'nominal' },
+ *     y: { field: 'val', type: 'quantitative' }
+ *   }
+ * };
+ *
+ * <VegaDeclarativeChart chartSchema={{ vegaLiteSpec: barSpec }} />
+ * ```
+ *
+ * @example Stacked Bar Chart
+ * ```tsx
+ * const stackedSpec = {
+ *   mark: 'bar',
+ *   data: { values: [
+ *     { cat: 'A', group: 'G1', val: 28 },
+ *     { cat: 'A', group: 'G2', val: 15 }
+ *   ]},
+ *   encoding: {
+ *     x: { field: 'cat', type: 'nominal' },
+ *     y: { field: 'val', type: 'quantitative' },
+ *     color: { field: 'group', type: 'nominal' }
+ *   }
+ * };
+ *
+ * <VegaDeclarativeChart chartSchema={{ vegaLiteSpec: stackedSpec }} />
+ * ```
+ *
+ * @example Donut Chart
+ * ```tsx
+ * const donutSpec = {
+ *   mark: 'arc',
+ *   data: { values: [{ category: 'A', value: 30 }, { category: 'B', value: 70 }] },
+ *   encoding: {
+ *     theta: { field: 'value', type: 'quantitative' },
+ *     color: { field: 'category', type: 'nominal' }
+ *   }
+ * };
+ *
+ * <VegaDeclarativeChart chartSchema={{ vegaLiteSpec: donutSpec }} />
+ * ```
+ *
+ * @example Heatmap
+ * ```tsx
+ * const heatmapSpec = {
+ *   mark: 'rect',
+ *   data: { values: [
+ *     { x: 'A', y: 'Mon', value: 28 },
+ *     { x: 'B', y: 'Mon', value: 55 },
+ *     { x: 'A', y: 'Tue', value: 43 }
+ *   ]},
+ *   encoding: {
+ *     x: { field: 'x', type: 'nominal' },
+ *     y: { field: 'y', type: 'nominal' },
+ *     color: { field: 'value', type: 'quantitative' }
+ *   }
+ * };
+ *
+ * <VegaDeclarativeChart chartSchema={{ vegaLiteSpec: heatmapSpec }} />
+ * ```
+ */
+export declare const VegaDeclarativeChart: React_2.ForwardRefExoticComponent<VegaDeclarativeChartProps & React_2.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Props for VegaDeclarativeChart component
+ */
+export declare interface VegaDeclarativeChartProps {
+    /**
+     * Vega-Lite chart schema
+     */
+    chartSchema: VegaSchema;
+    /**
+     * Callback when schema changes (e.g., legend selection)
+     */
+    onSchemaChange?: (newSchema: VegaSchema) => void;
+    /**
+     * Additional CSS class name
+     */
+    className?: string;
+    /**
+     * Additional inline styles
+     */
+    style?: React_2.CSSProperties;
+}
+
+/**
+ * Vega-Lite axis configuration
+ */
+declare interface VegaLiteAxis {
+    /**
+     * Axis title
+     */
+    title?: string | null;
+    /**
+     * Format string for axis tick labels
+     * Uses d3-format for quantitative and d3-time-format for temporal
+     */
+    format?: string;
+    /**
+     * Tick values to display
+     */
+    values?: number[] | string[];
+    /**
+     * Number of ticks
+     */
+    tickCount?: number;
+    /**
+     * Grid visibility
+     */
+    grid?: boolean;
+}
+
+/**
+ * Vega-Lite binning configuration
+ */
+declare interface VegaLiteBin {
+    /**
+     * Maximum number of bins
+     */
+    maxbins?: number;
+    /**
+     * Exact step size between bins
+     */
+    step?: number;
+    /**
+     * Extent [min, max] for binning
+     */
+    extent?: [number, number];
+    /**
+     * Base for nice bin values (e.g., 10 for powers of 10)
+     */
+    base?: number;
+    /**
+     * Whether to include the boundary in bins
+     */
+    anchor?: number;
+}
+
+/**
+ * Vega-Lite color encoding channel
+ */
+declare interface VegaLiteColorEncoding {
+    /**
+     * Field name for color differentiation
+     */
+    field?: string;
+    /**
+     * Data type
+     */
+    type?: VegaLiteType;
+    /**
+     * Legend configuration
+     */
+    legend?: VegaLiteLegend | null;
+    /**
+     * Scale configuration
+     */
+    scale?: VegaLiteScale | null;
+    /**
+     * Fixed color value
+     */
+    value?: string;
+}
+
+/**
+ * Vega-Lite inline data
+ */
+declare interface VegaLiteData {
+    /**
+     * Inline data values (array of objects)
+     */
+    values?: Array<Record<string, unknown>>;
+    /**
+     * URL to load data from
+     * TODO: Implement remote data loading
+     */
+    url?: string;
+    /**
+     * Named dataset reference
+     * TODO: Implement named dataset resolution
+     */
+    name?: string;
+    /**
+     * Data format specification
+     * TODO: Implement format parsing (csv, json, etc.)
+     */
+    format?: {
+        type?: 'json' | 'csv' | 'tsv';
+        parse?: Record<string, string>;
+    };
+}
+
+/**
+ * Vega-Lite encoding channels
+ */
+declare interface VegaLiteEncoding {
+    /**
+     * X-axis encoding
+     */
+    x?: VegaLitePositionEncoding;
+    /**
+     * Y-axis encoding
+     */
+    y?: VegaLitePositionEncoding;
+    /**
+     * Color encoding for series differentiation
+     */
+    color?: VegaLiteColorEncoding;
+    /**
+     * Size encoding for point marks
+     */
+    size?: VegaLiteSizeEncoding;
+    /**
+     * Shape encoding for point marks
+     */
+    shape?: VegaLiteShapeEncoding;
+    /**
+     * Theta encoding for pie/donut charts and polar coordinates
+     */
+    theta?: VegaLiteThetaEncoding;
+    /**
+     * Radius encoding for polar charts
+     */
+    radius?: VegaLiteRadiusEncoding;
+    /**
+     * X2 encoding for interval marks (rect, rule, bar with ranges)
+     */
+    x2?: VegaLitePositionEncoding;
+    /**
+     * Y2 encoding for interval marks (rect, rule, bar with ranges)
+     */
+    y2?: VegaLitePositionEncoding;
+    /**
+     * Text encoding for text marks
+     */
+    text?: VegaLiteTextEncoding;
+    /**
+     * xOffset encoding for grouped bar charts
+     */
+    xOffset?: VegaLitePositionEncoding;
+    /**
+     * Tooltip encoding (single field or array of fields)
+     */
+    tooltip?: any;
+}
+
+/**
+ * Vega-Lite interpolation method
+ */
+declare type VegaLiteInterpolate = 'linear' | 'linear-closed' | 'step' | 'step-before' | 'step-after' | 'basis' | 'cardinal' | 'monotone' | 'natural';
+
+/**
+ * Vega-Lite legend configuration
+ */
+declare interface VegaLiteLegend {
+    /**
+     * Legend title
+     */
+    title?: string | null;
+    /**
+     * Hide the legend
+     */
+    disable?: boolean;
+}
+
+/**
+ * Vega-Lite mark types
+ */
+declare type VegaLiteMark = 'line' | 'point' | 'circle' | 'square' | 'bar' | 'area' | 'rect' | 'rule' | 'text' | 'arc';
+
+/**
+ * Vega-Lite mark definition (can be string or object)
+ */
+declare type VegaLiteMarkDef = VegaLiteMark | {
+    type: VegaLiteMark;
+    /**
+     * Mark color
+     */
+    color?: string;
+    /**
+     * Line interpolation method
+     */
+    interpolate?: VegaLiteInterpolate;
+    /**
+     * Point marker visibility
+     */
+    point?: boolean | {
+        filled?: boolean;
+        size?: number;
+    };
+    /**
+     * Stroke width
+     */
+    strokeWidth?: number;
+    /**
+     * Stroke dash pattern (e.g., [5, 5] for dashed, [2, 2] for dotted)
+     */
+    strokeDash?: number[];
+    /**
+     * Fill opacity
+     */
+    fillOpacity?: number;
+    /**
+     * Stroke opacity
+     */
+    strokeOpacity?: number;
+    /**
+     * Overall opacity
+     */
+    opacity?: number;
+    /**
+     * Inner radius for arc/pie/donut marks (0-1 or pixel value)
+     */
+    innerRadius?: number;
+    /**
+     * Outer radius for arc/pie marks (pixel value)
+     */
+    outerRadius?: number;
+};
+
+/**
+ * Vega-Lite position encoding channel (x or y)
+ */
+declare interface VegaLitePositionEncoding {
+    /**
+     * Field name in data
+     */
+    field?: string;
+    /**
+     * Data type
+     */
+    type?: VegaLiteType;
+    /**
+     * Axis configuration
+     */
+    axis?: VegaLiteAxis | null;
+    /**
+     * Constant value for encoding (for reference lines and annotations)
+     */
+    value?: number | string | Date;
+    /**
+     * Datum value for encoding (alternative to value)
+     */
+    datum?: number | string | Date;
+    /**
+     * Scale configuration
+     */
+    scale?: VegaLiteScale | null;
+    /**
+     * Sort order for categorical axes
+     * Supports: 'ascending', 'descending', null, array of values, or object with field/op/order
+     */
+    sort?: VegaLiteSort;
+    /**
+     * Binning configuration for histograms
+     * Set to true for default binning or provide custom bin parameters
+     */
+    bin?: boolean | VegaLiteBin;
+    /**
+     * Stack configuration for area/bar charts
+     * - null: disable stacking
+     * - 'zero': stack from zero baseline (default for area charts)
+     * - 'center': center stack
+     * - 'normalize': normalize to 100%
+     */
+    stack?: null | 'zero' | 'center' | 'normalize';
+    /**
+     * Aggregate function
+     */
+    aggregate?: 'count' | 'sum' | 'mean' | 'average' | 'median' | 'min' | 'max';
+    /**
+     * Axis title (shorthand alternative to axis.title)
+     */
+    title?: string;
+    /**
+     * Time unit for temporal fields (e.g., 'yearmonth', 'month', 'day')
+     */
+    timeUnit?: string;
+}
+
+/**
+ * Vega-Lite radius encoding channel for polar charts
+ */
+declare interface VegaLiteRadiusEncoding {
+    /**
+     * Field name
+     */
+    field?: string;
+    /**
+     * Data type
+     */
+    type?: VegaLiteType;
+    /**
+     * Aggregate function
+     */
+    aggregate?: 'count' | 'sum' | 'mean' | 'average' | 'median' | 'min' | 'max';
+    /**
+     * Axis configuration
+     */
+    axis?: VegaLiteAxis | null;
+    /**
+     * Scale configuration
+     */
+    scale?: VegaLiteScale | null;
+}
+
+/**
+ * Vega-Lite scale configuration
+ */
+declare interface VegaLiteScale {
+    /**
+     * Scale type
+     */
+    type?: VegaLiteScaleType;
+    /**
+     * Domain values [min, max]
+     */
+    domain?: (number | string)[];
+    /**
+     * Range values [min, max]
+     */
+    range?: [number | string, number | string] | string[];
+    /**
+     * Color scheme name (e.g., 'category10', 'tableau10')
+     */
+    scheme?: string;
+    /**
+     * Whether scale domain should include zero
+     */
+    zero?: boolean;
+    /**
+     * Whether to reverse the scale
+     */
+    reverse?: boolean;
+}
+
+/**
+ * Vega-Lite scale type
+ */
+declare type VegaLiteScaleType = 'linear' | 'log' | 'pow' | 'sqrt' | 'symlog' | 'time' | 'utc' | 'ordinal' | 'band' | 'point';
+
+/**
+ * Vega-Lite shape encoding channel
+ */
+declare interface VegaLiteShapeEncoding {
+    /**
+     * Field name for shape encoding
+     */
+    field?: string;
+    /**
+     * Data type
+     */
+    type?: VegaLiteType;
+    /**
+     * Fixed shape value
+     */
+    value?: string;
+}
+
+/**
+ * Vega-Lite size encoding channel
+ */
+declare interface VegaLiteSizeEncoding {
+    /**
+     * Field name for size encoding
+     */
+    field?: string;
+    /**
+     * Data type
+     */
+    type?: VegaLiteType;
+    /**
+     * Fixed size value
+     */
+    value?: number;
+}
+
+/**
+ * Vega-Lite sort specification
+ */
+declare type VegaLiteSort = 'ascending' | 'descending' | null | {
+    field?: string;
+    op?: 'count' | 'sum' | 'mean' | 'average' | 'median' | 'min' | 'max';
+    order?: 'ascending' | 'descending';
+} | string[];
+
+/**
+ * Top-level Vega-Lite specification
+ */
+export declare interface VegaLiteSpec {
+    /**
+     * Schema version
+     */
+    $schema?: string;
+    /**
+     * Chart title - can be a string or a detailed title configuration
+     */
+    title?: string | VegaLiteTitleParams;
+    /**
+     * Chart description
+     */
+    description?: string;
+    /**
+     * Chart width
+     */
+    width?: number | 'container';
+    /**
+     * Chart height
+     */
+    height?: number | 'container';
+    /**
+     * Data specification (for single/layer specs)
+     */
+    data?: VegaLiteData;
+    /**
+     * Mark type (for single view)
+     */
+    mark?: VegaLiteMarkDef;
+    /**
+     * Encoding channels (for single view)
+     */
+    encoding?: VegaLiteEncoding;
+    /**
+     * Horizontal concatenation for multi-plot layouts
+     */
+    hconcat?: VegaLiteSpec[];
+    /**
+     * Vertical concatenation for multi-plot layouts
+     */
+    vconcat?: VegaLiteSpec[];
+    /**
+     * Layer specification
+     */
+    layer?: VegaLiteUnitSpec[];
+    /**
+     * Data transformations
+     * TODO: Implement transform pipeline
+     */
+    transform?: Array<Record<string, unknown>>;
+    /**
+     * Background color
+     */
+    background?: string;
+    /**
+     * Padding configuration
+     */
+    padding?: number | {
+        top?: number;
+        bottom?: number;
+        left?: number;
+        right?: number;
+    };
+    /**
+     * Auto-size configuration
+     */
+    autosize?: string | {
+        type?: string;
+        contains?: string;
+    };
+    /**
+     * Configuration overrides
+     * TODO: Implement config resolution
+     */
+    config?: Record<string, unknown>;
+    /**
+     * Interactive selection definitions
+     * TODO: Implement selection support
+     */
+    selection?: Record<string, unknown>;
+    /**
+     * Facet specification for small multiples
+     * TODO: Implement facet support
+     */
+    facet?: Record<string, unknown>;
+    /**
+     * Repeat specification for small multiples
+     * TODO: Implement repeat support
+     */
+    repeat?: Record<string, unknown>;
+    /**
+     * Scale resolution configuration
+     * Controls whether scales are shared or independent across views
+     */
+    resolve?: {
+        scale?: {
+            x?: 'shared' | 'independent';
+            y?: 'shared' | 'independent';
+            color?: 'shared' | 'independent';
+            opacity?: 'shared' | 'independent';
+            size?: 'shared' | 'independent';
+            shape?: 'shared' | 'independent';
+        };
+        axis?: {
+            x?: 'shared' | 'independent';
+            y?: 'shared' | 'independent';
+        };
+        legend?: {
+            color?: 'shared' | 'independent';
+            opacity?: 'shared' | 'independent';
+            size?: 'shared' | 'independent';
+            shape?: 'shared' | 'independent';
+        };
+    };
+}
+
+/**
+ * Vega-Lite text encoding channel
+ */
+declare interface VegaLiteTextEncoding {
+    /**
+     * Field name
+     */
+    field?: string;
+    /**
+     * Data type
+     */
+    type?: VegaLiteType;
+    /**
+     * Fixed text value
+     */
+    value?: string;
+    /**
+     * Datum value for text encoding
+     */
+    datum?: string | number;
+}
+
+/**
+ * Vega-Lite theta encoding channel for pie/donut charts and polar coordinates
+ */
+declare interface VegaLiteThetaEncoding {
+    /**
+     * Field name
+     */
+    field?: string;
+    /**
+     * Data type
+     */
+    type?: VegaLiteType;
+    /**
+     * Aggregate function
+     */
+    aggregate?: 'count' | 'sum' | 'mean' | 'average' | 'median' | 'min' | 'max';
+    /**
+     * Axis configuration for polar charts
+     */
+    axis?: VegaLiteAxis | null;
+    /**
+     * Scale configuration for polar charts
+     */
+    scale?: VegaLiteScale | null;
+}
+
+/**
+ * Vega-Lite title configuration with styling options
+ */
+declare interface VegaLiteTitleParams {
+    /**
+     * Title text
+     */
+    text: string;
+    /**
+     * Subtitle text
+     */
+    subtitle?: string;
+    /**
+     * Font for the title
+     */
+    font?: string;
+    /**
+     * Font size for the title
+     */
+    fontSize?: number;
+    /**
+     * Font style for the title (e.g., 'normal', 'italic')
+     */
+    fontStyle?: string;
+    /**
+     * Font weight for the title (e.g., 'normal', 'bold', 100-900)
+     */
+    fontWeight?: string | number;
+    /**
+     * Color of the title text
+     */
+    color?: string;
+    /**
+     * Horizontal anchor position for the title
+     * - 'start': left-aligned
+     * - 'middle': centered
+     * - 'end': right-aligned
+     */
+    anchor?: 'start' | 'middle' | 'end';
+    /**
+     * Vertical offset from the top of the chart
+     */
+    offset?: number;
+    /**
+     * Additional padding around the subtitle
+     */
+    subtitlePadding?: number;
+}
+
+/**
+ * Vega-Lite TypeScript interfaces for declarative chart specifications.
+ * This is a minimal subset focused on line/point charts with basic encodings.
+ *
+ * RECOMMENDED: For full type coverage, install the official vega-lite package:
+ * ```
+ * npm install vega-lite
+ * ```
+ * Then import `TopLevelSpec` from 'vega-lite' for complete schema support.
+ *
+ * The types provided here are a lightweight alternative that covers common use cases
+ * without requiring the full vega-lite dependency (~5.8MB unpacked).
+ *
+ * Full Vega-Lite spec: https://vega.github.io/vega-lite/docs/
+ *
+ * TODO: Add support for:
+ * - Transform operations (filter, aggregate, calculate, etc.)
+ * - Remote data sources (url, named datasets)
+ * - Facet and concatenation for multi-view layouts
+ * - Selection interactions
+ * - Additional mark types (bar, area, etc.)
+ * - Conditional encodings
+ * - Tooltip customization
+ */
+/**
+ * Vega-Lite data type for field encodings
+ */
+declare type VegaLiteType = 'quantitative' | 'temporal' | 'ordinal' | 'nominal' | 'geojson';
+
+/**
+ * Base Vega-Lite spec unit (single view)
+ */
+declare interface VegaLiteUnitSpec {
+    /**
+     * Mark type
+     */
+    mark: VegaLiteMarkDef;
+    /**
+     * Encoding channels
+     */
+    encoding?: VegaLiteEncoding;
+    /**
+     * Data specification
+     */
+    data?: VegaLiteData;
+    /**
+     * Data transformations
+     * TODO: Implement transform pipeline
+     */
+    transform?: Array<Record<string, unknown>>;
+}
+
+/**
+ * Schema for VegaDeclarativeChart component
+ */
+export declare interface VegaSchema {
+    /**
+     * Vega-Lite specification
+     *
+     * @see https://vega.github.io/vega-lite/docs/spec.html
+     */
+    vegaLiteSpec: VegaLiteSpec;
+    /**
+     * Selected legends for filtering
+     */
+    selectedLegends?: string[];
+}
+
 /**
  * VerticalBarchart component
  * {@docCategory VerticalBarChart}