@astral/ui 4.82.0 → 4.83.0

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

package/components/Onboarding/core/StepResolver/StepResolver.js

@@ -0,0 +1,49 @@
+import { DEFAULT_WAIT_ELEMENT_TIMEOUT_MS } from '../../constants';
+/**
+ * Вычисляет итоговые значения по приоритету источников:
+ * - `title`/`content`: рантайм-override → значение шага;
+ * - `position`/`dialogSize`/видимость кнопок: шаг → значение по умолчанию;
+ * - `isInteractive`/`waitForTimeout`: шаг → конфигурация тура → значение по умолчанию;
+ * - презентация тура (`resolvePresentation`): конфигурация тура → значение по умолчанию.
+ */
+export class StepResolver {
+    constructor(config) {
+        this.config = config;
+    }
+    resolve(step, override) {
+        return {
+            ...step,
+            title: override?.title ?? step.title,
+            content: override?.content ?? step.content,
+            position: step.position ?? 'bottom',
+            dialogSize: step.dialogSize ?? 'xs',
+            isNextButtonVisible: step.isNextButtonVisible ?? true,
+            isPrevButtonVisible: step.isPrevButtonVisible ?? true,
+            waitForTimeout: this.resolveWaitForTimeout(step),
+        };
+    }
+    resolveWaitForTimeout(step) {
+        return (step.waitForTimeout ??
+            this.config.waitForTimeout ??
+            DEFAULT_WAIT_ELEMENT_TIMEOUT_MS);
+    }
+    resolveIsInteractive(step) {
+        return step.isInteractive ?? this.config.isInteractive ?? false;
+    }
+    /**
+     * Конфигурация тура с применёнными значениями по умолчанию.
+     */
+    resolvePresentation() {
+        return {
+            isDotsVisible: this.config.isDotsVisible ?? true,
+            isCounterVisible: this.config.isCounterVisible ?? true,
+            confirmExit: this.config.confirmExit ?? {},
+            buttons: {
+                prevLabel: this.config.buttons?.prevLabel ?? 'Назад',
+                nextLabel: this.config.buttons?.nextLabel ?? 'Далее',
+                finishLabel: this.config.buttons?.finishLabel ?? 'Закрыть',
+                finishVariant: this.config.buttons?.finishVariant ?? 'contained',
+            },
+        };
+    }
+}

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

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

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

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

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

@@ -0,0 +1,16 @@
+import { type Step, type StepHandles, type StepOverride } from '../../types';
+/**
+ * Владеет рантайм-переопределениями содержимого шагов (через `tour.steps[name].setX`)
+ * и строит типобезопасную карту объектов управления `tour.steps`. О каждом изменении сообщает
+ * наружу через `onChange`, чтобы оркестратор перерисовал активный шаг, если он
+ * сейчас показан.
+ */
+export declare class StepsController<TSteps extends readonly Step[]> {
+    private readonly onChange;
+    private readonly overrides;
+    readonly handles: StepHandles<TSteps>;
+    constructor(steps: TSteps, onChange: (stepName: string) => void);
+    getOverride(stepName: string): StepOverride | undefined;
+    private patch;
+    private createHandles;
+}

package/components/Onboarding/core/StepsController/StepsController.js

@@ -0,0 +1,35 @@
+import { TOUR_ID_ATTR } from '../../constants';
+/**
+ * Владеет рантайм-переопределениями содержимого шагов (через `tour.steps[name].setX`)
+ * и строит типобезопасную карту объектов управления `tour.steps`. О каждом изменении сообщает
+ * наружу через `onChange`, чтобы оркестратор перерисовал активный шаг, если он
+ * сейчас показан.
+ */
+export class StepsController {
+    constructor(steps, onChange) {
+        this.onChange = onChange;
+        this.overrides = new Map();
+        this.handles = this.createHandles(steps);
+    }
+    getOverride(stepName) {
+        return this.overrides.get(stepName);
+    }
+    patch(stepName, override) {
+        this.overrides.set(stepName, {
+            ...this.overrides.get(stepName),
+            ...override,
+        });
+        this.onChange(stepName);
+    }
+    createHandles(steps) {
+        const handles = {};
+        steps.forEach((step) => {
+            handles[step.name] = {
+                getHighlightProps: () => ({ [TOUR_ID_ATTR]: step.name }),
+                setTitle: (title) => this.patch(step.name, { title }),
+                setContent: (content) => this.patch(step.name, { content }),
+            };
+        });
+        return handles;
+    }
+}

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

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

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

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

