Skip to content

The Open Standard for Generative UI

19.6 KB
Raw Blame
"use client";

import { observability, type ObservabilityEvent } from "@openuidev/observability";
import { Inbox, RotateCcw, Settings, X } from "lucide-react";
import { useEffect, useRef, useState, type CSSProperties } from "react";
import { DEFAULT_EDITOR_PCT, useDebug } from "./debug";
import {
  EventRow,
  getQuotaError,
  getReactLangStreamDetail,
  QuotaErrorRow,
  ReactLangStreamEventRow,
} from "./inspect";
import {
  addOrReplaceEvent,
  isLibraryEvent,
  useCornerDrag,
  useDevtoolsConfig,
  useDevtoolsSingleton,
  type DevtoolsConfig,
} from "./lib";
import {
  DEFAULT_COLOR_MODE,
  DevtoolsModeProvider,
  FONT,
  rootStyle,
  theme,
  useStyles,
  type ThemeTokens,
} from "./theme";
import type { DevtoolsPosition, OpenUIDevtoolsWidgetProps } from "./types";
import {
  ErrorBoundary,
  IconButton,
  INTER_FONT_FACE,
  PositionSegmented,
  ShiroLogo,
  ThemeSegmented,
} from "./ui";
import { DeployBanner, DeployHint } from "./ui/DeployHint";
import ReliabilityBanner from "./ui/ReliabilityBanner";

export type { DevtoolsPosition, OpenUIDevtoolsProps, OpenUIDevtoolsWidgetProps } from "./types";

/** Uniform row height for the settings menu, set by its tallest control. */
const MENU_ROW_HEIGHT = 28;

/**
 * Tray geometry. The two trays together fill a block anchored to the
 * launcher's corner — 85% of the viewport, capped so it stops growing on very
 * large displays. Inspect keeps a fixed width and Debug takes whatever is left,
 * overlapping Inspect rather than collapsing once it hits its floor.
 */
const TRAY_EDGE = 12;
const TRAY_GAP = 12;
const INSPECT_WIDTH = 480;
const DEBUG_MIN_WIDTH = 360;
const BLOCK_W = `min(85vw, 3456px)`;
const BLOCK_H = `min(85vh, 2234px)`;

/**
 * Full Inspect/Debug UI. Only loaded from the CDN browser bundle after the
 * host has injected React into the slot — not from the npm package entry.
 */
