@opentf/web-docs 0.1.0 → 0.3.0

package/components/PostCard.jsx

@@ -0,0 +1,19 @@
+// One post in the blog index: a link to the post with its meta + title + excerpt.
+import { Link } from "@opentf/web";
+import PostMeta from "./PostMeta.jsx";
+
+export default function PostCard(props) {
+  const post = props.post;
+  return (
+    <Link href={post.path} class={post.cover ? "otfw-post-card otfw-has-cover" : "otfw-post-card"}>
+      {post.cover ? (
+        <img class="otfw-post-card-cover" src={post.cover} alt={post.title} loading="lazy" />
+      ) : null}
+      <div class="otfw-post-card-body">
+        <PostMeta post={post} />
+        <div class="otfw-post-card-title">{post.title}</div>
+        {post.description ? <p class="otfw-post-card-desc">{post.description}</p> : null}
+      </div>
+    </Link>
+  );
+}

package/components/PostList.jsx

@@ -0,0 +1,17 @@
+// The blog index listing: renders a PostCard per post. Pass the list from
+// `@opentf/web-docs/posts`:
+//
+//   import { posts } from "@opentf/web-docs/posts";
+//   <PostList posts={posts} />
+import PostCard from "./PostCard.jsx";
+
+export default function PostList(props) {
+  const posts = props.posts || [];
+  return (
+    <div class="otfw-post-list">
+      {posts.length
+        ? posts.map((post) => <PostCard post={post} />)
+        : <p class="otfw-post-empty">No posts yet.</p>}
+    </div>
+  );
+}

package/components/PostMeta.jsx

@@ -0,0 +1,28 @@
+// A post's metadata row: date · author · reading time. Pass a post record (from
+// `@opentf/web-docs/posts`) as `post`, or the fields directly. Missing fields are
+// omitted. Used in both the post banner and the index cards.
+import ReadingTime from "./ReadingTime.jsx";
+import { formatDate } from "./format.js";
+
+export default function PostMeta(props) {
+  const post = props.post || props;
+  return (
+    <div class="otfw-post-meta">
+      {post.author ? (
+        <span class="otfw-post-author">
+          {post.authorAvatar ? (
+            <img class="otfw-post-avatar" src={post.authorAvatar} alt={post.author} loading="lazy" />
+          ) : null}
+          <span class="otfw-post-author-name">{post.author}</span>
+          {post.authorRole ? <span class="otfw-post-author-role">{post.authorRole}</span> : null}
+        </span>
+      ) : null}
+      {post.date ? (
+        <time class="otfw-post-date" datetime={String(post.date)}>
+          {formatDate(post.date)}
+        </time>
+      ) : null}
+      {post.readingTime ? <ReadingTime minutes={post.readingTime} /> : null}
+    </div>
+  );
+}

package/components/ReadingTime.jsx

@@ -0,0 +1,6 @@
+// Reading-time label, e.g. "4 min read". `minutes` is precomputed at build time by
+// the blog posts plugin (see build/reading-time.js).
+export default function ReadingTime(props) {
+  const minutes = props.minutes ?? 1;
+  return <span class="otfw-reading-time">{minutes} min read</span>;
+}

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);