@lumiose/ui 0.0.0-stage → 0.1.0

package/dist/dialog/dialog.tsx

@@ -0,0 +1,214 @@
+// Dialog and alert dialog (decision-62, TASK-355): a native modal <dialog> opened and closed by
+// invoker commands, so it works in server HTML with no JavaScript. The dialog element is the only
+// state: the trigger, a close button, Escape, a click on the backdrop and the `open` prop all end
+// in its `toggle` event, the single source of `onOpenChange`. Ported from Timeless's approach
+// (https://timeless.build); the keyboard contract is the platform's (APG Dialog pattern).
+import {
+  createContext,
+  effect,
+  isServer,
+  onCleanup,
+  ref,
+  signal,
+  untrack,
+  useContext,
+  useId,
+  type Signal,
+} from "lumiose";
+import dialogScript from "./dialog.script.ts?client";
+
+/**
+ * `Dialog.Root` renders no element: it holds the dialog's state and the ids its parts share.
+ * `bind:open={signal}` stands in for `open` and `onOpenChange`.
+ */
+export interface DialogRootProps {
+  /**
+   * Opens (`true`) or closes (`false`) the dialog when it changes, in the browser. Pair it with
+   * `onOpenChange` to keep a signal in sync; leave both out and the dialog keeps its own state.
+   * Server HTML always starts closed: a modal dialog only opens from script or a trigger.
+   */
+  open?: boolean;
+  /** Called after the dialog opens or closes, whatever opened or closed it. */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * `"alertdialog"` for a confirmation that needs an answer: a click outside does not close it
+   * (Escape still does). Default `"dialog"`.
+   */
+  role?: "dialog" | "alertdialog";
+  /** The other parts: a `Dialog.Trigger` and the `Dialog.Popup`, anywhere inside. */
+  children?: JSX.Element;
+}
+
+/** A `<button>` that opens the dialog (`command="show-modal"`). */
+export type DialogTriggerProps = JSX.IntrinsicElements["button"];
+/** The `<dialog>`. `closedby` defaults to `"any"`, or `"closerequest"` for an alert dialog. */
+export type DialogPopupProps = JSX.IntrinsicElements["dialog"];
+/** The `<h2>` that names the dialog. */
+export type DialogTitleProps = JSX.IntrinsicElements["h2"];
+/** The `<p>` that describes the dialog. */
+export type DialogDescriptionProps = JSX.IntrinsicElements["p"];
+/** A `<button>` that closes the dialog (`command="close"`); its `value` becomes `returnValue`. */
+export type DialogCloseProps = JSX.IntrinsicElements["button"];
+
+interface DialogContextValue {
+  popup: JSX.Ref<HTMLDialogElement>;
+  role: () => "dialog" | "alertdialog";
+  /** Whether the dialog is open, as its last `toggle` event said. */
+  open: Signal<boolean>;
+  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 DialogContext = createContext<DialogContextValue>();
+
+function useDialog(): DialogContextValue {
+  const context = useContext(DialogContext);
+  if (!context) throw new Error("Dialog parts must be inside <Dialog.Root>.");
+  return context;
+}
+
+function Root(props: DialogRootProps) {
+  // Closes the native dialog's gaps where JavaScript runs; the page loads it once (decision-63).
+  dialogScript();
+  const popup = ref<HTMLDialogElement>();
+  const id = useId();
+  const open = signal(false);
+  const context: DialogContextValue = {
+    popup,
+    role: () => props.role ?? "dialog",
+    open,
+    onToggle: (next) => {
+      open.set(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 dialog's `toggle` event reports back, so a
+  // signal written by `onOpenChange` sees the same value again and nothing loops.
+  effect(() => {
+    const dialog = popup();
+    const wanted = props.open;
+    if (!dialog?.isConnected || wanted === undefined) return;
+    if (wanted && !dialog.open) dialog.showModal();
+    else if (!wanted && dialog.open) dialog.close();
+  });
+
+  return <DialogContext value={context}>{props.children}</DialogContext>;
+}
+
+// Each part spreads the caller's props first, so they override the defaults (`type`, `closedby`,
+// the label references), and sets the wiring last, so `id`, `command` and `commandfor` stay
+// consistent between the parts.
+
+function Trigger({ children, ...rest }: DialogTriggerProps) {
+  const dialog = useDialog();
+  // While the modal dialog is open the trigger is inert, so the server's "false" is never wrong
+  // where assistive technology can reach it; in the browser it follows the dialog.
+  return (
+    <button
+      type="button"
+      aria-haspopup="dialog"
+      aria-expanded={dialog.open()}
+      {...rest}
+      command="show-modal"
+      commandfor={dialog.popupId}
+    >
+      {children}
+    </button>
+  );
+}
+
+function Popup({ children, ref: forwarded, ...rest }: DialogPopupProps) {
+  const dialog = useDialog();
+  const alert = () => dialog.role() === "alertdialog";
+  // The server writes the attributes before it renders the children, so it renders them first to
+  // know which Title and Description exist. The browser claims the dialog before its children
+  // (hydration needs that order) and updates the references when the parts register. The server
+  // renders once, so reading them once is the intent: `untrack` says so (no LUM2001).
+  const content = isServer ? untrack(() => children) : undefined;
+  return (
+    <dialog
+      role={alert() ? "alertdialog" : undefined}
+      closedby={alert() ? "closerequest" : "any"}
+      aria-labelledby={dialog.titles() > 0 ? dialog.titleId : undefined}
+      aria-describedby={dialog.descriptions() > 0 ? dialog.descriptionId : undefined}
+      {...rest}
+      ref={(element: HTMLDialogElement) => {
+        dialog.popup(element);
+        forwarded?.(element);
+      }}
+      id={dialog.popupId}
+      on:toggle={(event: ToggleEvent) => dialog.onToggle(event.newState === "open")}
+    >
+      {isServer ? content : children}
+    </dialog>
+  );
+}
+
+/** 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 }: DialogTitleProps) {
+  const dialog = useDialog();
+  // 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) dialog.titleId = rest.id;
+  register(dialog.titles);
+  return (
+    <h2 {...rest} id={dialog.titleId}>
+      {children}
+    </h2>
+  );
+}
+
+function Description({ children, ...rest }: DialogDescriptionProps) {
+  const dialog = useDialog();
+  // As Title's.
+  if (rest.id) dialog.descriptionId = rest.id;
+  register(dialog.descriptions);
+  return (
+    <p {...rest} id={dialog.descriptionId}>
+      {children}
+    </p>
+  );
+}
+
+function Close({ children, ...rest }: DialogCloseProps) {
+  const dialog = useDialog();
+  return (
+    <button type="button" {...rest} command="close" commandfor={dialog.popupId}>
+      {children}
+    </button>
+  );
+}
+
+/**
+ * A modal dialog, or an alert dialog with `role="alertdialog"` on `Root`. No JavaScript: the
+ * native `<dialog>` and invoker commands do the work, in server HTML too. Unstyled: style the
+ * parts through `class` and native state (`dialog[open]`, `::backdrop`).
+ *
+ * @example
+ * <Dialog.Root role="alertdialog">
+ *   <Dialog.Trigger>Delete project…</Dialog.Trigger>
+ *   <Dialog.Popup>
+ *     <Dialog.Title>Delete project?</Dialog.Title>
+ *     <Dialog.Description>This removes the project and its deployments.</Dialog.Description>
+ *     <Dialog.Close value="cancel">Cancel</Dialog.Close>
+ *     <Dialog.Close value="delete">Delete</Dialog.Close>
+ *   </Dialog.Popup>
+ * </Dialog.Root>
+ */
+export const Dialog = { Root, Trigger, Popup, Title, Description, Close };

package/dist/drawer/drawer.css

@@ -0,0 +1,38 @@
+/*
+ * A drawer is a modal <dialog> against the edge of the window its `data-swipe-direction` names,
+ * across that edge's length, instead of the browser's centred box; Dialog's rule keeps the page
+ * behind it from scrolling. While it is swiped it takes the pointer's moves rather than selecting
+ * text.
+ */
+@layer lu.core, lu.theme;
+@import "../dialog/dialog.css";
+
+@layer lu.core {
+  dialog[data-swipe-direction] {
+    margin: 0;
+    max-inline-size: none;
+    max-block-size: none;
+  }
+  /* The browser's `fit-content` would leave it short of the edge's length. */
+  dialog:is([data-swipe-direction="down"], [data-swipe-direction="up"]) {
+    inline-size: auto;
+  }
+  dialog:is([data-swipe-direction="left"], [data-swipe-direction="right"]) {
+    block-size: auto;
+  }
+  dialog[data-swipe-direction="down"] {
+    inset: auto 0 0;
+  }
+  dialog[data-swipe-direction="up"] {
+    inset: 0 0 auto;
+  }
+  dialog[data-swipe-direction="left"] {
+    inset: 0 auto 0 0;
+  }
+  dialog[data-swipe-direction="right"] {
+    inset: 0 0 0 auto;
+  }
+  dialog[data-swipe-direction][data-swiping] {
+    user-select: none;
+  }
+}

package/dist/drawer/drawer.script.ts

@@ -0,0 +1,207 @@
+// Drawer's client script (decision-62, decision-63). A drawer is a Dialog: a native modal
+// `<dialog>` with `data-swipe-direction`, which drawer.css puts against that edge of the window,
+// so it opens and closes, traps focus and makes the page inert in server HTML with no JavaScript,
+// and Dialog's script closes the native element's gaps. This module, which runs once on a page
+// that renders a Drawer, adds swiping it away in that direction, as Base UI's Drawer does:
+//
+// - A drag in the dismiss direction moves the drawer: `data-swiping` and
+//   `--lu-drawer-swipe-movement-x` or `-y` (pixels) while it runs, `--lu-drawer-swipe-progress` (0 to 1)
+//   for the backdrop. Against that direction it moves a little, as a hint.
+// - Released past 40% of its size, or flicked (faster than 0.5px/ms over 20px), it closes, with
+//   `data-swipe-dismiss` so a stylesheet can let it leave from where it is. Otherwise it springs
+//   back.
+// - A drag never starts on a control (a button, link or field) or inside `[data-swipe-ignore]`,
+//   and not where the content under it can still scroll that way: the content scrolls instead.
+//   It starts only inside the drawer's box, not on its backdrop (TASK-436 M5), and a mouse or pen
+//   never starts one in `Drawer.Content` (`[data-drawer-content]`), where it selects text (M6).
+//   On a touch screen it takes the gesture (`touchmove`'s `preventDefault`) only once it is a swipe.
+// - The close buttons, Escape and a click on the backdrop close it without a gesture (WCAG 2.5.7).
+//
+// It must not import `lumiose`: server-rendered pages load it without the runtime.
+import { afterAnimations } from "../animation/animation.ts";
+
+const CONTROLS = "button, a[href], input, select, textarea, [contenteditable], [data-swipe-ignore]";
+/** Pixels a drag moves before it counts, and the share of the drawer's size that dismisses it. */
+const SLOP = 6;
+const DISMISS = 0.4;
+const FLICK = 0.5;
+
+type Direction = "up" | "down" | "left" | "right";
+
+interface Drag {
+  dialog: HTMLDialogElement;
+  direction: Direction;
+  x: number;
+  y: number;
+  /** Whether the drag became a swipe (it moved in the dismiss direction). */
+  swiping: boolean;
+  /** The last move's time and movement, for the flick. */
+  at: number;
+  movement: number;
+  velocity: number;
+}
+
+let drag: Drag | undefined;
+
+const axis = (direction: Direction) => (direction === "up" || direction === "down" ? "y" : "x");
+const sign = (direction: Direction) => (direction === "down" || direction === "right" ? 1 : -1);
+
+/** Whether an element between `target` and the dialog can scroll toward `direction`'s opposite. */
+function scrolls(target: Element, dialog: HTMLDialogElement, direction: Direction): boolean {
+  for (
+    let node: Element | null = target;
+    node && node !== dialog.parentElement;
+    node = node.parentElement
+  ) {
+    const vertical = axis(direction) === "y";
+    const size = vertical
+      ? node.scrollHeight - node.clientHeight
+      : node.scrollWidth - node.clientWidth;
+    if (size <= 1) continue;
+    const overflow = getComputedStyle(node)[vertical ? "overflowY" : "overflowX"];
+    if (!/auto|scroll/.test(overflow)) continue;
+    const position = vertical ? node.scrollTop : node.scrollLeft;
+    // Swiping down dismisses only once the content is scrolled to its top, and so on.
+    if (sign(direction) > 0 ? position > 0 : position < size - 1) return true;
+  }
+  return false;
+}
+
+function start(target: EventTarget | null, x: number, y: number, mouse: boolean): boolean {
+  if (!(target instanceof Element)) return false;
+  const dialog = target.closest<HTMLDialogElement>("dialog[data-swipe-direction]");
+  if (!dialog?.open || target.closest(CONTROLS)) return false;
+  // A press on the backdrop targets the dialog too: only presses in its box count.
+  const box = dialog.getBoundingClientRect();
+  if (x < box.left || x > box.right || y < box.top || y > box.bottom) return false;
+  if (mouse && target.closest("[data-drawer-content]")) return false;
+  const direction = dialog.dataset["swipeDirection"] as Direction;
+  if (scrolls(target, dialog, direction)) return false;
+  drag = {
+    dialog,
+    direction,
+    x,
+    y,
+    swiping: false,
+    at: performance.now(),
+    movement: 0,
+    velocity: 0,
+  };
+  return true;
+}
+
+/** Follows the pointer; returns whether the drag is a swipe (so a touch is not a scroll). */
+function move(x: number, y: number): boolean {
+  if (!drag) return false;
+  const { dialog, direction } = drag;
+  const delta = axis(direction) === "y" ? y - drag.y : x - drag.x;
+  const toward = delta * sign(direction);
+  if (!drag.swiping) {
+    if (Math.abs(delta) < SLOP) return false;
+    // A first move the other way, or along the other axis, is not a swipe.
+    const across = axis(direction) === "y" ? Math.abs(x - drag.x) : Math.abs(y - drag.y);
+    if (toward <= 0 || across > Math.abs(delta)) {
+      drag = undefined;
+      return false;
+    }
+    drag.swiping = true;
+    dialog.setAttribute("data-swiping", "");
+  }
+  const now = performance.now();
+  const movement = toward > 0 ? toward : toward / 8;
+  drag.velocity = (movement - drag.movement) / Math.max(1, now - drag.at);
+  drag.at = now;
+  drag.movement = movement;
+  const size = axis(direction) === "y" ? dialog.offsetHeight : dialog.offsetWidth;
+  dialog.style.setProperty(
+    `--lu-drawer-swipe-movement-${axis(direction)}`,
+    `${movement * sign(direction)}px`,
+  );
+  dialog.style.setProperty(
+    "--lu-drawer-swipe-progress",
+    String(Math.min(1, Math.max(0, movement / size))),
+  );
+  return true;
+}
+
+function reset(dialog: HTMLDialogElement) {
+  for (const name of [
+    "--lu-drawer-swipe-movement-x",
+    "--lu-drawer-swipe-movement-y",
+    "--lu-drawer-swipe-progress",
+  ]) {
+    dialog.style.removeProperty(name);
+  }
+}
+
+function end(): void {
+  const current = drag;
+  drag = undefined;
+  if (!current?.swiping) return;
+  const { dialog, direction, movement, velocity } = current;
+  dialog.removeAttribute("data-swiping");
+  const size = axis(direction) === "y" ? dialog.offsetHeight : dialog.offsetWidth;
+  if (movement > size * DISMISS || (velocity > FLICK && movement > 20)) {
+    dialog.setAttribute("data-swipe-dismiss", direction);
+    dialog.close();
+    // Once it has left: a reopened drawer starts from its edge.
+    void afterAnimations(dialog).then(() => {
+      if (dialog.open) return;
+      dialog.removeAttribute("data-swipe-dismiss");
+      reset(dialog);
+    });
+  } else reset(dialog);
+}
+
+function on<K extends keyof DocumentEventMap>(
+  type: K,
+  listener: (event: DocumentEventMap[K]) => void,
+  options: AddEventListenerOptions = {},
+) {
+  document.addEventListener(type, listener, { capture: true, ...options });
+}
+
+// Mouse and pen: pointer events. Touch: touch events, so the swipe can take the gesture from
+// scrolling only once it is one.
+on("pointerdown", (event) => {
+  if (event.pointerType !== "touch" && event.button === 0 && event.isPrimary) {
+    start(event.target, event.clientX, event.clientY, true);
+  }
+});
+on("pointermove", (event) => {
+  if (event.pointerType !== "touch" && move(event.clientX, event.clientY)) event.preventDefault();
+});
+on("pointerup", (event) => {
+  if (event.pointerType !== "touch") end();
+});
+on("pointercancel", (event) => {
+  if (event.pointerType !== "touch" && drag) {
+    reset(drag.dialog);
+    drag.dialog.removeAttribute("data-swiping");
+    drag = undefined;
+  }
+});
+on("touchstart", (event) => {
+  const touch = event.touches[0];
+  if (event.touches.length === 1 && touch) {
+    start(event.target, touch.clientX, touch.clientY, false);
+  } else if (drag) end();
+});
+on(
+  "touchmove",
+  (event) => {
+    const touch = event.touches[0];
+    if (touch && move(touch.clientX, touch.clientY)) event.preventDefault();
+  },
+  { passive: false },
+);
+on("touchend", () => end());
+on("touchcancel", () => end());
+// A drawer that opens again starts from its edge.
+on("toggle", (event) => {
+  const dialog = event.target;
+  if (dialog instanceof HTMLDialogElement && dialog.open && dialog.dataset["swipeDirection"]) {
+    dialog.removeAttribute("data-swipe-dismiss");
+    reset(dialog);
+  }
+});

package/dist/drawer/drawer.tsx

@@ -0,0 +1,113 @@
+// Drawer (decision-62, TASK-382): a Dialog against an edge of the window that a swipe toward that
+// edge closes, after Base UI's Drawer. Its parts are Dialog's (a native modal `<dialog>` opened by
+// an invoker command, so it works in server HTML with no JavaScript); Popup adds
+// `data-swipe-direction`, which drawer.css turns into the edge it sits on, and the client script
+// (./drawer.script.ts) the swipe. Ported from Timeless's approach (https://timeless.build).
+import { createContext, useContext } from "lumiose";
+import {
+  Dialog,
+  type DialogCloseProps,
+  type DialogDescriptionProps,
+  type DialogPopupProps,
+  type DialogTitleProps,
+  type DialogTriggerProps,
+} from "../dialog/dialog.tsx";
+import drawerScript from "./drawer.script.ts?client";
+
+/** The direction a swipe closes the drawer in, and the edge of the window it sits against. */
+export type DrawerSwipeDirection = "up" | "down" | "left" | "right";
+
+/**
+ * `Drawer.Root` renders no element: it holds the state the other parts share, as `Dialog.Root`.
+ * `bind:open={signal}` stands in for `open` and `onOpenChange`.
+ */
+export interface DrawerRootProps {
+  /**
+   * Opens (`true`) or closes (`false`) the drawer when it changes, in the browser. Pair it with
+   * `onOpenChange` to keep a signal in sync; leave both out and the drawer keeps its own state.
+   * Server HTML always starts closed: a modal dialog only opens from script or a trigger.
+   */
+  open?: boolean;
+  /** Called after the drawer opens or closes, whatever did it: a swipe included. */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * The direction a swipe closes the drawer in, which is also the window's edge it sits against.
+   * Default `"down"`: a bottom sheet.
+   */
+  swipeDirection?: DrawerSwipeDirection;
+  /** The other parts: a `Drawer.Trigger` and the `Drawer.Popup`, anywhere inside. */
+  children?: JSX.Element;
+}
+
+/** The `<button>` that opens the drawer, as `Dialog.Trigger`. */
+export type DrawerTriggerProps = DialogTriggerProps;
+/** The drawer: a `<dialog>` with `data-swipe-direction`, against that edge of the window. */
+export type DrawerPopupProps = DialogPopupProps;
+/** A `<div>` around the drawer's content, which may scroll: a swipe inside it waits for its top. */
+export type DrawerContentProps = JSX.IntrinsicElements["div"];
+/** The `<h2>` that names the drawer. */
+export type DrawerTitleProps = DialogTitleProps;
+/** The `<p>` that describes the drawer. */
+export type DrawerDescriptionProps = DialogDescriptionProps;
+/** A `<button>` that closes the drawer: the alternative to the swipe. */
+export type DrawerCloseProps = DialogCloseProps;
+
+const DrawerContext = createContext<{ direction: () => DrawerSwipeDirection }>();
+
+function Root(props: DrawerRootProps) {
+  // The swipe; the page loads it once (decision-63). Dialog.Root loads Dialog's script.
+  drawerScript();
+  return (
+    <DrawerContext value={{ direction: () => props.swipeDirection ?? "down" }}>
+      <Dialog.Root open={props.open} onOpenChange={props.onOpenChange}>
+        {props.children}
+      </Dialog.Root>
+    </DrawerContext>
+  );
+}
+
+function Popup({ children, ...rest }: DrawerPopupProps) {
+  const drawer = useContext(DrawerContext);
+  if (!drawer) throw new Error("Drawer parts must be inside <Drawer.Root>.");
+  return (
+    <Dialog.Popup {...rest} data-swipe-direction={drawer.direction()}>
+      {children}
+    </Dialog.Popup>
+  );
+}
+
+function Content({ children, ...rest }: DrawerContentProps) {
+  // A mouse or pen drag here selects text: it never swipes the drawer (drawer.script.ts).
+  return (
+    <div {...rest} data-drawer-content="">
+      {children}
+    </div>
+  );
+}
+
+/**
+ * A panel that slides in from an edge of the window: a modal dialog, so it opens from its trigger
+ * in server HTML with no JavaScript, and a swipe toward its edge closes it, as do its close
+ * buttons, Escape and a click on the backdrop. Unstyled: style it through `class`,
+ * `[data-swipe-direction]`, `[open]`, `[data-swiping]`, `[data-swipe-dismiss]` and the
+ * `--lu-drawer-swipe-movement-x`/`-y` and `--lu-drawer-swipe-progress` variables.
+ *
+ * @example
+ * <Drawer.Root>
+ *   <Drawer.Trigger>Filters</Drawer.Trigger>
+ *   <Drawer.Popup>
+ *     <Drawer.Title>Filters</Drawer.Title>
+ *     <Drawer.Content>…</Drawer.Content>
+ *     <Drawer.Close>Done</Drawer.Close>
+ *   </Drawer.Popup>
+ * </Drawer.Root>
+ */
+export const Drawer = {
+  Root,
+  Trigger: Dialog.Trigger,
+  Popup,
+  Content,
+  Title: Dialog.Title,
+  Description: Dialog.Description,
+  Close: Dialog.Close,
+};