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

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/combobox.js

@@ -49,6 +49,69 @@
 // the active option is cleared when the option it named is filtered away, the
 // count is remeasured, and `aria-activedescendant` never names an id that has
 // left the document.
+//
+// # Groups, and the two elements that had to change to have them
+//
+// A `listbox` may own `option` and `group` elements, and nothing else. This
+// module rendered a `<ul>` of `<li>`s, which is the right shape for a flat list
+// and the wrong one the moment a group appears: a group's options belong inside
+// the group, a group inside a `<ul>` is an `<li>`, and an `<li>` inside an
+// `<li>` is not something HTML has. The parser closes the outer one, so the
+// markup a server sent and the tree a browser built would disagree — which
+// React finds at hydration, in production, on the one page that had groups.
+//
+// The way out that keeps the list is a second `<ul role="presentation">` around
+// each group's options, and it was rejected twice over. It works by an
+// inheritance rule — a presentational role propagating to the elements its own
+// role requires, except where a child carries an explicit role — which is
+// correct in the specification and up to the software, and this package's whole
+// premise is not building on that distinction. It would also leave the two
+// halves of one pattern with two differently shaped listboxes, for a reason
+// neither module could state.
+//
+// So `Combobox.List` and `Combobox.Option` are `div`s, exactly as `select.js`'s
+// are and for the reason its header already gives at length. That is a change
+// to what this component renders, and a caller whose stylesheet names `ul` or
+// `li` will see it; nothing else moved, because the roles were always the part
+// that carried the meaning.
+//
+// `Combobox.Group` and `Combobox.GroupLabel` are then `Select.Group` and
+// `Select.GroupLabel`. The second name is deliberate rather than clumsy:
+// `Combobox.Label` already means the *field's* label, so the heading over a
+// group of options cannot also be `Combobox.Label`, and shadcn's single
+// `SelectLabel` — which is the group's — has no name left for the field's.
+//
+// There is no `Combobox.Separator`, and that is the same decision `select.js`
+// made about the tree rather than a different one about the part. A rule
+// between two groups of options cannot be a `role="separator"`, because a
+// listbox may not own one; it is `aria-hidden` decoration, and a
+// `<div aria-hidden="true">` is something a caller writes without needing a
+// part for it. `Select.Separator` exists because a select's options are a fixed
+// list somebody wrote out and the rule between two of them is fixed too. A
+// combobox's options are whatever survived the filter, so a rule that stays put
+// while the groups either side of it disappear is decoration in the wrong
+// place, and the caller who filtered is the one who knows where it goes.
+//
+// # A command palette is a composition, not a seventh module
+//
+// `crates/uf_lib/src/ui.rs` lists a `Command` with `Root`, `Input`, `List`,
+// `Item`, `Group` and `Empty`, and with groups here every one of those parts
+// now exists: a palette is a `Combobox` inside a `Dialog`, opened by
+// `useKeyCombo("mod+k", …)` from `@uniflowed/hooks/keyboard`, with
+// `Combobox.Group` for the sections, `Combobox.Empty` for the no-results state
+// and `Combobox.Status` for the count. `ubugeeei-redundancy.md`'s objection to
+// small lookalikes is an objection to shipping a module whose entire content is
+// a composition the reader could have written, so the answer is the
+// documentation page — `docs/app/reference/ui`, under "A command palette" —
+// and not a seventh module.
+//
+// One behaviour a `Command` module would genuinely add is not in that page,
+// because it is not implemented anywhere: a palette whose filter matched
+// nothing still traps focus, so `Tab` cycles between a text field and a close
+// button while the reader is told there are no results. That is `Dialog`'s
+// question rather than this module's — a modal with nothing in it to reach is
+// the general case — and it is left open on purpose rather than answered here
+// by a component that would only look like it had.
 
 "use client";
 
@@ -64,12 +127,16 @@ import {
 } from "@uniflowed/react";
 import { useStableCallback } from "@uniflowed/hooks/lifecycle";
 
+import type { Align, LogicalSide } from "./internal/anchor.js";
+import { useAnchor } from "./internal/anchor.js";
 import type { Rest } from "./internal/merge-props.js";
 import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
 import { itemsOf, moveTo } from "./internal/roving-focus.js";
 import { useControlled } from "./internal/controlled-state.js";
 import { FormValue } from "./internal/form-value.js";
 
+export type { Align, LogicalSide, Side } from "./internal/anchor.js";
+
 const OPTION_SELECTOR = '[role="option"]';
 const LISTBOX_SELECTOR = '[role="listbox"]';
 
@@ -116,6 +183,14 @@ hook useCombobox(part: string): ComboboxState {
   return state;
 }
 
+/** The id of a group's label, so `Combobox.Group` only claims one that exists. */
+type ComboboxGroupState = {|
+  readonly labelId: string,
+  readonly registerLabel: (present: boolean) => void,
+|};
+
+const ComboboxGroupContext: React.Context<ComboboxGroupState | null> = createContext(null);
+
 /**
  * The combobox.
  *
@@ -347,11 +422,24 @@ export component ComboboxInput(...rest: Rest) {
 /**
  * The list of options, in the document only while it is open.
  *
+ * A `div` rather than the `ul` this was, because a listbox that owns groups
+ * cannot be a list without a second `list` role between a group and the options
+ * it holds. The module header has the argument and what it costs a caller.
+ *
  * It also keeps the two things that have to stay true as the caller filters:
  * the count the live region announces, and the invariant that
  * `aria-activedescendant` never names an option that has left the list.
  */
