@lumiose/ui 0.0.0-stage → 0.1.0

package/dist/popover/popover.script.ts

@@ -0,0 +1,256 @@
+// Popover's client script (decision-62's "native gaps are closed by small scripts", shipped through
+// the client-script import of decision-63). Popover works without it; on a page that renders one,
+// this module runs once and closes what a native `popover="auto"` misses next to Base UI and Zag
+// (doc-9), for every Popover popup on the page (`[popover][data-side][role=dialog]`):
+//
+// - Focus on open: the first focusable element, or the popup itself when there is none or when it
+//   was opened by touch (no virtual keyboard). The browser only focuses an `autofocus` element.
+// - Focus return: when closing leaves focus nowhere (a click outside on the page, WebKit not
+//   focusing a clicked trigger, a trigger that is gone), focus goes to the opener, else a trigger,
+//   without scrolling. A click outside on another control keeps focus there.
+// - Dismissal: the dismissal model Popover shares with Menu and Combobox (layer/layer.ts). A
+//   trigger's click makes the popup a manual popover before `popovertarget` opens it, so a
+//   right-click or a second finger outside does not close it (native light dismiss would, and
+//   cannot be cancelled); the layer model closes it on a main-button press outside, a close
+//   request, or another layer opening outside it. Server HTML keeps `popover="auto"`, so the
+//   browser light-dismisses it until the script runs.
+// - `aria-expanded` on the triggers, following the popover.
+// - Placement where CSS anchor positioning is missing (placement/place.ts).
+// - Open on hover (TASK-394): a trigger with `data-open-on-hover` opens its popover after
+//   `data-delay` (300 ms) of hover by a mouse or a pen, never by touch or focus, without moving
+//   focus. It stays open while the pointer is on the trigger or the popup (WCAG 1.4.13: hoverable)
+//   and closes `data-close-delay` (0 ms, at least a 100 ms grace to cross the gap) after it left
+//   both. A click on the trigger keeps it open until it is dismissed (an outside press, Escape).
+// - A modal popover is a modal `<dialog data-side>` opened by `command="show-modal"`: placement,
+//   focus and `aria-expanded` as above; Dialog's script and the native dialog do the rest.
+// - `data-trap-focus` (`modal="trap-focus"`, TASK-410): Tab and Shift+Tab go around the open
+//   popup's tab stops (not a roving item, nor an unchecked radio of a group with a checked one),
+//   and the popup stays non-modal otherwise (the page scrolls and takes presses). Focus on open
+//   goes to the first tab stop too (TASK-436 M4).
+// - Focus leaving a non-modal popover for elsewhere on the page (Tab past it) closes it, so it
+//   covers no focused control (TASK-436 M2). Focus going nowhere is left to the outside press, and
+//   focus into a toast leaves it open, as a press there does.
+// - A popover a hover opened gives focus back on close only if it held focus (TASK-436 M3).
+//
+// It must not import `lumiose`: server-rendered pages load it without the runtime.
+import { openLayer } from "../layer/layer.ts";
+import { hoverIntent } from "./hover.ts";
+import { anchoring, place } from "../placement/place.ts";
+
+/** The last press, until a key is pressed: what an opening came from. */
+let press: PointerEvent | undefined;
+const openers = new WeakMap<HTMLElement, HTMLElement>();
+/** The popovers that held focus as they started to close. */
+const holding = new WeakSet<HTMLElement>();
+/** The open popovers that the fallback placement follows on scroll and resize. */
+const placed = new Set<HTMLElement>();
+
+const FOCUSABLE =
+  "a[href], button:not([disabled]), input:not([disabled]):not([type=hidden]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex='-1']), [contenteditable]";
+
+function on<K extends keyof DocumentEventMap>(
+  type: K,
+  listener: (event: DocumentEventMap[K]) => void,
+) {
+  document.addEventListener(type, listener, true);
+}
+
+/**
+ * The popup's tab stops, in order: focusable and shown, not taken out of the order (`tabindex="-1"`,
+ * a roving toolbar's or toggle group's other items), and one radio per group (the checked one, or
+ * the first enabled one).
+ */
+function tabStops(popup: HTMLElement): HTMLElement[] {
+  return [...popup.querySelectorAll<HTMLElement>(FOCUSABLE)].filter((element) => {
+    if (element.tabIndex < 0 || !element.checkVisibility()) return false;
+    if (!(element instanceof HTMLInputElement) || element.type !== "radio" || !element.name) {
+      return true;
+    }
+    const group = [
+      ...popup.querySelectorAll<HTMLInputElement>(
+        `input[type=radio][name="${CSS.escape(element.name)}"]`,
+      ),
+    ].filter((radio) => !radio.disabled);
+    return element === (group.find((radio) => radio.checked) ?? group[0]);
+  });
+}
+
+const isPopover = (node: unknown): node is HTMLElement =>
+  node instanceof HTMLElement &&
+  node.matches("[popover][data-side][role=dialog], dialog[data-side]");
+
+/** The buttons that open or toggle the popover. */
+const triggers = (popup: HTMLElement) => {
+  const id = CSS.escape(popup.id);
+  return document.querySelectorAll<HTMLElement>(
+    `[popovertarget="${id}"]:not([popovertargetaction=hide]), [commandfor="${id}"][command=show-modal]`,
+  );
+};
+
+function anchor(popup: HTMLElement): HTMLElement | undefined {
+  const opener = openers.get(popup);
+  return opener?.isConnected ? opener : (triggers(popup)[0] ?? undefined);
+}
+
+function follow() {
+  for (const popup of placed) {
+    const trigger = anchor(popup);
+    if (trigger) place(popup, trigger);
+  }
+}
+
+on("pointerdown", (event) => (press = event));
+on("keydown", () => (press = undefined));
+
+on("keydown", (event) => {
+  if (event.key !== "Tab" || event.defaultPrevented || event.altKey || event.ctrlKey) return;
+  const popup = (event.target as Element).closest?.<HTMLElement>("[data-trap-focus]");
+  if (!isPopover(popup) || !popup.matches(":popover-open")) return;
+  const stops = tabStops(popup);
+  const first = stops[0];
+  const last = stops.at(-1);
+  const at = event.target as HTMLElement;
+  const wrap = !first
+    ? popup
+    : event.shiftKey
+      ? at === first || at === popup
+        ? last
+        : undefined
+      : at === last
+        ? first
+        : undefined;
+  if (!wrap) return;
+  event.preventDefault();
+  wrap.focus();
+});
+
+/** Stops dismissing each open popover (layer/layer.ts). */
+const layers = new Map<HTMLElement, () => void>();
+
+// Before `popovertarget` acts: a closed popup becomes a manual popover, which the layer model
+// dismisses. A key press on the trigger clicks it too. A click on the trigger of a popover its
+// hover opened keeps it open instead of closing it.
+on("click", (event) => {
+  const trigger = (event.target as Element).closest?.<HTMLElement>("[popovertarget]");
+  const popup = trigger && document.getElementById(trigger.getAttribute("popovertarget")!);
+  if (!isPopover(popup) || trigger!.matches("[popovertargetaction=hide]")) return;
+  if (!popup.matches(":popover-open")) popup.popover = "manual";
+  else if (hovered.has(popup)) {
+    event.preventDefault();
+    hover.forget(popup);
+  }
+});
+
+// Focus leaving an open non-modal popover (and those around it) for elsewhere on the page closes
+// it; a trap-focus popover keeps focus in itself.
+on("focusout", (event) => {
+  const from = event.target as Node;
+  const to = event.relatedTarget as Node | null;
+  // Focus going nowhere is the outside press's to judge; into a toast, it leaves layers alone.
+  if (!to || (to instanceof Element && to.closest("lu-toast-viewport"))) return;
+  const open = document.querySelectorAll<HTMLElement>(
+    "[popover][data-side][role=dialog]:popover-open:not([data-trap-focus])",
+  );
+  for (const popup of [...open].toReversed()) {
+    if (!popup.contains(from) || popup.contains(to)) continue;
+    if ([...triggers(popup)].some((trigger) => trigger.contains(to))) continue;
+    popup.hidePopover();
+  }
+});
+
+// Open on hover (hover.ts) -------------------------------------------------------------------
+
+const hover = hoverIntent({
+  triggerAt: (node) =>
+    node.closest?.<HTMLElement>("button[data-open-on-hover][popovertarget]") ?? undefined,
+  popupOf: (trigger) => {
+    const popup = document.getElementById(trigger.getAttribute("popovertarget")!);
+    return isPopover(popup) ? popup : undefined;
+  },
+  show: (trigger, popup) => {
+    // A hover-opened popover leaves focus where it is (see `toggle`).
+    popup.popover = "manual";
+    (popup.showPopover as (options?: { source?: HTMLElement }) => void)({ source: trigger });
+  },
+  hide: (popup) => popup.hidePopover(),
+  delay: 300,
+  closeDelay: 0,
+});
+const hovered = hover.hovered;
+
+/** Stops dismissing `popup`: as it closes, so the next close request goes to the layer below. */
+function release(popup: HTMLElement) {
+  layers.get(popup)?.();
+  layers.delete(popup);
+}
+
+on("beforetoggle", (event) => {
+  const popup = event.target;
+  if (!isPopover(popup)) return;
+  release(popup);
+  if (event.newState === "closed") {
+    if (popup.contains(document.activeElement)) holding.add(popup);
+    return;
+  }
+  // Now, not on `toggle` a task later: a press right after the opening already counts.
+  if (popup.popover === "manual") {
+    layers.set(
+      popup,
+      openLayer({
+        popup,
+        contains: (node) =>
+          popup.contains(node) || [...triggers(popup)].some((trigger) => trigger.contains(node)),
+        dismiss: () => popup.hidePopover(),
+      }),
+    );
+  }
+  const active = document.activeElement;
+  const pressed = press && (press.target as Element).closest?.<HTMLElement>("[popovertarget]");
+  const opener = active instanceof HTMLElement && active !== document.body ? active : pressed;
+  if (opener) openers.set(popup, opener);
+  // Placed in the frame it first paints in, once it can be measured (`toggle` may come later).
+  if (!anchoring) {
+    requestAnimationFrame(() => {
+      if (!popup.matches(":popover-open")) return;
+      placed.add(popup);
+      follow();
+    });
+  }
+});
+
+on("toggle", (event) => {
+  const popup = event.target;
+  if (!isPopover(popup)) return;
+  const open = event.newState === "open";
+  for (const trigger of triggers(popup)) trigger.setAttribute("aria-expanded", String(open));
+
+  if (open) {
+    // A hover opens it without taking focus from where it is.
+    if (hovered.has(popup) || popup.contains(document.activeElement)) return;
+    const touch = press?.pointerType === "touch" && event.timeStamp - press.timeStamp < 1000;
+    const first = touch ? undefined : tabStops(popup)[0];
+    if (first) first.focus();
+    else {
+      if (!popup.hasAttribute("tabindex")) popup.tabIndex = -1;
+      popup.focus({ preventScroll: true });
+    }
+    return;
+  }
+
+  placed.delete(popup);
+  const wasHovered = hovered.has(popup);
+  const held = holding.has(popup);
+  holding.delete(popup);
+  hover.forget(popup);
+  // A hover opened it and focus was elsewhere: closing it moves no focus.
+  if (wasHovered && !held) return;
+  const active = document.activeElement;
+  if (active && active !== document.body && !popup.contains(active)) return;
+  anchor(popup)?.focus({ preventScroll: true });
+  openers.delete(popup);
+});
+
+if (!anchoring) {
+  addEventListener("scroll", follow, { capture: true, passive: true });
+  addEventListener("resize", follow, { passive: true });
+}

