@tour-kit/core API

import { TourKitProvider } from '@tour-kit/core';

<TourKitProvider config={config} dir="ltr">
  {children}
</TourKitProvider>

import { TourProvider } from '@tour-kit/core';

<TourProvider tours={tours} router={router}>
  {children}
</TourProvider>

import { useTour } from '@tour-kit/core';

const {
  isActive,
  currentStep,
  currentStepIndex,
  totalSteps,
  isFirstStep,
  isLastStep,
  progress,
  isLoading,
  isTransitioning,
  start,
  next,
  prev,
  goTo,
  skip,
  complete,
  stop,
  isStepActive,
  getStep,
} = useTour(tourId?);

import { useStep } from '@tour-kit/core';

const { isActive, isVisible, hasCompleted, targetElement, targetRect } = useStep(stepId);

import { useSpotlight } from '@tour-kit/core';

const { isVisible, targetRect, overlayStyle, cutoutStyle, show, hide, update } = useSpotlight();

import { useElementPosition } from '@tour-kit/core';

const { element, rect, scrollParent, update } = useElementPosition(target);

import { useKeyboardNavigation } from '@tour-kit/core';

useKeyboardNavigation(config?);

import { useFocusTrap } from '@tour-kit/core';

const { containerRef, activate, deactivate } = useFocusTrap(enabled?);

import { usePersistence } from '@tour-kit/core';

const {
  getCompletedTours,
  getSkippedTours,
  getDontShowAgain,
  getLastStep,
  markCompleted,
  markSkipped,
  setDontShowAgain,
  saveStep,
  reset,
} = usePersistence(config?);

import { useRoutePersistence } from '@tour-kit/core';

const { save, load, clear, isStale } = useRoutePersistence(config);

import { useMediaQuery } from '@tour-kit/core';

const matches = useMediaQuery('(min-width: 768px)');

import { usePrefersReducedMotion } from '@tour-kit/core';

const prefersReducedMotion = usePrefersReducedMotion();

import { useAdvanceOn } from '@tour-kit/core';

useAdvanceOn({
  event: 'click',
  selector: '#target',
  onAdvance: () => next(),
});

import { createTour, createNamedTour, createStep, createNamedStep } from '@tour-kit/core';

// Auto-generated ID
const tour = createTour(steps, options?);

// Named tour
const namedTour = createNamedTour('my-tour', steps, options?);

// Auto-generated step ID
const step = createStep(target, content, options?);

// Named step
const namedStep = createNamedStep('step-1', target, content, options?);

import {
  createStorageAdapter,
  createNoopStorage,
  createCookieStorage,
  createPrefixedStorage,
  safeJSONParse,
} from '@tour-kit/core';

// Create adapter
const adapter = createStorageAdapter('localStorage'); // or 'sessionStorage'

// Cookie storage
const cookies = createCookieStorage({ expires: 30 });

// Prefixed storage
const prefixed = createPrefixedStorage(adapter, 'myapp');

// SSR-safe storage
const noop = createNoopStorage();

// Safe JSON parsing
const data = safeJSONParse<MyType>(json, defaultValue);

import {
  getElement,
  isElementVisible,
  isElementPartiallyVisible,
  waitForElement,
  getFocusableElements,
  getScrollParent,
} from '@tour-kit/core';

// Resolve element from selector, ref, or HTMLElement
const element = getElement('#my-element');

// Check visibility
const visible = isElementVisible(element);
const partial = isElementPartiallyVisible(element);

// Wait for element to appear
const el = await waitForElement('#dynamic', { timeout: 5000 });

// Get focusable elements for focus trap
const focusable = getFocusableElements(container);

// Find scroll parent
const scrollParent = getScrollParent(element);

import {
  calculatePosition,
  calculatePositionWithCollision,
  getElementRect,
  getViewportDimensions,
  parsePlacement,
  wouldOverflow,
  getOppositeSide,
  getFallbackPlacements,
  mirrorPlacementForRTL,
} from '@tour-kit/core';

// Calculate tooltip position
const pos = calculatePosition(targetRect, tooltipSize, 'bottom', offset?);

// With collision detection
const result = calculatePositionWithCollision(targetRect, tooltipSize, 'bottom', options?);

// Parse placement string
const { side, alignment } = parsePlacement('bottom-start');

// RTL support
const rtlPlacement = mirrorPlacementForRTL('left-start', true);

import {
  scrollIntoView,
  scrollTo,
  getScrollPosition,
  lockScroll,
} from '@tour-kit/core';

// Scroll element into view
await scrollIntoView(element, { behavior: 'smooth', block: 'center' });

// Scroll to position
scrollTo(container, position, 'smooth');

// Get scroll position
const { x, y } = getScrollPosition(container?);

