@uniflowed/ui 0.0.0-alpha.13 → 0.0.0-alpha.14

package/accordion.js

@@ -54,6 +54,19 @@
 // are here because a long FAQ is nicer with them — but nothing about them takes
 // a header out of the tab order.
 //
+// # The height a stylesheet animates to
+//
+// `measure` on the root puts each panel's would-be height on it as
+// `--uf-collapsible-height` — one property name across both disclosure
+// components, because it is one measurement and a second name would be a second
+// rule to keep in step. `collapsible.js`'s header shows the stylesheet, and
+// `internal/disclosure.js` holds the measuring pass and the argument for the
+// opt-in.
+//
+// It is on `Accordion.Root` rather than on each `Accordion.Content` because a
+// forty-section FAQ is one decision, made once, rather than forty props that
+// have to agree.
+//
 // # How the sections are found
 //
 // By a `data-*` attribute of this package's own rather than by role, which is
@@ -81,7 +94,7 @@ import type { Rest } from "./internal/merge-props.js";
 import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
 import { moveOnKey } from "./internal/roving-focus.js";
 import type { RovingSet } from "./internal/roving-focus.js";
-import { usePresence, useUntilFound } from "./internal/disclosure.js";
+import { useMeasuredHeight, usePresence, useUntilFound } from "./internal/disclosure.js";
 import { useControlled } from "./internal/controlled-state.js";
 
 /** Whether one section is open at a time, or any number of them. */
@@ -110,6 +123,8 @@ type AccordionState = {|
   /** Whether closing the last open section is allowed; only meaningful for `single`. */
   readonly closable: boolean,
   readonly type: AccordionType,
+  /** Whether each panel carries its measured height; see the module header. */
+  readonly measure: boolean,
 |};
 
 const AccordionContext: React.Context<AccordionState | null> = createContext(null);
