@brett_lamy/docstream-editor 0.3.2 → 0.3.4

package/README.md

@@ -13,6 +13,7 @@ TipTap editor components for Docstream GitBook-style markdown documents.
 - Code block support through `lowlight`.
 - Table, task list, heading, quote, and inline formatting support.
 - Preserves Docstream/GitBook block semantics when converting back to markdown.
+- Preserves mounted source-file/export provenance and can write edits to the real file through Vite.
 
 ## Installation
 
@@ -97,12 +98,39 @@ The editor supports common ProseMirror/TipTap content plus GitBook-flavored bloc
 - Steppers
 - Embeds
 - Content references
+- Component and Storybook source references
 - Columns
 - Figures and images
 - OpenAPI operation placeholders
 
 Some blocks are intentionally represented as structured nodes rather than fully bespoke editing controls. They are preserved through parse, edit, and serialize flows so the document can continue to round-trip as GitBook-style markdown.
 
+## Edit a referenced source file
+
+`GitbookEditor` edits the Markdown composition, including a structured
+`source-ref` node. `SourceFileEditor` edits the real file behind that node:
+
+```tsx
+import { createViteSourceClient, type SourceRefNode } from "@brett_lamy/docstream"
+import { SourceFileEditor } from "@brett_lamy/docstream-editor"
+
+const client = createViteSourceClient()
+const reference: SourceRefNode = {
+  type: "source-ref",
+  mount: "ui",
+  path: "Button.stories.tsx",
+  exportName: "Primary",
+  kind: "story",
+}
+
+<SourceFileEditor reference={reference} client={client} />
+```
+
+Saving calls the Docstream Vite plugin, writes the mounted file, returns its
+provenance, and refreshes the live component/story preview. Configure the mount
+with `docstreamSources()` from `@brett_lamy/docstream/vite` as shown in the
+Docstream README.
+
 ## Slash Menu
 
 The editor includes a slash menu extension for inserting supported block structures. Type `/` in an empty paragraph to open block insertion options.
@@ -127,6 +155,8 @@ Exports:
 - `astToTiptap`
 - `tiptapToAst`
 - `PMNode`
+- `SourceFileEditor`
+- `SourceFileEditorProps`
 
 ## Styling and Theming
 

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@brett_lamy/docstream-editor",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "TipTap editor for Docstream GitBook-style markdown documents.",
   "type": "module",
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "files": [
@@ -20,7 +24,7 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@brett_lamy/docstream": "0.3.2",
+    "@brett_lamy/docstream": "0.3.7",
     "lowlight": "^3.3.0",
     "lucide-react": "^1.17.0"
   },
@@ -39,5 +43,23 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/BLamy/docstream-editor.git"
+  },
+  "devDependencies": {
+    "@agent-wasm/core": "^0.4.0",
+    "@tiptap/core": "^3.26.1",
+    "@tiptap/extension-code-block-lowlight": "^3.26.1",
+    "@tiptap/extension-list": "^3.26.1",
+    "@tiptap/extension-placeholder": "^3.26.1",
+    "@tiptap/extension-table": "^3.26.1",
+    "@tiptap/pm": "^3.26.1",
+    "@tiptap/react": "^3.26.1",
+    "@tiptap/starter-kit": "^3.26.1",
+    "@tiptap/suggestion": "^3.26.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19",
+    "react-dom": "^19",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
   }
 }

package/src/editor/ReactDemoEditor.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useState } from "react"
 import { FileCode2, Play } from "lucide-react"
 
