@uniflowed/ui 0.0.0-alpha.8 → 0.1.0

package/internal/disclosure.js

@@ -48,6 +48,58 @@
 // or re-adds the attribute and this upgrades it again. Nothing here writes an
 // attribute React believes it owns while React believes it.
 //
+// # The height a closed panel would have
+//
+// The third rule, and the one that took a piece of work rather than a line.
+// `height: 0 → var(--uf-collapsible-height)` is the whole of animating a
+// disclosure, and the number in that property is the one thing a stylesheet
+// cannot compute: it is the height the content *would* have, wanted at the
+// moment the panel is still closed, because a transition has to know its
+// destination before it starts.
+//
+// Every obvious way of getting it answers zero. A closed panel is `hidden`, so
+// it has no box: `ResizeObserver` reports `0`, `getBoundingClientRect()` is
+// empty, `scrollHeight` is `0`, and `useElementSize` from
+// `@uniflowed/hooks/dom` measures a hidden element and reports zero — which is
+// exactly the moment the number is wanted. Measuring after the panel opens
+// gives the right number one frame late, which is the jank this removes.
+//
+// So `useMeasuredHeight` lays the panel out without painting it: inline
+// `display`, `position: absolute` and `visibility: hidden`, read, restore. Four
+// things about that are not obvious:
+//
+//   * It overrides `display` inline rather than removing `hidden`. The
+//     attribute is `useUntilFound`'s and React's; an effect that took it away
+//     and put it back would be fighting both of them for one frame, and would
+//     lose whichever ran last. An inline declaration beats the user-agent
+//     stylesheet's `[hidden] { display: none }` and touches nothing anybody
+//     else believes they own.
+//   * It sets `content-visibility: visible` in the same pass, because
+//     `hidden="until-found"` is `content-visibility: hidden`, which does not lay
+//     its subtree out either. Defeating one of the two and not the other
+//     measures zero on exactly the panels this package ships.
+//   * It sets `height: auto` in the same pass, for the same reason and against
+//     the very rule this property exists for. A closed panel is `height: 0` —
+//     that is the half of `height: 0 → var(--uf-collapsible-height)` that is
+//     always on — so a panel laid out with the stylesheet still applying
+//     measures zero and writes `0px` back into the property it was asked to
+//     fill. Defeating `display` and not `height` is the same mistake as
+//     defeating `display` and not `content-visibility`, one declaration along.
+//   * And it pins the width, because taking a box out of flow makes it
+//     shrink-to-fit against its containing block — the nearest positioned
+//     ancestor, which on most pages is the viewport. Text that wraps to four
+//     lines where the panel lives measures one line there. The width it would
+//     have in flow is its parent's content box; when that cannot be read the
+//     pass leaves the width alone rather than inventing one.
+//
+// It is opt-in, and that is the honest answer to "it should cost nothing on a
+// page that never animates". Whether a stylesheet reads the property is not
+// something the component can ask — `getComputedStyle` on a `display: none`
+// element answers about the declaration, not about whether anybody transitions
+// on it — so the alternative to a prop is a forced layout per panel per render
+// on every page that has a collapsible, animated or not. A forty-section FAQ is
+// forty synchronous layouts nobody asked for.
+//
 // # Why this is `internal/` and not a subpath
 //
 // The same reason `roving-focus.js` gives. These are rules about markup this
@@ -95,3 +147,152 @@ export hook useUntilFound(ref: { current: HTMLElement | null }, open: boolean):
     element.setAttribute("hidden", "until-found");
   }, [ref, open]);
 }
