@opentf/web-docs 0.1.0 → 0.2.0

package/components/Search.jsx

@@ -0,0 +1,211 @@
+// Pagefind-backed search modal (Phase 2). The navbar's `SearchTrigger` and the global
+// ⌘K / Ctrl+K shortcut open it via `window.__otfwOpenSearch`, which this component
+// installs on mount. The static index is generated at build time (`otfw build --ssg`
+// with `docs.search.provider === "pagefind"`) and lives at `/pagefind/`; we load its
+// runtime on first open so pages without a search never pay for it.
+//
+// Note: results only exist against a built site (`dist/`). In dev there is no index,
+// so the modal opens but reports no results — expected.
+import { onMount, router, RawHtml, Portal } from "@opentf/web";
+
+let pagefindPromise = null;
+function loadPagefind() {
+  if (!pagefindPromise) {
+    // A non-literal specifier keeps the bundler from trying to resolve the index at
+    // build time (it doesn't exist yet) — it stays a runtime import of the static file.
+    const path = "/pagefind/pagefind.js";
+    pagefindPromise = import(/* @vite-ignore */ path).then(async (pf) => {
+      await pf.init?.();
+      return pf;
+    });
+  }
+  return pagefindPromise;
+}
+
+export default function Search() {
+  let open = $state(false);
+  let query = $state("");
+  let results = $state([]);
+  let active = $state(0);
+  let loading = $state(false);
+  const inputRef = $ref();
+
+  let timer;
+  let token = 0;
+
+  async function runSearch(q) {
+    const mine = ++token;
+    if (!q.trim()) {
+      results = [];
+      loading = false;
+      return;
+    }
+    loading = true;
+    try {
+      const pf = await loadPagefind();
+      const search = await pf.search(q);
+      const top = (search.results || []).slice(0, 6);
+      const data = await Promise.all(top.map((r) => r.data()));
+      if (mine !== token) return; // a newer query superseded this one
+      // Flatten to heading-anchored sub-results so each row deep-links to the matched
+      // section (`/page/#heading`) rather than the page top. Pagefind builds these from
+      // the body's headings; a page with none falls back to a single page-level row.
+      const flat = [];
+      for (const d of data) {
+        const crumb = d.meta && d.meta.breadcrumb ? d.meta.breadcrumb.replace(/\s*\/\s*/g, " › ") : "";
+        // The page/post title — always shown as the result heading so you can tell which
+        // page (or blog post) a hit belongs to, even across same-named sections.
+        const pageTitle = (d.meta && d.meta.title) || d.url;
+        const subs =
+          d.sub_results && d.sub_results.length
+            ? d.sub_results
+            : [{ title: pageTitle, url: d.url, excerpt: d.excerpt }];
+        for (const s of subs.slice(0, 4)) {
+          flat.push({
+            url: s.url,
+            title: pageTitle,
+            // The matched section heading, when it differs from the page title.
+            section: s.title && s.title !== pageTitle ? s.title : "",
+            crumb,
+            excerpt: s.excerpt,
+          });
+          if (flat.length >= 10) break;
+        }
+        if (flat.length >= 10) break;
+      }
+      results = flat;
+      active = 0;
+    } catch (e) {
+      if (mine === token) results = [];
+    } finally {
+      if (mine === token) loading = false;
+    }
+  }
+
+  $effect(() => {
+    const q = query;
+    clearTimeout(timer);
+    timer = setTimeout(() => runSearch(q), 150);
+  });
+
+  const focusInput = () => {
+    const el = inputRef;
+    if (el && typeof requestAnimationFrame !== "undefined") requestAnimationFrame(() => el.focus());
+  };
+  const openModal = () => {
+    open = true;
+    focusInput();
+  };
+  const close = () => {
+    open = false;
+    query = "";
+    results = [];
+    active = 0;
+  };
+  const go = (url) => {
+    close();
+    router.push(url);
+  };
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+    window.__otfwOpenSearch = openModal;
+    const onKey = (e) => {
+      const k = e.key;
+      if ((e.metaKey || e.ctrlKey) && k.toLowerCase() === "k") {
+        e.preventDefault();
+        openModal();
+        return;
+      }
+      if (!open) return;
+      if (k === "Escape") close();
+      else if (k === "ArrowDown") {
+        e.preventDefault();
+        active = results.length ? (active + 1) % results.length : 0;
+      } else if (k === "ArrowUp") {
+        e.preventDefault();
+        active = results.length ? (active - 1 + results.length) % results.length : 0;
+      } else if (k === "Enter" && results[active]) {
+        e.preventDefault();
+        go(results[active].url);
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => {
+      window.removeEventListener("keydown", onKey);
+      if (window.__otfwOpenSearch === openModal) delete window.__otfwOpenSearch;
+    };
+  });
+
+  // Portal to <body>: the navbar (our render parent) sets `backdrop-filter`, which
+  // establishes a containing block for fixed-position descendants — so without this the
+  // `position: fixed` overlay would collapse to the navbar's box instead of the viewport.
+  return (
+    <Portal>
+    <div
+      class={open ? "otfw-search-modal is-open" : "otfw-search-modal"}
+      onclick={(e) => {
+        if (e.target === e.currentTarget) close();
+      }}
+    >
+      <div class="otfw-search-panel" role="dialog" aria-label="Search docs">
+        <div class="otfw-search-field">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
+            <circle cx="11" cy="11" r="7" />
+            <line x1="21" y1="21" x2="16.65" y2="16.65" stroke-linecap="round" />
+          </svg>
+          <input
+            ref={inputRef}
+            class="otfw-search-input-field"
+            type="search"
+            placeholder="Search docs…"
+            aria-label="Search docs"
+            value={query}
+            oninput={(e) => (query = e.target.value)}
+          />
+        </div>
+        <ul class="otfw-search-results">
+          {results.map((r, i) => (
+            <li>
+              <a
+                href={r.url}
+                class={i === active ? "otfw-search-result is-active" : "otfw-search-result"}
+                onclick={(e) => {
+                  e.preventDefault();
+                  go(r.url);
+                }}
+                onmouseenter={() => (active = i)}
+              >
+                {r.crumb ? <span class="otfw-search-result-crumb">{r.crumb}</span> : null}
+                <span class="otfw-search-result-title">{r.title}</span>
+                {r.section ? <span class="otfw-search-result-section">{r.section}</span> : null}
+                <span class="otfw-search-result-excerpt">
+                  <RawHtml html={r.excerpt} />
+                </span>
+              </a>
+            </li>
+          ))}
+        </ul>
+        {query.trim() && !loading && results.length === 0 ? (
+          <div class="otfw-search-empty">No results for “{query}”.</div>
+        ) : null}
+        <div class="otfw-search-hint">
+          <span class="otfw-search-hint-item">
+            <kbd>↑</kbd>
+            <kbd>↓</kbd>
+            navigate
+          </span>
+          <span class="otfw-search-hint-item">
+            <kbd>↵</kbd>
+            select
+          </span>
+          <span class="otfw-search-hint-item">
+            <kbd>esc</kbd>
+            close
+          </span>
+        </div>
+      </div>
+    </div>
+    </Portal>
+  );
+}

