@uniflowed/ui 0.0.0-alpha.9 → 0.2.0

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,30 +17,142 @@
 // 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";
 
 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 type { RenderProp, 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.
+ *
+ * # It is declared here and produced there
+ *
+ * `@uniflowed/form`'s `useFieldSource` builds one of these, so this type is the
+ * seam between the two packages — and it lives on this side only because the
+ * dependency can only run this way today: this package is on npm and that one
+ * is not, and `tools/release/publishable.sh` refuses a published package that
+ * depends on an unpublished one.
+ *
+ * That is backwards, and ubugeeei-prod/uf#614 says so. It stands because
+ * declaring the type twice trades a documented edge for silent drift — a
+ * `Field.Root` accepting a shape `useFieldSource` no longer produces would
+ * type-check on both sides and fail only where they meet — and because the
+ * import is type-only, so no project installing `@uniflowed/form` loads,
+ * bundles or runs any of this package. #210 is the trigger: once
+ * `@uniflowed/form` publishes, this moves there and `@uniflowed/ui` imports it.
+ */
+export type FieldSource = {|
+  readonly invalid: boolean,
+  readonly required: boolean,
+  readonly disabled: boolean,
+  readonly busy: 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,
   readonly labelId: string,
   readonly descriptionId: string,
+  readonly statusId: string,
   readonly errorId: string,
   readonly invalid: boolean,
+  readonly required: boolean,
+  readonly busy: boolean,
+  readonly group: boolean,
+  readonly message: string | null,
+  readonly control: Rest,
   readonly describedBy: string | void,
   readonly registerDescription: (present: boolean) => void,
+  readonly registerStatus: (present: boolean) => void,
   readonly registerError: (present: boolean) => void,
 |};
 
@@ -63,74 +175,151 @@ 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,
+  busy?: boolean = false,
+  field?: FieldSource,
+  group?: boolean = false,
+  render?: RenderProp,
+  ...rest: Rest
+) {
   const base = useId();
   const [hasDescription, setHasDescription] = useState(false);
+  const [hasStatus, setHasStatus] = useState(false);
   const [hasError, setHasError] = useState(false);
+  const sourceInvalid = field?.invalid ?? false;
+  const sourceRequired = field?.required ?? false;
+  const sourceBusy = field?.busy ?? false;
+  const message = field?.message ?? null;
+  const control = field?.control ?? NO_CONTROL;
 
   const state = useMemo(() => {
     const descriptionId = `${base}-description`;
+    const statusId = `${base}-status`;
     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,
+      hasStatus ? statusId : null,
+      wrong && hasError ? errorId : null,
     ].filter(Boolean);
 
     return {
       controlId: `${base}-control`,
       labelId: `${base}-label`,
       descriptionId,
+      statusId,
       errorId,
-      invalid,
+      invalid: wrong,
+      required: required || sourceRequired,
+      busy: busy || sourceBusy,
+      group,
+      message,
+      control,
       describedBy: described.length === 0 ? undefined : described.join(" "),
       registerDescription: setHasDescription,
+      registerStatus: setHasStatus,
       registerError: setHasError,
     };
-  }, [base, invalid, hasDescription, hasError]);
+  }, [
+    base,
+    invalid,
+    sourceInvalid,
+    required,
+    sourceRequired,
+    busy,
+    sourceBusy,
+    group,
+    message,
+    control,
+    hasDescription,
+    hasStatus,
+    hasError,
+  ]);
+
+  const props = withProps(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-busy": group && state.busy ? "true" : undefined,
+    "aria-describedby": group ? state.describedBy : undefined,
+    "aria-invalid": group && state.invalid ? "true" : undefined,
+    "aria-labelledby": group ? state.labelId : undefined,
+    children,
+    role: group ? "group" : undefined,
+  });
 
   return (
     <FieldContext.Provider value={state}>
-      <div {...rest}>{children}</div>
+      {render != null ? render(props) : <div {...props} />}
     </FieldContext.Provider>
   );
 }
 
