@adea-ai/ui 0.140.0 → 0.142.0

package/src/components/composites/message-scroller/scroll-anchor.ts

@@ -0,0 +1,170 @@
+/**
+ * Keeping the reader's place when content appears above them.
+ *
+ * The browser's own scroll anchoring does this in some engines for some DOM
+ * shapes and not in others (and not at all with `content-visibility`), so it is
+ * done explicitly. What is remembered is where the turns around the viewport sit
+ * in the document (their distance from the top of the content, which scrolling
+ * does not change). After the content moves, the turn the reader is on is found
+ * again and the scroll offset is moved by however far it moved in the document, so
+ * it sits where it did in the viewport.
+ *
+ * Only the *content's* movement is undone, because the reader's scrolling does not
+ * move a turn in the document. A reader who scrolls while a load is open (a wheel
+ * fling or touch momentum that was still running when the load began) keeps the
+ * scroll: nothing is restored to an offset captured earlier.
+ *
+ * It is the turn the reader was on that is measured, found from where the turns sat
+ * when the marks were taken and not from where the change has left them: a row above
+ * the reader that grows far enough to reach into the view has not become the turn they
+ * are reading, and the turn they are reading has moved down by the growth. Nothing
+ * below that turn counts: a row further down that sizes itself late (an
+ * image, highlighted code, a row leaving `content-visibility`) moves rows below the
+ * reader, not the reader. The turns above the reader count, because they are what
+ * an insert or a late resize above pushes the view down by.
+ */
+export type ScrollAnchor = {
+  /** `data-anchor-id` of the first turn in view when the marks were taken, if any turn has one. */
+  id: string | undefined
+  /**
+   * The document position (px from the top of the content) of the turns around the
+   * viewport when the marks were taken, by id: a few above the first one in view, it, and
+   * some below. Empty when no turn carries an id.
+   */
+  marks: Map<string, number>
+  /** The document position of the bottom edge of each marked turn, when the marks were taken. */
+  ends: Map<string, number>
+  /** Fallback when no turn carries an id: the scroll height at the last restore. */
+  scrollHeight: number
+  /** The scroll offset at the last restore. */
+  scrollTop: number
+  /**
+   * When set, only these turns are marked: the ones that were there when the load began.
+   * A turn that has just landed is still at its estimated height, so a correction taken
+   * from it would come from a row about to resize.
+   */
+  known?: ReadonlySet<string>
+}
+
+const ANCHOR_ATTRIBUTE = 'data-anchor-id'
+
+/** Turns marked above the first one in view, and below it. */
+const MARKS_ABOVE = 8
+const MARKS_BELOW = 12
+
+/** The ids of the turns in the scroller now. */
+export function anchorIds(scroller: HTMLElement): Set<string> {
+  const ids = new Set<string>()
+  for (const element of scroller.querySelectorAll<HTMLElement>(`[${ANCHOR_ATTRIBUTE}]`))
+    ids.add(element.getAttribute(ANCHOR_ATTRIBUTE)!)
+  return ids
+}
+
+/** Mark the turns around the viewport: where each sits in the document now. */
+export function captureAnchor(scroller: HTMLElement, known?: ReadonlySet<string>): ScrollAnchor {
+  const box = scroller.getBoundingClientRect()
+  const scrollTop = scroller.scrollTop
+  const marks = new Map<string, number>()
+  const ends = new Map<string, number>()
+  const above: Array<[string, number, number]> = []
+  let id: string | undefined
+  let below = 0
+  for (const element of scroller.querySelectorAll<HTMLElement>(`[${ANCHOR_ATTRIBUTE}]`)) {
+    const turn = element.getAttribute(ANCHOR_ATTRIBUTE)!
+    if (known && !known.has(turn)) continue
+    const rect = element.getBoundingClientRect()
+    const position = rect.top - box.top + scrollTop
+    const end = rect.bottom - box.top + scrollTop
+    if (id === undefined) {
+      if (rect.bottom > box.top) {
+        id = turn
+        for (const [earlier, where, bottom] of above) {
+          marks.set(earlier, where)
+          ends.set(earlier, bottom)
+        }
+        marks.set(turn, position)
+        ends.set(turn, end)
+      } else {
+        above.push([turn, position, end])
+        if (above.length > MARKS_ABOVE) above.shift()
+      }
+    } else {
+      marks.set(turn, position)
+      ends.set(turn, end)
+      below += 1
+      if (below >= MARKS_BELOW) break
+    }
+  }
+  return { id, marks, ends, scrollHeight: scroller.scrollHeight, scrollTop }
+}
+
+/**
+ * The marked turn the reader is on and where it sits in the document now. The turn is
+ * chosen by where the marked turns were (the first one that reached into the view at the
+ * scroll offset now, or the last one if every marked turn was above it), among those still
+ * in the scroller; its position is read from where the content has put it.
+ */
+function turnInView(
+  scroller: HTMLElement,
+  anchor: ScrollAnchor
+): { id: string; position: number } | undefined {
+  const box = scroller.getBoundingClientRect()
+  const scrollTop = scroller.scrollTop
+  const present = new Map<string, number>()
+  for (const element of scroller.querySelectorAll<HTMLElement>(`[${ANCHOR_ATTRIBUTE}]`)) {
+    const id = element.getAttribute(ANCHOR_ATTRIBUTE)!
+    if (anchor.marks.has(id))
+      present.set(id, element.getBoundingClientRect().top - box.top + scrollTop)
+  }
+  let last: { id: string; position: number } | undefined
+  for (const id of anchor.marks.keys()) {
+    const position = present.get(id)
+    if (position === undefined) continue
+    last = { id, position }
+    if ((anchor.ends.get(id) ?? Infinity) > scrollTop) return last
+  }
+  return last
+}
+
+/**
+ * Put the reader back where the content's movement left them. Returns the correction
+ * applied, in px.
+ *
+ * The turn the reader is on is found among the marked turns, and the scroll offset is
+ * moved by how far that turn has moved in the document since the marks were taken: an
+ * insert or a late resize above it moves it, scrolling and growth below it do not.
+ * The marks are then taken again around wherever the reader now is, so a second restore
+ * after the same change finds nothing left to correct, and a reader who has moved on
+ * (before this call, in the same task as a change, or by a scroll event that has not
+ * yet arrived) is measured from the turn they are on and not from one they have left.
+ * Nothing here depends on seeing the scroll event first.
+ */
+export function restoreAnchor(scroller: HTMLElement, anchor: ScrollAnchor | undefined): number {
+  if (!anchor) return 0
+  let correction = 0
+  if (anchor.marks.size > 0) {
+    const turn = turnInView(scroller, anchor)
+    if (turn) correction = turn.position - anchor.marks.get(turn.id)!
+  } else if (anchor.id === undefined) {
+    // No turn carries an id: the growth since the last restore is added to where the
+    // reader is, so a second restore after the same insert (the observer and the settle
+    // both run one) finds it already applied, and growth that lands later moves the
+    // reader only by what is still missing.
+    correction = scroller.scrollHeight - anchor.scrollHeight
+  }
+  if (Math.abs(correction) >= 1) scroller.scrollTop += correction
+  const next = captureAnchor(scroller, anchor.known)
+  if (next.marks.size > 0 || anchor.marks.size === 0) {
+    anchor.id = next.id
+    anchor.marks = next.marks
+    anchor.ends = next.ends
+  } else {
+    // None of the turns that were there before the load is in view (the reader is among
+    // the rows that landed): keep the old marks, moved by what the content did.
+    for (const [id, position] of anchor.marks) anchor.marks.set(id, position + correction)
+    for (const [id, end] of anchor.ends) anchor.ends.set(id, end + correction)
+  }
+  anchor.scrollTop = scroller.scrollTop
+  anchor.scrollHeight = scroller.scrollHeight
+  return correction
+}

