h2o-library 2.0.0 → 2.1.0

package/dist/hooks/src/use-onboarding.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pluggable persistence adapter for onboarding flows. Swap to back completion
+ * with cookies, a backend, or anything else by implementing these two methods.
+ *
+ * @property {(id: string) => boolean} isCompleted - Whether the flow `id` was already finished/skipped.
+ * @property {(id: string, completed: boolean) => void} setCompleted - Persist (or clear) completion for `id`.
+ */
+export interface OnboardingStorage {
+    isCompleted: (id: string) => boolean;
+    setCompleted: (id: string, completed: boolean) => void;
+}
+export declare const localStorageOnboarding: OnboardingStorage;
+export declare const memoryOnboarding: OnboardingStorage;
+/**
+ * Options for {@link useOnboarding}.
+ *
+ * @property {string} id - Stable flow identifier; used as the persistence key.
+ * @property {number} total - Number of steps in the flow.
+ * @property {boolean} [run] - Controlled active state. Omit to let the hook manage start/stop internally.
+ * @property {boolean} [autoStart] - In uncontrolled mode, start on mount when the flow is not yet completed. Default `true`.
+ * @property {boolean} [persist] - Persist completion so a finished/skipped flow does not auto-restart. Default `true`.
+ * @property {OnboardingStorage} [storage] - Persistence adapter. Default `localStorageOnboarding`.
+ * @property {number} [startDelay] - Delay (ms) before auto-start, e.g. to let the page settle. Default `0`.
+ */
+export interface UseOnboardingOptions {
+    id: string;
+    total: number;
+    run?: boolean;
+    autoStart?: boolean;
+    persist?: boolean;
+    storage?: OnboardingStorage;
+    startDelay?: number;
+    onStart?: () => void;
+    onStepChange?: (index: number, previous: number) => void;
+    onSkip?: (index: number) => void;
+    onFinish?: () => void;
+    onStop?: () => void;
+}
+/** Imperative control surface + state returned by {@link useOnboarding}. */
+export interface UseOnboardingReturn {
+    active: boolean;
+    index: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+    completed: boolean;
+    start: () => void;
+    stop: () => void;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    skip: () => void;
+    finish: () => void;
+    reset: () => void;
+}
+/**
+ * Headless onboarding/tour state machine: drives a flow by `id`, tracks the
+ * current step, persists completion, and supports controlled or uncontrolled use.
+ *
+ * Pair with the `Onboarding` component for ready-made coachmarks, or render your
+ * own UI from the returned state for a fully custom flow.
+ *
+ * @param {UseOnboardingOptions} options
+ * @returns {UseOnboardingReturn} State (`active`, `index`, `isFirst`, …) and controls (`next`, `prev`, `skip`, `finish`, `reset`, …).
+ */
+export declare function useOnboarding({ id, total, run, autoStart, persist, storage, startDelay, onStart, onStepChange, onSkip, onFinish, onStop, }: UseOnboardingOptions): UseOnboardingReturn;