@astral/ui 4.82.0 → 4.84.0

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>;

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

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForElement = void 0;
+const constants_1 = require("../../constants");
+const getTargetElement_1 = require("../getTargetElement");
+/**
+ * Дожидается появления элемента highlight-шага в DOM.
+ *
+ * Если элемент уже есть — синхронный resolve. При `timeout <= 0` ожидание
+ * отключено. Иначе подписывается через MutationObserver и resolve при появлении,
+ * либо reject по тайм-ауту.
+ */
+const waitForElement = (stepName, { timeout = constants_1.DEFAULT_WAIT_ELEMENT_TIMEOUT_MS, root = document, } = {}) => new Promise((resolve, reject) => {
+    const existing = (0, getTargetElement_1.getTargetElement)(stepName, root);
+    if (existing) {
+        resolve(existing);
+        return;
+    }
+    // Ожидание отключено (по умолчанию): элемента в DOM нет — ждать нечего,
+    // делаем reject сразу, не подписываясь на мутации.
+    if (timeout <= 0) {
+        reject(new Error(`Элемент шага "${stepName}" не найден в DOM, а ожидание отключено (waitForTimeout=0). Навесьте data-tour-id через getHighlightProps() либо задайте waitForTimeout, если элемент появляется асинхронно.`));
+        return;
+    }
+    const observeRoot = root instanceof Document ? root.body : root;
+    let timer;
+    const observer = new MutationObserver(() => {
+        const element = (0, getTargetElement_1.getTargetElement)(stepName, root);
+        if (element) {
+            cleanup();
+            resolve(element);
+        }
+    });
+    const cleanup = () => {
+        observer.disconnect();
+        clearTimeout(timer);
+    };
+    observer.observe(observeRoot, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: [constants_1.TOUR_ID_ATTR],
+    });
+    timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Элемент шага "${stepName}" не найден за ${timeout}мс. Убедитесь, что на нём навешен data-tour-id через getHighlightProps().`));
+    }, timeout);
+});
+exports.waitForElement = waitForElement;

package/node/components/Onboarding/validation/index.d.ts

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

package/node/components/Onboarding/validation/index.js

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

package/node/components/Onboarding/validation/validateTourConfig/index.d.ts

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

package/node/components/Onboarding/validation/validateTourConfig/index.js

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

package/node/components/Onboarding/validation/validateTourConfig/validateTourConfig.d.ts

@@ -0,0 +1,12 @@
+import { type OnboardingTourConfig, type Step } from '../../types';
+/**
+ * Ошибка конфигурации тура
+ */
+export declare class OnboardingConfigError extends Error {
+    constructor(errors: unknown);
+}
+/**
+ * Проверяет конфигурацию тура и бросает ошибку при нарушениях.
+ * Вызывается при создании тура (в `createTour`).
+ */
+export declare const validateTourConfig: <TSteps extends readonly Step[]>(config: OnboardingTourConfig<TSteps>) => void;

package/node/components/Onboarding/validation/validateTourConfig/validateTourConfig.js

@@ -0,0 +1,80 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateTourConfig = exports.OnboardingConfigError = void 0;
+const v = __importStar(require("@astral/validations"));
+/**
+ * Имя шага в camelCase.
+ * Гарантирует доступ `tour.steps.stepName` и чистый `data-tour-id`.
+ */
+const CAMEL_CASE = /^[a-z][a-zA-Z0-9]*$/;
+/**
+ * Правило: имена шагов уникальны в рамках тура.
+ */
+const uniqueStepName = () => v.createRule((steps, ctx) => {
+    const seenNames = new Set();
+    for (const { name } of steps) {
+        if (seenNames.has(name)) {
+            return ctx.createError({
+                code: 'DUPLICATE_STEP_NAME',
+                message: `Имя шага «${name}» не уникально`,
+            });
+        }
+        seenNames.add(name);
+    }
+    return undefined;
+});
+/**
+ * Схема валидации конфигурации тура.
+ */
+const tourConfigSchema = v.object({
+    name: v.string(v.min(1)),
+    steps: v.array(v.min(1), v.arrayItem(v.object({
+        name: v.string(v.min(1), v.pattern(CAMEL_CASE, {
+            message: 'Имя шага должно быть в camelCase',
+        })),
+    })), uniqueStepName()),
+});
+/**
+ * Ошибка конфигурации тура
+ */
+class OnboardingConfigError extends Error {
+    constructor(errors) {
+        super(`Некорректная конфигурация тура:\n${JSON.stringify(errors, null, 2)}`);
+        this.name = 'OnboardingConfigError';
+    }
+}
+exports.OnboardingConfigError = OnboardingConfigError;
+/**
+ * Проверяет конфигурацию тура и бросает ошибку при нарушениях.
+ * Вызывается при создании тура (в `createTour`).
+ */
+const validateTourConfig = (config) => {
+    const errors = tourConfigSchema(config);
+    if (errors) {
+        throw new OnboardingConfigError(v.toPrettyError(errors));
+    }
+};
+exports.validateTourConfig = validateTourConfig;

package/node/services/Logger/Logger.d.ts

@@ -0,0 +1,45 @@
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+export type LogThreshold = LogLevel | 'silent';
+export type LogContext = Readonly<Record<string, unknown>>;
+export type LoggerOptions = {
+    context?: LogContext;
+};
+export type CreateLoggerOptions = LoggerOptions & {
+    name: string;
+    level?: LogThreshold;
+};
+export type ConfigureOptions = {
+    level?: LogThreshold;
+};
+/**
+ * Логгер.
+ * Формат логов: `{пакет}: {иконка} [{scope}]: {сообщение}`.
+ * */
+export declare class Logger {
+    private readonly name;
+    private readonly scope;
+    private readonly context;
+    private readonly parent;
+    private level?;
+    private readonly console;
+    private constructor();
+    static create: ({ name, context, level, }: CreateLoggerOptions) => Logger;
+    /**
+     * Меняет уровень пакета.
+     * Без `level` — сброс к env-дефолту.
+     * Возвращает функцию отмены — вернёт прежний уровень.
+     * */
+    configure: (options?: ConfigureOptions) => () => void;
+    /** Дочерний логгер: добавляет `scope`, наследует уровень корня. */
+    child: (scope: string, options?: LoggerOptions) => Logger;
+    /** Дойдёт ли лог такого уровня до консоли. */
+    isLevelEnabled: (level: LogLevel) => boolean;
+    success: (message: string, ...data: unknown[]) => void;
+    info: (message: string, ...data: unknown[]) => void;
+    warn: (message: string, ...data: unknown[]) => void;
+    debug: (message: string, ...data: unknown[]) => void;
+    error: (message: string, ...data: unknown[]) => void;
+    /** Свой уровень → уровень родителя по цепочке → env-дефолт. */
+    private effectiveLevel;
+    private print;
+}

package/node/services/Logger/Logger.js

@@ -0,0 +1,72 @@
+"use strict";
+// biome-ignore-all lint/suspicious/noConsole: Logger — единственная точка вывода в консоль
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+/** Приоритет уровней. Лог виден, если его приоритет ≤ порога. */
+const LOG_LEVEL_PRIORITY = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+/** Порог по умолчанию для каждого окружения. */
+const DEFAULT_LOG_LEVEL_BY_ENV = {
+    production: 'error',
+    test: 'silent',
+    development: 'warn',
+};
+/** Порог для текущего окружения. */
+const getEnvLevel = () => DEFAULT_LOG_LEVEL_BY_ENV[process.env.NODE_ENV ?? 'development'] ?? 'warn';
+/**
+ * Логгер.
+ * Формат логов: `{пакет}: {иконка} [{scope}]: {сообщение}`.
+ * */
+class Logger {
+    constructor(name, scope, context, parent, level, console = globalThis.console) {
+        this.name = name;
+        this.scope = scope;
+        this.context = context;
+        this.parent = parent;
+        this.level = level;
+        this.console = console;
+        /**
+         * Меняет уровень пакета.
+         * Без `level` — сброс к env-дефолту.
+         * Возвращает функцию отмены — вернёт прежний уровень.
+         * */
+        this.configure = (options = {}) => {
+            const previousLevel = this.level;
+            this.level = options.level;
+            return () => {
+                this.level = previousLevel;
+            };
+        };
+        /** Дочерний логгер: добавляет `scope`, наследует уровень корня. */
+        this.child = (scope, options) => {
+            return new Logger(this.name, 
+            // склеиваем scope: `Onboarding` → `Onboarding Tour`.
+            this.scope ? `${this.scope} ${scope}` : scope, { ...this.context, ...options?.context }, this, undefined, this.console);
+        };
+        /** Дойдёт ли лог такого уровня до консоли. */
+        this.isLevelEnabled = (level) => LOG_LEVEL_PRIORITY[level] <= LOG_LEVEL_PRIORITY[this.effectiveLevel()];
+        this.success = (message, ...data) => this.print('info', '✅', this.console.log, message, data);
+        this.info = (message, ...data) => this.print('info', 'ℹ️', this.console.log, message, data);
+        this.warn = (message, ...data) => this.print('warn', '⚠️', this.console.warn, message, data);
+        this.debug = (message, ...data) => this.print('debug', '🐞', this.console.log, message, data);
+        this.error = (message, ...data) => this.print('error', '❌', this.console.error, message, data);
+        /** Свой уровень → уровень родителя по цепочке → env-дефолт. */
+        this.effectiveLevel = () => this.level ?? this.parent?.effectiveLevel() ?? getEnvLevel();
+        this.print = (level, icon, sink, message, data) => {
+            if (!this.isLevelEnabled(level)) {
+                return;
+            }
+            const prefix = this.name ? `${this.name}: ` : '';
+            const scope = this.scope ? ` [${this.scope}]:` : '';
+            const withContext = Object.keys(this.context).length === 0 ? data : [...data, this.context];
+            sink(`${prefix}${icon}${scope} ${message}`, ...withContext);
+        };
+    }
+}
+exports.Logger = Logger;
+Logger.create = ({ name, context = {}, level, }) => new Logger(name, undefined, { ...context }, null, level);

package/node/services/Logger/index.d.ts

@@ -0,0 +1,10 @@
+import { Logger, type ConfigureOptions, type CreateLoggerOptions, type LogContext, type LoggerOptions, type LogLevel, type LogThreshold } from './Logger';
+export { Logger, type ConfigureOptions, type CreateLoggerOptions, type LogContext, type LoggerOptions, type LogLevel, type LogThreshold, };
+/**
+ * Фабрика Logger для `@astral/ui`: сервисы и компоненты получают инстанс через DI.
+ */
+export declare const createLogger: (scope: string, options?: LoggerOptions) => Logger;
+/**
+ * (Пере)-Настройка логгера пакета `@astral/ui` — вызывает `ConfigProvider`.
+ */
+export declare const configureLogger: (options?: ConfigureOptions) => () => void;

package/node/services/Logger/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureLogger = exports.createLogger = exports.Logger = void 0;
+const Logger_1 = require("./Logger");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return Logger_1.Logger; } });
+// Корневой логгер пакета @astral/ui.
+const uiLogger = Logger_1.Logger.create({ name: '@astral/ui' });
+/**
+ * Фабрика Logger для `@astral/ui`: сервисы и компоненты получают инстанс через DI.
+ */
+const createLogger = (scope, options) => uiLogger.child(scope, options);
+exports.createLogger = createLogger;
+/**
+ * (Пере)-Настройка логгера пакета `@astral/ui` — вызывает `ConfigProvider`.
+ */
+const configureLogger = (options) => uiLogger.configure(options);
+exports.configureLogger = configureLogger;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astral/ui",
-  "version": "4.82.0",
+  "version": "4.84.0",
   "browser": "./index.js",
   "main": "./node/index.js",
   "dependencies": {
@@ -24,7 +24,8 @@
     "remeda": "^1.61.0",
     "react-pdf": "9.2.1",
     "react-hook-form": "^7.66.1",
-    "focus-trap": "^7.8.0"
+    "focus-trap": "^7.8.0",
+    "use-sync-external-store": "^1.6.0"
   },
   "peerDependencies": {
     "react": "^17.0.0 || ^18.0.0 || ^19.0.0",

package/services/Logger/Logger.d.ts

@@ -0,0 +1,45 @@
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+export type LogThreshold = LogLevel | 'silent';
+export type LogContext = Readonly<Record<string, unknown>>;
+export type LoggerOptions = {
+    context?: LogContext;
+};
+export type CreateLoggerOptions = LoggerOptions & {
+    name: string;
+    level?: LogThreshold;
+};
+export type ConfigureOptions = {
+    level?: LogThreshold;
+};
+/**
+ * Логгер.
+ * Формат логов: `{пакет}: {иконка} [{scope}]: {сообщение}`.
+ * */
+export declare class Logger {
+    private readonly name;
+    private readonly scope;
+    private readonly context;
+    private readonly parent;
+    private level?;
+    private readonly console;
+    private constructor();
+    static create: ({ name, context, level, }: CreateLoggerOptions) => Logger;
+    /**
+     * Меняет уровень пакета.
+     * Без `level` — сброс к env-дефолту.
+     * Возвращает функцию отмены — вернёт прежний уровень.
+     * */
+    configure: (options?: ConfigureOptions) => () => void;
+    /** Дочерний логгер: добавляет `scope`, наследует уровень корня. */
+    child: (scope: string, options?: LoggerOptions) => Logger;
+    /** Дойдёт ли лог такого уровня до консоли. */
+    isLevelEnabled: (level: LogLevel) => boolean;
+    success: (message: string, ...data: unknown[]) => void;
+    info: (message: string, ...data: unknown[]) => void;
+    warn: (message: string, ...data: unknown[]) => void;
+    debug: (message: string, ...data: unknown[]) => void;
+    error: (message: string, ...data: unknown[]) => void;
+    /** Свой уровень → уровень родителя по цепочке → env-дефолт. */
+    private effectiveLevel;
+    private print;
+}