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

package/separator.js

@@ -0,0 +1,97 @@
+// @flow
+//
+// A rule, and the one decision in it: whether anybody is told it is there.
+//
+// Two lines of markup, and it belongs in this package rather than in the preset
+// for the same reason `Progress` does — the component *is* a conditional about
+// what a reader hears:
+//
+//   * A separator **between groups of content** is `role="separator"` with an
+//     `aria-orientation`. A reader moving down the page is told the subject
+//     changed, which is the information the line was drawn to give and the only
+//     way they get it.
+//   * A **decorative** rule — the line under a heading, the hairline between a
+//     card's padding and its footer — is `aria-hidden="true"` and announced to
+//     nobody. It is a border that happens to be an element.
+//
+// Getting it backwards is silent in both directions: a decorative rule with the
+// role adds a "separator" to every reading of the page, and a real boundary
+// without it takes the boundary away from everyone who is not looking at it.
+//
+// The default is the semantic one, because the two mistakes do not cost the
+// same. A rule wrongly announced is noise a reader can hear and skip; a
+// boundary wrongly silent is information that is simply not there, and nobody
+// finds out. `progress.js` makes the same trade in its own sentence: the safe
+// answer has to be the honest one.
+//
+// # Why this is a `<div>` and not an `<hr>`
+//
+// An `<hr>` already carries `role="separator"`, so for a horizontal rule
+// between two blocks of prose it is the better answer and a caller who can use
+// one should. This exists for what it cannot do.
+//
+// It comes with a border and a margin from the browser's own stylesheet, and a
+// package that ships no styles cannot ship a visible line — every consumer
+// would begin by turning it off. It is horizontal by definition, so a vertical
+// rule between two things in a row is a rotated element rather than a described
+// one. And it is a paragraph-level break in the flow, which is not what a
+// hairline inside a toolbar is.
+//
+// # The two separators that are not this one
+//
+// `Menu.Separator` is the rule between groups of menu items, and belongs to the
+// menu because it has to be skipped by the arrow keys that walk it.
+// `Resizable.Handle` announces itself as a separator too, and is a *control* —
+// the APG window splitter, a separator that behaves like a slider. Neither is
+// this, and reaching for this one in either place loses the behaviour that made
+// them their own components.
+//
+// # No `"use client"`
+//
+// One element, two attributes, nothing to remember. It renders on a server.
+
+import type { Orientation } from "./internal/roving-focus.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { withProps } from "./internal/merge-props.js";
+
+export type { Orientation } from "./internal/roving-focus.js";
+
+/**
+ * A rule between two things, or a line that is only a line.
+ *
+ * `decorative` is the whole component. Without it the element is a
+ * `role="separator"` a reader is told about; with it the element is hidden from
+ * the accessibility tree entirely.
+ *
+ *     <Separator />
+ *     <Separator orientation="vertical" />
+ *     <Separator decorative />
+ *
+ * The decorative one gets `aria-hidden` and no role, rather than
+ * `role="presentation"` as well: a `<div>` has nothing to hide behind a
+ * presentation role, and one attribute that removes the element from the tree
+ * says the whole thing. `Breadcrumb.Separator` carries both because it is an
+ * `<li>`, whose `listitem` role would otherwise be counted.
+ *
+ * `aria-orientation` is written out even for the horizontal case, where ARIA
+ * would default to it. It is the attribute a reader of this markup is looking
+ * for, and a default that is left implicit is a default somebody has to know.
+ *
+ * `render` changes the element carrying that decision, not the decision
+ * itself: decorative rules stay hidden, semantic rules keep the separator
+ * role and orientation.
+ */
+export component Separator(
+  decorative?: boolean = false,
+  orientation?: Orientation = "horizontal",
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const props = decorative
+    ? withProps(rest, { "aria-hidden": "true" })
+    : withProps(rest, { "aria-orientation": orientation, role: "separator" });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
+}

package/sheet.js

