@otfdashkit/ui 0.1.0

package/src/engagement/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/utils/cn.ts

@@ -0,0 +1 @@
+export { cn } from '../../utils/cn'

package/src/feedback/Toaster.tsx

@@ -0,0 +1,141 @@
+'use client'
+
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import { CheckCircle, XCircle, AlertTriangle, Info, X } from 'lucide-react'
+import { cn } from '../utils/cn'
+import { toastEmitter, type ToastEvent, type ToastType } from './toast-emitter'
+
+/* ── Toast item ──────────────────────────────────────────────────── */
+
+const iconMap: Record<ToastType, React.ReactNode> = {
+  success:  <CheckCircle className="h-4 w-4 text-green-500" />,
+  error:    <XCircle className="h-4 w-4 text-destructive" />,
+  warning:  <AlertTriangle className="h-4 w-4 text-yellow-500" />,
+  info:     <Info className="h-4 w-4 text-blue-500" />,
+  default:  null,
+}
+
+const borderMap: Record<ToastType, string> = {
+  success: 'border-green-500/20',
+  error:   'border-destructive/20',
+  warning: 'border-yellow-500/20',
+  info:    'border-blue-500/20',
+  default: 'border-border',
+}
+
+interface ToastState extends ToastEvent {
+  visible: boolean
+}
+
+const DEFAULT_DURATION = 4000
+const MAX_TOASTS = 5
+
+interface ToastItemProps {
+  toast: ToastState
+  onDismiss: (id: string) => void
+}
+
+function ToastItem({ toast: t, onDismiss }: ToastItemProps) {
+  const type: ToastType = t.options.type ?? 'default'
+  return (
+    <div
+      data-slot="toast"
+      role="status"
+      aria-live="polite"
+      className={cn(
+        'group relative flex items-start gap-3 w-[360px] max-w-[calc(100vw-2rem)]',
+        'rounded-lg border bg-popover px-4 py-3 shadow-lg',
+        'animate-in slide-in-from-right-full duration-300',
+        !t.visible && 'animate-out fade-out-0 slide-out-to-right-full duration-200',
+        borderMap[type],
+      )}
+    >
+      {iconMap[type] && (
+        <span className="mt-0.5 shrink-0">{iconMap[type]}</span>
+      )}
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium text-foreground leading-tight">{t.message}</p>
+        {t.options.description && (
+          <p className="mt-0.5 text-xs text-muted-foreground">{t.options.description}</p>
+        )}
+        {t.options.action && (
+          <button
+            onClick={t.options.action.onClick}
+            className="mt-1.5 text-xs font-medium text-primary hover:underline"
+          >
+            {t.options.action.label}
+          </button>
+        )}
+      </div>
+      <button
+        onClick={() => onDismiss(t.id)}
+        aria-label="Dismiss"
+        className="shrink-0 opacity-40 hover:opacity-100 transition-opacity focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
+      >
+        <X className="h-3.5 w-3.5" />
+      </button>
+    </div>
+  )
+}
+
+/* ── Toaster ─────────────────────────────────────────────────────── */
+
+export function Toaster() {
+  const [toasts, setToasts] = useState<ToastState[]>([])
+  const timers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map())
+
+  const dismiss = useCallback((id: string) => {
+    setToasts((prev) =>
+      prev.map((t) => (t.id === id ? { ...t, visible: false } : t))
+    )
+    // Remove from DOM after exit animation
+    setTimeout(() => {
+      setToasts((prev) => prev.filter((t) => t.id !== id))
+    }, 250)
+    const timer = timers.current.get(id)
+    if (timer) {
+      clearTimeout(timer)
+      timers.current.delete(id)
+    }
+  }, [])
+
+  useEffect(() => {
+    const unsubToast = toastEmitter.onToast((event) => {
+      setToasts((prev) => {
+        const next = [
+          { ...event, visible: true },
+          ...prev.filter((t) => t.id !== event.id),
+        ].slice(0, MAX_TOASTS)
+        return next
+      })
+
+      const duration = event.options.duration ?? DEFAULT_DURATION
+      if (duration > 0) {
+        const timer = setTimeout(() => dismiss(event.id), duration)
+        timers.current.set(event.id, timer)
+      }
+    })
+
+    const unsubDismiss = toastEmitter.onDismiss((id) => dismiss(id))
+
+    return () => {
+      unsubToast()
+      unsubDismiss()
+      timers.current.forEach(clearTimeout)
+    }
+  }, [dismiss])
+
+  return (
+    <div
+      aria-label="Notifications"
+      aria-live="polite"
+      className="fixed top-4 right-4 z-[100] flex flex-col gap-2 pointer-events-none"
+    >
+      {toasts.map((t) => (
+        <div key={t.id} className="pointer-events-auto">
+          <ToastItem toast={t} onDismiss={dismiss} />
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/feedback/index.ts

@@ -0,0 +1,2 @@
+export * from './toast-emitter'
+export * from './Toaster'

package/src/feedback/toast-emitter.ts

@@ -0,0 +1,74 @@
+export type ToastType = 'default' | 'success' | 'error' | 'warning' | 'info'
+
+export interface ToastOptions {
+  type?: ToastType
+  duration?: number
+  description?: string
+  id?: string
+  action?: { label: string; onClick: () => void }
+}
+
+export interface ToastEvent {
+  id: string
+  message: string
+  options: ToastOptions
+}
+
+type Listener = (event: ToastEvent) => void
+type DismissListener = (id: string) => void
+
+let _id = 0
+const listeners: Listener[] = []
+const dismissListeners: DismissListener[] = []
+
+function nextId() {
+  return `toast-${++_id}`
+}
+
+export const toastEmitter = {
+  emit(message: string, options: ToastOptions = {}) {
+    const id = options.id ?? nextId()
+    const event: ToastEvent = { id, message, options }
+    listeners.forEach((fn) => fn(event))
+    return id
+  },
+  dismiss(id: string) {
+    dismissListeners.forEach((fn) => fn(id))
+  },
+  onToast(fn: Listener) {
+    listeners.push(fn)
+    return () => {
+      const i = listeners.indexOf(fn)
+      if (i !== -1) listeners.splice(i, 1)
+    }
+  },
+  onDismiss(fn: DismissListener) {
+    dismissListeners.push(fn)
+    return () => {
+      const i = dismissListeners.indexOf(fn)
+      if (i !== -1) dismissListeners.splice(i, 1)
+    }
+  },
+}
+
+/* ── Imperative toast() helper ────────────────────────────────── */
+
+function toastFn(message: string, opts?: ToastOptions): string {
+  return toastEmitter.emit(message, opts)
+}
+
+toastFn.success = (message: string, opts?: Omit<ToastOptions, 'type'>) =>
+  toastEmitter.emit(message, { ...opts, type: 'success' })
+
+toastFn.error = (message: string, opts?: Omit<ToastOptions, 'type'>) =>
+  toastEmitter.emit(message, { ...opts, type: 'error' })
+
+toastFn.warning = (message: string, opts?: Omit<ToastOptions, 'type'>) =>
+  toastEmitter.emit(message, { ...opts, type: 'warning' })
+
+toastFn.info = (message: string, opts?: Omit<ToastOptions, 'type'>) =>
+  toastEmitter.emit(message, { ...opts, type: 'info' })
+
+toastFn.dismiss = (id: string) => toastEmitter.dismiss(id)
+
+export { toastFn as toast }

package/src/forms/ArrayField/ArrayField.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { ArrayField } from './ArrayField'
+
+// TODO: add all variants
+const meta: Meta<typeof ArrayField> = {
+  title: 'Forms/ArrayField',
+  component: ArrayField,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof ArrayField>
+
+export const Default: Story = {}

package/src/forms/ArrayField/ArrayField.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { ArrayField } from './ArrayField'
+
+// TODO: add full a11y + variant tests
+describe('ArrayField', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<ArrayField />)).not.toThrow()
+  })
+})

