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

package/tabs.js

@@ -50,8 +50,8 @@ import {
   useState,
 } from "@uniflowed/react";
 
-import type { Rest } from "./internal/merge-props.js";
-import { composeHandlers, withoutComposed } from "./internal/merge-props.js";
+import type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
+import { composeHandlers, withProps, withoutComposed } from "./internal/merge-props.js";
 import { moveOnKey } from "./internal/roving-focus.js";
 import { useControlled } from "./internal/controlled-state.js";
 import type { Orientation } from "./internal/roving-focus.js";
@@ -94,6 +94,7 @@ export component TabsRoot(
   onValueChange?: (value: string) => void,
   activationMode?: ActivationMode = "automatic",
   orientation?: Orientation = "horizontal",
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const base = useId();
@@ -125,9 +126,11 @@ export component TabsRoot(
     [base, selected, select, orientation, activationMode, mounted, registerPanel],
   );
 
+  const props = withProps(rest, { children });
+
   return (
     <TabsContext.Provider value={state}>
-      <div {...rest}>{children}</div>
+      {render == null ? <div {...props} /> : render(props)}
     </TabsContext.Provider>
   );
 }
@@ -142,38 +145,37 @@ export component TabsRoot(
  * tabs push themselves into as they mount answers with mount order, which stops
  * being document order the first time a tab is conditional.
  */
-export component TabsList(children: renders* TabsTab, ...rest: Rest) {
+export component TabsList(children: renders* TabsTab, render?: RenderProp, ...rest: Rest) {
   const tabs = useTabs("Tabs.List");
-  const passed = withoutComposed(rest, ["onKeyDown"]);
+  const props = withProps(withoutComposed(rest, ["onKeyDown"]), {
+    // A screen reader announces the axis, and it is also what tells a reader
+    // which arrow keys to try.
+    "aria-orientation": tabs.orientation,
+    children,
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      const list: $FlowFixMe = event.currentTarget;
+      // The list the key arrived on carries the answer to both halves of
+      // this: which items there are, and which way the page reads — so a tab
+      // set inside somebody else's `dir="rtl"` walks the right way without
+      // the caller having had to know it needed to say so.
+      const next = moveOnKey(event, list, {
+        item: '[role="tab"]',
+        owner: '[role="tablist"]',
+        orientation: tabs.orientation,
+        wrap: true,
+        skipDisabled: true,
+      });
+      if (next != null && tabs.activation === "automatic") {
+        tabs.select(next.getAttribute("data-value") ?? "");
+      }
+    }),
+    role: "tablist",
+  });
 
-  return (
-    <div
-      {...passed}
-      // A screen reader announces the axis, and it is also what tells a reader
-      // which arrow keys to try.
-      aria-orientation={tabs.orientation}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        const list: $FlowFixMe = event.currentTarget;
-        // The list the key arrived on carries the answer to both halves of
-        // this: which items there are, and which way the page reads — so a tab
-        // set inside somebody else's `dir="rtl"` walks the right way without
-        // the caller having had to know it needed to say so.
-        const next = moveOnKey(event, list, {
-          item: '[role="tab"]',
-          owner: '[role="tablist"]',
-          orientation: tabs.orientation,
-          wrap: true,
-          skipDisabled: true,
-        });
-        if (next != null && tabs.activation === "automatic") {
-          tabs.select(next.getAttribute("data-value") ?? "");
-        }
-      })}
-      role="tablist"
-    >
-      {children}
-    </div>
-  );
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
 }
 
 /**
@@ -188,54 +190,55 @@ export component TabsTab(
   value: string,
   children: React.Node,
   disabled?: boolean = false,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const tabs = useTabs("Tabs.Tab");
   const active = tabs.selected === value;
-  const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
+  // The caller's props first, and everything this component owns after them. A
+  // caller `onClick` used to replace the selection handler, so clicking a tab
+  // did nothing at all. `render` is handed this same object in this same
+  // order, which is why a tab rendered as somebody else's element is not a
+  // weaker tab.
+  const props = withProps(withoutComposed(rest, ["onClick", "onKeyDown"]), {
+    "aria-disabled": disabled ? "true" : undefined,
+    // Only when the panel is actually mounted. Panels are rendered on demand,
+    // and a tab pointing `aria-controls` at an id that is not in the document
+    // tells a reader there is somewhere to go and then has nowhere to send
+    // them.
+    "aria-controls": tabs.mounted.includes(value) ? `${tabs.base}-panel-${value}` : undefined,
+    "aria-selected": active ? "true" : "false",
+    children,
+    // Read by the list's key handler, which finds tabs in the document rather
+    // than in a registry and so needs each one to carry its own value.
+    "data-value": value,
+    id: `${tabs.base}-tab-${value}`,
+    onClick: composeHandlers(rest.onClick, () => {
+      if (!disabled) {
+        tabs.select(value);
+      }
+    }),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      // Manual activation's other half: the arrows moved focus here without
+      // selecting, and this is how the reader says they meant it.
+      if (event.key !== "Enter" && event.key !== " ") {
+        return;
+      }
+      event.preventDefault();
+      if (!disabled) {
+        tabs.select(value);
+      }
+    }),
+    role: "tab",
+    // The roving tabindex: Tab reaches the selected tab and nothing else in
+    // the list, so it moves past the whole set in one press.
+    tabIndex: active ? 0 : -1,
+  });
 
-  return (
-    <button
-      // `passed` first, and everything this component owns after it. A caller
-      // `onClick` used to replace the selection handler, so clicking a tab did
-      // nothing at all.
-      {...passed}
-      aria-disabled={disabled ? "true" : undefined}
-      // Only when the panel is actually mounted. Panels are rendered on demand,
-      // and a tab pointing `aria-controls` at an id that is not in the document
-      // tells a reader there is somewhere to go and then has nowhere to send
-      // them.
-      aria-controls={tabs.mounted.includes(value) ? `${tabs.base}-panel-${value}` : undefined}
-      aria-selected={active ? "true" : "false"}
-      // Read by the list's key handler, which finds tabs in the document rather
-      // than in a registry and so needs each one to carry its own value.
-      data-value={value}
-      id={`${tabs.base}-tab-${value}`}
-      onClick={composeHandlers(rest.onClick, () => {
-        if (!disabled) {
-          tabs.select(value);
-        }
-      })}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        // Manual activation's other half: the arrows moved focus here without
-        // selecting, and this is how the reader says they meant it.
-        if (event.key !== "Enter" && event.key !== " ") {
-          return;
-        }
-        event.preventDefault();
-        if (!disabled) {
-          tabs.select(value);
-        }
-      })}
-      role="tab"
-      // The roving tabindex: Tab reaches the selected tab and nothing else in
-      // the list, so it moves past the whole set in one press.
-      tabIndex={active ? 0 : -1}
-      type="button"
-    >
-      {children}
-    </button>
-  );
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
 }
 
 /**
@@ -246,7 +249,12 @@ export component TabsTab(
  * subscription rather than "the selected value equals mine", because a caller
  * may render a subset of panels, or none at all until data arrives.
  */
