@pienter/ui 0.2.0

package/utils/controllers/popover.ts

@@ -0,0 +1,434 @@
+/**
+ * Popover controller — shared by Popover, Tooltip, DropdownMenu,
+ * Combobox listbox, and HoverCard per the locked controller-sharing
+ * mapping in `CONVENTIONS.md`.
+ *
+ * The v1 popover family is built on top of the **native HTML Popover
+ * API** per the locked "Use native APIs where applicable" rule. The
+ * browser already handles:
+ *
+ * - Top-layer rendering (popover escapes any ancestor stacking
+ *   context / `overflow: hidden`)
+ * - Light-dismiss in `popover="auto"` mode (click outside, focus
+ *   outside, Escape all close the popover)
+ * - The `:popover-open` CSS pseudo-class for open-state styling
+ * - The `toggle` event (fires on every open/close transition with
+ *   `event.newState === 'open' | 'closed'`)
+ * - Focus management (the popover is rendered in the top-layer; the
+ *   browser does NOT auto-trap focus, but light-dismiss closes the
+ *   popover when focus moves outside in `auto` mode)
+ *
+ * What the browser does NOT provide and we layer on top:
+ *
+ * - **Anchor positioning** — CSS anchor positioning (`anchor-name`
+ *   + `position-anchor`) is the modern declarative approach but
+ *   Firefox support is incomplete in 2026. We compute position in
+ *   JS from the anchor's `getBoundingClientRect()` + popover
+ *   dimensions, applied via inline `style.left` / `style.top`. This
+ *   keeps the support floor at Chrome 114+ / Safari 17+ / Firefox
+ *   125+ (the Popover API floor itself).
+ * - **Placement-flip on viewport collision** — if `bottom-start`
+ *   overflows the bottom edge, we flip to `top-start`. Cross-axis
+ *   overflow is handled by shifting along that axis to keep the
+ *   popover inside the viewport.
+ * - **Reposition-on-scroll/resize** — while the popover is open,
+ *   `scroll` (capture) and `resize` listeners recompute the
+ *   position so the popover tracks its anchor.
+ * - A **callback** so framework code can reflect open/close state
+ *   back into reactive state (`update:open`).
+ * - **Anchor auto-detection** — if the consumer wires a trigger
+ *   button declaratively via `popovertarget="<id>"`, the controller
+ *   finds it via `document.querySelector('[popovertarget="<id>"]')`
+ *   on mount. An explicit anchor element overrides the lookup.
+ *
+ * Mount on:
+ * - The popover element itself (the element that carries the
+ *   `popover` attribute). The controller reads / sets the attribute
+ *   based on `config.modal`.
+ */
+
+/**
+ * Where the popover sits relative to its anchor.
+ *
+ * - The first segment (`top` / `right` / `bottom` / `left`) is the
+ *   side of the anchor the popover attaches to.
+ * - The optional second segment (`start` / `end`) aligns the
+ *   popover's leading or trailing edge with the anchor's
+ *   corresponding edge along the cross-axis. Without a second
+ *   segment, the popover is centered along the cross-axis.
+ *
+ * Placement flips automatically on viewport collision: a
+ * `bottom`-side placement that overflows flips to `top`, and
+ * vice-versa. Cross-axis overflow is shifted (the popover slides
+ * along the cross-axis to stay inside the viewport) rather than
+ * flipped.
+ */
+export type Placement =
+    | 'top'
+    | 'top-start'
+    | 'top-end'
+    | 'right'
+    | 'right-start'
+    | 'right-end'
+    | 'bottom'
+    | 'bottom-start'
+    | 'bottom-end'
+    | 'left'
+    | 'left-start'
+    | 'left-end';
+
+/**
+ * Imperative control surface returned by `mountPopover`. The
+ * controller owns the popover's runtime state (open/closed,
+ * positioning listeners) and lets the native Popover API handle
+ * top-layer rendering and light-dismiss. Frameworks call
+ * `show()` / `hide()` and watch incoming prop changes; they never
+ * own state directly.
+ */
+export interface PopoverControl {
+    /** Open the popover and position it against its anchor. */
+    show(): void;
+    /** Close the popover and tear down positioning listeners. */
+    hide(): void;
+    /** Toggle between open and closed. */
+    toggle(): void;
+    /** Whether the popover is currently open (DOM-truth). */
+    isOpen(): boolean;
+    /** Recompute position. Called automatically on scroll / resize while open. */
+    reposition(): void;
+    /** Release listeners and reset attributes. */
+    teardown(): void;
+}
+
+export interface PopoverConfig {
+    /**
+     * The element that anchors positioning (typically the trigger
+     * button). When `null`, the controller looks for a trigger via
+     * `document.querySelector('[popovertarget="<el.id>"]')`. If
+     * neither is available the popover still opens but is positioned
+     * at the viewport origin (0,0) — caller is responsible for
+     * supplying an anchor before `show()` is meaningful.
+     */
+    anchor?: HTMLElement | null;
+    /**
+     * Initial placement. The controller flips to the opposite side
+     * automatically on viewport collision and shifts along the
+     * cross-axis to keep the popover inside the viewport.
+     * Default: `'bottom-start'`.
+     */
+    placement?: Placement;
+    /**
+     * Offset from the anchor edge in pixels. The popover is pushed
+     * away from the anchor by this many pixels along the placement
+     * axis. Default: `8`.
+     */
+    offset?: number;
+    /**
+     * When `true`, the popover uses `popover="manual"` — the user
+     * cannot dismiss via outside click / focus loss / Escape; the
+     * popover stays open until programmatically hidden via
+     * `hide()`. When `false` (default), uses `popover="auto"` which
+     * provides browser-native light-dismiss.
+     */
+    modal?: boolean;
+    /**
+     * Called after the browser fires the `toggle` event with
+     * `newState === 'open'`. The framework reflects this into
+     * reactive state (e.g. `emit('update:open', true)`).
+     */
+    onOpen?: () => void;
+    /**
+     * Called after the browser fires the `toggle` event with
+     * `newState === 'closed'` — including light-dismiss closures
+     * the controller did not initiate. The framework reflects this
+     * into reactive state (e.g. `emit('update:open', false)`).
+     */
+    onClose?: () => void;
+}
+
+/**
+ * The DOM CSSStyleDeclaration assignment shape we use for
+ * positioning. Inline styles win over the popover's own CSS for
+ * `left` / `top`, which is what we want — the CSS supplies the
+ * surface look, the controller supplies the position.
+ */
+interface ComputedPosition {
+    left: number;
+    top: number;
+    /** The placement actually used after flip resolution. */
+    resolvedPlacement: Placement;
+}
+
+/**
+ * Pure helper — compute where the popover should be placed
+ * relative to the anchor, accounting for viewport collision via
+ * placement flip + cross-axis shift.
+ *
+ * Algorithm:
+ * 1. Compute the preferred (`left`, `top`) for the requested
+ *    placement.
+ * 2. If the popover overflows along the placement axis, flip to
+ *    the opposite side and recompute. (e.g., `bottom-start` →
+ *    `top-start` if there is more room above than below.)
+ * 3. Clamp the cross-axis position so the popover stays inside the
+ *    viewport (shift, not flip — flipping the cross-axis on a
+ *    `top-end` popover would re-flow the layout in a way that
+ *    breaks the user's mental model of the placement).
+ *
+ * Borrowed from Floating UI's basic algorithm without the dep.
+ */
+function computePosition(
+    anchor: HTMLElement,
+    popoverEl: HTMLElement,
+    placement: Placement,
+    offset: number,
+): ComputedPosition {
+    const anchorRect = anchor.getBoundingClientRect();
+    // The popover may not yet be laid out when we first compute, so
+    // reading `offsetWidth` / `offsetHeight` is safe only after
+    // `showPopover()` has been called (the browser sizes the popover
+    // before firing `toggle`). For first-call safety we fall back to
+    // `getBoundingClientRect()`.
+    const popoverRect = popoverEl.getBoundingClientRect();
+    const popoverW = popoverRect.width || popoverEl.offsetWidth;
+    const popoverH = popoverRect.height || popoverEl.offsetHeight;
+
+    const viewportW = document.documentElement.clientWidth;
+    const viewportH = document.documentElement.clientHeight;
+
+    function compute(p: Placement): { left: number; top: number } {
+        const [side, align] = p.split('-') as [
+            'top' | 'right' | 'bottom' | 'left',
+            'start' | 'end' | undefined,
+        ];
+
+        let left = 0;
+        let top = 0;
+
+        if (side === 'top') {
+            top = anchorRect.top - popoverH - offset;
+        } else if (side === 'bottom') {
+            top = anchorRect.bottom + offset;
+        } else if (side === 'left') {
+            left = anchorRect.left - popoverW - offset;
+        } else {
+            // right
+            left = anchorRect.right + offset;
+        }
+
+        // Cross-axis: align start/end/center against anchor's
+        // perpendicular dimension.
+        if (side === 'top' || side === 'bottom') {
+            if (align === 'start') left = anchorRect.left;
+            else if (align === 'end') left = anchorRect.right - popoverW;
+            else left = anchorRect.left + (anchorRect.width - popoverW) / 2;
+        } else {
+            // left | right
+            if (align === 'start') top = anchorRect.top;
+            else if (align === 'end') top = anchorRect.bottom - popoverH;
+            else top = anchorRect.top + (anchorRect.height - popoverH) / 2;
+        }
+
+        return { left, top };
+    }
+
+    function oppositeSide(p: Placement): Placement {
+        if (p.startsWith('top')) return p.replace('top', 'bottom') as Placement;
+        if (p.startsWith('bottom'))
+            return p.replace('bottom', 'top') as Placement;
+        if (p.startsWith('left'))
+            return p.replace('left', 'right') as Placement;
+        return p.replace('right', 'left') as Placement;
+    }
+
+    function overflowsMainAxis(
+        pos: { left: number; top: number },
+        p: Placement,
+    ): boolean {
+        if (p.startsWith('top')) return pos.top < 0;
+        if (p.startsWith('bottom')) return pos.top + popoverH > viewportH;
+        if (p.startsWith('left')) return pos.left < 0;
+        return pos.left + popoverW > viewportW;
+    }
+
+    let resolvedPlacement = placement;
+    let pos = compute(resolvedPlacement);
+
+    // Flip if the preferred placement overflows along the main axis,
+    // BUT only when the opposite side has more room (avoid flipping
+    // into worse overflow).
+    if (overflowsMainAxis(pos, resolvedPlacement)) {
+        const flipped = oppositeSide(resolvedPlacement);
+        const flippedPos = compute(flipped);
+        if (!overflowsMainAxis(flippedPos, flipped)) {
+            resolvedPlacement = flipped;
+            pos = flippedPos;
+        }
+    }
+
+    // Cross-axis clamp (shift, not flip). Keep at least 4px from the
+    // viewport edge so the popover never visually clips against the
+    // edge.
+    const margin = 4;
+    pos.left = Math.max(
+        margin,
+        Math.min(pos.left, viewportW - popoverW - margin),
+    );
+    pos.top = Math.max(
+        margin,
+        Math.min(pos.top, viewportH - popoverH - margin),
+    );
+
+    return { left: pos.left, top: pos.top, resolvedPlacement };
+}
+
+/**
+ * Mount the popover controller on `el`, which is the popover
+ * element itself (the element carrying the `popover` attribute).
+ * The native Popover API provides top-layer rendering, light
+ * dismiss, Escape handling, and the `:popover-open` pseudo-class;
+ * this controller layers on anchor positioning, placement flip on
+ * viewport collision, scroll/resize tracking, and `data-state`
+ * reflection so the existing CSS conventions keep working.
+ *
+ * Lifecycle:
+ * 1. On mount: set the `popover` attribute (`'auto'` for light
+ *    dismiss; `'manual'` for explicit-close-only). Wire the
+ *    `toggle` event so the framework hears about open/close
+ *    transitions. Resolve the anchor (explicit `config.anchor`,
+ *    else `document.querySelector('[popovertarget="<el.id>"]')`).
+ * 2. `show()`: call `el.showPopover()` (native top-layer + light
+ *    dismiss). Compute position via `computePosition` and apply
+ *    inline `style.left` / `style.top`. Wire scroll (capture) and
+ *    resize listeners that call `reposition()`.
+ * 3. `hide()`: call `el.hidePopover()` (native focus restoration
+ *    if focus was inside the popover). Remove scroll/resize
+ *    listeners.
+ * 4. `teardown()`: ensures hide ran, removes the `toggle`
+ *    listener.
+ *
+ * The controller does NOT decide when to close — `onOpen` /
+ * `onClose` are invoked when the browser fires the native `toggle`
+ * event. The caller is responsible for reflecting that into
+ * framework state. The framework's reactive prop is the source of
+ * truth for the open/closed boolean; the controller is the source
+ * of truth for runtime side-effects (positioning, listeners).
+ */
+export function mountPopover(
+    el: HTMLElement,
+    config: PopoverConfig = {},
+): PopoverControl {
+    const placement: Placement = config.placement ?? 'bottom-start';
+    const offset = config.offset ?? 8;
+    const modal = config.modal ?? false;
+
+    // `popover="auto"` opts into native light-dismiss: outside click,
+    // focus loss, and Escape all close the popover. `popover="manual"`
+    // means the popover stays until explicitly hidden via JS — used
+    // for non-dismissable surfaces (e.g., a modal-style popover that
+    // requires a button click to close).
+    el.setAttribute('popover', modal ? 'manual' : 'auto');
+    el.setAttribute('data-state', 'closed');
+
+    // Anchor resolution. Explicit `config.anchor` wins; otherwise
+    // look up the trigger via the native `popovertarget` attribute.
+    // Resolved lazily on each show() so the consumer can swap the
+    // trigger between mount and first open without re-mounting.
+    function resolveAnchor(): HTMLElement | null {
+        if (config.anchor) return config.anchor;
+        if (!el.id) return null;
+        return document.querySelector<HTMLElement>(
+            `[popovertarget="${CSS.escape(el.id)}"]`,
+        );
+    }
+
+    let scrollListenersWired = false;
+
+    function reposition(): void {
+        const anchor = resolveAnchor();
+        if (!anchor) return;
+        const { left, top, resolvedPlacement } = computePosition(
+            anchor,
+            el,
+            placement,
+            offset,
+        );
+        el.style.left = `${left}px`;
+        el.style.top = `${top}px`;
+        el.setAttribute('data-placement', resolvedPlacement);
+    }
+
+    function wireScrollListeners(): void {
+        if (scrollListenersWired) return;
+        // Capture phase so we catch scrolls inside any ancestor that
+        // might affect the anchor's viewport position. The listener is
+        // passive — we only read positions, never preventDefault.
+        window.addEventListener('scroll', reposition, {
+            capture: true,
+            passive: true,
+        });
+        window.addEventListener('resize', reposition, { passive: true });
+        scrollListenersWired = true;
+    }
+
+    function unwireScrollListeners(): void {
+        if (!scrollListenersWired) return;
+        window.removeEventListener('scroll', reposition, { capture: true });
+        window.removeEventListener('resize', reposition);
+        scrollListenersWired = false;
+    }
+
+    // Native `toggle` event fires on every open/close transition
+    // with `event.newState` set to `'open'` or `'closed'`. We use it
+    // as the single source of truth for `data-state` reflection and
+    // for invoking the framework callbacks — this catches both
+    // controller-initiated transitions (show/hide) and
+    // browser-initiated ones (light-dismiss, declarative
+    // `popovertarget` button click).
+    function handleToggle(event: Event): void {
+        const evt = event as ToggleEvent;
+        if (evt.newState === 'open') {
+            el.setAttribute('data-state', 'open');
+            // First reposition runs after the popover has been laid out
+            // by the browser (toggle fires after layout). Wire the
+            // scroll/resize listeners now so subsequent movement
+            // tracks.
+            reposition();
+            wireScrollListeners();
+            config.onOpen?.();
+        } else {
+            el.setAttribute('data-state', 'closed');
+            unwireScrollListeners();
+            config.onClose?.();
+        }
+    }
+
+    el.addEventListener('toggle', handleToggle);
+
+    function show(): void {
+        if (el.matches(':popover-open')) return; // idempotent
+        el.showPopover();
+    }
+
+    function hide(): void {
+        if (!el.matches(':popover-open')) return; // idempotent
+        el.hidePopover();
+    }
+
+    function toggle(): void {
+        if (el.matches(':popover-open')) hide();
+        else show();
+    }
+
+    function isOpen(): boolean {
+        return el.matches(':popover-open');
+    }
+
+    function teardown(): void {
+        if (isOpen()) hide();
+        unwireScrollListeners();
+        el.removeEventListener('toggle', handleToggle);
+    }
+
+    return { show, hide, toggle, isOpen, reposition, teardown };
+}