@uniflowed/ui 0.0.0-alpha.9 → 0.2.0

package/internal/segmented-field.js

@@ -0,0 +1,317 @@
+// @flow
+"use client";
+import * as React from "@uniflowed/react";
+import { useMemo, useState } from "@uniflowed/react";
+import { useStableCallback } from "@uniflowed/hooks/lifecycle";
+import { Temporal } from "@uniflowed/core/temporal";
+import { useControlled } from "./controlled-state.js";
+import { composeHandlers, withProps } from "./merge-props.js";
+import type { RenderProp, Rest } from "./merge-props.js";
+import { directionOf } from "./roving-focus.js";
+import { useLocale } from "../i18n-provider.js";
+import { visuallyHiddenStyle } from "./visually-hidden-style.js";
+
+type Segment = "year" | "month" | "day" | "hour" | "minute" | "second" | "dayPeriod";
+type Fields = { [string]: string };
+export type DateFieldProps = {
+  value?: string | null,
+  defaultValue?: string | null,
+  onValueChange?: (value: string | null) => void,
+  minValue?: string,
+  isDateUnavailable?: (value: string) => boolean,
+  maxValue?: string,
+  disabled?: boolean,
+  readOnly?: boolean,
+  required?: boolean,
+  granularity?: "minute" | "second",
+  hourCycle?: "h12" | "h23",
+  segmentLabels?: { [string]: string },
+  onValidationChange?: (invalid: boolean) => void,
+  render?: RenderProp,
+  readonly key?: empty,
+  readonly [string]: mixed,
+};
+function names(time: boolean, seconds: boolean): Array<Segment> {
+  return time
+    ? seconds
+      ? ["hour", "minute", "second"]
+      : ["hour", "minute"]
+    : ["year", "month", "day"];
+}
+function fieldsFor(value: string | null, time: boolean, seconds: boolean): Fields {
+  if (value == null) return {};
+  const parsed = time ? Temporal.PlainTime.from(value) : Temporal.PlainDate.from(value);
+  const fields: Fields = {};
+  for (const name of names(time, seconds)) fields[name] = String((parsed as $FlowFixMe)[name]);
+  return fields;
+}
+function serialize(fields: Fields, time: boolean, seconds: boolean): string | null {
+  const parts = names(time, seconds);
+  if (parts.some((part) => !/^\d+$/.test(fields[part] ?? ""))) return null;
+  try {
+    if (time) {
+      const value = `${fields.hour.padStart(2, "0")}:${fields.minute.padStart(2, "0")}:${seconds ? fields.second.padStart(2, "0") : "00"}`;
+      const parsed = Temporal.PlainTime.from(value);
+      return parsed.toString().slice(0, seconds ? 8 : 5);
+    }
+    const year = Number(fields.year),
+      month = Number(fields.month),
+      day = Number(fields.day);
+    if (year < 1 || year > 9999) return null;
+    const parsed = Temporal.PlainDate.from({ year, month, day });
+    if (parsed.year !== year || parsed.month !== month || parsed.day !== day) return null;
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}
+function maximum(name: Segment, fields: Fields): number {
+  if (name === "year") return 9999;
+  if (name === "month") return 12;
+  if (name === "hour") return 23;
+  if (name !== "day") return 59;
+  try {
+    return Temporal.PlainDate.from({
+      year: Number(fields.year) || 2000,
+      month: Number(fields.month) || 1,
+      day: 1,
+    }).daysInMonth;
+  } catch {
+    return 31;
+  }
+}
+
+/** Segment order, digits and labels come from the locale; the stored value is ISO. */
+export component SegmentedField(time: boolean, options: DateFieldProps) {
+  const {
+    value,
+    defaultValue = null,
+    onValueChange,
+    minValue,
+    isDateUnavailable,
+    maxValue,
+    disabled = false,
+    readOnly = false,
+    required = false,
+    granularity = "minute",
+    hourCycle,
+    segmentLabels,
+    onValidationChange,
+    render,
+    ...rest
+  } = options;
+  const { locale } = useLocale();
+  const seconds = granularity === "second";
+  const [current, setCurrent] = useControlled(value, defaultValue, onValueChange);
+  const [draft, setDraft] = useState<Fields | null>(null);
+  const [announcement, announce] = useState("");
+  const fields = draft ?? fieldsFor(current, time, seconds);
+  const empty = names(time, seconds).every((part) => !fields[part]);
+  const serialized = serialize(fields, time, seconds);
+  const minimum =
+    minValue == null ? null : serialize(fieldsFor(minValue, time, seconds), time, seconds);
+  const maximumValue =
+    maxValue == null ? null : serialize(fieldsFor(maxValue, time, seconds), time, seconds);
+  if (minimum != null && maximumValue != null && minimum > maximumValue)
+    throw new RangeError("DateField minimum exceeds maximum");
+  const invalid =
+    (empty ? required : serialized == null) ||
+    (serialized != null &&
+      ((minimum != null && serialized < minimum) ||
+        (maximumValue != null && serialized > maximumValue) ||
+        isDateUnavailable?.(serialized) === true));
+  const digits = useMemo(() => new Intl.NumberFormat(locale, { useGrouping: false }), [locale]);
+  const labels: $FlowFixMe = useMemo(
+    () => new (Intl as $FlowFixMe).DisplayNames(locale, { type: "dateTimeField" }),
+    [locale],
+  );
+  const parts: Array<{ type: string, value: string }> = useMemo(() => {
+    const formatter: $FlowFixMe = new Intl.DateTimeFormat(
+      locale,
+      time
+        ? {
+            hour: "2-digit",
+            minute: "2-digit",
+            second: seconds ? "2-digit" : undefined,
+            hourCycle,
+            timeZone: "UTC",
+          }
+        : {
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            calendar: "gregory",
+            timeZone: "UTC",
+          },
+    );
+    return formatter.formatToParts(new Date("2000-01-02T12:34:56Z"));
+  }, [locale, time, seconds, hourCycle]);
+  const hour12 = time && parts.some((part) => part.type === "dayPeriod");
+  const periodNames: Array<string> = useMemo(() => {
+    const formatter: $FlowFixMe = new Intl.DateTimeFormat(locale, {
+      hour: "numeric",
+      hour12: true,
+      timeZone: "UTC",
+    });
+    return [0, 12].map(
+      (hour) =>
+        formatter
+          .formatToParts(new Date(Date.UTC(2000, 0, 1, hour)))
+          .find((part) => part.type === "dayPeriod")?.value ?? (hour === 0 ? "AM" : "PM"),
+    );
+  }, [locale]);
+  const encode = (text: string): string =>
+    Array.from(text)
+      .map((digit) => digits.format(Number(digit)))
+      .join("");
+  const decode = (text: string): string => {
+    let result = text;
+    for (let digit = 0; digit < 10; digit += 1)
+      result = result.split(digits.format(digit)).join(String(digit));
+    return result.replace(/[^0-9]/g, "");
+  };
+  const commit = useStableCallback(() => {
+    if (disabled || readOnly) return;
+    onValidationChange?.(invalid);
+    if (invalid) {
+      announce("Enter a valid value within the allowed range");
+      return;
+    }
+    setCurrent(empty ? null : serialized);
+    setDraft(null);
+    announce(serialized ?? "Cleared");
+  });
+  const edit = useStableCallback((part: Segment, text: string) => {
+    if (!disabled && !readOnly) setDraft({ ...fields, [part]: text });
+  });
+  const keyboard = useStableCallback((event: $FlowFixMe, part: Segment) => {
+    if (disabled || readOnly) return;
+    const key = event.key;
+    if (key === "Enter") {
+      event.preventDefault();
+      commit();
+      return;
+    }
+    if (key === "ArrowLeft" || key === "ArrowRight") {
+      event.preventDefault();
+      const root = event.currentTarget.closest("[data-segmented]");
+      const segments = Array.from(root.querySelectorAll("[data-segment]"));
+      const at = segments.indexOf(event.currentTarget);
+      const forward =
+        key === (directionOf(event.currentTarget) === "rtl" ? "ArrowLeft" : "ArrowRight");
+      (segments[at + (forward ? 1 : -1)] as $FlowFixMe)?.focus();
+      return;
+    }
+    if (!["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End"].includes(key)) return;
+    event.preventDefault();
+    const min = time && !(part === "hour" && hour12) ? 0 : 1,
+      max = part === "hour" && hour12 ? 12 : maximum(part, fields);
+    const raw = Number(fields[part] || min);
+    const current = part === "hour" && hour12 ? ((raw + 11) % 12) + 1 : raw;
+    const next =
+      key === "Home"
+        ? min
+        : key === "End"
+          ? max
+          : current +
+            (key === "ArrowUp" ? 1 : key === "ArrowDown" ? -1 : key === "PageUp" ? 10 : -10);
+    const bounded = next > max ? min : next < min ? max : next;
+    const adjusted =
+      part === "hour" && hour12 ? (bounded % 12) + (Number(fields.hour) >= 12 ? 12 : 0) : bounded;
+    const nextFields = { ...fields, [part]: String(adjusted) };
+    if (!time && (part === "month" || part === "year") && nextFields.day)
+      nextFields.day = String(Math.min(Number(nextFields.day), maximum("day", nextFields)));
+    setDraft(nextFields);
+  });
+  const segments = parts.map((part, index) => {
+    if (part.type === "dayPeriod") {
+      const pm = Number(fields.hour) >= 12;
+      const toggle = () => edit("hour", String((Number(fields.hour) || 0) + (pm ? -12 : 12)));
+      return (
+        <span
+          key="period"
+          role="spinbutton"
+          tabIndex={disabled ? -1 : 0}
+          data-segment="dayPeriod"
+          aria-label={segmentLabels?.dayPeriod ?? labels.of("dayPeriod")}
+          aria-valuemin={0}
+          aria-valuemax={1}
+          aria-valuenow={pm ? 1 : 0}
+          aria-valuetext={periodNames[pm ? 1 : 0]}
+          aria-disabled={disabled || undefined}
+          aria-readonly={readOnly || undefined}
+          onClick={toggle}
+          onKeyDown={(event) => {
+            if (disabled || readOnly) return;
+            if (["ArrowUp", "ArrowDown", "Home", "End", " "].includes(event.key)) {
+              event.preventDefault();
+              if ((event.key !== "Home" || pm) && (event.key !== "End" || !pm)) toggle();
+            } else if (["ArrowLeft", "ArrowRight", "Enter"].includes(event.key))
+              keyboard(event, "dayPeriod");
+          }}
+        >
+          {periodNames[pm ? 1 : 0]}
+        </span>
+      );
+    }
+
+    if (!names(time, seconds).includes(part.type as $FlowFixMe))
+      return (
+        <span key={index} aria-hidden="true">
+          {part.value}
+        </span>
+      );
+    const name: Segment = part.type as $FlowFixMe;
+    const raw = fields[name] ?? "";
+    const text =
+      name === "hour" && hour12 && raw !== "" ? String(((Number(raw) + 11) % 12) + 1) : raw;
+    return (
+      <input
+        key={name}
+        type="text"
+        role="spinbutton"
+        inputMode="numeric"
+        data-segment={name}
+        aria-label={segmentLabels?.[name] ?? labels.of(name)}
+        aria-valuemin={time && !(name === "hour" && hour12) ? 0 : 1}
+        aria-valuemax={name === "hour" && hour12 ? 12 : maximum(name, fields)}
+        aria-valuenow={text ? Number(text) : undefined}
+        aria-valuetext={text ? encode(text) : undefined}
+        aria-invalid={invalid || undefined}
+        disabled={disabled}
+        readOnly={readOnly}
+        required={required}
+        maxLength={name === "year" ? 4 : 2}
+        placeholder={name === "year" ? "yyyy" : "--"}
+        value={text ? encode(text) : ""}
+        onChange={(event) => {
+          const text = decode(event.currentTarget.value);
+          edit(
+            name,
+            name === "hour" && hour12 && text && Number(text) <= 12
+              ? String((Number(text) % 12) + (Number(fields.hour) >= 12 ? 12 : 0))
+              : text,
+          );
+        }}
+        onKeyDown={(event) => keyboard(event, name)}
+      />
+    );
+  });
+  const props = withProps(rest, {
+    role: "group",
+    "data-segmented": time ? "time" : "date",
+    "aria-invalid": invalid || rest["aria-invalid"],
+    onBlur: composeHandlers(rest.onBlur, (event: $FlowFixMe) => {
+      if (!event.currentTarget.contains(event.relatedTarget)) commit();
+    }),
+    children: (
+      <>
+        {segments}
+        <span role="status" aria-live="polite" style={visuallyHiddenStyle}>
+          {announcement}
+        </span>
+      </>
+    ),
+  });
+  return render != null ? render(props) : <div {...props} />;
+}

package/internal/selection.js

@@ -0,0 +1,171 @@
+// @flow
+//
+// What a collection's selection becomes after one gesture, as pure functions.
+//
+// `ListBox`, `GridList`, `Tree` and `TagGroup` all ask the same four questions
+// — toggle this key, make it the only one, extend to it, take everything — and
+// the answers depend on three settings rather than on which collection is
+// asking. Keeping them here, apart from React, is what lets every rule be
+// tested without rendering and lets all four collections agree by construction.
+//
+// The rules are React Aria's selection manager (`@react-stately/selection`),
+// which is itself the WAI-ARIA APG's listbox and grid selection models made
+// precise:
+//
+//   * `mode` is what may be chosen: nothing, one key, or any number.
+//   * `behavior` is what a plain gesture does. `"toggle"` flips the key — the
+//     checkbox model, right for touch and for lists whose rows carry a
+//     checkbox. `"replace"` makes the key the whole selection — the file
+//     manager model, where Ctrl/Cmd adds one and Shift adds a range.
+//   * `disallowEmpty` refuses the gesture that would leave nothing selected,
+//     rather than accepting it and then reselecting.
+//
+// Every function returns the *same* set it was given when nothing changes, so a
+// caller can compare by identity and skip `onSelectionChange` for a gesture
+// that did nothing — a controlled parent is not told about a change that is
+// not one.
+//
+// # Why this is `internal/`
+//
+// A public selection manager would be a second way to build a collection, and
+// the point of this package is that there is one. The collections are the
+// public surface; `packages/ui/index.js` says why the internals stay internal.
+
+export type SelectionMode = "none" | "single" | "multiple";
+export type SelectionBehavior = "toggle" | "replace";
+
+/** The three settings every answer below depends on. */
+export type SelectionPolicy = {|
+  readonly mode: SelectionMode,
+  readonly behavior: SelectionBehavior,
+  readonly disallowEmpty: boolean,
+|};
+
+/**
+ * The keys a range covers, in collection order, inclusive at both ends.
+ *
+ * `order` is the selectable keys only — disabled rows are not in it — so a range
+ * dragged across a disabled row does not pick it up, which is what React Aria
+ * and every native list do. An end that is not in `order` (a key filtered out
+ * since it was chosen) contributes nothing rather than stretching the range to
+ * the start of the list.
+ */
+export function keyRange(
+  order: $ReadOnlyArray<string>,
+  from: string,
+  to: string,
+): $ReadOnlyArray<string> {
+  const start = order.indexOf(from);
+  const end = order.indexOf(to);
+  if (start < 0 || end < 0) return end < 0 ? [] : [to];
+  return order.slice(Math.min(start, end), Math.max(start, end) + 1);
+}
+
+/** Flip one key, unless that would empty a selection that must not be empty. */
+export function toggleKey(
+  policy: SelectionPolicy,
+  selected: $ReadOnlySet<string>,
+  key: string,
+): $ReadOnlySet<string> {
+  if (policy.mode === "none") return selected;
+  if (selected.has(key)) {
+    if (policy.disallowEmpty && selected.size === 1) return selected;
+    if (policy.mode === "single") return new Set();
+    const next = new Set(selected);
+    next.delete(key);
+    return next;
+  }
+  if (policy.mode === "single") return new Set([key]);
+  const next = new Set(selected);
+  next.add(key);
+  return next;
+}
+
+/** Make one key the whole selection. */
+export function replaceWith(
+  policy: SelectionPolicy,
+  selected: $ReadOnlySet<string>,
+  key: string,
+): $ReadOnlySet<string> {
+  if (policy.mode === "none") return selected;
+  if (selected.size === 1 && selected.has(key)) return selected;
+  return new Set([key]);
+}
+
+/**
+ * Extend from `anchor` to `key`, replacing the range the previous extension made.
+ *
+ * `lead` is where the last extension ended. Shift+Down, Shift+Down, Shift+Up
+ * must end with two rows selected rather than three, so the old range
+ * (`anchor`…`lead`) comes out before the new one (`anchor`…`key`) goes in —
+ * while anything selected outside both ranges, by an earlier Ctrl/Cmd+click,
+ * stays. With no anchor the extension starts at `key`.
+ */
+export function extendTo(
+  policy: SelectionPolicy,
+  selected: $ReadOnlySet<string>,
+  order: $ReadOnlyArray<string>,
+  anchor: string | null,
+  lead: string | null,
+  key: string,
+): $ReadOnlySet<string> {
+  if (policy.mode === "none") return selected;
+  if (policy.mode === "single") return replaceWith(policy, selected, key);
+  const from = anchor ?? key;
+  const next = new Set(selected);
+  if (lead != null) for (const each of keyRange(order, from, lead)) next.delete(each);
+  for (const each of keyRange(order, from, key)) next.add(each);
+  if (next.size === 0 && policy.disallowEmpty) return selected;
+  return sameKeys(next, selected) ? selected : next;
+}
+
+/** Every selectable key, when more than one may be chosen. */
+export function selectAll(
+  policy: SelectionPolicy,
+  selected: $ReadOnlySet<string>,
+  order: $ReadOnlyArray<string>,
+): $ReadOnlySet<string> {
+  if (policy.mode !== "multiple" || order.length === 0) return selected;
+  const next = new Set(selected);
+  for (const key of order) next.add(key);
+  return sameKeys(next, selected) ? selected : next;
+}
+
+/** Nothing, unless nothing is not allowed. */
+export function clearAll(
+  policy: SelectionPolicy,
+  selected: $ReadOnlySet<string>,
+): $ReadOnlySet<string> {
+  if (policy.mode === "none" || policy.disallowEmpty || selected.size === 0) return selected;
+  return new Set();
+}
+
+/**
+ * A selection as the array `onSelectionChange` reports: collection order first,
+ * then any key the collection is not showing, in the order it was chosen.
+ *
+ * Keys the collection is not showing are real — a child of a collapsed tree
+ * row, a row a filter hid — and dropping them because they are out of sight
+ * would deselect something the reader chose and cannot see go.
+ */
+export function orderedKeys(
+  selected: $ReadOnlySet<string>,
+  order: $ReadOnlyArray<string>,
+): $ReadOnlyArray<string> {
+  const result = [];
+  const placed = new Set<string>();
+  for (const key of order) {
+    if (selected.has(key)) {
+      result.push(key);
+      placed.add(key);
+    }
+  }
+  for (const key of selected) if (!placed.has(key)) result.push(key);
+  return result;
+}
+
+function sameKeys(a: $ReadOnlySet<string>, b: $ReadOnlySet<string>): boolean {
+  if (a.size !== b.size) return false;
+  for (const key of a) if (!b.has(key)) return false;
+  return true;
+}

package/internal/visually-hidden-style.js

@@ -0,0 +1,41 @@
+// @flow
+//
+// The one inline style for "hidden from sight, present for a screen reader".
+//
+// Its own module, with no `"use client"`, so a part that renders on the server
+// can import it without importing `visually-hidden.js` — a client module whose
+// every export is a client reference to a Server Component. Internal for the
+// reason `packages/ui/index.js` gives about every module here: the public
+// answer is `VisuallyHidden`.
+
+/**
+ * The style that hides an element from sight and from nothing else.
+ *
+ * Shared by `VisuallyHidden` and by the parts that keep a live region of their
+ * own beside what they render — the table's sort announcement, the
+ * collections', the calendar's and the range calendar's, and the segmented
+ * fields'. Frozen, because every one of them holds the same object.
+ */
+export const visuallyHiddenStyle: {|
+  readonly border: number,
+  readonly clip: string,
+  readonly clipPath: string,
+  readonly height: number,
+  readonly margin: number,
+  readonly overflow: string,
+  readonly padding: number,
+  readonly position: string,
+  readonly whiteSpace: string,
+  readonly width: number,
+|} = 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,
+});

package/list-box.js

@@ -0,0 +1,13 @@
+// @flow
+"use client";
+import * as React from "@uniflowed/react";
+import { CollectionRoot } from "./internal/collection.js";
+import type { CollectionProps } from "./internal/collection.js";
+export component ListBox(...props: CollectionProps) {
+  return <CollectionRoot options={props} kind="listbox" />;
+}
+export type {
+  CollectionItem,
+  CollectionItemState,
+  CollectionProps,
+} from "./internal/collection.js";