@adea-ai/ui 0.142.4 → 0.144.0

package/src/components/composites/icon-picker/icon-picker.tsx

@@ -0,0 +1,246 @@
+import { RadioGroup as Radio } from '@kobalte/core/radio-group'
+import { ChevronDown, ImageUp, Trash2 } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { For, Show, createSignal, createUniqueId, splitProps } from 'solid-js'
+import { Dynamic } from 'solid-js/web'
+import { cn } from '#lib/utils'
+import { Button } from '../../ui/button'
+import { Popover, PopoverContent, PopoverTrigger } from '../../ui/popover'
+import {
+  MarkImageError,
+  markImageFromFile,
+  markImageProblemCopy,
+  MARK_IMAGE_MAX_SOURCE_BYTES,
+} from './image-data-url'
+import { resolveShellIcon, shellIconEntries, shellIconLabel } from './shell-icons'
+
+/**
+ * IconPicker.
+ *
+ * The control behind "choose an icon" for a workspace or a project: a grid of
+ * curated glyphs, and optionally an uploaded picture in their place.
+ *
+ * It is a single-choice group. The glyph grid is a Kobalte radio group, so
+ * arrow keys move the choice and Tab enters and leaves the grid as one stop,
+ * which is the contract a 56-cell grid needs to stay usable from a keyboard. An
+ * uploaded image is a separate state, not a 57th cell: while `image` is set no
+ * glyph is checked, and choosing a glyph asks the caller to drop the image, so
+ * the stored mark is never both.
+ *
+ * The picker does not persist anything. The caller owns `value` and `image`
+ * and saves them with the rest of its form; the image arrives already resized
+ * to the stored square (see `markImageFromFile`).
+ */
+export type IconPickerProps = {
+  /** The group's accessible name, e.g. "Workspace icon". */
+  label: string
+  /** The checked icon key; ignored while `image` is set. */
+  value: string | undefined
+  onValueChange(key: string): void
+  /** The key the surface treats as unset, labelled "default" in the grid. */
+  defaultKey?: string
+  /** An uploaded mark (a data URL) currently chosen in place of a glyph. */
+  image?: string
+  /**
+   * Called with the resized upload, or `undefined` for Remove. Omit it for a
+   * surface that offers glyphs only; the upload row then does not render.
+   */
+  onImageChange?(image: string | undefined): void
+  disabled?: boolean
+  class?: string
+}
+
+export function IconPicker(props: IconPickerProps) {
+  const inputId = createUniqueId()
+  const [problem, setProblem] = createSignal<string>()
+  const [busy, setBusy] = createSignal(false)
+  const [fileInput, setFileInput] = createSignal<HTMLInputElement>()
+
+  const upload = async (file: File | undefined) => {
+    if (!file || !props.onImageChange) return
+    setProblem(undefined)
+    setBusy(true)
+    try {
+      props.onImageChange(await markImageFromFile(file))
+    } catch (error) {
+      setProblem(
+        markImageProblemCopy[error instanceof MarkImageError ? error.problem : 'unreadable']
+      )
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div data-slot="icon-picker" class={cn('flex flex-col gap-3', props.class)}>
+      <Show when={props.onImageChange}>
+        <div class="flex items-center gap-3" data-slot="icon-picker-upload">
+          <span
+            aria-hidden="true"
+            class="flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-lg border border-border bg-muted"
+          >
+            <Show
+              when={props.image}
+              fallback={<ImageUp class="size-5 text-muted-foreground" aria-hidden="true" />}
+            >
+              {(src) => <img src={src()} alt="" class="size-full object-cover" />}
+            </Show>
+          </span>
+          <div class="flex flex-wrap items-center gap-2">
+            <input
+              ref={setFileInput}
+              id={inputId}
+              type="file"
+              class="sr-only"
+              tabIndex={-1}
+              // The visible button drives this input; hide the duplicate from assistive
+              // technology but keep a name so the form-label rule is satisfied.
+              aria-hidden="true"
+              aria-label={props.image ? 'Replace image' : 'Upload image'}
+              accept="image/png,image/jpeg,image/webp,image/gif"
+              disabled={props.disabled}
+              onChange={(event) => {
+                const input = event.currentTarget
+                void upload(input.files?.[0])
+                // Clearing the value lets the same file be chosen again after Remove.
+                input.value = ''
+              }}
+            />
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              disabled={props.disabled || busy()}
+              onClick={() => fileInput()?.click()}
+            >
+              <ImageUp aria-hidden="true" />
+              {props.image ? 'Replace image' : 'Upload image'}
+            </Button>
+            <Show when={props.image}>
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                disabled={props.disabled || busy()}
+                onClick={() => {
+                  setProblem(undefined)
+                  props.onImageChange?.(undefined)
+                }}
+              >
+                <Trash2 aria-hidden="true" />
+                Remove image
+              </Button>
+            </Show>
+          </div>
+        </div>
+        <Show when={problem()}>
+          {(message) => (
+            <p role="alert" class="text-sm text-destructive">
+              {message()}
+            </p>
+          )}
+        </Show>
+        <p class="text-xs text-muted-foreground">
+          PNG, JPEG, WebP or GIF up to {MARK_IMAGE_MAX_SOURCE_BYTES / 1024 / 1024} MB. It is cropped
+          to a square.
+        </p>
+      </Show>
+      <Radio
+        aria-label={props.label}
+        value={props.image ? '' : (props.value ?? '')}
+        disabled={props.disabled}
+        onChange={(key) => {
+          if (key) props.onValueChange(key)
+        }}
+        class="grid grid-cols-[repeat(auto-fill,minmax(2.5rem,1fr))] gap-1.5"
+      >
+        <For each={shellIconEntries}>
+          {(entry) => {
+            const Icon = resolveShellIcon(entry.key)
+            return (
+              <Radio.Item value={entry.key} class="contents">
+                <Radio.ItemInput class="peer" />
+                <Radio.ItemLabel
+                  title={entry.key === props.defaultKey ? `${entry.label} (default)` : entry.label}
+                  class={cn(
+                    'flex size-10 cursor-pointer items-center justify-center rounded-lg border border-border bg-card text-muted-foreground',
+                    'transition-colors ease-out',
+                    'hover:bg-surface-hover hover:text-foreground',
+                    'peer-focus-visible:border-ring peer-focus-visible:ring-3 peer-focus-visible:ring-primary-subtle',
+                    'data-[checked]:border-primary data-[checked]:bg-primary-subtle data-[checked]:text-primary',
+                    'data-[disabled]:pointer-events-none data-[disabled]:opacity-50'
+                  )}
+                >
+                  <Icon class="size-5" aria-hidden="true" />
+                  <span class="sr-only">
+                    {entry.label}
+                    {entry.key === props.defaultKey ? ' (default)' : ''}
+                  </span>
+                </Radio.ItemLabel>
+              </Radio.Item>
+            )
+          }}
+        </For>
+      </Radio>
+    </div>
+  )
+}
+
+/**
+ * IconPickerDropdown.
+ *
+ * The compact form of the picker for a settings row: one button showing the
+ * current mark, opening the full grid (and the upload row, when the host offers
+ * it) in a popover. Choosing a glyph applies it and closes the popover; an
+ * upload or Remove leaves it open so the result is visible. The host owns the
+ * value exactly as it does for `IconPicker`.
+ */
+export type IconPickerDropdownProps = IconPickerProps & {
+  /** The mark shown on the trigger; defaults to the checked glyph or the uploaded image. */
+  trigger?: JSX.Element
+}
+
+export function IconPickerDropdown(props: IconPickerDropdownProps) {
+  const [open, setOpen] = createSignal(false)
+  const [local, picker] = splitProps(props, ['trigger', 'class'])
+  const Current = () => resolveShellIcon(props.value ?? props.defaultKey ?? '')
+  return (
+    <Popover open={open()} onOpenChange={setOpen} placement="bottom-start">
+      <PopoverTrigger
+        as={Button}
+        type="button"
+        variant="outline"
+        data-slot="icon-picker-trigger"
+        aria-label={`${props.label}: ${props.image ? 'uploaded image' : shellIconLabel(props.value ?? props.defaultKey ?? '')}`}
+        disabled={props.disabled}
+        class={cn('gap-2', local.class)}
+      >
+        <span aria-hidden="true" class="flex size-5 items-center justify-center overflow-hidden">
+          <Show
+            when={local.trigger}
+            fallback={
+              <Show
+                when={props.image}
+                fallback={<Dynamic component={Current()} class="size-4" aria-hidden="true" />}
+              >
+                {(src) => <img src={src()} alt="" class="size-full rounded-sm object-cover" />}
+              </Show>
+            }
+          >
+            {local.trigger}
+          </Show>
+        </span>
+        <ChevronDown class="size-4 text-muted-foreground" aria-hidden="true" />
+      </PopoverTrigger>
+      <PopoverContent class="w-[min(22rem,var(--kb-popper-available-width))]">
+        <IconPicker
+          {...picker}
+          onValueChange={(key) => {
+            picker.onValueChange(key)
+            setOpen(false)
+          }}
+        />
+      </PopoverContent>
+    </Popover>
+  )
+}

package/src/components/composites/icon-picker/image-data-url.ts

@@ -0,0 +1,107 @@
+/**
+ * Turning an uploaded picture into the small square mark a workspace stores.
+ *
+ * The mark travels with the workspace record (it is shown in every list the
+ * workspace appears in), so it is resized to a fixed square and re-encoded
+ * before it leaves the browser rather than stored as the user's original file.
+ * Re-encoding also drops metadata and any embedded script an SVG could carry:
+ * only raster images are accepted and the result is always a `data:image/webp`
+ * or `data:image/png` URL.
+ */
+
+/** The edge, in pixels, of the stored square. 2x the largest tile the apps draw. */
+export const MARK_IMAGE_SIZE = 128
+/** The largest source file read, before resizing. */
+export const MARK_IMAGE_MAX_SOURCE_BYTES = 8 * 1024 * 1024
+/** The largest encoded result kept; a stored mark never exceeds this many characters. */
+export const MARK_IMAGE_MAX_DATA_URL_LENGTH = 48 * 1024
+
+const ACCEPTED_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
+
+export type MarkImageProblem = 'type' | 'size' | 'unreadable' | 'too-large'
+
+/** Thrown by {@link markImageFromFile}; `problem` keys {@link markImageProblemCopy}. */
+export class MarkImageError extends Error {
+  readonly problem: MarkImageProblem
+  constructor(problem: MarkImageProblem) {
+    super(problem)
+    this.name = 'MarkImageError'
+    this.problem = problem
+  }
+}
+
+export const markImageProblemCopy: Readonly<Record<MarkImageProblem, string>> = {
+  type: 'Choose a PNG, JPEG, WebP or GIF image.',
+  size: 'That image is larger than 8 MB. Choose a smaller one.',
+  unreadable: 'That image could not be read. Try a different file.',
+  'too-large': 'That image is too detailed to store as a mark. Try a simpler one.',
+}
+
+/** Whether a stored value is a mark image this module could have produced. */
+export function isMarkImageDataUrl(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length <= MARK_IMAGE_MAX_DATA_URL_LENGTH &&
+    /^data:image\/(?:webp|png);base64,[A-Za-z0-9+/]+={0,2}$/.test(value)
+  )
+}
+
+/** Pre-flight checks that need no decoding; `undefined` means the file may be read. */
+export function checkMarkImageFile(
+  file: Readonly<{ type: string; size: number }>
+): MarkImageProblem | undefined {
+  if (!ACCEPTED_TYPES.has(file.type)) return 'type'
+  if (file.size > MARK_IMAGE_MAX_SOURCE_BYTES) return 'size'
+  return undefined
+}
+
+/** The source rectangle of the largest centred square, so the mark is a cover crop. */
+export function centredSquare(
+  width: number,
+  height: number
+): Readonly<{ x: number; y: number; side: number }> {
+  const side = Math.min(width, height)
+  return { x: Math.floor((width - side) / 2), y: Math.floor((height - side) / 2), side }
+}
+
+/**
+ * Resize an image file to the stored mark. Rejects with a {@link MarkImageError}
+ * so the caller can show `markImageProblemCopy[error.problem]`.
+ */
+export async function markImageFromFile(file: File): Promise<string> {
+  const problem = checkMarkImageFile(file)
+  if (problem) throw new MarkImageError(problem)
+  let bitmap: ImageBitmap
+  try {
+    bitmap = await createImageBitmap(file)
+  } catch {
+    throw new MarkImageError('unreadable')
+  }
+  try {
+    const canvas = document.createElement('canvas')
+    canvas.width = MARK_IMAGE_SIZE
+    canvas.height = MARK_IMAGE_SIZE
+    const context = canvas.getContext('2d')
+    if (!context) throw new MarkImageError('unreadable')
+    const crop = centredSquare(bitmap.width, bitmap.height)
+    context.drawImage(
+      bitmap,
+      crop.x,
+      crop.y,
+      crop.side,
+      crop.side,
+      0,
+      0,
+      MARK_IMAGE_SIZE,
+      MARK_IMAGE_SIZE
+    )
+    // WebP where the browser can encode it; PNG is the always-available fallback.
+    for (const type of ['image/webp', 'image/png']) {
+      const url = canvas.toDataURL(type, 0.85)
+      if (url.startsWith(`data:${type}`) && isMarkImageDataUrl(url)) return url
+    }
+    throw new MarkImageError('too-large')
+  } finally {
+    bitmap.close()
+  }
+}

