chore: API docs update and minor changes to test utils API (#45)

* chore: API docs update and minor changes to test utils API

* remove unneeded module import

* resolved pr feedback

* update callback names

Author: pan-kot

pages/01-cartesian-chart/controlled-visibility.page.tsx

@@ -108,7 +108,7 @@ function ExampleMixedChart() {
         valueFormatter: numberFormatter,
       }}
       visibleSeries={visibleSeries}
-      onChangeVisibleSeries={({ detail: { visibleSeries } }) => setSettings({ visibleItems: visibleSeries.join(",") })}
+      onVisibleSeriesChange={({ detail: { visibleSeries } }) => setSettings({ visibleItems: visibleSeries.join(",") })}
       emphasizeBaseline={settings.emphasizeBaseline}
     />
   );

pages/02-pie-chart/controlled-visibility.page.tsx

@@ -76,7 +76,7 @@ function ExamplePieChart() {
         `${segmentValue} units, ${((segmentValue / totalValue) * 100).toFixed(0)}%`
       }
       visibleSegments={visibleSegments}
-      onChangeVisibleSegments={({ detail: { visibleSegments } }) =>
+      onVisibleSegmentsChange={({ detail: { visibleSegments } }) =>
         setSettings({ visibleItems: visibleSegments.join(",") })
       }
     />

pages/04-migration/examples/line-chart.tsx

@@ -136,7 +136,7 @@ export function ComponentNew({ headerFilter, legendFilter }: { headerFilter?: bo
       }
       tooltip={{ placement: "middle" }}
       visibleSeries={visibleSeries}
-      onChangeVisibleSeries={({ detail }) => setVisibleSeries(detail.visibleSeries)}
+      onVisibleSeriesChange={({ detail }) => setVisibleSeries(detail.visibleSeries)}
     />
   );
 }

pages/04-migration/examples/pie-chart.tsx

@@ -93,7 +93,7 @@ export function ComponentNew({
         ) : undefined,
       }}
       visibleSegments={visibleSegments}
-      onChangeVisibleSegments={({ detail }) => setVisibleSegments(detail.visibleSegments)}
+      onVisibleSegmentsChange={({ detail }) => setVisibleSegments(detail.visibleSegments)}
       innerAreaTitle="60"
       innerAreaDescription="total instances"
     />

pages/common/use-highcharts.ts

