@a4ui/core 0.32.0 → 0.34.0

package/src/ui/Lightbox.tsx

@@ -0,0 +1,261 @@
+// Full-screen image viewer: a responsive thumbnail grid that opens (via
+// Portal, dark backdrop) into an overlay with the active image, prev/next
+// navigation, a close button, an alt-text caption, and a thumbnail strip —
+// same overlay idiom as Modal (backdrop click / Escape closes, body scroll
+// locks while open), just built directly on Portal instead of Kobalte's
+// Dialog so index/open state can be driven by the caller.
+import { ChevronLeft, ChevronRight, X, ZoomIn } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createEffect, createMemo, createSignal, For, onCleanup, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+import { Portal } from './Portal'
+
+/** One image in a {@link Lightbox}. */
+export interface LightboxImage {
+  src: string
+  alt?: string
+  /** Smaller image used in the thumbnail grid/strip; falls back to `src`. */
+  thumb?: string
+}
+
+export interface LightboxProps {
+  images: LightboxImage[]
+  /** Controlled overlay open state. When set, wins over internal state — pair with `onOpenChange`. */
+  open?: boolean
+  /** Controlled active image index (clamped to the images array). When set, wins over internal state — pair with `onIndexChange`. */
+  index?: number
+  onOpenChange?: (open: boolean) => void
+  onIndexChange?: (index: number) => void
+  /** Show the thumbnail strip at the bottom of the overlay. @default true */
+  showThumbnails?: boolean
+  class?: string
+}
+
+/**
+ * Responsive thumbnail grid (`thumb || src`) that opens into a full-screen
+ * viewer on click: the active image centered, prev/next chevrons, a close
+ * button, an alt-text caption, a zoom toggle, and (by default) a thumbnail
+ * strip with the active image highlighted. Navigate with the arrow keys or
+ * Escape, click the backdrop to close. Works controlled
+ * (`open`/`index` + `onOpenChange`/`onIndexChange`) or uncontrolled. Body
+ * scroll locks while open, like `Modal`; the zoom transition is skipped
+ * under `prefers-reduced-motion` but stays fully functional.
+ *
+ * @example
+ * ```tsx
+ * <Lightbox
+ *   images={[
+ *     { src: '/photos/1-full.jpg', thumb: '/photos/1-thumb.jpg', alt: 'Sunset over the bay' },
+ *     { src: '/photos/2-full.jpg', thumb: '/photos/2-thumb.jpg', alt: 'Mountain trail' },
+ *   ]}
+ * />
+ * ```
+ */
+export function Lightbox(props: LightboxProps): JSX.Element {
+  const [internalOpen, setInternalOpen] = createSignal(false)
+  const open = createMemo(() => props.open ?? internalOpen())
+
+  const [internalIndex, setInternalIndex] = createSignal(0)
+  const rawIndex = createMemo(() => props.index ?? internalIndex())
+
+  const lastIndex = createMemo(() => Math.max(0, props.images.length - 1))
+  const clampIndex = (i: number): number => Math.min(Math.max(i, 0), lastIndex())
+  const index = createMemo(() => clampIndex(rawIndex()))
+  const current = createMemo(() => props.images[index()])
+
+  const setOpen = (next: boolean): void => {
+    setInternalOpen(next)
+    props.onOpenChange?.(next)
+  }
+  const setIndex = (next: number): void => {
+    const clamped = clampIndex(next)
+    setInternalIndex(clamped)
+    props.onIndexChange?.(clamped)
+  }
+
+  const openAt = (i: number): void => {
+    setIndex(i)
+    setOpen(true)
+  }
+  const close = (): void => setOpen(false)
+  const prev = (): void => setIndex(index() - 1)
+  const next = (): void => setIndex(index() + 1)
+  const showThumbnails = (): boolean => props.showThumbnails !== false
+
+  // Zoom toggle for the active image; reset whenever the image or open state changes.
+  const [zoomed, setZoomed] = createSignal(false)
+  createEffect(() => {
+    index()
+    open()
+    setZoomed(false)
+  })
+
+  // Lock body scroll while the overlay is open — same idiom as Modal's Dialog.
+  createEffect(() => {
+    if (!open() || typeof document === 'undefined') return
+    const previousOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    onCleanup(() => {
+      document.body.style.overflow = previousOverflow
+    })
+  })
+
+  // Escape closes, ArrowLeft/ArrowRight navigate, while the overlay is open.
+  createEffect(() => {
+    if (!open() || typeof window === 'undefined') return
+    const onKeyDown = (e: KeyboardEvent): void => {
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        close()
+      } else if (e.key === 'ArrowLeft') {
+        e.preventDefault()
+        prev()
+      } else if (e.key === 'ArrowRight') {
+        e.preventDefault()
+        next()
+      }
+    }
+    window.addEventListener('keydown', onKeyDown)
+    onCleanup(() => window.removeEventListener('keydown', onKeyDown))
+  })
+
+  return (
+    <div class={cn('grid grid-cols-2 gap-3 sm:grid-cols-3 md:grid-cols-4', props.class)}>
+      <For each={props.images}>
+        {(image, i) => (
+          <button
+            type="button"
+            class="group relative aspect-square overflow-hidden rounded-lg border border-border bg-muted focus:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            aria-label={image.alt ?? `Open image ${i() + 1}`}
+            onClick={() => openAt(i())}
+          >
+            <img
+              src={image.thumb ?? image.src}
+              alt={image.alt ?? ''}
+              loading="lazy"
+              class="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
+            />
+          </button>
+        )}
+      </For>
+
+      <Show when={open() && current()}>
+        <Portal>
+          <div
+            role="dialog"
+            aria-modal="true"
+            aria-label={current()?.alt ?? 'Image viewer'}
+            tabindex="-1"
+            class="fixed inset-0 z-50 flex flex-col bg-background/95 backdrop-blur-sm outline-none"
+            onClick={close}
+            ref={(el) => {
+              queueMicrotask(() => el.focus())
+            }}
+          >
+            <div class="flex items-center justify-end p-4" onClick={(e) => e.stopPropagation()}>
+              <button
+                type="button"
+                aria-label="Close"
+                onClick={close}
+                class="grid h-10 w-10 place-items-center rounded-lg bg-card/80 text-foreground transition hover:bg-muted"
+              >
+                <X class="h-5 w-5" />
+              </button>
+            </div>
+
+            <div class="relative flex flex-1 items-center justify-center px-4">
+              <Show when={props.images.length > 1}>
+                <button
+                  type="button"
+                  aria-label="Previous image"
+                  disabled={index() === 0}
+                  onClick={(e) => {
+                    e.stopPropagation()
+                    prev()
+                  }}
+                  class="absolute left-2 z-10 grid h-10 w-10 place-items-center rounded-full bg-card/80 text-foreground transition hover:bg-muted disabled:pointer-events-none disabled:opacity-40 sm:left-4"
+                >
+                  <ChevronLeft class="h-6 w-6" />
+                </button>
+              </Show>
+
+              <img
+                src={current()?.src}
+                alt={current()?.alt ?? ''}
+                onClick={(e) => {
+                  e.stopPropagation()
+                  setZoomed((z) => !z)
+                }}
+                class={cn(
+                  'max-h-[calc(100vh-10rem)] max-w-[92vw] rounded-lg object-contain',
+                  !motionReduced() && 'transition-transform duration-300 ease-out',
+                  zoomed() ? 'scale-150 cursor-zoom-out' : 'cursor-zoom-in',
+                )}
+              />
+
+              <Show when={props.images.length > 1}>
+                <button
+                  type="button"
+                  aria-label="Next image"
+                  disabled={index() === lastIndex()}
+                  onClick={(e) => {
+                    e.stopPropagation()
+                    next()
+                  }}
+                  class="absolute right-2 z-10 grid h-10 w-10 place-items-center rounded-full bg-card/80 text-foreground transition hover:bg-muted disabled:pointer-events-none disabled:opacity-40 sm:right-4"
+                >
+                  <ChevronRight class="h-6 w-6" />
+                </button>
+              </Show>
+            </div>
+
+            <div class="flex flex-col items-center gap-3 p-4" onClick={(e) => e.stopPropagation()}>
+              <div class="flex items-center gap-3">
+                <Show when={current()?.alt}>
+                  <p class="text-center text-sm text-muted-foreground">{current()?.alt}</p>
+                </Show>
+                <button
+                  type="button"
+                  aria-label={zoomed() ? 'Zoom out' : 'Zoom in'}
+                  aria-pressed={zoomed()}
+                  onClick={() => setZoomed((z) => !z)}
+                  class={cn(
+                    'grid h-8 w-8 shrink-0 place-items-center rounded-lg text-muted-foreground transition hover:bg-muted hover:text-foreground',
+                    zoomed() && 'bg-muted text-foreground',
+                  )}
+                >
+                  <ZoomIn class="h-4 w-4" />
+                </button>
+              </div>
+
+              <Show when={showThumbnails() && props.images.length > 1}>
+                <div class="flex max-w-full gap-2 overflow-x-auto py-1">
+                  <For each={props.images}>
+                    {(image, i) => (
+                      <button
+                        type="button"
+                        aria-label={image.alt ?? `Go to image ${i() + 1}`}
+                        aria-current={index() === i() ? 'true' : undefined}
+                        onClick={() => setIndex(i())}
+                        class={cn(
+                          'h-14 w-14 shrink-0 overflow-hidden rounded-md border-2 transition',
+                          index() === i()
+                            ? 'border-primary'
+                            : 'border-transparent opacity-60 hover:opacity-100',
+                        )}
+                      >
+                        <img src={image.thumb ?? image.src} alt="" class="h-full w-full object-cover" />
+                      </button>
+                    )}
+                  </For>
+                </div>
+              </Show>
+            </div>
+          </div>
+        </Portal>
+      </Show>
+    </div>
+  )
+}

