@uniflowed/ui 0.0.0-alpha.9 → 0.2.0

package/internal/menu-tree.js

@@ -0,0 +1,228 @@
+// @flow
+//
+// What every menu in this package is a menu *of*.
+//
+// `menu.js` was one module because there was one menu. shadcn ships four
+// components on this behaviour — a dropdown menu, a context menu, a menubar and
+// the checkable items all three of them share — and the three that are not the
+// dropdown differ from it in exactly two places: what opens the menu, and where
+// the menu goes. Everything between those two — the tree of open levels, what
+// `Escape` closes, what "choosing an item" dismisses, which selector finds an
+// item and which finds its owner — is one set of rules, and this is it.
+//
+// Written down here rather than exported from `menu.js` for the reason every
+// other module in `internal/` gives: these are relationships the components
+// build, not a menu-building kit. `MENU_SELECTOR` is only true because
+// `Menu.Body` renders `role="menu"`; handed to a consumer it would be a
+// selector that happens to work.
+//
+// # A menu is a chain, not a flag
+//
+// A submenu is a menu whose parent is another menu, and almost every rule that
+// distinguishes the two is a statement about that chain:
+//
+//   * `Escape` closes *one* level, so it needs to know which one it is in.
+//   * Choosing an item closes the whole chain, because leaving the parent menu
+//     open after a command has run is a state no native menu has been in.
+//   * Only the outermost level listens for a press outside, because a submenu
+//     closes with the tree and two listeners would each answer one press.
+//
+// So the chain is the shape the context carries, and `parent` is what a level
+// is given rather than something it works out.
+//
+// # Where a menu goes, when it is not against its trigger
+//
+// A context menu opens at the pointer, which is a *point* and not an element.
+// `MenuAnchorContext` is how a level says so: a rectangle that replaces the
+// trigger's own measurement inside `internal/anchor.js`, and nothing else — the
+// trigger element is still what the writing direction is read from and what
+// focus goes back to. A level with no provider above it measures its trigger,
+// which is every menu that hangs off a button.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+
+import type { Rect } from "./anchor.js";
+import type { Direction } from "./roving-focus.js";
+import { useControlled } from "./controlled-state.js";
+
+/**
+ * Anything that plays the part of a menu item, including the two checkable
+ * kinds. The keyboard has to move between all of them, so the selector names
+ * all of them rather than only the plain command.
+ */
+export const ITEM_SELECTOR: string =
+  '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]';
+
+/** What owns an item: the nearest menu, so a submenu keeps its own. */
+export const MENU_SELECTOR: string = '[role="menu"]';
+
+/**
+ * Which arrow key opens a submenu, and which closes it.
+ *
+ * The WAI-ARIA menu pattern puts a submenu on the *inline end*, so it opens to
+ * the right of a left-to-right menu and to the left of a right-to-left one, and
+ * the key that opens it is the one pointing at it. Written out as
+ * `ArrowRight` to open and `ArrowLeft` to close, an RTL reader pressed the key
+ * aimed at the submenu and closed the menu they were standing in — which is
+ * worse than nothing happening, because it loses their place.
+ */
+export function submenuKeys(direction: Direction): {|
+  readonly open: string,
+  readonly close: string,
+|} {
+  return direction === "rtl"
+    ? { open: "ArrowLeft", close: "ArrowRight" }
+    : { open: "ArrowRight", close: "ArrowLeft" };
+}
+
+export type MenuState = {|
+  readonly base: string,
+  readonly open: boolean,
+  readonly setOpen: (open: boolean) => void,
+  /** What opened this menu, and what focus goes back to when it closes. */
+  readonly triggerRef: { current: HTMLElement | null },
+  /**
+   * Which end the menu should open onto, written by whatever opened it.
+   *
+   * A ref rather than state because it is an instruction for the next commit,
+   * not a value anything renders: `ArrowUp` on a closed menu opens it *and*
+   * lands on the last item, and re-rendering the trigger to say so would be a
+   * render whose only purpose is to carry a message to an effect.
+   */
+  readonly pendingFocusRef: { current: "first" | "last" | null },
+  /** The menu this one hangs off, or null for the outermost. */
+  readonly parent: MenuState | null,
+  /**
+   * Whether a trigger is rendered *and* is something worth naming the menu
+   * after, so the body only claims a name that exists.
+   *
+   * A menu opened by `defaultOpen` in a page that never renders a trigger is a
+   * real arrangement, and an `aria-labelledby` pointing at the id that trigger
+   * *would* have had makes a screen reader announce nothing at all. A context
+   * menu's trigger is arbitrary content rather than a label, and registers
+   * itself as a trigger without registering itself as a name.
+   */
+  readonly triggered: boolean,
+  readonly registerTrigger: (present: boolean) => void,
+|};
+
+export const MenuContext: React.Context<MenuState | null> = createContext(null);
+
+/**
+ * The roving tab stop of one open menu.
+ *
+ * Provided by `Menu.Body` rather than by the root, because a submenu is a
+ * second list with a tab stop of its own: nesting the provider is what stops
+ * the parent menu and the submenu from fighting over which item is `tabindex=0`.
+ */
+export type MenuListState = {|
+  readonly activeId: string | null,
+  readonly setActiveId: (id: string | null) => void,
+|};
+
+export const MenuListContext: React.Context<MenuListState | null> = createContext(null);
+
+/**
+ * A box a menu body is placed against instead of its trigger's own.
+ *
+ * `null`, and no provider at all, both mean "measure the trigger". See the
+ * module header, and `AnchorRequest.anchorRect` for what it replaces.
+ */
+export const MenuAnchorContext: React.Context<Rect | null> = createContext(null);
+
+export hook useMenu(part: string): MenuState {
+  const state = useContext(MenuContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Menu.Root`);
+  }
+  return state;
+}
+
+/**
+ * Tell the menu that something worth naming it after is in the document.
+ *
+ * `Menu.Body` names its trigger with `aria-labelledby`, and it may only do that
+ * while there is one to name — a menu opened by `defaultOpen` in a page with no
+ * trigger would otherwise point at an id nothing has, and a screen reader given
+ * a dangling `aria-labelledby` announces nothing at all rather than falling back
+ * to the element's own content.
+ */
+export hook useTriggerRegistration(menu: MenuState): void {
+  const register = menu.registerTrigger;
+  useEffect(() => {
+    register(true);
+    return () => register(false);
+  }, [register]);
+}
+
+/** Every menu from `menu` outwards, innermost first. */
+export function ancestry(menu: MenuState): Array<MenuState> {
+  const chain = [];
+  let at: MenuState | null = menu;
+  while (at != null) {
+    chain.push(at);
+    at = at.parent;
+  }
+  return chain;
+}
+
+/**
+ * Close this menu and every menu it hangs off.
+ *
+ * Choosing an item in a submenu dismisses the whole thing — leaving the parent
+ * menu open after a command has run is a state no native menu has ever been in,
+ * and it leaves the reader looking at a menu whose action already happened.
+ */
+export function closeTree(menu: MenuState): void {
+  for (const each of ancestry(menu)) {
+    each.setOpen(false);
+  }
+}
+
+/**
+ * One level of the menu tree.
+ *
+ * Shared by `Menu.Root`, `Menu.Sub`, `ContextMenu.Root` and `Menubar.Menu`,
+ * which differ only in what they hand it: a submenu knows its parent, and a
+ * menubar's menu is opened and closed by the bar rather than by itself.
+ */
+export component MenuLevel(
+  children: React.Node,
+  parent: MenuState | null,
+  defaultOpen: boolean,
+  open?: boolean,
+  onOpenChange?: (open: boolean) => void,
+) {
+  const base = useId();
+  const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const pendingFocusRef = useRef<"first" | "last" | null>(null);
+  const [triggered, setTriggered] = useState(false);
+
+  const state = useMemo(
+    () => ({
+      base,
+      open: isOpen,
+      setOpen,
+      triggerRef,
+      pendingFocusRef,
+      parent,
+      triggered,
+      registerTrigger: setTriggered,
+    }),
+    [base, isOpen, setOpen, parent, triggered],
+  );
+
+  return <MenuContext.Provider value={state}>{children}</MenuContext.Provider>;
+}

package/internal/merge-props.js

@@ -20,6 +20,16 @@
 // a caller legitimately wants *both* — event handlers and refs — they are
 // composed rather than one replacing the other.
 //
+// # The other half of the rule: which element the props land on
+//
+// Everything above decides what goes onto the element. `RenderProp` is what
+// decides *which element*, and it is here rather than in a module of its own
+// because it is the same policy read from the other end: a part computes one
+// props object, and either puts it on the element it would have chosen or hands
+// it to the caller to put on theirs. Two ways of composing a caller's props
+// would be two chances to get the order wrong; one shape, stated once, is what
+// keeps a part that renders somebody else's element from being a weaker part.
+//
 // # Why this is `internal/` and not a subpath
 //
 // It is not a "props utils" module and there is nothing else in it. It is the
@@ -28,6 +38,8 @@
 // consumer to build a part that spreads `rest` last, which is the failure this
 // exists to prevent — so it stays unreachable from outside the package.
 
+import type { Node } from "@uniflowed/react";
+
 /**
  * Props on their way onto an element: what a caller hands a part, and what
  * `Field.Control` hands back for a caller to spread.
@@ -75,6 +87,78 @@
  */
 export type Rest = { readonly key?: empty, readonly [string]: mixed };
 
+/**
+ * The escape hatch: a caller's element in place of the part's own.
+ *
+ * `@uniflowed/ui` has no copy step — `packages/ui/index.js`'s header argues
+ * that at length — and the thing a copy step is *for* is changing the markup. A
+ * part that always renders a `<button>` cannot be the link a menu of links
+ * needs; a heading fixed at `<h2>` is wrong inside an accordion. This is what
+ * replaces owning the source: the part still computes every attribute, every
+ * composed handler and every id, and hands them to the caller to put on
+ * whatever element they wanted.
+ *
+ * One name and one signature everywhere, which is the point. `asChild` clones a
+ * child and hopes its props survive; this hands the props over explicitly, so a
+ * caller can see what they are getting, decide the order themselves, and drop
+ * one deliberately. The part is still the part — `Menu.Body`'s `renders*` still
+ * rejects a `<div>` where a `Menu.Item` belongs, because the escape hatch
+ * changes the element the item renders and not what the item *is*. That
+ * constraint is exactly what a copied source loses.
+ *
+ * # What is in the props, and what is not
+ *
+ * Everything the part would have put on its own element, in the order
+ * `withProps` fixes: the caller's `rest` underneath, the part's own semantics on
+ * top, handlers and refs composed rather than replaced. `children` is in there
+ * too, so `render={(props) => <a href={to} {...props} />}` renders what was
+ * written between the tags — a part whose children were silently dropped
+ * because the caller spread the props and forgot them is the kind of quiet
+ * wrongness this package exists to not have. JSX children win over a spread, so
+ * `<a {...props}>Other</a>` still says what it says.
+ *
+ * What is *not* in there is anything true of the element rather than of the
+ * part: `type="button"` is the only one in practice, and it stays on the
+ * `<button>` branch. Handing it to a caller rendering an `<a>` would put an
+ * attribute the HTML has no meaning for on their link.
+ */
+export type RenderProp = (props: Rest) => Node;
+
+/**
+ * What a part's own handler reads of the event it is handed.
+ *
+ * Inexact, and named rather than inferred, for the same reason `menu.js`'s
+ * `MenuSelect` is: what arrives is React's synthetic event, uf does not merge
+ * Flow's `jsx.js` environment so `lib/react.js` models no such thing, and these
+ * are the members the handlers in this package actually read.
+ *
+ * It exists because of `RenderProp`. A handler written inside a JSX attribute
+ * gets its parameter's type from the attribute, which for an intrinsic is
+ * `any`; the escape hatch has to build the props *before* there is an element
+ * to put them on, so the same handler in an object literal has an indexer's
+ * `mixed` for context and Flow asks for an annotation. This is that annotation,
+ * written once rather than at every handler in the package.
+ *
+ * One shape for keys and for presses, which is the one thing it is not honest
+ * about: `key` and the modifiers belong to a keyboard event and a click has no
+ * `key`. It is a parameter annotation for handlers this package writes rather
+ * than a description of an event, nothing widens `mixed` into it, and the day
+ * `$JSXIntrinsics` is real — the day `Rest` becomes `React.PropsOf`, which its
+ * own comment is waiting for — is the day this is React's event types instead.
+ */
+export type PartEvent = {
+  readonly defaultPrevented: boolean,
+  readonly key: string,
+  readonly altKey: boolean,
+  readonly ctrlKey: boolean,
+  readonly metaKey: boolean,
+  readonly shiftKey: boolean,
+  readonly currentTarget: mixed,
+  readonly preventDefault: () => mixed,
+  readonly stopPropagation: () => mixed,
+  ...
+};
+
 /**
  * A caller's props on their way to another *part of this package*, rather than
  * onto an intrinsic element.
@@ -116,7 +200,7 @@ export function forwarded(rest: Rest): $FlowFixMe {
  * `defaultPrevented` is the caller's way of saying "I handled this", which is
  * the same contract the DOM uses.
  */
-export function composeHandlers<TEvent extends { readonly defaultPrevented?: boolean }>(
+export function composeHandlers<TEvent extends { readonly defaultPrevented?: boolean, ... }>(
   theirs: mixed,
   ours: (event: TEvent) => mixed,
 ): (event: TEvent) => mixed {

package/internal/roving-focus.js

@@ -45,6 +45,7 @@
 // one the components make.
 
 import { useCallback, useEffect, useRef, useState } from "@uniflowed/react";
+import { useLocale, startsWithLocale } from "../i18n-provider.js";
 
 /** Which way a key asks the focus to move within a set. */
 export type Movement = "previous" | "next" | "first" | "last";
@@ -346,6 +347,8 @@ export hook useFirstItem(
       false,
       set.skipDisabled,
     );
+    // The first item is only knowable after the caller's items are in the DOM.
+    // uf-lint-disable-next-line react-compiler/set-state-in-effect
     setFirst(landing?.id ?? null);
   });
 
@@ -373,6 +376,7 @@ export hook useTypeahead(): (
   from: number,
   key: string,
 ) => HTMLElement | null {
+  const { locale } = useLocale();
   const buffer = useRef<{| text: string, at: number |}>({ text: "", at: 0 });
 
   return useCallback(
@@ -382,7 +386,7 @@ export hook useTypeahead(): (
       buffer.current = { text, at: now };
 
       const repeated = text.length > 1 && text.split("").every((each) => each === text[0]);
-      const needle = (repeated ? text[0] : text).toLowerCase();
+      const needle = repeated ? text[0] : text;
       // A single character — or the same one again — moves on from where we
       // are. A longer buffer starts *at* the current item, so typing "sa" after
       // "s" can keep the item "s" already found.
@@ -390,13 +394,20 @@ export hook useTypeahead(): (
 
       for (let tried = 0; tried < items.length; tried += 1) {
         const candidate = items[(((start + tried) % items.length) + items.length) % items.length];
-        if (isEnabled(candidate) && labelOf(candidate).startsWith(needle)) {
+        if (
+          isEnabled(candidate) &&
+          startsWithLocale(
+            labelOf(candidate),
+            needle,
+            candidate.closest("[lang]")?.getAttribute("lang") || locale,
+          )
+        ) {
           return candidate;
         }
       }
       return null;
     },
-    [],
+    [locale],
   );
 }
 
@@ -426,5 +437,5 @@ export function isTypeaheadKey(event: {
 /** What a reader hears for this item, lower-cased for matching. */
 function labelOf(element: HTMLElement): string {
   const spoken = element.getAttribute("aria-label") ?? element.textContent ?? "";
-  return spoken.replace(/\s+/g, " ").trim().toLowerCase();
+  return spoken.replace(/\s+/g, " ").trim();
 }