@uniflowed/ui 0.0.0-alpha.12 → 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/hover-card.js

@@ -43,7 +43,7 @@ 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 { composeRefs, withProps, withoutComposed } from "./internal/merge-props.js";
@@ -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,
@@ -213,7 +213,7 @@ export component HoverCardBody(
   alignOffset?: number = 0,
   avoidCollisions?: boolean = true,
   collisionPadding?: number = 0,
-  side?: Side = "bottom",
+  side?: LogicalSide = "bottom",
   sideOffset?: number = 0,
   ...rest: Rest
 ) {

package/index.js

@@ -98,9 +98,16 @@
 //   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.
-// - `combobox.js` — `aria-activedescendant` over a filtered list, and the
-//   count a screen reader is told.
+// - `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.
 // - `select.js` — the other half of the combobox pattern: the select-only one,
 //   with typeahead, option groups and a value a form can submit.
 // - `tabs.js` — the roving `tabindex`, and automatic versus manual activation.
@@ -137,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),
@@ -150,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.
 
@@ -182,10 +191,20 @@ import {
   CarouselPrevious,
   CarouselRoot,
 } from "./carousel.js";
+import {
+  CalendarDay,
+  CalendarMonth,
+  CalendarNext,
+  CalendarPrevious,
+  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,
+  ComboboxGroup,
+  ComboboxGroupLabel,
   ComboboxInput,
   ComboboxLabel,
   ComboboxList,
@@ -193,6 +212,12 @@ import {
   ComboboxRoot,
   ComboboxStatus,
 } from "./combobox.js";
+import {
+  DatePickerCalendar,
+  DatePickerInput,
+  DatePickerRoot,
+  DatePickerTrigger,
+} from "./date-picker.js";
 import {
   DialogBody,
   DialogClose,
@@ -221,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,
@@ -312,6 +341,9 @@ import { ToggleGroupItem, ToggleGroupRoot } from "./toggle-group.js";
 import { TooltipBody, TooltipProvider, TooltipRoot, TooltipTrigger } from "./tooltip.js";
 
 export type { AccordionType } from "./accordion.js";
+// A date, however a caller had one to hand: a `PlainDate` from
+// `@uniflowed/temporal`, or the ISO 8601 string a form field or a URL carries.
+export type { DateValue } from "./calendar.js";
 export type { ActivationMode } from "./tabs.js";
 // What a modal announces itself as, for a caller who holds one in a variable.
 // Two members, not a string: see `dialog.js`.
@@ -324,7 +356,10 @@ export type { SidebarSide } from "./sidebar.js";
 // Where an anchored overlay opens, for a caller who holds one in a variable or
 // a prop of their own. Unions rather than strings, so `side="botom"` is a type
 // error at the call rather than an overlay that quietly opens somewhere else.
-export type { Align, Side } from "./popover.js";
+// `LogicalSide` is the same four plus `inline-start` and `inline-end`, which
+// are the ones that mean "the way the reader reads" - what a submenu opens
+// onto, and the left of the page in Arabic.
+export type { Align, LogicalSide, Side } from "./popover.js";
 export type { Sort } from "./table.js";
 export type { Notification, ToastChanges, ToastOptions, Urgency } from "./toast.js";
 export type { ToggleGroupType } from "./toggle-group.js";
@@ -353,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,
@@ -739,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,
@@ -755,13 +875,19 @@ export const Menu = {
  *     <Combobox.Label>Country</Combobox.Label>
  *     <Combobox.Input />
  *     <Combobox.List>
- *       {matches.map((each) => (
- *         <Combobox.Option key={each} value={each}>{each}</Combobox.Option>
- *       ))}
+ *       <Combobox.Group>
+ *         <Combobox.GroupLabel>Europe</Combobox.GroupLabel>
+ *         {european.map((each) => (
+ *           <Combobox.Option key={each} value={each}>{each}</Combobox.Option>
+ *         ))}
+ *       </Combobox.Group>
  *     </Combobox.List>
  *     <Combobox.Empty>No matches.</Combobox.Empty>
  *     <Combobox.Status />
  *   </Combobox.Root>
+ *
+ * `Combobox.Label` names the field and `Combobox.GroupLabel` names a group of
+ * options, which is why there are two of them.
  */
 export const Combobox = {
   Root: ComboboxRoot,
@@ -769,6 +895,8 @@ export const Combobox = {
   Input: ComboboxInput,
   List: ComboboxList,
   Option: ComboboxOption,
+  Group: ComboboxGroup,
+  GroupLabel: ComboboxGroupLabel,
   Empty: ComboboxEmpty,
   Status: ComboboxStatus,
 };
@@ -837,6 +965,64 @@ export const Popover = {
   Body: PopoverBody,
 };
 
+/**
+ * A month of dates, as one stop in the page's tab order.
+ *
+ * The grid is `role="grid"`, the arrow keys move by a day and by a week, and
+ * `PageUp` and `PageDown` change the month - with `Shift`, the year. Running off
+ * the end of a month shows the next one and lands on its first day, and the
+ * month is announced in a live region when it changes.
+ *
+ *   <Calendar.Root defaultValue="2026-10-14" onValueChange={setWhen}>
+ *     <Calendar.Previous>Previous month</Calendar.Previous>
+ *     <Calendar.Next>Next month</Calendar.Next>
+ *     <Calendar.Month />
+ *   </Calendar.Root>
+ *
+ * `Calendar.Month` takes a function child when a day needs more than its number
+ * in it - a dot for an appointment, a price for a night - and it is handed the
+ * date and returns a `Calendar.Day`.
+ *
+ * Dates are `@uniflowed/temporal`'s `PlainDate`, or the ISO strings it reads.
+ * `isDateDisabled` marks a day unavailable *without* making it unreachable: it
+ * is `aria-disabled` and the arrow keys still land on it, which is the opposite
+ * of what a disabled menu item does and the only way a reader can find out which
+ * days are unavailable.
+ */
+export const Calendar = {
+  Root: CalendarRoot,
+  Previous: CalendarPrevious,
+  Next: CalendarNext,
+  Month: CalendarMonth,
+  Day: CalendarDay,
+};
+
+/**
+ * A field somebody types a date into, and a calendar for the times they would
+ * rather point at one.
+ *
+ *   <DatePicker.Root onValueChange={setWhen} value={when}>
+ *     <DatePicker.Input aria-label="Arrive on" />
+ *     <DatePicker.Trigger>Choose a date</DatePicker.Trigger>
+ *     <DatePicker.Calendar>
+ *       <Calendar.Previous>Previous month</Calendar.Previous>
+ *       <Calendar.Next>Next month</Calendar.Next>
+ *       <Calendar.Month />
+ *     </DatePicker.Calendar>
+ *   </DatePicker.Root>
+ *
+ * The field is the control and the grid is the second way in: `Escape` and a
+ * chosen date both put focus back on the field. `format` and `parse` are ISO
+ * 8601 both ways unless a caller passes their own - `date-picker.js` says why a
+ * locale format is not this package's to guess.
+ */
+export const DatePicker = {
+  Root: DatePickerRoot,
+  Input: DatePickerInput,
+  Trigger: DatePickerTrigger,
+  Calendar: DatePickerCalendar,
+};
+
 /**
  * A phrase about a control, on hover and on focus, that WCAG would accept.
  *