@astral/ui 4.81.0 → 4.83.0

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

@@ -0,0 +1,101 @@
+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 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);
+    /**
+     * Запуск тура с первого шага.
+     */
+    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/node/components/Onboarding/core/OnboardingTour/OnboardingTour.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnboardingTour = void 0;
+const ExitController_1 = require("../ExitController");
+const StepNavigator_1 = require("../StepNavigator");
+const StepResolver_1 = require("../StepResolver");
+const StepsController_1 = require("../StepsController");
+/**
+ * Управляющий объект одного тура: связывает навигацию (StepNavigator), разрешение
+ * значений шага (StepResolver), рантайм-переопределения (StepsController),
+ * выход (ExitController) и сохранение прогресса (ProgressStorage), публикуя
+ * состояние активного шага в store своего экземпляра онбординга.
+ */
+class OnboardingTour {
+    constructor(config, progressStorage, activeStepStore, errorService) {
+        this.config = config;
+        this.progressStorage = progressStorage;
+        this.activeStepStore = activeStepStore;
+        this.errorService = errorService;
+        this.status = 'idle';
+        /**
+         * Запуск тура с первого шага.
+         */
+        this.start = async () => {
+            const persisted = await this.progressStorage.load();
+            if (persisted?.isDismissed) {
+                return;
+            }
+            this.exitController.reset();
+            this.navigator.reset();
+            this.enterCurrentStep();
+        };
+        /**
+         * Снимает паузу шага с `waitForResume`
+         */
+        this.resume = () => {
+            if (this.status !== 'waiting-resume') {
+                return;
+            }
+            this.status = 'running';
+            this.publishStep();
+        };
+        /**
+         * Показ тура из сохранённого прогресса по запросу пользователя
+         */
+        this.restore = async () => {
+            const persisted = await this.progressStorage.load();
+            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.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.status = 'idle';
+            this.exitController.reset();
+            this.releaseStep();
+            this.config.onClose?.(reason);
+        };
+        this.handleError = (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_1.StepNavigator(config.steps);
+        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({
+            close: () => this.exit('dismissed'),
+            onChange: () => this.publishStep(),
+        });
+    }
+    /**
+     * Разрешена ли навигация сейчас: тур показан на экране и владеет активным
+     * шагом store
+     */
+    canNavigate() {
+        return this.status === 'running' && this.activeStepStore.isActiveTour(this);
+    }
+    /**
+     * Переход к текущему шагу. Шаг с `waitForResume` ставит тур в ожидание
+     * и не отрисовывается до явного `resume()`.
+     */
+    enterCurrentStep() {
+        // Показывать нечего: у тура нет ни одного видимого (не-пропущенного) шага.
+        if (this.navigator.total === 0) {
+            this.status = 'idle';
+            this.releaseStep();
+            return;
+        }
+        const step = this.navigator.current;
+        if (step.waitForResume) {
+            this.status = 'waiting-resume';
+            this.releaseStep();
+            return;
+        }
+        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();
+        }
+    }
+}
+exports.OnboardingTour = OnboardingTour;

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

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

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

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

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

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

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

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProgressStorage = void 0;
+/**
+ * «Пустой» прогресс
+ */
+const CLEARED_STATE = {
+    lastStepName: '',
+    isCompleted: false,
+    isDismissed: false,
+};
+/**
+ * Обёртка над переданной SaveStrategy, изолирующая тур от исключений хранилища
+ *
+ * Записи выполняются строго последовательно : при async-стратегии это
+ * не даёт конкурентным вызовам переставиться местами — быстрый next/next,
+ * save→reset или save→skip сохранят порядок.
+ * `load()` ждёт текущее сохранение, поэтому читает уже применённое состояние.
+ */
+class ProgressStorage {
+    constructor(strategy) {
+        this.strategy = strategy;
+        this.saving = Promise.resolve();
+    }
+    async load() {
+        // Дожидаемся текущего сохранения, чтобы не прочитать состояние до него.
+        await this.saving;
+        try {
+            return await this.strategy.load();
+        }
+        catch {
+            return null;
+        }
+    }
+    save(state) {
+        return this.enqueue(() => this.strategy.save(state));
+    }
+    /**
+     * Полный сброс прогресса. Если стратегия умеет `remove` — запись удаляется;
+     * иначе поверх пишется пустое состояние.
+     */
+    reset() {
+        return this.enqueue(() => {
+            if (this.strategy.remove) {
+                return this.strategy.remove();
+            }
+            return this.strategy.save(CLEARED_STATE);
+        });
+    }
+    enqueue(write) {
+        this.saving = this.saving.then(async () => {
+            try {
+                await write();
+            }
+            catch {
+                // Ошибка хранилища не должна ронять тур;
+            }
+        });
+        return this.saving;
+    }
+}
+exports.ProgressStorage = ProgressStorage;

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

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