-export component TabsPanel(value: string, children: React.Node, ...rest: Rest) {
+export component TabsPanel(
+  value: string,
+  children: React.Node,
+  render?: RenderProp,
+  ...rest: Rest
+) {
   const tabs = useTabs("Tabs.Panel");
   const register = tabs.registerPanel;
   const selected = tabs.selected === value;
@@ -263,18 +271,19 @@ export component TabsPanel(value: string, children: React.Node, ...rest: Rest) {
     return null;
   }
 
-  return (
-    <div
-      {...rest}
-      aria-labelledby={`${tabs.base}-tab-${value}`}
-      id={`${tabs.base}-panel-${value}`}
-      role="tabpanel"
-      // The panel itself is focusable so that Tab out of the tab list lands on
-      // the content the tab describes, which is where the reader expects to go
-      // and where a panel of plain prose has nothing else to offer.
-      tabIndex={0}
-    >
-      {children}
-    </div>
-  );
+  const props = withProps(rest, {
+    "aria-labelledby": `${tabs.base}-tab-${value}`,
+    children,
+    id: `${tabs.base}-panel-${value}`,
+    role: "tabpanel",
+    // The panel itself is focusable so that Tab out of the tab list lands on
+    // the content the tab describes, which is where the reader expects to go
+    // and where a panel of plain prose has nothing else to offer.
+    tabIndex: 0,
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
 }

package/toast.js

@@ -92,16 +92,18 @@
 //
 // `toast("Saved")` is called from an event handler, from a `catch`, from a
 // Server Action's error path — none of which have a component to put state in.
-// So the queue is a store in this module, read through `useSyncExternalStore`,
-// which is what `ubugeeei-redundancy.md` requires of an external store: cached
-// immutable snapshots, and a server snapshot consistent with them. Nothing here
-// is a mutable array a render reads.
+// So the queue is an atom in `@uniflowed/state`, declared at module scope and
+// written by the four module functions below. The live region reads it through
+// React's external-store hook via `read` and `subscribe`, deliberately against
+// the default store: a function in a module has no context with which to find a
+// scoped store, and letting a nearby `<Provider>` redirect the region would
+// split `toast()` from the place that displays it.
 //
-// Three properties are what that hook is actually asking for, and the store
-// below has those three and nothing more:
+// Three properties are what the hook is actually asking for, and the atom gives
+// this module those three without a second store implementation:
 //
 // - *An immutable snapshot whose reference changes only on a write.* The
-//   getter hands back the array it is holding rather than building one, and a
+//   atom holds the array itself rather than building one on every read, and a
 //   write that computes the value already there is dropped rather than
 //   announced. A getter that returns a fresh `[]` is a new identity every time
 //   React asks, which renders, which asks again — the infinite loop React
@@ -117,38 +119,10 @@
 // of notifications. A queue something could scope to a subtree would leave a
 // region showing an empty stack while `toast()` filled up a store it had no
 // way to find.
-//
-// # Why this is not an atom in `@uniflowed/state`
-//
-// It was one, and it should be one again. A queue read through
-// `useSyncExternalStore` is exactly what an atom is for, `@uniflowed/state` is
-// what this project offers instead of Jotai, and the version of this file that
-// imported `atom`, `read`, `subscribe` and `write` was not making a mistake.
-//
-// It cannot ship that way today. `@uniflowed/ui` is published to npm and
-// `@uniflowed/state` is not: its name has never been bound, binding it takes a
-// person with an `npm login` session and a 2FA prompt, and that is
-// ubugeeei-prod/uf#210. Until it happens the package waits in
-// `tools/release/pending-packages.txt`. A published package whose dependency
-// is missing installs as nothing — `ETARGET` on the first thing a user types —
-// so `tools/release/verify-npm.sh` refuses to release `@uniflowed/ui` while it
-// declares that dependency, and it is right to refuse.
-//
-// So the store below is the shippable design rather than the better one. It is
-// a second implementation of something this repository already has, written
-// out by hand because the first one cannot be installed. When #210 binds the
-// name and `state` moves into `published-packages.txt`, this goes back to an
-// atom and this section goes with it.
-//
-// This is the first `useSyncExternalStore` in this package, and `index.js` says
-// the package deliberately does not use one. That sentence is about reading
-// *layout* during a render, which is what the DOM-measuring components here
-// avoid by writing what they measured into state from an effect. A queue that
-// lives outside React is the case the API is for, and `index.js` now says both
-// things.
 
 "use client";
 
+import { atom, read, subscribe, write } from "@uniflowed/state";
 import * as React from "@uniflowed/react";
 import {
   createContext,
@@ -215,15 +189,16 @@ const DEFAULT_DURATION = 5000;
 const NONE: $ReadOnlyArray<Notification> = Object.freeze([]);
 
 /**
- * The queue, and what is watching it.
+ * The queue atom.
  *
  * Module scope is the requirement rather than a convenience: `toast()` has
- * nowhere else to put this. It costs a server nothing — importing this file
- * allocates one frozen array and one empty `Set` and starts no work, and
- * nothing on a server calls `toast()`, because this module is `"use client"`.
+ * nowhere else to put this. It costs a server little — importing this file
+ * declares one atom over one frozen array and starts no work, and nothing on a
+ * server calls `toast()`, because this module is `"use client"`.
  */
-let queue: $ReadOnlyArray<Notification> = NONE;
-const watchers: Set<() => void> = new Set();
+const queueAtom = atom<$ReadOnlyArray<Notification>>(NONE, {
+  debugLabel: "ui.toastQueue",
+});
 
 /**
  * Replace the queue, and wake what is watching it.
@@ -244,16 +219,12 @@ const watchers: Set<() => void> = new Set();
 function writeQueue(
   change: (current: $ReadOnlyArray<Notification>) => $ReadOnlyArray<Notification>,
 ): void {
-  const next = change(queue);
-  if (next === queue) {
+  const current = read(queueAtom);
+  const next = change(current);
+  if (next === current) {
     return;
   }
-  queue = next;
-  for (const watcher of Array.from(watchers)) {
-    if (watchers.has(watcher)) {
-      watcher();
-    }
-  }
+  write(queueAtom, next);
 }
 
 /** Ids are this module's, because `useId` needs a component and `toast()` is not one. */
@@ -330,10 +301,7 @@ export function dismissAllToasts(): void {
 
 /** Module-level and therefore stable, which is what stops React re-subscribing. */
 function subscribeToQueue(listener: () => void): () => void {
-  watchers.add(listener);
-  return () => {
-    watchers.delete(listener);
-  };
+  return subscribe(queueAtom, listener);
 }
 
 /**
@@ -346,7 +314,7 @@ function subscribeToQueue(listener: () => void): () => void {
  * `"use client"`.
  */
 function readQueue(): $ReadOnlyArray<Notification> {
-  return queue;
+  return read(queueAtom);
 }
 
 const NotificationContext: React.Context<Notification | null> = createContext(null);

package/toggle-group.js

@@ -60,11 +60,12 @@ import {
   useState,
 } from "@uniflowed/react";
 
-import type { Rest } from "./internal/merge-props.js";
+import type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
 import {
   composeHandlers,
   composeRefs,
   forwarded,
+  withProps,
   withoutComposed,
 } from "./internal/merge-props.js";
 import { moveOnKey, useFirstItem } from "./internal/roving-focus.js";
@@ -134,6 +135,7 @@ export component ToggleGroupRoot(
   value?: $ReadOnlyArray<string>,
   onValueChange?: (value: $ReadOnlyArray<string>) => void,
   orientation?: Orientation = "horizontal",
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const [pressed, setPressed] = useControlled<$ReadOnlyArray<string>>(
@@ -180,6 +182,7 @@ export component ToggleGroupRoot(
           {...forwarded(rest)}
           onValueChange={chooseOne}
           orientation={orientation}
+          render={render}
           value={pressed[0] ?? null}
         >
           {children}
@@ -189,26 +192,25 @@ export component ToggleGroupRoot(
   }
 
   const passed = withoutComposed(rest, ["onKeyDown", "ref"]);
+  const rootProps = withProps(passed, {
+    "aria-orientation": orientation,
+    children,
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      const group: $FlowFixMe = event.currentTarget;
+      // Moves and nothing else. Pressing every button the arrows pass over
+      // is what a `single` group does, and doing it here would apply half a
+      // dozen commands on the way to the one the reader wanted.
+      moveOnKey(event, group, toggleSet(orientation));
+    }),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      rootRef.current = element;
+    }),
+    role: "group",
+  });
 
   return (
     <ToggleGroupContext.Provider value={state}>
-      <div
-        {...passed}
-        aria-orientation={orientation}
-        onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-          const group: $FlowFixMe = event.currentTarget;
-          // Moves and nothing else. Pressing every button the arrows pass over
-          // is what a `single` group does, and doing it here would apply half a
-          // dozen commands on the way to the one the reader wanted.
-          moveOnKey(event, group, toggleSet(orientation));
-        })}
-        ref={composeRefs(rest.ref, (element) => {
-          rootRef.current = element;
-        })}
-        role="group"
-      >
-        {children}
-      </div>
+      {render != null ? render(rootProps) : <div {...rootProps} />}
     </ToggleGroupContext.Provider>
   );
 }
