@uniflowed/ui 0.0.0-alpha.9 → 0.2.0

package/toggle.js

@@ -28,8 +28,9 @@
 //
 // Because a toggle button is a button, and a button activates on both. That is
 // the same reasoning `switch.js` gives for `Enter`, and the opposite of
-// `checkbox.js`, which leaves `Enter` alone because a checkbox is something a
-// reader answers on their way to submitting a form.
+// `checkbox.js`, where `Enter` submits the form rather than touching the
+// control — because a checkbox is something a reader answers on their way to
+// submitting a form, and that is what the native one does with the key.
 //
 // # It is `disabled`, not `aria-disabled`
 //
@@ -43,49 +44,62 @@
 
 import * as React from "@uniflowed/react";
 
-import type { Rest } from "./internal/merge-props.js";
-import { composeHandlers, withoutComposed } from "./internal/merge-props.js";
+import type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
+import { composeHandlers, withProps, withoutComposed } from "./internal/merge-props.js";
 import { useControlled } from "./internal/controlled-state.js";
 
-/** A button whose state stays applied: pressed or not. */
+/**
+ * A button whose state stays applied: pressed or not.
+ *
+ * `render` is the escape hatch. A caller-rendered element gets `role="button"`
+ * because it may be a link or a `div`; the native button branch keeps the role
+ * implicit and only adds `type="button"`, which is true of the element rather
+ * than of the toggle behaviour.
+ */
 export component Toggle(
   pressed?: boolean,
   defaultPressed?: boolean = false,
   onPressedChange?: (pressed: boolean) => void,
   disabled?: boolean = false,
   children?: React.Node,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const [on, setOn] = useControlled(pressed, defaultPressed, onPressedChange);
   const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
+  const semantics = {
+    "aria-pressed": on ? "true" : "false",
+    children,
+    disabled,
+    onClick: composeHandlers(rest.onClick, (_event: PartEvent) => {
+      if (!disabled) {
+        setOn(!on);
+      }
+    }),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      if (disabled || (event.key !== " " && event.key !== "Enter")) {
+        return;
+      }
+      // Preventing the default stops `Space` scrolling the page, and stops
+      // the browser's own click arriving after this handler and pressing the
+      // button a second time — back to where it started, which reads as the
+      // key having done nothing at all.
+      event.preventDefault();
+      setOn(!on);
+    }),
+  };
+
+  if (render != null) {
+    return render(withProps(passed, { ...semantics, role: "button" }));
+  }
 
   return (
     <button
-      {...passed}
+      {...withProps(passed, semantics)}
       // No `role`: this *is* a button, and `aria-pressed` is what makes it a
       // toggle one. Adding `role="button"` to a `<button>` would be noise, and
       // adding any other role would be a lie about what pressing it does.
-      aria-pressed={on ? "true" : "false"}
-      disabled={disabled}
-      onClick={composeHandlers(rest.onClick, () => {
-        if (!disabled) {
-          setOn(!on);
-        }
-      })}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        if (disabled || (event.key !== " " && event.key !== "Enter")) {
-          return;
-        }
-        // Preventing the default stops `Space` scrolling the page, and stops
-        // the browser's own click arriving after this handler and pressing the
-        // button a second time — back to where it started, which reads as the
-        // key having done nothing at all.
-        event.preventDefault();
-        setOn(!on);
-      })}
       type="button"
-    >
-      {children}
-    </button>
+    />
   );
 }

package/tooltip.js

@@ -73,9 +73,9 @@ import { createContext, useContext, useEffect, useId, useMemo, useRef } from "@u
 import { useEventListener } from "@uniflowed/hooks/dom";
 import { useStableCallback } from "@uniflowed/hooks/lifecycle";
 
-import type { Align, Side } from "./internal/anchor.js";
+import type { Align, LogicalSide } from "./internal/anchor.js";
 import type { DelayGroup, HoverIntent } from "./internal/hover-intent.js";
