@brett_lamy/docstream-editor 0.5.5 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream-editor",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "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": "^0.5.5",
+    "@brett_lamy/docstream": "0.5.6",
     "lowlight": "^3.3.0",
     "lucide-react": "^1.17.0"
   },

package/src/editor/Editor.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef } from "react"
+import { useEffect, useMemo, useRef } from "react"
 import { EditorContent, useEditor, type Editor as TiptapEditor } from "@tiptap/react"
 import type { AnyExtension } from "@tiptap/core"
 import {
@@ -11,8 +11,10 @@ import {
 } from "lucide-react"
 
 import { parseMarkdown, serializeMarkdown, type CitationDef } from "@brett_lamy/docstream/gitbook"
+import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
 import { astToTiptap, tiptapToAst, type PMNode } from "./convert"
 import { createGitbookExtensions } from "./extensions"
+import { EditorRuntimeProvider } from "./runtime"
 import type { SlashItem } from "./slash-menu"
 
 export interface GitbookEditorProps {
@@ -47,6 +49,16 @@ export interface GitbookEditorProps {
   onPaste?: (event: ClipboardEvent) => boolean
   /** Receive the underlying TipTap editor instance (and null on teardown). */
   onEditorReady?: (editor: TiptapEditor | null) => void
+  /** Client used to edit and preview `{% source-ref %}` files. */
+  sourceClient?: SourceReferenceClient
+  /** Show the rendered export below a file-backed source editor (default true). */
+  sourcePreview?: boolean
+  /** Autosave file-backed source edits. `true` defaults to 500ms; a number sets the delay. */
+  sourceAutoSave?: boolean | number
+  /** Called after a file-backed source edit is written. */
+  onSourceSaved?: (snapshot: SourceFileSnapshot) => void
+  /** Called when reading, writing, or previewing a file-backed source fails. */
+  onSourceError?: (error: Error) => void
 }
 
 function ToolbarButton({
@@ -124,6 +136,11 @@ export function GitbookEditor({
   onKeyDown,
   onPaste,
   onEditorReady,
+  sourceClient,
+  sourcePreview = true,
+  sourceAutoSave = true,
+  onSourceSaved,
+  onSourceError,
 }: GitbookEditorProps) {
   // Tracks the markdown the editor itself produced, so external updates
   // (file switches) reset content but our own onChange echoes don't.
@@ -179,12 +196,22 @@ export function GitbookEditor({
     editor.commands.setContent(astToTiptap(doc), { emitUpdate: false })
   }, [editor, controlled, markdown])
 
+  const runtime = useMemo(() => ({
+    ...(sourceClient ? { sourceClient } : {}),
+    sourcePreview,
+    sourceAutoSave,
+    ...(onSourceSaved ? { onSourceSaved } : {}),
+    ...(onSourceError ? { onSourceError } : {}),
+  }), [onSourceError, onSourceSaved, sourceAutoSave, sourceClient, sourcePreview])
+
   if (!editor) return null
 
   return (
     <div className={className ? `gb ${className}` : "gb"}>
       {toolbar && <Toolbar editor={editor} />}
-      <EditorContent editor={editor} className="gb-content" />
+      <EditorRuntimeProvider value={runtime}>
+        <EditorContent editor={editor} className="gb-content" />
+      </EditorRuntimeProvider>
     </div>
   )
 }

package/src/editor/ReactDemoEditor.tsx

@@ -13,6 +13,10 @@ export interface ReactDemoEditorProps {
   className?: string
   /** Called whenever a file is edited. */
   onChange?: (files: Record<string, string>) => void
+  /** Refresh the AlmostNode preview as files are edited (default true). */
+  autoPreview?: boolean
+  /** Delay before a live preview receives edited files (default 350ms). */
+  previewDebounceMs?: number
 }
 
 function nextFile(files: Readonly<Record<string, string>>): string {
@@ -26,17 +30,29 @@ export function ReactDemoEditor({
   height = 320,
   className,
   onChange,
+  autoPreview = true,
+  previewDebounceMs = 350,
 }: ReactDemoEditorProps) {
   const [draftFiles, setDraftFiles] = useState<Record<string, string>>(() => ({ ...files }))
   const [selectedFile, setSelectedFile] = useState(() => nextFile(files))
-  const [previewFiles, setPreviewFiles] = useState<Record<string, string> | null>(null)
+  const [previewFiles, setPreviewFiles] = useState<Record<string, string>>(() => ({ ...files }))
   const [previewRevision, setPreviewRevision] = useState(0)
 
   useEffect(() => {
     setDraftFiles({ ...files })
+    setPreviewFiles({ ...files })
     setSelectedFile((current) => (current && files[current] !== undefined ? current : nextFile(files)))
   }, [files])
 
+  useEffect(() => {
+    if (!autoPreview) return
+    const timer = window.setTimeout(
+      () => setPreviewFiles({ ...draftFiles }),
+      Math.max(0, previewDebounceMs),
+    )
+    return () => window.clearTimeout(timer)
+  }, [autoPreview, draftFiles, previewDebounceMs])
+
   const updateFile = (content: string) => {
     if (!selectedFile) return
     const next = { ...draftFiles, [selectedFile]: content }
@@ -48,6 +64,13 @@ export function ReactDemoEditor({
 
   return (
     <section className={wrapperClass} data-docstream-react-demo-editor="">
+      <ReactCodePreview
+        key={previewRevision}
+        files={previewFiles}
+        entry={entry}
+        height={height}
+        title="React demo preview"
+      />
       <div className="gb-react-demo-editor-source">
         <aside className="gb-react-demo-files" aria-label="Demo files">
           <div className="gb-react-demo-files-header">
@@ -70,17 +93,21 @@ export function ReactDemoEditor({
         <div className="gb-react-demo-editor-pane">
           <div className="gb-react-demo-editor-toolbar">
             <code>{selectedFile || "No file selected"}</code>
-            <button
-              type="button"
-              className="gb-react-demo-preview-button"
-              disabled={!selectedFile}
-              onClick={() => {
-                setPreviewFiles({ ...draftFiles })
-                setPreviewRevision((value) => value + 1)
-              }}
-            >
-              <Play className="size-3.5" /> Run demo
-            </button>
+            {autoPreview ? (
+              <span className="gb-react-demo-live-status">Live preview</span>
+            ) : (
+              <button
+                type="button"
+                className="gb-react-demo-preview-button"
+                disabled={!selectedFile}
+                onClick={() => {
+                  setPreviewFiles({ ...draftFiles })
+                  setPreviewRevision((value) => value + 1)
+                }}
+              >
+                <Play className="size-3.5" /> Run demo
+              </button>
+            )}
           </div>
           <textarea
             className="gb-react-demo-textarea"
@@ -92,17 +119,6 @@ export function ReactDemoEditor({
           />
         </div>
       </div>
-      {previewFiles ? (
-        <ReactCodePreview
-          key={previewRevision}
-          files={previewFiles}
-          entry={entry}
-          height={height}
-          title="React demo preview"
-        />
-      ) : (
-        <div className="gb-react-demo-editor-empty">Edit a file, then run the demo to preview the complete project.</div>
-      )}
     </section>
   )
 }

package/src/editor/SourceFileEditor.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react"
+import { useCallback, useEffect, useState } from "react"
 import { FileCode2, Save } from "lucide-react"
 import { SourcePreview, type SourceFileSnapshot, type SourceReferenceClient } from "@brett_lamy/docstream/source"
 import type { SourceRefNode } from "@brett_lamy/docstream/gitbook"
@@ -8,6 +8,8 @@ export interface SourceFileEditorProps {
   client: SourceReferenceClient
   className?: string
   preview?: boolean
+  /** Automatically write edits after a pause. `true` defaults to 500ms. */
+  autoSave?: boolean | number
   onSaved?: (snapshot: SourceFileSnapshot) => void
   onError?: (error: Error) => void
 }
@@ -17,7 +19,7 @@ function asError(cause: unknown): Error {
 }
 
 /** Edit the real file behind a Markdown source reference and preview its export. */
-export function SourceFileEditor({ reference, client, className, preview = true, onSaved, onError }: SourceFileEditorProps) {
+export function SourceFileEditor({ reference, client, className, preview = true, autoSave = false, onSaved, onError }: SourceFileEditorProps) {
   const [content, setContent] = useState("")
   const [savedContent, setSavedContent] = useState("")
   const [revision, setRevision] = useState(0)
@@ -48,7 +50,7 @@ export function SourceFileEditor({ reference, client, className, preview = true,
     }
   }, [client, onError, reference])
 
-  const save = async () => {
+  const save = useCallback(async () => {
     setStatus("saving")
     setError(null)
     try {
@@ -63,7 +65,19 @@ export function SourceFileEditor({ reference, client, className, preview = true,
       setStatus("error")
       onError?.(next)
     }
-  }
+  }, [client, content, onError, onSaved, reference])
+
+  const autoSaveDelay = autoSave === true
+    ? 500
+    : typeof autoSave === "number" && Number.isFinite(autoSave)
+      ? Math.max(0, autoSave)
+      : null
+
+  useEffect(() => {
+    if (autoSaveDelay === null || status === "loading" || status === "saving" || content === savedContent) return
+    const timer = window.setTimeout(() => void save(), autoSaveDelay)
+    return () => window.clearTimeout(timer)
+  }, [autoSaveDelay, content, save, savedContent, status])
 
   const wrapper = className ? `gb-source-file-editor ${className}` : "gb-source-file-editor"
   return (
@@ -71,8 +85,9 @@ export function SourceFileEditor({ reference, client, className, preview = true,
       <header className="gb-source-file-editor-header">
         <FileCode2 className="size-4" />
         <code>{reference.mount}:{reference.path}#{reference.exportName}</code>
+        {autoSaveDelay !== null ? <span className="gb-source-file-editor-status">{status === "saving" ? "Saving…" : content === savedContent ? "Saved" : "Unsaved"}</span> : null}
         <button type="button" disabled={status === "loading" || status === "saving" || content === savedContent} onClick={() => void save()}>
-          <Save className="size-3.5" /> {status === "saving" ? "Saving…" : "Save file"}
+          <Save className="size-3.5" /> {status === "saving" ? "Saving…" : autoSaveDelay === null ? "Save file" : "Save now"}
         </button>
       </header>
       {error ? <pre className="gb-source-file-editor-error">{error}</pre> : null}

package/src/editor/nodes.tsx

@@ -1,6 +1,7 @@
 import { Node, mergeAttributes } from "@tiptap/core"
 import { CodeBlockLowlight } from "@tiptap/extension-code-block-lowlight"
 import { common, createLowlight } from "lowlight"
+import { useEffect, useMemo, useState } from "react"
 import {
   NodeViewContent,
   NodeViewWrapper,
@@ -21,11 +22,24 @@ import {
   XCircle,
 } from "lucide-react"
 
+import { DocsRenderer } from "@brett_lamy/docstream"
 import { resolveAsset } from "@brett_lamy/docstream/assets"
 import { OpenApiOperation } from "@brett_lamy/docstream/openapi"
-import type { HintStyle } from "@brett_lamy/docstream/gitbook"
+import type { DocumentNode, HintStyle, SourceRefNode } from "@brett_lamy/docstream/gitbook"
+import { ReactCodePreview } from "@brett_lamy/docstream/playground"
 import { ReplayPreview, isReplayQaUrl } from "@brett_lamy/docstream/replay"
 import { VideoEmbed } from "@brett_lamy/docstream/video"
+import { SourceFileEditor } from "./SourceFileEditor"
+import { useEditorRuntime } from "./runtime"
+
+function useDebouncedValue<T>(value: T, delay = 350): T {
+  const [debounced, setDebounced] = useState(value)
+  useEffect(() => {
+    const timer = window.setTimeout(() => setDebounced(value), delay)
+    return () => window.clearTimeout(timer)
+  }, [delay, value])
+  return debounced
+}
 
 // ---------- Hint ----------
 
@@ -433,22 +447,44 @@ export const GbContentRef = Node.create({
 
 function SourceRefView({ node, updateAttributes, editor }: NodeViewProps) {
   const editable = editor.isEditable
+  const { sourceClient, sourcePreview = true, sourceAutoSave = true, onSourceSaved, onSourceError } = useEditorRuntime()
+  const reference = useMemo<SourceRefNode>(() => ({
+    type: "source-ref",
+    mount: String(node.attrs.mount || "source"),
+    path: String(node.attrs.path || ""),
+    exportName: String(node.attrs.exportName || "default"),
+    kind: node.attrs.kind === "story" ? "story" : "component",
+    title: String(node.attrs.title || ""),
+  }), [node.attrs.exportName, node.attrs.kind, node.attrs.mount, node.attrs.path, node.attrs.title])
   return (
-    <NodeViewWrapper className="gb-source-ref" contentEditable={false}>
-      <FileCode2 className="size-4 shrink-0" />
-      {editable ? (
-        <>
-          <input className="gb-inline-input gb-source-ref-mount" value={node.attrs.mount} placeholder="mount" onChange={(event) => updateAttributes({ mount: event.target.value })} />
-          <input className="gb-inline-input gb-source-ref-path" value={node.attrs.path} placeholder="src/Button.tsx" onChange={(event) => updateAttributes({ path: event.target.value })} />
-          <input className="gb-inline-input gb-source-ref-export" value={node.attrs.exportName} placeholder="Button" onChange={(event) => updateAttributes({ exportName: event.target.value })} />
-          <select className="gb-source-ref-kind" value={node.attrs.kind} onChange={(event) => updateAttributes({ kind: event.target.value })}>
-            <option value="component">component</option>
-            <option value="story">story</option>
-          </select>
-        </>
-      ) : (
-        <span>{node.attrs.title || `${node.attrs.path}#${node.attrs.exportName}`}</span>
-      )}
+    <NodeViewWrapper className={sourceClient && reference.path ? "gb-source-ref-block gb-source-ref-block-editing" : "gb-source-ref-block"} contentEditable={false}>
+      <div className="gb-source-ref">
+        <FileCode2 className="size-4 shrink-0" />
+        {editable ? (
+          <>
+            <input className="gb-inline-input gb-source-ref-mount" value={node.attrs.mount} placeholder="mount" onChange={(event) => updateAttributes({ mount: event.target.value })} />
+            <input className="gb-inline-input gb-source-ref-path" value={node.attrs.path} placeholder="src/Button.tsx" onChange={(event) => updateAttributes({ path: event.target.value })} />
+            <input className="gb-inline-input gb-source-ref-export" value={node.attrs.exportName} placeholder="Button" onChange={(event) => updateAttributes({ exportName: event.target.value })} />
+            <select className="gb-source-ref-kind" value={node.attrs.kind} onChange={(event) => updateAttributes({ kind: event.target.value })}>
+              <option value="component">component</option>
+              <option value="story">story</option>
+            </select>
+          </>
+        ) : (
+          <span>{node.attrs.title || `${node.attrs.path}#${node.attrs.exportName}`}</span>
+        )}
+      </div>
+      {sourceClient && reference.path ? (
+        <SourceFileEditor
+          reference={reference}
+          client={sourceClient}
+          preview={sourcePreview}
+          autoSave={editable ? sourceAutoSave : false}
+          onSaved={onSourceSaved}
+          onError={onSourceError}
+          className="gb-source-ref-editor"
+        />
+      ) : null}
     </NodeViewWrapper>
   )
 }
@@ -597,8 +633,36 @@ export const GbMath = Node.create({
 // ---------- Code block with GitBook title/lineNumbers ----------
 
 function CodeView({ node, updateAttributes, editor }: NodeViewProps) {
+  const code = node.textContent
+  const previewCode = useDebouncedValue(code)
+  const language = String(node.attrs.language ?? "").toLowerCase()
+  const mermaid = language === "mermaid"
+  const almostNode = !!node.attrs.live && (language === "jsx" || language === "tsx" || language === "react")
+  const entry = String(node.attrs.entry || (language === "tsx" ? "/src/main.tsx" : "/src/main.jsx"))
+  const files = useMemo(() => ({ [entry]: previewCode }), [entry, previewCode])
+  const mermaidDocument = useMemo<DocumentNode>(() => ({
+    type: "doc",
+    children: [{ type: "code", language: "mermaid", code: previewCode, title: null, lineNumbers: true }],
+  }), [previewCode])
+
   return (
     <NodeViewWrapper className="gb-code">
+      {mermaid ? (
+        <div className="gb-code-preview gb-code-mermaid-preview" contentEditable={false}>
+          <DocsRenderer doc={mermaidDocument} />
+        </div>
+      ) : null}
+      {almostNode ? (
+        <div className="gb-code-preview gb-code-almost-preview" contentEditable={false}>
+          <ReactCodePreview
+            files={files}
+            entry={entry}
+            codeFile={entry}
+            height={300}
+            title={node.attrs.title || "Live preview"}
+          />
+        </div>
+      ) : null}
       <div className="gb-code-header" contentEditable={false}>
         {editor.isEditable ? (
           <>

package/src/editor/runtime.tsx

@@ -0,0 +1,21 @@
+import { createContext, useContext, type ReactNode } from "react"
+
+import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
+
+export interface EditorRuntimeOptions {
+  sourceClient?: SourceReferenceClient
+  sourcePreview?: boolean
+  sourceAutoSave?: boolean | number
+  onSourceSaved?: (snapshot: SourceFileSnapshot) => void
+  onSourceError?: (error: Error) => void
+}
+
+const EditorRuntimeContext = createContext<EditorRuntimeOptions>({})
+
+export function EditorRuntimeProvider({ value, children }: { value: EditorRuntimeOptions; children: ReactNode }) {
+  return <EditorRuntimeContext.Provider value={value}>{children}</EditorRuntimeContext.Provider>
+}
+
+export function useEditorRuntime(): EditorRuntimeOptions {
+  return useContext(EditorRuntimeContext)
+}

package/src/styles.css

@@ -62,6 +62,23 @@
   background: var(--gb-muted);
 }
 
+.gb-source-ref-block {
+  margin: 0.85em 0;
+}
+
+.gb-source-ref-block > .gb-source-ref {
+  margin: 0;
+}
+
+.gb-source-ref-block > .gb-source-ref-editor {
+  margin-top: -1px;
+  border-radius: 0 0 var(--gb-radius) var(--gb-radius);
+}
+
+.gb-source-ref-block-editing > .gb-source-ref {
+  border-radius: var(--gb-radius) var(--gb-radius) 0 0;
+}
+
 .gb-source-ref-path {
   flex: 1;
 }
@@ -89,6 +106,16 @@
   gap: 0.35rem;
 }
 
+.gb-source-file-editor-status {
+  margin-left: auto;
+  color: var(--gb-muted-foreground);
+  font-size: 11px;
+}
+
+.gb-source-file-editor-status + button {
+  margin-left: 0;
+}
+
 .gb-source-file-editor > textarea {
   box-sizing: border-box;
   width: 100%;
@@ -502,6 +529,24 @@
   margin: 0.85em 0;
   overflow: hidden;
 }
+.gb-code-preview {
+  min-height: 120px;
+  border-bottom: 1px solid var(--gb-border);
+  background: var(--gb-panel);
+}
+.gb-code-preview .docs-article {
+  margin: 0;
+  padding: 14px;
+}
+.gb-code-mermaid-preview .docs-mermaid-code,
+.gb-code-almost-preview .docs-react-demo-code {
+  display: none;
+}
+.gb-code-almost-preview .docs-react-demo {
+  margin: 0;
+  border: 0;
+  border-radius: 0;
+}
 .gb-code-header {
   display: flex;
   align-items: center;
@@ -526,7 +571,7 @@
   color: var(--gb-muted-foreground);
   font-size: 11px;
 }
-.gb-code pre {
+.gb-code > pre {
   margin: 0;
   padding: 13px 15px;
   overflow-x: auto;
@@ -536,8 +581,8 @@
   background: var(--gb-code-bg);
   color: var(--gb-code-fg);
 }
-.gb-code pre code { background: none; padding: 0; font-size: inherit; color: inherit; }
-.gb-code pre code .hljs-comment { font-style: italic; }
+.gb-code > pre code { background: none; padding: 0; font-size: inherit; color: inherit; }
+.gb-code > pre code .hljs-comment { font-style: italic; }
 .gb-code .hljs-keyword,
 .gb-code .hljs-selector-tag,
 .gb-code .hljs-built_in,
@@ -646,6 +691,15 @@
   border-radius: 12px;
   background: var(--gb-panel, var(--card, #ffffff));
 }
+.gb-react-demo-editor > .docs-react-demo {
+  margin: 0;
+  border: 0;
+  border-radius: 0;
+  border-bottom: 1px solid var(--gb-border, var(--border, #e4e4e7));
+}
+.gb-react-demo-editor > .docs-react-demo .docs-react-demo-code {
+  display: none;
+}
 .gb-react-demo-editor-source {
   display: grid;
   grid-template-columns: minmax(150px, 0.28fr) minmax(0, 1fr);
@@ -708,6 +762,12 @@
   font-size: 11px;
 }
 .gb-react-demo-preview-button:disabled { opacity: 0.5; }
+.gb-react-demo-live-status {
+  margin-left: auto;
+  color: var(--gb-success, #22c55e);
+  font-size: 11px;
+  font-weight: 600;
+}
 .gb-react-demo-textarea {
   flex: 1;
   width: 100%;