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

package/field.js

@@ -5,10 +5,10 @@
 // The hard part of a form field is not the markup, it is the wiring: the label
 // has to point at the control, the description and the error message have to be
 // named by `aria-describedby`, the control has to say `aria-invalid` when it is
-// wrong, and every id has to be unique on the page and stable across renders.
-// Doing that by hand is four attributes and two `useId` calls per field, and
-// getting one wrong is silent — the field looks right and a screen reader
-// announces nothing.
+// wrong and `aria-required` before the reader gets there, and every id has to be
+// unique on the page and stable across renders. Doing that by hand is five
+// attributes and two `useId` calls per field, and getting one wrong is silent —
+// the field looks right and a screen reader announces nothing.
 //
 // So the parts read the ids off a context the root creates. `Field.Label` knows
 // which control it labels because there is exactly one in its root, and
@@ -17,14 +17,79 @@
 // document makes a screen reader announce nothing at all, which is worse than
 // omitting the attribute.
 //
+// # One place computes the four attributes
+//
+// This is the whole of ubugeeei-prod/uf#297, and it was a bug that looked like
+// working code. `@uniflowed/form`'s `register("email")` also produces
+// `aria-invalid` and `aria-describedby`, from the form store's errors, and it is
+// right to: a form library is what knows whether a field is wrong. Spread both
+// onto one `<input>` and the *later spread wins*, so the field was described by
+// the form's message or by `Field.Description`, depending on argument order,
+// and never by both.
+//
+// The division that fixes it is the one each package can actually keep:
+//
+//   * **`Field` owns the ids and the attributes**, because it owns the label and
+//     the description and is the only thing that can compose a token list out of
+//     them.
+//   * **The form owns the facts**: is this field invalid, is it required, what
+//     does the message say, and what does the control have to be bound with.
+//
+// `FieldSource` is that handover, and `@uniflowed/form`'s `useFieldSource` is
+// what fills it. Notice what it does *not* contain: no `aria-*` at all. A source
+// that handed over a finished `aria-describedby` would be the same collision
+// with an extra step.
+//
+// # Why the form fills a prop rather than the field reading a context
+//
+// Because the dependency can only run one way. `@uniflowed/ui` is published to
+// npm and `@uniflowed/form` is not — its name has never been bound
+// (ubugeeei-prod/uf#210) — and `tools/ci/publishable.sh` refuses a published
+// package that depends on an unpublished one, because `npm install` would answer
+// `ETARGET` for a package that installs perfectly well from this workspace. So
+// `Field.Root` cannot import a form context, cannot take a `name` and look it
+// up, and cannot know that `@uniflowed/form` exists.
+//
+// What it can do is state the shape it accepts and let the package that *may*
+// depend on it produce one. `field={useFieldSource(form, "email")}` is one hook
+// call where the application used to write `invalid={errors.email != null}` by
+// hand and then choose which of two `aria-describedby` values survived.
+//
 // # Why it takes a render function
 //
 // `Field.Control` hands the attributes to a callback rather than rendering an
 // `<input>`, because a field wraps a select, a textarea, a `Combobox.Input` or
 // somebody else's component just as often, and each of those needs the same
-// four attributes on whatever element it eventually renders. A component that
+// attributes on whatever element it eventually renders. A component that
 // rendered the input itself would have to grow a prop for every element anyone
 // might want, and would still be wrong for the next one.
