@brett_lamy/docstream-editor 1.0.0 → 1.1.0

package/README.md

@@ -80,6 +80,7 @@ export interface GitbookEditorProps {
   onAttachmentAdd?: (attachment: EditorAttachment & { file: File }) => void
   onAttachmentRemove?: (ids: string[]) => void
   onAttachmentOpen?: (attachment: EditorAttachment) => void
+  demoResolver?: DemoResolver
 }
 ```
 
@@ -89,6 +90,8 @@ export interface GitbookEditorProps {
   return `true` when the application handled the event.
 - `imagePaste`, `attachments`, `onAttachmentAdd`, `onAttachmentRemove`, `onAttachmentOpen`:
   how pasted/dropped images are handled — see [Pasted and dropped images](#pasted-and-dropped-images).
+- `demoResolver`: resolves `{% demo src %}` ids so demo blocks show a live, read-only
+  preview — see [Demo blocks](#demo-blocks).
 
 The editor tracks the last markdown it emitted so normal controlled updates do not continuously reset the TipTap document. Passing a different external `markdown` value replaces the editor content.
 
@@ -104,12 +107,13 @@ The editor supports common ProseMirror/TipTap content plus GitBook-flavored bloc
 - Code blocks
 - Tables
 - Hints
-- Tabs
+- Tabs (including `{% tabs sync="key" %}` sync groups)
 - Expandables
 - Steppers
 - Embeds
 - Content references
 - Component and Storybook source references
+- File-backed live demos (`{% demo %}`)
 - Columns
 - Figures and images
 - OpenAPI operation placeholders
@@ -201,6 +205,25 @@ provenance, and refreshes the live component/story preview. Configure the mount
 with `docstreamSources()` from `@brett_lamy/docstream/vite` as shown in the
 Docstream README.
 
+## Demo blocks
+
+`{% demo src="<page>/<example>" %}` becomes a `gbDemo` atom node. Every tag
+attribute — `src`, `title`, `description`, `height`, `layout`, `variants`,
+`viewport` — is kept on the node, so the tag serializes back exactly as written.
+The node shows a compact header with editable `src` and `title` inputs (insert
+one with `/demo`). Pass the same `DemoResolver` you give the Docstream renderer
+to also show the live `DemoViewer` preview (read-only) under the header;
+without one, only the header is shown.
+
+```tsx
+import { createGlobDemoResolver } from "@brett_lamy/docstream/demo"
+import { GitbookEditor } from "@brett_lamy/docstream-editor"
+
+const demoResolver = createGlobDemoResolver({ /* see the Docstream README */ })
+
+<GitbookEditor markdown={markdown} onChange={setMarkdown} demoResolver={demoResolver} />
+```
+
 ## Slash Menu
 
 The editor includes a slash menu extension for inserting supported block structures. Type `/` in an empty paragraph to open block insertion options.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream-editor",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "TipTap editor for Docstream GitBook-style markdown documents.",
   "type": "module",
   "scripts": {
@@ -33,7 +33,7 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@brett_lamy/docstream": "1.0.0",
+    "@brett_lamy/docstream": "1.1.1",
     "gpu-lexer": "0.0.2",
     "lucide-react": "^1.17.0"
   },

package/src/editor/Editor.tsx

@@ -11,6 +11,7 @@ import {
 } from "lucide-react"
 
 import { parseMarkdown, type CitationDef } from "@brett_lamy/docstream/gitbook"
+import type { DemoResolver } from "@brett_lamy/docstream/demo"
 import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
 import {
   attachmentName,
@@ -86,6 +87,8 @@ export interface GitbookEditorProps {
   onSourceSaved?: (snapshot: SourceFileSnapshot) => void
   /** Called when reading, writing, or previewing a file-backed source fails. */
   onSourceError?: (error: Error) => void
+  /** Resolves `{% demo src %}` ids; when set, demo blocks show a live (read-only) preview under their header. */
+  demoResolver?: DemoResolver
 }
 
 function ToolbarButton({
@@ -173,6 +176,7 @@ export function GitbookEditor({
   sourceAutoSave = true,
   onSourceSaved,
   onSourceError,
+  demoResolver,
 }: GitbookEditorProps) {
   // Tracks the markdown the editor itself produced, so external updates
   // (file switches) reset content but our own onChange echoes don't.
@@ -295,7 +299,8 @@ export function GitbookEditor({
   }, [editor, onEditorReady])
 
   useEffect(() => {
-    if (!editor || !controlled) return
+    // StrictMode (and <Activity>) re-run effects against an editor useEditor has already destroyed.
+    if (!editor || editor.isDestroyed || !controlled) return
     if (markdown === lastEmitted.current) return
     lastEmitted.current = markdown as string
     const doc = parseMarkdown(markdown as string)
@@ -311,9 +316,10 @@ export function GitbookEditor({
     sourceAutoSave,
     ...(onSourceSaved ? { onSourceSaved } : {}),
     ...(onSourceError ? { onSourceError } : {}),
+    ...(demoResolver ? { demoResolver } : {}),
     ...(attachments ? { attachments } : {}),
     ...(onAttachmentOpen ? { onAttachmentOpen } : {}),
-  }), [attachments, onAttachmentOpen, onSourceError, onSourceSaved, sourceAutoSave, sourceClient, sourcePreview])
+  }), [attachments, demoResolver, onAttachmentOpen, onSourceError, onSourceSaved, sourceAutoSave, sourceClient, sourcePreview])
 
   if (!editor) return null
 

package/src/editor/convert.ts

@@ -2,6 +2,9 @@ import {
   plainText,
   serializeMarkdown,
   type Block,
+  type DemoLayout,
+  type DemoNode,
+  type DemoViewport,
   type DocumentNode,
   type Inline,
   type ListItemNode,
@@ -101,6 +104,7 @@ function blockToPM(b: Block): PMNode {
     case "tabs":
       return {
         type: "gbTabs",
+        ...(b.sync ? { attrs: { sync: b.sync } } : {}),
         content: b.tabs.map((t) => ({
           type: "gbTab",
           attrs: { title: t.title },
@@ -145,6 +149,19 @@ function blockToPM(b: Block): PMNode {
           title: b.title ?? "",
         },
       }
+    case "demo":
+      return {
+        type: "gbDemo",
+        attrs: {
+          src: b.src,
+          title: b.title ?? "",
+          description: b.description ?? "",
+          height: b.height ?? "",
+          layout: b.layout ?? null,
+          variants: b.variants?.length ? b.variants.map((v) => ({ id: v.id, label: v.label })) : null,
+          viewport: b.viewport ?? null,
+        },
+      }
     case "columns":
       return {
         type: "gbColumns",
@@ -310,6 +327,7 @@ function pmToBlock(n: PMNode): Block | null {
           title: String(t.attrs?.title ?? "Tab"),
           children: pmToBlocks(t.content),
         })),
+        ...(n.attrs?.sync ? { sync: String(n.attrs.sync) } : {}),
       }
     case "gbExpandable":
       return {
@@ -354,6 +372,8 @@ function pmToBlock(n: PMNode): Block | null {
         kind: n.attrs?.kind === "story" ? "story" : "component",
         ...(n.attrs?.title ? { title: String(n.attrs.title) } : {}),
       }
+    case "gbDemo":
+      return pmToDemo(n.attrs ?? {})
     case "gbColumns":
       return {
         type: "columns",
@@ -423,6 +443,30 @@ function pmToBlock(n: PMNode): Block | null {
   }
 }
 
+const DEMO_LAYOUTS: readonly string[] = ["auto", "single", "multi"] satisfies DemoLayout[]
+const DEMO_VIEWPORTS: readonly string[] = ["desktop", "tablet", "phone"] satisfies DemoViewport[]
+
+/** `gbDemo` attrs → `DemoNode`; also used by the node view to build the preview. */
+export function pmToDemo(a: Record<string, unknown>): DemoNode {
+  const variants = Array.isArray(a.variants)
+    ? (a.variants as Array<{ id?: unknown; label?: unknown }>)
+        .filter((v) => v && v.id)
+        .map((v) => ({ id: String(v.id), label: String(v.label || v.id) }))
+    : []
+  const layout = String(a.layout ?? "")
+  const viewport = String(a.viewport ?? "")
+  return {
+    type: "demo",
+    src: String(a.src ?? ""),
+    ...(a.title ? { title: String(a.title) } : {}),
+    ...(a.description ? { description: String(a.description) } : {}),
+    ...(a.height ? { height: String(a.height) } : {}),
+    ...(DEMO_LAYOUTS.includes(layout) ? { layout: layout as DemoLayout } : {}),
+    ...(variants.length ? { variants } : {}),
+    ...(DEMO_VIEWPORTS.includes(viewport) ? { viewport: viewport as DemoViewport } : {}),
+  }
+}
+
 function pmToBlocks(nodes: PMNode[] | undefined): Block[] {
   return (nodes ?? []).map(pmToBlock).filter((b): b is Block => b !== null)
 }

package/src/editor/nodes.tsx

@@ -10,6 +10,7 @@ import {
 } from "@tiptap/react"
 import {
   AlertTriangle,
+  AppWindow,
   AtSign,
   CheckCircle2,
   ChevronDown,
@@ -30,6 +31,8 @@ import type { DocumentNode, HintStyle, SourceRefNode } from "@brett_lamy/docstre
 import { ReactCodePreview } from "@brett_lamy/docstream/playground"
 import { ReplayPreview, isReplayQaUrl } from "@brett_lamy/docstream/replay"
 import { VideoEmbed } from "@brett_lamy/docstream/video"
+import { DemoViewer } from "@brett_lamy/docstream/demo"
+import { pmToDemo } from "./convert"
 import { SourceFileEditor } from "./SourceFileEditor"
 import { useEditorRuntime } from "./runtime"
 import { GbAttachment } from "./attachments"
@@ -176,7 +179,15 @@ export const GbTabs = Node.create({
   defining: true,
   isolating: true,
   addAttributes() {
-    return { active: { default: 0, rendered: false } }
+    return {
+      active: { default: 0, rendered: false },
+      // `{% tabs sync="key" %}` — tab sets sharing a key follow the reader's last choice.
+      sync: {
+        default: null,
+        parseHTML: (element) => element.getAttribute("data-sync") || null,
+        renderHTML: (attributes) => (attributes.sync ? { "data-sync": attributes.sync } : {}),
+      },
+    }
   },
   parseHTML() {
     return [{ tag: "div[data-gb-tabs]" }]
@@ -515,6 +526,76 @@ export const GbSourceRef = Node.create({
   },
 })
 
+// ---------- Demo ----------
+
+function DemoView({ node, updateAttributes, editor }: NodeViewProps) {
+  const editable = editor.isEditable
+  const { demoResolver } = useEditorRuntime()
+  const demo = useMemo(() => pmToDemo(node.attrs), [node.attrs])
+  // Typing into `src` would otherwise resolve every intermediate id.
+  const src = useDebouncedValue(demo.src)
+  return (
+    <NodeViewWrapper className={demoResolver && src ? "gb-demo-block gb-demo-block-preview" : "gb-demo-block"} contentEditable={false}>
+      <div className="gb-demo">
+        <AppWindow className="size-4 shrink-0" />
+        {editable ? (
+          <>
+            <input className="gb-inline-input gb-demo-src" value={node.attrs.src} placeholder="page/example" onChange={(event) => updateAttributes({ src: event.target.value })} />
+            <input className="gb-inline-input gb-demo-title" value={node.attrs.title} placeholder="Title" onChange={(event) => updateAttributes({ title: event.target.value })} />
+          </>
+        ) : (
+          <>
+            <code className="gb-demo-src">{demo.src || "demo"}</code>
+            {demo.title ? <span className="gb-demo-title">{demo.title}</span> : null}
+          </>
+        )}
+      </div>
+      {demoResolver && src ? (
+        <div className="gb-demo-preview">
+          <DemoViewer
+            key={src}
+            resolver={demoResolver}
+            src={src}
+            title={demo.title}
+            description={demo.description}
+            height={demo.height}
+            layout={demo.layout}
+            variants={demo.variants}
+            viewport={demo.viewport}
+          />
+        </div>
+      ) : null}
+    </NodeViewWrapper>
+  )
+}
+
+/** `{% demo %}` — every tag attribute is kept on the node so it round-trips losslessly. */
+export const GbDemo = Node.create({
+  name: "gbDemo",
+  group: "block",
+  atom: true,
+  addAttributes() {
+    return {
+      src: { default: "" },
+      title: { default: "" },
+      description: { default: "" },
+      height: { default: "" },
+      layout: { default: null },
+      variants: { default: null, rendered: false },
+      viewport: { default: null },
+    }
+  },
+  parseHTML() {
+    return [{ tag: "div[data-gb-demo]" }]
+  },
+  renderHTML({ HTMLAttributes, node }) {
+    return ["div", mergeAttributes(HTMLAttributes, { "data-gb-demo": node.attrs.src })]
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(DemoView)
+  },
+})
+
 // ---------- Columns ----------
 
 export const GbColumns = Node.create({
@@ -975,6 +1056,7 @@ export const gitbookNodes = [
   GbEmbed,
   GbContentRef,
   GbSourceRef,
+  GbDemo,
   GbColumns,
   GbColumn,
   GbFigure,

package/src/editor/runtime.tsx

@@ -1,5 +1,6 @@
 import { createContext, useContext, type ReactNode } from "react"
 
+import type { DemoResolver } from "@brett_lamy/docstream/demo"
 import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
 import type { EditorAttachment } from "./attachments"
 
@@ -9,6 +10,7 @@ export interface EditorRuntimeOptions {
   sourceAutoSave?: boolean | number
   onSourceSaved?: (snapshot: SourceFileSnapshot) => void
   onSourceError?: (error: Error) => void
+  demoResolver?: DemoResolver
   attachments?: EditorAttachment[]
   onAttachmentOpen?: (attachment: EditorAttachment) => void
 }

package/src/editor/slash-menu.tsx

@@ -1,6 +1,7 @@
 import { Extension, type Editor, type Range } from "@tiptap/core"
 import Suggestion from "@tiptap/suggestion"
 import {
+  AppWindow,
   Columns2,
   FileCode2,
   Heading1,
@@ -101,6 +102,12 @@ export const SLASH_ITEMS: SlashItem[] = [
     icon: Link2,
     run: insertBlock({ type: "gbContentRef", attrs: { url: "", label: "Page link" } }),
   },
+  {
+    title: "Demo",
+    keywords: "example live preview component playground",
+    icon: AppWindow,
+    run: insertBlock({ type: "gbDemo", attrs: { src: "", title: "" } }),
+  },
   {
     title: "Columns",
     keywords: "two column layout",

package/src/styles.css

@@ -88,6 +88,43 @@
   width: 8rem;
 }
 
+.gb-demo {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  border: 1px solid var(--gb-border);
+  border-radius: var(--gb-radius);
+  padding: 0.65rem 0.8rem;
+  background: var(--gb-muted);
+}
+
+.gb-demo-block {
+  margin: 0.85em 0;
+}
+
+.gb-demo-block-preview > .gb-demo {
+  border-radius: var(--gb-radius) var(--gb-radius) 0 0;
+}
+
+.gb-demo-src {
+  flex: 1;
+}
+
+.gb-demo-title {
+  width: 12rem;
+}
+
+.gb-demo-preview {
+  border: 1px solid var(--gb-border);
+  border-top: 0;
+  border-radius: 0 0 var(--gb-radius) var(--gb-radius);
+  overflow: hidden;
+}
+
+.gb-demo-preview > * {
+  margin: 0;
+}
+
 .gb-source-file-editor {
   border: 1px solid var(--gb-border);
   border-radius: var(--gb-radius);