@uniflowed/ui 0.0.0-alpha.9 → 0.2.0

package/range-calendar.js

@@ -0,0 +1,79 @@
+// @flow
+"use client";
+import * as React from "@uniflowed/react";
+import { useState } from "@uniflowed/react";
+import type { PlainDate } from "@uniflowed/core/temporal";
+import { useControlled } from "./internal/controlled-state.js";
+import type { Rest } from "./internal/merge-props.js";
+import type { DateRange } from "./internal/date-range.js";
+import { validateRange, unavailableInRange } from "./internal/date-range.js";
+import { CalendarRoot, CalendarMonth } from "./calendar.js";
+import { visuallyHiddenStyle } from "./internal/visually-hidden-style.js";
+export type { DateRange } from "./internal/date-range.js";
+
+export component RangeCalendarRoot(
+  children?: React.Node = <CalendarMonth />,
+  value?: DateRange | null,
+  defaultValue?: DateRange | null = null,
+  onValueChange?: (value: DateRange | null) => void,
+  minValue?: string,
+  maxValue?: string,
+  isDateDisabled?: (date: PlainDate) => boolean,
+  defaultFocused?: string,
+  today?: string,
+  locale?: string,
+  focusedDayRef?: { current: HTMLElement | null },
+  ...rest: Rest
+) {
+  const [range, setRange] = useControlled(value, defaultValue, onValueChange);
+  const [anchor, setAnchor] = useState<string | null>(null);
+  const [announcement, announce] = useState("");
+  validateRange(range);
+  const disabled = (date: PlainDate) =>
+    (minValue != null && date.toString() < minValue) ||
+    (maxValue != null && date.toString() > maxValue) ||
+    isDateDisabled?.(date) === true;
+  const choose = (date: PlainDate) => {
+    const iso = date.toString();
+    if (disabled(date)) return;
+    if (anchor == null) {
+      setAnchor(iso);
+      announce(`Start ${iso}. Choose an end date.`);
+      return;
+    }
+    const start = anchor < iso ? anchor : iso,
+      end = anchor < iso ? iso : anchor;
+    if (unavailableInRange(start, end, isDateDisabled)) {
+      announce("The range contains an unavailable date");
+      return;
+    }
+    setRange({ start, end });
+    setAnchor(null);
+    announce(`Selected ${start} to ${end}`);
+  };
+  const selected = (date: PlainDate) => {
+    const iso = date.toString();
+    return anchor != null
+      ? iso === anchor
+      : range != null && iso >= range.start && iso <= range.end;
+  };
+  return (
+    <div {...rest}>
+      <CalendarRoot
+        value={anchor ?? range?.start ?? null}
+        defaultFocused={defaultFocused}
+        today={today}
+        locale={locale}
+        focusedDayRef={focusedDayRef}
+        isDateDisabled={disabled}
+        isDateSelected={selected}
+        onValueChange={choose}
+      >
+        {children}
+      </CalendarRoot>
+      <span role="status" aria-live="polite" style={visuallyHiddenStyle}>
+        {announcement}
+      </span>
+    </div>
+  );
+}

package/resizable.js

@@ -10,8 +10,42 @@
 //
 // Almost every resizable panel on the web is pointer-only, which is a WCAG
 // 2.1.1 failure — no keyboard operation at all — and a 2.5.7 one on top of it.