+//
+// # A group is not a label's `for`
+//
+// `<label for>` names *one* form control. A set of radios, a checkbox group and
+// a date picker made of three selects have no single control to point at, and a
+// `for` aimed at the wrapper around them points at something that is not a form
+// control — which browsers ignore, silently. `Field.Root group` is the answer:
+// the root becomes `role="group"` named by the label through `aria-labelledby`,
+// the label stops being a `<label>`, and the description and the error describe
+// the set rather than one member of it.
+//
+// # Why `Field.Error` is `role="alert"` and `combobox.js` says the opposite
+//
+// `combobox.js`'s header argues that a live region inserted *together with* its
+// content is usually not announced, and that a status region has to be in the
+// document before there is anything to say. Both are true, and this component
+// does the opposite on purpose.
+//
+// The difference is politeness. `role="status"` is polite: a screen reader waits
+// for a pause, by which time a region that appeared and filled in one commit has
+// nothing left to distinguish it, and several engines never announce it at all.
+// `role="alert"` is assertive, and assertive regions are announced on insertion
+// by every engine that implements them — it is what `alert` is for. So the
+// constraint is real and it is `status`'s, not `alert`'s. Written down here
+// because the package states the general rule strongly in one file and does the
+// opposite in another, and a reader who finds the second one first is entitled
+// to know it was a decision.
 
 "use client";
 
@@ -32,6 +97,29 @@ import * as React from "@uniflowed/react";
 import { createContext, useContext, useEffect, useId, useMemo, useState } from "@uniflowed/react";
 
 import type { Rest } from "./internal/merge-props.js";