-import type { Rest } from "./internal/merge-props.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
 import { composeRefs, withProps, withoutComposed } from "./internal/merge-props.js";
 import {
   DEFAULT_CLOSE_DELAY,
@@ -89,7 +89,7 @@ import {
 import { useAnchor } from "./internal/anchor.js";
 import { useControlled } from "./internal/controlled-state.js";
 
-export type { Align, Side } from "./internal/anchor.js";
+export type { Align, LogicalSide, Side } from "./internal/anchor.js";
 
 /** What a `Tooltip.Provider` shares with the tooltips inside it. */
 type TooltipScope = {|
@@ -126,7 +126,7 @@ type TooltipState = {|
    * cannot be closed. It is cleared when the reader leaves the trigger, so
    * coming back opens it again.
    */
-  readonly dismissed: { current: boolean },
+  readonly dismissedRef: { current: boolean },
 |};
 
 const TooltipContext: React.Context<TooltipState | null> = createContext(null);
@@ -180,7 +180,7 @@ export component TooltipRoot(
   const scope = useContext(TooltipScopeContext);
   const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
   const triggerRef = useRef<HTMLElement | null>(null);
-  const dismissed = useRef(false);
+  const dismissedRef = useRef(false);
   const intent = useHoverIntent(setOpen);
   const own = openDelay ?? scope?.delayDuration ?? DEFAULT_OPEN_DELAY;
   const group = scope?.group;
@@ -217,7 +217,7 @@ export component TooltipRoot(
     () => ({
       base,
       closeDelay,
-      dismissed,
+      dismissedRef,
       intent,
       open: isOpen,
       openDelay: () => group?.delayFor(own) ?? own,
@@ -243,25 +243,21 @@ export component TooltipRoot(
  * `render` function that forgets to spread something still gets a working
  * tooltip; see the module header.
  */
-export component TooltipTrigger(
-  children?: React.Node,
-  render?: (props: Rest) => React.Node,
-  ...rest: Rest
-) {
+export component TooltipTrigger(children?: React.Node, render?: RenderProp, ...rest: Rest) {
   const tooltip = useTooltip("Tooltip.Trigger");
-  const { closeDelay, dismissed, intent, openDelay, setOpen, triggerRef } = tooltip;
+  const { closeDelay, dismissedRef, 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);
+  const pressedRef = 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) {
+    if (event.pointerType === "touch" || dismissedRef.current) {
       return;
     }
     intent.openAfter(openDelay());
@@ -269,57 +265,50 @@ export component TooltipTrigger(
   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;
+    dismissedRef.current = false;
     intent.closeAfter(closeDelay);
   });
   useEventListener(triggerRef, "pointerdown", () => {
-    pressed.current = true;
+    pressedRef.current = true;
     intent.cancel();
     setOpen(false);
   });
   useEventListener(triggerRef, "focusin", () => {
-    if (pressed.current) {
-      pressed.current = false;
+    if (pressedRef.current) {
+      pressedRef.current = false;
       return;
     }
-    if (dismissed.current) {
+    if (dismissedRef.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;
+    pressedRef.current = false;
+    dismissedRef.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.
+  // React calls callback refs during commit; pointer and focus handlers read it later.
+  // uf-lint-disable-next-line react-compiler/refs
   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 ours = {
+  const props = withProps(withoutComposed(rest, ["ref"]), {
     "aria-describedby": tooltip.open ? `${tooltip.base}-body` : undefined,
+    children,
     ref: attach,
-  };
+  });
 
   if (render != null) {
-    return render(withProps(withoutComposed(rest, ["ref"]), ours));
+    return render(props);
   }
-
-  return (
-    <button
-      {...withoutComposed(rest, ["ref"])}
-      aria-describedby={ours["aria-describedby"]}
-      ref={attach}
-      type="button"
-    >
-      {children}
-    </button>
-  );
+  return <button {...props} type="button" />;
 }
 
 /**
@@ -337,19 +326,20 @@ export component TooltipBody(
   alignOffset?: number = 0,
   avoidCollisions?: boolean = true,
   collisionPadding?: number = 0,
-  side?: Side = "top",
+  render?: RenderProp,
+  side?: LogicalSide = "top",
   sideOffset?: number = 0,
   ...rest: Rest
 ) {
   const tooltip = useTooltip("Tooltip.Body");
-  const { closeDelay, intent, open, triggerRef } = tooltip;
+  const { closeDelay, dismissedRef, 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;
+    dismissedRef.current = true;
     intent.cancel();
     tooltip.setOpen(false);
   });
@@ -391,21 +381,24 @@ export component TooltipBody(
     return null;
   }
 
-  return (
-    <div
-      {...withoutComposed(rest, ["ref"])}
-      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.
-    >
-      {children}
-    </div>
-  );
+  const props = withProps(withoutComposed(rest, ["ref"]), {
+    children,
+    "data-align": anchored.align,
+    "data-side": anchored.side,
+    "data-state": "open",
+    id: `${tooltip.base}-body`,
+    // React calls callback refs during commit; placement effects read it later.
+    // uf-lint-disable-next-line react-compiler/refs
+    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/tree.js

@@ -0,0 +1,8 @@
+// @flow
+"use client";
+import * as React from "@uniflowed/react";
+import { CollectionRoot } from "./internal/collection.js";
+import type { CollectionProps } from "./internal/collection.js";
+export component Tree(...props: CollectionProps) {
+  return <CollectionRoot options={props} kind="tree" />;
+}

package/visually-hidden.js

@@ -0,0 +1,259 @@
+// @flow
+"use client";
+//
+// Text for assistive technology and nobody else, and the announcer built on it.
+//
+// # `VisuallyHidden`
+//
+// `display: none` and `visibility: hidden` take an element out of the
+// accessibility tree as well as off the screen, which is the opposite of what a
+// visually hidden label is for. The style in `internal/visually-hidden-style.js`
+// is the one that survives every engine's accessibility mapping: a one-pixel
+// box, clipped twice (`clip` for the engines that predate `clip-path`), and
+// `white-space: nowrap` so a screen reader's virtual cursor does not read a
+// clipped paragraph one word per line.
+//
+// `focusable` is for the skip link: hidden until a keyboard lands on it, then
+// on screen while focus is anywhere inside, because a focus ring around a
+// one-pixel box is a focus ring nobody can see.
+//
+// # `announce`
+//
+// A live region only announces a *change*, and only when the region was in the
+// document before the change — so a region rendered together with its message
+// says nothing, and a component that renders its own region next to itself has
+// to exist, silent, before the thing it wants to say happens. Every component
+// that did that also put an element in the caller's layout, and three of them
+// (the collections, the range calendar and the segmented fields) left theirs
+// visible, so "3 selected" was printed on the page under the list.
+//
+// `announce()` is one pair of regions for the whole document, created on the
+// first call and kept. It follows React Aria's LiveAnnouncer, and not by
+// accident:
+//
+//   * one `role="log"` region per politeness, since a region's politeness is
+//     read when the region is first seen and cannot be changed on a live one;
+//   * each message is a new child node rather than a new text value, so the
+//     same message twice is announced twice (`aria-relevant="additions"`);
+//   * each message is removed after `timeout`, so a reader who arrives at the
+//     end of the document later does not find a transcript there;
+//   * the first message waits 100 ms after the regions are created, because a
+//     region and its first content inserted together are, again, silent.
+//
+// On the server there is no document and `announce` does nothing; there is
+// nothing to hydrate either, because the regions are never rendered by React.
+
+import * as React from "@uniflowed/react";
+import { useState } from "@uniflowed/react";
+import { composeHandlers, withProps, withoutComposed } from "./internal/merge-props.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { visuallyHiddenStyle } from "./internal/visually-hidden-style.js";
+
+type FocusEvent = {
+  readonly currentTarget: mixed,
+  readonly relatedTarget: mixed,
+  readonly defaultPrevented: boolean,
+  ...
+};
+
+/**
+ * Content a screen reader reads and a sighted reader does not see.
+ *
+ *     <button><Icon name="trash" /><VisuallyHidden>Delete draft</VisuallyHidden></button>
+ *     <VisuallyHidden focusable render={(props) => <a href="#main" {...props} />}>
+ *       Skip to content
+ *     </VisuallyHidden>
+ *
+ * A caller's `style` is kept, underneath the hiding, so it applies again the
+ * moment a `focusable` one is shown.
+ */
+export component VisuallyHidden(
+  children?: React.Node,
+  /** Show the content while focus is inside it: the skip-link pattern. */
+  focusable: boolean = false,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const [focused, setFocused] = useState(false);
+  const style = rest.style;
+  const own = typeof style === "object" && style != null ? style : {};
+  const hidden = !(focusable && focused);
+  const props = withProps(withoutComposed(rest, ["onFocus", "onBlur"]), {
+    children,
+    style: hidden ? { ...own, ...visuallyHiddenStyle } : style,
+    onFocus: composeHandlers(rest.onFocus, () => {
+      if (focusable) setFocused(true);
+    }),
+    onBlur: composeHandlers(rest.onBlur, (event: FocusEvent) => {
+      // Moving between two links inside one skip block is not leaving it.
+      const { currentTarget, relatedTarget } = event;
+      if (
+        currentTarget instanceof Node &&
+        relatedTarget instanceof Node &&
+        currentTarget.contains(relatedTarget)
+      )
+        return;
+      setFocused(false);
+    }),
+  });
+  return render != null ? render(props) : <span {...props} />;
+}
+
+export type Politeness = "polite" | "assertive";
+
+export type AnnounceOptions = {|
+  /**
+   * `"polite"` (the default) waits for the reader to finish; `"assertive"`
+   * interrupts, and is for what cannot wait — an error that stopped a save.
+   */
+  readonly politeness?: Politeness,
+  /** Milliseconds before the message leaves the document. 7000 by default. */
+  readonly timeout?: number,
+|};
+
+type Announcer = {|
+  readonly root: HTMLElement,
+  readonly polite: HTMLElement,
+  readonly assertive: HTMLElement,
+  /** When the regions went into the document; the first message waits for them. */
+  readonly created: number,
+|};
+
+let announcer: Announcer | null = null;
+
+/** Wait this long after creating the regions, so their first content is a change. */
+const SETTLE_MS = 100;
+
+function region(document: Document, politeness: Politeness): HTMLElement {
+  const element = document.createElement("div");
+  element.setAttribute("role", "log");
+  element.setAttribute("aria-live", politeness);
+  element.setAttribute("aria-relevant", "additions");
+  return element;
+}
+
+function announcerIn(document: Document): Announcer | null {
+  const body = document.body;
+  if (body == null) return null;
+  // A test's cleanup, or an app that replaces `<body>`, can take the regions
+  // out; a region that is not in the document announces nothing.
+  if (announcer != null && announcer.root.isConnected && announcer.root.ownerDocument === document)
+    return announcer;
+  const root = document.createElement("div");
+  root.setAttribute("data-uf-live-announcer", "");
+  root.style.cssText =
+    "position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;" +
+    "overflow:hidden;clip:rect(0, 0, 0, 0);clip-path:inset(50%);white-space:nowrap";
+  const assertive = region(document, "assertive");
+  const polite = region(document, "polite");
+  root.append(assertive, polite);
+  // A direct child of `<body>`, which is the level a modal's conceal walk
+  // reaches last; `dialog.js` skips it by the attribute above.
+  body.prepend(root);
+  announcer = { root, polite, assertive, created: Date.now() };
+  return announcer;
+}
+
+/**
+ * The timers `announce` has scheduled and not yet run, per politeness, so
+ * `clearAnnouncements` can take back a message that has not arrived yet as
+ * well as one that has.
+ */
+const pending: {| readonly polite: Set<TimeoutID>, readonly assertive: Set<TimeoutID> |} = {
+  polite: new Set(),
+  assertive: new Set(),
+};
+
+/**
+ * Run `work` after `ms`, unless `clearAnnouncements` cancels it first.
+ *
+ * A timer outlives whatever scheduled it: a test worker restores its globals
+ * between files, and an app can unmount, replace `<body>` or tear its window
+ * down, all while a message is still waiting to arrive or to leave. So a timer
+ * never reads the `document` global — `work` is handed the document and
+ * regions captured when the message was announced, and each timer checks they
+ * are still there before touching them.
+ */
+function schedule(politeness: Politeness, ms: number, work: () => void): void {
+  const timers = pending[politeness];
+  const timer: TimeoutID = setTimeout(() => {
+    timers.delete(timer);
+    work();
+  }, ms);
+  timers.add(timer);
+}
+
+/**
+ * Whether `document` is still the document this realm has, and `region` still
+ * in it: the one condition under which a timer may write to either.
+ */
+function stillLive(document: Document, region: HTMLElement): boolean {
+  return (
+    typeof globalThis.document !== "undefined" &&
+    globalThis.document === document &&
+    region.isConnected &&
+    region.ownerDocument === document
+  );
+}
+
+/**
+ * Say something to a screen reader, from anywhere.
+ *
+ *     announce(`${count} results`);
+ *     announce("Could not save the draft", { politeness: "assertive" });
+ *
+ * A function rather than a hook, because what needs announcing comes from
+ * event handlers, effects and `catch` blocks — `toast()` makes the same choice.
+ * An empty message is ignored rather than announced as silence. On the server
+ * it returns before scheduling anything.
+ */
+export function announce(message: string, options?: AnnounceOptions): void {
+  if (message.trim() === "" || typeof document === "undefined") return;
+  // Captured now, and the only document the timers below ever use.
+  const doc = document;
+  const current = announcerIn(doc);
+  if (current == null) return;
+  const politeness = options?.politeness ?? "polite";
+  const timeout = options?.timeout ?? 7000;
+  const target = politeness === "assertive" ? current.assertive : current.polite;
+  const insert = () => {
+    // The document went away (a worker's teardown, an unmounted frame) or the
+    // regions were taken out of it: there is nobody left to tell.
+    if (!stillLive(doc, target)) return;
+    const node = doc.createElement("div");
+    node.textContent = message;
+    target.append(node);
+    if (timeout > 0 && Number.isFinite(timeout))
+      schedule(politeness, timeout, () => {
+        // Removing a detached node is harmless; only a live one needs it.
+        if (node.isConnected) node.remove();
+      });
+  };
+  const wait = current.created + SETTLE_MS - Date.now();
+  if (wait > 0) schedule(politeness, wait, insert);
+  else insert();
+}
+
+/**
+ * Take every message out, for one politeness or both: the ones in the regions
+ * and the ones still waiting to arrive, whose timers are cancelled. After it,
+ * nothing `announce` scheduled for that politeness runs.
+ */
+export function clearAnnouncements(politeness?: Politeness): void {
+  const both: $ReadOnlyArray<Politeness> = ["assertive", "polite"];
+  for (const which of both) {
+    if (politeness != null && politeness !== which) continue;
+    const timers = pending[which];
+    for (const timer of timers) clearTimeout(timer);
+    timers.clear();
+  }
+  const current = announcer;
+  if (current == null) return;
+  // Regions a teardown took out are not reused, and need not be kept alive.
+  if (!current.root.isConnected) {
+    announcer = null;
+    return;
+  }
+  if (politeness !== "polite") current.assertive.replaceChildren();
+  if (politeness !== "assertive") current.polite.replaceChildren();
+}