PB + Writer (#287)

* add pb models

* api rules has updated to view public

* pb setup is completed

* add migrate script

* add pb migrations

* ignore storage

* add pocketbase SDK dependency

* change Tag.id and PageCardDto.id to string for PocketBase

* add DocV1 content block types

* add PB client singleton and PB record types

* rewrite factory for PocketBase record types

* rewrite api.ts for PocketBase SDK

* remove unused Strapi files, add PB to config

* mark Task 7 complete in plan

* feat: verify build, tests, and lint pass with PocketBase API layer

* move completed plan: 2026-04-06-pocketbase-api-layer.md

* scaffold hudozka-writer with Vite 8, React 19, TS 5.9, Tiptap

* add PocketBase client and DocV1 types to writer

* add Login component for PocketBase superuser auth

* add App shell with auth gate and page loader

* add DocV1 <-> Tiptap serialization layer

* mark Task 5 complete in writer redesign plan

* add custom Tiptap nodes for DocV1 block types

* add Tiptap editor with toolbar and save to PocketBase

* add image picker with browse and upload

* feat: verify writer build and complete integration task

* move completed plan: 2026-04-06-hudozka-writer-redesign.md

* add local env

* rm textblock from writer

* add writer editor improvements design spec

* add writer editor improvements implementation plan

* feat: use @tiptap/markdown for text block serialization

* feat: add global markdown/rendered toggle

* feat: add BlockMenu component for block type selection

* feat: add hover + button for block insertion

* feat: add slash commands for block insertion

* feat: add interactive file block editor with FilePicker

* feat: show resolved page titles in card grid block

* move completed plan: 2026-04-07-writer-editor-improvements.md

* writer ui improved

* pages migration

* spec: draft/publish workflow for hudozka-writer

* spec: rename draft_doc to draft in spec

* plan: writer draft/publish implementation

* plan has moved

* gitignores

* plans upd

* feat(writer): update PbPage type for draft/publish workflow

* feat(writer): add save/publish/discard handlers with dirty tracking

* feat(writer): add DraftBanner component

* feat(writer): add Publish button and update toolbar layout

* feat(writer): add published toggle and update duplicate for new schema

* docs: mark manual verification steps as skipped in writer draft/publish plan

* move completed plan: 20260407-writer-draft-publish.md

* feat(writer): add BlockActions component for inline block menus

* feat(writer): add draggable NodeViews for text blocks

* feat(writer): use BlockActions in custom block NodeViews

* feat(writer): replace floating BlockInsert with inline BlockActions

* fix(writer): ensure all block wrappers have position: relative for BlockActions

* chore: mark manual verification tasks as skipped in writer block actions plan

* move completed plan: 20260408-writer-block-actions.md

* writer update

* refactor(writer): simplify BlockActions to always-visible delete + drag handle

* feat(writer): add BlockInsert component for inserting blocks between nodes

* feat(writer): redesign block sidebar with always-visible actions and insert button

* move completed plan: 20260408-writer-block-actions-redesign.md

* add spec: textblock container redesign for writer editor

* feat(writer): add TextBlock container node definition

* feat(writer): replace DraggableXxx wrappers with TextBlock container

* feat(writer): update Editor extensions for TextBlock container

* feat(writer): add split button to BlockActions for text blocks

* feat(writer): update serialization for TextBlock container

* feat(writer): update BlockMenu and SlashCommands for TextBlock

* fix(writer): use Fragment.from() for replaceWith calls in BlockActions and SlashCommands

* move completed plan: 20260408-textblock-container.md

* add air
This commit is contained in:
tmshv authored and GitHub committed 2026-04-12 19:02:03 +03:00
1 parent 907298779c
commit ed3f93de53
109 files changed
+40520 -427

No files matched your search

@@ -0,0 +1,85 @@
# Writer Draft/Publish Feature
## Overview
Add draft-save and explicit publish workflow to hudozka-writer so editors can save work-in-progress without pushing changes live.
## Data Layer
PocketBase `pages` collection fields (already applied by user):
| Field | Type | Purpose |
|--------------|---------|--------------------------------------------------------|
| `doc` | JSON | Published document content (read by the main site) |
| `draft` | JSON | Unpublished work-in-progress, `null` when no draft |
| `published` | boolean | Page visibility (renamed from `draft`, inverted logic) |
## Editor Load Behavior
When opening a page:
- If `draft` is not null: load `draft` into the editor, show a banner "You have unpublished changes" with a **Discard** button.
- If `draft` is null: load `doc` into the editor, no banner.
## Save / Publish / Discard
| Action | API call | Effect |
|-------------|----------------------------------------------------|-------------------------------------------|
| **Save** | `update(id, { draft: editorContent })` | Persists WIP without affecting live site |
| **Publish** | `update(id, { doc: editorContent, draft: null })` | Pushes content live, clears draft |
| **Discard** | `update(id, { draft: null })` | Drops WIP, reloads editor from `doc` |
No confirmation dialog on Discard.
## Toolbar Changes
Current layout: `[formatting...] [MD] [Save]`
New layout: `[formatting...] [MD] [Save] [Publish]`
- **Save** button: enabled only when editor content differs from the last-saved state. Writes to `draft`.
- **Publish** button: enabled when there are any unpublished changes (unsaved edits or existing `draft`). Writes to `doc`, clears `draft`.
After Save: Save button becomes disabled (no new changes), Publish remains enabled (draft exists).
After Publish: both buttons become disabled (content is live, no draft).
## Draft Banner
Shown above the editor when `draft` was loaded. Simple bar with text and a Discard button:
```
[You have unpublished changes] [Discard]
```
Clicking Discard: sends API call to clear `draft`, reloads editor content from `doc`, hides the banner.
## Page Visibility Toggle
A checkbox in the app header (near page title/slug): `[ ] Published`
- Checked = page visible on site (`published: true`)
- Unchecked = page hidden (`published: false`)
- Toggling sends `update(id, { published: !current })` immediately
- Independent of save/publish content flow
## Dirty Tracking
Track whether editor content has changed since last load/save:
- On load: snapshot the initial content (serialized `DocV1`)
- On every editor change: compare current serialized content with snapshot
- After Save: update snapshot to current content
- After Publish: update snapshot to current content
- After Discard: update snapshot to `doc` content
This drives the enabled/disabled state of Save and Publish buttons.
## Type Changes
Update `PbPage` in `modules/hudozka-writer/src/types.ts`:
- Replace `draft: boolean` with `published: boolean` and `draft: DocV1 | null`
## Files to Modify
- `modules/hudozka-writer/src/types.ts` — update `PbPage` type
- `modules/hudozka-writer/src/components/Editor.tsx` — draft loading, save/publish/discard handlers, dirty tracking
- `modules/hudozka-writer/src/components/Toolbar.tsx` — add Publish button, accept dirty/hasDraft props
- `modules/hudozka-writer/src/App.tsx` — add published toggle in header, update `handleDuplicate` for new field names
@@ -0,0 +1,181 @@
# 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