@uniflowed/ui 0.0.0-alpha.4 → 0.0.0-alpha.41

package/alert.js

@@ -0,0 +1,142 @@
+// @flow
+//
+// A callout, and the live region it must not be by default.
+//
+// Of the twenty components in the catalogue that look like a class list, this
+// is the one whose usual shape is arguably wrong to copy rather than merely
+// empty. Every version of it renders `<div role="alert">`, always, and that one
+// attribute is a decision about interrupting the reader that nobody made.
+//
+// # `role="alert"` is a live region, not a colour
+//
+// A live region announces *changes*. An element carrying one that is already in
+// the document when the page loads has no change to report, so it is announced
+// on insertion or it is not announced at all — and which of those you get is a
+// property of the moment the element entered the document, not of the element.
+//
+// So a permanently rendered "your trial ends soon" box with `role="alert"` is
+// one of two things, both bad:
+//
+//   * an **interruption on every page load**, on the engines that treat the
+//     initial render as an insertion — the reader is pulled out of whatever
+//     they were doing to hear a sentence that was equally true yesterday;
+//   * or **silence**, on the engines that do not — in which case the role was
+//     decoration, and the box is read in its ordinary place in the page like
+//     the `<div>` it is.
+//
+// Neither is what the author wanted, and neither is visible in a screenshot.
+// The two cases have to be told apart by the caller, because the caller is the
+// only one who knows which one they have:
+//
+//   * a **static callout** — a panel that is part of the page — is a container
+//     with a heading and no live semantics at all. It is read where a reader
+//     reaches it, and heading navigation finds it, which is what `Alert.Title`
+//     being a real heading is for.
+//   * an **alert** — something that appeared because something happened — is
+//     `live`, and is `role="alert"`.
+//
+// `field.js` already makes exactly this call for `Field.Error`, which is
+// rendered only once the field is wrong and is `role="alert"` for that reason.
+//
+// # Why `live` is a boolean and there is no polite option
+//
+// Because a polite one cannot be built this way, and offering it would be
+// offering silence. `combobox.js` states the rule: a live region added to the
+// page in the same commit as the text it holds is usually not announced,
+// because the technology watching it had nothing to watch until it was already
+// too late. `role="status"` is polite, so it is subject to that rule in full —
+// a polite region has to have been in the document *first*, empty, and a
+// component you render at the moment the thing happens never was.
+//
+// `role="alert"` is assertive, and assertive regions are announced on insertion
+// by every engine that implements them; that is what the role is for. So the
+// one live shape this component can honestly offer is the assertive one.
+//
+// The polite, page-level shape is `Toast`, which is the component that exists
+// to have been watching already — `toast.js` and ubugeeei-prod/uf#289. An
+// application that wants "saved" said politely wants a toast, not an alert, and
+// pointing at it is a better answer than a `live="polite"` that does nothing.
+//
+// # No `"use client"`
+//
+// It holds no state, listens to nothing and manages no focus. Which of the two
+// alerts this is arrived as a prop, and the heading level did too. It renders
+// on a server.
+
+import * as React from "@uniflowed/react";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { withProps } from "./internal/merge-props.js";
+
+/**
+ * A callout: a panel that is part of the page, or one that just appeared.
+ *
+ * `live` is the whole component. Without it there is no role, deliberately —
+ * a box a reader reaches in reading order needs no announcement, and giving it
+ * one costs an interruption on every page load or nothing at all. With it the
+ * container is `role="alert"`, which is assertive and therefore the one live
+ * shape that is announced when it is inserted with its text in it.
+ *
+ *     {error != null && (
+ *       <Alert.Root live>
+ *         <Alert.Title>Could not save</Alert.Title>
+ *         <Alert.Description>{error}</Alert.Description>
+ *       </Alert.Root>
+ *     )}
+ *
+ * Rendered unconditionally with `live` on it, this is the mistake the module
+ * header is about: the role is a promise about a change, and a box that was
+ * always there has no change to report.
+ */
+export component AlertRoot(
+  children: React.Node,
+  live?: boolean = false,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const props = withProps(rest, { children, role: live ? "alert" : undefined });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
+}
+
+/**
+ * The callout's heading.
+ *
+ * A real heading rather than a bold `<div>`, because a heading is how a screen
+ * reader user finds a region of a page without reading it — and a callout
+ * nobody can jump to is a callout that has to be walked into.
+ *
+ * `level` is the caller's for the reason `accordion.js` gives for the same
+ * prop: the level that keeps a document outline true depends on what the
+ * callout is inside, and a hard-coded one produces an outline nobody can
+ * navigate. The guess is stated rather than hidden — `3`, which is right for a
+ * callout inside a section that has a title of its own — and a level outside
+ * the six HTML has is clamped, because `<h7>` is not an element and is
+ * announced as nothing at all.
+ */
+export component AlertTitle(
+  children: React.Node,
+  level?: number = 3,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const clamped = Math.min(6, Math.max(1, Math.trunc(level)));
+  const Heading = `h${String(clamped)}`;
+  const props = withProps(rest, { children });
+
+  if (render != null) {
+    return render(withProps(props, { "aria-level": clamped, role: "heading" }));
+  }
+  return <Heading {...props} />;
+}
+
+/** What the callout says, under its heading. */
+export component AlertDescription(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { children });
+  if (render != null) {
+    return render(props);
+  }
+  return <p {...props} />;
+}

