@astral/ui 4.81.0 → 4.83.0

package/node/components/Onboarding/ui/hooks/useViewportSize/useViewportSize.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useViewportSize = void 0;
+const react_1 = require("react");
+const geometry_1 = require("../../../utils/geometry");
+/**
+ * Синхронизирует размеры viewport без полос прокрутки окна.
+ */
+const useViewportSize = () => {
+    const [viewport, setViewport] = (0, react_1.useState)(geometry_1.getViewport);
+    (0, react_1.useEffect)(() => {
+        const handleResize = () => setViewport((0, geometry_1.getViewport)());
+        window.addEventListener('resize', handleResize);
+        return () => window.removeEventListener('resize', handleResize);
+    }, []);
+    return viewport;
+};
+exports.useViewportSize = useViewportSize;

package/node/components/Onboarding/ui/styles.d.ts

@@ -0,0 +1,5 @@
+import type { Theme } from '../../theme/types';
+/**
+ * Каркас модальных поверхностей: прозрачный backdrop, приподнятый z-index.
+ */
+export declare const onboardingModalSurface: (theme: Theme) => import("@emotion/utils").SerializedStyles;

package/node/components/Onboarding/ui/styles.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onboardingModalSurface = void 0;
+const Backdrop_1 = require("@mui/material/Backdrop");
+const styled_1 = require("../../styled");
+const constants_1 = require("../constants");
+/**
+ * Каркас модальных поверхностей: прозрачный backdrop, приподнятый z-index.
+ */
+const onboardingModalSurface = (theme) => (0, styled_1.css) `
+  && {
+    z-index: ${theme.zIndex.tooltip + constants_1.ONBOARDING_Z_INDEX_OFFSET.base};
+  }
+
+  && .${Backdrop_1.backdropClasses.root} {
+    background-color: transparent;
+  }
+`;
+exports.onboardingModalSurface = onboardingModalSurface;

package/node/components/Onboarding/utils/createVirtualAnchor/createVirtualAnchor.d.ts

@@ -0,0 +1,12 @@
+import { type Rect } from '../geometry';
+/**
+ * Виртуальный anchor для NewPopover — объект с `getBoundingClientRect`,
+ * который MUI Popper внутри NewPopover принимает вместо реального узла.
+ */
+export type VirtualAnchor = {
+    getBoundingClientRect: () => DOMRect;
+};
+/**
+ * Превращает область hole в anchor для позиционирования popover.
+ */
+export declare const createVirtualAnchor: (hole: Rect) => VirtualAnchor;

package/node/components/Onboarding/utils/createVirtualAnchor/createVirtualAnchor.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVirtualAnchor = void 0;
+/**
+ * Превращает область hole в anchor для позиционирования popover.
+ */
+const createVirtualAnchor = (hole) => ({
+    getBoundingClientRect: () => new DOMRect(hole.x, hole.y, hole.width, hole.height),
+});
+exports.createVirtualAnchor = createVirtualAnchor;

package/node/components/Onboarding/utils/createVirtualAnchor/index.d.ts

@@ -0,0 +1 @@
+export * from './createVirtualAnchor';

package/node/components/Onboarding/utils/createVirtualAnchor/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./createVirtualAnchor"), exports);

package/node/components/Onboarding/utils/geometry/index.d.ts

@@ -0,0 +1,4 @@
+export * from './overlayPath';
+export * from './parseOffset';
+export * from './rect';
+export * from './viewport';

package/node/components/Onboarding/utils/geometry/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./overlayPath"), exports);
+__exportStar(require("./parseOffset"), exports);
+__exportStar(require("./rect"), exports);
+__exportStar(require("./viewport"), exports);

package/node/components/Onboarding/utils/geometry/overlayPath/index.d.ts

@@ -0,0 +1 @@
+export { buildOverlayPath } from './overlayPath';

package/node/components/Onboarding/utils/geometry/overlayPath/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOverlayPath = void 0;
+var overlayPath_1 = require("./overlayPath");
+Object.defineProperty(exports, "buildOverlayPath", { enumerable: true, get: function () { return overlayPath_1.buildOverlayPath; } });

