@adea-ai/ui 0.140.0 → 0.142.0

package/dist/r/src/components/composites/inline-citation/inline-citation.tsx

@@ -0,0 +1,285 @@
+import { ChevronLeft, ChevronRight } from 'lucide-solid'
+import { createSignal, onCleanup, Show, splitProps } from 'solid-js'
+import { cn } from '../../../lib/utils'
+import { ActionButton } from '../action-button'
+import { Button } from '../../ui/button'
+import type { MessageCitations } from '../../ui/message'
+import { Popover, PopoverContent, PopoverTitle, PopoverTrigger } from '../../ui/popover'
+import { TextLink } from '../../ui/text-link'
+import {
+  SOURCE_SNIPPET_LIMIT,
+  boundText,
+  safeSourceUrl,
+  sourceHost,
+  sourceTitle,
+  type Source,
+} from '../sources/source'
+import {
+  citationLabel,
+  citationName,
+  nextCitationMode,
+  wrapIndex,
+  type CitationEvent,
+  type CitationMode,
+} from './citation'
+
+/**
+ * InlineCitation.
+ *
+ * A small badge inside a sentence — "1", or a host — that opens the source(s)
+ * behind the claim: title, host, address, snippet, and Previous/Next when several
+ * sources share one marker. It is an inline element for prose such as
+ * `MessageText`: it never breaks across lines, stays on the text baseline, and
+ * adds no block of its own. For the list of everything a reply used, reach for
+ * `Sources`; the two number sources the same way.
+ *
+ * ## One popover, two ways to open it
+ *
+ * A hover card would exclude everyone who is not holding a mouse, so this is a
+ * `Popover` that a pointer can also *peek* at:
+ *
+ * - **Hover or keyboard focus peeks.** The popover opens without taking focus
+ *   and closes when the pointer or focus leaves. Touch has no hover, so a touch
+ *   never peeks.
+ * - **Click, tap, Enter or Space pins.** Focus moves into the popover so its
+ *   link and Previous/Next are reachable; it stays until Escape, an outside press,
+ *   or the badge is pressed again, and focus returns to the badge. Pressing a badge
+ *   that is only peeking pins it rather than toggling it shut — the transitions
+ *   are the pure `nextCitationMode`.
+ *
+ * Kobalte's trigger toggles on every press, so `open` is controlled and its own
+ * close request is ignored for the press that we already decided (`pressing`).
+ * Without that, hover-then-click, the commonest pointer path, would close the card.
+ *
+ * ## It makes no claim without sources
+ *
+ * No sources renders nothing: a marker that points nowhere is not a citation.
+ * The address is a link only when `safeSourceUrl` allows it; the host comes from
+ * the parsed URL; titles and snippets are clipped, cleaned of direction
+ * overrides and rendered as text. The badge's accessible name carries the title
+ * and host (the visible label is only a number or a host), so a reader hears
+ * what is cited without opening anything.
+ */
+export type InlineCitationProps = {
+  /** One source, or several that support the same claim. */
+  sources: readonly Source[]
+  /**
+   * The 1-based number to show, matching the source's position in `Sources`.
+   * Omit it to show the host instead; a number is never guessed.
+   */
+  index?: number
+  /** Milliseconds a pointer rests before the peek opens. */
+  hoverDelay?: number
+  class?: string
+}
+
+const LEAVE_DELAY = 200
+
+export function InlineCitation(props: InlineCitationProps) {
+  const [local] = splitProps(props, ['sources', 'index', 'hoverDelay', 'class'])
+  const [mode, setMode] = createSignal<CitationMode>('closed')
+  const [position, setPosition] = createSignal(0)
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let content: HTMLElement | undefined
+  let pressing = false
+  // Focus handed back to the badge as the popover closes is not a request to
+  // peek again; without this, Escape from a pinned card reopens it as a preview.
+  let restoringFocus = false
+
+  const count = () => local.sources.length
+  const active = () => local.sources[wrapIndex(position(), count())]
+  const clear = () => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = undefined
+  }
+  onCleanup(clear)
+
+  const dispatch = (event: CitationEvent) => setMode((current) => nextCitationMode(current, event))
+  const schedule = (event: CitationEvent, delay: number) => {
+    clear()
+    timer = setTimeout(() => dispatch(event), delay)
+  }
+
+  const onPointerEnter = (event: PointerEvent) => {
+    if (event.pointerType === 'touch') return
+    schedule('enter', local.hoverDelay ?? 150)
+  }
+  const onPointerLeave = (event: PointerEvent) => {
+    if (event.pointerType === 'touch') return
+    schedule('leave', LEAVE_DELAY)
+  }
+
+  const onClick = () => {
+    clear()
+    const wasPeeking = mode() === 'peek'
+    dispatch('press')
+    // Kobalte toggles right after this handler; its request is not a dismissal.
+    pressing = true
+    queueMicrotask(() => {
+      pressing = false
+    })
+    // The peek never took focus; a deliberate press must hand it over.
+    if (wasPeeking) queueMicrotask(() => content?.focus())
+  }
+
+  return (
+    <Show when={count() > 0}>
+      <Popover
+        open={mode() !== 'closed'}
+        onOpenChange={(next) => {
+          if (!next && !pressing) dispatch('dismiss')
+        }}
+        placement="bottom"
+        gutter={6}
+      >
+        <PopoverTrigger
+          as={Button}
+          variant="subtle"
+          size="2xs"
+          touchTarget="comfortable"
+          data-slot="inline-citation"
+          aria-label={citationName(local.sources, local.index)}
+          class={cn('mx-0.5 align-baseline tabular-nums', local.class)}
+          onClick={onClick}
+          onPointerEnter={onPointerEnter}
+          onPointerLeave={onPointerLeave}
+          onFocus={(event: FocusEvent & { currentTarget: HTMLElement }) => {
+            // Mouse focus follows the press; only keyboard focus peeks.
+            if (restoringFocus) return
+            if (event.currentTarget.matches(':focus-visible')) dispatch('focus')
+          }}
+          onBlur={() => dispatch('blur')}
+        >
+          <span aria-hidden="true" class="max-w-32 truncate">
+            {citationLabel(local.index, local.sources[0])}
+          </span>
+          <Show when={count() > 1}>
+            <span aria-hidden="true">+{count() - 1}</span>
+          </Show>
+        </PopoverTrigger>
+        <PopoverContent
+          ref={(element: HTMLElement) => (content = element)}
+          class="w-72 max-w-full"
+          onOpenAutoFocus={(event: Event) => {
+            if (mode() === 'peek') event.preventDefault()
+          }}
+          onCloseAutoFocus={() => {
+            // The focus move that follows is synchronous; the microtask ends the window.
+            restoringFocus = true
+            queueMicrotask(() => {
+              restoringFocus = false
+            })
+          }}
+          onPointerEnter={(event: PointerEvent) => {
+            if (event.pointerType !== 'touch') clear()
+          }}
+          onPointerLeave={onPointerLeave}
+        >
+          <Show when={active()}>
+            {(source) => (
+              <div class="flex min-w-0 flex-col gap-1.5 px-2 py-1.5">
+                <Show when={count() > 1}>
+                  <div class="flex items-center justify-between gap-2">
+                    <span
+                      role="status"
+                      aria-live="polite"
+                      class="text-xs text-muted-foreground tabular-nums"
+                    >
+                      Source {wrapIndex(position(), count()) + 1} of {count()}
+                    </span>
+                    <span class="flex items-center gap-0.5">
+                      <ActionButton
+                        variant="ghost"
+                        size="icon-xs"
+                        aria-label="Previous source"
+                        tooltip="Previous source"
+                        onClick={() => setPosition((value) => wrapIndex(value - 1, count()))}
+                      >
+                        <ChevronLeft />
+                      </ActionButton>
+                      <ActionButton
+                        variant="ghost"
+                        size="icon-xs"
+                        aria-label="Next source"
+                        tooltip="Next source"
+                        onClick={() => setPosition((value) => wrapIndex(value + 1, count()))}
+                      >
+                        <ChevronRight />
+                      </ActionButton>
+                    </span>
+                  </div>
+                </Show>
+                <PopoverTitle class="p-0 [overflow-wrap:anywhere]">
+                  {sourceTitle(source())}
+                </PopoverTitle>
+                <CitationDetails source={source()} />
+              </div>
+            )}
+          </Show>
+        </PopoverContent>
+      </Popover>
+    </Show>
+  )
+}
+
+/**
+ * Citation markers for `MessageText`, from the sources a reply really used.
+ *
+ * `[^2]` in the text becomes the second source's badge; `[^1,3]` one badge for
+ * sources 1 and 3. A number beyond the list leaves the marker as written, and an
+ * empty list makes every marker literal, so text can never cite a source the host
+ * did not supply.
+ *
+ *     <MessageText text={reply} citations={messageCitations(sources)} />
+ */
+export function messageCitations(sources: readonly Source[]): MessageCitations {
+  return {
+    count: sources.length,
+    render: (numbers) => (
+      <InlineCitation
+        index={numbers[0]}
+        sources={numbers.flatMap((number) => {
+          const source = sources[number - 1]
+          return source ? [source] : []
+        })}
+      />
+    ),
+  }
+}
+
+function CitationDetails(props: { source: Source }) {
+  const href = () => safeSourceUrl(props.source.url)
+  const host = () => sourceHost(props.source.url)
+  const snippet = () =>
+    props.source.snippet ? boundText(props.source.snippet, SOURCE_SNIPPET_LIMIT) : ''
+  const withheld = () => props.source.url !== undefined && props.source.url !== '' && !href()
+
+  return (
+    <>
+      <Show when={host()}>
+        <p class="m-0 text-xs text-muted-foreground [overflow-wrap:anywhere]">{host()}</p>
+      </Show>
+      <Show when={href()}>
+        {(url) => (
+          <TextLink
+            href={url()}
+            target="_blank"
+            rel="noreferrer noopener"
+            class="w-fit max-w-full text-xs [overflow-wrap:anywhere]"
+          >
+            {boundText(url(), 96)}
+            <span class="visually-hidden"> (opens in a new tab)</span>
+          </TextLink>
+        )}
+      </Show>
+      <Show when={withheld()}>
+        <p class="m-0 text-xs text-muted-foreground">Address not linked</p>
+      </Show>
+      <Show when={snippet()}>
+        <p class="m-0 line-clamp-6 text-xs text-muted-foreground [overflow-wrap:anywhere]">
+          {snippet()}
+        </p>
+      </Show>
+    </>
+  )
+}

