@brett_lamy/docstream 1.2.1 → 1.2.3

package/README.md

@@ -107,6 +107,18 @@ Helpful context for the reader.
 
 Supported styles are `info`, `success`, `warning`, and `danger`.
 
+### Code fences
+
+````md
+```ts title="client.ts"
+const client = createClient()
+```
+````
+
+Titled (file) fences show line numbers; untitled fences don't. `lineNumbers="true"`
+or `lineNumbers="false"` overrides either way, and an explicit attribute is kept on
+serialize even when it matches the default.
+
 ### Tabs
 
 ````md
@@ -289,11 +301,30 @@ examples/button/sizes/
 ```
 
 `meta.height` is a minimum for single-file previews (in-page components may grow
-past it) and the stage height for the multi-file viewer. `className` / `surface`
-(a style object, CSS custom properties welcome) style the preview canvas,
-`status` shows a small label in the header ("Live", "Needs network"), and
-`variantsWidth` sizes the variant switch. Block-level demo roots fill the canvas
-width; intrinsically sized ones (a button, an image) are centred.
+past it; without a height they size to their content — hosts can set a floor with
+`--docs-demo-preview-min-height`) and the stage height for the multi-file viewer.
+`className` / `surface` (a style object, CSS custom properties welcome) style the
+preview canvas, `bleed` drops its padding, `status` shows a small label in the
+header ("Live", "Needs network"), and `variantsWidth` sizes the variant switch.
+The canvas is block flow: block-level demo roots fill its width and lay out as on a
+page (`max-width: 480px; margin: 0 auto` centres at 480px); intrinsically sized
+(inline-level) ones — a button, a badge, an image — are centred.
+
+Every `meta.json` field has a tag attribute of the same name:
+
+```md
+{% demo src="button/sizes" title="Sizes \"S\" to \"L\"" status="Live" bleed="true" className="brand"
+  surface="background: var(--brand-50); --demo-gap: 12px" variantsWidth="220" %}
+```
+
+(one line in practice). `surface` is written as CSS declarations; `bleed="false"`
+switches off a `meta.json` `bleed: true`. **Precedence:** a tag attribute wins,
+then `meta.json`, then the built-in default — field by field. Copy page folds
+`meta.json` into the tag, so the copied page renders the same without the resolver.
+
+Attribute values are double-quoted; inside them a double quote is written `\"`, a
+backslash `\\`, and `%}` as `%\}`. The serializer escapes, the parser unescapes
+(other backslashes are kept as written).
 
 #### Demos that carry their files (block form)
 

package/package.json

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

package/src/demo/DemoViewer.tsx

@@ -38,6 +38,7 @@ import { PillTabs, Segmented, rovingKeyDown } from "../docs/controls"
 import { useDemoResolver, useDemoRuntime } from "./context"
 import { languageForPath } from "./glob"
 import { inlineDemoMarkdown } from "./markdown"