package/components/Onboarding/faker.d.ts

@@ -0,0 +1,27 @@
+import { type ActiveStepState, type ResolvedStep, type SaveStrategy, type Step, type TourProgress } from './types';
+/**
+ * Фабрика шага со значениями по умолчанию standalone-типа.
+ */
+export declare const makeStep: (data?: Partial<Step>) => Step;
+/**
+ * Фабрика шага с уже применёнными значениями по умолчанию.
+ */
+export declare const makeResolvedStep: (data?: Partial<ResolvedStep>) => ResolvedStep;
+/**
+ * Фабрика состояния активного шага, которое тур публикует в store.
+ */
+export declare const makeActiveStepState: (data?: Partial<ActiveStepState>) => ActiveStepState;
+/**
+ * Список standalone-шагов по именам — частый кейс, когда важны только имена и
+ * порядок. `data` применяется к каждому шагу.
+ */
+export declare const makeSteps: (names: string[], data?: Partial<Step>) => Step[];
+/**
+ * Фабрика прогресса тура со значениями по умолчанию «в процессе».
+ */
+export declare const makeTourProgress: (data?: Partial<TourProgress>) => TourProgress;
+/**
+ * Стратегия хранения в памяти со шпионами: `save` пишет в замыкание, `load`
+ * читает оттуда же. Заменяет реальный localStorage/бэкенд в тестах.
+ */
+export declare const createMemoryStrategy: (initial?: TourProgress | null) => SaveStrategy;

package/components/Onboarding/faker.js

@@ -0,0 +1,79 @@
+import { vi } from 'vitest';
+/**
+ * Фабрика шага со значениями по умолчанию standalone-типа.
+ */
+export const makeStep = (data = {}) => ({
+    name: 'step',
+    type: 'standalone',
+    ...data,
+});
+/**
+ * Фабрика шага с уже применёнными значениями по умолчанию.
+ */
+export const makeResolvedStep = (data = {}) => ({
+    name: 'step',
+    type: 'standalone',
+    position: 'bottom',
+    dialogSize: 'xs',
+    isNextButtonVisible: true,
+    isPrevButtonVisible: true,
+    waitForTimeout: 0,
+    ...data,
+});
+/**
+ * Фабрика состояния активного шага, которое тур публикует в store.
+ */
+export const makeActiveStepState = (data = {}) => ({
+    tourName: 'tour',
+    step: makeResolvedStep(),
+    position: 0,
+    total: 1,
+    hasNext: false,
+    hasPrev: false,
+    isInteractive: false,
+    isConfirming: false,
+    isDotsVisible: true,
+    isCounterVisible: true,
+    confirmExit: {},
+    buttons: {
+        prevLabel: 'Назад',
+        nextLabel: 'Далее',
+        finishLabel: 'Закрыть',
+        finishVariant: 'contained',
+    },
+    onNext: vi.fn(),
+    onPrev: vi.fn(),
+    onSelectStep: vi.fn(),
+    requestClose: vi.fn(),
+    onConfirmExit: vi.fn(),
+    onCancelExit: vi.fn(),
+    onError: vi.fn(),
+    ...data,
+});
+/**
+ * Список standalone-шагов по именам — частый кейс, когда важны только имена и
+ * порядок. `data` применяется к каждому шагу.
+ */
+export const makeSteps = (names, data = {}) => names.map((name) => makeStep({ name, ...data }));
+/**
+ * Фабрика прогресса тура со значениями по умолчанию «в процессе».
+ */
+export const makeTourProgress = (data = {}) => ({
+    lastStepName: 'step',
+    isCompleted: false,
+    isDismissed: false,
+    ...data,
+});
+/**
+ * Стратегия хранения в памяти со шпионами: `save` пишет в замыкание, `load`
+ * читает оттуда же. Заменяет реальный localStorage/бэкенд в тестах.
+ */
+export const createMemoryStrategy = (initial = null) => {
+    let saved = initial;
+    return {
+        save: vi.fn((data) => {
+            saved = data;
+        }),
+        load: vi.fn(() => saved),
+    };
+};

