@brett_lamy/docstream-editor 0.1.0 → 0.3.1

package/README.md

@@ -0,0 +1,174 @@
+# @brett_lamy/docstream-editor
+
+TipTap editor components for Docstream GitBook-style markdown documents.
+
+`@brett_lamy/docstream-editor` provides the editable layer for the same document model rendered by `@brett_lamy/docstream`. It is intended for docs apps that need rich editing while preserving GitBook-flavored markdown blocks for preview, storage, and AI stream rendering.
+
+## Features
+
+- Controlled React editor component for GitBook-style markdown.
+- TipTap extensions for common writing flows.
+- Conversion helpers between the Docstream AST and TipTap JSON.
+- Slash menu for inserting supported blocks.
+- Code block support through `lowlight`.
+- Table, task list, heading, quote, and inline formatting support.
+- Preserves Docstream/GitBook block semantics when converting back to markdown.
+
+## Installation
+
+```sh
+npm install @brett_lamy/docstream-editor @brett_lamy/docstream react
+```
+
+React is a peer dependency. `@brett_lamy/docstream` is a runtime dependency because the editor uses the same parser, serializer, OpenAPI rendering, and asset helpers.
+
+## Basic Setup
+
+Import both package styles near your app entrypoint:
+
+```ts
+import "@brett_lamy/docstream/styles.css"
+import "@brett_lamy/docstream-editor/styles.css"
+```
+
+If your TypeScript app checks CSS side-effect imports, include Vite's standard environment declaration or an equivalent CSS module declaration:
+
+```ts
+/// <reference types="vite/client" />
+```
+
+## Usage
+
+`GitbookEditor` is a controlled component. Pass the current markdown and receive updated markdown through `onChange`.
+
+```tsx
+import { useState } from "react"
+import { GitbookEditor } from "@brett_lamy/docstream-editor"
+import "@brett_lamy/docstream/styles.css"
+import "@brett_lamy/docstream-editor/styles.css"
+
+const initialMarkdown = `# Getting started
+
+{% hint style="info" %}
+Type / to insert supported blocks.
+{% endhint %}
+`
+
+export function EditorPage() {
+  const [markdown, setMarkdown] = useState(initialMarkdown)
+
+  return (
+    <GitbookEditor
+      markdown={markdown}
+      onChange={setMarkdown}
+    />
+  )
+}
+```
+
+## Props
+
+```ts
+export interface GitbookEditorProps {
+  markdown: string
+  onChange: (markdown: string) => void
+}
+```
+
+- `markdown`: Source markdown to load into the editor.
+- `onChange`: Called with serialized markdown whenever TipTap content changes.
+
+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.
+
+## Supported Editing Surface
+
+The editor supports common ProseMirror/TipTap content plus GitBook-flavored blocks from Docstream.
+
+- Headings
+- Paragraphs
+- Bold, italic, strike, inline code, and links
+- Bullet, ordered, and task lists
+- Blockquotes
+- Code blocks
+- Tables
+- Hints
+- Tabs
+- Expandables
+- Steppers
+- Embeds
+- Content 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.
+
+## Slash Menu
+
+The editor includes a slash menu extension for inserting supported block structures. Type `/` in an empty paragraph to open block insertion options.
+
+## Conversion Helpers
+
+Use the conversion helpers when you need to inspect or transform editor state directly.
+
+```ts
+import { astToTiptap, tiptapToAst } from "@brett_lamy/docstream-editor"
+import { parseMarkdown, serializeMarkdown } from "@brett_lamy/docstream"
+
+const ast = parseMarkdown(markdown)
+const tiptapJson = astToTiptap(ast)
+const markdownAgain = serializeMarkdown(tiptapToAst(tiptapJson))
+```
+
+Exports:
+
+- `GitbookEditor`
+- `GitbookEditorProps`
+- `astToTiptap`
+- `tiptapToAst`
+- `PMNode`
+
+## Styling and Theming
+
+The editor CSS is designed to sit beside `@brett_lamy/docstream/styles.css` and inherit the same application theme tokens. In a shadcn-style app, define your theme variables globally and import both CSS entrypoints once.
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+  --border: 214.3 31.8% 91.4%;
+  --muted: 210 40% 96.1%;
+  --muted-foreground: 215.4 16.3% 46.9%;
+  --primary: 221.2 83.2% 53.3%;
+}
+```
+
+The editor exposes classes such as `gb`, `gb-toolbar`, `gb-tool`, `gb-tool-active`, and `gb-content` for host app overrides.
+
+## Bundler Notes
+
+This release ships TypeScript and TSX source through ESM exports:
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./styles.css": "./src/styles.css"
+  }
+}
+```
+
+It is validated with Vite and modern TypeScript `moduleResolution: "Bundler"`. Plain Node.js, CommonJS, or tooling that does not transpile TypeScript in dependencies may need a future precompiled JS build.
+
+## Renderer Pairing
+
+For read-only previews or AI stream output, pair this package with `@brett_lamy/docstream`:
+
+```tsx
+import { GitbookStreamdown } from "@brett_lamy/docstream"
+
+<GitbookStreamdown markdown={markdown} isStreaming={false} />
+```

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@brett_lamy/docstream-editor",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "TipTap editor for Docstream GitBook-style markdown documents.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "files": [
-    "src"
+    "src",
+    "README.md"
   ],
   "sideEffects": [
     "**/*.css"
@@ -19,19 +20,24 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
+    "@brett_lamy/docstream": "0.3.0",
+    "lowlight": "^3.3.0",
+    "lucide-react": "^1.17.0"
+  },
+  "peerDependencies": {
     "@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",
-    "@brett_lamy/docstream": "0.1.0",
-    "lowlight": "^3.3.0",
-    "lucide-react": "^1.17.0"
-  },
-  "peerDependencies": {
     "react": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BLamy/docstream-editor.git"
   }
 }

