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

package/accordion.js

@@ -90,8 +90,13 @@ import {
   useState,
 } 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,
+  withProps,
+  withoutComposed,
+} from "./internal/merge-props.js";
 import { moveOnKey } from "./internal/roving-focus.js";
 import type { RovingSet } from "./internal/roving-focus.js";
 import { useMeasuredHeight, usePresence, useUntilFound } from "./internal/disclosure.js";
@@ -176,6 +181,7 @@ export component AccordionRoot(
   value?: $ReadOnlyArray<string>,
   onValueChange?: (value: $ReadOnlyArray<string>) => void,
   measure?: boolean = false,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const [open, setOpen] = useControlled<$ReadOnlyArray<string>>(value, defaultValue, onValueChange);
@@ -203,22 +209,20 @@ export component AccordionRoot(
     () => ({ open, toggle, closable: type === "multiple" || collapsible, type, measure }),
     [open, toggle, type, collapsible, measure],
   );
-  const passed = withoutComposed(rest, ["onKeyDown"]);
+  const props = withProps(withoutComposed(rest, ["onKeyDown"]), {
+    children,
+    // The name the arrow keys use to tell this accordion's headers from those
+    // of an accordion nested inside one of its panels.
+    "data-accordion": "",
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      const stack: $FlowFixMe = event.currentTarget;
+      moveOnKey(event, stack, HEADERS);
+    }),
+  });
 
   return (
     <AccordionContext.Provider value={state}>
-      <div
-        {...passed}
-        // The name the arrow keys use to tell this accordion's headers from
-        // those of an accordion nested inside one of its panels.
-        data-accordion=""
-        onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-          const stack: $FlowFixMe = event.currentTarget;
-          moveOnKey(event, stack, HEADERS);
-        })}
-      >
-        {children}
-      </div>
+      {render == null ? <div {...props} /> : render(props)}
     </AccordionContext.Provider>
   );
 }
@@ -235,6 +239,7 @@ export component AccordionItem(
   value: string,
   children: renders* (AccordionHeader | AccordionContent),
   disabled?: boolean = false,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const accordion = useAccordion("Accordion.Item");
@@ -257,9 +262,11 @@ export component AccordionItem(
     [base, open, toggle, value, accordion.closable, disabled, present],
   );
 
+  const props = withProps(rest, { children });
+
   return (
     <AccordionItemContext.Provider value={state}>
-      <div {...rest}>{children}</div>
+      {render == null ? <div {...props} /> : render(props)}
     </AccordionItemContext.Provider>
   );
 }
