@db-vincent/components 0.0.0-stage → 0.1.1

package/src/scripts/toast.ts

@@ -0,0 +1,565 @@
+import "../styles/toast.css";
+import { ICONS } from "../data/icons";
+
+/**
+ * Toast runtime. A small, dependency-free API shaped like shadcn/ui's toast
+ * manager:
+ *
+ *   import { toast } from "@db-vincent/components/scripts/toast";
+ *
+ *   toast.add({ title: "Event created", description: "Sunday at 9:00 AM" });
+ *   const id = toast.add({ title: "Saved", type: "success" });
+ *   toast.close(id);
+ *   toast.promise(task, { loading: "Saving…", success: "Saved." });
+ *
+ * The shared region is created lazily so the module can be imported anywhere.
+ */
+
+export type ToastType =
+  "info" | "success" | "warning" | "error" | "danger" | "loading";
+
+export interface ToastContent {
+  title: string;
+  description?: string;
+}
+
+export interface ToastActionProps {
+  /** Visible action label. `children` mirrors the React API. */
+  label?: string;
+  children?: string;
+  href?: string;
+  onClick?: (event: MouseEvent, toastId: string) => void;
+}
+
+export interface ToastOptions {
+  id?: string;
+  title?: string;
+  description?: string;
+  /** Alias for `description`, kept for the existing Astro component API. */
+  message?: string;
+  type?: ToastType;
+  /** Alias for `type`, kept for the existing Astro component API. */
+  tone?: ToastType;
+  /** Milliseconds before auto-dismiss. `0` or `Infinity` keeps it open. */
+  duration?: number;
+  dismissible?: boolean;
+  icon?: boolean;
+  action?: ToastActionProps;
+  /** Alias for `action`, mirrors shadcn/ui's prop name. */
+  actionProps?: ToastActionProps;
+}
+
+export interface ToastPromiseOptions<T> {
+  loading: string | ToastContent;
+  success: string | ToastContent | ((value: T) => string | ToastContent);
+  error: string | ToastContent | ((error: unknown) => string | ToastContent);
+  /** Duration for the resolved success/error toast. */
+  duration?: number;
+}
+
+type ResolvedType = "info" | "success" | "warning" | "danger" | "loading";
+
+const DEFAULT_DURATION = 5000;
+const ERROR_DURATION = 8000;
+const MAX_VISIBLE = 3;
+const EXIT_DELAY = 180;
+
+const ICON_BY_TYPE: Record<ResolvedType, string> = {
+  info: "info",
+  success: "check-circle",
+  warning: "alert-triangle",
+  danger: "alert-circle",
+  loading: "loader",
+};
+
+const ASSERTIVE: ReadonlySet<ResolvedType> = new Set(["warning", "danger"]);
+
+interface ToastRecord {
+  element: HTMLElement;
+  id: string;
+  duration: number;
+  remaining: number;
+  startedAt: number;
+  timer: number | null;
+  options: ToastOptions;
+}
+
+const records = new Map<string, ToastRecord>();
+const origins = new WeakMap<HTMLElement, HTMLElement>();
+const actionHandlers = new WeakMap<HTMLElement, (event: MouseEvent) => void>();
+const boundRegions = new WeakSet<HTMLElement>();
+
+let region: HTMLElement | null = null;
+let counter = 0;
+let resizeObserver: ResizeObserver | null = null;
+
+function nextId(): string {
+  do {
+    counter += 1;
+  } while (records.has(`toast-${counter}`));
+  return `toast-${counter}`;
+}
+
+const SAFE_PROTOCOLS: ReadonlySet<string> = new Set([
+  "http:",
+  "https:",
+  "mailto:",
+]);
+
+/** Relative and #fragment URLs resolve to the page protocol, so they pass. */
+function isSafeHref(href: string): boolean {
+  try {
+    return SAFE_PROTOCOLS.has(new URL(href, document.baseURI).protocol);
+  } catch {
+    return false;
+  }
+}
+
+function normalizeType(type?: ToastType): ResolvedType {
+  if (type === "error") return "danger";
+  return type ?? "info";
+}
+
+function iconMarkup(name: string): string {
+  const paths = ICONS[name] ?? ICONS.info;
+  return `<svg class="ds-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">${paths}</svg>`;
+}
+
+function ensureRegion(): HTMLElement {
+  if (region?.isConnected) return region;
+
+  const existing = document.querySelector<HTMLElement>("[data-toast-region]");
+  const element = existing ?? document.createElement("div");
+
+  if (!existing) {
+    element.className = "ds-toast-region";
+    element.setAttribute("data-toast-region", "");
+    element.setAttribute("role", "region");
+    element.setAttribute("aria-label", "Notifications");
+    element.setAttribute("aria-live", "polite");
+    element.setAttribute("aria-relevant", "additions text");
+    document.body.append(element);
+  }
+
+  if (!boundRegions.has(element)) {
+    boundRegions.add(element);
+    element.addEventListener("click", onRegionClick);
+    document.addEventListener("keydown", onKeydown);
+  }
+
+  region = element;
+  return element;
+}
+
+function onRegionClick(event: MouseEvent): void {
+  const target = event.target;
+  if (!(target instanceof Element)) return;
+
+  const close = target.closest("[data-toast-close]");
+  if (close) {
+    const element = close.closest<HTMLElement>("[data-toast]");
+    if (element) dismiss(element);
+    return;
+  }
+
+  const action = target.closest("[data-toast-action]");
+  if (action) {
+    const element = action.closest<HTMLElement>("[data-toast]");
+    if (element) actionHandlers.get(element)?.(event);
+  }
+}
+
+const OPEN_POPUP = 'dialog[open], [role="listbox"], [aria-expanded="true"]';
+
+function onKeydown(event: KeyboardEvent): void {
+  if (event.key !== "Escape" || event.defaultPrevented) return;
+  const target = event.target;
+  const inRegion = target instanceof Node && !!region?.contains(target);
+  // Escape belongs to an open dialog or popup unless focus is in the toasts.
+  if (!inRegion && target instanceof Element && target.closest(OPEN_POPUP)) {
+    return;
+  }
+  const toasts = region?.querySelectorAll<HTMLElement>("[data-toast]");
+  const latest = toasts?.[toasts.length - 1];
+  if (latest) dismiss(latest);
+}
+
+function createAction(
+  element: HTMLElement,
+  id: string,
+  action: ToastActionProps,
+): HTMLElement | null {
+  const label = action.label ?? action.children ?? "Action";
+  const href = action.href && isSafeHref(action.href) ? action.href : undefined;
+  // An action whose only target was an unsafe URL has nothing left to do.
+  if (action.href && !href && !action.onClick) return null;
+
+  const node = document.createElement(href ? "a" : "button");
+  node.className = "ds-toast__action";
+  node.setAttribute("data-toast-action", "");
+  node.textContent = label;
+
+  if (href) {
+    (node as HTMLAnchorElement).href = href;
+  } else {
+    (node as HTMLButtonElement).type = "button";
+  }
+
+  if (action.onClick) {
+    actionHandlers.set(element, (event) => action.onClick?.(event, id));
+  }
+
+  return node;
+}
+
+function render(element: HTMLElement, id: string, options: ToastOptions): void {
+  const type = normalizeType(options.type ?? options.tone);
+  const assertive = ASSERTIVE.has(type);
+
+  element.className = `ds-toast ds-toast--${type}`;
+  element.setAttribute("data-toast", "");
+  element.setAttribute("data-toast-id", id);
+  element.setAttribute("data-toast-type", type);
+  element.setAttribute("role", assertive ? "alert" : "status");
+  element.setAttribute("aria-live", assertive ? "assertive" : "polite");
+  element.setAttribute("aria-atomic", "true");
+
+  element.replaceChildren();
+  actionHandlers.delete(element);
+
+  if (options.icon !== false) {
+    const icon = document.createElement("span");
+    icon.className = "ds-toast__icon";
+    icon.setAttribute("aria-hidden", "true");
+    icon.innerHTML = iconMarkup(ICON_BY_TYPE[type]);
+    element.append(icon);
+  }
+
+  const content = document.createElement("div");
+  content.className = "ds-toast__content";
+
+  const title = document.createElement("p");
+  title.className = "ds-toast__title";
+  title.textContent = options.title ?? "";
+  content.append(title);
+
+  const description = options.description ?? options.message;
+  if (description) {
+    const body = document.createElement("p");
+    body.className = "ds-toast__body";
+    body.textContent = description;
+    content.append(body);
+  }
+
+  element.append(content);
+
+  const action = options.action ?? options.actionProps;
+  if (action) {
+    const node = createAction(element, id, action);
+    if (node) {
+      const actions = document.createElement("div");
+      actions.className = "ds-toast__actions";
+      actions.append(node);
+      element.append(actions);
+    }
+  }
+
+  if (options.dismissible !== false) {
+    const close = document.createElement("button");
+    close.className = "ds-toast__close";
+    close.type = "button";
+    close.setAttribute("aria-label", "Close toast");
+    close.setAttribute("data-toast-close", "");
+    close.innerHTML = iconMarkup("x");
+    element.append(close);
+  }
+}
+
+function clearTimer(record: ToastRecord): void {
+  if (record.timer !== null) {
+    window.clearTimeout(record.timer);
+    record.timer = null;
+  }
+}
+
+function schedule(record: ToastRecord): void {
+  clearTimer(record);
+  if (!Number.isFinite(record.duration) || record.duration <= 0) return;
+  if (record.remaining <= 0) {
+    dismiss(record.element);
+    return;
+  }
+  record.startedAt = performance.now();
+  record.timer = window.setTimeout(
+    () => dismiss(record.element),
+    record.remaining,
+  );
+}
+
+function pause(record: ToastRecord): void {
+  if (record.timer === null) return;
+  clearTimer(record);
+  record.remaining -= performance.now() - record.startedAt;
+}
+
+function resume(record: ToastRecord): void {
+  if (record.timer !== null) return;
+  schedule(record);
+}
+
+function wire(record: ToastRecord): void {
+  const { element } = record;
+
+  element.addEventListener("pointerenter", () => pause(record));
+  element.addEventListener("pointerleave", () => resume(record));
+  element.addEventListener("focusin", () => pause(record));
+  element.addEventListener("focusout", (event) => {
+    const next = event.relatedTarget;
+    if (!(next instanceof Node) || !element.contains(next)) resume(record);
+  });
+}
+
+/**
+ * Only the newest MAX_VISIBLE toasts are on screen. Older ones stay mounted
+ * (like shadcn/ui's `data-limited` toasts) instead of being thrown away: they
+ * are inert, hidden and their countdown is paused until a visible toast makes
+ * room, then they surface with the time they had left.
+ */
+function applyVisibility(): void {
+  if (!region) return;
+
+  const newestFirst = Array.from(
+    region.querySelectorAll<HTMLElement>(
+      "[data-toast]:not([data-toast-leaving])",
+    ),
+  ).reverse();
+
+  newestFirst.forEach((element, index) => {
+    const record = records.get(element.dataset.toastId ?? "");
+    const limited = index >= MAX_VISIBLE;
+
+    if (limited === element.hasAttribute("data-toast-limited")) return;
+
+    if (limited) {
+      element.setAttribute("data-toast-limited", "");
+      element.inert = true;
+      if (record) pause(record);
+    } else {
+      element.removeAttribute("data-toast-limited");
+      element.inert = false;
+      if (record) resume(record);
+    }
+  });
+
+  recalcStack();
+}
+
+/**
+ * Give every visible toast its stack depth and the pixel offset it needs when
+ * the region expands on hover/focus. Heights are measured, so descriptions
+ * that wrap to several lines still separate cleanly.
+ */
+function recalcStack(): void {
+  if (!region) return;
+
+  const visible = Array.from(
+    region.querySelectorAll<HTMLElement>(
+      "[data-toast]:not([data-toast-leaving]):not([data-toast-limited])",
+    ),
+  ).reverse();
+  const gap = Number.parseFloat(getComputedStyle(region).rowGap) || 0;
+  let offset = 0;
+
+  visible.forEach((toast, index) => {
+    toast.style.setProperty("--toast-index", String(index));
+    toast.style.setProperty("--toast-offset", `${offset}px`);
+    offset += toast.offsetHeight + gap;
+  });
+}
+
+function observeToast(element: HTMLElement): void {
+  if (typeof ResizeObserver === "undefined") return;
+  resizeObserver ??= new ResizeObserver(() => recalcStack());
+  resizeObserver.observe(element);
+}
+
+function forgetToast(element: HTMLElement): void {
+  resizeObserver?.unobserve(element);
+}
+
+export function add(options: ToastOptions): string {
+  const id = options.id ?? nextId();
+  const element = document.createElement("div");
+  element.id = id;
+  const duration = options.duration ?? DEFAULT_DURATION;
+
+  const record: ToastRecord = {
+    element,
+    id,
+    duration,
+    remaining: duration,
+    startedAt: 0,
+    timer: null,
+    options,
+  };
+
+  render(element, id, options);
+  records.set(id, record);
+  ensureRegion().append(element);
+
+  wire(record);
+  observeToast(element);
+  schedule(record);
+  applyVisibility();
+
+  return id;
+}
+
+export function update(id: string, options: ToastOptions): boolean {
+  const record = records.get(id);
+  if (!record) return false;
+
+  // Content fields are replaced, not merged: a promise transition from
+  // "Creating…" to "Created." must not leave the loading description behind.
+  record.options = {
+    ...record.options,
+    ...options,
+    title: options.title ?? record.options.title,
+    description: options.description,
+    message: options.message,
+  };
+  record.duration = options.duration ?? DEFAULT_DURATION;
+  record.remaining = record.duration;
+
+  render(record.element, id, record.options);
+  recalcStack();
+  schedule(record);
+  return true;
+}
+
+export function dismiss(element: HTMLElement): void {
+  const id = element.dataset.toastId;
+  const record = id ? records.get(id) : undefined;
+  if (record) {
+    clearTimer(record);
+    records.delete(record.id);
+  }
+
+  if (element.hasAttribute("data-toast-leaving")) return;
+  element.setAttribute("data-toast-leaving", "");
+  recalcStack();
+
+  const hadFocus = element.contains(document.activeElement);
+  const origin = origins.get(element);
+  const remove = () => {
+    forgetToast(element);
+    element.remove();
+    applyVisibility();
+    if (hadFocus) origin?.focus();
+  };
+
+  const reduced =
+    typeof matchMedia === "function" &&
+    matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  if (reduced) remove();
+  else window.setTimeout(remove, EXIT_DELAY);
+}
+
+export function close(id: string): boolean {
+  const record = records.get(id);
+  if (!record) return false;
+  dismiss(record.element);
+  return true;
+}
+
+/**
+ * Mount an already-rendered toast (the Astro template clone) in the shared
+ * region and give it the same timer, pause-on-hover and dismissal behaviour.
+ */
+export function mount(element: HTMLElement, origin?: HTMLElement): string {
+  // Clones of one template share an id, so every mounted toast gets its own.
+  const id = nextId();
+  element.id = id;
+  element.setAttribute("data-toast-id", id);
+  const rawDuration = element.dataset.toastDuration;
+  const parsed = rawDuration === undefined ? Number.NaN : Number(rawDuration);
+  const duration = Number.isFinite(parsed) ? parsed : DEFAULT_DURATION;
+
+  const record: ToastRecord = {
+    element,
+    id,
+    duration,
+    remaining: duration,
+    startedAt: 0,
+    timer: null,
+    options: {},
+  };
+
+  if (origin) origins.set(element, origin);
+  records.set(id, record);
+  ensureRegion().append(element);
+
+  wire(record);
+  observeToast(element);
+  schedule(record);
+  applyVisibility();
+
+  return id;
+}
+
+function resolveContent<T>(
+  value: string | ToastContent | ((input: T) => string | ToastContent),
+  input?: T,
+): ToastContent {
+  const resolved =
+    typeof value === "function"
+      ? (value as (input: T) => string | ToastContent)(input as T)
+      : value;
+  return typeof resolved === "string" ? { title: resolved } : resolved;
+}
+
+/**
+ * Update one toast as an async task moves through loading, success and error,
+ * matching shadcn/ui's `toast.promise(promise, { loading, success, error })`.
+ * The original promise is returned untouched.
+ */
+export function promise<T>(
+  task: Promise<T>,
+  options: ToastPromiseOptions<T>,
+): Promise<T> {
+  const id = add({
+    ...resolveContent(options.loading),
+    type: "loading",
+    duration: 0,
+  });
+
+  task.then(
+    (value) => {
+      update(id, {
+        ...resolveContent(options.success, value),
+        type: "success",
+        duration: options.duration ?? DEFAULT_DURATION,
+      });
+    },
+    (error: unknown) => {
+      update(id, {
+        ...resolveContent(options.error, error),
+        type: "error",
+        duration: options.duration ?? ERROR_DURATION,
+      });
+    },
+  );
+
+  return task;
+}
+
+export const toast = {
+  add,
+  update,
+  close,
+  dismiss,
+  promise,
+};
+
+export default toast;