+import { withProps } from "./internal/merge-props.js";
+
+/**
+ * What a form library tells a field about one of its fields.
+ *
+ * Facts, and no attributes: see the module header for why an `aria-describedby`
+ * in here would be the collision this type exists to end. `control` is the
+ * binding — the `name`, the `ref` the store attaches through, `onChange`,
+ * `onBlur` and the constraint attributes a progressive form emits — spread onto
+ * whatever element `Field.Control` renders, underneath the attributes the field
+ * computes.
+ */
+export type FieldSource = {|
+  readonly invalid: boolean,
+  readonly required: boolean,
+  readonly disabled: boolean,
+  /** What is wrong, or null while the field is valid. */
+  readonly message: string | null,
+  readonly control: Rest,
+|};
+
+/** No form: the shape the field falls back to, made once. */
+const NO_CONTROL: Rest = Object.freeze({});
 
 type FieldState = {|
   readonly controlId: string,
@@ -39,6 +127,10 @@ type FieldState = {|
   readonly descriptionId: string,
   readonly errorId: string,
   readonly invalid: boolean,
+  readonly required: boolean,
+  readonly group: boolean,
+  readonly message: string | null,
+  readonly control: Rest,
   readonly describedBy: string | void,
   readonly registerDescription: (present: boolean) => void,
   readonly registerError: (present: boolean) => void,
@@ -63,24 +155,43 @@ hook useField(part: string): FieldState {
 /**
  * The field's container, and the only place ids are made.
  *
- * `invalid` is the root's business rather than the control's because three
- * parts have to agree about it: the control says `aria-invalid`, the error
- * message is rendered or not, and the control's `aria-describedby` includes the
- * error's id or not.
+ * `invalid` and `required` are the root's business rather than the control's
+ * because three parts have to agree about each: the control says `aria-invalid`
+ * and `aria-required`, the error message is rendered or not, and the control's
+ * `aria-describedby` includes the error's id or not.
+ *
+ * `field` is the same two facts arriving from a form store instead of from the
+ * caller's hand, and it wins over the props when it is there — a field inside a
+ * form has one source of truth about its own validity, and the props are what a
+ * field with no form around it uses. Passing both is not an error; it is a
+ * caller saying "and also mark it invalid", which is what `invalid || source`
+ * means and what a server-side error arriving beside a client-side one needs.
  */
-export component FieldRoot(children: React.Node, invalid?: boolean = false, ...rest: Rest) {
+export component FieldRoot(
+  children: React.Node,
+  invalid?: boolean = false,
+  required?: boolean = false,
+  field?: FieldSource,
+  group?: boolean = false,
+  ...rest: Rest
+) {
   const base = useId();
   const [hasDescription, setHasDescription] = useState(false);
   const [hasError, setHasError] = useState(false);
+  const sourceInvalid = field?.invalid ?? false;
+  const sourceRequired = field?.required ?? false;
+  const message = field?.message ?? null;
+  const control = field?.control ?? NO_CONTROL;
 
   const state = useMemo(() => {
     const descriptionId = `${base}-description`;
     const errorId = `${base}-error`;
+    const wrong = invalid || sourceInvalid;
     // Only ids that are in the document. `aria-describedby` naming a missing
     // element makes a screen reader announce nothing rather than skipping it.
     const described = [
       hasDescription ? descriptionId : null,
-      invalid && hasError ? errorId : null,
+      wrong && hasError ? errorId : null,
     ].filter(Boolean);
 
     return {
@@ -88,25 +199,64 @@ export component FieldRoot(children: React.Node, invalid?: boolean = false, ...r
       labelId: `${base}-label`,
       descriptionId,
       errorId,
-      invalid,
+      invalid: wrong,
+      required: required || sourceRequired,
+      group,
+      message,
+      control,
       describedBy: described.length === 0 ? undefined : described.join(" "),
       registerDescription: setHasDescription,
       registerError: setHasError,
     };
-  }, [base, invalid, hasDescription, hasError]);
+  }, [
+    base,
+    invalid,
+    sourceInvalid,
+    required,
+    sourceRequired,
+    group,
+    message,
+    control,
+    hasDescription,
+    hasError,
+  ]);
 
   return (
     <FieldContext.Provider value={state}>
-      <div {...rest}>{children}</div>
+      <div
+        {...rest}
+        // A group names itself, describes itself and reports its own validity,
+        // because there is no one control inside it to carry any of the three.
+        // See the module header.
+        aria-describedby={group ? state.describedBy : undefined}
+        aria-invalid={group && state.invalid ? "true" : undefined}
+        aria-labelledby={group ? state.labelId : undefined}
+        role={group ? "group" : undefined}
+      >
+        {children}
+      </div>
     </FieldContext.Provider>
   );
 }
 
-/** The label, pointing at the control by id rather than by nesting. */
+/**
+ * The label, pointing at the control by id rather than by nesting.
+ *
+ * In a group it is a `<span>` instead, and the group points at *it*: a
+ * `<label for>` naming something that is not a form control is ignored by every
+ * browser, and ignored silently. The module header says more.
+ */
 export component FieldLabel(children: React.Node, ...rest: Rest) {
   const field = useField("Field.Label");
   // `rest` first: a caller `id` here would break the relationship the control
   // points at, and it would break it silently.
+  if (field.group) {
+    return (
+      <span {...rest} id={field.labelId}>
+        {children}
+      </span>
+    );
+  }
   return (
     <label {...rest} htmlFor={field.controlId} id={field.labelId}>
       {children}
@@ -117,16 +267,27 @@ export component FieldLabel(children: React.Node, ...rest: Rest) {
 /**
  * The control, given every attribute the rest of the field implies.
  *
- * See the module header for why this takes a render function.
+ * See the module header for why this takes a render function, and for the
+ * division of labour that decides what is in here. The form's own binding is
+ * underneath, so a caller who spreads these onto an element gets the store's
+ * `ref` and handlers *and* the field's attributes from one spread instead of
+ * two that overwrite each other.
  */
 export component FieldControl(render: (props: Rest) => React.Node) {
   const field = useField("Field.Control");
-  return render({
-    id: field.controlId,
-    "aria-labelledby": field.labelId,
-    "aria-describedby": field.describedBy,
-    "aria-invalid": field.invalid ? "true" : undefined,
-  });
+  // A group already carries the name, the description and the validity, and a
+  // control repeating them makes a reader hear the error once for the set and
+  // again for the member. What is left is what only the control can say.
+  const own: Rest = field.group
+    ? { "aria-required": field.required ? "true" : undefined }
+    : {
+        id: field.controlId,
+        "aria-labelledby": field.labelId,
+        "aria-describedby": field.describedBy,
+        "aria-invalid": field.invalid ? "true" : undefined,
+        "aria-required": field.required ? "true" : undefined,
+      };
+  return render(withProps(field.control, own));
 }
 
 /** Help text, which the control points at while it is rendered. */
@@ -149,9 +310,15 @@ export component FieldDescription(children: React.Node, ...rest: Rest) {
  * The error message, rendered only when the field is invalid.
  *
  * `role="alert"` so it is announced when it appears, which is the point of an
- * error that arrives after a blur or a submit.
+ * error that arrives after a blur, a submit, or a Server Action — see the
+ * module header for why an assertive region may be inserted with its text where
+ * a polite one may not.
+ *
+ * With no children it shows the message the form gave, so a field bound to a
+ * store does not need the caller to reach back into `formState.errors` for a
+ * string the source is already carrying.
  */
-export component FieldError(children: React.Node, ...rest: Rest) {
+export component FieldError(children?: React.Node, ...rest: Rest) {
   const field = useField("Field.Error");
   const register = field.registerError;
   useEffect(() => {
@@ -164,7 +331,7 @@ export component FieldError(children: React.Node, ...rest: Rest) {
   }
   return (
     <p {...rest} id={field.errorId} role="alert">
-      {children}
+      {children ?? field.message}
     </p>
   );
 }

package/index.js

@@ -98,7 +98,13 @@
 //   than what they replaced. Each module's header says what it gives that the
 //   plain element does not; if it ever stops being true, the component should
 //   be deleted rather than fixed.
-// - `menu.js` — the arrow keys, typeahead, submenus and `Escape` stacking.
+// - `menu.js`, `context-menu.js` and `menubar.js` — the arrow keys, typeahead,
+//   submenus and `Escape` stacking, and the two components that are that
+//   behaviour opened differently. A context menu is opened by the right button,
+//   by `Shift+F10` and by a long press, and opens at a *point*; a menubar is a
+//   row of them with one tab stop and arrows that walk between the open menus.
+//   shadcn's fourth menu, Dropdown Menu, is `menu.js` under another name and is
+//   deliberately not a second export.
 // - `combobox.js` — `aria-activedescendant` over a filtered list, the count a
 //   screen reader is told, and the option groups that make a command palette a
 //   composition rather than a seventh module.
@@ -138,7 +144,7 @@
 // is by primitive because that is the unit a reader looks for, the unit a
 // bundler drops, and the unit the WAI-ARIA practices are written in.
 //
-// `internal/` holds nine modules and nothing else, each a rule the primitives
+// `internal/` holds ten modules and nothing else, each a rule the primitives
 // must apply identically and a consumer must not be able to apply differently:
 // `merge-props.js` (the caller's props go on first, the component's semantics
 // last), `controlled-state.js` (what "controlled" means here),
@@ -151,8 +157,10 @@
 // fit where it was asked to go), `focus.js` (which elements a reader can reach,
 // which a focus trap and a popover want opposite things from), and
 // `hover-intent.js` (what WCAG requires of content shown on hover or focus,
-// which is three clauses and one mechanism). Each says in its own header why it
-// is unreachable rather than exported. There is no `internal/props.js`-shaped
+// which is three clauses and one mechanism), and `menu-tree.js` (the chain of
+// open menus the three menu components share, and what `Escape` and choosing an
+// item are defined in terms of). Each says in its own header why it is
+// unreachable rather than exported. There is no `internal/props.js`-shaped
 // bag of helpers: a module that cannot say what it is about does not belong in
 // this package.
 
@@ -191,6 +199,7 @@ import {
   CalendarRoot,
 } from "./calendar.js";
 import { Checkbox } from "./checkbox.js";
+import { ContextMenuRoot, ContextMenuTrigger } from "./context-menu.js";
 import { CollapsibleContent, CollapsibleRoot, CollapsibleTrigger } from "./collapsible.js";
 import {
   ComboboxEmpty,
@@ -237,15 +246,19 @@ import { HoverCardBody, HoverCardRoot, HoverCardTrigger } from "./hover-card.js"
 import { InputOtpGroup, InputOtpRoot, InputOtpSeparator, InputOtpSlot } from "./input-otp.js";
 import {
   MenuBody,
+  MenuCheckboxItem,
   MenuGroup,
   MenuItem,
   MenuLabel,
+  MenuRadioGroup,
+  MenuRadioItem,
   MenuRoot,
   MenuSeparator,
   MenuSub,
   MenuSubTrigger,
   MenuTrigger,
 } from "./menu.js";
+import { MenubarMenu, MenubarRoot, MenubarTrigger } from "./menubar.js";
 import {
   NavigationMenuBody,
   NavigationMenuItem,
@@ -375,6 +388,20 @@ export { dismissAllToasts, dismissToast, toast, updateToast };
  *     <Field.Description>We will not share it.</Field.Description>
  *     <Field.Error>{error}</Field.Error>
  *   </Field.Root>
+ *
+ * Inside a form, `field` replaces the hand-written `invalid`: the form says
+ * whether the field is wrong and what the message is, and the field composes
+ * every `aria-*` from that in one place. `@uniflowed/form`'s `useFieldSource`
+ * is what produces one, and `field.js`'s header says why the hook lives there
+ * rather than here.
+ *
+ *   const email = useFieldSource(form, "email", { required: "We need one" });
+ *   <Field.Root field={email}>…<Field.Error /></Field.Root>
+ *
+ * `group` is for a set with no single control to point a `<label for>` at — a
+ * radio group, a checkbox group, three selects making a date. The root becomes
+ * `role="group"` named by the label, and the description and the error describe
+ * the set.
  */
 export const Field = {
   Root: FieldRoot,
@@ -761,6 +788,77 @@ export const Menu = {
   Trigger: MenuTrigger,
   Body: MenuBody,
   Item: MenuItem,
+  CheckboxItem: MenuCheckboxItem,
+  RadioGroup: MenuRadioGroup,
+  RadioItem: MenuRadioItem,
+  Separator: MenuSeparator,
+  Group: MenuGroup,
+  Label: MenuLabel,
+  Sub: MenuSub,
+  SubTrigger: MenuSubTrigger,
+};
+
+/**
+ * The same menu, opened by the right button — and by the keyboard.
+ *
+ * `Shift+F10`, the `ContextMenu` key and a long press all open it, because a
+ * command reachable only by right-click is reachable only by a pointer, which
+ * is a WCAG 2.1.1 failure. `context-menu.js` says why the trigger is in the tab
+ * order and when to take it out again.
+ *
+ * The body needs an `aria-label`: its trigger is a table row or a canvas rather
+ * than a short name, so unlike `Menu.Body` it cannot name itself after one.
+ *
+ *   <ContextMenu.Root>
+ *     <ContextMenu.Trigger>{row}</ContextMenu.Trigger>
+ *     <ContextMenu.Body aria-label="Row actions">
+ *       <ContextMenu.Item onSelect={rename}>Rename…</ContextMenu.Item>
+ *       <ContextMenu.CheckboxItem defaultChecked>Show hidden</ContextMenu.CheckboxItem>
+ *     </ContextMenu.Body>
+ *   </ContextMenu.Root>
+ */
+export const ContextMenu = {
+  Root: ContextMenuRoot,
+  Trigger: ContextMenuTrigger,
+  Body: MenuBody,
+  Item: MenuItem,
+  CheckboxItem: MenuCheckboxItem,
+  RadioGroup: MenuRadioGroup,
+  RadioItem: MenuRadioItem,
+  Separator: MenuSeparator,
+  Group: MenuGroup,
+  Label: MenuLabel,
+  Sub: MenuSub,
+  SubTrigger: MenuSubTrigger,
+};
+
+/**
+ * A row of menus that behaves as one control: File, Edit, View.
+ *
+ * One tab stop for the whole bar, arrows between the menus, and — the part that
+ * is always missing — arrows *while a menu is open* that close it and open the
+ * next one, so a reader walks File → Edit → View without pressing Escape.
+ *
+ *   <Menubar.Root aria-label="Main">
+ *     <Menubar.Menu value="file">
+ *       <Menubar.Trigger>File</Menubar.Trigger>
+ *       <Menubar.Body>
+ *         <Menubar.Item onSelect={open}>Open…</Menubar.Item>
+ *       </Menubar.Body>
+ *     </Menubar.Menu>
+ *   </Menubar.Root>
+ */
+export const Menubar = {
+  Root: MenubarRoot,
+  Menu: MenubarMenu,
+  Trigger: MenubarTrigger,
+  // `Menu.Body` itself: a bar's menu is a root menu, and `menubar.js`'s header
+  // says why a wrapper with the same defaults would be a second place to drift.
+  Body: MenuBody,
+  Item: MenuItem,
+  CheckboxItem: MenuCheckboxItem,
+  RadioGroup: MenuRadioGroup,
+  RadioItem: MenuRadioItem,
   Separator: MenuSeparator,
   Group: MenuGroup,
   Label: MenuLabel,

package/internal/anchor.js

@@ -183,6 +183,24 @@ export type Anchored = {|
 /** What `useAnchor` is told, on top of the geometry `placeOverlay` needs. */
 export type AnchorRequest = {|
   readonly anchorRef: { current: HTMLElement | null },
+  /**
+   * A box to place against instead of the anchor element's own.
+   *
+   * A context menu opens *at a point* rather than against an element: the
+   * pointer coordinates the reader right-clicked at, which is a zero-sized
+   * rectangle no element in the document has. The element is still needed —
+   * it is what the writing direction is read from, what a `ResizeObserver`
+   * watches, and what focus returns to — so this replaces the *measurement*
+   * and nothing else.
+   *
+   * `null` (and absent) means "measure the element", which is every other
+   * overlay in this package.
+   *
+   * It has to be stable between renders for the same position, because it is
+   * one of the things the placement effect re-runs for; a fresh object each
+   * render would re-measure on every render of the page around it.
+   */
+  readonly anchorRect?: Rect | null,
   readonly overlayRef: { current: HTMLElement | null },
   /** Nothing is measured while it is closed: there is nothing to measure. */
   readonly open: boolean,
@@ -424,6 +442,7 @@ export hook useAnchor(request: AnchorRequest): Anchored {
   const {
     align,
     alignOffset,
+    anchorRect,
     anchorRef,
     avoidCollisions,
     collisionPadding,
@@ -432,6 +451,9 @@ export hook useAnchor(request: AnchorRequest): Anchored {
     side,
     sideOffset,
   } = request;
+  // Absent and `null` are one answer here — "measure the element" — so the two
+  // spellings become one value before anything depends on it.
+  const virtual = anchorRect ?? null;
   // The left-to-right reading of a logical side, which is what `Anchored`
   // reports until something has been measured. In a right-to-left page a
   // submenu's `inline-end` is the *left*, and the first `reflow` says so - one
@@ -446,7 +468,7 @@ export hook useAnchor(request: AnchorRequest): Anchored {
     if (anchor == null || overlay == null || view == null) {
       return;
     }
-    const box = rectOf(anchor);
+    const box = virtual ?? rectOf(anchor);
     const placement = placeOverlay({
       align,
       alignOffset,
@@ -524,6 +546,7 @@ export hook useAnchor(request: AnchorRequest): Anchored {
   }, [
     align,
     alignOffset,
+    anchorRect,
     anchorRef,
     avoidCollisions,
     collisionPadding,