package/node/components/Onboarding/utils/geometry/overlayPath/overlayPath.d.ts

@@ -0,0 +1,6 @@
+import { type Rect } from '../rect';
+import { type Viewport } from '../viewport';
+/**
+ * SVG-путь overlay: viewport + hole-отверстие.
+ */
+export declare const buildOverlayPath: (viewport: Viewport, hole: Rect | null, radius: number) => string;

package/node/components/Onboarding/utils/geometry/overlayPath/overlayPath.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOverlayPath = void 0;
+/**
+ * SVG-путь скруглённой области (по часовой стрелке).
+ */
+const roundedRectPath = (rect, radius) => {
+    const r = Math.max(0, Math.min(radius, rect.width / 2, rect.height / 2));
+    const { x, y, width, height } = rect;
+    return [
+        `M${x + r},${y}`,
+        `H${x + width - r}`,
+        `A${r},${r} 0 0 1 ${x + width},${y + r}`,
+        `V${y + height - r}`,
+        `A${r},${r} 0 0 1 ${x + width - r},${y + height}`,
+        `H${x + r}`,
+        `A${r},${r} 0 0 1 ${x},${y + height - r}`,
+        `V${y + r}`,
+        `A${r},${r} 0 0 1 ${x + r},${y}`,
+        'Z',
+    ].join(' ');
+};
+/**
+ * SVG-путь overlay: viewport + hole-отверстие.
+ */
+const buildOverlayPath = (viewport, hole, radius) => {
+    const outer = `M0,0 H${viewport.width} V${viewport.height} H0 Z`;
+    if (!hole) {
+        return outer;
+    }
+    return `${outer} ${roundedRectPath(hole, radius)}`;
+};
+exports.buildOverlayPath = buildOverlayPath;

package/node/components/Onboarding/utils/geometry/parseOffset/index.d.ts

@@ -0,0 +1 @@
+export { parseOffset } from './parseOffset';

package/node/components/Onboarding/utils/geometry/parseOffset/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOffset = void 0;
+var parseOffset_1 = require("./parseOffset");
+Object.defineProperty(exports, "parseOffset", { enumerable: true, get: function () { return parseOffset_1.parseOffset; } });

package/node/components/Onboarding/utils/geometry/parseOffset/parseOffset.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Парсит `highlightOffset` вида `'4px'` в число.
+ */
+export declare const parseOffset: (offset?: `${number}px`) => number;

package/node/components/Onboarding/utils/geometry/parseOffset/parseOffset.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOffset = void 0;
+const constants_1 = require("../../../constants");
+/**
+ * Парсит `highlightOffset` вида `'4px'` в число.
+ */
+const parseOffset = (offset) => offset ? Number.parseFloat(offset) : constants_1.DEFAULT_HIGHLIGHT_PADDING;
+exports.parseOffset = parseOffset;

package/node/components/Onboarding/utils/geometry/rect/index.d.ts

@@ -0,0 +1,2 @@
+export { clampToScrollParents, clampToViewport, inflateRect, isSameRect, rectFromDomRect, } from './rect';
+export type { Rect } from './rect';

package/node/components/Onboarding/utils/geometry/rect/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rectFromDomRect = exports.isSameRect = exports.inflateRect = exports.clampToViewport = exports.clampToScrollParents = void 0;
+var rect_1 = require("./rect");
+Object.defineProperty(exports, "clampToScrollParents", { enumerable: true, get: function () { return rect_1.clampToScrollParents; } });
+Object.defineProperty(exports, "clampToViewport", { enumerable: true, get: function () { return rect_1.clampToViewport; } });
+Object.defineProperty(exports, "inflateRect", { enumerable: true, get: function () { return rect_1.inflateRect; } });
+Object.defineProperty(exports, "isSameRect", { enumerable: true, get: function () { return rect_1.isSameRect; } });
+Object.defineProperty(exports, "rectFromDomRect", { enumerable: true, get: function () { return rect_1.rectFromDomRect; } });