package/dist/r/src/components/composites/message-scroller/index.ts

@@ -0,0 +1,2 @@
+export { MessageScroller, type MessageScrollerProps } from './message-scroller'
+export { captureAnchor, restoreAnchor, type ScrollAnchor } from './scroll-anchor'

package/dist/r/src/components/composites/message-scroller/message-scroller.tsx

@@ -0,0 +1,301 @@
+import { History, LoaderCircle } from 'lucide-solid'
+import { createEffect, onCleanup, Show, splitProps, createSignal, type JSX } from 'solid-js'
+import { cn } from '../../../lib/utils'
+import { Button } from '../../ui/button'
+import {
+  ConversationSurface,
+  type ConversationSurfaceProps,
+} from '../../conversation/conversation-surface'
+import { anchorIds, captureAnchor, restoreAnchor, type ScrollAnchor } from './scroll-anchor'
+
+/**
+ * MessageScroller.
+ *
+ * The thread. It owns the three scroll behaviours a chat gets wrong when each
+ * is bolted on separately, and keeps them from fighting:
+ *
+ * 1. **Follow the reply only while the reader is at the bottom.** New and
+ *    streaming content scrolls into view when the reader is already at the end,
+ *    and never otherwise. Scrolling up parks the view; the "Jump to latest"
+ *    control brings it back. (This is `ConversationSurface`'s follow contract,
+ *    which this component wraps rather than reimplements.)
+ * 2. **Load history without moving what the reader is looking at.** When the
+ *    reader reaches the top, `onLoadOlder` is asked for earlier turns. Turns
+ *    inserted *above* the viewport would normally push the visible content down
+ *    by exactly their height; here the first visible turn (found by
+ *    `data-anchor-id`, which `Message` sets from `anchorId`) is measured before
+ *    the load and put back to the same offset after it, on every layout change
+ *    until the load settles — so images and code blocks that size themselves
+ *    late do not jolt the view either. A "Load earlier" button is always present
+ *    while there is more, because the scroll trigger alone is unreachable to a
+ *    keyboard or switch user and fires nothing in a short pane.
+ * 3. **Announce without flooding.** The scroller is a polite log, and a turn that
+ *    is still arriving marks itself `aria-busy`, so a screen reader waits for the
+ *    settled turn instead of reading every token. `announcement` is a separate
+ *    status region for the two moments that matter: a response starting and a
+ *    response finishing.
+ *
+ * What it does not own: which turns exist, their identity, or what "older"
+ * means. The host passes children and a loader; a session switch is
+ * `resetKey`, which re-arms follow and discards any in-flight anchor.
+ */
+export type MessageScrollerProps = Omit<ConversationSurfaceProps, 'header' | 'empty'> & {
+  /** There are earlier turns the host can load. */
+  hasOlder?: boolean
+  /** The host is loading earlier turns right now. */
+  loadingOlder?: boolean
+  /**
+   * Load earlier turns. The scroller preserves the reader's position across the
+   * resulting insert whether the host resolves before or after rendering them.
+   */
+  onLoadOlder?: () => void | Promise<void>
+  /** Words for the loader row; override for another language. */
+  olderLabel?: string
+  loadingOlderLabel?: string
+  /** Rendered above the first turn, below the history control. */
+  header?: JSX.Element
+  /** Rendered when there are no turns. */
+  empty?: JSX.Element
+  /** A short sentence for the live status region ("Assistant is responding"). */
+  announcement?: string
+}
+
+/** How far from the top counts as "reached the top", in px. */
+const TOP_MARGIN = 160
+
+/** How long a host that still reports `loadingOlder` is waited for, in frames (~10 s). */
+const MAX_HOST_WAIT_FRAMES = 600
+
+export function MessageScroller(props: MessageScrollerProps) {
+  const [local, rest] = splitProps(props, [
+    'class',
+    'hasOlder',
+    'loadingOlder',
+    'onLoadOlder',
+    'olderLabel',
+    'loadingOlderLabel',
+    'header',
+    'empty',
+    'announcement',
+    'ref',
+    'resetKey',
+    'children',
+  ])
+  let scroller: HTMLDivElement | undefined
+  let holdFollow: (() => () => void) | undefined
+  let epoch = 0
+  const [inFlight, setInFlight] = createSignal(false)
+
+  // While a load holds the reader's place, the browser's own scroll anchoring is
+  // switched off: it moves the offset by the same insert, and the two corrections
+  // would be added together.
+  let nativeAnchoring: string | undefined
+  const holdNativeAnchoring = () => {
+    if (!scroller || nativeAnchoring !== undefined) return
+    nativeAnchoring = scroller.style.overflowAnchor
+    scroller.style.overflowAnchor = 'none'
+  }
+  const releaseNativeAnchoring = () => {
+    if (scroller && nativeAnchoring !== undefined) scroller.style.overflowAnchor = nativeAnchoring
+    nativeAnchoring = undefined
+  }
+
+  // A session switch invalidates a load that was started for the previous one.
+  createEffect(() => {
+    void local.resetKey
+    epoch += 1
+    setInFlight(false)
+    stopWatching()
+    releaseNativeAnchoring()
+  })
+
+  const settle = (
+    anchor: ScrollAnchor | undefined,
+    run: number,
+    heightBefore: number,
+    restoreFocus: boolean,
+    releaseHold?: () => void
+  ) => {
+    const finish = () => {
+      if (run !== epoch) return releaseHold?.()
+      if (scroller) restoreAnchor(scroller, anchor)
+      stopWatching()
+      releaseNativeAnchoring()
+      setInFlight(false)
+      // The control that started the load was replaced by the loading line, which
+      // takes focus with it. Put it back on the control (or the thread), so a
+      // keyboard user is not dropped onto the page.
+      if (restoreFocus && scroller && document.activeElement === document.body) {
+        const again = scroller.querySelector<HTMLElement>(
+          '[data-slot="message-scroller-older"] button'
+        )
+        ;(again ?? scroller).focus({ preventScroll: true })
+      }
+      // Still at the top after a load that added content: keep going, so a
+      // pane taller than one page of history fills without a second scroll.
+      if (
+        scroller &&
+        local.hasOlder &&
+        scroller.scrollTop < TOP_MARGIN &&
+        scroller.scrollHeight > heightBefore
+      )
+        void load()
+      releaseHold?.()
+    }
+    // Two frames: the first lets the host's insert commit, the second lets
+    // late-sizing content (images, highlighted code) report its height. A host
+    // that says it is still loading (`loadingOlder`) after its promise resolved
+    // is not finished either: its turns will land later, and the anchor must
+    // still be held when they do.
+    const wait = (waited: number) =>
+      requestAnimationFrame(() => {
+        if (run !== epoch) return releaseHold?.()
+        if (local.loadingOlder && waited < MAX_HOST_WAIT_FRAMES) return void wait(waited + 1)
+        finish()
+      })
+    requestAnimationFrame(() => wait(0))
+  }
+
+  let observer: MutationObserver | undefined
+  let resizer: ResizeObserver | undefined
+  let unfollow: (() => void) | undefined
+  const stopWatching = () => {
+    observer?.disconnect()
+    resizer?.disconnect()
+    unfollow?.()
+    unfollow = undefined
+  }
+  const load = async (fromControl = false) => {
+    if (!scroller || !local.onLoadOlder || !local.hasOlder || local.loadingOlder || inFlight())
+      return
+    const run = epoch
+    const anchor = captureAnchor(scroller)
+    anchor.known = anchorIds(scroller)
+    const heightBefore = scroller.scrollHeight
+    const restoreFocus =
+      fromControl && document.activeElement?.closest('[data-slot="message-scroller-older"]') != null
+    setInFlight(true)
+    holdNativeAnchoring()
+    // Every layout change while the load is open re-pins the anchor *before
+    // paint*, which is what makes the insert invisible.
+    stopWatching()
+    observer = new MutationObserver(() => {
+      if (run === epoch && scroller) restoreAnchor(scroller, anchor)
+    })
+    observer.observe(scroller, { childList: true, subtree: true })
+    // Turns that size themselves late (`content-visibility`, images, highlighted code)
+    // move the anchor without adding or removing a node, and with the browser's own
+    // anchoring held off nothing else would carry the reader through that.
+    const content = scroller.querySelector('[data-slot="conversation-content"]')
+    if (content && typeof ResizeObserver !== 'undefined') {
+      resizer = new ResizeObserver(() => {
+        if (run === epoch && scroller) restoreAnchor(scroller, anchor)
+      })
+      resizer.observe(content)
+    }
+    // The reader may carry on scrolling while the host answers. A restore re-takes the
+    // anchor on the turn they have come to, whichever of the observers or this event
+    // reaches it first.
+    const follow = () => {
+      if (run === epoch && scroller) restoreAnchor(scroller, anchor)
+    }
+    scroller.addEventListener('scroll', follow, { passive: true })
+    const watched = scroller
+    unfollow = () => watched.removeEventListener('scroll', follow)
+    try {
+      await local.onLoadOlder()
+    } catch {
+      // The host reports its own failure; the control stays so the reader can retry.
+    }
+    // A load that outlived its conversation inserts into a thread whose reader it knows
+    // nothing about, and the anchor it held is gone. What it does to the layout (rows
+    // taking their height, a clamp, the insert itself) is not the reader scrolling, so the
+    // follow position is held until the two frames the insert needs have passed.
+    settle(anchor, run, heightBefore, restoreFocus, run !== epoch ? holdFollow?.() : undefined)
+  }
+
+  onCleanup(() => {
+    epoch += 1
+    stopWatching()
+    releaseNativeAnchoring()
+  })
+
+  const watchTop = (element: HTMLDivElement) => {
+    if (typeof IntersectionObserver === 'undefined') return
+    const io = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) void load()
+      },
+      { root: scroller ?? null, rootMargin: `${TOP_MARGIN}px 0px 0px 0px` }
+    )
+    io.observe(element)
+    onCleanup(() => io.disconnect())
+  }
+
+  return (
+    <div
+      class={cn('relative flex min-h-0 flex-1 flex-col', local.class)}
+      data-slot="message-scroller"
+    >
+      <ConversationSurface
+        role="log"
+        aria-live="polite"
+        aria-relevant="additions"
+        resetKey={local.resetKey}
+        onFollowHold={(hold) => {
+          holdFollow = hold
+        }}
+        {...rest}
+        ref={(element) => {
+          scroller = element
+          if (typeof local.ref === 'function') local.ref(element)
+        }}
+        class="flex-1"
+        header={
+          <>
+            <Show when={local.hasOlder || local.loadingOlder}>
+              <div
+                ref={watchTop}
+                data-slot="message-scroller-older"
+                class="flex justify-center py-2"
+              >
+                <Show
+                  when={local.loadingOlder || inFlight()}
+                  fallback={
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      class="gap-1.5 text-muted-foreground"
+                      onClick={() => void load(true)}
+                    >
+                      <History aria-hidden="true" />
+                      {local.olderLabel ?? 'Load earlier messages'}
+                    </Button>
+                  }
+                >
+                  <p
+                    role="status"
+                    // The button's own height: swapping one for the other must not move
+                    // the turns below it by even a pixel while the anchor is being held.
+                    class="flex h-control-sm items-center gap-1.5 text-xs text-muted-foreground"
+                  >
+                    <LoaderCircle aria-hidden="true" class="size-3.5 motion-safe:animate-spin" />
+                    {local.loadingOlderLabel ?? 'Loading earlier messages…'}
+                  </p>
+                </Show>
+              </div>
+            </Show>
+            {local.header}
+          </>
+        }
+        empty={local.empty}
+      >
+        {local.children}
+      </ConversationSurface>
+      <p role="status" class="sr-only">
+        {local.announcement}
+      </p>
+    </div>
+  )
+}