@uniflowed/ui 0.0.0-alpha.2 → 0.0.0-alpha.37

package/menubar.js

@@ -0,0 +1,287 @@
+// @flow
+//
+// A row of menus that behaves as one control: File, Edit, View.
+//
+// It is not a row of `Menu.Root`s, and the reason is that the *set* has a
+// keyboard map of its own — one that only exists because the menus are next to
+// each other:
+//
+//   * The whole bar takes **one** stop in the page's tab order, so `Tab` past an
+//     application menu is one press rather than six.
+//   * `ArrowLeft` / `ArrowRight` move between the top-level menus, mirrored in a
+//     right-to-left page because they are the inline axis.
+//   * `ArrowDown` opens the menu under the cursor and lands on its first item;
+//     `ArrowUp` opens it onto its last, which is the same argument `Menu.Trigger`
+//     makes about the destructive command at the bottom of a long menu.
+//   * `Home` / `End` go to the first and last menu.
+//   * And the part that is always missing: `ArrowLeft` / `ArrowRight` **while a
+//     menu is open** close it and open the adjacent one, so a reader can walk
+//     File → Edit → View without pressing `Escape` between them. A menubar
+//     without it makes the arrow keys mean two different things depending on
+//     whether a menu happens to be showing.
+//   * `Escape` closes the open menu and leaves focus on its trigger, in the bar,
+//     which `Menu.Body` already does — a menubar trigger is the menu's trigger.
+//
+// Everything inside a menu is `menu.js`: the arrow keys within it, typeahead,
+// submenus, the checkable items and the roving tab stop of the menu itself.
+// `Menubar.Body` is `Menu.Body` itself rather than a wrapper around it, because
+// a bar's menu *is* a root menu — it hangs off a button and drops from it — and
+// `Menu.Body` already places a root menu on the bottom, aligned to the start. A
+// wrapper would have been a second component with the same defaults written out
+// again, and a second place for them to drift.
+//
+// # How the bar finds its own triggers
+//
+// `internal/roving-focus.js`'s `itemsOf(container, item, owner)` takes the owner
+// selector as a parameter for exactly this: a set says what owns it. A menu
+// passes `[role="menu"]`, and a menubar has to pass **both** — an open menu is a
+// DOM descendant of the bar, and its items are `role="menuitem"` too, so a bar
+// that only asked "menu items inside me" would step into the open menu's items
+// with `ArrowRight`. Naming the two owners makes `closest` stop at the menu for
+// an item inside one and at the bar for a trigger, which is the distinction, and
+// it is settled by the roles the two containers already carry.
+//
+// Turning a trigger *element* back into the menu it opens is the one thing the
+// roles cannot say, and `data-uf-menubar-value` is that and nothing more. The
+// alternative is a registry of refs, which `roving-focus.js` explains at length
+// is a second opinion about document order.
+//
+// # Which menu is open is the bar's state
+//
+// One value, `string | null`, rather than a boolean per menu. Two menus open at
+// once is the state this component exists to prevent, and a per-menu boolean is
+// a set of booleans somebody has to keep exclusive; `accordion.js` makes the
+// same argument about `single`. It is also what makes "close this one and open
+// the next" a single assignment rather than a pair of them that render twice.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+
+import type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  withProps,
+  withoutComposed,
+} from "./internal/merge-props.js";
+import type { RovingSet } from "./internal/roving-focus.js";
+import {
+  directionOf,
+  indexOfActive,
+  itemsOf,
+  movementFor,
+  moveTo,
+  useFirstItem,
+} from "./internal/roving-focus.js";
+import { MenuLevel, useMenu } from "./internal/menu-tree.js";
+
+/**
+ * The bar's own items, and the two things that may own one.
+ *
+ * See the module header: an open menu is inside the bar and its items wear the
+ * same role, so the owner selector names both and `closest` settles it.
+ */
+const TRIGGERS: RovingSet = {
+  item: '[role="menuitem"]',
+  owner: '[role="menu"], [role="menubar"]',
+  orientation: "horizontal",
+  wrap: true,
+  skipDisabled: true,
+};
+
+type MenubarState = {|
+  /** Which menu is showing, by the `value` its `Menubar.Menu` was given. */
+  readonly open: string | null,
+  readonly setOpen: (value: string | null) => void,
+  /** Which trigger holds the bar's single tab stop, or null for "the first". */
+  readonly active: string | null,
+  readonly setActive: (value: string) => void,
+  readonly firstId: string | null,
+|};
+
+const MenubarContext: React.Context<MenubarState | null> = createContext(null);
+
+/** The `value` of the `Menubar.Menu` a trigger belongs to. */
+const MenubarMenuContext: React.Context<string | null> = createContext(null);
+
+hook useMenubar(part: string): MenubarState {
+  const state = useContext(MenubarContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Menubar.Root`);
+  }
+  return state;
+}
+
+/**
+ * The bar: `role="menubar"`, one tab stop, and the arrows between the menus.
+ *
+ * `aria-label` is the caller's and matters more here than on most containers —
+ * a page with an application menubar and a formatting toolbar has two, and
+ * "menu bar" twice tells a reader nothing about which is which.
+ */
+export component MenubarRoot(children: renders* MenubarMenu, render?: RenderProp, ...rest: Rest) {
+  const barRef = useRef<HTMLElement | null>(null);
+  const [open, setOpenValue] = useState<string | null>(null);
+  const [active, setActive] = useState<string | null>(null);
+  // Only while nothing has been focused or opened. Once a trigger holds the tab
+  // stop, asking the document which one comes first is work with no reader.
+  const firstId = useFirstItem(barRef, TRIGGERS, active == null);
+
+  const setOpen = useCallback((value: string | null) => {
+    setOpenValue(value);
+    if (value != null) {
+      setActive(value);
+    }
+  }, []);
+
+  const state = useMemo(
+    () => ({ open, setOpen, active, setActive, firstId }),
+    [open, setOpen, active, firstId],
+  );
+  const props = withProps(withoutComposed(rest, ["onKeyDown", "ref"]), {
+    "aria-orientation": "horizontal",
+    children,
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      const bar: $FlowFixMe = event.currentTarget;
+      const movement = movementFor(event.key, "horizontal", directionOf(bar));
+      if (movement == null) {
+        return;
+      }
+      const triggers = itemsOf(bar, TRIGGERS.item, TRIGGERS.owner);
+      // With a menu open, focus is on one of *its* items rather than on a
+      // trigger, so "where am I in the bar" is the expanded trigger. This
+      // is the whole of walking File → Edit → View without pressing Escape.
+      const focused = indexOfActive(triggers, bar.ownerDocument?.activeElement);
+      const at =
+        focused >= 0
+          ? focused
+          : triggers.findIndex((each) => each.getAttribute("aria-expanded") === "true");
+      const next = moveTo(triggers, at, movement, TRIGGERS.wrap, TRIGGERS.skipDisabled);
+      if (next == null) {
+        return;
+      }
+      // Claimed before focus moves, or the browser scrolls the page under
+      // the trigger that has just taken it; `moveOnKey` says the same.
+      event.preventDefault();
+      event.stopPropagation();
+      const value = next.getAttribute("data-uf-menubar-value");
+      if (open != null && value != null) {
+        // Swap which menu is showing. Focus lands on the new menu's first
+        // item through `Menu.Body`'s own opening effect, so nothing here
+        // moves it: focusing the trigger as well would be two focus moves
+        // in one commit and the reader would see the second.
+        setOpen(value);
+        return;
+      }
+      next.focus();
+      if (value != null) {
+        setActive(value);
+      }
+    }),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      barRef.current = element;
+    }),
+    role: "menubar",
+  });
+
+  return (
+    <MenubarContext.Provider value={state}>
+      {render == null ? <div {...props} /> : render(props)}
+    </MenubarContext.Provider>
+  );
+}
+
+/**
+ * One menu of the bar, named by the `value` the bar opens and closes it with.
+ *
+ * Renders no element of its own, for the reason `Menu.Root` gives: a trigger and
+ * its body are siblings in whatever layout the caller wrote.
+ */
+export component MenubarMenu(children: React.Node, value: string) {
+  const bar = useMenubar("Menubar.Menu");
+  const setOpen = bar.setOpen;
+  const onOpenChange = useCallback(
+    (next: boolean) => setOpen(next ? value : null),
+    [setOpen, value],
+  );
+
+  return (
+    <MenubarMenuContext.Provider value={value}>
+      <MenuLevel
+        defaultOpen={false}
+        onOpenChange={onOpenChange}
+        open={bar.open === value}
+        parent={null}
+      >
+        {children}
+      </MenuLevel>
+    </MenubarMenuContext.Provider>
+  );
+}
+
+/**
+ * The button that opens one of the bar's menus.
+ *
+ * `role="menuitem"` rather than a plain button, because it *is* an item of the
+ * menubar — a reader is told "File, menu item, has popup, 1 of 3" — and it is
+ * what makes the bar's arrow keys agree with what they were told is in it.
+ */
+export component MenubarTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const bar = useMenubar("Menubar.Trigger");
+  const menu = useMenu("Menubar.Trigger");
+  const value = useContext(MenubarMenuContext);
+  if (value == null) {
+    throw new Error("Menubar.Trigger must be rendered inside a Menubar.Menu");
+  }
+  const id = `${menu.base}-trigger`;
+  // The bar's single tab stop. Before anything has been focused or opened it
+  // belongs to the first trigger, which is a fact about the document rather
+  // than about this component — `useFirstItem` reads it in the bar.
+  const stop = bar.active == null ? bar.firstId === id : bar.active === value;
+
+  const props = withProps(withoutComposed(rest, ["onClick", "onFocus", "onKeyDown", "ref"]), {
+    "aria-controls": menu.open ? `${menu.base}-body` : undefined,
+    "aria-expanded": menu.open ? "true" : "false",
+    "aria-haspopup": "menu",
+    children,
+    // How the bar's keyboard turns a trigger element back into the menu it
+    // opens; the module header says why this is an attribute and the rest of
+    // the bar's arithmetic is not.
+    "data-uf-menubar-value": value,
+    id,
+    onClick: composeHandlers(rest.onClick, () => bar.setOpen(menu.open ? null : value)),
+    onFocus: composeHandlers(rest.onFocus, () => bar.setActive(value)),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      const end = match (event.key) {
+        "ArrowDown" => "first",
+        "ArrowUp" => "last",
+        _ => null,
+      };
+      if (end == null) {
+        return;
+      }
+      event.preventDefault();
+      menu.pendingFocus.current = end;
+      bar.setOpen(value);
+    }),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      menu.triggerRef.current = element;
+    }),
+    role: "menuitem",
+    tabIndex: stop ? 0 : -1,
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
+}

package/navigation-menu.js

@@ -0,0 +1,251 @@
+// @flow
+//
+// Site navigation, which is not a menu.
+//
+// This component exists mostly to prevent one mistake, and the mistake is
+// reaching for `role="menu"` because the thing is called a navigation menu.
+// `menu`, `menubar` and `menuitem` are for *application commands* — Cut, Paste,
+// Export as PNG — and using them for a site's navigation costs a reader three
+// things at once:
+//
+//   * A screen reader announces "menu, five items" where the reader expected a
+//     list of links, and a list of links is a thing they know how to read.
+//   * The whole menu keyboard map comes with the role, and a reader who knows
+//     it will use it: `Tab` should leave the set in one press, arrow keys
+//     should move between items, typing a letter should jump. Claiming the role
+//     and not implementing the map is worse than not claiming it.
+//   * `menuitem` is not a link. It is not announced as one, it is not in the
+//     list of links a reader can pull up, and "open in a new tab" is not
+//     obviously available on it.
+//
+// The WAI-ARIA practices have a pattern for exactly this and it is the
+// *Disclosure Navigation Menu*: a `<nav>` containing a list, where an
+// expandable entry is a `button` with `aria-expanded` controlling a list of
+// ordinary links. Radix's NavigationMenu makes the same choice. So: `Tab` walks
+// the links, because they are links; `Escape` closes the open group and gives
+// focus back to the button that opened it; choosing a link closes the group,
+// because the reader is leaving.
+//
+// # One group open at a time
+//
+// Opening one closes the others, which is what the practices' example does and
+// what a site's navigation looks like everywhere. It is also why the root holds
+// which entry is open rather than each entry holding its own state: "the open
+// one" is a fact about the set.
+//
+// # The closed group is not rendered
+//
+// `accordion.js` keeps its closed panels in the document with
+// `hidden="until-found"` so that find-in-page can reach the text in them. This
+// deliberately does not, and the difference is what the content is *for*. An
+// accordion panel is prose a reader might be searching. A closed navigation
+// group is a list of destinations, and having Ctrl+F unfold the site's
+// navigation on the way to a word in the article would be a surprise with
+// nothing to show for it.
+//
+// # Name the landmark
+//
+// `<nav>` is a landmark, and a page with two unnamed ones gives a reader a
+// choice between "navigation" and "navigation". Pass `aria-label`.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useId, useMemo, useState } from "@uniflowed/react";
+
+import type { Rest } from "./internal/merge-props.js";
+import { composeHandlers, withoutComposed } from "./internal/merge-props.js";
+import { usePresence } from "./internal/disclosure.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+type NavigationMenuState = {|
+  /** The entry whose group is open, or null for none. */
+  readonly open: string | null,
+  readonly setOpen: (value: string | null) => void,
+|};
+
+const NavigationMenuContext: React.Context<NavigationMenuState | null> = createContext(null);
+
+type NavigationMenuItemState = {|
+  readonly triggerId: string,
+  readonly bodyId: string,
+  readonly expanded: boolean,
+  readonly toggle: () => void,
+  readonly close: () => void,
+  /** Whether a `NavigationMenu.Body` is rendered, so the trigger names one that exists. */
+  readonly present: boolean,
+  readonly registerBody: (present: boolean) => void,
+|};
+
+const NavigationMenuItemContext: React.Context<NavigationMenuItemState | null> =
+  createContext(null);
+
+hook useNavigationMenu(part: string): NavigationMenuState {
+  const state = useContext(NavigationMenuContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a NavigationMenu.Root`);
+  }
+  return state;
+}
+
+hook useNavigationMenuItem(part: string): NavigationMenuItemState {
+  const state = useContext(NavigationMenuItemContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a NavigationMenu.Item`);
+  }
+  return state;
+}
+
+/**
+ * The landmark, and the one place `Escape` is handled.
+ *
+ * `Escape` is here rather than on each group because the reader may be anywhere
+ * inside the open one when they press it, and because the button to give focus
+ * back to is found the same way everything else in this package finds things:
+ * by asking the document at the moment of the press. The alternative — every
+ * trigger writing itself into a ref — is a registry that has to be kept in step
+ * with a document that already knows the answer.
+ */
+export component NavigationMenuRoot(
+  children: renders* NavigationMenuList,
+  defaultValue?: string | null = null,
+  value?: string | null,
+  onValueChange?: (value: string | null) => void,
+  ...rest: Rest
+) {
+  const [open, setOpen] = useControlled<string | null>(value, defaultValue, onValueChange);
+  const state = useMemo(() => ({ open, setOpen }), [open, setOpen]);
+  const passed = withoutComposed(rest, ["onKeyDown"]);
+
+  return (
+    <NavigationMenuContext.Provider value={state}>
+      <nav
+        {...passed}
+        onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+          if (event.key !== "Escape" || open == null) {
+            return;
+          }
+          event.preventDefault();
+          // This navigation menu, not a dialog around it.
+          event.stopPropagation();
+          const nav: $FlowFixMe = event.currentTarget;
+          const trigger = nav.querySelector('[aria-expanded="true"]');
+          setOpen(null);
+          // After closing, and synchronously: the trigger is not the element
+          // being removed — the group inside it is — so it is still there to
+          // take focus, and leaving focus on a `<li>` that no longer contains
+          // anything focusable drops the reader at the top of the page.
+          trigger?.focus?.();
+        })}
+      >
+        {children}
+      </nav>
+    </NavigationMenuContext.Provider>
+  );
+}
+
+/** The list of entries. A `<ul>`, because a reader is told how many there are. */
+export component NavigationMenuList(children: renders* NavigationMenuItem, ...rest: Rest) {
+  useNavigationMenu("NavigationMenu.List");
+  return <ul {...rest}>{children}</ul>;
+}
+
+/** One entry: a link on its own, or a button and the group it opens. */
+export component NavigationMenuItem(value: string, children: React.Node, ...rest: Rest) {
+  const menu = useNavigationMenu("NavigationMenu.Item");
+  const base = useId();
+  const [present, setPresent] = useState(false);
+  const setOpen = menu.setOpen;
+  const expanded = menu.open === value;
+
+  const state = useMemo(
+    () => ({
+      triggerId: `${base}-trigger`,
+      bodyId: `${base}-body`,
+      expanded,
+      toggle: () => setOpen(expanded ? null : value),
+      close: () => setOpen(null),
+      present,
+      registerBody: setPresent,
+    }),
+    [base, expanded, setOpen, value, present],
+  );
+
+  return (
+    <NavigationMenuItemContext.Provider value={state}>
+      <li {...rest}>{children}</li>
+    </NavigationMenuItemContext.Provider>
+  );
+}
+
+/** The button that opens an entry's group. Not a `menuitem`; see the header. */
+export component NavigationMenuTrigger(children: React.Node, ...rest: Rest) {
+  const item = useNavigationMenuItem("NavigationMenu.Trigger");
+  const passed = withoutComposed(rest, ["onClick"]);
+
+  return (
+    <button
+      {...passed}
+      aria-controls={item.present ? item.bodyId : undefined}
+      aria-expanded={item.expanded ? "true" : "false"}
+      id={item.triggerId}
+      onClick={composeHandlers(rest.onClick, item.toggle)}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+/**
+ * The group of links an entry opens.
+ *
+ * Named after its trigger, so a reader who lands in it by `Tab` is told which
+ * entry they are inside rather than hearing an unnamed list of four links.
+ */
+export component NavigationMenuBody(children: renders* NavigationMenuLink, ...rest: Rest) {
+  const item = useNavigationMenuItem("NavigationMenu.Body");
+  // Registered only while the group is actually in the document, which for this
+  // component means only while it is open — see the module header for why a
+  // closed group is removed rather than hidden. The register has to be handed
+  // over conditionally rather than the hook called conditionally, because a
+  // hook that runs on some renders and not others is a different bug.
+  usePresence(item.expanded ? item.registerBody : undefined);
+
+  if (!item.expanded) {
+    return null;
+  }
+
+  return (
+    <ul {...rest} aria-labelledby={item.triggerId} id={item.bodyId}>
+      {children}
+    </ul>
+  );
+}
+
+/**
+ * A destination.
+ *
+ * It renders its own `<li>` around the `<a>`, which is worth knowing before it
+ * surprises somebody: a `<ul>` may only contain `<li>`, and a `Link` that
+ * rendered a bare anchor would put this package's own markup outside what HTML
+ * allows in the list it sits in. The caller's props go on the anchor, which is
+ * the element they are about.
+ *
+ * Choosing one closes the group, because the reader is leaving. That is done
+ * without preventing anything: the click still navigates, and the group is shut
+ * behind them so that coming back — or a router that never unmounted the page —
+ * does not leave it hanging open.
+ */
+export component NavigationMenuLink(children: React.Node, ...rest: Rest) {
+  const item = useNavigationMenuItem("NavigationMenu.Link");
+  const passed = withoutComposed(rest, ["onClick"]);
+
+  return (
+    <li>
+      <a {...passed} onClick={composeHandlers(rest.onClick, item.close)}>
+        {children}
+      </a>
+    </li>
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/ui",
-  "version": "0.0.0-alpha.2",
+  "version": "0.0.0-alpha.37",
   "description": "Headless, accessible React components whose composition Flow checks, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -11,18 +11,18 @@
     "directory": "packages/ui"
   },
   "exports": {
-    "./dialog/types": "./dialog/types.js",
-    "./form/types": "./form/types.js",
-    ".": "./index.js",
-    "./types/renders": "./types/renders.js"
+    ".": "./index.js"
   },
   "files": [
-    "index.js",
-    "internal"
+    "*.js",
+    "internal",
+    "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/react": "0.0.0-alpha.2",
-    "@uniflowed/validator": "0.0.0-alpha.2"
+    "@uniflowed/core": "0.0.0-alpha.37",
+    "@uniflowed/hooks": "0.0.0-alpha.37",
+    "@uniflowed/react": "0.0.0-alpha.37",
+    "@uniflowed/state": "0.0.0-alpha.37"
   },
   "peerDependencies": {
     "react": ">=19"