@duro-app/ui 4.1.0 → 4.3.0

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,293 @@
+import {
+  type ReactNode,
+  type Ref,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react'
+import {createPortal} from 'react-dom'
+import {html} from 'react-strict-dom'
+import {usePortalMount} from '../ThemeProvider/ThemeProvider'
+import {styles} from './styles.css'
+import {computePopoverPosition, type PopoverAlign, type PopoverSide} from './position'
+import {isOutsidePress} from './outside'
+
+// --- Context ---
+
+type IgnoreEntry = Element | null | (() => Element | null)
+
+interface PopoverContextValue {
+  open: boolean
+  setOpen: (open: boolean) => void
+  popoverId: string
+  side: PopoverSide
+  align: PopoverAlign
+  anchor?: () => DOMRect
+  triggerRef: React.RefObject<HTMLButtonElement | null>
+  popupRef: React.RefObject<HTMLDivElement | null>
+  repositionRef: React.RefObject<(() => void) | null>
+}
+
+const PopoverContext = createContext<PopoverContextValue | null>(null)
+
+function usePopover(part: string) {
+  const ctx = useContext(PopoverContext)
+  if (!ctx) throw new Error(`Popover.${part} must be used within Popover.Root`)
+  return ctx
+}
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+const OFFSET = 4 // `xs` token
+
+/**
+ * Whether a nested popup control owns this Escape: a Select, Menu or
+ * Combobox inside the popup closes on Esc without preventing default, and
+ * that Esc must close only it. Only controls that open a popup count — an
+ * expanded trigger that declares one (`aria-haspopup`), an expanded combobox,
+ * or focus inside a listbox or menu — never a plain disclosure, and never
+ * this popover's own Trigger.
+ *
+ * holds-until: Duro's Select, Menu and Combobox call preventDefault on the
+ * Escape they consume; the defaultPrevented check alone then suffices and
+ * this selector goes.
+ */
+const NESTED_POPUP_OWNER =
+  '[aria-expanded="true"][aria-haspopup], [role="combobox"][aria-expanded="true"], [role="listbox"], [role="menu"]'
+
+function nestedOwnsEscape(target: EventTarget | null, ownTrigger: Element | null): boolean {
+  if (!(target instanceof Element)) return false
+  const owner = target.closest(NESTED_POPUP_OWNER)
+  return owner !== null && owner !== ownTrigger
+}
+
+// --- Root ---
+
+export interface PopoverHandle {
+  /** Re-measure the anchor and re-place the popup. */
+  reposition: () => void
+}
+
+interface RootProps {
+  children: ReactNode
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  side?: PopoverSide
+  align?: PopoverAlign
+  /** Virtual anchor: a viewport rect. Replaces the Trigger as the anchor. */
+  anchor?: () => DOMRect
+  /** Elements (or getters) whose pointerdown does not count as an outside press. */
+  ignore?: ReadonlyArray<IgnoreEntry>
+  ref?: Ref<PopoverHandle>
+}
+
+function Root({
+  children,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  side = 'bottom',
+  align = 'start',
+  anchor,
+  ignore,
+  ref,
+}: RootProps) {
+  const [inner, setInner] = useState(defaultOpen)
+  const controlled = openProp !== undefined
+  const open = controlled ? openProp : inner
+  const popoverId = useId()
+  const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const popupRef = useRef<HTMLDivElement | null>(null)
+  const repositionRef = useRef<(() => void) | null>(null)
+  const previousFocusRef = useRef<HTMLElement | null>(null)
+  const ignoreRef = useRef(ignore)
+  ignoreRef.current = ignore
+  const openRef = useRef(open)
+  openRef.current = open
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!controlled) setInner(next)
+      if (next !== openRef.current) onOpenChange?.(next)
+    },
+    [controlled, onOpenChange],
+  )
+
+  useImperativeHandle(ref, () => ({reposition: () => repositionRef.current?.()}), [])
+
+  // Focus: into the popup on open, back to the trigger (or the previously
+  // focused element when there is no trigger) on close.
+  const wasOpenRef = useRef(false)
+  useEffect(() => {
+    if (open && !wasOpenRef.current) {
+      previousFocusRef.current = document.activeElement as HTMLElement | null
+      const popup = popupRef.current
+      if (popup) {
+        const first = popup.querySelector<HTMLElement>(FOCUSABLE)
+        ;(first ?? popup).focus({preventScroll: true})
+      }
+    } else if (!open && wasOpenRef.current) {
+      const target = triggerRef.current ?? previousFocusRef.current
+      target?.focus?.()
+      previousFocusRef.current = null
+    }
+    wasOpenRef.current = open
+  }, [open])
+
+  // Esc and outside press.
+  useEffect(() => {
+    if (!open) return
+
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key !== 'Escape' || e.defaultPrevented) return
+      if (nestedOwnsEscape(e.target, triggerRef.current)) return
+      e.preventDefault()
+      setOpen(false)
+    }
+
+    function onPointerDown(e: PointerEvent) {
+      const ignored = (ignoreRef.current ?? []).map((entry) =>
+        typeof entry === 'function' ? entry() : entry,
+      )
+      const inside = [popupRef.current, triggerRef.current, ...ignored]
+      if (isOutsidePress(e.target as Node | null, inside)) setOpen(false)
+    }
+
+    document.addEventListener('keydown', onKeyDown)
+    document.addEventListener('pointerdown', onPointerDown, true)
+    return () => {
+      document.removeEventListener('keydown', onKeyDown)
+      document.removeEventListener('pointerdown', onPointerDown, true)
+    }
+  }, [open, setOpen])
+
+  const ctx: PopoverContextValue = {
+    open,
+    setOpen,
+    popoverId,
+    side,
+    align,
+    anchor,
+    triggerRef,
+    popupRef,
+    repositionRef,
+  }
+
+  return <PopoverContext.Provider value={ctx}>{children}</PopoverContext.Provider>
+}
+
+// --- Trigger ---
+// Trigger IS the button (like Menu.Trigger): give it a label, not a Button.
+
+function Trigger({children}: {children: ReactNode}) {
+  const {open, setOpen, popoverId, triggerRef} = usePopover('Trigger')
+
+  return (
+    <html.button
+      ref={triggerRef}
+      type="button"
+      onClick={() => setOpen(!open)}
+      aria-haspopup="dialog"
+      aria-expanded={open}
+      aria-controls={open ? popoverId : undefined}
+      style={styles.trigger}
+    >
+      {children}
+    </html.button>
+  )
+}
+
+// --- Popup ---
+
+interface PopupProps {
+  children: ReactNode
+  /** Accessible name for the dialog. */
+  label: string
+}
+
+function Popup({children, label}: PopupProps) {
+  const {open, popoverId, side, align, anchor, triggerRef, popupRef, repositionRef} =
+    usePopover('Popup')
+  const [coords, setCoords] = useState({top: 0, left: 0})
+  // Inside ThemeProvider's portal layer, like Select/Dialog/Drawer: theme
+  // tokens cascade into the popup and it stacks above dialogs.
+  const mount = usePortalMount()
+
+  // Measure before paint on open; re-measure on scroll/resize (capture phase
+  // catches any scrolling ancestor) and when Root.reposition() is called.
+  useLayoutEffect(() => {
+    if (!open) {
+      repositionRef.current = null
+      return
+    }
+    const update = () => {
+      const popup = popupRef.current
+      if (!popup) return
+      const rect = anchor ? anchor() : triggerRef.current?.getBoundingClientRect()
+      if (!rect) return
+      const next = computePopoverPosition({
+        anchor: {top: rect.top, left: rect.left, width: rect.width, height: rect.height},
+        popup: {width: popup.offsetWidth, height: popup.offsetHeight},
+        viewport: {width: window.innerWidth, height: window.innerHeight},
+        side,
+        align,
+        offset: OFFSET,
+      })
+      setCoords((prev) =>
+        prev.top === next.top && prev.left === next.left ? prev : {top: next.top, left: next.left},
+      )
+    }
+    repositionRef.current = update
+    update()
+    window.addEventListener('resize', update)
+    window.addEventListener('scroll', update, true)
+    return () => {
+      repositionRef.current = null
+      window.removeEventListener('resize', update)
+      window.removeEventListener('scroll', update, true)
+    }
+  }, [open, side, align, anchor, triggerRef, popupRef, repositionRef])
+
+  if (!open || typeof document === 'undefined') return null
+
+  return createPortal(
+    <html.div
+      ref={popupRef}
+      id={popoverId}
+      role="dialog"
+      aria-label={label}
+      tabIndex={-1}
+      style={[styles.popup, styles.popupPosition(coords.top, coords.left)]}
+    >
+      {children}
+    </html.div>,
+    mount ?? document.body,
+  )
+}
+
+// --- Close ---
+
+function Close({children}: {children: ReactNode}) {
+  const {setOpen} = usePopover('Close')
+
+  return (
+    <html.button type="button" onClick={() => setOpen(false)} style={styles.close}>
+      {children}
+    </html.button>
+  )
+}
+
+export const Popover = {
+  Root,
+  Trigger,
+  Popup,
+  Close,
+}