package/src/ui/ModelPicker.tsx

@@ -0,0 +1,119 @@
+// AI model picker — dropdown trigger (icon + name + chevron) over a menu of
+// models (icon + name + description + badge), selected one checkmarked.
+// Built on Kobalte's DropdownMenu (same primitive as Dropdown.tsx), using its
+// RadioGroup/RadioItem for single-select keyboard navigation and a11y
+// (role="menuitemradio", aria-checked) — Dropdown.tsx's own item API only
+// supports a plain string label, not this richer per-option content.
+import { DropdownMenu } from '@kobalte/core/dropdown-menu'
+import { Check, ChevronDown } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { For, Show, createSignal, untrack } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single selectable model in a {@link ModelPicker} menu. */
+export interface ModelOption {
+  id: string
+  name: string
+  icon?: JSX.Element
+  description?: string
+  badge?: JSX.Element
+}
+
+export interface ModelPickerProps {
+  models: ModelOption[]
+  /** Controlled selected model id. Omit and use `defaultValue` for uncontrolled use. */
+  value?: string
+  /** Initial selected model id when uncontrolled. Ignored if `value` is passed. */
+  defaultValue?: string
+  onChange?: (id: string) => void
+  class?: string
+}
+
+/**
+ * Dropdown trigger showing the selected model's icon + name + a chevron; the
+ * menu lists every model with icon, name, description, and optional badge,
+ * checkmarking the current selection. Controlled via `value`/`onChange` or
+ * uncontrolled via `defaultValue`, and fully keyboard-navigable (arrow keys,
+ * typeahead, Escape) via Kobalte's `DropdownMenu`.
+ *
+ * @example
+ * ```tsx
+ * <ModelPicker
+ *   models={[
+ *     { id: 'sonnet', name: 'Claude Sonnet', description: 'Balanced speed and quality' },
+ *     { id: 'opus', name: 'Claude Opus', description: 'Most capable', badge: <Badge tone="info">New</Badge> },
+ *   ]}
+ *   defaultValue="sonnet"
+ *   onChange={(id) => console.log('selected', id)}
+ * />
+ * ```
+ */
+export function ModelPicker(props: ModelPickerProps): JSX.Element {
+  // Initial value only: read once (untracked), by design — this seeds the
+  // uncontrolled fallback and must not re-run when `models`/`defaultValue` change later.
+  const [internal, setInternal] = createSignal(untrack(() => props.defaultValue ?? props.models[0]?.id))
+  const selectedId = () => props.value ?? internal()
+  const selectedModel = () => props.models.find((m) => m.id === selectedId())
+
+  const handleChange = (id: string) => {
+    if (props.value === undefined) setInternal(id)
+    props.onChange?.(id)
+  }
+
+  return (
+    <DropdownMenu preventScroll={false}>
+      <DropdownMenu.Trigger
+        class={cn(
+          'inline-flex items-center gap-2 rounded-md border border-input bg-background px-3 py-2 text-sm text-foreground outline-none transition-colors a4-field',
+          props.class,
+        )}
+        aria-label="Select model"
+      >
+        <Show when={selectedModel()?.icon}>
+          <span class="flex h-4 w-4 shrink-0 items-center justify-center text-muted-foreground">
+            {selectedModel()?.icon}
+          </span>
+        </Show>
+        <span class="truncate font-medium">{selectedModel()?.name}</span>
+        <ChevronDown class="h-4 w-4 shrink-0 text-muted-foreground" />
+      </DropdownMenu.Trigger>
+      <DropdownMenu.Portal>
+        <DropdownMenu.Content class="z-50 min-w-64 overflow-hidden rounded-md border border-border bg-card p-1 text-card-foreground shadow-sm">
+          <DropdownMenu.RadioGroup value={selectedId()} onChange={handleChange}>
+            <For each={props.models}>
+              {(model) => (
+                <DropdownMenu.RadioItem
+                  value={model.id}
+                  class="flex cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 outline-none hover:bg-muted data-[disabled]:pointer-events-none data-[disabled]:opacity-50"
+                >
+                  <Show when={model.icon}>
+                    <span class="flex h-4 w-4 shrink-0 items-center justify-center text-muted-foreground">
+                      {model.icon}
+                    </span>
+                  </Show>
+                  <span class="flex min-w-0 flex-1 flex-col">
+                    <DropdownMenu.ItemLabel class="truncate text-sm text-foreground">
+                      {model.name}
+                    </DropdownMenu.ItemLabel>
+                    <Show when={model.description}>
+                      <DropdownMenu.ItemDescription class="truncate text-xs text-muted-foreground">
+                        {model.description}
+                      </DropdownMenu.ItemDescription>
+                    </Show>
+                  </span>
+                  <Show when={model.badge}>{model.badge}</Show>
+                  <span class="flex h-4 w-4 shrink-0 items-center justify-center text-primary">
+                    <Show when={model.id === selectedId()}>
+                      <Check class="h-4 w-4" />
+                    </Show>
+                  </span>
+                </DropdownMenu.RadioItem>
+              )}
+            </For>
+          </DropdownMenu.RadioGroup>
+        </DropdownMenu.Content>
+      </DropdownMenu.Portal>
+    </DropdownMenu>
+  )
+}