@@ -0,0 +1,189 @@
+// @flow
+//
+// A sheet: a modal dialog attached to an edge of the viewport.
+//
+// # What it is not, first
+//
+// A `Sheet` that were only a `Dialog` with a class on it would not be worth
+// shipping, and this module would be a paragraph in the documentation saying
+// "use `Dialog` and style it". The edge is a visual decision, `role="dialog"`
+// is already right, and nothing a screen reader is told changes because the
+// dialog slid in from the left. A component that added a `<div>` and a name
+// for that would be a component that made a design system harder to read.
+//
+// What makes it a component is the two things a class cannot be:
+//
+//   * **`side` is a type.** `<Sheet.Root side="lft">` is a Flow error at the
+//     call. A class name is a string, and a misspelt one is a sheet rendered
+//     off the top of the page with nothing reported anywhere.
+//   * **`data-side` is one contract.** The same attribute name `popover.js`
+//     writes, so a stylesheet has one thing to key on for every overlay in this
+//     package — and, more to the point, `drawer.js` and `sidebar.js` are both
+//     *defined in terms of this module*. A drawer is a sheet you can drag away;
+//     a sidebar on a narrow viewport becomes one. Written three times, "left"
+//     would come to mean three subtly different things, and the day one of them
+//     was fixed is the day they stopped agreeing.
+//
+// So the module is small on purpose. It is the shared definition of an edge,
+// and the modal semantics under it are `dialog.js`'s, unchanged: focus in,
+// `Tab` trapped, `Escape` out, focus back, the page inert and still. A sheet is
+// modal, and every one of those is why.
+//
+// # The edge is not announced
+//
+// Deliberately. There is no `aria-*` for "this came in from the right", and
+// inventing one — a `Sheet` that named its edge in its accessible name — would
+// make a reader hear "Filters, right" and wonder what "right" meant. Where the
+// box came from is the eye's business. The reader is told it is a dialog, what
+// it is called, and that the rest of the page is unavailable, which is all
+// three of the things that are true.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useMemo } from "@uniflowed/react";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { forwarded } from "./internal/merge-props.js";
+import {
+  DialogBody,
+  DialogClose,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogRoot,
+  DialogTitle,
+  DialogTrigger,
+} from "./dialog.js";
+
+/**
+ * Which edge of the viewport a sheet is attached to.
+ *
+ * Physical, and deliberately not logical: a design that puts a navigation sheet
+ * against the left of the screen means the left of the screen in any writing
+ * direction, the same way `internal/anchor.js`'s `Side` does and for the same
+ * reason. What the writing direction changes is the reading order inside the
+ * sheet, which is the page's business rather than this component's.
+ *
+ * A union rather than a string, so a typo is a type error at the call rather
+ * than a `data-side="lft"` no stylesheet matches and no test notices.
+ */
+export type Edge = "top" | "right" | "bottom" | "left";
+
+type SheetState = {| readonly side: Edge |};
+
+const SheetContext: React.Context<SheetState | null> = createContext(null);
+
+/**
+ * The sheet a part belongs to.
+ *
+ * Raising rather than returning null, for the reason `useDialog` gives: a
+ * `Sheet.Body` outside a root would render a dialog with no edge, and it would
+ * look correct until somebody styled it.
+ */
+hook useSheet(part: string): SheetState {
+  const state = useContext(SheetContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Sheet.Root`);
+  }
+  return state;
+}
+
+/** The sheet, open or closed. Uncontrolled unless `open` is given. */
+export component SheetRoot(
+  children: React.Node,
+  defaultOpen?: boolean = false,
+  onOpenChange?: (open: boolean) => void,
+  open?: boolean,
+  side?: Edge = "right",
+) {
+  const state = useMemo(() => ({ side }), [side]);
+
+  return (
+    <SheetContext.Provider value={state}>
+      <DialogRoot defaultOpen={defaultOpen} onOpenChange={onOpenChange} open={open}>
+        {children}
+      </DialogRoot>
+    </SheetContext.Provider>
+  );
+}
+
+/** What opens it, and what focus comes back to when it closes. */
+export component SheetTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogTrigger {...forwarded(rest)} render={render}>
+      {children}
+    </DialogTrigger>
+  );
+}
+
+/**
+ * The backdrop, which knows the edge so a stylesheet does not have to be told
+ * twice.
+ */
+export component SheetOverlay(render?: RenderProp, ...rest: Rest) {
+  const sheet = useSheet("Sheet.Overlay");
+  return <DialogOverlay {...forwarded(rest)} data-side={sheet.side} render={render} />;
+}
+
+/**
+ * The sheet itself: `Dialog.Body`, plus the edge as an attribute.
+ *
+ * Every modal promise `dialog.js` makes is made here, unchanged. This part adds
+ * `data-side` and nothing else, which is the honest size of the difference.
+ */
+export component SheetBody(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const sheet = useSheet("Sheet.Body");
+
+  return (
+    <DialogBody {...forwarded(rest)} data-side={sheet.side} render={render}>
+      {children}
+    </DialogBody>
+  );
+}
+
+/** The top of the sheet. See `Dialog.Header` for why it is not a `<header>`. */
+export component SheetHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogHeader {...forwarded(rest)} render={render}>
+      {children}
+    </DialogHeader>
+  );
+}
+
+/** The bottom of the sheet, where the actions go. */
+export component SheetFooter(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogFooter {...forwarded(rest)} render={render}>
+      {children}
+    </DialogFooter>
+  );
+}
+
+/** The sheet's accessible name. A modal without one is announced as "dialog". */
+export component SheetTitle(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogTitle {...forwarded(rest)} render={render}>
+      {children}
+    </DialogTitle>
+  );
+}
+
+/** What the sheet is for, announced after its name. */
+export component SheetDescription(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogDescription {...forwarded(rest)} render={render}>
+      {children}
+    </DialogDescription>
+  );
+}
+
+/** A button that closes the sheet. */
+export component SheetClose(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogClose {...forwarded(rest)} render={render}>
+      {children}
+    </DialogClose>
+  );
+}

package/sidebar.js

@@ -0,0 +1,300 @@
+// @flow
+//
+// A sidebar: the one of the four dialog-shaped components that is usually not a
+// dialog at all.
+//
+// `alert-dialog.js`, `sheet.js` and `drawer.js` are modal, and being modal is
+// the point of each. A sidebar is *part of the page*: the reader uses what is
+// beside it while it is open, nothing behind it is inert, nothing is
+// scroll-locked, and there is no focus trap. It is a `<nav>` landmark and a
+// button that says whether it is showing — the disclosure pattern
+// `internal/disclosure.js` describes, applied to a region of the layout.
+//
+// Then the viewport gets narrow, and it *becomes* a dialog. That transition is
+// the component, and it is the reason this is not something a caller assembles
+// out of `Collapsible` and a media query:
+//
+//   * **Collapsed is not closed.** On a wide screen the sidebar collapses to
+//     its icons and stays in the page. On a narrow one it is a `Sheet`: modal,
+//     over the content, gone when it is closed. One `open` describes both, and
+//     `aria-expanded` on the trigger is true about both.
+//   * **Focus has to move in both directions.** Opening the narrow sidebar
+//     moves focus into it, because it is a modal dialog and that is what
+//     `dialog.js` promises; closing it gives focus back to the trigger. Opening
+//     the wide one moves focus nowhere at all, because nothing was taken away.
+//     A component that got this backwards would either strand a reader in a
+//     dialog they cannot leave or move their focus for no reason.
+//   * **A collapsed button still has a name.** This is where the pattern goes
+//     wrong in practice. Collapsed to icons, a button whose accessible name
+//     came from its text is announced as "button" — so `Sidebar.Item` takes a
+//     `label`, puts it in `aria-label` the moment the sidebar collapses, and
+//     shows it in a `Tooltip` for readers who can see the icon and do not know
+//     what it means. The name survives whatever the stylesheet does to the
+//     text, which is the only way to promise it survives.
+//
+// # The state is the caller's, and that is a server-rendering decision
+//
+// `open` is uncontrolled by default like everything else here, and a real
+// application will control it: shadcn persists the answer in a cookie so the
+// server renders the sidebar in the state the reader left it. That matters more
+// under RSC than it looks — an uncontrolled sidebar renders expanded on the
+// server and collapses on hydration, which is a layout shift on every
+// navigation. `open` and `onOpenChange` are how a caller reads the cookie and
+// hands the answer in.
+//
+// # The narrow viewport is a query, not a guess
+//
+// `useMediaQuery` from `@uniflowed/hooks/browser`, with `false` on the server:
+// there is no viewport during a prerender, and guessing "narrow" would send
+// every reader markup in which the navigation is a closed dialog. The wide
+// layout is the one that is still usable when the guess is wrong.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useId, useMemo } from "@uniflowed/react";
+import { useMediaQuery } from "@uniflowed/hooks/browser";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { composeHandlers, forwarded, withProps, withoutComposed } from "./internal/merge-props.js";
+import { SheetBody, SheetOverlay, SheetRoot, SheetTrigger } from "./sheet.js";
+import { TooltipBody, TooltipRoot, TooltipTrigger } from "./tooltip.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+/**
+ * Which side of the layout the sidebar is on.
+ *
+ * Two members and not `sheet.js`'s four, because a sidebar is never attached to
+ * the top or the bottom: a navigation rail across the top of a page is a header,
+ * with different semantics and a different component. `<Sidebar.Root side="top">`
+ * is a type error, which is the point of naming the union rather than reusing
+ * `Edge`.
+ */
+export type SidebarSide = "left" | "right";
+
+/** The breakpoint below which the sidebar is a modal sheet. */
+const NARROW = "(max-width: 48rem)";
+
+type SidebarState = {|
+  readonly base: string,
+  /** Expanded on a wide screen, and showing on a narrow one. */
+  readonly open: boolean,
+  readonly setOpen: (open: boolean) => void,
+  /** In the page, showing icons only. Never true while it is a sheet. */
+  readonly collapsed: boolean,
+  /** Whether the viewport has made it a modal sheet. */
+  readonly modal: boolean,
+  readonly side: SidebarSide,
+  /** Whether the navigation is in the document, so nothing names it when it is not. */
+  readonly present: boolean,
+|};
+
+const SidebarContext: React.Context<SidebarState | null> = createContext(null);
+
+/**
+ * The sidebar a part belongs to.
+ *
+ * Raising rather than returning null, for the reason `useDialog` gives: a
+ * `Sidebar.Trigger` outside a root would render a button with an
+ * `aria-expanded` that never changes, and it would look correct.
+ */
+hook useSidebar(part: string): SidebarState {
+  const state = useContext(SidebarContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Sidebar.Root`);
+  }
+  return state;
+}
+
+/**
+ * The sidebar, expanded or collapsed — and, on a narrow viewport, a sheet.
+ *
+ * Renders no element of its own when it is part of the page: the trigger and
+ * the navigation are siblings in whatever layout the caller wrote. When the
+ * viewport makes it modal it renders a `Sheet.Root` around both, so the trigger
+ * is the sheet's trigger and focus goes back to it — which is the half of the
+ * transition a wrapper around only the navigation could not do.
+ */
+export component SidebarRoot(
+  children: React.Node,
+  defaultOpen?: boolean = true,
+  narrowQuery?: string = NARROW,
+  onOpenChange?: (open: boolean) => void,
+  open?: boolean,
+  side?: SidebarSide = "left",
+) {
+  const base = useId();
+  const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
+  // `false` on the server: see the module header. The wide layout is the one
+  // that is still usable when there is no viewport to ask.
+  const modal = useMediaQuery(narrowQuery, false);
+
+  const state = useMemo(
+    () => ({
+      base,
+      collapsed: !modal && !isOpen,
+      modal,
+      open: isOpen,
+      // A sheet's navigation is in the document only while the sheet is open;
+      // the page's is always there, collapsed or not.
+      present: modal ? isOpen : true,
+      setOpen,
+      side,
+    }),
+    [base, isOpen, modal, setOpen, side],
+  );
+
+  return (
+    <SidebarContext.Provider value={state}>
+      {modal ? (
+        <SheetRoot onOpenChange={setOpen} open={isOpen} side={side}>
+          {children}
+        </SheetRoot>
+      ) : (
+        children
+      )}
+    </SidebarContext.Provider>
+  );
+}
+
+/**
+ * The button that expands and collapses it.
+ *
+ * `aria-expanded` either way, and it is a true sentence about two different
+ * things: on a wide screen it says whether the navigation is showing its
+ * labels, on a narrow one whether the sheet is open. `aria-controls` names the
+ * navigation only while the navigation is in the document — a reference to an
+ * id nothing has tells a reader there is somewhere to go and has nowhere to
+ * send them.
+ */
+export component SidebarTrigger(children: React.Node, ...rest: Rest) {
+  const sidebar = useSidebar("Sidebar.Trigger");
+  const passed = withoutComposed(rest, ["onClick"]);
+  const named = sidebar.present ? `${sidebar.base}-nav` : undefined;
+
+  // The sheet's own trigger while it is one: `Dialog.Trigger` is what records
+  // where focus came from, and focus going back to this button when the sheet
+  // closes is the second half of the transition.
+  if (sidebar.modal) {
+    // `Dialog.Trigger` names the sheet's own body while it is open, which is a
+    // better `aria-controls` than the navigation inside it, so this part adds
+    // nothing to it.
+    return <SheetTrigger {...forwarded(rest)}>{children}</SheetTrigger>;
+  }
+
+  return (
+    <button
+      {...passed}
+      aria-controls={named}
+      aria-expanded={sidebar.open ? "true" : "false"}
+      onClick={composeHandlers(rest.onClick, () => sidebar.setOpen(!sidebar.open))}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+/**
+ * The navigation itself: a named `<nav>` landmark, and on a narrow viewport a
+ * named `<nav>` landmark inside a modal sheet.
+ *
+ * A `<div>` here is the mistake the component exists to prevent. A `<nav>` is
+ * how a screen reader's landmark list offers "skip to the navigation", and a
+ * site's main navigation that is not one is navigation a reader has to find by
+ * tabbing through it.
+ *
+ * `label` is required rather than defaulted, because a landmark with no name is
+ * announced as "navigation" — and a page with two of those has told the reader
+ * there are two and which is which is a guess.
+ */
+export component SidebarBody(children: React.Node, label: string, ...rest: Rest) {
+  const sidebar = useSidebar("Sidebar.Body");
+  const nav = (
+    <nav
+      {...forwarded(rest)}
+      aria-label={label}
+      data-collapsed={sidebar.collapsed ? "true" : undefined}
+      id={`${sidebar.base}-nav`}
+    >
+      {children}
+    </nav>
+  );
+
+  if (!sidebar.modal) {
+    return nav;
+  }
+
+  // Named rather than titled: a heading nobody asked for would appear in the
+  // page's outline, and the sheet's name is the navigation's name.
+  return (
+    <>
+      <SheetOverlay />
+      <SheetBody aria-label={label}>{nav}</SheetBody>
+    </>
+  );
+}
+
+/** The top of the sidebar, as a place to put styles. See `Dialog.Header`. */
+export component SidebarHeader(children: React.Node, ...rest: Rest) {
+  return <div {...rest}>{children}</div>;
+}
+
+/** The bottom of the sidebar. See `Sidebar.Header`. */
+export component SidebarFooter(children: React.Node, ...rest: Rest) {
+  return <div {...rest}>{children}</div>;
+}
+
+/**
+ * One entry in the navigation, whose name survives the collapse.
+ *
+ * `label` is what the reader hears. While the sidebar is expanded the entry's
+ * own content is its name, so nothing is overridden and a label with an icon,
+ * a count and a second line reads as written. The moment it collapses,
+ * `aria-label` takes over — because at that point the text is whatever the
+ * stylesheet has done to it, and a promise about the accessible name cannot
+ * depend on that.
+ *
+ * `render` for an entry that is a link. Site navigation is links, and a
+ * `<button>` that navigates is a button a reader cannot open in a new tab; see
+ * `navigation-menu.js`, which is the same argument at the scale of a whole
+ * menu.
+ */
+export component SidebarItem(
+  children: React.Node,
+  label: string,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const sidebar = useSidebar("Sidebar.Item");
+  const passed = withoutComposed(rest, ["ref"]);
+  const mine: Rest = {
+    "aria-label": sidebar.collapsed ? label : undefined,
+    children,
+    "data-collapsed": sidebar.collapsed ? "true" : undefined,
+  };
+
+  const entry = (extra: Rest) => {
+    // `mine` on top, and the order is load-bearing now that a part's props
+    // carry its children: the collapsed branch hands this the props
+    // `Tooltip.Trigger` built, and those name `children` as `undefined`
+    // because that tooltip trigger has none of its own. Applied last, a named
+    // `undefined` would blank the entry.
+    const props = withProps(withProps(passed, extra), mine);
+    return render == null ? <button {...props} type="button" /> : render(props);
+  };
+
+  if (!sidebar.collapsed) {
+    return entry({ ref: rest.ref });
+  }
+
+  // The icon's name, shown. A reader who can see the rail and not read minds
+  // needs the same sentence `aria-label` gives everybody else, and a tooltip is
+  // the mechanism that already satisfies WCAG 1.4.13 in this package.
+  return (
+    <TooltipRoot>
+      <TooltipTrigger ref={rest.ref} render={(props: Rest) => entry(props)} />
+      <TooltipBody side={sidebar.side === "left" ? "right" : "left"}>{label}</TooltipBody>
+    </TooltipRoot>
+  );
+}