104 lines
4.7 KiB
Markdown
104 lines
4.7 KiB
Markdown
---
|
|
title: "feat: Inline WYSIWYG editor with HTML-JSON sync"
|
|
type: feat
|
|
status: completed
|
|
date: 2026-03-04
|
|
---
|
|
|
|
# feat: Inline WYSIWYG editor with HTML-JSON sync
|
|
|
|
## Overview
|
|
Build step 2 of the content workflow: a local-first WYSIWYG editor for the existing static page where creators can directly edit content on the rendered page and persist changes to both HTML and JSON.
|
|
|
|
This plan is limited to content editing and synchronization behavior. It explicitly excludes style/layout editing.
|
|
|
|
## Problem Statement / Motivation
|
|
The repository now has extractable structured content (`content/site-content.de.json`) but no practical editing surface for creators. Editors need direct, low-friction page editing (double-click text, click image) while keeping HTML and JSON in sync.
|
|
|
|
## Proposed Solution
|
|
Add an in-page edit mode with inline `contenteditable` text editing and an image overlay editor for `src` and `alt`. Implement autosave (blur/enter) plus manual save/undo controls. Persist edits via a local helper service that writes both `ikfreunde.com.html` and `content/site-content.de.json`.
|
|
|
|
Synchronization is bidirectional in model intent, with conflict default set to HTML wins when the same mapped key diverges.
|
|
|
|
## Scope
|
|
In scope:
|
|
- Text editing on double-click for editable content nodes
|
|
- Image editing overlay for `src` and `alt`
|
|
- Aspect-ratio warning (non-blocking) at 15% threshold
|
|
- Autosave + manual save/undo controls
|
|
- Local persistence endpoint to write HTML + JSON
|
|
- Content identity mapping between DOM elements and JSON keys
|
|
- Conflict handling policy: HTML wins
|
|
|
|
Out of scope:
|
|
- CSS/layout editing
|
|
- `srcset`/`picture` editing
|
|
- Multi-user collaboration or remote persistence
|
|
- Authentication/authorization layer
|
|
|
|
## Technical Considerations
|
|
- Current site scripts are bundled/minified, so editor behavior should be isolated in a dedicated script layer.
|
|
- Content identity mapping must be stable enough for repeat edits and sync.
|
|
- Editing rules should avoid hidden/system nodes (cookie mechanics/scripts/non-content regions unless explicitly intended).
|
|
- Local persistence requires a trusted local helper process and clear file write boundaries.
|
|
- Undo scope must be defined (session-level content undo, not full VCS-like history).
|
|
|
|
## SpecFlow Analysis
|
|
Primary flow:
|
|
1. Editor enters edit mode.
|
|
2. User double-clicks text node and edits inline.
|
|
3. User blur/enter triggers autosave path.
|
|
4. Mapping resolves edited node to JSON key.
|
|
5. HTML and JSON are both updated and persisted via local helper.
|
|
|
|
Image flow:
|
|
1. User selects editable image.
|
|
2. Overlay opens with current `src` and `alt`.
|
|
3. New source is validated; ratio warning shown if aspect ratio differs by >15%.
|
|
4. User can still save despite warning.
|
|
5. HTML and JSON are updated and persisted.
|
|
|
|
Conflict flow:
|
|
1. Divergent values detected for same mapped key.
|
|
2. Default resolution applies: HTML value wins.
|
|
3. JSON is reconciled to HTML on save.
|
|
|
|
## Acceptance Criteria
|
|
- [x] Double-click enables inline text editing on intended content elements.
|
|
- [x] Text autosaves on blur/enter and also supports explicit save/undo controls.
|
|
- [x] Clicking editable images opens an overlay with `src` and `alt` fields.
|
|
- [x] Image ratio check warns (non-blocking) when replacement differs by >15% aspect ratio.
|
|
- [x] Save operation persists both `ikfreunde.com.html` and `content/site-content.de.json`.
|
|
- [x] Sync mapping updates the correct JSON key for edited text/image values.
|
|
- [x] Conflict resolution follows HTML-wins default.
|
|
- [x] No CSS/layout properties are modified by editor actions.
|
|
|
|
## Success Metrics
|
|
- Editors can modify headings/body text/images directly on page without manual JSON editing.
|
|
- Saved output remains consistent between HTML and JSON for edited items.
|
|
- Editing interactions feel immediate and require minimal training.
|
|
- No unintended style/layout changes caused by the editor.
|
|
|
|
## Dependencies & Risks
|
|
Dependencies:
|
|
- Defined DOM↔JSON mapping contract for editable nodes
|
|
- Local helper service runtime available in the editor environment
|
|
|
|
Risks:
|
|
- Incorrect key mapping leading to wrong JSON updates
|
|
- Over-editability (allowing non-content nodes)
|
|
- Unexpected side effects from integrating with existing bundled scripts
|
|
- File write race conditions during rapid autosave
|
|
|
|
Mitigations:
|
|
- Explicit editable-node allowlist and mapping tests
|
|
- Isolated editor namespace/events
|
|
- Debounced autosave + write serialization
|
|
- Dry-run/preview diagnostics for mapping during development
|
|
|
|
## References & Research
|
|
- Brainstorm input: `docs/brainstorms/2026-03-04-wysiwyg-inline-editor-sync-brainstorm.md`
|
|
- Prior extraction plan: `docs/plans/2026-03-04-feat-dom-to-json-content-extraction-plan.md`
|
|
- Extractor/source contract: `scripts/extract_dom_content.php`, `content/site-content.de.json`
|
|
- Target HTML: `ikfreunde.com.html`
|