package/src/ui/OnboardingChecklist.tsx

@@ -0,0 +1,163 @@
+// Card-shaped step list for onboarding/setup flows. Completion state is
+// controlled by the caller (`steps[].done`) but each step also tracks its own
+// expanded/collapsed description locally, following the Collapse idiom.
+import { Check } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Button } from './Button'
+import { RingProgress } from './RingProgress'
+
+/** A single step in an {@link OnboardingChecklist}. */
+export interface OnboardingStep {
+  /** Stable identifier, used as the toggle key and `For` item key. */
+  id: string
+  title: JSX.Element
+  /** Optional detail shown when the step is expanded. */
+  description?: JSX.Element
+  /** Whether the step is complete. */
+  done?: boolean
+  /** Optional call-to-action rendered alongside the description. */
+  action?: { label: string; onClick: () => void }
+}
+
+export interface OnboardingChecklistProps {
+  steps: OnboardingStep[]
+  /** Called with the step id and its next `done` state when the indicator is toggled. */
+  onToggle?: (id: string, done: boolean) => void
+  /** Heading shown above the progress summary. Defaults to `'Getting started'`. */
+  title?: JSX.Element
+  class?: string
+}
+
+/**
+ * Card-shaped onboarding/setup checklist: a header with a completion ring and
+ * "{done} of {total} complete" summary, followed by expandable steps. Each
+ * step has a clickable check indicator (toggles `done` via `onToggle`), a
+ * title, and an optional description + CTA revealed on expand. Completion is
+ * controlled by the caller; expansion is local UI state (one step open at a time).
+ *
+ * @example
+ * ```tsx
+ * const [steps, setSteps] = createSignal<OnboardingStep[]>([
+ *   { id: 'profile', title: 'Complete your profile', done: true },
+ *   {
+ *     id: 'invite',
+ *     title: 'Invite a teammate',
+ *     description: 'Collaborate faster by adding at least one teammate.',
+ *     action: { label: 'Invite', onClick: () => openInviteDialog() },
+ *   },
+ * ])
+ * <OnboardingChecklist
+ *   steps={steps()}
+ *   onToggle={(id, done) =>
+ *     setSteps((prev) => prev.map((s) => (s.id === id ? { ...s, done } : s)))
+ *   }
+ * />
+ * ```
+ */
+export function OnboardingChecklist(props: OnboardingChecklistProps): JSX.Element {
+  const [expanded, setExpanded] = createSignal<string | null>(null)
+
+  const total = () => props.steps.length
+  const done = () => props.steps.filter((step) => step.done).length
+  const percent = () => (total() === 0 ? 0 : (done() / total()) * 100)
+
+  const toggleDone = (step: OnboardingStep): void => {
+    props.onToggle?.(step.id, !step.done)
+  }
+
+  const toggleExpanded = (id: string): void => {
+    setExpanded((prev) => (prev === id ? null : id))
+  }
+
+  return (
+    <div class={cn('rounded-xl border border-border bg-card text-card-foreground', props.class)}>
+      <div class="flex items-center gap-4 border-b border-border p-4">
+        <RingProgress
+          value={percent()}
+          size={56}
+          thickness={6}
+          label={
+            <span class="text-xs">
+              {done()}/{total()}
+            </span>
+          }
+        />
+        <div>
+          <p class="font-semibold text-foreground">{props.title ?? 'Getting started'}</p>
+          <p class="text-sm text-muted-foreground">
+            {done()} of {total()} complete
+          </p>
+        </div>
+      </div>
+      <ul role="list" class="divide-y divide-border">
+        <For each={props.steps}>
+          {(step) => {
+            const isExpanded = () => expanded() === step.id
+            const hasDetail = () => step.description !== undefined || step.action !== undefined
+            return (
+              <li class="p-4">
+                <div class="flex items-start gap-3">
+                  <button
+                    type="button"
+                    role="checkbox"
+                    aria-checked={!!step.done}
+                    aria-label={step.done ? 'Mark step as not done' : 'Mark step as done'}
+                    onClick={() => toggleDone(step)}
+                    class={cn(
+                      'mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border transition-colors',
+                      step.done
+                        ? 'border-emerald-500 bg-emerald-500 text-white'
+                        : 'border-input bg-background text-transparent hover:border-emerald-500/60',
+                    )}
+                  >
+                    <Check class="h-3.5 w-3.5" />
+                  </button>
+                  <button
+                    type="button"
+                    class="min-w-0 flex-1 text-left"
+                    aria-expanded={hasDetail() ? isExpanded() : undefined}
+                    disabled={!hasDetail()}
+                    onClick={() => hasDetail() && toggleExpanded(step.id)}
+                  >
+                    <span
+                      class={cn(
+                        'block text-sm font-medium',
+                        step.done ? 'text-muted-foreground line-through' : 'text-foreground',
+                      )}
+                    >
+                      {step.title}
+                    </span>
+                  </button>
+                </div>
+                <Show when={hasDetail()}>
+                  <div
+                    class={cn(
+                      'grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none',
+                      isExpanded() ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]',
+                    )}
+                  >
+                    <div class="overflow-hidden">
+                      <div class="mt-2 pl-8 text-sm text-muted-foreground">
+                        <Show when={step.description}>{step.description}</Show>
+                        <Show when={step.action}>
+                          {(action) => (
+                            <Button variant="outline" class="mt-2" onClick={() => action().onClick()}>
+                              {action().label}
+                            </Button>
+                          )}
+                        </Show>
+                      </div>
+                    </div>
+                  </div>
+                </Show>
+              </li>
+            )
+          }}
+        </For>
+      </ul>
+    </div>
+  )
+}

