@kingsleyweb/bun-ui 0.0.0-stage → 3.0.0-rc.2

package/app/docs/boot.tsx

@@ -0,0 +1,58 @@
+import type { Root } from "react-dom/client";
+import type { DocsUiConfig } from "../../lib/docs/browser/config.ts";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import { readDocsUiConfig } from "./config";
+import { createQueryClient } from "./queryClient";
+import { applyTheme, initialTheme } from "./theme";
+
+/** Options of {@link boot}. */
+export interface BootOptions {
+  /** The document to read the config from and render into. Defaults to `document`. */
+  doc?: Document;
+  /** Retry failed reads. Defaults to `true`; tests pass `false`. */
+  retry?: boolean;
+}
+
+/** What {@link boot} started. */
+export interface BootResult {
+  /** The config it read. */
+  config: DocsUiConfig;
+  /** The React root; `unmount()` tears the app down. */
+  root: Root;
+}
+
+/**
+ * Starts the viewer: reads the injected config, applies the theme, and renders
+ * into `#root`. A missing or malformed config renders a plain message
+ * instead (there is no document to fetch without it) and rethrows.
+ */
+export function boot(options: BootOptions = {}): BootResult {
+  const doc = options.doc ?? document;
+  const container = doc.getElementById("root");
+  if (!container) {
+    throw new Error("The page has no #root element.");
+  }
+  let config: DocsUiConfig;
+  try {
+    config = readDocsUiConfig(doc);
+  } catch (error) {
+    container.textContent = `The API docs viewer could not start: ${error instanceof Error ? error.message : String(error)}`;
+    throw error;
+  }
+  applyTheme(initialTheme(config.theme), doc.documentElement);
+  doc.title = config.title;
+
+  const queryClient = createQueryClient({ retry: options.retry });
+  const root = createRoot(container);
+  root.render(
+    <StrictMode>
+      <App
+        config={config}
+        queryClient={queryClient}
+      />
+    </StrictMode>,
+  );
+  return { config, root };
+}

package/app/docs/components/Badge.tsx

@@ -0,0 +1,65 @@
+import type { ReactNode } from "react";
+import { cx } from "./classNames";
+
+/** Colour of a {@link Badge}. */
+export type BadgeTone =
+  "neutral" | "info" | "success" | "warning" | "danger" | "accent";
+
+/** Props of {@link Badge}. */
+export interface BadgeProps {
+  /** Colour. Defaults to `"neutral"`. */
+  tone?: BadgeTone;
+  /** A tooltip / longer explanation. */
+  title?: string;
+  /** Extra class names. */
+  className?: string;
+  /**
+   * `data-testid` for the badge, when a test or an example must find this one
+   * among several — by what it is, rather than by its position.
+   */
+  testId?: string;
+  /** The text. */
+  children: ReactNode;
+}
+
+/** A small status label. */
+export function Badge({
+  tone = "neutral",
+  title,
+  className,
+  testId,
+  children,
+}: BadgeProps) {
+  return (
+    <span
+      className={cx("badge", `badge-${tone}`, className)}
+      title={title}
+      data-testid={testId}
+    >
+      {children}
+    </span>
+  );
+}
+
+/** Props of {@link Chip}. */
+export interface ChipProps {
+  /** What the value is, e.g. `"namespace"`. */
+  label: string;
+  /** The value. */
+  value: ReactNode;
+  /** A tooltip. */
+  title?: string;
+}
+
+/** A label/value pair, e.g. `namespace  orders`. */
+export function Chip({ label, value, title }: ChipProps) {
+  return (
+    <span
+      className="chip"
+      title={title}
+    >
+      <span className="chip-label">{label}</span>
+      <span className="chip-value">{value}</span>
+    </span>
+  );
+}

package/app/docs/components/Button.tsx

