From fbf75d8ffa577f89f3c30aea75ee7431cfe32314 Mon Sep 17 00:00:00 2001 From: "dong.nguyen" Date: Fri, 23 Oct 2026 00:52:55 +0700 Subject: [PATCH] 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. --- AGENTS.md | 4 +- .../specs/v4/spec-v4-data-organization.md | 162 ++++++++++++++++++ .../design/specs/v4/spec-v4-inline-editing.md | 116 +++++++++++++ docs/design/specs/v4/spec-v4-live-edit.md | 10 +- 4 files changed, 286 insertions(+), 6 deletions(-) create mode 100644 docs/design/specs/v4/spec-v4-data-organization.md create mode 100644 docs/design/specs/v4/spec-v4-inline-editing.md diff --git a/AGENTS.md b/AGENTS.md index 9008edd..8a87778 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,7 +90,7 @@ Content is split once, at authoring time, into language-neutral **structure docu - `src/i18n/draft.ts` — `DraftStore`: baselines (`data` + `last_commit_sha`) of the six content documents, copy-on-write draft, leaf-path diff, cross-document validation on every accepted edit, three-way rebase on 412 conflicts (origin / base / working kept separate), draft persisted to sessionStorage `portfolio-draft`, sequential-PUT save (one commit per touched document, resume from the first unwritten one on failure), and appending new id union members to `src/types/index.ts` after their documents land - `src/components/ui/EditableText.tsx` — the site's own element (`as` = the tag or motion component it renders today) becomes the inline editor only in edit mode; commit on blur only (Vietnamese IME-safe), Esc cancels, Enter commits single-line fields, paste is plain-text, empty required values are rejected at commit; without an `EditContext` provider it renders byte-identical markup to the plain element - `src/components/layout/EditBar.tsx` — fixed save bar: per-path diff with revert, conflict resolution (rebase / take-theirs / hand-merge), per-document save status, partial-save resume, exit confirm; `src/components/layout/JsonPanel.tsx` — per-document JSON editor with shape hints, record templates (structure + text stubs created together), orphan-free record delete, read-only `ui.json` tabs -- Editable surface is content text only (bio, tagline segments, project titles/summaries/section prose, experience titles/responsibilities, skill-group titles, philosophy titles/descriptions); structure fields (`featured`, `variant`, technologies, links, ids) are edited in the JSON panel; `ui.json` is read-only in v4 +- Editable surface is content text only (bio, tagline segments, project titles/summaries/section prose, experience titles/responsibilities, skill-group titles, philosophy titles/descriptions); structure fields (`featured`, `variant`, technologies, links, ids) are edited in the JSON panel; `ui.json` is read-only in v4. **Design agreed 2026-10-23 (`spec-v4-inline-editing.md`), not yet implemented:** the JSON panel will be deleted — pencil-icon-trigger inline editing with field-provenance chips (`document → pointer`), chip-level tag editors, ghost add/delete/move record controls, per-record settings popover, auto-generated ids, handle-only social links with loader-derived URLs - Dev parity: `vite.config.ts` proxies `/api/content/` to the Gitea Contents API exactly like production nginx — run `pnpm dev` with `GITEA_TOKEN` set; without it edit mode falls to the offline state (bundled content, save disabled) - Spec: `docs/design/specs/v4/spec-v4-live-edit.md` §5–§6 @@ -190,7 +190,7 @@ All specification documents are in `docs/design/`: | `specs/ui/spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) | | `specs/v2/spec-v2-*.md` | v2 feature specs (resume, seo, blog, analytics, testing, cicd) | | `specs/v3/spec-v3-*.md` | v3 feature specs (theme colors, theme switch, theme palette switch, palette reference, UI enhancements, mobile navigation, nav & CTA enhancements, nav swatch & hamburger, typography, i18n, resume improvements, resume redesign, review fixes) | -| `specs/v4/spec-v4-*.md` | v4 feature specs (i18n locale overlay, git-backed live edit with preview, authenticated Contents-API write path; supersedes v3-i18n Phase 2) | +| `specs/v4/spec-v4-*.md` | v4 feature specs (i18n locale overlay, git-backed live edit with preview, authenticated Contents-API write path; supersedes v3-i18n Phase 2). `spec-v4-data-organization.md`: per-entity content files, per-page field-level manifests, per-feature-group UI — design agreed 2026-10-23, **not yet implemented**. `spec-v4-inline-editing.md`: edit everything on the page (pencil-icon triggers, tag chips, record add/delete/move, settings popover), JSON panel deleted — design agreed 2026-10-23, **not yet implemented**; it supersedes live-edit §5.1/§5.4 panel scope. The current layout and JsonPanel below remain authoritative until those specs land | Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope. diff --git a/docs/design/specs/v4/spec-v4-data-organization.md b/docs/design/specs/v4/spec-v4-data-organization.md new file mode 100644 index 0000000..f32f37c --- /dev/null +++ b/docs/design/specs/v4/spec-v4-data-organization.md @@ -0,0 +1,162 @@ +# Specification — v4 Data Organization (per-entity content, per-page manifests, per-group UI) + +Status: **Design agreed 2026-10-23; implementation TODO.** Follow-up to `spec-v4-live-edit.md`; does not change its D1–D10 decisions, only the physical document layout and the edit-mode document registry. + +## 1. Decisions from the 2026-10-23 discussion + +| # | Decision | Rationale | +|---|---|---| +| D1 | Content text is managed **per entity**, one file per entity per language | Structure documents are already per entity; the text document mirrors its structure document 1:1. Join, validation, and commits become per-pair. | +| D2 | Page data is managed **per page** as a **manifest of references**, not as copied text | Entities legitimately span pages (bio on home + `/about`, experiences on home + `/experience`, projects on three pages). Copying per page re-creates the duplicated-fact problem the row 18–19 cutover just removed. The manifest answers "where does this page's data come from" without duplication. | +| D3 | UI chrome is one file per **feature-group**, not per React component file | Strings shared by sibling components (nav chrome by Navigation + MobileMenu + ThemePaletteMenu + ResumeNavButton; social by Footer + Contact) would duplicate or cross-import under a strict per-component split. A feature-group is "the component plus its variants". | +| D4 | Manifests are **field-level** | The stated goal is provenance per page; entity-level would not say which field renders where. Field-level is also what powers EditBar page grouping (§6.3). | +| D5 | Spec first, implementation in a later pass | This file is the contract; implementation order and acceptance criteria are §7–§8. | + +Non-goals: + +- Pages do **not** render from manifests. Section layouts are bespoke (hero ≠ timeline ≠ grid); a generic renderer driven by manifests would rewrite all seven pages and lose their design. The manifest is a provenance index and an edit-mode grouping source, not render config. +- No content is duplicated across documents. `CONTENT` and `UI` as consumed by components keep byte-identical shapes; components do not change. + +## 2. Target tree + +``` +src/data/ # structure, language-neutral (unchanged files) + profile.json skills.json experience.json projects.json + pages/ # NEW: per-page manifests, language-neutral + home.json about.json experience.json projects.json + project-detail.json contact.json philosophy.json + resume.json # synthetic consumer manifest (no route) — see §5 + pages.ts # NEW: loader + PageId typing + +src/i18n/locales/vi/ + content/ # text per entity (replaces content.json) + profile.json skills.json experience.json projects.json + ui/ # chrome per feature-group (replaces ui.json) + navigation.json footer.json social.json hero.json about.json + expertise.json experience.json projects.json project-detail.json + contact.json philosophy.json resume.json common.json edit.json +src/i18n/locales/en/ # mirror (partial overrides, unchanged semantics) +``` + +`src/i18n/index.ts` merges every file into the same `CONTENT` / `UI` records it exports today. `dict-types.ts` keeps the document types; each file is validated against its slice type at load, exactly as the current whole-document check. The existing fallback rule (missing EN field → VI value; arrays atomic) is unchanged and now operates per entity file. + +## 3. Content split per entity + +- `content.json` → four files per language under `locales//content/`. Entity id ↔ file ↔ resolved record: + +| Entity id (manifest, draft paths) | Structure doc | Text docs | Resolved record | +|---|---|---|---| +| `profile` | `src/data/profile.json` | `content/profile.json` | `c.profile` | +| `skillGroups` | `src/data/skills.json` | `content/skills.json` | `c.skillGroups` | +| `experiences` | `src/data/experience.json` | `content/experience.json` | `c.experiences` | +| `projects` | `src/data/projects.json` | `content/projects.json` | `c.projects` | + +- Cross-document validation rules (§3.6 of the live-edit spec) are unchanged in substance; they now run per pair — orphan/missing keys, HTML-in-text, id unions — with a smaller blast radius per rule. +- DraftStore baselines become per file. A save already PUTs one commit per touched document; after the split, touching bio and a project summary produces two commits (`profile.json`, `projects.json`) instead of one fat `content.json` commit. Conflict detection and three-way rebase are per-document and already independent — no semantics change, finer granularity. + +## 4. UI feature-groups + +The current `ui.json` namespaces map 1:1 onto groups; the split is mechanical. Ownership: + +| File (per language) | Namespace today | Owned by (feature-group) | +|---|---|---| +| `ui/navigation.json` | `nav` | Navigation, MobileMenu, ThemePaletteMenu, ResumeNavButton | +| `ui/footer.json` | `footer` | Footer | +| `ui/social.json` | `social` | SocialLinks (footer + contact surfaces) | +| `ui/hero.json` | `hero` | Hero (HeroParticles carries no copy) | +| `ui/about.json` | `about` | About section + AboutPage | +| `ui/expertise.json` | `expertise` | Expertise | +| `ui/experience.json` | `experience` | Experience section + ExperiencePage | +| `ui/projects.json` | `projects` | Projects section + ProjectsListPage | +| `ui/project-detail.json` | `projectDetail` | ProjectDetailPage | +| `ui/contact.json` | `contact` | Contact section + ContactPage | +| `ui/philosophy.json` | `philosophy` | PhilosophyPage | +| `ui/resume.json` | `resume` | resume PDF labels (consumed by `scripts/generate-resume.ts`) | +| `ui/common.json` | `common` | cross-cutting atoms: `backToTop`, `contactTag`, `experienceTag`, `resumeDownload`, resume-modal strings (BackToTop, tags, DownloadResume, ResumeDialog) | +| `ui/edit.json` | `edit` | EditBar, EditModeShell (incl. `edit.fields` labels; new inline-control labels per `spec-v4-inline-editing.md`) | + +`ui.json` stays read-only in edit mode (v4 rule, unchanged). `generate-resume.ts` and every component keep consuming the merged `UI` — zero call-site changes. + +## 5. Page manifests + +`src/data/pages/.json`, one per route, plus a synthetic `resume.json` consumer manifest (id `resume`, no route — the resume PDF is a real consumer of content text and would otherwise be the orphan-rule's blind spot). Schema: + +```json +{ + "id": "about", + "route": "/about", + "content": [ + { "entity": "profile", "fields": ["name", "bio", "subtitle", "currentInterests", "philosophy"] }, + { "entity": "skillGroups", "fields": ["*"] } + ], + "ui": ["about"] +} +``` + +- `entity` uses the §3 entity ids; `fields` are paths into the joined text/structure records; `"*"` claims the whole entity. +- `ui` lists **page-owned** groups only. Component-owned groups (`navigation`, `footer`, `social`, `common`, `resume`, `edit`) are owned by the component side and provenance for them is the component mapping in §4 — they are not repeated in every manifest. +- Manifests are language-neutral (which data a page shows is not a translation fact). They are structure-side data: part of validation, committed like structure documents, **read-only in the app** (`spec-v4-inline-editing.md` §3) — edited as repo files by the developer. + +Initial content mapping — derived from the code scan of every consumer (2026-10-23), to be re-derived exactly at implementation: + +| Page | profile | skillGroups | experiences | projects | +|---|---|---|---|---| +| `home` | `name`, `tagline`, `roles`, `bio`, `currentInterests`, `philosophy`, `tldr`, links (`email`, handles) | `*` (Expertise) | `*` (timeline) | featured subset: `title`, `summary`, `metrics` | +| `about` | `name`, `bio`, `subtitle`, `currentInterests`, `philosophy` | `*` | — | — | +| `experience` | `tldr` | — | `*` | — | +| `projects` | — | — | — | `*`: `title`, `summary`, `metrics` | +| `project-detail` | — | — | — | per-id: `title`, `summary`, `role`, `metrics`, `sections.*` | +| `contact` | links (`email`, handles) | — | — | — | +| `philosophy` | `philosophyQuotes` | — | — | — | +| `resume` (synthetic) | `name`, `title`, `bio`, `email`, links | `*` | `*` | `*` | + +`home` does **not** claim `title` — the code scan shows Hero renders `name`/`roles`/`tagline` only; `title` is consumed by the resume generator, which the synthetic manifest now covers honestly. + +### 5.1 Validation rules (added to `validate.ts`) + +1. Manifest ids = the 7 route ids (`PageId` union, matching the router) + the synthetic `resume` consumer; no orphan or missing manifest. +2. Every `content[].entity` is a known entity; every field path resolves in the joined records (`"*"` always valid). +3. Every `ui` group name exists in the UI documents. +4. **No orphan fields:** every editable content text field must be claimed by at least one manifest. This makes drift mechanically caught in the dangerous direction — add a field to a text document without declaring which page shows it → `pnpm build` fails. The reverse drift (a manifest claims a field a page stopped rendering) is not mechanically detectable; it is caught by the review checklist "changing what a page renders includes updating its manifest". + +## 6. Edit-pipeline consequences + +6.1 **Document registry** (`draft.ts`): writable documents = 4 structure + 8 text. The 7 manifests and the 28 UI files are **read-only in the app** (manifests per `spec-v4-inline-editing.md` §3; UI per the v4 rule) — they are not draft baselines. Baselines, snapshots (sessionStorage `portfolio-draft`), path-diff, and rebase key off the writable registry — same code, data-driven list instead of a hardcoded six. + +6.2 **Save:** unchanged sequential-PUT pipeline; commit granularity per touched file. The Gitea repository must contain the new file layout before the proxy answers 200 (same dependency as live-edit row 11). + +6.3 **EditBar:** the changed-path diff gains page grouping — each changed path is annotated with the pages whose manifest claims it ("appears on: /about, home"). Grouping is computed from the manifests, not from component code. + +Grouping includes the synthetic `resume` manifest ("appears on: resume PDF"). + +6.4 **JsonPanel:** SUPERSEDED 2026-10-23 by `spec-v4-inline-editing.md` (E1) — the panel is deleted; structural editing moves to on-page controls. Manifests are read-only in the app (developer documents; the orphan-field validation rule is the enforcement). EditBar page grouping (6.3) stands. + +6.5 **Unchanged:** nginx `/api/content/` proxy and `vite.config.ts` (paths are already data-driven), the auth/session flow, branch targeting (D10), `scripts/smoke-draft.ts` (fixtures follow the new registry), `generate-resume.ts`, `generate-sitemap.ts`. + +## 7. Implementation order + +Order decided 2026-10-23: this spec lands **after** `spec-v4-inline-editing.md` — the panel is deleted against the current 6-document layout first, so grouped panel tabs are never built for a panel that is about to die. + +1. Split `content.{vi,en}.json` → `content/{entity}.json`; loader merge; per-pair validation. Gate: merged `CONTENT` output byte-identical to pre-split (automated diff before/after). +2. Split `ui.{vi,en}.json` → `ui/{group}.json`; loader merge. Gate: merged `UI` byte-identical. +3. Add `src/data/pages/*.json` + `pages.ts` + `PageId`/manifest types + validator rules 1–4. +4. `draft.ts` registry, snapshot keys, `smoke-draft.ts` fixtures. +5. ~~JsonPanel grouped tabs~~ → inline editing controls per `spec-v4-inline-editing.md` §5; EditBar page annotations stay in scope. +6. Docs: AGENTS.md Data Layer + Component Structure, live-edit spec §12 follow-up row. + +## 8. Acceptance criteria + +- [ ] Merged `CONTENT` and `UI` byte-identical before/after the split (automated comparison script, throwaway). +- [ ] `pnpm build`, `pnpm validate:content`, `pnpm lint` (no new warnings), `pnpm build:resume-all` pass. +- [ ] `pnpm tsx scripts/smoke-draft.ts` passes against the new registry. +- [ ] Validator rejects: unknown entity, unresolvable field path, orphan content field, unknown ui group, missing manifest. +- [ ] Edit mode end-to-end (browser): edit one bio line + one project summary → EditBar shows two documents with page annotations → save produces two per-file commits on the target branch. +- [ ] Browser walkthrough unchanged for visitors: all 7 routes, both languages, identical rendering. + +## 9. Progress Tracking + +| # | Task | Status | +|---|---|---| +| 0 | Design agreed (D1–D5) | ✅ Done 2026-10-23 | +| 1–6 | Implementation steps §7 | ⬜ TODO | +| — | Acceptance §8 | ⬜ TODO | diff --git a/docs/design/specs/v4/spec-v4-inline-editing.md b/docs/design/specs/v4/spec-v4-inline-editing.md new file mode 100644 index 0000000..b3e28d8 --- /dev/null +++ b/docs/design/specs/v4/spec-v4-inline-editing.md @@ -0,0 +1,116 @@ +# Specification — v4 Inline Editing (edit everything on the page; no JSON panel) + +Status: **Design agreed 2026-10-23; implementation TODO.** Supersedes the JSON-panel parts of `spec-v4-live-edit.md` §5.1 ("Structural editing") and `spec-v4-data-organization.md` §6.4. The save pipeline (§5.4/§6 of live-edit), DraftStore semantics, conflict handling, branch targeting (D10), and the EditBar all stay as specified. Order decided 2026-10-23: this spec lands **before** `spec-v4-data-organization.md`. + +## 1. Decisions + +| # | Decision | Rationale | +|---|---|---| +| E1 | **No JSON editing in the app.** `JsonPanel.tsx` is deleted; every editable thing gets an affordance on the page where it renders. | Owner requirement. The panel was a workaround for data types without a natural UI control; this spec builds those controls instead. | +| E2 | Rare structural fields (`featured`, `variant`, `logo`) are edited in a **per-record settings popover** — form controls (toggle, select, text input), never JSON text. | These fields have no inline text to wrap; a small form attached to the record is the minimal honest control. | +| E3 | Record ids are **generated from the title slug and never editable** in the UI. | Ids are published in URLs and in the `src/types/index.ts` id unions; renaming them is rare and breaks external links. Slug generation: lowercase, ASCII-folded (diacritics stripped), non-alphanumeric → `-`, collision → `-2`, `-3`… The existing union-append pipeline in `draft.ts` continues to run after a document lands. | +| E4 | Social links: documents store **handles only**; all three profile URLs are derived in the loader (`profile.ts`): `github.com/{githubHandle}`, `linkedin.com/in/{linkedinHandle}`, `t.me/{telegramHandle}`. Editing happens on the contact card itself. | `profile.json` today holds `githubUrl` + `githubHandle` — two sources for one fact; the current `telegramUrl` literal is exactly `https://t.me/dongdn`, so deriving it loses nothing. The resolved record (`c.profile.githubUrl` …) keeps the same shape, so every consumer (Contact cards, Footer, resume generator, `social.ts`) is unchanged. | +| E5 | Reorder ships in this pass: **↑/↓ controls** on tag chips and on records (timeline entries, project cards, skill groups, philosophy points, project sections). | Removing the panel would otherwise leave no reorder path at all. Array order remains the display order; the move mutates the owning document (structure for `technologies`/record order, text for `metrics`/`interests`/`roles`/`keywords`). | +| E6 | Editing is triggered **only by the small icon**, never by clicking the text. | Text stays selectable and copyable; no accidental edit mode. | +| E7 | Every edit control shows the **field's storage location** on demand: tooltip on the pencil (`document → pointer`), and a monospace chip on the active editor (`locales/vi/content.json → profile.bio`); clicking the chip copies the full repo path + pointer to the clipboard. | The owner learns which field each text lives in, so a path seen in the app is exactly what to open in the editor/Gitea or search for in an EditBar diff. The info already exists in the draft registry (`documentId`, `path`) — this only renders it. | + +## 2. Interaction model, by data type + +### 2.1 Text fields (upgrade of `EditableText`) + +- In edit mode each editable text renders inside a subtle wrapper zone (dashed 1px `--border` outline; hover/focus → `--accent`) with a pencil `