-// If uf ships one, the keyboard is the feature, so the keyboard is what this
-// module is: there is no drag here yet, and there is a complete key map.
+// If uf ships one the keyboard is the feature, so the keyboard was written
+// first and shipped on its own: a keyboard-only splitter is a working
+// splitter, where a pointer-only one is not.
+//
+// It was not the finished control. A bar between two panes is a bar that
+// approximately everybody takes hold of first, and this one could not be
+// moved that way at all. Both halves are here now, and the key map is exactly
+// what it was — a drag that had quietly replaced it would be the first failure
+// in the other direction.
+//
+// # The drag, and the step it does not use
+//
+// It is `slider.js`'s `Slider.Track` arithmetic measured against the *group's*
+// box rather than a track's. `pointerdown` captures the pointer, so a drag
+// that wanders off a bar four pixels wide — which every drag does — keeps
+// arriving at the handle instead of being lost to whatever it wandered over;
+// `pointermove` turns the position into a percentage from
+// `getBoundingClientRect`; and the percentage goes through `internal/range.js`
+// like every other value here, so a drag cannot leave the pane anywhere an
+// arrow key could not put it, and `aria-valuenow` is true about it while it
+// moves.
+//
+// Pressing the handle does not move it. A press on a *track* means "put the
+// value here", which is what `Slider.Track` does with one and why it is half
+// of WCAG 2.5.7 there; a press on a handle means "take hold of this". A
+// splitter that also jumped by the distance between the pointer and its own
+// centre would move a little every time it was clicked, which is the one thing
+// a person who clicked it did not ask for.
+//
+// `step` stays the keyboard's, and the pointer has one of its own. `step`
+// defaults to 10 because ten presses of an arrow key ought to cross the pane,
+// and 10 is an absurd granularity for a bar being dragged under a pointer that
+// moves smoothly. The pointer's is one percent, and it is a constant rather
+// than a second prop because the value is already a percentage of the group:
+// one is the smallest move that means anything, and a splitter announcing
+// 47.382 would be reading out its arithmetic rather than its size.
 //
 // # The two separators in this package are not the same thing
 //
@@ -53,9 +87,9 @@
 //
 // Each pane carries its share as `--uf-resizable-size`, a percentage, and the
 // caller's stylesheet decides whether that is a width, a height, a `flex-basis`
-// or nothing at all. There is no drag: the pointer half is tracked work, and a
-// keyboard-only splitter is a working splitter, where a pointer-only one is
-// not.
+// or nothing at all. The group is measured rather than drawn — the drag reads
+// its box and never writes to it — so a caller whose panes are flex children,
+// grid tracks or absolutely positioned gets the same splitter.
 
 "use client";
 
@@ -71,11 +105,21 @@ import {
 } from "@uniflowed/react";
 
 import type { Rest } from "./internal/merge-props.js";
-import { composeHandlers, withoutComposed } from "./internal/merge-props.js";
+import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
 import type { Orientation } from "./internal/roving-focus.js";
-import { clamp, isReversed } from "./internal/range.js";
+import { clamp, isReversed, snap } from "./internal/range.js";
 import { useControlled } from "./internal/controlled-state.js";
 
