@uniflowed/ui 0.0.0-alpha.8 → 0.1.0

package/accordion.js

@@ -54,6 +54,19 @@
 // are here because a long FAQ is nicer with them — but nothing about them takes
 // a header out of the tab order.
 //
+// # The height a stylesheet animates to
+//
+// `measure` on the root puts each panel's would-be height on it as
+// `--uf-collapsible-height` — one property name across both disclosure
+// components, because it is one measurement and a second name would be a second
+// rule to keep in step. `collapsible.js`'s header shows the stylesheet, and
+// `internal/disclosure.js` holds the measuring pass and the argument for the
+// opt-in.
+//
+// It is on `Accordion.Root` rather than on each `Accordion.Content` because a
+// forty-section FAQ is one decision, made once, rather than forty props that
+// have to agree.
+//
 // # How the sections are found
 //
 // By a `data-*` attribute of this package's own rather than by role, which is
@@ -77,11 +90,16 @@ import {
   useState,
 } from "@uniflowed/react";
 
-import type { Rest } from "./internal/merge-props.js";
-import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
+import type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  withProps,
+  withoutComposed,
+} from "./internal/merge-props.js";
 import { moveOnKey } from "./internal/roving-focus.js";
 import type { RovingSet } from "./internal/roving-focus.js";
-import { usePresence, useUntilFound } from "./internal/disclosure.js";
+import { useMeasuredHeight, usePresence, useUntilFound } from "./internal/disclosure.js";
 import { useControlled } from "./internal/controlled-state.js";
 
 /** Whether one section is open at a time, or any number of them. */
@@ -110,6 +128,8 @@ type AccordionState = {|
   /** Whether closing the last open section is allowed; only meaningful for `single`. */
   readonly closable: boolean,
   readonly type: AccordionType,
+  /** Whether each panel carries its measured height; see the module header. */
+  readonly measure: boolean,
 |};
 
 const AccordionContext: React.Context<AccordionState | null> = createContext(null);
@@ -160,6 +180,8 @@ export component AccordionRoot(
   defaultValue?: $ReadOnlyArray<string> = NOTHING,
   value?: $ReadOnlyArray<string>,
   onValueChange?: (value: $ReadOnlyArray<string>) => void,
+  measure?: boolean = false,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const [open, setOpen] = useControlled<$ReadOnlyArray<string>>(value, defaultValue, onValueChange);
@@ -184,25 +206,23 @@ export component AccordionRoot(
   const state = useMemo(
     // `collapsible` only ever narrows a `single` accordion: in `multiple` mode
     // every section closes on its own, and there is no last one to protect.
-    () => ({ open, toggle, closable: type === "multiple" || collapsible, type }),
-    [open, toggle, type, collapsible],
+    () => ({ open, toggle, closable: type === "multiple" || collapsible, type, measure }),
+    [open, toggle, type, collapsible, measure],
   );
-  const passed = withoutComposed(rest, ["onKeyDown"]);
+  const props = withProps(withoutComposed(rest, ["onKeyDown"]), {
+    children,
+    // The name the arrow keys use to tell this accordion's headers from those
+    // of an accordion nested inside one of its panels.
+    "data-accordion": "",
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      const stack: $FlowFixMe = event.currentTarget;
+      moveOnKey(event, stack, HEADERS);
+    }),
+  });
 
   return (
     <AccordionContext.Provider value={state}>
-      <div
-        {...passed}
-        // The name the arrow keys use to tell this accordion's headers from
-        // those of an accordion nested inside one of its panels.
-        data-accordion=""
-        onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-          const stack: $FlowFixMe = event.currentTarget;
-          moveOnKey(event, stack, HEADERS);
-        })}
-      >
-        {children}
-      </div>
+      {render == null ? <div {...props} /> : render(props)}
     </AccordionContext.Provider>
   );
 }
@@ -219,6 +239,7 @@ export component AccordionItem(
   value: string,
   children: renders* (AccordionHeader | AccordionContent),
   disabled?: boolean = false,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const accordion = useAccordion("Accordion.Item");
@@ -241,9 +262,11 @@ export component AccordionItem(
     [base, open, toggle, value, accordion.closable, disabled, present],
   );
 
+  const props = withProps(rest, { children });
+
   return (
     <AccordionItemContext.Provider value={state}>
-      <div {...rest}>{children}</div>
+      {render == null ? <div {...props} /> : render(props)}
     </AccordionItemContext.Provider>
   );
 }
