@astral/ui 4.83.0 → 4.85.0

package/node/components/Onboarding/core/ExitController/ExitController.js

@@ -9,8 +9,9 @@ exports.ExitController = void 0;
  * (ConfirmExit); закрытие происходит только по confirm.
  */
 class ExitController {
-    constructor(params) {
+    constructor(params, logger) {
         this.params = params;
+        this.logger = logger;
         this.confirming = false;
         /**
          * Запрос на закрытие — показывает ConfirmExit. Повторные вызовы во время
@@ -20,6 +21,7 @@ class ExitController {
             if (this.confirming) {
                 return;
             }
+            this.logger.debug('Запрошен выход из тура, показано подтверждение');
             this.confirming = true;
             this.params.onChange();
         };
@@ -40,6 +42,7 @@ class ExitController {
             if (!this.confirming) {
                 return;
             }
+            this.logger.debug('Выход из тура отменён');
             this.confirming = false;
             this.params.onChange();
         };

package/node/components/Onboarding/core/OnboardingTour/OnboardingTour.d.ts

@@ -1,3 +1,4 @@
+import { type Logger } from '../../../../services/Logger';
 import { type ErrorService } from '../../../services/ErrorService';
 import { type OnboardingTourConfig, type Step, type StepHandles, type TourProgress } from '../../types';
 import { type ActiveStepStore } from '../ActiveStepStore';
@@ -13,6 +14,7 @@ export declare class OnboardingTour<TSteps extends readonly Step[] = readonly St
     private readonly progressStorage;
     private readonly activeStepStore;
     private readonly errorService;
+    private readonly logger;
     private readonly navigator;
     private readonly resolver;
     private readonly stepsController;
@@ -22,7 +24,7 @@ export declare class OnboardingTour<TSteps extends readonly Step[] = readonly St
      * Типобезопасный доступ к шагам по их именам.
      */
     readonly steps: StepHandles<TSteps>;
-    constructor(config: OnboardingTourConfig<TSteps>, progressStorage: ProgressStorage, activeStepStore: ActiveStepStore, errorService: ErrorService);
+    constructor(config: OnboardingTourConfig<TSteps>, progressStorage: ProgressStorage, activeStepStore: ActiveStepStore, errorService: ErrorService, logger: Logger);
     /**
      * Запуск тура с первого шага.
      */

package/node/components/Onboarding/core/OnboardingTour/OnboardingTour.js

@@ -12,11 +12,12 @@ const StepsController_1 = require("../StepsController");
  * состояние активного шага в store своего экземпляра онбординга.
  */
 class OnboardingTour {
-    constructor(config, progressStorage, activeStepStore, errorService) {
+    constructor(config, progressStorage, activeStepStore, errorService, logger) {
         this.config = config;
         this.progressStorage = progressStorage;
         this.activeStepStore = activeStepStore;
         this.errorService = errorService;
+        this.logger = logger;
         this.status = 'idle';
         /**
          * Запуск тура с первого шага.
@@ -24,8 +25,10 @@ class OnboardingTour {
         this.start = async () => {
             const persisted = await this.progressStorage.load();
             if (persisted?.isDismissed) {
+                this.logger.info('Тур пропущен: ранее закрыт пользователем');
                 return;
             }
+            this.logger.info('Тур запущен');
             this.exitController.reset();
             this.navigator.reset();
             this.enterCurrentStep();
@@ -35,8 +38,10 @@ class OnboardingTour {
          */
         this.resume = () => {
             if (this.status !== 'waiting-resume') {
+                this.logger.debug('resume проигнорирован: тур не на паузе');
                 return;
             }
+            this.logger.debug('Тур возобновлён после паузы');
             this.status = 'running';
             this.publishStep();
         };
@@ -45,6 +50,7 @@ class OnboardingTour {
          */
         this.restore = async () => {
             const persisted = await this.progressStorage.load();
+            this.logger.info('Тур восстановлен');
             this.exitController.reset();
             this.navigator.reset();
             // Пройденный тур переигрываем с начала; иначе продолжаем с сохранённого шага.
@@ -151,6 +157,7 @@ class OnboardingTour {
          */
         this.resetProgress = async () => {
             await this.progressStorage.reset();
+            this.logger.debug('Прогресс тура сброшен');
         };
         /**
          * Возвращает сохранённый прогресс тура
@@ -170,12 +177,14 @@ class OnboardingTour {
                     isDismissed: true,
                 });
             }
+            this.logger.info('Тур закрыт', { reason });
             this.status = 'idle';
             this.exitController.reset();
             this.releaseStep();
             this.config.onClose?.(reason);
         };
         this.handleError = (error) => {
+            this.logger.error('Ошибка тура', error);
             this.errorService.captureException(error, {
                 place: 'Onboarding',
                 tourName: this.config.name,
@@ -188,17 +197,22 @@ class OnboardingTour {
         this.resolver = new StepResolver_1.StepResolver(config);
         this.stepsController = new StepsController_1.StepsController(config.steps, (stepName) => this.refreshStep(stepName));
         this.steps = this.stepsController.handles;
-        this.exitController = new ExitController_1.ExitController({
+        const exitParams = {
             close: () => this.exit('dismissed'),
             onChange: () => this.publishStep(),
-        });
+        };
+        this.exitController = new ExitController_1.ExitController(exitParams, this.logger);
     }
     /**
      * Разрешена ли навигация сейчас: тур показан на экране и владеет активным
      * шагом store
      */
     canNavigate() {
-        return this.status === 'running' && this.activeStepStore.isActiveTour(this);
+        const isNavigable = this.status === 'running' && this.activeStepStore.isActiveTour(this);
+        if (!isNavigable) {
+            this.logger.debug('Навигация проигнорирована: тур неактивен');
+        }
+        return isNavigable;
     }
     /**
      * Переход к текущему шагу. Шаг с `waitForResume` ставит тур в ожидание
@@ -207,16 +221,23 @@ class OnboardingTour {
     enterCurrentStep() {
         // Показывать нечего: у тура нет ни одного видимого (не-пропущенного) шага.
         if (this.navigator.total === 0) {
+            this.logger.warn('Нет ни одного видимого шага, тур не показан');
             this.status = 'idle';
             this.releaseStep();
             return;
         }
         const step = this.navigator.current;
         if (step.waitForResume) {
+            this.logger.debug('Ожидание resume', { step: step.name });
             this.status = 'waiting-resume';
             this.releaseStep();
             return;
         }
+        this.logger.debug('Показан шаг', {
+            step: step.name,
+            position: this.navigator.position,
+            total: this.navigator.total,
+        });
         this.status = 'running';
         this.publishStep();
     }

package/node/components/Onboarding/core/ProgressStorage/ProgressStorage.d.ts

@@ -1,3 +1,4 @@
+import { type Logger } from '../../../../services/Logger';
 import { type SaveStrategy, type TourProgress } from '../../types';
 /**
  * Обёртка над переданной SaveStrategy, изолирующая тур от исключений хранилища
@@ -9,8 +10,9 @@ import { type SaveStrategy, type TourProgress } from '../../types';
  */
 export declare class ProgressStorage {
     private readonly strategy;
+    private readonly logger;
     private saving;
-    constructor(strategy: SaveStrategy);
+    constructor(strategy: SaveStrategy, logger: Logger);
     load(): Promise<TourProgress | null>;
     save(state: TourProgress): Promise<void>;
     /**

package/node/components/Onboarding/core/ProgressStorage/ProgressStorage.js

@@ -18,8 +18,9 @@ const CLEARED_STATE = {
  * `load()` ждёт текущее сохранение, поэтому читает уже применённое состояние.
  */
 class ProgressStorage {
-    constructor(strategy) {
+    constructor(strategy, logger) {
         this.strategy = strategy;
+        this.logger = logger;
         this.saving = Promise.resolve();
     }
     async load() {
@@ -28,7 +29,9 @@ class ProgressStorage {
         try {
             return await this.strategy.load();
         }
-        catch {
+        catch (error) {
+            // Ошибка хранилища не должна ронять тур, но остаётся видимой в логах.
+            this.logger.warn('Ошибка чтения прогресса из хранилища', error);
             return null;
         }
     }
@@ -52,8 +55,9 @@ class ProgressStorage {
             try {
                 await write();
             }
-            catch {
-                // Ошибка хранилища не должна ронять тур;
+            catch (error) {
+                // Ошибка хранилища не должна ронять тур, но остаётся видимой в логах.
+                this.logger.warn('Ошибка записи прогресса в хранилище', error);
             }
         });
         return this.saving;

package/node/components/Onboarding/ui/StepStrategy/steps/HighlightStep/HighlightStep.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HighlightStep = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
-const CrossOutlineMd_1 = require("../../../../../../icons/CrossOutlineMd");
 const Typography_1 = require("../../../../../Typography");
 const StepFooter_1 = require("../StepFooter");
 const styles_1 = require("./styles");
@@ -18,6 +17,6 @@ const HighlightStep = ({ activeStep, isClosing, geometry, }) => {
     if (!anchorEl) {
         return null;
     }
-    return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: shouldShowPopover && ((0, jsx_runtime_1.jsx)(styles_1.StepPopover, { isOpen: isOpen, disableAutoFocus: true, hasArrow: true, anchorEl: anchorEl, placement: step.position, children: (0, jsx_runtime_1.jsxs)(styles_1.PopoverBody, { ref: setPopoverNode, tabIndex: -1, children: [(0, jsx_runtime_1.jsx)(styles_1.CloseButton, { variant: "text", onClick: handleClose, "aria-label": "\u0417\u0430\u043A\u0440\u044B\u0442\u044C", children: (0, jsx_runtime_1.jsx)(CrossOutlineMd_1.CrossOutlineMd, {}) }), (0, jsx_runtime_1.jsxs)(styles_1.Content, { children: [step.title && ((0, jsx_runtime_1.jsx)(Typography_1.Typography, { component: "div", variant: "h5", children: step.title })), step.content && ((0, jsx_runtime_1.jsx)(Typography_1.Typography, { component: "div", variant: "body1", color: "grey", colorIntensity: "900", children: step.content }))] }), (0, jsx_runtime_1.jsx)(StepFooter_1.StepFooter, { activeStep: activeStep })] }) })) }));
+    return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: shouldShowPopover && ((0, jsx_runtime_1.jsx)(styles_1.StepPopover, { variant: "light", isOpen: isOpen, disableAutoFocus: true, anchorEl: anchorEl, placement: step.position, onClose: handleClose, contentRef: setPopoverNode, title: step.title, action: (0, jsx_runtime_1.jsx)(StepFooter_1.StepFooter, { activeStep: activeStep }), children: step.content && ((0, jsx_runtime_1.jsx)(Typography_1.Typography, { component: "div", variant: "body1", color: "grey", colorIntensity: "900", children: step.content })) })) }));
 };
 exports.HighlightStep = HighlightStep;

package/node/components/Onboarding/ui/StepStrategy/steps/HighlightStep/styles.d.ts

@@ -1,25 +1,9 @@
 /// <reference types="react" />
-/**
- * Popover шага, z-index над overlay, быстрое закрытие.
- */
-export declare const StepPopover: import("@emotion/styled/dist/declarations/src/types").StyledComponent<import("../../../../../NewPopover").NewPopoverProps & {
+export declare const StepPopover: import("@emotion/styled/dist/declarations/src/types").StyledComponent<Omit<import("../../../../../NewPopover").NewPopoverProps, "title" | "hasArrow" | "disableMobileDrawer"> & {
+    variant?: import("../../../../../HintPopover").HintPopoverVariant | undefined;
+    title?: import("react").ReactNode;
+    action?: import("react").ReactNode;
+    contentRef?: import("react").Ref<HTMLDivElement> | undefined;
+} & {
     theme?: import("@emotion/react").Theme | undefined;
 }, {}, {}>;
-export declare const PopoverBody: import("@emotion/styled/dist/declarations/src/types").StyledComponent<{
-    theme?: import("@emotion/react").Theme | undefined;
-    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
-}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
-export declare const CloseButton: import("@emotion/styled/dist/declarations/src/types").StyledComponent<Omit<import("../../../../..").WithoutEmotionSpecific<import("@mui/material").ButtonProps>, "color" | "component" | "size" | "variant" | "centerRipple" | "disableRipple" | "disableTouchRipple" | "focusRipple" | "TouchRippleProps" | "touchRippleRef" | "disableFocusRipple"> & {
-    variant?: "light" | "link" | "text" | "contained" | "outlined" | undefined;
-    loading?: boolean | undefined;
-    color?: "primary" | "success" | "warning" | "error" | "grey" | undefined;
-    component?: import("react").ElementType | undefined;
-    selected?: boolean | undefined;
-    size?: "large" | "medium" | undefined;
-} & Omit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, ""> & import("react").RefAttributes<HTMLButtonElement> & {
-    theme?: import("@emotion/react").Theme | undefined;
-}, {}, {}>;
-export declare const Content: import("@emotion/styled/dist/declarations/src/types").StyledComponent<{
-    theme?: import("@emotion/react").Theme | undefined;
-    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
-}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/node/components/Onboarding/ui/StepStrategy/steps/HighlightStep/styles.js

@@ -1,59 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Content = exports.CloseButton = exports.PopoverBody = exports.StepPopover = void 0;
-const IconButton_1 = require("../../../../../IconButton");
-const NewPopover_1 = require("../../../../../NewPopover");
+exports.StepPopover = void 0;
+const HintPopover_1 = require("../../../../../HintPopover");
 const constants_1 = require("../../../../../NewPopover/constants");
 const styled_1 = require("../../../../../styled");
 const constants_2 = require("../../../../constants");
-/**
- * Popover шага, z-index над overlay, быстрое закрытие.
- */
-exports.StepPopover = (0, styled_1.styled)(NewPopover_1.NewPopover) `
+exports.StepPopover = (0, styled_1.styled)(HintPopover_1.HintPopover) `
   && {
     z-index: ${({ theme }) => theme.zIndex.tooltip + constants_2.ONBOARDING_Z_INDEX_OFFSET.popover};
   }
-  
-  .${constants_1.popoverClassnames.innerContainer} {
-    border-radius: calc(${({ theme }) => theme.shape.medium} * 2);
-  }
 
   .${constants_1.popoverClassnames.animatedWrapper}:not(.${constants_1.popoverClassnames.animatedWrapperOpen}) {
     animation-duration: ${({ theme }) => theme.transitions.duration.shortest}ms;
   }
 `;
-exports.PopoverBody = styled_1.styled.div `
-  position: relative;
-
-  width: 400px;
-  padding: ${({ theme }) => theme.spacing(6)};
-
-  border-radius: calc(${({ theme }) => theme.shape.medium} * 2);
-
-  /* Фокус-трап ставит фокус на контейнер, браузерную рамку убираем. */
-  &:focus {
-    outline: none;
-  }
-`;
-exports.CloseButton = (0, styled_1.styled)(IconButton_1.IconButton) `
-  position: absolute;
-  top: ${({ theme }) => theme.spacing(6)};
-  right: ${({ theme }) => theme.spacing(6)};
-`;
-exports.Content = styled_1.styled.div `
-  display: flex;
-  flex-direction: column;
-  gap: ${({ theme }) => theme.spacing(4)};
-
-  margin-bottom: ${({ theme }) => theme.spacing(6)};
-
-  &:last-child {
-    margin-bottom: 0;
-  }
-
-  /* Резерв справа под крестик — только у верхнего элемента (заголовок, а если
-     его нет — текст) */
-  & > *:first-of-type {
-    padding-right: ${({ theme }) => theme.spacing(10)};
-  }
-`;

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.83.0",
+  "version": "4.85.0",
   "browser": "./index.js",
   "main": "./node/index.js",
   "dependencies": {

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

package/services/Logger/Logger.js

@@ -0,0 +1,68 @@
+// biome-ignore-all lint/suspicious/noConsole: Logger — единственная точка вывода в консоль
+/** Приоритет уровней. Лог виден, если его приоритет ≤ порога. */
+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}]: {сообщение}`.
+ * */
+export 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);
+        };
+    }
+}
+Logger.create = ({ name, context = {}, level, }) => new Logger(name, undefined, { ...context }, null, level);

package/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/services/Logger/index.js

@@ -0,0 +1,12 @@
+import { Logger, } from './Logger';
+export { Logger, };
+// Корневой логгер пакета @astral/ui.
+const uiLogger = Logger.create({ name: '@astral/ui' });
+/**
+ * Фабрика Logger для `@astral/ui`: сервисы и компоненты получают инстанс через DI.
+ */
+export const createLogger = (scope, options) => uiLogger.child(scope, options);
+/**
+ * (Пере)-Настройка логгера пакета `@astral/ui` — вызывает `ConfigProvider`.
+ */
+export const configureLogger = (options) => uiLogger.configure(options);

package/components/NewPopover/utils/resolveAnchorNode.d.ts

@@ -1,6 +0,0 @@
-import { type NewPopoverAnchorEl } from '../types';
-/**
- * Резолвит anchorEl в DOM-ноду, если это возможно.
- * Для virtual-элементов вернёт null.
- */
-export declare const resolveAnchorNode: (anchorEl: NewPopoverAnchorEl | undefined) => Node | null;

package/components/NewPopover/utils/resolveAnchorNode.js

@@ -1,8 +0,0 @@
-/**
- * Резолвит anchorEl в DOM-ноду, если это возможно.
- * Для virtual-элементов вернёт null.
- */
-export const resolveAnchorNode = (anchorEl) => {
-    const value = typeof anchorEl === 'function' ? anchorEl() : anchorEl;
-    return value instanceof Node ? value : null;
-};