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

package/combobox.js

@@ -49,6 +49,69 @@
 // the active option is cleared when the option it named is filtered away, the
 // count is remeasured, and `aria-activedescendant` never names an id that has
 // left the document.
+//
+// # Groups, and the two elements that had to change to have them
+//
+// A `listbox` may own `option` and `group` elements, and nothing else. This
+// module rendered a `<ul>` of `<li>`s, which is the right shape for a flat list
+// and the wrong one the moment a group appears: a group's options belong inside
+// the group, a group inside a `<ul>` is an `<li>`, and an `<li>` inside an
+// `<li>` is not something HTML has. The parser closes the outer one, so the
+// markup a server sent and the tree a browser built would disagree — which
+// React finds at hydration, in production, on the one page that had groups.
+//
+// The way out that keeps the list is a second `<ul role="presentation">` around
+// each group's options, and it was rejected twice over. It works by an
+// inheritance rule — a presentational role propagating to the elements its own
+// role requires, except where a child carries an explicit role — which is
+// correct in the specification and up to the software, and this package's whole
+// premise is not building on that distinction. It would also leave the two
+// halves of one pattern with two differently shaped listboxes, for a reason
+// neither module could state.
+//
+// So `Combobox.List` and `Combobox.Option` are `div`s, exactly as `select.js`'s
+// are and for the reason its header already gives at length. That is a change
+// to what this component renders, and a caller whose stylesheet names `ul` or
+// `li` will see it; nothing else moved, because the roles were always the part
+// that carried the meaning.
+//
+// `Combobox.Group` and `Combobox.GroupLabel` are then `Select.Group` and
+// `Select.GroupLabel`. The second name is deliberate rather than clumsy:
+// `Combobox.Label` already means the *field's* label, so the heading over a
+// group of options cannot also be `Combobox.Label`, and shadcn's single
+// `SelectLabel` — which is the group's — has no name left for the field's.
+//
+// There is no `Combobox.Separator`, and that is the same decision `select.js`
+// made about the tree rather than a different one about the part. A rule
+// between two groups of options cannot be a `role="separator"`, because a
+// listbox may not own one; it is `aria-hidden` decoration, and a
+// `<div aria-hidden="true">` is something a caller writes without needing a
+// part for it. `Select.Separator` exists because a select's options are a fixed
+// list somebody wrote out and the rule between two of them is fixed too. A
+// combobox's options are whatever survived the filter, so a rule that stays put
+// while the groups either side of it disappear is decoration in the wrong
+// place, and the caller who filtered is the one who knows where it goes.
+//
+// # A command palette is a composition, not a seventh module
+//
+// `crates/uf_lib/src/ui.rs` lists a `Command` with `Root`, `Input`, `List`,
+// `Item`, `Group` and `Empty`, and with groups here every one of those parts
+// now exists: a palette is a `Combobox` inside a `Dialog`, opened by
+// `useKeyCombo("mod+k", …)` from `@uniflowed/hooks/keyboard`, with
+// `Combobox.Group` for the sections, `Combobox.Empty` for the no-results state
+// and `Combobox.Status` for the count. `ubugeeei-redundancy.md`'s objection to
+// small lookalikes is an objection to shipping a module whose entire content is
+// a composition the reader could have written, so the answer is the
+// documentation page — `docs/app/reference/ui`, under "A command palette" —
+// and not a seventh module.
+//
+// One behaviour a `Command` module would genuinely add is not in that page,
+// because it is not implemented anywhere: a palette whose filter matched
+// nothing still traps focus, so `Tab` cycles between a text field and a close
+// button while the reader is told there are no results. That is `Dialog`'s
+// question rather than this module's — a modal with nothing in it to reach is
+// the general case — and it is left open on purpose rather than answered here
+// by a component that would only look like it had.
 
 "use client";
 
@@ -64,12 +127,16 @@ import {
 } from "@uniflowed/react";
 import { useStableCallback } from "@uniflowed/hooks/lifecycle";
 
+import type { Align, LogicalSide } from "./internal/anchor.js";
+import { useAnchor } from "./internal/anchor.js";
 import type { Rest } from "./internal/merge-props.js";
 import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
 import { itemsOf, moveTo } from "./internal/roving-focus.js";
 import { useControlled } from "./internal/controlled-state.js";
 import { FormValue } from "./internal/form-value.js";
 
+export type { Align, LogicalSide, Side } from "./internal/anchor.js";
+
 const OPTION_SELECTOR = '[role="option"]';
 const LISTBOX_SELECTOR = '[role="listbox"]';
 
@@ -116,6 +183,14 @@ hook useCombobox(part: string): ComboboxState {
   return state;
 }
 