package/node/components/Onboarding/utils/geometry/rect/rect.d.ts

@@ -0,0 +1,34 @@
+import { type Viewport } from '../viewport';
+/**
+ * Область hole/элемента в координатах viewport.
+ */
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Приводит нативный `DOMRect` к нашему `Rect` (только позиция и размеры).
+ */
+export declare const rectFromDomRect: (domRect: DOMRect) => Rect;
+/**
+ * Равны ли области покомпонентно.
+ */
+export declare const isSameRect: (a: Rect | null, b: Rect) => boolean;
+/**
+ * Расширяет область на padding во все стороны.
+ */
+export declare const inflateRect: (rect: Rect, padding: number) => Rect;
+/**
+ * Обрезает область hole по границам viewport.
+ */
+export declare const clampToViewport: (rect: Rect, viewport: Viewport) => Rect;
+export declare const isViewportSizedRect: (rect: Rect, viewport: Viewport) => boolean;
+/**
+ * Обрезает область элемента видимой областью каждого scroll-предка.
+ * Если элемент лежит во вложенном scroll-контейнере и частично уехал за его
+ * границу — и hole overlay, и якорь popover считаются уже по видимой
+ * части, а не по полной области элемента.
+ */
+export declare const clampToScrollParents: (rect: Rect, scrollParents: readonly Rect[], viewport: Viewport) => Rect;

package/node/components/Onboarding/utils/geometry/rect/rect.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampToScrollParents = exports.isViewportSizedRect = exports.clampToViewport = exports.inflateRect = exports.isSameRect = exports.rectFromDomRect = void 0;
+/**
+ * Приводит нативный `DOMRect` к нашему `Rect` (только позиция и размеры).
+ */
+const rectFromDomRect = (domRect) => ({
+    x: domRect.left,
+    y: domRect.top,
+    width: domRect.width,
+    height: domRect.height,
+});
+exports.rectFromDomRect = rectFromDomRect;
+/**
+ * Равны ли области покомпонентно.
+ */
+const isSameRect = (a, b) => a !== null &&
+    a.x === b.x &&
+    a.y === b.y &&
+    a.width === b.width &&
+    a.height === b.height;
+exports.isSameRect = isSameRect;
+/**
+ * Расширяет область на padding во все стороны.
+ */
+const inflateRect = (rect, padding) => ({
+    x: rect.x - padding,
+    y: rect.y - padding,
+    width: rect.width + padding * 2,
+    height: rect.height + padding * 2,
+});
+exports.inflateRect = inflateRect;
+/**
+ * Пересечение двух областей. Не пересекаются — ширина/высота 0.
+ */
+const intersectRect = (a, b) => {
+    const x = Math.max(a.x, b.x);
+    const y = Math.max(a.y, b.y);
+    const right = Math.min(a.x + a.width, b.x + b.width);
+    const bottom = Math.min(a.y + a.height, b.y + b.height);
+    return {
+        x,
+        y,
+        width: Math.max(0, right - x),
+        height: Math.max(0, bottom - y),
+    };
+};
+/**
+ * Обрезает область hole по границам viewport.
+ */
+const clampToViewport = (rect, viewport) => intersectRect(rect, {
+    x: 0,
+    y: 0,
+    width: viewport.width,
+    height: viewport.height,
+});
+exports.clampToViewport = clampToViewport;
+const isViewportSizedRect = (rect, viewport) => rect.width >= viewport.width - 1 && rect.height >= viewport.height - 1;
+exports.isViewportSizedRect = isViewportSizedRect;
+/**
+ * Обрезает область элемента видимой областью каждого scroll-предка.
+ * Если элемент лежит во вложенном scroll-контейнере и частично уехал за его
+ * границу — и hole overlay, и якорь popover считаются уже по видимой
+ * части, а не по полной области элемента.
+ */
+const clampToScrollParents = (rect, scrollParents, viewport) => scrollParents
+    .filter((parent) => !(0, exports.isViewportSizedRect)(parent, viewport))
+    .reduce(intersectRect, rect);
+exports.clampToScrollParents = clampToScrollParents;

