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

package/index.js

@@ -99,8 +99,9 @@
 //   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.
+// - `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.
@@ -182,10 +183,19 @@ import {
   CarouselPrevious,
   CarouselRoot,
 } from "./carousel.js";
+import {
+  CalendarDay,
+  CalendarMonth,
+  CalendarNext,
+  CalendarPrevious,
+  CalendarRoot,
+} from "./calendar.js";
 import { Checkbox } from "./checkbox.js";
 import { CollapsibleContent, CollapsibleRoot, CollapsibleTrigger } from "./collapsible.js";
 import {
   ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxGroupLabel,
   ComboboxInput,
   ComboboxLabel,
   ComboboxList,
@@ -193,6 +203,12 @@ import {
   ComboboxRoot,
   ComboboxStatus,
 } from "./combobox.js";
+import {
+  DatePickerCalendar,
+  DatePickerInput,
+  DatePickerRoot,
+  DatePickerTrigger,
+} from "./date-picker.js";
 import {
   DialogBody,
   DialogClose,
@@ -312,6 +328,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 +343,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";
@@ -755,13 +777,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 +797,8 @@ export const Combobox = {
   Input: ComboboxInput,
   List: ComboboxList,
   Option: ComboboxOption,
+  Group: ComboboxGroup,
+  GroupLabel: ComboboxGroupLabel,
   Empty: ComboboxEmpty,
   Status: ComboboxStatus,
 };
@@ -837,6 +867,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.
  *

package/internal/anchor.js

@@ -108,6 +108,19 @@ import { directionOf } from "./roving-focus.js";
  */
 export type Side = "top" | "right" | "bottom" | "left";
 
+/**
+ * A side a caller may ask for, which is the four above plus the two that mean
+ * "the way the reader reads".
+ *
+ * The WAI-ARIA menu pattern puts a submenu on the inline end - to the right of a
+ * left-to-right menu and to the left of a right-to-left one - and `menu.js`
+ * already spells the *keys* that way, so a physical-only `side` would have left
+ * one half of that pattern mirrored and the other half not. `Placement` and
+ * `placeOverlay` stay physical: a logical side is resolved once, against the
+ * trigger's own direction, before any arithmetic sees it.
+ */
+export type LogicalSide = Side | "inline-start" | "inline-end";
+
 /**
  * Where the overlay sits along the trigger's other axis.
  *
@@ -173,7 +186,8 @@ export type AnchorRequest = {|
   readonly overlayRef: { current: HTMLElement | null },
   /** Nothing is measured while it is closed: there is nothing to measure. */
   readonly open: boolean,
-  readonly side: Side,
+  /** Resolved against the trigger's writing direction; see `LogicalSide`. */
+  readonly side: LogicalSide,
   readonly align: Align,
   readonly sideOffset: number,
   readonly alignOffset: number,
@@ -189,6 +203,28 @@ const OPPOSITE: { readonly [Side]: Side } = {
   right: "left",
 };
 
+/**
+ * The side on the screen that `side` names for a reader reading `direction`.
+ *
+ * The four physical ones pass through unchanged, because a design that puts a
+ * popover to the right of a toolbar means the right of the toolbar in Arabic
+ * too; `Side`'s own documentation says why that is the useful default and why
+ * alignment is the axis that mirrors.
+ */
+export function physicalSide(side: LogicalSide, direction: Direction): Side {
+  // Written out rather than left to a wildcard, so that a sixth side added to
+  // `LogicalSide` one day is a checker error here instead of a value that falls
+  // through unresolved.
+  return match (side) {
+    "inline-start" => direction === "rtl" ? "right" : "left",
+    "inline-end" => direction === "rtl" ? "left" : "right",
+    "top" => "top",
+    "right" => "right",
+    "bottom" => "bottom",
+    "left" => "left",
+  };
+}
+
 /** Whether a side stacks the overlay above the trigger or beside it. */
 function isVertical(side: Side): boolean {
   return side === "top" || side === "bottom";
@@ -396,7 +432,12 @@ export hook useAnchor(request: AnchorRequest): Anchored {
     side,
     sideOffset,
   } = request;
-  const [settled, setSettled] = useState<Anchored>({ align, side });
+  // 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
+  // commit later, exactly as a flip does, and for the same reason: the direction
+  // is a fact about the document, and a render may not read one.
+  const [settled, setSettled] = useState<Anchored>({ align, side: physicalSide(side, "ltr") });
 
   const reflow = useStableCallback(() => {
     const anchor = anchorRef.current;
@@ -414,7 +455,7 @@ export hook useAnchor(request: AnchorRequest): Anchored {
       collisionPadding,
       direction: directionOf(anchor),
       overlay: rectOf(overlay),
-      side,
+      side: physicalSide(side, directionOf(anchor)),
       sideOffset,
       // The viewport of a fixed element, which is the whole of it: a fixed box
       // is positioned against the viewport rather than against whatever is
@@ -443,8 +484,9 @@ export hook useAnchor(request: AnchorRequest): Anchored {
       // drawn from `data-side` pointing the wrong way, after a reopen that
       // follows a flip.
       if (!open) {
+        const asked = physicalSide(side, anchor == null ? "ltr" : directionOf(anchor));
         setSettled((current) =>
-          current.side === side && current.align === align ? current : { align, side },
+          current.side === asked && current.align === align ? current : { align, side: asked },
         );
       }
       return;
@@ -496,5 +538,5 @@ export hook useAnchor(request: AnchorRequest): Anchored {
   // first commit — and the server's markup, which measures nothing at all —
   // says the requested side rather than the last one some other opening
   // happened to settle on.
-  return open ? settled : { align, side };
+  return open ? settled : { align, side: physicalSide(side, "ltr") };
 }

package/internal/date-grid.js

@@ -0,0 +1,260 @@
+// @flow
+//
+// The month a calendar shows, and the keyboard that walks it.
+//
+// # Why this is not `roving-focus.js`
+//
+// A date grid is a roving tab stop — one stop in the page's tab order, arrow
+// keys inside it — so most of `internal/roving-focus.js` applies and the
+// calendar uses it: `directionOf` for a right-to-left week, `isEnabled` nowhere,
+// and the same rule about reading the document rather than a registry. What does
+// not fit is the part that does the moving, and it does not fit for four
+// reasons rather than one:
+//
+//   * **The movement is arithmetic on a date, not an index in a NodeList.**
+//     `moveTo` walks the items it was handed. `ArrowDown` in a calendar is "a
+//     week later", and a week later is often a cell that is not in the grid at
+//     all yet — so the answer cannot be found among the elements, and a
+//     `movementFor` grown to two axes would still return "next" for a key whose
+//     real meaning is `+7 days`.
+//   * **Running off the end changes what is rendered.** `ArrowRight` on the 31st
+//     shows the next month *and* leaves focus on the 1st, which is a cell that
+//     did not exist when the key was pressed. That is a `pendingFocus` problem,
+//     the same shape `Menu.Body` solves for a menu opening onto its last item,
+//     and it is why the movement is computed as a value the component can act on
+//     over two renders rather than as a `.focus()` inside a helper.
+//   * **An unavailable date stays focusable.** `moveTo` skips anything
+//     `isEnabled` rejects, which is right for a menu item and wrong here: a
+//     reader arrowing through October has to be able to pass over the days that
+//     cannot be booked, each `aria-disabled="true"` and each still reachable. A
+//     grid that skipped them would present a month with holes in it and no way
+//     to find out what is in the holes.
+//   * **There is no wrap, and no ends.** A list has a first and a last item.
+//     A calendar has neither: every direction leads to another month.
+//
+// So the two primitives stay apart, and the boundary is that one owns *focus
+// among elements that exist* and this one owns *which date the keyboard means*.
+// Everything below is a pure function over `PlainDate` values: no element, no
+// React, no document. That is deliberate for the same reason
+// `internal/anchor.js` keeps `placeOverlay` pure — the month-boundary cases are
+// the ones worth testing exhaustively, and testing them through a rendered grid
+// would test the renderer instead.
+//
+// # Dates come from Temporal, and from `@uniflowed/core/temporal` in particular
+//
+// Not `Date`. A package that ships a temporal library and then computes a month
+// length with `new Date(y, m + 1, 0)` is the opposite of what "build uf with uf"
+// asks for, and `Date`'s month-is-zero-based, mutates-in-place, local-timezone
+// arithmetic is where calendar bugs come from in the first place.
+//
+// The specifier is `@uniflowed/core/temporal` rather than `@uniflowed/temporal`,
+// which is the same object — `packages/temporal/index.js` is a re-export and
+// says so. It has to be that one: `@uniflowed/ui` is published to npm,
+// `@uniflowed/temporal` is not yet (its calendar surface waits on the native
+// runtime), and `tools/ci/publishable.sh` refuses a published package that
+// depends on an unpublished one because `npm install` would answer `ETARGET`.
+// When the name is published this import can move, and nothing else changes.
+
+import type { PlainDate } from "@uniflowed/core/temporal";
+import { Temporal } from "@uniflowed/core/temporal";
+
+import type { Direction } from "./roving-focus.js";
+
+/**
+ * ISO 8601's first day of the week, which is Monday.
+ *
+ * The fallback when nothing better is known, and deliberately not Sunday: ISO is
+ * the standard the rest of this package's date handling follows, and a default
+ * that matched one large locale would be a guess dressed as a convention.
+ */
+export const ISO_WEEK_START: number = 1;
+
+/** Days in a week, which is the width of every grid here. */
+export const DAYS_IN_WEEK: number = 7;
+
+/**
+ * What a key asks the focused date to become.
+ *
+ * A value rather than a new date, because the component that acts on it has to
+ * do two things with the answer — move the focus and possibly re-render a
+ * different month — and because "PageDown means a month" is the part worth
+ * asserting on its own.
+ */
+export type DateMovement =
+  | {| readonly kind: "days", readonly by: number |}
+  | {| readonly kind: "months", readonly by: number |}
+  | {| readonly kind: "years", readonly by: number |}
+  | {| readonly kind: "week-edge", readonly to: "start" | "end" |};
+
+/** The part of a key event a grid reads. */
+export type DateKeyPress = {
+  readonly key: string,
+  readonly shiftKey?: boolean,
+  ...
+};
+
+/**
+ * The movement a key asks for, or null when the key is not the grid's.
+ *
+ * The unhandled keys matter as much as the handled ones, for the reason
+ * `movementFor` gives: `Tab` belongs to the page and `Escape` belongs to
+ * whatever the calendar is inside, and a grid that swallowed either would be a
+ * place a reader could not leave.
+ *
+ * `direction` mirrors the horizontal pair and nothing else. `ArrowDown` is a
+ * week later in an Arabic calendar exactly as in an English one — a
+ * right-to-left page still runs top to bottom — and `Home` and `End` name the
+ * first and last day of the week in *reading* order, which is what
+ * `weekEdge` walks.
+ *
+ * `Shift` turns the two page keys into years, which is the one keyboard
+ * convention here that a reader cannot discover by trying: it is in the
+ * WAI-ARIA date-picker pattern, every native date field has it, and a year is
+ * otherwise twelve `PageDown` presses.
+ */
+export function movementForDateKey(event: DateKeyPress, direction: Direction): DateMovement | null {
+  const forward = direction === "rtl" ? -1 : 1;
+  const pages = event.shiftKey === true ? 12 : 1;
+  return match (event.key) {
+    "ArrowRight" => { kind: "days", by: forward },
+    "ArrowLeft" => { kind: "days", by: -forward },
+    "ArrowDown" => { kind: "days", by: DAYS_IN_WEEK },
+    "ArrowUp" => { kind: "days", by: -DAYS_IN_WEEK },
+    "Home" => { kind: "week-edge", to: "start" },
+    "End" => { kind: "week-edge", to: "end" },
+    // A year is twelve months rather than `{ years: 1 }`, so that the day is
+    // clamped once by the same rule the month keys use: the 29th of February
+    // plus a year is the 28th, and adding a year to a month-clamped date and
+    // adding twelve months have to agree or `Shift+PageDown` twice would not
+    // equal `PageDown` twenty-four times.
+    "PageUp" => { kind: "months", by: -pages },
+    "PageDown" => { kind: "months", by: pages },
+    _ => null,
+  };
+}
+
+/**
+ * How far into its week `date` sits, counting from `weekStartsOn`.
+ *
+ * Zero for the first column, six for the last, in whichever order the week is
+ * laid out. Both `weekEdge` and the grid's leading blanks are this number.
+ */
+export function columnOf(date: PlainDate, weekStartsOn: number): number {
+  return (date.dayOfWeek - weekStartsOn + DAYS_IN_WEEK) % DAYS_IN_WEEK;
+}
+
+/** The first or the last day of `date`'s week, as this locale lays a week out. */
+export function weekEdge(date: PlainDate, weekStartsOn: number, to: "start" | "end"): PlainDate {
+  const into = columnOf(date, weekStartsOn);
+  return to === "start"
+    ? date.subtract({ days: into })
+    : date.add({ days: DAYS_IN_WEEK - 1 - into });
+}
+
+/**
+ * The date `movement` reaches from `from`.
+ *
+ * Nothing here refuses: a movement onto an unavailable date, into a month with
+ * nothing selectable in it, or past whatever range the caller allows still
+ * returns that date. Refusing is the component's decision and it makes a
+ * different one — the module header says why a reader has to be able to walk
+ * over an unavailable day rather than around it.
+ *
+ * The month and year movements clamp the day, because `PlainDate.add` does: the
+ * 31st of January plus a month is the 28th of February rather than the 3rd of
+ * March, which is Temporal's `constrain` overflow and what a person means by
+ * "next month".
+ */
+export function moveDate(from: PlainDate, movement: DateMovement, weekStartsOn: number): PlainDate {
+  return match (movement) {
+    {kind: "days", by: const by} => from.add({ days: by }),
+    {kind: "months", by: const by} => from.add({ months: by }),
+    {kind: "years", by: const by} => from.add({ years: by }),
+    {kind: "week-edge", to: const to} => weekEdge(from, weekStartsOn, to),
+  };
+}
+
+/**
+ * The rows of one month, seven cells wide, with `null` where no day falls.
+ *
+ * The blanks are blanks rather than the neighbouring months' days, and that is
+ * the decision the rest of the keyboard behaviour rests on. A grid that showed
+ * the 1st of November inside October's would have two cells that mean the same
+ * date whenever a reader moved between them, and the WAI-ARIA pattern's
+ * promise — that `ArrowRight` off the end of the month *changes the month* — has
+ * nowhere to happen. Every blank is a `<td>` with no `gridcell` role, so the
+ * rows stay rectangular for a screen reader counting columns.
+ */
+export function weeksOf(
+  year: number,
+  month: number,
+  weekStartsOn: number,
+): $ReadOnlyArray<$ReadOnlyArray<PlainDate | null>> {
+  const first = Temporal.PlainDate.from({ day: 1, month, year });
+  const blanks = columnOf(first, weekStartsOn);
+  const days = first.daysInMonth;
+  const rows = Math.ceil((blanks + days) / DAYS_IN_WEEK);
+
+  const weeks = [];
+  for (let row = 0; row < rows; row += 1) {
+    const week = [];
+    for (let column = 0; column < DAYS_IN_WEEK; column += 1) {
+      const day = row * DAYS_IN_WEEK + column - blanks + 1;
+      week.push(day >= 1 && day <= days ? first.add({ days: day - 1 }) : null);
+    }
+    weeks.push(week);
+  }
+  return weeks;
+}
+
+/**
+ * Seven dates, one per column, for naming the columns.
+ *
+ * Dates rather than strings, because the names are the locale's and
+ * `PlainDate.toLocaleString` is where a locale's day names live. Any week would
+ * do; this one starts on a Monday so that `weekStartsOn` indexes it directly.
+ */
+export function weekdaysFrom(weekStartsOn: number): $ReadOnlyArray<PlainDate> {
+  const monday = Temporal.PlainDate.from("2024-01-01");
+  const days = [];
+  for (let column = 0; column < DAYS_IN_WEEK; column += 1) {
+    days.push(monday.add({ days: weekStartsOn - ISO_WEEK_START + column }));
+  }
+  return days;
+}
+
+/** Whether two dates are in the same month of the same year. */
+export function sameMonth(a: PlainDate, b: PlainDate): boolean {
+  return a.year === b.year && a.month === b.month;
+}
+
+/**
+ * The day `locale` starts its weeks on, in ISO numbering.
+ *
+ * `Intl.Locale.prototype.getWeekInfo` is the answer the platform has, and its
+ * `firstDay` is already ISO-numbered, so no translation is needed. Everything
+ * around the call is defence rather than logic: Flow's vendored `intl.js`
+ * declares no `Locale` at all, the method is newer than the class on some hosts,
+ * and a locale tag that is merely *malformed* throws where an unknown one does
+ * not. Each of those ends at ISO Monday, which is a defensible week rather than
+ * a broken one.
+ *
+ * The cast is the narrowest available: one property read off `Intl`, for a class
+ * the checker has never heard of. Widening it to the return value would hide
+ * whether `firstDay` was a number at all, which is why that is asked separately.
+ */
+export function firstDayOfWeekFor(locale: string | void): number {
+  const factory = (Intl as $FlowFixMe).Locale;
+  if (typeof factory !== "function") {
+    return ISO_WEEK_START;
+  }
+  try {
+    const info = new factory(locale ?? "und").getWeekInfo?.();
+    const first = info?.firstDay;
+    return typeof first === "number" && first >= 1 && first <= DAYS_IN_WEEK
+      ? first
+      : ISO_WEEK_START;
+  } catch {
+    return ISO_WEEK_START;
+  }
+}

package/menu.js

@@ -39,6 +39,23 @@
 // were aiming at. Keyboard and click open a submenu; a deliberate hover
 // implementation is tracked work, not a line to be added carelessly.
 //
+// # Where the menu goes
+//
+// `internal/anchor.js`, the same module `Popover.Body` uses, and adopting it
+// here rather than writing a second one is most of ubugeeei-prod/uf#256. Two
+// things about a menu were wrong before it and are worth naming, because
+// neither looks like a positioning bug:
+//
+//   * A menu in a table row, a card, or anything else with `overflow: hidden`
+//     was cut off at that box's edge. It is `position: fixed` now, so the
+//     clipping ancestor is not its business.
+//   * A menu whose trigger sat near the bottom of the page opened downwards,
+//     off the screen, and the reader saw nothing at all.
+//
+// A submenu asks for `side="inline-end"` rather than `right`, which is the same
+// answer `submenuKeys` gives about the *keys*: the submenu opens the way the
+// page reads, and the arrow that opens it points at where it went.
+//
 // # Items are found in the document, not in a registry
 //
 // `internal/roving-focus.js` explains why. The short version is that mount
@@ -59,6 +76,8 @@ 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 {
@@ -73,6 +92,8 @@ import {
 import { useControlled } from "./internal/controlled-state.js";
 import type { Direction } from "./internal/roving-focus.js";
 
+export type { Align, LogicalSide, Side } from "./internal/anchor.js";
+
 /**
  * Anything that plays the part of a menu item, including the two checkable
  * kinds a caller may write themselves. The keyboard has to move between all of
@@ -328,6 +349,12 @@ export component MenuTrigger(children: React.Node, ...rest: Rest) {
  */
 export component MenuBody(
   children: renders* (MenuItem | MenuSeparator | MenuGroup | MenuSub),
+  align?: Align = "start",
+  alignOffset?: number = 0,
+  avoidCollisions?: boolean = true,
+  collisionPadding?: number = 0,
+  side?: LogicalSide,
+  sideOffset?: number = 0,
   ...rest: Rest
 ) {
   const menu = useMenu("Menu.Body");
@@ -343,6 +370,22 @@ export component MenuBody(
   const pendingFocus = menu.pendingFocus;
   const isRoot = menu.parent == null;
   const closeAll = useStableCallback(() => closeTree(menu));
+  // A root menu drops from its button; a submenu comes out of the side of the
+  // item that opened it, on the side the page reads towards. The default cannot
+  // be a parameter default because it is not a constant: it is the answer to
+  // "is this the outermost menu", which only this component knows.
+  const placement = side ?? (isRoot ? "bottom" : "inline-end");
+  const anchored = useAnchor({
+    align,
+    alignOffset,
+    anchorRef: triggerRef,
+    avoidCollisions,
+    collisionPadding,
+    open: menu.open,
+    overlayRef: bodyRef,
+    side: placement,
+    sideOffset,
+  });
   // Set when the menu was dismissed by a press somewhere else, so the cleanup
   // knows not to drag focus back to the trigger the reader just left.
   const dismissed = useRef(false);
@@ -418,6 +461,8 @@ export component MenuBody(
         {...passed}
         aria-labelledby={menu.triggered ? `${menu.base}-trigger` : undefined}
         aria-orientation="vertical"
+        data-align={anchored.align}
+        data-side={anchored.side}
         id={`${menu.base}-body`}
         onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
           const body: $FlowFixMe = event.currentTarget;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/ui",
-  "version": "0.0.0-alpha.12",
+  "version": "0.0.0-alpha.13",
   "description": "Headless, accessible React components whose composition Flow checks, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -14,10 +14,12 @@
     ".": "./index.js",
     "./accordion": "./accordion.js",
     "./alert-dialog": "./alert-dialog.js",
+    "./calendar": "./calendar.js",
     "./carousel": "./carousel.js",
     "./checkbox": "./checkbox.js",
     "./collapsible": "./collapsible.js",
     "./combobox": "./combobox.js",
+    "./date-picker": "./date-picker.js",
     "./dialog": "./dialog.js",
     "./drawer": "./drawer.js",
     "./field": "./field.js",
@@ -48,8 +50,9 @@
     "internal"
   ],
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.12",
-    "@uniflowed/react": "0.0.0-alpha.12"
+    "@uniflowed/core": "0.0.0-alpha.13",
+    "@uniflowed/hooks": "0.0.0-alpha.13",
+    "@uniflowed/react": "0.0.0-alpha.13"
   },
   "peerDependencies": {
     "react": ">=19"