+/** The id of a group's label, so `Combobox.Group` only claims one that exists. */
+type ComboboxGroupState = {|
+  readonly labelId: string,
+  readonly registerLabel: (present: boolean) => void,
+|};
+
+const ComboboxGroupContext: React.Context<ComboboxGroupState | null> = createContext(null);
+
 /**
  * The combobox.
  *
@@ -347,11 +422,24 @@ export component ComboboxInput(...rest: Rest) {
 /**
  * The list of options, in the document only while it is open.
  *
+ * A `div` rather than the `ul` this was, because a listbox that owns groups
+ * cannot be a list without a second `list` role between a group and the options
+ * it holds. The module header has the argument and what it costs a caller.
+ *
  * It also keeps the two things that have to stay true as the caller filters:
  * the count the live region announces, and the invariant that
  * `aria-activedescendant` never names an option that has left the list.
  */
-export component ComboboxList(children: renders* ComboboxOption, ...rest: Rest) {
+export component ComboboxList(
+  children: renders* (ComboboxOption | ComboboxGroup),
+  align?: Align = "start",
+  alignOffset?: number = 0,
+  avoidCollisions?: boolean = true,
+  collisionPadding?: number = 0,
+  side?: LogicalSide = "bottom",
+  sideOffset?: number = 0,
+  ...rest: Rest
+) {
   const combobox = useCombobox("Combobox.List");
   const { activeId, count, listRef, inputRef, pendingActive, setActiveId, setCount } = combobox;
   const close = useStableCallback(() => {
@@ -359,6 +447,22 @@ export component ComboboxList(children: renders* ComboboxOption, ...rest: Rest)
     combobox.setActiveId(null);
   });
 
+  // Anchored to the *field*, not to a wrapper the caller may not have written.
+  // `align="start"` because a list of options belongs under the edge the text
+  // starts at, and `--uf-anchor-trigger-width` is what a stylesheet reads to
+  // make it exactly as wide as the field.
+  const anchored = useAnchor({
+    align,
+    alignOffset,
+    anchorRef: inputRef,
+    avoidCollisions,
+    collisionPadding,
+    open: combobox.open,
+    overlayRef: listRef,
+    side,
+    sideOffset,
+  });
+
   // No dependency list on purpose: what this reads is the *rendered* options,
   // and they change whenever the caller re-filters — which is a change to
   // `children` that no dependency list can describe. Every write below is
@@ -427,9 +531,11 @@ export component ComboboxList(children: renders* ComboboxOption, ...rest: Rest)
   const passed = withoutComposed(rest, ["ref"]);
 
   return (
-    <ul
+    <div
       {...passed}
       aria-labelledby={combobox.labelled ? `${combobox.base}-label` : undefined}
+      data-align={anchored.align}
+      data-side={anchored.side}
       id={`${combobox.base}-list`}
       ref={composeRefs(rest.ref, (element) => {
         listRef.current = element;
@@ -437,7 +543,7 @@ export component ComboboxList(children: renders* ComboboxOption, ...rest: Rest)
       role="listbox"
     >
       {children}
-    </ul>
+    </div>
   );
 }
 
@@ -463,7 +569,7 @@ export component ComboboxOption(
   const passed = withoutComposed(rest, ["onClick", "onPointerDown", "onPointerMove"]);
 
   return (
-    <li
+    <div
       {...passed}
       aria-disabled={disabled ? "true" : undefined}
       aria-selected={combobox.value === value ? "true" : "false"}
@@ -495,7 +601,72 @@ export component ComboboxOption(
       role="option"
     >
       {children}
-    </li>
+    </div>
+  );
+}
+
+/**
+ * A named group of options.
+ *
+ * The name reaches the group through `aria-labelledby`, and only while a
+ * `Combobox.GroupLabel` is rendered — the same rule, and the same reason, as
+ * `Select.Group` and `Menu.Group` before it.
+ *
+ * Nothing about `Combobox.Input` had to learn that groups exist. It asks for
+ * `[role="option"]` elements whose nearest `[role="listbox"]` is this list, and
+ * a group is not a listbox — so the arrow keys walk an option at a time across
+ * a boundary they cannot see, and the heading is never a place the cursor can
+ * land, because it is not an option.
+ *
+ * `children` is narrower than `Select.Group`'s `React.Node`, and the narrower
+ * one is the true statement: a `group` inside a `listbox` may own options and
+ * its own heading, and nothing else. `Select.Group` should say the same and
+ * does not yet.
+ */
+export component ComboboxGroup(
+  children: renders* (ComboboxOption | ComboboxGroupLabel),
+  ...rest: Rest
+) {
+  const base = useId();
+  const [labelled, setLabelled] = useState(false);
+
+  const group = useMemo(() => ({ labelId: `${base}-label`, registerLabel: setLabelled }), [base]);
+
+  return (
+    <ComboboxGroupContext.Provider value={group}>
+      <div {...rest} aria-labelledby={labelled ? group.labelId : undefined} role="group">
+        {children}
+      </div>
+    </ComboboxGroupContext.Provider>
+  );
+}
+
+/**
+ * The heading of a `Combobox.Group`.
+ *
+ * `role="presentation"` because the group already carries the name: left as
+ * ordinary content a reader would hear the heading once as the group's name and
+ * again as a stray line of text among the options.
+ *
+ * This is not `Combobox.Label`. That one names the field; this one names a
+ * group of options, and a combobox with groups has both.
+ */
+export component ComboboxGroupLabel(children: React.Node, ...rest: Rest) {
+  const group = useContext(ComboboxGroupContext);
+  const register = group?.registerLabel;
+
+  useEffect(() => {
+    if (register == null) {
+      return;
+    }
+    register(true);
+    return () => register(false);
+  }, [register]);
+
+  return (
+    <div {...rest} id={group?.labelId} role="presentation">
+      {children}
+    </div>
   );
 }
 

package/date-picker.js

@@ -0,0 +1,346 @@
+// @flow
+//
+// A field somebody types a date into, and a calendar for the times they would
+// rather point at one.
+//
+// # Why the field comes first
+//
+// A date picker whose only input is the grid is slower for everybody who
+// already knows the date — nine keystrokes to arrow to a day they could have
+// typed in six — and it is unusable for anybody who cannot operate a grid at
+// all. So the text field is the control, the calendar is the second way in, and
+// the composition is written down here rather than left to each application to
+// assemble differently.
+//
+// # It is a composition, and the parts are the ones that already exist
+//
+// `Popover` for the overlay and its dismissal, `Calendar` for the grid. Nothing
+// about anchoring, outside presses, `Escape` or focus restoration is
+// reimplemented here, which is the point: ubugeeei-prod/uf#256's complaint was
+// five components each carrying a corner of the same behaviour, and a sixth
+// carrying its own corner would be the same mistake with a different name.
+//
+// What this module does own is the three joins between them:
+//
+//   * the field's text and the chosen date, which are not the same value and
+//     must not be kept in step by an effect that fights the reader's typing;
+//   * `Escape` and a chosen date both returning focus to the *field* rather than
+//     to the button, because the field is the primary control;
+//   * the calendar opening with focus on a date rather than on the button that
+//     steps back a month, which is `Popover.Body`'s `initialFocus` and
+//     `Calendar.Root`'s `focusedDayRef` meeting.
+//
+// # Parsing is `@uniflowed/temporal`'s, not this module's
+//
+// `format` and `parse` default to ISO 8601, because that is the format
+// `Temporal.PlainDate` reads and writes and the only one this package can claim
+// to handle. `12/03/26` is the third of December or the twelfth of March
+// depending on where the reader is, and answering that needs the locale's date
+// patterns — CLDR data, which is what `@uniflowed/temporal`'s calendar surface
+// waits on the native runtime for. A UI package that shipped its own guess at it
+// would be a wrong date in production rather than a missing feature, so the two
+// props are the seam: an application with a locale format passes both, and gets
+// its own round trip rather than this module's approximation of one.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useMemo, useRef, useState } from "@uniflowed/react";
+import { useStableCallback } from "@uniflowed/hooks/lifecycle";
+import type { PlainDate } from "@uniflowed/core/temporal";
+import { Temporal } from "@uniflowed/core/temporal";
+
+import type { DateValue } from "./calendar.js";
+import { CalendarRoot } from "./calendar.js";
+import { useControlled } from "./internal/controlled-state.js";
+import type { Align, LogicalSide } from "./internal/anchor.js";
+import type { Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  forwarded,
+  withoutComposed,
+} from "./internal/merge-props.js";
+import { PopoverBody, PopoverRoot, PopoverTrigger } from "./popover.js";
+
+type DatePickerState = {|
+  /** The text in the field, which is the draft while one is being typed. */
+  readonly text: string,
+  readonly setDraft: (text: string | null) => void,
+  /** Whether the last thing typed could not be read as a date. */
+  readonly invalid: boolean,
+  readonly commit: (text: string) => void,
+  readonly choose: (date: PlainDate) => void,
+  readonly value: PlainDate | null,
+  readonly fieldRef: { current: HTMLElement | null },
+  readonly focusField: () => void,
+|};
+
+const DatePickerContext: React.Context<DatePickerState | null> = createContext(null);
+
+hook useDatePicker(part: string): DatePickerState {
+  const state = useContext(DatePickerContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a DatePicker.Root`);
+  }
+  return state;
+}
+
+/** ISO 8601, which is what `PlainDate.toString` produces and `from` parses. */
+function isoFormat(date: PlainDate): string {
+  return date.toString();
+}
+
+/**
+ * ISO 8601 or nothing.
+ *
+ * `PlainDate.from` throws a `RangeError` on anything it cannot read, and a
+ * reader half way through typing a date is in that state on almost every
+ * keystroke — so the failure is a value here rather than an exception, and the
+ * field decides what to do about it.
+ */
+function isoParse(text: string): PlainDate | null {
+  const trimmed = text.trim();
+  if (trimmed === "") {
+    return null;
+  }
+  try {
+    return Temporal.PlainDate.from(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The value, the popover around the calendar, and the joins between them.
+ *
+ * Renders no element of its own: the field, the button and the calendar are
+ * siblings in whatever layout the caller wrote, and a wrapper would put a
+ * `<div>` between them that they then have to style around.
+ */
+export component DatePickerRoot(
+  children: React.Node,
+  defaultOpen?: boolean = false,
+  defaultValue?: DateValue | null = null,
+  /** How a chosen date is written into the field. ISO 8601 unless told otherwise. */
+  format?: (date: PlainDate) => string = isoFormat,
+  isDateDisabled?: (date: PlainDate) => boolean,
+  locale?: string,
+  onOpenChange?: (open: boolean) => void,
+  onValueChange?: (value: PlainDate | null) => mixed,
+  open?: boolean,
+  /** How typed text becomes a date, or null when it is not one yet. */
+  parse?: (text: string) => PlainDate | null = isoParse,
+  today?: DateValue,
+  value?: DateValue | null,
+  weekStartsOn?: number,
+) {
+  const fieldRef = useRef<HTMLElement | null>(null);
+  const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
+
+  const controlled = useMemo(
+    () =>
+      value === undefined ? undefined : value === null ? null : Temporal.PlainDate.from(value),
+    [value],
+  );
+  const initial = useMemo(
+    () => (defaultValue == null ? null : Temporal.PlainDate.from(defaultValue)),
+    [defaultValue],
+  );
+  const report = useStableCallback((next: PlainDate | null) => {
+    onValueChange?.(next);
+  });
+  const [chosen, setChosen] = useControlled<PlainDate | null>(controlled, initial, report);
+
+  // The field's text is the *draft* while there is one, and the formatted value
+  // otherwise. Two pieces of state kept in step by an effect is the arrangement
+  // this avoids: an effect that copies the value into the field overwrites what
+  // the reader is halfway through typing, and one that does not runs stale the
+  // moment the caller sets a value from outside.
+  const [draft, setDraft] = useState<string | null>(null);
+  const [invalid, setInvalid] = useState(false);
+  const text = draft ?? (chosen == null ? "" : format(chosen));
+
+  const focusField = useStableCallback(() => {
+    fieldRef.current?.focus?.();
+  });
+
+  const commit = useStableCallback((typed: string) => {
+    if (typed.trim() === "") {
+      setChosen(null);
+      setDraft(null);
+      setInvalid(false);
+      return;
+    }
+    const parsed = parse(typed);
+    if (parsed == null) {
+      // The text stays. Clearing it would throw away what the reader typed and
+      // leave them nothing to correct.
+      setInvalid(true);
+      return;
+    }
+    setChosen(parsed);
+    setDraft(null);
+    setInvalid(false);
+  });
+
+  const choose = useStableCallback((date: PlainDate) => {
+    setChosen(date);
+    setDraft(null);
+    setInvalid(false);
+    // Before the popover closes, and that order is load-bearing: `Popover.Body`
+    // restores focus to its trigger only when focus would otherwise be lost, so
+    // moving it to the field first is what makes the field - and not the button
+    // - where the reader ends up.
+    focusField();
+    setOpen(false);
+  });
+
+  const dateSettings = useMemo(
+    () => ({ isDateDisabled, locale, today, weekStartsOn }),
+    [isDateDisabled, locale, today, weekStartsOn],
+  );
+
+  const state = useMemo(
+    () => ({
+      choose,
+      commit,
+      fieldRef,
+      focusField,
+      invalid,
+      setDraft,
+      text,
+      value: chosen,
+    }),
+    [choose, chosen, commit, focusField, invalid, text],
+  );
+
+  return (
+    <DatePickerContext.Provider value={state}>
+      <CalendarSettings.Provider value={dateSettings}>
+        <PopoverRoot onOpenChange={setOpen} open={isOpen}>
+          {children}
+        </PopoverRoot>
+      </CalendarSettings.Provider>
+    </DatePickerContext.Provider>
+  );
+}
+
+/** What `DatePicker.Root` was told about dates, for the calendar it renders. */
+type CalendarSettingsValue = {|
+  readonly isDateDisabled: ((date: PlainDate) => boolean) | void,
+  readonly locale: string | void,
+  readonly today: DateValue | void,
+  readonly weekStartsOn: number | void,
+|};
+
+const CalendarSettings: React.Context<CalendarSettingsValue> = createContext({
+  isDateDisabled: undefined,
+  locale: undefined,
+  today: undefined,
+  weekStartsOn: undefined,
+});
+
+/**
+ * The text field, which is the control.
+ *
+ * An ordinary `<input type="text">` rather than `type="date"`: the native one is
+ * a different widget with its own popup, its own format and no way to be told
+ * which dates are unavailable, and wrapping it would leave two calendars in one
+ * control. It carries no `role`, no `aria-haspopup` and no `aria-expanded` — it
+ * does not open the popover, the button beside it does, and telling a reader the
+ * field expands something would be a promise the field does not keep.
+ */
+export component DatePickerInput(...rest: Rest) {
+  const picker = useDatePicker("DatePicker.Input");
+  const passed = withoutComposed(rest, ["onBlur", "onChange", "onKeyDown", "ref"]);
+
+  return (
+    <input
+      {...passed}
+      aria-invalid={picker.invalid ? "true" : undefined}
+      onBlur={composeHandlers(rest.onBlur, (event) => {
+        picker.commit((event.currentTarget: $FlowFixMe).value);
+      })}
+      onChange={composeHandlers(rest.onChange, (event) => {
+        picker.setDraft((event.currentTarget: $FlowFixMe).value);
+      })}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        if (event.key !== "Enter") {
+          return;
+        }
+        // Claimed, so a date picker inside a form is not a control where
+        // pressing Enter to confirm what you typed submits the page instead.
+        event.preventDefault();
+        picker.commit((event.currentTarget: $FlowFixMe).value);
+      })}
+      ref={composeRefs(rest.ref, (element) => {
+        picker.fieldRef.current = element;
+      })}
+      type="text"
+      value={picker.text}
+    />
+  );
+}
+
+/** The button that opens the calendar. */
+export component DatePickerTrigger(children: React.Node, ...rest: Rest) {
+  // `forwarded`, because this part renders another part rather than an
+  // intrinsic; `internal/merge-props.js` says what that costs and why.
+  return <PopoverTrigger {...forwarded(rest)}>{children}</PopoverTrigger>;
+}
+
+/**
+ * The calendar, in the popover, wired to the field.
+ *
+ * `children` is the calendar's own layout — the month buttons and
+ * `Calendar.Month` — because where those sit is a design decision and there is
+ * no arrangement of them this module could impose that would suit every one.
+ */
+export component DatePickerCalendar(
+  children: React.Node,
+  align?: Align = "start",
+  side?: LogicalSide = "bottom",
+  sideOffset?: number = 0,
+  ...rest: Rest
+) {
+  const picker = useDatePicker("DatePicker.Calendar");
+  const settings = useContext(CalendarSettings);
+  const dayRef = useRef<HTMLElement | null>(null);
+  const passed = withoutComposed(rest, ["onKeyDown"]);
+
+  return (
+    <PopoverBody
+      {...forwarded(passed)}
+      align={align}
+      // The date, not the first button in the popover. The APG's date picker
+      // dialog puts focus on the grid for the same reason.
+      initialFocus={dayRef}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        if (event.key !== "Escape") {
+          return;
+        }
+        // Not prevented and not stopped: `Popover.Body`'s own handler is what
+        // closes it, and this only decides where focus lands afterwards. Moving
+        // it to the field first is what makes the popover's restore stand down;
+        // `choose` says why that is the order.
+        picker.focusField();
+      })}
+      side={side}
+      sideOffset={sideOffset}
+    >
+      <CalendarRoot
+        defaultFocused={picker.value ?? undefined}
+        focusedDayRef={dayRef}
+        isDateDisabled={settings.isDateDisabled}
+        locale={settings.locale}
+        onValueChange={picker.choose}
+        today={settings.today}
+        value={picker.value}
+        weekStartsOn={settings.weekStartsOn}
+      >
+        {children}
+      </CalendarRoot>
+    </PopoverBody>
+  );
+}

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
 ) {