@uniflowed/ui 0.0.0-alpha.9 → 0.2.0

package/dialog.js

@@ -31,6 +31,32 @@
 // looks. The page behind is hidden by marking it inert rather than by moving
 // the dialog out of it, which gets the same guarantee without the move.
 //
+// # Three things a caller decides, and why they are props rather than four
+// components
+//
+// A modal dialog is one pattern with three places a *different* modal dialog
+// differs, and each of the three fails silently when it is hard-coded:
+//
+//   * **`role`** — `dialog` or `alertdialog`. The second tells a screen reader
+//     the dialog is interrupting to say something urgent and makes it announce
+//     the description immediately, which is the difference between "dialog,
+//     Delete this project?" and an alert the reader is expected to answer.
+//   * **`dismissOnOutsidePress`** — whether a press beside the dialog closes
+//     it. A confirmation that vanishes when the reader clicks slightly beside
+//     it, losing what they were about to confirm and saying nothing about which
+//     way it went, is the single behaviour an alert dialog exists to prevent.
+//     `Escape` keeps closing it either way: a modal a reader cannot leave from
+//     the keyboard is a trap, and declining an alert is what `Escape` means.
+//   * **`initialFocus`** — where focus lands. "The first thing worth acting on"
+//     is right for a dialog and wrong for a confirmation, where the APG puts
+//     focus on the *least* destructive action: Cancel, not Delete.
+//
+// They are three props on `Dialog.Body` and not a `variant` flag, because a
+// flag is a name for a bundle and the bundles differ: `alert-dialog.js` sets
+// all three, `sheet.js` sets none of them and adds an edge, `sidebar.js` is
+// most often not modal at all. What each of those components adds is written
+// where it lives; what they share is here, once.
+//
 // # Composition
 //
 // The parts are one namespace — `Dialog.Root`, `Dialog.Body`, `Dialog.Title` —
@@ -49,13 +75,34 @@ import {
   useRef,
   useState,
 } from "@uniflowed/react";
+import { useScrollLock } from "@uniflowed/hooks/browser";
 import { useStableCallback } from "@uniflowed/hooks/lifecycle";
 
-import type { Rest } from "./internal/merge-props.js";
-import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
+import { useInteractOutside } from "./interactions.js";
+
+import type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  withProps,
+  withoutComposed,
+} from "./internal/merge-props.js";
 import { focusable } from "./internal/focus.js";
 import { useControlled } from "./internal/controlled-state.js";
 