+/**
+ * How finely a drag may move the splitter, in percentage points.
+ *
+ * Not `step`, which is the keyboard's and defaults to ten; the module header
+ * says why the two cannot be the same number. One is a constant rather than a
+ * prop because the value is already a percentage of the group, so one is the
+ * smallest move that means anything.
+ */
+const POINTER_STEP = 1;
+
 type ResizableState = {|
   readonly base: string,
   /** The primary pane's share of the group, as a percentage. */
@@ -89,6 +133,14 @@ type ResizableState = {|
   readonly disabled: boolean,
   readonly hasPrimary: boolean,
   readonly registerPrimary: (present: boolean) => void,
+  /**
+   * The element a drag is measured against.
+   *
+   * The group rather than the handle, because the value is the primary pane's
+   * share *of the group* — the handle is a few pixels wide and has no idea how
+   * much space there is to divide.
+   */
+  readonly groupRef: { current: HTMLElement | null },
 |};
 
 const ResizableContext: React.Context<ResizableState | null> = createContext(null);
@@ -128,6 +180,7 @@ export component ResizablePanelGroup(
   const base = useId();
   const [share, setShare] = useControlled(value, defaultValue, onValueChange);
   const [hasPrimary, setHasPrimary] = useState(false);
+  const groupRef = useRef<HTMLElement | null>(null);
 
   const state = useMemo(
     () => ({
@@ -141,13 +194,23 @@ export component ResizablePanelGroup(
       disabled,
       hasPrimary,
       registerPrimary: setHasPrimary,
+      groupRef,
     }),
     [base, share, setShare, min, max, step, orientation, disabled, hasPrimary],
   );
 
+  const passed = withoutComposed(rest, ["ref"]);
+
   return (
     <ResizableContext.Provider value={state}>
-      <div {...rest}>{children}</div>
+      <div
+        {...passed}
+        ref={composeRefs(rest.ref, (element) => {
+          groupRef.current = element;
+        })}
+      >
+        {children}
+      </div>
     </ResizableContext.Provider>
   );
 }
@@ -199,16 +262,61 @@ export component ResizablePanel(children: React.Node, primary?: boolean = false,
  */
 export component ResizableHandle(label?: string = "Resize", ...rest: Rest) {
   const group = useResizable("Resizable.Handle");
-  const passed = withoutComposed(rest, ["onKeyDown"]);
+  const passed = withoutComposed(rest, [
+    "onKeyDown",
+    "onPointerCancel",
+    "onPointerDown",
+    "onPointerMove",
+    "onPointerUp",
+  ]);
   // Where the pane was before `Enter` collapsed it. A ref because nothing
   // renders it: it is a fact about the last keystroke, not about the layout.
   const restoreTo = useRef<number | null>(null);
+  // Whether the pointer is down on this handle. Also a ref, and for the same
+  // reason: it changes between renders and no render depends on it.
+  const dragging = useRef(false);
 
   const moveBy = (amount: number) => {
     restoreTo.current = null;
     group.setValue(clamp(group.value + amount, group.min, group.max));
   };
 
+  /** The primary pane's share at the pointer, or null with no box to read. */
+  const shareAt = (event: $FlowFixMe): number | null => {
+    const element = group.groupRef.current;
+    if (element == null) {
+      return null;
+    }
+    const box = element.getBoundingClientRect();
+    const vertical = group.orientation === "vertical";
+    const size = vertical ? box.height : box.width;
+    if (size <= 0) {
+      // A group with no box has no percentages in it, and dividing by its
+      // width would put `Infinity` into `aria-valuenow`.
+      return null;
+    }
+    // From the top for stacked panes, where `Slider.Track` reads from the
+    // bottom: a slider's minimum is at the bottom of its track, and a group's
+    // primary pane is the one *before* the handle, which is the top one.
+    const along = vertical ? event.clientY - box.top : event.clientX - box.left;
+    const part = clamp(along / size, 0, 1);
+    // In a right-to-left page the pane before the handle is the one on the
+    // right, so the reading runs the other way. `isReversed` mirrors nothing on
+    // a stacked group, because writing direction does not flip the vertical
+    // axis.
+    const forward = isReversed(element, group.orientation) ? 1 - part : part;
+    // The value *is* the percentage, so the position becomes one directly
+    // rather than being mapped across `min`–`max` the way a slider's is: those
+    // two are bounds on how far the pane may be dragged, not the ends of a
+    // scale. Mapping them would put the handle somewhere the pointer is not.
+    return snap(forward * 100, group.min, group.max, POINTER_STEP);
+  };
+
+  const endDrag = (event: $FlowFixMe) => {
+    dragging.current = false;
+    event.currentTarget?.releasePointerCapture?.(event.pointerId);
+  };
+
   return (
     <div
       {...passed}
@@ -224,6 +332,8 @@ export component ResizableHandle(label?: string = "Resize", ...rest: Rest) {
       aria-valuemax={group.max}
       aria-valuemin={group.min}
       aria-valuenow={group.value}
+      // Key and pointer handlers keep gesture state in refs between events.
+      // uf-lint-disable-next-line react-compiler/refs
       onKeyDown={composeHandlers(rest.onKeyDown, (event: $FlowFixMe) => {
         if (group.disabled) {
           return;
@@ -265,6 +375,42 @@ export component ResizableHandle(label?: string = "Resize", ...rest: Rest) {
           moveBy(amount);
         }
       })}
+      // uf-lint-disable-next-line react-compiler/refs
+      onPointerCancel={composeHandlers(rest.onPointerCancel, endDrag)}
+      // uf-lint-disable-next-line react-compiler/refs
+      onPointerDown={composeHandlers(rest.onPointerDown, (event: $FlowFixMe) => {
+        if (group.disabled) {
+          return;
+        }
+        // Otherwise the press selects the text in the panes either side on the
+        // way past, so a drag paints half the page blue.
+        event.preventDefault();
+        // Which also means the browser will not focus this element, and a
+        // reader who has just dragged the splitter is the reader most likely to
+        // want an arrow key next.
+        event.currentTarget?.focus?.();
+        event.currentTarget?.setPointerCapture?.(event.pointerId);
+        dragging.current = true;
+        // A drag is a move, so the pane `Enter` would put back is no longer
+        // where it was. Leaving it would make the next `Enter` restore a size
+        // from before the drag.
+        restoreTo.current = null;
+        // Deliberately no value change: taking hold of the handle is not asking
+        // it to move. The module header says what a press does on a track
+        // instead, and why the two are not the same gesture.
+      })}
+      // uf-lint-disable-next-line react-compiler/refs
+      onPointerMove={composeHandlers(rest.onPointerMove, (event: $FlowFixMe) => {
+        if (!dragging.current) {
+          return;
+        }
+        const share = shareAt(event);
+        if (share != null) {
+          group.setValue(share);
+        }
+      })}
+      // uf-lint-disable-next-line react-compiler/refs
+      onPointerUp={composeHandlers(rest.onPointerUp, endDrag)}
       role="separator"
       // A separator that is not in the tab sequence is the WCAG 2.1.1 failure
       // this module exists to avoid.

package/scroll-area.js

@@ -0,0 +1,283 @@
+// @flow
+//
+// A scroll area: a scrollbar you drew yourself, and the keyboard you took away
+// when you did.
+//
+// # What it gives that `overflow: auto` does not
+//
+// A `<div style="overflow: auto">` scrolls with the wheel, with a trackpad, and
+// with a finger. What it does not reliably do is scroll from the keyboard,
+// because it may not be focusable: Firefox makes a scrollable region focusable,
+// Chromium historically does not, and Safari's answer depends on the setting
+// that controls whether `Tab` reaches anything but form controls. So a region
+// that must be scrolled to be read is, in most browsers, a region a keyboard
+// reader can see the top of and nothing else. That is WCAG 2.1.1, and it is the
+// entire reason to have this component rather than the `div`:
+//
+//   * **`tabindex="0"`, `role="region"` and a name.** The tab stop is what
+//     makes the arrow keys and `PageDown` work; the role and the name are what
+//     keep a tab stop from being a mystery — a focusable `div` with no name is
+//     announced as nothing at all, which is a worse place to land than the
+//     `div` was.
+//   * **Nothing is intercepted.** No `onKeyDown`, no `onWheel`, no
+//     `scroll-behavior` written from JavaScript. Every key that scrolls a
+//     native overflow container scrolls this one, because this one *is* a
+//     native overflow container and the component's whole contribution is not
+//     getting in its way. A scroll area that reimplemented `PageDown` would
+//     have to reimplement `Home`, `End`, the space bar, caret browsing and
+//     whatever the reader's own software sends, and would get one of them
+//     wrong.
+//   * **`scrollIntoView({ block: "nearest" })` still works.** `combobox.js` and
+//     `select.js` both call it to keep the active option visible, so a
+//     `Combobox.List` inside a `ScrollArea` is a case that has to work. It does
+//     because the viewport is a plain scroll container and nothing here
+//     overrides `scrollTop`; the one time this module writes it is described
+//     below, and it is exactly the case where the browser has already thrown
+//     the position away.
+//   * **The position survives a re-render.** Replacing the content of a scroll
+//     container — a filtered list, a new page of results — makes the browser
+//     clamp `scrollTop` to a shorter document and it does not put it back. The
+//     viewport remembers where the reader actually scrolled to, from the
+//     `scroll` event, and restores it after a commit that lost it. A reader who
+//     scrolls to the top themselves fires a `scroll` event, so the remembered
+//     position is theirs and this never fights them.
+//
+// # The scrollbar is a picture
+//
+// `ScrollArea.Scrollbar` is `aria-hidden` and holds no controls. That is the
+// decision the component is made of: the *region* is the thing that scrolls and
+// the keyboard is how it is operated, so a drawn scrollbar has nothing it must
+// be able to do — which means it never has to answer WCAG 2.5.7's question
+// about dragging, because nothing here is achievable only by dragging. It
+// reports where the content is as two custom properties and stays out of the
+// accessibility tree, where a second, mouse-only copy of the scroll position
+// would be noise.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useEffect, useId, useMemo, useRef } from "@uniflowed/react";
+import { useEventListener } from "@uniflowed/hooks/dom";
+
+import type { Orientation } from "./internal/roving-focus.js";
+import type { Rest } from "./internal/merge-props.js";
+import { composeRefs, withoutComposed } from "./internal/merge-props.js";
+
+export type { Orientation } from "./internal/roving-focus.js";
+
+/** Where the reader last actually was, per axis. */
+type Offset = {| x: number, y: number |};
+
+type ScrollAreaState = {|
+  readonly base: string,
+  readonly label: string,
+  readonly viewportRef: { current: HTMLElement | null },
+  readonly rememberedRef: { current: Offset },
+  /** Written by the viewport, read by every scrollbar. */
+  readonly report: () => void,
+  readonly scrollbarsRef: { current: Array<HTMLElement> },
+|};
+
+const ScrollAreaContext: React.Context<ScrollAreaState | null> = createContext(null);
+
+/**
+ * The scroll area a part belongs to.
+ *
+ * Raising rather than returning null, for the reason `useDialog` gives: a
+ * `ScrollArea.Scrollbar` outside a root would draw a thumb for a viewport it
+ * has never measured, and it would look correct until the content moved.
+ */
+hook useScrollArea(part: string): ScrollAreaState {
+  const state = useContext(ScrollAreaContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a ScrollArea.Root`);
+  }
+  return state;
+}
+
+/**
+ * The box the viewport and the scrollbars sit in.
+ *
+ * `label` is required and lives here rather than on the viewport, because the
+ * name belongs to the whole component: it is what a reader hears when `Tab`
+ * lands them in it, and a scroll area that has to be scrolled to be read and is
+ * announced as "region" has told them nothing.
+ */
+export component ScrollAreaRoot(children: React.Node, label: string, ...rest: Rest) {
+  const base = useId();
+  const viewportRef = useRef<HTMLElement | null>(null);
+  const rememberedRef = useRef<Offset>({ x: 0, y: 0 });
+  const scrollbarsRef = useRef<Array<HTMLElement>>([]);
+
+  const state = useMemo(
+    () => ({
+      base,
+      label,
+      rememberedRef,
+      report: () => {
+        const viewport = viewportRef.current;
+        if (viewport == null) {
+          return;
+        }
+        for (const scrollbar of scrollbarsRef.current) {
+          write(scrollbar, viewport);
+        }
+      },
+      scrollbarsRef,
+      viewportRef,
+    }),
+    [base, label],
+  );
+
+  return (
+    <ScrollAreaContext.Provider value={state}>
+      <div {...rest}>{children}</div>
+    </ScrollAreaContext.Provider>
+  );
+}
+
+/**
+ * The element that actually scrolls: a named region, in the tab sequence.
+ *
+ * It carries no key handling at all. See the module header — every key that
+ * scrolls a native overflow container scrolls this one because it is one, and
+ * the component's contribution is the tab stop that lets those keys arrive.
+ */
+export component ScrollAreaViewport(children: React.Node, ...rest: Rest) {
+  const area = useScrollArea("ScrollArea.Viewport");
+  const { rememberedRef, report, viewportRef } = area;
+  const passed = withoutComposed(rest, ["ref"]);
+
+  useEventListener(viewportRef, "scroll", () => {
+    const viewport = viewportRef.current;
+    if (viewport == null) {
+      return;
+    }
+    // The reader's own position, including a deliberate scroll back to the
+    // top — which is why the restore below never fights them.
+    rememberedRef.current = { x: viewport.scrollLeft, y: viewport.scrollTop };
+    report();
+  });
+
+  // After every commit, because a commit is what replaces the content: a
+  // shorter document makes the browser clamp the offset to fit and it does not
+  // put it back when the content grows again.
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    if (viewport == null) {
+      return;
+    }
+    const { x, y } = rememberedRef.current;
+    if (y !== 0 && viewport.scrollTop === 0) {
+      viewport.scrollTop = y;
+    }
+    if (x !== 0 && viewport.scrollLeft === 0) {
+      viewport.scrollLeft = x;
+    }
+    report();
+  });
+
+  return (
+    <div
+      {...passed}
+      aria-label={area.label}
+      id={`${area.base}-viewport`}
+      ref={composeRefs(rest.ref, (element: HTMLElement | null) => {
+        viewportRef.current = element;
+      })}
+      // A named region, which is what makes the tab stop below explicable
+      // rather than a place a reader lands and cannot account for.
+      role="region"
+      // The whole component. Without it the arrow keys and `PageDown` never
+      // arrive, and the bottom of this box is unreachable from a keyboard in
+      // every browser that does not make scroll containers focusable.
+      tabIndex={0}
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * The drawn scrollbar: two numbers and no semantics.
+ *
+ * `--uf-scroll-thumb-size` is the thumb's length as a fraction of the track and
+ * `--uf-scroll-thumb-offset` is where along it the thumb sits, both between 0
+ * and 1, so a stylesheet can draw one with a `scale` and a `translate` and
+ * measure nothing. `aria-hidden`, because the region it belongs to is already
+ * the thing a reader operates.
+ */
+export component ScrollAreaScrollbar(
+  children?: React.Node,
+  orientation?: Orientation = "vertical",
+  ...rest: Rest
+) {
+  const area = useScrollArea("ScrollArea.Scrollbar");
+  const { report, scrollbarsRef } = area;
+  const passed = withoutComposed(rest, ["ref"]);
+
+  return (
+    <div
+      {...passed}
+      // A picture of the scroll position is not something a screen reader has
+      // any use for: it cannot be operated, and the region it describes
+      // announces itself.
+      aria-hidden="true"
+      data-orientation={orientation}
+      ref={composeRefs(rest.ref, (element: HTMLElement | null) => {
+        const kept = scrollbarsRef.current.filter((each) => each !== element);
+        scrollbarsRef.current = element == null ? kept : [...kept, element];
+        report();
+      })}
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Write where the content is onto a scrollbar.
+ *
+ * Imperatively, and only these two properties, for the reason
+ * `internal/anchor.js` gives about a placement: they change on every scroll
+ * frame, and re-rendering the scroll area and everything in it sixty times a
+ * second to move a thumb is the cost this package does not pay. React sets
+ * neither property, so a caller's `style` keeps everything in it.
+ *
+ * Both axes are written on every scrollbar rather than the one its
+ * `data-orientation` names, because a stylesheet reads the pair it wants and a
+ * branch here would be a second place the orientation is decided.
+ */
+function write(scrollbar: HTMLElement, viewport: HTMLElement): void {
+  const style = scrollbar.style;
+  style.setProperty(
+    "--uf-scroll-thumb-size",
+    String(fraction(viewport.clientHeight, viewport.scrollHeight)),
+  );
+  style.setProperty(
+    "--uf-scroll-thumb-offset",
+    String(fraction(viewport.scrollTop, viewport.scrollHeight - viewport.clientHeight)),
+  );
+  style.setProperty(
+    "--uf-scroll-thumb-size-x",
+    String(fraction(viewport.clientWidth, viewport.scrollWidth)),
+  );
+  style.setProperty(
+    "--uf-scroll-thumb-offset-x",
+    String(fraction(viewport.scrollLeft, viewport.scrollWidth - viewport.clientWidth)),
+  );
+}
+
+/**
+ * `part / whole`, clamped, and 1 when there is no whole.
+ *
+ * A document that computes no layout reports every measurement as zero, and
+ * `0 / 0` is `NaN` — which a stylesheet reading the custom property renders as
+ * a thumb of no size at all rather than as a full-length one.
+ */
+function fraction(part: number, whole: number): number {
+  if (!(whole > 0)) {
+    return 1;
+  }
+  return Math.min(1, Math.max(0, part / whole));
+}