@@ -0,0 +1,37 @@
+import type { ButtonHTMLAttributes, Ref } from "react";
+import { cx } from "./classNames";
+
+/** Visual weight of a {@link Button}. */
+export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
+
+/** Props of {@link Button}. */
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Visual weight. Defaults to `"secondary"`. */
+  variant?: ButtonVariant;
+  /** Size. Defaults to `"md"`. */
+  size?: "sm" | "md";
+  /** The underlying `<button>`, e.g. for a dialog's initial focus. */
+  ref?: Ref<HTMLButtonElement>;
+}
+
+/** A button; `type="button"` unless told otherwise, so it never submits a form by accident. */
+export function Button({
+  variant = "secondary",
+  size = "md",
+  type = "button",
+  className,
+  ...rest
+}: ButtonProps) {
+  return (
+    <button
+      {...rest}
+      type={type}
+      className={cx(
+        "btn",
+        `btn-${variant}`,
+        size === "sm" && "btn-sm",
+        className,
+      )}
+    />
+  );
+}

package/app/docs/components/Card.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode } from "react";
+import { useId } from "react";
+import { cx } from "./classNames";
+
+/** Props of {@link Card}. */
+export interface CardProps {
+  /** Heading, rendered as an `<h2>` that labels the card's region. */
+  title?: ReactNode;
+  /** Controls shown beside the heading. */
+  actions?: ReactNode;
+  /** Extra class names. */
+  className?: string;
+  /** The content. */
+  children: ReactNode;
+}
+
+/** A bordered surface; with a `title` it is a labelled `<section>`. */
+export function Card({ title, actions, className, children }: CardProps) {
+  const headingId = useId();
+  return (
+    <section
+      className={cx("card", className)}
+      aria-labelledby={title ? headingId : undefined}
+    >
+      {(title || actions) && (
+        <div className="card-header">
+          {title && (
+            <h2
+              id={headingId}
+              className="card-title"
+            >
+              {title}
+            </h2>
+          )}
+          {actions && <div className="card-actions">{actions}</div>}
+        </div>
+      )}
+      <div className="card-body">{children}</div>
+    </section>
+  );
+}

package/app/docs/components/ConfirmDialog.tsx