package/src/forms/ArrayField/ArrayField.tsx

@@ -0,0 +1,61 @@
+import React from 'react'
+import { Plus, X } from 'lucide-react'
+import { Button } from '../primitives/button'
+import { cn } from '../utils/cn'
+
+export interface ArrayFieldProps<T> {
+  value: T[]
+  onChange: (v: T[]) => void
+  renderItem: (item: T, index: number, remove: () => void) => React.ReactNode
+  addLabel?: string
+  maxItems?: number
+  defaultItem: T
+  className?: string
+}
+
+export function ArrayField<T>({
+  value,
+  onChange,
+  renderItem,
+  addLabel = 'Add item',
+  maxItems,
+  defaultItem,
+  className,
+}: ArrayFieldProps<T>) {
+  function add() {
+    if (maxItems && value.length >= maxItems) return
+    onChange([...value, defaultItem])
+  }
+
+  function remove(index: number) {
+    onChange(value.filter((_, i) => i !== index))
+  }
+
+  const atMax = maxItems !== undefined && value.length >= maxItems
+
+  return (
+    <div className={cn('flex flex-col gap-2', className)}>
+      {value.map((item, i) => (
+        <div key={i} className="flex items-start gap-2">
+          <div className="flex-1 min-w-0">{renderItem(item, i, () => remove(i))}</div>
+          <button
+            type="button"
+            onClick={() => remove(i)}
+            className="mt-2 shrink-0 text-[hsl(var(--muted-foreground))] hover:text-[hsl(var(--destructive))] transition-colors"
+          >
+            <X className="h-4 w-4" />
+          </button>
+        </div>
+      ))}
+      <div className="flex items-center justify-between">
+        <Button type="button" variant="outline" size="sm" onClick={add} disabled={atMax}>
+          <Plus className="h-4 w-4" />
+          {addLabel}
+        </Button>
+        {maxItems && (
+          <span className="text-xs text-[hsl(var(--muted-foreground))]">{value.length}/{maxItems}</span>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/forms/ArrayField/index.ts

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

package/src/forms/AutoForm/AutoForm.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { AutoForm } from './AutoForm'
+
+// TODO: add all variants
+const meta: Meta<typeof AutoForm> = {
+  title: 'Forms/AutoForm',
+  component: AutoForm,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof AutoForm>
+
+export const Default: Story = {}

package/src/forms/AutoForm/AutoForm.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { AutoForm } from './AutoForm'
+
+// TODO: add full a11y + variant tests
+describe('AutoForm', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<AutoForm />)).not.toThrow()
+  })
+})