// Lock scroll
const unlock = lockScroll();
// ... later
unlock();

import {
  announce,
  generateId,
  prefersReducedMotion,
  getStepAnnouncement,
} from '@tour-kit/core';

// Screen reader announcement
announce('Step 1 of 5: Welcome', 'polite');

// Generate unique ID
const id = generateId('tour'); // e.g., 'tour-abc123'

// Check motion preference (non-hook)
const reduced = prefersReducedMotion();

// Format step announcement
const text = getStepAnnouncement('Welcome', 1, 5); // "Step 1 of 5: Welcome"

import { logger } from '@tour-kit/core';

// Configure
logger.configure({ level: 'warn', prefix: '[MyApp]' });

// Use
logger.debug('Debug message');
logger.info('Info message');
logger.warn('Warning message');
logger.error('Error message');

interface TourKitConfig {
  keyboard?: KeyboardConfig;
  spotlight?: SpotlightConfig;
  persistence?: PersistenceConfig;
  a11y?: A11yConfig;
  scroll?: ScrollConfig;
  dir?: 'ltr' | 'rtl' | 'auto';
}

interface KeyboardConfig {
  enabled?: boolean;
  nextKeys?: string[];
  prevKeys?: string[];
  exitKeys?: string[];
  trapFocus?: boolean;
}

interface SpotlightConfig {
  enabled?: boolean;
  color?: string;
  padding?: number;
  borderRadius?: number;
  animate?: boolean;
  animationDuration?: number;
  clickToExit?: boolean;
}

interface PersistenceConfig {
  enabled?: boolean;
  storage?: 'localStorage' | 'sessionStorage' | Storage;
  keyPrefix?: string;
  rememberStep?: boolean;
  trackCompleted?: boolean;
  dontShowAgain?: boolean;
}

interface A11yConfig {
  announceSteps?: boolean;
  ariaLive?: 'polite' | 'assertive';
  focusTrap?: boolean;
  restoreFocus?: boolean;
  reducedMotion?: 'respect' | 'force' | 'ignore';
}

interface ScrollConfig {
  enabled?: boolean;
  behavior?: 'smooth' | 'auto';
  block?: 'start' | 'center' | 'end' | 'nearest';
  offset?: number;
}

interface Tour {
  id: string;
  steps: TourStep[];
  autoStart?: boolean;
  startAt?: number;
  keyboard?: KeyboardConfig;
  spotlight?: SpotlightConfig;
  persistence?: PersistenceConfig;
  a11y?: A11yConfig;
  scroll?: ScrollConfig;
  onStart?: () => void;
  onComplete?: () => void;
  onSkip?: (stepIndex: number) => void;
  onStepChange?: (step: TourStep, index: number) => void;
}

interface TourStep {
  id: string;
  target: string | React.RefObject<HTMLElement>;
  title?: string;
  content?: React.ReactNode;
  placement?: Placement;
  offset?: [number, number];
  route?: string;
  routeMatch?: 'exact' | 'startsWith' | 'contains';
  when?: (context: TourCallbackContext) => boolean | Promise<boolean>;
  advanceOn?: AdvanceOnConfig;
  waitForTarget?: boolean;
  waitTimeout?: number;
  spotlightPadding?: number;
  spotlightRadius?: number;
  interactive?: boolean;
  showNavigation?: boolean;
  showProgress?: boolean;
  showClose?: boolean;
  className?: string;
  onBeforeShow?: (
    context: TourCallbackContext
  ) => boolean | undefined | Promise<boolean | undefined>;
  onEnter?: (context: TourCallbackContext) => void | Promise<void>;
  onShow?: (context: TourCallbackContext) => void;
  onBeforeHide?: (
    context: TourCallbackContext
  ) => boolean | undefined | Promise<boolean | undefined>;
  onHide?: (context: TourCallbackContext) => void;
}

type Placement =
  | 'top' | 'top-start' | 'top-end' | 'top-center'
  | 'bottom' | 'bottom-start' | 'bottom-end' | 'bottom-center'
  | 'left' | 'left-start' | 'left-end' | 'left-center'
  | 'right' | 'right-start' | 'right-end' | 'right-center';

onBeforeHide(outgoing) → onBeforeShow(incoming) → onEnter(incoming)
                       → [the step commits] →
                         onHide(outgoing) → onShow(incoming)

{
  id: 'confirm-step',
  target: '#editor',
  content: 'Save before you continue',
  onBeforeHide: async ({ data }) => {
    if (!data.saved) {
      return false // stay on this step
    }
  },
}

{
  id: 'chart',
  target: '#revenue-chart',
  content: 'Your revenue at a glance',
  waitForTarget: true,
  waitTimeout: 5000,
}

