@classic-homes/charts-react 0.2.1 → 0.3.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { ReactNode, RefObject } from 'react';
-import { ChartLegendPosition, LegendRenderProps, ChartLegendConfig, LineChartProps, BarChartProps, PieChartProps, AreaChartProps, ScatterChartProps, DonutChartProps, RadarChartProps, FunnelChartProps, GaugeChartProps, HeatmapChartProps, TreemapChartProps, CandlestickChartProps, SankeyChartProps } from '@classic-homes/charts-core';
-export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, ChartFormatter, ChartLegendConfig, ChartLegendPosition, DataPointEventParams, DonutChartProps, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode } from '@classic-homes/charts-core';
+import { ChartLegendPosition, ChartDataTable as ChartDataTable$1, ChartExportConfig, LegendRenderProps, ChartLegendConfig, LineChartProps, BarChartProps, PieChartProps, AreaChartProps, ScatterChartProps, DonutChartProps, RadarChartProps, FunnelChartProps, GaugeChartProps, HeatmapChartProps, TreemapChartProps, CandlestickChartProps, SankeyChartProps, ChartEventHandlers } from '@classic-homes/charts-core';
+export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, ChartDataTable as ChartDataTableData, ChartEventHandlers, ChartExportConfig, ChartFormatter, ChartLegendConfig, ChartLegendPosition, DataPointEventParams, DonutChartProps, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, ReferenceBand, ReferenceLine, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode, ValueFormat, ValueFormatPreset } from '@classic-homes/charts-core';
 import * as echarts from 'echarts/core';
 import { EChartsOption } from 'echarts';
 import { ClassValue } from 'clsx';