package/src/forms/AutoForm/AutoForm.tsx

@@ -0,0 +1,133 @@
+import React from 'react'
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import * as z from 'zod'
+import { Input } from '../primitives/input'
+import { Checkbox } from '../primitives/checkbox'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../primitives/select'
+import { Button } from '../primitives/button'
+import { DatePicker } from './date-picker'
+import { Field } from './field'
+
+export interface AutoFormProps {
+  schema: z.ZodObject<z.ZodRawShape>
+  onSubmit: (data: Record<string, unknown>) => void
+  defaultValues?: Record<string, unknown>
+  submitLabel?: string
+}
+
+function toLabel(key: string) {
+  return key.replace(/([A-Z])/g, ' $1').replace(/^./, s => s.toUpperCase())
+}
+
+function getInputType(field: z.ZodTypeAny): string {
+  if (field instanceof z.ZodEmail) return 'email'
+  if (field instanceof z.ZodURL) return 'url'
+  return 'text'
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function unwrapOptional(field: z.ZodTypeAny): any {
+  if (field instanceof z.ZodOptional || field instanceof z.ZodNullable) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return unwrapOptional((field as any).unwrap())
+  }
+  return field
+}
+
+interface FieldRendererProps {
+  name: string
+  field: z.ZodTypeAny
+  register: ReturnType<typeof useForm>['register']
+  setValue: ReturnType<typeof useForm>['setValue']
+  watch: ReturnType<typeof useForm>['watch']
+  error?: string
+}
+
+function FieldRenderer({ name, field, register, setValue, watch, error }: FieldRendererProps) {
+  const inner = unwrapOptional(field)
+  const label = toLabel(name)
+  const isOptional = field instanceof z.ZodOptional
+
+  if (inner instanceof z.ZodBoolean) {
+    const checked = Boolean(watch(name))
+    return (
+      <Field label={label} error={error}>
+        <div className="flex items-center gap-2">
+          <Checkbox
+            id={name}
+            checked={checked}
+            onCheckedChange={v => setValue(name, v)}
+          />
+          <label htmlFor={name} className="text-sm text-[hsl(var(--foreground))]">{label}</label>
+        </div>
+      </Field>
+    )
+  }
+
+  if (inner instanceof z.ZodEnum) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const options = ((inner as any).options ?? []) as string[]
+    const value = watch(name) as string | undefined
+    return (
+      <Field label={label} required={!isOptional} error={error}>
+        <Select value={value} onValueChange={v => setValue(name, v)}>
+          <SelectTrigger><SelectValue placeholder={`Select ${label.toLowerCase()}`} /></SelectTrigger>
+          <SelectContent>
+            {options.map(opt => <SelectItem key={opt} value={opt}>{opt}</SelectItem>)}
+          </SelectContent>
+        </Select>
+      </Field>
+    )
+  }
+
+  if (inner instanceof z.ZodDate) {
+    const value = watch(name) as Date | undefined
+    return (
+      <Field label={label} required={!isOptional} error={error}>
+        <DatePicker value={value} onChange={d => setValue(name, d)} placeholder={`Select ${label.toLowerCase()}`} />
+      </Field>
+    )
+  }
+
+  if (inner instanceof z.ZodNumber) {
+    return (
+      <Field label={label} required={!isOptional} error={error}>
+        <Input type="number" {...register(name, { valueAsNumber: true })} />
+      </Field>
+    )
+  }
+
+  const inputType = getInputType(inner)
+  return (
+    <Field label={label} required={!isOptional} error={error}>
+      <Input type={inputType} {...register(name)} />
+    </Field>
+  )
+}
+
+export function AutoForm({ schema, onSubmit, defaultValues, submitLabel = 'Submit' }: AutoFormProps) {
+  const { register, handleSubmit, setValue, watch, formState } = useForm({
+    resolver: zodResolver(schema),
+    defaultValues: defaultValues as Record<string, unknown>,
+  })
+
+  const shape = schema.shape
+
+  return (
+    <form onSubmit={handleSubmit(d => onSubmit(d as Record<string, unknown>))} className="flex flex-col gap-4">
+      {Object.entries(shape).map(([name, field]) => (
+        <FieldRenderer
+          key={name}
+          name={name}
+          field={field as z.ZodTypeAny}
+          register={register}
+          setValue={setValue}
+          watch={watch}
+          error={formState.errors[name]?.message as string | undefined}
+        />
+      ))}
+      <Button type="submit">{submitLabel}</Button>
+    </form>
+  )
+}

package/src/forms/AutoForm/index.ts

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

package/src/forms/DatePicker/DatePicker.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { DatePicker } from './DatePicker'
+
+// TODO: add all variants
+const meta: Meta<typeof DatePicker> = {
+  title: 'Forms/DatePicker',
+  component: DatePicker,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof DatePicker>
+
+export const Default: Story = {}

package/src/forms/DatePicker/DatePicker.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { DatePicker } from './DatePicker'
+
+// TODO: add full a11y + variant tests
+describe('DatePicker', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<DatePicker />)).not.toThrow()
+  })
+})