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

package/radio-group.js

@@ -76,8 +76,13 @@
 import * as React from "@uniflowed/react";
 import { createContext, useCallback, useContext, useId, useMemo, useRef } from "@uniflowed/react";
 
-import type { Rest } from "./internal/merge-props.js";
-import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
+import type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  withoutComposed,
+  withProps,
+} from "./internal/merge-props.js";
 import { moveOnKey, useFirstItem } from "./internal/roving-focus.js";
 import type { Orientation, RovingSet } from "./internal/roving-focus.js";
 import { useControlled } from "./internal/controlled-state.js";
@@ -146,6 +151,7 @@ export component RadioGroupRoot(
   onValueChange?: (value: string) => void,
   orientation?: Orientation = "vertical",
   name?: string,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   // `onValueChange` promises a `string` while the group's *state* is
@@ -171,44 +177,46 @@ export component RadioGroupRoot(
 
   const state = useMemo(() => ({ selected, select, firstId }), [selected, select, firstId]);
   const passed = withoutComposed(rest, ["onKeyDown", "ref"]);
+  const content = (
+    <>
+      {children}
+      {/*
+        A form submits `<input>` elements, and none of the parts above is one.
+        Without this the group is a control a reader can operate and a form
+        cannot read, which is the same hole `Combobox` still has.
+
+        `type="hidden"` rather than a visually hidden real radio, because the
+        buttons above already carry the whole of the accessible semantics: a
+        second set of native radios would be announced as a second set of
+        answers, and hiding them from the accessibility tree to stop that
+        leaves elements a form's own validation would then point its
+        "please choose one" at.
+      */}
+      {name == null ? null : <input name={name} type="hidden" value={selected ?? ""} />}
+    </>
+  );
+  const props = withProps(passed, {
+    "aria-orientation": orientation,
+    children: content,
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      const group: $FlowFixMe = event.currentTarget;
+      const next = moveOnKey(event, group, radioSet(orientation));
+      if (next != null) {
+        // Checking in the same key press is not a shortcut, it is the
+        // pattern: a radio group whose arrows moved focus without checking
+        // leaves a reader believing they have answered when they have not.
+        select(next.getAttribute("data-value") ?? "");
+      }
+    }),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      rootRef.current = element;
+    }),
+    role: "radiogroup",
+  });
 
   return (
     <RadioGroupContext.Provider value={state}>
-      <div
-        {...passed}
-        // A reader is told which axis this runs along, and it is also what says
-        // which pair of arrow keys is live.
-        aria-orientation={orientation}
-        onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-          const group: $FlowFixMe = event.currentTarget;
-          const next = moveOnKey(event, group, radioSet(orientation));
-          if (next != null) {
-            // Checking in the same key press is not a shortcut, it is the
-            // pattern: a radio group whose arrows moved focus without checking
-            // leaves a reader believing they have answered when they have not.
-            select(next.getAttribute("data-value") ?? "");
-          }
-        })}
-        ref={composeRefs(rest.ref, (element) => {
-          rootRef.current = element;
-        })}
-        role="radiogroup"
-      >
-        {children}
-        {/*
-          A form submits `<input>` elements, and none of the parts above is one.
-          Without this the group is a control a reader can operate and a form
-          cannot read, which is the same hole `Combobox` still has.
-
-          `type="hidden"` rather than a visually hidden real radio, because the
-          buttons above already carry the whole of the accessible semantics: a
-          second set of native radios would be announced as a second set of
-          answers, and hiding them from the accessibility tree to stop that
-          leaves elements a form's own validation would then point its
-          "please choose one" at.
-        */}
-        {name == null ? null : <input name={name} type="hidden" value={selected ?? ""} />}
-      </div>
+      {render == null ? <div {...props} /> : render(props)}
     </RadioGroupContext.Provider>
   );
 }