+/**
+ * What a screen reader is told the dialog is.
+ *
+ * A union rather than a string, so `role="alertdailog"` is a type error at the
+ * call rather than a dialog announced as a `div` with a name — which is what a
+ * misspelt role produces, silently, in markup that looks correct.
+ *
+ * Two members and not the whole of ARIA: these are the two roles that carry
+ * `aria-modal`, and a `Dialog.Body` that is a `region` or a `complementary` is
+ * a different component rather than this one with another string.
+ */
+export type DialogRole = "dialog" | "alertdialog";
+
 type DialogState = {|
   readonly base: string,
   readonly open: boolean,
@@ -115,29 +162,36 @@ export component DialogRoot(
   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: Rest) {
+/**
+ * What opens the dialog, and what focus comes back to when it closes.
+ *
+ * `render` for a trigger that is not a `<button>` — a card, a table row, an
+ * icon in somebody else's `<Pressable>`. The ref goes across with everything
+ * else, which is what keeps "focus comes back here" true of whatever the
+ * caller rendered.
+ */
+export component DialogTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const dialog = useDialog("Dialog.Trigger");
-  const passed = withoutComposed(rest, ["onClick", "ref"]);
-
-  return (
-    <button
-      {...passed}
-      // Only while it is open. An `aria-controls` naming an element that is not
-      // in the document is worse than no `aria-controls`: a reader is told
-      // there is somewhere to go and there is not.
-      aria-controls={dialog.open ? `${dialog.base}-body` : undefined}
-      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>
-  );
+  const props = withProps(withoutComposed(rest, ["onClick", "ref"]), {
+    // Only while it is open. An `aria-controls` naming an element that is not
+    // in the document is worse than no `aria-controls`: a reader is told
+    // there is somewhere to go and there is not.
+    "aria-controls": dialog.open ? `${dialog.base}-body` : undefined,
+    "aria-expanded": dialog.open ? "true" : "false",
+    "aria-haspopup": "dialog",
+    children,
+    onClick: composeHandlers(rest.onClick, () => dialog.setOpen(true)),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      // React calls callback refs during commit; focus restoration reads it later.
+      // uf-lint-disable-next-line react-compiler/immutability
+      dialog.triggerRef.current = element;
+    }),
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
 }
 
 /**
@@ -149,12 +203,16 @@ export component DialogTrigger(children: React.Node, ...rest: Rest) {
  * their own backdrop or omits one entirely must still get it. That lives on
  * `Dialog.Body`, which is the part that knows where "outside" is.
  */
-export component DialogOverlay(...rest: Rest) {
+export component DialogOverlay(render?: RenderProp, ...rest: Rest) {
   const dialog = useDialog("Dialog.Overlay");
   if (!dialog.open) {
     return null;
   }
-  return <div {...rest} aria-hidden="true" data-state="open" />;
+  const props = withProps(rest, { "aria-hidden": "true", "data-state": "open" });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
 }
 
 /**
@@ -164,7 +222,14 @@ export component DialogOverlay(...rest: Rest) {
  * which is the half of "modal" that CSS cannot express; `inert` on everything
  * outside is the half the browser enforces.
  */
-export component DialogBody(children: React.Node, ...rest: Rest) {
+export component DialogBody(
+  children: React.Node,
+  dismissOnOutsidePress?: boolean = true,
+  initialFocus?: { current: HTMLElement | null },
+  role?: DialogRole = "dialog",
+  render?: RenderProp,
+  ...rest: Rest
+) {
   const dialog = useDialog("Dialog.Body");
   const bodyRef = useRef<HTMLElement | null>(null);
   // Stable, so the effect below depends on `open` and on nothing else. Keyed on
@@ -173,6 +238,19 @@ export component DialogBody(children: React.Node, ...rest: Rest) {
   // parent that re-rendered stole focus back from whatever the reader had
   // moved it to inside the dialog.
   const close = useStableCallback(() => dialog.setOpen(false));
+  // Asked at the moment of the press rather than named in the dependencies
+  // below, because naming it there re-runs the effect when it changes and
+  // re-running the effect re-takes focus. A caller who flips this on a
+  // breakpoint would otherwise have focus dragged back to the top of the
+  // dialog underneath the reader.
+  const dismissable = useStableCallback(() => dismissOnOutsidePress);
+
+  // The page is held still by `@uniflowed/hooks`' reference-counted lock rather
+  // than by a second one written here. Two implementations of this in one
+  // repository is the duplication "build uf with uf" exists to catch, and the
+  // shared one is the one that also pads out the scrollbar's width — a page
+  // that jumps sideways when a dialog opens is this component's doing.
+  useScrollLock(dialog.open);
 
   useEffect(() => {
     const body = bodyRef.current;
@@ -186,111 +264,114 @@ export component DialogBody(children: React.Node, ...rest: Rest) {
     const opener = trigger ?? (document.activeElement as $FlowFixMe);
 
     const restorePage = concealOutside(body);
-    const releaseScroll = lockScroll(document);
-
-    const onOutsidePress = (event: Event) => {
-      const target: $FlowFixMe = event.target;
-      if (target == null || body.contains(target)) {
-        return;
-      }
-      // The trigger is outside the dialog and is not "outside" for this
-      // purpose: closing here and letting the trigger's own click reopen made
-      // a press on the trigger a no-op that flickered.
-      if (trigger != null && trigger.contains(target)) {
-        return;
-      }
-      close();
-    };
-    // Capture, so a press is seen even where something below it stops the
-    // event — a menu inside the dialog, for instance.
-    document.addEventListener("pointerdown", onOutsidePress, true);
 
-    // The first thing worth acting on, and the dialog itself when it holds
-    // nothing focusable, so focus is inside it either way.
-    const target = focusable(body)[0] ?? body;
+    // Where the caller said, then the first thing worth acting on, then the
+    // dialog itself when it holds nothing focusable — so focus is inside it
+    // whichever of the three answers.
+    //
+    // The named element has to still be *in* this dialog: a ref left over from
+    // a previous opening, or one pointing at something the caller renders
+    // elsewhere, would move focus out of a dialog that announces the rest of
+    // the page is unavailable.
+    const named = initialFocus?.current ?? null;
+    const target = named != null && body.contains(named) ? named : (focusable(body)[0] ?? body);
     target.focus();
 
     return () => {
-      document.removeEventListener("pointerdown", onOutsidePress, true);
       // Order matters: the page comes back before focus is restored, because
       // the trigger is one of the elements that was made `inert` and an inert
       // element cannot take focus.
       restorePage();
-      releaseScroll();
       opener?.focus?.();
     };
-  }, [dialog.open, dialog.triggerRef, close]);
+  }, [dialog.open, dialog.triggerRef, initialFocus]);
+
+  // A confirmation declines to close here, and `Escape` still does. See the
+  // module header: there is a difference between a dialog the reader dismissed
+  // and one that went away while they were reaching for it.
+  useInteractOutside({
+    isDisabled: !dialog.open,
+    onInteractOutside: () => {
+      if (dismissable()) {
+        close();
+      }
+    },
+    refs: [bodyRef, dialog.triggerRef],
+  });
 
   if (!dialog.open) {
     return null;
   }
 
-  const passed = withoutComposed(rest, ["onKeyDown", "ref"]);
-
-  return (
-    <div
-      // `passed` first. A caller `ref` used to replace `bodyRef`, 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 it.
-      {...passed}
-      // Only ids that are in the document: an `aria-labelledby` naming a
-      // missing element makes a screen reader announce nothing at all, so a
-      // dialog without a `Dialog.Title` falls through to whatever `aria-label`
-      // the caller passed instead.
-      aria-describedby={dialog.described ? `${dialog.base}-description` : undefined}
-      aria-labelledby={dialog.titled ? `${dialog.base}-title` : undefined}
-      aria-modal="true"
-      id={`${dialog.base}-body`}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        if (event.key === "Escape") {
-          event.preventDefault();
-          // The dialog behind this one must not also close. Two stacked
-          // dialogs nest in the DOM, so without this the event bubbled to the
-          // outer dialog's handler and one Escape closed both.
-          event.stopPropagation();
-          close();
-          return;
-        }
-        if (event.key !== "Tab") {
-          return;
-        }
-        const body = bodyRef.current;
-        if (body == null) {
-          return;
-        }
-        const stops = focusable(body);
-        // An outer dialog must not also run its trap on this key.
+  // The caller's props first. A caller `ref` used to replace `bodyRef`, 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 it.
+  const props = withProps(withoutComposed(rest, ["onKeyDown", "ref"]), {
+    // Only ids that are in the document: an `aria-labelledby` naming a
+    // missing element makes a screen reader announce nothing at all, so a
+    // dialog without a `Dialog.Title` falls through to whatever `aria-label`
+    // the caller passed instead.
+    "aria-describedby": dialog.described ? `${dialog.base}-description` : undefined,
+    "aria-labelledby": dialog.titled ? `${dialog.base}-title` : undefined,
+    "aria-modal": "true",
+    children,
+    id: `${dialog.base}-body`,
+    // Key handling closes the mounted dialog and restores focus after events.
+    // uf-lint-disable-next-line react-compiler/refs
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        // The dialog behind this one must not also close. Two stacked
+        // dialogs nest in the DOM, so without this the event bubbled to the
+        // outer dialog's handler and one Escape closed both.
         event.stopPropagation();
-        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 = body.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 === body)) {
-          event.preventDefault();
-          last.focus();
-        } else if (!event.shiftKey && active === last) {
-          event.preventDefault();
-          first.focus();
-        }
-      })}
-      ref={composeRefs(rest.ref, (element) => {
-        bodyRef.current = element;
-      })}
-      role="dialog"
-      // So the dialog can hold focus itself when it contains nothing focusable,
-      // and so the trap has somewhere to put focus that is still inside.
-      tabIndex={-1}
-    >
-      {children}
-    </div>
-  );
+        close();
+        return;
+      }
+      if (event.key !== "Tab") {
+        return;
+      }
+      const body = bodyRef.current;
+      if (body == null) {
+        return;
+      }
+      const stops = focusable(body);
+      // An outer dialog must not also run its trap on this key.
+      event.stopPropagation();
+      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 = body.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 === body)) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && active === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    }),
+    // React calls callback refs during commit; focus effects and traps read it later.
+    // uf-lint-disable-next-line react-compiler/refs
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      bodyRef.current = element;
+    }),
+    role,
+    // So the dialog can hold focus itself when it contains nothing focusable,
+    // and so the trap has somewhere to put focus that is still inside.
+    tabIndex: -1,
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
 }
 
 /**
@@ -300,7 +381,7 @@ export component DialogBody(children: React.Node, ...rest: Rest) {
  * rendered — a conditional title that is absent used to leave the dialog
  * pointing at an id nothing had.
  */
