@astral/ui 4.82.0 → 4.84.0

package/components/Onboarding/core/ActiveStepStore/ActiveStepStore.d.ts

@@ -0,0 +1,50 @@
+import { type ActiveStepState } from '../../types';
+type Listener = VoidFunction;
+/**
+ * Ссылка на тур, которую держит store: по ней он опознаёт владельца слота
+ * (сравнение по идентичности экземпляра, а не по имени) и может закрыть тур.
+ */
+export type TourHandle = {
+    /**
+     * Закрытие тура штатным путём (используется `Onboarding.closeActiveTour`).
+     */
+    close: () => void;
+};
+/**
+ * Store активного шага, связывающий туры с `<OnboardingContainer/>`.
+ */
+export declare class ActiveStepStore {
+    private activeStep;
+    private activeTour;
+    private readonly listeners;
+    subscribe: (listener: Listener) => () => void;
+    /**
+     * Состояние активного шага (null — тур не показан).
+     */
+    getActiveStep: () => ActiveStepState | null;
+    /**
+     * Публикует шаг тура и делает этот тур владельцем слота.
+     */
+    setActiveStep: (step: ActiveStepState, tour: TourHandle) => void;
+    /**
+     * Владеет ли слотом сейчас именно тур (пустой store — `false`).
+     */
+    isActiveTour: (tour: TourHandle) => boolean;
+    /**
+     * Показан ли сейчас шаг тура. Имена шагов могут совпадать
+     * в разных турах, поэтому проверяется и тур, и имя.
+     */
+    isActiveStep: (tour: TourHandle, stepName: string) => boolean;
+    /**
+     * Освобождает слот, если тур сейчас его владелец.
+     */
+    release: (tour: TourHandle) => void;
+    /**
+     * Закрытие активного тура обычным путём.
+     * Внешний триггер: размонтирование онбординга, смена юзера.
+     */
+    closeActiveTour: () => void;
+    private clear;
+    private emit;
+}
+export {};

package/components/Onboarding/core/ActiveStepStore/ActiveStepStore.js

@@ -0,0 +1,63 @@
+/**
+ * Store активного шага, связывающий туры с `<OnboardingContainer/>`.
+ */
+export class ActiveStepStore {
+    constructor() {
+        this.activeStep = null;
+        this.activeTour = null;
+        this.listeners = new Set();
+        this.subscribe = (listener) => {
+            this.listeners.add(listener);
+            return () => {
+                this.listeners.delete(listener);
+            };
+        };
+        /**
+         * Состояние активного шага (null — тур не показан).
+         */
+        this.getActiveStep = () => this.activeStep;
+        /**
+         * Публикует шаг тура и делает этот тур владельцем слота.
+         */
+        this.setActiveStep = (step, tour) => {
+            this.activeStep = step;
+            this.activeTour = tour;
+            this.emit();
+        };
+        /**
+         * Владеет ли слотом сейчас именно тур (пустой store — `false`).
+         */
+        this.isActiveTour = (tour) => this.activeTour === tour;
+        /**
+         * Показан ли сейчас шаг тура. Имена шагов могут совпадать
+         * в разных турах, поэтому проверяется и тур, и имя.
+         */
+        this.isActiveStep = (tour, stepName) => this.isActiveTour(tour) && this.activeStep?.step.name === stepName;
+        /**
+         * Освобождает слот, если тур сейчас его владелец.
+         */
+        this.release = (tour) => {
+            if (this.isActiveTour(tour)) {
+                this.clear();
+            }
+        };
+        /**
+         * Закрытие активного тура обычным путём.
+         * Внешний триггер: размонтирование онбординга, смена юзера.
+         */
+        this.closeActiveTour = () => {
+            this.activeTour?.close();
+        };
+    }
+    clear() {
+        if (this.activeStep === null) {
+            return;
+        }
+        this.activeStep = null;
+        this.activeTour = null;
+        this.emit();
+    }
+    emit() {
+        this.listeners.forEach((listener) => listener());
+    }
+}

