@a4ui/core 0.24.3 → 0.26.0

package/src/lib/viewTransition.ts

@@ -0,0 +1,32 @@
+// Wrapper around the browser View Transitions API. Not every target browser
+// implements `document.startViewTransition` yet, and even where it exists we
+// want to skip it under reduced motion — this module centralizes both checks
+// so callers don't have to feature-detect or re-import motionReduced themselves.
+import { motionReduced } from './motion'
+
+/** Minimal shape of `Document` augmented with the View Transitions API. */
+interface DocumentWithViewTransitions {
+  startViewTransition: (callback: () => void) => unknown
+}
+
+function supportsViewTransitions(doc: Document): doc is Document & DocumentWithViewTransitions {
+  return (
+    'startViewTransition' in doc &&
+    typeof (doc as unknown as DocumentWithViewTransitions).startViewTransition === 'function'
+  )
+}
+
+/**
+ * Run `update` inside a View Transition when the browser supports it, so DOM
+ * changes cross-fade automatically; otherwise just run `update` synchronously.
+ * Respects reduced-motion (skips the transition).
+ * @example
+ * startViewTransition(() => setRoute('details'))
+ */
+export function startViewTransition(update: () => void): void {
+  if (typeof document === 'undefined' || motionReduced() || !supportsViewTransitions(document)) {
+    update()
+    return
+  }
+  document.startViewTransition(update)
+}

package/src/ui/ArtifactPanel.tsx

@@ -0,0 +1,88 @@
+// Inline (non-portalled) right-side panel for AI-generated output — code,
+// preview, or doc — shown alongside a chat. Unlike `Drawer` (a portalled
+// overlay on Kobalte's Dialog), the caller places this directly in a flex row
+// next to the main content: it reserves no space when closed (width collapses
+// to 0) and reveals by animating its own width, so the chat pane reflows next
+// to it instead of being covered. We collapse to width 0 rather than toggling
+// `display: none` because a `display` toggle jumps instantly — animating width
+// is what makes it slide.
+import { X } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface ArtifactPanelProps {
+  open: boolean
+  onClose?: () => void
+  title?: string
+  /** Panel width in px when open. @default 420 */
+  width?: number
+  children: JSX.Element
+  class?: string
+}
+
+/**
+ * Right-side split panel that holds generated output (code, preview, doc) next
+ * to a chat — for AI UIs that keep the artifact and the conversation visible at
+ * once. Inline, not an overlay: place it as the last child of a flex row next
+ * to the main content. Slides open/closed by animating width (and a matching
+ * fade/slide on its content), reduced-motion aware via `motionReduced()`.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = createSignal(false)
+ * <div class="flex h-full">
+ *   <main class="min-w-0 flex-1">…chat…</main>
+ *   <ArtifactPanel open={open()} onClose={() => setOpen(false)} title="script.py">
+ *     <pre class="p-4 text-sm">…generated code…</pre>
+ *   </ArtifactPanel>
+ * </div>
+ * ```
+ */
+export function ArtifactPanel(props: ArtifactPanelProps): JSX.Element {
+  const width = () => props.width ?? 420
+  const reduced = () => motionReduced()
+
+  return (
+    <div
+      role="complementary"
+      aria-label={props.title ?? 'Artifact'}
+      aria-hidden={!props.open}
+      class={cn(
+        'card h-full shrink-0 overflow-hidden border-border bg-glass',
+        props.open ? 'border-l' : 'border-0',
+        reduced() ? undefined : 'transition-[width] duration-300 ease-in-out',
+        props.class,
+      )}
+      style={{ width: `${props.open ? width() : 0}px` }}
+    >
+      {/* Fixed-width inner wrapper: the content never reflows/wraps while the
+          outer element's width animates between 0 and `width()`. */}
+      <div
+        class={cn(
+          'flex h-full flex-col',
+          reduced() ? undefined : 'transition-[opacity,transform] duration-300 ease-in-out',
+        )}
+        style={{
+          width: `${width()}px`,
+          opacity: props.open ? 1 : 0,
+          transform: props.open ? 'translateX(0)' : 'translateX(16px)',
+        }}
+      >
+        <div class="sticky top-0 z-10 flex items-center justify-between border-b border-border bg-background/90 px-5 py-4 backdrop-blur">
+          <span class="truncate text-[16px] font-bold leading-tight">{props.title ?? 'Artifact'}</span>
+          <button
+            type="button"
+            onClick={() => props.onClose?.()}
+            class="grid h-9 w-9 shrink-0 place-items-center rounded-lg text-muted-foreground transition hover:bg-muted hover:text-foreground"
+            aria-label="Close"
+          >
+            <X class="h-5 w-5" />
+          </button>
+        </div>
+        <div class="min-h-0 flex-1 overflow-y-auto">{props.children}</div>
+      </div>
+    </div>
+  )
+}

