@grandaniel/vue-markdown-editor 1.1.3-dev.ed12560 → 1.2.0-dev.3b1fd30

package/README.md

@@ -5,9 +5,13 @@
 
 # @grandaniel/vue-markdown-editor
 
-> A block-based, Notion-like Markdown editor for Vue 3. UI-first. Powered by [TipTap](https://tiptap.dev/).
+> A block-based, Notion-like Markdown editor **and** SSR-safe renderer for Vue 3. UI-first. Powered by [TipTap](https://tiptap.dev/).
 
-**@grandaniel/vue-markdown-editor** is a rich block-editing experience where every Markdown element — headlines, paragraphs, lists, images — is its own independently editable, draggable block. Built for content-first workflows: write, reorder, and format with keyboard shortcuts and an always-visible drag handle.
+**@grandaniel/vue-markdown-editor** provides two complementary packages:
+
+- **Editor** — A rich block-editing experience where every Markdown element — headlines, paragraphs, lists, images — is its own independently editable, draggable block. Built for content-first workflows: write, reorder, and format with keyboard shortcuts and an always-visible drag handle.
+
+- **Renderer** — A lightweight, SSR-safe component that renders Markdown strings to semantic HTML. Uses the same `remark-parse` pipeline as the editor, so custom module blocks render identically. Fully customizable: override any default render component with your own Vue components.
 
 Images are first-class citizens: paste an image to auto-upload, then edit its **src**, **alt text**, and **caption** in a dedicated modal. The editor serializes back to clean Markdown automatically.
 
@@ -17,10 +21,16 @@ Images are first-class citizens: paste an image to auto-upload, then edit its **
 
 - [Who uses it](#who-uses-it)
 - [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Keyboard Shortcuts](#keyboard-shortcuts)
-- [Image Upload](#image-upload)
-- [API Reference](#api-reference)
+- [Editor](#editor)
+  - [Quick Start](#editor-quick-start)
+  - [Keyboard Shortcuts](#keyboard-shortcuts)
+  - [Image Upload](#image-upload)
+  - [API Reference](#editor-api-reference)
+- [Renderer](#renderer)
+  - [Quick Start](#renderer-quick-start)
+  - [Custom Render Components](#custom-render-components)
+  - [API Reference](#renderer-api-reference)
+- [Exported Types & Utilities](#exported-types--utilities)
 - [Custom Styling](#custom-styling)
 - [Supply Chain Security](#supply-chain-security)
 - [Contributing](#contributing)
@@ -46,19 +56,21 @@ npm install @grandaniel/vue-markdown-editor
 > **Peer dependency:** Vue `^3.5.0`  
 > **Node:** `>=22`  
 
-Import the component **and** the stylesheet:
+Import the components **and** the stylesheet:
 
 ```ts
-import { MarkdownEditor, useMarkdownEditor } from "@grandaniel/vue-markdown-editor";
+import { MarkdownEditor, MarkdownRenderer, useMarkdownEditor, useMarkdownRenderer } from "@grandaniel/vue-markdown-editor";
 import "@grandaniel/vue-markdown-editor/style.css";
 ```
 
 ---
 
-## Quick Start
+## Editor
 
 The editor is driven by a composable: `useMarkdownEditor()` creates the reactive state, and `<MarkdownEditor>` renders it.
 
+### Editor Quick Start
+
 ```vue
 <script setup lang="ts">
 import { ref } from "vue";
@@ -81,7 +93,7 @@ const focusedNode = ref<MarkdownAstNode | null>(null);
 </template>
 ```
 
-### Reading the output
+#### Reading the output
 
 The composable keeps the raw Markdown in sync automatically. Read it at any time:
 
@@ -98,7 +110,7 @@ editor.markdownContent.value = "## New heading\n\nFresh content.";
 
 ---
 
-## Keyboard Shortcuts
+### Keyboard Shortcuts
 
 | Key | Action |
 |---|---|
@@ -108,17 +120,17 @@ editor.markdownContent.value = "## New heading\n\nFresh content.";
 | <kbd>Delete</kbd> (empty block) | Delete the block, focus stays at same index |
 | Click blank area | Append a new empty paragraph at the bottom |
 
-### Auto type‑detection
+#### Auto type‑detection
 
 Type `# `, `## `, or `### ` at the start of a paragraph and the block auto‑converts to the matching heading level.
 
 ---
 
-## Image Upload
+### Image Upload
 
 Images are first-class blocks with **src**, **alt text**, and **caption** fields. Right‑click any image → **Edit Attributes** to open the editing modal.
 
-### Paste‑to‑upload
+#### Paste‑to‑upload
 
 Pass an `imageUploadFunction` prop — any pasted image (`Ctrl+V`) from the clipboard will be sent through your upload handler and inserted as a new image block:
 
@@ -156,9 +168,9 @@ caption: Photo taken during the 2026 summit
 
 ---
 
-## API Reference
+### Editor API Reference
 
-### `useMarkdownEditor(initialContent?: string)`
+#### `useMarkdownEditor(initialContent?: string)`
 
 Returns a reactive editor instance:
 
@@ -172,7 +184,7 @@ Returns a reactive editor instance:
 | `replaceNodeType(node, newType)` | `(node: MarkdownAstNode, type: MarkdownNodeType) => { newNode, index } \| null` | Convert between block types (e.g. paragraph → heading). |
 | `moveNode(from, to)` | `(fromIndex: number, toIndex: number) => void` | Programmatically reorder a block. |
 
-### `MarkdownEditor` props
+#### `MarkdownEditor` props
 
 | Prop | Type | Required | Description |
 |---|---|---|---|
@@ -180,40 +192,28 @@ Returns a reactive editor instance:
 | `focusedNode` | `MarkdownAstNode \| null` | — | For `v-model:focused-node` tracking. |
 | `imageUploadFunction` | `(file: File) => Promise<string>` | — | Async callback for paste‑to‑upload. |
 
-### `MarkdownEditor` emits
+#### `MarkdownEditor` emits
 
 | Event | Payload | Description |
 |---|---|---|
 | `update:focused-node` | `MarkdownAstNode \| null` | Fires when focus moves to a new block. |
 
-### `MarkdownEditor` slots
+#### `MarkdownEditor` slots
 
 | Slot | Description |
 |---|---|
 | `after-controls` | Injected inside every block, after the drag‑handle / add / delete controls. |
 
-### Exported types & utilities
-
-| Export | Kind |
-|---|---|
-| `MarkdownEditorInstance` | Type — return type of `useMarkdownEditor()`. |
-| `MarkdownAstNode` | Class — AST node with `id`, `type`, `componentState`, `editingState`. |
-| `MarkdownAstNodeType` | Enum — `PARAGRAPH`, `HEADLINE1`, `HEADLINE2`, `HEADLINE3`, `IMAGE`, `LIST`. |
-| `ImageNode` | Type alias — `MarkdownAstNode<MarkdownModuleImageState>`. |
-| `TextNode` | Type alias — `MarkdownAstNode<MarkdownModuleTextState>`. |
-| `TextishNodeType` | Type — union of `PARAGRAPH \| HEADLINE1 \| HEADLINE2 \| HEADLINE3 \| LIST`. |
-| `isTextNodeState(node)` | Type guard for text‑based nodes. |
-| `isTextNodeType(type)` | Type guard for text‑based node types. |
-| `MarkdownRenderer` | Component — renders Markdown to plain HTML. SSR‑safe. |
-
 ---
 
-## MarkdownRenderer
+## Renderer
 
-`<MarkdownRenderer>` converts a Markdown string to plain HTML. It uses the same `remark-parse` pipeline as the editor, so custom module blocks (like `"""MarkdownModuleImage"""`) render as rich `<figure>` elements automatically.
+`<MarkdownRenderer>` converts a Markdown string to semantic HTML. It uses the same `remark-parse` pipeline as the editor, so custom module blocks (like `"""MarkdownModuleImage"""`) render as rich `<figure>` elements automatically.
 
 The renderer is **SSR‑safe** — no browser APIs, no TipTap. It works in `nuxt generate`, `vite-ssg`, and any server‑side rendering context.
 
+### Renderer Quick Start
+
 ```vue
 <script setup lang="ts">
 import { MarkdownRenderer } from "@grandaniel/vue-markdown-editor";
@@ -238,7 +238,7 @@ caption: Photo caption
 </template>
 ```
 
-### Live preview alongside the editor
+#### Live preview alongside the editor
 
 Bind the editor's reactive `markdownContent` to the renderer:
 
@@ -257,11 +257,116 @@ const editor = useMarkdownEditor("# Start writing…");
 </template>
 ```
 
-### Props
+---
+
+### Custom Render Components
+
+You can override any default render component with your own Vue component. Use `useMarkdownRenderer()` to create a renderer instance, then call `overrideComponent()` to swap in your custom component for a specific node type.
+
+Each override is **strictly typed** — the replacement component must accept a `state` prop matching the correct state class for that node type (e.g. `MarkdownModuleImageState` for images, `MarkdownModuleTextState` for paragraphs and headings).
+
+#### Overriding the image render component
+
+```vue
+<script setup lang="ts">
+import {
+  MarkdownRenderer,
+  useMarkdownRenderer,
+  MarkdownAstNodeType,
+  type MarkdownModuleImageState,
+} from "@grandaniel/vue-markdown-editor";
+import CustomImageRender from "./CustomImageRender.vue";
+
+// Create a renderer instance and override the image component
+const renderer = useMarkdownRenderer();
+renderer.overrideComponent(MarkdownAstNodeType.IMAGE, CustomImageRender);
+
+const markdown = `"""MarkdownModuleImage
+src: https://example.com/photo.jpg
+alt: A scenic view
+caption: My custom caption
+"""
+`;
+</script>
+
+<template>
+  <MarkdownRenderer
+    :markdown="markdown"
+    :renderer="renderer"
+  />
+</template>
+```
+
+Your custom component receives the state as a typed prop:
+
+```vue
+<!-- CustomImageRender.vue -->
+<script setup lang="ts">
+import { type MarkdownModuleImageState } from "@grandaniel/vue-markdown-editor";
+
+defineProps<{ state: MarkdownModuleImageState }>();
+</script>
+
+<template>
+  <div class="my-custom-image-wrapper">
+    <img :src="state.src" :alt="state.alt" />
+    <span class="my-caption">{{ state.caption }}</span>
+  </div>
+</template>
+```
+
+#### Available node types and their state classes
+
+| Node Type | State Class | Prop Interface |
+|---|---|---|
+| `MarkdownAstNodeType.PARAGRAPH` | `MarkdownModuleTextState` | `{ text: string }` |
+| `MarkdownAstNodeType.HEADLINE1` | `MarkdownModuleTextState` | `{ text: string }` |
+| `MarkdownAstNodeType.HEADLINE2` | `MarkdownModuleTextState` | `{ text: string }` |
+| `MarkdownAstNodeType.HEADLINE3` | `MarkdownModuleTextState` | `{ text: string }` |
+| `MarkdownAstNodeType.LIST` | `MarkdownModuleListState` | `{ items: MarkdownModuleTextState[] }` |
+| `MarkdownAstNodeType.IMAGE` | `MarkdownModuleImageState` | `{ src: string; alt: string; caption: string }` |
+| `MarkdownAstNodeType.FILE` | `MarkdownModuleFileState` | `{ url: string; fileName: string; fileSize: number; mimeType: string; uploadError: string }` |
+
+---
+
+### Renderer API Reference
+
+#### `useMarkdownRenderer()`
+
+Returns a reactive renderer instance with a customizable component registry:
+
+| Member | Type | Description |
+|---|---|---|
+| `componentRegistry` | `Reactive<{ [K in MarkdownNodeType]: RenderComponent<RenderStateMap[K]> }>` | Reactive map of node types to their current render components. |
+| `overrideComponent(type, component)` | `<K extends MarkdownNodeType>(type: K, component: RenderComponent<RenderStateMap[K]>) => void` | Replace the render component for a given node type. Strictly typed — the component must accept the correct `state` prop. |
+
+#### `MarkdownRenderer` props
 
 | Prop | Type | Required | Description |
 |---|---|---|---|
 | `markdown` | `string` | ✓ | Raw Markdown string to render as HTML. |
+| `renderer` | `MarkdownRendererInstance` | — | Instance from `useMarkdownRenderer()`. Optional — when omitted, the built-in default render components are used. Provide this to supply custom render components via `overrideComponent()`. |
+
+---
+
+## Exported Types & Utilities
+
+| Export | Kind |
+|---|---|
+| `MarkdownEditorInstance` | Type — return type of `useMarkdownEditor()`. |
+| `MarkdownRendererInstance` | Type — return type of `useMarkdownRenderer()`. |
+| `MarkdownAstNode` | Class — AST node with `id`, `type`, `componentState`, `editingState`. |
+| `MarkdownAstNodeType` | Enum — `PARAGRAPH`, `HEADLINE1`, `HEADLINE2`, `HEADLINE3`, `IMAGE`, `LIST`, `FILE`. |
+| `ImageNode` | Type alias — `MarkdownAstNode<MarkdownModuleImageState>`. |
+| `TextNode` | Type alias — `MarkdownAstNode<MarkdownModuleTextState>`. |
+| `FileNode` | Type alias — `MarkdownAstNode<MarkdownModuleFileState>`. |
+| `TextishNodeType` | Type — union of `PARAGRAPH \| HEADLINE1 \| HEADLINE2 \| HEADLINE3 \| LIST`. |
+| `isTextNodeState(node)` | Type guard for text‑based nodes. |
+| `isTextNodeType(type)` | Type guard for text‑based node types. |
+| `RenderComponent<TState>` | Type — a Vue component that accepts `{ state: TState }` as props. |
+| `RenderStateMap` | Interface — maps each `MarkdownNodeType` to its state class for strict typing. |
+| `MarkdownModuleImageState` | Class — state for image nodes (`src`, `alt`, `caption`). |
+| `MarkdownModuleFileState` | Class — state for file nodes (`url`, `fileName`, `fileSize`, `mimeType`, `uploadError`). |
 
 ---
 
@@ -385,3 +490,122 @@ The dev server launches at `http://localhost:4010`. The entry point is `dev/App.
 ## License
 
 [ISC](LICENSE) © 2026 [danielgran](https://github.com/danielgran)
+
+All components use scoped SCSS. To override styles, use **global CSS** with higher specificity, or Vue's `:deep()` combinator from a parent component.
+
+### CSS class reference
+
+| Class | Applies to |
+|---|---|
+| `.markdown-editor` | Root editor container |
+| `.markdown-editor-module` | Individual block wrapper — `.is-focused` when active |
+| `.markdown-editor-module-controls` | Left control bar (drag handle + add/delete buttons) |
+| `.markdown-editor-module-content` | Content area inside a block |
+| `.markdown-editor-module-content-focused` | Content area when the block is focused |
+| `.markdown-editor-focus-controls` | Row containing drag‑handle, delete, and add buttons |
+| `.drag-handle` | SortableJS drag handle (⠿) |
+| `.focus-control-btn` | Delete / Add buttons in the control bar |
+| `.markdown-editor-context-menu` | Floating block context menu (`z-index: 1000`) |
+| `.markdown-editor-context-menu-block-item` | Full‑width context menu button |
+| `.markdown-editor-context-menu-inline-item` | Inline toolbar button (`.is-active` when toggled) |
+| `.markdown-editor-modal-overlay` | Modal backdrop (`z-index: 9999`) |
+| `.markdown-editor-modal` | Modal container |
+| `.markdown-editor-modal-header` | Modal title bar |
+| `.markdown-editor-modal-title` | Modal heading text |
+| `.markdown-editor-modal-close` | Close (✕) button |
+| `.markdown-editor-modal-body` | Modal content area |
+| `.markdown-editor-modal-footer` | Modal action bar |
+| `.markdown-editor-modal-button` | Base modal button |
+| `.markdown-editor-modal-button-primary` | Primary (Save) button — blue |
+| `.markdown-editor-modal-button-secondary` | Secondary (Cancel) button — gray |
+| `.markdown-module-image` | Image block wrapper |
+| `.markdown-module-image-form` | Image edit form inside the modal |
+| `.markdown-module-image-form-field` | Form field group (label + input) |
+
+### Styling TipTap content
+
+Each text‑based block hosts its own TinyMCE‑style TipTap editor. Target `.tiptap` inside a block's content area:
+
+```css
+/* Make all TipTap editors use your font */
+.markdown-editor-module-content .tiptap {
+  font-family: "Georgia", serif;
+  font-size: 1.1rem;
+  line-height: 1.8;
+}
+```
+
+### Do's
+
+- ✅ Import the stylesheet: `import "@grandaniel/vue-markdown-editor/style.css"`
+- ✅ Use **global** (unscoped) CSS or `:deep()` from a parent to override styles
+- ✅ Target `.tiptap` inside `.markdown-editor-module-content` for editor typography
+- ✅ Use `z-index` values above `1000` / `9999` for anything that must layer **above** context menus and modals
+
+### Don'ts
+
+- ❌ Don't rely on CSS custom properties — the editor uses hard‑coded Tailwind‑scale colors (grays and blues)
+- ❌ Don't override `z-index` on `.markdown-editor-context-menu` or `.markdown-editor-modal-overlay` — it will break layering
+- ❌ Don't use `display: contents` on `.markdown-editor-module` — it interferes with SortableJS drag logic
+- ❌ Don't set `outline: none` on `.markdown-editor-module-content` globally — the focus ring is intentional for keyboard navigation
+
+---
+
+## Supply Chain Security
+
+We take package integrity seriously.
+
+| Measure | Status |
+|---|---|
+| **npm package provenance** | ✅ Enabled — every publish includes [provenance attestations](https://docs.npmjs.com/generating-provenance-statements) via GitHub Actions and Sigstore. |
+| **CI/CD** | ✅ GitHub Actions runs `npm ci` → `npm test` → `npm run build` → publish on every push to `dev` and `main`. |
+| **Prerelease tags** | ✅ Non‑main branches publish with a `dev` dist‑tag (e.g. `1.1.3-dev.abc1234`). |
+| **Dependabot** | 🔜 Planned — automated dependency update PRs will be enabled via `.github/dependabot.yml`. |
+
+To verify provenance locally:
+
+```bash
+npm audit signatures
+```
+
+---
+
+## Contributing
+
+We welcome contributions! Please follow the guidelines below.
+
+### PR Policy
+
+1. **Fork** the repository and create a feature branch off `dev`.
+2. **Keep changes focused** — one feature or fix per PR.
+3. **Add tests** for any new functionality. The project uses [Vitest](https://vitest.dev/) + [`@vue/test-utils`](https://test-utils.vuejs.org/).
+4. **Run the full check** before pushing:
+
+   ```bash
+   npm ci
+   npm run test
+   npm run type-check
+   npm run build
+   ```
+
+5. **Open a PR** against the `dev` branch with a clear description of what changed and why.
+
+### Dev setup
+
+```bash
+# Clone and install
+git clone https://github.com/danielgran/vue-markdown-editor.git
+cd vue-markdown-editor
+npm ci
+
+# Start the dev server
+npm run dev
+```
+
+The dev server launches at `http://localhost:4010`. The entry point is `dev/App.vue` — a full showcase that demonstrates every editor feature: block types, drag & drop, image upload, context menus, keyboard navigation, and Markdown output serialization. Use it as a playground while developing.
+
+---
+
+## License
+
+[ISC](LICENSE) © 2026 [danielgran](https://github.com/danielgran)