@uniflowed/ui 0.0.0-alpha.9 → 0.1.0

package/slider.js

@@ -76,8 +76,13 @@ import * as React from "@uniflowed/react";
 import { createContext, useContext, useMemo, useRef } from "@uniflowed/react";
 import { useStableCallback } from "@uniflowed/hooks/lifecycle";
 
-import type { Rest } from "./internal/merge-props.js";
-import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  withProps,
+  withoutComposed,
+} from "./internal/merge-props.js";
 import type { Orientation } from "./internal/roving-focus.js";
 import { clamp, fraction, isReversed, snap } from "./internal/range.js";
 import { useControlled } from "./internal/controlled-state.js";
@@ -128,6 +133,7 @@ export component SliderRoot(
   orientation?: Orientation = "horizontal",
   disabled?: boolean = false,
   valueText?: (value: number, index: number) => string,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const [values, setValues] = useControlled(value, defaultValue, onValueChange);
@@ -190,7 +196,7 @@ export component SliderRoot(
 
   return (
     <SliderContext.Provider value={state}>
-      <div {...rest}>{children}</div>
+      {render == null ? <div {...rest}>{children}</div> : render(withProps(rest, { children }))}
     </SliderContext.Provider>
   );
 }
@@ -203,7 +209,7 @@ export component SliderRoot(
  * wanders off the track — which every drag does — keeps arriving here instead
  * of being lost to whatever it wandered over.
  */
-export component SliderTrack(children: React.Node, ...rest: Rest) {
+export component SliderTrack(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const slider = useSlider("Slider.Track");
   const passed = withoutComposed(rest, ["onPointerDown", "onPointerMove", "onPointerUp", "ref"]);
   const dragging = useRef<number | null>(null);
@@ -239,35 +245,39 @@ export component SliderTrack(children: React.Node, ...rest: Rest) {
     slider.setAt(at, target);
   };
 
-  return (
-    <div
-      {...passed}
-      onPointerDown={composeHandlers(rest.onPointerDown, (event: $FlowFixMe) => {
-        if (slider.disabled) {
-          return;
-        }
-        // Otherwise the press selects the page's text on the way past, which
-        // makes a drag paint everything blue.
-        event.preventDefault();
-        event.currentTarget?.setPointerCapture?.(event.pointerId);
-        moveTo(event, null);
-      })}
-      onPointerMove={composeHandlers(rest.onPointerMove, (event: $FlowFixMe) => {
-        if (dragging.current != null) {
-          moveTo(event, dragging.current);
-        }
-      })}
-      onPointerUp={composeHandlers(rest.onPointerUp, (event: $FlowFixMe) => {
-        dragging.current = null;
-        event.currentTarget?.releasePointerCapture?.(event.pointerId);
-      })}
-      ref={composeRefs(rest.ref, (element) => {
-        slider.trackRef.current = element;
-      })}
-    >
-      {children}
-    </div>
-  );
+  const props = withProps(passed, {
+    children,
+    // Pointer handlers keep the active thumb in a ref between events.
+    // uf-lint-disable-next-line react-compiler/refs
+    onPointerDown: composeHandlers(rest.onPointerDown, (event: $FlowFixMe) => {
+      if (slider.disabled) {
+        return;
+      }
+      // Otherwise the press selects the page's text on the way past, which
+      // makes a drag paint everything blue.
+      event.preventDefault();
+      event.currentTarget?.setPointerCapture?.(event.pointerId);
+      moveTo(event, null);
+    }),
+    // uf-lint-disable-next-line react-compiler/refs
+    onPointerMove: composeHandlers(rest.onPointerMove, (event: $FlowFixMe) => {
+      if (dragging.current != null) {
+        moveTo(event, dragging.current);
+      }
+    }),
+    // uf-lint-disable-next-line react-compiler/refs
+    onPointerUp: composeHandlers(rest.onPointerUp, (event: $FlowFixMe) => {
+      dragging.current = null;
+      event.currentTarget?.releasePointerCapture?.(event.pointerId);
+    }),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      // React calls callback refs during commit; pointer handlers read the track later.
+      // uf-lint-disable-next-line react-compiler/immutability
+      slider.trackRef.current = element;
+    }),
+  });
+
+  return render == null ? <div {...props} /> : render(props);
 }
 
 /**
@@ -281,24 +291,22 @@ export component SliderTrack(children: React.Node, ...rest: Rest) {
  * is told the value by the thumb and telling them again here would be telling
  * them twice.
  */
-export component SliderRange(...rest: Rest) {
+export component SliderRange(render?: RenderProp, ...rest: Rest) {
   const slider = useSlider("Slider.Range");
   const passed = withoutComposed(rest, ["style"]);
   const ends = [...slider.values].sort((first, second) => first - second);
   const start = slider.values.length > 1 ? (ends[0] ?? slider.min) : slider.min;
   const end = ends[ends.length - 1] ?? slider.min;
+  const props = withProps(passed, {
+    "aria-hidden": "true",
+    style: {
+      ...(rest.style as $FlowFixMe),
+      "--uf-slider-start": fraction(start, slider.min, slider.max),
+      "--uf-slider-end": fraction(end, slider.min, slider.max),
+    },
+  });
 
-  return (
-    <div
-      {...passed}
-      aria-hidden="true"
-      style={{
-        ...(rest.style as $FlowFixMe),
-        "--uf-slider-start": fraction(start, slider.min, slider.max),
-        "--uf-slider-end": fraction(end, slider.min, slider.max),
-      }}
-    />
-  );
+  return render == null ? <div {...props} /> : render(props);
 }
 
 /**
@@ -315,55 +323,53 @@ export component SliderRange(...rest: Rest) {
  * "Maximum" told apart is the whole difference between a control a reader can
  * operate and two identical "slider"s.
  */
-export component SliderThumb(index?: number = 0, ...rest: Rest) {
+export component SliderThumb(index?: number = 0, render?: RenderProp, ...rest: Rest) {
   const slider = useSlider("Slider.Thumb");
   const passed = withoutComposed(rest, ["onKeyDown", "style"]);
   const value = slider.values[index] ?? slider.min;
   const [lower, upper] = boundsOf(slider.values, index, slider.min, slider.max);
+  const props = withProps(passed, {
+    "aria-disabled": slider.disabled ? "true" : undefined,
+    "aria-orientation": slider.orientation,
+    // The neighbour's value, not the slider's end. A reader told they may
+    // set this thumb to 90 while the control refuses at 60 has been told
+    // something the control disagrees with.
+    "aria-valuemax": upper,
+    "aria-valuemin": lower,
+    "aria-valuenow": value,
+    "aria-valuetext": slider.valueText?.(value, index),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: $FlowFixMe) => {
+      if (slider.disabled) {
+        return;
+      }
+      const reversed = isReversed(event.currentTarget, slider.orientation);
+      const move = stepFor(event.key, slider.step, slider.largeStep, reversed);
+      if (move != null) {
+        // Before moving: the arrow keys scroll the page, and a slider that
+        // moves the page under the reader as it moves the value is a control
+        // they cannot watch.
+        event.preventDefault();
+        slider.setAt(index, value + move);
+        return;
+      }
+      if (event.key === "Home" || event.key === "End") {
+        event.preventDefault();
+        // This thumb's own ends, which for the lower thumb of a range is its
+        // neighbour rather than the slider's maximum.
+        slider.setAt(index, event.key === "Home" ? lower : upper);
+      }
+    }),
+    role: "slider",
+    style: {
+      ...(rest.style as $FlowFixMe),
+      "--uf-slider-fraction": fraction(value, slider.min, slider.max),
+    },
+    // In the tab sequence, and out of it while disabled — the browser does
+    // this for a real control and there is no real control here to do it.
+    tabIndex: slider.disabled ? -1 : 0,
+  });
 
-  return (
-    <span
-      {...passed}
-      aria-disabled={slider.disabled ? "true" : undefined}
-      aria-orientation={slider.orientation}
-      // The neighbour's value, not the slider's end. A reader told they may
-      // set this thumb to 90 while the control refuses at 60 has been told
-      // something the control disagrees with.
-      aria-valuemax={upper}
-      aria-valuemin={lower}
-      aria-valuenow={value}
-      aria-valuetext={slider.valueText?.(value, index)}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event: $FlowFixMe) => {
-        if (slider.disabled) {
-          return;
-        }
-        const reversed = isReversed(event.currentTarget, slider.orientation);
-        const move = stepFor(event.key, slider.step, slider.largeStep, reversed);
-        if (move != null) {
-          // Before moving: the arrow keys scroll the page, and a slider that
-          // moves the page under the reader as it moves the value is a control
-          // they cannot watch.
-          event.preventDefault();
-          slider.setAt(index, value + move);
-          return;
-        }
-        if (event.key === "Home" || event.key === "End") {
-          event.preventDefault();
-          // This thumb's own ends, which for the lower thumb of a range is its
-          // neighbour rather than the slider's maximum.
-          slider.setAt(index, event.key === "Home" ? lower : upper);
-        }
-      })}
-      role="slider"
-      style={{
-        ...(rest.style as $FlowFixMe),
-        "--uf-slider-fraction": fraction(value, slider.min, slider.max),
-      }}
-      // In the tab sequence, and out of it while disabled — the browser does
-      // this for a real control and there is no real control here to do it.
-      tabIndex={slider.disabled ? -1 : 0}
-    />
-  );
+  return render == null ? <span {...props} /> : render(props);
 }
 
 /**

package/switch.js

@@ -19,55 +19,63 @@
 //
 // The keyboard follows from the same distinction. `Space` toggles both. `Enter`
 // toggles a *switch*, because a switch is an operation and pressing Enter on
-// something that operates is what a reader expects — while `checkbox.js`
-// deliberately leaves `Enter` alone so that a checkbox inside a form still
-// submits it. That is the whole reason these are not one file with a flag.
+// something that operates is what a reader expects — while `checkbox.js` turns
+// `Enter` into the submission of the form the checkbox is in, which is what a
+// native `<input type="checkbox">` does with the key and what a reader
+// answering a question on their way to a submit button is asking for. That is
+// the whole reason these are not one file with a flag.
 
 "use client";
 
 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 two-state switch: on or off. */