-/** The label, pointing at the control by id rather than by nesting. */
-export component FieldLabel(children: React.Node, ...rest: Rest) {
+/**
+ * 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, render?: RenderProp, ...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.
-  return (
-    <label {...rest} htmlFor={field.controlId} id={field.labelId}>
-      {children}
-    </label>
-  );
+  if (field.group) {
+    const props = withProps(rest, { children, id: field.labelId });
+    return render != null ? render(props) : <span {...props} />;
+  }
+  const props = withProps(rest, { children, htmlFor: field.controlId, id: field.labelId });
+  return render != null ? render(props) : <label {...props} />;
 }
 
 /**
  * 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) {
+export component FieldControl(render: RenderProp) {
   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 }
+    : {
+        "aria-busy": field.busy ? "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. */
-export component FieldDescription(children: React.Node, ...rest: Rest) {
+export component FieldDescription(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const field = useField("Field.Description");
   const register = field.registerDescription;
   useEffect(() => {
@@ -138,20 +327,47 @@ export component FieldDescription(children: React.Node, ...rest: Rest) {
     return () => register(false);
   }, [register]);
 
-  return (
-    <p {...rest} id={field.descriptionId}>
-      {children}
-    </p>
-  );
+  const props = withProps(rest, { children, id: field.descriptionId });
+  return render != null ? render(props) : <p {...props} />;
+}
+
+/**
+ * Non-error feedback for the field.
+ *
+ * A polite live region has to exist before the text changes. So unlike
+ * `Field.Error`, this part stays in the document even while it is empty; the
+ * control points at it only while the caller rendered the part.
+ */
+export component FieldStatus(children?: React.Node, render?: RenderProp, ...rest: Rest) {
+  const field = useField("Field.Status");
+  const register = field.registerStatus;
+  useEffect(() => {
+    register(true);
+    return () => register(false);
+  }, [register]);
+
+  const props = withProps(rest, {
+    "aria-live": "polite",
+    children: children ?? "",
+    id: field.statusId,
+    role: "status",
+  });
+  return render != null ? render(props) : <p {...props} />;
 }
 
 /**
  * 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, render?: RenderProp, ...rest: Rest) {
   const field = useField("Field.Error");
   const register = field.registerError;
   useEffect(() => {
@@ -162,9 +378,10 @@ export component FieldError(children: React.Node, ...rest: Rest) {
   if (!field.invalid) {
     return null;
   }
-  return (
-    <p {...rest} id={field.errorId} role="alert">
-      {children}
-    </p>
-  );
+  const props = withProps(rest, {
+    children: children ?? field.message,
+    id: field.errorId,
+    role: "alert",
+  });
+  return render != null ? render(props) : <p {...props} />;
 }

package/grid-list.js

@@ -0,0 +1,8 @@
+// @flow
+"use client";
+import * as React from "@uniflowed/react";
+import { CollectionRoot } from "./internal/collection.js";
+import type { CollectionProps } from "./internal/collection.js";
+export component GridList(...props: CollectionProps) {
+  return <CollectionRoot options={props} kind="grid" />;
+}

package/hover-card.js

@@ -43,9 +43,9 @@ import { createContext, useContext, useEffect, useId, useMemo, useRef } from "@u
 import { useEventListener } from "@uniflowed/hooks/dom";
 import { useStableCallback } from "@uniflowed/hooks/lifecycle";
 
-import type { Align, Side } from "./internal/anchor.js";
+import type { Align, LogicalSide } from "./internal/anchor.js";
 import type { HoverIntent } from "./internal/hover-intent.js";
-import type { Rest } from "./internal/merge-props.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
 import { composeRefs, withProps, withoutComposed } from "./internal/merge-props.js";
 import {
   DEFAULT_CLOSE_DELAY,
@@ -57,7 +57,7 @@ import {
 import { useAnchor } from "./internal/anchor.js";
 import { useControlled } from "./internal/controlled-state.js";
 
-export type { Align, Side } from "./internal/anchor.js";
+export type { Align, LogicalSide, Side } from "./internal/anchor.js";
 
 type HoverCardState = {|
   readonly base: string,
@@ -68,7 +68,7 @@ type HoverCardState = {|
   readonly openDelay: number,
   readonly closeDelay: number,
   /** Whether `Escape` has dismissed it; see `tooltip.js`, which shares the rule. */
-  readonly dismissed: { current: boolean },
+  readonly dismissedRef: { current: boolean },
 |};
 
 const HoverCardContext: React.Context<HoverCardState | null> = createContext(null);
@@ -99,14 +99,14 @@ export component HoverCardRoot(
   const base = useId();
   const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
   const triggerRef = useRef<HTMLElement | null>(null);
-  const dismissed = useRef(false);
+  const dismissedRef = useRef(false);
   const intent = useHoverIntent(setOpen);
 
   const state = useMemo(
     () => ({
       base,
       closeDelay,
-      dismissed,
+      dismissedRef,
       intent,
       open: isOpen,
       openDelay,
@@ -127,42 +127,38 @@ export component HoverCardRoot(
  * reachable by keyboard, and `useFocusableTrigger` refuses anything else —
  * a hover card on a `<span>` is one a keyboard reader can never see.
  */
-export component HoverCardTrigger(
-  children?: React.Node,
-  render?: (props: Rest) => React.Node,
-  ...rest: Rest
-) {
+export component HoverCardTrigger(children?: React.Node, render?: RenderProp, ...rest: Rest) {
   const card = useHoverCard("HoverCard.Trigger");
-  const { closeDelay, dismissed, intent, openDelay, triggerRef } = card;
+  const { closeDelay, dismissedRef, intent, openDelay, triggerRef } = card;
   useFocusableTrigger(triggerRef, "HoverCard.Trigger");
 
   // A press focuses the trigger, and a card opening under the reader's own
   // click would cover what they just went to. See `tooltip.js`.
-  const pressed = useRef(false);
+  const pressedRef = useRef(false);
 
   useEventListener(triggerRef, "pointerenter", (event: $FlowFixMe) => {
-    if (event.pointerType === "touch" || dismissed.current) {
+    if (event.pointerType === "touch" || dismissedRef.current) {
       return;
     }
     intent.openAfter(openDelay);
   });
   useEventListener(triggerRef, "pointerleave", () => {
-    dismissed.current = false;
+    dismissedRef.current = false;
     intent.closeAfter(closeDelay);
   });
   useEventListener(triggerRef, "pointerdown", () => {
-    pressed.current = true;
+    pressedRef.current = true;
     intent.cancel();
   });
   useEventListener(triggerRef, "focusin", () => {
-    if (pressed.current) {
-      pressed.current = false;
+    if (pressedRef.current) {
+      pressedRef.current = false;
       return;
     }
     // The focus a dismissed card hands *back* to this trigger must not reopen
     // it, which is the whole reason the flag exists: without it `Escape` closes
     // the card, focus returns here, and the card comes straight back.
-    if (dismissed.current) {
+    if (dismissedRef.current) {
       return;
     }
     // A reader who tabbed here has said what they want; only the pointer is
@@ -170,8 +166,8 @@ export component HoverCardTrigger(
     intent.openAfter(0);
   });
   useEventListener(triggerRef, "focusout", () => {
-    pressed.current = false;
-    dismissed.current = false;
+    pressedRef.current = false;
+    dismissedRef.current = false;
     // `closeAfter` rather than a close, and this is where the delay earns its
     // keep a second time: `Tab` from the trigger *into* the card is a leave
     // followed immediately by an arrival, and the card's own `focusin` calls
@@ -183,19 +179,18 @@ export component HoverCardTrigger(
 
   // Annotated because this one is not written inside a `ref={...}`, and there
   // is nothing else here for Flow to infer the element's type from.
+  // React calls callback refs during commit; pointer and focus handlers read it later.
+  // uf-lint-disable-next-line react-compiler/refs
   const attach = composeRefs(rest.ref, (element: HTMLElement | null) => {
     triggerRef.current = element;
   });
 
+  const props = withProps(withoutComposed(rest, ["ref"]), { children, ref: attach });
+
   if (render != null) {
-    return render(withProps(withoutComposed(rest, ["ref"]), { ref: attach }));
+    return render(props);
   }
-
-  return (
-    <button {...withoutComposed(rest, ["ref"])} ref={attach} type="button">
-      {children}
-    </button>
-  );
+  return <button {...props} type="button" />;
 }
 
 /**
@@ -213,21 +208,22 @@ export component HoverCardBody(
   alignOffset?: number = 0,
   avoidCollisions?: boolean = true,
   collisionPadding?: number = 0,
-  side?: Side = "bottom",
+  render?: RenderProp,
+  side?: LogicalSide = "bottom",
   sideOffset?: number = 0,
   ...rest: Rest
 ) {
   const card = useHoverCard("HoverCard.Body");
-  const { closeDelay, intent, open, triggerRef } = card;
+  const { closeDelay, dismissedRef, intent, open, triggerRef } = card;
   const bodyRef = useRef<HTMLElement | null>(null);
   // Whether the reader is *in* the card, as opposed to over it. It decides one
   // thing and it cannot be asked afterwards: a card closed while it held focus
   // has to hand focus back, and by the time the effect below is cleaned up the
   // element is gone from the document and `activeElement` has already fallen to
   // `<body>` — so the answer is kept while it is still true.
-  const held = useRef(false);
+  const heldRef = useRef(false);
   const close = useStableCallback(() => {
-    card.dismissed.current = true;
+    dismissedRef.current = true;
     intent.cancel();
     card.setOpen(false);
   });
@@ -256,11 +252,11 @@ export component HoverCardBody(
     const stay = () => intent.cancel();
     const go = () => intent.closeAfter(closeDelay);
     const arrived = () => {
-      held.current = true;
+      heldRef.current = true;
       stay();
     };
     const gone = () => {
-      held.current = false;
+      heldRef.current = false;
       go();
     };
     body.addEventListener("pointerenter", stay);
@@ -295,8 +291,8 @@ export component HoverCardBody(
     if (open) {
       return;
     }
-    if (held.current) {
-      held.current = false;
+    if (heldRef.current) {
+      heldRef.current = false;
       triggerRef.current?.focus?.();
     }
   }, [open, triggerRef]);
@@ -305,8 +301,8 @@ export component HoverCardBody(
   // the reader is inside it leaves focus on a node that is gone.
   useEffect(
     () => () => {
-      if (held.current) {
-        held.current = false;
+      if (heldRef.current) {
+        heldRef.current = false;
         triggerRef.current?.focus?.();
       }
     },
@@ -317,18 +313,22 @@ export component HoverCardBody(
     return null;
   }
 
-  return (
-    <div
-      {...withoutComposed(rest, ["ref"])}
-      data-align={anchored.align}
-      data-side={anchored.side}
-      data-state="open"
-      id={`${card.base}-body`}
-      ref={composeRefs(rest.ref, (element) => {
-        bodyRef.current = element;
-      })}
-    >
-      {children}
-    </div>
-  );
+  const props = withProps(withoutComposed(rest, ["ref"]), {
+    children,
+    "data-align": anchored.align,
+    "data-side": anchored.side,
+    "data-state": "open",
+    id: `${card.base}-body`,
+    // React calls callback refs during commit; placement effects read it later.
+    // uf-lint-disable-next-line react-compiler/refs
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      bodyRef.current = element;
+    }),
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+
+  return <div {...props} />;
 }