+import { cssToSurface, surfaceStyle, surfaceToCss } from "./surface"
 import type { DemoComponent, DemoFile, DemoMeta, DemoResolver, DemoVariant, InlineDemoRuntime } from "./types"
 
 export interface DemoViewerProps {
@@ -66,7 +67,23 @@ export interface DemoViewerProps {
   runtime?: InlineDemoRuntime
   /** Extra npm dependencies for the runtime, merged over `demoDependencies` from context. */
   dependencies?: Record<string, string>
+  /** Class on the viewer's outer element. (The preview canvas's class is `canvasClassName`.) */
   className?: string
+  /*
+   * Look. Each falls back to the resolver's `meta.json` field of the same name when unset —
+   * props (a `{% demo %}` tag's attributes) win over `meta.json`, which wins over the
+   * defaults — so a copied page renders the same with or without the resolver.
+   */
+  /** Status shown in the header (`meta.status`). */
+  status?: string
+  /** Full-bleed canvas without the padded surface (`meta.bleed`). */
+  bleed?: boolean
+  /** Extra class on the preview canvas (`meta.className`). */
+  canvasClassName?: string
+  /** Canvas inline style: an object like `meta.surface`, or CSS declarations as in the tag's `surface`. */
+  surface?: Record<string, string | number> | string
+  /** Width of the variant switch (`meta.variantsWidth`). */
+  variantsWidth?: number | string
 }
 
 /* ---------- data ---------- */
@@ -249,7 +266,11 @@ function DemoCanvas({ src, preview, variant, bleed, look }: {
   }
   if (preview.kind === "runtime") {
     return (
-      <div className="docs-demo-canvas docs-demo-canvas-bleed docs-demo-canvas-runtime" data-variant={variant}>
+      <div
+        className={["docs-demo-canvas docs-demo-canvas-bleed docs-demo-canvas-runtime", look?.className ?? ""].filter(Boolean).join(" ")}
+        style={surfaceStyle(look?.surface)}
+        data-variant={variant}
+      >
         <DemoErrorBoundary src={src || "demo"}>{preview.render(variant)}</DemoErrorBoundary>
       </div>
     )
@@ -258,7 +279,7 @@ function DemoCanvas({ src, preview, variant, bleed, look }: {
   return (
     <div
       className={["docs-demo-canvas", bleed ? "docs-demo-canvas-bleed" : "", look?.className ?? ""].filter(Boolean).join(" ")}
-      style={look?.surface as CSSProperties | undefined}
+      style={surfaceStyle(look?.surface)}
       data-variant={variant}
     >
       {component.status === "ready" ? (
@@ -498,7 +519,7 @@ function VariantSwitch({ variants, value, onChange, title, width }: {
       onChange={onChange}
       label={`${title} variant`}
       className={width === undefined ? "docs-demo-variants" : "docs-demo-variants docs-demo-variants-sized"}
-      style={width === undefined ? undefined : { width: typeof width === "number" ? `${width}px` : width }}
+      style={width === undefined ? undefined : { width: cssLength(width, "auto") }}
     />
   )
 }
@@ -600,10 +621,15 @@ export function DemoViewer(props: DemoViewerProps) {
   const layout: "single" | "multi" | null =
     layoutPref !== "auto" ? layoutPref : fileList ? (fileList.length > 1 ? "multi" : "single") : null
   const heightValue = props.height ?? metaValue?.height
-  const bleed = metaValue?.bleed
-  const look: CanvasLook | undefined = metaValue
-  const variantsWidth = metaValue?.variantsWidth
-  const status = metaValue?.status
+  // Look: the tag's attributes (props) first, then `meta.json`.
+  const bleed = props.bleed ?? metaValue?.bleed
+  const propSurface = typeof props.surface === "string" ? cssToSurface(props.surface) : props.surface
+  const look: CanvasLook = {
+    className: props.canvasClassName ?? metaValue?.className,
+    surface: propSurface ?? metaValue?.surface,
+  }
+  const variantsWidth = props.variantsWidth ?? metaValue?.variantsWidth
+  const status = props.status ?? metaValue?.status
   const [fullscreen, setFullscreen] = useState(false)
   const href = mode === "resolver" ? resolver?.href?.(src, variant ? { variant } : undefined) : undefined
   const baseId = useId()
@@ -637,6 +663,11 @@ export function DemoViewer(props: DemoViewerProps) {
     ...(props.layout ? { layout: props.layout } : {}),
     ...(props.variants?.length ? { variants: props.variants } : {}),
     ...(props.viewport ? { viewport: props.viewport } : {}),
+    ...(props.status ? { status: props.status } : {}),
+    ...(props.bleed !== undefined ? { bleed: props.bleed } : {}),
+    ...(props.canvasClassName ? { className: props.canvasClassName } : {}),
+    ...(props.surface ? { surface: typeof props.surface === "string" ? props.surface : surfaceToCss(props.surface) } : {}),
+    ...(props.variantsWidth !== undefined && props.variantsWidth !== "" ? { variantsWidth: String(props.variantsWidth) } : {}),
   }
   const copyDemo = () => inlineDemoMarkdown(node, fileList ?? [], metaValue)
 
@@ -676,8 +707,15 @@ export function DemoViewer(props: DemoViewerProps) {
           {runnable ? (
             <div
               className="docs-react-demo-preview docs-demo-single-preview"
-              // A hint, not a cap: in-page components may grow past it. An iframe needs a real height.
-              style={preview.kind === "runtime" ? { height: cssLength(heightValue, "360px") } : { minHeight: cssLength(heightValue, "120px") }}
+              // A hint, not a cap: in-page components may grow past it (no height: size to content;
+              // hosts may set a floor with --docs-demo-preview-min-height). An iframe needs a real height.
+              style={
+                preview.kind === "runtime"
+                  ? { height: cssLength(heightValue, "360px") }
+                  : heightValue === undefined || heightValue === ""
+                    ? undefined
+                    : { minHeight: cssLength(heightValue, "0px") }
+              }
             >
               {near ? <DemoCanvas src={src} preview={preview} variant={variant} bleed={bleed} look={look} /> : <Spinner />}
             </div>
@@ -844,6 +882,11 @@ export function DemoBlock({ node }: { node: DemoNode }) {
       files={node.files}
       entry={node.entry}
       streaming={node.open}
+      status={node.status}
+      bleed={node.bleed}
+      canvasClassName={node.className}
+      surface={node.surface}
+      variantsWidth={node.variantsWidth}
     />
   )
 }

package/src/demo/index.ts

@@ -11,6 +11,7 @@ export {
 } from "./glob"
 export type { GlobDemoResolverOptions } from "./glob"
 export { defaultDemoMarkdown, inlineDemoMarkdown, inlineDemoNode, resolveDemosToMarkdown, toInlineFiles } from "./markdown"
+export { cssToSurface, surfaceToCss } from "./surface"
 export type { DemoMarkdownFormat, ResolveDemosOptions, ResolvedDemo } from "./markdown"
 export type {
   DemoComponent,

package/src/demo/markdown.ts

@@ -1,9 +1,11 @@
 import type { DemoInlineFile, DemoNode } from "../gitbook/ast"
+import { TAG_ATTRS } from "../gitbook/attrs"
 import { flattenForPlainMarkdown } from "../gitbook/flatten"
 import { demoBody, fenceTracker, parseBlocks, parseMarkdown } from "../gitbook/parse"
 import { fenceFor, serializeBlocks, serializeMarkdown } from "../gitbook/serialize"
 import type { DemoFile, DemoMeta, DemoResolver } from "./types"
 import { languageForPath } from "./glob"
+import { surfaceToCss } from "./surface"
 
 export { fenceFor }
 
@@ -39,7 +41,7 @@ export interface ResolvedDemo {
   title: string
 }
 
-const TAG_RE = /^(\s*)\{%\s*demo(\s[^%]*?)?\s*\/?%\}\s*$/
+const TAG_RE = new RegExp(String.raw`^(\s*)\{%\s*demo(\s${TAG_ATTRS})?\s*\/?%\}\s*$`)
 
 function titleFor(src: string, node: DemoNode, meta: DemoMeta | undefined) {
   return node.title ?? meta?.title ?? (src.split("/").pop() || src || "Demo")
@@ -77,7 +79,9 @@ export function toInlineFiles(files: DemoFile[]): DemoInlineFile[] {
 /**
  * A demo as a self-contained block-form `{% demo %}`: the node's attributes, with the
  * folder's `meta.json` defaults folded in (so the block renders the same without the
- * resolver), and `files` as inline fences.
+ * resolver) — title, description, height, layout, variants, entry and the look fields
+ * `status`, `bleed`, `className`, `surface` (as CSS declarations) and `variantsWidth` —
+ * and `files` as inline fences. Tag attributes win over `meta.json` where both exist.
  */
 export function inlineDemoNode(node: DemoNode, files: DemoFile[], meta?: DemoMeta): DemoNode {
   const inline = toInlineFiles(files)
@@ -87,6 +91,11 @@ export function inlineDemoNode(node: DemoNode, files: DemoFile[], meta?: DemoMet
   const layout = node.layout ?? meta?.layout
   const variants = node.variants?.length ? node.variants : meta?.variants?.length ? meta.variants : undefined
   const entry = node.entry ?? (meta?.entry && inline[0]?.path !== meta.entry ? meta.entry : undefined)
+  const status = node.status ?? meta?.status
+  const bleed = node.bleed ?? meta?.bleed
+  const className = node.className ?? meta?.className
+  const surface = node.surface ?? (meta?.surface ? surfaceToCss(meta.surface) : undefined)
+  const variantsWidth = node.variantsWidth ?? (meta?.variantsWidth === undefined || meta.variantsWidth === "" ? undefined : String(meta.variantsWidth))
   return {
     type: "demo",
     src: node.src,
@@ -97,6 +106,11 @@ export function inlineDemoNode(node: DemoNode, files: DemoFile[], meta?: DemoMet
     ...(variants ? { variants } : {}),
     ...(node.viewport ? { viewport: node.viewport } : {}),
     ...(entry ? { entry } : {}),
+    ...(status ? { status } : {}),
+    ...(bleed === undefined ? {} : { bleed }),
+    ...(className ? { className } : {}),
+    ...(surface ? { surface } : {}),
+    ...(variantsWidth ? { variantsWidth } : {}),
     ...(inline.length ? { files: inline } : {}),
   }
 }
@@ -123,7 +137,7 @@ export async function resolveDemosToMarkdown(
   options: ResolveDemosOptions = {},
 ): Promise<string> {
   // Plain output also flattens docstream-only presentation blocks (command boxes, titled tabs).
-  if (options.format === "plain" && /\{%\s*(?:command\b|tabs\s[^%]*\btitle=)/.test(markdown)) {
+  if (options.format === "plain" && /\{%\s*(?:command\b|tabs\s(?:[^%\n]|%(?!\}))*\btitle=)/.test(markdown)) {
     markdown = serializeMarkdown(flattenForPlainMarkdown(parseMarkdown(markdown)))
   }
   const lines = markdown.split("\n")

package/src/demo/surface.ts

@@ -0,0 +1,67 @@
+import type { CSSProperties } from "react"
+
+/*
+ * A demo canvas's `surface` (inline style) has two spellings:
+ * - `meta.json`: an object, `{ "background": "var(--brand-50)", "--demo-gap": "12px", "padding": 12 }`;
+ * - the `{% demo surface="…" %}` attribute: CSS declarations,
+ *   `background: var(--brand-50); --demo-gap: 12px; padding: 12`.
+ * Keys are kept as written (camelCase, kebab-case or custom properties).
+ */
+
+/** A `meta.json` surface object as the declaration string the demo tag carries. */
+export function surfaceToCss(surface: Record<string, string | number>): string {
+  return Object.entries(surface)
+    .filter(([key, value]) => key.trim() && value !== undefined && value !== null && String(value).trim() !== "")
+    .map(([key, value]) => `${key.trim()}: ${String(value).trim()}`)
+    .join("; ")
+}
+
+/** Split on `;` outside parentheses and quotes (`url("a;b")` stays whole). */
+function declarations(css: string): string[] {
+  const out: string[] = []
+  let depth = 0
+  let quote = ""
+  let current = ""
+  for (const ch of css) {
+    if (quote) {
+      if (ch === quote) quote = ""
+    } else if (ch === '"' || ch === "'") quote = ch
+    else if (ch === "(") depth++
+    else if (ch === ")") depth = Math.max(0, depth - 1)
+    else if (ch === ";" && depth === 0) {
+      out.push(current)
+      current = ""
+      continue
+    }
+    current += ch
+  }
+  out.push(current)
+  return out
+}
+
+/**
+ * The tag's declaration string as a React style object. Custom properties keep their
+ * name; `kebab-case` becomes camelCase; plain numbers on ordinary properties become
+ * numbers (so `padding: 12` means 12px, as it does in `meta.json`).
+ */
+export function cssToSurface(css: string): Record<string, string | number> {
+  const style: Record<string, string | number> = {}
+  for (const declaration of declarations(css)) {
+    const colon = declaration.indexOf(":")
+    if (colon < 0) continue
+    const key = declaration.slice(0, colon).trim()
+    const value = declaration.slice(colon + 1).trim()
+    if (!key || !value) continue
+    if (key.startsWith("--")) {
+      style[key] = value
+      continue
+    }
+    const name = key.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase())
+    style[name] = /^-?\d+(?:\.\d+)?$/.test(value) ? Number(value) : value
+  }
+  return style
+}
+
+export function surfaceStyle(surface: Record<string, string | number> | undefined): CSSProperties | undefined {
+  return surface && Object.keys(surface).length ? (surface as CSSProperties) : undefined
+}

package/src/gitbook/ast.ts

@@ -16,8 +16,24 @@ export interface TextNode {
    * (`[**x**](url)`, the default). Kept so the source round-trips byte-for-byte.
    */
   linkInner?: true
+  /**
+   * How the source spelled this run's formatting, outermost → innermost, when that differs from the default
+   * output (`_italic_`, `**bold**`, `~~strike~~`, link around its emphasis, bare autolinks). Each entry is an
+   * emphasis marker, or a link form: `"link"` (`[x](url)`), `"<>"` (`<url>`), `"url"` (bare autolink).
+   * E.g. `**_x_**` → `["**", "_"]`, `***x***` → `["*", "**"]`, `*x*` → `["*"]`.
+   *
+   * A hint only — the boolean marks and `link` stay authoritative: entries for marks the run no longer has are
+   * ignored, marks it has without an entry get the default spelling and position. Absent on runs that
+   * serialize the default way and on programmatically created nodes.
+   */
+  delims?: InlineDelimiter[]
 }
 
+/** An emphasis marker as written in the source. */
+export type EmphasisDelimiter = "**" | "__" | "*" | "_" | "~~"
+/** An entry of {@link TextNode.delims}: an emphasis marker or a link form. */
+export type InlineDelimiter = EmphasisDelimiter | "link" | "<>" | "url"
+
 /** Inline HTML image, optionally wrapped in a link — GitHub README badge style. */
 export interface InlineImageNode {
   type: "image"
@@ -67,7 +83,16 @@ export interface CodeBlockNode {
   type: "code"
   language: string | null
   title: string | null
+  /**
+   * Show line numbers. Defaults (when the fence doesn't say) to on for titled fences and
+   * off for untitled ones; `lineNumbers="true"` / `"false"` overrides.
+   */
   lineNumbers: boolean
+  /**
+   * The source wrote `lineNumbers` (or `showLineNumbers`) explicitly: the serializer keeps
+   * the attribute even when it matches the default, so pages round-trip byte-for-byte.
+   */
+  lineNumbersExplicit?: boolean
   code: string
   /** Run a React/JSX/TSX entry file in the optional almost-node preview. */
   live?: boolean
@@ -201,8 +226,11 @@ export interface DemoInlineFile {
  * A live demo: `{% demo src="<page>/<example>" %}`. With a host `DemoResolver`
  * that knows `src`, the example folder is the authority for the component, its
  * source files and its defaults; attributes here override the folder's
- * `meta.json`. The block form carries the files inline so the Markdown renders
- * anywhere, resolver or not:
+ * `meta.json` field by field (tag attribute first, then `meta.json`, then the built-in
+ * default) — including the look attributes `status`, `bleed`, `className`, `surface` and
+ * `variantsWidth`, which Copy page writes so the block renders the same without the resolver.
+ * The block form carries the files inline so the Markdown renders anywhere, resolver
+ * or not:
  *
  *     {% demo src="composer/scroll-fab" title="Scroll → FAB" %}
  *     ```tsx title="index.tsx"
@@ -225,6 +253,19 @@ export interface DemoNode {
   viewport?: DemoViewport
   /** Entry file among the inline files (`entry="App.tsx"`). Defaults to the first file. */
   entry?: string
+  /** Short status shown in the demo header (`status="Live"`). */
+  status?: string
+  /** Drop the padded preview surface (`bleed="true"`) for demos with their own full-bleed frame. */
+  bleed?: boolean
+  /** Extra class on the preview canvas (`className="brand-surface"`). */
+  className?: string
+  /**
+   * Inline style for the preview canvas as CSS declarations, kept verbatim:
+   * `surface="background: var(--brand-50); --demo-gap: 12px"`.
+   */
+  surface?: string
+  /** Width of the variant switch, kept verbatim (`"240"`, `"16rem"`). */
+  variantsWidth?: string
   /** Files carried inline by the block form, in document order. */
   files?: DemoInlineFile[]
   /**

package/src/gitbook/attrs.ts

@@ -0,0 +1,39 @@
+/*
+ * Tag and fence attribute values (`{% demo title="…" %}`, ```` ```ts title="…" ````).
+ *
+ * Values are double-quoted. On serialize a backslash becomes `\\`, a double quote `\"`,
+ * and the tag terminator `%}` becomes `%\}` — so a value can never end its tag early or
+ * truncate at a quote. On parse `\\`, `\"` and `\}` are unescaped; any other backslash is
+ * kept literally (so `C:\temp` written by hand still reads as written).
+ */
+
+/** Escape one attribute value for a double-quoted `name="…"` pair. */
+export function escapeAttr(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%\}/g, "%\\}")
+}
+
+/** Undo `escapeAttr`. */
+export function unescapeAttr(raw: string): string {
+  return raw.replace(/\\(["\\}])/g, "$1")
+}
+
+/** ` name="value"` with the value escaped (leading space included). */
+export function attr(name: string, value: string | number | boolean): string {
+  return ` ${name}="${escapeAttr(String(value))}"`
+}
+
+/** Every `name="value"` pair in `raw` (escapes honoured, values unescaped). */
+export function parseAttrs(raw: string | undefined): Record<string, string> {
+  const attrs: Record<string, string> = {}
+  if (!raw) return attrs
+  for (const m of raw.matchAll(/([\w-]+)="((?:[^"\\]|\\.)*)"/g)) {
+    attrs[m[1]] = unescapeAttr(m[2])
+  }
+  return attrs
+}
+
+/**
+ * The attribute part of a `{% name … %}` tag, as a regex source: anything up to the
+ * closing `%}` (a lone `%` is fine; `%}` inside a value is always escaped as `%\}`).
+ */
+export const TAG_ATTRS = String.raw`(?:[^%\n]|%(?!\}))*?`

package/src/gitbook/flatten.ts

@@ -19,7 +19,7 @@ export function flattenBlocks(blocks: Block[]): Block[] {
   return blocks.flatMap((b): Block[] => {
     switch (b.type) {
       case "command":
-        return [{ type: "code", language: "sh", title: null, lineNumbers: true, code: b.command }]
+        return [{ type: "code", language: "sh", title: null, lineNumbers: false, code: b.command }]
       case "tabs":
         if (b.title) {
           return [

package/src/gitbook/index.ts

@@ -1,9 +1,10 @@
 // Pure GitBook markdown engine (no React, no mermaid/streamdown). Safe to import
 // in non-DOM environments such as a server-side AI agent or a Cloudflare Worker.
 export type * from "./ast"
+export { escapeAttr, unescapeAttr } from "./attrs"
 export { closesFence, demoBody, fenceOpener, fenceTracker, parseDemoVariants, parseMarkdown, parseBlocks, trimPartialInlineToken } from "./parse"
 export { fenceFor, serializeBlocks, serializeDemoFile, serializeMarkdown } from "./serialize"
-export { footnoteDefinitions, parseInline, plainText, refDefinitions, serializeInline, serializeReference } from "./inline"
+export { defaultInlineDelims, footnoteDefinitions, inlineDelims, parseInline, plainText, refDefinitions, serializeInline, serializeReference } from "./inline"
 export { PACKAGE_MANAGERS, packageManagerCommands } from "./package-managers"
 export { flattenBlocks, flattenForPlainMarkdown } from "./flatten"
 export { documentOutline, slugify } from "./outline"