@@ -290,35 +297,34 @@ export component AccordionHeader(
  * It carries no `tabIndex` of its own on purpose: every header stays in the
  * page's tab order, which is what makes this an accordion and not a tab list.
  */
-export component AccordionTrigger(children: React.Node, ...rest: Rest) {
+export component AccordionTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const item = useAccordionItem("Accordion.Trigger");
-  const passed = withoutComposed(rest, ["onClick"]);
   // Locked and disabled are two different sentences a reader hears the same
   // way, and both are `aria-disabled` rather than `disabled` so the header
   // stays where they can find it: "this section will not close" and "this
   // section is unavailable".
   const inert = item.locked || item.disabled;
 
-  return (
-    <button
-      {...passed}
-      aria-controls={item.present ? item.contentId : undefined}
-      aria-disabled={inert ? "true" : undefined}
-      aria-expanded={item.open ? "true" : "false"}
-      // What the arrow keys look for. Not a role, because the accordion pattern
-      // has none to look for; see the module header.
-      data-accordion-trigger=""
-      id={item.triggerId}
-      onClick={composeHandlers(rest.onClick, () => {
-        if (!inert) {
-          item.toggle();
-        }
-      })}
-      type="button"
-    >
-      {children}
-    </button>
-  );
+  const props = withProps(withoutComposed(rest, ["onClick"]), {
+    "aria-controls": item.present ? item.contentId : undefined,
+    "aria-disabled": inert ? "true" : undefined,
+    "aria-expanded": item.open ? "true" : "false",
+    children,
+    // What the arrow keys look for. Not a role, because the accordion pattern
+    // has none to look for; see the module header.
+    "data-accordion-trigger": "",
+    id: item.triggerId,
+    onClick: composeHandlers(rest.onClick, () => {
+      if (!inert) {
+        item.toggle();
+      }
+    }),
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
 }
 
 /**
@@ -327,7 +333,7 @@ export component AccordionTrigger(children: React.Node, ...rest: Rest) {
  * `internal/disclosure.js` explains what "stays in the document" is worth and
  * what `hidden` is upgraded to for it.
  */
-export component AccordionContent(children: React.Node, ...rest: Rest) {
+export component AccordionContent(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const accordion = useAccordion("Accordion.Content");
   const item = useAccordionItem("Accordion.Content");
   const contentRef = useRef<HTMLElement | null>(null);
@@ -335,19 +341,20 @@ export component AccordionContent(children: React.Node, ...rest: Rest) {
   useUntilFound(contentRef, item.open);
   useMeasuredHeight(contentRef, accordion.measure);
 
-  return (
-    <div
-      {...withoutComposed(rest, ["ref"])}
-      // The name a reader hears for this landmark is the header they pressed.
-      aria-labelledby={item.triggerId}
-      hidden={!item.open}
-      id={item.contentId}
-      ref={composeRefs(rest.ref, (element) => {
-        contentRef.current = element;
-      })}
-      role="region"
-    >
-      {children}
-    </div>
-  );
+  const props = withProps(withoutComposed(rest, ["ref"]), {
+    // The name a reader hears for this landmark is the header they pressed.
+    "aria-labelledby": item.triggerId,
+    children,
+    hidden: !item.open,
+    id: item.contentId,
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      contentRef.current = element;
+    }),
+    role: "region",
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
 }

package/alert-dialog.js

@@ -46,7 +46,7 @@
 import * as React from "@uniflowed/react";
 import { createContext, useContext, useEffect, useMemo, useRef } from "@uniflowed/react";
 
-import type { Rest } from "./internal/merge-props.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
 import { composeRefs, forwarded, withoutComposed } from "./internal/merge-props.js";
 import {
   DialogBody,
@@ -118,13 +118,17 @@ export component AlertDialogRoot(
 }
 
 /** What opens it, and what focus comes back to when it closes. */
-export component AlertDialogTrigger(children: React.Node, ...rest: Rest) {
-  return <DialogTrigger {...forwarded(rest)}>{children}</DialogTrigger>;
+export component AlertDialogTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogTrigger {...forwarded(rest)} render={render}>
+      {children}
+    </DialogTrigger>
+  );
 }
 
 /** The backdrop. See `Dialog.Overlay`: it is decoration and says so. */
-export component AlertDialogOverlay(...rest: Rest) {
-  return <DialogOverlay {...forwarded(rest)} />;
+export component AlertDialogOverlay(render?: RenderProp, ...rest: Rest) {
+  return <DialogOverlay {...forwarded(rest)} render={render} />;
 }
 
 /**
@@ -136,7 +140,7 @@ export component AlertDialogOverlay(...rest: Rest) {
  * who set two of them would have an alert dialog that is wrong in the third
  * without anything saying so.
  */
-export component AlertDialogBody(children: React.Node, ...rest: Rest) {
+export component AlertDialogBody(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const alert = useAlertDialog("AlertDialog.Body");
 
   return (
@@ -144,6 +148,7 @@ export component AlertDialogBody(children: React.Node, ...rest: Rest) {
       {...forwarded(rest)}
       dismissOnOutsidePress={false}
       initialFocus={alert.cancelRef}
+      render={render}
       role="alertdialog"
     >
       {children}
@@ -184,18 +189,30 @@ component RequireDescription() {
 }
 
 /** The top of the alert dialog. See `Dialog.Header` for why it is a `div`. */
-export component AlertDialogHeader(children: React.Node, ...rest: Rest) {
-  return <DialogHeader {...forwarded(rest)}>{children}</DialogHeader>;
+export component AlertDialogHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogHeader {...forwarded(rest)} render={render}>
+      {children}
+    </DialogHeader>
+  );
 }
 
 /** The bottom, where `Action` and `Cancel` go. */
-export component AlertDialogFooter(children: React.Node, ...rest: Rest) {
-  return <DialogFooter {...forwarded(rest)}>{children}</DialogFooter>;
+export component AlertDialogFooter(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogFooter {...forwarded(rest)} render={render}>
+      {children}
+    </DialogFooter>
+  );
 }
 
 /** The question, which is the alert dialog's accessible name. */
-export component AlertDialogTitle(children: React.Node, ...rest: Rest) {
-  return <DialogTitle {...forwarded(rest)}>{children}</DialogTitle>;
+export component AlertDialogTitle(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogTitle {...forwarded(rest)} render={render}>
+      {children}
+    </DialogTitle>
+  );
 }
 
 /**
@@ -205,7 +222,7 @@ export component AlertDialogTitle(children: React.Node, ...rest: Rest) {
  * exists to deliver, and the only moment the reader has to decide whether they
  * care is before they have pressed anything.
  */
-export component AlertDialogDescription(children: React.Node, ...rest: Rest) {
+export component AlertDialogDescription(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const alert = useAlertDialog("AlertDialog.Description");
   const describedBy = alert.describedBy;
 
@@ -216,7 +233,11 @@ export component AlertDialogDescription(children: React.Node, ...rest: Rest) {
     };
   }, [describedBy]);
 
-  return <DialogDescription {...forwarded(rest)}>{children}</DialogDescription>;
+  return (
+    <DialogDescription {...forwarded(rest)} render={render}>
+      {children}
+    </DialogDescription>
+  );
 }
 
 /**
@@ -227,8 +248,12 @@ export component AlertDialogDescription(children: React.Node, ...rest: Rest) {
  * are made of, so the composition rule about a caller's `onClick` has one
  * implementation rather than a second copy here.
  */
-export component AlertDialogAction(children: React.Node, ...rest: Rest) {
-  return <DialogClose {...forwarded(rest)}>{children}</DialogClose>;
+export component AlertDialogAction(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  return (
+    <DialogClose {...forwarded(rest)} render={render}>
+      {children}
+    </DialogClose>
+  );
 }
 
 /**
@@ -238,7 +263,7 @@ export component AlertDialogAction(children: React.Node, ...rest: Rest) {
  * without the caller wiring a ref: the least destructive action is a fact about
  * which part this is, not a decision to be repeated at every call.
  */
-export component AlertDialogCancel(children: React.Node, ...rest: Rest) {
+export component AlertDialogCancel(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const alert = useAlertDialog("AlertDialog.Cancel");
   const cancelRef = alert.cancelRef;
   const passed = withoutComposed(rest, ["ref"]);
@@ -249,6 +274,7 @@ export component AlertDialogCancel(children: React.Node, ...rest: Rest) {
       ref={composeRefs(rest.ref, (element: HTMLElement | null) => {
         cancelRef.current = element;
       })}
+      render={render}
     >
       {children}
     </DialogClose>

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} />;
+}