TypeScript Types

interface Feature {
  id: string
  name: string
  trigger: FeatureTrigger
  adoptionCriteria?: AdoptionCriteria
  resources?: FeatureResources
  priority?: number
  category?: string
  description?: string
  premium?: boolean
}

type FeatureTrigger =
  | string // CSS selector
  | { event: string } // Custom event
  | { callback: () => boolean } // Programmatic check

// CSS selector (click tracking)
trigger: '#dark-mode-toggle'
trigger: '[data-feature="export"]'

// Custom event
trigger: { event: 'export:complete' }
trigger: { event: 'ai:generated' }

// Callback (polled every 1s)
trigger: { callback: () => document.fullscreenElement !== null }

interface AdoptionCriteria {
  minUses?: number // default: 3
  recencyDays?: number // default: 30
  custom?: (usage: FeatureUsage) => boolean
}

interface FeatureResources {
  tourId?: string
  hintIds?: string[]
}

interface FeatureUsage {
  featureId: string
  firstUsed: string | null // ISO date string
  lastUsed: string | null // ISO date string
  useCount: number
  status: AdoptionStatus
}

type AdoptionStatus = 'not_started' | 'exploring' | 'adopted' | 'churned'

interface FeatureWithUsage extends Feature {
  usage: FeatureUsage
}

interface AdoptionProviderProps {
  children: React.ReactNode
  features: Feature[]
  storage?: StorageConfig
  nudge?: NudgeConfig
  userId?: string
  onAdoption?: (feature: Feature) => void
  onChurn?: (feature: Feature) => void
  onNudge?: (feature: Feature, action: 'shown' | 'clicked' | 'dismissed') => void
}

type StorageConfig =
  | { type: 'localStorage'; key?: string }
  | { type: 'memory' }
  | { type: 'custom'; adapter: StorageAdapter }

interface StorageAdapter {
  getItem(key: string): Promise<string | null> | string | null
  setItem(key: string, value: string): Promise<void> | void
  removeItem(key: string): Promise<void> | void
}

interface NudgeConfig {
  enabled?: boolean // default: true
  initialDelay?: number // default: 5000
  cooldown?: number // default: 86400000 (24h)
  maxPerSession?: number // default: 3
  maxFeatures?: number // default: 1
}

interface UseFeatureReturn {
  feature: Feature | null
  usage: FeatureUsage
  isAdopted: boolean
  status: AdoptionStatus
  useCount: number
  trackUsage: () => void
}

interface AdoptionStats {
  features: FeatureWithUsage[]
  adoptionRate: number
  adoptedCount: number
  totalCount: number
  byStatus: Record<AdoptionStatus, FeatureWithUsage[]>
  byCategory: Record<string, { adopted: number; total: number; rate: number }>
}

interface UseNudgeReturn {
  pendingNudges: Feature[]
  hasNudges: boolean
  showNudge: (featureId: string) => void
  dismissNudge: (featureId: string) => void
  snoozeNudge: (featureId: string, durationMs: number) => void
  handleNudgeClick: (featureId: string) => void
}

interface AdoptionNudgeProps extends React.ComponentPropsWithoutRef<'div'> {
  render?: (props: NudgeRenderProps) => React.ReactNode
  delay?: number
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  size?: 'sm' | 'md' | 'lg'
  asChild?: boolean
}

interface NudgeRenderProps {
  feature: Feature
  onDismiss: () => void
  onSnooze: (durationMs: number) => void
  onClick: () => void
}

interface FeatureButtonProps extends React.ComponentPropsWithoutRef<'button'> {
  featureId: string
  showNewIndicator?: boolean
  variant?: 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive'
  size?: 'sm' | 'md' | 'lg'
  asChild?: boolean
}

interface NewFeatureBadgeProps extends React.ComponentPropsWithoutRef<'span'> {
  featureId: string
  text?: string
  variant?: 'default' | 'secondary' | 'outline' | 'destructive'
  size?: 'sm' | 'md' | 'lg'
}

interface AdoptionDashboardProps {
  showFilters?: boolean
  showStats?: boolean
  showChart?: boolean
  showTable?: boolean
  className?: string
}

interface AdoptionStatCardProps {
  title: string
  value: string | number
  description?: string
  trend?: number
  trendLabel?: string
  icon?: React.ReactNode
  variant?: 'default' | 'success' | 'warning' | 'danger'
  size?: 'sm' | 'md' | 'lg'
}

interface AdoptionTableProps {
  sortBy?: 'name' | 'status' | 'useCount' | 'lastUsed' | 'category'
  sortOrder?: 'asc' | 'desc'
  showCategory?: boolean
  showPriority?: boolean
  features?: FeatureWithUsage[]
  onRowClick?: (feature: FeatureWithUsage) => void
  className?: string
}

interface AdoptionCategoryChartProps {
  showPercentages?: boolean
  highlightCategory?: string
  orientation?: 'horizontal' | 'vertical'
  className?: string
}

interface AdoptionStatusBadgeProps {
  status: AdoptionStatus
  size?: 'sm' | 'md' | 'lg'
  showIcon?: boolean
  className?: string
}

interface AdoptionFiltersProps {
  filters: AdoptionFiltersState
  onChange: (filters: AdoptionFiltersState) => void
  categories?: string[]
  className?: string
}

interface AdoptionFiltersState {
  status: AdoptionStatus | 'all'
  category: string | 'all'
  search: string
}

import type { Feature } from '@tour-kit/adoption'

const features: Feature[] = [
  {
    id: 'dark-mode',
    name: 'Dark Mode',
    trigger: '#dark-mode-toggle',
    category: 'customization',
    adoptionCriteria: {
      minUses: 3,
      recencyDays: 30,
    },
  },
]

import { useFeature, type UseFeatureReturn } from '@tour-kit/adoption'

function Component() {
  const feature: UseFeatureReturn = useFeature('my-feature')

  feature.trackUsage() // ✓ Type-safe
  feature.isAdopted // ✓ Type-safe
}

import type { FeatureButtonProps } from '@tour-kit/adoption'

const buttonProps: FeatureButtonProps = {
  featureId: 'export',
  variant: 'default',
  onClick: () => console.log('clicked'),
}