package/src/components/composites/icon-picker/index.ts

@@ -0,0 +1,25 @@
+export {
+  IconPicker,
+  IconPickerDropdown,
+  type IconPickerDropdownProps,
+  type IconPickerProps,
+} from './icon-picker'
+export {
+  MARK_IMAGE_MAX_DATA_URL_LENGTH,
+  MARK_IMAGE_MAX_SOURCE_BYTES,
+  MARK_IMAGE_SIZE,
+  MarkImageError,
+  centredSquare,
+  checkMarkImageFile,
+  isMarkImageDataUrl,
+  markImageFromFile,
+  markImageProblemCopy,
+  type MarkImageProblem,
+} from './image-data-url'
+export {
+  isShellIconKey,
+  resolveShellIcon,
+  shellIconEntries,
+  shellIconLabel,
+  type ShellIconKey,
+} from './shell-icons'

package/src/components/composites/icon-picker/shell-icons.ts

@@ -0,0 +1,166 @@
+import {
+  Anchor,
+  Bot,
+  Box,
+  BookOpen,
+  Brain,
+  Briefcase,
+  Building2,
+  Camera,
+  ChartColumn,
+  Cloud,
+  Code,
+  Coffee,
+  Compass,
+  Cpu,
+  Database,
+  Dumbbell,
+  Flag,
+  Flame,
+  FlaskConical,
+  Folder,
+  FolderGit2,
+  Gamepad2,
+  Gem,
+  Globe,
+  GraduationCap,
+  Hammer,
+  Heart,
+  House,
+  Key,
+  Layers,
+  Leaf,
+  Lightbulb,
+  type LucideIcon,
+  Map as MapIcon,
+  Megaphone,
+  MessagesSquare,
+  Moon,
+  Mountain,
+  Music,
+  Newspaper,
+  Package,
+  Palette,
+  Plane,
+  Puzzle,
+  Rocket,
+  Server,
+  Shapes,
+  Shield,
+  ShoppingCart,
+  Sparkles,
+  Star,
+  Sun,
+  Target,
+  Terminal,
+  Trophy,
+  Users,
+  Utensils,
+  Wallet,
+  Wrench,
+  Zap,
+} from 'lucide-solid'
+
+/**
+ * The icons a workspace or a project may choose for itself.
+ *
+ * A curated set rather than the whole Lucide catalogue, for two reasons the
+ * picker depends on: the keys are persisted, so each one is a promise that the
+ * glyph keeps existing, and every icon here is imported by name so a consumer's
+ * bundle pays for these few dozen glyphs and not for the library.
+ *
+ * `home`, `box` and `folder` lead the list because they are the defaults the
+ * apps already use: Home workspaces carry `home`, other workspaces `box` and
+ * projects `folder`. Keys are lowercase kebab-case so they are valid project
+ * `iconKey`s as well as workspace logo values.
+ */
+export const shellIconEntries = [
+  { key: 'home', label: 'Home', icon: House },
+  { key: 'box', label: 'Box', icon: Box },
+  { key: 'folder', label: 'Folder', icon: Folder },
+  { key: 'git-folder', label: 'Repository', icon: FolderGit2 },
+  { key: 'briefcase', label: 'Briefcase', icon: Briefcase },
+  { key: 'building', label: 'Building', icon: Building2 },
+  { key: 'users', label: 'Team', icon: Users },
+  { key: 'rocket', label: 'Rocket', icon: Rocket },
+  { key: 'star', label: 'Star', icon: Star },
+  { key: 'heart', label: 'Heart', icon: Heart },
+  { key: 'code', label: 'Code', icon: Code },
+  { key: 'terminal', label: 'Terminal', icon: Terminal },
+  { key: 'cpu', label: 'Chip', icon: Cpu },
+  { key: 'server', label: 'Server', icon: Server },
+  { key: 'database', label: 'Database', icon: Database },
+  { key: 'cloud', label: 'Cloud', icon: Cloud },
+  { key: 'globe', label: 'Globe', icon: Globe },
+  { key: 'bot', label: 'Agent', icon: Bot },
+  { key: 'brain', label: 'Brain', icon: Brain },
+  { key: 'sparkles', label: 'Sparkles', icon: Sparkles },
+  { key: 'lightbulb', label: 'Idea', icon: Lightbulb },
+  { key: 'flask', label: 'Lab', icon: FlaskConical },
+  { key: 'book', label: 'Book', icon: BookOpen },
+  { key: 'graduation', label: 'Study', icon: GraduationCap },
+  { key: 'newspaper', label: 'News', icon: Newspaper },
+  { key: 'megaphone', label: 'Marketing', icon: Megaphone },
+  { key: 'chart', label: 'Chart', icon: ChartColumn },
+  { key: 'wallet', label: 'Finance', icon: Wallet },
+  { key: 'cart', label: 'Shop', icon: ShoppingCart },
+  { key: 'package', label: 'Package', icon: Package },
+  { key: 'layers', label: 'Layers', icon: Layers },
+  { key: 'puzzle', label: 'Puzzle', icon: Puzzle },
+  { key: 'shield', label: 'Security', icon: Shield },
+  { key: 'key', label: 'Key', icon: Key },
+  { key: 'wrench', label: 'Tools', icon: Wrench },
+  { key: 'hammer', label: 'Build', icon: Hammer },
+  { key: 'zap', label: 'Bolt', icon: Zap },
+  { key: 'flame', label: 'Flame', icon: Flame },
+  { key: 'target', label: 'Target', icon: Target },
+  { key: 'trophy', label: 'Trophy', icon: Trophy },
+  { key: 'flag', label: 'Flag', icon: Flag },
+  { key: 'compass', label: 'Compass', icon: Compass },
+  { key: 'map', label: 'Map', icon: MapIcon },
+  { key: 'plane', label: 'Travel', icon: Plane },
+  { key: 'anchor', label: 'Anchor', icon: Anchor },
+  { key: 'mountain', label: 'Mountain', icon: Mountain },
+  { key: 'leaf', label: 'Garden', icon: Leaf },
+  { key: 'sun', label: 'Sun', icon: Sun },
+  { key: 'moon', label: 'Moon', icon: Moon },
+  { key: 'palette', label: 'Design', icon: Palette },
+  { key: 'camera', label: 'Camera', icon: Camera },
+  { key: 'music', label: 'Music', icon: Music },
+  { key: 'gamepad', label: 'Games', icon: Gamepad2 },
+  { key: 'coffee', label: 'Coffee', icon: Coffee },
+  { key: 'utensils', label: 'Kitchen', icon: Utensils },
+  { key: 'dumbbell', label: 'Gym', icon: Dumbbell },
+  { key: 'gem', label: 'Gem', icon: Gem },
+  { key: 'messages', label: 'Chat', icon: MessagesSquare },
+  { key: 'shapes', label: 'Shapes', icon: Shapes },
+] as const satisfies readonly Readonly<{ key: string; label: string; icon: LucideIcon }>[]
+
+export type ShellIconKey = (typeof shellIconEntries)[number]['key']
+
+const shellIconByKey: ReadonlyMap<string, LucideIcon> = new Map(
+  shellIconEntries.map((entry) => [entry.key, entry.icon])
+)
+
+/** Whether a stored string names an icon in the curated set. */
+export function isShellIconKey(value: string): value is ShellIconKey {
+  return shellIconByKey.has(value)
+}
+
+/**
+ * The glyph for a stored key, or `fallback` when the key is not in the set.
+ * Callers pass the fallback their surface wants (a workspace falls back to
+ * `box`, a project to `folder`), so an unknown key degrades to the default
+ * rather than to an empty tile.
+ */
+export function resolveShellIcon(
+  key: string | null | undefined,
+  fallback: ShellIconKey = 'folder'
+): LucideIcon {
+  return (key ? shellIconByKey.get(key) : undefined) ?? shellIconByKey.get(fallback)!
+}
+
+/** The picker's accessible name for a key. */
+export function shellIconLabel(key: string): string {
+  return shellIconEntries.find((entry) => entry.key === key)?.label ?? key
+}

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

