@uniflowed/ui 0.0.0-alpha.2 → 0.0.0-alpha.4

package/switch.js

@@ -0,0 +1,72 @@
+// @flow
+//
+// A switch: two states, and a screen reader that says which.
+//
+// It exists because the styled version of an on/off control is almost always a
+// `div` with a knob drawn in it, and the moment it stops being a real control it
+// stops being announced, stops toggling on `Space`, and stops being reachable by
+// `Tab`. This keeps all three — the role, the `aria-checked` state, and the
+// keys — while shipping no styles at all.
+//
+// # A switch is not a checkbox
+//
+// A screen reader says "on" and "off" for a switch and "checked" and
+// "unchecked" for a checkbox, and the two are not interchangeable: a checkbox
+// answers a question ("include me in the mailing list") and a switch operates a
+// thing ("notifications, on"). A checkbox also has a third state that a switch
+// does not, which is why `checkbox.js` is a separate component rather than this
+// one with a different `role`.
+//
+// The keyboard follows from the same distinction. `Space` toggles both. `Enter`
+// toggles a *switch*, because a switch is an operation and pressing Enter on
+// something that operates is what a reader expects — while `checkbox.js`
+// deliberately leaves `Enter` alone so that a checkbox inside a form still
+// submits it. That is the whole reason these are not one file with a flag.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+
+import { composeHandlers, withoutComposed } from "./internal/merge-props.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+/** A two-state switch: on or off. */
+export component Switch(
+  checked?: boolean,
+  defaultChecked?: boolean = false,
+  onCheckedChange?: (checked: boolean) => void,
+  disabled?: boolean = false,
+  children?: React.Node,
+  ...rest: { readonly [string]: mixed }
+) {
+  const [on, setOn] = useControlled(checked, defaultChecked, onCheckedChange);
+  const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
+
+  return (
+    <button
+      {...passed}
+      aria-checked={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 is not decoration. It stops `Space` scrolling
+        // the page — which is what makes a hand-written toggle feel broken even
+        // when it works — and it stops the browser's own click from arriving
+        // after this handler and toggling the switch a second time.
+        event.preventDefault();
+        setOn(!on);
+      })}
+      role="switch"
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}

package/tabs.js