+/**
+ * A two-state switch: on or off.
+ *
+ * `render` is the escape hatch, and on a switch it is what a caller with their
+ * own `<Pressable>` or a `<div role="switch">` in a design system reaches for.
+ * `type="button"` is the one thing it does not hand over, because that is true
+ * of the element rather than of the switch.
+ */
 export component Switch(
   checked?: boolean,
   defaultChecked?: boolean = false,
   onCheckedChange?: (checked: boolean) => void,
   disabled?: boolean = false,
   children?: React.Node,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const [on, setOn] = useControlled(checked, defaultChecked, onCheckedChange);
-  const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
-
-  return (
-    <button
-      {...passed}
-      aria-checked={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 is not decoration. It stops `Space` scrolling
-        // the page — which is what makes a hand-written toggle feel broken even
-        // when it works — and it stops the browser's own click from arriving
-        // after this handler and toggling the switch a second time.
-        event.preventDefault();
+  const props = withProps(withoutComposed(rest, ["onClick", "onKeyDown"]), {
+    "aria-checked": on ? "true" : "false",
+    children,
+    disabled,
+    onClick: composeHandlers(rest.onClick, () => {
+      if (!disabled) {
         setOn(!on);
-      })}
-      role="switch"
-      type="button"
-    >
-      {children}
-    </button>
-  );
+      }
+    }),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      if (disabled || (event.key !== " " && event.key !== "Enter")) {
+        return;
+      }
+      // Preventing the default is not decoration. It stops `Space` scrolling
+      // the page — which is what makes a hand-written toggle feel broken even
+      // when it works — and it stops the browser's own click from arriving
+      // after this handler and toggling the switch a second time.
+      event.preventDefault();
+      setOn(!on);
+    }),
+    role: "switch",
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
 }