package/node/components/Onboarding/utils/geometry/viewport/index.d.ts

@@ -0,0 +1,2 @@
+export { getViewport } from './viewport';
+export type { Viewport } from './viewport';

package/node/components/Onboarding/utils/geometry/viewport/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getViewport = void 0;
+var viewport_1 = require("./viewport");
+Object.defineProperty(exports, "getViewport", { enumerable: true, get: function () { return viewport_1.getViewport; } });

package/node/components/Onboarding/utils/geometry/viewport/viewport.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Размеры viewport.
+ */
+export type Viewport = {
+    width: number;
+    height: number;
+};
+/**
+ * Текущие размеры viewport.
+ *
+ * Именно `documentElement.clientWidth/Height`, а не `window.innerWidth/Height`:
+ * inner-размеры включают полосы прокрутки окна.
+ */
+export declare const getViewport: () => Viewport;

package/node/components/Onboarding/utils/geometry/viewport/viewport.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getViewport = void 0;
+/**
+ * Текущие размеры viewport.
+ *
+ * Именно `documentElement.clientWidth/Height`, а не `window.innerWidth/Height`:
+ * inner-размеры включают полосы прокрутки окна.
+ */
+const getViewport = () => ({
+    width: document.documentElement.clientWidth,
+    height: document.documentElement.clientHeight,
+});
+exports.getViewport = getViewport;

package/node/components/Onboarding/utils/getScrollParents/getScrollParents.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Возвращает цепочку scroll-предков элемента (от ближайшего к корню).
+ *
+ * Нужна, чтобы прокручивать вложенные контейнеры и слушать их `scroll`
+ * для синхронизации hole overlay.
+ */
+export declare const getScrollParents: (element: Element | null) => HTMLElement[];

package/node/components/Onboarding/utils/getScrollParents/getScrollParents.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getScrollParents = void 0;
+/**
+ * Является ли элемент scroll-контейнером.
+ */
+const isScrollable = (element) => {
+    const { overflow, overflowX, overflowY } = getComputedStyle(element);
+    return /(auto|scroll|overlay)/.test(`${overflow}${overflowX}${overflowY}`);
+};
+/**
+ * Возвращает цепочку scroll-предков элемента (от ближайшего к корню).
+ *
+ * Нужна, чтобы прокручивать вложенные контейнеры и слушать их `scroll`
+ * для синхронизации hole overlay.
+ */
+const getScrollParents = (element) => {
+    const parents = [];
+    let node = element?.parentElement ?? null;
+    while (node && node !== document.body && node !== document.documentElement) {
+        if (isScrollable(node)) {
+            parents.push(node);
+        }
+        node = node.parentElement;
+    }
+    return parents;
+};
+exports.getScrollParents = getScrollParents;

package/node/components/Onboarding/utils/getScrollParents/index.d.ts

@@ -0,0 +1 @@
+export { getScrollParents } from './getScrollParents';

package/node/components/Onboarding/utils/getScrollParents/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getScrollParents = void 0;
+var getScrollParents_1 = require("./getScrollParents");
+Object.defineProperty(exports, "getScrollParents", { enumerable: true, get: function () { return getScrollParents_1.getScrollParents; } });

package/node/components/Onboarding/utils/getTargetElement/getTargetElement.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Находит элемент highlight-шага по `[data-tour-id="<stepName>"]`.
+ */
+export declare const getTargetElement: (stepName: string, root?: ParentNode) => HTMLElement | null;

