Files
hudozka/docs/specs/20260407-writer-editor-improvements.md
T
2026-04-24 21:24:46 +03:00

182 lines
9.2 KiB
Markdown

# Writer Editor Improvements
Improvements to `modules/hudozka-writer/` — the Tiptap-based page editor for the hudozka CMS.
## 1. Fix Markdown Serialization + Global Toggle
### Problem
The `@tiptap/markdown` extension is registered but not used in the serialization layer (`src/lib/serialize.ts`). Currently:
- `docToTiptap()` splits text on `\n\n` and wraps each chunk in a plain paragraph node — no markdown parsing
- `tiptapToDoc()` extracts raw text content, discarding all inline marks (bold, italic, links) and block structure (headings, lists)
Result: formatting applied via toolbar is lost on save.
### Solution
Use `@tiptap/markdown` for both directions:
**Loading (DocV1 → Tiptap):** For each `text` block, call `editor.commands.setContent(block.text)` or use the Markdown extension's parser to convert the markdown string into Tiptap JSON nodes. This replaces the naive paragraph splitting in `textBlockToTiptap()`.
**Saving (Tiptap → DocV1):** When flushing the text buffer in `tiptapToDoc()`, use the Markdown extension's serializer (`editor.storage.markdown.getMarkdown()`) to convert Tiptap JSON back to a markdown string. This replaces the lossy `tiptapTextContent()` that strips all formatting.
Implementation approach: create a headless Tiptap editor instance (no DOM) used solely for markdown↔JSON conversion in `serialize.ts`. This keeps serialization pure and avoids coupling to the live editor instance.
### Global Markdown Toggle
Add a toolbar button that switches the entire editor between two modes:
- **Rendered mode** (default): Normal WYSIWYG editing via Tiptap
- **Markdown mode**: Replace the Tiptap editor surface with a plain `<textarea>` showing the serialized markdown of the full document
Toggle flow:
1. User clicks "MD" button in toolbar
2. Serialize current Tiptap content to markdown string (using the markdown serializer)
3. Hide `<EditorContent>`, show `<textarea>` with the markdown string
4. Custom blocks (image, document, embed, card-grid) are represented as fenced markers in the markdown view, e.g. `<!-- image:abc123 -->` — these are read-only anchors that preserve block positions
5. When toggling back: parse the textarea content, reconstruct Tiptap JSON, call `editor.commands.setContent()`
State: a single `markdownMode: boolean` in the `Editor` component.
## 2. Block Menu (Insert + Slash Commands)
### Hover "+" Button
A `+` button appears between blocks on hover. Clicking opens a dropdown menu with available block types:
- Text (inserts empty paragraph)
- Image (inserts imageBlock with empty attrs)
- File (inserts documentBlock with empty attrs)
- Embed (inserts embedBlock with empty attrs)
- Card Grid (inserts cardGridBlock with empty items)
Implementation: a Tiptap extension that uses a plugin to track cursor/hover position and renders a floating React element via a plugin view. The button appears in the left gutter between block-level nodes.
The dropdown is a simple list of block types. Clicking one inserts the corresponding node at the gap position using `editor.chain().focus().insertContentAt(pos, node).run()`.
### Slash Commands
Type `/` at the start of an empty paragraph to open the same block type picker as an inline dropdown. Uses Tiptap's `@tiptap/suggestion` pattern:
- Trigger: `/` character at start of empty paragraph
- Shows filtered list of block types (filters as user types, e.g. `/im` shows "Image")
- Enter or click to insert the selected block type, replacing the empty paragraph
- Escape to dismiss
Both the "+" menu and slash command share the same `BlockTypeMenu` React component — only the trigger and positioning differ.
### Block Types Available for Insertion
| Type | Tiptap node | Default attrs |
|-----------|-----------------|-------------------------------------------|
| Text | paragraph | empty paragraph |
| Image | imageBlock | `{ imageId: "", wide: false, caption: "" }`|
| File | documentBlock | `{ fileId: "", title: "" }` |
| Embed | embedBlock | `{ src: "" }` |
| Card Grid | cardGridBlock | `{ items: "[]" }` |
### Drag Reorder for All Blocks
All custom blocks already have `draggable: true`. No change needed for custom blocks.
For text blocks (paragraphs, headings, lists, etc.): Tiptap's default behavior allows cursor-based text editing, not dragging. Adding drag handles to standard text nodes would conflict with text selection. Leave text blocks non-draggable — users reorder text by cut/paste or by using the block menu to insert at the right position.
Custom blocks (image, document, embed, card-grid) remain draggable via their existing `data-drag-handle` attribute.
## 3. File Block Editor
Transform `DocumentBlock` from read-only display into a full editor, following the same pattern as `ImageBlock`.
### UI Layout
```
┌──────────────────────────────────────┐
│ Document │
│ ┌──────────────────────────────────┐ │
│ │ 📎 filename.pdf │ │
│ │ (or "Click to select file") │ │
│ └──────────────────────────────────┘ │
│ Title: [___________________________] │
│ [Pick] btn │
└──────────────────────────────────────┘
```
### FilePicker Component
New component `src/components/FilePicker.tsx`, modeled after `ImagePicker`:
- **Browse tab**: paginated list of files from a PocketBase `files` collection (or whichever collection stores documents). Each row shows filename + file size. Click to select.
- **Upload tab**: file input (no `accept` restriction — any file type) + upload button. Creates a record in the files collection, returns the new record ID.
Props: `{ onSelect: (fileId: string) => void, onClose: () => void }`
### DocumentBlock Changes
- Add local state: `showPicker: boolean`, `filename: string | null` (resolved from PB)
- On mount (when `fileId` is set): fetch file record from PB to get `filename` for display
- "Pick" button opens `FilePicker` modal
- Title field: inline `<input>` that calls `updateAttributes({ title: value })`
- Selecting a new file via picker calls `updateAttributes({ fileId: newId })`
### PocketBase Collection
Assumes a `files` collection exists with at least: `id`, `file` (file field), `filename` (string). If not, this needs to be created in PocketBase schema. The exact collection name and schema should be verified before implementation.
## 4. Card Grid Display Enhancement
`CardGridBlock` stays read-only. Enhance the view to show resolved page titles instead of just item count.
### Current Display
```
Card Grid
3 items
```
### New Display
```
Card Grid (3)
• Акварельная живопись
• Графический дизайн
• Скульптура и керамика
```
### Implementation
In `CardGridBlockView`:
1. Parse `items` from attrs (already done)
2. For each item, fetch `pb.collection("pages").getOne(item.page)` to get the page title
3. Show a bulleted list of page titles
4. Handle loading state (show "Loading..." while fetching)
5. Handle missing pages (show page ID if fetch fails)
Use `useEffect` + `useState` to batch-fetch all page titles on mount or when `items` attr changes. Cache results to avoid redundant fetches during re-renders.
## Files to Create
| File | Purpose |
|---------------------------------------|------------------------------------|
| `src/components/FilePicker.tsx` | File browse/upload modal |
| `src/components/FilePicker.css` | FilePicker styles |
| `src/components/BlockMenu.tsx` | Shared block type dropdown |
| `src/components/BlockMenu.css` | BlockMenu styles |
| `src/nodes/BlockInsertButton.tsx` | Hover "+" Tiptap plugin view |
| `src/extensions/SlashCommands.ts` | Slash command Tiptap extension |
## Files to Modify
| File | Changes |
|---------------------------------------|--------------------------------------------------|
| `src/lib/serialize.ts` | Use `@tiptap/markdown` for text block conversion |
| `src/components/Editor.tsx` | Add markdown toggle state, register new extensions |
| `src/components/Toolbar.tsx` | Add "MD" toggle button |
| `src/nodes/DocumentBlock.tsx` | Add interactive editing (picker, title input) |
| `src/nodes/CardGridBlock.tsx` | Fetch and display page titles |
| `src/nodes/index.ts` | Export new extensions |
| `src/components/Editor.css` | Styles for markdown textarea mode |
## Out of Scope
- Undo/redo system (deferred)
- Per-block markdown toggle (future enhancement)
- Card grid editing (add/remove/reorder items)
- Embed block editing