-export component DialogTitle(children: React.Node, ...rest: Rest) {
+export component DialogTitle(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const dialog = useDialog("Dialog.Title");
   const register = dialog.registerTitle;
   useEffect(() => {
@@ -308,11 +389,15 @@ export component DialogTitle(children: React.Node, ...rest: Rest) {
     return () => register(false);
   }, [register]);
 
-  return (
-    <h2 {...rest} id={`${dialog.base}-title`}>
-      {children}
-    </h2>
-  );
+  const props = withProps(rest, { children, id: `${dialog.base}-title` });
+  // `<h2>` is a default rather than a decision. Which heading level a dialog's
+  // name is depends on what is around it — ubugeeei-prod/uf#276 is the same
+  // observation about an accordion — and `render` is how a caller says so
+  // without losing the id `aria-labelledby` points at.
+  if (render != null) {
+    return render(props);
+  }
+  return <h2 {...props} />;
 }
 
 /**
@@ -322,7 +407,7 @@ export component DialogTitle(children: React.Node, ...rest: Rest) {
  * the one moment the reader has to decide whether they care — so this is where
  * "this cannot be undone" belongs, not in body text further down.
  */
-export component DialogDescription(children: React.Node, ...rest: Rest) {
+export component DialogDescription(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const dialog = useDialog("Dialog.Description");
   const register = dialog.registerDescription;
   useEffect(() => {
@@ -330,11 +415,11 @@ export component DialogDescription(children: React.Node, ...rest: Rest) {
     return () => register(false);
   }, [register]);
 
-  return (
-    <p {...rest} id={`${dialog.base}-description`}>
-      {children}
-    </p>
-  );
+  const props = withProps(rest, { children, id: `${dialog.base}-description` });
+  if (render != null) {
+    return render(props);
+  }
+  return <p {...props} />;
 }
 
 /**
@@ -346,29 +431,35 @@ export component DialogDescription(children: React.Node, ...rest: Rest) {
  * styling layer has a name to attach to, and contributes no semantics because
  * it has none to contribute.
  */
-export component DialogHeader(children: React.Node, ...rest: Rest) {
-  return <div {...rest}>{children}</div>;
+export component DialogHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { children });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
 }
 
 /** The bottom of the dialog, where the actions go. See `Dialog.Header`. */
-export component DialogFooter(children: React.Node, ...rest: Rest) {
-  return <div {...rest}>{children}</div>;
+export component DialogFooter(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { children });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
 }
 
 /** A button that closes the dialog. */
-export component DialogClose(children: React.Node, ...rest: Rest) {
+export component DialogClose(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const dialog = useDialog("Dialog.Close");
-  const passed = withoutComposed(rest, ["onClick"]);
-
-  return (
-    <button
-      {...passed}
-      onClick={composeHandlers(rest.onClick, () => dialog.setOpen(false))}
-      type="button"
-    >
-      {children}
-    </button>
-  );
+  const props = withProps(withoutComposed(rest, ["onClick"]), {
+    children,
+    onClick: composeHandlers(rest.onClick, () => dialog.setOpen(false)),
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
 }
 
 /**
@@ -380,6 +471,11 @@ export component DialogClose(children: React.Node, ...rest: Rest) {
  * hiding body's children would hide nothing new and the outer dialog's own
  * content would stay readable behind the inner one.
  *
+ * The one sibling left alone is the live announcer `visually-hidden.js`
+ * creates, which lives in `<body>` and would otherwise go silent for as long as
+ * any dialog is open. React Aria's `ariaHideOutside` keeps its announcer for the
+ * same reason.
+ *
  * Both attributes, because they address different audiences. `aria-hidden`
  * removes the subtree from the accessibility tree; `inert` also stops clicks
  * and takes it out of the tab order, which is the browser's own enforcement of
@@ -397,7 +493,9 @@ function concealOutside(element: HTMLElement): () => void {
       break;
     }
     for (const sibling of Array.from(parent.children)) {
-      if (sibling === node) {
+      // `announce()`'s regions stay readable: a message about what the dialog
+      // just did ("Saved", "3 results") is exactly what a modal needs to say.
+      if (sibling === node || sibling.hasAttribute("data-uf-live-announcer")) {
         continue;
       }
       restore.push({
@@ -427,36 +525,3 @@ function concealOutside(element: HTMLElement): () => void {
     }
   };
 }
-
-/**
- * How many dialogs are holding the page still, and what it looked like before.
- *
- * A count rather than each dialog saving and restoring, because two dialogs
- * that open and close in any order but the strictest nesting would otherwise
- * hand the page back a value the other one had already replaced.
- */
-let scrollLocks = 0;
-let overflowBeforeLock: string = "";
-
-/** Stop the page behind the dialog from scrolling, and undo exactly that. */
-function lockScroll(document: Document): () => void {
-  const body: $FlowFixMe = document.body;
-  if (scrollLocks === 0) {
-    overflowBeforeLock = body.style.overflow;
-    body.style.overflow = "hidden";
-  }
-  scrollLocks += 1;
-
-  let released = false;
-  return () => {
-    if (released) {
-      return;
-    }
-    released = true;
-    scrollLocks -= 1;
-    if (scrollLocks === 0) {
-      body.style.overflow = overflowBeforeLock;
-      overflowBeforeLock = "";
-    }
-  };
-}