@uniflowed/ui 0.0.0-alpha.9 → 0.2.0

package/menubar.js

@@ -0,0 +1,295 @@
+// @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, useTriggerRegistration } 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);
+      }
+    }),
+    // React calls callback refs during commit; keyboard handlers read it later.
+    // uf-lint-disable-next-line react-compiler/refs
+    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);
+  useTriggerRegistration(menu);
+  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();
+      // This is an instruction for the menu body after the opening commit.
+      // uf-lint-disable-next-line react-compiler/immutability
+      menu.pendingFocusRef.current = end;
+      bar.setOpen(value);
+    }),
+    // React calls callback refs during commit; menu focus restoration reads it later.
+    // uf-lint-disable-next-line react-compiler/refs
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      // uf-lint-disable-next-line react-compiler/immutability
+      menu.triggerRef.current = element;
+    }),
+    role: "menuitem",
+    tabIndex: stop ? 0 : -1,
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
+}

package/number-field.js

@@ -0,0 +1,263 @@
+// @flow
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useMemo, useState } from "@uniflowed/react";
+import { useStableCallback } from "@uniflowed/hooks/lifecycle";
+import { useControlled } from "./internal/controlled-state.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { composeHandlers, withProps } from "./internal/merge-props.js";
+import { useLocale } from "./i18n-provider.js";
+
+type NumberFormatter = {
+  format: (value: number) => string,
+  formatToParts: (value: number) => Array<{ type: string, value: string }>,
+  resolvedOptions: () => { locale: string, style: string, ... },
+};
+export type NumberFormatOptions = {
+  style?: "decimal" | "percent" | "currency" | "unit",
+  currency?: string,
+  currencyDisplay?: "symbol" | "narrowSymbol" | "code" | "name",
+  currencySign?: "standard" | "accounting",
+  unit?: string,
+  unitDisplay?: "long" | "short" | "narrow",
+  useGrouping?: boolean,
+  minimumFractionDigits?: number,
+  maximumFractionDigits?: number,
+  minimumIntegerDigits?: number,
+  numberingSystem?: string,
+};
+// Flow's bundled Intl declarations predate formatToParts and unit formatting.
+function numberFormatter(locale: string, options?: NumberFormatOptions): NumberFormatter {
+  return new Intl.NumberFormat(locale, { maximumFractionDigits: 20, ...options }) as $FlowFixMe;
+}
+
+/** Parse only the symbols the formatter emits, never arbitrary trailing text. */
+export function parseNumber(text: string, formatter: NumberFormatter): number | null {
+  if (text.trim() === "") return null;
+  const options = formatter.resolvedOptions();
+  const digits = new Intl.NumberFormat(options.locale, { useGrouping: false });
+  let clean = text.trim();
+  for (let digit = 0; digit < 10; digit += 1)
+    clean = clean.split(digits.format(digit)).join(String(digit));
+  const parts = formatter.formatToParts(-12345.6);
+  const decimal =
+    numberFormatter(options.locale)
+      .formatToParts(1.1)
+      .find((part) => part.type === "decimal")?.value ?? ".";
+  const accounting = clean.startsWith("(") && clean.endsWith(")");
+  if (accounting) clean = clean.slice(1, -1);
+  for (const part of parts) {
+    if (["group", "currency", "unit", "percentSign", "literal"].includes(part.type))
+      clean = clean.split(part.value).join("");
+    if (part.type === "minusSign") clean = clean.split(part.value).join("-");
+  }
+  clean = clean
+    .split(decimal)
+    .join(".")
+    .replace(/[\s\u200e\u200f\u061c]/g, "");
+  if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(clean)) return NaN;
+  const value = (Number(clean) * (accounting ? -1 : 1)) / (options.style === "percent" ? 100 : 1);
+  return Number.isFinite(value) ? value : NaN;
+}
+
+type NumberState = {
+  value: number | null,
+  text: string,
+  invalid: boolean,
+  disabled: boolean,
+  readOnly: boolean,
+  min: number | void,
+  max: number | void,
+  formatter: NumberFormatter,
+  edit: (text: string) => void,
+  commit: () => void,
+  stepBy: (direction: number) => void,
+  boundary: (value: number | void) => void,
+};
+const NumberContext: React.Context<NumberState | null> = createContext(null);
+hook useNumber(): NumberState {
+  const state = useContext(NumberContext);
+  if (state == null) throw new Error("NumberField parts must be inside NumberField.Root");
+  return state;
+}
+
+export component NumberFieldRoot(
+  children: React.Node,
+  value?: number | null,
+  defaultValue?: number | null = null,
+  onValueChange?: (value: number | null) => void,
+  onValidationChange?: (invalid: boolean) => void,
+  min?: number,
+  max?: number,
+  step?: number,
+  formatOptions?: NumberFormatOptions,
+  disabled?: boolean = false,
+  readOnly?: boolean = false,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const increment = step ?? (formatOptions?.style === "percent" ? 0.01 : 1);
+  if (
+    !Number.isFinite(increment) ||
+    increment <= 0 ||
+    (min != null && !Number.isFinite(min)) ||
+    (max != null && !Number.isFinite(max)) ||
+    (min != null && max != null && min > max)
+  ) {
+    throw new RangeError("NumberField requires finite bounds and a positive increment");
+  }
+  const upperBound =
+    max == null
+      ? undefined
+      : Number(
+          ((min ?? 0) + Math.floor((max - (min ?? 0)) / increment + 1e-9) * increment).toPrecision(
+            15,
+          ),
+        );
+  const { locale } = useLocale();
+  const formatter = useMemo(() => numberFormatter(locale, formatOptions), [locale, formatOptions]);
+  const [current, setCurrent] = useControlled(value, defaultValue, onValueChange);
+  const [draft, setDraft] = useState<string | null>(null);
+  const text = draft ?? (current == null ? "" : formatter.format(current));
+  const parsed = parseNumber(text, formatter);
+  const invalid =
+    parsed != null &&
+    (!Number.isFinite(parsed) ||
+      (min != null && parsed < min) ||
+      (max != null && parsed > max) ||
+      Math.abs((parsed - (min ?? 0)) / increment - Math.round((parsed - (min ?? 0)) / increment)) >
+        1e-7);
+  const assign = useStableCallback((next: number | null) => {
+    if (disabled || readOnly) return;
+    setDraft(null);
+    setCurrent(next);
+    onValidationChange?.(false);
+  });
+  const commit = useStableCallback(() => {
+    if (disabled || readOnly) return;
+    onValidationChange?.(invalid);
+    if (!invalid) assign(parsed);
+  });
+  const stepBy = useStableCallback((direction: number) => {
+    const start = parsed != null && Number.isFinite(parsed) ? parsed : (current ?? min ?? 0);
+    const base = min ?? 0;
+    const position = (start - base) / increment;
+    const index =
+      direction > 0
+        ? Math.floor(position + 1e-9) + direction
+        : Math.ceil(position - 1e-9) + direction;
+    const next = Number((base + index * increment).toPrecision(15));
+    const ceiling =
+      max == null
+        ? Infinity
+        : Number((base + Math.floor((max - base) / increment + 1e-9) * increment).toPrecision(15));
+    assign(Math.max(min ?? -Infinity, Math.min(ceiling, next)));
+  });
+  const state = {
+    value: current,
+    text,
+    invalid,
+    disabled,
+    readOnly,
+    min,
+    max: upperBound,
+    formatter,
+    edit: (next: string) => {
+      if (!disabled && !readOnly) setDraft(next);
+    },
+    commit,
+    stepBy,
+    boundary: (next: number | void) => {
+      if (next != null)
+        assign(
+          Number(
+            (
+              (min ?? 0) +
+              Math.floor((next - (min ?? 0)) / increment + 1e-9) * increment
+            ).toPrecision(15),
+          ),
+        );
+    },
+  };
+  const props = withProps(rest, { children, "data-invalid": invalid ? "" : undefined });
+  return (
+    <NumberContext.Provider value={state}>
+      {render != null ? render(props) : <div {...props} />}
+    </NumberContext.Provider>
+  );
+}
+
+/** Field.Control may render this input to supply the label, description and error ids. */
+export component NumberFieldInput(render?: RenderProp, ...rest: Rest) {
+  const state = useNumber();
+  const props = withProps(rest, {
+    type: "text",
+    role: "spinbutton",
+    inputMode: "decimal",
+    value: state.text,
+    disabled: state.disabled,
+    readOnly: state.readOnly,
+    "aria-valuenow": state.value == null || !Number.isFinite(state.value) ? undefined : state.value,
+    "aria-valuetext": state.text || undefined,
+    "aria-valuemin": state.min,
+    "aria-valuemax": state.max,
+    "aria-invalid": state.invalid ? "true" : rest["aria-invalid"],
+    onChange: composeHandlers(rest.onChange, (event: $FlowFixMe) =>
+      state.edit(event.currentTarget.value),
+    ),
+    onBlur: composeHandlers(rest.onBlur, state.commit),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: $FlowFixMe) => {
+      if (state.disabled || state.readOnly) return;
+      const key = event.key;
+      if (["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", "Enter"].includes(key)) {
+        event.preventDefault();
+        if (key === "Home") state.boundary(state.min);
+        else if (key === "End") state.boundary(state.max);
+        else if (key === "Enter") state.commit();
+        else
+          state.stepBy(
+            key === "ArrowUp" ? 1 : key === "ArrowDown" ? -1 : key === "PageUp" ? 10 : -10,
+          );
+      }
+    }),
+  });
+  return render != null ? render(props) : <input {...props} />;
+}
+
+export component NumberFieldIncrement(
+  children?: React.Node = "+",
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const state = useNumber();
+  const props = withProps(rest, {
+    children,
+    type: "button",
+    "aria-label": rest["aria-label"] ?? "Increase",
+    disabled:
+      state.disabled ||
+      state.readOnly ||
+      (state.max != null && state.value != null && state.value >= state.max),
+    onClick: composeHandlers(rest.onClick, () => state.stepBy(1)),
+  });
+  return render != null ? render(props) : <button {...props} />;
+}
+export component NumberFieldDecrement(
+  children?: React.Node = "−",
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const state = useNumber();
+  const props = withProps(rest, {
+    children,
+    type: "button",
+    "aria-label": rest["aria-label"] ?? "Decrease",
+    disabled:
+      state.disabled ||
+      state.readOnly ||
+      (state.min != null && state.value != null && state.value <= state.min),
+    onClick: composeHandlers(rest.onClick, () => state.stepBy(-1)),
+  });
+  return render != null ? render(props) : <button {...props} />;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/ui",
-  "version": "0.0.0-alpha.9",
+  "version": "0.2.0",
   "description": "Headless, accessible React components whose composition Flow checks, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -11,38 +11,18 @@
     "directory": "packages/ui"
   },
   "exports": {
-    ".": "./index.js",
-    "./accordion": "./accordion.js",
-    "./checkbox": "./checkbox.js",
-    "./collapsible": "./collapsible.js",
-    "./combobox": "./combobox.js",
-    "./dialog": "./dialog.js",
-    "./field": "./field.js",
-    "./hover-card": "./hover-card.js",
-    "./menu": "./menu.js",
-    "./navigation-menu": "./navigation-menu.js",
-    "./pagination": "./pagination.js",
-    "./popover": "./popover.js",
-    "./progress": "./progress.js",
-    "./radio-group": "./radio-group.js",
-    "./resizable": "./resizable.js",
-    "./select": "./select.js",
-    "./slider": "./slider.js",
-    "./switch": "./switch.js",
-    "./table": "./table.js",
-    "./tabs": "./tabs.js",
-    "./toast": "./toast.js",
-    "./toggle": "./toggle.js",
-    "./toggle-group": "./toggle-group.js",
-    "./tooltip": "./tooltip.js"
+    ".": "./index.js"
   },
   "files": [
     "*.js",
-    "internal"
+    "internal",
+    "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.9",
-    "@uniflowed/react": "0.0.0-alpha.9"
+    "@uniflowed/core": "0.2.0",
+    "@uniflowed/hooks": "0.2.0",
+    "@uniflowed/react": "0.2.0",
+    "@uniflowed/state": "0.2.0"
   },
   "peerDependencies": {
     "react": ">=19"