docs(specs): v4 data-organization + inline-editing design specs (agreed 2026-10-23)

spec-v4-data-organization.md: per-entity content files, per-feature-group UI (14 groups), per-page field-level manifests incl. synthetic resume consumer, orphan-field validation rule; lands after inline-editing. spec-v4-inline-editing.md (E1-E7): delete JsonPanel, pencil-icon-trigger inline editing with field-provenance chips/tooltips (document -> pointer, clipboard copy), chip-level tag editors, ghost add/delete/move record controls, per-record settings popover, auto-generated slug ids, handle-only social links with loader-derived URLs, per-field keep-mine/keep-theirs conflict resolution. spec-v4-live-edit.md: mark JSON-panel scope superseded (5.1, 5.4, 5.8, row 14). AGENTS.md: register both specs as design-agreed-not-yet-implemented.
This commit is contained in:
dong.nguyen committed 2026-10-23 00:52:55 +07:00
1 parent fecbd44899
commit fbf75d8ffa
4 files changed
+286 -6

No files matched your search

+6 -4
View File
@@ -332,8 +332,8 @@ The site itself gains an edit mode. There is no second preview machinery — the
- **Draft initialization:** the draft is initialized from **live repository files fetched through the proxy** (`GET` per document + its `last_commit_sha`), not from the bundle — the bundle may be older than master if anyone edited via Gitea web since the last build, and a bundle-seeded draft would silently revert those edits. The static bundle is used only as an offline fallback, with a visible "stale" warning.
- **Mechanism:** edit mode wraps `<Layout>` in `<I18nProvider override={draft}>`. All pages, all components, both languages render the draft — text **and** structure.
- **Inline text editing:** rendered text nodes bound to a text-document path become editable on focus (`contentEditable`); blur writes `{ path, value }` into the draft. Editing `projects['iot-dws-integration'].title` updates the card on `/projects`, the header on `/projects/:id`, and the featured block on the home page **simultaneously** — one draft, every consumer.
- **Editable surface (curated scope):** inline editing covers **text documents only** — profile bio and tagline (each tagline segment is an individually editable span; the `emphasis` toggle is edited in the JSON panel), profile subtitle / career TL;DR / philosophy quote titles+paragraphs (row 18), project titles/summaries/section content/role, experience titles/companies/durations/responsibilities (row 19), skill group titles, philosophy titles/descriptions. Tag arrays (`currentInterests`, `roles`, `keywords`, `metrics`) are JSON-panel-only — tag chips are not inline-edit targets. `ui.json` is **read-only** in v4 (labels/aria are low-frequency chrome). This bounds the wrapping work to the ~40 content render sites, not the 130+ UI-string sites. Adjacent tagline segments are separate edit targets — the caret does not cross a segment boundary; intended behavior (D9), not a bug.
- **Structural editing:** add/remove/edit records in the structure documents and their text entries happens in a JSON panel docked beside the page (the panel edits the draft documents directly; the live page re-renders on every valid change). The panel validates against §3.2/§3.6 before accepting — an invalid draft never reaches the preview.
- **Editable surface (curated scope):** inline editing covers **text documents only** — profile bio and tagline (each tagline segment is an individually editable span), profile subtitle / career TL;DR / philosophy quote titles+paragraphs (row 18), project titles/summaries/section content/role, experience titles/companies/durations/responsibilities (row 19), skill group titles, philosophy titles/descriptions. `ui.json` is **read-only** in v4 (labels/aria are low-frequency chrome). This bounds the wrapping work to the ~40 content render sites, not the 130+ UI-string sites. Adjacent tagline segments are separate edit targets — the caret does not cross a segment boundary; intended behavior (D9), not a bug. *Superseded 2026-10-23 by `spec-v4-inline-editing.md`: editing is triggered by a per-field pencil icon, never by text focus; tag arrays (`currentInterests`, `roles`, `keywords`, `metrics`, `technologies`, tagline segments + emphasis toggle) become chip-level edit units with add/delete/move.*
- **Structural editing:** *Original scope: add/remove/edit records in a JSON panel docked beside the page, validated against §3.2/§3.6 before accepting.* Superseded 2026-10-23 by `spec-v4-inline-editing.md` (E1): the panel is deleted; record add/delete/move and rare fields (`featured`, `variant`, `logo`) move to on-page affordances (ghost add controls, confirm-gated delete, per-record settings popover). Validation-before-accept semantics are unchanged.
- **Language/theme:** the existing language, theme, and palette controls work unchanged inside edit mode — the owner previews exactly what visitors will see.
- **Save:** a persistent save bar lists the diff (changed paths per document), runs the §3.6 validator on the full draft, then PUTs each touched document through the proxy (§6). Unsaved draft is invisible to visitors.
@@ -372,6 +372,8 @@ stateDiagram-v2
### 5.4 JSON panel (structural editing)
> **Superseded 2026-10-23** by `spec-v4-inline-editing.md` (E1): `JsonPanel.tsx` is deleted; everything this section described is edited on the page instead. Kept as the implementation record of what was built in 3b — the templates, orphan-free delete, and validation gating it used are reused by the inline controls.
- Docked sheet: 420px right side above 1024px, full-width bottom sheet below; toggled from the EditBar; the live page stays interactive beside it.
- Tabs: `profile.json`, `skills.json`, `experience.json`, `projects.json`, `content.vi.json`, `content.en.json`; `ui.{vi,en}.json` shown read-only for reference.
- Editor: monospace textarea + parse/validation status bar; errors render JSON-pointer paths with line numbers. The preview keeps rendering the **last valid draft** — an invalid panel state never reaches the page or the save.
@@ -402,7 +404,7 @@ stateDiagram-v2
### 5.8 Layout knobs and the deferred layout designer
v4 exposes no new layout knobs. `featured` and `variant` already exist and are editable via the JSON panel. A `layout.ts` config (section order/visibility) and any WYSIWYG layout editing are recorded here as **deferred research**, explicitly out of v4 scope.
v4 exposes no new layout knobs. `featured` and `variant` already exist and are editable via the JSON panel (superseded 2026-10-23: the same fields are edited in the per-record settings popover, `spec-v4-inline-editing.md` §2.4). A `layout.ts` config (section order/visibility) and any WYSIWYG layout editing are recorded here as **deferred research**, explicitly out of v4 scope.
---
@@ -590,7 +592,7 @@ Deferred (not v4):
| 11 | Production nginx step (§6.3) | 2 | ⬜ TODO — server step + `GITEA_TOKEN` are owner-side; the Phase-1 JSON documents must also be pushed to the repository before the proxy answers 200 |
| 12 | Local proxy config + compose + auth | 2 | ✅ Done 2026-10-22 — `nginx.conf` template location, compose env/htpasswd mounts, `deploy/htpasswd`. Compose smoke: unauthenticated GET → 401 + `WWW-Authenticate: Basic realm="Editor"`; authenticated request passes htpasswd and reaches Gitea (answers 404 `rel_path` — the JSON documents are not yet pushed and `GITEA_TOKEN` is unset locally, so the 200/412 legs land with row 11). `vite.config.ts` dev proxy mirrors nginx exactly |
| 13 | Edit mode 3a: draft store, inline editing, save happy path | 3 | ✅ Done 2026-10-22 (automated) — `draft.ts` (copy-on-write, path diff, origin/base separation + three-way rebase, sessionStorage snapshot, sequential-PUT save, id-union append), `edit-mode.ts` (`?edit`, session flag, Basic probe, dirty guard), `EditableText.tsx` (§5.3 contract), `useEdit.ts` context split, `App.tsx` lazy `MaybeEditMode` gate; editable surface wrapped in Hero/About/AboutPage/Expertise/Experience/ExperiencePage/Projects/ProjectsListPage/ProjectDetailPage. Verified: `pnpm build` (EditModeShell is a separate 24 kB lazy chunk, entry unchanged), `pnpm lint` (no new warnings), `scripts/smoke-draft.ts` 7/7 (accept/reject, empty-required, orphan-free delete, template, snapshot round-trip, conflict detection, clean rebase). ⬜ Browser: IME dấu commit on blur, cross-page live preview, reload restores the draft |
| 14 | Edit mode 3b: JSON panel + record templates | 3 | ✅ Done 2026-10-22 (automated) — `JsonPanel.tsx`: per-document tabs + read-only `ui` tabs, shape hints, templates (project / experience / skill-group / philosophy / section-with-project-picker), record list + confirm-gated delete (structure + both text documents in one validated step), side-by-side hand-merge for conflicted documents, parse + validator status line. Verified via an SSR wiring smoke (`react-dom/server`, vi markup: tabs, templates, delete controls, status) — deleted after the run. ⬜ Browser: add/delete → live preview + validator behavior |
| 14 | Edit mode 3b: JSON panel + record templates | 3 | ✅ Done 2026-10-22 (automated) — `JsonPanel.tsx`: per-document tabs + read-only `ui` tabs, shape hints, templates (project / experience / skill-group / philosophy / section-with-project-picker), record list + confirm-gated delete (structure + both text documents in one validated step), side-by-side hand-merge for conflicted documents, parse + validator status line. Verified via an SSR wiring smoke (`react-dom/server`, vi markup: tabs, templates, delete controls, status) — deleted after the run. **Superseded 2026-10-23 by `spec-v4-inline-editing.md` E1**: the panel will be deleted; templates and orphan-free delete are reused by on-page controls. ⬜ Browser: add/delete → live preview + validator behavior (re-targeted to the inline controls) |
| 15 | Edit mode 3c: save bar, conflicts, failure recovery | 3 | ✅ Done 2026-10-22 (automated) — `EditBar.tsx`: changed-path diff with per-path revert and per-document discard, validate-before-save, sequential-PUT progress lines (written / conflict / failed), resume after partial failure, conflict actions (rebase / take-theirs / hand-merge), exit confirm when dirty. Verified via the same (now deleted) SSR smoke — vi markup carried the conflict controls, save statuses, and the resume button. ⬜ Browser + Gitea: save → commit → queued CI deploy → live change; full 412 flow against a real stale sha |
| 16 | Layout designer research (WYSIWYG / layout config) | deferred | ⬜ Out of v4 scope |
| 17 | Target-branch editing (D10): `?edit=<branch>`, `?ref=` on GET, `branch` on PUT, branch chip + merge hint | 3 | ✅ Done 2026-10-22 (automated) — tri-state URL parsing with git-ref validation (`edit-mode.ts`), `?ref=` on every document GET and `branch` in every PUT body (`draft.ts`, incl. the 412-refresh and id-union legs), branch persisted beside the session flag, EditBar branch chip + merge hint on non-default branches (`ui.json` `branchLabel`/`mergeHint`). Verified: `pnpm build`, `pnpm lint` (no new warnings), `scripts/smoke-draft.ts` 7/7, throwaway wiring smoke (URL tri-state, ref/branch transport, EditBar render for branch vs master) — deleted after the run. ⬜ Browser + Gitea: edit on a non-master branch → commits land there; merge → deploy |