+
+/** The custom property a stylesheet transitions a disclosure's height to. */
+export const HEIGHT_PROPERTY: string = "--uf-collapsible-height";
+
+/**
+ * The width `element` would have in flow, as a CSS length, or nothing.
+ *
+ * Taking the panel out of flow to measure it costs shrink-to-fit: an absolutely
+ * positioned box with `width: auto` is as wide as its *content* wants to be,
+ * bounded by its containing block — which is the nearest positioned ancestor
+ * and, on most pages, is the viewport rather than the panel's parent. A
+ * paragraph that wraps to four lines in a sidebar measures one line there, and
+ * the number written into the property is then a height the panel never has.
+ *
+ * The width it would have in flow is its parent's content box, which is what
+ * `getComputedStyle` reports for `width` on a laid-out element. Nothing is
+ * returned when the answer is not a length — a parent that is itself
+ * `display: none`, or a DOM with no layout to report — and the pass then does
+ * what it did before rather than pinning a width it had to guess.
+ */
+function widthInFlow(element: HTMLElement): string | null {
+  const parent = element.parentElement;
+  const view: $FlowFixMe = element.ownerDocument?.defaultView;
+  if (parent == null || view == null || typeof view.getComputedStyle !== "function") {
+    return null;
+  }
+  const width: mixed = view.getComputedStyle(parent).width;
+  return typeof width === "string" && width.endsWith("px") ? width : null;
+}
+
+/**
+ * The height `element` has, or would have if it were not hidden.
+ *
+ * The measuring pass, and the reason this module has a header section about it.
+ * An open panel is measured where it stands; a closed one is briefly laid out
+ * and not painted. Either way this reads layout, which is a synchronous reflow
+ * — the caller is the one that decides it is worth paying.
+ *
+ * # The two things a closed panel is not, and has to be made
+ *
+ * Laying it out is necessary and is not sufficient, because the stylesheet this
+ * property exists for is `height: 0` on the closed panel and
+ * `height: var(--uf-collapsible-height)` on the open one. A panel laid out with
+ * that rule still applying measures **zero**, the property is written back as
+ * `0px`, and the transition has a destination of nothing — the bug the whole
+ * hook was written to avoid, arriving through the rule it was written for. So
+ * `height: auto` is set inline for the pass, exactly as `display` is: not
+ * because the panel wants an inline height but because the author declaration
+ * has to be defeated for one synchronous read and put back.
+ *
+ * `width` is the same argument for the other axis and is `widthInFlow`'s. Both
+ * are restored with everything else; a stylesheet is never left fighting an
+ * inline declaration this wrote.
+ */
+function heightOf(element: HTMLElement): number {
+  if (!element.hasAttribute("hidden")) {
+    return element.getBoundingClientRect().height;
+  }
+  const style = element.style;
+  const before = {
+    boxSizing: style.boxSizing,
+    contentVisibility: style.getPropertyValue("content-visibility"),
+    display: style.display,
+    height: style.height,
+    position: style.position,
+    visibility: style.visibility,
+    width: style.width,
+  };
+  // Out of flow and unpainted, so nothing below the panel moves and no frame
+  // shows it. The order is not significant; this is all one style
+  // recalculation, paid for by the single read below.
+  style.display = "block";
+  style.setProperty("content-visibility", "visible");
+  style.position = "absolute";
+  style.visibility = "hidden";
+  style.height = "auto";
+  const width = widthInFlow(element);
+  if (width != null) {
+    // `border-box`, because what fills the parent's content width in flow is
+    // the panel's margin box rather than its content box: measuring a padded
+    // panel content-box wide would make it wider than it will ever be and its
+    // text shorter than it will ever wrap to.
+    style.boxSizing = "border-box";
+    style.width = width;
+  }
+  const height = element.getBoundingClientRect().height;
+  style.boxSizing = before.boxSizing;
+  style.display = before.display;
+  style.setProperty("content-visibility", before.contentVisibility);
+  style.height = before.height;
+  style.position = before.position;
+  style.visibility = before.visibility;
+  style.width = before.width;
+  return height;
+}
+
+/**
+ * Keep `HEIGHT_PROPERTY` on a disclosure's panel equal to its content's height.
+ *
+ * `enabled` is the caller's opt-in; see the module header for why there is one.
+ * When it is off this writes nothing and measures nothing, which is what makes
+ * a page with no animation pay nothing.
+ *
+ * Two effects rather than one, because they answer different questions. The
+ * first measures on every render, with no dependency array on purpose: what the
+ * panel would be worth changes when the *caller* renders different children
+ * into it, and a dependency list here would be a claim about when that happens
+ * that only the caller could keep — `useFirstItem` in `roving-focus.js` makes
+ * the same argument for the same reason. The second watches for a size change
+ * no render caused: an image that finished loading, a font that swapped. It
+ * only ever fires while the panel is open, because a `display: none` element
+ * has no box for a `ResizeObserver` to report on — which is the whole problem
+ * this hook exists for, arriving one more time.
+ */
+export hook useMeasuredHeight(ref: { current: HTMLElement | null }, enabled: boolean): void {
+  useEffect(() => {
+    const element = ref.current;
+    if (!enabled || element == null) {
+      return;
+    }
+    const measured = `${String(heightOf(element))}px`;
+    // Compared before writing, so a render that changed nothing does not dirty
+    // the element's style and invite another style recalculation.
+    if (element.style.getPropertyValue(HEIGHT_PROPERTY) !== measured) {
+      element.style.setProperty(HEIGHT_PROPERTY, measured);
+    }
+  });
+
+  useEffect(() => {
+    const element = ref.current;
+    const view = element?.ownerDocument?.defaultView;
+    if (!enabled || element == null || view == null) {
+      return;
+    }
+    // Read off the window rather than through a local, for the reason
+    // `internal/anchor.js` gives where it does the same: a capitalised name
+    // holding a constructor is read as a React component by `uf lint`, and the
+    // window's own property is the thing being asked about anyway.
+    const host: $FlowFixMe = view;
+    if (typeof host.ResizeObserver !== "function") {
+      return;
+    }
+    const sizes = new host.ResizeObserver(() => {
+      element.style.setProperty(HEIGHT_PROPERTY, `${String(heightOf(element))}px`);
+    });
+    sizes.observe(element);
+    return () => sizes.disconnect();
+  }, [ref, enabled]);
+}