@@ -225,6 +227,7 @@ export component ToggleGroupItem(
   value: string,
   children?: React.Node,
   disabled?: boolean = false,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const group = useToggleGroup("ToggleGroup.Item");
@@ -237,7 +240,7 @@ export component ToggleGroupItem(
     // arrow keys that check as they move all belong to the radio group that
     // `ToggleGroup.Root` rendered around this.
     return (
-      <RadioGroupItem {...forwarded(rest)} disabled={disabled} value={value}>
+      <RadioGroupItem {...forwarded(rest)} disabled={disabled} render={render} value={value}>
         {children}
       </RadioGroupItem>
     );
@@ -246,35 +249,35 @@ export component ToggleGroupItem(
   const on = group.pressed.includes(value);
   const passed = withoutComposed(rest, ["onClick", "onFocus", "onKeyDown"]);
   const setActiveId = group.setActiveId;
-
-  return (
-    <button
-      {...passed}
-      aria-disabled={disabled ? "true" : undefined}
-      aria-pressed={on ? "true" : "false"}
-      id={id}
-      onClick={composeHandlers(rest.onClick, () => {
-        if (!disabled) {
-          group.toggle(value);
-        }
-      })}
-      // The roving tab stop follows real focus rather than leading it, so a
-      // pointer that moves focus and an arrow key that moves focus agree
-      // without the two having to be kept in step by hand.
-      onFocus={composeHandlers(rest.onFocus, () => setActiveId(id))}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        if (disabled || (event.key !== " " && event.key !== "Enter")) {
-          return;
-        }
-        // Stops `Space` scrolling the page, and stops the browser's own click
-        // arriving afterwards and pressing this back to where it started.
-        event.preventDefault();
+  const itemProps = withProps(passed, {
+    "aria-disabled": disabled ? "true" : undefined,
+    "aria-pressed": on ? "true" : "false",
+    children,
+    id,
+    onClick: composeHandlers(rest.onClick, (_event: PartEvent) => {
+      if (!disabled) {
         group.toggle(value);
-      })}
-      tabIndex={group.activeId === id || (group.activeId == null && group.firstId === id) ? 0 : -1}
-      type="button"
-    >
-      {children}
-    </button>
-  );
+      }
+    }),
+    // The roving tab stop follows real focus rather than leading it, so a
+    // pointer that moves focus and an arrow key that moves focus agree
+    // without the two having to be kept in step by hand.
+    onFocus: composeHandlers(rest.onFocus, (_event: PartEvent) => setActiveId(id)),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      if (disabled || (event.key !== " " && event.key !== "Enter")) {
+        return;
+      }
+      // Stops `Space` scrolling the page, and stops the browser's own click
+      // arriving afterwards and pressing this back to where it started.
+      event.preventDefault();
+      group.toggle(value);
+    }),
+    tabIndex: group.activeId === id || (group.activeId == null && group.firstId === id) ? 0 : -1,
+  });
+
+  if (render != null) {
+    return render(withProps(itemProps, { role: "button" }));
+  }
+
+  return <button {...itemProps} type="button" />;
 }

