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

package/skeleton.js

@@ -0,0 +1,159 @@
+// @flow
+//
+// A loading placeholder, and the reader it is usually invisible to.
+//
+// A skeleton is the one component on the presentational list that silently
+// makes a page *worse*. A screen of grey rounded rectangles tells a sighted
+// reader that content is coming and something is happening. To everybody else
+// it is a screen of empty `<div>`s: nothing is announced, nothing is described,
+// and the honest summary of the page is that it has no content — which is
+// exactly the conclusion somebody reaches before they leave.
+//
+// Three attributes fix it and none of them is on the grey box:
+//
+//   * the skeletons themselves are **`aria-hidden="true"`**, because a
+//     placeholder is a picture of content and not content;
+//   * the region they stand in is **`aria-busy="true"`**, which is the
+//     attribute that says "this is being filled in" and stops assistive
+//     technology reporting a half-built subtree;
+//   * and something has to **say so out loud**, because `aria-busy` is a
+//     property a reader can ask about rather than an announcement they are
+//     given.
+//
+// # The live region, and why it is empty for one commit
+//
+// This is ubugeeei-prod/uf#289's rule met at the worst possible moment.
+// `combobox.js` states it: a live region added to the page in the same commit
+// as the text it holds is usually not announced, because the technology
+// watching it had nothing to watch until it was already too late.
+//
+// A skeleton screen is busy on its *first* render. So the naive version —
+// render `<div role="status">Loading…</div>` while `pending` — mounts the
+// region with the sentence already in it and is silent, then unmounts the whole
+// thing when the content arrives and is silent again. It announces nothing,
+// ever, which is the same as not having been written.
+//
+// `Skeleton.Root` therefore renders the region empty and fills it in an effect,
+// one commit later. The region existed before the text did, which is the whole
+// of what the rule asks for, and it costs a second commit on mount and nothing
+// afterwards.
+//
+// # Keep the root mounted across the load
+//
+// Which is the one thing this component asks of a caller, and the reason
+// `busy` is a prop rather than the root's presence. A root that is unmounted
+// when the content arrives takes its live region with it, so "loaded" is said
+// to nobody and the reader is left with the last thing they heard, which was
+// "loading". Wrap the thing that loads and toggle `busy`; that is also what
+// lets `aria-busy` go from true to false on one element, which is what it is
+// for.
+//
+// # Not `Progress`
+//
+// A skeleton says *that* something is loading. `Progress` says *how far along*
+// it is, has `aria-valuenow` and lives in `progress.js`. A skeleton with a
+// percentage is a progress bar that has been drawn as boxes, and a progress bar
+// with no number is the indeterminate one that module already ships.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { useEffect, useRef, useState } from "@uniflowed/react";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { withProps } from "./internal/merge-props.js";
+
+/**
+ * The region that is being filled in, and the sentence that says so.
+ *
+ * `children` is the skeletons while `busy`, and the real content once it is
+ * not — both go inside, because it is one region either way and `aria-busy`
+ * describes it in both states.
+ *
+ *     <Skeleton.Root busy={pending}>
+ *       {pending ? (
+ *         <>
+ *           <Skeleton.Box />
+ *           <Skeleton.Box />
+ *         </>
+ *       ) : (
+ *         <Invoices rows={invoices} />
+ *       )}
+ *     </Skeleton.Root>
+ *
+ * `label` and `doneLabel` are what is announced. English defaults, because a
+ * component that announces nothing by default is the component this one exists
+ * to replace; a real application passes its translation.
+ *
+ * `doneLabel` is announced only after a spell of `busy`, so a region that was
+ * never loading never says it has loaded.
+ *
+ * `render` changes the element that owns the busy state. The live region stays
+ * beside it, mounted by this component, because that timing is the accessibility
+ * contract rather than markup the caller can safely recreate by sight.
+ */
+export component SkeletonRoot(
+  children: React.Node,
+  busy?: boolean = true,
+  label?: string = "Loading…",
+  doneLabel?: string = "Loaded",
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const [message, setMessage] = useState("");
+  // Whether there has been anything to finish. Written and read in effects
+  // only, and nothing renders it — the promise `index.js` makes about refs.
+  const waited = useRef(false);
+
+  useEffect(() => {
+    if (busy) {
+      waited.current = true;
+      setMessage(label);
+      return;
+    }
+    setMessage(waited.current ? doneLabel : "");
+  }, [busy, doneLabel, label]);
+
+  const props = withProps(rest, {
+    "aria-busy": busy ? "true" : undefined,
+    children,
+  });
+
+  return (
+    <>
+      {render == null ? <div {...props} /> : render(props)}
+      {/*
+        Beside the region rather than inside it, so a reader walking into the
+        content does not find a sentence about it sitting among the rows — and
+        mounted from the first render holding nothing, because a live region
+        that appears together with its text is not announced at all. The module
+        header says why that matters more here than anywhere else.
+      */}
+      <div aria-atomic="true" aria-live="polite" data-uf-skeleton-status="" role="status">
+        {message}
+      </div>
+    </>
+  );
+}
+
+/**
+ * One grey box.
+ *
+ * `aria-hidden="true"`, which is the entire component: a placeholder is a
+ * picture of content, and content it is not. Everything about its size, its
+ * shape and its shimmer is a class name the caller brings.
+ *
+ * `children` is allowed and is hidden with the rest of it, because sizing a
+ * box by putting the text it stands in for inside it is a real technique and
+ * there is no reason to make a caller reach for a second element to do it.
+ *
+ * `render` changes the placeholder element, not the fact that it is hidden
+ * from the accessibility tree.
+ */
+export component SkeletonBox(children?: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { "aria-hidden": "true", children });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
+}