package/components/Onboarding/index.d.ts

@@ -0,0 +1,5 @@
+export { createOnboarding, type Onboarding } from './Onboarding';
+export { OnboardingContainer, type OnboardingContainerProps, } from './ui/OnboardingContainer';
+export { LocalStorageSaveStrategy } from './services/LocalStorageSaveStrategy';
+export type { OnboardingTour } from './core/OnboardingTour';
+export type { OnboardingConfig, OnboardingTourConfig, SaveStrategy as OnboardingSaveStrategy, TourProgress as OnboardingTourProgress, } from './types';

package/components/Onboarding/index.js

@@ -0,0 +1,3 @@
+export { createOnboarding } from './Onboarding';
+export { OnboardingContainer, } from './ui/OnboardingContainer';
+export { LocalStorageSaveStrategy } from './services/LocalStorageSaveStrategy';

package/components/Onboarding/public.d.ts

@@ -0,0 +1,5 @@
+export type { OnboardingTour } from './core/OnboardingTour';
+export { createOnboarding, type Onboarding } from './Onboarding';
+export { LocalStorageSaveStrategy } from './services/LocalStorageSaveStrategy';
+export type { OnboardingConfig, OnboardingTourConfig, SaveStrategy as OnboardingSaveStrategy, TourProgress as OnboardingTourProgress, } from './types';
+export { OnboardingContainer, type OnboardingContainerProps, } from './ui/OnboardingContainer';

package/components/Onboarding/public.js

@@ -0,0 +1,3 @@
+export { createOnboarding } from './Onboarding';
+export { LocalStorageSaveStrategy } from './services/LocalStorageSaveStrategy';
+export { OnboardingContainer, } from './ui/OnboardingContainer';

package/components/Onboarding/services/LocalStorageSaveStrategy/LocalStorageSaveStrategy.d.ts

@@ -0,0 +1,20 @@
+import { type SaveStrategy, type SaveStrategyFactory, type TourProgress } from '../../types';
+/**
+ * Префикс ключа `localStorage` для стратегии хранения прогресса по умолчанию.
+ * К нему добавляется имя тура.
+ */
+export declare const LOCAL_STORAGE_KEY_PREFIX = "astral-ui-onboarding:";
+/**
+ * Реализация по умолчанию SaveStrategy: хранит прогресс тура в `localStorage`
+ */
+export declare class LocalStorageSaveStrategy implements SaveStrategy {
+    /**
+     * Ключ уникален на тур (префикс + имя), чтобы туры не перетирали друг друга.
+     */
+    private readonly key;
+    constructor(tourName: string);
+    save: (data: TourProgress) => void;
+    load: () => TourProgress | null;
+    remove: () => void;
+}
+export declare const createLocalStorageSaveStrategy: SaveStrategyFactory;

package/components/Onboarding/services/LocalStorageSaveStrategy/LocalStorageSaveStrategy.js

