@brett_lamy/docstream 1.19.1 → 1.20.0

package/src/site/DocsSite.tsx

@@ -24,6 +24,7 @@ import {
 import { ArrowLeft, ArrowRight, ChevronRight, FileText, Hash, Menu, Moon, PencilLine, Search, Sun, X } from "lucide-react"
 
 import { AssetResolverContext, AssetResolverProvider, type AssetResolver } from "../asset-resolver"
+import { envNamesFromProperties } from "../doc-env"
 import { MarkdownContent, type DocRenderOptions, type LivePreviewRenderer, type SourceReferenceRenderer } from "../docs/DocsRenderer"
 import { DocPageActions, type DocPageActionsOptions } from "../docs/PageActions"
 import { documentOutline, type OutlineEntry } from "../gitbook/outline"
@@ -40,6 +41,44 @@ export interface DocsSiteLink {
   icon?: ReactNode
 }
 
+/** A section of the site in the header, like GitBook's spaces: the sidebar shows only its pages. */
+export interface DocsSiteTab {
+  title: string
+  /** Slug prefix of its pages: `"blocks"` takes `blocks` and `blocks/…`. `""` takes every page no other tab claims. */
+  path: string
+  /** Where the tab goes. Default: the first of its pages in reading order. */
+  slug?: string
+}
+
+const trimPath = (p: string) => p.replace(/^\/+|\/+$/g, "")
+
+/** The tab a page belongs to: the longest `path` that prefixes its slug, else the catch-all (`""`) tab. */
+export function tabForSlug(tabs: readonly DocsSiteTab[], slug: string): DocsSiteTab | undefined {
+  let best: DocsSiteTab | undefined
+  for (const t of tabs) {
+    const p = trimPath(t.path)
+    if (p && (slug === p || slug.startsWith(`${p}/`)) && (!best || p.length > trimPath(best.path).length)) best = t
+  }
+  return best ?? tabs.find((t) => !trimPath(t.path))
+}
+
+/** The sidebar items whose pages belong to `tab` (groups and folders keep only those; empty ones go). */
+function navForTab(items: DocsNavItem[], tabs: readonly DocsSiteTab[], tab: DocsSiteTab): DocsNavItem[] {
+  const out: DocsNavItem[] = []
+  for (const item of items) {
+    if (item.kind === "link") {
+      if (tab === tabs.find((t) => !trimPath(t.path))) out.push(item)
+      continue
+    }
+    const children = navForTab(item.children, tabs, tab)
+    if (item.kind === "page") {
+      if (tabForSlug(tabs, item.slug) === tab) out.push({ ...item, children })
+      else out.push(...children)
+    } else if (children.length) out.push({ ...item, children })
+  }
+  return out
+}
+
 export interface DocsSiteProps extends Omit<DocRenderOptions, "pageActions"> {
   /** The files to publish: `{ path: content }` or `[{ path, content }]`. Only Markdown is kept. */
   files?: DocsFiles
@@ -52,6 +91,11 @@ export interface DocsSiteProps extends Omit<DocRenderOptions, "pageActions"> {
   logo?: ReactNode
   /** Header links (GitHub, npm, …). */
   links?: DocsSiteLink[]
+  /**
+   * Sections in the header (`[{ title: "Components", path: "" }, { title: "Blocks", path: "blocks" }]`): each owns the
+   * pages under its `path`, the sidebar and Previous / Next stay inside the current one, and search covers them all.
+   */
+  tabs?: DocsSiteTab[]
   /** `"hash"` (default): `#/guides/install`. `"history"`: real paths under `basePath`. `"memory"`: no URL. */
   routing?: DocsSiteRouting
   /** URL prefix for `routing="history"` (e.g. `"/docs"`). */
@@ -549,6 +593,7 @@ export function DocsSite(props: DocsSiteProps) {
     title,
     logo,
     links = [],
+    tabs,
     routing = "hash",
     basePath = "",
     initialPath,
@@ -573,6 +618,7 @@ export function DocsSite(props: DocsSiteProps) {
     demoVFS,
     onTaskStateChange,
     documentProperties,
+    envHost,
     className,
     style,
   } = props
@@ -699,9 +745,11 @@ export function DocsSite(props: DocsSiteProps) {
     go(a.dataset.dsSlug ?? "", a.dataset.dsHash ?? "")
   }
 
-  const index = shown ? tree.order.indexOf(shown) : -1
-  const prev = index > 0 ? tree.order[index - 1] : undefined
-  const next = index >= 0 ? tree.order[index + 1] : undefined
+  const activeTab = tabs?.length ? tabForSlug(tabs, shown?.slug ?? location.slug) : undefined
+  const order = activeTab ? tree.order.filter((p) => tabForSlug(tabs!, p.slug) === activeTab) : tree.order
+  const index = shown ? order.indexOf(shown) : -1
+  const prev = index > 0 ? order[index - 1] : undefined
+  const next = index >= 0 ? order[index + 1] : undefined
 
   const actions = shown ? (typeof pageActions === "function" ? pageActions(shown) : pageActions) : false
   const pageMarkdown = shown ? `# ${shown.title}\n\n${shown.description ? `${shown.description}\n\n` : ""}${shown.body}` : ""
@@ -720,6 +768,8 @@ export function DocsSite(props: DocsSiteProps) {
         demoVFS={demoVFS}
         onTaskStateChange={onTaskStateChange}
         documentProperties={documentProperties}
+        envHost={envHost}
+        env={envNamesFromProperties(shown.frontmatter)}
       />
     </AssetResolverProvider>
   ) : null
@@ -744,7 +794,28 @@ export function DocsSite(props: DocsSiteProps) {
       {title ? <span className="ds-site-title">{title}</span> : null}
     </a>
   )
-  const navTree = <NavList items={tree.nav} current={shown?.slug ?? location.slug} href={(s) => href(s)} go={(s) => go(s)} />
+  const navItems = activeTab ? navForTab(tree.nav, tabs!, activeTab) : tree.nav
+  const navTree = <NavList items={navItems} current={shown?.slug ?? location.slug} href={(s) => href(s)} go={(s) => go(s)} />
+  const tabTarget = (t: DocsSiteTab) => t.slug ?? tree.order.find((p) => tabForSlug(tabs!, p.slug) === t)?.slug ?? trimPath(t.path)
+  const tabBar = (where: "header" | "drawer") => tabs?.length ? (
+    <nav className={`ds-site-tabs ds-site-tabs-${where}`} aria-label="Sections">
+      {tabs.map((t) => (
+        <a
+          key={t.title}
+          className="ds-site-tab"
+          href={href(tabTarget(t))}
+          aria-current={t === activeTab ? "page" : undefined}
+          onClick={(e) => {
+            if (!plainClick(e)) return
+            e.preventDefault()
+            go(tabTarget(t))
+          }}
+        >
+          {t.title}
+        </a>
+      ))}
+    </nav>
+  ) : null
 
   return (
     <div
@@ -760,6 +831,7 @@ export function DocsSite(props: DocsSiteProps) {
           <Menu size={18} aria-hidden="true" />
         </button>
         {brand}
+        {tabBar("header")}
         <div className="ds-site-header-spacer" />
         {search ? (
           <button type="button" className="ds-site-search-btn" onClick={() => setSearchOpen(true)} aria-label="Search documentation" aria-keyshortcuts="Meta+K Control+K">
@@ -792,7 +864,8 @@ export function DocsSite(props: DocsSiteProps) {
         </nav>
 
         <div className="ds-site-scroll" ref={scrollerRef}>
-          <div className="ds-site-columns">
+          {/* Frontmatter `layout: wide` widens the column (galleries, full-width demos) and drops the outline. */}
+          <div className="ds-site-columns" data-layout={shown?.frontmatter.layout === "wide" ? "wide" : undefined}>
             <main className="ds-site-main" ref={articleRef} onClick={onArticleClick}>
               {shown ? (
                 <article className="ds-site-article">
@@ -937,6 +1010,7 @@ export function DocsSite(props: DocsSiteProps) {
                 <X size={18} aria-hidden="true" />
               </button>
             </div>
+            {tabBar("drawer")}
             <div className="ds-site-sidebar-scroll">{navTree}</div>
             {sidebarFooter ? <div className="ds-site-sidebar-foot">{sidebarFooter}</div> : null}
           </nav>

package/src/site/index.ts

@@ -1,6 +1,6 @@
 // A GitBook-style docs site from a folder of Markdown files. Root-entry safe: no almost-node.
-export { DocsSite } from "./DocsSite"
-export type { DocsSiteLink, DocsSiteProps, DocsSiteRouting, DocsSiteTheme } from "./DocsSite"
+export { DocsSite, tabForSlug } from "./DocsSite"
+export type { DocsSiteLink, DocsSiteProps, DocsSiteRouting, DocsSiteTab, DocsSiteTheme } from "./DocsSite"
 export {
   SITE_FRONTMATTER_KEYS,
   buildDocsTree,

package/src/site/site.css

@@ -206,6 +206,61 @@
   color: var(--ds-site-fg);
 }
 
+/* Header tabs: the site's sections (`tabs`). In the drawer they sit above the navigation. */
+.ds-site .ds-site-tabs {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  min-width: 0;
+}
+
+.ds-site .ds-site-tabs-header {
+  margin-left: 18px;
+  align-self: stretch;
+}
+
+.ds-site .ds-site-tab {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  padding: 6px 10px;
+  border-radius: 8px;
+  color: var(--ds-site-muted);
+  font-size: 13.5px;
+  font-weight: 600;
+  text-decoration: none;
+  white-space: nowrap;
+}
+
+.ds-site .ds-site-tab:hover {
+  background: var(--ds-site-hover);
+  color: var(--ds-site-fg);
+}
+
+.ds-site .ds-site-tab[aria-current="page"] {
+  color: var(--ds-site-fg);
+}
+
+.ds-site .ds-site-tabs-header .ds-site-tab[aria-current="page"]::after {
+  content: "";
+  position: absolute;
+  right: 10px;
+  bottom: calc((var(--ds-site-header-h) - 31px) / -2);
+  left: 10px;
+  height: 2px;
+  border-radius: 2px;
+  background: var(--primary);
+}
+
+.ds-site .ds-site-tabs-drawer {
+  padding: 4px 12px 8px;
+  border-bottom: 1px solid var(--ds-site-border);
+}
+
+.ds-site .ds-site-tabs-drawer .ds-site-tab[aria-current="page"] {
+  background: var(--ds-site-hover);
+}
+
 /* Body: sidebar | scroller (article + outline) */
 .ds-site .ds-site-body {
   display: flex;
@@ -381,6 +436,14 @@
   max-width: var(--ds-site-content-w);
 }
 
+.ds-site .ds-site-columns[data-layout="wide"] .ds-site-main {
+  max-width: var(--ds-site-wide-w, 1240px);
+}
+
+.ds-site .ds-site-columns[data-layout="wide"] .ds-site-toc {
+  display: none;
+}
+
 .ds-site .ds-site-article {
   padding: 36px 0 72px;
 }
@@ -773,6 +836,10 @@
     display: inline-grid;
   }
 
+  .ds-site .ds-site-tabs-header {
+    display: none;
+  }
+
   .ds-site .ds-site-header {
     padding: 0 12px;
   }

package/src/site/tree.ts

@@ -10,7 +10,8 @@
      and titles. Frontmatter `order` overrides the prefix.
    - A page's title is, in order: its SUMMARY.md label, frontmatter `title`, its first
      `# heading`, then the file name (`quick-start.md` → "Quick start"). Frontmatter
-     `description` is its lede and `hidden: true` keeps it out of the sidebar.
+     `description` is its lede, `hidden: true` keeps it out of the sidebar and `layout: wide`
+     gives it the full width.
    - Every other file in the docs root is an asset (`tree.assets`): DocsSite serves it to the
      pages, so `![logo](images/logo.svg)` or an OpenAPI block's `[api](specs/api.json)` loads
      the file from the VFS.
@@ -72,7 +73,7 @@ export interface BuildDocsTreeOptions {
 }
 
 /** Frontmatter keys that describe the page to the site rather than the reader. */
-export const SITE_FRONTMATTER_KEYS = ["title", "description", "order", "hidden", "icon"] as const
+export const SITE_FRONTMATTER_KEYS = ["title", "description", "order", "hidden", "icon", "env", "layout"] as const
 
 const MARKDOWN = /\.(md|markdown|mdx)$/i
 const INDEX = /^(readme|index)$/i

package/src/streamdown.tsx

@@ -37,6 +37,8 @@ export function GitbookStreamdown({
   pageActions,
   documentProperties,
   onTaskStateChange,
+  envHost,
+  env,
 }: GitbookStreamdownProps) {
   const content = markdown ?? children ?? ""
   const gitbookDoc = useMemo(
@@ -63,6 +65,8 @@ export function GitbookStreamdown({
         pageActions={isStreaming ? false : pageActions}
         documentProperties={documentProperties}
         onTaskStateChange={onTaskStateChange}
+        envHost={envHost}
+        env={env}
       />
     </div>
   )

package/src/styles.css

@@ -3214,6 +3214,95 @@
   line-height: 1.5;
 }
 
+/* An example waiting for the page's env variables (frontmatter `env`). */
+.docs-demo-canvas-env {
+  display: grid;
+  place-items: center;
+  padding: 20px 14px;
+}
+.docs-env-gate {
+  display: grid;
+  gap: 10px;
+  width: min(100%, 420px);
+  padding: 14px 16px;
+  border: 1px solid var(--gb-border);
+  border-radius: 10px;
+  background: var(--gb-background);
+  color: var(--gb-foreground);
+  font-size: 13.5px;
+  line-height: 1.45;
+}
+.docs-env-gate-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+}
+.docs-env-gate-icon {
+  display: inline-grid;
+  place-items: center;
+  width: 26px;
+  height: 26px;
+  border-radius: 50%;
+  background: color-mix(in oklab, var(--gb-primary) 14%, transparent);
+  color: var(--gb-primary);
+  flex: none;
+}
+.docs-env-gate-list {
+  display: grid;
+  gap: 4px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.docs-env-gate-list li {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 12px;
+}
+.docs-env-gate-list span,
+.docs-env-gate-note {
+  color: var(--gb-muted-foreground);
+  font-size: 12.5px;
+}
+.docs-env-gate-form {
+  display: grid;
+  gap: 8px;
+}
+.docs-env-gate-form label {
+  display: grid;
+  gap: 4px;
+}
+.docs-env-gate-form input {
+  font: inherit;
+  padding: 6px 8px;
+  border: 1px solid var(--gb-border);
+  border-radius: 6px;
+  background: transparent;
+  color: inherit;
+}
+.docs-env-gate-button {
+  justify-self: start;
+  font: inherit;
+  font-weight: 600;
+  padding: 6px 14px;
+  border: 0;
+  border-radius: 999px;
+  background: var(--gb-primary);
+  color: var(--gb-primary-foreground, #fff);
+  cursor: pointer;
+}
+.docs-env-gate-button:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+.docs-env-gate-error {
+  margin: 0;
+  color: var(--gb-destructive, #d93025);
+  font-size: 12.5px;
+}
+
 .docs-demo-loading {
   display: grid;
   place-items: center;