@otfdashkit/ui 0.1.0

package/src/engagement/Tour/Tour.tsx

@@ -0,0 +1,106 @@
+import React, { createContext, useContext, useState, useEffect, useCallback } from 'react'
+import { cn } from '../utils/cn'
+import { Button } from '../primitives/button'
+
+interface TourContextValue {
+  currentStep: number
+  totalSteps: number
+  isActive: boolean
+  start: () => void
+  stop: () => void
+  next: () => void
+  prev: () => void
+  goTo: (step: number) => void
+}
+
+const TourContext = createContext<TourContextValue | null>(null)
+
+export function useTour(): TourContextValue {
+  const ctx = useContext(TourContext)
+  if (!ctx) throw new Error('useTour must be used within <Tour>')
+  return ctx
+}
+
+export interface TourProps {
+  totalSteps: number
+  children: React.ReactNode
+}
+
+export function Tour({ totalSteps, children }: TourProps) {
+  const [currentStep, setCurrentStep] = useState(0)
+  const [isActive, setIsActive] = useState(false)
+
+  const stop = useCallback(() => setIsActive(false), [])
+  const start = useCallback(() => { setCurrentStep(0); setIsActive(true) }, [])
+  const next = useCallback(() => setCurrentStep(s => Math.min(s + 1, totalSteps - 1)), [totalSteps])
+  const prev = useCallback(() => setCurrentStep(s => Math.max(s - 1, 0)), [])
+  const goTo = useCallback((step: number) => setCurrentStep(Math.max(0, Math.min(step, totalSteps - 1))), [totalSteps])
+
+  useEffect(() => {
+    if (!isActive) return
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') stop()
+      if (e.key === 'ArrowRight') next()
+      if (e.key === 'ArrowLeft') prev()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [isActive, stop, next, prev])
+
+  return (
+    <TourContext.Provider value={{ currentStep, totalSteps, isActive, start, stop, next, prev, goTo }}>
+      {children}
+    </TourContext.Provider>
+  )
+}
+
+const placementClasses: Record<string, string> = {
+  top: 'bottom-full left-1/2 -translate-x-1/2 mb-2',
+  bottom: 'top-full left-1/2 -translate-x-1/2 mt-2',
+  left: 'right-full top-1/2 -translate-y-1/2 mr-2',
+  right: 'left-full top-1/2 -translate-y-1/2 ml-2',
+}
+
+export interface TourStepProps {
+  step: number
+  title: string
+  description: string
+  placement?: 'top' | 'bottom' | 'left' | 'right'
+  children: React.ReactNode
+}
+
+export function TourStep({ step, title, description, placement = 'bottom', children }: TourStepProps) {
+  const { currentStep, isActive, stop, next, prev, totalSteps } = useTour()
+  const active = isActive && currentStep === step
+  const isLast = step === totalSteps - 1
+
+  return (
+    <span className="relative inline-block">
+      {active && (
+        <span
+          className="fixed inset-0 z-40 pointer-events-none"
+          style={{ boxShadow: '0 0 0 9999px rgba(0,0,0,0.5)' }}
+        />
+      )}
+      <span className={cn('relative', active && 'z-50 ring-2 ring-[hsl(var(--primary))] ring-offset-2 rounded-md')}>
+        {children}
+      </span>
+      {active && (
+        <div className={cn('absolute z-50 w-64 rounded-md border border-[hsl(var(--border))] bg-[hsl(var(--card))] p-4 shadow-lg', placementClasses[placement])}>
+          <p className="font-semibold text-sm mb-1">{title}</p>
+          <p className="text-xs text-[hsl(var(--muted-foreground))] mb-3">{description}</p>
+          <div className="flex items-center justify-between gap-2">
+            <span className="text-xs text-[hsl(var(--muted-foreground))]">{step + 1} / {totalSteps}</span>
+            <div className="flex gap-1.5">
+              {step > 0 && <Button size="sm" variant="outline" onClick={prev}>Back</Button>}
+              {isLast
+                ? <Button size="sm" onClick={stop}>Done</Button>
+                : <Button size="sm" onClick={next}>Next</Button>
+              }
+            </div>
+          </div>
+        </div>
+      )}
+    </span>
+  )
+}

package/src/engagement/Tour/index.ts

@@ -0,0 +1,2 @@
+// @tier: stub — full checklist in Phase 3
+export * from './Tour'

package/src/engagement/beacon.tsx

@@ -0,0 +1,50 @@
+import React from 'react'
+import { cn } from '../utils/cn'
+
+const colorMap = {
+  primary: 'bg-[hsl(var(--primary))]',
+  success: 'bg-green-500',
+  warning: 'bg-yellow-500',
+  error: 'bg-red-500',
+}
+
+const sizeMap = {
+  sm: 'h-1.5 w-1.5',
+  md: 'h-2.5 w-2.5',
+  lg: 'h-3.5 w-3.5',
+}
+
+export interface BeaconProps {
+  color?: keyof typeof colorMap
+  size?: keyof typeof sizeMap
+  children?: React.ReactNode
+  className?: string
+}
+
+function BeaconDot({ color = 'primary', size = 'md' }: Pick<BeaconProps, 'color' | 'size'>) {
+  return (
+    <span className="relative flex">
+      <span className={cn('animate-ping absolute inline-flex h-full w-full rounded-full opacity-75', colorMap[color])} />
+      <span className={cn('relative inline-flex rounded-full', sizeMap[size], colorMap[color])} />
+    </span>
+  )
+}
+
+export function Beacon({ color = 'primary', size = 'md', children, className }: BeaconProps) {
+  if (!children) {
+    return (
+      <span className={cn('inline-flex', className)}>
+        <BeaconDot color={color} size={size} />
+      </span>
+    )
+  }
+
+  return (
+    <span className={cn('relative inline-flex', className)}>
+      {children}
+      <span className="absolute -top-1 -right-1 flex">
+        <BeaconDot color={color} size={size} />
+      </span>
+    </span>
+  )
+}

package/src/engagement/checklist.tsx

@@ -0,0 +1,259 @@
+'use client'
+
+import React, { createContext, useCallback, useContext, useMemo, useState } from 'react'
+import { Check, ChevronDown, ChevronUp } from 'lucide-react'
+import { cn } from '../utils/cn'
+
+// ── Checklist ────────────────────────────────────────────────────────────────
+// Linear/Vercel/Stripe-style onboarding checklist. Compound API:
+//
+//   <Checklist title="Getting started" onComplete={() => setOpen(false)}>
+//     <ChecklistItem id="invite"  title="Invite teammates" />
+//     <ChecklistItem id="connect" title="Connect your repo" />
+//     <ChecklistItem id="deploy"  title="Deploy to production" action={<Button>Deploy</Button>} />
+//   </Checklist>
+//
+// Items can be controlled (pass `completed`) or uncontrolled (use the context's
+// `setCompleted`). The header shows "{done} of {total}" + a progress bar that
+// snaps to 100% when every item is done. Collapsible by default.
+
+interface ChecklistContextValue {
+  completed: Record<string, boolean>
+  setCompleted: (id: string, value: boolean) => void
+  total: number
+  doneCount: number
+}
+
+const ChecklistContext = createContext<ChecklistContextValue | null>(null)
+
+function useChecklist() {
+  const ctx = useContext(ChecklistContext)
+  if (!ctx) throw new Error('<ChecklistItem> must be used inside <Checklist>')
+  return ctx
+}
+
+export interface ChecklistProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Header title. */
+  title?: string
+  /** Optional subtitle / description. */
+  description?: string
+  /** Controlled map of itemId → completed. If omitted, state is internal. */
+  completed?: Record<string, boolean>
+  /** Called when an item's completion changes. */
+  onItemChange?: (id: string, completed: boolean) => void
+  /** Fired the first time every item flips to completed. */
+  onComplete?: () => void
+  /** Whether the body is collapsible. Default true. */
+  collapsible?: boolean
+  /** Initial open state (uncontrolled). Default true. */
+  defaultOpen?: boolean
+  /** Hide the progress bar. Default false. */
+  hideProgress?: boolean
+}
+
+export const Checklist = React.forwardRef<HTMLDivElement, ChecklistProps>(
+  (
+    {
+      title = 'Getting started',
+      description,
+      completed: controlledCompleted,
+      onItemChange,
+      onComplete,
+      collapsible = true,
+      defaultOpen = true,
+      hideProgress = false,
+      className,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const [internalCompleted, setInternalCompleted] = useState<Record<string, boolean>>({})
+    const [open, setOpen] = useState(defaultOpen)
+    const completedFiredRef = React.useRef(false)
+
+    const isControlled = controlledCompleted !== undefined
+    const completed = isControlled ? controlledCompleted! : internalCompleted
+
+    const setCompleted = useCallback(
+      (id: string, value: boolean) => {
+        if (!isControlled) setInternalCompleted((prev) => ({ ...prev, [id]: value }))
+        onItemChange?.(id, value)
+      },
+      [isControlled, onItemChange],
+    )
+
+    // Count items by walking children once
+    const total = useMemo(() => {
+      let n = 0
+      React.Children.forEach(children, (child) => {
+        if (React.isValidElement(child) && (child.type as React.ComponentType).displayName === 'ChecklistItem') {
+          n++
+        }
+      })
+      return n
+    }, [children])
+
+    const doneCount = useMemo(
+      () => Object.values(completed).filter(Boolean).length,
+      [completed],
+    )
+
+    React.useEffect(() => {
+      if (!completedFiredRef.current && total > 0 && doneCount >= total) {
+        completedFiredRef.current = true
+        onComplete?.()
+      }
+      if (doneCount < total) completedFiredRef.current = false
+    }, [doneCount, total, onComplete])
+
+    const pct = total === 0 ? 0 : Math.round((doneCount / total) * 100)
+    const ctx: ChecklistContextValue = { completed, setCompleted, total, doneCount }
+
+    return (
+      <ChecklistContext.Provider value={ctx}>
+        <div
+          ref={ref}
+          data-slot="checklist"
+          data-state={open ? 'open' : 'closed'}
+          className={cn(
+            'rounded-lg border border-[hsl(var(--border))] bg-[hsl(var(--card))] text-[hsl(var(--card-foreground))] overflow-hidden',
+            className,
+          )}
+          {...props}
+        >
+          {/* Header */}
+          <div
+            className={cn(
+              'flex items-start gap-3 p-4',
+              collapsible && 'cursor-pointer select-none',
+            )}
+            onClick={collapsible ? () => setOpen((o) => !o) : undefined}
+            role={collapsible ? 'button' : undefined}
+            aria-expanded={collapsible ? open : undefined}
+          >
+            <div className="flex-1 min-w-0">
+              <div className="flex items-baseline justify-between gap-3">
+                <h3 className="text-sm font-semibold tracking-tight">{title}</h3>
+                <span className="text-xs text-[hsl(var(--muted-foreground))] font-mono shrink-0 tabular-nums">
+                  {doneCount} of {total}
+                </span>
+              </div>
+              {description && (
+                <p className="text-xs text-[hsl(var(--muted-foreground))] mt-1 leading-relaxed">{description}</p>
+              )}
+              {!hideProgress && (
+                <div className="mt-3 h-1 w-full overflow-hidden rounded-full bg-[hsl(var(--muted))]">
+                  <div
+                    className="h-full bg-[hsl(var(--primary))] transition-[width] duration-500 ease-out"
+                    style={{ width: `${pct}%` }}
+                  />
+                </div>
+              )}
+            </div>
+            {collapsible && (
+              <span className="shrink-0 text-[hsl(var(--muted-foreground))] mt-0.5">
+                {open ? <ChevronUp className="h-4 w-4" /> : <ChevronDown className="h-4 w-4" />}
+              </span>
+            )}
+          </div>
+
+          {/* Body */}
+          {open && (
+            <div className="border-t border-[hsl(var(--border))] divide-y divide-[hsl(var(--border))]">
+              {children}
+            </div>
+          )}
+        </div>
+      </ChecklistContext.Provider>
+    )
+  },
+)
+Checklist.displayName = 'Checklist'
+
+export interface ChecklistItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title' | 'onClick'> {
+  /** Stable id used to track completion. */
+  id: string
+  /** Item title (required). */
+  title: string
+  /** Optional description shown under the title. */
+  description?: string
+  /** Render a CTA on the right (e.g. <Button>Connect</Button>). */
+  action?: React.ReactNode
+  /** Click handler for the entire row (excluding the action slot). */
+  onActivate?: () => void
+}
+
+export const ChecklistItem = React.forwardRef<HTMLDivElement, ChecklistItemProps>(
+  ({ id, title, description, action, onActivate, className, ...props }, ref) => {
+    const { completed, setCompleted } = useChecklist()
+    const done = !!completed[id]
+
+    const toggle = useCallback(() => {
+      setCompleted(id, !done)
+    }, [id, done, setCompleted])
+
+    return (
+      <div
+        ref={ref}
+        data-slot="checklist-item"
+        data-state={done ? 'completed' : 'pending'}
+        className={cn(
+          'flex items-start gap-3 px-4 py-3 transition-colors',
+          done && 'bg-[hsl(var(--muted)/0.4)]',
+          (onActivate || action) && 'group',
+          className,
+        )}
+        {...props}
+      >
+        <button
+          type="button"
+          onClick={toggle}
+          aria-label={done ? `Mark ${title} as not done` : `Mark ${title} as done`}
+          aria-pressed={done}
+          className={cn(
+            'mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border transition-colors',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] focus-visible:ring-offset-2 focus-visible:ring-offset-[hsl(var(--background))]',
+            done
+              ? 'border-[hsl(var(--primary))] bg-[hsl(var(--primary))] text-[hsl(var(--primary-foreground))]'
+              : 'border-[hsl(var(--border))] bg-[hsl(var(--background))] hover:border-[hsl(var(--primary)/0.5)]',
+          )}
+        >
+          {done && <Check className="h-3 w-3" strokeWidth={3} />}
+        </button>
+
+        <div
+          className={cn('flex-1 min-w-0', onActivate && !done && 'cursor-pointer')}
+          onClick={onActivate && !done ? onActivate : undefined}
+          role={onActivate && !done ? 'button' : undefined}
+        >
+          <p
+            className={cn(
+              'text-sm font-medium leading-tight transition-colors',
+              done ? 'text-[hsl(var(--muted-foreground))] line-through' : 'text-[hsl(var(--foreground))]',
+            )}
+          >
+            {title}
+          </p>
+          {description && (
+            <p
+              className={cn(
+                'text-xs mt-1 leading-relaxed',
+                done ? 'text-[hsl(var(--muted-foreground)/0.7)]' : 'text-[hsl(var(--muted-foreground))]',
+              )}
+            >
+              {description}
+            </p>
+          )}
+        </div>
+
+        {action && !done && (
+          <div className="shrink-0 self-center" onClick={(e) => e.stopPropagation()}>
+            {action}
+          </div>
+        )}
+      </div>
+    )
+  },
+)
+ChecklistItem.displayName = 'ChecklistItem'