-import { ReactCodePreview } from "@brett_lamy/docstream"
+import { ReactCodePreview } from "@brett_lamy/docstream/playground"
 
 export interface ReactDemoEditorProps {
   /** Source files keyed by their project-relative or absolute paths. */

package/src/editor/SourceFileEditor.tsx

@@ -0,0 +1,83 @@
+import { 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"
+
+export interface SourceFileEditorProps {
+  reference: SourceRefNode
+  client: SourceReferenceClient
+  className?: string
+  preview?: boolean
+  onSaved?: (snapshot: SourceFileSnapshot) => void
+  onError?: (error: Error) => void
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause))
+}
+
+/** Edit the real file behind a Markdown source reference and preview its export. */
+export function SourceFileEditor({ reference, client, className, preview = true, onSaved, onError }: SourceFileEditorProps) {
+  const [content, setContent] = useState("")
+  const [savedContent, setSavedContent] = useState("")
+  const [revision, setRevision] = useState(0)
+  const [status, setStatus] = useState<"loading" | "ready" | "saving" | "error">("loading")
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    setStatus("loading")
+    setError(null)
+    void client.read(reference).then(
+      (snapshot) => {
+        if (cancelled) return
+        setContent(snapshot.content)
+        setSavedContent(snapshot.content)
+        setStatus("ready")
+      },
+      (cause: unknown) => {
+        if (cancelled) return
+        const next = asError(cause)
+        setError(next.message)
+        setStatus("error")
+        onError?.(next)
+      },
+    )
+    return () => {
+      cancelled = true
+    }
+  }, [client, onError, reference])
+
+  const save = async () => {
+    setStatus("saving")
+    setError(null)
+    try {
+      const snapshot = await client.write(reference, content)
+      setSavedContent(snapshot.content)
+      setStatus("ready")
+      setRevision((value) => value + 1)
+      onSaved?.(snapshot)
+    } catch (cause) {
+      const next = asError(cause)
+      setError(next.message)
+      setStatus("error")
+      onError?.(next)
+    }
+  }
+
+  const wrapper = className ? `gb-source-file-editor ${className}` : "gb-source-file-editor"
+  return (
+    <section className={wrapper} data-docstream-source-file-editor="">
+      <header className="gb-source-file-editor-header">
+        <FileCode2 className="size-4" />
+        <code>{reference.mount}:{reference.path}#{reference.exportName}</code>
+        <button type="button" disabled={status === "loading" || status === "saving" || content === savedContent} onClick={() => void save()}>
+          <Save className="size-3.5" /> {status === "saving" ? "Saving…" : "Save file"}
+        </button>
+      </header>
+      {error ? <pre className="gb-source-file-editor-error">{error}</pre> : null}
+      <textarea value={content} onChange={(event) => setContent(event.target.value)} disabled={status === "loading"} spellCheck={false} aria-label={`Edit ${reference.path}`} />
+      {preview ? <SourcePreview key={revision} reference={reference} client={client} /> : null}
+    </section>
+  )
+}

package/src/editor/convert.ts

@@ -110,6 +110,17 @@ function blockToPM(b: Block): PMNode {
     }
     case "content-ref":
       return { type: "gbContentRef", attrs: { url: b.url, label: plainText(b.children) } }