package/src/ui/CategoryStrip.tsx

@@ -0,0 +1,80 @@
+// Horizontally-scrollable strip of icon+label category filters, with an
+// active-underline indicator — e.g. a storefront category nav (All, Fresh,
+// Bakery, Dairy, …). Scrollbar is hidden; Left/Right arrows move selection.
+import type { JSX } from 'solid-js'
+import { For } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single selectable category: value, label, and optional leading icon. */
+export interface CategoryItem {
+  value: string
+  label: string
+  icon?: JSX.Element
+}
+
+export interface CategoryStripProps {
+  items: CategoryItem[]
+  value: string
+  onChange: (value: string) => void
+  class?: string
+}
+
+/**
+ * Horizontally-scrollable row of icon-over-label category tabs with a
+ * bottom-underline indicator on the active item. Left/Right arrow keys move
+ * the selection between items.
+ *
+ * @example
+ * ```tsx
+ * <CategoryStrip items={categories} value={category()} onChange={setCategory} />
+ * ```
+ */
+export function CategoryStrip(props: CategoryStripProps): JSX.Element {
+  const activeIndex = () => props.items.findIndex((item) => item.value === props.value)
+
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return
+    event.preventDefault()
+    const count = props.items.length
+    if (count === 0) return
+    const current = activeIndex()
+    const delta = event.key === 'ArrowRight' ? 1 : -1
+    const next = ((current === -1 ? 0 : current) + delta + count) % count
+    props.onChange(props.items[next].value)
+  }
+
+  return (
+    <div
+      role="tablist"
+      class={cn(
+        'flex gap-6 overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden',
+        props.class,
+      )}
+      onKeyDown={onKeyDown}
+    >
+      <For each={props.items}>
+        {(item) => {
+          const isActive = () => item.value === props.value
+          return (
+            <button
+              type="button"
+              role="tab"
+              aria-selected={isActive()}
+              class={cn(
+                'flex shrink-0 flex-col items-center gap-1 border-b-2 px-1 pb-2 text-xs font-medium transition-colors',
+                isActive()
+                  ? 'border-primary text-foreground'
+                  : 'border-transparent text-muted-foreground hover:text-foreground',
+              )}
+              onClick={() => props.onChange(item.value)}
+            >
+              {item.icon}
+              <span>{item.label}</span>
+            </button>
+          )
+        }}
+      </For>
+    </div>
+  )
+}

package/src/ui/ChatThread.tsx