package/slider.js

@@ -0,0 +1,405 @@
+// @flow
+//
+// A slider, and the one decision that makes it reachable at all.
+//
+// `role="slider"` goes on the **thumb**. Not on the track, not on the wrapper.
+// That single placement is the difference between a control a keyboard reader
+// can operate and a decorative div, because the element carrying the role is
+// the element that carries `tabindex="0"`, and a track with the role is a
+// track nobody can focus with a thumb nobody can find.
+//
+// It follows that a range slider is **two** sliders. Two thumbs are two
+// elements with `role="slider"`, each in the tab order, each with its own
+// name — "Minimum" and "Maximum" — and each with its own bounds. Announcing
+// both as 0–100 while the behaviour stops them passing each other is worse
+// than not shipping the range at all: the reader is told they may set the low
+// thumb to 90, they try, and the control silently refuses.
+//
+// So each thumb's `aria-valuemin` and `aria-valuemax` are bounded by its
+// neighbour's current value, and they move when the neighbour moves. That is
+// what the APG means by "when the range of another slider is dependent on the
+// current value of a slider, the values of `aria-valuemin` or `aria-valuemax`
+// of the dependent sliders are updated when the value changes".
+//
+// # `aria-valuetext` is the reason to write this component
+//
+// `aria-valuenow="3"` is announced as "3". If the scale is Low, Medium, High,
+// or a price, or a date, then 3 is not the meaning and the reader is being
+// given the implementation. `aria-valuetext="Medium"` is the meaning.
+//
+// It is a function on the root rather than a string on the thumb, because an
+// uncontrolled slider's value is the component's and a caller cannot write
+// down a string for a number they have not been told. `valueText(value, index)`
+// is called with both, so a range can say "from £20" and "to £60".
+//
+// # The keyboard
+//
+//   * `ArrowRight` / `ArrowUp` add a step, `ArrowLeft` / `ArrowDown` subtract
+//     one. Both axes work on both orientations, because a reader on a vertical
+//     slider still reaches for the horizontal keys about as often as not.
+//   * `PageUp` / `PageDown` move by `largeStep`, which is what makes a slider
+//     from 0 to 10,000 crossable without holding a key down for a minute.
+//   * `Home` and `End` go to that thumb's own ends — which for the lower thumb
+//     of a range is its neighbour, not the slider's maximum, so the two
+//     announcements and the two behaviours agree.
+//   * The horizontal keys mirror in a right-to-left page. `ArrowRight` means
+//     "further along", and further along is to the left there;
+//     `internal/range.js` reads the direction off the element the key arrived
+//     on. The vertical keys and `Home`/`End` are unaffected.
+//
+// # WCAG 2.5.7, and why the track is a part
+//
+// *Dragging Movements* says a control operated by dragging needs a way that is
+// not a drag. The arrow keys are one; a press on the track is the other, and
+// it is the one a pointer reader expects — so `Slider.Track` moves the nearest
+// thumb to wherever it was pressed, and the drag that follows is a
+// convenience on top of a control that already worked without it.
+//
+// That is also why the track is a part of this component rather than a `div`
+// the caller draws: the press has to be turned into a value, which means
+// measuring the track, and a caller who did it themselves would have to
+// re-derive the snapping, the clamping and the direction.
+//
+// # Drawing it
+//
+// Nothing here has a width, a colour or a position, and an uncontrolled
+// slider's value is not the caller's to compute from. So each thumb and the
+// range carry the fraction they are at as custom properties —
+// `--uf-slider-fraction` on a thumb, `--uf-slider-start` and `--uf-slider-end`
+// on the range — and the caller's stylesheet decides what to do with them. A
+// caller who writes no CSS sees nothing, which is the same promise every other
+// module here makes.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useMemo, useRef } from "@uniflowed/react";
+import { useStableCallback } from "@uniflowed/hooks/lifecycle";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  withProps,
+  withoutComposed,
+} from "./internal/merge-props.js";
+import type { Orientation } from "./internal/roving-focus.js";
+import { clamp, fraction, isReversed, snap } from "./internal/range.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+type SliderState = {|
+  readonly values: $ReadOnlyArray<number>,
+  readonly min: number,
+  readonly max: number,
+  readonly step: number,
+  readonly largeStep: number,
+  readonly orientation: Orientation,
+  readonly disabled: boolean,
+  readonly valueText: ((value: number, index: number) => string) | void,
+  /** Move one thumb, holding it inside its neighbours. */
+  readonly setAt: (index: number, value: number) => void,
+  /** The thumb nearest a value, which is the one a press on the track moves. */
+  readonly nearest: (value: number) => number,
+  readonly trackRef: { current: HTMLElement | null },
+|};
+
+const SliderContext: React.Context<SliderState | null> = createContext(null);
+
+hook useSlider(part: string): SliderState {
+  const state = useContext(SliderContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Slider.Root`);
+  }
+  return state;
+}
+
+/**
+ * The slider.
+ *
+ * `value` is always an array, with one entry per thumb, because a range slider
+ * is not a different component from a single one — it is the same component
+ * with two thumbs, and a `number | [number, number]` prop would make every
+ * caller narrow a union to read their own value back.
+ */
+export component SliderRoot(
+  children: React.Node,
+  value?: $ReadOnlyArray<number>,
+  defaultValue?: $ReadOnlyArray<number> = [0],
+  onValueChange?: (value: $ReadOnlyArray<number>) => void,
+  min?: number = 0,
+  max?: number = 100,
+  step?: number = 1,
+  largeStep?: number = 10,
+  orientation?: Orientation = "horizontal",
+  disabled?: boolean = false,
+  valueText?: (value: number, index: number) => string,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const [values, setValues] = useControlled(value, defaultValue, onValueChange);
+  const trackRef = useRef<HTMLElement | null>(null);
+
+  const setAt = useStableCallback((index: number, next: number) => {
+    if (disabled) {
+      return;
+    }
+    const current = values[index];
+    if (current === undefined) {
+      return;
+    }
+    // Bounded by the neighbours rather than by the slider, which is what stops
+    // the thumbs being dragged through each other — and it is the same pair of
+    // numbers the thumb announces as its own min and max, so what a reader is
+    // told and what the control does cannot drift apart.
+    const [lower, upper] = boundsOf(values, index, min, max);
+    const settled = snap(next, lower, upper, step);
+    if (settled === current) {
+      return;
+    }
+    const changed = values.slice();
+    changed[index] = settled;
+    setValues(changed);
+  });
+
+  const nearest = useStableCallback((target: number): number => {
+    let at = 0;
+    let best = Infinity;
+    for (let index = 0; index < values.length; index += 1) {
+      const distance = Math.abs((values[index] ?? 0) - target);
+      // Strictly nearer, so a press exactly between two thumbs takes the first
+      // one rather than the last — arbitrary either way, and consistent is
+      // what stops it feeling random.
+      if (distance < best) {
+        best = distance;
+        at = index;
+      }
+    }
+    return at;
+  });
+
+  const state = useMemo(
+    () => ({
+      values,
+      min,
+      max,
+      step,
+      largeStep,
+      orientation,
+      disabled,
+      valueText,
+      setAt,
+      nearest,
+      trackRef,
+    }),
+    [values, min, max, step, largeStep, orientation, disabled, valueText, setAt, nearest],
+  );
+
+  return (
+    <SliderContext.Provider value={state}>
+      {render == null ? <div {...rest}>{children}</div> : render(withProps(rest, { children }))}
+    </SliderContext.Provider>
+  );
+}
+
+/**
+ * The bar the thumbs sit on, and the half of WCAG 2.5.7 that is not a key.
+ *
+ * A press anywhere on it moves the nearest thumb there, and holding the
+ * pointer down drags that thumb. The pointer is captured, so a drag that
+ * wanders off the track — which every drag does — keeps arriving here instead
+ * of being lost to whatever it wandered over.
+ */
+export component SliderTrack(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const slider = useSlider("Slider.Track");
+  const passed = withoutComposed(rest, ["onPointerDown", "onPointerMove", "onPointerUp", "ref"]);
+  const dragging = useRef<number | null>(null);
+
+  /** The value the pointer is over, from the track's own box. */
+  const valueAt = (event: $FlowFixMe): number | null => {
+    const track = slider.trackRef.current;
+    if (track == null) {
+      return null;
+    }
+    const box = track.getBoundingClientRect();
+    const vertical = slider.orientation === "vertical";
+    const size = vertical ? box.height : box.width;
+    if (size <= 0) {
+      return null;
+    }
+    const along = vertical ? box.bottom - event.clientY : event.clientX - box.left;
+    // A vertical slider's minimum is at the *bottom*, which is why the reading
+    // above is taken from `bottom` rather than `top`: a slider that grows
+    // downwards is the one arrangement no reader expects.
+    const part = clamp(along / size, 0, 1);
+    const forward = isReversed(track, slider.orientation) ? 1 - part : part;
+    return slider.min + forward * (slider.max - slider.min);
+  };
+
+  const moveTo = (event: $FlowFixMe, index: number | null) => {
+    const target = valueAt(event);
+    if (target == null) {
+      return;
+    }
+    const at = index ?? slider.nearest(target);
+    dragging.current = at;
+    slider.setAt(at, target);
+  };
+
+  const props = withProps(passed, {
+    children,
+    onPointerDown: composeHandlers(rest.onPointerDown, (event: $FlowFixMe) => {
+      if (slider.disabled) {
+        return;
+      }
+      // Otherwise the press selects the page's text on the way past, which
+      // makes a drag paint everything blue.
+      event.preventDefault();
+      event.currentTarget?.setPointerCapture?.(event.pointerId);
+      moveTo(event, null);
+    }),
+    onPointerMove: composeHandlers(rest.onPointerMove, (event: $FlowFixMe) => {
+      if (dragging.current != null) {
+        moveTo(event, dragging.current);
+      }
+    }),
+    onPointerUp: composeHandlers(rest.onPointerUp, (event: $FlowFixMe) => {
+      dragging.current = null;
+      event.currentTarget?.releasePointerCapture?.(event.pointerId);
+    }),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      slider.trackRef.current = element;
+    }),
+  });
+
+  return render == null ? <div {...props} /> : render(props);
+}
+
+/**
+ * The filled part of the track.
+ *
+ * From the lowest thumb to the highest, which for a single thumb is from the
+ * slider's minimum to that thumb — the difference between a volume control and
+ * a price range, expressed by how many thumbs there are rather than by a prop.
+ *
+ * Presentational: it is inside the track and carries no role, because a reader
+ * is told the value by the thumb and telling them again here would be telling
+ * them twice.
+ */
+export component SliderRange(render?: RenderProp, ...rest: Rest) {
+  const slider = useSlider("Slider.Range");
+  const passed = withoutComposed(rest, ["style"]);
+  const ends = [...slider.values].sort((first, second) => first - second);
+  const start = slider.values.length > 1 ? (ends[0] ?? slider.min) : slider.min;
+  const end = ends[ends.length - 1] ?? slider.min;
+  const props = withProps(passed, {
+    "aria-hidden": "true",
+    style: {
+      ...(rest.style as $FlowFixMe),
+      "--uf-slider-start": fraction(start, slider.min, slider.max),
+      "--uf-slider-end": fraction(end, slider.min, slider.max),
+    },
+  });
+
+  return render == null ? <div {...props} /> : render(props);
+}
+
+/**
+ * One thumb, which is the slider as far as a screen reader is concerned.
+ *
+ * `index` is which of the root's values this thumb owns, and it defaults to
+ * zero so a one-thumb slider never mentions it. It is a prop rather than
+ * something counted from the document, because the tab order of a range slider
+ * has to stay put while the thumbs move — the APG is explicit that a thumb
+ * passing another does not reorder them — and a position counted from the page
+ * is a position that changes when the page does.
+ *
+ * A name is the caller's, and for a range it is two names: "Minimum" and
+ * "Maximum" told apart is the whole difference between a control a reader can
+ * operate and two identical "slider"s.
+ */
+export component SliderThumb(index?: number = 0, render?: RenderProp, ...rest: Rest) {
+  const slider = useSlider("Slider.Thumb");
+  const passed = withoutComposed(rest, ["onKeyDown", "style"]);
+  const value = slider.values[index] ?? slider.min;
+  const [lower, upper] = boundsOf(slider.values, index, slider.min, slider.max);
+  const props = withProps(passed, {
+    "aria-disabled": slider.disabled ? "true" : undefined,
+    "aria-orientation": slider.orientation,
+    // The neighbour's value, not the slider's end. A reader told they may
+    // set this thumb to 90 while the control refuses at 60 has been told
+    // something the control disagrees with.
+    "aria-valuemax": upper,
+    "aria-valuemin": lower,
+    "aria-valuenow": value,
+    "aria-valuetext": slider.valueText?.(value, index),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: $FlowFixMe) => {
+      if (slider.disabled) {
+        return;
+      }
+      const reversed = isReversed(event.currentTarget, slider.orientation);
+      const move = stepFor(event.key, slider.step, slider.largeStep, reversed);
+      if (move != null) {
+        // Before moving: the arrow keys scroll the page, and a slider that
+        // moves the page under the reader as it moves the value is a control
+        // they cannot watch.
+        event.preventDefault();
+        slider.setAt(index, value + move);
+        return;
+      }
+      if (event.key === "Home" || event.key === "End") {
+        event.preventDefault();
+        // This thumb's own ends, which for the lower thumb of a range is its
+        // neighbour rather than the slider's maximum.
+        slider.setAt(index, event.key === "Home" ? lower : upper);
+      }
+    }),
+    role: "slider",
+    style: {
+      ...(rest.style as $FlowFixMe),
+      "--uf-slider-fraction": fraction(value, slider.min, slider.max),
+    },
+    // In the tab sequence, and out of it while disabled — the browser does
+    // this for a real control and there is no real control here to do it.
+    tabIndex: slider.disabled ? -1 : 0,
+  });
+
+  return render == null ? <span {...props} /> : render(props);
+}
+
+/**
+ * How far a key moves the value, or nothing when the key is not ours.
+ *
+ * `PageUp` and `PageDown` are never mirrored: they mean "a lot more" and "a
+ * lot less", which is not a direction on the page. Neither are `ArrowUp` and
+ * `ArrowDown`, since writing direction does not flip the vertical axis.
+ */
+function stepFor(key: string, step: number, largeStep: number, reversed: boolean): number | null {
+  const forward = reversed ? -1 : 1;
+  const move = step <= 0 ? 1 : step;
+  return match (key) {
+    "ArrowRight" => move * forward,
+    "ArrowLeft" => -move * forward,
+    "ArrowUp" => move,
+    "ArrowDown" => -move,
+    "PageUp" => largeStep <= 0 ? move : largeStep,
+    "PageDown" => -(largeStep <= 0 ? move : largeStep),
+    _ => null,
+  };
+}
+
+/**
+ * What a thumb may be set to: its neighbours' values, or the slider's ends.
+ *
+ * One function, called by the thumb to announce its bounds and by the root to
+ * enforce them, so the two cannot disagree.
+ */
+function boundsOf(
+  values: $ReadOnlyArray<number>,
+  index: number,
+  min: number,
+  max: number,
+): [number, number] {
+  const below = index > 0 ? values[index - 1] : undefined;
+  const above = index < values.length - 1 ? values[index + 1] : undefined;
+  return [below ?? min, above ?? max];
+}

package/switch.js

@@ -19,54 +19,63 @@
 //
 // 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.
+// something that operates is what a reader expects — while `checkbox.js` turns
+// `Enter` into the submission of the form the checkbox is in, which is what a
+// native `<input type="checkbox">` does with the key and what a reader
+// answering a question on their way to a submit button is asking for. 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 type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
+import { composeHandlers, withProps, withoutComposed } from "./internal/merge-props.js";
 import { useControlled } from "./internal/controlled-state.js";
 
-/** A two-state switch: on or off. */
+/**
+ * A two-state switch: on or off.
+ *
+ * `render` is the escape hatch, and on a switch it is what a caller with their
+ * own `<Pressable>` or a `<div role="switch">` in a design system reaches for.
+ * `type="button"` is the one thing it does not hand over, because that is true
+ * of the element rather than of the switch.
+ */
 export component Switch(
   checked?: boolean,
   defaultChecked?: boolean = false,
   onCheckedChange?: (checked: boolean) => void,
   disabled?: boolean = false,
   children?: React.Node,
-  ...rest: { readonly [string]: mixed }
+  render?: RenderProp,
+  ...rest: Rest
 ) {
   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();
+  const props = withProps(withoutComposed(rest, ["onClick", "onKeyDown"]), {
+    "aria-checked": on ? "true" : "false",
+    children,
+    disabled,
+    onClick: composeHandlers(rest.onClick, () => {
+      if (!disabled) {
         setOn(!on);
-      })}
-      role="switch"
-      type="button"
-    >
-      {children}
-    </button>
-  );
+      }
+    }),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      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",
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
 }