package/src/editor/Editor.tsx

@@ -1,9 +1,6 @@
 import { useEffect, useRef } from "react"
 import { EditorContent, useEditor, type Editor as TiptapEditor } from "@tiptap/react"
-import StarterKit from "@tiptap/starter-kit"
-import Placeholder from "@tiptap/extension-placeholder"
-import { TaskItem, TaskList } from "@tiptap/extension-list"
-import { Table, TableCell, TableHeader, TableRow } from "@tiptap/extension-table"
+import type { AnyExtension } from "@tiptap/core"
 import {
   Bold,
   Code as CodeIcon,
@@ -13,23 +10,39 @@ import {
   Strikethrough,
 } from "lucide-react"
 
-import { parseMarkdown, serializeMarkdown } from "@brett_lamy/docstream"
+import { parseMarkdown, serializeMarkdown } from "@brett_lamy/docstream/gitbook"
 import { astToTiptap, tiptapToAst, type PMNode } from "./convert"
-import { GbCodeBlock, gitbookNodes } from "./nodes"
-import { SlashMenu } from "./slash-menu"
+import { createGitbookExtensions } from "./extensions"
+import type { SlashItem } from "./slash-menu"
 
 export interface GitbookEditorProps {
-  markdown: string
-  onChange: (markdown: string) => void
+  /** Markdown source. When provided, the editor stays in sync with it (controlled). */
+  markdown?: string
+  /** Called with serialized GitBook markdown on every edit. */
+  onChange?: (markdown: string) => void
+  /** Show the built-in formatting toolbar (default true). */
+  toolbar?: boolean
+  /** Built-in "/" slash menu: true (default), false, or a custom item list. */
+  slashMenu?: boolean | { items?: SlashItem[] }
+  /** Whether the document is editable (default true). */
+  editable?: boolean
+  /** Placeholder shown in an empty document. */
+  placeholder?: string
+  /** Class applied to the editor wrapper. */
+  className?: string
+  /** Focus the editor on mount. */
+  autofocus?: boolean
+  /**
+   * Disable StarterKit's undo/redo — required when supplying a Yjs Collaboration
+   * extension via `extensions`, which manages shared history itself.
+   */
+  disableHistory?: boolean
+  /** Extra TipTap extensions appended last (e.g. Collaboration, CollaborationCursor). */
+  extensions?: AnyExtension[]
+  /** Receive the underlying TipTap editor instance (and null on teardown). */
+  onEditorReady?: (editor: TiptapEditor | null) => void
 }
 
-// Carries GitBook's data-view (e.g. "cards") through the editor untouched.
-const GbTable = Table.extend({
-  addAttributes() {
-    return { ...this.parent?.(), view: { default: null } }
-  },
-})
-
 function ToolbarButton({
   onClick,
   active,
@@ -90,45 +103,60 @@ function Toolbar({ editor }: { editor: TiptapEditor }) {
   )
 }
 
-export function GitbookEditor({ markdown, onChange }: GitbookEditorProps) {
+export function GitbookEditor({
+  markdown,
+  onChange,
+  toolbar = true,
+  slashMenu = true,
+  editable = true,
+  placeholder,
+  className,
+  autofocus = false,
+  disableHistory,
+  extensions,
+  onEditorReady,
+}: GitbookEditorProps) {
   // Tracks the markdown the editor itself produced, so external updates
   // (file switches) reset content but our own onChange echoes don't.
   const lastEmitted = useRef<string | null>(null)
+  const controlled = markdown !== undefined
 
   const editor = useEditor({
-    extensions: [
-      StarterKit.configure({ codeBlock: false }),
-      GbCodeBlock,
-      TaskList,
-      TaskItem.configure({ nested: true }),
-      GbTable.configure({ resizable: false }),
-      TableRow,
-      TableHeader,
-      TableCell,
-      Placeholder.configure({ placeholder: "Write, or type / to insert a block…" }),
-      SlashMenu,
-      ...gitbookNodes,
-    ],
-    content: astToTiptap(parseMarkdown(markdown)),
+    editable,
+    autofocus,
+    extensions: createGitbookExtensions({
+      ...(placeholder !== undefined ? { placeholder } : {}),
+      slashMenu,
+      ...(disableHistory !== undefined ? { disableHistory } : {}),
+      ...(extensions ? { extensions } : {}),
+    }),
+    ...(controlled ? { content: astToTiptap(parseMarkdown(markdown as string)) } : {}),
     onUpdate({ editor }) {
+      if (!onChange) return
       const md = serializeMarkdown(tiptapToAst(editor.getJSON() as PMNode))
       lastEmitted.current = md
       onChange(md)
     },
   })
 
+  // Surface the editor instance to the host (for awareness, commands, etc.).
+  useEffect(() => {
+    onEditorReady?.(editor ?? null)
+    return () => onEditorReady?.(null)
+  }, [editor, onEditorReady])
+
   useEffect(() => {
-    if (!editor) return
+    if (!editor || !controlled) return
     if (markdown === lastEmitted.current) return
-    lastEmitted.current = markdown
-    editor.commands.setContent(astToTiptap(parseMarkdown(markdown)), { emitUpdate: false })
-  }, [editor, markdown])
+    lastEmitted.current = markdown as string
+    editor.commands.setContent(astToTiptap(parseMarkdown(markdown as string)), { emitUpdate: false })
+  }, [editor, controlled, markdown])
 
   if (!editor) return null
 
   return (
-    <div className="gb">
-      <Toolbar editor={editor} />
+    <div className={className ? `gb ${className}` : "gb"}>
+      {toolbar && <Toolbar editor={editor} />}
       <EditorContent editor={editor} className="gb-content" />
     </div>
   )

package/src/editor/ReactDemoEditor.tsx

@@ -0,0 +1,108 @@
+import { useEffect, useState } from "react"
+import { FileCode2, Play } from "lucide-react"
+
+import { ReactCodePreview } from "@brett_lamy/docstream"
+
+export interface ReactDemoEditorProps {
+  /** Source files keyed by their project-relative or absolute paths. */
+  files: Readonly<Record<string, string>>
+  /** Vite entry file. Defaults to `/src/main.jsx`. */
+  entry?: string
+  /** Preview height after the user runs the demo. */
+  height?: number | string
+  className?: string
+  /** Called whenever a file is edited. */
+  onChange?: (files: Record<string, string>) => void
+}
+
+function nextFile(files: Readonly<Record<string, string>>): string {
+  return Object.keys(files).sort()[0] ?? ""
+}
+
+/** A small multi-file source editor paired with the Docstream React preview. */
+export function ReactDemoEditor({
+  files,
+  entry = "/src/main.jsx",
+  height = 320,
+  className,
+  onChange,
+}: 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 [previewRevision, setPreviewRevision] = useState(0)
+
+  useEffect(() => {
+    setDraftFiles({ ...files })
+    setSelectedFile((current) => (current && files[current] !== undefined ? current : nextFile(files)))
+  }, [files])
+
+  const updateFile = (content: string) => {
+    if (!selectedFile) return
+    const next = { ...draftFiles, [selectedFile]: content }
+    setDraftFiles(next)
+    onChange?.(next)
+  }
+
+  const wrapperClass = className ? `gb-react-demo-editor ${className}` : "gb-react-demo-editor"
+
+  return (
+    <section className={wrapperClass} data-docstream-react-demo-editor="">
+      <div className="gb-react-demo-editor-source">
+        <aside className="gb-react-demo-files" aria-label="Demo files">
+          <div className="gb-react-demo-files-header">
+            <span>Files</span>
+            <FileCode2 className="size-4" />
+          </div>
+          {Object.keys(draftFiles)
+            .sort()
+            .map((path) => (
+              <button
+                type="button"
+                key={path}
+                className={path === selectedFile ? "gb-react-demo-file gb-react-demo-file-active" : "gb-react-demo-file"}
+                onClick={() => setSelectedFile(path)}
+              >
+                {path.replace(/^\//, "")}
+              </button>
+            ))}
+        </aside>
+        <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>
+          </div>
+          <textarea
+            className="gb-react-demo-textarea"
+            value={selectedFile ? draftFiles[selectedFile] ?? "" : ""}
+            onChange={(event) => updateFile(event.target.value)}
+            spellCheck={false}
+            disabled={!selectedFile}
+            aria-label={selectedFile ? `Edit ${selectedFile}` : "No file selected"}
+          />
+        </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/convert.ts

@@ -1,4 +1,4 @@
-import { plainText, type Block, type DocumentNode, type Inline, type ListItemNode } from "@brett_lamy/docstream"
+import { plainText, type Block, type DocumentNode, type Inline, type ListItemNode } from "@brett_lamy/docstream/gitbook"
 
 // TipTap/ProseMirror JSON shape (loosely typed on purpose)
 export interface PMNode {
@@ -63,7 +63,13 @@ function blockToPM(b: Block): PMNode {
     case "code":
       return {
         type: "codeBlock",
-        attrs: { language: b.language, title: b.title, lineNumbers: b.lineNumbers },
+        attrs: {
+          language: b.language,
+          title: b.title,
+          lineNumbers: b.lineNumbers,
+          live: !!b.live,
+          entry: b.entry ?? null,
+        },
         content: b.code ? [{ type: "text", text: b.code }] : [],
       }
     case "hint":
@@ -215,6 +221,8 @@ function pmToBlock(n: PMNode): Block | null {
         language: (n.attrs?.language as string) || null,
         title: (n.attrs?.title as string) || null,
         lineNumbers: !!n.attrs?.lineNumbers,
+        live: !!n.attrs?.live,
+        entry: (n.attrs?.entry as string) || null,
         code: n.content?.map((c) => c.text ?? "").join("") ?? "",
       }
     case "gbHint":

package/src/editor/extensions.ts

@@ -0,0 +1,74 @@
+import StarterKit from "@tiptap/starter-kit"
+import Placeholder from "@tiptap/extension-placeholder"
+import { TaskItem, TaskList } from "@tiptap/extension-list"
+import { Table, TableCell, TableHeader, TableRow } from "@tiptap/extension-table"
+import { getSchema, type AnyExtension } from "@tiptap/core"
+import type { Schema } from "@tiptap/pm/model"
+import { GbCodeBlock, gitbookNodes } from "./nodes"
+import { SlashMenu, createSlashMenu, type SlashItem } from "./slash-menu"
+
+// Carries GitBook's data-view (e.g. "cards") through the editor untouched.
+export const GbTable = Table.extend({
+  addAttributes() {
+    return { ...this.parent?.(), view: { default: null } }
+  },
+})
+
+export interface GitbookExtensionOptions {
+  placeholder?: string
+  /** Built-in "/" slash menu: true (default), false, or a custom item list. */
+  slashMenu?: boolean | { items?: SlashItem[] }
+  /**
+   * Disable StarterKit's built-in undo/redo. Required when wiring Yjs
+   * Collaboration, which provides its own shared history.
+   */
+  disableHistory?: boolean
+  /** Extra TipTap extensions appended last (e.g. Collaboration, CollaborationCursor). */
+  extensions?: AnyExtension[]
+}
+
+/**
+ * The full GitBook editing extension set, composable by host apps. Use this to
+ * build a custom `useEditor(...)` (e.g. with Yjs collaboration) instead of the
+ * batteries-included `GitbookEditor` component.
+ */
+export function createGitbookExtensions(options: GitbookExtensionOptions = {}): AnyExtension[] {
+  const {
+    placeholder = "Write, or type / to insert a block…",
+    slashMenu = true,
+    disableHistory = false,
+    extensions = [],
+  } = options
+
+  const list: AnyExtension[] = [
+    StarterKit.configure({
+      codeBlock: false,
+      ...(disableHistory ? { undoRedo: false } : {}),
+    }),
+    GbCodeBlock,
+    TaskList,
+    TaskItem.configure({ nested: true }),
+    GbTable.configure({ resizable: false }),
+    TableRow,
+    TableHeader,
+    TableCell,
+    Placeholder.configure({ placeholder }),
+    ...gitbookNodes,
+  ]
+
+  if (slashMenu) {
+    list.push(slashMenu === true ? SlashMenu : createSlashMenu(slashMenu.items))
+  }
+
+  list.push(...extensions)
+  return list
+}
+
+/**
+ * The ProseMirror schema for GitBook documents — identical to what GitbookEditor
+ * uses. Hosts wiring Yjs collaboration (y-prosemirror) need this exact schema to
+ * convert between a Y.XmlFragment and ProseMirror/markdown safely.
+ */
+export function getGitbookSchema(): Schema {
+  return getSchema(createGitbookExtensions({ slashMenu: false }))
+}

package/src/editor/nodes.tsx

@@ -18,7 +18,10 @@ import {
   XCircle,
 } from "lucide-react"
 
-import { OpenApiOperation, resolveAsset, type HintStyle } 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 { ReplayPreview, VideoEmbed, isReplayQaUrl } from "@brett_lamy/docstream"
 
 // ---------- Hint ----------
 
@@ -299,13 +302,19 @@ function embedPreview(url: string): string | null {
   return null
 }
 
+function isDirectVideo(url: string): boolean {
+  return /\.(?:mp4|webm|ogg)(?:[?#]|$)/i.test(url)
+}
+
 function EmbedView({ node, updateAttributes, editor }: NodeViewProps) {
   const url = node.attrs.url as string
   const preview = embedPreview(url)
   return (
     <NodeViewWrapper className="gb-embed" contentEditable={false}>
-      {preview ? (
-        <iframe className="gb-embed-frame" src={preview} title={url} allowFullScreen />
+      {isReplayQaUrl(url) ? (
+        <ReplayPreview source={url} title="Replay preview" />
+      ) : preview || isDirectVideo(url) ? (
+        <VideoEmbed src={preview ?? url} className="gb-embed-frame" title={url} />
       ) : (
         <a className="gb-embed-link" href={url} target="_blank" rel="noreferrer">
           <Link2 className="size-4" /> {url || "Embed URL…"}
@@ -534,11 +543,28 @@ function CodeView({ node, updateAttributes, editor }: NodeViewProps) {
               />
               #
             </label>
+            <label className="gb-code-live">
+              <input
+                type="checkbox"
+                checked={!!node.attrs.live}
+                onChange={(e) => updateAttributes({ live: e.target.checked })}
+              />
+              Live
+            </label>
+            {node.attrs.live && (
+              <input
+                className="gb-inline-input gb-code-entry"
+                value={node.attrs.entry ?? ""}
+                placeholder="entry (e.g. src/main.jsx)"
+                onChange={(e) => updateAttributes({ entry: e.target.value || null })}
+              />
+            )}
           </>
         ) : (
           <>
             {node.attrs.title && <span className="gb-code-title">{node.attrs.title}</span>}
             {node.attrs.language && <span className="gb-code-lang">{node.attrs.language}</span>}
+            {node.attrs.live && <span className="gb-code-live-badge">Live</span>}
           </>
         )}
       </div>
@@ -555,6 +581,8 @@ export const GbCodeBlock = CodeBlockLowlight.extend({
       ...this.parent?.(),
       title: { default: null },
       lineNumbers: { default: false },
+      live: { default: false },
+      entry: { default: null },
     }
   },
   addNodeView() {