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

package/collapsible.js

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

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,9 +127,17 @@ import {
 } from "@uniflowed/react";
 import { useStableCallback } from "@uniflowed/hooks/lifecycle";
 
+import { useInteractOutside } from "./interactions.js";
+
+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"]';
@@ -114,6 +185,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.
  *
@@ -122,6 +201,14 @@ hook useCombobox(part: string): ComboboxState {
  * `open` is whether the list is showing. A search box owns the text and nothing
  * else; a form field owns the value; a page with a "browse all" button owns
  * `open`. Tying them together would make two of those three impossible.
+ *
+ * `name` is what a form submits, and it exists because that same distinction
+ * had a hole in it. `Combobox.Input` renders the *text* — the label the reader
+ * sees — so a combobox named `country` inside a `<form>` submitted "United
+ * Kingdom" where the application meant `GB`, silently and only in production.
+ * Given a `name`, the root renders a hidden control carrying `value` instead;
+ * `internal/form-value.js` says why it is an `<input>` and why
+ * `@uniflowed/form` does not need it.
  */
 export component ComboboxRoot(
   children: React.Node,
@@ -134,7 +221,8 @@ export component ComboboxRoot(
   open?: boolean,
   defaultOpen?: boolean = false,
   onOpenChange?: (open: boolean) => void,
-  ...rest: { readonly [string]: mixed }
+  name?: string,
+  ...rest: Rest
 ) {
   const base = useId();
   const [chosen, setChosen] = useControlled(value, defaultValue, onValueChange);
@@ -190,7 +278,10 @@ export component ComboboxRoot(
 
   return (
     <ComboboxContext.Provider value={state}>
-      <div {...rest}>{children}</div>
+      <div {...rest}>
+        {children}
+        {name == null ? null : <FormValue name={name} value={chosen} />}
+      </div>
     </ComboboxContext.Provider>
   );
 }
@@ -203,7 +294,7 @@ export component ComboboxRoot(
  * because the list names it, and naming a label that is not rendered is worse
  * than leaving the list unnamed.
  */
-export component ComboboxLabel(children: React.Node, ...rest: { readonly [string]: mixed }) {
+export component ComboboxLabel(children: React.Node, ...rest: Rest) {
   const combobox = useCombobox("Combobox.Label");
   const register = combobox.registerLabel;
   useEffect(() => {
@@ -219,7 +310,7 @@ export component ComboboxLabel(children: React.Node, ...rest: { readonly [string
 }
 
 /** The text field, and every key the pattern defines. */
-export component ComboboxInput(...rest: { readonly [string]: mixed }) {
+export component ComboboxInput(...rest: Rest) {
   const combobox = useCombobox("Combobox.Input");
   const passed = withoutComposed(rest, ["onChange", "onKeyDown", "ref"]);
 
@@ -333,13 +424,23 @@ export component ComboboxInput(...rest: { readonly [string]: mixed }) {
 /**
  * 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: { readonly [string]: mixed }
+  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;
@@ -348,6 +449,22 @@ export component ComboboxList(
     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
@@ -381,33 +498,18 @@ export component ComboboxList(
     }
   });
 
-  // Keyed on `combobox.open`, and that is load-bearing. This component is
-  // mounted the whole time and only *renders* while the list is open, so keyed
-  // on the stable callbacks alone the effect ran once — on the first commit,
-  // when `listRef.current` was still null — and never again. The listener was
-  // never attached, and a press outside the combobox closed nothing.
-  useEffect(() => {
-    const list = listRef.current;
-    if (list == null) {
-      return;
-    }
-    const document = list.ownerDocument;
-    const onOutsidePress = (event: Event) => {
-      const target: $FlowFixMe = event.target;
-      if (target == null || list.contains(target)) {
-        return;
-      }
-      // The field is not "outside": pressing it is how a reader gets back to
-      // typing, and closing on it would fight the input's own handlers.
-      const input = inputRef.current;
-      if (input != null && input.contains(target)) {
-        return;
-      }
-      close();
-    };
-    document.addEventListener("pointerdown", onOutsidePress, true);
-    return () => document.removeEventListener("pointerdown", onOutsidePress, true);
-  }, [combobox.open, close, listRef, inputRef]);
+  // The field is not "outside": pressing it is how a reader gets back to
+  // typing, and closing on it would fight the input's own handlers.
+  //
+  // The refs are read when a press arrives rather than when the listener is
+  // attached. This component is mounted the whole time and only *renders*
+  // while the list is open, and the listener that was attached on the first
+  // commit — when `listRef.current` was still null — closed nothing at all.
+  useInteractOutside({
+    isDisabled: !combobox.open,
+    onInteractOutside: () => close(),
+    refs: [listRef, inputRef],
+  });
 
   if (!combobox.open) {
     return null;
@@ -416,9 +518,11 @@ export component ComboboxList(
   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;
@@ -426,7 +530,7 @@ export component ComboboxList(
       role="listbox"
     >
       {children}
-    </ul>
+    </div>
   );
 }
 
@@ -444,7 +548,7 @@ export component ComboboxOption(
   children: React.Node,
   label?: string,
   disabled?: boolean = false,
-  ...rest: { readonly [string]: mixed }
+  ...rest: Rest
 ) {
   const combobox = useCombobox("Combobox.Option");
   const id = useId();
@@ -452,7 +556,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"}
@@ -484,7 +588,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 the true statement rather than a `React.Node` that would take
+ * anything: a `group` inside a `listbox` may own options and its own heading,
+ * and nothing else. `Select.Group` says the same since ubugeeei-prod/uf#562 —
+ * it is the same listbox, and it took a second breaking change to get there.
+ */
+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>
   );
 }
 
@@ -495,7 +664,7 @@ export component ComboboxOption(
  * contain options: an "no matches" row inside one is announced as an option a
  * reader can choose, and choosing it does nothing.
  */
-export component ComboboxEmpty(children: React.Node, ...rest: { readonly [string]: mixed }) {
+export component ComboboxEmpty(children: React.Node, ...rest: Rest) {
   const combobox = useCombobox("Combobox.Empty");
   if (!combobox.open || combobox.count > 0) {
     return null;
@@ -514,7 +683,7 @@ export component ComboboxEmpty(children: React.Node, ...rest: { readonly [string
  * `children` overrides the wording — the default is English and a real
  * application has a translation table.
  */
-export component ComboboxStatus(children?: React.Node, ...rest: { readonly [string]: mixed }) {
+export component ComboboxStatus(children?: React.Node, ...rest: Rest) {
   const combobox = useCombobox("Combobox.Status");
   const message = children ?? defaultAnnouncement(combobox.open, combobox.count);