@@ -160,6 +175,7 @@ export component AccordionRoot(
   defaultValue?: $ReadOnlyArray<string> = NOTHING,
   value?: $ReadOnlyArray<string>,
   onValueChange?: (value: $ReadOnlyArray<string>) => void,
+  measure?: boolean = false,
   ...rest: Rest
 ) {
   const [open, setOpen] = useControlled<$ReadOnlyArray<string>>(value, defaultValue, onValueChange);
@@ -184,8 +200,8 @@ export component AccordionRoot(
   const state = useMemo(
     // `collapsible` only ever narrows a `single` accordion: in `multiple` mode
     // every section closes on its own, and there is no last one to protect.
-    () => ({ open, toggle, closable: type === "multiple" || collapsible, type }),
-    [open, toggle, type, collapsible],
+    () => ({ open, toggle, closable: type === "multiple" || collapsible, type, measure }),
+    [open, toggle, type, collapsible, measure],
   );
   const passed = withoutComposed(rest, ["onKeyDown"]);
 
@@ -312,10 +328,12 @@ export component AccordionTrigger(children: React.Node, ...rest: Rest) {
  * what `hidden` is upgraded to for it.
  */
 export component AccordionContent(children: React.Node, ...rest: Rest) {
+  const accordion = useAccordion("Accordion.Content");
   const item = useAccordionItem("Accordion.Content");
   const contentRef = useRef<HTMLElement | null>(null);
   usePresence(item.registerContent);
   useUntilFound(contentRef, item.open);
+  useMeasuredHeight(contentRef, accordion.measure);
 
   return (
     <div

package/checkbox.js

@@ -20,12 +20,49 @@
 // `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
+// # `Enter` submits the form; it does not toggle
 //
-// `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.
+// This 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 — and for a long time this header claimed it by *leaving the key alone*.
+// Neither half of that claim survived contact with the component, which is
+// ubugeeei-prod/uf#324:
+//
+//   * **A `<button type="button">` never submits a form.** That is the whole of
+//     what `type="button"` means, and this renders one. So the form was not
+//     submitted by anybody.
+//   * **And leaving a key unhandled does not make it inert.** It lets the
+//     *default action* happen, and the default action of `Enter` on a focused
+//     `<button>` is a click — which this component's own `onClick` turns into a
+//     toggle. So a focused checkbox both failed to submit the form and changed
+//     its own state, which is the opposite of the intent on both counts.
+//
+// What a native `<input type="checkbox">` does with `Enter` is *implicit
+// submission*: the key does not touch the checkbox, and the form around it is
+// submitted as though its default button had been pressed. That is the
+// behaviour this replaces, so it is the behaviour it owes, and it is written
+// out here because a styled substitute that silently drops it is exactly the
+// kind of regression `index.js` says this package exists to prevent.
+//
+// So `Enter` is claimed — `preventDefault()`, which is what stops the browser's
+// click and the toggle behind it — and turned back into a submission of the
+// `<form>` the control is in. Outside a form it does nothing at all, which is
+// again what the native control does. `requestSubmit` rather than `submit`
+// because only the first fires the `submit` event and runs constraint
+// validation, and a `<form onSubmit>` that never heard about the submission is
+// the failure this would otherwise trade for the old one.
+//
+// The default button is passed to it rather than left out. `requestSubmit()`
+// with no argument submits with *no* submitter, so a form whose handler reads
+// `event.submitter` — a Server Action's `formAction`, a "save" and a "save and
+// close" beside each other — would be told nobody pressed anything. Implicit
+// submission names the default button, so this does too.
+//
+// Which button that is, and whether a form with no button submits at all, are
+// both the specification's questions rather than this component's, and both are
+// answered below: a submit button belongs to the form that *owns* it rather
+// than to the form it sits inside, and a form with no submit button submits
+// itself only while at most one of its fields blocks implicit submission.
 
 "use client";
 
@@ -35,6 +72,137 @@ import type { Rest } from "./internal/merge-props.js";
 import { composeHandlers, withoutComposed } from "./internal/merge-props.js";
 import { useControlled } from "./internal/controlled-state.js";
 
+/**
+ * The button a form would submit itself through, or nothing.
+ *
+ * The specification's "default button" is the first submit button in tree order
+ * **whose form owner is this form**, and neither half of that is "a
+ * descendant". A control's form owner is the `form` attribute when it has one
+ * and the nearest ancestor `<form>` otherwise, so the two cases a subtree
+ * search gets wrong are both real markup:
+ *
+ *   * `<button type="submit" form="signup">` *beside* the form — the pattern a
+ *     dialog's footer is written in — is the default button and a subtree
+ *     search never sees it. Missing it is not a small error: it falls through
+ *     to the no-submitter branch, which is the exact `event.submitter` this
+ *     component exists to answer.
+ *   * `<button type="submit" form="other">` *inside* the form belongs to the
+ *     other one, and handing it to `requestSubmit` throws `NotFoundError` —
+ *     which reaches a reader as a key that does nothing and a console the page
+ *     did not write.
+ *
+ * So the search is over the form's root and each candidate is asked which form
+ * it belongs to. The root rather than the document, because a form in a shadow
+ * tree, or one rendered but not yet inserted, has to find its own buttons and
+ * only its own.
+ *
+ * A `<button>` with no `type` is a submit button, which is the case most easily
+ * missed. A disabled one is skipped, because the browser skips it — implicit
+ * submission through a button nobody could press is not a thing the platform
+ * does.
+ */
+function defaultButtonOf(form: HTMLElement): HTMLElement | null {
+  const searched: $FlowFixMe = (form as $FlowFixMe).getRootNode?.() ?? form.ownerDocument;
+  if (searched == null || typeof searched.querySelectorAll !== "function") {
+    return null;
+  }
+  const candidates = searched.querySelectorAll(
+    'button:not([type]), button[type="submit"], input[type="submit"], input[type="image"]',
+  );
+  for (const candidate of candidates) {
+    const button: $FlowFixMe = candidate;
+    if (button.form === form && button.disabled !== true) {
+      return button as $FlowFixMe;
+    }
+  }
+  return null;
+}
+
+/**
+ * The `<input>` types that block implicit submission.
+ *
+ * The specification's list, copied rather than reasoned about, because what is
+ * being reproduced is what the browser does. A checkbox, a radio, a hidden
+ * field, a `<select>` and a `<textarea>` are not on it.
+ */
+const BLOCKING_TYPES: Set<string> = new Set([
+  "date",
+  "datetime-local",
+  "email",
+  "month",
+  "number",
+  "password",
+  "search",
+  "tel",
+  "text",
+  "time",
+  "url",
+  "week",
+]);
+
+/**
+ * Whether the platform would decline to submit `form` from the form itself.
+ *
+ * The other half of the implicit submission rule, and the half a script never
+ * meets: a form with **no** submit button is submitted implicitly only when at
+ * most one of its fields blocks implicit submission. A login form with a
+ * username and a password and no button is the everyday case — `Enter` in
+ * either field does nothing at all in every browser.
+ *
+ * `requestSubmit()` does not apply that rule, and is right not to: it is the
+ * route a script takes to submit deliberately. A component reproducing the
+ * *implicit* mechanism has to apply it here, or `Enter` on a checkbox submits
+ * forms that `Enter` in the text field beside it would not — which is the same
+ * class of divergence this whole change is about, pointing the other way.
+ */
+function moreThanOneFieldBlocks(form: $FlowFixMe): boolean {
+  const fields: $FlowFixMe = form.elements;
+  if (fields == null) {
+    return false;
+  }
+  let blocking = 0;
+  for (const field of fields) {
+    const control: $FlowFixMe = field;
+    // `.type` rather than the attribute: it is missing on `<input>` and any
+    // value the specification does not know is the Text state, and both of
+    // those block.
+    if (control.tagName === "INPUT" && BLOCKING_TYPES.has(String(control.type))) {
+      blocking += 1;
+      if (blocking > 1) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Submit the form this control is in, the way `Enter` on a native checkbox does.
+ *
+ * Does nothing when there is no form, when the browser has no `requestSubmit` —
+ * it is everywhere current, and a checkbox that threw on an old one would be
+ * worse than a key that does nothing — or when the form is one the platform
+ * would not submit implicitly either, which is the rule
+ * `moreThanOneFieldBlocks` states.
+ */
+function submitImplicitly(control: HTMLElement): void {
+  const form: $FlowFixMe = (control as $FlowFixMe).form;
+  if (form == null || typeof form.requestSubmit !== "function") {
+    return;
+  }
+  const submitter = defaultButtonOf(form);
+  if (submitter == null) {
+    // A form with no submit button submits itself, but only under the rule
+    // `moreThanOneFieldBlocks` carries — `requestSubmit()` will not apply it,
+    // so this does.
+    if (!moreThanOneFieldBlocks(form)) {
+      form.requestSubmit();
+    }
+    return;
+  }
+  form.requestSubmit(submitter);
+}
+
 /** A checkbox, which may also be mixed. */
 export component Checkbox(
   checked?: boolean,
@@ -63,13 +231,23 @@ export component Checkbox(
         }
       })}
       onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        if (disabled || event.key !== " ") {
+        if (disabled) {
           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);
+        if (event.key === " ") {
+          // Stops `Space` scrolling the page, and stops the browser's own click
+          // arriving afterwards and toggling this a second time.
+          event.preventDefault();
+          setOn(next);
+          return;
+        }
+        if (event.key === "Enter") {
+          // Claimed, and *not* to make the key inert: the default action here
+          // is a click on this button, and a click on this button toggles. See
+          // the module header for the whole of it.
+          event.preventDefault();
+          submitImplicitly(event.currentTarget as $FlowFixMe);
+        }
       })}
       role="checkbox"
       type="button"

package/collapsible.js

@@ -23,16 +23,29 @@
 // `internal/disclosure.js` explains what is done instead, and why React needs a
 // hook to say it.
 //
-// # No height, yet
+// # The height, for a stylesheet that animates it
 //
-// 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`.
+// `measure` puts the height the content *would* have on
+// `Collapsible.Content` as `--uf-collapsible-height`, correct while the panel
+// is still closed — which is the only moment it is any use, because
+// `height: 0 → var(--uf-collapsible-height)` is a transition that has to know
+// its destination before it starts. `internal/disclosure.js` holds the
+// measuring pass and says why the obvious ways of asking all answer zero, and
+// why the prop is opt-in rather than always on.
+//
+//   [data-collapsible-content] {
+//     overflow: hidden;
+//     transition: height 150ms;
+//     height: 0;
+//   }
+//   [data-collapsible-content]:not([hidden]) {
+//     height: var(--uf-collapsible-height);
+//   }
+//
+// The selector is the caller's — a class, a `data-*` of their own, whatever
+// they already style with. This package emits the number and no styles at all,
+// which is the same division `internal/anchor.js` keeps for a popover: a
+// stylesheet can say *how* to move, and only the component can say how far.
 
 "use client";
 
@@ -41,7 +54,7 @@ import { createContext, useContext, useId, useMemo, useRef, useState } from "@un
 
 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 { useMeasuredHeight, usePresence, useUntilFound } from "./internal/disclosure.js";
 import { useControlled } from "./internal/controlled-state.js";
 
 type CollapsibleState = {|
@@ -51,6 +64,8 @@ type CollapsibleState = {|
   /** Whether a `Collapsible.Content` is rendered, so the trigger names one that exists. */
   readonly present: boolean,
   readonly registerContent: (present: boolean) => void,
+  /** Whether the content carries its measured height; see the module header. */
+  readonly measure: boolean,
 |};
 
 const CollapsibleContext: React.Context<CollapsibleState | null> = createContext(null);
@@ -76,14 +91,15 @@ export component CollapsibleRoot(
   defaultOpen?: boolean = false,
   open?: boolean,
   onOpenChange?: (open: boolean) => void,
+  measure?: boolean = false,
 ) {
   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],
+    () => ({ contentId, open: isOpen, setOpen, present, registerContent: setPresent, measure }),
+    [contentId, isOpen, setOpen, present, measure],
   );
 
   return <CollapsibleContext.Provider value={state}>{children}</CollapsibleContext.Provider>;
@@ -131,6 +147,7 @@ export component CollapsibleContent(children: React.Node, ...rest: Rest) {
   const contentRef = useRef<HTMLElement | null>(null);
   usePresence(collapsible.registerContent);
   useUntilFound(contentRef, collapsible.open);
+  useMeasuredHeight(contentRef, collapsible.measure);
 
   return (
     <div

package/context-menu.js

@@ -0,0 +1,198 @@
+// @flow
+//
+// The same menu, opened by the right button.
+//
+// Everything below the trigger is `menu.js` — the arrow keys, typeahead,
+// submenus, `Escape` stacking, the roving tab stop and the two checkable item
+// kinds — because a context menu *is* a menu and a second implementation of one
+// would be a second set of keyboard bugs. What is here is the two things that
+// make it a component rather than an `oncontextmenu` handler, and both of them
+// are the parts people leave out.
+//
+// # It has to be reachable from the keyboard
+//
+// `Shift+F10` and the `ContextMenu` key open a context menu, on every platform,
+// and a component that only listens for `contextmenu` is a WCAG 2.1.1 failure:
+// the commands in it are reachable by pointer and by nothing else. Long press
+// is the touch equivalent of the same gesture, and `@uniflowed/hooks/dom`'s
+// `useLongPress` already knows what a long press is — including that a press
+// that moves is a drag and not a press.
+//
+// The trigger is therefore focusable. That is a real cost and it is stated
+// rather than hidden: a list of two hundred rows with a context menu on each is
+// two hundred tab stops. A caller whose trigger already *contains* something
+// focusable should pass `tabIndex={-1}` and let the keys arrive from inside it,
+// which they do — the handler is on the trigger and the event bubbles. What is
+// not on offer is leaving the keys out, because the alternative to a tab stop
+// is a command a keyboard cannot reach.
+//
+// # It opens at a point, and sometimes at an element
+//
+// A context menu opened by the pointer belongs at the pointer — the reader is
+// looking at their cursor, and a menu that appeared against the top-left corner
+// of a table row is a menu they have to go and find. Opened by the keyboard
+// there is no pointer, and the menu belongs against the element that has focus.
+//
+// So the anchor is a rectangle rather than an element, and
+// `internal/anchor.js`'s `anchorRect` is the seam: the trigger element is still
+// what the writing direction is read from and what focus goes back to, and only
+// the *measurement* is replaced. `null` — which is what the keyboard path
+// leaves behind — measures the trigger, so both routes end in one code path
+// rather than two placements that drift.
+//
+// # The body is not named after the trigger
+//
+// `Menu.Body` names itself with `aria-labelledby` pointing at its trigger,
+// because a dropdown menu's trigger is a button with a short label — "File" —
+// and that is the menu's name. A context menu's trigger is arbitrary content: a
+// table row, a canvas, a paragraph. Naming the menu after it would announce the
+// whole row as the menu's name. So `ContextMenu.Trigger` registers itself as
+// the thing focus returns to and *not* as a name, and the caller gives
+// `ContextMenu.Body` an `aria-label`. That is the one attribute this component
+// cannot supply and the reference page says so.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { useCallback, useContext, useMemo, useRef, useState } from "@uniflowed/react";
+import { useLongPress } from "@uniflowed/hooks/dom";
+
+import type { Rect } from "./internal/anchor.js";
+import type { Rest } from "./internal/merge-props.js";
+import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
+import { MenuAnchorContext, MenuContext, MenuLevel, useMenu } from "./internal/menu-tree.js";
+
+/**
+ * Where the pointer was, or nothing when the keyboard opened the menu.
+ *
+ * Held by the root rather than by the trigger because the *body* is what reads
+ * it, and the body is a sibling of the trigger rather than a child of it.
+ */
+type PointState = {|
+  readonly point: Rect | null,
+  readonly openAt: (point: Rect | null) => void,
+|};
+
+const PointContext: React.Context<PointState | null> = React.createContext(null);
+
+/** A zero-sized box at a pointer's coordinates, which is what a point is. */
+function pointAt(x: number, y: number): Rect {
+  return { height: 0, width: 0, x, y };
+}
+
+/**
+ * The trigger, the menu, and where the pointer was when it opened.
+ *
+ * Renders no element of its own, for the reason `Menu.Root` gives: the trigger
+ * and the body are siblings in whatever layout the caller wrote.
+ */
+export component ContextMenuRoot(
+  children: React.Node,
+  defaultOpen?: boolean = false,
+  open?: boolean,
+  onOpenChange?: (open: boolean) => void,
+) {
+  // State rather than a ref, and that is load-bearing: the rectangle is one of
+  // the things the placement effect re-runs for, so a second right-click
+  // somewhere else has to be a new value React has committed rather than a
+  // mutation nothing heard about.
+  const [point, setPoint] = useState<Rect | null>(null);
+  const openAt = useCallback((next: Rect | null) => setPoint(next), []);
+  const state = useMemo(() => ({ point, openAt }), [point, openAt]);
+
+  return (
+    <PointContext.Provider value={state}>
+      <MenuAnchorContext.Provider value={point}>
+        <MenuLevel defaultOpen={defaultOpen} onOpenChange={onOpenChange} open={open} parent={null}>
+          {children}
+        </MenuLevel>
+      </MenuAnchorContext.Provider>
+    </PointContext.Provider>
+  );
+}
+
+hook usePoint(part: string): PointState {
+  const state = useContext(PointContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a ContextMenu.Root`);
+  }
+  return state;
+}
+
+/**
+ * The content the menu belongs to.
+ *
+ * A `<div>` rather than a button, because what a context menu hangs off is a
+ * region of the page. The module header says why it is in the tab order and
+ * when a caller should take it out again.
+ */
+export component ContextMenuTrigger(children: React.Node, ...rest: Rest) {
+  const menu = useMenu("ContextMenu.Trigger");
+  const { openAt } = usePoint("ContextMenu.Trigger");
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const passed = withoutComposed(rest, ["onContextMenu", "onKeyDown", "ref"]);
+
+  const openHere = useCallback(() => {
+    // No point: the menu goes against the element, which is where the reader's
+    // focus already is.
+    openAt(null);
+    menu.pendingFocus.current = "first";
+    menu.setOpen(true);
+  }, [menu, openAt]);
+
+  // The touch equivalent of the right button. `useLongPress` cancels itself
+  // when the pointer moves, so a drag across a list is not two hundred menus.
+  useLongPress(triggerRef, (event: Event) => {
+    const pointer: $FlowFixMe = event;
+    openAt(pointAt(pointer.clientX ?? 0, pointer.clientY ?? 0));
+    menu.pendingFocus.current = "first";
+    menu.setOpen(true);
+  });
+
+  return (
+    <div
+      // Above the spread, alone, because it is the one attribute here a caller
+      // is invited to overrule: the module header promises `tabIndex={-1}` to a
+      // caller whose trigger already contains something focusable, and a prop
+      // written *after* `{...passed}` wins over the caller's silently — which
+      // is a documented escape hatch that does nothing. Everything below the
+      // spread is this component's own and stays there.
+      tabIndex={0}
+      {...passed}
+      aria-haspopup="menu"
+      id={`${menu.base}-trigger`}
+      onContextMenu={composeHandlers(rest.onContextMenu, (event) => {
+        const press: $FlowFixMe = event;
+        // The browser's own menu would otherwise cover this one, and the reader
+        // would be looking at the platform's Back/Reload rather than at the
+        // commands the page has for what they pressed on.
+        press.preventDefault();
+        openAt(pointAt(press.clientX ?? 0, press.clientY ?? 0));
+        menu.pendingFocus.current = "first";
+        menu.setOpen(true);
+      })}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        // Both spellings. `ContextMenu` is the dedicated key on a PC keyboard;
+        // `Shift+F10` is the one every platform has, and is what a laptop
+        // without that key leaves a reader with.
+        const asked =
+          event.key === "ContextMenu" || (event.key === "F10" && event.shiftKey === true);
+        if (!asked) {
+          return;
+        }
+        event.preventDefault();
+        openHere();
+      })}
+      ref={composeRefs(rest.ref, (element) => {
+        triggerRef.current = element;
+        // What focus goes back to when the menu closes. It is deliberately not
+        // registered as the menu's *name*; see the module header.
+        menu.triggerRef.current = element;
+      })}
+    >
+      {children}
+    </div>
+  );
+}
+
+export type { MenuSelect } from "./menu.js";