package/src/components/Popover/outside.ts

@@ -0,0 +1,9 @@
+// True when a pointerdown target lies outside the popup, the trigger and every
+// ignored element. `inside` may hold nulls (refs not yet attached).
+export function isOutsidePress(
+  target: Node | null,
+  inside: ReadonlyArray<Element | null>,
+): boolean {
+  if (!target) return true
+  return !inside.some((el) => el != null && el.contains(target))
+}

package/src/components/Popover/position.ts

@@ -0,0 +1,48 @@
+export interface PopoverRect {
+  top: number
+  left: number
+  width: number
+  height: number
+}
+
+export interface PopoverSize {
+  width: number
+  height: number
+}
+
+export type PopoverSide = 'top' | 'bottom'
+export type PopoverAlign = 'start' | 'center' | 'end'
+
+interface Input {
+  anchor: PopoverRect
+  popup: PopoverSize
+  viewport: PopoverSize
+  side: PopoverSide
+  align: PopoverAlign
+  offset: number
+}
+
+// Pure placement: puts the popup on the requested side of the anchor, flips to
+// the opposite side when it would overflow the viewport there (and the other
+// side fits), and clamps horizontally into the viewport.
+export function computePopoverPosition({anchor, popup, viewport, side, align, offset}: Input) {
+  const below = anchor.top + anchor.height + offset
+  const above = anchor.top - offset - popup.height
+  const fitsBelow = below + popup.height <= viewport.height
+  const fitsAbove = above >= 0
+
+  let resolved: PopoverSide = side
+  if (side === 'bottom' && !fitsBelow && fitsAbove) resolved = 'top'
+  else if (side === 'top' && !fitsAbove && fitsBelow) resolved = 'bottom'
+
+  const top = resolved === 'bottom' ? below : above
+
+  let left = anchor.left
+  if (align === 'center') left = anchor.left + (anchor.width - popup.width) / 2
+  else if (align === 'end') left = anchor.left + anchor.width - popup.width
+
+  const maxLeft = Math.max(0, viewport.width - popup.width)
+  left = Math.min(Math.max(0, left), maxLeft)
+
+  return {top, left, side: resolved}
+}

