@gravity-ui/charts 1.44.0 → 1.46.0

package/dist/cjs/hooks/useShapes/line/index.js

@@ -6,16 +6,19 @@ import get from 'lodash/get';
 import { getLineDashArray } from '../../../core/utils';
 import { block } from '../../../utils';
 import { HtmlLayer } from '../HtmlLayer';
+import { renderAnnotations } from '../annotation';
 import { getMarkerHaloVisibility, getMarkerVisibility, renderMarker, selectMarkerHalo, selectMarkerSymbol, setMarker, } from '../marker';
 import { setActiveState } from '../utils';
 const b = block('line');
 export const LineSeriesShapes = (args) => {
-    const { dispatcher, preparedData, seriesOptions, htmlLayout, clipPathId } = args;
+    const { boundsHeight, boundsWidth, dispatcher, preparedData, seriesOptions, htmlLayout, clipPathId, } = args;
     const hoveredDataRef = React.useRef(null);
     const plotRef = React.useRef(null);
     const markersRef = React.useRef(null);
     const hoverMarkersRef = React.useRef(null);
+    const annotationsRef = React.useRef(null);
     React.useEffect(() => {
+        var _a, _b;
         if (!plotRef.current || !markersRef.current) {
             return () => { };
         }
@@ -64,6 +67,15 @@ export const LineSeriesShapes = (args) => {
             .data(markers)
             .join('g')
             .call(renderMarker);
+        if (annotationsRef.current) {
+            const anchors = preparedData.flatMap((d) => d.annotations);
+            renderAnnotations({
+                anchors,
+                container: select(annotationsRef.current),
+                plotHeight: boundsHeight,
+                plotWidth: boundsWidth,
+            });
+        }
         const hoverEnabled = hoverOptions === null || hoverOptions === void 0 ? void 0 : hoverOptions.enabled;
         const inactiveEnabled = inactiveOptions === null || inactiveOptions === void 0 ? void 0 : inactiveOptions.enabled;
         function handleShapeHover(data) {
@@ -165,11 +177,12 @@ export const LineSeriesShapes = (args) => {
         if (hoveredDataRef.current !== null) {
             handleShapeHover(hoveredDataRef.current);
         }
-        dispatcher === null || dispatcher === void 0 ? void 0 : dispatcher.on('hover-shape.line', handleShapeHover);
+        const eventName = `hover-shape.line-${(_b = (_a = preparedData[0]) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : 'unknown'}`;
+        dispatcher === null || dispatcher === void 0 ? void 0 : dispatcher.on(eventName, handleShapeHover);
         return () => {
-            dispatcher === null || dispatcher === void 0 ? void 0 : dispatcher.on('hover-shape.line', null);
+            dispatcher === null || dispatcher === void 0 ? void 0 : dispatcher.on(eventName, null);
         };
-    }, [dispatcher, preparedData, seriesOptions]);
+    }, [boundsHeight, boundsWidth, dispatcher, preparedData, seriesOptions]);
     const htmlLayerData = React.useMemo(() => {
         const items = preparedData.map((d) => d === null || d === void 0 ? void 0 : d.htmlLabels).flat();
         return { htmlElements: items };
@@ -178,5 +191,6 @@ export const LineSeriesShapes = (args) => {
         React.createElement("g", { ref: plotRef, className: b(), clipPath: `url(#${clipPathId})` }),
         React.createElement("g", { ref: markersRef }),
         React.createElement("g", { ref: hoverMarkersRef }),
+        React.createElement("g", { ref: annotationsRef }),
         React.createElement(HtmlLayer, { preparedData: htmlLayerData, htmlLayout: htmlLayout })));
 };

package/dist/cjs/hooks/useShapes/line/prepare-data.d.ts

@@ -2,10 +2,11 @@ import type { PreparedSplit } from '../../../core/layout/split-types';
 import type { ChartScale } from '../../../core/scales/types';
 import type { ShapeDataWithLabels } from '../../../types';
 import type { PreparedXAxis, PreparedYAxis } from '../../useAxis/types';
-import type { PreparedLineSeries } from '../../useSeries/types';
+import type { PreparedLineSeries, PreparedSeriesOptions } from '../../useSeries/types';
 import type { PreparedLineData } from './types';
 export declare const prepareLineData: (args: {
     series: PreparedLineSeries[];
+    seriesOptions?: PreparedSeriesOptions;
     xAxis: PreparedXAxis;
     xScale: ChartScale;
     yAxis: PreparedYAxis[];

package/dist/cjs/hooks/useShapes/line/prepare-data.js

@@ -1,3 +1,4 @@
+import { prepareAnnotation } from '../../../core/series/prepare-annotation';
 import { filterOverlappingLabels, getLabelsSize, getTextSizeFn } from '../../../core/utils';
 import { getFormattedValue } from '../../../core/utils/format';
 import { getXValue, getYValue } from '../utils';
@@ -15,8 +16,8 @@ async function getHtmlLabel(point, series, xMax) {
     };
 }
 export const prepareLineData = async (args) => {
-    var _a, _b, _c, _d;
-    const { series, xAxis, yAxis, xScale, yScale, split, isOutsideBounds, isRangeSlider, otherLayers, } = args;
+    var _a, _b, _c, _d, _e, _f, _g;
+    const { series, seriesOptions, xAxis, yAxis, xScale, yScale, split, isOutsideBounds, isRangeSlider, otherLayers, } = args;
     const [_xMin, xRangeMax] = xScale.range();
     const xMax = xRangeMax;
     const acc = [];
@@ -29,21 +30,31 @@ export const prepareLineData = async (args) => {
         if (!seriesYScale) {
             continue;
         }
-        const points = s.data.map((d) => {
+        const annotationOpts = (_b = seriesOptions === null || seriesOptions === void 0 ? void 0 : seriesOptions.line) === null || _b === void 0 ? void 0 : _b.annotation;
+        const points = [];
+        for (let j = 0; j < s.data.length; j++) {
+            const d = s.data[j];
             const yValue = getYValue({
                 point: d,
                 points: s.data,
                 yAxis: seriesYAxis,
                 yScale: seriesYScale,
             });
-            return {
+            points.push({
                 x: getXValue({ point: d, points: s.data, xAxis, xScale }),
                 y: yValue === null ? null : yAxisTop + yValue,
-                active: true,
+                color: (_d = (_c = d.marker) === null || _c === void 0 ? void 0 : _c.color) !== null && _d !== void 0 ? _d : d.color,
                 data: d,
                 series: s,
-            };
-        });
+                annotation: d.annotation && !isRangeSlider
+                    ? await prepareAnnotation({
+                        annotation: d.annotation,
+                        optionsLabel: annotationOpts === null || annotationOpts === void 0 ? void 0 : annotationOpts.label,
+                        optionsPopup: annotationOpts === null || annotationOpts === void 0 ? void 0 : annotationOpts.popup,
+                    })
+                    : undefined,
+            });
+        }
         let htmlElements = [];
         let svgLabels = [];
         if (s.dataLabels.enabled && !isRangeSlider) {
@@ -64,7 +75,7 @@ export const prepareLineData = async (args) => {
                     if (point.y !== null &&
                         point.x !== null &&
                         !isOutsideBounds(point.x, point.y)) {
-                        const labelValue = (_b = point.data.label) !== null && _b !== void 0 ? _b : point.data.y;
+                        const labelValue = (_e = point.data.label) !== null && _e !== void 0 ? _e : point.data.y;
                         const text = getFormattedValue(Object.assign({ value: labelValue }, s.dataLabels));
                         const labelSize = await getTextSize(text);
                         const style = s.dataLabels.style;
@@ -112,7 +123,14 @@ export const prepareLineData = async (args) => {
                 return result;
             }, []);
         }
+        const annotations = points.reduce((result, p) => {
+            if (p.annotation && p.x !== null && p.y !== null) {
+                result.push({ annotation: p.annotation, x: p.x, y: p.y });
+            }
+            return result;
+        }, []);
         const result = {
+            annotations,
             points,
             markers,
             svgLabels: svgLabels,
@@ -122,11 +140,11 @@ export const prepareLineData = async (args) => {
             id: s.id,
             htmlLabels: htmlElements,
             color: s.color,
-            lineWidth: (_c = (isRangeSlider ? s.rangeSlider.lineWidth : undefined)) !== null && _c !== void 0 ? _c : s.lineWidth,
+            lineWidth: (_f = (isRangeSlider ? s.rangeSlider.lineWidth : undefined)) !== null && _f !== void 0 ? _f : s.lineWidth,
             dashStyle: s.dashStyle,
             linecap: s.linecap,
             linejoin: s.linejoin,
-            opacity: (_d = (isRangeSlider ? s.rangeSlider.opacity : undefined)) !== null && _d !== void 0 ? _d : s.opacity,
+            opacity: (_g = (isRangeSlider ? s.rangeSlider.opacity : undefined)) !== null && _g !== void 0 ? _g : s.opacity,
         };
         acc.push(result);
     }

package/dist/cjs/hooks/useShapes/line/types.d.ts

@@ -1,11 +1,14 @@
 import type { DashStyle, LineCap, LineJoin } from '../../../core/constants';
+import type { PreparedAnnotation } from '../../../core/series/types';
 import type { HtmlItem, LabelData, LineSeriesData, LineSeriesLineBaseStyle } from '../../../types';
 import type { PreparedLineSeries } from '../../useSeries/types';
+import type { AnnotationAnchor } from '../annotation';
 export type PointData = {
     x: number | null;
     y: number | null;
     data: LineSeriesData;
     series: PreparedLineSeries;
+    annotation?: PreparedAnnotation;
     color?: string;
 };
 export type MarkerPointData = PointData & {
@@ -19,6 +22,7 @@ export type MarkerData = {
     clipped: boolean;
 };
 export type PreparedLineData = {
+    annotations: AnnotationAnchor[];
     id: string;
     points: PointData[];
     markers: MarkerData[];

package/dist/cjs/types/chart-ui.d.ts

@@ -24,6 +24,8 @@ export interface HtmlItem {
         height: number;
     };
     style?: BaseTextStyle & React.CSSProperties;
+    /** Coordinate space for positioning: 'plot' uses the plot area origin, 'chart' uses the full chart origin. Defaults to 'plot'. */
+    scope?: 'plot' | 'chart';
 }
 export interface ShapeDataWithLabels {
     svgLabels: LabelData[];

package/dist/esm/components/ChartInner/index.js

@@ -256,7 +256,7 @@ export const ChartInner = (props) => {
                 React.createElement("rect", { x: 0, y: 0, width: boundsWidth, height: boundsHeight })),
             React.createElement("clipPath", { id: getClipPathIdByBounds({ clipPathId, bounds: 'horizontal' }) },
                 React.createElement("rect", { x: 0, y: -boundsHeight, width: boundsWidth, height: boundsHeight * 3 }))),
-        preparedTitle && React.createElement(Title, Object.assign({}, preparedTitle)),
+        preparedTitle && React.createElement(Title, Object.assign({}, preparedTitle, { htmlLayout: htmlLayout })),
         React.createElement("g", { transform: `translate(0, ${boundsOffsetTop})` }, preparedSplit === null || preparedSplit === void 0 ? void 0 : preparedSplit.plots.map((plot, index) => {
             return React.createElement(PlotTitle, { key: `plot-${index}`, title: plot.title });
         })),
@@ -285,7 +285,7 @@ export const ChartInner = (props) => {
             // when starting to select an area, the tooltip remains in the position where the selection began
             onPointerMove: throttledHandlePointerMove, onPointerLeave: handlePointerLeave, onTouchStart: throttledHandleTouchMove, onTouchMove: throttledHandleTouchMove, onClick: handleChartClick }, initialized ? chartContent : null),
         React.createElement("div", { className: b('html-layer'), ref: setHtmlLayout, style: {
-                '--g-html-layout-transform': `translate(${boundsOffsetLeft}px, ${boundsOffsetTop}px)`,
+                '--g-html-layout-plot-transform': `translate(${boundsOffsetLeft}px, ${boundsOffsetTop}px)`,
             } }),
         Object.keys(zoomState).length > 0 && (preparedChart === null || preparedChart === void 0 ? void 0 : preparedChart.zoom) && (React.createElement(Button, { className: b('reset-zoom-button'), onClick: () => {
                 var _a;

package/dist/esm/components/ChartInner/styles.css

@@ -10,6 +10,6 @@
 .gcharts-chart__html-layer {
   display: contents;
 }
-.gcharts-chart__html-layer-item {
-  transform: var(--g-html-layout-transform);
+.gcharts-chart__html-layer-item_plot {
+  transform: var(--g-html-layout-plot-transform);
 }

package/dist/esm/components/ChartInner/useChartInnerProps.js

@@ -53,6 +53,7 @@ export function useChartInnerProps(props) {
             const preparedTitle = await getPreparedTitle({
                 title: data.title,
                 chartWidth: width,
+                chartHeight: height,
                 chartMargin: (_a = data.chart) === null || _a === void 0 ? void 0 : _a.margin,
             });
             const preparedChart = getPreparedChart({
@@ -203,7 +204,6 @@ export function useChartInnerProps(props) {
                 getYAxisWidth,
                 legendConfig,
             });
-            //end
             const newStateValue = {
                 allPreparedSeries,
                 boundsHeight,

package/dist/esm/components/ChartInner/utils/title.d.ts

@@ -1,7 +1,8 @@
 import type { PreparedTitle } from '../../../hooks/types';
 import type { ChartData, ChartMargin } from '../../../types';
-export declare const getPreparedTitle: ({ title, chartWidth, chartMargin, }: {
+export declare const getPreparedTitle: ({ title, chartWidth, chartHeight, chartMargin, }: {
     title: ChartData["title"];
     chartWidth: number;
+    chartHeight: number;
     chartMargin?: Partial<ChartMargin>;
 }) => Promise<PreparedTitle | undefined>;

package/dist/esm/components/ChartInner/utils/title.js

@@ -1,26 +1,64 @@
-import get from 'lodash/get';
-import { getTextSizeFn, getTextWithElipsis, wrapText } from '../../../core/utils';
+import { calculateNumericProperty, getLabelsSize, getTextSizeFn, getTextWithElipsis, wrapText, } from '../../../core/utils';
 const DEFAULT_TITLE_FONT_SIZE = '15px';
 const DEFAULT_TITLE_MARGIN = 10;
-export const getPreparedTitle = async ({ title, chartWidth, chartMargin, }) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+const DEFAULT_TITLE_MAX_HEIGHT = '50%';
+export const getPreparedTitle = async ({ title, chartWidth, chartHeight, chartMargin, }) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    const titleText = title === null || title === void 0 ? void 0 : title.text;
+    if (!titleText) {
+        return undefined;
+    }
     const chartMarginTop = (_a = chartMargin === null || chartMargin === void 0 ? void 0 : chartMargin.top) !== null && _a !== void 0 ? _a : 0;
     const chartMarginLeft = (_b = chartMargin === null || chartMargin === void 0 ? void 0 : chartMargin.left) !== null && _b !== void 0 ? _b : 0;
     const chartMarginRight = (_c = chartMargin === null || chartMargin === void 0 ? void 0 : chartMargin.right) !== null && _c !== void 0 ? _c : 0;
-    const titleText = get(title, 'text');
     const titleStyle = {
         fontSize: (_e = (_d = title === null || title === void 0 ? void 0 : title.style) === null || _d === void 0 ? void 0 : _d.fontSize) !== null && _e !== void 0 ? _e : DEFAULT_TITLE_FONT_SIZE,
         fontWeight: (_g = (_f = title === null || title === void 0 ? void 0 : title.style) === null || _f === void 0 ? void 0 : _f.fontWeight) !== null && _g !== void 0 ? _g : 'var(--g-text-subheader-font-weight)',
         fontColor: (_j = (_h = title === null || title === void 0 ? void 0 : title.style) === null || _h === void 0 ? void 0 : _h.fontColor) !== null && _j !== void 0 ? _j : 'var(--g-color-text-primary)',
     };
-    if (!titleText) {
-        return undefined;
+    const usableWidth = chartWidth - chartMarginLeft - chartMarginRight;
+    const titleMargin = (_k = title === null || title === void 0 ? void 0 : title.margin) !== null && _k !== void 0 ? _k : DEFAULT_TITLE_MARGIN;
+    if (title === null || title === void 0 ? void 0 : title.html) {
+        const titleSize = await getLabelsSize({
+            labels: [titleText],
+            style: Object.assign(Object.assign({}, titleStyle), { maxWidth: `${usableWidth}px` }),
+            html: true,
+        });
+        const resolvedMaxHeight = calculateNumericProperty({
+            value: (_l = title.maxHeight) !== null && _l !== void 0 ? _l : DEFAULT_TITLE_MAX_HEIGHT,
+            base: chartHeight,
+        });
+        const titleHeight = resolvedMaxHeight === undefined
+            ? titleSize.maxHeight
+            : Math.min(titleSize.maxHeight, resolvedMaxHeight);
+        const qa = title === null || title === void 0 ? void 0 : title.qa;
+        const qaAttr = qa ? ` data-qa="${qa}"` : '';
+        const maxHeightStyle = resolvedMaxHeight === undefined ? '' : ` max-height: ${resolvedMaxHeight}px;`;
+        const htmlContent = `<div${qaAttr} style="max-width: ${usableWidth}px; overflow: hidden;${maxHeightStyle}">${titleText}</div>`;
+        const titleWidth = Math.min(titleSize.maxWidth, usableWidth);
+        return {
+            text: titleText,
+            style: titleStyle,
+            height: titleHeight,
+            margin: titleMargin,
+            qa,
+            html: true,
+            htmlElements: [
+                {
+                    x: chartMarginLeft + (usableWidth - titleWidth) / 2,
+                    y: chartMarginTop,
+                    content: htmlContent,
+                    size: { width: titleWidth, height: titleHeight },
+                    style: titleStyle,
+                    scope: 'chart',
+                },
+            ],
+        };
     }
+    const xCenter = chartMarginLeft + usableWidth / 2;
     const getTitleTextSize = getTextSizeFn({ style: titleStyle });
-    const maxRowCount = (_k = title === null || title === void 0 ? void 0 : title.maxRowCount) !== null && _k !== void 0 ? _k : 1;
+    const maxRowCount = (_m = title === null || title === void 0 ? void 0 : title.maxRowCount) !== null && _m !== void 0 ? _m : 1;
     const contentRows = [];
-    const usableWidth = chartWidth - chartMarginLeft - chartMarginRight;
-    const xCenter = chartMarginLeft + usableWidth / 2;
     if (maxRowCount > 1) {
         let titleTextRows = await wrapText({
             text: titleText,
@@ -33,7 +71,7 @@ export const getPreparedTitle = async ({ title, chartWidth, chartMargin, }) => {
                 acc.push(row);
             }
             else {
-                acc[maxRowCount - 1].text += row.text;
+                acc[maxRowCount - 1] = Object.assign(Object.assign({}, acc[maxRowCount - 1]), { text: acc[maxRowCount - 1].text + row.text });
             }
             return acc;
         }, []);
@@ -71,12 +109,11 @@ export const getPreparedTitle = async ({ title, chartWidth, chartMargin, }) => {
         });
     }
     const totalTextHeight = contentRows.reduce((acc, row) => acc + row.size.height, 0);
-    const titleHeight = totalTextHeight;
     return {
         text: titleText,
         style: titleStyle,
-        height: titleHeight,
-        margin: (_l = title === null || title === void 0 ? void 0 : title.margin) !== null && _l !== void 0 ? _l : DEFAULT_TITLE_MARGIN,
+        height: totalTextHeight,
+        margin: titleMargin,
         qa: title === null || title === void 0 ? void 0 : title.qa,
         contentRows,
     };

package/dist/esm/components/Title/index.d.ts

@@ -1,5 +1,7 @@
 import React from 'react';
 import type { PreparedTitle } from '../../hooks';
-type Props = PreparedTitle;
-export declare const Title: (props: Props) => React.JSX.Element;
+type Props = PreparedTitle & {
+    htmlLayout?: HTMLElement | null;
+};
+export declare const Title: (props: Props) => React.JSX.Element | null;
 export {};

package/dist/esm/components/Title/index.js

@@ -1,9 +1,16 @@
 import React from 'react';
+import { HtmlLayer } from '../../hooks/useShapes/HtmlLayer';
 export const Title = (props) => {
-    const { style, qa, contentRows } = props;
+    const { style, qa, contentRows, html, htmlElements, htmlLayout } = props;
+    if (html) {
+        if (!htmlLayout || !htmlElements) {
+            return null;
+        }
+        return React.createElement(HtmlLayer, { htmlLayout: htmlLayout, preparedData: { htmlElements } });
+    }
     return (React.createElement("text", { dominantBaseline: "hanging", textAnchor: "middle", style: {
             fill: style === null || style === void 0 ? void 0 : style.fontColor,
             fontSize: style === null || style === void 0 ? void 0 : style.fontSize,
             fontWeight: style === null || style === void 0 ? void 0 : style.fontWeight,
-        }, "data-qa": qa }, contentRows.map((row, i) => (React.createElement("tspan", { key: i, x: row.x, y: row.y, dominantBaseline: "hanging", dangerouslySetInnerHTML: { __html: row.text } })))));
+        }, "data-qa": qa }, contentRows === null || contentRows === void 0 ? void 0 : contentRows.map((row, i) => (React.createElement("tspan", { key: i, x: row.x, y: row.y, dominantBaseline: "hanging", dangerouslySetInnerHTML: { __html: row.text } })))));
 };

package/dist/esm/core/constants/defaults/annotation.d.ts

@@ -0,0 +1,12 @@
+export declare const annotationLabelDefaults: {
+    style: {
+        fontSize: string;
+        fontColor: string;
+    };
+};
+export declare const annotationPopupDefaults: {
+    backgroundColor: string;
+    borderRadius: number;
+    offset: number;
+    padding: [number, number];
+};

package/dist/esm/core/constants/defaults/annotation.js

@@ -0,0 +1,12 @@
+export const annotationLabelDefaults = {
+    style: {
+        fontSize: '13px',
+        fontColor: 'var(--g-color-text-light-primary)',
+    },
+};
+export const annotationPopupDefaults = {
+    backgroundColor: 'var(--g-color-base-float-heavy)',
+    borderRadius: 4,
+    offset: 5,
+    padding: [4, 8],
+};

package/dist/esm/core/constants/defaults/index.d.ts

@@ -1,3 +1,4 @@
+export * from './annotation';
 export * from './axis';
 export * from './brush';
 export * from './data-labels';

package/dist/esm/core/constants/defaults/index.js

@@ -1,3 +1,4 @@
+export * from './annotation';
 export * from './axis';
 export * from './brush';
 export * from './data-labels';

package/dist/esm/core/series/constants.d.ts

@@ -4,4 +4,4 @@ export declare const DEFAULT_LEGEND_SYMBOL_SIZE = 8;
 export declare const DEFAULT_LEGEND_SYMBOL_PADDING = 5;
 export declare const DEFAULT_DATALABELS_PADDING = 5;
 export declare const DEFAULT_HALO_OPTIONS: Required<Halo>;
-export declare const DEFAULT_POINT_MARKER_OPTIONS: Omit<Required<PointMarkerOptions>, 'enabled'>;
+export declare const DEFAULT_POINT_MARKER_OPTIONS: Omit<Required<PointMarkerOptions>, 'color' | 'enabled'>;

package/dist/esm/core/series/constants.js

@@ -7,8 +7,8 @@ export const DEFAULT_HALO_OPTIONS = {
     size: 6,
 };
 export const DEFAULT_POINT_MARKER_OPTIONS = {
-    radius: 4,
     borderColor: '',
     borderWidth: 0,
+    radius: 4,
     symbol: 'circle',
 };

package/dist/esm/core/series/prepare-annotation.d.ts

@@ -0,0 +1,12 @@
+import type { ChartAnnotationLabel, ChartAnnotationPopup } from '../../types';
+import type { PreparedAnnotation } from './types';
+type AnnotationOptionsLabel = Omit<ChartAnnotationLabel, 'text'> | undefined;
+export declare function prepareAnnotation(args: {
+    annotation: {
+        label: ChartAnnotationLabel;
+        popup?: ChartAnnotationPopup;
+    };
+    optionsLabel?: AnnotationOptionsLabel;
+    optionsPopup?: ChartAnnotationPopup;
+}): Promise<PreparedAnnotation>;
+export {};

package/dist/esm/core/series/prepare-annotation.js

@@ -0,0 +1,31 @@
+import { annotationLabelDefaults, annotationPopupDefaults } from '../constants';
+import { getTextSizeFn } from '../utils';
+function resolvePadding(padding) {
+    if (padding === undefined) {
+        return annotationPopupDefaults.padding;
+    }
+    if (typeof padding === 'number') {
+        return [padding, padding];
+    }
+    return padding;
+}
+export async function prepareAnnotation(args) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    const { annotation, optionsLabel, optionsPopup } = args;
+    const style = Object.assign(Object.assign(Object.assign({}, annotationLabelDefaults.style), optionsLabel === null || optionsLabel === void 0 ? void 0 : optionsLabel.style), annotation.label.style);
+    const getTextSize = getTextSizeFn({ style });
+    const textSize = await getTextSize(annotation.label.text);
+    return {
+        label: {
+            style,
+            text: annotation.label.text,
+            size: { height: textSize.height, width: textSize.width },
+        },
+        popup: {
+            backgroundColor: (_c = (_b = (_a = annotation.popup) === null || _a === void 0 ? void 0 : _a.backgroundColor) !== null && _b !== void 0 ? _b : optionsPopup === null || optionsPopup === void 0 ? void 0 : optionsPopup.backgroundColor) !== null && _c !== void 0 ? _c : annotationPopupDefaults.backgroundColor,
+            borderRadius: (_f = (_e = (_d = annotation.popup) === null || _d === void 0 ? void 0 : _d.borderRadius) !== null && _e !== void 0 ? _e : optionsPopup === null || optionsPopup === void 0 ? void 0 : optionsPopup.borderRadius) !== null && _f !== void 0 ? _f : annotationPopupDefaults.borderRadius,
+            offset: (_j = (_h = (_g = annotation.popup) === null || _g === void 0 ? void 0 : _g.offset) !== null && _h !== void 0 ? _h : optionsPopup === null || optionsPopup === void 0 ? void 0 : optionsPopup.offset) !== null && _j !== void 0 ? _j : annotationPopupDefaults.offset,
+            padding: resolvePadding((_l = (_k = annotation.popup) === null || _k === void 0 ? void 0 : _k.padding) !== null && _l !== void 0 ? _l : optionsPopup === null || optionsPopup === void 0 ? void 0 : optionsPopup.padding),
+        },
+    };
+}

package/dist/esm/core/series/types.d.ts

@@ -1,5 +1,21 @@
 import type { AreaSeries, AreaSeriesData, BarXSeries, BarXSeriesData, BarYSeries, BarYSeriesData, BaseTextStyle, ChartLegend, ChartSeries, ChartSeriesRangeSliderOptions, ConnectorCurve, ConnectorShape, FunnelSeries, FunnelSeriesData, HeatmapSeries, HeatmapSeriesData, LineSeries, LineSeriesData, LineSeriesLineBaseStyle, PathLegendSymbolOptions, PieSeries, PieSeriesData, RadarSeries, RadarSeriesCategory, RadarSeriesData, RectLegendSymbolOptions, SankeySeries, SankeySeriesData, ScatterSeries, ScatterSeriesData, SymbolLegendSymbolOptions, TreemapSeries, TreemapSeriesData, ValueFormat, WaterfallSeries, WaterfallSeriesData, XRangeSeries, XRangeSeriesData } from '../../types';
 import type { DashStyle, LayoutAlgorithm, LineCap, LineJoin, SeriesOptionsDefaults, SymbolType } from '../constants';
+export type PreparedAnnotation = {
+    label: {
+        size: {
+            height: number;
+            width: number;
+        };
+        style: BaseTextStyle;
+        text: string;
+    };
+    popup: {
+        backgroundColor: string;
+        borderRadius: number;
+        offset: number;
+        padding: [number, number];
+    };
+};
 export type RectLegendSymbol = {
     shape: 'rect';
 } & Required<RectLegendSymbolOptions>;

package/dist/esm/core/types/chart/annotation.d.ts

@@ -0,0 +1,45 @@
+import type { BaseTextStyle } from './base';
+export interface ChartAnnotationLabel {
+    /** Annotation text */
+    text: string;
+    /** Text style. fontColor defaults to 'var(--g-color-text-light-primary)' */
+    style?: Partial<BaseTextStyle>;
+}
+export interface ChartAnnotationPopup {
+    /**
+     * Background color of the popup.
+     * @default 'var(--g-color-base-float-heavy)'
+     */
+    backgroundColor?: string;
+    /**
+     * Border radius of the popup.
+     * @default 4
+     */
+    borderRadius?: number;
+    /**
+     * Distance in pixels between the anchor point and the popup edge along the main axis.
+     * The main axis depends on the automatically chosen placement:
+     * for top/bottom — vertical distance, for left/right — horizontal distance.
+     * @default 5
+     */
+    offset?: number;
+    /**
+     * Popup padding. Number or [vertical, horizontal].
+     * @default [4, 8]
+     */
+    padding?: number | [number, number];
+}
+/** Default annotation settings applied to all data points in a series */
+export interface ChartAnnotationSeriesOptions {
+    /** Default label style for annotations */
+    label?: Omit<ChartAnnotationLabel, 'text'>;
+    /** Default popup settings for annotations */
+    popup?: ChartAnnotationPopup;
+}
+/** Annotation for a specific data point. Renders as a popup with text label near the data point. */
+export interface ChartPointAnnotation {
+    /** Text content and style of the annotation */
+    label: ChartAnnotationLabel;
+    /** Visual settings for the annotation popup container (background, padding, etc.) */
+    popup?: ChartAnnotationPopup;
+}

package/dist/esm/core/types/chart/annotation.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/core/types/chart/area.d.ts

@@ -1,5 +1,6 @@
 import type { SERIES_TYPE } from '../../constants';
 import type { MeaningfulAny } from '../misc';
+import type { ChartPointAnnotation } from './annotation';
 import type { BaseSeries, BaseSeriesData, BaseSeriesLegend } from './base';
 import type { RectLegendSymbolOptions } from './legend';
 import type { PointMarkerOptions } from './marker';
@@ -23,6 +24,8 @@ export interface AreaSeriesData<T = MeaningfulAny> extends BaseSeriesData<T> {
     label?: string | number;
     /** Individual marker options for the point. */
     marker?: {
+        /** Fill color of the marker for this point */
+        color?: string;
         /** States for a single point marker. */
         states?: {
             /** The normal state of a single point marker. */
@@ -35,6 +38,11 @@ export interface AreaSeriesData<T = MeaningfulAny> extends BaseSeriesData<T> {
             };
         };
     };
+    /**
+     * Annotation displayed near this data point as a bubble with text label and optional marker.
+     * Useful for highlighting specific values, events, or adding contextual notes.
+     */
+    annotation?: ChartPointAnnotation;
 }
 export type AreaMarkerSymbol = 'circle' | 'square';
 export interface AreaMarkerOptions extends PointMarkerOptions {

package/dist/esm/core/types/chart/bar-x.d.ts

@@ -1,5 +1,6 @@
 import type { SERIES_TYPE } from '../../constants';
 import type { MeaningfulAny } from '../misc';
+import type { ChartPointAnnotation } from './annotation';
 import type { BaseSeries, BaseSeriesData, BaseSeriesLegend } from './base';
 import type { RectLegendSymbolOptions } from './legend';
 import type { ChartSeriesOptions, ChartSeriesRangeSliderOptions } from './series';
@@ -27,6 +28,11 @@ export interface BarXSeriesData<T = MeaningfulAny> extends BaseSeriesData<T> {
     label?: string | number;
     /** Individual opacity for the bar-x column. */
     opacity?: number;
+    /**
+     * Annotation displayed near this data point as a bubble with text label.
+     * Useful for highlighting specific values, events, or adding contextual notes.
+     */
+    annotation?: ChartPointAnnotation;
 }
 export interface BarXSeries<T = MeaningfulAny> extends BaseSeries {
     type: typeof SERIES_TYPE.BarX;

package/dist/esm/core/types/chart/line.d.ts

@@ -1,5 +1,6 @@
 import type { DashStyle, LineCap, LineJoin, SERIES_TYPE } from '../../constants';
 import type { MeaningfulAny } from '../misc';
+import type { ChartPointAnnotation } from './annotation';
 import type { BaseSeries, BaseSeriesData, BaseSeriesLegend } from './base';
 import type { RectLegendSymbolOptions } from './legend';
 import type { PointMarkerOptions } from './marker';
@@ -22,12 +23,19 @@ export interface LineSeriesData<T = MeaningfulAny> extends BaseSeriesData<T> {
     /** Data label value of the point. If not specified, the y value is used. */
     label?: string | number;
     marker?: {
+        /** Fill color of the marker for this point */
+        color?: string;
         states?: {
             normal?: {
                 enabled: boolean;
             };
         };
     };
+    /**
+     * Annotation displayed near this data point as a bubble with text label and optional marker.
+     * Useful for highlighting specific values, events, or adding contextual notes.
+     */
+    annotation?: ChartPointAnnotation;
 }
 export interface LineSeriesLineBaseStyle {
     /**