@adea-ai/ui 0.84.0 → 0.87.0

package/src/components/composites/list-row/list-row.tsx

@@ -2,6 +2,7 @@ import type { PolymorphicProps } from '@kobalte/core/polymorphic'
 import { Polymorphic } from '@kobalte/core/polymorphic'
 import type { ComponentProps, JSX, ValidComponent } from 'solid-js'
 import { Show, splitProps } from 'solid-js'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../../ui/tooltip'
 import { cn } from '#lib/utils'
 
 /**
@@ -18,9 +19,8 @@ import { cn } from '#lib/utils'
  * arithmetic.
  *
  * A row is only interactive when it is given an `as` that can be activated
- * (an anchor, a button) or an `onClick`. Without either it renders as a
- * `div` with no hover treatment, because a hover state on something that does
- * nothing is a lie.
+ * (an anchor, a button) or an `onClick`. Click handlers default to a native
+ * button; a row without either remains a `div` with no hover treatment.
  */
 export type ListRowProps<T extends ValidComponent = 'div'> = PolymorphicProps<
   T,
@@ -36,30 +36,50 @@ export type ListRowProps<T extends ValidComponent = 'div'> = PolymorphicProps<
     trailing?: JSX.Element
     /** A dimmed second line under the main content. */
     description?: string
+    /** A short explanation shown on pointer hover and keyboard focus. */
+    tooltip?: string
+    /** Native button type; defaults to `button` for button rows. */
+    type?: ComponentProps<'button'>['type']
   }
 >
 
