@adea-ai/ui 0.85.0 → 0.88.0

package/src/components/conversation/scroll-follow.ts

@@ -28,6 +28,7 @@ const geometry = (element: HTMLDivElement) => ({
   scrollHeight: element.scrollHeight,
   clientHeight: element.clientHeight,
 })
+const noop = () => {}
 
 /** Internal plain-scroller binding; host-owned restoration can disable follow. */
 export function createScrollFollow(options: {
@@ -45,6 +46,9 @@ export function createScrollFollow(options: {
   let lastWriteClientHeight = -1
   let previousTop = -1
   let lastScrollClientHeight = 0
+  let pendingRestore: { frame: number; fromTop: number; target: number } | undefined
+  let pendingRestoreUserIntent = false
+  let removeRestoreIntentListeners = noop
   const reportPosition = () => {
     if (scroller)
       untrack(() =>
@@ -60,12 +64,12 @@ export function createScrollFollow(options: {
     // Instant writes keep the self-scroll reference synchronized. A smooth
     // animation would produce intermediate positions that resemble user input.
     element.scrollTop = target
-    lastWriteTop = target
+    lastWriteTop = element.scrollTop
     lastWriteClientHeight = element.clientHeight
-    previousTop = target
+    previousTop = element.scrollTop
   }
   const pinAuto = () => {
-    if (!scroller || !options.enabled()) return
+    if (!scroller || !options.enabled() || pendingRestore) return
     const geom = geometry(scroller)
     const result = evaluateAutoPin({
       stick,
@@ -84,6 +88,26 @@ export function createScrollFollow(options: {
   }
   const onScroll = () => {
     if (!scroller) return
+    if (pendingRestore) {
+      // A reset can clamp the outgoing offset while the incoming rows are
+      // shorter. That notification is layout, not reader intent, and must not
+      // cancel the snapshot waiting for the new rows to commit.
+      const maxTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight)
+      const clampedFromTop = Math.min(pendingRestore.fromTop, maxTop)
+      if (
+        pendingRestore.fromTop - clampedFromTop > 1 &&
+        Math.abs(scroller.scrollTop - clampedFromTop) <= 1
+      )
+        return
+      // An unexplained offset change can also be a browser clamp. Only actual
+      // user scroll intent followed by a non-clamp movement cancels restoration.
+      if (!pendingRestoreUserIntent) return
+      cancelAnimationFrame(pendingRestore.frame)
+      pendingRestore = undefined
+      pendingRestoreUserIntent = false
+      removeRestoreIntentListeners()
+      removeRestoreIntentListeners = noop
+    }
     if (!options.enabled()) {
       reportPosition()
       return
@@ -125,7 +149,21 @@ export function createScrollFollow(options: {
     options.resetKey()
     const enabled = options.enabled()
     // Capture before any reporting callback can replace the host snapshot.
-    const initial = untrack(() => options.initialPosition?.())
+    const candidate = untrack(() => options.initialPosition?.())
+    const initial =
+      candidate && Number.isFinite(candidate.top) && candidate.top >= 0 ? candidate : undefined
+    let scheduledRestore: typeof pendingRestore
+    let observer: ResizeObserver | undefined
+    onCleanup(() => {
+      if (scheduledRestore) {
+        cancelAnimationFrame(scheduledRestore.frame)
+        if (pendingRestore === scheduledRestore) pendingRestore = undefined
+      }
+      pendingRestoreUserIntent = false
+      removeRestoreIntentListeners()
+      removeRestoreIntentListeners = noop
+      observer?.disconnect()
+    })
     stick = true
     lastWriteTop = -1
     lastWriteClientHeight = -1
@@ -135,19 +173,75 @@ export function createScrollFollow(options: {
     if (!enabled || !scroller) return
     // Snapshot updates must not become another positioning owner. Consume the
     // host's snapshot only at entry/reset, then native reader intent owns follow.
-    if (initial && Number.isFinite(initial.top) && initial.top >= 0) {
-      stick = initial.following
-      writePin(scroller, stick ? bottomTarget(geometry(scroller)) : initial.top)
-      previousTop = scroller.scrollTop
-      lastScrollClientHeight = scroller.clientHeight
-    } else writePin(scroller, bottomTarget(geometry(scroller)))
+    if (initial) {
+      stick = enabled && initial.following
+    }
+
+    const observe = () => {
+      if (!enabled || typeof ResizeObserver === 'undefined') return
+      observer = new ResizeObserver(pinAuto)
+      observer.observe(scroller!)
+      if (content) observer.observe(content)
+    }
+
+    const watchRestoreIntent = () => {
+      const element = scroller
+      if (!element) return
+      const markIntent = (event: Event) => {
+        if (!pendingRestore) return
+        if (event.type === 'pointerdown' && event.target !== element) return
+        if (event.type === 'keydown') {
+          if (event.target !== element) return
+          const key = (event as KeyboardEvent).key
+          if (!['ArrowDown', 'ArrowUp', 'PageDown', 'PageUp', 'Home', 'End', ' '].includes(key))
+            return
+        }
+        pendingRestoreUserIntent = true
+      }
+      element.addEventListener('wheel', markIntent, { passive: true })
+      element.addEventListener('pointerdown', markIntent)
+      element.addEventListener('keydown', markIntent)
+      removeRestoreIntentListeners = () => {
+        element.removeEventListener('wheel', markIntent)
+        element.removeEventListener('pointerdown', markIntent)
+        element.removeEventListener('keydown', markIntent)
+      }
+    }
+
+    if (initial && !stick) {
+      // The identity effect can run before Solid has inserted the new rows. A
+      // synchronous write is clamped by the outgoing short transcript, so defer
+      // restoration until the browser has committed the new content and layout.
+      const restore = {
+        frame: 0,
+        fromTop: scroller.scrollTop,
+        target: initial.top,
+      }
+      scheduledRestore = restore
+      pendingRestore = restore
+      pendingRestoreUserIntent = false
+      watchRestoreIntent()
+      // Keep resize observation alive during the pending frame. Its callback is
+      // guarded above, and remains active if user input cancels restoration.
+      observe()
+      restore.frame = requestAnimationFrame(() => {
+        if (pendingRestore !== restore || !scroller) return
+        pendingRestore = undefined
+        pendingRestoreUserIntent = false
+        removeRestoreIntentListeners()
+        removeRestoreIntentListeners = noop
+        writePin(scroller, restore.target)
+        setAtBottom(computeAtBottom(geometry(scroller), options.threshold()))
+        reportPosition()
+      })
+      return
+    }
+
+    if (!initial && enabled) writePin(scroller, bottomTarget(geometry(scroller)))
+    else if (initial && stick) writePin(scroller, bottomTarget(geometry(scroller)))
     setAtBottom(computeAtBottom(geometry(scroller), options.threshold()))
     reportPosition()
-    if (typeof ResizeObserver === 'undefined') return
-    const observer = new ResizeObserver(pinAuto)
-    observer.observe(scroller)
-    if (content) observer.observe(content)
-    onCleanup(() => observer.disconnect())
+    observe()
   })
 
   return {

package/src/components/layout/app-shell/index.ts

@@ -1 +1,2 @@
 export { AppShell, AppShellBody, AppShellContent, AppShellMain } from './app-shell'
+export { SkipLink } from './skip-link'

package/src/components/layout/app-shell/skip-link.tsx

@@ -0,0 +1,35 @@
+import type { ComponentProps } from 'solid-js'
+import { splitProps } from 'solid-js'
+import { cn } from '#lib/utils'
+
+/**
+ * A keyboard-first link to the main content region.
+ *
+ * Place it before the shell's navigation and set the destination element's
+ * `id` to match `href`. The link stays translated above the viewport until it
+ * receives focus, then moves into view. Its text remains available to assistive
+ * technology while it is visually hidden.
+ */
+export function SkipLink(props: ComponentProps<'a'>) {
+  const [local, rest] = splitProps(props, ['class', 'children', 'href', 'tabIndex'])
+
+  return (
+    <a
+      data-slot="skip-link"
+      class={cn(
+        'fixed top-0 start-2 z-(--z-toast) -translate-y-full',
+        'inline-flex items-center rounded-md border border-border bg-background',
+        'px-control-md py-2 text-sm font-medium text-foreground shadow-lg',
+        'underline decoration-2 underline-offset-2 outline-none transition-transform duration-150',
+        'focus:translate-y-0 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-primary-subtle',
+        'motion-reduce:transition-none',
+        local.class
+      )}
+      href={local.href ?? '#main-content'}
+      tabIndex={local.tabIndex ?? 0}
+      {...rest}
+    >
+      {local.children === undefined ? 'Skip to main content' : local.children}
+    </a>
+  )
+}

package/src/components/layout/floating-preview/floating-preview.tsx

@@ -0,0 +1,260 @@
+import { createEffect, createSignal, onCleanup, onMount, on, type JSX } from 'solid-js'
+import { Move, X } from 'lucide-solid'
+import { ActionButton } from '../../composites/action-button'
+import { ScrollArea } from '../../ui/scroll-area'
+import {
+  type FloatingPreviewFrame,
+  type FloatingPreviewResizeDirection,
+  type FloatingPreviewSize,
+  resolveFloatingPreviewFrame,
+  resizeFloatingPreview,
+} from './model'
+
+const directions: readonly {
+  direction: FloatingPreviewResizeDirection
+  class: string
+  glyph: string
+}[] = [
+  {
+    direction: 'north',
+    class: 'absolute -top-3 right-6 left-6 h-control-xs w-auto cursor-ns-resize touch-none',
+    glyph: '↕',
+  },
+  {
+    direction: 'south',
+    class: 'absolute -bottom-3 right-6 left-6 h-control-xs w-auto cursor-ns-resize touch-none',
+    glyph: '↕',
+  },
+  {
+    direction: 'east',
+    class: 'absolute -right-3 top-6 bottom-6 w-6 h-auto cursor-ew-resize touch-none',
+    glyph: '↔',
+  },
+  {
+    direction: 'west',
+    class: 'absolute -left-3 top-6 bottom-6 w-6 h-auto cursor-ew-resize touch-none',
+    glyph: '↔',
+  },
+  {
+    direction: 'northwest',
+    class: 'absolute -top-3 -left-3 size-control-xs cursor-nwse-resize touch-none',
+    glyph: '↖',
+  },
+  {
+    direction: 'northeast',
+    class: 'absolute -top-3 -right-3 size-control-xs cursor-nesw-resize touch-none',
+    glyph: '↗',
+  },
+  {
+    direction: 'southwest',
+    class: 'absolute -bottom-3 -left-3 size-control-xs cursor-nesw-resize touch-none',
+    glyph: '↙',
+  },
+  {
+    direction: 'southeast',
+    class: 'absolute -bottom-3 -right-3 size-control-xs cursor-nwse-resize touch-none',
+    glyph: '↘',
+  },
+]
+
+export type FloatingPreviewProps = {
+  label: string
+  source: FloatingPreviewSize
+  onClose?: () => void
+  actions?: JSX.Element
+  children: JSX.Element
+}
+
+/** A host-bounded movable preview frame. Content and actions remain caller-owned. */
+export function FloatingPreview(props: FloatingPreviewProps) {
+  const [frame, setFrame] = createSignal<FloatingPreviewFrame>({ x: 0, y: 0, width: 1, height: 1 })
+  // oxlint-disable-next-line no-unassigned-vars -- assigned through Solid's ref callback.
+  let bounds: HTMLDivElement | undefined
+  let observer: ResizeObserver | undefined
+  let gesture:
+    | {
+        id: number
+        x: number
+        y: number
+        start: FloatingPreviewFrame
+        direction: FloatingPreviewResizeDirection | null
+      }
+    | undefined
+
+  const measure = () => {
+    const rect = bounds?.getBoundingClientRect()
+    if (!rect) return
+    setFrame((current) =>
+      resolveFloatingPreviewFrame({
+        width: current.width > 1 ? current.width : null,
+        position: current.width > 1 ? { x: current.x, y: current.y } : null,
+        source: props.source,
+        container: { width: rect.width, height: rect.height },
+      })
+    )
+  }
+  createEffect(
+    on(
+      () => [props.source.width, props.source.height] as const,
+      () => measure(),
+      { defer: true }
+    )
+  )
+  onMount(() => {
+    if (bounds) {
+      observer = new ResizeObserver(measure)
+      observer.observe(bounds)
+      measure()
+    }
+  })
+  onCleanup(() => observer?.disconnect())
+
+  function start(event: PointerEvent, direction: FloatingPreviewResizeDirection | null) {
+    if (event.button !== 0 || gesture) return
+    event.preventDefault()
+    event.stopPropagation()
+    gesture = { id: event.pointerId, x: event.clientX, y: event.clientY, start: frame(), direction }
+    ;(event.currentTarget as HTMLElement).setPointerCapture(event.pointerId)
+  }
+  function move(event: PointerEvent) {
+    if (!gesture || gesture.id !== event.pointerId) return
+    const rect = bounds?.getBoundingClientRect()
+    if (!rect) return
+    const container = { width: rect.width, height: rect.height }
+    const delta = { x: event.clientX - gesture.x, y: event.clientY - gesture.y }
+    setFrame(
+      gesture.direction
+        ? resizeFloatingPreview({
+            start: gesture.start,
+            direction: gesture.direction,
+            delta,
+            source: props.source,
+            container,
+          })
+        : resolveFloatingPreviewFrame({
+            width: gesture.start.width,
+            position: { x: gesture.start.x + delta.x, y: gesture.start.y + delta.y },
+            source: props.source,
+            container,
+          })
+    )
+  }
+  function end(event: PointerEvent) {
+    if (gesture?.id === event.pointerId) gesture = undefined
+  }
+  function keyboardMove(event: KeyboardEvent) {
+    const delta = { x: 0, y: 0 }
+    if (event.key === 'ArrowLeft') delta.x = -10
+    else if (event.key === 'ArrowRight') delta.x = 10
+    else if (event.key === 'ArrowUp') delta.y = -10
+    else if (event.key === 'ArrowDown') delta.y = 10
+    else return
+    event.preventDefault()
+    const rect = bounds?.getBoundingClientRect()
+    if (!rect) return
+    const current = frame()
+    setFrame(
+      resolveFloatingPreviewFrame({
+        width: current.width,
+        position: { x: current.x + delta.x, y: current.y + delta.y },
+        source: props.source,
+        container: { width: rect.width, height: rect.height },
+      })
+    )
+  }
+  function keyboardResize(event: KeyboardEvent, direction: FloatingPreviewResizeDirection) {
+    if (!event.key.startsWith('Arrow')) return
+    event.preventDefault()
+    const rect = bounds?.getBoundingClientRect()
+    if (!rect) return
+    const delta = {
+      x: event.key === 'ArrowRight' ? 10 : event.key === 'ArrowLeft' ? -10 : 0,
+      y: event.key === 'ArrowDown' ? 10 : event.key === 'ArrowUp' ? -10 : 0,
+    }
+    setFrame(
+      resizeFloatingPreview({
+        start: frame(),
+        direction,
+        delta,
+        source: props.source,
+        container: { width: rect.width, height: rect.height },
+      })
+    )
+  }
+
+  return (
+    <div
+      ref={bounds}
+      class="pointer-events-none absolute inset-0 z-(--z-sticky) overflow-hidden"
+      aria-label={props.label}
+    >
+      <section
+        class="pointer-events-auto absolute flex flex-col overflow-visible rounded-lg border border-border bg-card text-card-foreground shadow-lg"
+        aria-label={props.label}
+        style={{
+          left: `${frame().x}px`,
+          top: `${frame().y}px`,
+          width: `${frame().width}px`,
+          height: `${frame().height}px`,
+        }}
+      >
+        <header class="flex h-control-sm items-center gap-1 border-b border-border p-1">
+          <ActionButton
+            type="button"
+            variant="ghost"
+            size="sm"
+            class="flex-1 cursor-move touch-none"
+            aria-label={`Move ${props.label}`}
+            tooltip={`Move ${props.label}. Use arrow keys to adjust its position.`}
+            onPointerDown={(event) => start(event, null)}
+            onPointerMove={move}
+            onPointerUp={end}
+            onPointerCancel={end}
+            onLostPointerCapture={end}
+            onKeyDown={keyboardMove}
+          >
+            <>
+              <Move aria-hidden="true" />
+              Move
+            </>
+          </ActionButton>
+          <div class="flex items-center gap-1">{props.actions}</div>
+          {props.onClose && (
+            <ActionButton
+              type="button"
+              variant="ghost"
+              size="icon-sm"
+              aria-label={`Close ${props.label}`}
+              tooltip={`Close ${props.label}.`}
+              onClick={props.onClose}
+            >
+              <X aria-hidden="true" />
+            </ActionButton>
+          )}
+        </header>
+        <ScrollArea role="region" aria-label={`${props.label} content`} class="flex-1" tabIndex={0}>
+          {props.children}
+        </ScrollArea>
+        {directions.map(({ direction, class: className, glyph }) => (
+          <ActionButton
+            type="button"
+            variant="ghost"
+            size="icon-sm"
+            class={className}
+            data-direction={direction}
+            aria-label={`Resize ${props.label} ${direction}`}
+            tooltip={`Resize ${props.label} from the ${direction} edge. Use arrow keys to resize.`}
+            onPointerDown={(event) => start(event, direction)}
+            onPointerMove={move}
+            onPointerUp={end}
+            onPointerCancel={end}
+            onLostPointerCapture={end}
+            onKeyDown={(event) => keyboardResize(event, direction)}
+          >
+            <span aria-hidden="true">{glyph}</span>
+          </ActionButton>
+        ))}
+      </section>
+    </div>
+  )
+}

package/src/components/layout/floating-preview/index.ts

@@ -0,0 +1,2 @@
+export * from './model'
+export * from './floating-preview'