@a4ui/core 0.24.3 → 0.26.0

package/src/ui/MasterDetail.tsx

@@ -0,0 +1,117 @@
+// List + detail-pane layout with keyboard navigation, e.g. an inbox or a
+// command-result view. The list is a `listbox`; Up/Down move the selection,
+// Home/End jump to the first/last item. Controlled (`selectedId`+`onSelect`)
+// or uncontrolled (internal signal, defaults to the first item).
+import type { JSX } from 'solid-js'
+import { createMemo, createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface MasterDetailItem {
+  id: string
+  label: string
+  meta?: JSX.Element
+  detail: JSX.Element
+}
+
+export interface MasterDetailProps {
+  items: MasterDetailItem[]
+  /** Controlled selection. Uncontrolled (internal signal, defaults to the first item) when omitted. */
+  selectedId?: string
+  onSelect?: (id: string) => void
+  class?: string
+}
+
+/**
+ * List + detail-pane layout: a scrollable list of items on the left, the
+ * selected item's detail content on the right. Arrow keys (and Home/End)
+ * move the selection within the list.
+ *
+ * @example
+ * ```tsx
+ * <MasterDetail
+ *   items={messages.map((m) => ({ id: m.id, label: m.subject, meta: <Badge>{m.from}</Badge>, detail: <MessageBody message={m} /> }))}
+ * />
+ * ```
+ */
+export function MasterDetail(props: MasterDetailProps): JSX.Element {
+  const [internalId, setInternalId] = createSignal<string | undefined>(props.items[0]?.id)
+
+  const selectedId = createMemo(() => props.selectedId ?? internalId())
+
+  const select = (id: string) => {
+    if (props.selectedId === undefined) setInternalId(id)
+    props.onSelect?.(id)
+  }
+
+  const selectedItem = createMemo(() => props.items.find((item) => item.id === selectedId()))
+
+  let listEl: HTMLDivElement | undefined
+
+  const onKeyDown = (event: KeyboardEvent) => {
+    const items = props.items
+    if (items.length === 0) return
+    const currentIndex = items.findIndex((item) => item.id === selectedId())
+
+    let nextIndex: number
+    if (event.key === 'ArrowDown')
+      nextIndex = currentIndex < 0 ? 0 : Math.min(currentIndex + 1, items.length - 1)
+    else if (event.key === 'ArrowUp') nextIndex = currentIndex < 0 ? 0 : Math.max(currentIndex - 1, 0)
+    else if (event.key === 'Home') nextIndex = 0
+    else if (event.key === 'End') nextIndex = items.length - 1
+    else return
+
+    event.preventDefault()
+    const next = items[nextIndex]
+    if (!next) return
+    select(next.id)
+    listEl?.querySelector<HTMLElement>(`[data-item-id="${next.id}"]`)?.focus()
+  }
+
+  return (
+    <div class={cn('grid grid-cols-1 gap-4 sm:grid-cols-[16rem_1fr]', props.class)}>
+      <div
+        ref={listEl}
+        role="listbox"
+        aria-label="Items"
+        tabindex={0}
+        onKeyDown={onKeyDown}
+        class="flex max-h-96 flex-col gap-1 overflow-y-auto rounded-xl border border-border bg-card p-1 text-card-foreground sm:max-h-[28rem]"
+      >
+        <For each={props.items}>
+          {(item) => {
+            const isSelected = () => item.id === selectedId()
+            return (
+              <button
+                type="button"
+                role="option"
+                aria-selected={isSelected()}
+                data-item-id={item.id}
+                tabindex={-1}
+                onClick={() => select(item.id)}
+                class={cn(
+                  'flex w-full items-center justify-between gap-2 rounded-lg px-3 py-2 text-left text-sm transition-colors',
+                  isSelected() ? 'bg-muted text-foreground' : 'text-muted-foreground hover:bg-muted/60',
+                )}
+              >
+                <span class="truncate">{item.label}</span>
+                <Show when={item.meta}>{item.meta}</Show>
+              </button>
+            )
+          }}
+        </For>
+      </div>
+      <div class="rounded-xl border border-border bg-card p-5 text-card-foreground">
+        {/* keyed: re-render the detail when the selected item changes (a plain
+            Show wouldn't re-run its child when `when` stays truthy across items). */}
+        <Show
+          when={selectedItem()}
+          keyed
+          fallback={<p class="text-sm text-muted-foreground">Select an item to see its details.</p>}
+        >
+          {(item) => item.detail}
+        </Show>
+      </div>
+    </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/PillSearch.tsx

@@ -0,0 +1,86 @@
+// Compact multi-parameter search entry: a single rounded-full bar that
+// compresses several fields (e.g. Where / When / Who) into clickable
+// segments, ending in a round primary search button.
+import type { JSX } from 'solid-js'
+import { For } from 'solid-js'
+import { Search } from 'lucide-solid'
+
+import { cn } from '../lib/cn'
+
+export interface PillField {
+  /** Stable identifier passed back via {@link PillSearchProps.onFieldClick}. */
+  key: string
+  /** Small label shown above the value, e.g. `"Where"`. */
+  label: string
+  /** Current value shown below the label. Falls back to `placeholder` when unset. */
+  value?: string
+  /** Muted hint shown when `value` is unset. */
+  placeholder?: string
+}
+
+export interface PillSearchProps {
+  fields: PillField[]
+  /** Called with the clicked field's `key`. */
+  onFieldClick?: (key: string) => void
+  /** Called when the round search button is pressed. */
+  onSearch?: () => void
+  class?: string
+}
+
+/**
+ * Rounded-full search bar that packs several fields into segments with a
+ * round primary search button — the classic "Where / When / Who" pattern
+ * compressed into one compact control.
+ *
+ * @example
+ * ```tsx
+ * <PillSearch
+ *   fields={[
+ *     { key: 'where', label: 'Where', value: 'Lisbon' },
+ *     { key: 'when', label: 'When', placeholder: 'Add dates' },
+ *     { key: 'who', label: 'Who', placeholder: 'Add guests' },
+ *   ]}
+ *   onFieldClick={(key) => console.log('open', key)}
+ *   onSearch={() => console.log('search')}
+ * />
+ * ```
+ */
+export function PillSearch(props: PillSearchProps): JSX.Element {
+  return (
+    <div
+      class={cn(
+        'inline-flex max-w-full items-center overflow-x-auto rounded-full border border-border bg-card shadow-sm',
+        props.class,
+      )}
+    >
+      <For each={props.fields}>
+        {(field, index) => (
+          <button
+            type="button"
+            aria-label={field.label}
+            onClick={() => props.onFieldClick?.(field.key)}
+            class={cn(
+              'flex min-w-[6.5rem] shrink-0 flex-col items-start px-4 py-2 text-left transition-colors duration-150 hover:bg-muted focus:outline-none focus:ring-2 focus:ring-ring',
+              index() === 0 ? 'rounded-l-full' : 'border-l border-border',
+            )}
+          >
+            <span class="text-xs font-medium text-muted-foreground">{field.label}</span>
+            <span class={cn('text-sm', field.value ? 'text-foreground' : 'text-muted-foreground')}>
+              {field.value ?? field.placeholder}
+            </span>
+          </button>
+        )}
+      </For>
+      <div class="shrink-0 py-1.5 pl-1 pr-1.5">
+        <button
+          type="button"
+          aria-label="Search"
+          onClick={() => props.onSearch?.()}
+          class="inline-flex h-10 w-10 items-center justify-center rounded-full bg-primary text-primary-foreground transition-[color,background-color,transform] duration-150 hover:bg-primary/90 active:scale-[0.97] focus:outline-none focus:ring-2 focus:ring-ring"
+        >
+          <Search class="h-4 w-4" aria-hidden="true" />
+        </button>
+      </div>
+    </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>
+  )
+}