package/src/engagement/intro-disclosure.tsx

@@ -0,0 +1,210 @@
+'use client'
+
+import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import { ChevronLeft, ChevronRight, X } from 'lucide-react'
+import { cn } from '../utils/cn'
+import { Button } from '../primitives/button'
+
+// ── IntroDisclosure ──────────────────────────────────────────────────────────
+// A first-run "welcome" modal. Multi-step carousel with progress dots, Skip /
+// Back / Next, and a localStorage-backed "don't show again" key so it only
+// fires once per user. Closes on Escape or backdrop click.
+//
+// Each step is { title, description, media } where `media` can be any node —
+// image, illustration, animation, even a <video>.
+
+export interface IntroStep {
+  title: string
+  description: string
+  media?: React.ReactNode
+}
+
+export interface IntroDisclosureProps {
+  /** The steps to walk through, in order. */
+  steps: IntroStep[]
+  /** Controlled open prop. If omitted, falls back to localStorage on mount. */
+  open?: boolean
+  /** Called when the user dismisses (skip / done / backdrop / escape). */
+  onOpenChange?: (open: boolean) => void
+  /** localStorage key. Once seen, the component stays closed for that key.
+   *  Set to `undefined` to disable persistence (always opens). */
+  storageKey?: string
+  /** Optional extra label e.g. "What's new in 2.0". */
+  eyebrow?: string
+  /** Skip button label. Default "Skip". */
+  skipLabel?: string
+  /** Final-step CTA label. Default "Get started". */
+  finishLabel?: string
+}
+
+export function IntroDisclosure({
+  steps,
+  open: controlledOpen,
+  onOpenChange,
+  storageKey = 'otf:intro-seen',
+  eyebrow,
+  skipLabel = 'Skip',
+  finishLabel = 'Get started',
+}: IntroDisclosureProps) {
+  const isControlled = controlledOpen !== undefined
+  const [internalOpen, setInternalOpen] = useState<boolean>(false)
+  const [step, setStep] = useState(0)
+
+  // Hydrate uncontrolled state from localStorage once on the client.
+  useEffect(() => {
+    if (isControlled) return
+    if (typeof window === 'undefined') return
+    if (!storageKey) {
+      setInternalOpen(true)
+      return
+    }
+    const seen = window.localStorage.getItem(storageKey)
+    setInternalOpen(seen !== '1')
+  }, [isControlled, storageKey])
+
+  const isOpen = isControlled ? controlledOpen! : internalOpen
+  const total = steps.length
+  const isLast = step === total - 1
+
+  const close = useCallback(() => {
+    if (!isControlled) {
+      setInternalOpen(false)
+      if (storageKey && typeof window !== 'undefined') window.localStorage.setItem(storageKey, '1')
+    }
+    onOpenChange?.(false)
+  }, [isControlled, onOpenChange, storageKey])
+
+  const next = useCallback(() => {
+    if (isLast) close()
+    else setStep((s) => s + 1)
+  }, [isLast, close])
+
+  const prev = useCallback(() => setStep((s) => Math.max(0, s - 1)), [])
+
+  // Keyboard shortcuts
+  useEffect(() => {
+    if (!isOpen) return
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') close()
+      else if (e.key === 'ArrowRight') next()
+      else if (e.key === 'ArrowLeft') prev()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [isOpen, close, next, prev])
+
+  const current = useMemo(() => steps[Math.min(step, total - 1)], [steps, step, total])
+
+  if (!isOpen || total === 0 || !current) return null
+
+  return (
+    <div
+      data-slot="intro-disclosure"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="otf-intro-title"
+      className="fixed inset-0 z-[60] flex items-center justify-center p-4"
+    >
+      {/* Backdrop */}
+      <div
+        aria-hidden
+        className="absolute inset-0 bg-black/60 backdrop-blur-sm animate-in fade-in duration-200"
+        onClick={close}
+      />
+
+      {/* Card */}
+      <div
+        data-slot="intro-disclosure-card"
+        className={cn(
+          'relative w-full max-w-md overflow-hidden rounded-xl border shadow-2xl',
+          'border-[hsl(var(--border))] bg-[hsl(var(--card))] text-[hsl(var(--card-foreground))]',
+          'animate-in fade-in zoom-in-95 duration-200',
+        )}
+      >
+        <button
+          type="button"
+          onClick={close}
+          aria-label="Close"
+          className={cn(
+            'absolute right-3 top-3 z-10 grid h-7 w-7 place-items-center rounded-md',
+            'text-[hsl(var(--muted-foreground))] hover:text-[hsl(var(--foreground))] hover:bg-[hsl(var(--muted))]',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]',
+            'transition-colors',
+          )}
+        >
+          <X className="h-4 w-4" />
+        </button>
+
+        {/* Media */}
+        {current.media && (
+          <div
+            data-slot="intro-disclosure-media"
+            className="relative aspect-[16/10] w-full overflow-hidden border-b border-[hsl(var(--border))] bg-[hsl(var(--muted)/0.5)]"
+            key={`media-${step}`}
+          >
+            {current.media}
+          </div>
+        )}
+
+        {/* Body */}
+        <div data-slot="intro-disclosure-body" className="px-6 pt-6 pb-5" key={`body-${step}`}>
+          {eyebrow && (
+            <p className="font-mono text-[10px] uppercase tracking-[0.18em] text-[hsl(var(--primary))] mb-2">
+              {eyebrow}
+            </p>
+          )}
+          <h2 id="otf-intro-title" className="text-xl font-semibold tracking-tight text-[hsl(var(--foreground))]">
+            {current.title}
+          </h2>
+          <p className="mt-2 text-sm leading-relaxed text-[hsl(var(--muted-foreground))]">
+            {current.description}
+          </p>
+        </div>
+
+        {/* Footer */}
+        <div
+          data-slot="intro-disclosure-footer"
+          className="flex items-center justify-between gap-3 border-t border-[hsl(var(--border))] bg-[hsl(var(--muted)/0.3)] px-6 py-3"
+        >
+          {/* Progress dots */}
+          <div className="flex items-center gap-1.5" aria-hidden>
+            {steps.map((_, i) => (
+              <span
+                key={i}
+                className={cn(
+                  'h-1.5 rounded-full transition-all duration-300',
+                  i === step
+                    ? 'w-6 bg-[hsl(var(--primary))]'
+                    : i < step
+                      ? 'w-1.5 bg-[hsl(var(--primary)/0.5)]'
+                      : 'w-1.5 bg-[hsl(var(--border))]',
+                )}
+              />
+            ))}
+          </div>
+
+          <div className="flex items-center gap-2">
+            {step === 0 ? (
+              <Button variant="ghost" size="sm" onClick={close}>
+                {skipLabel}
+              </Button>
+            ) : (
+              <Button variant="ghost" size="sm" onClick={prev} aria-label="Previous step">
+                <ChevronLeft className="h-4 w-4 mr-1" /> Back
+              </Button>
+            )}
+            <Button size="sm" onClick={next}>
+              {isLast ? finishLabel : (
+                <>
+                  Next <ChevronRight className="h-4 w-4 ml-1" />
+                </>
+              )}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+IntroDisclosure.displayName = 'IntroDisclosure'