@@ -0,0 +1,286 @@
+// @flow
+//
+// Tabs, with the keyboard behaviour the pattern requires.
+//
+// A tab list is not a row of buttons. Only one tab is in the page's tab order —
+// Tab moves *into* and *out of* the list, and the arrow keys move between the
+// tabs inside it — because a list of twelve tabs that each take a Tab press
+// makes everything after it unreachable for anyone not using a mouse. That is a
+// roving `tabindex`, and it is the thing hand-written tabs almost always leave
+// out.
+//
+// # Automatic and manual activation
+//
+// The second thing they leave out is the choice between them, and it is not a
+// preference: it is about what a panel costs to show.
+//
+//   * **Automatic** — the default. Moving to a tab selects it, so reaching a
+//     panel is one key press. This is what the pattern prescribes when the
+//     panels are already in the document and showing one is free.
+//   * **Manual** — arrow keys move focus and select nothing until `Enter` or
+//     `Space`. This is what a panel that fetches, or that takes real work to
+//     render, needs: with automatic activation a reader arrowing from the first
+//     tab to the fourth starts three loads they did not ask for, and a screen
+//     reader announces three panels they never wanted to hear about.
+//
+// # Which arrow keys
+//
+// `orientation` decides, and the keys it does *not* claim matter as much as the
+// ones it does: `ArrowDown` in a horizontal tab list belongs to the page, and a
+// component that swallows it has taken scrolling away from every reader who
+// uses the keyboard to read.
+//
+// # Composition is type-checked
+//
+// `Tabs.List` takes `renders* TabsTab`, so putting a `<button>` in the list is
+// a *type error* rather than a screen reader announcing "button" where the
+// reader expected "tab, 2 of 5". A library written in TypeScript can document
+// that constraint; Flow can state it.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+} from "@uniflowed/react";
+
+import { composeHandlers, withoutComposed } from "./internal/merge-props.js";
+import { indexOfActive, itemsOf, movementFor, moveTo } from "./internal/roving-focus.js";
+import { useControlled } from "./internal/controlled-state.js";
+import type { Orientation } from "./internal/roving-focus.js";
+
+/** When a tab becomes the selected one. */
+export type ActivationMode = "automatic" | "manual";
+
+type TabsState = {|
+  readonly base: string,
+  readonly selected: string,
+  readonly select: (value: string) => void,
+  readonly orientation: Orientation,
+  readonly activation: ActivationMode,
+  /** The panel values currently mounted, so a tab only claims one that exists. */
+  readonly mounted: $ReadOnlyArray<string>,
+  readonly registerPanel: (value: string, present: boolean) => void,
+|};
+
+const TabsContext: React.Context<TabsState | null> = createContext(null);
+
+hook useTabs(part: string): TabsState {
+  const state = useContext(TabsContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Tabs.Root`);
+  }
+  return state;
+}
+
+/**
+ * The tab set.
+ *
+ * Uncontrolled by default and controlled when `value` is given, which is the
+ * distinction every one of these components needs: a form library owns the
+ * value, and a page that just wants tabs does not.
+ */
+export component TabsRoot(
+  children: React.Node,
+  defaultValue: string,
+  value?: string,
+  onValueChange?: (value: string) => void,
+  activationMode?: ActivationMode = "automatic",
+  orientation?: Orientation = "horizontal",
+  ...rest: { readonly [string]: mixed }
+) {
+  const base = useId();
+  const [selected, select] = useControlled(value, defaultValue, onValueChange);
+  const [mounted, setMounted] = useState<$ReadOnlyArray<string>>([]);
+
+  // Functional updates, so two panels mounting in the same commit do not each
+  // overwrite the other's registration with a list computed before it existed.
+  const registerPanel = useCallback((panel: string, present: boolean) => {
+    setMounted((current) => {
+      const has = current.includes(panel);
+      if (present === has) {
+        return current;
+      }
+      return present ? [...current, panel] : current.filter((each) => each !== panel);
+    });
+  }, []);
+
+  const state = useMemo(
+    () => ({
+      base,
+      selected,
+      select,
+      orientation,
+      activation: activationMode,
+      mounted,
+      registerPanel,
+    }),
+    [base, selected, select, orientation, activationMode, mounted, registerPanel],
+  );
+
+  return (
+    <TabsContext.Provider value={state}>
+      <div {...rest}>{children}</div>
+    </TabsContext.Provider>
+  );
+}
+
+/**
+ * The row of tabs, and the one place the arrow keys are handled.
+ *
+ * The handler is here rather than on each tab because the keys are about the
+ * *set*: "the next tab" is a question only the list can answer, and answering it
+ * from the DOM at the moment of the press means a tab added, removed or
+ * reordered since the last render is still in the right place. A registry the
+ * tabs push themselves into as they mount answers with mount order, which stops
+ * being document order the first time a tab is conditional.
+ */
+export component TabsList(children: renders* TabsTab, ...rest: { readonly [string]: mixed }) {
+  const tabs = useTabs("Tabs.List");
+  const passed = withoutComposed(rest, ["onKeyDown"]);
+
+  return (
+    <div
+      {...passed}
+      // A screen reader announces the axis, and it is also what tells a reader
+      // which arrow keys to try.
+      aria-orientation={tabs.orientation}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        const list: $FlowFixMe = event.currentTarget;
+        const movement = movementFor(event.key, tabs.orientation);
+        if (movement == null) {
+          return;
+        }
+        const items = itemsOf(list, '[role="tab"]', '[role="tablist"]');
+        const active = list.ownerDocument?.activeElement;
+        const next = moveTo(items, indexOfActive(items, active), movement, true);
+        if (next == null) {
+          return;
+        }
+        // Before moving, or the arrow also scrolls the page under the tab that
+        // just took focus.
+        event.preventDefault();
+        next.focus();
+        if (tabs.activation === "automatic") {
+          tabs.select(next.getAttribute("data-value") ?? "");
+        }
+      })}
+      role="tablist"
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * One tab. Exactly one of them is in the page's tab order.
+ *
+ * A disabled tab is `aria-disabled` rather than `disabled`, so it stays in the
+ * accessibility tree: a reader is told "Billing, tab, dimmed, 3 of 5" and knows
+ * the section exists and is unavailable, where a native `disabled` would leave a
+ * gap they cannot ask about. The keyboard steps over it either way.
+ */
+export component TabsTab(
+  value: string,
+  children: React.Node,
+  disabled?: boolean = false,
+  ...rest: { readonly [string]: mixed }
+) {
+  const tabs = useTabs("Tabs.Tab");
+  const active = tabs.selected === value;
+  const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
+
+  return (
+    <button
+      // `passed` first, and everything this component owns after it. A caller
+      // `onClick` used to replace the selection handler, so clicking a tab did
+      // nothing at all.
+      {...passed}
+      aria-disabled={disabled ? "true" : undefined}
+      // Only when the panel is actually mounted. Panels are rendered on demand,
+      // and a tab pointing `aria-controls` at an id that is not in the document
+      // tells a reader there is somewhere to go and then has nowhere to send
+      // them.
+      aria-controls={tabs.mounted.includes(value) ? `${tabs.base}-panel-${value}` : undefined}
+      aria-selected={active ? "true" : "false"}
+      // Read by the list's key handler, which finds tabs in the document rather
+      // than in a registry and so needs each one to carry its own value.
+      data-value={value}
+      id={`${tabs.base}-tab-${value}`}
+      onClick={composeHandlers(rest.onClick, () => {
+        if (!disabled) {
+          tabs.select(value);
+        }
+      })}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        // Manual activation's other half: the arrows moved focus here without
+        // selecting, and this is how the reader says they meant it.
+        if (event.key !== "Enter" && event.key !== " ") {
+          return;
+        }
+        event.preventDefault();
+        if (!disabled) {
+          tabs.select(value);
+        }
+      })}
+      role="tab"
+      // The roving tabindex: Tab reaches the selected tab and nothing else in
+      // the list, so it moves past the whole set in one press.
+      tabIndex={active ? 0 : -1}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+/**
+ * The panel a tab controls, rendered only while its tab is selected.
+ *
+ * It registers itself with the root while it is mounted, which is what lets
+ * `Tabs.Tab` decide whether it has a panel to name. That has to be a real
+ * subscription rather than "the selected value equals mine", because a caller
+ * may render a subset of panels, or none at all until data arrives.
+ */
+export component TabsPanel(
+  value: string,
+  children: React.Node,
+  ...rest: { readonly [string]: mixed }
+) {
+  const tabs = useTabs("Tabs.Panel");
+  const register = tabs.registerPanel;
+  const selected = tabs.selected === value;
+
+  useEffect(() => {
+    if (!selected) {
+      return;
+    }
+    register(value, true);
+    return () => register(value, false);
+  }, [register, value, selected]);
+
+  if (!selected) {
+    return null;
+  }
+
+  return (
+    <div
+      {...rest}
+      aria-labelledby={`${tabs.base}-tab-${value}`}
+      id={`${tabs.base}-panel-${value}`}
+      role="tabpanel"
+      // The panel itself is focusable so that Tab out of the tab list lands on
+      // the content the tab describes, which is where the reader expects to go
+      // and where a panel of plain prose has nothing else to offer.
+      tabIndex={0}
+    >
+      {children}
+    </div>
+  );
+}

package/internal/dialog.js

@@ -1,236 +0,0 @@
-// @flow
-//
-// A modal dialog, which is the component people most often get wrong.
-//
-// Four things have to be true for a dialog to be usable by someone who is not
-// using a mouse, and a hand-written one usually has one or two of them:
-//
-//   * Focus moves into the dialog when it opens, and to the first thing worth
-//     acting on rather than to whatever happens to be first in the document.
-//   * Tab cannot leave. A dialog you can Tab out of leaves the reader
-//     somewhere in a page they cannot see, with no way back.
-//   * Escape closes it.
-//   * Focus returns to whatever opened it. Otherwise it restarts at the top of
-//     the document, and the reader has to find their place again.
-//
-// The dialog is rendered where it is declared rather than through a portal.
-// A portal solves a stacking-context problem that belongs to CSS, and it costs
-// the thing this component is for: rendered in place, the dialog is next to its
-// trigger in the accessibility tree, which is where a screen reader looks.
-
-import * as React from "@uniflowed/react";
-
-import { composeHandlers, composeRefs, withoutComposed } from "./props.js";
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useId,
-  useMemo,
-  useRef,
-  useState,
-} from "@uniflowed/react";
-
-type DialogState = {|
-  readonly base: string,
-  readonly open: boolean,
-  readonly setOpen: (open: boolean) => void,
-  readonly triggerRef: { current: HTMLElement | null },
-|};
-
-const DialogContext: React.Context<DialogState | null> = createContext(null);
-
-function useDialog(part: string): DialogState {
-  const state = useContext(DialogContext);
-  if (state == null) {
-    throw new Error(`${part} must be rendered inside a Dialog.Root`);
-  }
-  return state;
-}
-
-/** The dialog, open or closed. Uncontrolled unless `open` is given. */
-export component DialogRoot(
-  children: React.Node,
-  defaultOpen?: boolean = false,
-  open?: boolean,
-  onOpenChange?: (open: boolean) => void,
-) {
-  const base = useId();
-  const [internal, setInternal] = useState(defaultOpen);
-  const triggerRef = useRef<HTMLElement | null>(null);
-  const isOpen = open ?? internal;
-
-  const setOpen = useCallback(
-    (next: boolean) => {
-      if (open == null) {
-        setInternal(next);
-      }
-      onOpenChange?.(next);
-    },
-    [open, onOpenChange],
-  );
-
-  const state = useMemo(
-    () => ({ base, open: isOpen, setOpen, triggerRef }),
-    [base, isOpen, setOpen],
-  );
-
-  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: { readonly [string]: mixed }) {
-  const dialog = useDialog("Dialog.Trigger");
-  const passed = withoutComposed(rest, ["onClick", "ref"]);
-
-  return (
-    <button
-      {...passed}
-      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>
-  );
-}
-
-/**
- * The dialog itself: focus moved in, Tab kept inside, Escape closing it.
- *
- * `aria-modal` tells a screen reader that the rest of the page is not
- * available, which is the half of "modal" that CSS cannot express.
- */
-export component DialogContent(children: React.Node, ...rest: { readonly [string]: mixed }) {
-  const dialog = useDialog("Dialog.Content");
-  const contentRef = useRef<HTMLElement | null>(null);
-
-  useEffect(() => {
-    if (!dialog.open) {
-      return;
-    }
-    const opener = dialog.triggerRef.current;
-    const content = contentRef.current;
-    // The first thing worth acting on, not the first thing in the document —
-    // and the dialog itself if it contains nothing focusable, so focus is
-    // inside it either way.
-    const target = content == null ? null : (focusable(content)[0] ?? content);
-    target?.focus();
-
-    return () => {
-      // Back to the trigger. Leaving focus on a removed node sends it to the
-      // top of the document, and the reader has to find their place again.
-      opener?.focus();
-    };
-  }, [dialog.open, dialog.triggerRef]);
-
-  if (!dialog.open) {
-    return null;
-  }
-
-  const passed = withoutComposed(rest, ["onKeyDown", "ref"]);
-
-  return (
-    <div
-      // `passed` first. A caller `ref` used to replace `contentRef`, 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 the dialog.
-      {...passed}
-      aria-labelledby={`${dialog.base}-title`}
-      aria-modal="true"
-      id={`${dialog.base}-content`}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        if (event.key === "Escape") {
-          event.preventDefault();
-          dialog.setOpen(false);
-          return;
-        }
-        if (event.key !== "Tab") {
-          return;
-        }
-        const content = contentRef.current;
-        if (content == null) {
-          return;
-        }
-        const stops = focusable(content);
-        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 = content.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 === content)) {
-          event.preventDefault();
-          last.focus();
-        } else if (!event.shiftKey && active === last) {
-          event.preventDefault();
-          first.focus();
-        }
-      })}
-      ref={composeRefs(rest.ref, (element) => {
-        contentRef.current = element;
-      })}
-      role="dialog"
-      tabIndex={-1}
-    >
-      {children}
-    </div>
-  );
-}
-
-/** The dialog's accessible name, which `aria-labelledby` points at. */
-export component DialogTitle(children: React.Node, ...rest: { readonly [string]: mixed }) {
-  const dialog = useDialog("Dialog.Title");
-  return (
-    <h2 {...rest} id={`${dialog.base}-title`}>
-      {children}
-    </h2>
-  );
-}
-
-/** A button that closes the dialog. */
-export component DialogClose(children: React.Node, ...rest: { readonly [string]: mixed }) {
-  const dialog = useDialog("Dialog.Close");
-  const passed = withoutComposed(rest, ["onClick"]);
-
-  return (
-    <button
-      {...passed}
-      onClick={composeHandlers(rest.onClick, () => dialog.setOpen(false))}
-      type="button"
-    >
-      {children}
-    </button>
-  );
-}
-
-/**
- * The focus stops inside an element, in document order.
- *
- * Disabled controls and `tabindex="-1"` are excluded because the browser
- * excludes them, and anything inside `[hidden]` or `aria-hidden` is excluded
- * because a reader cannot see it.
- */
-function focusable(root: HTMLElement): Array<HTMLElement> {
-  const selector =
-    'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
-  return Array.from(root.querySelectorAll(selector)).filter(
-    (element: any) =>
-      // Both attributes hide a whole subtree, so both are checked on the
-      // ancestors. Reading `aria-hidden` off the element alone returned a
-      // button inside `<div aria-hidden="true">` as a focus stop, and the trap
-      // then moved focus to a control no screen reader exposes.
-      element.closest("[hidden]") == null && element.closest('[aria-hidden="true"]') == null,
-  );
-}