package/node/components/Onboarding/utils/getTargetElement/getTargetElement.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTargetElement = void 0;
+const constants_1 = require("../../constants");
+/**
+ * Экранирует значение для безопасной подстановки в CSS-селектор атрибута.
+ */
+const escapeAttrValue = (value) => value.replace(/["\\]/g, '\\$&');
+/**
+ * Находит элемент highlight-шага по `[data-tour-id="<stepName>"]`.
+ */
+const getTargetElement = (stepName, root = document) => root.querySelector(`[${constants_1.TOUR_ID_ATTR}="${escapeAttrValue(stepName)}"]`);
+exports.getTargetElement = getTargetElement;

package/node/components/Onboarding/utils/getTargetElement/index.d.ts

@@ -0,0 +1 @@
+export { getTargetElement } from './getTargetElement';

package/node/components/Onboarding/utils/getTargetElement/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTargetElement = void 0;
+var getTargetElement_1 = require("./getTargetElement");
+Object.defineProperty(exports, "getTargetElement", { enumerable: true, get: function () { return getTargetElement_1.getTargetElement; } });

package/node/components/Onboarding/utils/observeRemoval/index.d.ts

@@ -0,0 +1 @@
+export * from './observeRemoval';

package/node/components/Onboarding/utils/observeRemoval/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./observeRemoval"), exports);

package/node/components/Onboarding/utils/observeRemoval/observeRemoval.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Следит за удалением элемента из DOM (размонтирование, условный render).
+ */
+export declare const observeRemoval: (element: HTMLElement, onRemoved: () => void) => VoidFunction;

package/node/components/Onboarding/utils/observeRemoval/observeRemoval.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observeRemoval = void 0;
+/**
+ * Следит за удалением элемента из DOM (размонтирование, условный render).
+ */
+const observeRemoval = (element, onRemoved) => {
+    const observer = new MutationObserver(() => {
+        if (!element.isConnected) {
+            observer.disconnect();
+            onRemoved();
+        }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    return () => observer.disconnect();
+};
+exports.observeRemoval = observeRemoval;

package/node/components/Onboarding/utils/scrollIntoView/index.d.ts

@@ -0,0 +1 @@
+export { scrollIntoView } from './scrollIntoView';

package/node/components/Onboarding/utils/scrollIntoView/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scrollIntoView = void 0;
+var scrollIntoView_1 = require("./scrollIntoView");
+Object.defineProperty(exports, "scrollIntoView", { enumerable: true, get: function () { return scrollIntoView_1.scrollIntoView; } });

package/node/components/Onboarding/utils/scrollIntoView/scrollIntoView.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Доводит элемент highlight-шага до центра viewport и ждёт, пока прокрутка
+ * реально доедет.
+ *
+ * Зачем: цель может быть за пределами экрана или внутри прокрученного
+ * контейнера — её надо показать, прежде чем подсвечивать. Нативный
+ * `scrollIntoView` сам прокручивает всю цепочку вложенных scroll-контейнеров.
+ *
+ * Почему ждём: прокрутка плавная (анимированная), позиция элемента меняется
+ * кадр за кадром. Дожидаемся её стабилизации, чтобы hole overlay и popover встали
+ * по финальной позиции, а не по промежуточной «едущей».
+ */
+export declare const scrollIntoView: (element: HTMLElement, behavior?: ScrollBehavior) => Promise<void>;

package/node/components/Onboarding/utils/scrollIntoView/scrollIntoView.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scrollIntoView = void 0;
+const constants_1 = require("../../constants");
+const geometry_1 = require("../geometry");
+const getScrollParents_1 = require("../getScrollParents");
+/**
+ * Сколько кадров подряд позиция не меняется, чтобы счесть прокрутку стабилизировавшейся.
+ */
+const STABLE_FRAMES = 3;
+/**
+ * Предохранитель: если позиция так и не стабилизировалась (постоянные
+ * layout-сдвиги), делаем resolve по тайм-ауту, чтобы Promise не завис и тур не застрял.
+ */
+const SETTLE_TIMEOUT_MS = 1000;
+/**
+ * Дожидается окончания плавной прокрутки.
+ *
+ * У браузера нет надёжного сигнала «плавная прокрутка доехала».
+ * Поэтому отслеживаем позицию элемента покадрово и считаем прокрутку
+ * законченной, когда `top` перестаёт меняться 3 кадра
+ * подряд — либо когда срабатывает предохранитель 1000мс.
+ */
+const waitForScrollSettle = (element) => new Promise((resolve) => {
+    let raf = 0;
+    let stableFrames = 0;
+    let prevTop = Number.NaN;
+    const timer = setTimeout(() => {
+        cancelAnimationFrame(raf);
+        resolve();
+    }, SETTLE_TIMEOUT_MS);
+    const tick = () => {
+        const { top } = element.getBoundingClientRect();
+        // Позиция не изменилась за кадр — копим «стабильные» кадры; дёрнулась —
+        // сбрасываем счётчик и запоминаем новую позицию.
+        if (top === prevTop) {
+            stableFrames += 1;
+        }
+        else {
+            stableFrames = 0;
+            prevTop = top;
+        }
+        // Достаточно кадров без движения → анимация закончилась.
+        if (stableFrames >= STABLE_FRAMES) {
+            clearTimeout(timer);
+            resolve();
+            return;
+        }
+        raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+});
+/**
+ * Элемент целиком видим: помещается и во viewport, и в рамки каждого своего
+ * scroll-предка.
+ */
+const isFullyVisible = (element) => {
+    const rect = element.getBoundingClientRect();
+    const { width, height } = (0, geometry_1.getViewport)();
+    const viewport = new DOMRect(0, 0, width, height);
+    const frames = [
+        viewport,
+        ...(0, getScrollParents_1.getScrollParents)(element).map((parent) => parent.getBoundingClientRect()),
+    ];
+    return frames.every((frame) => rect.top >= frame.top &&
+        rect.left >= frame.left &&
+        rect.bottom <= frame.bottom &&
+        rect.right <= frame.right);
+};
+/**
+ * Доводит элемент highlight-шага до центра viewport и ждёт, пока прокрутка
+ * реально доедет.
+ *
+ * Зачем: цель может быть за пределами экрана или внутри прокрученного
+ * контейнера — её надо показать, прежде чем подсвечивать. Нативный
+ * `scrollIntoView` сам прокручивает всю цепочку вложенных scroll-контейнеров.
+ *
+ * Почему ждём: прокрутка плавная (анимированная), позиция элемента меняется
+ * кадр за кадром. Дожидаемся её стабилизации, чтобы hole overlay и popover встали
+ * по финальной позиции, а не по промежуточной «едущей».
+ */
+const scrollIntoView = async (element, behavior = constants_1.SCROLL_BEHAVIOR) => {
+    if (isFullyVisible(element)) {
+        return;
+    }
+    element.scrollIntoView({ behavior, block: 'center', inline: 'center' });
+    await waitForScrollSettle(element);
+};
+exports.scrollIntoView = scrollIntoView;

package/node/components/Onboarding/utils/waitForElement/index.d.ts

@@ -0,0 +1,2 @@
+export { waitForElement } from './waitForElement';
+export type { WaitForElementOptions } from './waitForElement';

package/node/components/Onboarding/utils/waitForElement/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForElement = void 0;
+var waitForElement_1 = require("./waitForElement");
+Object.defineProperty(exports, "waitForElement", { enumerable: true, get: function () { return waitForElement_1.waitForElement; } });

package/node/components/Onboarding/utils/waitForElement/waitForElement.d.ts

@@ -0,0 +1,21 @@
+export type WaitForElementOptions = {
+    /**
+     * Тайм-аут ожидания, мс. `0` — не ждём: проверяем DOM синхронно и, если
+     * элемента нет, сразу делаем reject.
+     * @default 0
+     */
+    timeout?: number;
+    /**
+     * Корень для поиска и наблюдения за DOM.
+     * @default document
+     */
+    root?: Document | HTMLElement;
+};
+/**
+ * Дожидается появления элемента highlight-шага в DOM.
+ *
+ * Если элемент уже есть — синхронный resolve. При `timeout <= 0` ожидание
+ * отключено. Иначе подписывается через MutationObserver и resolve при появлении,
+ * либо reject по тайм-ауту.
+ */
+export declare const waitForElement: (stepName: string, { timeout, root, }?: WaitForElementOptions) => Promise<HTMLElement>;