@otfdashkit/ui 0.1.0

package/src/forms/SearchInput/SearchInput.tsx

@@ -0,0 +1,64 @@
+import React, { useState } from 'react'
+import { Search, X } from 'lucide-react'
+import { cn } from '../utils/cn'
+import { type InputProps } from '../primitives/input'
+
+export interface SearchInputProps extends Omit<InputProps, 'onChange'> {
+  shortcut?: string
+  onClear?: () => void
+  onChange?: (value: string) => void
+}
+
+export const SearchInput = React.forwardRef<HTMLInputElement, SearchInputProps>(
+  ({ className, shortcut, onClear, onChange, value: valueProp, defaultValue, ...props }, ref) => {
+    const [internalValue, setInternalValue] = useState(defaultValue ?? '')
+    const isControlled = valueProp !== undefined
+    const value = isControlled ? String(valueProp) : String(internalValue)
+
+    function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
+      if (!isControlled) setInternalValue(e.target.value)
+      onChange?.(e.target.value)
+    }
+
+    function handleClear() {
+      if (!isControlled) setInternalValue('')
+      onChange?.('')
+      onClear?.()
+    }
+
+    return (
+      <div className="relative flex items-center">
+        <Search className="pointer-events-none absolute left-2.5 h-4 w-4 text-[hsl(var(--muted-foreground))]" />
+        <input
+          ref={ref}
+          value={value}
+          onChange={handleChange}
+          className={cn(
+            'flex h-9 w-full rounded-md border border-[hsl(var(--input))] bg-transparent pl-8 pr-8 text-sm shadow-sm transition-colors',
+            'placeholder:text-[hsl(var(--muted-foreground))]',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]',
+            'disabled:cursor-not-allowed disabled:opacity-50',
+            className
+          )}
+          {...props}
+        />
+        <div className="absolute right-2.5 flex items-center">
+          {value ? (
+            <button
+              type="button"
+              onClick={handleClear}
+              className="text-[hsl(var(--muted-foreground))] hover:text-[hsl(var(--foreground))] transition-colors"
+            >
+              <X className="h-4 w-4" />
+            </button>
+          ) : shortcut ? (
+            <kbd className="pointer-events-none rounded border border-[hsl(var(--border))] px-1.5 py-0.5 text-[10px] text-[hsl(var(--muted-foreground))]">
+              {shortcut}
+            </kbd>
+          ) : null}
+        </div>
+      </div>
+    )
+  }
+)
+SearchInput.displayName = 'SearchInput'

package/src/forms/SearchInput/index.ts

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

package/src/forms/StepForm/StepForm.stories.tsx

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

package/src/forms/StepForm/StepForm.test.tsx

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

package/src/forms/StepForm/StepForm.tsx