@@ -226,6 +234,7 @@ export component RadioGroupItem(
   value: string,
   children?: React.Node,
   disabled?: boolean = false,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const group = useRadioGroup("RadioGroup.Item");
@@ -233,41 +242,39 @@ export component RadioGroupItem(
   const checked = group.selected === value;
   const item = useMemo(() => ({ checked }), [checked]);
   const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
+  const props = withProps(passed, {
+    "aria-checked": checked ? "true" : "false",
+    "aria-disabled": disabled ? "true" : undefined,
+    // Read by the group's key handler, which finds items in the document
+    // rather than in a registry and so needs each one to carry its value.
+    "data-value": value,
+    children,
+    id,
+    onClick: composeHandlers(rest.onClick, (_event: PartEvent) => {
+      if (!disabled) {
+        group.select(value);
+      }
+    }),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      if (disabled || event.key !== " ") {
+        return;
+      }
+      // Stops `Space` scrolling the page — which is what makes a
+      // hand-written radio feel broken even when it works — and stops the
+      // browser's own click arriving afterwards to check this again.
+      event.preventDefault();
+      group.select(value);
+    }),
+    role: "radio",
+    // The roving tab stop: the chosen answer, or the first one while there
+    // is no answer, so `Tab` reaches the group in either state and leaves
+    // it in one press.
+    tabIndex: checked || (group.selected == null && group.firstId === id) ? 0 : -1,
+  });
 
   return (
     <RadioItemContext.Provider value={item}>
-      <button
-        {...passed}
-        aria-checked={checked ? "true" : "false"}
-        aria-disabled={disabled ? "true" : undefined}
-        // Read by the group's key handler, which finds items in the document
-        // rather than in a registry and so needs each one to carry its value.
-        data-value={value}
-        id={id}
-        onClick={composeHandlers(rest.onClick, () => {
-          if (!disabled) {
-            group.select(value);
-          }
-        })}
-        onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-          if (disabled || event.key !== " ") {
-            return;
-          }
-          // Stops `Space` scrolling the page — which is what makes a
-          // hand-written radio feel broken even when it works — and stops the
-          // browser's own click arriving afterwards to check this again.
-          event.preventDefault();
-          group.select(value);
-        })}
-        role="radio"
-        // The roving tab stop: the chosen answer, or the first one while there
-        // is no answer, so `Tab` reaches the group in either state and leaves
-        // it in one press.
-        tabIndex={checked || (group.selected == null && group.firstId === id) ? 0 : -1}
-        type="button"
-      >
-        {children}
-      </button>
+      {render == null ? <button {...props} type="button" /> : render(props)}
     </RadioItemContext.Provider>
   );
 }
