@brett_lamy/docstream 0.6.3 → 0.7.0

package/README.md

@@ -311,6 +311,25 @@ The package CSS is intentionally token-driven. It uses normal CSS variables and
 
 Import the CSS once, then set tokens globally in your app. Components also expose stable classes such as `docs-code`, `docs-tabs`, `docs-hint`, `docs-table`, and `docs-openapi`.
 
+Code highlighting follows the surrounding `color-scheme`: set `color-scheme: dark` on a dark page (or any dark container) and code switches to the dark palette. Each token color is a custom property (`--docs-tok-keyword`, `--docs-tok-string`, `--docs-tok-type`, `--docs-tok-function`, `--docs-tok-number`, `--docs-tok-constant`, `--docs-tok-operator`, `--docs-tok-comment`) if you want your own palette.
+
+### Live demos with in-page components
+
+`ReactDemo` from `@brett_lamy/docstream/playground` boots an almost-node Vite server for self-contained projects. When the components already run on your page, pass `preview` instead: you keep the same frame, header, and collapsible code panel without a runtime.
+
+```tsx
+import { ReactDemo } from "@brett_lamy/docstream/playground"
+
+<ReactDemo
+  title="Counter"
+  status={false}
+  preview={<Counter />}
+  height="auto"
+  code={`import { Counter } from "my-ui"\n\nexport default () => <Counter />`}
+  language="tsx"
+/>
+```
+
 ## Bundler Notes
 
 This release ships TypeScript and TSX source through ESM exports:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "publishConfig": {
     "access": "public"

package/src/docs/HighlightedCode.tsx

@@ -7,10 +7,8 @@ type Span = {
   end: number
 }
 
-const COLORS: Record<Span["type"], string | undefined> = {
-  plain: undefined, comment: "#6B6B78", string: "#A5D6A7", number: "#F78C6C",
-  keyword: "#C792EA", type: "#FFCB6B", function: "#82AAFF", constant: "#F07178", operator: "#89DDFF",
-}
+/* Token colors live in styles.css (`.docs-tok-*`) and follow the host's color-scheme, so code reads on
+   light and dark backgrounds alike. Hosts can retheme via the --docs-tok-* custom properties. */
 
 function escapeHtml(value: string) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\"/g, "&quot;")
@@ -22,8 +20,7 @@ function spansToHtml(code: string, spans: Span[]) {
     const prefix = escapeHtml(code.slice(cursor, span.start))
     const text = escapeHtml(code.slice(span.start, span.end))
     cursor = span.end
-    const color = COLORS[span.type]
-    return `${prefix}${color ? `<span style="color:${color}">${text}</span>` : text}`
+    return `${prefix}${span.type === "plain" ? text : `<span class="docs-tok docs-tok-${span.type}">${text}</span>`}`
   }).join("") + escapeHtml(code.slice(cursor))
 }
 