@@ -0,0 +1,113 @@
+import React, { createContext, useContext, useState } from 'react'
+import { Button } from '../primitives/button'
+import { cn } from '../utils/cn'
+
+interface StepFormContextValue {
+  currentStep: number
+  totalSteps: number
+  steps: string[]
+  next: () => void
+  prev: () => void
+  isFirst: boolean
+  isLast: boolean
+}
+
+const StepFormContext = createContext<StepFormContextValue | null>(null)
+
+function useStepForm() {
+  const ctx = useContext(StepFormContext)
+  if (!ctx) throw new Error('useStepForm must be used within StepForm')
+  return ctx
+}
+
+export interface StepFormProps {
+  steps: string[]
+  onSubmit: () => void
+  children: React.ReactNode
+  className?: string
+}
+
+export function StepForm({ steps, onSubmit, children, className }: StepFormProps) {
+  const [currentStep, setCurrentStep] = useState(0)
+  const totalSteps = steps.length
+
+  const ctx: StepFormContextValue = {
+    currentStep,
+    totalSteps,
+    steps,
+    next: () => setCurrentStep(s => Math.min(s + 1, totalSteps - 1)),
+    prev: () => setCurrentStep(s => Math.max(s - 1, 0)),
+    isFirst: currentStep === 0,
+    isLast: currentStep === totalSteps - 1,
+  }
+
+  const childArray = React.Children.toArray(children)
+  const currentChild = childArray[currentStep]
+
+  return (
+    <StepFormContext.Provider value={ctx}>
+      <div className={cn('flex flex-col gap-6', className)}>
+        <StepIndicator steps={steps} currentStep={currentStep} />
+        <div>{currentChild}</div>
+        <StepFormNavigation onSubmit={onSubmit} />
+      </div>
+    </StepFormContext.Provider>
+  )
+}
+
+function StepIndicator({ steps, currentStep }: { steps: string[]; currentStep: number }) {
+  return (
+    <div className="flex items-center gap-2">
+      {steps.map((label, i) => (
+        <React.Fragment key={i}>
+          {i > 0 && <div className={cn('h-px flex-1 bg-[hsl(var(--border))]', i <= currentStep && 'bg-[hsl(var(--primary))]')} />}
+          <div className="flex flex-col items-center gap-1">
+            <div className={cn(
+              'flex h-7 w-7 items-center justify-center rounded-full text-xs font-medium border transition-colors',
+              i < currentStep && 'bg-[hsl(var(--primary))] border-[hsl(var(--primary))] text-[hsl(var(--primary-foreground))]',
+              i === currentStep && 'border-[hsl(var(--primary))] text-[hsl(var(--primary))]',
+              i > currentStep && 'border-[hsl(var(--border))] text-[hsl(var(--muted-foreground))]'
+            )}>{i + 1}</div>
+            <span className="hidden text-[10px] text-[hsl(var(--muted-foreground))] sm:block">{label}</span>
+          </div>
+        </React.Fragment>
+      ))}
+    </div>
+  )
+}
+
+export interface StepFormStepProps {
+  title: string
+  description?: string
+  children: React.ReactNode
+}
+
+export function StepFormStep({ title, description, children }: StepFormStepProps) {
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <h3 className="text-base font-semibold text-[hsl(var(--foreground))]">{title}</h3>
+        {description && <p className="text-sm text-[hsl(var(--muted-foreground))]">{description}</p>}
+      </div>
+      {children}
+    </div>
+  )
+}
+
+export interface StepFormNavigationProps {
+  onSubmit?: () => void
+  submitLabel?: string
+}
+
+export function StepFormNavigation({ onSubmit, submitLabel = 'Submit' }: StepFormNavigationProps) {
+  const { prev, next, isFirst, isLast } = useStepForm()
+  return (
+    <div className="flex justify-between">
+      <Button type="button" variant="outline" onClick={prev} disabled={isFirst}>Previous</Button>
+      {isLast
+        ? <Button type="button" onClick={onSubmit}>{submitLabel}</Button>
+        : <Button type="button" onClick={next}>Next</Button>
+      }
+    </div>
+  )
+}

package/src/forms/StepForm/index.ts

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

package/src/forms/array-field.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/auto-form.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/color-picker.tsx

