@uniflowed/ui 0.0.0-alpha.10

package/carousel.js

@@ -0,0 +1,410 @@
+// @flow
+//
+// A carousel: content that moves, which is the one thing on a page a
+// specification tells you to let people stop.
+//
+// # What it gives that a list does not
+//
+// Nothing, for a reader who can see it. A carousel is a list of things shown
+// one at a time, and the plain HTML it replaces — a list — is better at every
+// job except fitting in a small space. So the whole of this module is the part
+// that keeps the replacement from being worse than the list:
+//
+//   * **It can be stopped.** WCAG 2.2.2, *Pause, Stop, Hide*: anything that
+//     starts automatically, moves, and lasts more than five seconds needs a
+//     mechanism to pause it. `Carousel.Pause` is that mechanism, and it must be
+//     the **first** focusable thing inside the carousel — a pause button after
+//     the slides is a pause button nobody reaches in time. That is enforced
+//     here rather than suggested: an autoplaying carousel whose first focus
+//     stop is not the pause control raises.
+//   * **It says what it is.** `aria-roledescription="carousel"` on a named
+//     group, and `aria-roledescription="slide"` with "3 of 7" on each slide.
+//     Without them a reader is told "group, group" and has no way to know
+//     where they are or how much of it there is.
+//   * **It stops announcing itself while it moves.** The slide container is
+//     `aria-live="off"` while it is rotating and `"polite"` while it is not.
+//     A live region that reads out every slide of an auto-rotating carousel is
+//     unusable, and one that never announces anything makes the Next button
+//     silent.
+//   * **`Tab` cannot walk into a slide nobody can see.** This is the bug that
+//     survives every other fix. The slides that are scrolled out of view are
+//     still in the DOM, so their links and buttons are still focus stops — and
+//     a reader who tabs into one is in content the page is not showing. They
+//     are `inert`, which takes them out of the tab order *and* out of the
+//     accessibility tree, and which `internal/focus.js` already skips.
+//   * **It respects `prefers-reduced-motion`.** A reader who asked their system
+//     to stop moving things gets a carousel that does not rotate on its own.
+//     `usePrefersReducedMotion` from `@uniflowed/hooks/browser`.
+//
+// Rotation also stops while the pointer is over it and while focus is inside
+// it — a reader in the middle of reading a slide should not have it taken away
+// — and once `Carousel.Pause` has been pressed it stays stopped, because that
+// was a decision rather than a hover.
+//
+// # Why the caller counts the slides
+//
+// `Carousel.Root` takes `count` and `Carousel.Item` takes `index`, the same way
+// `Table.Root` takes `rowCount` and `Table.Row` takes `index`. The alternative
+// — counting the children — is wrong the first time a caller renders a slide
+// conditionally, filters a list, or wraps one in a component of their own, and
+// it is wrong silently: the label says "3 of 6" in a carousel with seven
+// slides, which is exactly the sentence a reader is relying on.
+//
+// # It is a `group`, not a `region`
+//
+// A `region` is a landmark, and a landmark is a promise that this is one of the
+// handful of places worth jumping to on the page. A gallery of photographs
+// three screens down is not, and a page with four carousels in it would put
+// four entries in a reader's landmark list. `role="group"` says the same thing
+// about the relationship between the slides without making that claim; a caller
+// whose carousel *is* the page can pass `role="region"` and get it.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+import { usePrefersReducedMotion } from "@uniflowed/hooks/browser";
+
+import type { Orientation } from "./internal/roving-focus.js";
+import type { Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  forwarded,
+  withoutComposed,
+} from "./internal/merge-props.js";
+import { focusable } from "./internal/focus.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+export type { Orientation } from "./internal/roving-focus.js";
+
+type CarouselState = {|
+  readonly base: string,
+  readonly count: number,
+  readonly index: number,
+  readonly setIndex: (next: number) => void,
+  readonly loop: boolean,
+  readonly orientation: Orientation,
+  /** Whether it is rotating right now, which is what `aria-live` reads. */
+  readonly rotating: boolean,
+  /** Whether the reader stopped it on purpose, which nothing but they undo. */
+  readonly stopped: boolean,
+  readonly setStopped: (stopped: boolean) => void,
+  /** Whether a rotation was ever asked for, so `Carousel.Pause` can say so. */
+  readonly rotates: boolean,
+  readonly registerPause: (present: boolean) => void,
+|};
+
+const CarouselContext: React.Context<CarouselState | null> = createContext(null);
+
+/**
+ * The carousel a part belongs to.
+ *
+ * Raising rather than returning null, for the reason `useDialog` gives: a
+ * `Carousel.Item` outside a root would render a slide labelled "1 of 0".
+ */
+hook useCarousel(part: string): CarouselState {
+  const state = useContext(CarouselContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Carousel.Root`);
+  }
+  return state;
+}
+
+/**
+ * The carousel: a named group of slides, one of them showing.
+ *
+ * `autoplay` is how many milliseconds each slide is shown for, or `null` for a
+ * carousel that only moves when it is asked to. A carousel that rotates must
+ * hold a `Carousel.Pause`, and that one must be the first thing `Tab` reaches
+ * inside it; both are checked.
+ */
+export component CarouselRoot(
+  children: React.Node,
+  autoplay?: number | null = null,
+  count: number,
+  defaultIndex?: number = 0,
+  index?: number,
+  label: string,
+  loop?: boolean = true,
+  onIndexChange?: (index: number) => void,
+  orientation?: Orientation = "horizontal",
+  ...rest: Rest
+) {
+  const base = useId();
+  const [current, setIndex] = useControlled(index, defaultIndex, onIndexChange);
+  const rootRef = useRef<HTMLElement | null>(null);
+  const paused = useRef(0);
+  const [stopped, setStopped] = useState(false);
+  // Whether the pointer or focus is resting on it. State rather than a ref,
+  // because the timer below is an effect and has to be torn down when it
+  // changes.
+  const [held, setHeld] = useState(false);
+  const reducedMotion = usePrefersReducedMotion();
+  const passed = withoutComposed(rest, [
+    "onBlur",
+    "onFocus",
+    "onPointerEnter",
+    "onPointerLeave",
+    "ref",
+  ]);
+  // Stable, so `Carousel.Pause`'s registration effect runs once rather than
+  // once per render of the root — which would decrement and re-increment the
+  // count, and leave it at zero for exactly as long as it takes the check
+  // below to read it.
+  const registerPause = useCallback((present: boolean) => {
+    paused.current += present ? 1 : -1;
+  }, []);
+
+  // A reader who asked their system to stop moving things has answered this
+  // question already, and the answer is not "rotate anyway and offer a button".
+  const rotates = autoplay != null && !reducedMotion;
+  const rotating = rotates && !stopped && !held;
+
+  const state = useMemo(
+    () => ({
+      base,
+      count,
+      index: current,
+      loop,
+      orientation,
+      registerPause,
+      rotates,
+      rotating,
+      setIndex,
+      setStopped,
+      stopped,
+    }),
+    [base, count, current, loop, orientation, registerPause, rotates, rotating, setIndex, stopped],
+  );
+
+  useEffect(() => {
+    if (!rotating || count <= 1) {
+      return;
+    }
+    // The global timer rather than the document's, the same as
+    // `internal/hover-intent.js`: one clock for the package, and the one a
+    // caller's fake timers replace.
+    const timer = setTimeout(() => {
+      setIndex(current === count - 1 ? 0 : current + 1);
+    }, autoplay ?? 0);
+    return () => {
+      clearTimeout(timer);
+    };
+    // `current` is named, so each slide's turn is timed from the moment it
+    // arrived rather than from a repeating interval that keeps running while
+    // the reader presses Next.
+  }, [autoplay, count, current, rotating, setIndex]);
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!rotates || root == null) {
+      return;
+    }
+    if (paused.current === 0) {
+      throw new Error(
+        "A Carousel.Root with autoplay must hold a Carousel.Pause: WCAG 2.2.2 " +
+          "requires a mechanism to stop anything that moves by itself for more " +
+          "than five seconds.",
+      );
+    }
+    const first = focusable(root)[0];
+    if (first == null || first.getAttribute("data-uf-carousel-pause") == null) {
+      throw new Error(
+        "Carousel.Pause must be the first focusable element inside " +
+          "Carousel.Root: a pause control the reader reaches after the slides " +
+          "is one they reach after the thing they wanted to stop.",
+      );
+    }
+  }, [rotates]);
+
+  return (
+    <CarouselContext.Provider value={state}>
+      <div
+        {...passed}
+        aria-label={label}
+        // What the reader is told instead of "group". Everything else here is
+        // arrangement; this is the sentence.
+        aria-roledescription="carousel"
+        data-orientation={orientation}
+        onBlur={composeHandlers(rest.onBlur, (event: $FlowFixMe) => {
+          if (!event.currentTarget?.contains?.(event.relatedTarget)) {
+            setHeld(false);
+          }
+        })}
+        // Rotation stops while a reader is in it and starts again when they
+        // leave — unless they stopped it deliberately, which `stopped` keeps.
+        onFocus={composeHandlers(rest.onFocus, () => setHeld(true))}
+        onPointerEnter={composeHandlers(rest.onPointerEnter, () => setHeld(true))}
+        onPointerLeave={composeHandlers(rest.onPointerLeave, () => setHeld(false))}
+        ref={composeRefs(rest.ref, (element: HTMLElement | null) => {
+          rootRef.current = element;
+        })}
+        role="group"
+      >
+        {children}
+      </div>
+    </CarouselContext.Provider>
+  );
+}
+
+/**
+ * The slides, and the live region that says which one is showing.
+ *
+ * `aria-live="off"` while it rotates: a live region reading out a slide every
+ * four seconds is a page a screen reader cannot be used on. `"polite"` the rest
+ * of the time, so pressing Next says something.
+ */
+export component CarouselContent(children: React.Node, ...rest: Rest) {
+  const carousel = useCarousel("Carousel.Content");
+
+  return (
+    <div
+      {...rest}
+      aria-live={carousel.rotating ? "off" : "polite"}
+      data-orientation={carousel.orientation}
+      id={`${carousel.base}-content`}
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * One slide, which says where in the set it is and gets out of the way when it
+ * is not the one showing.
+ *
+ * `inert` rather than a class: the slides that are not showing are still in the
+ * document, and without it `Tab` walks into a link nobody can see. It also
+ * takes the subtree out of the accessibility tree, which is what stops a reader
+ * being read six slides in a row.
+ */
+export component CarouselItem(children: React.Node, index: number, ...rest: Rest) {
+  const carousel = useCarousel("Carousel.Item");
+  const current = index === carousel.index;
+
+  return (
+    <div
+      {...rest}
+      // "3 of 7", which is the only way a reader knows where they are. A caller
+      // who has a better name for the slide keeps it.
+      aria-label={
+        rest["aria-label"] == null && rest["aria-labelledby"] == null
+          ? `${String(index + 1)} of ${String(carousel.count)}`
+          : undefined
+      }
+      aria-roledescription="slide"
+      data-state={current ? "active" : "inactive"}
+      // React renders `inert` from a boolean, and `undefined` removes it.
+      inert={current ? undefined : true}
+      role="group"
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * The control WCAG 2.2.2 is about, and the first thing `Tab` reaches.
+ *
+ * It says which state pressing it produces, which is what a toggle button is
+ * for: `aria-pressed` on a pause button is the announcement "pause, pressed",
+ * and a reader who has stopped a carousel wants to be told it is stopped.
+ */
+export component CarouselPause(
+  children?: React.Node,
+  pauseLabel?: string = "Stop the carousel",
+  playLabel?: string = "Start the carousel",
+  ...rest: Rest
+) {
+  const carousel = useCarousel("Carousel.Pause");
+  const register = carousel.registerPause;
+  const passed = withoutComposed(rest, ["onClick"]);
+  const named = rest["aria-label"] != null || rest["aria-labelledby"] != null;
+
+  useEffect(() => {
+    register(true);
+    return () => register(false);
+  }, [register]);
+
+  return (
+    <button
+      {...passed}
+      aria-controls={`${carousel.base}-content`}
+      aria-label={named ? undefined : carousel.stopped ? playLabel : pauseLabel}
+      aria-pressed={carousel.stopped ? "true" : "false"}
+      // How `Carousel.Root` recognises this button as the pause control without
+      // reaching into React's tree, which it has no way to do from an effect.
+      data-uf-carousel-pause=""
+      onClick={composeHandlers(rest.onClick, () => carousel.setStopped(!carousel.stopped))}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+/** The button that goes back one slide. */
+export component CarouselPrevious(
+  children?: React.Node,
+  label?: string = "Previous slide",
+  ...rest: Rest
+) {
+  return (
+    <CarouselStep {...forwarded(rest)} label={label} step={-1}>
+      {children}
+    </CarouselStep>
+  );
+}
+
+/** The button that goes forward one slide. */
+export component CarouselNext(children?: React.Node, label?: string = "Next slide", ...rest: Rest) {
+  return (
+    <CarouselStep {...forwarded(rest)} label={label} step={1}>
+      {children}
+    </CarouselStep>
+  );
+}
+
+/**
+ * Both of the stepping buttons.
+ *
+ * One component because the difference is a sign and a name, and two copies of
+ * the wrapping arithmetic is how a carousel comes to loop in one direction and
+ * stop in the other.
+ */
+component CarouselStep(children?: React.Node, label: string, step: number, ...rest: Rest) {
+  const carousel = useCarousel(step < 0 ? "Carousel.Previous" : "Carousel.Next");
+  const passed = withoutComposed(rest, ["onClick"]);
+  const last = carousel.count - 1;
+  const at = step < 0 ? 0 : last;
+  const wrapped = step < 0 ? last : 0;
+  const ends = carousel.index === at;
+
+  return (
+    <button
+      {...passed}
+      aria-controls={`${carousel.base}-content`}
+      aria-label={rest["aria-label"] == null ? label : undefined}
+      // Disabled at the end of a carousel that does not loop, because a button
+      // that does nothing is a button a reader presses twice before believing
+      // it.
+      disabled={!carousel.loop && ends}
+      onClick={composeHandlers(rest.onClick, () => {
+        carousel.setIndex(ends ? wrapped : carousel.index + step);
+      })}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}

package/checkbox.js

@@ -0,0 +1,80 @@
+// @flow
+//
+// A checkbox that is not an `<input>`, with the third state a checkbox has.
+//
+// A styled checkbox is almost always a `div` with a tick 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 while
+// shipping no styles.
+//
+// # The third state is the reason this is not `switch.js`
+//
+// A checkbox has three states — checked, unchecked and *mixed* — and a switch
+// has two. `aria-checked="mixed"` is what a "select all" box says when some of
+// its rows are selected, and there is no way to express it with a switch, which
+// is why this is a component of its own rather than `switch.js` with a
+// different `role`.
+//
+// Mixed is the caller's to own. A control cannot decide on its own that it is
+// no longer partly selected — that is a fact about the rows it summarises — so
+// `indeterminate` is a prop, and clicking a mixed checkbox reports `true`,
+// which is the state a reader expects "select all" to move to.
+//
+// # `Enter` is deliberately not handled
+//
+// `Space` toggles; `Enter` is left alone, so a checkbox inside a form still
+// submits it. That is the difference between a control that answers a question
+// and one that operates a thing — `switch.js` takes `Enter` because a switch is
+// the second kind.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+
+import type { Rest } from "./internal/merge-props.js";
+import { composeHandlers, withoutComposed } from "./internal/merge-props.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+/** A checkbox, which may also be mixed. */
+export component Checkbox(
+  checked?: boolean,
+  defaultChecked?: boolean = false,
+  indeterminate?: boolean = false,
+  onCheckedChange?: (checked: boolean) => void,
+  disabled?: boolean = false,
+  children?: React.Node,
+  ...rest: Rest
+) {
+  const [on, setOn] = useControlled(checked, defaultChecked, onCheckedChange);
+  // A mixed checkbox moves to checked, not to "the opposite of the boolean
+  // underneath it": a half-selected "select all" that clears itself on the
+  // first click is the behaviour every table in every application gets wrong.
+  const next = indeterminate ? true : !on;
+  const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
+
+  return (
+    <button
+      {...passed}
+      aria-checked={indeterminate ? "mixed" : on ? "true" : "false"}
+      disabled={disabled}
+      onClick={composeHandlers(rest.onClick, () => {
+        if (!disabled) {
+          setOn(next);
+        }
+      })}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        if (disabled || event.key !== " ") {
+          return;
+        }
+        // Stops `Space` scrolling the page, and stops the browser's own click
+        // arriving afterwards and toggling this a second time.
+        event.preventDefault();
+        setOn(next);
+      })}
+      role="checkbox"
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}

package/collapsible.js

@@ -0,0 +1,147 @@
+// @flow
+//
+// A button and the region it shows: the disclosure pattern, on its own.
+//
+// This is the smallest component in the package and it is here because the
+// three attributes it gets right are the three everybody leaves out.
+// `<button onClick={() => setOpen(!open)}>` with a `{open && <div>…</div>}`
+// after it looks finished and tells a screen reader nothing: not that the
+// button controls anything, not whether the thing is showing, and not which
+// region it is. A reader hears "Details, button" and has no way to know that
+// pressing it changed the page.
+//
+// So: `aria-expanded` on the trigger, `aria-controls` naming the content —
+// and only while there is content to name, because an `aria-controls` pointing
+// at an id nothing has is a promise the component cannot keep.
+//
+// # The closed content stays in the document
+//
+// `Tabs.Panel` returns `null` when it is not selected and that is right for a
+// tab set. Here it is wrong, and the reason is the browser's find-in-page: text
+// in a section that is not in the document cannot be found, so a page of
+// collapsed sections is a page a reader has to open by hand to search.
+// `internal/disclosure.js` explains what is done instead, and why React needs a
+// hook to say it.
+//
+// # No height, yet
+//
+// A collapsible that animates open needs the height its content *would* have,
+// which a stylesheet cannot compute — the obvious `useElementSize` from
+// `@uniflowed/hooks/dom` measures the element while it is hidden and reports
+// zero, which is exactly the moment the number is wanted. Getting it right
+// means a measuring pass with the panel briefly laid out and not painted, and
+// that is a piece of work of its own rather than a line to be added here — #330.
+// This component ships without it rather than with a custom property that reads
+// `0px`.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, 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 { usePresence, useUntilFound } from "./internal/disclosure.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+type CollapsibleState = {|
+  readonly contentId: string,
+  readonly open: boolean,
+  readonly setOpen: (open: boolean) => void,
+  /** Whether a `Collapsible.Content` is rendered, so the trigger names one that exists. */
+  readonly present: boolean,
+  readonly registerContent: (present: boolean) => void,
+|};
+
+const CollapsibleContext: React.Context<CollapsibleState | null> = createContext(null);
+
+hook useCollapsible(part: string): CollapsibleState {
+  const state = useContext(CollapsibleContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Collapsible.Root`);
+  }
+  return state;
+}
+
+/**
+ * The pair, and the state they agree about.
+ *
+ * Renders no element of its own: a trigger and its content are siblings in
+ * whatever layout the caller wrote, and a wrapper would put a `<div>` between
+ * them that the caller then has to style around. `Menu.Root` makes the same
+ * choice for the same reason.
+ */
+export component CollapsibleRoot(
+  children: React.Node,
+  defaultOpen?: boolean = false,
+  open?: boolean,
+  onOpenChange?: (open: boolean) => void,
+) {
+  const contentId = `${useId()}-content`;
+  const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
+  const [present, setPresent] = useState(false);
+
+  const state = useMemo(
+    () => ({ contentId, open: isOpen, setOpen, present, registerContent: setPresent }),
+    [contentId, isOpen, setOpen, present],
+  );
+
+  return <CollapsibleContext.Provider value={state}>{children}</CollapsibleContext.Provider>;
+}
+
+/** The button that shows and hides the content. */
+export component CollapsibleTrigger(
+  children: React.Node,
+  disabled?: boolean = false,
+  ...rest: Rest
+) {
+  const collapsible = useCollapsible("Collapsible.Trigger");
+  const passed = withoutComposed(rest, ["onClick"]);
+
+  return (
+    <button
+      {...passed}
+      // Named only while the content is in the document. A caller who renders
+      // the content conditionally — or not at all until data arrives — would
+      // otherwise have this button pointing at nothing.
+      aria-controls={collapsible.present ? collapsible.contentId : undefined}
+      aria-expanded={collapsible.open ? "true" : "false"}
+      disabled={disabled}
+      onClick={composeHandlers(rest.onClick, () => {
+        if (!disabled) {
+          collapsible.setOpen(!collapsible.open);
+        }
+      })}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+/**
+ * The region the trigger shows.
+ *
+ * It is always rendered and `hidden` while closed, rather than removed — see
+ * the module header, and `internal/disclosure.js` for what `hidden` is upgraded
+ * to and why that takes an effect.
+ */
+export component CollapsibleContent(children: React.Node, ...rest: Rest) {
+  const collapsible = useCollapsible("Collapsible.Content");
+  const contentRef = useRef<HTMLElement | null>(null);
+  usePresence(collapsible.registerContent);
+  useUntilFound(contentRef, collapsible.open);
+
+  return (
+    <div
+      {...withoutComposed(rest, ["ref"])}
+      hidden={!collapsible.open}
+      id={collapsible.contentId}
+      ref={composeRefs(rest.ref, (element) => {
+        contentRef.current = element;
+      })}
+    >
+      {children}
+    </div>
+  );
+}