package/src/components/Popover/styles.css.ts

@@ -0,0 +1,75 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
+import {shadows} from '@duro-app/tokens/tokens/shadows.css'
+import {duration} from '@duro-app/tokens/tokens/motion.css'
+
+export const styles = css.create({
+  trigger: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: spacing.sm,
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+    color: colors.text,
+    backgroundColor: {
+      default: 'transparent',
+      ':hover': colors.bgCardHover,
+    },
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    borderRadius: radii.sm,
+    cursor: 'pointer',
+    transitionProperty: 'background-color, border-color',
+    transitionDuration: duration.fast,
+  },
+  popup: {
+    position: 'fixed',
+    top: 0,
+    left: 0,
+    boxSizing: 'border-box',
+    backgroundColor: colors.bgCard,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    borderRadius: radii.sm,
+    boxShadow: shadows.md,
+    padding: spacing.md,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+    color: colors.text,
+    zIndex: 50,
+    // The portal layer is pointer-events: none so clicks fall through it;
+    // the popup takes them back.
+    pointerEvents: 'auto',
+  },
+  close: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    paddingLeft: spacing.sm,
+    paddingRight: spacing.sm,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+    color: colors.text,
+    backgroundColor: {
+      default: 'transparent',
+      ':hover': colors.bgCardHover,
+    },
+    borderWidth: 0,
+    borderRadius: radii.sm,
+    cursor: 'pointer',
+  },
+  // Dynamic position — applied at runtime from the measured anchor.
+  popupPosition: (top: number, left: number) => ({
+    top,
+    left,
+  }),
+})

package/src/components/Tooltip/Tooltip.meta.ts

@@ -9,7 +9,7 @@ export const meta: ComponentMeta = {
   ],
   whenNotToUse: [
     'Critical information that must always be visible — use Text or Callout',
-    'Interactive content (links, buttons) — tooltips are not interactive',
+    'Interactive content (links, buttons) — tooltips are not interactive — use Popover',
   ],
   anatomy: {
     required: ['Root', 'Trigger'],

package/src/index.ts

@@ -90,6 +90,8 @@ export {Text, type TextVariant, type TextColor} from './components/Text/Text'
 export {Toggle, type ToggleSize} from './components/Toggle/Toggle'
 export {ToggleGroup} from './components/ToggleGroup/ToggleGroup'
 export {Tooltip} from './components/Tooltip/Tooltip'
+export {Popover} from './components/Popover/Popover'
+export type {PopoverHandle} from './components/Popover/Popover'
 export {Switch} from './components/Switch/Switch'
 
 // Layout primitives