@uniflowed/ui 0.0.0-alpha.10

package/accordion.js

@@ -0,0 +1,335 @@
+// @flow
+//
+// An accordion: a stack of disclosures that know about each other.
+//
+// The disclosure itself is `collapsible.js` and the argument for the closed
+// panel staying in the document is `internal/disclosure.js`. What this adds is
+// everything that follows from the sections being a *stack*, and every one of
+// them is a thing a hand-written accordion leaves out.
+//
+// # The heading level is the caller's
+//
+// The trigger is a button inside a heading, and which heading depends entirely
+// on where the accordion sits: inside a section titled by an `<h2>` it must be
+// an `<h3>`, and at the top of a page it might be an `<h2>`. A component that
+// hard-codes one produces a document outline nobody can navigate — and skimming
+// by heading is how a screen-reader user reads a long page, so the outline is
+// not decoration. `Dialog.Title` hard-codes `<h2>`, which is defensible for a
+// dialog, because a dialog is a document of its own with one title in it. It is
+// not defensible here.
+//
+// # The panel is a named region
+//
+// `role="region"` with `aria-labelledby` naming the trigger that opens it, so
+// the panel turns up in a screen reader's list of landmarks under the name the
+// reader just pressed. An unnamed region is a landmark that says "region" and
+// nothing else, which is why the naming is wired here rather than left as
+// advice — and why the trigger's id and the panel's are made in one place.
+//
+// # `single`, `multiple`, and the section that cannot be closed
+//
+// A `single` accordion keeps one section open; `multiple` lets any number be.
+// `collapsible` asks whether the open section of a `single` accordion may be
+// closed again, leaving nothing open. When it may not, the open section's
+// trigger says `aria-disabled="true"` rather than `disabled`, so a reader is
+// told "pressing this does nothing" instead of finding that a header they can
+// see has vanished from the accessibility tree — the same distinction
+// `menu.js` and `tabs.js` make, for the same reason.
+//
+// It has one consequence worth stating, because it is the opposite of every
+// other set in this package: the arrow keys **land on** a disabled header here
+// rather than stepping over it. `moveTo`'s `skipDisabled` is where that lives.
+// An accordion's headers are ordinary buttons in the page's tab order — `Tab`
+// reaches every one of them — so arrows that skipped one would disagree with
+// `Tab` about which headers exist.
+//
+// # The headers are not a roving tab stop
+//
+// This is the difference between an accordion and a tab list, and it is easy to
+// get backwards. A tab list is *one* control, so it takes one stop in the tab
+// order and the arrows move inside it. An accordion is a stack of ordinary
+// buttons that happen to be near each other: `Tab` reaches every header,
+// because each one is a real control a reader might want to press. The arrow
+// keys between headers are a convenience the practices call optional, and they
+// are here because a long FAQ is nicer with them — but nothing about them takes
+// a header out of the tab order.
+//
+// # How the sections are found
+//
+// By a `data-*` attribute of this package's own rather than by role, which is
+// the exception to what `roving-focus.js`'s other sets do. There is no ARIA
+// role for an accordion, nor for one of its headers — the pattern is built out
+// of headings and buttons — so there is no role to ask for, and an accordion
+// nested inside another accordion's panel still has to keep its own arrow keys
+// to itself. That needs a name for the container and a name for the header, and
+// this package has to be the one to give them.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+
+import type { Rest } from "./internal/merge-props.js";
+import { composeHandlers, composeRefs, 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 { useControlled } from "./internal/controlled-state.js";
+
+/** Whether one section is open at a time, or any number of them. */
+export type AccordionType = "single" | "multiple";
+
+/** Nothing open, as one array rather than a new one per render. */
+const NOTHING: $ReadOnlyArray<string> = [];
+
+/**
+ * The headers the arrow keys run across, and what owns them.
+ *
+ * `skipDisabled` is false, which is this set's one departure from every other
+ * one here; the module header says why.
+ */
+const HEADERS: RovingSet = {
+  item: "[data-accordion-trigger]",
+  owner: "[data-accordion]",
+  orientation: "vertical",
+  wrap: true,
+  skipDisabled: false,
+};
+
+type AccordionState = {|
+  readonly open: $ReadOnlyArray<string>,
+  readonly toggle: (value: string) => void,
+  /** Whether closing the last open section is allowed; only meaningful for `single`. */
+  readonly closable: boolean,
+  readonly type: AccordionType,
+|};
+
+const AccordionContext: React.Context<AccordionState | null> = createContext(null);
+
+type AccordionItemState = {|
+  readonly triggerId: string,
+  readonly contentId: string,
+  readonly open: boolean,
+  readonly toggle: () => void,
+  /** True when this section is open and the accordion will not let it close. */
+  readonly locked: boolean,
+  readonly disabled: boolean,
+  /** Whether an `Accordion.Content` is rendered, so the trigger names one that exists. */
+  readonly present: boolean,
+  readonly registerContent: (present: boolean) => void,
+|};
+
+const AccordionItemContext: React.Context<AccordionItemState | null> = createContext(null);
+
+hook useAccordion(part: string): AccordionState {
+  const state = useContext(AccordionContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside an Accordion.Root`);
+  }
+  return state;
+}
+
+hook useAccordionItem(part: string): AccordionItemState {
+  const state = useContext(AccordionItemContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside an Accordion.Item`);
+  }
+  return state;
+}
+
+/**
+ * The stack, and the one place the arrow keys are handled.
+ *
+ * `value` is the list of open sections in both modes, for the reason
+ * `toggle-group.js` gives at greater length: in `single` mode it holds at most
+ * one, and keeping that invariant is the component's job rather than the
+ * caller's to remember.
+ */
+export component AccordionRoot(
+  children: renders* AccordionItem,
+  type?: AccordionType = "single",
+  collapsible?: boolean = true,
+  defaultValue?: $ReadOnlyArray<string> = NOTHING,
+  value?: $ReadOnlyArray<string>,
+  onValueChange?: (value: $ReadOnlyArray<string>) => void,
+  ...rest: Rest
+) {
+  const [open, setOpen] = useControlled<$ReadOnlyArray<string>>(value, defaultValue, onValueChange);
+
+  const toggle = useCallback(
+    (item: string) => {
+      const isOpen = open.includes(item);
+      if (type === "multiple") {
+        setOpen(isOpen ? open.filter((each) => each !== item) : [...open, item]);
+        return;
+      }
+      // Opening one closes the other, which is the whole of `single`. Closing
+      // the open one is a separate question, and `collapsible` answers it.
+      if (isOpen && !collapsible) {
+        return;
+      }
+      setOpen(isOpen ? NOTHING : [item]);
+    },
+    [open, setOpen, type, collapsible],
+  );
+
+  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],
+  );
+  const passed = withoutComposed(rest, ["onKeyDown"]);
+
+  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>
+    </AccordionContext.Provider>
+  );
+}
+
+/**
+ * One section: a header and the panel it shows.
+ *
+ * Renders a `<div>` because a section needs an element to be styled as one, and
+ * because the heading and the panel have to be siblings rather than nested —
+ * a panel inside its own heading would be part of the heading's accessible
+ * name.
+ */
+export component AccordionItem(
+  value: string,
+  children: renders* (AccordionHeader | AccordionContent),
+  disabled?: boolean = false,
+  ...rest: Rest
+) {
+  const accordion = useAccordion("Accordion.Item");
+  const base = useId();
+  const [present, setPresent] = useState(false);
+  const open = accordion.open.includes(value);
+  const toggle = accordion.toggle;
+
+  const state = useMemo(
+    () => ({
+      triggerId: `${base}-trigger`,
+      contentId: `${base}-content`,
+      open,
+      toggle: () => toggle(value),
+      locked: open && !accordion.closable,
+      disabled,
+      present,
+      registerContent: setPresent,
+    }),
+    [base, open, toggle, value, accordion.closable, disabled, present],
+  );
+
+  return (
+    <AccordionItemContext.Provider value={state}>
+      <div {...rest}>{children}</div>
+    </AccordionItemContext.Provider>
+  );
+}
+
+/**
+ * The heading the trigger lives in.
+ *
+ * `level` is the caller's and has no sensible default beyond a guess, so the
+ * guess is stated: `3`, which is right for an accordion inside a section that
+ * has a title of its own. HTML has six levels and `<h7>` is not an element, so
+ * a level outside that range is clamped rather than rendered — a tag nobody
+ * recognises is announced as nothing at all, which loses the heading entirely.
+ */
+export component AccordionHeader(
+  children: renders AccordionTrigger,
+  level?: number = 3,
+  ...rest: Rest
+) {
+  const clamped = Math.min(6, Math.max(1, Math.trunc(level)));
+  const Heading = `h${String(clamped)}`;
+
+  return <Heading {...rest}>{children}</Heading>;
+}
+
+/**
+ * The button that opens and closes the section.
+ *
+ * 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) {
+  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>
+  );
+}
+
+/**
+ * The panel, which is a named region and stays in the document while closed.
+ *
+ * `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) {
+  const item = useAccordionItem("Accordion.Content");
+  const contentRef = useRef<HTMLElement | null>(null);
+  usePresence(item.registerContent);
+  useUntilFound(contentRef, item.open);
+
+  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>
+  );
+}

package/alert-dialog.js

@@ -0,0 +1,256 @@
+// @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 { 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, ...rest: Rest) {
+  return <DialogTrigger {...forwarded(rest)}>{children}</DialogTrigger>;
+}
+
+/** The backdrop. See `Dialog.Overlay`: it is decoration and says so. */
+export component AlertDialogOverlay(...rest: Rest) {
+  return <DialogOverlay {...forwarded(rest)} />;
+}
+
+/**
+ * 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, ...rest: Rest) {
+  const alert = useAlertDialog("AlertDialog.Body");
+
+  return (
+    <DialogBody
+      {...forwarded(rest)}
+      dismissOnOutsidePress={false}
+      initialFocus={alert.cancelRef}
+      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, ...rest: Rest) {
+  return <DialogHeader {...forwarded(rest)}>{children}</DialogHeader>;
+}
+
+/** The bottom, where `Action` and `Cancel` go. */
+export component AlertDialogFooter(children: React.Node, ...rest: Rest) {
+  return <DialogFooter {...forwarded(rest)}>{children}</DialogFooter>;
+}
+
+/** The question, which is the alert dialog's accessible name. */
+export component AlertDialogTitle(children: React.Node, ...rest: Rest) {
+  return <DialogTitle {...forwarded(rest)}>{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, ...rest: Rest) {
+  const alert = useAlertDialog("AlertDialog.Description");
+  const describedBy = alert.describedBy;
+
+  useEffect(() => {
+    describedBy.current += 1;
+    return () => {
+      describedBy.current -= 1;
+    };
+  }, [describedBy]);
+
+  return <DialogDescription {...forwarded(rest)}>{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, ...rest: Rest) {
+  return <DialogClose {...forwarded(rest)}>{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, ...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;
+      })}
+    >
+      {children}
+    </DialogClose>
+  );
+}