preview-className-component

Skill: Building Components That Preview className Changes

Mental Model

Every interactive control in the panel follows a three-phase lifecycle:

HOVER → preview (live in user's app)
LEAVE → revert  (snap back to original)
CLICK → stage   (lock the new value as a draft)

The control itself only calls onHover(newClass) and onLeave(). The parent (usually Picker.tsx) owns the patchManager and wires those callbacks to preview() / revertPreview() / stage().

---

The onHover / onLeave Prop Contract

Every control that can preview a class change must accept these two props:

onHover: (fullClass: string) => void;  // called when a candidate value is highlighted
onLeave: () => void;                   // called when interaction ends without committing

onHover — fire on every discrete candidate value:

• Mouse enters a swatch / list item → onHover(fullClass)
• Scrub moves to a new step → onHover(fullClass)
• Keyboard navigates to an option → onHover(fullClass)

onLeave — fire when the user abandons the interaction without clicking:

• Mouse leaves the entire control
• Dropdown closes without selecting
• Focus leaves the container
• Escape is pressed

The parent wires them:

// In Picker.tsx (or wherever patchManager is available)
<MyControl
  onHover={(newClass) => patchManager.preview(currentClass, newClass)}
  onLeave={() => patchManager.revertPreview()}
  onClick={(newClass) => {
    handleStage(property, currentClass, newClass);
    // commitPreview() is called automatically after staging
  }}
/>

---

Dropdown Controls: the Focus-Trap Pattern

Any control with a dropdown / floating menu must use the canonical floating menu stack:

1. useFloating — positioning, flip, shift (from @floating-ui/react)
2. FloatingPortal — renders outside any overflow: hidden ancestor, preventing clipping
3. FocusTrapContainer — auto-focuses, fires onClose on blur/Escape
4. useDismiss — optional, adds pointer click-outside close