export function OpenUIDevtoolsWidget({
  enabled,
  position = "bottom-right",
  maxEvents = 50,
  errorsOnly = false,
  autoOpenOnError = true,
  theme: themeProp,
  __autoMounted = false,
}: OpenUIDevtoolsWidgetProps) {
  const isEnabled =
    enabled ?? (typeof process === "undefined" || process.env["NODE_ENV"] !== "production");
  // Only one instance renders even when several are mounted (e.g. react-lang's
  // auto-mount plus a manual <OpenUIDevtools /> in the host's layout).
  const isSingleton = useDevtoolsSingleton(__autoMounted);
  const [events, setEvents] = useState<ObservabilityEvent[]>([]);
  const [open, setOpen] = useState(false);
  const [toggleHovered, setToggleHovered] = useState(false);
  const { config, setConfig, configRef } = useDevtoolsConfig(
    {
      autoOpen: autoOpenOnError,
      onlyErrors: errorsOnly,
      theme: DEFAULT_COLOR_MODE,
      position,
      helpSeen: false,
      editorPct: DEFAULT_EDITOR_PCT,
    },
    { theme: themeProp },
  );
  const { onlyErrors, theme: mode, position: corner } = config;
  const debug = useDebug({
    theme: mode,
    helpSeen: config.helpSeen,
    editorPct: config.editorPct,
    setConfig,
  });
  const styles = uiStyles(theme(mode));
  const drag = useCornerDrag(corner, (position) => setConfig({ position }));

  // Read configRef inside the (stable) subscription without re-subscribing.
  useEffect(() => {
    if (!isEnabled) return;
    return observability.listenAll((event) => {
      if (isLibraryEvent(event)) return;
      setEvents((prev) => addOrReplaceEvent(prev, event, maxEvents));
      if (event.level === "error" && configRef.current.autoOpen) setOpen(true);
    });
  }, [isEnabled, maxEvents, configRef]);

  // Escape dismisses the top tray first: Debug → Inspect → closed. The
  // settings menu handles its own Escape first (capture phase), so it never
  // falls through to here.
  useEffect(() => {
    if (!open && !debug.trayOpen) return;
    const onKeyDown = (event: KeyboardEvent) => {
      if (event.key !== "Escape") return;
      if (debug.trayOpen) debug.retract();
      else setOpen(false);
    };
    document.addEventListener("keydown", onKeyDown);
    return () => document.removeEventListener("keydown", onKeyDown);
  }, [open, debug.trayOpen, debug.retract]);

  if (!isEnabled || !isSingleton) return null;

  const errorCount = events.filter((event) => event.level === "error").length;
  const visibleEvents = onlyErrors ? events.filter((event) => event.level !== "info") : events;

  // Inspect is pinned to the launcher's side; Debug fills the rest of the
  // block and slides over to reclaim Inspect's slot whenever Inspect is out.
  const side = corner.endsWith("left") ? "left" : "right";
  const edge = corner.startsWith("top") ? "top" : "bottom";
  const inspectSlot = open ? INSPECT_WIDTH + TRAY_GAP : 0;
  const inspectTray: CSSProperties = {
    [side]: TRAY_EDGE,
    [edge]: TRAY_EDGE,
    height: BLOCK_H,
    width: `min(${INSPECT_WIDTH}px, calc(100vw - ${TRAY_EDGE * 2}px))`,
    transform: open
      ? "translateX(0)"
      : `translateX(calc((100% + ${TRAY_EDGE}px) * ${side === "left" ? -1 : 1}))`,
  };
  // Debug is a workspace rather than a peek at the app behind it: it fills
  // everything Inspect leaves (left/right edges rather than a width, so the
  // inset matches top and bottom) and cuts straight in instead of sliding.
  // Overrides the shared UI, so it is spread last.
  const debugTray: CSSProperties = {
    [side]: TRAY_EDGE + inspectSlot,
    [edge]: TRAY_EDGE,
    height: BLOCK_H,
    width: `max(${DEBUG_MIN_WIDTH}px, calc(${BLOCK_W} - ${inspectSlot}px))`,
    transform: "none",
    transition: "none",
    visibility: debug.trayOpen ? "visible" : "hidden",
  };

  return (
    <DevtoolsModeProvider mode={mode}>
      <style>{INTER_FONT_FACE}</style>
      <DeployHint position={corner} hidden={open || debug.trayOpen || drag.dragging} />
      <div
        ref={drag.ref}
        style={{ ...styles.toggleWrap, ...rootStyle(mode), ...positionStyles[corner] }}
      >
        <button
          style={{
            ...styles.toggle,
            ...(errorCount > 0 ? styles.toggleError : null),
            ...(toggleHovered ? styles.toggleHover : null),
            ...(drag.dragging ? styles.toggleDragging : null),
          }}
          {...drag.handlers}
          onClick={() => {
            if (!drag.consumeDrag()) setOpen(true);
          }}
          onMouseEnter={() => setToggleHovered(true)}
          onMouseLeave={() => setToggleHovered(false)}
          aria-label="Open OpenUI Inspect"
          aria-expanded={open}
          title={
            errorCount > 0 ? `${errorCount} error${errorCount === 1 ? "" : "s"}` : "OpenUI Inspect"
          }
        >
          {errorCount > 0 ? (
            <span style={styles.toggleCount}>{errorCount > 99 ? "99+" : errorCount}</span>
          ) : (
            <ShiroLogo size={22} />
          )}
        </button>
      </div>

      {/* Kept mounted so open/close can transition; hidden + inert when closed. */}
      <aside
        style={{
          ...styles.drawer,
          ...rootStyle(mode),
          ...inspectTray,
          ...(open ? styles.drawerOpen : null),
        }}
        role="dialog"
        aria-modal={false}
        aria-label="OpenUI Inspect"
        inert={!open}
      >
        <div style={styles.header}>
          <div style={styles.headerLeft}>
            <span style={styles.title}>OpenUI Inspect</span>
          </div>
          <div style={styles.headerActions}>
            <IconButton
              onClick={() => setEvents([])}
              aria-label="Reset events"
              title="Reset events"
            >
              <RotateCcw size={14} />
            </IconButton>
            <SettingsMenu config={config} onChange={setConfig} />
            <IconButton onClick={() => setOpen(false)} aria-label="Close OpenUI Inspect">
              <X size={15} />
            </IconButton>
          </div>
        </div>

        <ReliabilityBanner themeMode={mode} />

        <ErrorBoundary title="Inspect ran into a problem">
          <div style={styles.list}>
            <DeployBanner />
            {visibleEvents.length === 0 ? (
              <div style={styles.empty}>
                <span style={styles.emptyIcon}>
                  <Inbox size={20} />
                </span>
                No events captured yet.
              </div>
            ) : (
              visibleEvents.map((event, index) => {
                const key =
                  typeof event.detail["id"] === "string"
                    ? event.detail["id"]
                    : `${event.timestamp}-${index}`;
                const quotaError = getQuotaError(event);
                if (quotaError) return <QuotaErrorRow key={key} info={quotaError} />;
                const stream = getReactLangStreamDetail(event);
                if (stream) {
                  return (
                    <ReactLangStreamEventRow
                      key={key}
                      event={event}
                      stream={stream}
                      canOpenInDebug={debug.canOpen}
                      onOpenInDebug={debug.openWith}
                    />
                  );
                }
                return <EventRow key={key} event={event} />;
              })
            )}
          </div>
        </ErrorBoundary>
        <span style={styles.trayFade} aria-hidden />
      </aside>

      <aside
        style={{
          ...styles.drawer,
          ...rootStyle(mode),
          ...(debug.trayOpen ? styles.drawerOpen : null),
          ...debugTray,
        }}
        role="dialog"
        aria-modal={false}
        aria-label="OpenUI Debug"
        inert={!debug.trayOpen}
      >
        <div style={styles.debugHost}>{debug.view}</div>
      </aside>
      {debug.portal}
    </DevtoolsModeProvider>
  );
}