package/components/Onboarding/core/ActiveStepStore/index.d.ts

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

package/components/Onboarding/core/ActiveStepStore/index.js

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

package/components/Onboarding/core/ExitController/ExitController.d.ts

@@ -0,0 +1,48 @@
+import { type Logger } from '../../../../services/Logger';
+export type ExitControllerParams = {
+    /**
+     * Фактическое закрытие тура. Вызывается только после подтверждения в
+     * ConfirmExit, поэтому всегда означает пользовательский выход (тур помечается
+     * прерванным).
+     */
+    close: () => void;
+    /**
+     * Уведомить о смене состояния (перерисовать активный шаг) — например, чтобы
+     * показать/скрыть ConfirmExit.
+     */
+    onChange: () => void;
+};
+/**
+ * Единая точка выхода из тура.
+ *
+ * Все пути закрытия (Esc, клик по overlay, крестик, клик мимо) идут через
+ * requestClose и всегда требуют подтверждение
+ * (ConfirmExit); закрытие происходит только по confirm.
+ */
+export declare class ExitController {
+    private readonly params;
+    private readonly logger;
+    private confirming;
+    constructor(params: ExitControllerParams, logger: Logger);
+    /**
+     * Идёт ли запрос подтверждения выхода.
+     */
+    get isConfirming(): boolean;
+    /**
+     * Запрос на закрытие — показывает ConfirmExit. Повторные вызовы во время
+     * подтверждения игнорируются.
+     */
+    requestClose: () => void;
+    /**
+     * Подтверждение выхода из ConfirmExit.
+     */
+    confirm: () => void;
+    /**
+     * Отмена выхода — продолжаем тур.
+     */
+    cancel: () => void;
+    /**
+     * Сброс состояния (при старте/закрытии тура).
+     */
+    reset: () => void;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Единая точка выхода из тура.
+ *
+ * Все пути закрытия (Esc, клик по overlay, крестик, клик мимо) идут через
+ * requestClose и всегда требуют подтверждение
+ * (ConfirmExit); закрытие происходит только по confirm.
+ */
+export class ExitController {
+    constructor(params, logger) {
+        this.params = params;
+        this.logger = logger;
+        this.confirming = false;
+        /**
+         * Запрос на закрытие — показывает ConfirmExit. Повторные вызовы во время
+         * подтверждения игнорируются.
+         */
+        this.requestClose = () => {
+            if (this.confirming) {
+                return;
+            }
+            this.logger.debug('Запрошен выход из тура, показано подтверждение');
+            this.confirming = true;
+            this.params.onChange();
+        };
+        /**
+         * Подтверждение выхода из ConfirmExit.
+         */
+        this.confirm = () => {
+            if (!this.confirming) {
+                return;
+            }
+            this.confirming = false;
+            this.params.close();
+        };
+        /**
+         * Отмена выхода — продолжаем тур.
+         */
+        this.cancel = () => {
+            if (!this.confirming) {
+                return;
+            }
+            this.logger.debug('Выход из тура отменён');
+            this.confirming = false;
+            this.params.onChange();
+        };
+        /**
+         * Сброс состояния (при старте/закрытии тура).
+         */
+        this.reset = () => {
+            this.confirming = false;
+        };
+    }
+    /**
+     * Идёт ли запрос подтверждения выхода.
+     */
+    get isConfirming() {
+        return this.confirming;
+    }
+}

package/components/Onboarding/core/ExitController/index.d.ts

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

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

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

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

@@ -0,0 +1,103 @@
+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';
+import { type ProgressStorage } from '../ProgressStorage';
+/**
+ * Управляющий объект одного тура: связывает навигацию (StepNavigator), разрешение
+ * значений шага (StepResolver), рантайм-переопределения (StepsController),
+ * выход (ExitController) и сохранение прогресса (ProgressStorage), публикуя
+ * состояние активного шага в store своего экземпляра онбординга.
+ */
+export declare class OnboardingTour<TSteps extends readonly Step[] = readonly Step[]> {
+    private readonly config;
+    private readonly progressStorage;
+    private readonly activeStepStore;
+    private readonly errorService;
+    private readonly logger;
+    private readonly navigator;
+    private readonly resolver;
+    private readonly stepsController;
+    private readonly exitController;
+    private status;
+    /**
+     * Типобезопасный доступ к шагам по их именам.
+     */
+    readonly steps: StepHandles<TSteps>;
+    constructor(config: OnboardingTourConfig<TSteps>, progressStorage: ProgressStorage, activeStepStore: ActiveStepStore, errorService: ErrorService, logger: Logger);
+    /**
+     * Запуск тура с первого шага.
+     */
+    start: () => Promise<void>;
+    /**
+     * Снимает паузу шага с `waitForResume`
+     */
+    resume: () => void;
+    /**
+     * Показ тура из сохранённого прогресса по запросу пользователя
+     */
+    restore: () => Promise<void>;
+    /**
+     * Переход к следующему шагу. На последнем шаге завершает тур.
+     */
+    next: () => void;
+    /**
+     * Переход к предыдущему шагу.
+     */
+    prev: () => void;
+    /**
+     * Переход к шагу по его позиции среди видимых шагов.
+     */
+    goToPosition: (position: number) => void;
+    /**
+     * Завершение тура: помечаем пройденным (`isCompleted`) и закрываем.
+     */
+    finish: () => void;
+    /**
+     * Программное закрытие тура.
+     * В отличие от навигации работает в любом состоянии: закрывает и тур,
+     * ожидающий `resume()`.
+     */
+    close: () => void;
+    /**
+     * Запрос выхода.
+     */
+    private requestClose;
+    /**
+     * Сбрасывает сохранённый прогресс тура
+     * После сброса `start()` снова покажет тур с первого шага.
+     */
+    resetProgress: () => Promise<void>;
+    /**
+     * Возвращает сохранённый прогресс тура
+     */
+    getState: () => Promise<TourProgress | null>;
+    /**
+     * Разрешена ли навигация сейчас: тур показан на экране и владеет активным
+     * шагом store
+     */
+    private canNavigate;
+    /**
+     * Единая точка закрытия тура
+     */
+    private exit;
+    /**
+     * Переход к текущему шагу. Шаг с `waitForResume` ставит тур в ожидание
+     * и не отрисовывается до явного `resume()`.
+     */
+    private enterCurrentStep;
+    /**
+     * Очищает store, только если активный шаг принадлежит именно этому туру.
+     */
+    private releaseStep;
+    private handleError;
+    /**
+     * Публикует состояние текущего шага в store.
+     */
+    private publishStep;
+    private buildActiveStep;
+    /**
+     * Перерисовывает шаг после изменения его override-содержимого
+     */
+    private refreshStep;
+}

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

@@ -0,0 +1,283 @@
+import { ExitController } from '../ExitController';
+import { StepNavigator } from '../StepNavigator';
+import { StepResolver } from '../StepResolver';
+import { StepsController } from '../StepsController';
+/**
+ * Управляющий объект одного тура: связывает навигацию (StepNavigator), разрешение
+ * значений шага (StepResolver), рантайм-переопределения (StepsController),
+ * выход (ExitController) и сохранение прогресса (ProgressStorage), публикуя
+ * состояние активного шага в store своего экземпляра онбординга.
+ */
+export class OnboardingTour {
+    constructor(config, progressStorage, activeStepStore, errorService, logger) {
+        this.config = config;
+        this.progressStorage = progressStorage;
+        this.activeStepStore = activeStepStore;
+        this.errorService = errorService;
+        this.logger = logger;
+        this.status = 'idle';
+        /**
+         * Запуск тура с первого шага.
+         */
+        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();
+        };
+        /**
+         * Снимает паузу шага с `waitForResume`
+         */
+        this.resume = () => {
+            if (this.status !== 'waiting-resume') {
+                this.logger.debug('resume проигнорирован: тур не на паузе');
+                return;
+            }
+            this.logger.debug('Тур возобновлён после паузы');
+            this.status = 'running';
+            this.publishStep();
+        };
+        /**
+         * Показ тура из сохранённого прогресса по запросу пользователя
+         */
+        this.restore = async () => {
+            const persisted = await this.progressStorage.load();
+            this.logger.info('Тур восстановлен');
+            this.exitController.reset();
+            this.navigator.reset();
+            // Пройденный тур переигрываем с начала; иначе продолжаем с сохранённого шага.
+            if (persisted && !persisted.isCompleted) {
+                this.navigator.goToStep(persisted.lastStepName);
+            }
+            this.enterCurrentStep();
+        };
+        /**
+         * Переход к следующему шагу. На последнем шаге завершает тур.
+         */
+        this.next = () => {
+            if (!this.canNavigate()) {
+                return;
+            }
+            if (this.navigator.hasNext) {
+                // Обратный вызов шага — только при реальном переходе (на последнем next = finish).
+                this.navigator.current.onNextClick?.();
+                this.navigator.next();
+                this.progressStorage.save({
+                    lastStepName: this.navigator.current.name,
+                    isCompleted: false,
+                    isDismissed: false,
+                });
+                this.enterCurrentStep();
+            }
+            else {
+                this.finish();
+            }
+        };
+        /**
+         * Переход к предыдущему шагу.
+         */
+        this.prev = () => {
+            if (!this.canNavigate()) {
+                return;
+            }
+            if (this.navigator.hasPrev) {
+                // Обратный вызов шага — только при реальном переходе.
+                this.navigator.current.onPrevClick?.();
+                this.navigator.prev();
+                this.progressStorage.save({
+                    lastStepName: this.navigator.current.name,
+                    isCompleted: false,
+                    isDismissed: false,
+                });
+                this.enterCurrentStep();
+            }
+        };
+        /**
+         * Переход к шагу по его позиции среди видимых шагов.
+         */
+        this.goToPosition = (position) => {
+            if (!this.canNavigate()) {
+                return;
+            }
+            const previous = this.navigator.position;
+            this.navigator.goToPosition(position);
+            if (this.navigator.position === previous) {
+                return;
+            }
+            this.progressStorage.save({
+                lastStepName: this.navigator.current.name,
+                isCompleted: false,
+                isDismissed: false,
+            });
+            this.enterCurrentStep();
+        };
+        /**
+         * Завершение тура: помечаем пройденным (`isCompleted`) и закрываем.
+         */
+        this.finish = () => {
+            if (!this.canNavigate()) {
+                return;
+            }
+            this.progressStorage.save({
+                lastStepName: this.navigator.current.name,
+                isCompleted: true,
+                isDismissed: true,
+            });
+            this.exit('completed');
+        };
+        /**
+         * Программное закрытие тура.
+         * В отличие от навигации работает в любом состоянии: закрывает и тур,
+         * ожидающий `resume()`.
+         */
+        this.close = () => {
+            this.exit('closed');
+        };
+        /**
+         * Запрос выхода.
+         */
+        this.requestClose = () => {
+            if (!this.navigator.hasNext) {
+                this.finish();
+                return;
+            }
+            this.exitController.requestClose();
+        };
+        /**
+         * Сбрасывает сохранённый прогресс тура
+         * После сброса `start()` снова покажет тур с первого шага.
+         */
+        this.resetProgress = async () => {
+            await this.progressStorage.reset();
+            this.logger.debug('Прогресс тура сброшен');
+        };
+        /**
+         * Возвращает сохранённый прогресс тура
+         */
+        this.getState = () => this.progressStorage.load();
+        /**
+         * Единая точка закрытия тура
+         */
+        this.exit = (reason) => {
+            if (this.status === 'idle') {
+                return;
+            }
+            if (reason === 'dismissed') {
+                this.progressStorage.save({
+                    lastStepName: this.navigator.current.name,
+                    isCompleted: false,
+                    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,
+                step: this.navigator.current?.name,
+            });
+            this.config.onError?.(error);
+            this.exit('closed');
+        };
+        this.navigator = new StepNavigator(config.steps);
+        this.resolver = new StepResolver(config);
+        this.stepsController = new StepsController(config.steps, (stepName) => this.refreshStep(stepName));
+        this.steps = this.stepsController.handles;
+        const exitParams = {
+            close: () => this.exit('dismissed'),
+            onChange: () => this.publishStep(),
+        };
+        this.exitController = new ExitController(exitParams, this.logger);
+    }
+    /**
+     * Разрешена ли навигация сейчас: тур показан на экране и владеет активным
+     * шагом store
+     */
+    canNavigate() {
+        const isNavigable = this.status === 'running' && this.activeStepStore.isActiveTour(this);
+        if (!isNavigable) {
+            this.logger.debug('Навигация проигнорирована: тур неактивен');
+        }
+        return isNavigable;
+    }
+    /**
+     * Переход к текущему шагу. Шаг с `waitForResume` ставит тур в ожидание
+     * и не отрисовывается до явного `resume()`.
+     */
+    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();
+    }
+    /**
+     * Очищает store, только если активный шаг принадлежит именно этому туру.
+     */
+    releaseStep() {
+        this.activeStepStore.release(this);
+    }
+    /**
+     * Публикует состояние текущего шага в store.
+     */
+    publishStep() {
+        const current = this.navigator.current;
+        const step = this.resolver.resolve(current, this.stepsController.getOverride(current.name));
+        this.activeStepStore.setActiveStep(this.buildActiveStep(step), this);
+    }
+    buildActiveStep(step) {
+        return {
+            ...this.resolver.resolvePresentation(),
+            tourName: this.config.name,
+            step,
+            position: this.navigator.position,
+            total: this.navigator.total,
+            hasNext: this.navigator.hasNext,
+            hasPrev: this.navigator.hasPrev,
+            isInteractive: this.resolver.resolveIsInteractive(step),
+            isConfirming: this.exitController.isConfirming,
+            onNext: this.next,
+            onPrev: this.prev,
+            onSelectStep: this.goToPosition,
+            requestClose: this.requestClose,
+            onConfirmExit: this.exitController.confirm,
+            onCancelExit: this.exitController.cancel,
+            onError: this.handleError,
+        };
+    }
+    /**
+     * Перерисовывает шаг после изменения его override-содержимого
+     */
+    refreshStep(stepName) {
+        if (this.activeStepStore.isActiveStep(this, stepName)) {
+            this.publishStep();
+        }
+    }
+}

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

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

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

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

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

@@ -0,0 +1,24 @@
+import { type Logger } from '../../../../services/Logger';
+import { type SaveStrategy, type TourProgress } from '../../types';
+/**
+ * Обёртка над переданной SaveStrategy, изолирующая тур от исключений хранилища
+ *
+ * Записи выполняются строго последовательно : при async-стратегии это
+ * не даёт конкурентным вызовам переставиться местами — быстрый next/next,
+ * save→reset или save→skip сохранят порядок.
+ * `load()` ждёт текущее сохранение, поэтому читает уже применённое состояние.
+ */
+export declare class ProgressStorage {
+    private readonly strategy;
+    private readonly logger;
+    private saving;
+    constructor(strategy: SaveStrategy, logger: Logger);
+    load(): Promise<TourProgress | null>;
+    save(state: TourProgress): Promise<void>;
+    /**
+     * Полный сброс прогресса. Если стратегия умеет `remove` — запись удаляется;
+     * иначе поверх пишется пустое состояние.
+     */
+    reset(): Promise<void>;
+    private enqueue;
+}