@@ -0,0 +1,173 @@
+import type { FormEvent, ReactNode } from "react";
+import { useRef, useState } from "react";
+import { Button } from "./Button";
+import { Dialog } from "./Dialog";
+import { Field } from "./Field";
+import { TextInput } from "./inputs";
+import { ProblemBanner } from "./ProblemBanner";
+
+/** Props of {@link ConfirmDialog}. */
+export interface ConfirmDialogProps {
+  /** Whether it is showing. State (typed text, error) resets on each opening. */
+  open: boolean;
+  /** Asks to close (Cancel, Escape, backdrop, or after a successful confirm). Ignored while pending. */
+  onClose: () => void;
+  /** The question, e.g. "Drain queue emails?". */
+  title: ReactNode;
+  /** What will happen, in a sentence. */
+  description?: ReactNode;
+  /** Extra body content, e.g. options such as a "include delayed" checkbox. */
+  children?: ReactNode;
+  /**
+   * The action. May be async: the dialog shows a pending state until it
+   * settles, closes on success, and on a throw stays open with the error
+   * shown inline (an `ApiError` as a {@link ProblemBanner}).
+   */
+  onConfirm: () => unknown;
+  /** The confirm button's text. Defaults to `"Confirm"`. */
+  confirmLabel?: string;
+  /** The confirm button's text while pending. Defaults to `confirmLabel` + "…". */
+  pendingLabel?: string;
+  /** The cancel button's text. Defaults to `"Cancel"`. */
+  cancelLabel?: string;
+  /** `"danger"` for destructive actions: a red button, `alertdialog`, and Cancel focused first. Defaults to `"default"`. */
+  variant?: "default" | "danger";
+  /** When set, the user must type exactly this (e.g. the queue name) before Confirm enables. */
+  confirmText?: string;
+  /** The typed-confirmation label. Defaults to "Type <confirmText> to confirm". */
+  confirmTextLabel?: ReactNode;
+  /** Close after a successful `onConfirm`. Defaults to `true`. */
+  closeOnSuccess?: boolean;
+  /** Keeps Confirm disabled, e.g. while the body's options are invalid. */
+  confirmDisabled?: boolean;
+}
+
+/**
+ * A yes/no dialog for an action, built on {@link Dialog}: an optional typed
+ * confirmation for destructive ones, an async `onConfirm` with a pending
+ * state, and the failure shown in place so the user can retry or cancel.
+ */
+export function ConfirmDialog(props: ConfirmDialogProps) {
+  return props.open ? <OpenConfirmDialog {...props} /> : null;
+}
+
+/** The mounted dialog; its state lives exactly as long as one opening. */
+function OpenConfirmDialog({
+  onClose,
+  title,
+  description,
+  children,
+  onConfirm,
+  confirmLabel = "Confirm",
+  pendingLabel,
+  cancelLabel = "Cancel",
+  variant = "default",
+  confirmText,
+  confirmTextLabel,
+  closeOnSuccess = true,
+  confirmDisabled = false,
+}: ConfirmDialogProps) {
+  const [typed, setTyped] = useState("");
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<unknown>(null);
+  const cancelRef = useRef<HTMLButtonElement>(null);
+  const confirmRef = useRef<HTMLButtonElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const matches = confirmText === undefined || typed === confirmText;
+  const canConfirm = matches && !pending && !confirmDisabled;
+  const danger = variant === "danger";
+
+  const confirm = async () => {
+    if (!canConfirm) {
+      return;
+    }
+    setPending(true);
+    setError(null);
+    try {
+      await onConfirm();
+      setPending(false);
+      if (closeOnSuccess) {
+        onClose();
+      }
+    } catch (caught) {
+      setPending(false);
+      setError(caught);
+    }
+  };
+
+  const onSubmit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    void confirm();
+  };
+
+  const close = () => {
+    if (!pending) {
+      onClose();
+    }
+  };
+
+  return (
+    <Dialog
+      open
+      onClose={close}
+      title={title}
+      description={description}
+      role={danger ? "alertdialog" : "dialog"}
+      size="sm"
+      closeOnEscape={!pending}
+      closeOnBackdrop={!pending}
+      initialFocusRef={
+        confirmText !== undefined ? inputRef : danger ? cancelRef : confirmRef
+      }
+      footer={
+        <>
+          <Button
+            ref={cancelRef}
+            onClick={close}
+            disabled={pending}
+          >
+            {cancelLabel}
+          </Button>
+          <Button
+            ref={confirmRef}
+            variant={danger ? "danger" : "primary"}
+            disabled={!canConfirm}
+            aria-busy={pending || undefined}
+            onClick={() => void confirm()}
+          >
+            {pending ? (pendingLabel ?? `${confirmLabel}…`) : confirmLabel}
+          </Button>
+        </>
+      }
+    >
+      <form
+        className="confirm-dialog-body"
+        onSubmit={onSubmit}
+      >
+        {children}
+        {confirmText !== undefined && (
+          <Field
+            label={
+              confirmTextLabel ?? (
+                <>
+                  Type <code>{confirmText}</code> to confirm
+                </>
+              )
+            }
+          >
+            <TextInput
+              ref={inputRef}
+              value={typed}
+              onChange={setTyped}
+              autoComplete="off"
+              spellCheck={false}
+              disabled={pending}
+            />
+          </Field>
+        )}
+        {error !== null && <ProblemBanner error={error} />}
+      </form>
+    </Dialog>
+  );
+}

package/app/docs/components/CopyButton.tsx