package/table.js

@@ -57,9 +57,8 @@
 // It is rendered by the root rather than offered as a part a caller places,
 // because a sort that announces nothing is the failure this component exists
 // to prevent and a part is a thing somebody forgets. The cost is one extra
-// element in the caller's layout, and a sentence that is visible until they
-// style it — which is not a bad thing to see, and a table that shows its sort
-// status in words is a table more people can use.
+// element after the table, hidden from layout and visible to the screen readers
+// watching it.
 
 "use client";
 
@@ -68,8 +67,13 @@ import { createContext, useContext, useEffect, useId, useMemo, useState } from "
 import { useStableCallback } from "@uniflowed/hooks/lifecycle";
 
 import { Checkbox } from "./checkbox.js";
-import type { Rest } from "./internal/merge-props.js";
-import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import {
+  composeHandlers,
+  composeRefs,
+  withProps,
+  withoutComposed,
+} from "./internal/merge-props.js";
 import { useControlled } from "./internal/controlled-state.js";
 
 /** Which column a table is sorted by, and which way. */
@@ -100,6 +104,19 @@ const TableContext: React.Context<TableState | null> = createContext(null);
 /** Whether the rows below are header rows, which decides `th` versus `td`. */
 const HeaderContext: React.Context<boolean> = createContext(false);
 
