@a4ui/core 0.24.2 → 0.25.0

package/src/ui/Citation.tsx

@@ -0,0 +1,97 @@
+// Citation — inline source-reference chip for AI answers that cite sources,
+// plus a compact SourceList for the "Sources" block below the answer.
+import { For, type JSX, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+const CITATION_BASE =
+  'citation inline-flex items-center justify-center rounded-full bg-muted text-muted-foreground ' +
+  'text-[0.65rem] leading-none align-super h-[1.1em] min-w-[1.1em] px-1 font-semibold'
+
+export interface CitationProps {
+  /** The source number shown in the chip, e.g. `1`. */
+  index: number
+  /** Links out to the source when present (opens in a new tab). */
+  href?: string
+  /** Shown as a native tooltip and used as the accessible name. */
+  title?: string
+  class?: string
+}
+
+/**
+ * Small inline chip citing a numbered source, meant to sit inside a sentence
+ * right after the claim it backs up.
+ *
+ * @example
+ * ```tsx
+ * <p>
+ *   Glass surfaces use a translucent backdrop blur
+ *   <Citation index={1} href="https://example.com/spec" title="Design spec" />.
+ * </p>
+ * ```
+ */
+export function Citation(props: CitationProps): JSX.Element {
+  return (
+    <Show
+      when={props.href}
+      fallback={
+        <span class={cn(CITATION_BASE, props.class)} title={props.title}>
+          {props.index}
+        </span>
+      }
+    >
+      <a
+        href={props.href}
+        target="_blank"
+        rel="noreferrer"
+        title={props.title}
+        aria-label={props.title ?? `Source ${props.index}`}
+        class={cn(CITATION_BASE, 'hover:bg-primary/15 hover:text-foreground', props.class)}
+      >
+        {props.index}
+      </a>
+    </Show>
+  )
+}
+
+export interface SourceListProps {
+  sources: { title: string; href?: string }[]
+  class?: string
+}
+
+/**
+ * Compact numbered "Sources" block matching the indices used by {@link Citation}.
+ *
+ * @example
+ * ```tsx
+ * <SourceList
+ *   sources={[
+ *     { title: 'Design spec', href: 'https://example.com/spec' },
+ *     { title: 'Internal style guide' },
+ *   ]}
+ * />
+ * ```
+ */
+export function SourceList(props: SourceListProps): JSX.Element {
+  return (
+    <ol class={cn('flex flex-col gap-1 text-sm text-muted-foreground', props.class)}>
+      <For each={props.sources}>
+        {(source, index) => (
+          <li class="flex gap-2">
+            <span class="text-muted-foreground/70">{index() + 1}.</span>
+            <Show when={source.href} fallback={<span>{source.title}</span>}>
+              <a
+                href={source.href}
+                target="_blank"
+                rel="noreferrer"
+                class="text-foreground underline decoration-border underline-offset-2 hover:text-primary"
+              >
+                {source.title}
+              </a>
+            </Show>
+          </li>
+        )}
+      </For>
+    </ol>
+  )
+}

package/src/ui/FloatingToolbar.tsx

@@ -0,0 +1,75 @@
+// Detached, centered glass toolbar that condenses (tighter padding, slight
+// scale-down, stronger blur) once the page scrolls past a small threshold —
+// a "Liquid Glass"-style floating bar for persistent actions.
+import type { JSX } from 'solid-js'
+import { createSignal, onCleanup, onMount } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+// Scroll distance (px) past which the bar condenses.
+const CONDENSE_THRESHOLD = 24
+
+const POSITION_CLASSES: Record<'top' | 'bottom', string> = {
+  top: 'top-4',
+  bottom: 'bottom-4',
+}
+
+export interface FloatingToolbarProps {
+  children: JSX.Element
+  /** Which edge of the viewport the bar is anchored to. Defaults to `'bottom'`. */
+  position?: 'top' | 'bottom'
+  /** Shrink padding/scale and intensify the glass blur once scrolled past ~24px. Defaults to `true`. */
+  condenseOnScroll?: boolean
+  class?: string
+}
+
+/**
+ * Fixed, horizontally-centered glass toolbar that floats above the page
+ * content. When `condenseOnScroll` is on (the default), it tightens its
+ * padding and scales down slightly once the user scrolls past a small
+ * threshold, mimicking a "Liquid Glass" detached bar. Reduced-motion aware:
+ * the condense change applies instantly, without a transition, when
+ * {@link motionReduced} is true.
+ *
+ * @example
+ * ```tsx
+ * <FloatingToolbar position="bottom">
+ *   <IconButton label="Undo"><UndoIcon /></IconButton>
+ *   <IconButton label="Redo"><RedoIcon /></IconButton>
+ * </FloatingToolbar>
+ * ```
+ */
+export function FloatingToolbar(props: FloatingToolbarProps): JSX.Element {
+  const [condensed, setCondensed] = createSignal(false)
+
+  onMount(() => {
+    if (props.condenseOnScroll === false) return
+
+    const onScroll = () => {
+      setCondensed(window.scrollY > CONDENSE_THRESHOLD)
+    }
+
+    onScroll()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    onCleanup(() => window.removeEventListener('scroll', onScroll))
+  })
+
+  return (
+    <div
+      role="toolbar"
+      class={cn(
+        'card glass fixed left-1/2 z-40 flex -translate-x-1/2 items-center gap-1 rounded-full',
+        'border border-border/60 shadow-lg',
+        POSITION_CLASSES[props.position ?? 'bottom'],
+        !motionReduced() && 'transition-all duration-300 ease-out',
+        condensed()
+          ? 'scale-95 gap-0.5 px-2 py-1 backdrop-blur-xl'
+          : 'scale-100 gap-1 px-3 py-2 backdrop-blur-md',
+        props.class,
+      )}
+    >
+      {props.children}
+    </div>
+  )
+}

package/src/ui/InlineSelect.tsx

@@ -0,0 +1,101 @@
+// InlineSelect — click-to-edit select. Shows the current value as plain text
+// until clicked, then swaps to a `Select` for picking a new value; committing
+// (or blurring/Escape) returns it to text. For status/priority-style editing
+// inline in rows/tables.
+import type { JSX } from 'solid-js'
+import { createEffect, createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Select } from './Select'
+
+export interface InlineSelectOption {
+  value: string
+  label: string
+}
+
+export interface InlineSelectProps {
+  value: string
+  options: InlineSelectOption[]
+  onChange: (value: string) => void
+  placeholder?: string
+  class?: string
+}
+
+/**
+ * Edit-in-place select: renders the current value as a clickable chip until
+ * clicked, then swaps to a `Select` for picking a new value. Committing a
+ * choice returns it to text; blurring away or pressing Escape cancels back
+ * to the previous value. Built for status/priority-style editing inline in
+ * rows/tables.
+ *
+ * @example
+ * ```tsx
+ * <InlineSelect
+ *   value={status()}
+ *   options={[
+ *     { value: 'todo', label: 'To do' },
+ *     { value: 'doing', label: 'In progress' },
+ *     { value: 'done', label: 'Done' },
+ *   ]}
+ *   onChange={setStatus}
+ * />
+ * ```
+ */
+export function InlineSelect(props: InlineSelectProps): JSX.Element {
+  const [editing, setEditing] = createSignal(false)
+  let wrapperEl: HTMLDivElement | undefined
+
+  const selectedLabel = () =>
+    props.options.find((option) => option.value === props.value)?.label ?? props.placeholder ?? ''
+
+  const cancel = () => setEditing(false)
+
+  const commit = (value: string) => {
+    props.onChange(value)
+    setEditing(false)
+  }
+
+  // Focus the <select> as soon as it mounts, so a click straight into edit
+  // mode is immediately usable from the keyboard (and blur-to-cancel below
+  // has something to blur from).
+  createEffect(() => {
+    if (editing()) wrapperEl?.querySelector('select')?.focus()
+  })
+
+  return (
+    <div
+      ref={wrapperEl}
+      class={cn('inline-flex', props.class)}
+      onFocusOut={() => {
+        // Defer: swapping the trigger button for the <select> fires a transient
+        // focusout (relatedTarget is momentarily null) before the effect below
+        // moves focus onto the <select>. Re-check on the next tick so we only
+        // cancel when focus has genuinely left the wrapper.
+        setTimeout(() => {
+          if (wrapperEl && !wrapperEl.contains(document.activeElement)) cancel()
+        }, 0)
+      }}
+      onKeyDown={(ev) => {
+        if (ev.key === 'Escape') cancel()
+      }}
+    >
+      <Show
+        when={editing()}
+        fallback={
+          <button
+            type="button"
+            class="rounded px-1.5 py-0.5 text-left hover:bg-muted"
+            aria-label={`Edit — ${selectedLabel()}`}
+            onClick={() => setEditing(true)}
+          >
+            {selectedLabel()}
+          </button>
+        }
+      >
+        <Select value={props.value} onChange={commit}>
+          <For each={props.options}>{(option) => <option value={option.value}>{option.label}</option>}</For>
+        </Select>
+      </Show>
+    </div>
+  )
+}

package/src/ui/Message.tsx

@@ -0,0 +1,69 @@
+// Message — one chat message row, full-width (no bubble). Rich content is
+// passed as children so the caller can render markdown, code blocks, lists,
+// etc. inside the readable prose block.
+import { type JSX, Match, Show, Switch } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** Who sent a {@link Message}; drives its subtle visual treatment. */
+export type ChatRole = 'user' | 'assistant' | 'system'
+
+export interface MessageProps {
+  role: ChatRole
+  children: JSX.Element
+  /** Display name shown in the header line. Omitted for `system` messages. */
+  author?: string
+  /** Small avatar node, e.g. an icon or `<Avatar/>`. Omitted for `system` messages. */
+  avatar?: JSX.Element
+  /** Preformatted timestamp string, e.g. `'2:45 PM'`. */
+  timestamp?: string
+  class?: string
+}
+
+/**
+ * Full-width chat message row with no bubble: an optional avatar/author
+ * header line followed by a prose content block. Role is differentiated with
+ * subtle, token-based treatment only — `assistant` gets a faint muted panel,
+ * `user` stays plain, `system` is a small centered note.
+ *
+ * @example
+ * ```tsx
+ * <Message role="assistant" author="Nova" timestamp="2:45 PM">
+ *   <p>Here's the summary you asked for.</p>
+ * </Message>
+ * ```
+ */
+export function Message(props: MessageProps): JSX.Element {
+  return (
+    <Switch>
+      <Match when={props.role === 'system'}>
+        <div class={cn('text-center text-xs text-muted-foreground italic', props.class)}>
+          {props.children}
+        </div>
+      </Match>
+      <Match when={true}>
+        <div
+          class={cn(
+            'flex flex-col gap-1',
+            props.role === 'assistant' && 'rounded-xl bg-muted/40 p-3',
+            props.role === 'user' && 'rounded-xl bg-primary/5 p-3',
+            props.class,
+          )}
+        >
+          <Show when={props.author || props.avatar || props.timestamp}>
+            <div class="flex items-center gap-2">
+              {props.avatar}
+              <Show when={props.author}>
+                <span class="text-sm font-medium text-foreground">{props.author}</span>
+              </Show>
+              <Show when={props.timestamp}>
+                <span class="text-xs text-muted-foreground">{props.timestamp}</span>
+              </Show>
+            </div>
+          </Show>
+          <div class="space-y-2 text-sm leading-relaxed text-foreground">{props.children}</div>
+        </div>
+      </Match>
+    </Switch>
+  )
+}

package/src/ui/PageTransition.tsx

@@ -0,0 +1,90 @@
+// Keyed cross-fade / slide transition for route or view swaps: change `key`
+// and the outgoing content fades (and optionally slides) out, then the new
+// `children` fades in. Driven purely by the `key` prop — no routing library
+// involved. Uses Motion's `animate` (opacity + `y`, transform/opacity only)
+// like `animateIn` in lib/motion.ts, and swaps instantly under reduced motion.
+import { createEffect, createSignal, onCleanup, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+/** Transition style for {@link PageTransition}. `slide` adds a small vertical shift. */
+export type PageTransitionMode = 'fade' | 'slide'
+
+export interface PageTransitionProps {
+  /** Change this value (e.g. a route or view id) to trigger a transition. */
+  key: string | number
+  children: JSX.Element
+  /** `fade` = opacity only; `slide` = opacity + small vertical shift. @default 'fade' */
+  mode?: PageTransitionMode
+  class?: string
+}
+
+const SLIDE_Y = 12
+const OUT_DURATION = 0.16
+const IN_DURATION = 0.22
+
+/**
+ * Cross-fades (or slides) its `children` out and in whenever `key` changes —
+ * for route/view transitions. Driven purely by the `key` prop; pair it with a
+ * router's current path or any view-switch signal. Swaps instantly under
+ * reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <PageTransition key={activeTab()} mode="slide">
+ *   <TabContent id={activeTab()} />
+ * </PageTransition>
+ * ```
+ */
+export function PageTransition(props: PageTransitionProps): JSX.Element {
+  const [content, setContent] = createSignal(props.children)
+  let wrapEl: HTMLDivElement | undefined
+  let controls: ReturnType<typeof animate> | undefined
+  let previousKey = props.key
+  let mounted = false
+
+  createEffect(() => {
+    const nextKey = props.key
+    const nextChildren = props.children
+
+    if (!mounted) {
+      mounted = true
+      previousKey = nextKey
+      return
+    }
+
+    if (nextKey === previousKey) {
+      // Children changed without a key change: sync in place, no transition.
+      setContent(() => nextChildren)
+      return
+    }
+    previousKey = nextKey
+
+    const el = wrapEl
+    const y = (props.mode ?? 'fade') === 'slide' ? SLIDE_Y : 0
+
+    controls?.stop()
+
+    if (!el || motionReduced()) {
+      setContent(() => nextChildren)
+      return
+    }
+
+    controls = animate(el, { opacity: [1, 0], y: [0, -y] }, { duration: OUT_DURATION, ease: 'easeIn' })
+    controls.finished
+      .then(() => {
+        setContent(() => nextChildren)
+        controls = animate(el, { opacity: [0, 1], y: [y, 0] }, { duration: IN_DURATION, ease: 'easeOut' })
+      })
+      .catch(() => {})
+  })
+
+  onCleanup(() => controls?.stop())
+
+  return (
+    <div ref={wrapEl} class={cn(props.class)}>
+      {content()}
+    </div>
+  )
+}

package/src/ui/PromptComposer.tsx

@@ -0,0 +1,138 @@
+// The input area for a chat/AI UI: an auto-growing textarea in a glass card,
+// removable attachment chips, and a bottom bar with an optional attach button
+// and a Send button. Submits on Cmd/Ctrl+Enter or the Send click.
+import { Paperclip, SendHorizontal, X } from 'lucide-solid'
+import { createEffect, For, type JSX, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Button } from './Button'
+
+export interface PromptComposerProps {
+  value: string
+  onInput: (value: string) => void
+  onSubmit: (value: string) => void
+  placeholder?: string
+  disabled?: boolean
+  /** Small helper text under the field, e.g. model name or a character count. */
+  hint?: JSX.Element
+  /** Attachment labels/filenames shown as removable chips above the input. */
+  attachments?: string[]
+  onRemoveAttachment?: (index: number) => void
+  /** When set, shows a paperclip button that calls this on click. */
+  onAttach?: () => void
+  class?: string
+}
+
+/**
+ * The input area for a chat/AI UI: an auto-growing textarea inside a glass
+ * card, removable attachment chips, and a bottom bar with an optional attach
+ * button and a Send button. Fully controlled — the parent owns `value`.
+ * Submits on **Cmd/Ctrl+Enter** or the Send button click.
+ *
+ * @example
+ * ```tsx
+ * const [value, setValue] = createSignal('')
+ * <PromptComposer
+ *   value={value()}
+ *   onInput={setValue}
+ *   onSubmit={(v) => { sendMessage(v); setValue('') }}
+ *   placeholder="Ask anything…"
+ * />
+ * ```
+ */
+export function PromptComposer(props: PromptComposerProps): JSX.Element {
+  let textareaRef: HTMLTextAreaElement | undefined
+
+  // Auto-grow: reset height then snap to scrollHeight, capped by max-h via CSS.
+  createEffect(() => {
+    void props.value
+    if (!textareaRef) return
+    textareaRef.style.height = 'auto'
+    textareaRef.style.height = `${textareaRef.scrollHeight}px`
+  })
+
+  const canSubmit = (): boolean => !props.disabled && props.value.trim().length > 0
+
+  const submit = (): void => {
+    if (!canSubmit()) return
+    props.onSubmit(props.value)
+  }
+
+  const handleKeyDown = (event: KeyboardEvent): void => {
+    if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') {
+      event.preventDefault()
+      submit()
+    }
+  }
+
+  return (
+    <div
+      class={cn(
+        'card w-full rounded-2xl border border-border bg-card p-3 text-card-foreground shadow-lg',
+        props.class,
+      )}
+    >
+      <Show when={(props.attachments?.length ?? 0) > 0}>
+        <div class="mb-2 flex flex-wrap gap-1.5">
+          <For each={props.attachments}>
+            {(label, i) => (
+              <span class="inline-flex items-center gap-1 rounded-full bg-muted px-2 py-1 text-xs text-muted-foreground ring-1 ring-inset ring-border">
+                <span class="max-w-[12rem] truncate">{label}</span>
+                <button
+                  type="button"
+                  aria-label={`Remove attachment ${label}`}
+                  onClick={() => props.onRemoveAttachment?.(i())}
+                  class="rounded-full p-0.5 text-muted-foreground transition-colors hover:bg-background hover:text-foreground"
+                >
+                  <X class="h-3 w-3" aria-hidden="true" />
+                </button>
+              </span>
+            )}
+          </For>
+        </div>
+      </Show>
+
+      <textarea
+        ref={textareaRef}
+        aria-label="Message"
+        value={props.value}
+        placeholder={props.placeholder ?? 'Send a message…'}
+        disabled={props.disabled}
+        rows={1}
+        onInput={(ev) => props.onInput(ev.currentTarget.value)}
+        onKeyDown={handleKeyDown}
+        class="a4-field max-h-64 min-h-[24px] w-full resize-none border-0 bg-transparent p-0 text-sm text-foreground outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50"
+      />
+
+      <Show when={props.hint}>
+        <p class="mt-1 text-xs text-muted-foreground">{props.hint}</p>
+      </Show>
+
+      <div class="mt-2 flex items-center justify-between gap-2">
+        <Show when={props.onAttach} fallback={<span />}>
+          <Button
+            type="button"
+            variant="ghost"
+            aria-label="Attach file"
+            disabled={props.disabled}
+            onClick={() => props.onAttach?.()}
+            class="px-2"
+          >
+            <Paperclip class="h-4 w-4" aria-hidden="true" />
+          </Button>
+        </Show>
+
+        <Button
+          type="button"
+          variant="primary"
+          aria-label="Send message"
+          disabled={!canSubmit()}
+          onClick={submit}
+          class="px-2"
+        >
+          <SendHorizontal class="h-4 w-4" aria-hidden="true" />
+        </Button>
+      </div>
+    </div>
+  )
+}

package/src/ui/StreamingText.tsx

@@ -0,0 +1,98 @@
+// Streams `text` in as new characters are appended — eases in the newly
+// added tail at `speed` chars/sec (via a rAF loop) rather than snapping
+// straight to the new length, with a blinking caret while more is expected.
+// Built for AI answer UIs where `text` grows incrementally as tokens arrive.
+import { createEffect, createSignal, onCleanup, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface StreamingTextProps {
+  /** The (possibly growing) full text so far. */
+  text: string
+  /** Whether more text is still coming; shows the blinking caret while `true`. @default true */
+  streaming?: boolean
+  /** Reveal speed, in characters per second, for newly appended text. @default 120 */
+  speed?: number
+  class?: string
+}
+
+/**
+ * Reveals `text` as it "streams" in: when `text` grows, the newly appended
+ * characters ease in at `speed` chars/sec instead of snapping into place,
+ * with a blinking caret while `streaming`. Already-revealed characters never
+ * re-animate — only the new tail is eased in, so appending to `text` doesn't
+ * replay the whole reveal. Skips the reveal (shows the full text at once)
+ * under reduced motion — the caret still blinks while `streaming` in that
+ * case. `streaming={false}` shows the full text immediately with no caret,
+ * for the final/settled answer.
+ *
+ * @example
+ * ```tsx
+ * <StreamingText text={answer()} streaming={!done()} />
+ * ```
+ */
+export function StreamingText(props: StreamingTextProps): JSX.Element {
+  // eslint-disable-next-line solid/reactivity -- one-time seed; the effect below re-reads props.text on each change
+  const [revealed, setRevealed] = createSignal(motionReduced() ? props.text.length : 0)
+
+  let raf: number | undefined
+  let prevText = ''
+
+  const stop = (): void => {
+    if (raf === undefined) return
+    cancelAnimationFrame(raf)
+    raf = undefined
+  }
+
+  createEffect(() => {
+    const text = props.text
+    const isAppend = text.startsWith(prevText)
+    const from = isAppend ? revealed() : 0
+    prevText = text
+
+    stop()
+
+    if (motionReduced() || (props.streaming ?? true) === false) {
+      setRevealed(text.length)
+      return
+    }
+
+    if (from >= text.length) {
+      setRevealed(text.length)
+      return
+    }
+
+    const speed = props.speed ?? 120
+    let count = from
+    let last: number | undefined
+
+    const step = (now: number): void => {
+      if (last === undefined) last = now
+      const elapsed = (now - last) / 1000
+      last = now
+      count = Math.min(text.length, count + elapsed * speed)
+      setRevealed(Math.floor(count))
+      raf = count < text.length ? requestAnimationFrame(step) : undefined
+    }
+
+    setRevealed(from)
+    raf = requestAnimationFrame(step)
+  })
+
+  onCleanup(stop)
+
+  const display = (): string => props.text.slice(0, revealed())
+  const showCaret = (): boolean => props.streaming ?? true
+
+  return (
+    <span class={cn('whitespace-pre-wrap', props.class)}>
+      {display()}
+      {showCaret() && (
+        <span aria-hidden="true" class="animate-pulse text-current motion-reduce:animate-none">
+          ▍
+        </span>
+      )}
+    </span>
+  )
+}