@uniflowed/ui 0.0.0-alpha.2 → 0.0.0-alpha.37

package/tooltip.js

@@ -0,0 +1,400 @@
+// @flow
+//
+// A tooltip: the component most likely to make a page *worse* than the plain
+// HTML it replaced.
+//
+// The failure is specified rather than a matter of taste. WCAG 2.1 SC 1.4.13,
+// *Content on Hover or Focus*, requires content shown that way to be
+// dismissible with `Escape`, hoverable — the pointer can travel onto it —  and
+// persistent until one of those things ends it. A `title` attribute fails all
+// three: it is on the browser's clock, it cannot be hovered, and `Escape` does
+// nothing. A `div` that appears on `:hover` fails the first two. Those are the
+// two things a project without this component writes.
+//
+// `internal/hover-intent.js` holds all three clauses, because they are one
+// mechanism and separating them is how a component ends up with two of them.
+//
+// # What a tooltip is not
+//
+// It is **not focusable**, and nothing in it may be. A tooltip that takes focus
+// puts a stop in the tab order the reader did not ask for and cannot leave in
+// the direction they expect; the APG says so, and it is why anything with a
+// link or a button in it is a `HoverCard` and not this. It carries
+// `role="tooltip"` and describes its trigger with `aria-describedby` — and only
+// while it is in the document, because a reference to an element that is not
+// there makes a screen reader announce nothing at all.
+//
+// It has **no `aria-haspopup`**. That attribute promises an interactive popup,
+// and a reader who is told a button has one and then finds nothing to interact
+// with has been sent somewhere that does not exist.
+//
+// # The delay, and the one that must not be there
+//
+// A pointer resting on a trigger opens the tooltip after a delay; a pointer
+// crossing a toolbar on its way elsewhere passes six triggers and must open
+// none of them. **Focus opens it with no delay at all** — a reader who tabbed
+// to a control has already said what they want, and a wait exists to filter out
+// intent nobody expressed.
+//
+// `Tooltip.Provider` shares one clock between a group of tooltips, so the
+// second icon in a toolbar answers immediately once the reader has waited out
+// the first. A tooltip outside a provider is a complete tooltip and keeps its
+// own delay.
+//
+// # Touch, which is a decision rather than an accident
+//
+// **This does not open on touch.** There is no hover on a touch screen, so the
+// only gesture left is the tap — and a tooltip that opens on tap either
+// swallows the tap the control needed or shows content the next tap dismisses
+// before it has been read. Both are worse than nothing.
+//
+// What follows from that is a rule for the caller rather than for this module:
+// a tooltip may not be the only place something is said. If the trigger is an
+// icon button, the tooltip's text is what a reader on a phone needs *as the
+// button's name* — so give the button an `aria-label` and let the tooltip
+// repeat it. `pointerenter` is ignored for a touch pointer here, which is what
+// stops the tap being eaten.
+//
+// # Why the pointer is watched natively
+//
+// `pointerenter` and `pointerleave` are the platform's way of saying the
+// pointer arrived at *this* element; React's `onPointerEnter` is its own
+// reconstruction of them from `pointerover` and `pointerout`. The reconstruction
+// is faithful and it is not the same event — and the property this component
+// has to read to know a tap from a hover, `pointerType`, belongs to the pointer
+// event the platform sent. So the listeners go on the element, through
+// `@uniflowed/hooks`' `useEventListener`, which is also what stops a caller's
+// `render` function from dropping a handler by forgetting to spread it.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useEffect, useId, useMemo, useRef } from "@uniflowed/react";
+import { useEventListener } from "@uniflowed/hooks/dom";
+import { useStableCallback } from "@uniflowed/hooks/lifecycle";
+
+import type { Align, LogicalSide } from "./internal/anchor.js";
+import type { DelayGroup, HoverIntent } from "./internal/hover-intent.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { composeRefs, withProps, withoutComposed } from "./internal/merge-props.js";
+import {
+  DEFAULT_CLOSE_DELAY,
+  DEFAULT_OPEN_DELAY,
+  DEFAULT_SKIP_DELAY,
+  useDelayGroup,
+  useDismissOnEscape,
+  useFocusableTrigger,
+  useHoverIntent,
+} from "./internal/hover-intent.js";
+import { useAnchor } from "./internal/anchor.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+export type { Align, LogicalSide, Side } from "./internal/anchor.js";
+
+/** What a `Tooltip.Provider` shares with the tooltips inside it. */
+type TooltipScope = {|
+  /** The default `openDelay` for every tooltip in the group. */
+  readonly delayDuration: number,
+  readonly group: DelayGroup,
+|};
+
+const TooltipScopeContext: React.Context<TooltipScope | null> = createContext(null);
+
+type TooltipState = {|
+  readonly base: string,
+  readonly open: boolean,
+  readonly setOpen: (open: boolean) => void,
+  readonly triggerRef: { current: HTMLElement | null },
+  readonly intent: HoverIntent,
+  /**
+   * How long a pointer must rest before this tooltip opens, asked at the moment
+   * it arrives rather than read from a render.
+   *
+   * A function because the answer is the group's and changes as the reader
+   * moves: the same tooltip waits the full delay when it is the first one
+   * touched and opens at once when it is the second.
+   */
+  readonly openDelay: () => number,
+  readonly closeDelay: number,
+  /**
+   * Whether `Escape` has dismissed it while the reader is still here.
+   *
+   * A ref rather than state because nothing renders it, and because what it
+   * guards happens inside an event handler: without it, a dismissal is undone
+   * by the very next thing the pointer or focus does — which for a hover card
+   * is the focus it hands back to its own trigger, and is a component that
+   * cannot be closed. It is cleared when the reader leaves the trigger, so
+   * coming back opens it again.
+   */
+  readonly dismissed: { current: boolean },
+|};
+
+const TooltipContext: React.Context<TooltipState | null> = createContext(null);
+
+hook useTooltip(part: string): TooltipState {
+  const state = useContext(TooltipContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Tooltip.Root`);
+  }
+  return state;
+}
+
+/**
+ * One clock for a group of tooltips.
+ *
+ * `delayDuration` is the delay each tooltip inside uses unless it sets its own,
+ * so a toolbar says it once. `skipDelayDuration` is the window after one closes
+ * during which the next opens immediately — the interaction that makes a row of
+ * icon buttons readable rather than tedious.
+ *
+ * Renders no element: it is a context and a clock, and a `<div>` around a
+ * toolbar is the caller's business.
+ */
+export component TooltipProvider(
+  children: React.Node,
+  delayDuration?: number = DEFAULT_OPEN_DELAY,
+  skipDelayDuration?: number = DEFAULT_SKIP_DELAY,
+) {
+  const group = useDelayGroup(skipDelayDuration);
+  const scope = useMemo(() => ({ delayDuration, group }), [delayDuration, group]);
+
+  return <TooltipScopeContext.Provider value={scope}>{children}</TooltipScopeContext.Provider>;
+}
+
+/**
+ * One tooltip and its trigger.
+ *
+ * `openDelay` falls back to the enclosing `Tooltip.Provider`'s
+ * `delayDuration`, and to 700ms when there is no provider — a tooltip on its
+ * own is a complete tooltip and needs nothing around it.
+ */
+export component TooltipRoot(
+  children: React.Node,
+  closeDelay?: number = DEFAULT_CLOSE_DELAY,
+  defaultOpen?: boolean = false,
+  onOpenChange?: (open: boolean) => void,
+  open?: boolean,
+  openDelay?: number,
+) {
+  const base = useId();
+  const scope = useContext(TooltipScopeContext);
+  const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const dismissed = useRef(false);
+  const intent = useHoverIntent(setOpen);
+  const own = openDelay ?? scope?.delayDuration ?? DEFAULT_OPEN_DELAY;
+  const group = scope?.group;
+
+  // What this tooltip last told the group, so that mounting closed says
+  // nothing — a page of six tooltips would otherwise open six skip windows
+  // before the reader had touched anything.
+  const told = useRef(false);
+  useEffect(() => {
+    if (group == null || told.current === isOpen) {
+      return;
+    }
+    told.current = isOpen;
+    if (isOpen) {
+      group.opened();
+    } else {
+      group.closed();
+    }
+  }, [group, isOpen]);
+
+  // A tooltip taken away while it was showing has to say so, or the group is
+  // left believing one is open and answers every later hover instantly.
+  useEffect(
+    () => () => {
+      if (told.current) {
+        told.current = false;
+        group?.closed();
+      }
+    },
+    [group],
+  );
+
+  const state = useMemo(
+    () => ({
+      base,
+      closeDelay,
+      dismissed,
+      intent,
+      open: isOpen,
+      openDelay: () => group?.delayFor(own) ?? own,
+      setOpen,
+      triggerRef,
+    }),
+    [base, closeDelay, group, intent, isOpen, own, setOpen],
+  );
+
+  return <TooltipContext.Provider value={state}>{children}</TooltipContext.Provider>;
+}
+
+/**
+ * What the tooltip describes.
+ *
+ * A `<button>` by default, and whatever the caller renders when they pass
+ * `render` — a link, a menu item, an icon button of their own. Either way it
+ * has to be something the keyboard can reach, and `useFocusableTrigger` refuses
+ * anything else: a tooltip on a `<span>` is a tooltip only a mouse can find,
+ * and it looks perfect in the markup.
+ *
+ * Every handler is attached to the element rather than passed as a prop, so a
+ * `render` function that forgets to spread something still gets a working
+ * tooltip; see the module header.
+ */
+export component TooltipTrigger(children?: React.Node, render?: RenderProp, ...rest: Rest) {
+  const tooltip = useTooltip("Tooltip.Trigger");
+  const { closeDelay, dismissed, intent, openDelay, setOpen, triggerRef } = tooltip;
+  useFocusableTrigger(triggerRef, "Tooltip.Trigger");
+
+  // Whether the pointer put focus here. A click focuses the button, and
+  // reopening the tooltip the click just dismissed would put it back over the
+  // thing the reader pressed — so a focus that arrived with a press opens
+  // nothing, and the next one, which is the keyboard's, does.
+  const pressed = useRef(false);
+
+  useEventListener(triggerRef, "pointerenter", (event: $FlowFixMe) => {
+    // A tap is not a hover. See the module header: opening here is what eats
+    // the tap the control was there to receive.
+    if (event.pointerType === "touch" || dismissed.current) {
+      return;
+    }
+    intent.openAfter(openDelay());
+  });
+  useEventListener(triggerRef, "pointerleave", () => {
+    // Leaving is what makes a dismissal stop applying: coming back is a fresh
+    // gesture and deserves a fresh answer.
+    dismissed.current = false;
+    intent.closeAfter(closeDelay);
+  });
+  useEventListener(triggerRef, "pointerdown", () => {
+    pressed.current = true;
+    intent.cancel();
+    setOpen(false);
+  });
+  useEventListener(triggerRef, "focusin", () => {
+    if (pressed.current) {
+      pressed.current = false;
+      return;
+    }
+    if (dismissed.current) {
+      return;
+    }
+    // No delay: the reader has already said what they want by arriving here.
+    intent.openAfter(0);
+  });
+  useEventListener(triggerRef, "focusout", () => {
+    pressed.current = false;
+    dismissed.current = false;
+    intent.closeAfter(0);
+  });
+
+  // Annotated because this one is not written inside a `ref={...}`, and there
+  // is nothing else here for Flow to infer the element's type from.
+  const attach = composeRefs(rest.ref, (element: HTMLElement | null) => {
+    triggerRef.current = element;
+  });
+  // Only while it is there. `aria-describedby` pointing at an element that has
+  // been removed is the dangling reference this package keeps coming back to.
+  const props = withProps(withoutComposed(rest, ["ref"]), {
+    "aria-describedby": tooltip.open ? `${tooltip.base}-body` : undefined,
+    children,
+    ref: attach,
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
+}
+
+/**
+ * The tooltip itself.
+ *
+ * Hoverable, which is the clause every hand-written tooltip fails: the pointer
+ * arriving here calls off the close the trigger scheduled when the pointer
+ * left it, so the trip across the gap does not take the content away. It never
+ * takes focus, holds no tab stop, and answers `Escape` from wherever focus
+ * happens to be.
+ */
+export component TooltipBody(
+  children: React.Node,
+  align?: Align = "center",
+  alignOffset?: number = 0,
+  avoidCollisions?: boolean = true,
+  collisionPadding?: number = 0,
+  render?: RenderProp,
+  side?: LogicalSide = "top",
+  sideOffset?: number = 0,
+  ...rest: Rest
+) {
+  const tooltip = useTooltip("Tooltip.Body");
+  const { closeDelay, intent, open, triggerRef } = tooltip;
+  const bodyRef = useRef<HTMLElement | null>(null);
+  const close = useStableCallback(() => {
+    // `Escape` dismisses it *and* keeps it dismissed while the reader is still
+    // on the trigger. Without the flag the pointer that is still resting there
+    // — or, for a hover card, the focus it hands back — reopens it at once,
+    // and the key does nothing a reader can see.
+    tooltip.dismissed.current = true;
+    intent.cancel();
+    tooltip.setOpen(false);
+  });
+
+  const anchored = useAnchor({
+    align,
+    alignOffset,
+    anchorRef: triggerRef,
+    avoidCollisions,
+    collisionPadding,
+    open,
+    overlayRef: bodyRef,
+    side,
+    sideOffset,
+  });
+
+  useDismissOnEscape(open, bodyRef, close);
+
+  // Keyed on `open` rather than written with `useEventListener`, and the
+  // difference is load-bearing: that hook reads its target once, when it
+  // attaches, and this element does not exist until the tooltip opens. It is
+  // the same trap `select.js` documents about its outside-press listener.
+  useEffect(() => {
+    const body = bodyRef.current;
+    if (!open || body == null) {
+      return;
+    }
+    const stay = () => intent.cancel();
+    const go = () => intent.closeAfter(closeDelay);
+    body.addEventListener("pointerenter", stay);
+    body.addEventListener("pointerleave", go);
+    return () => {
+      body.removeEventListener("pointerenter", stay);
+      body.removeEventListener("pointerleave", go);
+    };
+  }, [open, intent, closeDelay]);
+
+  if (!open) {
+    return null;
+  }
+
+  const props = withProps(withoutComposed(rest, ["ref"]), {
+    children,
+    "data-align": anchored.align,
+    "data-side": anchored.side,
+    "data-state": "open",
+    id: `${tooltip.base}-body`,
+    ref: composeRefs(rest.ref, (element) => {
+      bodyRef.current = element;
+    }),
+    role: "tooltip",
+    // No `tabIndex`. A tooltip the keyboard can land in is a stop the reader
+    // did not ask for and cannot leave the way they expect.
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
+}

package/internal/dialog.js

@@ -1,236 +0,0 @@
-// @flow
-//
-// A modal dialog, which is the component people most often get wrong.
-//
-// Four things have to be true for a dialog to be usable by someone who is not
-// using a mouse, and a hand-written one usually has one or two of them:
-//
-//   * Focus moves into the dialog when it opens, and to the first thing worth
-//     acting on rather than to whatever happens to be first in the document.
-//   * Tab cannot leave. A dialog you can Tab out of leaves the reader
-//     somewhere in a page they cannot see, with no way back.
-//   * Escape closes it.
-//   * Focus returns to whatever opened it. Otherwise it restarts at the top of
-//     the document, and the reader has to find their place again.
-//
-// The dialog is rendered where it is declared rather than through a portal.
-// A portal solves a stacking-context problem that belongs to CSS, and it costs
-// the thing this component is for: rendered in place, the dialog is next to its
-// trigger in the accessibility tree, which is where a screen reader looks.
-
-import * as React from "@uniflowed/react";
-
-import { composeHandlers, composeRefs, withoutComposed } from "./props.js";
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useId,
-  useMemo,
-  useRef,
-  useState,
-} from "@uniflowed/react";
-
-type DialogState = {|
-  readonly base: string,
-  readonly open: boolean,
-  readonly setOpen: (open: boolean) => void,
-  readonly triggerRef: { current: HTMLElement | null },
-|};
-
-const DialogContext: React.Context<DialogState | null> = createContext(null);
-
-function useDialog(part: string): DialogState {
-  const state = useContext(DialogContext);
-  if (state == null) {
-    throw new Error(`${part} must be rendered inside a Dialog.Root`);
-  }
-  return state;
-}
-
-/** The dialog, open or closed. Uncontrolled unless `open` is given. */
-export component DialogRoot(
-  children: React.Node,
-  defaultOpen?: boolean = false,
-  open?: boolean,
-  onOpenChange?: (open: boolean) => void,
-) {
-  const base = useId();
-  const [internal, setInternal] = useState(defaultOpen);
-  const triggerRef = useRef<HTMLElement | null>(null);
-  const isOpen = open ?? internal;
-
-  const setOpen = useCallback(
-    (next: boolean) => {
-      if (open == null) {
-        setInternal(next);
-      }
-      onOpenChange?.(next);
-    },
-    [open, onOpenChange],
-  );
-
-  const state = useMemo(
-    () => ({ base, open: isOpen, setOpen, triggerRef }),
-    [base, isOpen, setOpen],
-  );
-
-  return <DialogContext.Provider value={state}>{children}</DialogContext.Provider>;
-}
-
-/** What opens the dialog, and what focus comes back to when it closes. */
-export component DialogTrigger(children: React.Node, ...rest: { readonly [string]: mixed }) {
-  const dialog = useDialog("Dialog.Trigger");
-  const passed = withoutComposed(rest, ["onClick", "ref"]);
-
-  return (
-    <button
-      {...passed}
-      aria-expanded={dialog.open ? "true" : "false"}
-      aria-haspopup="dialog"
-      onClick={composeHandlers(rest.onClick, () => dialog.setOpen(true))}
-      ref={composeRefs(rest.ref, (element) => {
-        dialog.triggerRef.current = element;
-      })}
-      type="button"
-    >
-      {children}
-    </button>
-  );
-}
-
-/**
- * The dialog itself: focus moved in, Tab kept inside, Escape closing it.
- *
- * `aria-modal` tells a screen reader that the rest of the page is not
- * available, which is the half of "modal" that CSS cannot express.
- */
-export component DialogContent(children: React.Node, ...rest: { readonly [string]: mixed }) {
-  const dialog = useDialog("Dialog.Content");
-  const contentRef = useRef<HTMLElement | null>(null);
-
-  useEffect(() => {
-    if (!dialog.open) {
-      return;
-    }
-    const opener = dialog.triggerRef.current;
-    const content = contentRef.current;
-    // The first thing worth acting on, not the first thing in the document —
-    // and the dialog itself if it contains nothing focusable, so focus is
-    // inside it either way.
-    const target = content == null ? null : (focusable(content)[0] ?? content);
-    target?.focus();
-
-    return () => {
-      // Back to the trigger. Leaving focus on a removed node sends it to the
-      // top of the document, and the reader has to find their place again.
-      opener?.focus();
-    };
-  }, [dialog.open, dialog.triggerRef]);
-
-  if (!dialog.open) {
-    return null;
-  }
-
-  const passed = withoutComposed(rest, ["onKeyDown", "ref"]);
-
-  return (
-    <div
-      // `passed` first. A caller `ref` used to replace `contentRef`, which
-      // left it null, made the Tab branch below return early, and turned the
-      // focus trap off while the dialog still announced `aria-modal="true"`.
-      // A caller `onKeyDown` used to replace this one, and Escape stopped
-      // closing the dialog.
-      {...passed}
-      aria-labelledby={`${dialog.base}-title`}
-      aria-modal="true"
-      id={`${dialog.base}-content`}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        if (event.key === "Escape") {
-          event.preventDefault();
-          dialog.setOpen(false);
-          return;
-        }
-        if (event.key !== "Tab") {
-          return;
-        }
-        const content = contentRef.current;
-        if (content == null) {
-          return;
-        }
-        const stops = focusable(content);
-        if (stops.length === 0) {
-          // Nothing to move to, so Tab must not leave either.
-          event.preventDefault();
-          return;
-        }
-        const first = stops[0];
-        const last = stops[stops.length - 1];
-        const active = content.ownerDocument?.activeElement;
-        // Wrap at the ends. This is the whole of "focus cannot leave": every
-        // other Tab press is the browser's own business.
-        if (event.shiftKey && (active === first || active === content)) {
-          event.preventDefault();
-          last.focus();
-        } else if (!event.shiftKey && active === last) {
-          event.preventDefault();
-          first.focus();
-        }
-      })}
-      ref={composeRefs(rest.ref, (element) => {
-        contentRef.current = element;
-      })}
-      role="dialog"
-      tabIndex={-1}
-    >
-      {children}
-    </div>
-  );
-}
-
-/** The dialog's accessible name, which `aria-labelledby` points at. */
-export component DialogTitle(children: React.Node, ...rest: { readonly [string]: mixed }) {
-  const dialog = useDialog("Dialog.Title");
-  return (
-    <h2 {...rest} id={`${dialog.base}-title`}>
-      {children}
-    </h2>
-  );
-}
-
-/** A button that closes the dialog. */
-export component DialogClose(children: React.Node, ...rest: { readonly [string]: mixed }) {
-  const dialog = useDialog("Dialog.Close");
-  const passed = withoutComposed(rest, ["onClick"]);
-
-  return (
-    <button
-      {...passed}
-      onClick={composeHandlers(rest.onClick, () => dialog.setOpen(false))}
-      type="button"
-    >
-      {children}
-    </button>
-  );
-}
-
-/**
- * The focus stops inside an element, in document order.
- *
- * Disabled controls and `tabindex="-1"` are excluded because the browser
- * excludes them, and anything inside `[hidden]` or `aria-hidden` is excluded
- * because a reader cannot see it.
- */
-function focusable(root: HTMLElement): Array<HTMLElement> {
-  const selector =
-    'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
-  return Array.from(root.querySelectorAll(selector)).filter(
-    (element: any) =>
-      // Both attributes hide a whole subtree, so both are checked on the
-      // ancestors. Reading `aria-hidden` off the element alone returned a
-      // button inside `<div aria-hidden="true">` as a focus stop, and the trap
-      // then moved focus to a control no screen reader exposes.
-      element.closest("[hidden]") == null && element.closest('[aria-hidden="true"]') == null,
-  );
-}