package/node/components/Onboarding/core/ProgressStorage/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("./ProgressStorage"), exports);

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

@@ -0,0 +1,28 @@
+import { type Step } from '../../types';
+/**
+ * Навигатор по шагам тура. Пропущенные шаги в навигации и в прогрессе не существуют.
+ */
+export declare class StepNavigator<TSteps extends readonly Step[] = readonly Step[]> {
+    private readonly steps;
+    /** Видимые шаги в порядке прохождения. */
+    private visibleSteps;
+    /** Текущая позиция среди видимых шагов */
+    private cursor;
+    constructor(steps: TSteps);
+    get current(): TSteps[number];
+    get position(): number;
+    get total(): number;
+    get hasNext(): boolean;
+    get hasPrev(): boolean;
+    next(): TSteps[number];
+    prev(): TSteps[number];
+    goToPosition(position: number): TSteps[number];
+    goToStep(stepName: string): TSteps[number];
+    /**
+     * Пересобирает список видимых шагов под актуальное состояние (здесь и только
+     * здесь вычисляются предикаты `shouldSkip`) и встаёт на первый шаг. Вызывается
+     * при (пере)запуске тура.
+     */
+    reset(): TSteps[number];
+    private collectVisibleSteps;
+}

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

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StepNavigator = void 0;
+/**
+ * Нужно ли пропустить шаг.
+ */
+const isStepSkipped = (step) => {
+    const { shouldSkip } = step;
+    return typeof shouldSkip === 'function' ? shouldSkip() : Boolean(shouldSkip);
+};
+/**
+ * Навигатор по шагам тура. Пропущенные шаги в навигации и в прогрессе не существуют.
+ */
+class StepNavigator {
+    constructor(steps) {
+        this.steps = steps;
+        /** Видимые шаги в порядке прохождения. */
+        this.visibleSteps = [];
+        /** Текущая позиция среди видимых шагов */
+        this.cursor = 0;
+        this.visibleSteps = this.collectVisibleSteps();
+    }
+    get current() {
+        return this.visibleSteps[this.cursor] ?? this.steps[0];
+    }
+    get position() {
+        return this.cursor;
+    }
+    get total() {
+        return this.visibleSteps.length;
+    }
+    get hasNext() {
+        return this.cursor < this.visibleSteps.length - 1;
+    }
+    get hasPrev() {
+        return this.cursor > 0;
+    }
+    next() {
+        if (this.hasNext) {
+            this.cursor += 1;
+        }
+        return this.current;
+    }
+    prev() {
+        if (this.hasPrev) {
+            this.cursor -= 1;
+        }
+        return this.current;
+    }
+    goToPosition(position) {
+        if (position >= 0 && position < this.visibleSteps.length) {
+            this.cursor = position;
+        }
+        return this.current;
+    }
+    goToStep(stepName) {
+        const position = this.visibleSteps.findIndex((step) => step.name === stepName);
+        if (position !== -1) {
+            this.cursor = position;
+        }
+        return this.current;
+    }
+    /**
+     * Пересобирает список видимых шагов под актуальное состояние (здесь и только
+     * здесь вычисляются предикаты `shouldSkip`) и встаёт на первый шаг. Вызывается
+     * при (пере)запуске тура.
+     */
+    reset() {
+        this.visibleSteps = this.collectVisibleSteps();
+        this.cursor = 0;
+        return this.current;
+    }
+    collectVisibleSteps() {
+        return this.steps.filter((step) => !isStepSkipped(step));
+    }
+}
+exports.StepNavigator = StepNavigator;

package/node/components/Onboarding/core/StepNavigator/index.d.ts

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

package/node/components/Onboarding/core/StepNavigator/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("./StepNavigator"), exports);

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

@@ -0,0 +1,19 @@
+import { type OnboardingTourConfig, type ResolvedStep, type Step, type StepOverride, type TourPresentation } from '../../types';
+/**
+ * Вычисляет итоговые значения по приоритету источников:
+ * - `title`/`content`: рантайм-override → значение шага;
+ * - `position`/`dialogSize`/видимость кнопок: шаг → значение по умолчанию;
+ * - `isInteractive`/`waitForTimeout`: шаг → конфигурация тура → значение по умолчанию;
+ * - презентация тура (`resolvePresentation`): конфигурация тура → значение по умолчанию.
+ */
+export declare class StepResolver {
+    private readonly config;
+    constructor(config: OnboardingTourConfig<readonly Step[]>);
+    resolve(step: Step, override?: StepOverride): ResolvedStep;
+    private resolveWaitForTimeout;
+    resolveIsInteractive(step: Step): boolean;
+    /**
+     * Конфигурация тура с применёнными значениями по умолчанию.
+     */
+    resolvePresentation(): TourPresentation;
+}