package/internal/focus.js

@@ -0,0 +1,64 @@
+// @flow
+//
+// What a reader can reach, in the order they reach it.
+//
+// One list, asked for by two components that want opposite things from it.
+// `Dialog.Body` uses it to keep focus *in*: the first and last entries are
+// where `Tab` and `Shift+Tab` wrap. `Popover.Body` uses it to put focus in
+// once and then leaves it alone, because tabbing out of a popover is how a
+// reader leaves one. The list has to be the same list for those two to be
+// describable as different policies over the same fact rather than as two
+// components that disagree about what focusable means.
+//
+// # The selector is the browser's rule, written down
+//
+// A disabled control is out because the browser will not focus one, and
+// `tabindex="-1"` is out because it means "focusable by script, not by Tab" —
+// which is what every roving tab stop in this package uses, so a menu inside a
+// dialog would otherwise report thirty items as focus stops and the trap would
+// wrap between two of them instead of at the dialog's edges.
+//
+// The three ancestor checks are the ones a selector cannot make. `hidden`,
+// `inert` and `aria-hidden="true"` each hide a whole subtree, and reading them
+// off the element alone returned a button inside `<div aria-hidden="true">` as
+// a focus stop — after which the trap moved focus to a control no screen
+// reader exposes and the reader was somewhere they could not be told about.
+//
+// # Why this is `internal/` and not a subpath
+//
+// The same reason `merge-props.js` gives. A public `focusable()` is a
+// general-purpose DOM utility, and a second, weaker copy of one is how two
+// parts of a package come to disagree about which elements exist. What is
+// shipped here is narrower: the definition this package's focus behaviour is
+// written against.
+
+/**
+ * The elements a browser will move focus to with `Tab`.
+ *
+ * Exported as the selector as well as through `focusable`, because one
+ * question is asked about a single element rather than about a subtree: a
+ * tooltip's trigger has to *be* one of these or the tooltip is one only a mouse
+ * can reach, and `element.matches(FOCUS_STOPS)` is that question.
+ */
+export const FOCUS_STOPS: string =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * The focus stops inside an element, in document order.
+ *
+ * Document order rather than mount order, for the reason
+ * `internal/roving-focus.js` gives about items: the two stop agreeing the first
+ * time something is rendered conditionally, and the reader's `Tab` follows the
+ * document.
+ */
+export function focusable(root: HTMLElement): Array<HTMLElement> {
+  return Array.from(root.querySelectorAll(FOCUS_STOPS)).filter(
+    (element: $FlowFixMe) =>
+      // All three hide a whole subtree, so all three are asked of the
+      // ancestors; see the module header for what reading them off the element
+      // alone let through.
+      element.closest("[hidden]") == null &&
+      element.closest("[inert]") == null &&
+      element.closest('[aria-hidden="true"]') == null,
+  );
+}

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]);
+}