@uniflowed/ui 0.0.0-alpha.10

package/radio-group.js

@@ -0,0 +1,298 @@
+// @flow
+//
+// A radio group: several answers, where choosing one unchooses the rest.
+//
+// The group is the control, not the buttons in it. That is the sentence the
+// whole component follows from: a reader is told "Plan, radio group" and then
+// "Pro, radio button, 2 of 3, selected", the *set* takes one stop in the page's
+// tab order, and the arrow keys move inside it. Twelve hand-written radios take
+// twelve Tab presses to get past and announce themselves as twelve unrelated
+// buttons, which is a different widget wearing the same paint.
+//
+// # It is a tab list with automatic activation, under another name
+//
+// `tabs.js` already implements almost all of this: one tab stop, arrows that
+// move, and `activationMode="automatic"` where moving to an item selects it. A
+// radio group is that with `role="radio"` in place of `role="tab"` and no
+// manual mode at all — arrows in a radio group *always* check, because that is
+// what the pattern says, and a radio group whose arrows only moved focus would
+// leave a reader believing they had answered when they had not.
+//
+// The one thing it needs that no other set here does is **the initial tab
+// stop**. `Tabs.Tab` computes `tabIndex={active ? 0 : -1}` from the selection,
+// which is right for both — but `Tabs` always has a selection, because
+// `defaultValue` is required, and a radio group with nothing chosen is the
+// state every unanswered form starts in. With the tab stop derived from the
+// selection alone, nothing carries `tabindex="0"`, and an unanswered radio
+// group is unreachable from the keyboard: not hard to reach, not awkward —
+// absent. `internal/roving-focus.js`'s `useFirstItem` is the answer, and it is
+// there rather than here because a toggle group nobody has focused yet has the
+// same hole.
+//
+// # Which arrow keys, and a deviation stated rather than hidden
+//
+// The WAI-ARIA practices list both pairs for a radio group: `ArrowDown` and
+// `ArrowRight` both move to the next radio. This package gates on `orientation`
+// instead, as its tab list and its menu do, and the reason is the one
+// `internal/roving-focus.js` gives about the keys a component does *not* claim:
+// `ArrowDown` scrolls the page, and a horizontal row of three radios that
+// swallows it has taken reading away from everyone who reads with the keyboard
+// to buy a second way to do what `ArrowRight` already does. `aria-orientation`
+// says which pair is live, so a reader is told rather than left to guess, and
+// the default is `vertical` because that is how a radio group is nearly always
+// laid out.
+//
+// # Naming the group
+//
+// A radio group with no name is announced as "radio group" and nothing else,
+// which tells a reader that three answers exist and not what the question was.
+// There is no `RadioGroup.Label` part because `Field` already is one:
+//
+//     <Field.Root>
+//       <Field.Label>Plan</Field.Label>
+//       <Field.Control
+//         render={(props) => (
+//           <RadioGroup.Root {...props} defaultValue="free">…</RadioGroup.Root>
+//         )}
+//       />
+//     </Field.Root>
+//
+// `Field.Control` hands over `aria-labelledby` pointing at the label it
+// rendered, which is the wiring `Field` exists to get right, and a second
+// spelling of it here would be a second thing to keep in step.
+//
+// # Space, and the key that is not handled
+//
+// `Space` checks the focused radio, and prevents its default so the page does
+// not scroll and the browser's own click does not arrive afterwards and check
+// it a second time. `Enter` is not handled: it reaches these items as the
+// browser's own click on a `<button>` and checks them, which is the least
+// surprising thing for it to do. Claiming it in order to *stop* it would leave
+// the key dead — `type="button"` cannot submit a form either — which is worse
+// than the practices being quiet about it.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useCallback, useContext, useId, useMemo, useRef } from "@uniflowed/react";
+
+import type { Rest } from "./internal/merge-props.js";
+import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
+import { moveOnKey, useFirstItem } from "./internal/roving-focus.js";
+import type { Orientation, RovingSet } from "./internal/roving-focus.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+/**
+ * What the keyboard steps across in a radio group, and what owns one.
+ *
+ * By role rather than by a `data-*` attribute of this package's own, because
+ * that is the promise the component makes to a reader: whatever produced a
+ * `role="radio"` inside this group is one of the answers, and the arrow keys
+ * have to reach it. `ToggleGroup type="single"` renders through here and is the
+ * reason that matters in practice rather than in principle.
+ */
+export function radioSet(orientation: Orientation): RovingSet {
+  return {
+    item: '[role="radio"]',
+    owner: '[role="radiogroup"]',
+    orientation,
+    wrap: true,
+    skipDisabled: true,
+  };
+}
+
+type RadioGroupState = {|
+  readonly selected: string | null,
+  readonly select: (value: string) => void,
+  /** The item holding the tab stop while nothing is chosen; see `useFirstItem`. */
+  readonly firstId: string | null,
+|};
+
+const RadioGroupContext: React.Context<RadioGroupState | null> = createContext(null);
+
+/** Whether the surrounding item is the chosen one, for `RadioGroup.Indicator`. */
+type RadioItemState = {| readonly checked: boolean |};
+
+const RadioItemContext: React.Context<RadioItemState | null> = createContext(null);
+
+hook useRadioGroup(part: string): RadioGroupState {
+  const state = useContext(RadioGroupContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a RadioGroup.Root`);
+  }
+  return state;
+}
+
+/**
+ * The group, which is the control a reader is told about.
+ *
+ * `children` is `React.Node` rather than `renders* RadioGroupItem`, and the
+ * reason is worth stating rather than leaving as an omission. `ToggleGroup
+ * type="single"` is this component wearing segments: it renders a
+ * `RadioGroup.Root` and passes its own items through. A `renders*` constraint
+ * is a promise about the element a child produces, and a `ToggleGroup.Item`
+ * cannot make it — it produces a radio in one mode and a toggle button in the
+ * other — while naming both kinds here would make this module import the module
+ * that imports it. `Tabs.List` keeps the tighter promise because nothing else
+ * in this package renders a `tab`.
+ *
+ * `name` puts the answer where a form can submit it; see the hidden input
+ * below.
+ */
+export component RadioGroupRoot(
+  children: React.Node,
+  defaultValue?: string | null = null,
+  value?: string | null,
+  onValueChange?: (value: string) => void,
+  orientation?: Orientation = "vertical",
+  name?: string,
+  ...rest: Rest
+) {
+  // `onValueChange` promises a `string` while the group's *state* is
+  // `string | null`, and the two meet here rather than being flattened into one
+  // type that lies in one direction or the other: "nothing chosen yet" is a
+  // state a radio group starts in, and it is not an event it can ever report,
+  // because no gesture inside a radio group unchooses an answer. Widening the
+  // prop to `string | null` would also make every `(plan: string) => void` a
+  // caller already has a type error at the call site.
+  const report = useCallback(
+    (next: string | null) => {
+      if (next != null) {
+        onValueChange?.(next);
+      }
+    },
+    [onValueChange],
+  );
+  const [selected, select] = useControlled<string | null>(value, defaultValue, report);
+  const rootRef = useRef<HTMLElement | null>(null);
+  // Only while nothing is chosen. Once there is an answer it holds the tab
+  // stop, and asking the document which item comes first is work with no reader.
+  const firstId = useFirstItem(rootRef, radioSet(orientation), selected == null);
+
+  const state = useMemo(() => ({ selected, select, firstId }), [selected, select, firstId]);
+  const passed = withoutComposed(rest, ["onKeyDown", "ref"]);
+
+  return (
+    <RadioGroupContext.Provider value={state}>
+      <div
+        {...passed}
+        // A reader is told which axis this runs along, and it is also what says
+        // which pair of arrow keys is live.
+        aria-orientation={orientation}
+        onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+          const group: $FlowFixMe = event.currentTarget;
+          const next = moveOnKey(event, group, radioSet(orientation));
+          if (next != null) {
+            // Checking in the same key press is not a shortcut, it is the
+            // pattern: a radio group whose arrows moved focus without checking
+            // leaves a reader believing they have answered when they have not.
+            select(next.getAttribute("data-value") ?? "");
+          }
+        })}
+        ref={composeRefs(rest.ref, (element) => {
+          rootRef.current = element;
+        })}
+        role="radiogroup"
+      >
+        {children}
+        {/*
+          A form submits `<input>` elements, and none of the parts above is one.
+          Without this the group is a control a reader can operate and a form
+          cannot read, which is the same hole `Combobox` still has.
+
+          `type="hidden"` rather than a visually hidden real radio, because the
+          buttons above already carry the whole of the accessible semantics: a
+          second set of native radios would be announced as a second set of
+          answers, and hiding them from the accessibility tree to stop that
+          leaves elements a form's own validation would then point its
+          "please choose one" at.
+        */}
+        {name == null ? null : <input name={name} type="hidden" value={selected ?? ""} />}
+      </div>
+    </RadioGroupContext.Provider>
+  );
+}
+
+/**
+ * One answer.
+ *
+ * A disabled item is `aria-disabled` rather than `disabled`, so it stays in the
+ * accessibility tree: a reader is told "Enterprise, radio button, dimmed, 3 of
+ * 3" and learns that the answer exists and is unavailable, where a native
+ * `disabled` leaves a gap they cannot ask about. The arrow keys step over it
+ * either way, and so does the search for the item that holds the tab stop.
+ */
+export component RadioGroupItem(
+  value: string,
+  children?: React.Node,
+  disabled?: boolean = false,
+  ...rest: Rest
+) {
+  const group = useRadioGroup("RadioGroup.Item");
+  const id = useId();
+  const checked = group.selected === value;
+  const item = useMemo(() => ({ checked }), [checked]);
+  const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
+
+  return (
+    <RadioItemContext.Provider value={item}>
+      <button
+        {...passed}
+        aria-checked={checked ? "true" : "false"}
+        aria-disabled={disabled ? "true" : undefined}
+        // Read by the group's key handler, which finds items in the document
+        // rather than in a registry and so needs each one to carry its value.
+        data-value={value}
+        id={id}
+        onClick={composeHandlers(rest.onClick, () => {
+          if (!disabled) {
+            group.select(value);
+          }
+        })}
+        onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+          if (disabled || event.key !== " ") {
+            return;
+          }
+          // Stops `Space` scrolling the page — which is what makes a
+          // hand-written radio feel broken even when it works — and stops the
+          // browser's own click arriving afterwards to check this again.
+          event.preventDefault();
+          group.select(value);
+        })}
+        role="radio"
+        // The roving tab stop: the chosen answer, or the first one while there
+        // is no answer, so `Tab` reaches the group in either state and leaves
+        // it in one press.
+        tabIndex={checked || (group.selected == null && group.firstId === id) ? 0 : -1}
+        type="button"
+      >
+        {children}
+      </button>
+    </RadioItemContext.Provider>
+  );
+}
+
+/**
+ * The mark inside the chosen answer, rendered only while it is chosen.
+ *
+ * `aria-hidden` because the item it sits in already says `aria-checked`: a dot
+ * that also announced itself would have a reader hear the answer's state twice,
+ * once as a state and once as a stray element. It exists so a caller can style
+ * a mark that appears and disappears without reaching for
+ * `[aria-checked="true"] > *`, and so the "only while chosen" part is not
+ * something each caller reimplements.
+ */
+export component RadioGroupIndicator(children?: React.Node, ...rest: Rest) {
+  const item = useContext(RadioItemContext);
+  if (item == null) {
+    throw new Error("RadioGroup.Indicator must be rendered inside a RadioGroup.Item");
+  }
+  if (!item.checked) {
+    return null;
+  }
+  return (
+    <span {...rest} aria-hidden="true">
+      {children}
+    </span>
+  );
+}

package/resizable.js

@@ -0,0 +1,307 @@
+// @flow
+//
+// Two panes and the handle between them — a slider wearing a different role.
+//
+// The APG calls this a **window splitter**, and it defines it as a separator
+// that behaves like a slider: `aria-valuenow`, `aria-valuemin` and
+// `aria-valuemax` say how much of the space the primary pane has, and the
+// arrow keys change it. That is why it is next to `slider.js` and shares
+// `internal/range.js` with it rather than living with the layout components.
+//
+// Almost every resizable panel on the web is pointer-only, which is a WCAG
+// 2.1.1 failure — no keyboard operation at all — and a 2.5.7 one on top of it.
+// If uf ships one, the keyboard is the feature, so the keyboard is what this
+// module is: there is no drag here yet, and there is a complete key map.
+//
+// # The two separators in this package are not the same thing
+//
+// A reader who greps for `separator` finds this and `menu.js`, and they are
+// unrelated:
+//
+//   * `Menu.Separator` is a rule between groups of items. It is not focusable,
+//     it has no value, and it exists so a reader moving through a menu is told
+//     the group changed.
+//   * `Resizable.Handle` is a *window splitter*. It is focusable, it carries a
+//     value, and operating it changes the layout.
+//
+// ARIA gives both the same role because both are separators; only the second
+// one is a control. The difference is `tabindex` and `aria-valuenow`, which is
+// also how a screen reader tells them apart.
+//
+// # `aria-orientation` is the separator's, not the layout's
+//
+// Two panes side by side are divided by a **vertical** line, so a
+// `PanelGroup` whose `orientation` is `"horizontal"` renders a handle whose
+// `aria-orientation` is `"vertical"`. That inversion is easy to get backwards
+// and worth stating: `aria-orientation` on a separator describes the separator,
+// and ARIA's default for the role is `horizontal` — so a vertical splitter
+// that says nothing is announced as a horizontal rule.
+//
+// The APG's own pattern page does not mention `aria-orientation` at all, which
+// is why implementations differ. This follows the role's definition rather
+// than the pattern's silence.
+//
+// # Two panes, which is the pattern and not a limitation
+//
+// The window splitter is defined between two panes: a primary one whose size
+// is the value, and the rest. A group of five panels is a layout-constraint
+// problem — every handle's range depends on every other panel's minimum — and
+// it is a different component with a different core, not a bigger version of
+// this one. What is here is the pattern, complete.
+//
+// # Drawing it
+//
+// Each pane carries its share as `--uf-resizable-size`, a percentage, and the
+// caller's stylesheet decides whether that is a width, a height, a `flex-basis`
+// or nothing at all. There is no drag: the pointer half is tracked work, and a
+// keyboard-only splitter is a working splitter, where a pointer-only one is
+// not.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+
+import type { Rest } from "./internal/merge-props.js";
+import { composeHandlers, withoutComposed } from "./internal/merge-props.js";
+import type { Orientation } from "./internal/roving-focus.js";
+import { clamp, isReversed } from "./internal/range.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+type ResizableState = {|
+  readonly base: string,
+  /** The primary pane's share of the group, as a percentage. */
+  readonly value: number,
+  readonly setValue: (value: number) => void,
+  readonly min: number,
+  readonly max: number,
+  readonly step: number,
+  /** How the panes are laid out; the handle's own orientation is the other one. */
+  readonly orientation: Orientation,
+  readonly disabled: boolean,
+  readonly hasPrimary: boolean,
+  readonly registerPrimary: (present: boolean) => void,
+|};
+
+const ResizableContext: React.Context<ResizableState | null> = createContext(null);
+
+hook useResizable(part: string): ResizableState {
+  const state = useContext(ResizableContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Resizable.PanelGroup`);
+  }
+  return state;
+}
+
+/**
+ * The two panes and their handle.
+ *
+ * `value` is the primary pane's percentage of the group, which is what the
+ * handle announces — the APG's "a decimal value representing the current
+ * position of the separator", where 0 is collapsed and 100 is as large as it
+ * is allowed to be.
+ *
+ * `min` is the size the primary pane collapses to. It is 0 by default, so
+ * `Enter` collapses the pane entirely; a group whose primary pane should never
+ * disappear gives it a floor.
+ */
+export component ResizablePanelGroup(
+  children: React.Node,
+  value?: number,
+  defaultValue?: number = 50,
+  onValueChange?: (value: number) => void,
+  min?: number = 0,
+  max?: number = 100,
+  step?: number = 10,
+  orientation?: Orientation = "horizontal",
+  disabled?: boolean = false,
+  ...rest: Rest
+) {
+  const base = useId();
+  const [share, setShare] = useControlled(value, defaultValue, onValueChange);
+  const [hasPrimary, setHasPrimary] = useState(false);
+
+  const state = useMemo(
+    () => ({
+      base,
+      value: clamp(share, min, max),
+      setValue: setShare,
+      min,
+      max,
+      step,
+      orientation,
+      disabled,
+      hasPrimary,
+      registerPrimary: setHasPrimary,
+    }),
+    [base, share, setShare, min, max, step, orientation, disabled, hasPrimary],
+  );
+
+  return (
+    <ResizableContext.Provider value={state}>
+      <div {...rest}>{children}</div>
+    </ResizableContext.Provider>
+  );
+}
+
+/**
+ * One pane.
+ *
+ * `primary` marks the one whose size is the value, and the one the handle
+ * names with `aria-controls`. Exactly one pane in a group is primary; the
+ * other takes what is left. It is a prop rather than "the first one", because
+ * the first one in the document is not the first one to mount the moment a
+ * caller renders a pane conditionally, and a handle pointing at the wrong pane
+ * is a handle that announces someone else's size.
+ */
+export component ResizablePanel(children: React.Node, primary?: boolean = false, ...rest: Rest) {
+  const group = useResizable("Resizable.Panel");
+  const passed = withoutComposed(rest, ["style"]);
+  const register = group.registerPrimary;
+
+  useEffect(() => {
+    if (!primary) {
+      return;
+    }
+    register(true);
+    return () => register(false);
+  }, [primary, register]);
+
+  return (
+    <div
+      {...passed}
+      id={primary ? `${group.base}-primary` : undefined}
+      style={{
+        ...(rest.style as $FlowFixMe),
+        "--uf-resizable-size": `${String(primary ? group.value : 100 - group.value)}%`,
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * The splitter: a separator that behaves like a slider.
+ *
+ * `label` is its accessible name and has a default, because a splitter is a
+ * bare bar with no text in it every time — and a focusable separator with no
+ * name is announced as "separator", which tells a reader there is a control
+ * here and nothing about what it does.
+ */
+export component ResizableHandle(label?: string = "Resize", ...rest: Rest) {
+  const group = useResizable("Resizable.Handle");
+  const passed = withoutComposed(rest, ["onKeyDown"]);
+  // Where the pane was before `Enter` collapsed it. A ref because nothing
+  // renders it: it is a fact about the last keystroke, not about the layout.
+  const restoreTo = useRef<number | null>(null);
+
+  const moveBy = (amount: number) => {
+    restoreTo.current = null;
+    group.setValue(clamp(group.value + amount, group.min, group.max));
+  };
+
+  return (
+    <div
+      {...passed}
+      aria-label={label}
+      // Only while a primary pane is in the document, for the reason every
+      // part of this package repeats: an `aria-controls` naming an id nothing
+      // has is worse than saying nothing at all.
+      aria-controls={group.hasPrimary ? `${group.base}-primary` : undefined}
+      aria-disabled={group.disabled ? "true" : undefined}
+      // The separator's own orientation, which is the other axis from the one
+      // the panes are laid out along. See the module header.
+      aria-orientation={group.orientation === "horizontal" ? "vertical" : "horizontal"}
+      aria-valuemax={group.max}
+      aria-valuemin={group.min}
+      aria-valuenow={group.value}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event: $FlowFixMe) => {
+        if (group.disabled) {
+          return;
+        }
+        if (event.key === "Enter") {
+          event.preventDefault();
+          // Collapse, or put it back where it was. The APG gives `Enter` both
+          // jobs, and a collapse with no way back is a pane a keyboard reader
+          // has thrown away.
+          const previous = restoreTo.current;
+          if (previous != null) {
+            restoreTo.current = null;
+            group.setValue(previous);
+            return;
+          }
+          if (group.value === group.min) {
+            return;
+          }
+          restoreTo.current = group.value;
+          group.setValue(group.min);
+          return;
+        }
+
+        if (event.key === "Home" || event.key === "End") {
+          event.preventDefault();
+          restoreTo.current = null;
+          group.setValue(event.key === "Home" ? group.min : group.max);
+          return;
+        }
+
+        const amount = stepFor(
+          event.key,
+          group.step,
+          group.orientation,
+          isReversed(event.currentTarget, group.orientation),
+        );
+        if (amount != null) {
+          event.preventDefault();
+          moveBy(amount);
+        }
+      })}
+      role="separator"
+      // A separator that is not in the tab sequence is the WCAG 2.1.1 failure
+      // this module exists to avoid.
+      tabIndex={group.disabled ? -1 : 0}
+    />
+  );
+}
+
+/**
+ * How far a key moves the splitter, or nothing when the key is not ours.
+ *
+ * Only the keys along the axis the panes are laid out on: `ArrowUp` in a group
+ * of side-by-side panes is the page's, and swallowing it takes a scroll key
+ * away from every reader who uses one.
+ *
+ * The primary pane is the one before the handle, so moving the handle towards
+ * the end of the axis makes it larger — and in a right-to-left page the end of
+ * a horizontal axis is on the left, so the arrows mirror.
+ */
+function stepFor(
+  key: string,
+  step: number,
+  orientation: Orientation,
+  reversed: boolean,
+): number | null {
+  const move = step <= 0 ? 1 : step;
+  if (orientation === "vertical") {
+    return match (key) {
+      "ArrowDown" => move,
+      "ArrowUp" => -move,
+      _ => null,
+    };
+  }
+  const forward = reversed ? -1 : 1;
+  return match (key) {
+    "ArrowRight" => move * forward,
+    "ArrowLeft" => -move * forward,
+    _ => null,
+  };
+}