@uniflowed/ui 0.0.0-alpha.10

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

@@ -0,0 +1,57 @@
+{
+  "name": "@uniflowed/ui",
+  "version": "0.0.0-alpha.10",
+  "description": "Headless, accessible React components whose composition Flow checks, part of the Unified Toolchain for Flow.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/ui"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./accordion": "./accordion.js",
+    "./alert-dialog": "./alert-dialog.js",
+    "./carousel": "./carousel.js",
+    "./checkbox": "./checkbox.js",
+    "./collapsible": "./collapsible.js",
+    "./combobox": "./combobox.js",
+    "./dialog": "./dialog.js",
+    "./drawer": "./drawer.js",
+    "./field": "./field.js",
+    "./hover-card": "./hover-card.js",
+    "./input-otp": "./input-otp.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",
+    "./scroll-area": "./scroll-area.js",
+    "./select": "./select.js",
+    "./sheet": "./sheet.js",
+    "./sidebar": "./sidebar.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"
+  },
+  "files": [
+    "*.js",
+    "internal"
+  ],
+  "dependencies": {
+    "@uniflowed/hooks": "0.0.0-alpha.10",
+    "@uniflowed/react": "0.0.0-alpha.10"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  }
+}

package/pagination.js

@@ -0,0 +1,197 @@
+// @flow
+//
+// Pagination: the navigation a table needs to be usable, and its four rules.
+//
+// It is here rather than in `table.js` because it is `crates/uf_lib`'s own
+// entry and because a paginated list is not always a table — but it is written
+// for the table next door, and the two are documented together.
+//
+// Four things, each of which is invisible when it is missing:
+//
+//   * **It is navigation, so it is a `<nav>` with a name.** A page has more
+//     than one `nav`, and an unnamed one is announced as "navigation" with no
+//     way to tell it from the site's menu. `aria-label="Pagination"` is what
+//     puts it in a screen reader's landmark list under a useful name.
+//   * **The current page is `aria-current="page"`.** Not a class, not bold
+//     text, not `aria-selected` — `page` is the value ARIA defines for exactly
+//     this, and it is the only one that tells a reader where they are.
+//   * **Previous and next are named as such.** A link whose content is `‹` is
+//     announced as "link, left single quotation mark", which is not a thing
+//     anybody can act on. The glyph stays; the name is words.
+//   * **The change is announced.** Pressing "next" replaces the rows and moves
+//     nothing a reader is looking at, so a live region that was already there
+//     says "Page 4 of 25". `combobox.js` states the rule about why it has to
+//     have been there first.
+//
+// # Why the controls are links
+//
+// `Pagination.Item` renders an `<a>`, not a `<button>`, and that is an opinion
+// worth stating because it constrains the caller: page four of a table is a
+// *place*, and a reader expects to be able to open it in a new tab, copy it,
+// bookmark it and come back to it. A list paginated with buttons is a list
+// whose fourth page does not exist as far as the rest of the web is concerned.
+//
+// An application that genuinely has no URL for a page — a modal, an unsaved
+// draft — is the case where this is the wrong component, and a `<button>` the
+// caller writes themselves is the right answer. That is a smaller cost than
+// making every well-behaved application invent its own links.
+//
+// # No `"use client"`
+//
+// Nothing here holds state, listens to anything or moves focus. Which page is
+// current is the caller's, the links are links, and the announcement is a
+// string in a div. It renders on a server.
+
+import * as React from "@uniflowed/react";
+
+import type { Rest } from "./internal/merge-props.js";
+import { withoutComposed } from "./internal/merge-props.js";
+
+/**
+ * The pagination, as a named landmark, and the region that announces it.
+ *
+ * `page` and `pageCount` are what the announcement says. They are separate
+ * from which `Pagination.Item` is marked current because the two answer
+ * different questions — a reader is told "page 4 of 25" whether or not 25
+ * links are on screen, and a component that showed five links out of
+ * twenty-five would otherwise announce "page 4 of 5".
+ */
+export component PaginationRoot(
+  children: React.Node,
+  label?: string = "Pagination",
+  page?: number | null = null,
+  pageCount?: number | null = null,
+  announcePage?: (page: number, pageCount: number) => string,
+  ...rest: Rest
+) {
+  const message =
+    page == null || pageCount == null ? "" : (announcePage ?? defaultAnnouncement)(page, pageCount);
+
+  return (
+    <>
+      <nav {...rest} aria-label={label}>
+        {children}
+      </nav>
+      {/*
+        Beside the navigation rather than inside it, so a reader walking the
+        landmark hears the links and not a sentence about them — and mounted
+        from the first render holding nothing, because a live region that
+        appears together with its text is not announced at all.
+      */}
+      <div aria-atomic="true" aria-live="polite" data-uf-pagination-status="" role="status">
+        {message}
+      </div>
+    </>
+  );
+}
+
+/**
+ * The list of pages.
+ *
+ * A real list, so a reader is told how many there are before walking them and
+ * can skip the whole thing in one keystroke.
+ */
+export component PaginationContent(
+  children: renders* (PaginationItem | PaginationPrevious | PaginationNext),
+  ...rest: Rest
+) {
+  return <ul {...rest}>{children}</ul>;
+}
+
+/**
+ * One page.
+ *
+ * The `<li>` is structural and takes nothing; everything a caller passes goes
+ * on the `<a>`, which is what they style and what a reader activates.
+ */
+export component PaginationItem(
+  children: React.Node,
+  current?: boolean = false,
+  disabled?: boolean = false,
+  ...rest: Rest
+) {
+  return (
+    <PageLink current={current} disabled={disabled} rest={rest}>
+      {children}
+    </PageLink>
+  );
+}
+
+/**
+ * The link to the page before this one.
+ *
+ * `label` is its accessible name and has a default, because the content of
+ * this link is a chevron every time — and "link, left single quotation mark"
+ * is not something a reader can act on. Pass `label` to translate it; the
+ * glyph stays whatever the caller rendered.
+ */
+export component PaginationPrevious(
+  children?: React.Node,
+  label?: string = "Previous page",
+  disabled?: boolean = false,
+  ...rest: Rest
+) {
+  return (
+    <PageLink disabled={disabled} label={label} rest={rest}>
+      {children}
+    </PageLink>
+  );
+}
+
+/** The link to the page after this one. See `Pagination.Previous`. */
+export component PaginationNext(
+  children?: React.Node,
+  label?: string = "Next page",
+  disabled?: boolean = false,
+  ...rest: Rest
+) {
+  return (
+    <PageLink disabled={disabled} label={label} rest={rest}>
+      {children}
+    </PageLink>
+  );
+}
+
+/**
+ * The `<li><a>` the three parts above all render.
+ *
+ * `rest` arrives as a *named prop* rather than as a spread, and that is not a
+ * style choice. `Rest` is the type of props on their way onto an intrinsic —
+ * `merge-props.js` explains why an intrinsic's own props are unchecked here —
+ * and spreading its `mixed` indexer onto a typed component makes the checker
+ * say, correctly, that `disabled` might not be a boolean. Handing the bag over
+ * as one value keeps it a bag until it reaches the element it was always for.
+ *
+ * `disabled` drops the `href` rather than adding an attribute, because there
+ * is no such thing as a disabled link: an `<a>` with no `href` is not in the
+ * tab order and is not announced as a link, which is exactly what "there is no
+ * previous page" means. `aria-disabled` is there too, so a reader who reaches
+ * it another way is told why it does nothing.
+ */
+component PageLink(
+  rest: Rest,
+  children?: React.Node,
+  current?: boolean = false,
+  disabled?: boolean = false,
+  label?: string,
+) {
+  const passed = withoutComposed(rest, disabled ? ["href"] : []);
+
+  return (
+    <li>
+      <a
+        {...passed}
+        aria-current={current ? "page" : undefined}
+        aria-disabled={disabled ? "true" : undefined}
+        aria-label={label}
+      >
+        {children}
+      </a>
+    </li>
+  );
+}
+
+/** The wording used when the caller supplies none. */
+function defaultAnnouncement(page: number, pageCount: number): string {
+  return `Page ${String(page)} of ${String(pageCount)}.`;
+}