@@ -274,35 +297,34 @@ export component AccordionHeader(
  * It carries no `tabIndex` of its own on purpose: every header stays in the
  * page's tab order, which is what makes this an accordion and not a tab list.
  */
-export component AccordionTrigger(children: React.Node, ...rest: Rest) {
+export component AccordionTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const item = useAccordionItem("Accordion.Trigger");
-  const passed = withoutComposed(rest, ["onClick"]);
   // Locked and disabled are two different sentences a reader hears the same
   // way, and both are `aria-disabled` rather than `disabled` so the header
   // stays where they can find it: "this section will not close" and "this
   // section is unavailable".
   const inert = item.locked || item.disabled;
 
-  return (
-    <button
-      {...passed}
-      aria-controls={item.present ? item.contentId : undefined}
-      aria-disabled={inert ? "true" : undefined}
-      aria-expanded={item.open ? "true" : "false"}
-      // What the arrow keys look for. Not a role, because the accordion pattern
-      // has none to look for; see the module header.
-      data-accordion-trigger=""
-      id={item.triggerId}
-      onClick={composeHandlers(rest.onClick, () => {
-        if (!inert) {
-          item.toggle();
-        }
-      })}
-      type="button"
-    >
-      {children}
-    </button>
-  );
+  const props = withProps(withoutComposed(rest, ["onClick"]), {
+    "aria-controls": item.present ? item.contentId : undefined,
+    "aria-disabled": inert ? "true" : undefined,
+    "aria-expanded": item.open ? "true" : "false",
+    children,
+    // What the arrow keys look for. Not a role, because the accordion pattern
+    // has none to look for; see the module header.
+    "data-accordion-trigger": "",
+    id: item.triggerId,
+    onClick: composeHandlers(rest.onClick, () => {
+      if (!inert) {
+        item.toggle();
+      }
+    }),
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
 }
 
 /**
@@ -311,25 +333,30 @@ export component AccordionTrigger(children: React.Node, ...rest: Rest) {
  * `internal/disclosure.js` explains what "stays in the document" is worth and
  * what `hidden` is upgraded to for it.
  */
-export component AccordionContent(children: React.Node, ...rest: Rest) {
+export component AccordionContent(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const accordion = useAccordion("Accordion.Content");
   const item = useAccordionItem("Accordion.Content");
   const contentRef = useRef<HTMLElement | null>(null);
   usePresence(item.registerContent);
   useUntilFound(contentRef, item.open);
+  useMeasuredHeight(contentRef, accordion.measure);
 
-  return (
-    <div
-      {...withoutComposed(rest, ["ref"])}
-      // The name a reader hears for this landmark is the header they pressed.
-      aria-labelledby={item.triggerId}
-      hidden={!item.open}
-      id={item.contentId}
-      ref={composeRefs(rest.ref, (element) => {
-        contentRef.current = element;
-      })}
-      role="region"
-    >
-      {children}
-    </div>
-  );
+  const props = withProps(withoutComposed(rest, ["ref"]), {
+    // The name a reader hears for this landmark is the header they pressed.
+    "aria-labelledby": item.triggerId,
+    children,
+    hidden: !item.open,
+    id: item.contentId,
+    // React calls callback refs during commit; this node is only read by effects.
+    // uf-lint-disable-next-line react-compiler/refs
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      contentRef.current = element;
+    }),
+    role: "region",
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
 }

package/alert-dialog.js

@@ -0,0 +1,284 @@
+// @flow
+//
+// An alert dialog: the modal a reader has to answer.
+//
+// It is `dialog.js` with the three decisions that module's header names taken
+// the other way, and it is a component rather than a page of advice because
+// each of the three is silent when it is wrong:
+//
+//   * **`role="alertdialog"`.** A screen reader announces an `alertdialog`'s
+//     description as soon as focus arrives, without waiting to be asked. That
+//     is the whole of what the role buys, and it is why the description below
+//     is not optional.
+//   * **A press outside does not close it.** There is no way to decline by
+//     accident. `Escape` still closes it, because a modal a reader cannot leave
+//     from the keyboard is a trap and declining is what `Escape` means — so the
+//     two dismissals differ deliberately: the deliberate one works, the
+//     accidental one does not.
+//   * **Focus lands on `AlertDialog.Cancel`.** The APG puts it on the least
+//     destructive action, and `Cancel` is that action by construction here
+//     rather than by a caller remembering to pass a ref. A confirmation whose
+//     `Enter` deletes the project is a confirmation that asked nothing.
+//
+// # Why the description is required
+//
+// `aria-describedby` is what makes `alertdialog` worth using. An alert dialog
+// with nothing to announce is a `dialog` that has told the reader's software to
+// expect something urgent and then said only its title — which is worse than
+// the plain `Dialog`, because the reader has been interrupted for nothing.
+//
+// So `AlertDialog.Body` raises when no `AlertDialog.Description` is inside it.
+// Raising rather than warning, for the reason `useDialog` gives: the failure is
+// invisible in the markup, invisible in a screenshot, and audible only to
+// somebody who is not in the room. A component that lets it through ships it.
+//
+// # Action and Cancel are two parts, not one `Close` with a variant
+//
+// `Dialog.Close` closes the dialog and says nothing about what closing meant.
+// The two buttons of a confirmation mean opposite things — one carries out the
+// thing being confirmed, the other declines it — and a reader who has been
+// asked a question is entitled to have the answer be a named button rather
+// than a `variant="destructive"` on a shared one. `Cancel` is also the part
+// focus goes to, which is a behaviour a variant cannot carry.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useEffect, useMemo, useRef } from "@uniflowed/react";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { composeRefs, forwarded, withoutComposed } from "./internal/merge-props.js";
+import {
+  DialogBody,
+  DialogClose,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogRoot,
+  DialogTitle,
+  DialogTrigger,
+} from "./dialog.js";
+
+type AlertDialogState = {|
+  /**
+   * The least destructive action, and where focus goes.
+   *
+   * A ref rather than state, because nothing renders it: it is read once, by
+   * `Dialog.Body`'s focus effect, after the commit that attached it.
+   */
+  readonly cancelRef: { current: HTMLElement | null },
+  /**
+   * How many `AlertDialog.Description`s are in the document.
+   *
+   * A counted ref rather than the `described` boolean `Dialog.Root` already
+   * keeps, because that one is state: it is `false` on the commit that mounts
+   * the description, so a check against it would raise on every alert dialog
+   * ever rendered. A child's effect runs before its parent's, so by the time
+   * `AlertDialog.Body` asks, every description below it has answered.
+   */
+  readonly describedBy: { current: number },
+|};
+
+const AlertDialogContext: React.Context<AlertDialogState | null> = createContext(null);
+
+/**
+ * The alert dialog a part belongs to.
+ *
+ * Raising rather than returning null, for the reason `useDialog` gives: an
+ * `AlertDialog.Cancel` outside a root would render a button that closes nothing
+ * and takes no focus, and it would look correct.
+ */
+hook useAlertDialog(part: string): AlertDialogState {
+  const state = useContext(AlertDialogContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside an AlertDialog.Root`);
+  }
+  return state;
+}
+
+/** The alert dialog, open or closed. Uncontrolled unless `open` is given. */
+export component AlertDialogRoot(
+  children: React.Node,
+  defaultOpen?: boolean = false,
+  open?: boolean,
+  onOpenChange?: (open: boolean) => void,
+) {
+  const cancelRef = useRef<HTMLElement | null>(null);
+  const describedBy = useRef(0);
+  const state = useMemo(() => ({ cancelRef, describedBy }), []);
+
+  return (
+    <AlertDialogContext.Provider value={state}>
+      <DialogRoot defaultOpen={defaultOpen} onOpenChange={onOpenChange} open={open}>
+        {children}
+      </DialogRoot>
+    </AlertDialogContext.Provider>
+  );
+}
+
+/** What opens it, and what focus comes back to when it closes. */
+export component AlertDialogTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogTrigger {...forwarded(rest)} render={render}>
+      {children}
+    </DialogTrigger>
+  );
+}
+
+/** The backdrop. See `Dialog.Overlay`: it is decoration and says so. */
+export component AlertDialogOverlay(render?: RenderProp, ...rest: Rest) {
+  return <DialogOverlay {...forwarded(rest)} render={render} />;
+}
+
+/**
+ * The alert dialog itself: announced as one, described, and not dismissible by
+ * a press beside it.
+ *
+ * The three props it sets on `Dialog.Body` are the three the module header
+ * names, and they are set here rather than left to a caller because a caller
+ * who set two of them would have an alert dialog that is wrong in the third
+ * without anything saying so.
+ */
+export component AlertDialogBody(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const alert = useAlertDialog("AlertDialog.Body");
+
+  return (
+    <DialogBody
+      {...forwarded(rest)}
+      dismissOnOutsidePress={false}
+      initialFocus={alert.cancelRef}
+      render={render}
+      role="alertdialog"
+    >
+      {children}
+      <RequireDescription />
+    </DialogBody>
+  );
+}
+
+/**
+ * The check that there is something to announce, made where it is answerable.
+ *
+ * Inside `Dialog.Body` and last, and both halves are load-bearing. Inside,
+ * because `Dialog.Body` renders nothing at all while it is closed — an alert
+ * dialog that has not been opened has no description in the document, and a
+ * check in `AlertDialog.Body` itself therefore fired on every alert dialog ever
+ * rendered. Last, because React runs a subtree's effects in document order, so
+ * every `AlertDialog.Description` above this has already counted itself by the
+ * time this asks.
+ *
+ * It renders nothing, which is the point: the requirement is about the tree and
+ * not about the markup.
+ */
+component RequireDescription() {
+  const alert = useAlertDialog("AlertDialog.Body");
+  const describedBy = alert.describedBy;
+
+  useEffect(() => {
+    if (describedBy.current === 0) {
+      throw new Error(
+        "AlertDialog.Body must contain an AlertDialog.Description: " +
+          'role="alertdialog" exists to announce one, and an alert dialog ' +
+          "without a description interrupts the reader to say nothing.",
+      );
+    }
+  }, [describedBy]);
+
+  return null;
+}
+
+/** The top of the alert dialog. See `Dialog.Header` for why it is a `div`. */
+export component AlertDialogHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogHeader {...forwarded(rest)} render={render}>
+      {children}
+    </DialogHeader>
+  );
+}
+
+/** The bottom, where `Action` and `Cancel` go. */
+export component AlertDialogFooter(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogFooter {...forwarded(rest)} render={render}>
+      {children}
+    </DialogFooter>
+  );
+}
+
+/** The question, which is the alert dialog's accessible name. */
+export component AlertDialogTitle(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogTitle {...forwarded(rest)} render={render}>
+      {children}
+    </DialogTitle>
+  );
+}
+
+/**
+ * What answering costs, announced the moment focus arrives.
+ *
+ * This is where "this cannot be undone" belongs. It is the sentence the role
+ * exists to deliver, and the only moment the reader has to decide whether they
+ * care is before they have pressed anything.
+ */
+export component AlertDialogDescription(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const alert = useAlertDialog("AlertDialog.Description");
+  const describedBy = alert.describedBy;
+
+  useEffect(() => {
+    // This mount counter is a ref because it is read by Dialog.Body after commit.
+    // uf-lint-disable-next-line react-compiler/immutability
+    describedBy.current += 1;
+    return () => {
+      describedBy.current -= 1;
+    };
+  }, [describedBy]);
+
+  return (
+    <DialogDescription {...forwarded(rest)} render={render}>
+      {children}
+    </DialogDescription>
+  );
+}
+
+/**
+ * The button that carries out the thing being confirmed.
+ *
+ * It closes the dialog after the caller's handler has run, and it is not where
+ * focus starts; see `AlertDialog.Cancel`. `Dialog.Close` is what both answers
+ * are made of, so the composition rule about a caller's `onClick` has one
+ * implementation rather than a second copy here.
+ */
+export component AlertDialogAction(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogClose {...forwarded(rest)} render={render}>
+      {children}
+    </DialogClose>
+  );
+}
+
+/**
+ * The button that declines, and the one focus lands on.
+ *
+ * It registers itself so `AlertDialog.Body` can name it as the initial focus
+ * without the caller wiring a ref: the least destructive action is a fact about
+ * which part this is, not a decision to be repeated at every call.
+ */
+export component AlertDialogCancel(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const alert = useAlertDialog("AlertDialog.Cancel");
+  const cancelRef = alert.cancelRef;
+  const passed = withoutComposed(rest, ["ref"]);
+
+  return (
+    <DialogClose
+      {...forwarded(passed)}
+      ref={composeRefs(rest.ref, (element: HTMLElement | null) => {
+        cancelRef.current = element;
+      })}
+      render={render}
+    >
+      {children}
+    </DialogClose>
+  );
+}

package/alert.js

@@ -0,0 +1,142 @@
+// @flow
+//
+// A callout, and the live region it must not be by default.
+//
+// Of the twenty components in the catalogue that look like a class list, this
+// is the one whose usual shape is arguably wrong to copy rather than merely
+// empty. Every version of it renders `<div role="alert">`, always, and that one
+// attribute is a decision about interrupting the reader that nobody made.
+//
+// # `role="alert"` is a live region, not a colour
+//
+// A live region announces *changes*. An element carrying one that is already in
+// the document when the page loads has no change to report, so it is announced
+// on insertion or it is not announced at all — and which of those you get is a
+// property of the moment the element entered the document, not of the element.
+//
+// So a permanently rendered "your trial ends soon" box with `role="alert"` is
+// one of two things, both bad:
+//
+//   * an **interruption on every page load**, on the engines that treat the
+//     initial render as an insertion — the reader is pulled out of whatever
+//     they were doing to hear a sentence that was equally true yesterday;
+//   * or **silence**, on the engines that do not — in which case the role was
+//     decoration, and the box is read in its ordinary place in the page like
+//     the `<div>` it is.
+//
+// Neither is what the author wanted, and neither is visible in a screenshot.
+// The two cases have to be told apart by the caller, because the caller is the
+// only one who knows which one they have:
+//
+//   * a **static callout** — a panel that is part of the page — is a container
+//     with a heading and no live semantics at all. It is read where a reader
+//     reaches it, and heading navigation finds it, which is what `Alert.Title`
+//     being a real heading is for.
+//   * an **alert** — something that appeared because something happened — is
+//     `live`, and is `role="alert"`.
+//
+// `field.js` already makes exactly this call for `Field.Error`, which is
+// rendered only once the field is wrong and is `role="alert"` for that reason.
+//
+// # Why `live` is a boolean and there is no polite option
+//
+// Because a polite one cannot be built this way, and offering it would be
+// offering silence. `combobox.js` states the rule: a live region added to the
+// page in the same commit as the text it holds is usually not announced,
+// because the technology watching it had nothing to watch until it was already
+// too late. `role="status"` is polite, so it is subject to that rule in full —
+// a polite region has to have been in the document *first*, empty, and a
+// component you render at the moment the thing happens never was.
+//
+// `role="alert"` is assertive, and assertive regions are announced on insertion
+// by every engine that implements them; that is what the role is for. So the
+// one live shape this component can honestly offer is the assertive one.
+//
+// The polite, page-level shape is `Toast`, which is the component that exists
+// to have been watching already — `toast.js` and ubugeeei-prod/uf#289. An
+// application that wants "saved" said politely wants a toast, not an alert, and
+// pointing at it is a better answer than a `live="polite"` that does nothing.
+//
+// # No `"use client"`
+//
+// It holds no state, listens to nothing and manages no focus. Which of the two
+// alerts this is arrived as a prop, and the heading level did too. It renders
+// on a server.
+
+import * as React from "@uniflowed/react";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { withProps } from "./internal/merge-props.js";
+
+/**
+ * A callout: a panel that is part of the page, or one that just appeared.
+ *
+ * `live` is the whole component. Without it there is no role, deliberately —
+ * a box a reader reaches in reading order needs no announcement, and giving it
+ * one costs an interruption on every page load or nothing at all. With it the
+ * container is `role="alert"`, which is assertive and therefore the one live
+ * shape that is announced when it is inserted with its text in it.
+ *
+ *     {error != null && (
+ *       <Alert.Root live>
+ *         <Alert.Title>Could not save</Alert.Title>
+ *         <Alert.Description>{error}</Alert.Description>
+ *       </Alert.Root>
+ *     )}
+ *
+ * Rendered unconditionally with `live` on it, this is the mistake the module
+ * header is about: the role is a promise about a change, and a box that was
+ * always there has no change to report.
+ */
+export component AlertRoot(
+  children: React.Node,
+  live?: boolean = false,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const props = withProps(rest, { children, role: live ? "alert" : undefined });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
+}
+
+/**
+ * The callout's heading.
+ *
+ * A real heading rather than a bold `<div>`, because a heading is how a screen
+ * reader user finds a region of a page without reading it — and a callout
+ * nobody can jump to is a callout that has to be walked into.
+ *
+ * `level` is the caller's for the reason `accordion.js` gives for the same
+ * prop: the level that keeps a document outline true depends on what the
+ * callout is inside, and a hard-coded one produces an outline nobody can
+ * navigate. The guess is stated rather than hidden — `3`, which is right for a
+ * callout inside a section that has a title of its own — and a level outside
+ * the six HTML has is clamped, because `<h7>` is not an element and is
+ * announced as nothing at all.
+ */
+export component AlertTitle(
+  children: React.Node,
+  level?: number = 3,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const clamped = Math.min(6, Math.max(1, Math.trunc(level)));
+  const Heading = `h${String(clamped)}`;
+  const props = withProps(rest, { children });
+
+  if (render != null) {
+    return render(withProps(props, { "aria-level": clamped, role: "heading" }));
+  }
+  return <Heading {...props} />;
+}
+
+/** What the callout says, under its heading. */
+export component AlertDescription(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { children });
+  if (render != null) {
+    return render(props);
+  }
+  return <p {...props} />;
+}