/**
 * A real checkbox painted as a switch — the input stays in the tree (hidden but
 * clickable and focusable) so keyboard, form semantics, and screen readers get
 * the native control rather than a div pretending to be one.
 */
function SettingSwitch({
  label,
  checked,
  onChange,
}: {
  label: string;
  checked: boolean;
  onChange: (checked: boolean) => void;
}) {
  const styles = useStyles(uiStyles);
  return (
    <label style={styles.menuCheckbox}>
      <span style={styles.menuLabel}>{label}</span>
      <span style={{ ...styles.switchTrack, ...(checked ? styles.switchTrackOn : null) }}>
        <input
          type="checkbox"
          checked={checked}
          onChange={(event) => onChange(event.target.checked)}
          style={styles.switchInput}
        />
        <span style={{ ...styles.switchKnob, ...(checked ? styles.switchKnobOn : null) }} />
      </span>
    </label>
  );
}

/**
 * Header dropdown for the display filters and the widget theme, so the list is
 * all list. Escape is handled in the capture phase so closing the menu doesn't
 * also step the drawer back.
 */
function SettingsMenu({
  config,
  onChange,
}: {
  config: DevtoolsConfig;
  onChange: (patch: Partial<DevtoolsConfig>) => void;
}) {
  const [open, setOpen] = useState(false);
  const styles = useStyles(uiStyles);
  const wrap = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!open) return;
    const onPointerDown = (event: MouseEvent) => {
      if (!wrap.current?.contains(event.target as Node)) setOpen(false);
    };
    const onKeyDown = (event: KeyboardEvent) => {
      if (event.key !== "Escape") return;
      event.stopPropagation();
      setOpen(false);
    };
    document.addEventListener("mousedown", onPointerDown);
    document.addEventListener("keydown", onKeyDown, true);
    return () => {
      document.removeEventListener("mousedown", onPointerDown);
      document.removeEventListener("keydown", onKeyDown, true);
    };
  }, [open]);

  return (
    <div ref={wrap} style={styles.menuWrap}>
      <IconButton
        active={open}
        onClick={() => setOpen((current) => !current)}
        aria-label="Devtools settings"
        aria-haspopup="true"
        aria-expanded={open}
        title="Settings"
      >
        <Settings size={14} />
      </IconButton>
      {open ? (
        <div style={styles.menu} role="group" aria-label="Devtools settings">
          {/* Every row reads the same way: name on the left, control on the
              right, hairline between. */}
          <SettingSwitch
            label="Auto-open on error"
            checked={config.autoOpen}
            onChange={(autoOpen) => onChange({ autoOpen })}
          />
          <div style={styles.menuDivider} />
          <SettingSwitch
            label="Show errors only"
            checked={config.onlyErrors}
            onChange={(onlyErrors) => onChange({ onlyErrors })}
          />
          <div style={styles.menuDivider} />
          <div style={styles.menuRow}>
            <span style={styles.menuLabel}>Theme</span>
            <ThemeSegmented value={config.theme} onChange={(theme) => onChange({ theme })} />
          </div>
          <div style={styles.menuDivider} />
          <div style={styles.menuRow}>
            <span style={styles.menuLabel}>Position</span>
            <PositionSegmented
              value={config.position}
              onChange={(position) => onChange({ position })}
            />
          </div>
        </div>
      ) : null}
    </div>
  );
}