package/toggle.js

@@ -44,49 +44,62 @@
 
 import * as React from "@uniflowed/react";
 
-import type { Rest } from "./internal/merge-props.js";
-import { composeHandlers, withoutComposed } from "./internal/merge-props.js";
+import type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
+import { composeHandlers, withProps, withoutComposed } from "./internal/merge-props.js";
 import { useControlled } from "./internal/controlled-state.js";
 
-/** A button whose state stays applied: pressed or not. */
+/**
+ * A button whose state stays applied: pressed or not.
+ *
+ * `render` is the escape hatch. A caller-rendered element gets `role="button"`
+ * because it may be a link or a `div`; the native button branch keeps the role
+ * implicit and only adds `type="button"`, which is true of the element rather
+ * than of the toggle behaviour.
+ */
 export component Toggle(
   pressed?: boolean,
   defaultPressed?: boolean = false,
   onPressedChange?: (pressed: boolean) => void,
   disabled?: boolean = false,
   children?: React.Node,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const [on, setOn] = useControlled(pressed, defaultPressed, onPressedChange);
   const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
+  const semantics = {
+    "aria-pressed": on ? "true" : "false",
+    children,
+    disabled,
+    onClick: composeHandlers(rest.onClick, (_event: PartEvent) => {
+      if (!disabled) {
+        setOn(!on);
+      }
+    }),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      if (disabled || (event.key !== " " && event.key !== "Enter")) {
+        return;
+      }
+      // Preventing the default stops `Space` scrolling the page, and stops
+      // the browser's own click arriving after this handler and pressing the
+      // button a second time — back to where it started, which reads as the
+      // key having done nothing at all.
+      event.preventDefault();
+      setOn(!on);
+    }),
+  };
+
+  if (render != null) {
+    return render(withProps(passed, { ...semantics, role: "button" }));
+  }
 
   return (
     <button
-      {...passed}
+      {...withProps(passed, semantics)}
       // No `role`: this *is* a button, and `aria-pressed` is what makes it a
       // toggle one. Adding `role="button"` to a `<button>` would be noise, and
       // adding any other role would be a lie about what pressing it does.
-      aria-pressed={on ? "true" : "false"}
-      disabled={disabled}
-      onClick={composeHandlers(rest.onClick, () => {
-        if (!disabled) {
-          setOn(!on);
-        }
-      })}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        if (disabled || (event.key !== " " && event.key !== "Enter")) {
-          return;
-        }
-        // Preventing the default stops `Space` scrolling the page, and stops
-        // the browser's own click arriving after this handler and pressing the
-        // button a second time — back to where it started, which reads as the
-        // key having done nothing at all.
-        event.preventDefault();
-        setOn(!on);
-      })}
       type="button"
-    >
-      {children}
-    </button>
+    />
   );
 }