-export component ComboboxList(children: renders* ComboboxOption, ...rest: Rest) {
+export component ComboboxList(
+  children: renders* (ComboboxOption | ComboboxGroup),
+  align?: Align = "start",
+  alignOffset?: number = 0,
+  avoidCollisions?: boolean = true,
+  collisionPadding?: number = 0,
+  side?: LogicalSide = "bottom",
+  sideOffset?: number = 0,
+  ...rest: Rest
+) {
   const combobox = useCombobox("Combobox.List");
   const { activeId, count, listRef, inputRef, pendingActive, setActiveId, setCount } = combobox;
   const close = useStableCallback(() => {
@@ -359,6 +447,22 @@ export component ComboboxList(children: renders* ComboboxOption, ...rest: Rest)
     combobox.setActiveId(null);
   });
 
+  // Anchored to the *field*, not to a wrapper the caller may not have written.
+  // `align="start"` because a list of options belongs under the edge the text
+  // starts at, and `--uf-anchor-trigger-width` is what a stylesheet reads to
+  // make it exactly as wide as the field.
+  const anchored = useAnchor({
+    align,
+    alignOffset,
+    anchorRef: inputRef,
+    avoidCollisions,
+    collisionPadding,
+    open: combobox.open,
+    overlayRef: listRef,
+    side,
+    sideOffset,
+  });
+
   // No dependency list on purpose: what this reads is the *rendered* options,
   // and they change whenever the caller re-filters — which is a change to
   // `children` that no dependency list can describe. Every write below is
@@ -427,9 +531,11 @@ export component ComboboxList(children: renders* ComboboxOption, ...rest: Rest)
   const passed = withoutComposed(rest, ["ref"]);
 
   return (
-    <ul
+    <div
       {...passed}
       aria-labelledby={combobox.labelled ? `${combobox.base}-label` : undefined}
+      data-align={anchored.align}
+      data-side={anchored.side}
       id={`${combobox.base}-list`}
       ref={composeRefs(rest.ref, (element) => {
         listRef.current = element;
@@ -437,7 +543,7 @@ export component ComboboxList(children: renders* ComboboxOption, ...rest: Rest)
       role="listbox"
     >
       {children}
-    </ul>
+    </div>
   );
 }
 
@@ -463,7 +569,7 @@ export component ComboboxOption(
   const passed = withoutComposed(rest, ["onClick", "onPointerDown", "onPointerMove"]);
 
   return (
-    <li
+    <div
       {...passed}
       aria-disabled={disabled ? "true" : undefined}
       aria-selected={combobox.value === value ? "true" : "false"}
@@ -495,7 +601,72 @@ export component ComboboxOption(
       role="option"
     >
       {children}
-    </li>
+    </div>
+  );
+}
+
+/**
+ * A named group of options.
+ *
+ * The name reaches the group through `aria-labelledby`, and only while a
+ * `Combobox.GroupLabel` is rendered — the same rule, and the same reason, as
+ * `Select.Group` and `Menu.Group` before it.
+ *
+ * Nothing about `Combobox.Input` had to learn that groups exist. It asks for
+ * `[role="option"]` elements whose nearest `[role="listbox"]` is this list, and
+ * a group is not a listbox — so the arrow keys walk an option at a time across
+ * a boundary they cannot see, and the heading is never a place the cursor can
+ * land, because it is not an option.
+ *
+ * `children` is narrower than `Select.Group`'s `React.Node`, and the narrower
+ * one is the true statement: a `group` inside a `listbox` may own options and
+ * its own heading, and nothing else. `Select.Group` should say the same and
+ * does not yet.
+ */
+export component ComboboxGroup(
+  children: renders* (ComboboxOption | ComboboxGroupLabel),
+  ...rest: Rest
+) {
+  const base = useId();
+  const [labelled, setLabelled] = useState(false);
+
+  const group = useMemo(() => ({ labelId: `${base}-label`, registerLabel: setLabelled }), [base]);
+
+  return (
+    <ComboboxGroupContext.Provider value={group}>
+      <div {...rest} aria-labelledby={labelled ? group.labelId : undefined} role="group">
+        {children}
+      </div>
+    </ComboboxGroupContext.Provider>
+  );
+}
+
+/**
+ * The heading of a `Combobox.Group`.
+ *
+ * `role="presentation"` because the group already carries the name: left as
+ * ordinary content a reader would hear the heading once as the group's name and
+ * again as a stray line of text among the options.
+ *
+ * This is not `Combobox.Label`. That one names the field; this one names a
+ * group of options, and a combobox with groups has both.
+ */
+export component ComboboxGroupLabel(children: React.Node, ...rest: Rest) {
+  const group = useContext(ComboboxGroupContext);
+  const register = group?.registerLabel;
+
+  useEffect(() => {
+    if (register == null) {
+      return;
+    }
+    register(true);
+    return () => register(false);
+  }, [register]);
+
+  return (
+    <div {...rest} id={group?.labelId} role="presentation">
+      {children}
+    </div>
   );
 }