package/src/components/composites/model-selector/index.ts

@@ -0,0 +1,14 @@
+export { ModelSelector, type ModelSelectorProps } from './model-selector'
+export {
+  findModel,
+  groupModels,
+  modelSearchValue,
+  MODEL_SEARCH_THRESHOLD,
+  needsSearch,
+  normalizeEfforts,
+  resolveEffort,
+  type EffortOption,
+  type ModelEffort,
+  type ModelGroup,
+  type ModelOption,
+} from './models'

package/src/components/composites/model-selector/model-selector.tsx

@@ -0,0 +1,420 @@
+import { Brain, Check, ChevronsUpDown } from 'lucide-solid'
+import {
+  createEffect,
+  createMemo,
+  createSignal,
+  createUniqueId,
+  For,
+  Show,
+  splitProps,
+} from 'solid-js'
+import { cn } from '#lib/utils'
+import { Button } from '../../ui/button'
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '../../ui/command'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from '../../ui/dropdown-menu'
+import { Popover, PopoverContent, PopoverTrigger } from '../../ui/popover'
+import { boundText } from '../sources/source'
+import {
+  findModel,
+  groupModels,
+  modelSearchValue,
+  needsSearch,
+  normalizeEfforts,
+  resolveEffort,
+  type ModelOption,
+} from './models'
+
+/**
+ * ModelSelector.
+ *
+ * Two controls in one group beside the composer: *which model*, and *how hard it
+ * thinks*. They are one component because the second depends on the first — an
+ * effort level belongs to a model, and switching model can make the chosen effort
+ * meaningless — so a host should not have to keep two menus consistent by hand.
+ *
+ * ## What it takes and what it will not decide
+ *
+ * `models` carries each option's provider, optional description and optional
+ * `disabledReason`; `value` and `effort` are the current choice; `onChange` and
+ * `onEffortChange` report a new one. The component holds no selection of its own
+ * (the host may veto, persist or reset it) and never decides what is allowed:
+ *
+ * - **An unavailable model stays in the list**, disabled, with the host's reason
+ *   beside it in words. Hiding it would leave the person guessing where it went.
+ * - **No `onChange`, no menu.** The model is then plain text — a read-only
+ *   statement of what is running — not a button that does nothing. The same holds
+ *   for effort and `onEffortChange`.
+ * - **Effort renders only when the selected model advertises `efforts`.** A model
+ *   that does not has no effort control, and a stored `effort` the model does not
+ *   offer is shown as unset rather than as a level the model never had.
+ * - **A `value` that is not in the list is shown as given**, not swapped for a
+ *   model the person did not choose.
+ * - `disabledReason` disables both and says why under the group.
+ *
+ * ## Short list or long
+ *
+ * Up to `searchThreshold` models (7) the model picker is a `DropdownMenu` with
+ * radio rows grouped by provider: arrows, typeahead and Escape come from the menu
+ * contract. Beyond it the list is a `Popover` holding a `Command` palette with a
+ * search box, because scanning thirty rows is slower than typing four letters.
+ * Both close on choice and return focus to the trigger. Triggers use
+ * `aria-disabled` so a blocked control is still reachable and its reason read.
+ */
+export type ModelSelectorProps = {
+  models: readonly ModelOption[]
+  /** The selected model's id. */
+  value?: string
+  /** The selected effort's id. */
+  effort?: string
+  onChange?: (id: string) => void
+  onEffortChange?: (effort: string) => void
+  /** Show a search box above this many models. Default 7. */
+  searchThreshold?: number
+  /** Why neither control can be used right now. */
+  disabledReason?: string
+  /** The group's accessible name. */
+  label?: string
+  class?: string
+}
+
+export function ModelSelector(props: ModelSelectorProps) {
+  const [local] = splitProps(props, [
+    'models',
+    'value',
+    'effort',
+    'onChange',
+    'onEffortChange',
+    'searchThreshold',
+    'disabledReason',
+    'label',
+    'class',
+  ])
+  const blocked = () => local.disabledReason !== undefined
+  const selected = () => findModel(local.models, local.value)
+  const efforts = createMemo(() => normalizeEfforts(selected()?.efforts))
+  const effortChoice = () => resolveEffort(selected(), local.effort)
+  const reason = () => (local.disabledReason ? boundText(local.disabledReason, 240) : undefined)
+  const reasonId = `${createUniqueId()}-reason`
+  const describedBy = () => (reason() ? reasonId : undefined)
+
+  return (
+    <div data-slot="model-selector" class={cn('flex min-w-0 flex-col gap-1', local.class)}>
+      <div
+        role="group"
+        aria-label={local.label ?? 'Model and thinking effort'}
+        class="flex min-w-0 items-center gap-1"
+      >
+        <Show
+          when={local.onChange}
+          fallback={
+            <Show when={local.value}>
+              <span class="truncate px-2 text-sm text-muted-foreground">
+                <span class="visually-hidden">Model: </span>
+                {triggerText({ selected: selected(), value: local.value })}
+              </span>
+            </Show>
+          }
+        >
+          <Show
+            when={needsSearch(local.models.length, local.searchThreshold)}
+            fallback={
+              <ModelMenu
+                models={local.models}
+                selected={selected()}
+                value={local.value}
+                blocked={blocked()}
+                describedBy={describedBy()}
+                onChange={(id) => local.onChange?.(id)}
+              />
+            }
+          >
+            <ModelSearch
+              models={local.models}
+              selected={selected()}
+              value={local.value}
+              blocked={blocked()}
+              describedBy={describedBy()}
+              onChange={(id) => local.onChange?.(id)}
+            />
+          </Show>
+        </Show>
+        <Show when={efforts().length > 0}>
+          <Show
+            when={local.onEffortChange}
+            fallback={
+              <Show when={effortChoice()}>
+                {(choice) => (
+                  <span class="flex items-center gap-1 truncate px-2 text-sm text-muted-foreground">
+                    <Brain aria-hidden="true" class="size-3.5 shrink-0" />
+                    <span class="visually-hidden">Thinking effort: </span>
+                    {choice().label}
+                  </span>
+                )}
+              </Show>
+            }
+          >
+            <EffortMenu
+              efforts={efforts()}
+              value={effortChoice()?.id}
+              blocked={blocked()}
+              describedBy={describedBy()}
+              onChange={(id) => local.onEffortChange?.(id)}
+            />
+          </Show>
+        </Show>
+      </div>
+      <Show when={reason()}>
+        <p id={reasonId} role="status" class="m-0 text-xs text-muted-foreground">
+          {reason()}
+        </p>
+      </Show>
+    </div>
+  )
+}
+
+function triggerText(props: { selected?: ModelOption; value?: string }): string {
+  if (props.selected) return boundText(props.selected.label, 60)
+  return props.value ? boundText(props.value, 60) : 'Choose a model'
+}
+
+function ModelOptionBody(props: { model: ModelOption }) {
+  return (
+    <span class="flex min-w-0 flex-col">
+      <span class="[overflow-wrap:anywhere]">{boundText(props.model.label, 60)}</span>
+      <Show when={props.model.description}>
+        <span class="text-xs text-muted-foreground [overflow-wrap:anywhere]">
+          {boundText(props.model.description ?? '', 160)}
+        </span>
+      </Show>
+      <Show when={props.model.disabledReason}>
+        <span class="text-xs text-muted-foreground [overflow-wrap:anywhere]">
+          <span class="visually-hidden">Unavailable: </span>
+          {boundText(props.model.disabledReason ?? '', 160)}
+        </span>
+      </Show>
+    </span>
+  )
+}
+
+type PickerProps = {
+  models: readonly ModelOption[]
+  selected?: ModelOption
+  value?: string
+  blocked: boolean
+  describedBy?: string
+  onChange: (id: string) => void
+}
+
+function ModelTrigger(props: { selected?: ModelOption; value?: string; empty: boolean }) {
+  return (
+    <>
+      <span class="max-w-48 truncate">
+        {props.empty ? 'No models available' : triggerText(props)}
+      </span>
+      <ChevronsUpDown aria-hidden="true" />
+    </>
+  )
+}
+
+function ModelMenu(props: PickerProps) {
+  const [open, setOpen] = createSignal(false)
+  const groups = createMemo(() => groupModels(props.models))
+  const inert = () => props.blocked || props.models.length === 0
+
+  createEffect(() => {
+    if (inert()) setOpen(false)
+  })
+
+  return (
+    <DropdownMenu
+      open={open()}
+      onOpenChange={(next) => setOpen(next && !inert())}
+      placement="top-start"
+      gutter={6}
+    >
+      <DropdownMenuTrigger
+        as={Button}
+        variant="ghost"
+        size="sm"
+        aria-label={`Model: ${props.models.length === 0 ? 'none available' : triggerText(props)}`}
+        aria-disabled={inert() || undefined}
+        aria-describedby={props.describedBy}
+      >
+        <ModelTrigger
+          selected={props.selected}
+          value={props.value}
+          empty={props.models.length === 0}
+        />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent hideArrow class="w-72 max-w-full">
+        <DropdownMenuRadioGroup
+          value={props.value ?? ''}
+          onChange={(id: unknown) => {
+            // Disabled rows cannot be activated, but the guard is the contract.
+            const model = typeof id === 'string' ? findModel(props.models, id) : undefined
+            if (!props.blocked && model && model.disabledReason === undefined) {
+              props.onChange(model.id)
+            }
+          }}
+        >
+          <For each={groups()}>
+            {(group) => (
+              <DropdownMenuGroup>
+                <DropdownMenuLabel>{group.provider}</DropdownMenuLabel>
+                <For each={group.models}>
+                  {(model) => (
+                    <DropdownMenuRadioItem
+                      value={model.id}
+                      disabled={inert() || model.disabledReason !== undefined}
+                    >
+                      <ModelOptionBody model={model} />
+                    </DropdownMenuRadioItem>
+                  )}
+                </For>
+              </DropdownMenuGroup>
+            )}
+          </For>
+        </DropdownMenuRadioGroup>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+function ModelSearch(props: PickerProps) {
+  const [open, setOpen] = createSignal(false)
+  const groups = createMemo(() => groupModels(props.models))
+
+  createEffect(() => {
+    if (props.blocked) setOpen(false)
+  })
+
+  return (
+    <Popover
+      open={open()}
+      onOpenChange={(next) => setOpen(next && !props.blocked)}
+      placement="top-start"
+      gutter={6}
+    >
+      <PopoverTrigger
+        as={Button}
+        variant="ghost"
+        size="sm"
+        aria-label={`Model: ${triggerText(props)}`}
+        aria-disabled={props.blocked || undefined}
+        aria-describedby={props.describedBy}
+      >
+        <ModelTrigger selected={props.selected} value={props.value} empty={false} />
+      </PopoverTrigger>
+      <PopoverContent class="w-80 max-w-full">
+        <Command label="Choose a model">
+          <CommandInput placeholder="Search models" />
+          <CommandList>
+            <CommandEmpty>No model matches.</CommandEmpty>
+            <For each={groups()}>
+              {(group) => (
+                <CommandGroup heading={group.provider}>
+                  <For each={group.models}>
+                    {(model) => (
+                      <CommandItem
+                        value={modelSearchValue(model)}
+                        disabled={props.blocked || model.disabledReason !== undefined}
+                        onSelect={() => {
+                          if (props.blocked || model.disabledReason !== undefined) return
+                          props.onChange(model.id)
+                          setOpen(false)
+                        }}
+                      >
+                        <ModelOptionBody model={model} />
+                        <Show when={model.id === props.value}>
+                          <Check aria-hidden="true" class="ms-auto text-primary" />
+                          <span class="visually-hidden">Current model</span>
+                        </Show>
+                      </CommandItem>
+                    )}
+                  </For>
+                </CommandGroup>
+              )}
+            </For>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+function EffortMenu(props: {
+  efforts: ReturnType<typeof normalizeEfforts>
+  value?: string
+  blocked: boolean
+  describedBy?: string
+  onChange: (id: string) => void
+}) {
+  const [open, setOpen] = createSignal(false)
+  const label = () => props.efforts.find((effort) => effort.id === props.value)?.label
+
+  createEffect(() => {
+    if (props.blocked) setOpen(false)
+  })
+
+  return (
+    <DropdownMenu
+      open={open()}
+      onOpenChange={(next) => setOpen(next && !props.blocked)}
+      placement="top-start"
+      gutter={6}
+    >
+      <DropdownMenuTrigger
+        as={Button}
+        variant="ghost"
+        size="sm"
+        aria-label={`Thinking effort: ${label() ?? 'not set'}`}
+        aria-disabled={props.blocked || undefined}
+        aria-describedby={props.describedBy}
+      >
+        <Brain aria-hidden="true" />
+        <span aria-hidden="true">{label() ?? 'Effort'}</span>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent hideArrow class="w-56 max-w-full">
+        <DropdownMenuRadioGroup
+          value={props.value ?? ''}
+          onChange={(id: unknown) => {
+            if (!props.blocked && typeof id === 'string') props.onChange(id)
+          }}
+        >
+          <DropdownMenuGroup>
+            <DropdownMenuLabel>Thinking effort</DropdownMenuLabel>
+            <For each={props.efforts}>
+              {(effort) => (
+                <DropdownMenuRadioItem value={effort.id} disabled={props.blocked}>
+                  <span class="flex min-w-0 flex-col">
+                    <span>{effort.label}</span>
+                    <Show when={effort.description}>
+                      <span class="text-xs text-muted-foreground [overflow-wrap:anywhere]">
+                        {effort.description}
+                      </span>
+                    </Show>
+                  </span>
+                </DropdownMenuRadioItem>
+              )}
+            </For>
+          </DropdownMenuGroup>
+        </DropdownMenuRadioGroup>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}