@uniflowed/ui 0.0.0-alpha.9 → 0.2.0

package/select.js

@@ -146,6 +146,10 @@ 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 type { Movement } from "./internal/roving-focus.js";
@@ -153,6 +157,8 @@ import { isTypeaheadKey, itemsOf, moveTo, useTypeahead } from "./internal/roving
 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"]';
 
@@ -186,7 +192,7 @@ type SelectState = {|
   /** The id of the option `aria-activedescendant` names, if any. */
   readonly activeId: string | null,
   readonly setActiveId: (id: string | null) => void,
-  readonly pendingLanding: { current: Landing | null },
+  readonly pendingLandingRef: { current: Landing | null },
   readonly triggerRef: { current: HTMLElement | null },
   readonly listRef: { current: HTMLElement | null },
   /**
@@ -264,7 +270,7 @@ export component SelectRoot(
   const [activeId, setActiveId] = useState<string | null>(null);
   const [labels, setLabels] = useState<{ readonly [string]: string }>({});
   const [labelled, setLabelled] = useState(false);
-  const pendingLanding = useRef<Landing | null>(null);
+  const pendingLandingRef = useRef<Landing | null>(null);
   const triggerRef = useRef<HTMLElement | null>(null);
   const listRef = useRef<HTMLElement | null>(null);
   const typeahead = useTypeahead();
@@ -307,7 +313,7 @@ export component SelectRoot(
       choose,
       activeId,
       setActiveId,
-      pendingLanding,
+      pendingLandingRef,
       triggerRef,
       listRef,
       labels,
@@ -409,7 +415,9 @@ export component SelectTrigger(children: React.Node, ...rest: Rest) {
   /** Move the cursor within an open list, or open with an instruction. */
   const move = (end: Movement, preferSelected: boolean) => {
     if (!select.open) {
-      select.pendingLanding.current = { kind: "end", end, preferSelected };
+      // This is an instruction for the list after the opening commit.
+      // uf-lint-disable-next-line react-compiler/immutability
+      select.pendingLandingRef.current = { kind: "end", end, preferSelected };
       select.setOpen(true);
       return;
     }
@@ -452,7 +460,9 @@ export component SelectTrigger(children: React.Node, ...rest: Rest) {
           select.setActiveId(null);
           return;
         }
-        select.pendingLanding.current = { kind: "end", end: "first", preferSelected: true };
+        // This is an instruction for the list after the opening commit.
+        // uf-lint-disable-next-line react-compiler/immutability
+        select.pendingLandingRef.current = { kind: "end", end: "first", preferSelected: true };
         select.setOpen(true);
       })}
       onKeyDown={composeHandlers(rest.onKeyDown, (event: $FlowFixMe) => {
@@ -494,7 +504,9 @@ export component SelectTrigger(children: React.Node, ...rest: Rest) {
           // again as a click.
           event.preventDefault();
           if (!select.open) {
-            select.pendingLanding.current = { kind: "end", end: "first", preferSelected: true };
+            // This is an instruction for the list after the opening commit.
+            // uf-lint-disable-next-line react-compiler/immutability
+            select.pendingLandingRef.current = { kind: "end", end: "first", preferSelected: true };
             select.setOpen(true);
             return;
           }
@@ -538,7 +550,8 @@ export component SelectTrigger(children: React.Node, ...rest: Rest) {
           event.preventDefault();
           // The options are not in the document yet, so the keystroke travels
           // to the commit that renders them.
-          select.pendingLanding.current = { kind: "typed", key: event.key };
+          // uf-lint-disable-next-line react-compiler/immutability
+          select.pendingLandingRef.current = { kind: "typed", key: event.key };
           select.setOpen(true);
           return;
         }
@@ -554,6 +567,8 @@ export component SelectTrigger(children: React.Node, ...rest: Rest) {
         }
       })}
       ref={composeRefs(rest.ref, (element) => {
+        // React calls callback refs during commit; the list reads the trigger later.
+        // uf-lint-disable-next-line react-compiler/immutability
         select.triggerRef.current = element;
       })}
       role="combobox"
@@ -613,20 +628,46 @@ export component SelectValue(children?: React.Node, placeholder?: React.Node, ..
  */
 export component SelectList(
   children: renders* (SelectOption | SelectGroup | SelectSeparator),
+  align?: Align = "start",
+  alignOffset?: number = 0,
+  avoidCollisions?: boolean = true,
+  collisionPadding?: number = 0,
+  side?: LogicalSide = "bottom",
+  sideOffset?: number = 0,
   ...rest: Rest
 ) {
   const select = useSelect("Select.List");
-  const { activeId, listRef, pendingLanding, setActiveId, triggerRef, typeahead, value } = select;
+  const { activeId, listRef, pendingLandingRef, setActiveId, triggerRef, typeahead, value } =
+    select;
   const close = useStableCallback(() => {
     select.setOpen(false);
     select.setActiveId(null);
   });
 
+  // The popup a select opens is the one case where the trigger's *width* is
+  // part of the design rather than a detail: a list narrower than the button it
+  // came out of reads as a different control. `--uf-anchor-trigger-width` is
+  // written on this element for a stylesheet to use, which is why the
+  // measurement is here and not in the caller.
+  const anchored = useAnchor({
+    align,
+    alignOffset,
+    anchorRef: triggerRef,
+    avoidCollisions,
+    collisionPadding,
+    open: select.open,
+    overlayRef: listRef,
+    side,
+    sideOffset,
+  });
+
   // No dependency list, for the reason `combobox.js` gives: what this reads is
   // the *rendered* options, and a caller may render different ones on any
   // render — a change to `children` that no dependency list can describe. Every
   // write is guarded by a comparison, so it settles after one extra pass rather
   // than looping.
+  // This effect measures caller-rendered options after commit.
+  // uf-lint-disable-next-line react-compiler/immutability
   useEffect(() => {
     const list = listRef.current;
     if (list == null) {
@@ -634,9 +675,10 @@ export component SelectList(
     }
     const items = itemsOf(list, OPTION_SELECTOR, LISTBOX_SELECTOR);
 
-    const wanted = pendingLanding.current;
+    const wanted = pendingLandingRef.current;
     if (wanted != null) {
-      pendingLanding.current = null;
+      // uf-lint-disable-next-line react-compiler/immutability
+      pendingLandingRef.current = null;
       // An `if` rather than a `match` on `wanted.kind`, because matching on a
       // property does not refine the object that property came from: inside
       // `match (wanted.kind)` both arms still see the whole union, and `uf
@@ -664,32 +706,16 @@ export component SelectList(
     }
   });
 
-  // Keyed on `select.open`, which 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 would run once, on the commit where
-  // `listRef.current` was still null, and never attach the listener at all.
-  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 trigger is not "outside": closing here and letting its own click
-      // reopen the list makes a press on the trigger a no-op that flickers.
-      const trigger = triggerRef.current;
-      if (trigger != null && trigger.contains(target)) {
-        return;
-      }
-      close();
-    };
-    document.addEventListener("pointerdown", onOutsidePress, true);
-    return () => document.removeEventListener("pointerdown", onOutsidePress, true);
-  }, [select.open, close, listRef, triggerRef]);
+  // The refs are read when a press arrives rather than when the listener is
+  // attached, which is what makes `select.open` the only thing this depends on:
+  // this component is mounted the whole time and only *renders* while the list
+  // is open, and a listener attached on the commit where `listRef.current` was
+  // still null used to be one that never worked.
+  useInteractOutside({
+    isDisabled: !select.open,
+    onInteractOutside: () => close(),
+    refs: [listRef, triggerRef],
+  });
 
   if (!select.open) {
     return null;
@@ -701,6 +727,8 @@ export component SelectList(
     <div
       {...passed}
       aria-labelledby={select.labelled ? `${select.base}-label` : undefined}
+      data-align={anchored.align}
+      data-side={anchored.side}
       id={`${select.base}-list`}
       ref={composeRefs(rest.ref, (element) => {
         listRef.current = element;
@@ -793,8 +821,26 @@ export component SelectOption(
  * `Select.GroupLabel` is rendered — the same rule, and the same reason, as
  * `Menu.Group`. The arrow keys pass over the label without stopping on it,
  * because they only ever look for `role="option"`.
+ *
+ * `children` is `renders* (SelectOption | SelectGroupLabel)`, which is what a
+ * `group` inside a `listbox` may hold: options, and the heading that names
+ * them. It took `React.Node` until ubugeeei-prod/uf#562, so a `<div>` in a
+ * group was a runtime surprise — an element with no role between two options,
+ * which the arrow keys walk straight past and a screen reader reads as a stray
+ * line — rather than a type error. `Combobox.Group` has stated the constraint
+ * since #558 and this is the same listbox.
+ *
+ * No `Select.Separator`, and that is deliberate rather than an omission: a rule
+ * separates *groups*, so it belongs between them in `Select.List` — which does
+ * admit one. A separator inside a group is a rule with nothing on one side of
+ * it.
+ *
+ * **Breaking.** A caller passing anything else — a `<div>` wrapper, a fragment
+ * of their own, a component that returns options — now fails `uf check`. The
+ * fix is to hand the options to the group directly; a wrapper had no effect on
+ * what this renders, because the group's element is the one below.
  */
-export component SelectGroup(children: React.Node, ...rest: Rest) {
+export component SelectGroup(children: renders* (SelectOption | SelectGroupLabel), ...rest: Rest) {
   const base = useId();
   const [labelled, setLabelled] = useState(false);
 

package/separator.js

@@ -0,0 +1,97 @@
+// @flow
+//
+// A rule, and the one decision in it: whether anybody is told it is there.
+//
+// Two lines of markup, and it belongs in this package rather than in the preset
+// for the same reason `Progress` does — the component *is* a conditional about
+// what a reader hears:
+//
+//   * A separator **between groups of content** is `role="separator"` with an
+//     `aria-orientation`. A reader moving down the page is told the subject
+//     changed, which is the information the line was drawn to give and the only
+//     way they get it.
+//   * A **decorative** rule — the line under a heading, the hairline between a
+//     card's padding and its footer — is `aria-hidden="true"` and announced to
+//     nobody. It is a border that happens to be an element.
+//
+// Getting it backwards is silent in both directions: a decorative rule with the
+// role adds a "separator" to every reading of the page, and a real boundary
+// without it takes the boundary away from everyone who is not looking at it.
+//
+// The default is the semantic one, because the two mistakes do not cost the
+// same. A rule wrongly announced is noise a reader can hear and skip; a
+// boundary wrongly silent is information that is simply not there, and nobody
+// finds out. `progress.js` makes the same trade in its own sentence: the safe
+// answer has to be the honest one.
+//
+// # Why this is a `<div>` and not an `<hr>`
+//
+// An `<hr>` already carries `role="separator"`, so for a horizontal rule
+// between two blocks of prose it is the better answer and a caller who can use
+// one should. This exists for what it cannot do.
+//
+// It comes with a border and a margin from the browser's own stylesheet, and a
+// package that ships no styles cannot ship a visible line — every consumer
+// would begin by turning it off. It is horizontal by definition, so a vertical
+// rule between two things in a row is a rotated element rather than a described
+// one. And it is a paragraph-level break in the flow, which is not what a
+// hairline inside a toolbar is.
+//
+// # The two separators that are not this one
+//
+// `Menu.Separator` is the rule between groups of menu items, and belongs to the
+// menu because it has to be skipped by the arrow keys that walk it.
+// `Resizable.Handle` announces itself as a separator too, and is a *control* —
+// the APG window splitter, a separator that behaves like a slider. Neither is
+// this, and reaching for this one in either place loses the behaviour that made
+// them their own components.
+//
+// # No `"use client"`
+//
+// One element, two attributes, nothing to remember. It renders on a server.
+
+import type { Orientation } from "./internal/roving-focus.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { withProps } from "./internal/merge-props.js";
+
+export type { Orientation } from "./internal/roving-focus.js";
+
+/**
+ * A rule between two things, or a line that is only a line.
+ *
+ * `decorative` is the whole component. Without it the element is a
+ * `role="separator"` a reader is told about; with it the element is hidden from
+ * the accessibility tree entirely.
+ *
+ *     <Separator />
+ *     <Separator orientation="vertical" />
+ *     <Separator decorative />
+ *
+ * The decorative one gets `aria-hidden` and no role, rather than
+ * `role="presentation"` as well: a `<div>` has nothing to hide behind a
+ * presentation role, and one attribute that removes the element from the tree
+ * says the whole thing. `Breadcrumb.Separator` carries both because it is an
+ * `<li>`, whose `listitem` role would otherwise be counted.
+ *
+ * `aria-orientation` is written out even for the horizontal case, where ARIA
+ * would default to it. It is the attribute a reader of this markup is looking
+ * for, and a default that is left implicit is a default somebody has to know.
+ *
+ * `render` changes the element carrying that decision, not the decision
+ * itself: decorative rules stay hidden, semantic rules keep the separator
+ * role and orientation.
+ */
+export component Separator(
+  decorative?: boolean = false,
+  orientation?: Orientation = "horizontal",
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const props = decorative
+    ? withProps(rest, { "aria-hidden": "true" })
+    : withProps(rest, { "aria-orientation": orientation, role: "separator" });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
+}

package/sheet.js

@@ -0,0 +1,189 @@
+// @flow
+//
+// A sheet: a modal dialog attached to an edge of the viewport.
+//
+// # What it is not, first
+//
+// A `Sheet` that were only a `Dialog` with a class on it would not be worth
+// shipping, and this module would be a paragraph in the documentation saying
+// "use `Dialog` and style it". The edge is a visual decision, `role="dialog"`
+// is already right, and nothing a screen reader is told changes because the
+// dialog slid in from the left. A component that added a `<div>` and a name
+// for that would be a component that made a design system harder to read.
+//
+// What makes it a component is the two things a class cannot be:
+//
+//   * **`side` is a type.** `<Sheet.Root side="lft">` is a Flow error at the
+//     call. A class name is a string, and a misspelt one is a sheet rendered
+//     off the top of the page with nothing reported anywhere.
+//   * **`data-side` is one contract.** The same attribute name `popover.js`
+//     writes, so a stylesheet has one thing to key on for every overlay in this
+//     package — and, more to the point, `drawer.js` and `sidebar.js` are both
+//     *defined in terms of this module*. A drawer is a sheet you can drag away;
+//     a sidebar on a narrow viewport becomes one. Written three times, "left"
+//     would come to mean three subtly different things, and the day one of them
+//     was fixed is the day they stopped agreeing.
+//
+// So the module is small on purpose. It is the shared definition of an edge,
+// and the modal semantics under it are `dialog.js`'s, unchanged: focus in,
+// `Tab` trapped, `Escape` out, focus back, the page inert and still. A sheet is
+// modal, and every one of those is why.
+//
+// # The edge is not announced
+//
+// Deliberately. There is no `aria-*` for "this came in from the right", and
+// inventing one — a `Sheet` that named its edge in its accessible name — would
+// make a reader hear "Filters, right" and wonder what "right" meant. Where the
+// box came from is the eye's business. The reader is told it is a dialog, what
+// it is called, and that the rest of the page is unavailable, which is all
+// three of the things that are true.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useMemo } from "@uniflowed/react";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { forwarded } from "./internal/merge-props.js";
+import {
+  DialogBody,
+  DialogClose,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogRoot,
+  DialogTitle,
+  DialogTrigger,
+} from "./dialog.js";
+
+/**
+ * Which edge of the viewport a sheet is attached to.
+ *
+ * Physical, and deliberately not logical: a design that puts a navigation sheet
+ * against the left of the screen means the left of the screen in any writing
+ * direction, the same way `internal/anchor.js`'s `Side` does and for the same
+ * reason. What the writing direction changes is the reading order inside the
+ * sheet, which is the page's business rather than this component's.
+ *
+ * A union rather than a string, so a typo is a type error at the call rather
+ * than a `data-side="lft"` no stylesheet matches and no test notices.
+ */
+export type Edge = "top" | "right" | "bottom" | "left";
+
+type SheetState = {| readonly side: Edge |};
+
+const SheetContext: React.Context<SheetState | null> = createContext(null);
+
+/**
+ * The sheet a part belongs to.
+ *
+ * Raising rather than returning null, for the reason `useDialog` gives: a
+ * `Sheet.Body` outside a root would render a dialog with no edge, and it would
+ * look correct until somebody styled it.
+ */
+hook useSheet(part: string): SheetState {
+  const state = useContext(SheetContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Sheet.Root`);
+  }
+  return state;
+}
+
+/** The sheet, open or closed. Uncontrolled unless `open` is given. */
+export component SheetRoot(
+  children: React.Node,
+  defaultOpen?: boolean = false,
+  onOpenChange?: (open: boolean) => void,
+  open?: boolean,
+  side?: Edge = "right",
+) {
+  const state = useMemo(() => ({ side }), [side]);
+
+  return (
+    <SheetContext.Provider value={state}>
+      <DialogRoot defaultOpen={defaultOpen} onOpenChange={onOpenChange} open={open}>
+        {children}
+      </DialogRoot>
+    </SheetContext.Provider>
+  );
+}
+
+/** What opens it, and what focus comes back to when it closes. */
+export component SheetTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogTrigger {...forwarded(rest)} render={render}>
+      {children}
+    </DialogTrigger>
+  );
+}
+
+/**
+ * The backdrop, which knows the edge so a stylesheet does not have to be told
+ * twice.
+ */
+export component SheetOverlay(render?: RenderProp, ...rest: Rest) {
+  const sheet = useSheet("Sheet.Overlay");
+  return <DialogOverlay {...forwarded(rest)} data-side={sheet.side} render={render} />;
+}
+
+/**
+ * The sheet itself: `Dialog.Body`, plus the edge as an attribute.
+ *
+ * Every modal promise `dialog.js` makes is made here, unchanged. This part adds
+ * `data-side` and nothing else, which is the honest size of the difference.
+ */
+export component SheetBody(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const sheet = useSheet("Sheet.Body");
+
+  return (
+    <DialogBody {...forwarded(rest)} data-side={sheet.side} render={render}>
+      {children}
+    </DialogBody>
+  );
+}
+
+/** The top of the sheet. See `Dialog.Header` for why it is not a `<header>`. */
+export component SheetHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogHeader {...forwarded(rest)} render={render}>
+      {children}
+    </DialogHeader>
+  );
+}
+
+/** The bottom of the sheet, where the actions go. */
+export component SheetFooter(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogFooter {...forwarded(rest)} render={render}>
+      {children}
+    </DialogFooter>
+  );
+}
+
+/** The sheet's accessible name. A modal without one is announced as "dialog". */
+export component SheetTitle(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogTitle {...forwarded(rest)} render={render}>
+      {children}
+    </DialogTitle>
+  );
+}
+
+/** What the sheet is for, announced after its name. */
+export component SheetDescription(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogDescription {...forwarded(rest)} render={render}>
+      {children}
+    </DialogDescription>
+  );
+}
+
+/** A button that closes the sheet. */
+export component SheetClose(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogClose {...forwarded(rest)} render={render}>
+      {children}
+    </DialogClose>
+  );
+}