@@ -13,6 +13,10 @@ interface ChartContainerProps extends React.HTMLAttributes<HTMLDivElement> {
     description?: string;
     /** Chart height */
     height?: number | string;
+    /** Minimum height in pixels */
+    minHeight?: number;
+    /** Maximum height in pixels */
+    maxHeight?: number;
     /** Show loading state */
     loading?: boolean;
     /** Error message */
@@ -32,10 +36,20 @@ interface ChartContainerProps extends React.HTMLAttributes<HTMLDivElement> {
     legend?: React.ReactNode;
     /** Where the custom legend sits (defaults to 'bottom') */
     legendPosition?: ChartLegendPosition;
+    /** The chart's data as a table, for screen readers, "Show data" and CSV export */
+    dataTable?: ChartDataTable$1;
+    /** 'sr-only' (the default) renders the table for screen readers, true adds a visible toggle */
+    showDataTable?: boolean | 'sr-only';
+    /** Formats values in the data table */
+    format?: (value: number) => string;
+    /** Show download buttons */
+    exportable?: boolean | ChartExportConfig;
+    /** Renders the chart to an image data URL, for the PNG download */
+    exportImage?: () => string | null;
 }
 /**
  * Container component for all charts
- * Handles loading, error, and empty states
+ * Handles loading, error, and empty states, the data table and export
  */
 declare const ChartContainer: React.ForwardRefExoticComponent<ChartContainerProps & React.RefAttributes<HTMLDivElement>>;
 
@@ -81,6 +95,22 @@ interface ChartLegendProps extends Pick<LegendRenderProps, 'items' | 'toggle'>,
  */
 declare const ChartLegend: React.ForwardRefExoticComponent<ChartLegendProps & React.RefAttributes<HTMLUListElement>>;
 
+interface ChartDataTableProps {
+    /** Table contents */
+    table: ChartDataTable$1;
+    /** Caption naming the chart the data belongs to */
+    caption: string;
+    /** Formats 'value' columns */
+    format?: (value: number) => string;
+    /** Hide visually, leaving the table to screen readers */
+    srOnly?: boolean;
+    className?: string;
+}
+/**
+ * A chart's data as a table, for screen readers and the "Show data" toggle
+ */
+declare function ChartDataTable({ table, caption, format, srOnly, className, }: ChartDataTableProps): React.JSX.Element;
+
 /** Props shared by charts that can render a custom legend */
 interface CustomLegendProps {
     /**
@@ -195,6 +225,11 @@ declare const CandlestickChart: React.ForwardRefExoticComponent<CandlestickChart
  */
 declare const SankeyChart: React.ForwardRefExoticComponent<SankeyChartProps & React.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Register extra ECharts modules (series types, components or renderers)
+ * that an `option` override needs, e.g. `registerEchartsModules([ToolboxComponent])`
+ */
+declare const registerEchartsModules: typeof echarts.use;
 interface UseChartOptions {
     /** ECharts options */
     option: EChartsOption;
@@ -202,21 +237,55 @@ interface UseChartOptions {
     theme?: 'light' | 'dark' | 'auto';
     /** Override animation setting */
     animation?: boolean;
-    /** Callback when chart is ready */
+    /** Fill series with decal patterns as well as colour */
+    patterns?: boolean;
+    /**
+     * ECharts event handlers by event name. Listeners are bound for each name
+     * with a handler and call the current handler at event time, so handlers
+     * set or replaced after mount work.
+     */
+    events?: ChartEventHandlers;
+    /**
+     * Callback when the chart instance is (re)created, before its option is
+     * applied. Register event handlers here; a theme change re-runs it so
+     * handlers are attached to the live instance.
+     */
     onReady?: (chart: echarts.ECharts) => void;
+    /**
+     * Consumer callback, called with each new instance once its option is
+     * applied (the chart's `onReady` prop)
+     */
+    onCreated?: (chart: echarts.ECharts) => void;
 }
 interface UseChartReturn {
     /** Chart instance ref */
     chartRef: RefObject<echarts.ECharts | null>;
     /** Container ref to attach to DOM element */
     containerRef: RefObject<HTMLDivElement>;
+    /** Current chart instance (null before mount) */
+    chart: echarts.ECharts | null;
     /** Current theme name */
     currentTheme: string;
+    /** Render the chart to an image data URL */
+    exportImage: (options?: ExportImageOptions) => string | null;
+}
+interface ExportImageOptions {
+    /** Image format (defaults to 'png') */
+    type?: 'png' | 'jpeg';
+    /** Resolution multiplier (defaults to 2) */
+    pixelRatio?: number;
+    /** Background colour (defaults to the card colour, so the image is not transparent) */
+    backgroundColor?: string;
 }
+/**
+ * Render a chart instance to an image data URL, or null when it has no
+ * live instance
+ */
+declare function exportChartImage(chart: echarts.ECharts | null | undefined, { type, pixelRatio, backgroundColor }?: ExportImageOptions): string | null;
 /**
  * Hook to manage ECharts instance lifecycle
  */
-declare function useChart({ option, theme, animation, onReady, }: UseChartOptions): UseChartReturn;
+declare function useChart({ option, theme, animation, patterns, events, onReady, onCreated, }: UseChartOptions): UseChartReturn;
 
 /**
  * Register Classic Theme ECharts themes
@@ -239,4 +308,4 @@ declare function useReducedMotion(): boolean;
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { AreaChart, type AreaChartComponentProps, BarChart, type BarChartComponentProps, CandlestickChart, ChartContainer, type ChartContainerProps, ChartEmpty, type ChartEmptyProps, ChartError, type ChartErrorProps, ChartLegend, type ChartLegendProps, ChartSkeleton, type ChartSkeletonProps, type CustomLegendProps, DonutChart, type DonutChartComponentProps, FunnelChart, type FunnelChartComponentProps, GaugeChart, HeatmapChart, LineChart, type LineChartComponentProps, PieChart, type PieChartComponentProps, RadarChart, type RadarChartComponentProps, SankeyChart, ScatterChart, type ScatterChartComponentProps, TreemapChart, type UseChartLegendOptions, type UseChartLegendReturn, type UseChartOptions, type UseChartReturn, cn, registerClassicThemes, useChart, useChartLegend, useChartResize, useChartTheme, useReducedMotion };
+export { AreaChart, type AreaChartComponentProps, BarChart, type BarChartComponentProps, CandlestickChart, ChartContainer, type ChartContainerProps, ChartDataTable, type ChartDataTableProps, ChartEmpty, type ChartEmptyProps, ChartError, type ChartErrorProps, ChartLegend, type ChartLegendProps, ChartSkeleton, type ChartSkeletonProps, type CustomLegendProps, DonutChart, type DonutChartComponentProps, type ExportImageOptions, FunnelChart, type FunnelChartComponentProps, GaugeChart, HeatmapChart, LineChart, type LineChartComponentProps, PieChart, type PieChartComponentProps, RadarChart, type RadarChartComponentProps, SankeyChart, ScatterChart, type ScatterChartComponentProps, TreemapChart, type UseChartLegendOptions, type UseChartLegendReturn, type UseChartOptions, type UseChartReturn, cn, exportChartImage, registerClassicThemes, registerEchartsModules, useChart, useChartLegend, useChartResize, useChartTheme, useReducedMotion };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { ReactNode, RefObject } from 'react';
-import { ChartLegendPosition, LegendRenderProps, ChartLegendConfig, LineChartProps, BarChartProps, PieChartProps, AreaChartProps, ScatterChartProps, DonutChartProps, RadarChartProps, FunnelChartProps, GaugeChartProps, HeatmapChartProps, TreemapChartProps, CandlestickChartProps, SankeyChartProps } from '@classic-homes/charts-core';
-export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, ChartFormatter, ChartLegendConfig, ChartLegendPosition, DataPointEventParams, DonutChartProps, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode } from '@classic-homes/charts-core';
+import { ChartLegendPosition, ChartDataTable as ChartDataTable$1, ChartExportConfig, LegendRenderProps, ChartLegendConfig, LineChartProps, BarChartProps, PieChartProps, AreaChartProps, ScatterChartProps, DonutChartProps, RadarChartProps, FunnelChartProps, GaugeChartProps, HeatmapChartProps, TreemapChartProps, CandlestickChartProps, SankeyChartProps, ChartEventHandlers } from '@classic-homes/charts-core';
+export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, ChartDataTable as ChartDataTableData, ChartEventHandlers, ChartExportConfig, ChartFormatter, ChartLegendConfig, ChartLegendPosition, DataPointEventParams, DonutChartProps, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, ReferenceBand, ReferenceLine, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode, ValueFormat, ValueFormatPreset } from '@classic-homes/charts-core';
 import * as echarts from 'echarts/core';
 import { EChartsOption } from 'echarts';
 import { ClassValue } from 'clsx';
@@ -13,6 +13,10 @@ interface ChartContainerProps extends React.HTMLAttributes<HTMLDivElement> {
     description?: string;
     /** Chart height */
     height?: number | string;
+    /** Minimum height in pixels */
+    minHeight?: number;
+    /** Maximum height in pixels */
+    maxHeight?: number;
     /** Show loading state */
     loading?: boolean;
     /** Error message */
@@ -32,10 +36,20 @@ interface ChartContainerProps extends React.HTMLAttributes<HTMLDivElement> {
     legend?: React.ReactNode;
     /** Where the custom legend sits (defaults to 'bottom') */
     legendPosition?: ChartLegendPosition;
+    /** The chart's data as a table, for screen readers, "Show data" and CSV export */
+    dataTable?: ChartDataTable$1;
+    /** 'sr-only' (the default) renders the table for screen readers, true adds a visible toggle */
+    showDataTable?: boolean | 'sr-only';
+    /** Formats values in the data table */
+    format?: (value: number) => string;
+    /** Show download buttons */
+    exportable?: boolean | ChartExportConfig;
+    /** Renders the chart to an image data URL, for the PNG download */
+    exportImage?: () => string | null;
 }
 /**
  * Container component for all charts
- * Handles loading, error, and empty states
+ * Handles loading, error, and empty states, the data table and export
  */
 declare const ChartContainer: React.ForwardRefExoticComponent<ChartContainerProps & React.RefAttributes<HTMLDivElement>>;
 
@@ -81,6 +95,22 @@ interface ChartLegendProps extends Pick<LegendRenderProps, 'items' | 'toggle'>,
  */
 declare const ChartLegend: React.ForwardRefExoticComponent<ChartLegendProps & React.RefAttributes<HTMLUListElement>>;
 
+interface ChartDataTableProps {
+    /** Table contents */
+    table: ChartDataTable$1;
+    /** Caption naming the chart the data belongs to */
+    caption: string;
+    /** Formats 'value' columns */
+    format?: (value: number) => string;
+    /** Hide visually, leaving the table to screen readers */
+    srOnly?: boolean;
+    className?: string;
+}
+/**
+ * A chart's data as a table, for screen readers and the "Show data" toggle
+ */
+declare function ChartDataTable({ table, caption, format, srOnly, className, }: ChartDataTableProps): React.JSX.Element;
+
 /** Props shared by charts that can render a custom legend */
 interface CustomLegendProps {
     /**
@@ -195,6 +225,11 @@ declare const CandlestickChart: React.ForwardRefExoticComponent<CandlestickChart
  */
 declare const SankeyChart: React.ForwardRefExoticComponent<SankeyChartProps & React.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Register extra ECharts modules (series types, components or renderers)
+ * that an `option` override needs, e.g. `registerEchartsModules([ToolboxComponent])`
+ */
+declare const registerEchartsModules: typeof echarts.use;
 interface UseChartOptions {
     /** ECharts options */
     option: EChartsOption;
@@ -202,21 +237,55 @@ interface UseChartOptions {
     theme?: 'light' | 'dark' | 'auto';
     /** Override animation setting */
     animation?: boolean;
-    /** Callback when chart is ready */
+    /** Fill series with decal patterns as well as colour */
+    patterns?: boolean;
+    /**
+     * ECharts event handlers by event name. Listeners are bound for each name
+     * with a handler and call the current handler at event time, so handlers
+     * set or replaced after mount work.
+     */
+    events?: ChartEventHandlers;
+    /**
+     * Callback when the chart instance is (re)created, before its option is
+     * applied. Register event handlers here; a theme change re-runs it so
+     * handlers are attached to the live instance.
+     */
     onReady?: (chart: echarts.ECharts) => void;
+    /**
+     * Consumer callback, called with each new instance once its option is
+     * applied (the chart's `onReady` prop)
+     */
+    onCreated?: (chart: echarts.ECharts) => void;
 }
 interface UseChartReturn {
     /** Chart instance ref */
     chartRef: RefObject<echarts.ECharts | null>;
     /** Container ref to attach to DOM element */
     containerRef: RefObject<HTMLDivElement>;
+    /** Current chart instance (null before mount) */
+    chart: echarts.ECharts | null;
     /** Current theme name */
     currentTheme: string;
+    /** Render the chart to an image data URL */
+    exportImage: (options?: ExportImageOptions) => string | null;
+}
+interface ExportImageOptions {
+    /** Image format (defaults to 'png') */
+    type?: 'png' | 'jpeg';
+    /** Resolution multiplier (defaults to 2) */
+    pixelRatio?: number;
+    /** Background colour (defaults to the card colour, so the image is not transparent) */
+    backgroundColor?: string;
 }
+/**
+ * Render a chart instance to an image data URL, or null when it has no
+ * live instance
+ */
+declare function exportChartImage(chart: echarts.ECharts | null | undefined, { type, pixelRatio, backgroundColor }?: ExportImageOptions): string | null;
 /**
  * Hook to manage ECharts instance lifecycle
  */
-declare function useChart({ option, theme, animation, onReady, }: UseChartOptions): UseChartReturn;
+declare function useChart({ option, theme, animation, patterns, events, onReady, onCreated, }: UseChartOptions): UseChartReturn;
 
 /**
  * Register Classic Theme ECharts themes
@@ -239,4 +308,4 @@ declare function useReducedMotion(): boolean;
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { AreaChart, type AreaChartComponentProps, BarChart, type BarChartComponentProps, CandlestickChart, ChartContainer, type ChartContainerProps, ChartEmpty, type ChartEmptyProps, ChartError, type ChartErrorProps, ChartLegend, type ChartLegendProps, ChartSkeleton, type ChartSkeletonProps, type CustomLegendProps, DonutChart, type DonutChartComponentProps, FunnelChart, type FunnelChartComponentProps, GaugeChart, HeatmapChart, LineChart, type LineChartComponentProps, PieChart, type PieChartComponentProps, RadarChart, type RadarChartComponentProps, SankeyChart, ScatterChart, type ScatterChartComponentProps, TreemapChart, type UseChartLegendOptions, type UseChartLegendReturn, type UseChartOptions, type UseChartReturn, cn, registerClassicThemes, useChart, useChartLegend, useChartResize, useChartTheme, useReducedMotion };
+export { AreaChart, type AreaChartComponentProps, BarChart, type BarChartComponentProps, CandlestickChart, ChartContainer, type ChartContainerProps, ChartDataTable, type ChartDataTableProps, ChartEmpty, type ChartEmptyProps, ChartError, type ChartErrorProps, ChartLegend, type ChartLegendProps, ChartSkeleton, type ChartSkeletonProps, type CustomLegendProps, DonutChart, type DonutChartComponentProps, type ExportImageOptions, FunnelChart, type FunnelChartComponentProps, GaugeChart, HeatmapChart, LineChart, type LineChartComponentProps, PieChart, type PieChartComponentProps, RadarChart, type RadarChartComponentProps, SankeyChart, ScatterChart, type ScatterChartComponentProps, TreemapChart, type UseChartLegendOptions, type UseChartLegendReturn, type UseChartOptions, type UseChartReturn, cn, exportChartImage, registerClassicThemes, registerEchartsModules, useChart, useChartLegend, useChartResize, useChartTheme, useReducedMotion };