@uniflowed/ui 0.0.0-alpha.8 → 0.1.0

package/hover-card.js

@@ -0,0 +1,334 @@
+// @flow
+//
+// A hover card: the preview a name expands into, taken seriously.
+//
+// It is a tooltip's sibling and it is not a tooltip, and the difference is what
+// is inside. A tooltip holds a phrase and must never be focusable; a hover card
+// holds an avatar, a paragraph and two links, and every one of those has to be
+// reachable — so the pointer has to be able to get there and so does `Tab`.
+//
+// That makes SC 1.4.13's hoverable clause the whole component rather than a
+// detail of it: the gap between a name and the card that describes it takes a
+// moment to cross with a mouse, longer with a trackpad, and much longer for a
+// reader magnifying the screen. Closing on `pointerleave` snatches it away
+// mid-journey. `internal/hover-intent.js` is the delay that stops that, shared
+// with `tooltip.js` so the two cannot drift.
+//
+// # What it is not
+//
+// **Not a dialog.** It carries no `role="dialog"` and no `aria-modal`: nothing
+// about it is modal, focus is not moved into it when it opens, and announcing a
+// dialog a reader never asked for is worse than announcing nothing. Its content
+// is in the document immediately after its trigger, so the reading order
+// carries it and `Tab` reaches it — which is the whole of what a keyboard
+// reader needs from it.
+//
+// **Not described by `aria-describedby`.** A card of links flattened into one
+// description string is a sentence nobody can act on: the links stop being
+// links. `tooltip.js` describes its trigger because a tooltip is a phrase; this
+// does not, because this is not.
+//
+// # Touch
+//
+// It does not open on touch, for the reason `tooltip.js` gives at more length:
+// there is no hover on a touch screen, and the only gesture left is the tap the
+// trigger itself needs. A hover card is therefore an *enrichment* — the link
+// under it must go somewhere useful on its own, because a reader on a phone
+// will only ever get the link.
+
+"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 { useStableCallback } from "@uniflowed/hooks/lifecycle";
+
+import type { Align, LogicalSide } from "./internal/anchor.js";
+import type { HoverIntent } from "./internal/hover-intent.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { composeRefs, withProps, withoutComposed } from "./internal/merge-props.js";
+import {
+  DEFAULT_CLOSE_DELAY,
+  DEFAULT_OPEN_DELAY,
+  useDismissOnEscape,
+  useFocusableTrigger,
+  useHoverIntent,
+} from "./internal/hover-intent.js";
+import { useAnchor } from "./internal/anchor.js";
+import { useControlled } from "./internal/controlled-state.js";
+
+export type { Align, LogicalSide, Side } from "./internal/anchor.js";
+
+type HoverCardState = {|
+  readonly base: string,
+  readonly open: boolean,
+  readonly setOpen: (open: boolean) => void,
+  readonly triggerRef: { current: HTMLElement | null },
+  readonly intent: HoverIntent,
+  readonly openDelay: number,
+  readonly closeDelay: number,
+  /** Whether `Escape` has dismissed it; see `tooltip.js`, which shares the rule. */
+  readonly dismissedRef: { current: boolean },
+|};
+
+const HoverCardContext: React.Context<HoverCardState | null> = createContext(null);
+
+hook useHoverCard(part: string): HoverCardState {
+  const state = useContext(HoverCardContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a HoverCard.Root`);
+  }
+  return state;
+}
+
+/**
+ * A hover card and the thing it previews.
+ *
+ * `closeDelay` is longer than a tooltip's would need to be on purpose: it is
+ * the time the reader has to reach the card, and a card holding links is a card
+ * they are reaching for.
+ */
+export component HoverCardRoot(
+  children: React.Node,
+  closeDelay?: number = DEFAULT_CLOSE_DELAY,
+  defaultOpen?: boolean = false,
+  onOpenChange?: (open: boolean) => void,
+  open?: boolean,
+  openDelay?: number = DEFAULT_OPEN_DELAY,
+) {
+  const base = useId();
+  const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const dismissedRef = useRef(false);
+  const intent = useHoverIntent(setOpen);
+
+  const state = useMemo(
+    () => ({
+      base,
+      closeDelay,
+      dismissedRef,
+      intent,
+      open: isOpen,
+      openDelay,
+      setOpen,
+      triggerRef,
+    }),
+    [base, closeDelay, intent, isOpen, openDelay, setOpen],
+  );
+
+  return <HoverCardContext.Provider value={state}>{children}</HoverCardContext.Provider>;
+}
+
+/**
+ * What the card is about, which is usually a link.
+ *
+ * `render` is how it becomes one: `<HoverCard.Trigger render={(props) => <a
+ * href={profile} {...props}>@ada</a>} />`. Whatever it ends up as has to be
+ * reachable by keyboard, and `useFocusableTrigger` refuses anything else —
+ * a hover card on a `<span>` is one a keyboard reader can never see.
+ */
+export component HoverCardTrigger(children?: React.Node, render?: RenderProp, ...rest: Rest) {
+  const card = useHoverCard("HoverCard.Trigger");
+  const { closeDelay, dismissedRef, intent, openDelay, triggerRef } = card;
+  useFocusableTrigger(triggerRef, "HoverCard.Trigger");
+
+  // A press focuses the trigger, and a card opening under the reader's own
+  // click would cover what they just went to. See `tooltip.js`.
+  const pressedRef = useRef(false);
+
+  useEventListener(triggerRef, "pointerenter", (event: $FlowFixMe) => {
+    if (event.pointerType === "touch" || dismissedRef.current) {
+      return;
+    }
+    intent.openAfter(openDelay);
+  });
+  useEventListener(triggerRef, "pointerleave", () => {
+    dismissedRef.current = false;
+    intent.closeAfter(closeDelay);
+  });
+  useEventListener(triggerRef, "pointerdown", () => {
+    pressedRef.current = true;
+    intent.cancel();
+  });
+  useEventListener(triggerRef, "focusin", () => {
+    if (pressedRef.current) {
+      pressedRef.current = false;
+      return;
+    }
+    // The focus a dismissed card hands *back* to this trigger must not reopen
+    // it, which is the whole reason the flag exists: without it `Escape` closes
+    // the card, focus returns here, and the card comes straight back.
+    if (dismissedRef.current) {
+      return;
+    }
+    // A reader who tabbed here has said what they want; only the pointer is
+    // guessed at, so only the pointer waits.
+    intent.openAfter(0);
+  });
+  useEventListener(triggerRef, "focusout", () => {
+    pressedRef.current = false;
+    dismissedRef.current = false;
+    // `closeAfter` rather than a close, and this is where the delay earns its
+    // keep a second time: `Tab` from the trigger *into* the card is a leave
+    // followed immediately by an arrival, and the card's own `focusin` calls
+    // this off before it runs. A `closeDelay` of nought would close the card
+    // in the instant the reader reached it, which is why the default is not
+    // nought and why a caller who sets one should not set that.
+    intent.closeAfter(closeDelay);
+  });
+
+  // Annotated because this one is not written inside a `ref={...}`, and there
+  // is nothing else here for Flow to infer the element's type from.
+  // React calls callback refs during commit; pointer and focus handlers read it later.
+  // uf-lint-disable-next-line react-compiler/refs
+  const attach = composeRefs(rest.ref, (element: HTMLElement | null) => {
+    triggerRef.current = element;
+  });
+
+  const props = withProps(withoutComposed(rest, ["ref"]), { children, ref: attach });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
+}
+
+/**
+ * The card.
+ *
+ * Stays while the pointer is over it and while focus is inside it, which are
+ * the same rule applied to the two ways a reader can be in it. `Escape` closes
+ * it from either — and when focus was inside, focus goes back to the trigger,
+ * because a card that took its own links away and left focus on `<body>` would
+ * send the reader back to the top of the page.
+ */
+export component HoverCardBody(
+  children: React.Node,
+  align?: Align = "center",
+  alignOffset?: number = 0,
+  avoidCollisions?: boolean = true,
+  collisionPadding?: number = 0,
+  render?: RenderProp,
+  side?: LogicalSide = "bottom",
+  sideOffset?: number = 0,
+  ...rest: Rest
+) {
+  const card = useHoverCard("HoverCard.Body");
+  const { closeDelay, dismissedRef, intent, open, triggerRef } = card;
+  const bodyRef = useRef<HTMLElement | null>(null);
+  // Whether the reader is *in* the card, as opposed to over it. It decides one
+  // thing and it cannot be asked afterwards: a card closed while it held focus
+  // has to hand focus back, and by the time the effect below is cleaned up the
+  // element is gone from the document and `activeElement` has already fallen to
+  // `<body>` — so the answer is kept while it is still true.
+  const heldRef = useRef(false);
+  const close = useStableCallback(() => {
+    dismissedRef.current = true;
+    intent.cancel();
+    card.setOpen(false);
+  });
+
+  const anchored = useAnchor({
+    align,
+    alignOffset,
+    anchorRef: triggerRef,
+    avoidCollisions,
+    collisionPadding,
+    open,
+    overlayRef: bodyRef,
+    side,
+    sideOffset,
+  });
+
+  useDismissOnEscape(open, bodyRef, close);
+
+  // Keyed on `open`, because the element does not exist until then; see
+  // `tooltip.js` for why `useEventListener` cannot be used here.
+  useEffect(() => {
+    const body = bodyRef.current;
+    if (!open || body == null) {
+      return;
+    }
+    const stay = () => intent.cancel();
+    const go = () => intent.closeAfter(closeDelay);
+    const arrived = () => {
+      heldRef.current = true;
+      stay();
+    };
+    const gone = () => {
+      heldRef.current = false;
+      go();
+    };
+    body.addEventListener("pointerenter", stay);
+    body.addEventListener("pointerleave", go);
+    // `focusin` and `focusout` rather than `focus` and `blur`: the pair that
+    // bubbles is the one that hears a reader moving between two links *inside*
+    // the card, where the leave is immediately followed by an arrival and the
+    // scheduled close is called off before it runs.
+    body.addEventListener("focusin", arrived);
+    body.addEventListener("focusout", gone);
+
+    return () => {
+      body.removeEventListener("pointerenter", stay);
+      body.removeEventListener("pointerleave", go);
+      body.removeEventListener("focusin", arrived);
+      body.removeEventListener("focusout", gone);
+    };
+  }, [open, intent, closeDelay, triggerRef]);
+
+  // Focus goes back to the trigger when the card *closes* under the reader's
+  // focus, which is what `Escape` does: focus was on a link that no longer
+  // exists, and leaving it on `<body>` sends the reader back to the top of the
+  // page. A card that closed because the pointer left, with focus somewhere
+  // else entirely, has no business moving it.
+  //
+  // Its own effect, keyed on `open` alone. It used to live in the cleanup of
+  // the listener effect above, which runs whenever any of that effect's
+  // dependencies change — and `closeDelay` is a caller's prop. A caller
+  // changing it while the card was open with focus inside pulled focus off the
+  // link the reader was on, and the effect then re-attached with `held` reset.
+  useEffect(() => {
+    if (open) {
+      return;
+    }
+    if (heldRef.current) {
+      heldRef.current = false;
+      triggerRef.current?.focus?.();
+    }
+  }, [open, triggerRef]);
+
+  // And on unmount, which the effect above cannot see: a card removed while
+  // the reader is inside it leaves focus on a node that is gone.
+  useEffect(
+    () => () => {
+      if (heldRef.current) {
+        heldRef.current = false;
+        triggerRef.current?.focus?.();
+      }
+    },
+    [triggerRef],
+  );
+
+  if (!open) {
+    return null;
+  }
+
+  const props = withProps(withoutComposed(rest, ["ref"]), {
+    children,
+    "data-align": anchored.align,
+    "data-side": anchored.side,
+    "data-state": "open",
+    id: `${card.base}-body`,
+    // React calls callback refs during commit; placement effects read it later.
+    // uf-lint-disable-next-line react-compiler/refs
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      bodyRef.current = element;
+    }),
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+
+  return <div {...props} />;
+}

package/i18n-provider.js

@@ -0,0 +1,89 @@
+// @flow
+"use client";
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useMemo } from "@uniflowed/react";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { withProps } from "./internal/merge-props.js";
+
+export type Locale = {| readonly locale: string, readonly direction: "ltr" | "rtl" |};
+const LocaleContext: React.Context<Locale> = createContext({ locale: "en-US", direction: "ltr" });
+
+/** An explicit locale keeps server and client output identical. Nested providers form islands. */
+export component I18nProvider(
+  children: React.Node,
+  locale?: string,
+  direction?: "ltr" | "rtl",
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const parent = useLocale();
+  const state = useMemo((): Locale => {
+    const resolved = new Intl.Locale(locale ?? parent.locale);
+    const script = resolved.maximize().script;
+    const rtl = ["Arab", "Hebr", "Thaa", "Nkoo", "Adlm", "Rohg"].includes(script ?? "");
+    return {
+      locale: resolved.toString(),
+      direction: direction ?? (locale == null ? parent.direction : rtl ? "rtl" : "ltr"),
+    };
+  }, [locale, direction, parent]);
+  const props = withProps(rest, { children, lang: state.locale, dir: state.direction });
+  return (
+    <LocaleContext.Provider value={state}>
+      {render != null ? render(props) : <div {...props} />}
+    </LocaleContext.Provider>
+  );
+}
+
+export hook useLocale(): Locale {
+  return useContext(LocaleContext);
+}
+
+/** Share Intl's language-specific ordering with caller-owned collections. */
+export hook useCollator(options?: Intl$CollatorOptions): Intl$Collator {
+  const { locale } = useLocale();
+  return useMemo(() => new Intl.Collator(locale, options), [locale, options]);
+}
+
+// Bound the cache when a long-lived server serves many requested locales.
+const searchCollators = new Map<string, Intl$Collator>();
+function searchCollator(locale: string): Intl$Collator {
+  const cached = searchCollators.get(locale);
+  if (cached != null) return cached;
+  const collator = new Intl.Collator(locale, { usage: "search", sensitivity: "base" });
+  if (searchCollators.size >= 32) searchCollators.clear();
+  searchCollators.set(locale, collator);
+  return collator;
+}
+
+export function startsWithLocale(text: string, query: string, locale: string): boolean {
+  const value = text.normalize("NFC");
+  const needle = query.normalize("NFC");
+  return (
+    searchCollator(locale).compare(
+      Array.from(value).slice(0, Array.from(needle).length).join(""),
+      needle,
+    ) === 0
+  );
+}
+
+/** Filtering uses the same collation as typeahead; consumers own the result list. */
+export hook useFilter(): {
+  startsWith: (text: string, query: string) => boolean,
+  contains: (text: string, query: string) => boolean,
+} {
+  const { locale } = useLocale();
+  return useMemo(
+    () => ({
+      startsWith: (text, query) => startsWithLocale(text, query, locale),
+      contains: (text, query) => {
+        const chars = Array.from(text.normalize("NFC"));
+        return (
+          query === "" ||
+          chars.some((_, index) => startsWithLocale(chars.slice(index).join(""), query, locale))
+        );
+      },
+    }),
+    [locale],
+  );
+}