From 2571c1fd552aae81f7c817baacfa29c11dd150b7 Mon Sep 17 00:00:00 2001
From: Sarah Dayan <5370675+sarahdayan@users.noreply.github.com>
Date: Sat, 21 Feb 2026 09:25:21 +0100
Subject: [PATCH] feat(toolbar): add description tooltips to field components

Add a Tooltip UI primitive and InfoTooltip helper, then wire a
`description` prop through TextField, SwitchField, and ObjectField so
that `paramDescriptions` from widget configs are shown as info icons
with hover tooltips next to field labels.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../toolbar/src/components/block-editor.tsx   |  4 +
 .../src/components/fields/info-tooltip.tsx    | 26 +++++
 .../src/components/fields/object-field.tsx    |  8 +-
 .../src/components/fields/switch-field.tsx    | 14 ++-
 .../src/components/fields/text-field.tsx      |  8 +-
 .../toolbar/src/components/ui/tooltip.tsx     | 97 +++++++++++++++++++
 6 files changed, 153 insertions(+), 4 deletions(-)
 create mode 100644 packages/toolbar/src/components/fields/info-tooltip.tsx
 create mode 100644 packages/toolbar/src/components/ui/tooltip.tsx

diff --git a/packages/toolbar/src/components/block-editor.tsx b/packages/toolbar/src/components/block-editor.tsx
index e941d7a..137bb74 100644
--- a/packages/toolbar/src/components/block-editor.tsx
+++ b/packages/toolbar/src/components/block-editor.tsx
@@ -27,6 +27,7 @@ export function BlockEditor({
   const widgetType = WIDGET_TYPES[type];
   const overrides = widgetType?.fieldOverrides ?? {};
   const paramLabels = widgetType?.paramLabels ?? {};
+  const paramDescriptions = widgetType?.paramDescriptions ?? {};
 
   const paramKeys = widgetType?.fieldOrder
     ? widgetType.fieldOrder.filter((key) => {
@@ -84,6 +85,7 @@ export function BlockEditor({
             <TextField
               key={key}
               label={paramLabels[key] ?? key}
+              description={paramDescriptions[key]}
               value={typeof value === 'string' ? value : JSON.stringify(value)}
               onInput={(text) => {
                 return onParameterChange(key, text);
@@ -98,6 +100,7 @@ export function BlockEditor({
               <SwitchField
                 key={key}
                 label={override.label}
+                description={paramDescriptions[key]}
                 checked={Boolean(value)}
                 onToggle={(checked) => {
                   return onParameterChange(key, checked);
@@ -172,6 +175,7 @@ export function BlockEditor({
               <ObjectField
                 key={key}
                 label={override.label}
+                description={paramDescriptions[key]}
                 enabled={enabled}
                 value={objectValue}
                 defaultValue={override.defaultValue}
diff --git a/packages/toolbar/src/components/fields/info-tooltip.tsx b/packages/toolbar/src/components/fields/info-tooltip.tsx
new file mode 100644
index 0000000..c67ca69
--- /dev/null
+++ b/packages/toolbar/src/components/fields/info-tooltip.tsx
@@ -0,0 +1,26 @@
+import { Tooltip } from '../ui/tooltip';
+
+type InfoTooltipProps = {
+  content: string;
+  class?: string;
+};
+
+export function InfoTooltip({ content, class: className }: InfoTooltipProps) {
+  return (
+    <Tooltip content={content} class={className}>
+      <svg
+        class="size-3.5 text-muted-foreground"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
+        <circle cx="12" cy="12" r="10" />
+        <path d="M12 16v-4" />
+        <path d="M12 8h.01" />
+      </svg>
+    </Tooltip>
+  );
+}
diff --git a/packages/toolbar/src/components/fields/object-field.tsx b/packages/toolbar/src/components/fields/object-field.tsx
index 2a26030..94b0a44 100644
--- a/packages/toolbar/src/components/fields/object-field.tsx
+++ b/packages/toolbar/src/components/fields/object-field.tsx
@@ -1,5 +1,6 @@
 import { useId, useState } from 'preact/hooks';
 
+import { InfoTooltip } from './info-tooltip';
 import { CollapsibleContent, CollapsibleTrigger } from '../ui/collapsible';
 import { Label } from '../ui/label';
 import { Switch } from '../ui/switch';
@@ -7,6 +8,7 @@ import { TextField } from './text-field';
 
 type ObjectFieldProps = {
   label: string;
+  description?: string;
   enabled: boolean;
   value: Record<string, unknown>;
   defaultValue: Record<string, unknown>;
@@ -18,6 +20,7 @@ type ObjectFieldProps = {
 
 export function ObjectField({
   label,
+  description,
   enabled,
   value,
   defaultValue,
@@ -32,7 +35,10 @@ export function ObjectField({
   return (
     <div>
       <div class="flex items-center justify-between">
-        <Label htmlFor={id}>{label}</Label>
+        <Label htmlFor={id}>
+          {label}
+          {description && <InfoTooltip content={description} class="mt-0.5" />}
+        </Label>
         <Switch
           id={id}
           checked={enabled}
diff --git a/packages/toolbar/src/components/fields/switch-field.tsx b/packages/toolbar/src/components/fields/switch-field.tsx
index 2ee47fc..2be17dc 100644
--- a/packages/toolbar/src/components/fields/switch-field.tsx
+++ b/packages/toolbar/src/components/fields/switch-field.tsx
@@ -1,20 +1,30 @@
 import { useId } from 'preact/hooks';
 
+import { InfoTooltip } from './info-tooltip';
 import { Label } from '../ui/label';
 import { Switch } from '../ui/switch';
 
 type SwitchFieldProps = {
   label: string;
+  description?: string;
   checked: boolean;
   onToggle: (checked: boolean) => void;
 };
 
-export function SwitchField({ label, checked, onToggle }: SwitchFieldProps) {
+export function SwitchField({
+  label,
+  description,
+  checked,
+  onToggle,
+}: SwitchFieldProps) {
   const id = useId();
 
   return (
     <div class="flex items-center justify-between">
-      <Label htmlFor={id}>{label}</Label>
+      <Label htmlFor={id}>
+        {label}
+        {description && <InfoTooltip content={description} class="mt-0.5" />}
+      </Label>
       <Switch id={id} checked={checked} onCheckedChange={onToggle} />
     </div>
   );
diff --git a/packages/toolbar/src/components/fields/text-field.tsx b/packages/toolbar/src/components/fields/text-field.tsx
index a934bd0..1b11794 100644
--- a/packages/toolbar/src/components/fields/text-field.tsx
+++ b/packages/toolbar/src/components/fields/text-field.tsx
@@ -1,10 +1,12 @@
 import { useId } from 'preact/hooks';
 
+import { InfoTooltip } from './info-tooltip';
 import { Input } from '../ui/input';
 import { Label } from '../ui/label';
 
 type TextFieldProps = {
   label: string;
+  description?: string;
   value: string;
   placeholder?: string;
   onInput: (value: string) => void;
@@ -13,6 +15,7 @@ type TextFieldProps = {
 
 export function TextField({
   label,
+  description,
   value,
   placeholder,
   onInput,
@@ -22,7 +25,10 @@ export function TextField({
 
   return (
     <div class="group space-y-1">
-      <Label htmlFor={id}>{label}</Label>
+      <Label htmlFor={id}>
+        {label}
+        {description && <InfoTooltip content={description} class="mt-0.5" />}
+      </Label>
       <Input
         id={id}
         value={value}
diff --git a/packages/toolbar/src/components/ui/tooltip.tsx b/packages/toolbar/src/components/ui/tooltip.tsx
new file mode 100644
index 0000000..5b928a5
--- /dev/null
+++ b/packages/toolbar/src/components/ui/tooltip.tsx
@@ -0,0 +1,97 @@
+import type { ComponentChildren } from 'preact';
+import { useCallback, useId, useRef, useState } from 'preact/hooks';
+
+import { cn } from '../../lib/utils';
+
+type TooltipProps = {
+  content: ComponentChildren;
+  children: ComponentChildren;
+  class?: string;
+};
+
+type Position = { top: number; left: number };
+
+function Tooltip({ content, children, class: className }: TooltipProps) {
+  const id = useId();
+  const [open, setOpen] = useState(false);
+  const [position, setPosition] = useState<Position | null>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const tooltipRef = useRef<HTMLSpanElement>(null);
+
+  const reposition = useCallback(() => {
+    const trigger = triggerRef.current;
+    const tooltip = tooltipRef.current;
+    if (!trigger || !tooltip) return;
+
+    // Use the Shadow DOM host as the boundary for clamping. Falls back to
+    // the viewport width if rendered outside a Shadow DOM (e.g., in tests).
+    const root = trigger.getRootNode();
+    const host = root instanceof ShadowRoot ? (root.host as HTMLElement) : null;
+    const hostRect = host?.getBoundingClientRect();
+    const triggerRect = trigger.getBoundingClientRect();
+    const tooltipWidth = tooltip.offsetWidth;
+    const tooltipHeight = tooltip.offsetHeight;
+
+    const gap = 6;
+    const padding = 8;
+    const minLeft = (hostRect?.left ?? 0) + padding;
+    const maxRight = (hostRect?.right ?? window.innerWidth) - padding;
+
+    // Center horizontally on trigger, clamp within host
+    const idealLeft =
+      triggerRect.left + triggerRect.width / 2 - tooltipWidth / 2;
+    const clampedLeft = Math.max(
+      minLeft,
+      Math.min(idealLeft, maxRight - tooltipWidth)
+    );
+
+    setPosition({
+      top: triggerRect.top - tooltipHeight - gap,
+      left: clampedLeft,
+    });
+  }, []);
+
+  const show = useCallback(() => {
+    setOpen(true);
+    requestAnimationFrame(reposition);
+  }, [reposition]);
+
+  const hide = useCallback(() => {
+    setOpen(false);
+    setPosition(null);
+  }, []);
+
+  return (
+    <span class={cn('inline-flex', className)}>
+      <button
+        ref={triggerRef}
+        type="button"
+        class="inline-flex cursor-help"
+        onMouseEnter={show}
+        onMouseLeave={hide}
+        onFocus={show}
+        onBlur={hide}
+        aria-describedby={open ? id : undefined}
+      >
+        {children}
+      </button>
+      {open && (
+        <span
+          id={id}
+          ref={tooltipRef}
+          role="tooltip"
+          class="bg-background text-foreground border-border fixed z-50 w-max max-w-56 rounded-md border px-2.5 py-1.5 text-xs shadow-md"
+          style={
+            position
+              ? { top: `${position.top}px`, left: `${position.left}px` }
+              : { visibility: 'hidden' }
+          }
+        >
+          {content}
+        </span>
+      )}
+    </span>
+  );
+}
+
+export { Tooltip };