package/src/ui/ReasoningTrace.tsx

@@ -0,0 +1,83 @@
+// ReasoningTrace — collapsible "thinking" panel for AI surfaces. Mirrors
+// Collapse.tsx's header/panel idiom (grid-rows transition, chevron rotate)
+// but owns its own open state (seeded from `defaultOpen`) and adds a
+// streaming pulse indicator for in-flight reasoning.
+import { Brain, ChevronDown } from 'lucide-solid'
+import { type JSX, Show, createSignal } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface ReasoningTraceProps {
+  /** Reasoning body content; takes precedence over `text` when both are given. */
+  children?: JSX.Element
+  /** Plain-text reasoning body, rendered with preserved whitespace. */
+  text?: string
+  /** Header label. Defaults to `'Reasoning'`. */
+  label?: JSX.Element
+  /** Whether the panel starts expanded. Defaults to `false`. */
+  defaultOpen?: boolean
+  /** Show a pulsing dot in the header to indicate reasoning is still streaming. */
+  streaming?: boolean
+  class?: string
+}
+
+/**
+ * Collapsible panel for surfacing a model's intermediate "thinking"/reasoning
+ * trace. The header is a toggle button (brain icon + label + rotating
+ * chevron, plus a pulsing dot while `streaming`); the body is a muted,
+ * smaller-text block showing `text` or `children` with whitespace preserved.
+ * Collapsed by default unless `defaultOpen`. Height/opacity transition,
+ * instant under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <ReasoningTrace streaming text={reasoningSoFar()} />
+ * ```
+ */
+export function ReasoningTrace(props: ReasoningTraceProps): JSX.Element {
+  const [open, setOpen] = createSignal(props.defaultOpen ?? false)
+
+  return (
+    <div class={cn('rounded-xl border border-border bg-card', props.class)}>
+      <button
+        type="button"
+        aria-expanded={open()}
+        onClick={() => setOpen(!open())}
+        class="flex w-full items-center gap-2 rounded-xl px-3 py-2 text-sm font-medium text-muted-foreground hover:bg-muted"
+      >
+        <Brain class="h-4 w-4 shrink-0" aria-hidden="true" />
+        <span class="flex-1 text-left">{props.label ?? 'Reasoning'}</span>
+        <Show when={props.streaming}>
+          <span class="relative flex h-1.5 w-1.5 shrink-0" aria-hidden="true">
+            <span class="absolute inline-flex h-full w-full animate-ping rounded-full bg-current opacity-75 motion-reduce:animate-none" />
+            <span class="relative inline-flex h-1.5 w-1.5 rounded-full bg-current" />
+          </span>
+        </Show>
+        <ChevronDown
+          class={cn(
+            'h-4 w-4 shrink-0 transition-transform duration-200 motion-reduce:transition-none',
+            open() && 'rotate-180',
+          )}
+          aria-hidden="true"
+        />
+      </button>
+      <div
+        class={cn(
+          'grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none',
+          open() ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]',
+        )}
+      >
+        <div class="overflow-hidden">
+          <div
+            class={cn(
+              'whitespace-pre-wrap px-3 pb-3 text-xs leading-relaxed text-muted-foreground transition-opacity duration-200 motion-reduce:transition-none',
+              open() ? 'opacity-100' : 'opacity-0',
+            )}
+          >
+            {props.children ?? props.text}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}