@@ -0,0 +1,24 @@
+/**
+ * Префикс ключа `localStorage` для стратегии хранения прогресса по умолчанию.
+ * К нему добавляется имя тура.
+ */
+export const LOCAL_STORAGE_KEY_PREFIX = 'astral-ui-onboarding:';
+/**
+ * Реализация по умолчанию SaveStrategy: хранит прогресс тура в `localStorage`
+ */
+export class LocalStorageSaveStrategy {
+    constructor(tourName) {
+        this.save = (data) => {
+            localStorage.setItem(this.key, JSON.stringify(data));
+        };
+        this.load = () => {
+            const raw = localStorage.getItem(this.key);
+            return raw ? JSON.parse(raw) : null;
+        };
+        this.remove = () => {
+            localStorage.removeItem(this.key);
+        };
+        this.key = `${LOCAL_STORAGE_KEY_PREFIX}${tourName}`;
+    }
+}
+export const createLocalStorageSaveStrategy = (tourName) => new LocalStorageSaveStrategy(tourName);

package/components/Onboarding/services/LocalStorageSaveStrategy/index.d.ts

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

package/components/Onboarding/services/LocalStorageSaveStrategy/index.js

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

package/components/Onboarding/types/config.d.ts

@@ -0,0 +1,18 @@
+import { type SaveStrategyFactory } from './progress';
+/**
+ * Конфигурация экземпляра онбординга
+ */
+export type OnboardingConfig = {
+    /**
+     * Фабрика стратегии хранения прогресса: вызывается при создании каждого
+     * тура, получает его имя. По умолчанию — `localStorage`.
+     *
+     * @example
+     * // Бэкенд реализация
+     * saveStrategy: (tourName) => ({
+     *   save: (data) => api.saveProgress(tourName, data),
+     *   load: () => api.loadProgress(tourName),
+     * })
+     */
+    saveStrategy?: SaveStrategyFactory;
+};

package/components/Onboarding/types/config.js

@@ -0,0 +1 @@
+export {};

package/components/Onboarding/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './step';
+export * from './progress';
+export * from './config';
+export * from './tour';

package/components/Onboarding/types/index.js

@@ -0,0 +1,4 @@
+export * from './step';
+export * from './progress';
+export * from './config';
+export * from './tour';

package/components/Onboarding/types/progress.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Прогресс прохождения тура, сохраняемый между сессиями
+ */
+export type TourProgress = {
+    lastStepName: string;
+    /**
+     * Тур пройден до конца.
+     */
+    isCompleted: boolean;
+    /**
+     * «Больше не показывать»: ставится при прохождении до конца ИЛИ подтверждённом
+     * выходе.
+     */
+    isDismissed: boolean;
+};
+/**
+ * Стратегия хранения прогресса тура.
+ */
+export type SaveStrategy = {
+    save: (data: TourProgress) => void | Promise<void>;
+    load: () => TourProgress | null | Promise<TourProgress | null>;
+    /**
+     * Полное удаление сохранённого прогресса.
+     * Если не реализовано, прогресс сбрасывается перезаписью пустым состоянием.
+     */
+    remove?: () => void | Promise<void>;
+};
+export type SaveStrategyFactory = (tourName: string) => SaveStrategy;

package/components/Onboarding/types/progress.js

@@ -0,0 +1 @@
+export {};

package/components/Onboarding/types/step.d.ts