@@ -0,0 +1,68 @@
+import { useEffect, useState } from "react";
+import { Button } from "./Button";
+import { cx } from "./classNames";
+import { COPY_FEEDBACK_MS, copyText } from "./copy";
+
+/** Props of {@link CopyButton}. */
+export interface CopyButtonProps {
+  /** What to copy, or a function producing it on click (so a large payload is only serialised when asked). */
+  text: string | (() => string);
+  /** The button's visible text. Defaults to `"Copy"`. */
+  label?: string;
+  /** Accessible name when it differs from `label`, e.g. `"Copy job id"`. */
+  ariaLabel?: string;
+  /** Size. Defaults to `"sm"`. */
+  size?: "sm" | "md";
+  /** Extra class names. */
+  className?: string;
+  /** Called after each attempt with whether the clipboard write succeeded. */
+  onCopied?: (ok: boolean) => void;
+}
+
+/**
+ * Copies text to the clipboard and says so: the label turns into "Copied"
+ * (or "Copy failed") for {@link COPY_FEEDBACK_MS}, announced politely.
+ */
+export function CopyButton({
+  text,
+  label = "Copy",
+  ariaLabel,
+  size = "sm",
+  className,
+  onCopied,
+}: CopyButtonProps) {
+  const [status, setStatus] = useState<"idle" | "copied" | "failed">("idle");
+
+  useEffect(() => {
+    if (status === "idle") {
+      return;
+    }
+    const timer = setTimeout(setStatus, COPY_FEEDBACK_MS, "idle");
+    return () => clearTimeout(timer);
+  }, [status]);
+
+  const onClick = async () => {
+    const ok = await copyText(typeof text === "function" ? text() : text);
+    setStatus(ok ? "copied" : "failed");
+    onCopied?.(ok);
+  };
+
+  return (
+    <Button
+      variant="ghost"
+      size={size}
+      className={cx("copy-button", className)}
+      aria-label={ariaLabel}
+      data-status={status}
+      onClick={() => void onClick()}
+    >
+      <span aria-live="polite">
+        {status === "copied"
+          ? "Copied"
+          : status === "failed"
+            ? "Copy failed"
+            : label}
+      </span>
+    </Button>
+  );
+}

package/app/docs/components/Dialog.tsx