package/avatar.js

@@ -0,0 +1,280 @@
+// @flow
+//
+// An avatar: three states, and an `alt` that is empty on purpose.
+//
+// This one looks like a rounded `<img>` with a `<span>` behind it, and it is a
+// component because of two things that are not visible in a screenshot: what
+// happens between the states, and what a screen reader says.
+//
+// # The three states, and the flash between two of them
+//
+// An image is *loading*, *loaded* or *failed*, and the naive version has two —
+// there is an image or there is not — so it renders the fallback whenever the
+// image has not painted yet. On a cached image that is a flash of somebody's
+// initials for one frame, on every navigation, for ever. The fix is to hold the
+// fallback back for a moment: an image that is going to appear immediately does
+// so before the delay is up, and only an image that is genuinely slow or
+// genuinely broken ever shows initials.
+//
+// # Asking the DOM, and the one direction it may be asked in
+//
+// The event is not enough on its own. A cached image can finish loading before
+// React has attached `onLoad` — most obviously when the markup came from a
+// server and the browser started the request while the JavaScript was still
+// downloading — and a component that waits for an event that already happened
+// waits for ever, which is the same flash held permanently.
+//
+// So the element is asked directly, in an effect, which is where this package
+// is allowed to read the document (see `index.js`). And it is asked in *one*
+// direction:
+//
+//   * `complete` **and** `naturalWidth > 0` means it loaded. Pixels exist;
+//     nothing else produces them.
+//   * anything else means nothing. In particular `complete` with no pixels is
+//     *not* read as a failure, because that is also what a DOM that does not
+//     fetch images says about a perfectly good `src` — a test environment, a
+//     server-side render, a browser with images turned off — and concluding
+//     "failed" from it would put a fallback over an image that was never asked
+//     for. The `error` event is what says a load failed, and an image that
+//     failed before anything was listening falls through to the delay and shows
+//     the fallback a moment later, which is the same answer arriving late
+//     rather than the wrong answer arriving early.
+//
+// # `alt=""` is the default, and it is the accessible answer
+//
+// An avatar almost always sits beside the name of the person it is a picture
+// of. Putting that name in `alt` makes every screen reader say it twice —
+// "Ada Lovelace, image, Ada Lovelace" — which is the most common avatar bug
+// there is, and it is caused by a component being helpful. An empty `alt` takes
+// the image out of the accessibility tree, which is what "decorative" means and
+// what this one is.
+//
+// A caller whose avatar is the *only* thing identifying the person — a bare
+// grid of faces, a comment with no byline — passes `alt` and gets it. The
+// default is the common case; the prop is the honest one.
+//
+// The fallback's content is the caller's and is announced, because this
+// component cannot know whether "AL" is a decoration beside a name or the only
+// thing on the row. A decorative avatar wants `aria-hidden` on its fallback for
+// the same reason its image wants `alt=""`, and that is one prop the caller
+// spreads.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+import { useTimeout } from "@uniflowed/hooks/timing";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  withProps,
+  withoutComposed,
+} from "./internal/merge-props.js";
+
+/**
+ * Where an avatar's image is between having been asked for and being there.
+ *
+ * Three members rather than a `loaded` boolean, because the fallback's whole
+ * job is to tell the middle one from the last one: an image that has not
+ * arrived *yet* must not be replaced, and one that is never arriving must.
+ */
+export type AvatarStatus = "loading" | "loaded" | "error";
+
+/** What has been decided, and about which source. */
+type Seen = {| readonly source: string | null, readonly status: AvatarStatus |};
+
+/** Nothing asked yet. A source of `null` with no verdict cannot collide. */
+const START: Seen = Object.freeze({ source: null, status: "loading" });
+
+type AvatarState = {|
+  readonly status: AvatarStatus,
+  readonly hasImage: boolean,
+  readonly report: (source: string | null, status: AvatarStatus) => void,
+  readonly registerImage: (present: boolean) => void,
+|};
+
+const AvatarContext: React.Context<AvatarState | null> = createContext(null);
+
+/**
+ * The avatar a part belongs to.
+ *
+ * Raising rather than returning null, for `field.js`'s reason: an
+ * `Avatar.Fallback` outside a root would render initials that never go away and
+ * would look exactly like one that works.
+ */
+hook useAvatar(part: string): AvatarState {
+  const state = useContext(AvatarContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside an Avatar.Root`);
+  }
+  return state;
+}
+
+/**
+ * The avatar, and the state machine its two parts read.
+ *
+ * A `<span>` rather than a `<div>`, because an avatar belongs beside a name —
+ * in a table cell, in a paragraph, inside a button's label — and a block
+ * element is invalid in half of those.
+ */
+export component AvatarRoot(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const [seen, setSeen] = useState<Seen>(START);
+  const [hasImage, setHasImage] = useState(false);
+
+  const report = useCallback((source: string | null, status: AvatarStatus) => {
+    setSeen((current) => {
+      if (current.source !== source) {
+        return { source, status };
+      }
+      // A verdict already reached about this source is not revisited. Without
+      // this the failed image would be put back to ask again, fail again, and
+      // be put back again: `Avatar.Image` stops rendering the element once it
+      // has failed, so "loading" for the same source is a loop and not a retry.
+      if (status === "loading" || current.status === status) {
+        return current;
+      }
+      return { source, status };
+    });
+  }, []);
+
+  const state = useMemo(
+    () => ({
+      status: seen.status,
+      hasImage,
+      report,
+      registerImage: setHasImage,
+    }),
+    [seen, hasImage, report],
+  );
+  const props = withProps(rest, { children });
+
+  return (
+    <AvatarContext.Provider value={state}>
+      {render != null ? render(props) : <span {...props} />}
+    </AvatarContext.Provider>
+  );
+}
+
+/**
+ * The picture.
+ *
+ * `src` is named rather than left in `rest` because the state machine is about
+ * it: a new source is a new question, and the verdict reached about the last
+ * one has to stop applying the moment it changes.
+ *
+ * `alt` defaults to `""`, which is the decision this component exists for as
+ * much as the three states are — see the module header.
+ *
+ * The element stops being rendered once it has failed, rather than being left
+ * to show the browser's broken-image glyph beside the fallback that replaced
+ * it. That is a thing a package which ships no styles cannot leave to a
+ * stylesheet: `hidden` loses to any `display` the caller sets, and a caller who
+ * has not written that rule yet would see both.
+ */
+export component AvatarImage(
+  alt?: string = "",
+  src?: string | null,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const avatar = useAvatar("Avatar.Image");
+  const element = useRef<HTMLImageElement | null>(null);
+  const report = avatar.report;
+  const registerImage = avatar.registerImage;
+  const source = src ?? null;
+  const passed = withoutComposed(rest, ["onError", "onLoad", "ref"]);
+
+  useEffect(() => {
+    registerImage(true);
+    return () => registerImage(false);
+  }, [registerImage]);
+
+  useEffect(() => {
+    if (source == null || source === "") {
+      // No source is not a slow source. There is nothing coming, so the
+      // fallback is the answer now rather than after the delay.
+      report(source, "error");
+      return;
+    }
+    const image = element.current;
+    // Null only when this source has already failed and the element went with
+    // it, in which case the verdict on record is the right one.
+    if (image != null && image.complete && image.naturalWidth > 0) {
+      report(source, "loaded");
+      return;
+    }
+    report(source, "loading");
+  }, [report, source]);
+
+  if (avatar.status === "error") {
+    return null;
+  }
+  const props = withProps(passed, {
+    alt,
+    onError: composeHandlers(rest.onError, () => report(source, "error")),
+    onLoad: composeHandlers(rest.onLoad, () => report(source, "loaded")),
+    // React calls callback refs during commit; the load effect reads it later.
+    // uf-lint-disable-next-line react-compiler/refs
+    ref: composeRefs(rest.ref, (node: HTMLImageElement | null) => {
+      element.current = node;
+    }),
+    src: source ?? undefined,
+  });
+  if (render != null) {
+    return render(props);
+  }
+  return <img {...props} />;
+}
+
+/**
+ * What is shown instead: initials, a silhouette, a coloured disc.
+ *
+ * Absent while the image is still loading, which is the point. `delay` is how
+ * long "still loading" is allowed to last before the fallback appears anyway —
+ * long enough that a cached image never flashes initials, short enough that a
+ * genuinely slow one does not leave a hole. Pass `0` to show it the moment
+ * there is nothing to show instead.
+ *
+ * The delay applies to *loading* and to nothing else. A failed image and an
+ * avatar with no `Avatar.Image` at all are both answers rather than waits, and
+ * the fallback for either is immediate.
+ */
+export component AvatarFallback(
+  children: React.Node,
+  delay?: number = 300,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const avatar = useAvatar("Avatar.Fallback");
+  const [elapsed, setElapsed] = useState(false);
+  const waiting = avatar.hasImage && avatar.status === "loading";
+
+  useTimeout(() => setElapsed(true), waiting && delay > 0 ? delay : null);
+
+  useEffect(() => {
+    if (!waiting) {
+      // The fallback delay resets after the image leaves its loading window.
+      // uf-lint-disable-next-line react-compiler/set-state-in-effect
+      setElapsed(false);
+    }
+  }, [waiting]);
+
+  if (avatar.status === "loaded" || (waiting && delay > 0 && !elapsed)) {
+    return null;
+  }
+  const props = withProps(rest, { children });
+  if (render != null) {
+    return render(props);
+  }
+  return <span {...props} />;
+}

package/breadcrumb.js

@@ -0,0 +1,138 @@
+// @flow
+//
+// A breadcrumb trail, read as a trail rather than as punctuation.
+//
+// It is `pagination.js`'s shape — a named `<nav>` around a list, with one item
+// marked `aria-current="page"` — and it is a separate module for the same
+// reason those two are separate entries: a paginated table and a trail through
+// a hierarchy are different things to a reader, and the parts are named after
+// what they mean rather than after what they render.
+//
+// Three decisions, 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
+//     nothing to tell it from the site's menu. `aria-label="Breadcrumb"` is
+//     what puts it in a screen reader's landmark list under a useful name, and
+//     it is the name assistive technology's own documentation tells readers to
+//     look for.
+//   * **The last item is `aria-current="page"`, and it is not a link.** It is
+//     where the reader already is. A trail whose last entry is a link that
+//     leads to the page it is on is a link that does nothing, and announcing
+//     "link" for it is a promise the page does not keep — so `Breadcrumb.Page`
+//     is a `<span>`. The `role="link"` with `aria-disabled` that this component
+//     is usually copied with says "link, dimmed", which is a *control the
+//     reader cannot use* rather than a place they have arrived at.
+//   * **The separators are `aria-hidden`.** Otherwise the trail is read as
+//     "Home slash Settings slash Billing", and the slashes are the loudest
+//     thing in it. They are `<li>` elements because an `<ol>` may only contain
+//     `<li>`, and they carry `role="presentation"` as well so that the count a
+//     reader is given — "list, three items" — is the number of places and not
+//     the number of places plus the punctuation between them.
+//
+// # What the type says that the markup cannot
+//
+// `Breadcrumb.List` declares `renders* (Breadcrumb.Item | Breadcrumb.Separator)`,
+// so a `<div>` between two crumbs is a type error rather than an `<ol>` a
+// validator would reject and a screen reader would count wrong.
+// `Pagination.Content` states the same constraint for the same element and the
+// same reason.
+//
+// # No `"use client"`
+//
+// Nothing here holds state, listens to anything or moves focus. Which crumb is
+// current is the caller's, and the links are links. It renders on a server.
+
+import * as React from "@uniflowed/react";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { withProps } from "./internal/merge-props.js";
+
+/**
+ * The trail, as a named landmark.
+ *
+ * `label` is the accessible name and has a default because there is one right
+ * answer in English and it is the one readers are taught to look for. Pass it
+ * to translate; there is no case for leaving it off, which is why it is not
+ * optional in the sense of being absent.
+ */
+export component BreadcrumbRoot(
+  children: React.Node,
+  label?: string = "Breadcrumb",
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const props = withProps(rest, { "aria-label": label, children });
+  if (render != null) {
+    return render(withProps(props, { role: "navigation" }));
+  }
+  return <nav {...props} />;
+}
+
+/**
+ * The crumbs, in order.
+ *
+ * An ordered list rather than a row of links, because the order is the whole
+ * information: a reader is told how many levels there are before walking them,
+ * and can skip the lot in one keystroke.
+ */
+export component BreadcrumbList(
+  children: renders* (BreadcrumbItem | BreadcrumbSeparator),
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const props = withProps(rest, { children });
+  if (render != null) {
+    return render(withProps(props, { role: "list" }));
+  }
+  return <ol {...props} />;
+}
+
+/** One level of the trail. Holds a `Breadcrumb.Link` or a `Breadcrumb.Page`. */
+export component BreadcrumbItem(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { children });
+  if (render != null) {
+    return render(withProps(props, { role: "listitem" }));
+  }
+  return <li {...props} />;
+}
+
+/** A level you can go back to. */
+export component BreadcrumbLink(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { children });
+  if (render != null) {
+    return render(withProps(props, { role: "link" }));
+  }
+  return <a {...props} />;
+}
+
+/**
+ * The level you are on.
+ *
+ * `aria-current="page"` is the whole of it, and it is on this part rather than
+ * being a `current` prop on `Breadcrumb.Link` so that the last crumb cannot be
+ * a link by accident. See the module header for why announcing it as a disabled
+ * link is worse than announcing it as text.
+ */
+export component BreadcrumbPage(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { "aria-current": "page", children });
+  if (render != null) {
+    return render(props);
+  }
+  return <span {...props} />;
+}
+
+/**
+ * The mark between two crumbs.
+ *
+ * The glyph is the caller's — a slash, a chevron, an icon — because it is a
+ * design decision and this package makes none. What is not the caller's is that
+ * it is announced to nobody.
+ */
+export component BreadcrumbSeparator(children?: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { "aria-hidden": "true", children, role: "presentation" });
+  if (render != null) {
+    return render(props);
+  }
+  return <li {...props} />;
+}