@@ -282,7 +289,7 @@ export component RadioGroupItem(
  * `[aria-checked="true"] > *`, and so the "only while chosen" part is not
  * something each caller reimplements.
  */
-export component RadioGroupIndicator(children?: React.Node, ...rest: Rest) {
+export component RadioGroupIndicator(children?: React.Node, render?: RenderProp, ...rest: Rest) {
   const item = useContext(RadioItemContext);
   if (item == null) {
     throw new Error("RadioGroup.Indicator must be rendered inside a RadioGroup.Item");
@@ -290,9 +297,6 @@ export component RadioGroupIndicator(children?: React.Node, ...rest: Rest) {
   if (!item.checked) {
     return null;
   }
-  return (
-    <span {...rest} aria-hidden="true">
-      {children}
-    </span>
-  );
+  const props = withProps(rest, { "aria-hidden": "true", children });
+  return render == null ? <span {...props} /> : render(props);
 }

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

@@ -43,7 +43,7 @@
 import * as React from "@uniflowed/react";
 import { createContext, useContext, useMemo } from "@uniflowed/react";
 
-import type { Rest } from "./internal/merge-props.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
 import { forwarded } from "./internal/merge-props.js";
 import {
   DialogBody,
@@ -110,17 +110,21 @@ export component SheetRoot(
 }
 
 /** What opens it, and what focus comes back to when it closes. */
-export component SheetTrigger(children: React.Node, ...rest: Rest) {
-  return <DialogTrigger {...forwarded(rest)}>{children}</DialogTrigger>;
+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(...rest: Rest) {
+export component SheetOverlay(render?: RenderProp, ...rest: Rest) {
   const sheet = useSheet("Sheet.Overlay");
-  return <DialogOverlay {...forwarded(rest)} data-side={sheet.side} />;
+  return <DialogOverlay {...forwarded(rest)} data-side={sheet.side} render={render} />;
 }
 
 /**
@@ -129,37 +133,57 @@ export component SheetOverlay(...rest: Rest) {
  * 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, ...rest: Rest) {
+export component SheetBody(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const sheet = useSheet("Sheet.Body");
 
   return (
-    <DialogBody {...forwarded(rest)} data-side={sheet.side}>
+    <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, ...rest: Rest) {
-  return <DialogHeader {...forwarded(rest)}>{children}</DialogHeader>;
+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, ...rest: Rest) {
-  return <DialogFooter {...forwarded(rest)}>{children}</DialogFooter>;
+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, ...rest: Rest) {
-  return <DialogTitle {...forwarded(rest)}>{children}</DialogTitle>;
+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, ...rest: Rest) {
-  return <DialogDescription {...forwarded(rest)}>{children}</DialogDescription>;
+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, ...rest: Rest) {
-  return <DialogClose {...forwarded(rest)}>{children}</DialogClose>;
+export component SheetClose(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogClose {...forwarded(rest)} render={render}>
+      {children}
+    </DialogClose>
+  );
 }

package/sidebar.js

@@ -55,7 +55,7 @@ import * as React from "@uniflowed/react";
 import { createContext, useContext, useId, useMemo } from "@uniflowed/react";
 import { useMediaQuery } from "@uniflowed/hooks/browser";
 
-import type { Rest } from "./internal/merge-props.js";
+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";
@@ -263,25 +263,25 @@ export component SidebarFooter(children: React.Node, ...rest: Rest) {
 export component SidebarItem(
   children: React.Node,
   label: string,
-  render?: (props: Rest) => React.Node,
+  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) => {
-    const props = withProps(withProps(passed, mine), extra);
-    return render == null ? (
-      <button {...props} type="button">
-        {children}
-      </button>
-    ) : (
-      render(props)
-    );
+    // `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) {

package/skeleton.js

@@ -0,0 +1,159 @@
+// @flow
+//
+// A loading placeholder, and the reader it is usually invisible to.
+//
+// A skeleton is the one component on the presentational list that silently
+// makes a page *worse*. A screen of grey rounded rectangles tells a sighted
+// reader that content is coming and something is happening. To everybody else
+// it is a screen of empty `<div>`s: nothing is announced, nothing is described,
+// and the honest summary of the page is that it has no content — which is
+// exactly the conclusion somebody reaches before they leave.
+//
+// Three attributes fix it and none of them is on the grey box:
+//
+//   * the skeletons themselves are **`aria-hidden="true"`**, because a
+//     placeholder is a picture of content and not content;
+//   * the region they stand in is **`aria-busy="true"`**, which is the
+//     attribute that says "this is being filled in" and stops assistive
+//     technology reporting a half-built subtree;
+//   * and something has to **say so out loud**, because `aria-busy` is a
+//     property a reader can ask about rather than an announcement they are
+//     given.
+//
+// # The live region, and why it is empty for one commit
+//
+// This is ubugeeei-prod/uf#289's rule met at the worst possible moment.
+// `combobox.js` states it: 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.
+//
+// A skeleton screen is busy on its *first* render. So the naive version —
+// render `<div role="status">Loading…</div>` while `pending` — mounts the
+// region with the sentence already in it and is silent, then unmounts the whole
+// thing when the content arrives and is silent again. It announces nothing,
+// ever, which is the same as not having been written.
+//
+// `Skeleton.Root` therefore renders the region empty and fills it in an effect,
+// one commit later. The region existed before the text did, which is the whole
+// of what the rule asks for, and it costs a second commit on mount and nothing
+// afterwards.
+//
+// # Keep the root mounted across the load
+//
+// Which is the one thing this component asks of a caller, and the reason
+// `busy` is a prop rather than the root's presence. A root that is unmounted
+// when the content arrives takes its live region with it, so "loaded" is said
+// to nobody and the reader is left with the last thing they heard, which was
+// "loading". Wrap the thing that loads and toggle `busy`; that is also what
+// lets `aria-busy` go from true to false on one element, which is what it is
+// for.
+//
+// # Not `Progress`
+//
+// A skeleton says *that* something is loading. `Progress` says *how far along*
+// it is, has `aria-valuenow` and lives in `progress.js`. A skeleton with a
+// percentage is a progress bar that has been drawn as boxes, and a progress bar
+// with no number is the indeterminate one that module already ships.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { useEffect, useRef, useState } from "@uniflowed/react";
+
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { withProps } from "./internal/merge-props.js";
+
+/**
+ * The region that is being filled in, and the sentence that says so.
+ *
+ * `children` is the skeletons while `busy`, and the real content once it is
+ * not — both go inside, because it is one region either way and `aria-busy`
+ * describes it in both states.
+ *
+ *     <Skeleton.Root busy={pending}>
+ *       {pending ? (
+ *         <>
+ *           <Skeleton.Box />
+ *           <Skeleton.Box />
+ *         </>
+ *       ) : (
+ *         <Invoices rows={invoices} />
+ *       )}
+ *     </Skeleton.Root>
+ *
+ * `label` and `doneLabel` are what is announced. English defaults, because a
+ * component that announces nothing by default is the component this one exists
+ * to replace; a real application passes its translation.
+ *
+ * `doneLabel` is announced only after a spell of `busy`, so a region that was
+ * never loading never says it has loaded.
+ *
+ * `render` changes the element that owns the busy state. The live region stays
+ * beside it, mounted by this component, because that timing is the accessibility
+ * contract rather than markup the caller can safely recreate by sight.
+ */
+export component SkeletonRoot(
+  children: React.Node,
+  busy?: boolean = true,
+  label?: string = "Loading…",
+  doneLabel?: string = "Loaded",
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const [message, setMessage] = useState("");
+  // Whether there has been anything to finish. Written and read in effects
+  // only, and nothing renders it — the promise `index.js` makes about refs.
+  const waited = useRef(false);
+
+  useEffect(() => {
+    if (busy) {
+      waited.current = true;
+      setMessage(label);
+      return;
+    }
+    setMessage(waited.current ? doneLabel : "");
+  }, [busy, doneLabel, label]);
+
+  const props = withProps(rest, {
+    "aria-busy": busy ? "true" : undefined,
+    children,
+  });
+
+  return (
+    <>
+      {render == null ? <div {...props} /> : render(props)}
+      {/*
+        Beside the region rather than inside it, so a reader walking into the
+        content does not find a sentence about it sitting among the rows — and
+        mounted from the first render holding nothing, because a live region
+        that appears together with its text is not announced at all. The module
+        header says why that matters more here than anywhere else.
+      */}
+      <div aria-atomic="true" aria-live="polite" data-uf-skeleton-status="" role="status">
+        {message}
+      </div>
+    </>
+  );
+}
+
+/**
+ * One grey box.
+ *
+ * `aria-hidden="true"`, which is the entire component: a placeholder is a
+ * picture of content, and content it is not. Everything about its size, its
+ * shape and its shimmer is a class name the caller brings.
+ *
+ * `children` is allowed and is hidden with the rest of it, because sizing a
+ * box by putting the text it stands in for inside it is a real technique and
+ * there is no reason to make a caller reach for a second element to do it.
+ *
+ * `render` changes the placeholder element, not the fact that it is hidden
+ * from the accessibility tree.
+ */
+export component SkeletonBox(children?: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { "aria-hidden": "true", children });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
+}