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

package/pagination.js

@@ -0,0 +1,209 @@
+// @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 { RenderProp, Rest } from "./internal/merge-props.js";
+import { withProps, 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,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const message =
+    page == null || pageCount == null ? "" : (announcePage ?? defaultAnnouncement)(page, pageCount);
+  const props = withProps(rest, { "aria-label": label, children });
+
+  return (
+    <>
+      {render == null ? <nav {...props} /> : render(withProps(props, { role: "navigation" }))}
+      {/*
+        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),
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const props = withProps(rest, { children });
+  if (render != null) {
+    return render(withProps(props, { role: "list" }));
+  }
+  return <ul {...props} />;
+}
+
+/**
+ * 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,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  return (
+    <PageLink current={current} disabled={disabled} render={render} 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,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  return (
+    <PageLink disabled={disabled} label={label} render={render} 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,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  return (
+    <PageLink disabled={disabled} label={label} render={render} 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,
+  render?: RenderProp,
+) {
+  const passed = withoutComposed(rest, disabled ? ["href"] : []);
+  const props = withProps(passed, {
+    "aria-current": current ? "page" : undefined,
+    "aria-disabled": disabled ? "true" : undefined,
+    "aria-label": label,
+    children,
+  });
+
+  if (render != null) {
+    return <li>{render(withProps(props, { role: disabled ? undefined : "link" }))}</li>;
+  }
+
+  return (
+    <li>
+      <a {...props} />
+    </li>
+  );
+}
+
+/** The wording used when the caller supplies none. */
+function defaultAnnouncement(page: number, pageCount: number): string {
+  return `Page ${String(page)} of ${String(pageCount)}.`;
+}

package/popover.js

@@ -0,0 +1,343 @@
+// @flow
+//
+// A popover: a dialog that is not modal, which is the whole of the difference.
+//
+// `dialog.js` is modal and only modal, on purpose — every line of it is a
+// promise that the rest of the page is unavailable. A popover makes the
+// opposite promise, and it has to make it in every one of the same places:
+//
+//   * No `aria-modal`, because the page behind is still there.
+//   * Nothing is made `inert` and nothing is `aria-hidden`, because a reader
+//     may still reach it.
+//   * The page is not scroll-locked, because a wheel over a popover scrolling
+//     the page behind is what a reader expects from something that did not
+//     take the page over.
+//   * **`Tab` leaves.** This is the load-bearing one. A trap is what makes a
+//     modal dialog safe and what makes a popover a hole a reader falls into:
+//     they tabbed in, they tab out, and a component that wraps them back to
+//     the first control has taken the page away without ever saying so.
+//
+// So a popover is not a `Dialog` with a flag. A flag would mean every one of
+// the behaviours above reading it, and the failure of the one that forgot would
+// be a dialog that is not modal while announcing that it is — silent, and
+// wrong in the direction that traps people.
+//
+// What it *does* share with a dialog is the part a reader notices when it is
+// missing: focus moves into it when it opens, `Escape` closes it, and focus
+// goes back to the trigger — unless the reader dismissed it by pressing or
+// tabbing somewhere else, in which case it stays where they put it.
+//
+// # Where it goes
+//
+// `internal/anchor.js`, the same as every other overlay here: `side`, `align`,
+// `sideOffset` and `alignOffset` place it against the trigger, it flips and
+// slides to stay on the screen, and it reports where it ended up as `data-side`
+// and `data-align` so a stylesheet can point an arrow without measuring
+// anything itself.
+//
+// # Its name
+//
+// `role="dialog"` needs an accessible name, and a popover has no `Title` part
+// to take one from — shadcn's does not either, and adding one would make the
+// common case (a form, a colour picker, a date picker) carry a heading nobody
+// asked for. So the body is named after the button that opened it, which is
+// true and is what a reader would say the popover is, and a caller who passes
+// `aria-label` or `aria-labelledby` of their own keeps it.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+import { useStableCallback } from "@uniflowed/hooks/lifecycle";
+
+import type { Align, LogicalSide } from "./internal/anchor.js";
+import type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  withProps,
+  withoutComposed,
+} from "./internal/merge-props.js";
+import { focusable } from "./internal/focus.js";
+import { useAnchor } from "./internal/anchor.js";
+import { useControlled } from "./internal/controlled-state.js";
+import { usePresence } from "./internal/disclosure.js";
+
+export type { Align, LogicalSide, Side } from "./internal/anchor.js";
+
+type PopoverState = {|
+  readonly base: string,
+  readonly open: boolean,
+  readonly setOpen: (open: boolean) => void,
+  /** What opened it, where it is anchored, and where focus goes back to. */
+  readonly triggerRef: { current: HTMLElement | null },
+  /**
+   * Whether a trigger is rendered, so the body only names one that exists.
+   *
+   * A popover opened by `defaultOpen` in a page with no trigger is a real
+   * arrangement — a first-run hint pointing at something — and an
+   * `aria-labelledby` naming the id that trigger *would* have had makes a
+   * screen reader announce nothing at all.
+   */
+  readonly triggered: boolean,
+  readonly registerTrigger: (present: boolean) => void,
+|};
+
+const PopoverContext: React.Context<PopoverState | null> = createContext(null);
+
+/**
+ * The popover a part belongs to.
+ *
+ * Raising rather than returning null, for the reason `useDialog` gives: a
+ * `Popover.Body` outside a root would render a `role="dialog"` that nothing
+ * opens, closes or names, and it would look correct.
+ */
+hook usePopover(part: string): PopoverState {
+  const state = useContext(PopoverContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Popover.Root`);
+  }
+  return state;
+}
+
+/**
+ * The popover, open or closed. Uncontrolled unless `open` is given.
+ *
+ * Renders no element of its own: the trigger and the body are siblings in
+ * whatever layout the caller wrote, and a wrapper would put a `<div>` between
+ * them for the caller to style around.
+ */
+export component PopoverRoot(
+  children: React.Node,
+  defaultOpen?: boolean = false,
+  open?: boolean,
+  onOpenChange?: (open: boolean) => void,
+) {
+  const base = useId();
+  const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const [triggered, setTriggered] = useState(false);
+
+  const state = useMemo(
+    () => ({
+      base,
+      open: isOpen,
+      registerTrigger: setTriggered,
+      setOpen,
+      triggerRef,
+      triggered,
+    }),
+    [base, isOpen, setOpen, triggered],
+  );
+
+  return <PopoverContext.Provider value={state}>{children}</PopoverContext.Provider>;
+}
+
+/**
+ * The button that opens the popover, and what it is anchored to.
+ *
+ * A toggle rather than an opener: pressing the button of an open popover closes
+ * it, which is what every disclosure does and what a reader who pressed it by
+ * accident expects. The outside-press handler in `Popover.Body` knows the
+ * trigger is not "outside" for exactly this reason — closing there and letting
+ * this click reopen made the press a no-op that flickered.
+ */
+export component PopoverTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const popover = usePopover("Popover.Trigger");
+  const passed = withoutComposed(rest, ["onClick", "ref"]);
+  usePresence(popover.registerTrigger);
+  const props = withProps(passed, {
+    // Only while it is open: an `aria-controls` naming an element that is not
+    // in the document tells a reader there is somewhere to go and then has
+    // nowhere to send them.
+    "aria-controls": popover.open ? `${popover.base}-body` : undefined,
+    "aria-expanded": popover.open ? "true" : "false",
+    "aria-haspopup": "dialog",
+    children,
+    id: `${popover.base}-trigger`,
+    onClick: composeHandlers(rest.onClick, () => popover.setOpen(!popover.open)),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      popover.triggerRef.current = element;
+    }),
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
+}
+
+/**
+ * The popover itself: positioned, focused, dismissible, and not a trap.
+ *
+ * The three ways out are the three a reader tries. `Escape` closes it and gives
+ * focus back to the trigger, because the reader is still where they were. A
+ * press outside closes it and leaves focus alone, because they have already
+ * moved on. `Tab` past the last control inside closes it for the same reason
+ * and leaves focus where the browser put it — which is the behaviour that
+ * separates this from a dialog, and the one a copy of `dialog.js` with the
+ * `aria-modal` deleted would get wrong.
+ */
+export component PopoverBody(
+  children: React.Node,
+  align?: Align = "center",
+  alignOffset?: number = 0,
+  avoidCollisions?: boolean = true,
+  collisionPadding?: number = 0,
+  /**
+   * Where focus lands when it opens, when the first focus stop is the wrong
+   * answer. The same prop `Dialog.Body` takes, deliberately spelled the same
+   * way: `DatePicker.Calendar` fills it with the day that holds the grid's tab
+   * stop, because a reader who opened a date picker is looking for the date and
+   * not for the button that steps back a month.
+   */
+  initialFocus?: { current: HTMLElement | null },
+  render?: RenderProp,
+  side?: LogicalSide = "bottom",
+  sideOffset?: number = 0,
+  ...rest: Rest
+) {
+  const popover = usePopover("Popover.Body");
+  const bodyRef = useRef<HTMLElement | null>(null);
+  // Stable, so the effect below depends on `open` and on nothing else. Keyed on
+  // `setOpen` it re-ran whenever the caller passed a fresh `onOpenChange`
+  // closure — which is every render — and re-running it took focus back from
+  // wherever the reader had moved it inside the popover.
+  const close = useStableCallback(() => popover.setOpen(false));
+  // Set when the reader left rather than closed: a press outside, or a Tab that
+  // carried them out. Focus is theirs from then on, and dragging it back to the
+  // trigger would undo the thing they just did.
+  const left = useRef(false);
+  const triggerRef = popover.triggerRef;
+
+  const anchored = useAnchor({
+    align,
+    alignOffset,
+    anchorRef: triggerRef,
+    avoidCollisions,
+    collisionPadding,
+    open: popover.open,
+    overlayRef: bodyRef,
+    side,
+    sideOffset,
+  });
+
+  useEffect(() => {
+    const body = bodyRef.current;
+    if (!popover.open || body == null) {
+      return;
+    }
+    const document = body.ownerDocument;
+    const trigger = triggerRef.current;
+    // Whatever had focus, which is the trigger for a popover that was opened
+    // and the previously focused element for one that opened itself.
+    const opener = trigger ?? (document.activeElement as $FlowFixMe);
+
+    const outside = (target: EventTarget | null): boolean => {
+      const node: $FlowFixMe = target;
+      // The trigger is outside the body and is not "outside" for this purpose.
+      return node != null && !body.contains(node) && !(trigger?.contains(node) ?? false);
+    };
+
+    const onOutsidePress = (event: Event) => {
+      if (!outside(event.target)) {
+        return;
+      }
+      left.current = true;
+      close();
+    };
+    // Capture, so a press is seen even where something below it stops the
+    // event — a menu inside the popover, for instance.
+    document.addEventListener("pointerdown", onOutsidePress, true);
+
+    // Tab out is a dismissal, not an escape hatch that leaves a popover open
+    // behind the reader: a non-modal overlay whose reader has gone is one they
+    // can no longer press Escape at, because Escape is handled where focus is.
+    const onFocusMoved = (event: Event) => {
+      if (!outside(event.target)) {
+        return;
+      }
+      left.current = true;
+      close();
+    };
+    document.addEventListener("focusin", onFocusMoved, true);
+
+    // Where the caller said, then the first thing worth acting on, then the
+    // popover itself when it holds nothing focusable - so focus is inside it
+    // whichever of the three answers, and Escape reaches the handler below.
+    //
+    // The named element has to still be *in* this popover, for the reason
+    // `dialog.js` gives at the same line: a ref left from a previous opening
+    // would move focus somewhere the reader did not open.
+    const named = initialFocus?.current ?? null;
+    ((named != null && body.contains(named) ? named : focusable(body)[0]) ?? body).focus();
+
+    return () => {
+      document.removeEventListener("pointerdown", onOutsidePress, true);
+      document.removeEventListener("focusin", onFocusMoved, true);
+      if (left.current) {
+        left.current = false;
+        return;
+      }
+      // Only when focus would otherwise be lost to `<body>`, the same
+      // condition `menu.js` restores under: a popover closed by a control
+      // inside it that moved focus somewhere deliberate must not have that
+      // undone.
+      const active = document.activeElement;
+      if (active == null || active === document.body || body.contains(active)) {
+        opener?.focus?.();
+      }
+    };
+  }, [popover.open, triggerRef, close, initialFocus]);
+
+  if (!popover.open) {
+    return null;
+  }
+
+  const passed = withoutComposed(rest, ["onKeyDown", "ref"]);
+  // Named by its trigger unless the caller said otherwise. Setting it anyway
+  // would override an `aria-label` they passed — `aria-labelledby` wins — and
+  // leave the popover announced as its button rather than as itself.
+  const named = rest["aria-label"] != null || rest["aria-labelledby"] != null;
+
+  const props = withProps(passed, {
+    "aria-labelledby": named || !popover.triggered ? undefined : `${popover.base}-trigger`,
+    children,
+    "data-align": anchored.align,
+    "data-side": anchored.side,
+    "data-state": "open",
+    id: `${popover.base}-body`,
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      if (event.key !== "Escape") {
+        return;
+      }
+      event.preventDefault();
+      // This popover, not the dialog around it. Two overlays nest in the
+      // DOM, so without this one Escape closed both.
+      event.stopPropagation();
+      close();
+    }),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      bodyRef.current = element;
+    }),
+    // No `aria-modal`. The page behind a popover is still available, and
+    // saying otherwise is the one lie a screen reader cannot see through.
+    role: "dialog",
+    // So the popover can hold focus itself when it contains nothing focusable,
+    // and so Escape has somewhere to be heard.
+    tabIndex: -1,
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
+}

package/progress.js

@@ -0,0 +1,91 @@
+// @flow
+//
+// A progress bar, whose one line is the line everybody gets wrong.
+//
+// This is the smallest component in the package and the one most often written
+// inline, which is exactly why it is worth owning: `<div className="bar" />`
+// with a width in a style attribute is invisible to a screen reader, and the
+// version that adds a role usually adds the rest of it wrong.
+//
+// # The indeterminate state
+//
+// A progress bar that does not know how far along it is **omits
+// `aria-valuenow` entirely**. It does not set it to `0`.
+//
+// The two are opposite statements. `aria-valuenow="0"` says "nothing has
+// happened yet", and a reader who asks again in ten seconds and hears zero
+// again concludes the operation is stuck. Omitting it says "in progress,
+// amount unknown", which is what a spinner means and what is actually true.
+// The whole component is a conditional, and this is the condition.
+//
+// # `aria-valuetext`, for when the percentage is not the answer
+//
+// "3 of 10 files" is what a reader wants to hear; "30" is a number they then
+// have to do arithmetic on. `aria-valuetext` replaces the announced value
+// without touching `aria-valuenow`, so the assistive technology still has the
+// number to draw a gauge with and the reader still hears the sentence.
+//
+// It is a prop rather than something a caller adds afterwards because
+// `aria-valuenow` and `aria-valuetext` have to agree, and a caller spreading
+// one of them onto a component that owns the other gets a control that says
+// two different things.
+//
+// # No `"use client"`
+//
+// It holds no state, listens to nothing and manages no focus, so it renders on
+// a server. That is the reason this is a component and not a hook: everything
+// it knows, it was told.
+
+import * as React from "@uniflowed/react";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { withProps } from "./internal/merge-props.js";
+import { clamp } from "./internal/range.js";
+
+/**
+ * How far along something is, or that it is under way at all.
+ *
+ * `value` is `null` for a bar that does not know — the default, because a bar
+ * that has not been told anything genuinely does not know, and the safe answer
+ * has to be the honest one rather than "nothing has happened".
+ *
+ * A name is the caller's: `aria-label="Uploading"` or an `aria-labelledby`
+ * pointing at a heading. A progress bar with no name is announced as
+ * "progressbar" and a reader is left to guess what is progressing, which is
+ * why every example in the documentation carries one.
+ *
+ * Nothing here is drawn and nothing is measured for the caller — unlike
+ * `Slider`, whose value may be its own, a progress bar's value arrived as a
+ * prop, so the caller already has everything they need to size a bar with and
+ * a helpful custom property would only be their own arithmetic handed back.
+ *
+ * `render` changes the element and not the accessibility contract: the
+ * progressbar role and value attributes are the props handed to the caller.
+ */
+export component Progress(
+  value?: number | null = null,
+  min?: number = 0,
+  max?: number = 100,
+  valueText?: string,
+  children?: React.Node,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const known = value == null ? null : clamp(value, min, max);
+  const props = withProps(rest, {
+    "aria-valuemax": max,
+    "aria-valuemin": min,
+    // Omitted, not zeroed. `aria-valuenow="0"` tells a reader that nothing
+    // has happened; leaving it out tells them the amount is unknown, which
+    // is the true one and the one a spinner means.
+    "aria-valuenow": known ?? undefined,
+    "aria-valuetext": valueText,
+    children,
+    role: "progressbar",
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
+}