@@ -0,0 +1,59 @@
+// ChatThread — layout shell for AI/conversation UIs: a centered, scrollable
+// reading column that stacks chat messages. Purely a container: it has no
+// idea what a "message" looks like, so any element can be stacked inside it.
+import { createEffect, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface ChatThreadProps {
+  children: JSX.Element
+  /** Max width of the reading column, in px. Defaults to `768`. */
+  maxWidth?: number
+  /** Auto-scroll to the newest message on mount and whenever children change. Defaults to `true`. */
+  stickToBottom?: boolean
+  class?: string
+}
+
+/**
+ * Scrollable, centered reading column that stacks chat messages. Layout-only:
+ * it renders whatever is passed as `children`, so pair it with your own
+ * message bubbles/components.
+ *
+ * @example
+ * ```tsx
+ * <ChatThread maxWidth={640}>
+ *   <div>Hi! Ask me anything about your itinerary.</div>
+ *   <div>What's the weather like in Rivertown this weekend?</div>
+ *   <div>Sunny and mild, 18–22°C, light breeze on Saturday.</div>
+ * </ChatThread>
+ * ```
+ */
+export function ChatThread(props: ChatThreadProps): JSX.Element {
+  let scrollEl: HTMLDivElement | undefined
+
+  const scrollToBottom = () => {
+    if (!scrollEl) return
+    scrollEl.scrollTo({ top: scrollEl.scrollHeight, behavior: motionReduced() ? 'auto' : 'smooth' })
+  }
+
+  onMount(() => {
+    if (props.stickToBottom ?? true) scrollToBottom()
+  })
+
+  createEffect(() => {
+    // Track children so newly appended messages pull the thread down.
+    void props.children
+    if (props.stickToBottom ?? true) queueMicrotask(scrollToBottom)
+  })
+
+  return (
+    <div
+      ref={scrollEl}
+      class={cn('mx-auto flex w-full flex-col gap-4 overflow-y-auto', props.class)}
+      style={{ 'max-width': `${props.maxWidth ?? 768}px` }}
+    >
+      {props.children}
+    </div>
+  )
+}

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/CodeTabs.tsx

@@ -0,0 +1,100 @@
+// Tabbed code blocks with a per-tab copy button, for embedding several code
+// samples/languages (docs, marketing) in a single card. Plain monospace —
+// no syntax highlighting.
+import { Check, Copy } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single tab's content: label, source code, and optional language tag. */
+export interface CodeTab {
+  label: string
+  code: string
+  /** Language tag, e.g. `'tsx'`. Not used for highlighting; informational only. */
+  lang?: string
+}
+
+export interface CodeTabsProps {
+  tabs: CodeTab[]
+  class?: string
+}
+
+const COPIED_TIMEOUT_MS = 1500
+
+/**
+ * Card of tabbed code blocks with a copy button for the active tab, for
+ * showing several code samples or language variants side by side.
+ *
+ * @example
+ * ```tsx
+ * <CodeTabs
+ *   tabs={[
+ *     { label: 'npm', code: 'npm install @a4ui/core' },
+ *     { label: 'pnpm', code: 'pnpm add @a4ui/core' },
+ *   ]}
+ * />
+ * ```
+ */
+export function CodeTabs(props: CodeTabsProps): JSX.Element {
+  const [activeIndex, setActiveIndex] = createSignal(0)
+  const [copied, setCopied] = createSignal(false)
+
+  const active = () => props.tabs[activeIndex()]
+
+  const copy = () => {
+    if (!navigator.clipboard) return
+    navigator.clipboard.writeText(active().code).then(() => {
+      setCopied(true)
+      setTimeout(() => setCopied(false), COPIED_TIMEOUT_MS)
+    })
+  }
+
+  return (
+    <div class={cn('overflow-hidden rounded-lg border border-border bg-card', props.class)}>
+      <div class="flex items-center justify-between border-b border-border pr-2">
+        <div class="flex" role="tablist">
+          <For each={props.tabs}>
+            {(tab, index) => (
+              <button
+                type="button"
+                role="tab"
+                aria-selected={activeIndex() === index()}
+                class={cn(
+                  'border-b-2 px-4 py-2 text-sm font-medium transition-colors',
+                  activeIndex() === index()
+                    ? 'border-foreground text-foreground'
+                    : 'border-transparent text-muted-foreground hover:text-foreground',
+                )}
+                onClick={() => setActiveIndex(index())}
+              >
+                {tab.label}
+              </button>
+            )}
+          </For>
+        </div>
+        <button
+          type="button"
+          class="inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium text-muted-foreground hover:text-foreground"
+          onClick={copy}
+        >
+          <Show
+            when={copied()}
+            fallback={
+              <>
+                <Copy class="h-3.5 w-3.5" />
+                Copy
+              </>
+            }
+          >
+            <Check class="h-3.5 w-3.5" />
+            Copied
+          </Show>
+        </button>
+      </div>
+      <pre class="overflow-x-auto p-4 text-sm font-mono text-foreground">
+        <code>{active().code}</code>
+      </pre>
+    </div>
+  )
+}

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>
+  )
+}