@a4ui/core 0.32.0 → 0.33.0

package/src/index.ts

@@ -8,7 +8,7 @@
 //   import '@a4ui/core/styles.css'
 //   import { Button, Card, Modal } from '@a4ui/core'
 
-export const A4UI_VERSION = '0.32.0'
+export const A4UI_VERSION = '0.33.0'
 
 // Helpers (src/lib) — generic, framework-level utilities.
 export { cn } from './lib/cn'
@@ -186,6 +186,29 @@ export { Dock, type DockItem, type DockProps } from './ui/Dock'
 export { AnimatedBeam, type AnimatedBeamProps } from './ui/AnimatedBeam'
 export { BorderBeam, type BorderBeamProps } from './ui/BorderBeam'
 export { Meteors, type MeteorsProps } from './ui/Meteors'
+
+// AI agent surface + chat affordances.
+export { ReasoningTrace, type ReasoningTraceProps } from './ui/ReasoningTrace'
+export {
+  ToolCallTimeline,
+  type ToolCall,
+  type ToolCallStatus,
+  type ToolCallTimelineProps,
+} from './ui/ToolCallTimeline'
+export { DiffViewer, type DiffLine, type DiffViewerProps } from './ui/DiffViewer'
+export { ModelPicker, type ModelOption, type ModelPickerProps } from './ui/ModelPicker'
+export { UsageMeter, type UsageMeterProps } from './ui/UsageMeter'
+export { SuggestionChips, type SuggestionChipsProps } from './ui/SuggestionChips'
+
+// Content blocks.
+export { Callout, type CalloutTone, type CalloutProps } from './ui/Callout'
+export { Snippet, type SnippetProps } from './ui/Snippet'
+
+// Spatial showpieces + motion extras.
+export { Globe, type GlobeMarker, type GlobeArc, type GlobeProps } from './ui/Globe'
+export { WorldMap, type WorldMapPoint, type WorldMapConnection, type WorldMapProps } from './ui/WorldMap'
+export { Confetti, fireConfetti, type ConfettiProps } from './ui/Confetti'
+export { CursorTrail, type CursorTrailProps } from './ui/CursorTrail'
 export {
   CopyButton,
   type CopyButtonProps,

package/src/ui/Callout.tsx

@@ -0,0 +1,66 @@
+// Prose-embed highlight block for docs/guidance content. Distinct from Alert
+// (a dismissible notification banner): Callout sits inline in a body of text —
+// left accent border, tinted background, comfortable padding — and is never
+// dismissed. Tone tokens are shared with Alert so info/success/warning/danger
+// read identically across both components.
+import { CircleCheck, CircleX, Info, TriangleAlert } from 'lucide-solid'
+import type { Component, JSX } from 'solid-js'
+import { Show } from 'solid-js'
+import { Dynamic } from 'solid-js/web'
+
+import { cn } from '../lib/cn'
+
+/** Semantic tone of a {@link Callout}; drives the accent border, tint, and default icon. */
+export type CalloutTone = 'info' | 'success' | 'warning' | 'danger' | 'neutral'
+
+const TONE: Record<CalloutTone, { wrap: string; icon: string; Icon: Component<{ class?: string }> }> = {
+  info: { wrap: 'border-sky-500 bg-sky-500/10', icon: 'text-sky-500', Icon: Info },
+  success: { wrap: 'border-emerald-500 bg-emerald-500/10', icon: 'text-emerald-500', Icon: CircleCheck },
+  warning: { wrap: 'border-amber-500 bg-amber-500/10', icon: 'text-amber-500', Icon: TriangleAlert },
+  danger: { wrap: 'border-rose-500 bg-rose-500/10', icon: 'text-rose-500', Icon: CircleX },
+  neutral: { wrap: 'border-border bg-muted', icon: 'text-muted-foreground', Icon: Info },
+}
+
+export interface CalloutProps {
+  /** Visual/semantic tone. Defaults to `'info'`. */
+  tone?: 'info' | 'success' | 'warning' | 'danger' | 'neutral'
+  /** Optional bold heading shown above the body. */
+  title?: JSX.Element
+  /** Overrides the tone's default icon. */
+  icon?: JSX.Element
+  children: JSX.Element
+  class?: string
+}
+
+/**
+ * Inline highlighted block for embedding guidance/notes inside prose (docs,
+ * READMEs, long-form content) — a left accent border, a faint tone-tinted
+ * background, and an icon. Unlike {@link Alert} it isn't a dismissible
+ * notification; it's part of the content flow.
+ *
+ * @example
+ * ```tsx
+ * <Callout tone="warning" title="Before you continue">
+ *   This action can't be undone once the migration starts.
+ * </Callout>
+ * ```
+ */
+export function Callout(props: CalloutProps): JSX.Element {
+  const tone = () => TONE[props.tone ?? 'info']
+  return (
+    <div class={cn('flex gap-3 rounded-lg border-l-4 p-4 text-sm text-foreground', tone().wrap, props.class)}>
+      <Show
+        when={props.icon}
+        fallback={<Dynamic component={tone().Icon} class={cn('mt-0.5 h-4 w-4 shrink-0', tone().icon)} />}
+      >
+        {props.icon}
+      </Show>
+      <div class="flex-1">
+        <Show when={props.title}>
+          <p class="font-semibold">{props.title}</p>
+        </Show>
+        <div class="text-muted-foreground">{props.children}</div>
+      </div>
+    </div>
+  )
+}

package/src/ui/Confetti.tsx

@@ -0,0 +1,131 @@
+// Decorative confetti burst: a spawn-then-remove particle idiom (same as
+// Ripple.tsx) driven by the native Web Animations API — each piece is a
+// one-shot element with nothing for a JS animation engine to add. Angle and
+// velocity per piece are derived deterministically from the piece's index
+// (via Math.sin), not Math.random, so a burst is reproducible and doesn't
+// depend on an RNG.
+import { createEffect, on, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface ConfettiProps {
+  /** Bump this (e.g. a counter) to fire a burst. Mount does not count. */
+  trigger?: number
+  /** Number of pieces per burst. @default 80 */
+  count?: number
+  class?: string
+}
+
+const CONFETTI_COLORS = ['hsl(var(--primary))', 'hsl(var(--accent))', 'hsl(var(--foreground))']
+
+/**
+ * Fires one burst of confetti pieces from the bottom-center of `container`,
+ * flying up and outward in a fan, rotating, then falling with gravity and
+ * fading out — each piece removes itself once its animation finishes. Angle,
+ * speed, fall distance and spin are derived deterministically from each
+ * piece's index (Math.sin), so the same `count` always produces the same
+ * fan. `container` should be `position: relative` (or already positioned)
+ * with `overflow: hidden` so pieces don't affect layout. No-op under
+ * {@link motionReduced}. This is the primitive behind {@link Confetti}.
+ *
+ * @example
+ * ```ts
+ * fireConfetti(cardEl, { count: 120 })
+ * ```
+ */
+export function fireConfetti(container: HTMLElement, opts: { count?: number } = {}): void {
+  if (motionReduced()) return
+  const count = opts.count ?? 80
+  const rect = container.getBoundingClientRect()
+  const originX = rect.width / 2
+  const originY = rect.height
+
+  for (let i = 0; i < count; i++) {
+    // Fan the burst across a ~126° arc centered straight up; wobble is a
+    // deterministic pseudo-random 0..1 derived from the index.
+    const spread = Math.PI * 0.7
+    const wobble = Math.sin(i * 12.9898) * 0.5 + 0.5
+    const angle = -Math.PI / 2 + (wobble - 0.5) * spread
+    const speed = 180 + (Math.sin(i * 4.567) * 0.5 + 0.5) * 160
+    const dx = Math.cos(angle) * speed
+    const dy = Math.sin(angle) * speed
+    const fall = 200 + (Math.sin(i * 5.113) * 0.5 + 0.5) * 160
+    const rotation = 240 + (Math.sin(i * 3.377) * 0.5 + 0.5) * 640
+    const duration = 900 + (Math.sin(i * 2.1) * 0.5 + 0.5) * 500
+
+    const el = document.createElement('span')
+    el.setAttribute('aria-hidden', 'true')
+    Object.assign(el.style, {
+      position: 'absolute',
+      left: `${originX}px`,
+      top: `${originY}px`,
+      width: `${5 + (i % 3) * 2}px`,
+      height: `${10 + (i % 4) * 2}px`,
+      borderRadius: '1px',
+      background: CONFETTI_COLORS[i % CONFETTI_COLORS.length],
+      pointerEvents: 'none',
+    })
+    container.appendChild(el)
+
+    const animation = el.animate(
+      [
+        { transform: 'translate(-50%,-50%) translate(0px,0px) rotate(0deg)', opacity: '1' },
+        {
+          transform: `translate(-50%,-50%) translate(${dx * 0.7}px,${dy}px) rotate(${rotation * 0.5}deg)`,
+          opacity: '1',
+          offset: 0.45,
+        },
+        {
+          transform: `translate(-50%,-50%) translate(${dx}px,${dy + fall}px) rotate(${rotation}deg)`,
+          opacity: '0',
+        },
+      ],
+      { duration, easing: 'cubic-bezier(0.2, 0.6, 0.4, 1)' },
+    )
+    const done = (): void => el.remove()
+    animation.finished.then(done).catch(done)
+  }
+}
+
+/**
+ * Absolutely-positioned confetti layer: fires a burst of colored pieces from
+ * the bottom-center whenever `trigger` changes (the initial mount does not
+ * fire one). Purely decorative — `pointer-events-none` and `aria-hidden`.
+ * Place it inside a `position: relative` container; pair with a `count`
+ * prop, or reach for {@link fireConfetti} directly to fire into an
+ * arbitrary element outside Solid's render tree.
+ *
+ * @example
+ * ```tsx
+ * const [bursts, setBursts] = createSignal(0)
+ * return (
+ *   <div class="relative h-64">
+ *     <Confetti trigger={bursts()} count={100} />
+ *     <Button onClick={() => setBursts((n) => n + 1)}>Celebrate</Button>
+ *   </div>
+ * )
+ * ```
+ */
+export function Confetti(props: ConfettiProps): JSX.Element {
+  let containerEl: HTMLDivElement | undefined
+
+  createEffect(
+    on(
+      () => props.trigger,
+      () => {
+        if (!containerEl) return
+        fireConfetti(containerEl, { count: props.count })
+      },
+      { defer: true },
+    ),
+  )
+
+  return (
+    <div
+      ref={containerEl}
+      class={cn('absolute inset-0 overflow-hidden pointer-events-none', props.class)}
+      aria-hidden="true"
+    />
+  )
+}

package/src/ui/CursorTrail.tsx

@@ -0,0 +1,88 @@
+// Decorative cursor trail: same spawn-then-remove particle idiom as
+// Ripple.tsx / Confetti.tsx, driven by the native Web Animations API. The
+// layer itself is pointer-events-none, so the listener lives on the
+// `relative` parent that hosts it.
+import { onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface CursorTrailProps {
+  /** Blob tone. @default 'primary' */
+  color?: 'primary' | 'accent'
+  /** Blob diameter in px. @default 24 */
+  size?: number
+  class?: string
+}
+
+const SPAWN_THROTTLE_MS = 20
+
+/**
+ * Layer that spawns a soft, blurred blob at the cursor position on every
+ * throttled `pointermove` over its parent, scaling down and fading out as
+ * it removes itself — leaving a trail. Must sit inside a `position:
+ * relative` parent (the layer listens on `parentElement`, since it is
+ * itself `pointer-events-none`). Purely decorative — `pointer-events-none`
+ * and `aria-hidden`. No-op under {@link motionReduced}; listeners are
+ * cleaned up on unmount.
+ *
+ * @example
+ * ```tsx
+ * <div class="relative h-48 rounded-lg border">
+ *   <CursorTrail color="accent" size={32} />
+ * </div>
+ * ```
+ */
+export function CursorTrail(props: CursorTrailProps): JSX.Element {
+  let layerEl: HTMLDivElement | undefined
+  let lastSpawn = 0
+
+  const handlePointerMove = (event: PointerEvent): void => {
+    if (motionReduced() || !layerEl) return
+    const now = performance.now()
+    if (now - lastSpawn < SPAWN_THROTTLE_MS) return
+    lastSpawn = now
+
+    const rect = layerEl.getBoundingClientRect()
+    const x = event.clientX - rect.left
+    const y = event.clientY - rect.top
+    const size = props.size ?? 24
+    const tone = props.color === 'accent' ? 'accent' : 'primary'
+
+    const el = document.createElement('span')
+    el.setAttribute('aria-hidden', 'true')
+    Object.assign(el.style, {
+      position: 'absolute',
+      left: `${x}px`,
+      top: `${y}px`,
+      width: `${size}px`,
+      height: `${size}px`,
+      borderRadius: '9999px',
+      background: `hsl(var(--${tone}) / 0.35)`,
+      filter: 'blur(6px)',
+      pointerEvents: 'none',
+      transform: 'translate(-50%,-50%) scale(1)',
+    })
+    layerEl.appendChild(el)
+
+    const animation = el.animate(
+      [
+        { transform: 'translate(-50%,-50%) scale(1)', opacity: '1' },
+        { transform: 'translate(-50%,-50%) scale(0.2)', opacity: '0' },
+      ],
+      { duration: 500, easing: 'ease-out' },
+    )
+    const done = (): void => el.remove()
+    animation.finished.then(done).catch(done)
+  }
+
+  onMount(() => {
+    const parent = layerEl?.parentElement
+    parent?.addEventListener('pointermove', handlePointerMove)
+    onCleanup(() => parent?.removeEventListener('pointermove', handlePointerMove))
+  })
+
+  return (
+    <div ref={layerEl} class={cn('absolute inset-0 pointer-events-none', props.class)} aria-hidden="true" />
+  )
+}

package/src/ui/DiffViewer.tsx

@@ -0,0 +1,166 @@
+// Read-only unified-diff / line-diff renderer. Reuses the CodeTabs monospace
+// idiom (rounded border, bg-card, font-mono text-sm) and the Alert/Badge tone
+// tokens: `emerald` for added (their `success` tone) and the `destructive`
+// CSS-var token for removed. No syntax highlighting.
+import { type JSX, Show } from 'solid-js'
+import { createMemo, For } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single rendered row of a diff. */
+export interface DiffLine {
+  type: 'add' | 'remove' | 'context'
+  content: string
+  /** Line number in the old file. Present for `'remove'` and `'context'` rows. */
+  oldNum?: number
+  /** Line number in the new file. Present for `'add'` and `'context'` rows. */
+  newNum?: number
+}
+
+export interface DiffViewerProps {
+  /** Unified diff text (as produced by `git diff`/`diff -u`). Ignored if `lines` is set. */
+  diff?: string
+  /** Pre-parsed diff rows. Takes precedence over `diff`. */
+  lines?: DiffLine[]
+  /** Header label. If omitted, inferred from the `+++`/`---` headers of `diff`, when present. */
+  filename?: string
+  class?: string
+}
+
+const MARKER: Record<DiffLine['type'], string> = { add: '+', remove: '-', context: ' ' }
+
+const ROW_BG: Record<DiffLine['type'], string> = {
+  add: 'bg-emerald-500/10',
+  remove: 'bg-destructive/10',
+  context: '',
+}
+
+const MARKER_TONE: Record<DiffLine['type'], string> = {
+  add: 'text-emerald-500',
+  remove: 'text-destructive',
+  context: 'text-muted-foreground',
+}
+
+const CONTENT_TONE: Record<DiffLine['type'], string> = {
+  add: 'text-foreground',
+  remove: 'text-foreground',
+  context: 'text-muted-foreground',
+}
+
+const HUNK_HEADER = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/
+
+/** Parses a unified diff string into rows plus an optional inferred filename. */
+function parseUnifiedDiff(diff: string): { lines: DiffLine[]; filename?: string } {
+  const rawLines = diff.split('\n')
+  // Drop the trailing empty element produced when `diff` ends with a newline.
+  if (rawLines.length > 0 && rawLines[rawLines.length - 1] === '') rawLines.pop()
+
+  const lines: DiffLine[] = []
+  let filename: string | undefined
+  let oldNum = 0
+  let newNum = 0
+
+  for (const raw of rawLines) {
+    if (raw.startsWith('+++ ') || raw.startsWith('--- ')) {
+      const path = raw.slice(4).trim()
+      if (raw.startsWith('+++ ') && path !== '/dev/null') filename = path.replace(/^[ab]\//, '')
+      continue
+    }
+    const hunkMatch = HUNK_HEADER.exec(raw)
+    if (hunkMatch) {
+      oldNum = Number(hunkMatch[1])
+      newNum = Number(hunkMatch[2])
+      continue
+    }
+    if (raw.startsWith('\\')) continue // ""
+
+    if (raw.startsWith('+')) {
+      lines.push({ type: 'add', content: raw.slice(1), newNum: newNum++ })
+    } else if (raw.startsWith('-')) {
+      lines.push({ type: 'remove', content: raw.slice(1), oldNum: oldNum++ })
+    } else {
+      lines.push({
+        type: 'context',
+        content: raw.startsWith(' ') ? raw.slice(1) : raw,
+        oldNum: oldNum++,
+        newNum: newNum++,
+      })
+    }
+  }
+
+  return { lines, filename }
+}
+
+/**
+ * Read-only diff block: renders added/removed/context lines with a line-number
+ * gutter and a +/-/space marker. Accepts either a raw unified-diff string
+ * (parsed internally) or pre-parsed {@link DiffLine} rows.
+ *
+ * @example
+ * ```tsx
+ * <DiffViewer
+ *   filename="src/lib/cn.ts"
+ *   diff={`@@ -1,3 +1,3 @@\n-export const cn = (a) => a\n+export const cn = (a, b) => a + b\n context line`}
+ * />
+ * ```
+ */
+export function DiffViewer(props: DiffViewerProps): JSX.Element {
+  const parsed = createMemo(() =>
+    props.lines ? { lines: props.lines, filename: undefined } : parseUnifiedDiff(props.diff ?? ''),
+  )
+
+  const rows = () => parsed().lines
+  const displayFilename = () => props.filename ?? parsed().filename
+
+  const counts = createMemo(() => {
+    let added = 0
+    let removed = 0
+    for (const line of rows()) {
+      if (line.type === 'add') added++
+      else if (line.type === 'remove') removed++
+    }
+    return { added, removed }
+  })
+
+  const ariaLabel = () => {
+    const { added, removed } = counts()
+    const name = displayFilename()
+    return `Diff${name ? ` for ${name}` : ''}: ${added} added, ${removed} removed`
+  }
+
+  return (
+    <div
+      role="figure"
+      aria-label={ariaLabel()}
+      class={cn('overflow-hidden rounded-lg border border-border bg-card', props.class)}
+    >
+      <Show when={displayFilename()}>
+        <div class="border-b border-border px-4 py-2 text-sm font-medium text-foreground">
+          {displayFilename()}
+        </div>
+      </Show>
+      <div class="overflow-x-auto">
+        <div class="min-w-max font-mono text-sm">
+          <For each={rows()}>
+            {(line) => (
+              <div class={cn('flex', ROW_BG[line.type])}>
+                <span class="w-12 shrink-0 select-none py-0.5 pr-2 text-right tabular-nums text-xs text-muted-foreground">
+                  {line.oldNum ?? ''}
+                </span>
+                <span class="w-12 shrink-0 select-none py-0.5 pr-2 text-right tabular-nums text-xs text-muted-foreground">
+                  {line.newNum ?? ''}
+                </span>
+                <span class={cn('w-5 shrink-0 select-none py-0.5 text-center', MARKER_TONE[line.type])}>
+                  {MARKER[line.type]}
+                </span>
+                <span class={cn('flex-1 whitespace-pre py-0.5 pr-4', CONTENT_TONE[line.type])}>
+                  {line.content}
+                </span>
+              </div>
+            )}
+          </For>
+        </div>
+      </div>
+    </div>
+  )
+}