@uniflowed/ui 0.0.0-alpha.8 → 0.0.0-alpha.9

package/internal/hover-intent.js

@@ -0,0 +1,259 @@
+// @flow
+//
+// What WCAG requires of anything that appears because a pointer or focus
+// arrived, which is a tooltip and a hover card and nothing else in this
+// package.
+//
+// SC 1.4.13, *Content on Hover or Focus*, is three clauses, and a hand-written
+// tooltip fails all three. They are not a matter of taste and they are not
+// separable, so they live in one module:
+//
+//   * **Dismissible** — `Escape` removes it without moving the pointer. The
+//     content never holds focus, so the key never reaches it: the listener has
+//     to be on the document, which is `useDismissOnEscape` below.
+//   * **Hoverable** — the pointer can travel from the trigger onto the content
+//     without it vanishing on the way. That is why leaving schedules a close
+//     rather than performing one, and why arriving anywhere cancels it. A
+//     component that closes on `pointerleave` snatches the content away from a
+//     reader who was moving towards it — including every reader who magnifies
+//     the screen, for whom the trip is long.
+//   * **Persistent** — it stays until it is dismissed or the pointer and focus
+//     have both left. A timer that closes it on its own is out.
+//
+// The opening delay is not one of the three clauses; it is what makes the
+// component bearable. A pointer crossing a toolbar enters six triggers on its
+// way somewhere else, and a tooltip that opened on each would be six
+// interruptions. **A delay belongs to the pointer and not to focus**: a reader
+// who tabbed to a control has already said what they want, and making them wait
+// for it is a delay with nothing to prevent.
+//
+// # The clock is a ref, and `useTimeout` is deliberately not used
+//
+// `@uniflowed/hooks/timing` has the hook this looks like it wants, and its
+// contract is not this one: `useTimeout(body, millis)` sets its timer in an
+// effect keyed on `millis`, so asking again for the *same* delay does not
+// restart it. Every interesting sequence here asks twice — enter, leave,
+// enter — and with an open delay equal to the close delay the second request
+// would inherit the first request's deadline and fire early. What is wanted is
+// "restart the clock", which is a command rather than a state, so it is written
+// as one.
+//
+// # Why this is `internal/` and not a subpath
+//
+// It is not a `useHoverIntent` for anybody to build a tooltip with; it is the
+// half of `tooltip.js` and `hover-card.js` that has to be the same in both. A
+// consumer given a copy could build the component that closes on
+// `pointerleave`, which is the failure this exists to prevent.
+
+import { useEffect, useMemo, useRef } from "@uniflowed/react";
+import { useStableCallback } from "@uniflowed/hooks/lifecycle";
+
+import { FOCUS_STOPS } from "./focus.js";
+
+/** How long a pointer must rest on a trigger before its tooltip opens. */
+export const DEFAULT_OPEN_DELAY: number = 700;
+
+/**
+ * How long the content stays after the pointer leaves.
+ *
+ * This is the hoverable clause's whole implementation: the gap between a
+ * trigger and its overlay takes a moment to cross, and a reader who is crossing
+ * it has not left.
+ */
+export const DEFAULT_CLOSE_DELAY: number = 300;
+
+/**
+ * How long after one tooltip closes the next one opens with no delay.
+ *
+ * A reader who has waited out the delay once has established that they are
+ * reading tooltips; the second icon in a toolbar should answer immediately.
+ */
+export const DEFAULT_SKIP_DELAY: number = 300;
+
+/** Opening and closing, on a clock that can be restarted or called off. */
+export type HoverIntent = {|
+  /** Open after `millis`, or in this tick when that is nought. */
+  readonly openAfter: (millis: number) => void,
+  /** Close after `millis`, or in this tick when that is nought. */
+  readonly closeAfter: (millis: number) => void,
+  /** Forget whatever was scheduled. Arriving anywhere calls this first. */
+  readonly cancel: () => void,
+|};
+
+/**
+ * A group of tooltips that share one clock.
+ *
+ * `Tooltip.Provider` holds it; `Tooltip.Root` asks it what delay to use. A
+ * tooltip outside a provider never sees one and uses its own delay, which is
+ * the behaviour a tooltip on its own has always had.
+ */
+export type DelayGroup = {|
+  /** `own`, or nought while the group is inside its skip window. */
+  readonly delayFor: (own: number) => number,
+  /** Told that a tooltip in the group has opened. */
+  readonly opened: () => void,
+  /** Told that one has closed, which is what starts the window. */
+  readonly closed: () => void,
+|};
+
+/**
+ * A pending open or close, restartable, and cancelled when the component goes.
+ *
+ * `setOpen` is called with the answer rather than with a toggle, so a schedule
+ * that is overtaken by a second one does not leave the component holding the
+ * first one's opinion.
+ */
+export hook useHoverIntent(setOpen: (open: boolean) => void): HoverIntent {
+  const timer = useRef<TimeoutID | null>(null);
+  const change = useStableCallback(setOpen);
+
+  const cancel = useStableCallback(() => {
+    if (timer.current != null) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+  });
+
+  const schedule = useStableCallback((open: boolean, millis: number) => {
+    cancel();
+    if (millis <= 0) {
+      // In this tick, not in a zero-millisecond timeout. A tooltip that opens
+      // on focus, and the second tooltip in a toolbar, both have to be open by
+      // the time the event handler returns — a test that has to advance a clock
+      // to see them is describing a wait the reader would also have had.
+      change(open);
+      return;
+    }
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      change(open);
+    }, millis);
+  });
+
+  // The component can be taken away while a tooltip is waiting to open, and a
+  // timer that outlives it sets state on something that is gone.
+  useEffect(() => cancel, [cancel]);
+
+  return useMemo(
+    () => ({
+      cancel,
+      closeAfter: (millis: number) => schedule(false, millis),
+      openAfter: (millis: number) => schedule(true, millis),
+    }),
+    [cancel, schedule],
+  );
+}
+
+/**
+ * The shared clock behind `Tooltip.Provider`.
+ *
+ * Refs rather than state, and that is the whole design: nothing here is
+ * rendered. A group that held "are we skipping" in state would re-render every
+ * tooltip in a toolbar twice for each one the pointer passed over, to change
+ * nothing anybody can see.
+ *
+ * The window is open while a tooltip in the group is showing — moving along a
+ * toolbar with one already open is the case that must not stutter — and for
+ * `skipDelay` after the last one closes.
+ */
+export hook useDelayGroup(skipDelay: number): DelayGroup {
+  const skipping = useRef(false);
+  const timer = useRef<TimeoutID | null>(null);
+
+  const stop = useStableCallback(() => {
+    if (timer.current != null) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+  });
+
+  useEffect(() => stop, [stop]);
+
+  return useMemo(
+    () => ({
+      closed: () => {
+        stop();
+        if (skipDelay <= 0) {
+          skipping.current = false;
+          return;
+        }
+        skipping.current = true;
+        timer.current = setTimeout(() => {
+          timer.current = null;
+          skipping.current = false;
+        }, skipDelay);
+      },
+      delayFor: (own: number) => (skipping.current ? 0 : own),
+      opened: () => {
+        // While one is open the group is answering instantly, and the window
+        // does not start counting down until it closes.
+        stop();
+        skipping.current = true;
+      },
+    }),
+    [skipDelay, stop],
+  );
+}
+
+/**
+ * Close on `Escape`, from wherever focus happens to be.
+ *
+ * On the document, because the content shown on hover holds no focus and a
+ * handler on it would never be reached — which is exactly why the hand-written
+ * version fails the dismissible clause rather than implementing it wrongly.
+ *
+ * Capture, and `stopPropagation`, so one `Escape` is one dismissal: a tooltip
+ * inside a dialog answers the key itself rather than leaving the reader with a
+ * dialog that closed because a tooltip was showing.
+ */
+export hook useDismissOnEscape(
+  open: boolean,
+  ref: { current: HTMLElement | null },
+  onDismiss: () => void,
+): void {
+  const dismiss = useStableCallback(onDismiss);
+
+  useEffect(() => {
+    const document = ref.current?.ownerDocument;
+    if (!open || document == null) {
+      return;
+    }
+    const onKeyDown = (event: $FlowFixMe) => {
+      if (event.key !== "Escape") {
+        return;
+      }
+      event.stopPropagation();
+      dismiss();
+    };
+    document.addEventListener("keydown", onKeyDown, true);
+    return () => document.removeEventListener("keydown", onKeyDown, true);
+  }, [open, ref, dismiss]);
+}
+
+/**
+ * Refuse a trigger the keyboard cannot reach.
+ *
+ * A tooltip on a `<span>` is a tooltip only a mouse can find, and it looks
+ * perfect: the markup is right, the styles are right, and a reader who never
+ * touches a mouse is told nothing at all. It is the failure this package exists
+ * to make loud, so it is an error rather than a warning — the same answer
+ * `useDialog` gives to a part outside its root.
+ *
+ * Checked in an effect because it is a question about an element, and the
+ * element does not exist until one has been committed.
+ */
+export hook useFocusableTrigger(ref: { current: HTMLElement | null }, part: string): void {
+  useEffect(() => {
+    const element = ref.current;
+    if (element == null || element.matches(FOCUS_STOPS)) {
+      return;
+    }
+    throw new Error(
+      `${part} must be something the keyboard can reach: it was rendered onto ` +
+        `<${element.tagName.toLowerCase()}>, which is not focusable, so the ` +
+        `content would only ever appear for a pointer. Render a button or a ` +
+        `link, or give the element a tabindex of 0. A disabled control is not ` +
+        `focusable either: use aria-disabled and keep it in the tab order.`,
+    );
+  }, [ref, part]);
+}