+const VISUALLY_HIDDEN_STYLE = Object.freeze({
+  border: 0,
+  clip: "rect(0, 0, 0, 0)",
+  clipPath: "inset(50%)",
+  height: 1,
+  margin: -1,
+  overflow: "hidden",
+  padding: 0,
+  position: "absolute",
+  whiteSpace: "nowrap",
+  width: 1,
+});
+
 hook useTable(part: string): TableState {
   const state = useContext(TableContext);
   if (state == null) {
@@ -130,6 +147,7 @@ export component TableRoot(
   rowCount?: number | null = null,
   rowOffset?: number = 0,
   announceSort?: (column: string, direction: "ascending" | "descending") => string,
+  render?: RenderProp,
   ...rest: Rest
 ) {
   const base = useId();
@@ -184,30 +202,28 @@ export component TableRoot(
           labels[current.column] ?? current.column,
           current.direction,
         );
+  const props = withProps(rest, {
+    "aria-labelledby": captioned ? `${base}-caption` : undefined,
+    "aria-rowcount": rowCount == null ? undefined : rowCount + headerRows,
+    children,
+  });
 
   return (
     <TableContext.Provider value={state}>
-      <table
-        {...rest}
-        // The caption is a `<table>`'s accessible name in HTML-AAM already;
-        // naming it again here is what turns "the host will probably do this"
-        // into something this component promises, and it costs nothing because
-        // both point at the same words. Only while a caption is rendered, for
-        // the reason every part of this package repeats.
-        aria-labelledby={captioned ? `${base}-caption` : undefined}
-        // Every row in the table, which is the data plus the header — the
-        // arithmetic a caller should not have to remember.
-        aria-rowcount={rowCount == null ? undefined : rowCount + headerRows}
-      >
-        {children}
-      </table>
+      {render == null ? <table {...props} /> : render(withProps(props, { role: "table" }))}
       {/*
         Beside the table rather than inside it, because a `<table>` may only
         contain a caption, column groups and row groups — and mounted from the
         first render, holding nothing, because a live region that appears with
         its text is a live region that says nothing.
       */}
-      <div aria-atomic="true" aria-live="polite" data-uf-table-status="" role="status">
+      <div
+        aria-atomic="true"
+        aria-live="polite"
+        data-uf-table-status=""
+        role="status"
+        style={VISUALLY_HIDDEN_STYLE}
+      >
         {message}
       </div>
     </TableContext.Provider>
@@ -221,7 +237,7 @@ export component TableRoot(
  * what a screen reader reads when a reader lands on it. A heading above the
  * table looks the same and is not the table's name.
  */
-export component TableCaption(children: React.Node, ...rest: Rest) {
+export component TableCaption(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const table = useTable("Table.Caption");
   const register = table.registerCaption;
 
@@ -230,11 +246,11 @@ export component TableCaption(children: React.Node, ...rest: Rest) {
     return () => register(false);
   }, [register]);
 
-  return (
-    <caption {...rest} id={table.captionId}>
-      {children}
-    </caption>
-  );
+  const props = withProps(rest, { children, id: table.captionId });
+  if (render != null) {
+    return render(withProps(props, { role: "caption" }));
+  }
+  return <caption {...props} />;
 }
 
 /**
@@ -243,7 +259,7 @@ export component TableCaption(children: React.Node, ...rest: Rest) {
  * It tells the root that it exists, because `aria-rowcount` and every row's
  * `aria-rowindex` count header rows and a table without one counts differently.
  */
-export component TableHeader(children: React.Node, ...rest: Rest) {
+export component TableHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const table = useTable("Table.Header");
   const register = table.registerHeader;
 
@@ -252,18 +268,21 @@ export component TableHeader(children: React.Node, ...rest: Rest) {
     return () => register(false);
   }, [register]);
 
+  const props = withProps(rest, { children });
+
   return (
     <HeaderContext.Provider value={true}>
-      <thead {...rest}>{children}</thead>
+      {render == null ? <thead {...props} /> : render(withProps(props, { role: "rowgroup" }))}
     </HeaderContext.Provider>
   );
 }
 
 /** The data rows. */
-export component TableBody(children: React.Node, ...rest: Rest) {
+export component TableBody(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { children });
   return (
     <HeaderContext.Provider value={false}>
-      <tbody {...rest}>{children}</tbody>
+      {render == null ? <tbody {...props} /> : render(withProps(props, { role: "rowgroup" }))}
     </HeaderContext.Provider>
   );
 }
@@ -284,7 +303,12 @@ export component TableBody(children: React.Node, ...rest: Rest) {
  * adding them anyway is a second source of truth that can disagree with the
  * document.
  */
-export component TableRow(children: React.Node, index?: number | null = null, ...rest: Rest) {
+export component TableRow(
+  children: React.Node,
+  index?: number | null = null,
+  render?: RenderProp,
+  ...rest: Rest
+) {
   const table = useTable("Table.Row");
   const header = useContext(HeaderContext);
   const counted = table.rowCount != null;
@@ -300,11 +324,11 @@ export component TableRow(children: React.Node, index?: number | null = null, ..
     rowIndex = table.headerRows + table.rowOffset + (index ?? 0) + 1;
   }
 
-  return (
-    <tr {...rest} aria-rowindex={rowIndex}>
-      {children}
-    </tr>
-  );
+  const props = withProps(rest, { "aria-rowindex": rowIndex, children });
+  if (render != null) {
+    return render(withProps(props, { role: "row" }));
+  }
+  return <tr {...props} />;
 }
 
 /**
@@ -320,7 +344,12 @@ export component TableRow(children: React.Node, index?: number | null = null, ..
  * Not `"none"` on the others: eleven headers each announcing "not sorted" is
  * eleven announcements of nothing, on every pass through the table.
  */
-export component TableHead(children: React.Node, column?: string | null = null, ...rest: Rest) {
+export component TableHead(
+  children: React.Node,
+  column?: string | null = null,
+  render?: RenderProp,
+  ...rest: Rest
+) {
   const table = useTable("Table.Head");
   const passed = withoutComposed(rest, column == null ? [] : ["onClick", "ref"]);
   const sorted = column != null && table.sort?.column === column;
@@ -341,41 +370,49 @@ export component TableHead(children: React.Node, column?: string | null = null,
   });
 
   if (column == null) {
-    return (
-      <th {...rest} scope="col">
-        {children}
-      </th>
-    );
+    const props = withProps(rest, { children, scope: "col" });
+    if (render != null) {
+      return render(withProps(props, { role: "columnheader" }));
+    }
+    return <th {...props} />;
   }
 
-  return (
-    <th
-      {...passed}
-      aria-sort={sorted ? table.sort?.direction : undefined}
-      ref={composeRefs(rest.ref, setElement)}
-      scope="col"
+  const button = (
+    <button
+      onClick={composeHandlers(rest.onClick, () => {
+        // Two states, not three. A sort that cycles back to "unsorted" gives
+        // a reader a third press whose result is a table in an order nobody
+        // asked for.
+        table.setSort({
+          column,
+          direction: sorted && table.sort?.direction === "ascending" ? "descending" : "ascending",
+        });
+      })}
+      type="button"
     >
-      <button
-        onClick={composeHandlers(rest.onClick, () => {
-          // Two states, not three. A sort that cycles back to "unsorted" gives
-          // a reader a third press whose result is a table in an order nobody
-          // asked for.
-          table.setSort({
-            column,
-            direction: sorted && table.sort?.direction === "ascending" ? "descending" : "ascending",
-          });
-        })}
-        type="button"
-      >
-        {children}
-      </button>
-    </th>
+      {children}
+    </button>
   );
+  const props = withProps(passed, {
+    "aria-sort": sorted ? table.sort?.direction : undefined,
+    children: button,
+    ref: composeRefs(rest.ref, setElement),
+    scope: "col",
+  });
+
+  if (render != null) {
+    return render(withProps(props, { role: "columnheader" }));
+  }
+  return <th {...props} />;
 }
 
 /** One cell. */
-export component TableCell(children: React.Node, ...rest: Rest) {
-  return <td {...rest}>{children}</td>;
+export component TableCell(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { children });
+  if (render != null) {
+    return render(withProps(props, { role: "cell" }));
+  }
+  return <td {...props} />;
 }
 
 /**
@@ -386,12 +423,12 @@ export component TableCell(children: React.Node, ...rest: Rest) {
  * moves down the year column. A table of records usually has one and almost
  * never marks it.
  */
-export component TableRowHeader(children: React.Node, ...rest: Rest) {
-  return (
-    <th {...rest} scope="row">
-      {children}
-    </th>
-  );
+export component TableRowHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { children, scope: "row" });
+  if (render != null) {
+    return render(withProps(props, { role: "rowheader" }));
+  }
+  return <th {...props} />;
 }
 
 /**
@@ -430,6 +467,7 @@ export component TableSelectAll(
   label?: string = "Select all rows",
   className?: string,
   disabled?: boolean = false,
+  render?: RenderProp,
 ) {
   return (
     <Checkbox
@@ -439,6 +477,7 @@ export component TableSelectAll(
       disabled={disabled}
       indeterminate={checked === "mixed"}
       onCheckedChange={onCheckedChange}
+      render={render}
     />
   );
 }
@@ -461,6 +500,7 @@ export component TableRowSelect(
   onCheckedChange: (checked: boolean) => void,
   className?: string,
   disabled?: boolean = false,
+  render?: RenderProp,
 ) {
   return (
     <Checkbox
@@ -469,6 +509,7 @@ export component TableRowSelect(
       className={className}
       disabled={disabled}
       onCheckedChange={onCheckedChange}
+      render={render}
     />
   );
 }