@@ -0,0 +1,258 @@
+import React from 'react'
+import {
+  HexColorPicker,
+  HexAlphaColorPicker,
+  RgbStringColorPicker,
+  HslStringColorPicker,
+} from 'react-colorful'
+import { Pipette } from 'lucide-react'
+import { Input } from '../primitives/input'
+import { cn } from '../utils/cn'
+
+type ColorFormat = 'hex' | 'rgb' | 'hsl'
+
+export type ColorPickerProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> & {
+  /** Controlled color value (e.g. '#3b82f6' for hex, 'rgb(59, 130, 246)' for rgb). */
+  value?: string
+  /** Uncontrolled initial value. */
+  defaultValue?: string
+  /** Fires whenever the color changes. */
+  onValueChange?: (value: string) => void
+  /** Format for the text input + picker. Default 'hex'. */
+  format?: ColorFormat
+  /** Include alpha channel (only meaningful for hex). Default false. */
+  showAlpha?: boolean
+  /** Optional preset palette displayed as clickable swatches. */
+  swatches?: string[]
+  /** Show the eye-dropper button when the API is available. Default true. */
+  showEyeDropper?: boolean
+  /** Disable interaction. */
+  disabled?: boolean
+}
+
+// Minimal type for the experimental EyeDropper API (not yet in lib.dom.d.ts everywhere).
+type EyeDropperResult = { sRGBHex: string }
+type EyeDropperLike = { open: () => Promise<EyeDropperResult> }
+type EyeDropperCtor = new () => EyeDropperLike
+
+const HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i
+const RGB_RE = /^rgba?\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*(,\s*(0|1|0?\.\d+)\s*)?\)$/i
+const HSL_RE = /^hsla?\(\s*\d+\s*,\s*\d+%\s*,\s*\d+%\s*(,\s*(0|1|0?\.\d+)\s*)?\)$/i
+
+function isValid(value: string, format: ColorFormat, showAlpha: boolean): boolean {
+  if (format === 'hex') {
+    if (!HEX_RE.test(value)) return false
+    // Without alpha: only 3 or 6 hex digits.
+    if (!showAlpha && (value.length === 5 || value.length === 9)) return false
+    return true
+  }
+  if (format === 'rgb') return RGB_RE.test(value)
+  return HSL_RE.test(value)
+}
+
+function defaultFor(format: ColorFormat, showAlpha: boolean): string {
+  if (format === 'hex') return showAlpha ? '#3b82f6ff' : '#3b82f6'
+  if (format === 'rgb') return showAlpha ? 'rgba(59, 130, 246, 1)' : 'rgb(59, 130, 246)'
+  return showAlpha ? 'hsla(217, 91%, 60%, 1)' : 'hsl(217, 91%, 60%)'
+}
+
+/**
+ * Inline color picker with optional eye-dropper, swatches, and alpha channel.
+ * Wraps `react-colorful` and themes it to OTF's design tokens.
+ */
+export const ColorPicker = React.forwardRef<HTMLDivElement, ColorPickerProps>(
+  (
+    {
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      format = 'hex',
+      showAlpha = false,
+      swatches,
+      showEyeDropper = true,
+      disabled = false,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const fallback = defaultValue ?? defaultFor(format, showAlpha)
+    const isControlled = valueProp !== undefined
+    const [internal, setInternal] = React.useState<string>(fallback)
+    const value = isControlled ? (valueProp as string) : internal
+
+    // Mirror the value into the text input. Lets users type freely (incl. invalid intermediate
+    // states) without the picker fighting them.
+    const [draft, setDraft] = React.useState<string>(value)
+    const [draftValid, setDraftValid] = React.useState(true)
+    React.useEffect(() => {
+      setDraft(value)
+      setDraftValid(true)
+    }, [value])
+
+    const [eyeDropperSupported, setEyeDropperSupported] = React.useState(false)
+    React.useEffect(() => {
+      if (typeof window !== 'undefined' && 'EyeDropper' in window) {
+        setEyeDropperSupported(true)
+      }
+    }, [])
+
+    const commit = React.useCallback(
+      (next: string) => {
+        if (!isControlled) setInternal(next)
+        onValueChange?.(next)
+      },
+      [isControlled, onValueChange],
+    )
+
+    const handleDraftChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+      const next = e.target.value
+      setDraft(next)
+      const valid = isValid(next, format, showAlpha)
+      setDraftValid(valid || next === '')
+      if (valid) commit(next)
+    }
+
+    const handleEyeDropper = async () => {
+      if (disabled) return
+      const Ctor = (window as unknown as { EyeDropper?: EyeDropperCtor }).EyeDropper
+      if (!Ctor) return
+      try {
+        const result = await new Ctor().open()
+        // EyeDropper always returns hex. If the picker wants rgb/hsl we still pass the hex —
+        // react-colorful handles the conversion internally on next render.
+        commit(result.sRGBHex)
+      } catch {
+        // User cancelled — ignore.
+      }
+    }
+
+    const Picker = (() => {
+      const common = {
+        color: value,
+        onChange: commit,
+        className: cn(
+          'otf-color-picker',
+          disabled && 'pointer-events-none opacity-50 grayscale',
+        ),
+      }
+      if (format === 'hex' && showAlpha) return <HexAlphaColorPicker {...common} />
+      if (format === 'hex') return <HexColorPicker {...common} />
+      if (format === 'rgb') return <RgbStringColorPicker {...common} />
+      return <HslStringColorPicker {...common} />
+    })()
+
+    const showDropper = showEyeDropper && eyeDropperSupported
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'flex w-full max-w-[220px] flex-col gap-3',
+          disabled && 'opacity-60',
+          className,
+        )}
+        {...props}
+      >
+        {/* react-colorful theming — scoped via the .otf-color-picker className. */}
+        <style>{`
+          .otf-color-picker { width: 100% !important; height: auto !important; }
+          .otf-color-picker .react-colorful__saturation {
+            border-radius: calc(var(--radius) - 2px);
+            border-bottom: none;
+            margin-bottom: 8px;
+            height: 140px;
+          }
+          .otf-color-picker .react-colorful__hue,
+          .otf-color-picker .react-colorful__alpha {
+            height: 12px;
+            border-radius: 9999px;
+            margin-bottom: 6px;
+          }
+          .otf-color-picker .react-colorful__alpha:last-child { margin-bottom: 0; }
+          .otf-color-picker .react-colorful__pointer {
+            width: 16px;
+            height: 16px;
+            border-width: 2px;
+          }
+          .otf-color-picker .react-colorful__saturation-pointer { width: 18px; height: 18px; }
+        `}</style>
+
+        <div
+          className={cn(
+            'rounded-md border border-[hsl(var(--border))] bg-[hsl(var(--card))] p-2',
+            disabled && 'pointer-events-none',
+          )}
+        >
+          {Picker}
+        </div>
+
+        <div className="flex items-center gap-2">
+          <div
+            className="h-9 w-9 shrink-0 rounded-md border border-[hsl(var(--border))]"
+            style={{ backgroundColor: draftValid ? value : undefined }}
+            aria-hidden="true"
+          />
+          <Input
+            value={draft}
+            onChange={handleDraftChange}
+            disabled={disabled}
+            spellCheck={false}
+            autoComplete="off"
+            className={cn(
+              'font-mono text-xs',
+              !draftValid && 'border-[hsl(var(--destructive))] focus-visible:ring-[hsl(var(--destructive))]',
+            )}
+            aria-label={`Color value (${format})`}
+            aria-invalid={!draftValid}
+          />
+          {showDropper && (
+            <button
+              type="button"
+              onClick={handleEyeDropper}
+              disabled={disabled}
+              aria-label="Pick color from screen"
+              className={cn(
+                'inline-flex h-9 w-9 shrink-0 items-center justify-center rounded-md border border-[hsl(var(--border))]',
+                'text-[hsl(var(--muted-foreground))] transition-colors',
+                'hover:bg-[hsl(var(--accent))] hover:text-[hsl(var(--accent-foreground))]',
+                'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]',
+                'disabled:cursor-not-allowed disabled:opacity-50',
+              )}
+            >
+              <Pipette className="h-4 w-4" />
+            </button>
+          )}
+        </div>
+
+        {swatches && swatches.length > 0 && (
+          <div className="flex flex-wrap gap-1.5" role="listbox" aria-label="Preset colors">
+            {swatches.map((swatch) => {
+              const active = value.toLowerCase() === swatch.toLowerCase()
+              return (
+                <button
+                  key={swatch}
+                  type="button"
+                  role="option"
+                  aria-selected={active}
+                  aria-label={swatch}
+                  onClick={() => commit(swatch)}
+                  disabled={disabled}
+                  className={cn(
+                    'h-6 w-6 rounded-full border border-[hsl(var(--border))] transition-transform',
+                    'hover:scale-110 active:scale-95',
+                    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] focus-visible:ring-offset-1',
+                    active && 'ring-2 ring-[hsl(var(--ring))] ring-offset-1',
+                    'disabled:cursor-not-allowed disabled:opacity-50',
+                  )}
+                  style={{ backgroundColor: swatch }}
+                />
+              )
+            })}
+          </div>
+        )}
+      </div>
+    )
+  },
+)
+ColorPicker.displayName = 'ColorPicker'