package/internal/merge-props.js

@@ -146,6 +146,38 @@ export function composeRefs<T>(
   };
 }
 
+/**
+ * Two sets of props, the component's on top.
+ *
+ * The same rule as everywhere else in this package, applied where the element
+ * is the *caller's* rather than the component's: `Tooltip.Trigger` and
+ * `HoverCard.Trigger` hand their attributes to a render function so a caller
+ * can put them on a link or a menu item of their own, and the attributes that
+ * make the trigger work — the `aria-describedby` naming the content, the ref
+ * the content is measured against — have to survive whatever the caller passed
+ * alongside them.
+ *
+ * A spread would say this in one line and cannot be written: Flow declines to
+ * compute a type for `{ ...base, name: value }` when `base` has an indexer,
+ * because the indexer may overwrite the named key in a way it cannot track.
+ * The loop is that spread, with `key` dropped for the reason `withoutComposed`
+ * gives.
+ */
+export function withProps(base: Rest, ours: Rest): Rest {
+  const merged: { key?: empty, [string]: mixed } = {};
+  for (const name of Object.keys(base)) {
+    if (name !== "key") {
+      merged[name] = base[name];
+    }
+  }
+  for (const name of Object.keys(ours)) {
+    if (name !== "key") {
+      merged[name] = ours[name];
+    }
+  }
+  return merged;
+}
+
 /**
  * A caller's props with the handlers and ref removed.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/ui",
-  "version": "0.0.0-alpha.8",
+  "version": "0.0.0-alpha.9",
   "description": "Headless, accessible React components whose composition Flow checks, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -18,9 +18,11 @@
     "./combobox": "./combobox.js",
     "./dialog": "./dialog.js",
     "./field": "./field.js",
+    "./hover-card": "./hover-card.js",
     "./menu": "./menu.js",
     "./navigation-menu": "./navigation-menu.js",
     "./pagination": "./pagination.js",
+    "./popover": "./popover.js",
     "./progress": "./progress.js",
     "./radio-group": "./radio-group.js",
     "./resizable": "./resizable.js",
@@ -31,15 +33,16 @@
     "./tabs": "./tabs.js",
     "./toast": "./toast.js",
     "./toggle": "./toggle.js",
-    "./toggle-group": "./toggle-group.js"
+    "./toggle-group": "./toggle-group.js",
+    "./tooltip": "./tooltip.js"
   },
   "files": [
     "*.js",
     "internal"
   ],
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.8",
-    "@uniflowed/react": "0.0.0-alpha.8"
+    "@uniflowed/hooks": "0.0.0-alpha.9",
+    "@uniflowed/react": "0.0.0-alpha.9"
   },
   "peerDependencies": {
     "react": ">=19"

package/popover.js

@@ -0,0 +1,326 @@
+// @flow
+//
+// A popover: a dialog that is not modal, which is the whole of the difference.
+//
+// `dialog.js` is modal and only modal, on purpose — every line of it is a
+// promise that the rest of the page is unavailable. A popover makes the
+// opposite promise, and it has to make it in every one of the same places:
+//
+//   * No `aria-modal`, because the page behind is still there.
+//   * Nothing is made `inert` and nothing is `aria-hidden`, because a reader
+//     may still reach it.
+//   * The page is not scroll-locked, because a wheel over a popover scrolling
+//     the page behind is what a reader expects from something that did not
+//     take the page over.
+//   * **`Tab` leaves.** This is the load-bearing one. A trap is what makes a
+//     modal dialog safe and what makes a popover a hole a reader falls into:
+//     they tabbed in, they tab out, and a component that wraps them back to
+//     the first control has taken the page away without ever saying so.
+//
+// So a popover is not a `Dialog` with a flag. A flag would mean every one of
+// the behaviours above reading it, and the failure of the one that forgot would
+// be a dialog that is not modal while announcing that it is — silent, and
+// wrong in the direction that traps people.
+//
+// What it *does* share with a dialog is the part a reader notices when it is
+// missing: focus moves into it when it opens, `Escape` closes it, and focus
+// goes back to the trigger — unless the reader dismissed it by pressing or
+// tabbing somewhere else, in which case it stays where they put it.
+//
+// # Where it goes
+//
+// `internal/anchor.js`, the same as every other overlay here: `side`, `align`,
+// `sideOffset` and `alignOffset` place it against the trigger, it flips and
+// slides to stay on the screen, and it reports where it ended up as `data-side`
+// and `data-align` so a stylesheet can point an arrow without measuring
+// anything itself.
+//
+// # Its name
+//
+// `role="dialog"` needs an accessible name, and a popover has no `Title` part
+// to take one from — shadcn's does not either, and adding one would make the
+// common case (a form, a colour picker, a date picker) carry a heading nobody
+// asked for. So the body is named after the button that opened it, which is
+// true and is what a reader would say the popover is, and a caller who passes
+// `aria-label` or `aria-labelledby` of their own keeps it.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+import { useStableCallback } from "@uniflowed/hooks/lifecycle";
+
+import type { Align, Side } from "./internal/anchor.js";
+import type { Rest } from "./internal/merge-props.js";
+import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
+import { focusable } from "./internal/focus.js";
+import { useAnchor } from "./internal/anchor.js";
+import { useControlled } from "./internal/controlled-state.js";
+import { usePresence } from "./internal/disclosure.js";
+
+export type { Align, Side } from "./internal/anchor.js";
+
+type PopoverState = {|
+  readonly base: string,
+  readonly open: boolean,
+  readonly setOpen: (open: boolean) => void,
+  /** What opened it, where it is anchored, and where focus goes back to. */
+  readonly triggerRef: { current: HTMLElement | null },
+  /**
+   * Whether a trigger is rendered, so the body only names one that exists.
+   *
+   * A popover opened by `defaultOpen` in a page with no trigger is a real
+   * arrangement — a first-run hint pointing at something — and an
+   * `aria-labelledby` naming the id that trigger *would* have had makes a
+   * screen reader announce nothing at all.
+   */
+  readonly triggered: boolean,
+  readonly registerTrigger: (present: boolean) => void,
+|};
+
+const PopoverContext: React.Context<PopoverState | null> = createContext(null);
+
+/**
+ * The popover a part belongs to.
+ *
+ * Raising rather than returning null, for the reason `useDialog` gives: a
+ * `Popover.Body` outside a root would render a `role="dialog"` that nothing
+ * opens, closes or names, and it would look correct.
+ */
+hook usePopover(part: string): PopoverState {
+  const state = useContext(PopoverContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Popover.Root`);
+  }
+  return state;
+}
+
+/**
+ * The popover, open or closed. Uncontrolled unless `open` is given.
+ *
+ * Renders no element of its own: the trigger and the body are siblings in
+ * whatever layout the caller wrote, and a wrapper would put a `<div>` between
+ * them for the caller to style around.
+ */
+export component PopoverRoot(
+  children: React.Node,
+  defaultOpen?: boolean = false,
+  open?: boolean,
+  onOpenChange?: (open: boolean) => void,
+) {
+  const base = useId();
+  const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const [triggered, setTriggered] = useState(false);
+
+  const state = useMemo(
+    () => ({
+      base,
+      open: isOpen,
+      registerTrigger: setTriggered,
+      setOpen,
+      triggerRef,
+      triggered,
+    }),
+    [base, isOpen, setOpen, triggered],
+  );
+
+  return <PopoverContext.Provider value={state}>{children}</PopoverContext.Provider>;
+}
+
+/**
+ * The button that opens the popover, and what it is anchored to.
+ *
+ * A toggle rather than an opener: pressing the button of an open popover closes
+ * it, which is what every disclosure does and what a reader who pressed it by
+ * accident expects. The outside-press handler in `Popover.Body` knows the
+ * trigger is not "outside" for exactly this reason — closing there and letting
+ * this click reopen made the press a no-op that flickered.
+ */
+export component PopoverTrigger(children: React.Node, ...rest: Rest) {
+  const popover = usePopover("Popover.Trigger");
+  const passed = withoutComposed(rest, ["onClick", "ref"]);
+  usePresence(popover.registerTrigger);
+
+  return (
+    <button
+      {...passed}
+      // Only while it is open: an `aria-controls` naming an element that is not
+      // in the document tells a reader there is somewhere to go and then has
+      // nowhere to send them.
+      aria-controls={popover.open ? `${popover.base}-body` : undefined}
+      aria-expanded={popover.open ? "true" : "false"}
+      aria-haspopup="dialog"
+      id={`${popover.base}-trigger`}
+      onClick={composeHandlers(rest.onClick, () => popover.setOpen(!popover.open))}
+      ref={composeRefs(rest.ref, (element) => {
+        popover.triggerRef.current = element;
+      })}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+/**
+ * The popover itself: positioned, focused, dismissible, and not a trap.
+ *
+ * The three ways out are the three a reader tries. `Escape` closes it and gives
+ * focus back to the trigger, because the reader is still where they were. A
+ * press outside closes it and leaves focus alone, because they have already
+ * moved on. `Tab` past the last control inside closes it for the same reason
+ * and leaves focus where the browser put it — which is the behaviour that
+ * separates this from a dialog, and the one a copy of `dialog.js` with the
+ * `aria-modal` deleted would get wrong.
+ */
+export component PopoverBody(
+  children: React.Node,
+  align?: Align = "center",
+  alignOffset?: number = 0,
+  avoidCollisions?: boolean = true,
+  collisionPadding?: number = 0,
+  side?: Side = "bottom",
+  sideOffset?: number = 0,
+  ...rest: Rest
+) {
+  const popover = usePopover("Popover.Body");
+  const bodyRef = useRef<HTMLElement | null>(null);
+  // Stable, so the effect below depends on `open` and on nothing else. Keyed on
+  // `setOpen` it re-ran whenever the caller passed a fresh `onOpenChange`
+  // closure — which is every render — and re-running it took focus back from
+  // wherever the reader had moved it inside the popover.
+  const close = useStableCallback(() => popover.setOpen(false));
+  // Set when the reader left rather than closed: a press outside, or a Tab that
+  // carried them out. Focus is theirs from then on, and dragging it back to the
+  // trigger would undo the thing they just did.
+  const left = useRef(false);
+  const triggerRef = popover.triggerRef;
+
+  const anchored = useAnchor({
+    align,
+    alignOffset,
+    anchorRef: triggerRef,
+    avoidCollisions,
+    collisionPadding,
+    open: popover.open,
+    overlayRef: bodyRef,
+    side,
+    sideOffset,
+  });
+
+  useEffect(() => {
+    const body = bodyRef.current;
+    if (!popover.open || body == null) {
+      return;
+    }
+    const document = body.ownerDocument;
+    const trigger = triggerRef.current;
+    // Whatever had focus, which is the trigger for a popover that was opened
+    // and the previously focused element for one that opened itself.
+    const opener = trigger ?? (document.activeElement as $FlowFixMe);
+
+    const outside = (target: EventTarget | null): boolean => {
+      const node: $FlowFixMe = target;
+      // The trigger is outside the body and is not "outside" for this purpose.
+      return node != null && !body.contains(node) && !(trigger?.contains(node) ?? false);
+    };
+
+    const onOutsidePress = (event: Event) => {
+      if (!outside(event.target)) {
+        return;
+      }
+      left.current = true;
+      close();
+    };
+    // Capture, so a press is seen even where something below it stops the
+    // event — a menu inside the popover, for instance.
+    document.addEventListener("pointerdown", onOutsidePress, true);
+
+    // Tab out is a dismissal, not an escape hatch that leaves a popover open
+    // behind the reader: a non-modal overlay whose reader has gone is one they
+    // can no longer press Escape at, because Escape is handled where focus is.
+    const onFocusMoved = (event: Event) => {
+      if (!outside(event.target)) {
+        return;
+      }
+      left.current = true;
+      close();
+    };
+    document.addEventListener("focusin", onFocusMoved, true);
+
+    // The first thing worth acting on, and the popover itself when it holds
+    // nothing focusable, so focus is inside it either way and Escape reaches
+    // the handler below.
+    (focusable(body)[0] ?? body).focus();
+
+    return () => {
+      document.removeEventListener("pointerdown", onOutsidePress, true);
+      document.removeEventListener("focusin", onFocusMoved, true);
+      if (left.current) {
+        left.current = false;
+        return;
+      }
+      // Only when focus would otherwise be lost to `<body>`, the same
+      // condition `menu.js` restores under: a popover closed by a control
+      // inside it that moved focus somewhere deliberate must not have that
+      // undone.
+      const active = document.activeElement;
+      if (active == null || active === document.body || body.contains(active)) {
+        opener?.focus?.();
+      }
+    };
+  }, [popover.open, triggerRef, close]);
+
+  if (!popover.open) {
+    return null;
+  }
+
+  const passed = withoutComposed(rest, ["onKeyDown", "ref"]);
+  // Named by its trigger unless the caller said otherwise. Setting it anyway
+  // would override an `aria-label` they passed — `aria-labelledby` wins — and
+  // leave the popover announced as its button rather than as itself.
+  const named = rest["aria-label"] != null || rest["aria-labelledby"] != null;
+
+  return (
+    <div
+      // `passed` first, then this component's semantics; see
+      // `internal/merge-props.js` for the three bugs that rule is made of.
+      {...passed}
+      aria-labelledby={named || !popover.triggered ? undefined : `${popover.base}-trigger`}
+      data-align={anchored.align}
+      data-side={anchored.side}
+      data-state="open"
+      id={`${popover.base}-body`}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        if (event.key !== "Escape") {
+          return;
+        }
+        event.preventDefault();
+        // This popover, not the dialog around it. Two overlays nest in the
+        // DOM, so without this one Escape closed both.
+        event.stopPropagation();
+        close();
+      })}
+      ref={composeRefs(rest.ref, (element) => {
+        bodyRef.current = element;
+      })}
+      // No `aria-modal`. The page behind a popover is still available, and
+      // saying otherwise is the one lie a screen reader cannot see through.
+      role="dialog"
+      // So the popover can hold focus itself when it contains nothing
+      // focusable, and so Escape has somewhere to be heard.
+      tabIndex={-1}
+    >
+      {children}
+    </div>
+  );
+}