interface RouterAdapter {
  getCurrentRoute(): string;
  navigate(route: string): void;
  matchRoute(pattern: string, mode?: 'exact' | 'startsWith' | 'contains'): boolean;
  onRouteChange(callback: (route: string) => void): () => void;
}

interface MultiPagePersistenceConfig {
  enabled?: boolean;
  storage?: 'localStorage' | 'sessionStorage' | 'memory' | Storage;
  key?: string;
  syncTabs?: boolean;
  expiryMs?: number;
}

// Discriminated union for filtered step lists. See useStep / useTour.
type VisibleTourStep = TourStep & { __visible: true };
type HiddenTourStep = TourStep & { __visible: false };

function isVisibleStep(step: TourStep): step is VisibleTourStep;

// Target resolution types
type TourTargetRef = React.RefObject<HTMLElement | null>;
type TourTargetGetter = () => HTMLElement | null;

// Step media — image / video / lottie attached to a step
interface TourStepMedia {
  type: 'image' | 'video' | 'lottie';
  src: string;
  alt?: string;
  poster?: string;
}

interface WaitForStepTargetOptions {
  timeoutMs?: number;       // default: 5000
  pollIntervalMs?: number;  // default: 50
  signal?: AbortSignal;
}

// Resolves when a step's target appears in the DOM, rejects on timeout/abort.
function waitForStepTarget(
  step: TourStep,
  options?: WaitForStepTargetOptions
): Promise<HTMLElement>;

interface LocaleContextValue {
  locale: string;
  messages: Messages;
  t?: TranslateFn;
  direction?: 'ltr' | 'rtl';
}

interface LocaleProviderProps extends Partial<LocaleContextValue> {
  children: React.ReactNode;
}

type TranslateFn = (key: string, vars?: Record<string, unknown>) => string;

// Type guard for `LocalizedText`'s key-shape branch
function isI18nKey(value: unknown): value is { key: string };

// Segments registered on <SegmentationProvider>
type SegmentDefinition = AudienceCondition[];                    // AND-joined

interface StaticSegment {
  type: 'static';
  userIds: ReadonlyArray<string>;
}

type SegmentSource = SegmentDefinition | StaticSegment;

interface SegmentationContextValue {
  segments: Record<string, SegmentSource>;
  userContext?: Record<string, unknown>;
  currentUserId?: string;
}

interface SegmentationProviderProps extends SegmentationContextValue {
  children: React.ReactNode;
}

// Audience prop accepted on tours, hints, announcements
type AudienceProp = AudienceCondition[] | { segment: string };

// Type guard for the segment-shape branch
function isSegmentAudience(audience: AudienceProp): audience is { segment: string };

// Headless audience evaluator (re-exports in @tour-kit/react too)
function evaluateAudience(
  audience: AudienceProp | undefined,
  segments: Record<string, boolean>,
  userContext: Record<string, unknown> | undefined,
  source?: string
): boolean;

// Returns a human-readable explanation of why an audience did/didn't match
function explainAudience(
  audience: AudienceProp,
  segments: Record<string, boolean>,
  userContext?: Record<string, unknown>
): string;

// All built-in gates evaluated by the can-show pipeline, in declared order
const BUILTIN_GATE_ORDER: readonly GateName[];

// Stable identifiers used by diagnostics and analytics events
type GateName =
  | 'audience' | 'segment' | 'frequency' | 'schedule'
  | 'persistence' | 'capacity' | 'custom';

type GateCode = 'pass' | 'fail' | 'skipped' | 'error';

// Context passed to diagnostic listeners (eventbus, devtools)
interface DiagnosticContext {
  source: 'tour' | 'hint' | 'announcement' | 'checklist';
  id: string;
  gate: GateName;
  code: GateCode;
  reason?: string;
}

interface UseFlowSessionConfig {
  flowId: string;
  storage?: 'localStorage' | 'sessionStorage' | 'memory';
  ttlMs?: number;
}

interface FlowSessionConfig extends UseFlowSessionConfig {
  initialState?: Record<string, unknown>;
}

interface UseFlowSessionReturn<TState = Record<string, unknown>> {
  state: TState;
  setState: (next: Partial<TState>) => void;
  clear: () => void;
  isRestored: boolean;
}

interface UseBroadcastReturn {
  broadcast: (event: string, payload?: unknown) => void;
  subscribe: (event: string, handler: (payload: unknown) => void) => () => void;
}

interface FrequencyState {
  lastShownAt?: number;
  shownCount: number;
  dismissedAt?: number;
  completedAt?: number;
}

import {
  defaultKeyboardConfig,
  defaultSpotlightConfig,
  defaultPersistenceConfig,
  defaultA11yConfig,
  defaultScrollConfig,
} from '@tour-kit/core';