@opentf/web-docs 0.1.0

package/components/Toc.jsx

@@ -0,0 +1,70 @@
+// "On this page" table of contents. Built from the rendered content headings (so it
+// works for both MDX and JSX pages), with scroll-spy highlighting via
+// IntersectionObserver. Rebuilds on route change.
+//
+// The MDX front-end already emits stable heading ids (slugs); we read them from the
+// DOM after mount. (SSG output ships the heading anchors statically; this nav chrome
+// activates once the client bundle mounts.)
+
+import { onMount, router } from "@opentf/web";
+
+export default function Toc() {
+  let items = $state([]);
+  let activeId = $state("");
+  let observer = null;
+
+  const build = () => {
+    if (typeof document === "undefined") return;
+    const root = document.getElementById("otfw-content");
+    if (!root) return;
+    const hs = Array.from(root.querySelectorAll("h2[id], h3[id]"));
+    items = hs.map((h) => ({
+      id: h.id,
+      text: h.textContent || "",
+      sub: h.tagName === "H3",
+    }));
+    if (observer) observer.disconnect();
+    observer = new IntersectionObserver(
+      (entries) => {
+        for (const e of entries) if (e.isIntersecting) activeId = e.target.id;
+      },
+      { rootMargin: "-10% 0px -80% 0px", threshold: 0 },
+    );
+    for (const h of hs) observer.observe(h);
+  };
+
+  onMount(() => {
+    build();
+    return () => observer && observer.disconnect();
+  });
+
+  // Rebuild when the route changes (content swaps under the same layout).
+  $effect(() => {
+    router.pathname;
+    if (typeof requestAnimationFrame !== "undefined") requestAnimationFrame(build);
+  });
+
+  return (
+    <nav class="otfw-toc" aria-label="On this page">
+      {() =>
+        items.length > 0 ? (
+          <div class="otfw-toc-inner">
+            <div class="otfw-toc-heading">On this page</div>
+            <ul class="otfw-toc-list">
+              {items.map((h) => (
+                <li class={h.sub ? "otfw-toc-item otfw-toc-sub" : "otfw-toc-item"}>
+                  <a
+                    href={"#" + h.id}
+                    class={activeId === h.id ? "otfw-toc-link otfw-active" : "otfw-toc-link"}
+                  >
+                    {h.text}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ) : null
+      }
+    </nav>
+  );
+}

package/config.js

@@ -0,0 +1,42 @@
+// Site/docs configuration helper.
+//
+// `defineDocsConfig` is an identity function: it returns the config untouched, but
+// gives authors editor type-hints (via the JSDoc typedef) and a stable import the
+// toolchain can recognise. Used in `otfw.config.js`:
+//
+//   import { defineDocsConfig } from "@opentf/web-docs/config";
+//   export default defineDocsConfig({ site: { url }, docs: { … } });
+
+/**
+ * @typedef {Object} DocsNavLink
+ * @property {string} label
+ * @property {string} href
+ *
+ * @typedef {Object} DocsFooter
+ * @property {string} [text]
+ * @property {DocsNavLink[]} [links]
+ *
+ * @typedef {Object} DocsConfig
+ * @property {string} [title]        Site/product name shown in the navbar.
+ * @property {string} [logo]         URL of the navbar logo image.
+ * @property {string} [homeUrl]      Where the navbar brand links to (default "/").
+ * @property {string} [github]       GitHub URL (shown in the navbar).
+ * @property {string} [dir]          Docs content folder under app/ (default "docs").
+ * @property {DocsNavLink[]} [nav]   Top-level navbar links.
+ * @property {DocsFooter} [footer]   Footer content.
+ * @property {{ provider?: string }} [search]  Search provider (Phase 2: "pagefind").
+ *
+ * @typedef {Object} SiteConfig
+ * @property {{ url?: string }} [site]   Canonical site origin (for SEO / sitemap).
+ * @property {DocsConfig} [docs]         Documentation generator config.
+ */
+
+/**
+ * @param {SiteConfig} config
+ * @returns {SiteConfig}
+ */
+export function defineDocsConfig(config) {
+  return config;
+}
+
+export default defineDocsConfig;

package/index.js

@@ -0,0 +1,38 @@
+// Public barrel for @opentf/web-docs.
+//
+// Components are shipped as JSX source and compiled by the consuming app's pipeline
+// (the `@opentf/web` Link.jsx model) — each becomes a `web-*` Custom Element with
+// CSR + SSG renderers for free. otfwc compiles JSX tags to element *strings*
+// (`web-callout`), so the JS import of a component would be tree-shaken; the bare
+// `import "./components/X.jsx"` retains its `customElements.define` side effect
+// (the compiled modules are marked side-effectful), and the re-export lets authors
+// pull a component in by name (`import { Callout } from "@opentf/web-docs"`).
+
+import "./components/DocsLayout.jsx";
+import "./components/Navbar.jsx";
+import "./components/Sidebar.jsx";
+import "./components/SidebarNode.jsx";
+import "./components/Toc.jsx";
+import "./components/Footer.jsx";
+import "./components/Breadcrumbs.jsx";
+import "./components/Pagination.jsx";
+import "./components/ThemeToggle.jsx";
+import "./components/SearchTrigger.jsx";
+import "./components/Callout.jsx";
+import "./components/Tabs.jsx";
+import "./components/CodeGroup.jsx";
+import "./components/Table.jsx";
+
+export { default as DocsLayout } from "./components/DocsLayout.jsx";
+export { default as Navbar } from "./components/Navbar.jsx";
+export { default as Sidebar } from "./components/Sidebar.jsx";
+export { default as Toc } from "./components/Toc.jsx";
+export { default as Footer } from "./components/Footer.jsx";
+export { default as Breadcrumbs } from "./components/Breadcrumbs.jsx";
+export { default as Pagination } from "./components/Pagination.jsx";
+export { default as ThemeToggle } from "./components/ThemeToggle.jsx";
+export { default as SearchTrigger } from "./components/SearchTrigger.jsx";
+export { default as Callout } from "./components/Callout.jsx";
+export { default as Tabs } from "./components/Tabs.jsx";
+export { default as CodeGroup } from "./components/CodeGroup.jsx";
+export { default as Table } from "./components/Table.jsx";

package/nav-virtual.js

@@ -0,0 +1,16 @@
+// Fallback for `@opentf/web-docs/nav`.
+//
+// When `docsNavPlugin` is active (the toolchain registers it whenever the project
+// has a `docs` config), it intercepts this specifier and replaces it with a
+// build-time-generated module exporting the real navigation tree. This file is only
+// loaded when the plugin is NOT active (e.g. an editor, or a non-docs build), in
+// which case the nav is simply empty.
+
+if (typeof console !== "undefined") {
+  console.warn(
+    "[@opentf/web-docs] navigation requested but docsNavPlugin is not active — " +
+      "did you add a `docs` block to otfw.config.js? Returning an empty nav.",
+  );
+}
+
+export default [];

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@opentf/web-docs",
+  "version": "0.1.0",
+  "description": "Documentation-site generator for OTF Web — themed shell components (sidebar, TOC, callouts, tabs), a build-time nav generator, and a default light/dark theme.",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./theme": "./theme/index.css",
+    "./config": "./config.js",
+    "./nav": "./nav-virtual.js",
+    "./build": "./build/index.js"
+  },
+  "files": [
+    "index.js",
+    "config.js",
+    "nav-virtual.js",
+    "components",
+    "theme",
+    "build",
+    "!**/*.test.js"
+  ],
+  "keywords": [
+    "opentf",
+    "documentation",
+    "docs",
+    "mdx",
+    "static-site-generator",
+    "ssg"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Open-Tech-Foundation/Web-App-Framework.git",
+    "directory": "packages/web-docs"
+  },
+  "homepage": "https://github.com/Open-Tech-Foundation/Web-App-Framework#readme",
+  "bugs": "https://github.com/Open-Tech-Foundation/Web-App-Framework/issues",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opentf/web": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}