@tour-kit/announcements API

import { AnnouncementsProvider } from '@tour-kit/announcements';

<AnnouncementsProvider
  announcements={announcements}
  userId="user-123"
  userProperties={{ plan: 'pro' }}
  onShow={(id) => console.log('Shown:', id)}
  onDismiss={(id, reason) => console.log('Dismissed:', id, reason)}
>
  {children}
</AnnouncementsProvider>

import { useAnnouncement } from '@tour-kit/announcements';

const {
  announcement,
  isVisible,
  show,
  dismiss,
  complete,
} = useAnnouncement('announcement-id');

import { useAnnouncements } from '@tour-kit/announcements';

const {
  announcements,
  visible,
  showAnnouncement,
  dismissAnnouncement,
} = useAnnouncements();

import { useAnnouncementQueue } from '@tour-kit/announcements';

const {
  queue,
  current,
  next,
  clear,
} = useAnnouncementQueue();

import { AnnouncementModal } from '@tour-kit/announcements';

<AnnouncementModal id="welcome-modal" />

import { AnnouncementSlideout } from '@tour-kit/announcements';

<AnnouncementSlideout id="feature-slideout" />

import { AnnouncementBanner } from '@tour-kit/announcements';

<AnnouncementBanner id="maintenance-banner" />

import { AnnouncementToast } from '@tour-kit/announcements';

<AnnouncementToast id="update-toast" />

import { AnnouncementSpotlight } from '@tour-kit/announcements';

<AnnouncementSpotlight id="feature-spotlight" />

import {
  AnnouncementOverlay,
  AnnouncementClose,
  AnnouncementContent,
  AnnouncementActions,
} from '@tour-kit/announcements';

import {
  HeadlessModal,
  HeadlessSlideout,
  HeadlessBanner,
  HeadlessToast,
  HeadlessSpotlight,
} from '@tour-kit/announcements/headless';

<HeadlessModal id="my-modal">
  {({ isVisible, dismiss, announcement }) => (
    <CustomModal />
  )}
</HeadlessModal>

// Show only once ever
frequency: 'once'

// Show once per session
frequency: 'session'

// Show every time conditions met
frequency: 'always'

// Show N times total
frequency: { type: 'times', count: 3 }

// Show every N days
frequency: { type: 'interval', days: 7 }

audience: [
  { property: 'plan', operator: 'equals', value: 'pro' },
  { property: 'signupDate', operator: 'before', value: '2024-01-01' },
  { property: 'features', operator: 'contains', value: 'beta' },
]

priority: 'low' | 'normal' | 'high' | 'critical'

interface AnnouncementConfig {
  id: string;
  variant: 'modal' | 'slideout' | 'banner' | 'toast' | 'spotlight';
  priority?: 'low' | 'normal' | 'high' | 'critical';
  title?: string;
  description?: string | ReactNode;
  media?: AnnouncementMedia;
  primaryAction?: AnnouncementAction;
  secondaryAction?: AnnouncementAction;
  frequency?: FrequencyRule;
  schedule?: Schedule;
  audience?: AudienceCondition[];
  modalOptions?: ModalOptions;
  slideoutOptions?: SlideoutOptions;
  bannerOptions?: BannerOptions;
  toastOptions?: ToastOptions;
  spotlightOptions?: SpotlightOptions;
  onShow?: () => void;
  onDismiss?: (reason: DismissalReason) => void;
  onComplete?: () => void;
}

type DismissalReason =
  | 'close_button'
  | 'overlay_click'
  | 'escape_key'
  | 'primary_action'
  | 'secondary_action'
  | 'auto_dismiss'
  | 'programmatic';

interface AnnouncementState {
  id: string;
  isActive: boolean;
  isVisible: boolean;
  isDismissed: boolean;
  viewCount: number;
  lastViewedAt: Date | null;
  dismissedAt: Date | null;
  dismissalReason: DismissalReason | null;
  completedAt: Date | null;
}

// Audience prop accepted by AnnouncementConfig.audience
type AudienceProp = AudienceCondition[] | { segment: string };

// Re-exported from @tour-kit/core
import { isSegmentAudience } from '@tour-kit/announcements';
isSegmentAudience(audience): audience is { segment: string };

import { evaluateAnnouncementAudience } from '@tour-kit/announcements';

// Single-item evaluator used by useFilteredAnnouncements. Returns `true` for
// undefined and array-shape audiences (deferred to the scheduler); evaluates
// the segment branch against the current segments map.
evaluateAnnouncementAudience(
  audience: AudienceProp | undefined,
  segments: Record<string, boolean>
): boolean;

// Storage key used by useAnnouncement(id, { forceShow: true }) to bypass
// frequency / schedule / persistence gates during development.
const ForceShowBypassKey: string;

type Reaction = '👍' | '👎' | '🎉' | '🚀' | '❤️' | '🤔';

interface ReactionsProps {
  announcementId: string;
  available?: Reaction[];           // default: all
  onReact?: (reaction: Reaction) => void;
  className?: string;
}

interface ChangelogPageProps {
  announcements: AnnouncementConfig[];
  title?: string;
  description?: string;
  filters?: ChangelogFilterProps['filters'];
  className?: string;
}

interface ChangelogFilterProps {
  filters: Array<{ id: string; label: string; predicate: (a: AnnouncementConfig) => boolean }>;
  value: string | null;
  onChange: (next: string | null) => void;
}

interface ChangelogEntryProps {
  announcement: AnnouncementConfig;
  className?: string;
}

interface ToastAdapterRenderArgs {
  id: string;
  title?: React.ReactNode;
  description?: React.ReactNode;
  variant?: 'default' | 'success' | 'warning' | 'destructive';
  duration?: number;
  onDismiss?: () => void;
  onAction?: () => void;
}

interface ToastAdapterHandle {
  /** Dismiss the toast programmatically. */
  dismiss: () => void;
}

interface ToastAdapter {
  /** Show a toast and return a handle the provider can use to dismiss it. */
  show: (args: ToastAdapterRenderArgs) => ToastAdapterHandle;
}