@@ -182,7 +182,7 @@ export function SettingsNavigation(props: SettingsNavigationProps) {
                 class={cn(
                   sidebarNavItemClass,
                   sidebarNavItemStateClass.idle,
-                  'h-row-lg justify-start border-0 px-3 py-2 text-left data-[selected]:bg-primary-subtle data-[selected]:text-foreground',
+                  'h-row-lg justify-start border-0 px-3 py-2 text-left text-foreground data-[selected]:bg-primary-subtle',
                   strip() ? 'w-auto shrink-0' : 'w-full'
                 )}
               >

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

@@ -1,7 +1,9 @@
+import { CircleHelp } from 'lucide-solid'
 import type { ComponentProps, JSX } from 'solid-js'
 import { createUniqueId, Show, splitProps } from 'solid-js'
 import { createFormFieldContext, FormFieldContext } from '#lib/form-field'
 import { cn } from '#lib/utils'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../../ui/tooltip'
 import { Heading } from '../../ui/typography'
 
 /**
@@ -18,10 +20,29 @@ import { Heading } from '../../ui/typography'
  * the first control inside it. `SettingsField` is the visual stacked layout;
  * use `FormField` when the control needs label, help, or validation wiring.
  */
+function HelpTip(props: { label: string; help: string }) {
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        as="button"
+        type="button"
+        data-slot="settings-row-help"
+        aria-label={`About ${props.label}`}
+        class="inline-flex size-4 items-center justify-center rounded-full text-muted-foreground hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:outline-none"
+      >
+        <CircleHelp class="size-3.5" aria-hidden="true" />
+      </TooltipTrigger>
+      <TooltipContent>{props.help}</TooltipContent>
+    </Tooltip>
+  )
+}
+
 export function SettingsSection(
   props: ComponentProps<'section'> & {
     title: string
     description?: string
+    /** A short explanation behind a help icon beside the title; prefer it to a long description. */
+    help?: 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. */
@@ -32,6 +53,7 @@ export function SettingsSection(
     'class',
     'title',
     'description',
+    'help',
     'action',
     'bodyLayout',
     'children',
@@ -45,9 +67,12 @@ export function SettingsSection(
     >
       <div class="flex items-start justify-between gap-4">
         <div class="flex min-w-0 flex-col gap-0.5">
-          <Heading as="h2" size="card">
-            {local.title}
-          </Heading>
+          <div class="flex items-center gap-1.5">
+            <Heading as="h2" size="card">
+              {local.title}
+            </Heading>
+            <Show when={local.help}>{(help) => <HelpTip label={local.title} help={help()} />}</Show>
+          </div>
           <Show when={local.description}>
             <p class="max-w-prose text-sm text-muted-foreground text-pretty">{local.description}</p>
           </Show>
@@ -82,6 +107,12 @@ export function SettingsRow(
   props: ComponentProps<'div'> & {
     label: string
     description?: string
+    /**
+     * A short explanation behind a help icon beside the label. Prefer it to a
+     * long description: the row stays quiet and the explanation is one hover or
+     * focus away.
+     */
+    help?: string
     /** Render a vertical stack when the control needs the full width. */
     orientation?: 'horizontal' | 'vertical'
     /** Hide the divider this row would otherwise contribute. */
@@ -100,6 +131,7 @@ export function SettingsRow(
     'class',
     'label',
     'description',
+    'help',
     'orientation',
     'bare',
     'flush',
@@ -132,8 +164,11 @@ export function SettingsRow(
         {...rest}
       >
         <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 class="flex items-center gap-1.5">
+            <div id={labelId} data-slot="settings-row-label" class="text-sm font-medium">
+              {local.label}
+            </div>
+            <Show when={local.help}>{(help) => <HelpTip label={local.label} help={help()} />}</Show>
           </div>
           <Show when={local.description}>
             <p id={descriptionId} class="max-w-prose text-sm text-muted-foreground text-pretty">