feat(i18n): per-entity content, per-group UI, page manifests (spec-v4-data-organization)

- split content.json -> content/{profile,skills,experience,projects}.json and
  ui.json -> 14 feature-group files (vi+en); index.ts merges both trees and
  asserts the merge against the group lists; merged CONTENT verified
  byte-identical against pre-split baseline dumps
- src/data/pages/*.json: 8 per-route manifests + pages.ts loader +
  PageId/PageManifestClaim/PageManifest types; validate.ts rules 1-4 (unknown
  entity, unknown ui group, unresolvable field path, orphan text field,
  missing manifest) - all five rejects verified by a throwaway harness
- draft.ts: data-driven registry of the 12 writable documents (4 structure +
  8 text); describeField() names the per-entity file; smoke-draft fixtures
  follow the new registry (8/8)
- EditBar: 'appears on' page annotations computed from the manifests
- remove JsonPanel.tsx + panel labels (inline-editing task 8); docs: AGENTS.md
  Data Layer / Live Edit Mode / Component Structure, v4 spec progress tables
This commit is contained in:
dong.nguyen committed 2026-10-23 10:55:29 +07:00
1 parent dad5f3edd7
commit 939260e4fb
69 files changed
+1816 -1596

No files matched your search

@@ -1,6 +1,6 @@
# 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.
Status: **Design agreed 2026-10-23; implemented 2026-10-23** (§9). Automated gates pass; the remaining open items are the owner's browser walkthrough (§8 last two rows) and pushing the new file layout to the Gitea content repository (live-edit row 11 dependency — the proxy answers 404 for paths the repository does not have). 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
@@ -146,10 +146,10 @@ Order decided 2026-10-23: this spec lands **after** `spec-v4-inline-editing.md`
## 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.
- [x] Merged `CONTENT` and `UI` byte-identical before/after the split (automated comparison script, throwaway). — verified 2026-10-23 against baseline dumps captured before the cutover: `CONTENT.vi`/`CONTENT.en` identical; `UI` differs only by the intentional label changes of the inline-editing cutover (panel labels removed, `edit.fields` + `appears*` labels added).
- [x] `pnpm build`, `pnpm validate:content`, `pnpm lint` (no new warnings), `pnpm build:resume-all` pass. — verified 2026-10-23; the resume generator consumes the merged `UI`/`CONTENT` with zero call-site changes, both PDFs render.
- [x] `pnpm tsx scripts/smoke-draft.ts` passes against the new registry. — 8/8 checks 2026-10-23, fixtures over `experience.json` / `experience.vi.json` / `projects.json`.
- [x] Validator rejects: unknown entity, unresolvable field path, orphan content field, unknown ui group, missing manifest. — verified 2026-10-23 by a throwaway mutation harness (all five rejects + a clean acceptance asserted); the unknown-ui-group rule caught a real mistake during implementation (`project-detail.json` naming the group by file name instead of namespace).
- [ ] 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.
@@ -158,5 +158,5 @@ Order decided 2026-10-23: this spec lands **after** `spec-v4-inline-editing.md`
| # | Task | Status |
|---|---|---|
| 0 | Design agreed (D1–D5) | ✅ Done 2026-10-23 |
| 1–6 | Implementation steps §7 | ⬜ TODO |
| — | Acceptance §8 | ⬜ TODO |
| 1–6 | Implementation steps §7 | ✅ Done 2026-10-23 — content split (4 files × 2 languages) + UI split (14 groups × 2) with merge asserted in `index.ts`; `src/data/pages/*.json` (8 manifests) + `pages.ts` + `PageId`/`PageManifestClaim`/`PageManifest` in `src/types/index.ts`; validator rules 1–4 in `validate.ts` (run at load and by `validate:content`); `draft.ts` registry data-driven over 12 writable documents (4 structure + 8 text, `entityOfDoc`/`docEntityMap` exported for provenance + EditBar); `describeField()` names the per-entity file automatically; EditBar "appears on" annotations via `manifestsClaiming`/`recordEntity`; AGENTS.md Data Layer + Live Edit Mode + Component Structure updated |
| — | Acceptance §8 | 🟡 Automated rows verified 2026-10-23 (see §8 checkboxes); browser rows open — the owner verifies in a real browser |
@@ -1,6 +1,6 @@
# 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`.
Status: **Design agreed 2026-10-23; implemented 2026-10-23** (see §7). The remaining gate is the owner's browser walkthrough of §6. 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` — both have now landed, in that order.
## 1. Decisions
@@ -113,6 +113,6 @@ Page manifests (`spec-v4-data-organization.md` §5) are **read-only in the app**
|---|---|---|
| 0 | Design agreed (E1–E7) | ✅ Done 2026-10-23 |
| 1–7 | Implementation §5 | ✅ Done 2026-10-23 — EditableText zone/pencil/provenance, TagListEditor over all tag arrays, tagline emphasis, `RecordControls` + `AddGhost` on every record surface (About, AboutPage, Expertise, Experience, ExperiencePage, Projects, ProjectsListPage, ProjectDetailPage incl. sections, PhilosophyPage), `RecordSettings` (featured, section list + type picker, variant, location, logo), id-slug rename on title commit, per-field conflict UI in EditBar; chrome CSS in `App.css`, labels in both `ui.json` |
| 8 | Remove `JsonPanel` + panel labels | ⬜ TODO — kept until the inline surface is verified in a real browser |
| 9 | Docs superseded notes | ⬜ TODO |
| — | Acceptance §6 | 🟡 Partial — `pnpm build`, `pnpm validate:content`, `pnpm lint` (no new warnings), `pnpm tsx scripts/smoke-draft.ts` pass 2026-10-23; browser verification of the edit surfaces pending (user verifies in a real browser) |
| 8 | Remove `JsonPanel` + panel labels | ✅ Done 2026-10-23 — `JsonPanel.tsx` deleted (already orphaned by the inline wiring; no imports remained); panel labels removed from both UI documents: `openPanel`, `closePanel`, `handMerge`, the whole `edit.panel.*` namespace |
| 9 | Docs superseded notes | ✅ Done 2026-10-23 — superseded notes at live-edit §5.1 (panel shape) and §12 row 14; AGENTS.md "Live Edit Mode" + "Component Structure" rewritten for the inline surface |
| — | Acceptance §6 | 🟡 Partial — `pnpm build`, `pnpm validate:content`, `pnpm lint` (no new warnings), `pnpm tsx scripts/smoke-draft.ts`, `pnpm build:resume-all` pass 2026-10-23; browser verification of the edit surfaces pending (user verifies in a real browser) |
@@ -599,3 +599,4 @@ Deferred (not v4):
| 18 | Move the three person-content keys out of `ui.json` (§11): `about.subtitle` → `profile.subtitle`, `experience.tldrText` → `profile.tldr`, `philosophy.quotes` → `profile.philosophyQuotes`; extend `ProfileText`, repoint 4 call sites, `EditableText` wrap + `SectionHeading` `subtitle: ReactNode`, JsonPanel hint update; `tsc` is the migration net | post-v4 | ✅ Done 2026-10-22 (automated) — values in both `content.{vi,en}.json`, keys deleted from both `ui` documents, `edit.fields` labels added; verified: `pnpm build`, `pnpm validate:content`, `pnpm lint` (no new warnings), `scripts/smoke-draft.ts` 7/7, throwaway SSR smoke asserting the subtitle / TL;DR / essay markers on `/about`, home + `/experience`, `/philosophy` in both languages — deleted after the run. ⬜ Browser: inline-edit the three fields in `?edit` |
| 19 | Localize the §4 structure-assigned strings (`experience.company` of non-company entries, `duration`, `currentInterests`, `roles`, `keywords`, `projects.role`/`metrics`) or keep them EN-only like `technologies` | post-v4 | ✅ Done 2026-10-22 (automated) — fields moved to the text documents (§4 follow-up); VI document carries localized values (numeric dates + "nay", "Sẵn sàng cho cơ hội mới", "Nghỉ giữa chặng", "Đã triển khai tại 16 sortations", "Xử lý 70.000 ảnh/tháng"), en overrides with the originals, proper nouns and term lists identical (en omits); company/duration/role inline-editable, tag arrays JSON-panel-only; templates in `draft.ts` and JsonPanel hints follow the new shapes; resume generator reads `profile.tldr` from content. Verified: `pnpm build`, `pnpm validate:content`, `pnpm lint` (no new warnings), `pnpm build:resume-all` (both PDFs), SSR smoke marker sets per language incl. localized durations/companies/metrics/roles on home + `/experience` + project detail — deleted after the run. ⬜ Browser: VI pages show the localized timeline; `?edit` company/duration/role |
| 20 | Save pipeline adapted to the live Gitea 28 Contents API | 3 | ✅ Done 2026-10-23 — the first real save answered 422 "repository file already exists [path: src/i18n/locales/vi/content.json]": Gitea 28 decides create-vs-update by the body `sha` (blob ID), which the client never sent. `draft.ts`: `fetchDoc`/`fetchTextFile` keep the blob `sha`; PUT bodies send `sha`; the new blob sha is read from the FileResponse `content.sha`; save conflict detection = 422 with a "does not match" message (412 kept for older deployments); §6.1 amended. Verified: `tsc -b`, `pnpm lint` (no new warnings), `scripts/smoke-draft.ts` 8/8. ⬜ Browser + Gitea: save → commit lands on the target branch; stale blob sha → conflict flow |
| 21 | v4 cutover: `spec-v4-inline-editing.md` E1–E7 (pencil-trigger inline editing, chip tag editors, ghost record add/delete/move, settings popovers, auto-ids, handle-only socials, `JsonPanel.tsx` deleted) + `spec-v4-data-organization.md` (content per entity, UI in 14 groups, per-route manifests + validator rules 1–4, 12-document draft registry, EditBar "appears on" annotations) | post-v4 | ✅ Done 2026-10-23 (automated) — details and evidence in each spec's Progress Tracking: the split is gated against baseline dumps (merged `CONTENT` byte-identical both languages; `UI` differs only by the intentional label changes), the manifest validator rejects all five bad cases (unknown entity / field path / orphan field / ui group / missing manifest), `smoke-draft.ts` 8/8 on the new registry, `tsc -b`, `pnpm build`, `pnpm lint` (no new warnings), `pnpm build:resume-all` all pass. ⬜ Browser: edit-mode walkthrough (pencil-only editing, provenance chips, save → per-file commits with page annotations) + visitor routes unchanged; the Gitea content repository must carry the new file layout before saves answer 200 (row 11 dependency) |