const positionStyles: Record<DevtoolsPosition, CSSProperties> = {
  "top-left": { top: 16, left: 16 },
  "top-right": { top: 16, right: 16 },
  "bottom-left": { bottom: 16, left: 16 },
  "bottom-right": { bottom: 16, right: 16 },
};

function uiStyles(t: ThemeTokens) {
  return {
    toggleWrap: {
      position: "fixed",
      // Max 32-bit signed int — sit above any app UI.
      zIndex: 2147483647,
    },
    toggle: {
      boxSizing: "border-box",
      width: 40,
      height: 40,
      display: "flex",
      alignItems: "center",
      justifyContent: "center",
      borderRadius: "50%",
      borderWidth: 1,
      borderStyle: "solid",
      borderColor: t.toggleBorder,
      background: t.toggleBg,
      color: t.toggleFg,
      cursor: "pointer",
      boxShadow: t.toggleShadow,
      fontFamily: FONT,
      padding: 0,
      touchAction: "none",
      transition: "background 150ms ease, box-shadow 150ms ease, transform 150ms ease",
    },
    toggleHover: {
      transform: "scale(1.08)",
    },
    toggleDragging: {
      cursor: "grabbing",
      transform: "scale(1.08)",
    },
    // Errors swap the mark for a count on a red disc, held inside a light puck so
    // the number reads as a badge rather than flooding the whole button red.
    toggleError: {
      background: t.toggleErrorSurface,
      borderColor: t.toggleErrorRing,
    },
    toggleCount: {
      display: "inline-flex",
      alignItems: "center",
      justifyContent: "center",
      boxSizing: "border-box",
      minWidth: 24,
      height: 24,
      padding: "0 6px",
      borderRadius: 999,
      background: t.toggleError,
      color: "#fff",
      fontSize: 13,
      fontWeight: 700,
      lineHeight: 1,
    },
    // Geometry (side/width/transform) is per-tray and set inline; this is the
    // shared UI. Each tray hides itself when closed so the other can stay open
    // without a retracted tray remaining focusable.
    drawer: {
      position: "fixed",
      // Max 32-bit signed int — sit above any app UI, including the toggle.
      zIndex: 2147483647,
      boxSizing: "border-box",
      display: "flex",
      flexDirection: "column",
      borderWidth: 1,
      borderStyle: "solid",
      borderColor: t.trayRing,
      borderRadius: 16,
      background: t.bg,
      boxShadow: t.trayShadow,
      color: t.fg,
      fontFamily: FONT,
      fontSize: 13,
      visibility: "hidden",
      transition:
        "transform 220ms cubic-bezier(0.32, 0.72, 0, 1), right 260ms cubic-bezier(0.32, 0.72, 0, 1), left 260ms cubic-bezier(0.32, 0.72, 0, 1), width 260ms cubic-bezier(0.32, 0.72, 0, 1), visibility 0s linear 220ms",
      overflow: "hidden",
    },
    drawerOpen: {
      visibility: "visible",
      transition:
        "transform 220ms cubic-bezier(0.32, 0.72, 0, 1), right 260ms cubic-bezier(0.32, 0.72, 0, 1), left 260ms cubic-bezier(0.32, 0.72, 0, 1), width 260ms cubic-bezier(0.32, 0.72, 0, 1), visibility 0s",
    },
    debugHost: {
      flex: 1,
      minHeight: 0,
    },
    header: {
      display: "flex",
      justifyContent: "space-between",
      alignItems: "center",
      gap: 8,
      padding: "12px 16px",
      fontWeight: 600,
      fontSize: 14,
    },
    headerLeft: {
      display: "flex",
      alignItems: "center",
      gap: 6,
      minWidth: 0,
    },
    title: {
      overflow: "hidden",
      textOverflow: "ellipsis",
      whiteSpace: "nowrap",
    },
    headerActions: {
      display: "flex",
      alignItems: "center",
      gap: 6,
      flexShrink: 0,
    },
    menuWrap: {
      position: "relative",
      display: "inline-flex",
    },
    menu: {
      position: "absolute",
      top: "calc(100% + 6px)",
      right: 0,
      // Above the banner group.
      zIndex: 2,
      boxSizing: "border-box",
      width: 236,
      display: "flex",
      flexDirection: "column",
      gap: 10,
      border: `1px solid ${t.border}`,
      borderRadius: 12,
      background: t.bg,
      boxShadow: t.shadow,
      padding: 12,
      fontWeight: 400,
    },
    // Every row is the height of the tallest control (the theme toggle), so the
    // dividers land on an even rhythm no matter what each row holds.
    menuCheckbox: {
      display: "flex",
      alignItems: "center",
      justifyContent: "space-between",
      gap: 12,
      minHeight: MENU_ROW_HEIGHT,
      cursor: "pointer",
    },
    switchTrack: {
      position: "relative",
      boxSizing: "border-box",
      flexShrink: 0,
      width: 30,
      height: 18,
      borderRadius: 999,
      background: t.border,
      transition: "background 150ms ease",
    },
    switchTrackOn: {
      background: t.inverted,
    },
    // Covers the whole track so the hit area and focus ring stay on the input.
    switchInput: {
      position: "absolute",
      inset: 0,
      width: "100%",
      height: "100%",
      margin: 0,
      borderRadius: 999,
      opacity: 0,
      cursor: "pointer",
    },
    switchKnob: {
      position: "absolute",
      top: 2,
      left: 2,
      width: 14,
      height: 14,
      borderRadius: "50%",
      background: t.bg,
      boxShadow: t.shadowSubtle,
      transition: "transform 150ms ease",
      pointerEvents: "none",
    },
    switchKnobOn: {
      transform: "translateX(12px)",
    },
    menuDivider: {
      height: 1,
      background: t.borderSubtle,
    },
    menuRow: {
      display: "flex",
      alignItems: "center",
      justifyContent: "space-between",
      gap: 12,
      minHeight: MENU_ROW_HEIGHT,
    },
    menuLabel: {
      fontSize: 12,
      fontWeight: 500,
      color: t.fg,
    },
    // Fades rows at the tray's bottom edge, so they dissolve into the
    // drawer instead of meeting the border mid-row. Pinned to the tray rather
    // than the list, so it covers the stack-trace view too.
    trayFade: {
      position: "absolute",
      left: 0,
      right: 0,
      bottom: 0,
      height: 28,
      background: `linear-gradient(to top, ${t.bg}, transparent)`,
      pointerEvents: "none",
    },
    list: {
      flex: 1,
      minHeight: 0,
      overflowY: "auto",
      padding: "0 12px 12px",
      display: "flex",
      flexDirection: "column",
      gap: 10,
    },
    // Fills the list so the message sits in the middle of the tray, not pinned
    // under the header.
    empty: {
      flex: 1,
      minHeight: 0,
      display: "flex",
      flexDirection: "column",
      alignItems: "center",
      justifyContent: "center",
      gap: 12,
      color: t.fgFaint,
      textAlign: "center",
    },
    emptyIcon: {
      display: "inline-flex",
      alignItems: "center",
      justifyContent: "center",
    },
  } satisfies Record<string, CSSProperties>;
}