@brett_lamy/docstream 0.1.0

package/src/gitbook/serialize.ts

@@ -0,0 +1,151 @@
+import type { Block, DocumentNode, Inline, ListItemNode } from "./ast"
+import { serializeInline } from "./inline"
+
+export function serializeMarkdown(doc: DocumentNode): string {
+  return serializeBlocks(doc.children).trimEnd() + "\n"
+}
+
+export function serializeBlocks(blocks: Block[]): string {
+  return blocks.map(serializeBlock).join("\n\n")
+}
+
+function indent(s: string, pad: string): string {
+  return s
+    .split("\n")
+    .map((l) => (l ? pad + l : l))
+    .join("\n")
+}
+
+function serializeBlock(b: Block): string {
+  switch (b.type) {
+    case "paragraph":
+      return serializeInline(b.children)
+
+    case "heading": {
+      const inline = serializeInline(b.children)
+      return inline ? `${"#".repeat(b.level)} ${inline}` : "#".repeat(b.level)
+    }
+
+    case "code": {
+      const fence = "```" + (b.language ?? "")
+      const body = `${fence}\n${b.code}\n\`\`\``
+      if (b.title || b.lineNumbers) {
+        const attrs = [
+          b.title ? ` title="${b.title}"` : "",
+          b.lineNumbers ? ` lineNumbers="true"` : "",
+        ].join("")
+        return `{% code${attrs} %}\n${body}\n{% endcode %}`
+      }
+      return body
+    }
+
+    case "hint":
+      return `{% hint style="${b.style}" %}\n${serializeBlocks(b.children)}\n{% endhint %}`
+
+    case "tabs":
+      return `{% tabs %}\n${b.tabs
+        .map((t) => `{% tab title="${t.title}" %}\n${serializeBlocks(t.children)}\n{% endtab %}`)
+        .join("\n\n")}\n{% endtabs %}`
+
+    case "expandable":
+      return `<details>\n\n<summary>${b.summary}</summary>\n\n${serializeBlocks(b.children)}\n\n</details>`
+
+    case "stepper":
+      return `{% stepper %}\n${b.steps
+        .map((s) => {
+          const title = s.title ? `### ${s.title}\n\n` : ""
+          return `{% step %}\n${title}${serializeBlocks(s.children)}\n{% endstep %}`
+        })
+        .join("\n\n")}\n{% endstepper %}`
+
+    case "embed":
+      return `{% embed url="${b.url}" %}`
+
+    case "content-ref":
+      return `{% content-ref url="${b.url}" %}\n${serializeInline(b.children)}\n{% endcontent-ref %}`
+
+    case "columns":
+      return `{% columns %}\n${b.columns
+        .map((c) => `{% column %}\n${serializeBlocks(c.children)}\n{% endcolumn %}`)
+        .join("\n\n")}\n{% endcolumns %}`
+
+    case "figure": {
+      const alt = b.alt ? ` alt="${b.alt}"` : ' alt=""'
+      const cap = b.caption ? `<figcaption><p>${b.caption}</p></figcaption>` : "<figcaption></figcaption>"
+      return `<figure><img src="${b.src}"${alt}>${cap}</figure>`
+    }
+
+    case "list":
+      return b.items.map((item, idx) => serializeListItem(item, b.ordered, b.task, idx)).join("\n")
+
+    case "blockquote":
+      return serializeBlocks(b.children)
+        .split("\n")
+        .map((l) => (l ? `> ${l}` : ">"))
+        .join("\n")
+
+    case "divider":
+      return "---"
+
+    case "table": {
+      if (b.view) {
+        const cellHtml = (c: Inline[]) => inlineToHtml(c)
+        const head = `<thead><tr>${b.header.map((c) => `<th>${cellHtml(c)}</th>`).join("")}</tr></thead>`
+        const body = `<tbody>${b.rows
+          .map((r) => `<tr>${r.map((c) => `<td>${cellHtml(c)}</td>`).join("")}</tr>`)
+          .join("")}</tbody>`
+        return `<table data-view="${b.view}">${head}${body}</table>`
+      }
+      const row = (cells: Inline[][]) => `| ${cells.map((c) => serializeInline(c)).join(" | ")} |`
+      const sep = `| ${b.header.map(() => "---").join(" | ")} |`
+      return [row(b.header), sep, ...b.rows.map(row)].join("\n")
+    }
+
+    case "math":
+      return `$$\n${b.formula}\n$$`
+
+    case "updates":
+      return `{% updates${b.format ? ` format="${b.format}"` : ""} %}\n${b.updates
+        .map(
+          (u) =>
+            `{% update date="${u.date}" %}\n${serializeBlocks(u.children)}\n{% endupdate %}`
+        )
+        .join("\n\n")}\n{% endupdates %}`
+
+    case "openapi-operation": {
+      const attrs = [
+        b.spec ? ` spec="${b.spec}"` : "",
+        b.path ? ` path="${b.path}"` : "",
+        b.method ? ` method="${b.method}"` : "",
+      ].join("")
+      const inner = b.specUrl ? `\n[${b.label || b.spec || "OpenAPI"}](${b.specUrl})` : ""
+      return `{% openapi-operation${attrs} %}${inner}\n{% endopenapi-operation %}`
+    }
+  }
+}
+
+function inlineToHtml(nodes: Inline[]): string {
+  return nodes
+    .map((n) => {
+      if (n.type === "image") {
+        const img = `<img src="${n.src}"${n.alt ? ` alt="${n.alt}"` : ""}>`
+        return n.link ? `<a href="${n.link}">${img}</a>` : img
+      }
+      let s = n.text
+      if (n.code) s = `<code>${s}</code>`
+      if (n.bold) s = `<strong>${s}</strong>`
+      if (n.italic) s = `<em>${s}</em>`
+      if (n.link) s = `<a href="${n.link}">${s}</a>`
+      return s
+    })
+    .join("")
+}
+
+function serializeListItem(item: ListItemNode, ordered: boolean, task: boolean, idx: number): string {
+  const bullet = ordered ? `${idx + 1}.` : "-"
+  const check = task ? `[${item.checked ? "x" : " "}] ` : ""
+  const [first, ...rest] = item.children
+  const firstText = first?.type === "paragraph" ? serializeInline(first.children) : first ? serializeBlock(first) : ""
+  const restText = rest.length ? "\n" + indent(serializeBlocks(rest), "  ") : ""
+  return `${bullet} ${check}${firstText}${restText}`
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { GitbookStreamdown } from "./streamdown"
+export type { GitbookStreamdownProps } from "./streamdown"
+export { DocsRenderer, MarkdownContent } from "./docs/DocsRenderer"
+export { OpenApiOperation } from "./openapi/OpenApiOperation"
+export { resolveAsset, setAssetBase } from "./assets"
+export { parseMarkdown, parseBlocks } from "./gitbook/parse"
+export { serializeBlocks, serializeMarkdown } from "./gitbook/serialize"
+export { parseInline, plainText, refDefinitions, serializeInline } from "./gitbook/inline"
+export { Streamdown } from "streamdown"
+export type { StreamdownProps } from "streamdown"
+export type * from "./gitbook/ast"

package/src/openapi/OpenApiOperation.tsx

@@ -0,0 +1,238 @@
+import { useEffect, useState } from "react"
+import { parse as parseYaml } from "yaml"
+
+import { MarkdownContent } from "../docs/DocsRenderer"
+import { HighlightedCode } from "../docs/HighlightedCode"
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+const specCache = new Map<string, Promise<any>>()
+
+function loadSpec(url: string): Promise<any> {
+  if (!specCache.has(url)) {
+    specCache.set(
+      url,
+      fetch(url)
+        .then((r) => {
+          if (!r.ok) throw new Error(`Failed to load spec (${r.status})`)
+          return r.text()
+        })
+        .then((text) => (text.trimStart().startsWith("{") ? JSON.parse(text) : parseYaml(text)))
+    )
+  }
+  return specCache.get(url)!
+}
+
+function resolveRef(spec: any, node: any): any {
+  if (node && typeof node === "object" && typeof node.$ref === "string") {
+    const parts = node.$ref.replace(/^#\//, "").split("/")
+    let cur = spec
+    for (const p of parts) cur = cur?.[p]
+    return resolveRef(spec, cur)
+  }
+  return node
+}
+
+function exampleFromSchema(spec: any, schema: any, depth = 0): any {
+  schema = resolveRef(spec, schema)
+  if (!schema || depth > 4) return null
+  if (schema.example !== undefined) return schema.example
+  if (schema.type === "array") return [exampleFromSchema(spec, schema.items, depth + 1)]
+  if (schema.type === "object" || schema.properties) {
+    const obj: Record<string, any> = {}
+    for (const [k, v] of Object.entries<any>(schema.properties ?? {})) {
+      obj[k] = exampleFromSchema(spec, v, depth + 1)
+    }
+    return obj
+  }
+  if (schema.enum?.length) return schema.enum[0]
+  switch (schema.type) {
+    case "integer":
+    case "number":
+      return 1
+    case "boolean":
+      return true
+    default:
+      return "string"
+  }
+}
+
+function SchemaFields({ spec, schema }: { spec: any; schema: any }) {
+  schema = resolveRef(spec, schema)
+  if (schema?.type === "array") schema = resolveRef(spec, schema.items)
+  const props = Object.entries<any>(schema?.properties ?? {})
+  if (!props.length) return null
+  const required: string[] = schema.required ?? []
+  return (
+    <div className="oas-fields">
+      {props.map(([name, raw]) => {
+        const p = resolveRef(spec, raw)
+        return (
+          <div key={name} className="oas-field">
+            <div>
+              <code className="oas-field-name">{name}</code>{" "}
+              <span className="oas-field-type">
+                {p.type ?? "object"}
+                {p.format ? ` · ${p.format}` : ""}
+              </span>{" "}
+              <span className={required.includes(name) ? "oas-required" : "oas-optional"}>
+                {required.includes(name) ? "required" : "optional"}
+              </span>
+            </div>
+            {p.description && <p className="oas-field-desc">{p.description}</p>}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+export function OpenApiOperation({
+  specUrl,
+  path,
+  method,
+}: {
+  specUrl: string
+  path: string
+  method: string
+}) {
+  const [spec, setSpec] = useState<any>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!specUrl) return
+    setSpec(null)
+    setError(null)
+    loadSpec(specUrl)
+      .then(setSpec)
+      .catch((e) => setError(String(e.message ?? e)))
+  }, [specUrl])
+
+  if (!specUrl) return <div className="oas oas-empty">Set an OpenAPI spec URL…</div>
+  if (error) return <div className="oas oas-empty">⚠︎ {error}</div>
+  if (!spec) return <div className="oas oas-empty">Loading OpenAPI spec…</div>
+
+  const op = spec.paths?.[path]?.[method.toLowerCase()]
+  if (!op) {
+    return (
+      <div className="oas oas-empty">
+        Operation {method.toUpperCase()} {path} not found in spec.
+      </div>
+    )
+  }
+
+  const server = spec.servers?.[0]?.url ?? ""
+  const security: any[] = op.security ?? spec.security ?? []
+  const schemes = Object.entries<any>(spec.components?.securitySchemes ?? {}).filter(([name]) =>
+    security.some((s) => name in s)
+  )
+  const responses = Object.entries<any>(op.responses ?? {})
+  const okResponse = responses.find(([code]) => code.startsWith("2"))?.[1]
+  const okSchema = okResponse?.content?.["application/json"]?.schema
+  const example = okSchema ? exampleFromSchema(spec, okSchema) : null
+
+  const curl = [
+    `curl -L ${server}${path} \\`,
+    ...(schemes.length ? [`  -H 'Authorization: Bearer YOUR_API_KEY'`] : []),
+  ].join("\n")
+
+  return (
+    <div className="oas">
+      <h3 className="oas-title">{op.summary ?? `${method.toUpperCase()} ${path}`}</h3>
+      <div className="oas-endpoint">
+        <span className={`oas-method oas-method-${method.toLowerCase()}`}>
+          {method.toUpperCase()}
+        </span>
+        {server && <span className="oas-server">{server}</span>}
+        <code className="oas-path">{path}</code>
+      </div>
+      {op.description && (
+        <div className="oas-desc">
+          <MarkdownContent markdown={op.description} />
+        </div>
+      )}
+
+      {schemes.length > 0 && (
+        <section className="oas-section">
+          <h4>Authorizations</h4>
+          {schemes.map(([name, s]) => (
+            <div key={name} className="oas-field">
+              <div>
+                <code className="oas-field-name">{s.name ?? "Authorization"}</code>{" "}
+                <span className="oas-field-type">{s.type}</span>{" "}
+                <span className="oas-required">required</span>
+              </div>
+              {s.description && <p className="oas-field-desc">{s.description}</p>}
+            </div>
+          ))}
+        </section>
+      )}
+
+      {(op.parameters?.length ?? 0) > 0 && (
+        <section className="oas-section">
+          <h4>Parameters</h4>
+          {op.parameters.map((raw: any, i: number) => {
+            const p = resolveRef(spec, raw)
+            return (
+              <div key={i} className="oas-field">
+                <div>
+                  <code className="oas-field-name">{p.name}</code>{" "}
+                  <span className="oas-field-type">
+                    {p.schema?.type ?? "string"} · {p.in}
+                  </span>{" "}
+                  <span className={p.required ? "oas-required" : "oas-optional"}>
+                    {p.required ? "required" : "optional"}
+                  </span>
+                </div>
+                {p.description && <p className="oas-field-desc">{p.description}</p>}
+              </div>
+            )
+          })}
+        </section>
+      )}
+
+      <section className="oas-section">
+        <h4>Responses</h4>
+        {responses.map(([code, raw]) => {
+          const r = resolveRef(spec, raw)
+          const schema = r.content?.["application/json"]?.schema
+          return (
+            <details key={code} className="oas-response" open={code.startsWith("2")}>
+              <summary>
+                <span className={`oas-code oas-code-${code[0]}`}>{code}</span>
+                <span>{r.description}</span>
+              </summary>
+              {schema && <SchemaFields spec={spec} schema={schema} />}
+            </details>
+          )
+        })}
+      </section>
+
+      <section className="oas-section oas-samples">
+        <div className="oas-sample">
+          <div className="oas-sample-head">
+            <span className={`oas-method oas-method-${method.toLowerCase()}`}>
+              {method.toUpperCase()}
+            </span>
+            <code>{path}</code>
+            <span className="oas-sample-label">cURL</span>
+          </div>
+          <pre>
+            <HighlightedCode code={curl} language="bash" />
+          </pre>
+        </div>
+        {example !== null && (
+          <div className="oas-sample">
+            <div className="oas-sample-head">
+              <span className="oas-code oas-code-2">200</span>
+              <span>{okResponse?.description}</span>
+            </div>
+            <pre>
+              <HighlightedCode code={JSON.stringify(example, null, 2)} language="json" />
+            </pre>
+          </div>
+        )}
+      </section>
+    </div>
+  )
+}

package/src/streamdown.tsx

@@ -0,0 +1,33 @@
+import { useMemo } from "react"
+import { DocsRenderer } from "./docs/DocsRenderer"
+import { parseMarkdown } from "./gitbook/parse"
+
+export interface GitbookStreamdownProps {
+  children?: string
+  className?: string
+  isAnimating?: boolean
+  isStreaming?: boolean
+  markdown?: string
+}
+
+export function GitbookStreamdown({
+  children,
+  className,
+  isAnimating,
+  isStreaming = false,
+  markdown,
+}: GitbookStreamdownProps) {
+  const content = markdown ?? children ?? ""
+  const gitbookDoc = useMemo(() => parseMarkdown(content), [content])
+
+  return (
+    <div
+      aria-busy={isAnimating ?? isStreaming}
+      className={className}
+      data-docstream=""
+      data-streaming={isStreaming ? "" : undefined}
+    >
+      <DocsRenderer doc={gitbookDoc} />
+    </div>
+  )
+}