@@ -0,0 +1,144 @@
+import { type ReactNode } from 'react';
+import { type DialogSize } from '../../Dialog';
+import { type TOUR_ID_ATTR } from '../constants';
+/**
+ * Содержимое шага.
+ */
+export type StepContent = ReactNode;
+/**
+ * Рантайм-переопределение содержимого шага.
+ */
+export type StepOverride = {
+    title?: StepContent;
+    content?: StepContent;
+};
+/**
+ * Тип шага:
+ * - `standalone` — самостоятельная модалка по центру экрана;
+ * - `highlight` — подсветка элемента UI рядом с popover.
+ */
+export type StepType = 'highlight' | 'standalone';
+/**
+ * Желаемая позиция popover относительно подсвечиваемого элемента.
+ */
+export type StepPosition = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * Описание одного шага тура.
+ */
+export type Step = {
+    /**
+     * Уникальное в рамках тура имя шага.
+     */
+    name: string;
+    /**
+     * Заголовок шага.
+     */
+    title?: StepContent;
+    /**
+     * Содержимое шага.
+     */
+    content?: StepContent;
+    /**
+     * Тип шага:
+     * - `standalone` — самостоятельная модалка по центру экрана;
+     * - `highlight` — подсветка элемента UI рядом с popover.
+     */
+    type: StepType;
+    /**
+     * Желаемая позиция popover (только для highlight).
+     * @default 'bottom'
+     */
+    position?: StepPosition;
+    /**
+     * Отступ подсветки вокруг выделяемого элемента.
+     * @default '8px'
+     * @example '4px'
+     */
+    highlightOffset?: `${number}px`;
+    /**
+     * Можно ли кликать по подсвечиваемому элементу во время тура.
+     * @default false
+     */
+    isInteractive?: boolean;
+    /**
+     * Показывать ли кнопку перехода вперёд.
+     * @default true
+     */
+    isNextButtonVisible?: boolean;
+    /**
+     * Показывать ли кнопку перехода назад.
+     * @default true
+     */
+    isPrevButtonVisible?: boolean;
+    /**
+     * Обратный вызов перед переходом к следующему шагу.
+     */
+    onNextClick?: () => void;
+    /**
+     * Обратный вызов перед переходом к предыдущему шагу.
+     */
+    onPrevClick?: () => void;
+    /**
+     * Пропускать шаг при навигации.
+     */
+    shouldSkip?: boolean | (() => boolean);
+    /**
+     * При переходе на этот шаг тур встаёт в ожидание и НЕ отрисовывает шаг, пока не
+     * будет вызван `tour.resume()`.
+     */
+    waitForResume?: boolean;
+    /**
+     * Размер диалога для standalone-шага. Для highlight-шага игнорируется.
+     * @default 'xs'
+     */
+    dialogSize?: DialogSize;
+    /**
+     * Сколько миллисекунд тур ждёт появления элемента highlight-шага в DOM.
+     *
+     * По умолчанию (`0`) элемент ищется сразу; если его нет — срабатывает `onError`.
+     * Задавайте, только когда элемент появляется сам (анимация, поздняя отрисовка).
+     * Если появление зависит от действия пользователя или загрузки данных —
+     * используйте `waitForResume`, а не тайм-аут: подобранное вручную значение
+     * сработает у вас, но на более медленном устройстве или соединении пользователя
+     * тур может не дождаться элемента.
+     * @default 0
+     */
+    waitForTimeout?: number;
+};
+/**
+ * Шаг с уже применёнными значениями по умолчанию.
+ */
+export type ResolvedStep = Step & {
+    isNextButtonVisible: boolean;
+    isPrevButtonVisible: boolean;
+    /**
+     * Итоговая позиция popover: значение по умолчанию -`'bottom'`.
+     */
+    position: StepPosition;
+    /**
+     * Итоговый размер диалога standalone-шага: значение по умолчанию `'xs'`.
+     */
+    dialogSize: DialogSize;
+    /**
+     * Итоговый тайм-аут ожидания элемента (мс)`
+     */
+    waitForTimeout: number;
+};
+/**
+ * Объект управления шагом, возвращаемый через `tour.steps[stepName]/tour.steps.stepName`.
+ */
+export type StepHandle = {
+    /**
+     * Параметры (атрибут `data-tour-id`) для передачи в подсвечиваемый элемент.
+     * @example <button {...tour.steps.save.getHighlightProps()} />
+     */
+    getHighlightProps: () => Record<typeof TOUR_ID_ATTR, string>;
+    setTitle: (title: StepContent) => void;
+    setContent: (content: StepContent) => void;
+};
+/**
+ * Карта объектов управления шагами по их литеральным именам — типобезопасный `tour.steps`.
+ */
+export type StepHandles<TSteps extends readonly Step[]> = {
+    [TName in TSteps[number]['name']]: StepHandle;
+};

package/components/Onboarding/types/step.js

@@ -0,0 +1 @@
+export {};