package/src/scripts/tooltip.ts

@@ -0,0 +1,127 @@
+/**
+ * Tooltip runtime. Dependency-free; shared by the Astro component and the
+ * React port. The surface is a `popover="manual"` element so it escapes
+ * clipping; this script decides when it shows.
+ *
+ *   import { mountTooltip } from "@db-vincent/components/scripts/tooltip";
+ *   const destroy = mountTooltip(document.querySelector("[data-ds-tooltip]"));
+ *
+ * Hover opens after a delay and only on hover-capable fine pointers. Keyboard
+ * focus opens at once. Escape, leaving, pressing the trigger and blur close it.
+ * While one tooltip is open, and briefly after it closes, the next one opens
+ * with `data-instant` so it skips the animation.
+ */
+
+const HOVER_CAPABLE = "(hover: hover) and (pointer: fine)";
+const DEFAULT_DELAY_MS = 400;
+/** Time to cross the gap between trigger and surface without closing. */
+const LEAVE_GRACE_MS = 100;
+/** How long after a close the next tooltip still opens instantly. */
+const WARM_MS = 300;
+
+interface Handle {
+  hide: (instant: boolean) => void;
+}
+
+let current: Handle | null = null;
+let warmUntil = 0;
+
+/** A tooltip is open, or one closed moments ago: skip delay and animation. */
+const isWarm = () => current !== null || performance.now() < warmUntil;
+
+/** Wire up one `[data-ds-tooltip]` root. Returns a cleanup function. */
+export function mountTooltip(root: HTMLElement): () => void {
+  const surface = root.querySelector<HTMLElement>('[role="tooltip"]');
+  const trigger = root.querySelector<HTMLElement>(
+    ':scope > :not([role="tooltip"])',
+  );
+  if (!surface || !trigger) return () => {};
+
+  const describedBy = new Set(
+    (trigger.getAttribute("aria-describedby") ?? "")
+      .split(/\s+/)
+      .filter(Boolean),
+  );
+  describedBy.add(surface.id);
+  trigger.setAttribute("aria-describedby", [...describedBy].join(" "));
+
+  const delay = Number(root.dataset.delay ?? DEFAULT_DELAY_MS);
+  let showTimer = 0;
+  let hideTimer = 0;
+
+  const isOpen = () => surface.matches(":popover-open");
+  const clearTimers = () => {
+    window.clearTimeout(showTimer);
+    window.clearTimeout(hideTimer);
+  };
+
+  const onDocumentKeydown = (event: KeyboardEvent) => {
+    if (event.key !== "Escape" || !isOpen()) return;
+    // Dismiss the tooltip first; do not also close a surrounding dialog.
+    event.preventDefault();
+    event.stopPropagation();
+    hide(false);
+  };
+
+  const handle: Handle = { hide: (instant) => hide(instant) };
+
+  function hide(instant: boolean) {
+    clearTimers();
+    if (!isOpen()) return;
+    surface!.toggleAttribute("data-instant", instant);
+    surface!.hidePopover();
+    document.removeEventListener("keydown", onDocumentKeydown, true);
+    if (current === handle) {
+      current = null;
+      warmUntil = performance.now() + WARM_MS;
+    }
+  }
+
+  function show() {
+    clearTimers();
+    if (isOpen()) return;
+    const instant = isWarm();
+    current?.hide(true);
+    surface!.toggleAttribute("data-instant", instant);
+    surface!.showPopover();
+    current = handle;
+    document.addEventListener("keydown", onDocumentKeydown, true);
+  }
+
+  const onPointerEnter = (event: PointerEvent) => {
+    if (event.pointerType === "touch" || !matchMedia(HOVER_CAPABLE).matches)
+      return;
+    clearTimers();
+    if (isOpen()) return;
+    if (isWarm()) show();
+    else showTimer = window.setTimeout(show, delay);
+  };
+
+  const onPointerLeave = () => {
+    clearTimers();
+    if (isOpen())
+      hideTimer = window.setTimeout(() => hide(false), LEAVE_GRACE_MS);
+  };
+
+  const onFocusIn = (event: FocusEvent) => {
+    if ((event.target as Element).matches(":focus-visible")) show();
+  };
+
+  const onFocusOut = () => hide(false);
+  const onPointerDown = () => hide(false);
+
+  root.addEventListener("pointerenter", onPointerEnter);
+  root.addEventListener("pointerleave", onPointerLeave);
+  root.addEventListener("pointerdown", onPointerDown);
+  root.addEventListener("focusin", onFocusIn);
+  root.addEventListener("focusout", onFocusOut);
+
+  return () => {
+    hide(true);
+    root.removeEventListener("pointerenter", onPointerEnter);
+    root.removeEventListener("pointerleave", onPointerLeave);
+    root.removeEventListener("pointerdown", onPointerDown);
+    root.removeEventListener("focusin", onFocusIn);
+    root.removeEventListener("focusout", onFocusOut);
+  };
+}