@spider-analyzer/timeline 4.0.2 → 5.0.0

package/src/TimeLine.tsx

@@ -0,0 +1,994 @@
+import {
+    forwardRef,
+    useCallback,
+    useEffect,
+    useImperativeHandle,
+    useRef,
+    useState,
+} from 'react';
+import moment from './moment-shim';
+import { scaleLinear, scaleTime } from 'd3-scale';
+import { merge as _merge } from './utils';
+import { round as _round } from './utils';
+import { max as _max } from './utils';
+import { floor as _floor } from './utils';
+import { isEqual as isEqual } from './utils';
+import { isFunction as isFunction } from './utils';
+
+import CursorRaw from './Cursor';
+import HistogramRaw from './timeLineElements/Histogram';
+import XAxisRaw from './timeLineElements/XAxis';
+import YAxisRaw from './timeLineElements/YAxis';
+import LegendRaw from './timeLineElements/Legend';
+import ToolsRaw from './timeLineElements/Tools';
+import HistoToolTipDefaultRaw from './timeLineElements/HistoToolTip';
+
+// Children are still JSX; their PropTypes-inferred types are too narrow
+// for the live prop surface. Cast to any until they are converted to .tsx.
+const Cursor = CursorRaw as any;
+const Histogram = HistogramRaw as any;
+const XAxis = XAxisRaw as any;
+const YAxis = YAxisRaw as any;
+const Legend = LegendRaw as any;
+const Tools = ToolsRaw as any;
+const HistoToolTipDefault = HistoToolTipDefaultRaw as any;
+import theme, { defaultLabels, defaultQualityScale } from './theme';
+
+import QualityLine from './timeLineElements/QualityLine';
+import YGrid from './timeLineElements/YGrid';
+import XGrid from './timeLineElements/XGrid';
+
+const marginDefault = { left: 50, right: 45, top: 5, bottom: 5 };
+const xAxisDefault = { height: 20, spaceBetweenTicks: 70, barsBetweenTicks: 8 };
+const defaultZoomOutFactor = 1.25;
+
+const defaultTools = {
+    slideForward: true,
+    slideBackward: true,
+    resetTimeline: true,
+    gotoNow: true,
+    cursor: true,
+    zoomIn: true,
+    zoomOut: true,
+};
+
+export interface TimeLineHandle {
+    zoomIn(): void;
+    zoomOut(): void;
+    shiftTimeLine(delta: number): void;
+}
+
+function computeMarginAndWidth(props: any) {
+    const { margin, showLegend, metricsDefinition, width } = props;
+    const localMargin = { ...marginDefault, ...margin };
+    if (showLegend) {
+        const maxLength = _max(metricsDefinition.legends.map((s: string) => s.length));
+        localMargin.left = _max([5 + (maxLength as number) * 9, localMargin.left]);
+    }
+    return {
+        margin: localMargin,
+        histoWidth: width - localMargin.left - localMargin.right,
+    };
+}
+
+import {
+    toMoment,
+    toDuration,
+    domainToMoments,
+    timeSpanToMoments,
+} from './time';
+
+// --- Outer shell: boundary normalization + single-domain API --------------
+//
+// Consumers of the new v5 API pass:
+//   - `domain: {min, max}` (single, controlled by host)
+//   - `onDomainChange(domain)` to be notified of zoom/pan/shift changes
+//   - `onTimeSpanChange({start, stop})` instead of onCustomRange
+//   - `onLoadHisto({intervalMs, start, end})` as an object
+//   - `onLoadDefaultDomain()` returns Domain | Promise<Domain>
+//   - native `Date` at every instant, number-ms at every duration
+//   - required `timeZone: string` (IANA)
+//
+// Internally the component still runs against a `domains` STACK (for
+// zoom-out undo semantics) and moment-timezone types. The outer wrapper
+// owns the stack as useState and translates in both directions.
+
+const momentToDate = (m: any): Date | null =>
+    m && m.toDate ? m.toDate() : (m ?? null);
+
+const dateDomain = (d: any): { min: Date; max: Date } => ({
+    min: momentToDate(d?.min)!,
+    max: momentToDate(d?.max)!,
+});
+
+const TimeLineInner = forwardRef<TimeLineHandle, any>(function TimeLine(props, ref) {
+    const {
+        width, height, histo, quality, qualityScale = defaultQualityScale, metricsDefinition,
+        classes = {}, rcToolTipPrefixCls = theme.rcToolTipPrefixCls, showLegend = true,
+        tools = defaultTools,
+        onFormatTimeLegend, onFormatMetricLegend, onResetTime, onFormatTimeToolTips,
+        xAxis: xAxisProp = xAxisDefault, yAxis: yAxisProp = {},
+        showHistoToolTip,
+        HistoToolTip = HistoToolTipDefault,
+    } = props;
+
+    // --- Refs for instance-level mutable data (the class's `this.*`) --------
+
+    const xAxisRef = useRef<any>(null);
+    const timelineElementRef = useRef<SVGSVGElement | null>(null);
+
+    const autoMoveRef = useRef<ReturnType<typeof setInterval> | null>(null);
+    const isAutoMovingRef = useRef(false);
+    const lastAutoMovingDeltaRef = useRef(0);
+    const movedSinceLastFetchedRef = useRef(0);
+    const widthOfLastUpdateRef = useRef<number | null>(null);
+    const itemsRef = useRef<any[]>([]);
+
+    const labelsRef = useRef<any>(_merge({ ...defaultLabels }, props.labels));
+    useEffect(() => {
+        labelsRef.current = _merge({ ...defaultLabels }, props.labels);
+    }, [props.labels]);
+
+    // --- Reactive state (the class's `this.state`) --------------------------
+
+    const [state, setStateRaw] = useState<any>(() => {
+        const initial: any = {
+            isActive: false,
+            start: props.timeSpan.start,
+            stop: props.timeSpan.stop,
+            maxTimespan: false,
+            waitForLoad: false,
+            tooltipVisible: false,
+            barHovered: null,
+            dragging: false,
+            ticks: [],
+            verticalMarks: [],
+            ...computeMarginAndWidth(props),
+        };
+        return {
+            ...initial,
+            ...checkAndCorrectDomainPure({
+                domain: props.domains[0],
+                biggestVisibleDomain: props.biggestVisibleDomain,
+                maxDomain: props.maxDomain,
+                smallestResolution: props.smallestResolution,
+                histoWidth: initial.histoWidth,
+            }),
+        };
+    });
+
+    // Mirrors for closure-free access inside callbacks.
+    const stateRef = useRef(state);
+    stateRef.current = state;
+    const propsRef = useRef(props);
+    propsRef.current = props;
+
+    const patchState = useCallback((patch: any | ((s: any) => any)) => {
+        setStateRaw((s: any) => ({ ...s, ...(typeof patch === 'function' ? patch(s) : patch) }));
+    }, []);
+
+    // --- Domain math --------------------------------------------------------
+
+    const checkAndCorrectDomain = useCallback(({ domain }: { domain: any }) => {
+        return checkAndCorrectDomainPure({
+            domain,
+            biggestVisibleDomain: propsRef.current.biggestVisibleDomain,
+            maxDomain: propsRef.current.maxDomain,
+            smallestResolution: propsRef.current.smallestResolution,
+            histoWidth: stateRef.current.histoWidth,
+        });
+    }, []);
+
+    // --- Data loading -------------------------------------------------------
+
+    const getItems = useCallback((p: any, domain: any, shouldReload = true) => {
+        const histoWidth = computeMarginAndWidth(propsRef.current).histoWidth;
+
+        const xAxis = scaleTime().domain([domain.min, domain.max]).range([0, histoWidth]);
+        xAxis.clamp(true);
+        xAxisRef.current = xAxis;
+
+        const ticks = xAxis.ticks(_floor(histoWidth / p.xAxis.spaceBetweenTicks));
+        const intervalMs = _max([
+            _round(moment(ticks[1]).diff(moment(ticks[0])) / p.xAxis.barsBetweenTicks),
+            propsRef.current.smallestResolution.asMilliseconds(),
+        ]) as number;
+
+        patchState({ histoWidth, isActive: true, ticks });
+
+        if (shouldReload && intervalMs) {
+            widthOfLastUpdateRef.current = p.width;
+            patchState({ waitForLoad: true });
+            p.onLoadHisto(intervalMs, domain.min, domain.max);
+        }
+    }, [patchState]);
+
+    // --- Mount: mirror componentDidMount ------------------------------------
+
+    useEffect(() => {
+        if (stateRef.current.domain) {
+            getItems(propsRef.current, stateRef.current.domain);
+        } else {
+            propsRef.current.onLoadDefaultDomain();
+        }
+        patchState(computeMarginAndWidth(propsRef.current));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    // --- Effects mirroring componentDidUpdate branches ----------------------
+
+    // Max selection message
+    const prevMaxTimespanRef = useRef(state.maxTimespan);
+    useEffect(() => {
+        if (!prevMaxTimespanRef.current && state.maxTimespan) {
+            propsRef.current.onShowMessage(labelsRef.current.maxSelectionMsg);
+        }
+        prevMaxTimespanRef.current = state.maxTimespan;
+    }, [state.maxTimespan]);
+
+    // Width / margin change
+    const prevWidthRef = useRef<number | undefined>(props.width);
+    const prevMarginRef = useRef<any>(props.margin);
+    useEffect(() => {
+        if (prevWidthRef.current === props.width && isEqual(prevMarginRef.current, props.margin)) {
+            prevWidthRef.current = props.width;
+            prevMarginRef.current = props.margin;
+            return;
+        }
+        const s = stateRef.current;
+        if (s.isActive) {
+            const big =
+                widthOfLastUpdateRef.current !== null
+                && Math.abs((props.width ?? 0) - (widthOfLastUpdateRef.current ?? 0)) > 30;
+            getItems(props, s.domain, big);
+            patchState(computeMarginAndWidth(props));
+        } else {
+            patchState(computeMarginAndWidth(props));
+        }
+
+        if (stateRef.current.domain) {
+            const res = checkAndCorrectDomain({ domain: stateRef.current.domain });
+            const { maxZoom, minZoom, domain, domainHasChanged, minTime, maxTime } = res;
+            if (maxZoom !== stateRef.current.maxZoom || minZoom !== stateRef.current.minZoom) {
+                patchState({
+                    maxZoom, minZoom, minTime, maxTime,
+                    domain: domainHasChanged ? domain : stateRef.current.domain,
+                });
+                if (domainHasChanged) {
+                    const newDomains = [domain, ...propsRef.current.domains.slice(1)];
+                    propsRef.current.onUpdateDomains(newDomains);
+                }
+            }
+        }
+        prevWidthRef.current = props.width;
+        prevMarginRef.current = props.margin;
+    }, [props.width, props.margin, getItems, patchState, checkAndCorrectDomain]);
+
+    // timeSpan change
+    const prevTimeSpanRef = useRef(props.timeSpan);
+    useEffect(() => {
+        const prev = prevTimeSpanRef.current;
+        if (prev.start.isSame(props.timeSpan.start) && prev.stop.isSame(props.timeSpan.stop)) {
+            return;
+        }
+        const newDomains = shiftDomainsPure(props.domains, {
+            min: props.timeSpan.start,
+            max: props.timeSpan.stop,
+        }, props.biggestVisibleDomain);
+        if (newDomains !== props.domains) {
+            props.onUpdateDomains(newDomains);
+        }
+        patchState({ start: props.timeSpan.start, stop: props.timeSpan.stop });
+        prevTimeSpanRef.current = props.timeSpan;
+    }, [props.timeSpan, props.domains, props.biggestVisibleDomain, props, patchState]);
+
+    // Current domain change
+    const prevDomain0Ref = useRef(props.domains[0]);
+    useEffect(() => {
+        const prev = prevDomain0Ref.current;
+        const curr = props.domains[0];
+        const changed =
+            (!prev && curr) ||
+            (prev && curr && (!prev.min.isSame(curr.min) || !prev.max.isSame(curr.max)));
+        if (!changed) {
+            prevDomain0Ref.current = curr;
+            return;
+        }
+        const res = checkAndCorrectDomain({ domain: curr });
+        const { maxZoom, minZoom, domain, domainHasChanged, minTime, maxTime } = res;
+        patchState({ maxZoom, minZoom, minTime, maxTime, domain });
+        if (domainHasChanged) {
+            const newDomains = [domain, ...propsRef.current.domains.slice(1)];
+            propsRef.current.onUpdateDomains(newDomains);
+        } else {
+            getItems(propsRef.current, domain);
+        }
+        prevDomain0Ref.current = curr;
+    }, [props.domains, checkAndCorrectDomain, getItems, patchState]);
+
+    // histo change
+    const prevHistoRef = useRef(props.histo);
+    useEffect(() => {
+        if (prevHistoRef.current !== props.histo) {
+            patchState({ waitForLoad: false });
+            prevHistoRef.current = props.histo;
+        }
+    }, [props.histo, patchState]);
+
+    // legend change → recompute margin
+    const prevLegendsRef = useRef(props.metricsDefinition.legends);
+    useEffect(() => {
+        if (prevLegendsRef.current !== props.metricsDefinition.legends) {
+            patchState(computeMarginAndWidth(propsRef.current));
+            prevLegendsRef.current = props.metricsDefinition.legends;
+        }
+    }, [props.metricsDefinition.legends, patchState]);
+
+    // --- Prepare vertical scale + histogram (render helpers) ----------------
+
+    const prepareVerticalScale = useCallback(() => {
+        const items = histo && histo.items;
+        const s = stateRef.current;
+        const maxHeight =
+            height - s.margin.bottom - s.margin.top - (xAxisProp.height || xAxisDefault.height);
+        const maxScale = items ? (_max(items.map((i: any) => i.total)) as number) || 0 : 0;
+        const verticalScale = scaleLinear().domain([0, maxScale]).range([0, maxHeight]);
+        const verticalMarks =
+            yAxisProp.spaceBetweenTicks && maxHeight > yAxisProp.spaceBetweenTicks * 2
+                ? verticalScale.ticks(_floor(maxHeight / yAxisProp.spaceBetweenTicks))
+                : [maxScale];
+        return { verticalScale, verticalMarks, maxHeight };
+    }, [histo, height, xAxisProp, yAxisProp]);
+
+    const prepareHistogram = useCallback((args: { domain: any; verticalScale: any }) => {
+        const { domain, verticalScale } = args;
+        const xAxis = xAxisRef.current;
+        if (histo && histo.items && domain && xAxis) {
+            const { min, max } = domain;
+            return histo.items
+                .filter((item: any) =>
+                    item.total > 0 && item.time.isSameOrAfter(min) && item.time.isBefore(max),
+                )
+                .map((item: any) => {
+                    const start = moment(item.time);
+                    const end = moment(item.time).add(histo.intervalMs);
+                    return {
+                        x1: xAxis(start),
+                        x2: xAxis(end),
+                        start, end,
+                        metrics: item.metrics,
+                        total: item.total,
+                        height: verticalScale(item.total),
+                    };
+                });
+        }
+        return [];
+    }, [histo]);
+
+    // --- Cursor / drag / zoom handlers (former instance methods) ------------
+
+    const setAutoMove = useCallback((active: boolean, action?: any, delta?: number) => {
+        if (active) {
+            if (
+                !autoMoveRef.current ||
+                (autoMoveRef.current && Math.abs(lastAutoMovingDeltaRef.current - (delta ?? 0)) > 5)
+            ) {
+                if (autoMoveRef.current) clearInterval(autoMoveRef.current);
+                autoMoveRef.current = setInterval(() => {
+                    action(delta);
+                    moveTimeLine(-(delta ?? 0));
+                    isAutoMovingRef.current = true;
+                    lastAutoMovingDeltaRef.current = delta ?? 0;
+                }, 30);
+            }
+        } else {
+            if (autoMoveRef.current) clearInterval(autoMoveRef.current);
+            autoMoveRef.current = null;
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    const handleAutoSliding = useCallback((mouse: any, action: any) => {
+        if (!mouse) return;
+        const posX = mouse[0];
+        const s = stateRef.current;
+        if (posX < 0) setAutoMove(true, action, posX);
+        else if (posX >= 0 && posX <= s.histoWidth) setAutoMove(false);
+        else if (posX > s.histoWidth) setAutoMove(true, action, posX - s.histoWidth);
+    }, [setAutoMove]);
+
+    const movedTimeLine = useCallback(() => {
+        movedSinceLastFetchedRef.current = 0;
+        const domain = stateRef.current.domain;
+        const p = propsRef.current;
+        const domains = [domain, ...p.domains.slice(1)];
+        const newDomains = shiftDomainsPure(domains, domain, p.biggestVisibleDomain);
+        p.onUpdateDomains(newDomains);
+    }, []);
+
+    const stopAutoMove = useCallback(() => {
+        if (autoMoveRef.current) setAutoMove(false);
+        if (isAutoMovingRef.current) {
+            isAutoMovingRef.current = false;
+            movedTimeLine();
+        }
+    }, [setAutoMove, movedTimeLine]);
+
+    const moveTimeLineCore = useCallback((delta: number) => {
+        const p = propsRef.current;
+        const s = stateRef.current;
+        const { maxDomain, onShowMessage } = p;
+        let { domain: currentDomain, minTime = false, maxTime = false } = s;
+        const currentSpan = currentDomain.max.diff(currentDomain.min);
+
+        if ((minTime && delta > 0) || (maxTime && delta < 0)) {
+            return { ...currentDomain, moved: 0, minTime, maxTime };
+        }
+        const xAxis = xAxisRef.current;
+        let min = moment(xAxis.invert(-delta));
+        let max = moment(xAxis.invert(s.histoWidth - delta));
+        let moved = delta;
+
+        if (maxDomain.min && min.isBefore(maxDomain.min)) {
+            moved = xAxis(maxDomain.min);
+            min = moment(maxDomain.min);
+            max = moment(min).add(currentSpan);
+            minTime = true;
+            onShowMessage(labelsRef.current.minDomainMsg);
+        }
+        if (maxDomain.max && max.isAfter(maxDomain.max)) {
+            moved = xAxis(maxDomain.max);
+            max = moment(maxDomain.max);
+            min = moment(max).subtract(currentSpan);
+            maxTime = true;
+            onShowMessage(labelsRef.current.maxDomainMsg);
+        }
+        return { min, max, moved, minTime, maxTime };
+    }, []);
+
+    const moveTimeLine = useCallback((delta: number) => {
+        const xAxis = xAxisRef.current;
+        xAxis.clamp(false);
+        const { min, max, moved, minTime, maxTime } = moveTimeLineCore(delta);
+        if (moved !== 0) {
+            xAxis.domain([min, max]);
+            xAxis.clamp(true);
+            const p = propsRef.current;
+            const s = stateRef.current;
+            const ticks = xAxis.ticks(_floor(s.histoWidth / p.xAxis.spaceBetweenTicks));
+            movedSinceLastFetchedRef.current += moved;
+            if (Math.abs(movedSinceLastFetchedRef.current) > 75 && p.fetchWhileSliding) {
+                movedSinceLastFetchedRef.current = 0;
+                getItems(p, { min, max });
+            }
+            patchState({ domain: { min, max }, minTime, maxTime, ticks });
+        }
+    }, [moveTimeLineCore, getItems, patchState]);
+
+    const onResizeLeftCursor = useCallback((delta: number, mouse: any) => {
+        const xAxis = xAxisRef.current;
+        const s = stateRef.current;
+        const p = propsRef.current;
+        let newStart = moment(xAxis.invert(xAxis(s.start) + delta));
+        let newStop = s.stop;
+        let maxTimespan = false;
+        if (newStart.isSameOrAfter(newStop)) {
+            newStop = moment(xAxis.invert(xAxis(newStop) + delta));
+        }
+        if (p.biggestTimeSpan) {
+            const min = moment(newStop).subtract(p.biggestTimeSpan);
+            if (min.isSameOrAfter(newStart)) {
+                newStart = min;
+                maxTimespan = true;
+            }
+        }
+        handleAutoSliding(mouse, onResizeLeftCursor);
+        if (
+            (newStop !== s.stop && newStop.isSameOrBefore(s.domain.max)) ||
+            newStart.isSameOrAfter(s.domain.min)
+        ) {
+            patchState({ start: newStart, stop: newStop, maxTimespan });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [handleAutoSliding, patchState]);
+
+    const onResizeRightCursor = useCallback((delta: number, mouse: any) => {
+        const xAxis = xAxisRef.current;
+        const s = stateRef.current;
+        const p = propsRef.current;
+        let newStop = moment(xAxis.invert(xAxis(s.stop) + delta));
+        let newStart = s.start;
+        let maxTimespan = false;
+        if (newStop.isSameOrBefore(newStart)) {
+            newStart = moment(xAxis.invert(xAxis(newStart) + delta));
+        }
+        if (p.biggestTimeSpan) {
+            const max = moment(newStart).add(p.biggestTimeSpan);
+            if (max.isSameOrBefore(newStop)) {
+                newStop = max;
+                maxTimespan = true;
+            }
+        }
+        handleAutoSliding(mouse, onResizeRightCursor);
+        if (newStop.isSameOrBefore(s.domain.max) && newStart.isSameOrAfter(s.domain.min)) {
+            patchState({ start: newStart, stop: newStop, maxTimespan });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [handleAutoSliding, patchState]);
+
+    const onDragCursor = useCallback((delta: number, mouse: any) => {
+        const xAxis = xAxisRef.current;
+        const s = stateRef.current;
+        const p = propsRef.current;
+        xAxis.clamp(false);
+        const duration = s.stop.diff(s.start);
+        let newStart = moment(xAxis.invert(xAxis(s.start) + delta));
+        let newStop = moment(newStart).add(duration, 'milliseconds');
+        xAxis.clamp(true);
+        const { maxDomain } = p;
+        if (maxDomain.min && newStart.isBefore(maxDomain.min)) newStart = moment(maxDomain.min);
+        if (maxDomain.max && newStop.isAfter(maxDomain.max)) newStop = moment(maxDomain.max);
+        handleAutoSliding(mouse, onDragCursor);
+        patchState({ start: newStart, stop: newStop });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [handleAutoSliding, patchState]);
+
+    const onStartDrawCursor = useCallback((pos: number) => {
+        const xAxis = xAxisRef.current;
+        patchState({
+            start: moment(xAxis.invert(pos)),
+            stop: moment(xAxis.invert(pos + 1)),
+            maxTimespan: false,
+        });
+    }, [patchState]);
+
+    const onDrawCursor = useCallback((delta: number, mouse: any) => {
+        const xAxis = xAxisRef.current;
+        const s = stateRef.current;
+        const p = propsRef.current;
+        let newStop = moment(xAxis.invert(xAxis(s.stop) + delta));
+        let newStart = s.start;
+        let maxTimespan = false;
+        if (newStop.isSameOrBefore(newStart)) {
+            newStart = moment(xAxis.invert(xAxis(newStart) + delta));
+        }
+        if (p.biggestTimeSpan) {
+            const max = moment(newStart).add(p.biggestTimeSpan);
+            if (max.isSameOrBefore(newStop)) {
+                newStop = max;
+                maxTimespan = true;
+            }
+        }
+        handleAutoSliding(mouse, onDrawCursor);
+        if (newStop.isSameOrBefore(s.domain.max) && newStart.isSameOrAfter(s.domain.min)) {
+            patchState({ start: newStart, stop: newStop, maxTimespan });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [handleAutoSliding, patchState]);
+
+    const onEndDrawCursor = useCallback(() => {
+        stopAutoMove();
+        const { onCustomRange, selectBarOnClick } = propsRef.current;
+        const s = stateRef.current;
+        let { start, stop, barHovered } = s;
+        if (selectBarOnClick && itemsRef.current && barHovered > -1) {
+            const item = itemsRef.current[barHovered];
+            if (start.isSameOrAfter(item.start) && stop.isSameOrBefore(item.end)) {
+                start = moment(item.start);
+                stop = moment(item.end);
+                patchState({ start, stop });
+            }
+        }
+        onCustomRange(start, stop);
+    }, [stopAutoMove, patchState]);
+
+    const onEndChangeCursor = useCallback(() => {
+        stopAutoMove();
+        const { onCustomRange } = propsRef.current;
+        const { start, stop } = stateRef.current;
+        onCustomRange(start, stop);
+    }, [stopAutoMove]);
+
+    const zoomOnDomain = useCallback((targetDomain: any) => {
+        const p = propsRef.current;
+        const s = stateRef.current;
+        if (s.waitForLoad) return;
+        if (targetDomain.min.isSame(s.domain.min) && targetDomain.max.isSame(s.domain.max)) {
+            p.onShowMessage(labelsRef.current.zoomInWithoutChangingSelectionMsg);
+            return;
+        }
+        const { maxZoom, domain } = checkAndCorrectDomain({ domain: targetDomain });
+        const { maxZoom: currentMaxZoom } = s;
+        if (maxZoom && maxZoom !== currentMaxZoom) {
+            p.onShowMessage(labelsRef.current.zoomSelectionResolutionExtended);
+        }
+        const domains = [domain, ...p.domains];
+        patchState({ maxZoom, minZoom: false, domain });
+        p.onUpdateDomains(domains);
+    }, [checkAndCorrectDomain, patchState]);
+
+    const zoomOutTo = useCallback((domains: any[]) => {
+        const res = checkAndCorrectDomain({ domain: domains[0] });
+        const { minZoom, domain, domainHasChanged, maxTime, minTime } = res;
+        const p = propsRef.current;
+        if (minZoom) p.onShowMessage(labelsRef.current.minZoomMsg);
+        if (minTime) p.onShowMessage(labelsRef.current.minDomainMsg);
+        if (maxTime) p.onShowMessage(labelsRef.current.maxDomainMsg);
+        const newDomains = domainHasChanged ? [domain, ...p.domains.slice(1)] : domains;
+        patchState({ maxZoom: false, minZoom, domain });
+        p.onUpdateDomains(newDomains);
+    }, [checkAndCorrectDomain, patchState]);
+
+    const zoomOnTarget = useCallback((x: number) => {
+        const xAxis = xAxisRef.current;
+        const [minOrigin, maxOrigin] = xAxis.domain();
+        const target = moment(xAxis.invert(x));
+        const min = moment(target).subtract(0.25 * target.diff(moment(minOrigin)));
+        const max = moment(target).add(0.25 * moment(maxOrigin).diff(target));
+        zoomOnDomain({ min, max });
+    }, [zoomOnDomain]);
+
+    const zoomOutOfTarget = useCallback((x: number) => {
+        const xAxis = xAxisRef.current;
+        const [minOrigin, maxOrigin] = xAxis.domain();
+        const target = moment(xAxis.invert(x));
+        const min = moment(target).subtract(1.25 * target.diff(moment(minOrigin)));
+        const max = moment(target).add(1.25 * moment(maxOrigin).diff(target));
+        zoomOutTo([{ min, max }]);
+    }, [zoomOutTo]);
+
+    const zoomIn = useCallback(() => {
+        const s = stateRef.current;
+        if (!s.maxZoom) {
+            zoomOnDomain({ min: s.start, max: s.stop });
+        } else {
+            propsRef.current.onShowMessage(labelsRef.current.doubleClickMaxZoomMsg);
+        }
+    }, [zoomOnDomain]);
+
+    const zoomOut = useCallback(() => {
+        const s = stateRef.current;
+        if (s.waitForLoad || s.minZoom) return;
+        const p = propsRef.current;
+        const domains = [...p.domains];
+        if (domains.length > 1) {
+            domains.shift();
+        } else {
+            const xAxis = xAxisRef.current;
+            const [minOrigin, maxOrigin] = xAxis.domain();
+            const halfDuration = moment(maxOrigin).diff(moment(minOrigin)) / 2;
+            const target = moment(minOrigin).add(halfDuration);
+            const zoomOutFactor = p.zoomOutFactor ?? defaultZoomOutFactor;
+            const min = moment(target).subtract(zoomOutFactor * halfDuration);
+            const max = moment(target).add(zoomOutFactor * halfDuration);
+            domains[0] = { min, max };
+        }
+        zoomOutTo(domains);
+    }, [zoomOutTo]);
+
+    const onWheel = useCallback((event: any) => {
+        const s = stateRef.current;
+        const p = propsRef.current;
+        event.stopPropagation();
+        const baseX = timelineElementRef.current?.getBoundingClientRect().left ?? 0;
+        const x = event.clientX - baseX - s.margin.left;
+        if (s.waitForLoad) return;
+        if (event.deltaY < -50) {
+            if (s.maxZoom) p.onShowMessage(labelsRef.current.scrollMaxZoomMsg);
+            else zoomOnTarget(x);
+        } else if (event.deltaY > 50) {
+            if (s.minZoom) p.onShowMessage(labelsRef.current.minZoomMsg);
+            else if (p.domains.length > 1) zoomOut();
+            else zoomOutOfTarget(x);
+        }
+    }, [zoomOnTarget, zoomOut, zoomOutOfTarget]);
+
+    const onGotoCursor = useCallback(() => {
+        const s = stateRef.current;
+        const p = propsRef.current;
+        const middle = moment(s.start).add(s.stop.diff(s.start) / 2);
+        const xAxis = xAxisRef.current;
+        xAxis.clamp(false);
+        const currentX = s.histoWidth / 2;
+        const newX = xAxis(middle);
+        const newDomain = moveTimeLineCore(currentX - newX);
+        const domains = [...p.domains];
+        domains.splice(0, 1, newDomain);
+        const newDomains = shiftDomainsPure(domains, newDomain, p.biggestVisibleDomain);
+        p.onUpdateDomains(newDomains);
+        xAxis.clamp(true);
+    }, [moveTimeLineCore]);
+
+    const onGoto = useCallback((d: any) => {
+        const s = stateRef.current;
+        const p = propsRef.current;
+        const halfTimeAgg = s.stop.diff(s.start) / 2;
+        const when = d || moment();
+        const newStop = moment(when).add(halfTimeAgg);
+        const newStart = moment(when).subtract(halfTimeAgg);
+        p.onCustomRange(newStart, newStop);
+    }, []);
+
+    const shiftTimeLine = useCallback((delta: number) => {
+        const incr = (delta / Math.abs(delta)) * 8;
+        let i = 0;
+        function step() {
+            moveTimeLine(incr);
+            i += 8;
+            if (i < Math.abs(delta)) setTimeout(step, 10);
+            else movedTimeLine();
+        }
+        step();
+    }, [moveTimeLine, movedTimeLine]);
+
+    // --- Cleanup on unmount -------------------------------------------------
+
+    useEffect(() => () => {
+        if (autoMoveRef.current) clearInterval(autoMoveRef.current);
+    }, []);
+
+    // --- Imperative handle --------------------------------------------------
+
+    useImperativeHandle(ref, () => ({ zoomIn, zoomOut, shiftTimeLine }), [zoomIn, zoomOut, shiftTimeLine]);
+
+    // --- Render -------------------------------------------------------------
+
+    const { isActive, domain, histoWidth, margin, start, stop, maxZoom, minZoom,
+            maxTimespan, barHovered, tooltipVisible, ticks, dragging } = state;
+
+    const xAxisHeight = xAxisProp.height || xAxisDefault.height;
+    const pointZero = { x: 0, y: height - margin.bottom - xAxisHeight };
+    const originCursor = { x: 0, y: margin.top - 5 };
+
+    if (!isFunction(xAxisRef.current)) return null;
+
+    const { verticalScale, verticalMarks, maxHeight } = prepareVerticalScale();
+    const items = prepareHistogram({ domain, verticalScale });
+    itemsRef.current = items;
+
+    return (
+        <svg
+            ref={timelineElementRef}
+            width={width}
+            height={height}
+            onWheel={isActive ? onWheel : undefined}
+        >
+            <g transform={`translate(${margin.left},${margin.top})`}>
+                {yAxisProp.showGrid && (
+                    <YGrid classes={classes} origin={pointZero} yAxis={verticalScale}
+                           marks={verticalMarks} xAxisWidth={histoWidth + 13} />
+                )}
+                {xAxisProp.showGrid && (
+                    <XGrid classes={classes} origin={pointZero} xAxis={xAxisRef.current}
+                           marks={ticks} yAxisHeight={maxHeight} />
+                )}
+                {isActive && (
+                    <Histogram classes={classes} origin={pointZero} items={items} histo={histo}
+                               verticalScale={verticalScale} metricsDefinition={metricsDefinition}
+                               barHovered={barHovered} dragging={dragging}
+                               tooltipVisible={tooltipVisible}
+                               onFormatTimeToolTips={onFormatTimeToolTips}
+                               onFormatMetricLegend={onFormatMetricLegend}
+                               HistoToolTip={HistoToolTip} />
+                )}
+                <XAxis classes={classes} origin={pointZero} axisWidth={histoWidth + 13}
+                       min={domain && domain.min} max={domain && domain.max}
+                       xAxis={xAxisRef.current} marks={ticks}
+                       arrowPath={xAxisProp.arrowPath} yAxisHeight={maxHeight}
+                       showGrid={xAxisProp.showGrid} onFormatTimeLegend={onFormatTimeLegend} />
+                <Tools classes={classes} rcToolTipPrefixCls={rcToolTipPrefixCls} origin={pointZero}
+                       histoWidth={histoWidth} isActive={isActive} tools={tools}
+                       labels={labelsRef.current} onGoto={onGoto}
+                       onResetTime={onResetTime} shiftTimeLine={shiftTimeLine} />
+                <YAxis classes={classes} origin={pointZero} maxHeight={maxHeight}
+                       yAxis={verticalScale} marks={verticalMarks}
+                       arrowPath={yAxisProp.arrowPath} showGrid={yAxisProp.showGrid}
+                       xAxisWidth={histoWidth + 13} onFormatMetricLegend={onFormatMetricLegend} />
+                {showLegend && (
+                    <Legend classes={classes}
+                            origin={{ x: -5, y: margin.top + 2 }}
+                            metricsDefinition={metricsDefinition} />
+                )}
+                {isActive && tools.cursor !== false && (
+                    <Cursor
+                        origin={originCursor} rcToolTipPrefixCls={rcToolTipPrefixCls} classes={classes}
+                        startPos={xAxisRef.current(start)}
+                        startIsOutOfView={start.isBefore(domain.min) || start.isAfter(domain.max)}
+                        endPos={xAxisRef.current(stop)}
+                        endIsOutOfView={stop.isBefore(domain.min) || stop.isAfter(domain.max)}
+                        cursorIsBeforeView={start.isBefore(domain.min) && stop.isBefore(domain.min)}
+                        cursorIsAfterView={start.isAfter(domain.max) && stop.isAfter(domain.max)}
+                        height={maxHeight} overlayHeight={height - margin.top} overlayWidth={histoWidth}
+                        tooltipVisible={tooltipVisible} barHovered={barHovered}
+                        setToolTipVisible={(v: boolean) => patchState({ tooltipVisible: v })}
+                        setBarHovered={(b: any) => patchState({ barHovered: b })}
+                        items={items} showHistoToolTip={showHistoToolTip}
+                        dragging={dragging}
+                        setDragging={(d: any) => patchState({ dragging: d })}
+                        canZoom={true} minZoom={minZoom} maxZoom={maxZoom}
+                        startText={onFormatTimeToolTips(start)} stopText={onFormatTimeToolTips(stop)}
+                        maxSize={maxTimespan} tools={tools}
+                        gotoCursorLabel={labelsRef.current.gotoCursor}
+                        zoomInLabel={labelsRef.current.zoomInLabel}
+                        zoomOutLabel={labelsRef.current.zoomOutLabel}
+                        zoomIn={zoomIn} zoomOut={zoomOut}
+                        onResizeLeftCursor={onResizeLeftCursor}
+                        onResizeRightCursor={onResizeRightCursor}
+                        onEndResizeCursor={onEndChangeCursor}
+                        onDragCursor={onDragCursor} onEndDragCursor={onEndChangeCursor}
+                        onStartDrawCursor={onStartDrawCursor}
+                        onDrawCursor={onDrawCursor} onEndCursor={onEndDrawCursor}
+                        onMoveDomain={moveTimeLine} onMovedDomain={movedTimeLine}
+                        onGotoCursor={onGotoCursor}
+                    />
+                )}
+                {isActive && quality && quality.items && (
+                    <QualityLine classes={classes} rcToolTipPrefixCls={rcToolTipPrefixCls}
+                                 origin={pointZero} quality={quality} qualityScale={qualityScale}
+                                 xAxis={xAxisRef.current} />
+                )}
+            </g>
+        </svg>
+    );
+});
+
+const TimeLine = forwardRef<TimeLineHandle, any>(function TimeLineWrapper(props, ref) {
+    const zone: string | undefined = props.timeZone;
+
+    // Internal zoom-history stack (kept as moment-typed for the inner).
+    // Initial stack: single entry from props.domain (or empty if null).
+    const [stack, setStack] = useState<any[]>(() =>
+        props.domain ? [domainToMoments(props.domain, zone)] : []
+    );
+
+    // If the host updates `domain` (e.g. via URL / redux), sync the top of
+    // the stack — same identity if equal, replaced otherwise.
+    const prevDomainRef = useRef<any>(props.domain);
+    useEffect(() => {
+        if (prevDomainRef.current === props.domain) return;
+        prevDomainRef.current = props.domain;
+        if (!props.domain) {
+            setStack([]);
+            return;
+        }
+        const m = domainToMoments(props.domain, zone);
+        setStack((prev) => {
+            if (prev.length === 0) return [m];
+            const top = prev[0];
+            if (top.min.isSame(m.min) && top.max.isSame(m.max)) return prev;
+            return [m, ...prev.slice(1)];
+        });
+    }, [props.domain, zone]);
+
+    // onUpdateDomains is the inner's single source of truth for domain mutation.
+    // Intercept it, persist into `stack`, and report the top to the host.
+    const handleUpdateDomains = useCallback((newDomains: any[]) => {
+        setStack(newDomains);
+        const top = newDomains[0];
+        if (top && props.onDomainChange) {
+            props.onDomainChange({ min: top.min.toDate(), max: top.max.toDate() });
+        }
+    }, [props.onDomainChange]);
+
+    // onLoadDefaultDomain may now return Domain | Promise<Domain>.
+    // If it does, seed the stack + inform the host.
+    const handleLoadDefault = useCallback(() => {
+        const ret = props.onLoadDefaultDomain?.();
+        const apply = (d: any) => {
+            if (!d) return;
+            const m = domainToMoments(d, zone);
+            setStack([m]);
+            if (props.onDomainChange) {
+                props.onDomainChange({ min: m.min.toDate(), max: m.max.toDate() });
+            }
+        };
+        if (ret && typeof (ret as any).then === 'function') (ret as Promise<any>).then(apply);
+        else if (ret) apply(ret);
+    }, [props.onLoadDefaultDomain, props.onDomainChange, zone]);
+
+    // Build the moment-typed props the inner expects.
+    const innerProps: any = {
+        ...props,
+        domains: stack,
+        timeSpan: props.timeSpan ? timeSpanToMoments(props.timeSpan, zone) : undefined,
+        maxDomain: props.maxDomain ? domainToMoments(props.maxDomain, zone) : undefined,
+        histo: props.histo?.items
+            ? { ...props.histo, items: props.histo.items.map((it: any) => ({ ...it, time: toMoment(it.time, zone) })) }
+            : props.histo,
+        quality: props.quality?.items
+            ? { ...props.quality, items: props.quality.items.map((it: any) => ({ ...it, time: toMoment(it.time, zone) })) }
+            : props.quality,
+        biggestVisibleDomain: props.biggestVisibleDomain != null ? toDuration(props.biggestVisibleDomain) : undefined,
+        biggestTimeSpan: props.biggestTimeSpan != null ? toDuration(props.biggestTimeSpan) : undefined,
+        smallestResolution: props.smallestResolution != null ? toDuration(props.smallestResolution) : undefined,
+        onUpdateDomains: handleUpdateDomains,
+        onLoadDefaultDomain: handleLoadDefault,
+        // onLoadHisto: object shape + Date instants
+        onLoadHisto: props.onLoadHisto
+            ? (ms: number, start: any, end: any) =>
+                props.onLoadHisto({ intervalMs: ms, start: momentToDate(start)!, end: momentToDate(end)! })
+            : undefined,
+        // onCustomRange → onTimeSpanChange, object shape
+        onCustomRange: props.onTimeSpanChange
+            ? (start: any, stop: any) =>
+                props.onTimeSpanChange({ start: momentToDate(start)!, stop: momentToDate(stop)! })
+            : props.onCustomRange,
+        onFormatTimeToolTips: props.onFormatTimeToolTips
+            ? (t: any) => props.onFormatTimeToolTips(momentToDate(t))
+            : undefined,
+        onFormatTimeLegend: props.onFormatTimeLegend
+            ? (t: any) => props.onFormatTimeLegend(momentToDate(t))
+            : undefined,
+    };
+
+    return <TimeLineInner {...innerProps} ref={ref} />;
+});
+
+export default TimeLine;
+
+// --- Pure helpers (extracted so they can be called from constructor+runtime) ---
+
+function checkAndCorrectDomainPure({
+    domain, biggestVisibleDomain, maxDomain, smallestResolution, histoWidth,
+}: any) {
+    if (!domain) {
+        return { domain, maxZoom: false, minZoom: false, domainHasChanged: false };
+    }
+    const newDomain = { ...domain };
+    let domainHasChanged = false;
+    const duration = newDomain.max.diff(newDomain.min);
+    let maxZoom = false;
+    const minRes = smallestResolution.asMilliseconds();
+    if (duration <= (histoWidth * minRes) / 15) {
+        maxZoom = true;
+        newDomain.max = moment(newDomain.min).add((histoWidth * minRes) / 15, 'ms');
+    }
+    let minTime: boolean | undefined;
+    let maxTime: boolean | undefined;
+    if (maxDomain?.min && newDomain.min.isBefore(maxDomain.min)) {
+        newDomain.min = moment(maxDomain.min);
+        minTime = true;
+    }
+    if (maxDomain?.max && newDomain.max.isAfter(maxDomain.max)) {
+        newDomain.max = moment(maxDomain.max);
+        maxTime = true;
+    }
+    let minZoom = false;
+    if (biggestVisibleDomain && newDomain.max.isSameOrAfter(moment(newDomain.min).add(biggestVisibleDomain))) {
+        minZoom = true;
+        newDomain.min = moment(newDomain.max).subtract(biggestVisibleDomain);
+    }
+    if (!(newDomain.min.isSame(domain.min) && newDomain.max.isSame(domain.max))) {
+        domainHasChanged = true;
+    }
+    return {
+        domain: domainHasChanged ? newDomain : domain,
+        maxZoom, minZoom, maxTime, minTime, domainHasChanged,
+    };
+}
+
+function shiftDomainsPure(domains: any[], { min, max }: any, biggestVisibleDomain: any) {
+    let toUpdate = false;
+    const newDomains = domains.map((domain, index) => {
+        if ((min && min.isBefore(domain.min)) || (max && max.isAfter(domain.max))) {
+            toUpdate = true;
+            if (index === domains.length - 1) {
+                const newDomain: any = {
+                    min: min && min.isBefore(domain.min) ? min : domain.min,
+                    max: max && max.isAfter(domain.max) ? max : domain.max,
+                };
+                if (biggestVisibleDomain && moment(newDomain.min).add(biggestVisibleDomain).isSameOrBefore(newDomain.max)) {
+                    if (min.isBefore(domain.min)) newDomain.max = moment(min).add(biggestVisibleDomain);
+                    else newDomain.min = moment(max).subtract(biggestVisibleDomain);
+                }
+                return newDomain;
+            }
+            if (min && min.isBefore(domain.min)) {
+                return { min, max: moment(domain.max).subtract(domain.min.diff(min)) };
+            }
+            return { min: moment(domain.min).add(max.diff(domain.max)), max };
+        }
+        return domain;
+    });
+    return toUpdate ? newDomains : domains;
+}