@@ -0,0 +1,230 @@
+import type {
+  KeyboardEvent,
+  MouseEvent,
+  ReactNode,
+  RefObject,
+  SyntheticEvent,
+} from "react";
+import { useEffect, useId, useRef } from "react";
+import { Button } from "./Button";
+import { cx } from "./classNames";
+
+/** What counts as focusable inside a dialog, for the trap and the initial focus. */
+const FOCUSABLE = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled]):not([type='hidden'])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "summary",
+  "[contenteditable]:not([contenteditable='false'])",
+  "[tabindex]:not([tabindex='-1'])",
+].join(",");
+
+/** The focusable elements inside `root`, in DOM order. */
+function focusableIn(root: HTMLElement): HTMLElement[] {
+  return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
+    (element) => !element.hasAttribute("inert") && !element.closest("[inert]"),
+  );
+}
+
+/** Props of {@link Dialog}. */
+export interface DialogProps {
+  /** Whether the dialog is showing. The content only mounts while open, so its state resets on each opening. */
+  open: boolean;
+  /** Asks to close: Escape, a backdrop click or the close button. The caller sets `open` to `false`. */
+  onClose: () => void;
+  /** The heading; it labels the dialog (`aria-labelledby`). */
+  title: ReactNode;
+  /** A sentence under the title; it describes the dialog (`aria-describedby`). */
+  description?: ReactNode;
+  /** The body. */
+  children?: ReactNode;
+  /** Actions along the bottom, usually {@link Button}s; the primary one last. */
+  footer?: ReactNode;
+  /** Close on Escape. Defaults to `true`; turn off while something is pending. */
+  closeOnEscape?: boolean;
+  /** Close on a click outside the panel. Defaults to `true`. */
+  closeOnBackdrop?: boolean;
+  /** Show the × button in the header. Defaults to `true`. */
+  showCloseButton?: boolean;
+  /** Width. Defaults to `"md"` (`sm` 400px, `md` 560px, `lg` 800px, each capped at the viewport). */
+  size?: "sm" | "md" | "lg";
+  /** What to focus on open. Defaults to the first focusable element in the body, then the footer, then the panel. */
+  initialFocusRef?: RefObject<HTMLElement | null>;
+  /** `"alertdialog"` for a confirmation that interrupts. Defaults to `"dialog"`. */
+  role?: "dialog" | "alertdialog";
+  /** Extra class names on the panel. */
+  className?: string;
+}
+
+/**
+ * A modal on the native `<dialog>` element (`showModal()`, so the page
+ * behind is inert and it sits in the top layer; no portal needed).
+ *
+ * Tab and Shift+Tab cycle inside it; Escape and a backdrop click call
+ * `onClose` when allowed; on close, focus returns to whatever had it when
+ * the dialog opened.
+ */
+export function Dialog(props: DialogProps) {
+  return props.open ? <OpenDialog {...props} /> : null;
+}
+
+/** The mounted dialog: mount is "open", unmount is "close". */
+function OpenDialog({
+  onClose,
+  title,
+  description,
+  children,
+  footer,
+  closeOnEscape = true,
+  closeOnBackdrop = true,
+  showCloseButton = true,
+  size = "md",
+  initialFocusRef,
+  role = "dialog",
+  className,
+}: DialogProps) {
+  const ref = useRef<HTMLDialogElement>(null);
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const titleId = useId();
+  const descriptionId = useId();
+
+  useEffect(() => {
+    const dialog = ref.current;
+    if (!dialog) {
+      return;
+    }
+    const opener =
+      document.activeElement instanceof HTMLElement
+        ? document.activeElement
+        : null;
+    if (!dialog.open) {
+      if (typeof dialog.showModal === "function") {
+        dialog.showModal();
+      } else {
+        dialog.setAttribute("open", "");
+      }
+    }
+    const target =
+      initialFocusRef?.current ??
+      (bodyRef.current && focusableIn(bodyRef.current)[0]) ??
+      focusableIn(dialog).find((element) => !element.dataset.dialogClose) ??
+      dialog;
+    target.focus();
+    return () => {
+      if (dialog.open && typeof dialog.close === "function") {
+        dialog.close();
+      }
+      if (opener?.isConnected) {
+        opener.focus();
+      }
+    };
+    // Runs once per opening (the ref objects are stable).
+  }, [initialFocusRef]);
+
+  const onKeyDown = (event: KeyboardEvent<HTMLDialogElement>) => {
+    if (event.key === "Escape") {
+      // Stop the native `cancel` so the element's open state stays ours.
+      event.preventDefault();
+      event.stopPropagation();
+      if (closeOnEscape) {
+        onClose();
+      }
+      return;
+    }
+    if (event.key !== "Tab" || !ref.current) {
+      return;
+    }
+    const focusable = focusableIn(ref.current);
+    if (focusable.length === 0) {
+      event.preventDefault();
+      ref.current.focus();
+      return;
+    }
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const active = document.activeElement;
+    const inside = active instanceof Node && ref.current.contains(active);
+    if (event.shiftKey && (active === first || !inside)) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && (active === last || !inside)) {
+      event.preventDefault();
+      first.focus();
+    }
+  };
+
+  // Escape in a real browser can arrive as `cancel` without a keydown we saw.
+  const onCancel = (event: SyntheticEvent<HTMLDialogElement>) => {
+    event.preventDefault();
+    if (closeOnEscape) {
+      onClose();
+    }
+  };
+
+  // The panel fills the element, so a click whose target is the element
+  // itself landed on the backdrop.
+  const onClick = (event: MouseEvent<HTMLDialogElement>) => {
+    if (closeOnBackdrop && event.target === event.currentTarget) {
+      onClose();
+    }
+  };
+
+  return (
+    // The keyboard handling lives on the dialog element (Escape and the
+    // focus trap); a backdrop click is a pointer-only convenience.
+    <dialog
+      ref={ref}
+      role={role === "alertdialog" ? "alertdialog" : undefined}
+      aria-modal="true"
+      aria-labelledby={titleId}
+      aria-describedby={description ? descriptionId : undefined}
+      className={cx("dialog", `dialog-${size}`, className)}
+      tabIndex={-1}
+      onKeyDown={onKeyDown}
+      onCancel={onCancel}
+      onClick={onClick}
+    >
+      <div className="dialog-panel">
+        <div className="dialog-header">
+          <h2
+            id={titleId}
+            className="dialog-title"
+          >
+            {title}
+          </h2>
+          {showCloseButton && (
+            <Button
+              variant="ghost"
+              size="sm"
+              className="dialog-close"
+              aria-label="Close"
+              data-dialog-close="true"
+              onClick={onClose}
+            >
+              <span aria-hidden="true">×</span>
+            </Button>
+          )}
+        </div>
+        {description && (
+          <p
+            id={descriptionId}
+            className="dialog-description"
+          >
+            {description}
+          </p>
+        )}
+        {children !== undefined && (
+          <div
+            ref={bodyRef}
+            className="dialog-body"
+          >
+            {children}
+          </div>
+        )}
+        {footer && <div className="dialog-footer">{footer}</div>}
+      </div>
+    </dialog>
+  );
+}