package/dist/popover/popover.tsx

@@ -0,0 +1,317 @@
+// Popover (decision-62, TASK-356): a native `popover="auto"` opened and closed by its trigger's
+// `popovertarget`, so it works in server HTML with no JavaScript, placed next to the trigger with
+// CSS anchor positioning (placement.css). The popup is a non-modal dialog (`role="dialog"`), as in
+// Base UI and Zag. The popup element is the only state: the trigger, a close button, Escape, a
+// click outside and the `open` prop all end in its `toggle` event, the single source of
+// `onOpenChange`. Ported from Timeless's approach (https://timeless.build).
+//
+// TASK-394: a trigger may open the popover on hover (`openOnHover`, after `delay`, closing
+// `closeDelay` after the pointer leaves both), which popover.script.ts runs. A `modal` popover is a
+// modal `<dialog>` instead, opened by the trigger's `command="show-modal"`: the page behind it is
+// inert and does not scroll, focus stays inside, and a press outside or Escape closes it.
+import {
+  createContext,
+  effect,
+  isServer,
+  onCleanup,
+  ref,
+  signal,
+  untrack,
+  useContext,
+  useId,
+  type Signal,
+} from "lumiose";
+import dialogScript from "../dialog/dialog.script.ts?client";
+import { anchorName, placement, withStyle, type PlacementProps } from "../placement/placement.ts";
+import popoverScript from "./popover.script.ts?client";
+import { OUTSIDE_TOOLBAR, ToolbarContext } from "../toolbar/context.ts";
+
+/**
+ * `Popover.Root` renders no element: it holds the ids its parts share. `bind:open={signal}`
+ * stands in for `open` and `onOpenChange`.
+ */
+export interface PopoverRootProps {
+  /**
+   * Opens (`true`) or closes (`false`) the popover when it changes, in the browser. Pair it with
+   * `onOpenChange` to keep a signal in sync; leave both out and the popover keeps its own state.
+   * Server HTML always starts closed: a popover only opens from script or its trigger.
+   */
+  open?: boolean;
+  /** Called after the popover opens or closes, whatever opened or closed it. */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * A modal popover: the rest of the page is inert and does not scroll, focus stays in the popup,
+   * and a press outside or Escape closes it. The popup is then a modal `<dialog>`. With
+   * `"trap-focus"`, only Tab and Shift+Tab stay in the popup: the page still scrolls and takes
+   * presses (one outside closes it).
+   */
+  modal?: boolean | "trap-focus";
+  /** The other parts: a `Popover.Trigger` and the `Popover.Popup`, anywhere inside. */
+  children?: JSX.Element;
+}
+
+/**
+ * A `<button>` that opens and closes the popover (`popovertarget`, or `command="show-modal"` when
+ * modal), and its anchor.
+ */
+export type PopoverTriggerProps = JSX.IntrinsicElements["button"] & {
+  /**
+   * Hovering the trigger with a mouse or a pen opens the popover too, and it closes once the
+   * pointer has left the trigger and the popup. A click keeps it open; touch and the keyboard
+   * open it with a click, as without. Not for a modal popover.
+   */
+  openOnHover?: boolean;
+  /** With `openOnHover`: how long the pointer rests on the trigger before it opens, in ms. Default `300`. */
+  delay?: number;
+  /** With `openOnHover`: how long it stays open after the pointer leaves, in ms. Default `0`. */
+  closeDelay?: number;
+};
+/** The popup: a `<div popover role="dialog">` (a modal `<dialog>`), placed next to the trigger. */
+export type PopoverPopupProps = JSX.IntrinsicElements["div"] & PlacementProps;
+/** The `<h2>` that names the popover. */
+export type PopoverTitleProps = JSX.IntrinsicElements["h2"];
+/** The `<p>` that describes the popover. */
+export type PopoverDescriptionProps = JSX.IntrinsicElements["p"];
+/** A `<button>` that closes the popover (`popovertargetaction="hide"`, or `command="close"`). */
+export type PopoverCloseProps = JSX.IntrinsicElements["button"];
+
+interface PopoverContextValue {
+  id: string;
+  modal: boolean;
+  trapFocus: boolean;
+  trigger: JSX.Ref<HTMLButtonElement>;
+  popup: JSX.Ref<HTMLElement>;
+  onToggle: (open: boolean) => void;
+  popupId: string;
+  titleId: string;
+  descriptionId: string;
+  /** How many Title and Description parts are rendered: the popup references only those. */
+  titles: Signal<number>;
+  descriptions: Signal<number>;
+}
+
+const PopoverContext = createContext<PopoverContextValue>();
+
+function usePopover(): PopoverContextValue {
+  const context = useContext(PopoverContext);
+  if (!context) throw new Error("Popover parts must be inside <Popover.Root>.");
+  return context;
+}
+
+function Root(props: PopoverRootProps) {
+  // Focus on open and its return, `aria-expanded`, and placement without anchor positioning; the
+  // page loads it once (decision-63).
+  popoverScript();
+  const modal = untrack(() => props.modal === true);
+  // A modal popover is a modal <dialog>: Dialog's script closes its gaps (invoker commands where
+  // missing, light dismiss, focus return, scroll lock).
+  if (modal) dialogScript();
+  const id = useId();
+  const trigger = ref<HTMLButtonElement>();
+  const popup = ref<HTMLElement>();
+  const context: PopoverContextValue = {
+    id,
+    modal,
+    trapFocus: untrack(() => props.modal === "trap-focus"),
+    trigger,
+    popup,
+    onToggle: (next) => props.onOpenChange?.(next),
+    popupId: `${id}-popup`,
+    titleId: `${id}-title`,
+    descriptionId: `${id}-description`,
+    titles: signal(0),
+    descriptions: signal(0),
+  };
+
+  // The `open` prop drives the native state; the popup's `toggle` event reports back, so a signal
+  // written by `onOpenChange` sees the same value again and nothing loops.
+  effect(() => {
+    const element = popup();
+    const wanted = props.open;
+    if (!element?.isConnected || wanted === undefined) return;
+    if (element instanceof HTMLDialogElement) {
+      if (wanted && !element.open) element.showModal();
+      else if (!wanted && element.open) element.close();
+      return;
+    }
+    const shown = element.matches(":popover-open");
+    // A manual popover, as the client script makes it on a trigger's click: the script's shared
+    // dismissal closes it. `source` makes the trigger the popover's invoker, as a click on it
+    // does: focus order and nesting follow it.
+    if (wanted && !shown) {
+      element.popover = "manual";
+      (element.showPopover as (options?: { source?: HTMLElement }) => void)({
+        source: trigger(),
+      });
+    } else if (!wanted && shown) element.hidePopover();
+  });
+
+  return <PopoverContext value={context}>{props.children}</PopoverContext>;
+}
+
+// Each part spreads the caller's props first, so they override the defaults (`type`, the label
+// references), and sets the wiring last, so `id` and `popovertarget` stay consistent.
+
+function Trigger({
+  children,
+  ref: forwarded,
+  openOnHover,
+  delay,
+  closeDelay,
+  ...rest
+}: PopoverTriggerProps) {
+  const popover = usePopover();
+  // A disabled Toolbar disables it: focusable, it opens nothing (TASK-437 M13).
+  const toolbar = useContext(ToolbarContext);
+  const off = untrack(() => toolbar?.disabled() === true);
+  // A modal popover opens with an invoker command; the others with `popovertarget`.
+  const opens = off
+    ? { "aria-disabled": "true" as const }
+    : popover.modal
+      ? { command: "show-modal", commandfor: popover.popupId, "aria-expanded": "false" as const }
+      : { popovertarget: popover.popupId };
+  // A function, so hover opening and its delays follow the props: the script reads them from
+  // the trigger at each hover (TASK-477).
+  const hover = () =>
+    openOnHover && !popover.modal && !off
+      ? { "data-open-on-hover": "", "data-delay": delay, "data-close-delay": closeDelay }
+      : {};
+  return (
+    <button
+      type="button"
+      aria-haspopup="dialog"
+      {...rest}
+      {...hover()}
+      ref={(element: HTMLButtonElement) => {
+        popover.trigger(element);
+        forwarded?.(element);
+      }}
+      style={withStyle(rest.style, { "anchor-name": anchorName(popover.id) })}
+      {...opens}
+    >
+      {children}
+    </button>
+  );
+}
+
+function Popup({
+  children,
+  ref: forwarded,
+  side,
+  align,
+  sideOffset,
+  alignOffset,
+  ...rest
+}: PopoverPopupProps) {
+  const popover = usePopover();
+  // The server writes the attributes before it renders the children, so it renders them first to
+  // know which Title and Description exist (as Dialog.Popup does), once.
+  // Its content is not a surrounding toolbar's (TASK-413).
+  const inside = () => <ToolbarContext value={OUTSIDE_TOOLBAR}>{children}</ToolbarContext>;
+  const content = isServer ? untrack(inside) : undefined;
+  const attach = (element: HTMLElement) => {
+    popover.popup(element);
+    forwarded?.(element as HTMLDivElement);
+  };
+  const toggle = (event: ToggleEvent) => popover.onToggle(event.newState === "open");
+  // Modal: a <dialog> that a press outside closes (`closedby="any"`), as Base UI's does.
+  return popover.modal ? (
+    <dialog
+      aria-labelledby={popover.titles() > 0 ? popover.titleId : undefined}
+      aria-describedby={popover.descriptions() > 0 ? popover.descriptionId : undefined}
+      {...(rest as JSX.IntrinsicElements["dialog"])}
+      {...placement(
+        { side, align, sideOffset, alignOffset, style: rest.style },
+        popover.id,
+        "bottom",
+      )}
+      ref={attach}
+      id={popover.popupId}
+      closedby="any"
+      on:toggle={toggle}
+    >
+      {isServer ? content : inside()}
+    </dialog>
+  ) : (
+    <div
+      role="dialog"
+      aria-labelledby={popover.titles() > 0 ? popover.titleId : undefined}
+      aria-describedby={popover.descriptions() > 0 ? popover.descriptionId : undefined}
+      {...rest}
+      {...placement(
+        { side, align, sideOffset, alignOffset, style: rest.style },
+        popover.id,
+        "bottom",
+      )}
+      ref={attach}
+      id={popover.popupId}
+      popover="auto"
+      data-trap-focus={popover.trapFocus ? "" : undefined}
+      on:toggle={toggle}
+    >
+      {isServer ? content : inside()}
+    </div>
+  );
+}
+
+/** Counts a rendered part in `count` while it is mounted. */
+function register(count: Signal<number>) {
+  count.update((n) => n + 1);
+  onCleanup(() => count.update((n) => n - 1));
+}
+
+function Title({ children, ...rest }: PopoverTitleProps) {
+  const popover = usePopover();
+  // A caller's `id` names it: the Popup renders its parts before its own attributes on the server,
+  // and follows them in the browser (TASK-441 M39).
+  if (rest.id) popover.titleId = rest.id;
+  register(popover.titles);
+  return (
+    <h2 {...rest} id={popover.titleId}>
+      {children}
+    </h2>
+  );
+}
+
+function Description({ children, ...rest }: PopoverDescriptionProps) {
+  const popover = usePopover();
+  // As Title's.
+  if (rest.id) popover.descriptionId = rest.id;
+  register(popover.descriptions);
+  return (
+    <p {...rest} id={popover.descriptionId}>
+      {children}
+    </p>
+  );
+}
+
+function Close({ children, ...rest }: PopoverCloseProps) {
+  const popover = usePopover();
+  const closes = popover.modal
+    ? { command: "close", commandfor: popover.popupId }
+    : { popovertarget: popover.popupId, popovertargetaction: "hide" as const };
+  return (
+    <button type="button" {...rest} {...closes}>
+      {children}
+    </button>
+  );
+}
+
+/**
+ * A popup anchored to its trigger: a non-modal dialog that a click outside, Escape or a close
+ * button dismisses; or opened on hover (`openOnHover`); or modal (`modal`). No JavaScript needed
+ * to open and close it: the native popover and `popovertarget` (a modal `<dialog>` and invoker
+ * commands) do the work, in server HTML too. Unstyled: style the parts through `class` and native
+ * state (`:popover-open`, `[open]`, `[aria-expanded]`, `[data-side]`).
+ *
+ * @example
+ * <Popover.Root>
+ *   <Popover.Trigger>Notifications</Popover.Trigger>
+ *   <Popover.Popup side="bottom" align="start" sideOffset={8}>
+ *     <Popover.Title>Notifications</Popover.Title>
+ *     <Popover.Description>You are all caught up.</Popover.Description>
+ *     <Popover.Close>Close</Popover.Close>
+ *   </Popover.Popup>
+ * </Popover.Root>
+ */
+export const Popover = { Root, Trigger, Popup, Title, Description, Close };

package/dist/preview-card/preview-card.css

@@ -0,0 +1,7 @@
+/*
+ * Preview Card needs no CSS to open or close: the native popover does it. What it needs is its
+ * placement next to the link, shared with Popover and Tooltip (placement.css).
+ */
+@layer lu.core, lu.theme;
+
+@import "../placement/placement.css";