@@ -14,7 +14,6 @@ export function useHighcharts({ more = false, xrange = false }: { more?: boolean
       const Highcharts = await import("highcharts");
 
       await import("highcharts/modules/accessibility");
-      await import("highcharts/modules/heatmap"); // Required for point visibility API!
 
       // Required for arearange, areasplinerange, columnrange, gauge, boxplot, errorbar, waterfall, polygon, bubble
       if (more) {

src/__tests__/__snapshots__/documenter.test.ts.snap

@@ -23,13 +23,13 @@ function getVisibilityState() {
   };
 }
 
-const onChangeVisibleSeries = vi.fn();
+const onVisibleSeriesChange = vi.fn();
 
 afterEach(() => {
-  onChangeVisibleSeries.mockReset();
+  onVisibleSeriesChange.mockReset();
 });
 
-const defaultProps = { highcharts, onChangeVisibleSeries };
+const defaultProps = { highcharts, onVisibleSeriesChange };
 
 const lineSeries: CartesianChartProps.SeriesOptions[] = [
   {
@@ -74,7 +74,7 @@ describe("CartesianChart: visibility", () => {
       hiddenSeries: ["L1"],
     });
 
-    expect(onChangeVisibleSeries).toHaveBeenCalledWith(
+    expect(onVisibleSeriesChange).toHaveBeenCalledWith(
       expect.objectContaining({
         detail: {
           visibleSeries: ["L2"],

src/cartesian-chart/__tests__/cartesian-chart-visibility.test.tsx

@@ -19,9 +19,9 @@ export const StatefulChart = forwardRef((props: CartesianChartProps, ref: React.
       ref={ref}
       {...props}
       visibleSeries={visibleSeries}
-      onChangeVisibleSeries={(event) => {
+      onVisibleSeriesChange={(event) => {
         setVisibleSeries(event.detail.visibleSeries);
-        props.onChangeVisibleSeries?.(event);
+        props.onVisibleSeriesChange?.(event);
       }}
     />
   );
@@ -58,5 +58,5 @@ export const getTooltip = () => getChart().findTooltip()!;
 export const getTooltipHeader = () => getChart().findTooltip()!.findHeader()!;
 export const getTooltipBody = () => getChart().findTooltip()!.findBody()!;
 export const getTooltipFooter = () => getChart().findTooltip()!.findFooter()!;
-export const getAllTooltipSeries = () => getChart().findTooltip()!.findSeries();
+export const getAllTooltipSeries = () => getChart().findTooltip()!.findPoints();
 export const getTooltipSeries = (index: number) => getAllTooltipSeries()[index];

src/cartesian-chart/__tests__/common.tsx

@@ -32,12 +32,12 @@ export const InternalCartesianChart = forwardRef(
   ({ tooltip, ...props }: InternalCartesianChartProps, ref: React.Ref<CartesianChartProps.Ref>) => {
     const apiRef = useRef<null | CoreChartAPI>(null);
 
-    // When visibleSeries and onChangeVisibleSeries are provided - the series visibility can be controlled from the outside.
+    // When visibleSeries and onVisibleSeriesChange are provided - the series visibility can be controlled from the outside.
     // Otherwise - the component handles series visibility using its internal state.
-    useControllableState(props.visibleSeries, props.onChangeVisibleSeries, undefined, {
+    useControllableState(props.visibleSeries, props.onVisibleSeriesChange, undefined, {
       componentName: "CartesianChart",
       propertyName: "visibleSeries",
-      changeHandlerName: "onChangeVisibleSeries",
+      changeHandlerName: "onVisibleSeriesChange",
     });
     const allSeriesIds = props.series.map((s) => getOptionsId(s));
     // We keep local visible series state to compute threshold series data, that depends on series visibility.
@@ -46,7 +46,7 @@ export const InternalCartesianChart = forwardRef(
     const onVisibleSeriesChange: CoreChartProps["onVisibleItemsChange"] = (items) => {
       const visibleSeries = items.filter((i) => i.visible).map((i) => i.id);
       if (props.visibleSeries) {
-        fireNonCancelableEvent(props.onChangeVisibleSeries, { visibleSeries });
+        fireNonCancelableEvent(props.onVisibleSeriesChange, { visibleSeries });
       } else {
         setVisibleSeriesLocal(visibleSeries);
       }

src/cartesian-chart/chart-cartesian-internal.tsx

@@ -7,7 +7,10 @@ import { NonCancelableEventHandler } from "../internal/events";
 // CartesianChartProps is the type for CartesianChart React component properties. Unlike in Highcharts API,
 // we pass options directly to the component, instead of grouping them all into a single "options" property.
 // We do still organize related options in groups, e.g.: "SeriesOptions", "TooltipOptions".
-export interface CartesianChartProps extends CoreTypes.BaseChartOptions, CoreTypes.CoreCartesianOptions {
+export interface CartesianChartProps
+  extends CoreTypes.BaseChartOptions,
+    CoreTypes.CoreCartesianOptions,
+    CoreTypes.WithCartesianI18nStrings {
   /**
    * Inverts X and Y axes. Use it to show horizontal columns (bars).
    * This property corresponds to [chart.inverted](https://api.highcharts.com/highcharts/chart.inverted).
@@ -21,7 +24,7 @@ export interface CartesianChartProps extends CoreTypes.BaseChartOptions, CoreTyp
   stacking?: "normal";
 
   /**
-   * Chart series options.
+   * Defines series options of the chart.
    * This property corresponds to [series](https://api.highcharts.com/highcharts/series), and extends it
    * with two additional series types: "x-threshold", and "y-threshold".
    *
@@ -39,31 +42,29 @@ export interface CartesianChartProps extends CoreTypes.BaseChartOptions, CoreTyp
   series: readonly CartesianChartProps.SeriesOptions[];
 
   /**
-   * Chart tooltip options.
-   *
-   * Supported options:
+   * Defines tooltip options of the chart, including:
    * * `enabled` - (optional, boolean) - Hides the tooltip.
    * * `size` - (optional, "small" | "medium" | "large") - Specifies max tooltip size.
    * * `placement` - (optional, "middle" | "outside") - Specifies preferred tooltip placement.
    * * `point` - (optional, function) - Customizes tooltip series point rendering.
-   * * `header` - (optional, function) - Provides a custom tooltip header.
-   * * `body` - (optional, function) - Provides a custom tooltip content.
-   * * `footer` - (optional, function) - Adds a tooltip footer.
+   * * `header` - (optional, function) - Renders a custom tooltip header.
+   * * `body` - (optional, function) - Renders a custom tooltip body.
+   * * `footer` - (optional, function) - Renders a custom tooltip footer.
    */
   tooltip?: CartesianChartProps.TooltipOptions;
 
   /**
-   * X-axis options.
+   * Defines options of the chart's x axis.
    * This property corresponds to [xAxis](https://api.highcharts.com/highcharts/xAxis), and extends it
    * with a custom value formatter.
    *
    * Supported options:
    * * `title` (optional, string) - Axis title.
-   * * `type` (optional, 'linear' | 'datetime' | 'category' | 'logarithmic') - Axis type.
-   * * * linear - Uses continuous proportional values scale.
-   * * * datetime - Similar to linear, but takes epoch time as values.
-   * * * category - Uses discrete scale, requires `categories` to be set.
-   * * * logarithmic - Uses continuous logarithmic values scale.
+   * * `type` (optional, "linear" | "datetime" | "category" | "logarithmic") - Axis type.
+   * * * "linear" - Uses continuous proportional values scale.
+   * * * "datetime" - Similar to linear, but takes epoch time as values.
+   * * * "category" - Uses discrete scale, requires `categories` to be set.
+   * * * "logarithmic" - Uses continuous logarithmic values scale.
    * * `min` (optional, number) - Axis min value boundary.
    * * `max` (optional, number) - Axis max value boundary.
    * * `tickInterval` (optional, number) - Distance between axis ticks.
@@ -74,52 +75,49 @@ export interface CartesianChartProps extends CoreTypes.BaseChartOptions, CoreTyp
   xAxis?: CartesianChartProps.XAxisOptions;
 
   /**
-   * Y-axis options.
+   * Defines options of the chart's y axis.
    * This property corresponds to [xAxis](https://api.highcharts.com/highcharts/yAxis), and extends it
    * with a custom value formatter.
    *
    * Supported options:
    * * `title` (optional, string) - Axis title.
-   * * `type` (optional, 'linear' | 'datetime' | 'category' | 'logarithmic') - Axis type.
-   * * * linear - Uses continuous proportional values scale.
-   * * * datetime - Similar to linear, but takes epoch time as values.
-   * * * category - Uses discrete scale, requires `categories` to be set.
-   * * * logarithmic - Uses continuous logarithmic values scale.
+   * * `type` (optional, "linear" | "datetime" | "category" | "logarithmic") - Axis type.
+   * * * "linear" - Uses continuous proportional values scale.
+   * * * "datetime" - Similar to linear, but takes epoch time as values.
+   * * * "category" - Uses discrete scale, requires `categories` to be set.
+   * * * "logarithmic" - Uses continuous logarithmic values scale.
    * * `min` (optional, number) - Axis min value boundary.
    * * `max` (optional, number) - Axis max value boundary.
    * * `tickInterval` (optional, number) - Distance between axis ticks.
    * * `categories` (optional, Array<string>) - Predefined list of values, used for categorical axis type.
    * * `reversedStacks` (optional, boolean) - Reverts series order in stacked series.
    * * `valueFormatter` (optional, function) - Takes axis tick as input and returns a formatted string. This formatter also
-   * applies to the tooltip series value.
+   * applies to the tooltip points values.
    */
   yAxis?: CartesianChartProps.YAxisOptions;
 
   /**
-   * Specifies visible series by their IDs. When unset, all series are visible by default, and the visibility state
-   * is managed internally by the component. When a series does not have an ID, its name is used instead.
-   * When the property is provided, use `onChangeVisibleSeries` to manage state updates.
+   * Specifies which series to show using their IDs. By default, all series are visible and managed by the component.
+   * If a series doesn't have an ID, its name is used. When using this property, manage state updates with `onVisibleSeriesChange`.
    */
   visibleSeries?: readonly string[];
 
   /**
-   * A callback, triggered when series visibility changes as result of user interacting with the legend or filter.
-   */
-  onChangeVisibleSeries?: NonCancelableEventHandler<{ visibleSeries: string[] }>;
-
-  /**
-   * An object that contains all of the localized strings required by the component.
-   * @i18n
+   * A callback function, triggered when series visibility changes as a result of user interaction with the legend or filter.
    */
-  i18nStrings?: CoreTypes.CartesianI18nStrings;
+  onVisibleSeriesChange?: NonCancelableEventHandler<{ visibleSeries: string[] }>;
 }
 
 export namespace CartesianChartProps {
   export interface Ref {
-    // Controls series visibility that works with both controlled and uncontrolled visibility mode.
+    /**
+     * Controls series visibility and works with both controlled and uncontrolled visibility modes.
+     */
     setVisibleSeries(visibleSeries: readonly string[]): void;
-    // Same as `setVisibleSeries`, but applies to all series and requires no series IDs on input. This is useful when
-    // implementing clear-filter action in no-match state.
+    /**
+     * Functions similarly to `setVisibleSeries`, but applies to all series and doesn't require series IDs as input.
+     * Use this when implementing clear-filter actions in no-match states.
+     */
     showAllSeries(): void;
   }