package/components/SearchTrigger.jsx

@@ -1,7 +1,18 @@
-// Search box trigger in the navbar (⌘K). Inert in Phase 1 — it calls a global
-// opener that the Phase 2 Pagefind-backed <Search> modal installs on `window`.
+// Search box trigger in the navbar. Calls the global opener that the Pagefind-backed
+// <Search> modal installs on `window` (the ⌘K / Ctrl+K shortcut opens it too). Shows
+// the shortcut as a hint; the modifier resolves to ⌘ on Apple platforms, Ctrl
+// elsewhere, on mount.
+
+import { onMount } from "@opentf/web";
 
 export default function SearchTrigger() {
+  let mod = $state("Ctrl");
+
+  onMount(() => {
+    const ua = navigator.platform || navigator.userAgent || "";
+    if (/Mac|iPhone|iPad|iPod/.test(ua)) mod = "⌘";
+  });
+
   const open = () => {
     if (typeof window !== "undefined" && typeof window.__otfwOpenSearch === "function") {
       window.__otfwOpenSearch();
@@ -15,7 +26,7 @@ export default function SearchTrigger() {
         <line x1="21" y1="21" x2="16.65" y2="16.65" stroke-linecap="round" />
       </svg>
       <span class="otfw-search-label">Search</span>
-      <kbd class="otfw-search-kbd">⌘K</kbd>
+      <kbd class="otfw-search-kbd">{() => `${mod} K`}</kbd>
     </button>
   );
 }

package/components/Sidebar.jsx

@@ -1,21 +1,123 @@
 // Documentation sidebar — renders the build-time nav tree (from
 // `@opentf/web-docs/nav`). Static content (crawlable with JS off); the active link
 // updates reactively in SidebarNode.
+//
+// On desktop it is the sticky left column of the docs grid. On mobile (< 768px) the
+// same element becomes an off-canvas drawer: hidden off-screen, slid in over a
+// backdrop. The drawer is opened by the navbar hamburger, which lives in a different
+// component (and, on the website, a different layout), so the two are coupled the same
+// way Search/SearchTrigger are — through a global toggle installed here:
+//
+//   • `window.__otfwToggleSidebar()` / `__otfwCloseSidebar()` — called by the burger.
+//   • `document.documentElement[data-otfw-has-sidebar]` — set while a Sidebar is
+//     mounted, so the burger shows only on pages that actually have one.
+//   • a `otfw:sidebar` CustomEvent (`{ open }`) — lets the burger mirror `aria-expanded`.
+//
+// The drawer closes on navigation, Escape, backdrop click, or a viewport resize up to
+// the desktop breakpoint, and locks body scroll while open.
+
+import { onMount, router } from "@opentf/web";
 
 import SidebarNode from "./SidebarNode.jsx";
+import NavbarLink from "./NavbarLink.jsx";
+
+const DESKTOP_QUERY = "(min-width: 768px)";
+
+// How many Sidebars are mounted right now. On SPA navigation a new section's Sidebar can
+// mount *before* the old one unmounts, so the burger's `data-otfw-has-sidebar` flag must
+// be reference-counted — otherwise the departing instance's cleanup would clear the flag
+// the arriving instance just set, and the burger would vanish after navigating.
+let liveSidebars = 0;
 
 export default function Sidebar(props) {
   const nav = props.nav || [];
+  // Top-level site links (config.nav). On desktop they live in the navbar; on mobile the
+  // navbar hides them and the drawer surfaces them above the section tree, so the whole
+  // nav is reachable from one place.
+  const navLinks = (props.config && props.config.nav) || [];
+  let open = $state(false);
+
+  const close = () => (open = false);
+  // Stable per-instance toggle so cleanup can tell whether the global still points at us.
+  const toggle = () => (open = !open);
+
+  onMount(() => {
+    const root = document.documentElement;
+    liveSidebars += 1;
+    root.setAttribute("data-otfw-has-sidebar", "");
+
+    // The burger (navbar) drives the drawer through these globals — same decoupling as
+    // the Search modal's `__otfwOpenSearch`. The latest-mounted Sidebar owns them.
+    window.__otfwToggleSidebar = toggle;
+    window.__otfwCloseSidebar = close;
+
+    const onKey = (e) => e.key === "Escape" && close();
+    window.addEventListener("keydown", onKey);
+
+    // If the viewport grows to desktop while the drawer is open, drop the drawer state
+    // (CSS turns the element back into the sticky column; this releases the scroll lock
+    // and resyncs the burger).
+    const mql = window.matchMedia(DESKTOP_QUERY);
+    const onDesktop = (e) => e.matches && close();
+    mql.addEventListener?.("change", onDesktop);
+
+    return () => {
+      window.removeEventListener("keydown", onKey);
+      mql.removeEventListener?.("change", onDesktop);
+      document.body.style.removeProperty("overflow");
+      root.removeAttribute("data-otfw-sidebar-open");
+      // Only drop the flag/globals if we're the last Sidebar and still the owner — an
+      // arriving instance may already have taken over during navigation.
+      liveSidebars -= 1;
+      if (liveSidebars <= 0) {
+        liveSidebars = 0;
+        root.removeAttribute("data-otfw-has-sidebar");
+      }
+      if (window.__otfwToggleSidebar === toggle) delete window.__otfwToggleSidebar;
+      if (window.__otfwCloseSidebar === close) delete window.__otfwCloseSidebar;
+    };
+  });
+
+  // Reflect open state: lock body scroll, mark the root (for styling), and notify the
+  // burger so it can mirror `aria-expanded`. Reading `open` (not writing it) keeps this
+  // effect free of the route/resize effects.
+  $effect(() => {
+    const isOpen = open;
+    if (typeof document === "undefined") return;
+    document.documentElement.toggleAttribute("data-otfw-sidebar-open", isOpen);
+    document.body.style.overflow = isOpen ? "hidden" : "";
+    window.dispatchEvent(new CustomEvent("otfw:sidebar", { detail: { open: isOpen } }));
+  });
+
+  // Close on navigation — clicking a drawer link should dismiss it.
+  $effect(() => {
+    router.pathname; // subscribe
+    close();
+  });
 
   return (
-    <aside class="otfw-sidebar">
-      <nav class="otfw-sidebar-nav" aria-label="Documentation">
-        <ul class="otfw-sidebar-list">
-          {nav.map((item) => (
-            <SidebarNode item={item} />
-          ))}
-        </ul>
-      </nav>
-    </aside>
+    <div class="otfw-sidebar-shell">
+      <div
+        class={open ? "otfw-sidebar-backdrop is-open" : "otfw-sidebar-backdrop"}
+        onclick={close}
+        aria-hidden="true"
+      ></div>
+      <aside id="otfw-sidebar" class={open ? "otfw-sidebar is-open" : "otfw-sidebar"}>
+        {navLinks.length ? (
+          <nav class="otfw-drawer-links" aria-label="Site">
+            {navLinks.map((link) => (
+              <NavbarLink link={link} />
+            ))}
+          </nav>
+        ) : null}
+        <nav class="otfw-sidebar-nav" aria-label="Documentation">
+          <ul class="otfw-sidebar-list">
+            {nav.map((item) => (
+              <SidebarNode item={item} />
+            ))}
+          </ul>
+        </nav>
+      </aside>
+    </div>
   );
 }

package/components/SidebarNode.jsx

@@ -14,6 +14,7 @@ export default function SidebarNode(props) {
           href={item.path}
           class={router.pathname === item.path ? "otfw-sidebar-link otfw-active" : "otfw-sidebar-link"}
         >
+          <span class="otfw-sidebar-dot" aria-hidden="true"></span>
           {item.title}
         </Link>
       ) : (

package/components/SidebarToggle.jsx

@@ -0,0 +1,47 @@
+// Hamburger button in the navbar that opens the mobile sidebar drawer. Like
+// SearchTrigger, it is decoupled from the thing it controls: the <Sidebar> installs
+// `window.__otfwToggleSidebar` and emits an `otfw:sidebar` event, so this button works
+// even when the navbar and the sidebar live in different layouts (the website renders
+// the navbar at its root, the sidebar only inside the docs/api sections).
+//
+// The button is hidden by default and revealed by CSS only on small screens and only
+// while a Sidebar is mounted (`:root[data-otfw-has-sidebar]`), so it never shows on a
+// page without a drawer (e.g. the marketing home).
+
+import { onMount } from "@opentf/web";
+
+export default function SidebarToggle() {
+  let expanded = $state(false);
+
+  onMount(() => {
+    // Mirror the drawer's real state so aria-expanded stays correct however it was
+    // toggled (button, backdrop, Escape, navigation, resize).
+    const onState = (e) => (expanded = !!(e.detail && e.detail.open));
+    window.addEventListener("otfw:sidebar", onState);
+    return () => window.removeEventListener("otfw:sidebar", onState);
+  });
+
+  const toggle = () => window.__otfwToggleSidebar?.();
+
+  return (
+    <button
+      class="otfw-navbar-icon otfw-navbar-burger"
+      onclick={toggle}
+      aria-label="Toggle navigation"
+      aria-controls="otfw-sidebar"
+      aria-expanded={expanded ? "true" : "false"}
+    >
+      {() =>
+        expanded ? (
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+            <path d="M6 6l12 12M18 6L6 18" />
+          </svg>
+        ) : (
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+            <path d="M3 6h18M3 12h18M3 18h18" />
+          </svg>
+        )
+      }
+    </button>
+  );
+}

package/components/Steps.jsx

@@ -0,0 +1,14 @@
+// Numbered, vertically-connected steps for walkthroughs. Each child heading
+// (`<h3>`/`<h4>`) becomes a numbered step via a CSS counter, so it composes with
+// plain Markdown inside MDX:
+//
+//   <Steps>
+//   ### Install
+//   …
+//   ### Run the dev server
+//   …
+//   </Steps>
+
+export default function Steps(props) {
+  return <div class="otfw-steps">{props.children}</div>;
+}

package/components/Tabs.jsx

@@ -1,6 +1,8 @@
-// Generic tabbed panel. `tabs` is an array of `{ label, content }`.
+// Generic tabbed panel. `tabs` is an array of `{ label, content }`. `content` is
+// rendered as-is: a string is plain text, a node is the node. For a code panel with a
+// copy button, pass a `CodeBlock`: `{ label, content: <CodeBlock code="…" /> }`.
 //
-//   <Tabs tabs={[{ label: "npm", content: <…/> }, …]} />
+//   <Tabs tabs={[{ label: "npm", content: <CodeBlock code="npm i …" /> }, …]} />
 
 export default function Tabs(props) {
   let active = $state(0);

package/components/ThemeToggle.jsx

@@ -1,39 +1,164 @@
-// Light/dark toggle. Sets `data-theme` on <html>, persists to localStorage, and
-// respects the OS preference on first load. Pair with the no-flash inline script in
-// the docs shell index.html so the initial paint already has the right theme.
+// Theme switcher: a subtle ghost icon button that opens a Light / Dark / System menu.
+//
+// The chosen *mode* is persisted to localStorage("theme") as "light" | "dark" |
+// "system" (default "system"). The applied theme is the resolved value — in System
+// mode it follows the OS and live-updates when the OS preference flips. The trigger
+// shows the mode's icon; in System mode it shows the monitor icon plus a small badge of
+// the currently resolved icon (sun/moon), so you can see both the choice and the result.
+//
+// Pair with the no-flash inline script in index.html, which must resolve "system"/none
+// to a concrete theme on first paint.
 
 import { onMount } from "@opentf/web";
 
+import Tooltip from "./Tooltip.jsx";
+
+const STORAGE_KEY = "theme";
+const prefersDark = () =>
+  typeof window !== "undefined" && window.matchMedia("(prefers-color-scheme: dark)").matches;
+
 export default function ThemeToggle() {
-  let theme = $state("light");
+  let mode = $state("system"); // "light" | "dark" | "system"
+  let resolved = $state("light"); // "light" | "dark"
+  let openMenu = $state(false);
 
-  onMount(() => {
-    const saved =
-      localStorage.getItem("theme") ||
-      (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
-    theme = saved;
-    document.documentElement.setAttribute("data-theme", theme);
-  });
+  const rootRef = $ref();
 
-  const toggle = () => {
-    theme = theme === "light" ? "dark" : "light";
-    document.documentElement.setAttribute("data-theme", theme);
-    localStorage.setItem("theme", theme);
+  const resolve = (m) => (m === "system" ? (prefersDark() ? "dark" : "light") : m);
+
+  const apply = (m) => {
+    resolved = resolve(m);
+    if (typeof document !== "undefined") {
+      document.documentElement.setAttribute("data-theme", resolved);
+    }
+  };
+
+  const setMode = (m) => {
+    mode = m;
+    openMenu = false;
+    try {
+      localStorage.setItem(STORAGE_KEY, m);
+    } catch {}
+    apply(m);
   };
 
+  onMount(() => {
+    const saved = (() => {
+      try {
+        return localStorage.getItem(STORAGE_KEY);
+      } catch {
+        return null;
+      }
+    })();
+    mode = saved === "light" || saved === "dark" || saved === "system" ? saved : "system";
+    apply(mode);
+
+    // Follow the OS while in System mode.
+    const mql = window.matchMedia("(prefers-color-scheme: dark)");
+    const onOS = () => mode === "system" && apply("system");
+    mql.addEventListener?.("change", onOS);
+
+    // Close the menu on outside click / Escape.
+    const onDocClick = (e) => {
+      if (openMenu && rootRef && !rootRef.contains(e.target)) openMenu = false;
+    };
+    const onKey = (e) => e.key === "Escape" && (openMenu = false);
+    document.addEventListener("click", onDocClick);
+    document.addEventListener("keydown", onKey);
+
+    return () => {
+      mql.removeEventListener?.("change", onOS);
+      document.removeEventListener("click", onDocClick);
+      document.removeEventListener("keydown", onKey);
+    };
+  });
+
   return (
-    <button class="otfw-theme-toggle" onclick={toggle} aria-label="Toggle color theme">
+    <div class="otfw-theme" ref={rootRef}>
+      <Tooltip text="Change theme">
+        <button
+          class="otfw-navbar-icon otfw-theme-trigger"
+          onclick={(e) => {
+            e.stopPropagation();
+            openMenu = !openMenu;
+          }}
+          aria-label="Change theme"
+          aria-haspopup="menu"
+          aria-expanded={openMenu ? "true" : "false"}
+        >
+          {() =>
+            mode === "system" ? (
+              <span class="otfw-theme-trigger-system">
+                <MonitorIcon />
+                <span class="otfw-theme-trigger-badge">
+                  {resolved === "dark" ? <MoonIcon small /> : <SunIcon small />}
+                </span>
+              </span>
+            ) : mode === "dark" ? (
+              <MoonIcon />
+            ) : (
+              <SunIcon />
+            )
+          }
+        </button>
+      </Tooltip>
+
       {() =>
-        theme === "light" ? (
-          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-            <path stroke-linecap="round" stroke-linejoin="round" d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z" />
-          </svg>
-        ) : (
-          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-            <path stroke-linecap="round" stroke-linejoin="round" d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364-6.364l-.707.707M6.343 17.657l-.707.707m12.728 0l-.707-.707M6.343 6.343l-.707-.707M12 5a7 7 0 100 14 7 7 0 000-14z" />
-          </svg>
-        )
+        openMenu ? (
+          <div class="otfw-theme-menu" role="menu">
+            <MenuItem active={mode === "light"} onclick={() => setMode("light")}>
+              <SunIcon small /> Light
+            </MenuItem>
+            <MenuItem active={mode === "dark"} onclick={() => setMode("dark")}>
+              <MoonIcon small /> Dark
+            </MenuItem>
+            <MenuItem active={mode === "system"} onclick={() => setMode("system")}>
+              <MonitorIcon small /> System
+            </MenuItem>
+          </div>
+        ) : null
       }
+    </div>
+  );
+}
+
+function MenuItem(props) {
+  return (
+    <button
+      class={props.active ? "otfw-theme-item is-active" : "otfw-theme-item"}
+      role="menuitemradio"
+      aria-checked={props.active ? "true" : "false"}
+      onclick={props.onclick}
+    >
+      {props.children}
     </button>
   );
 }
+
+function SunIcon(props) {
+  const s = props.small ? 15 : 17;
+  return (
+    <svg width={s} height={s} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364-6.364l-.707.707M6.343 17.657l-.707.707m12.728 0l-.707-.707M6.343 6.343l-.707-.707M12 5a7 7 0 100 14 7 7 0 000-14z" />
+    </svg>
+  );
+}
+
+function MoonIcon(props) {
+  const s = props.small ? 15 : 17;
+  return (
+    <svg width={s} height={s} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z" />
+    </svg>
+  );
+}
+
+function MonitorIcon(props) {
+  const s = props.small ? 15 : 17;
+  return (
+    <svg width={s} height={s} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <rect x="2" y="3" width="20" height="14" rx="2" />
+      <path d="M8 21h8M12 17v4" />
+    </svg>
+  );
+}

package/components/Tooltip.jsx

@@ -0,0 +1,19 @@
+// A small hover/focus tooltip. CSS-driven (no JS state) — wrap any element and pass
+// `text`; the bubble shows on hover or keyboard focus of the wrapped content.
+//
+//   <Tooltip text="Change theme"><button>…</button></Tooltip>
+//
+// `placement` is "bottom" (default) or "top". The bubble is aria-hidden decorative
+// chrome; give the wrapped control its own `aria-label` for assistive tech.
+
+export default function Tooltip(props) {
+  const placement = props.placement === "top" ? "otfw-tooltip-top" : "otfw-tooltip-bottom";
+  return (
+    <span class={`otfw-tooltip ${placement}`}>
+      {props.children}
+      <span class="otfw-tooltip-bubble" role="tooltip" aria-hidden="true">
+        {props.text}
+      </span>
+    </span>
+  );
+}