@apollovisionlabs/guide-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,175 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface Rect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+type MissingTargetPolicy = 'skip' | 'wait' | 'error';
+type Placement = 'top' | 'bottom' | 'left' | 'right';
+interface Step {
+    /** Logical key carried by the data-guide attribute on the targeted element. */
+    target: string;
+    /** Route pattern on which the step is valid. Accepts :param and *. */
+    route?: string;
+    /** Concrete path to navigate to. Defaults to route when route is literal. */
+    navigateTo?: string;
+    placement?: Placement;
+    /** Lets the user interact with the page during the step. */
+    interactive?: boolean;
+    title?: string;
+    titleKey?: string;
+    body?: string;
+    bodyKey?: string;
+    /** Overrides the global policy for this step. */
+    onMissingTarget?: MissingTargetPolicy;
+}
+interface Tour {
+    id: string;
+    steps: Step[];
+}
+type TourStatus = 'idle' | 'running' | 'paused' | 'completed';
+interface TourProgress {
+    status: 'in-progress' | 'completed';
+    stepIndex: number;
+}
+interface GuideStorage {
+    read(tourId: string): Promise<TourProgress | null>;
+    write(tourId: string, progress: TourProgress): Promise<void>;
+}
+type GuideEvent = {
+    type: 'tour:start';
+    tourId: string;
+    stepIndex: number;
+} | {
+    type: 'tour:complete';
+    tourId: string;
+} | {
+    type: 'tour:stop';
+    tourId: string;
+    stepIndex: number;
+} | {
+    type: 'step:show';
+    tourId: string;
+    stepIndex: number;
+    target: string;
+} | {
+    type: 'target:missing';
+    tourId: string;
+    stepIndex: number;
+    target: string;
+};
+type Translate = (key: string) => string;
+
+declare function createMemoryStorage(initial?: Record<string, TourProgress>): GuideStorage;
+declare function createBrowserStorage(namespace?: string): GuideStorage;
+
+declare function isLiteralRoute(pattern: string): boolean;
+declare function matchRoute(pattern: string, pathname: string): boolean;
+
+interface TourState {
+    tourId: string | null;
+    stepIndex: number;
+    status: TourStatus;
+}
+type TourAction = {
+    type: 'START';
+    tourId: string;
+    stepIndex: number;
+} | {
+    type: 'NEXT';
+    stepCount: number;
+} | {
+    type: 'PREVIOUS';
+} | {
+    type: 'PAUSE';
+} | {
+    type: 'RESUME';
+} | {
+    type: 'STOP';
+};
+declare const initialTourState: TourState;
+declare function tourReducer(state: TourState, action: TourAction): TourState;
+
+interface UseTargetElementOptions {
+    timeoutMs?: number;
+    attribute?: string;
+}
+declare function useTargetElement(target: string | null, options?: UseTargetElementOptions): {
+    element: HTMLElement | null;
+    timedOut: boolean;
+};
+
+declare function useElementRect(element: HTMLElement | null): Rect | null;
+
+interface UseFocusTrapOptions {
+    /**
+     * Element that receives focus on entry. 'first' takes the first focusable element; 'container'
+     * takes the container itself, which must then carry tabIndex={-1}. Defaults to 'first'.
+     */
+    initialFocus?: 'first' | 'container';
+}
+declare function useFocusTrap(container: HTMLElement | null, active: boolean, options?: UseFocusTrapOptions): void;
+declare function useAnnouncer(): (message: string) => void;
+declare function usePrefersReducedMotion(): boolean;
+
+interface ActiveStep {
+    tourId: string;
+    step: Step;
+    stepIndex: number;
+    stepCount: number;
+    element: HTMLElement | null;
+    rect: Rect | null;
+    title: string;
+    body: string;
+    isFirst: boolean;
+    isLast: boolean;
+    next: () => void;
+    previous: () => void;
+    stop: () => void;
+}
+interface GuideContextValue {
+    state: TourState;
+    activeStep: ActiveStep | null;
+    start: (tourId: string, options?: {
+        from?: number;
+        resume?: boolean;
+    }) => Promise<void>;
+    next: () => void;
+    previous: () => void;
+    stop: () => void;
+}
+declare const GuideContext: react.Context<GuideContextValue | null>;
+interface GuideProviderProps {
+    tours: Tour[];
+    children: ReactNode;
+    navigate?: (path: string) => void;
+    location?: string;
+    storage?: GuideStorage;
+    translate?: Translate;
+    onEvent?: (event: GuideEvent) => void;
+    onMissingTarget?: MissingTargetPolicy;
+    targetTimeoutMs?: number;
+}
+declare function GuideProvider({ tours, children, navigate, location, storage, translate, onEvent, onMissingTarget, targetTimeoutMs, }: GuideProviderProps): react.JSX.Element;
+
+interface UseTourResult {
+    start: (options?: {
+        from?: number;
+        resume?: boolean;
+    }) => Promise<void>;
+    next: () => void;
+    previous: () => void;
+    stop: () => void;
+    status: TourStatus;
+    stepIndex: number;
+}
+declare function useTour(tourId: string): UseTourResult;
+
+declare function findMissingTargets(tour: Tour, location: string | undefined, attribute?: string): string[];
+
+declare function useGuideStep(): ActiveStep | null;
+
+export { type ActiveStep, GuideContext, type GuideContextValue, type GuideEvent, GuideProvider, type GuideProviderProps, type GuideStorage, type MissingTargetPolicy, type Placement, type Rect, type Step, type Tour, type TourAction, type TourProgress, type TourState, type TourStatus, type Translate, type UseFocusTrapOptions, type UseTargetElementOptions, type UseTourResult, createBrowserStorage, createMemoryStorage, findMissingTargets, initialTourState, isLiteralRoute, matchRoute, tourReducer, useAnnouncer, useElementRect, useFocusTrap, useGuideStep, usePrefersReducedMotion, useTargetElement, useTour };

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface Rect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+type MissingTargetPolicy = 'skip' | 'wait' | 'error';
+type Placement = 'top' | 'bottom' | 'left' | 'right';
+interface Step {
+    /** Logical key carried by the data-guide attribute on the targeted element. */
+    target: string;
+    /** Route pattern on which the step is valid. Accepts :param and *. */
+    route?: string;
+    /** Concrete path to navigate to. Defaults to route when route is literal. */
+    navigateTo?: string;
+    placement?: Placement;
+    /** Lets the user interact with the page during the step. */
+    interactive?: boolean;
+    title?: string;
+    titleKey?: string;
+    body?: string;
+    bodyKey?: string;
+    /** Overrides the global policy for this step. */
+    onMissingTarget?: MissingTargetPolicy;
+}
+interface Tour {
+    id: string;
+    steps: Step[];
+}
+type TourStatus = 'idle' | 'running' | 'paused' | 'completed';
+interface TourProgress {
+    status: 'in-progress' | 'completed';
+    stepIndex: number;
+}
+interface GuideStorage {
+    read(tourId: string): Promise<TourProgress | null>;
+    write(tourId: string, progress: TourProgress): Promise<void>;
+}
+type GuideEvent = {
+    type: 'tour:start';
+    tourId: string;
+    stepIndex: number;
+} | {
+    type: 'tour:complete';
+    tourId: string;
+} | {
+    type: 'tour:stop';
+    tourId: string;
+    stepIndex: number;
+} | {
+    type: 'step:show';
+    tourId: string;
+    stepIndex: number;
+    target: string;
+} | {
+    type: 'target:missing';
+    tourId: string;
+    stepIndex: number;
+    target: string;
+};
+type Translate = (key: string) => string;
+
+declare function createMemoryStorage(initial?: Record<string, TourProgress>): GuideStorage;
+declare function createBrowserStorage(namespace?: string): GuideStorage;
+
+declare function isLiteralRoute(pattern: string): boolean;
+declare function matchRoute(pattern: string, pathname: string): boolean;
+
+interface TourState {
+    tourId: string | null;
+    stepIndex: number;
+    status: TourStatus;
+}
+type TourAction = {
+    type: 'START';
+    tourId: string;
+    stepIndex: number;
+} | {
+    type: 'NEXT';
+    stepCount: number;
+} | {
+    type: 'PREVIOUS';
+} | {
+    type: 'PAUSE';
+} | {
+    type: 'RESUME';
+} | {
+    type: 'STOP';
+};
+declare const initialTourState: TourState;
+declare function tourReducer(state: TourState, action: TourAction): TourState;
+
+interface UseTargetElementOptions {
+    timeoutMs?: number;
+    attribute?: string;
+}
+declare function useTargetElement(target: string | null, options?: UseTargetElementOptions): {
+    element: HTMLElement | null;
+    timedOut: boolean;
+};
+
+declare function useElementRect(element: HTMLElement | null): Rect | null;
+
+interface UseFocusTrapOptions {
+    /**
+     * Element that receives focus on entry. 'first' takes the first focusable element; 'container'
+     * takes the container itself, which must then carry tabIndex={-1}. Defaults to 'first'.
+     */
+    initialFocus?: 'first' | 'container';
+}
+declare function useFocusTrap(container: HTMLElement | null, active: boolean, options?: UseFocusTrapOptions): void;
+declare function useAnnouncer(): (message: string) => void;
+declare function usePrefersReducedMotion(): boolean;
+
+interface ActiveStep {
+    tourId: string;
+    step: Step;
+    stepIndex: number;
+    stepCount: number;
+    element: HTMLElement | null;
+    rect: Rect | null;
+    title: string;
+    body: string;
+    isFirst: boolean;
+    isLast: boolean;
+    next: () => void;
+    previous: () => void;
+    stop: () => void;
+}
+interface GuideContextValue {
+    state: TourState;
+    activeStep: ActiveStep | null;
+    start: (tourId: string, options?: {
+        from?: number;
+        resume?: boolean;
+    }) => Promise<void>;
+    next: () => void;
+    previous: () => void;
+    stop: () => void;
+}
+declare const GuideContext: react.Context<GuideContextValue | null>;
+interface GuideProviderProps {
+    tours: Tour[];
+    children: ReactNode;
+    navigate?: (path: string) => void;
+    location?: string;
+    storage?: GuideStorage;
+    translate?: Translate;
+    onEvent?: (event: GuideEvent) => void;
+    onMissingTarget?: MissingTargetPolicy;
+    targetTimeoutMs?: number;
+}
+declare function GuideProvider({ tours, children, navigate, location, storage, translate, onEvent, onMissingTarget, targetTimeoutMs, }: GuideProviderProps): react.JSX.Element;
+
+interface UseTourResult {
+    start: (options?: {
+        from?: number;
+        resume?: boolean;
+    }) => Promise<void>;
+    next: () => void;
+    previous: () => void;
+    stop: () => void;
+    status: TourStatus;
+    stepIndex: number;
+}
+declare function useTour(tourId: string): UseTourResult;
+
+declare function findMissingTargets(tour: Tour, location: string | undefined, attribute?: string): string[];
+
+declare function useGuideStep(): ActiveStep | null;
+
+export { type ActiveStep, GuideContext, type GuideContextValue, type GuideEvent, GuideProvider, type GuideProviderProps, type GuideStorage, type MissingTargetPolicy, type Placement, type Rect, type Step, type Tour, type TourAction, type TourProgress, type TourState, type TourStatus, type Translate, type UseFocusTrapOptions, type UseTargetElementOptions, type UseTourResult, createBrowserStorage, createMemoryStorage, findMissingTargets, initialTourState, isLiteralRoute, matchRoute, tourReducer, useAnnouncer, useElementRect, useFocusTrap, useGuideStep, usePrefersReducedMotion, useTargetElement, useTour };