-export function ListRow<T extends ValidComponent = 'div'>(props: ListRowProps<T>) {
+type ListRowBaseProps<T extends ValidComponent = 'div'> = ListRowProps<T> & {
+  as?: T
+  type?: ComponentProps<'button'>['type']
+}
+
+function ListRowBase<T extends ValidComponent = 'div'>(props: ListRowBaseProps<T>) {
   const [local, rest] = splitProps(props as ListRowProps, [
+    'as',
     'class',
     'selected',
     'dense',
     'leading',
     'trailing',
     'description',
+    'tooltip',
+    'type',
+    'tabIndex',
     'children',
   ])
 
   return (
     <Polymorphic
-      as="div"
+      as={(local.as ?? 'div') as T}
+      type={local.as === 'button' ? (local.type ?? 'button') : local.type}
+      tabIndex={local.tabIndex ?? (local.as === 'button' || local.as === 'a' ? 0 : undefined)}
       aria-current={local.selected ? 'true' : undefined}
       data-selected={local.selected ? '' : undefined}
       class={cn(
         'group/row flex min-w-0 items-center gap-2.5 rounded-md px-2 text-sm',
         'transition-colors ease-out outline-none',
         'focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-primary-subtle',
-        { 'h-row-sm': local.dense, 'h-row-md': !local.dense },
+        {
+          'h-row-sm': local.dense && !local.description,
+          'h-row-md': !local.dense && !local.description,
+          'min-h-row-sm py-1': local.dense && local.description,
+          'min-h-row-md py-1.5': !local.dense && local.description,
+        },
         {
           'bg-primary-subtle text-foreground': local.selected,
           'hover:bg-surface-hover': !local.selected,
@@ -76,11 +96,25 @@ export function ListRow<T extends ValidComponent = 'div'>(props: ListRowProps<T>
       <span class="flex min-w-0 flex-1 flex-col">
         <span class="truncate">{local.children}</span>
         <Show when={local.description}>
-          <span class="text-muted-foreground truncate text-xs">{local.description}</span>
+          <span
+            data-slot="list-row-description"
+            class={cn(
+              'truncate text-xs',
+              local.selected ? 'text-foreground' : 'text-muted-foreground'
+            )}
+          >
+            {local.description}
+          </span>
         </Show>
       </span>
       <Show when={local.trailing}>
-        <span class="ms-auto flex shrink-0 items-center gap-1 text-muted-foreground">
+        <span
+          data-slot="list-row-trailing"
+          class={cn(
+            'ms-auto flex shrink-0 items-center gap-1',
+            local.selected ? 'text-foreground' : 'text-muted-foreground'
+          )}
+        >
           {local.trailing}
         </span>
       </Show>
@@ -88,6 +122,45 @@ export function ListRow<T extends ValidComponent = 'div'>(props: ListRowProps<T>
   )
 }
 
+type ListRowTooltipTargetProps<T extends ValidComponent = 'div'> = Omit<
+  ListRowBaseProps<T>,
+  'as'
+> & { rowAs?: T }
+
+/** Adapts TooltipTrigger's polymorphic target to ListRow's semantic element. */
+function ListRowTooltipTarget<T extends ValidComponent = 'div'>(
+  props: ListRowTooltipTargetProps<T>
+) {
+  const [local, rest] = splitProps(props as ListRowTooltipTargetProps, ['rowAs'])
+  return <ListRowBase as={local.rowAs} {...(rest as ListRowBaseProps<T>)} />
+}
+
+export function ListRow<T extends ValidComponent = 'div'>(props: ListRowProps<T>) {
+  const [local, rest] = splitProps(props as ListRowProps, ['as', 'tooltip'])
+  const hasClickHandler = () => Boolean(rest.onClick || rest['on:click'])
+  const rowAs = () => (local.as ?? (hasClickHandler() ? 'button' : 'div')) as T
+  const rowType = () => (rowAs() === 'button' ? (rest.type ?? 'button') : rest.type)
+
+  return (
+    <Show
+      when={local.tooltip}
+      fallback={<ListRowBase as={rowAs()} type={rowType()} {...(rest as ListRowBaseProps<T>)} />}
+    >
+      <Tooltip>
+        <TooltipTrigger
+          as={ListRowTooltipTarget}
+          rowAs={rowAs()}
+          type={rowType()}
+          {...(rest as ListRowTooltipTargetProps<T>)}
+        >
+          {rest.children}
+        </TooltipTrigger>
+        <TooltipContent>{local.tooltip}</TooltipContent>
+      </Tooltip>
+    </Show>
+  )
+}
+
 /**
  * A group of rows with an optional heading and a scrolling body. The heading is
  * a plain label rather than a control: grouping is for reading, and a

package/src/components/composites/settings/settings.tsx

@@ -1,5 +1,6 @@
 import type { ComponentProps, JSX } from 'solid-js'
-import { Show, splitProps } from 'solid-js'
+import { createUniqueId, Show, splitProps } from 'solid-js'
+import { createFormFieldContext, FormFieldContext } from '#lib/form-field'
 import { cn } from '#lib/utils'
 
 /**
@@ -10,13 +11,10 @@ import { cn } from '#lib/utils'
  * placement all wander unless something fixes them.
  *
  * The row is a two-column layout at a fixed label width, so controls line up
- * down the page regardless of how long the labels are. That alignment is the
- * difference between a settings page that reads as designed and one that reads
- * as a form.
- *
- * `SettingsRow` puts the control on the trailing side and the label leading;
- * `SettingsField` stacks them for a control too wide for a row (a textarea, a
- * list). Both share the same label and description treatment.
+ * down the page regardless of how long the labels are. `SettingsRow` also
+ * exposes its label and description through the shared form-field context to
+ * the first control inside it. `SettingsField` is the visual stacked layout;
+ * use `FormField` when the control needs label, help, or validation wiring.
  */
 export function SettingsSection(
   props: ComponentProps<'section'> & {
@@ -24,9 +22,18 @@ export function SettingsSection(
     description?: string
     /** A control for the section as a whole, e.g. a master toggle. */
     action?: JSX.Element
+    /** Use a spaced content stack for fields, alerts, and cards instead of divided rows. */
+    bodyLayout?: 'rows' | 'content'
   }
 ) {
-  const [local, rest] = splitProps(props, ['class', 'title', 'description', 'action', 'children'])
+  const [local, rest] = splitProps(props, [
+    'class',
+    'title',
+    'description',
+    'action',
+    'bodyLayout',
+    'children',
+  ])
 
   return (
     <section
@@ -45,7 +52,16 @@ export function SettingsSection(
           <div class="flex shrink-0 items-center gap-2">{local.action}</div>
         </Show>
       </div>
-      <div class="divide-y divide-border rounded-xl border border-border">{local.children}</div>
+      <div
+        data-slot="settings-section-body"
+        class={cn(
+          local.bodyLayout === 'content'
+            ? 'flex flex-col gap-4'
+            : 'divide-y divide-border rounded-xl border border-border'
+        )}
+      >
+        {local.children}
+      </div>
     </section>
   )
 }
@@ -54,10 +70,9 @@ export function SettingsSection(
  * One setting: a label and description on the leading side, a control on the
  * trailing side.
  *
- * `label` is wired to the control through `aria-labelledby` when the control is
- * not already labelled, so a caller can pass a bare `Switch` and still get an
- * accessible name. The row does not invent an id per render — it derives one
- * from the label, which is stable across renders and readable in a snapshot.
+ * The label and description are linked to a shared control through field
+ * context. An explicit `aria-label` or `aria-labelledby` on the control keeps
+ * precedence; otherwise the visible row label names it.
  */
 export function SettingsRow(
   props: ComponentProps<'div'> & {
@@ -77,34 +92,49 @@ export function SettingsRow(
     'bare',
     'children',
   ])
+  const rowId = createUniqueId()
+  const labelId = `${rowId}-label`
+  const descriptionId = `${rowId}-description`
+  const field = createFormFieldContext({
+    defaultControlId: rowId,
+    labelId,
+    descriptionId,
+    hint: () => local.description,
+    error: () => undefined,
+    group: () => false,
+  })
 
   return (
-    <div
-      data-slot="settings-row"
-      class={cn(
-        'flex gap-4 p-4',
-        local.orientation === 'vertical'
-          ? 'flex-col'
-          : 'flex-col sm:flex-row sm:items-center sm:justify-between',
-        local.class
-      )}
-      {...rest}
-    >
-      <div class="flex min-w-0 flex-col gap-0.5">
-        <div data-slot="settings-row-label" class="text-sm font-medium">
-          {local.label}
-        </div>
-        <Show when={local.description}>
-          <p class="max-w-prose text-sm text-muted-foreground text-pretty">{local.description}</p>
-        </Show>
-      </div>
+    <FormFieldContext.Provider value={field}>
       <div
-        data-slot="settings-row-control"
-        class={cn('shrink-0', local.orientation === 'vertical' && 'w-full')}
+        data-slot="settings-row"
+        class={cn(
+          'flex gap-4 p-4',
+          local.orientation === 'vertical'
+            ? 'flex-col'
+            : 'flex-col sm:flex-row sm:items-center sm:justify-between',
+          local.class
+        )}
+        {...rest}
       >
-        {local.children}
+        <div class="flex min-w-0 flex-col gap-0.5">
+          <div id={labelId} data-slot="settings-row-label" class="text-sm font-medium">
+            {local.label}
+          </div>
+          <Show when={local.description}>
+            <p id={descriptionId} class="max-w-prose text-sm text-muted-foreground text-pretty">
+              {local.description}
+            </p>
+          </Show>
+        </div>
+        <div
+          data-slot="settings-row-control"
+          class={cn('shrink-0', local.orientation === 'vertical' && 'w-full')}
+        >
+          {local.children}
+        </div>
       </div>
-    </div>
+    </FormFieldContext.Provider>
   )
 }
 

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