+    case "source-ref":
+      return {
+        type: "gbSourceRef",
+        attrs: {
+          mount: b.mount,
+          path: b.path,
+          exportName: b.exportName,
+          kind: b.kind,
+          title: b.title ?? "",
+        },
+      }
     case "columns":
       return {
         type: "gbColumns",
@@ -282,6 +293,15 @@ function pmToBlock(n: PMNode): Block | null {
         url: String(n.attrs?.url ?? ""),
         children: [{ type: "text", text: String(n.attrs?.label ?? "") }],
       }
+    case "gbSourceRef":
+      return {
+        type: "source-ref",
+        mount: String(n.attrs?.mount ?? "source"),
+        path: String(n.attrs?.path ?? ""),
+        exportName: String(n.attrs?.exportName ?? "default"),
+        kind: n.attrs?.kind === "story" ? "story" : "component",
+        ...(n.attrs?.title ? { title: String(n.attrs.title) } : {}),
+      }
     case "gbColumns":
       return {
         type: "columns",

package/src/editor/nodes.tsx

@@ -13,6 +13,7 @@ import {
   ChevronDown,
   Info,
   Link2,
+  FileCode2,
   Plus,
   X,
   XCircle,
@@ -21,7 +22,8 @@ import {
 import { resolveAsset } from "@brett_lamy/docstream/assets"
 import { OpenApiOperation } from "@brett_lamy/docstream/openapi"
 import type { HintStyle } from "@brett_lamy/docstream/gitbook"
-import { ReplayPreview, VideoEmbed, isReplayQaUrl } from "@brett_lamy/docstream"
+import { ReplayPreview, isReplayQaUrl } from "@brett_lamy/docstream/replay"
+import { VideoEmbed } from "@brett_lamy/docstream/video"
 
 // ---------- Hint ----------
 
@@ -425,6 +427,54 @@ export const GbContentRef = Node.create({
   },
 })
 
+// ---------- Source ref ----------
+
+function SourceRefView({ node, updateAttributes, editor }: NodeViewProps) {
+  const editable = editor.isEditable
+  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>
+  )
+}
+
+export const GbSourceRef = Node.create({
+  name: "gbSourceRef",
+  group: "block",
+  atom: true,
+  addAttributes() {
+    return {
+      mount: { default: "source" },
+      path: { default: "" },
+      exportName: { default: "default" },
+      kind: { default: "component" },
+      title: { default: "" },
+    }
+  },
+  parseHTML() {
+    return [{ tag: "div[data-gb-source-ref]" }]
+  },
+  renderHTML({ HTMLAttributes, node }) {
+    return ["div", mergeAttributes(HTMLAttributes, { "data-gb-source-ref": `${node.attrs.mount}:${node.attrs.path}` })]
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(SourceRefView)
+  },
+})
+
 // ---------- Columns ----------
 
 export const GbColumns = Node.create({
@@ -790,6 +840,7 @@ export const gitbookNodes = [
   GbStep,
   GbEmbed,
   GbContentRef,
+  GbSourceRef,
   GbColumns,
   GbColumn,
   GbFigure,

package/src/index.ts

@@ -12,3 +12,5 @@ export { SlashMenu, createSlashMenu, SLASH_ITEMS } from "./editor/slash-menu"
 export type { SlashItem } from "./editor/slash-menu"
 export { ReactDemoEditor } from "./editor/ReactDemoEditor"
 export type { ReactDemoEditorProps } from "./editor/ReactDemoEditor"
+export { SourceFileEditor } from "./editor/SourceFileEditor"
+export type { SourceFileEditorProps } from "./editor/SourceFileEditor"

package/src/styles.css

@@ -48,6 +48,65 @@
   color: var(--gb-text);
 }
 
+.gb-source-ref,
+.gb-source-file-editor-header {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.gb-source-ref {
+  border: 1px solid var(--gb-border);
+  border-radius: var(--gb-radius);
+  padding: 0.65rem 0.8rem;
+  background: var(--gb-muted);
+}
+
+.gb-source-ref-path {
+  flex: 1;
+}
+
+.gb-source-ref-mount,
+.gb-source-ref-export {
+  width: 8rem;
+}
+
+.gb-source-file-editor {
+  border: 1px solid var(--gb-border);
+  border-radius: var(--gb-radius);
+  overflow: hidden;
+}
+
+.gb-source-file-editor-header {
+  padding: 0.55rem 0.7rem;
+  background: var(--gb-muted);
+}
+
+.gb-source-file-editor-header button {
+  margin-left: auto;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+}
+
+.gb-source-file-editor > textarea {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 16rem;
+  border: 0;
+  border-top: 1px solid var(--gb-border);
+  border-bottom: 1px solid var(--gb-border);
+  padding: 0.8rem;
+  resize: vertical;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+.gb-source-file-editor-error {
+  color: var(--gb-danger-foreground, #b42318);
+  padding: 0.6rem 0.8rem;
+  white-space: pre-wrap;
+}
+
 /* lucide icon sizing (the node views use size-* utility classes) */
 .gb .size-3 { width: 12px; height: 12px; }
 .gb .size-3\.5 { width: 14px; height: 14px; }
@@ -559,9 +618,9 @@
 
 .gb-react-demo-editor {
   overflow: hidden;
-  border: 1px solid var(--gb-border, var(--border));
+  border: 1px solid var(--gb-border, var(--border, #e4e4e7));
   border-radius: 12px;
-  background: var(--gb-panel, var(--card));
+  background: var(--gb-panel, var(--card, #ffffff));
 }
 .gb-react-demo-editor-source {
   display: grid;
@@ -569,8 +628,8 @@
   min-height: 260px;
 }
 .gb-react-demo-files {
-  border-right: 1px solid var(--gb-border, var(--border));
-  background: var(--gb-muted, var(--muted));
+  border-right: 1px solid var(--gb-border, var(--border, #e4e4e7));
+  background: var(--gb-muted, var(--muted, #f4f4f5));
 }
 .gb-react-demo-files-header,
 .gb-react-demo-editor-toolbar {
@@ -579,19 +638,19 @@
   gap: 8px;
   min-height: 40px;
   padding: 8px 10px;
-  border-bottom: 1px solid var(--gb-border, var(--border));
+  border-bottom: 1px solid var(--gb-border, var(--border, #e4e4e7));
   font-size: 12px;
 }
 .gb-react-demo-files-header svg {
   margin-left: auto;
-  color: var(--gb-muted-foreground, var(--muted-foreground));
+  color: var(--gb-muted-foreground, var(--muted-foreground, #71717a));
 }
 .gb-react-demo-file {
   display: block;
   width: 100%;
   padding: 8px 10px;
   overflow: hidden;
-  color: var(--gb-muted-foreground, var(--muted-foreground));
+  color: var(--gb-muted-foreground, var(--muted-foreground, #71717a));
   font-family: ui-monospace, Menlo, monospace;
   font-size: 11px;
   text-align: left;
@@ -599,8 +658,8 @@
   white-space: nowrap;
 }
 .gb-react-demo-file-active {
-  color: var(--gb-panel-foreground, var(--foreground));
-  background: var(--gb-panel, var(--card));
+  color: var(--gb-panel-foreground, var(--foreground, #18181b));
+  background: var(--gb-panel, var(--card, #ffffff));
 }
 .gb-react-demo-editor-pane {
   display: flex;
@@ -609,7 +668,7 @@
 }
 .gb-react-demo-editor-toolbar code {
   overflow: hidden;
-  color: var(--gb-muted-foreground, var(--muted-foreground));
+  color: var(--gb-muted-foreground, var(--muted-foreground, #71717a));
   text-overflow: ellipsis;
   white-space: nowrap;
 }
@@ -618,10 +677,10 @@
   align-items: center;
   gap: 5px;
   margin-left: auto;
-  border: 1px solid var(--gb-border, var(--border));
+  border: 1px solid var(--gb-border, var(--border, #e4e4e7));
   border-radius: 6px;
   padding: 4px 8px;
-  color: var(--gb-panel-foreground, var(--foreground));
+  color: var(--gb-panel-foreground, var(--foreground, #18181b));
   font-size: 11px;
 }
 .gb-react-demo-preview-button:disabled { opacity: 0.5; }
@@ -633,15 +692,15 @@
   border: 0;
   padding: 14px;
   outline: none;
-  color: var(--gb-panel-foreground, var(--foreground));
-  background: var(--gb-panel, var(--card));
+  color: var(--gb-panel-foreground, var(--foreground, #18181b));
+  background: var(--gb-panel, var(--card, #ffffff));
   font-family: ui-monospace, Menlo, monospace;
   font-size: 12px;
   line-height: 1.6;
 }
 .gb-react-demo-editor-empty {
   padding: 18px;
-  color: var(--gb-muted-foreground, var(--muted-foreground));
+  color: var(--gb-muted-foreground, var(--muted-foreground, #71717a));
   font-size: 12px;
   text-align: center;
 }
@@ -651,7 +710,7 @@
     display: flex;
     overflow-x: auto;
     border-right: 0;
-    border-bottom: 1px solid var(--gb-border, var(--border));
+    border-bottom: 1px solid var(--gb-border, var(--border, #e4e4e7));
   }
   .gb-react-demo-files-header { flex: 0 0 auto; border-bottom: 0; }
   .gb-react-demo-file { width: auto; flex: 0 0 auto; }