package/src/playground/ReactCodePreview.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useId, useMemo, useState, type CSSProperties } from "react"
+import { useEffect, useId, useMemo, useState, type CSSProperties, type ReactNode } from "react"
 import { HighlightedCode } from "../docs/HighlightedCode"
 import {
   createAlmostNodeWorkspace,
@@ -11,8 +11,21 @@ import {
 } from "./filesystem"
 
 export interface ReactDemoProps {
-  /** Complete project file map. Relative paths are rooted at `/`. */
-  files: AlmostNodeFiles
+  /** Complete project file map. Relative paths are rooted at `/`. Not needed when `preview` is given. */
+  files?: AlmostNodeFiles
+  /**
+   * Render this in place of the almost-node iframe — for hosts that can mount the demo directly
+   * (components already on the page). No runtime starts; the frame, header, and code panel stay the same.
+   */
+  preview?: ReactNode
+  /** Source text for the code panel. Overrides reading `codeFile` from `files`. */
+  code?: string
+  /** Highlighting language for `code` (e.g. "tsx"). Defaults to the extension of `codeFile`. */
+  language?: string
+  /** Header status. Defaults to the runtime state ("ready", "starting"…); pass `false` to hide it. */
+  status?: ReactNode | false
+  /** Extra header content after the status, e.g. controls that switch between demo variants. */
+  actions?: ReactNode
   /** Vite entry file. Defaults to `/src/main.jsx`. */
   entry?: string
   /** Preferred virtual port. almost-node picks the next free port if needed. */
@@ -71,8 +84,15 @@ function sourceText(files: AlmostNodeFiles, requestedPath: string): string | nul
 }
 
 /** Render a multi-file React/JSX/TSX project through almost-node's Vite server. */
+const NO_FILES: AlmostNodeFiles = {}
+
 export function ReactDemo({
-  files,
+  files = NO_FILES,
+  preview,
+  code: codeProp,
+  language,
+  status,
+  actions,
   entry = "/src/main.jsx",
   port = 4173,
   height = 360,
@@ -87,16 +107,17 @@ export function ReactDemo({
   onReady,
   onError,
 }: ReactDemoProps) {
-  const [run, setRun] = useState(autoStart ? 1 : 0)
-  const [state, setState] = useState<PreviewState>(autoStart ? "starting" : "idle")
+  const inline = preview !== undefined
+  const [run, setRun] = useState(autoStart && !inline ? 1 : 0)
+  const [state, setState] = useState<PreviewState>(inline ? "ready" : autoStart ? "starting" : "idle")
   const [url, setUrl] = useState<string | null>(null)
   const [error, setError] = useState<string | null>(null)
   const [codeExpanded, setCodeExpanded] = useState(false)
   const codePanelId = useId()
   const displayedCodeFile = codeFile ?? entry
   const code = useMemo(
-    () => sourceText(files, displayedCodeFile),
-    [displayedCodeFile, files],
+    () => codeProp ?? sourceText(files, displayedCodeFile),
+    [codeProp, displayedCodeFile, files],
   )
   const collapsedLines = positiveLineCount(collapsedCodeLines, 3)
   const expandedLines = Math.max(
@@ -105,6 +126,7 @@ export function ReactDemo({
   )
 
   useEffect(() => {
+    if (inline) return
     if (!run) {
       setState("idle")
       setUrl(null)
@@ -162,7 +184,7 @@ export function ReactDemo({
       cancelled = true
       workspace?.dispose()
     }
-  }, [entry, files, onError, onReady, port, run, workspaceOptions])
+  }, [entry, files, inline, onError, onReady, port, run, workspaceOptions])
 
   const wrapperClass = className ? `docs-react-demo ${className}` : "docs-react-demo"
   const running = state === "starting"
@@ -171,10 +193,13 @@ export function ReactDemo({
     <section className={wrapperClass} data-docstream-react-demo="">
       <header className="docs-react-demo-header">
         <span>{title}</span>
-        <span className={`docs-react-demo-status docs-react-demo-status-${state}`}>
-          {state === "ready" ? "ready" : state === "starting" ? "starting" : state}
-        </span>
-        {!autoStart || state === "error" ? (
+        {status === false ? null : (
+          <span className={`docs-react-demo-status docs-react-demo-status-${state}`}>
+            {status ?? (state === "ready" ? "ready" : state === "starting" ? "starting" : state)}
+          </span>
+        )}
+        {actions}
+        {!inline && (!autoStart || state === "error") ? (
           <button
             type="button"
             className="docs-react-demo-run"
@@ -185,7 +210,9 @@ export function ReactDemo({
           </button>
         ) : null}
       </header>
-      {error ? (
+      {inline ? (
+        <div className="docs-react-demo-preview" style={frameHeight(height)}>{preview}</div>
+      ) : error ? (
         <pre className="docs-react-demo-error">{error}</pre>
       ) : url ? (
         <iframe
@@ -211,7 +238,7 @@ export function ReactDemo({
           >
             <HighlightedCode
               code={code}
-              language={sourceLanguage(displayedCodeFile)}
+              language={language ?? sourceLanguage(displayedCodeFile)}
               lineNumbers
             />
           </pre>

package/src/styles.css

@@ -135,10 +135,6 @@
   margin-block: 0.75em;
 }
 
-:is([data-docstream], .docs-article) [data-docstream-blocks] > :is(.docs-table, table) {
-  margin-block: 0;
-}
-
 :is([data-docstream], .docs-article) [data-docstream-blocks] > :is(.docs-cards, .docs-code, .docs-math, .docs-hint, .docs-tabs, .docs-expandable, .docs-stepper, .docs-mermaid-preview, .oas, .docs-embed, .docstream-viz, figure, blockquote, ul, ol, hr) {
   margin-block: 0.75em;
 }
@@ -511,6 +507,17 @@
   display: block;
 }
 
+/* Syntax tokens (HighlightedCode). Palenight on dark color-schemes, same-hue AA colors on light ones.
+   Override any --docs-tok-* property to retheme. */
+.docs-tok-keyword { color: var(--docs-tok-keyword, light-dark(#8839C4, #C792EA)); }
+.docs-tok-type { color: var(--docs-tok-type, light-dark(#A15C00, #FFCB6B)); }
+.docs-tok-function { color: var(--docs-tok-function, light-dark(#2F5BD3, #82AAFF)); }
+.docs-tok-string { color: var(--docs-tok-string, light-dark(#23803A, #A5D6A7)); }
+.docs-tok-number { color: var(--docs-tok-number, light-dark(#C2410C, #F78C6C)); }
+.docs-tok-constant { color: var(--docs-tok-constant, light-dark(#C8283F, #F07178)); }
+.docs-tok-operator { color: var(--docs-tok-operator, light-dark(#0B7285, #89DDFF)); }
+.docs-tok-comment { color: var(--docs-tok-comment, light-dark(#6E6E7A, #8A8A98)); font-style: italic; }
+
 .docs-code-line {
   display: flex;
   gap: 14px;
@@ -977,6 +984,12 @@
   background: #fff;
 }
 
+/* Inline preview (`preview` prop): the host's own content, so no forced background. `height: auto` grows to fit. */
+.docs-react-demo-preview {
+  position: relative;
+  overflow: hidden;
+}
+
 .docs-react-demo-placeholder {
   display: grid;
   place-items: center;
@@ -1295,3 +1308,9 @@
   height: 14px;
   border-radius: 4px;
 }
+
+/* Keep every rendered table variant flush, after the shared block spacing rules. */
+:is([data-docstream], .docs-article) [data-docstream-blocks] > :is(.docs-table, table, .docs-cards) {
+  margin-block-start: 0;
+  margin-block-end: 0;
+}