From 939260e4fb294d6144046a40dab299d53ef61a77 Mon Sep 17 00:00:00 2001 From: "dong.nguyen" Date: Fri, 23 Oct 2026 10:55:29 +0700 Subject: [PATCH] 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 --- AGENTS.md | 25 +- .../specs/v4/spec-v4-data-organization.md | 14 +- .../design/specs/v4/spec-v4-inline-editing.md | 8 +- docs/design/specs/v4/spec-v4-live-edit.md | 1 + scripts/smoke-draft.ts | 53 +-- scripts/validate-content.ts | 45 ++- src/App.css | 145 +------- src/components/layout/EditBar.tsx | 48 ++- src/components/layout/EditModeShell.tsx | 28 +- src/components/layout/JsonPanel.tsx | 291 --------------- src/components/sections/Hero.tsx | 14 +- src/components/ui/EditableText.tsx | 25 +- src/components/ui/TagListEditor.tsx | 22 +- src/data/pages.ts | 75 ++++ src/data/pages/about.json | 12 + src/data/pages/contact.json | 19 + src/data/pages/experience.json | 9 + src/data/pages/home.json | 29 ++ src/data/pages/philosophy.json | 8 + src/data/pages/project-detail.json | 11 + src/data/pages/projects.json | 8 + src/data/pages/resume.json | 25 ++ src/hooks/useEdit.ts | 27 +- src/i18n/dict-types.ts | 40 ++- src/i18n/draft.ts | 331 ++++++++++++------ src/i18n/index.ts | 104 +++++- src/i18n/locales/en/content.json | 143 -------- src/i18n/locales/en/content/experience.json | 39 +++ src/i18n/locales/en/content/profile.json | 37 ++ src/i18n/locales/en/content/projects.json | 65 ++++ src/i18n/locales/en/content/skills.json | 1 + src/i18n/locales/en/ui.json | 235 ------------- src/i18n/locales/en/ui/about.json | 7 + src/i18n/locales/en/ui/common.json | 10 + src/i18n/locales/en/ui/contact.json | 7 + src/i18n/locales/en/ui/edit.json | 105 ++++++ src/i18n/locales/en/ui/experience.json | 4 + src/i18n/locales/en/ui/expertise.json | 3 + src/i18n/locales/en/ui/footer.json | 9 + src/i18n/locales/en/ui/hero.json | 6 + src/i18n/locales/en/ui/navigation.json | 27 ++ src/i18n/locales/en/ui/philosophy.json | 3 + src/i18n/locales/en/ui/project-detail.json | 8 + src/i18n/locales/en/ui/projects.json | 14 + src/i18n/locales/en/ui/resume.json | 7 + src/i18n/locales/en/ui/social.json | 9 + src/i18n/locales/vi/content.json | 261 -------------- src/i18n/locales/vi/content/experience.json | 47 +++ src/i18n/locales/vi/content/profile.json | 92 +++++ src/i18n/locales/vi/content/projects.json | 100 ++++++ src/i18n/locales/vi/content/skills.json | 20 ++ src/i18n/locales/vi/ui.json | 235 ------------- src/i18n/locales/vi/ui/about.json | 7 + src/i18n/locales/vi/ui/common.json | 10 + src/i18n/locales/vi/ui/contact.json | 7 + src/i18n/locales/vi/ui/edit.json | 105 ++++++ src/i18n/locales/vi/ui/experience.json | 4 + src/i18n/locales/vi/ui/expertise.json | 3 + src/i18n/locales/vi/ui/footer.json | 9 + src/i18n/locales/vi/ui/hero.json | 6 + src/i18n/locales/vi/ui/navigation.json | 27 ++ src/i18n/locales/vi/ui/philosophy.json | 3 + src/i18n/locales/vi/ui/project-detail.json | 8 + src/i18n/locales/vi/ui/projects.json | 14 + src/i18n/locales/vi/ui/resume.json | 7 + src/i18n/locales/vi/ui/social.json | 9 + src/i18n/validate.ts | 220 ++++++++++-- src/pages/PhilosophyPage.tsx | 26 +- src/types/index.ts | 36 ++ 69 files changed, 1816 insertions(+), 1596 deletions(-) delete mode 100644 src/components/layout/JsonPanel.tsx create mode 100644 src/data/pages.ts create mode 100644 src/data/pages/about.json create mode 100644 src/data/pages/contact.json create mode 100644 src/data/pages/experience.json create mode 100644 src/data/pages/home.json create mode 100644 src/data/pages/philosophy.json create mode 100644 src/data/pages/project-detail.json create mode 100644 src/data/pages/projects.json create mode 100644 src/data/pages/resume.json delete mode 100644 src/i18n/locales/en/content.json create mode 100644 src/i18n/locales/en/content/experience.json create mode 100644 src/i18n/locales/en/content/profile.json create mode 100644 src/i18n/locales/en/content/projects.json create mode 100644 src/i18n/locales/en/content/skills.json delete mode 100644 src/i18n/locales/en/ui.json create mode 100644 src/i18n/locales/en/ui/about.json create mode 100644 src/i18n/locales/en/ui/common.json create mode 100644 src/i18n/locales/en/ui/contact.json create mode 100644 src/i18n/locales/en/ui/edit.json create mode 100644 src/i18n/locales/en/ui/experience.json create mode 100644 src/i18n/locales/en/ui/expertise.json create mode 100644 src/i18n/locales/en/ui/footer.json create mode 100644 src/i18n/locales/en/ui/hero.json create mode 100644 src/i18n/locales/en/ui/navigation.json create mode 100644 src/i18n/locales/en/ui/philosophy.json create mode 100644 src/i18n/locales/en/ui/project-detail.json create mode 100644 src/i18n/locales/en/ui/projects.json create mode 100644 src/i18n/locales/en/ui/resume.json create mode 100644 src/i18n/locales/en/ui/social.json delete mode 100644 src/i18n/locales/vi/content.json create mode 100644 src/i18n/locales/vi/content/experience.json create mode 100644 src/i18n/locales/vi/content/profile.json create mode 100644 src/i18n/locales/vi/content/projects.json create mode 100644 src/i18n/locales/vi/content/skills.json delete mode 100644 src/i18n/locales/vi/ui.json create mode 100644 src/i18n/locales/vi/ui/about.json create mode 100644 src/i18n/locales/vi/ui/common.json create mode 100644 src/i18n/locales/vi/ui/contact.json create mode 100644 src/i18n/locales/vi/ui/edit.json create mode 100644 src/i18n/locales/vi/ui/experience.json create mode 100644 src/i18n/locales/vi/ui/expertise.json create mode 100644 src/i18n/locales/vi/ui/footer.json create mode 100644 src/i18n/locales/vi/ui/hero.json create mode 100644 src/i18n/locales/vi/ui/navigation.json create mode 100644 src/i18n/locales/vi/ui/philosophy.json create mode 100644 src/i18n/locales/vi/ui/project-detail.json create mode 100644 src/i18n/locales/vi/ui/projects.json create mode 100644 src/i18n/locales/vi/ui/resume.json create mode 100644 src/i18n/locales/vi/ui/social.json diff --git a/AGENTS.md b/AGENTS.md index f6ebf4e..2673351 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,7 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript | `pnpm build:resume` | Generate resume PDF (default EN) via Playwright | | `pnpm build:resume-all` | Generate bilingual resume PDFs (EN + VI) | | `pnpm lint` | Run Oxlint | -| `pnpm validate:content` | Validate the content dictionaries against the structure documents (also run by the loader at module load) | +| `pnpm validate:content` | Validate the content dictionaries against the structure documents and the page manifests (also run by the loader at module load) | | `pnpm sitemap` | Regenerate `dist/sitemap.xml` on its own (also run by `pnpm build`) | | `pnpm preview` | Preview production build locally | @@ -67,14 +67,15 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript ## Data Layer -Content is split once, at authoring time, into language-neutral **structure documents** and per-language **text/UI dictionaries**, joined once at load (spec: `docs/design/specs/v4/spec-v4-live-edit.md`). +Content is split once, at authoring time, into language-neutral **structure documents**, per-language **text/UI dictionaries** — one file per entity (`content/{entity}.json`) and per feature group (`ui/{group}.json`) — and per-route **field manifests** (`src/data/pages/`), joined once at load (spec: `docs/design/specs/v4/spec-v4-live-edit.md` + `spec-v4-data-organization.md`). - `src/data/profile.json` + `profile.ts` loader — links, social handles (`githubHandle`, `linkedinHandle`, `telegramHandle`), messaging URLs (`telegramUrl`), `firstName`/`lastName`, the ordered philosophy id list — the Contact cards render `@{c.profile.githubHandle}`, never a literal; name / title / tagline / bio / about-subtitle / career TL;DR / interests / roles / philosophy quotes + keywords are text, so they live in the content dictionaries - `src/data/skills.json` + `skills.ts` loader — skill groups: `{id, skills}`; group titles are text - `src/data/experience.json` + `experience.ts` loader — work history: id / location / logo / optional `variant: 'current' | 'gap'` (timeline decoration: live node / career break); company, duration, titles and responsibilities are text — the VI document carries localized dates ("11/2026 – nay") and company labels, en overrides with the originals, proper nouns identical per language - `src/data/projects.json` + `projects.ts` loader — cards: category / technologies / featured / `sections[].{id, type}`; titles, summaries, role, metrics and section prose are text (role follows the owner's EN title convention; metrics are localized) -- `src/i18n/locales/{vi,en}/content.json` — all content text, keyed by the structure ids; the `profile` record is fixed-keyed (`name`, `title`, `bio`, `subtitle`, `tldr`, `tagline`, `currentInterests`, `roles`, `philosophyQuotes`, `philosophy..{title, description, keywords}`); `src/i18n/locales/{vi,en}/ui.json` — chrome strings only, in each language (nav group labels, Mode options, language names `langEn` / `langVi`, action labels, social `aria-label`s, the resume's section labels, edit-mode labels) — person text never lives here -- `src/i18n/index.ts` — load + validate + join ONCE at module load; exports `UI` and `CONTENT` as `Record`; `src/i18n/dict-types.ts` carries the document types; `src/i18n/validate.ts` + `scripts/validate-content.ts` enforce the cross-document rules (orphan or missing keys, HTML markup in text values) — a malformed document fails `pnpm build`, CI, and the browser load, never a silent half-render +- `src/i18n/locales/{vi,en}/content/{profile,skills,experience,projects}.json` — all content text, one file per entity, keyed by the structure ids; the `profile` record is fixed-keyed (`name`, `title`, `bio`, `subtitle`, `tldr`, `tagline`, `currentInterests`, `roles`, `philosophyQuotes`, `philosophy..{title, description, keywords}`); `src/i18n/locales/{vi,en}/ui/{group}.json` — 14 chrome groups (`navigation`, `footer`, `social`, `hero`, `about`, `expertise`, `experience`, `projects`, `projectDetail`, `contact`, `philosophy`, `resume`, `edit`, `common`), in each language (nav group labels, Mode options, language names `langEn` / `langVi`, action labels, social `aria-label`s, the resume's section labels, edit-mode labels) — person text never lives here; `src/i18n/index.ts` merges both trees back into the same `UI`/`CONTENT` records and asserts the merge against the group lists — a group dropped in the split is a load-time error, never a silent omission +- `src/data/pages/{home,about,experience,projects,project-detail,contact,philosophy,resume}.json` + `pages.ts` loader — per-route manifests: which entity fields the page renders (`fields[]`; `*` = every field the record id owns) and which UI groups it reads; `src/types/index.ts` carries `PageId` / `PageManifestClaim` / `PageManifest`. The validator enforces: no unknown entity, no unknown UI group, no unresolvable field path, **no orphan text field** (every text leaf in the content documents is claimed by at least one manifest), no missing manifest for a route in `src/data/navigation.ts` plus `/projects/:id` +- `src/i18n/index.ts` — load + validate + join ONCE at module load; exports `UI` and `CONTENT` as `Record`; `src/i18n/dict-types.ts` carries the document types; `src/i18n/validate.ts` + `scripts/validate-content.ts` enforce the cross-document rules (orphan or missing keys, HTML markup in text values, the manifest rules above) — a malformed document fails `pnpm build`, CI, and the browser load, never a silent half-render - `src/i18n/provider.tsx` — `I18nProvider` wraps the app; components consume `const { ui: s, content: c } = useI18n()`: `s` is the chrome of the current language, `c` the joined records (`c.profile`, `c.skillGroups`, `c.experiences`, `c.projects`). There is no `field()` and no `*En` field pair anymore - Translation is a JSON edit, never a component edit; a new language is a new locale directory plus one `Language` union member - `src/data/resume.ts` — resume availability, supported languages, URL generation, and `resumeQr` (the `{id, file, label}` descriptors the resume header renders as QR codes) @@ -87,10 +88,10 @@ Content is split once, at authoring time, into language-neutral **structure docu - Entry: any route with `?edit` — `MaybeEditMode` in `App.tsx` lazy-mounts `EditModeShell` (its own chunk; visitors never load edit code). The shell authenticates, fetches the live master documents through the proxy, and re-wraps the tree in an `I18nProvider` override — the seven routes ARE the preview - Target branch (spec D10): `?edit=` reads (`?ref=`) and writes (`branch` in the PUT body) that branch; a bare `?edit` resumes the session's last branch, default `master`. Names are validated against git ref rules in `src/i18n/edit-mode.ts` before any request (illegal → exit like a failed auth); the branch is stored beside the session flag. The target branch must already exist — Contents API updates never create branches. Only `master` deploys, so the EditBar shows a merge hint on other branches - Auth: HTTP Basic at the nginx `/api/content/` proxy is the security boundary; `src/i18n/edit-mode.ts` probes it through a hidden iframe, keeps the session flag `portfolio-edit` in sessionStorage, and strips `?edit` when the probe fails (401 or cancelled prompt → normal visitor site) -- `src/i18n/draft.ts` — `DraftStore`: baselines (`data` + blob `sha`) of the six content documents, copy-on-write draft, leaf-path diff, cross-document validation on every accepted edit, three-way rebase on save conflicts (Gitea 28 reports a blob-sha mismatch as 422 with a "does not match" message; older deployments answered 412 — both are handled; 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/i18n/draft.ts` — `DraftStore`: baselines (`data` + blob `sha`) of the 12 writable documents (4 structure + 8 text), copy-on-write draft, leaf-path diff, cross-document validation on every accepted edit, three-way rebase on save conflicts (Gitea 28 reports a blob-sha mismatch as 422 with a "does not match" message; older deployments answered 412 — both are handled; 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. **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 +- `src/components/layout/EditBar.tsx` — fixed save bar: per-path diff with revert and "appears on" page annotations (computed from the page manifests via `manifestsClaiming`, never from component code), conflict resolution (rebase / take-theirs / per-field keep-mine–keep-theirs), per-document save status, partial-save resume, exit confirm +- Editable surface: content text inline (pencil-triggered, click never edits) **and** structure — chip-level tag editors (technologies, categories, interests, roles, keywords, tagline emphasis), ghost add/delete/move on every record surface, per-record settings popover (`featured`, project section list + type picker, `variant`, location, logo), ids auto-generated from title slugs, social links handle-only with URLs derived in the loaders. Implemented 2026-10-23 (`spec-v4-inline-editing.md` + `spec-v4-data-organization.md`); the JSON panel is deleted. UI documents stay read-only in v4. Field provenance: hovering any pencil shows `document → pointer` (`describeField()` names the per-entity file automatically); the EditBar diff line and a `validate:content` error for the same field read identically - 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 @@ -99,11 +100,11 @@ Content is split once, at authoring time, into language-neutral **structure docu ``` src/ components/ - layout/ — Layout.tsx, Navigation.tsx, MobileMenu.tsx, Footer.tsx, ThemePaletteMenu.tsx, ResumeNavButton.tsx, EditModeShell.tsx, EditBar.tsx, JsonPanel.tsx + layout/ — Layout.tsx, Navigation.tsx, MobileMenu.tsx, Footer.tsx, ThemePaletteMenu.tsx, ResumeNavButton.tsx, EditModeShell.tsx, EditBar.tsx sections/ — Hero, About, Expertise, Experience, Projects, Contact, HeroParticles, DownloadResume (the hero lazer CTA; it gates itself on `resumeAvailable`) - ui/ — Badge, Button, ContactLinks, LanguageIcon, ResumeDialog, SectionHeading, SocialLinks, Tag, Typewriter, InView, RollingTextLink, BackToTop, EditableText, icons - data/ — profile, skills, experience, projects (JSON documents + typed loaders), resume, palettes, navigation, social, site (TS modules) - i18n/ — index.ts (loader), dict-types.ts, validate.ts, provider.tsx, draft.ts (DraftStore + save pipeline), edit-mode.ts (session/auth), locales/{vi,en}/{content,ui}.json + ui/ — Badge, Button, ContactLinks, LanguageIcon, ResumeDialog, SectionHeading, SocialLinks, Tag, Typewriter, InView, RollingTextLink, BackToTop, EditableText, TagListEditor, RecordControls, RecordSettings, icons + data/ — profile, skills, experience, projects (JSON documents + typed loaders), pages (manifest JSON + pages.ts loader), resume, palettes, navigation, social, site (TS modules) + i18n/ — index.ts (loader), dict-types.ts, validate.ts, provider.tsx, draft.ts (DraftStore + save pipeline), edit-mode.ts (session/auth), locales/{vi,en}/content/{profile,skills,experience,projects}.json + ui/{group}.json (14 chrome groups) hooks/ — useTheme.tsx, useLanguage.tsx, useClickOutside.ts, useResumeDialog.ts, useEdit.ts (edit context) pages/ — HomePage, AboutPage, ExperiencePage, ProjectsListPage, ProjectDetailPage, PhilosophyPage, ContactPage types/ — shared TypeScript interfaces @@ -190,7 +191,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). `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 | +| `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 — implemented 2026-10-23 (automated checks pass; browser walkthrough pending). `spec-v4-inline-editing.md`: edit everything on the page (pencil-icon triggers, tag chips, record add/delete/move, settings popover), JSON panel deleted — implemented 2026-10-23; it supersedes live-edit §5.1/§5.4 panel scope | 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 index f32f37c..567b079 100644 --- a/docs/design/specs/v4/spec-v4-data-organization.md +++ b/docs/design/specs/v4/spec-v4-data-organization.md @@ -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 | diff --git a/docs/design/specs/v4/spec-v4-inline-editing.md b/docs/design/specs/v4/spec-v4-inline-editing.md index f2feb5b..01709e1 100644 --- a/docs/design/specs/v4/spec-v4-inline-editing.md +++ b/docs/design/specs/v4/spec-v4-inline-editing.md @@ -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) | diff --git a/docs/design/specs/v4/spec-v4-live-edit.md b/docs/design/specs/v4/spec-v4-live-edit.md index 1f1134d..42762bf 100644 --- a/docs/design/specs/v4/spec-v4-live-edit.md +++ b/docs/design/specs/v4/spec-v4-live-edit.md @@ -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) | diff --git a/scripts/smoke-draft.ts b/scripts/smoke-draft.ts index 75e38f0..4656de4 100644 --- a/scripts/smoke-draft.ts +++ b/scripts/smoke-draft.ts @@ -1,4 +1,5 @@ -// Throwaway smoke test for the draft store (spec-v4 §5.1, §5.5, §5.6). +// Throwaway smoke test for the draft store (spec-v4 §5.1, §5.5, §5.6; +// registry per spec-v4-data-organization §6.1). // Run: pnpm tsx scripts/smoke-draft.ts import { DraftStore, bundledBase } from '../src/i18n/draft'; @@ -13,28 +14,30 @@ const store = new DraftStore(structuredClone(bases)); const projects = store.dataOf('projects') as { id: string }[]; const firstProject = projects[0].id; -// 1. setValue on a text path is accepted and tracked. +// 1. setValue on a text path is accepted and tracked in the entity document +// of the edited language; the diff stores the document-relative pointer. const rejected = store.setValue('vi', `projects.${firstProject}.summary`, 'SUMMARY CHANGED'); if (rejected !== null) fail(`valid edit rejected: ${JSON.stringify(rejected)}`); if (!store.isDirty()) fail('store not dirty after accepted edit'); -const paths = store.changedPaths('content.vi'); -if (!paths.includes(`projects.${firstProject}.summary`)) fail(`path not diffed: ${paths}`); +const paths = store.changedPaths('projects.vi'); +if (!paths.includes(`${firstProject}.summary`)) fail(`path not diffed: ${paths}`); // 2. Empty required value is rejected and leaves the draft untouched. -const before = structuredClone(store.dataOf('content.vi')); +const before = structuredClone(store.dataOf('profile.vi')); const empty = store.setValue('vi', 'profile.bio', ' '); if (empty === null) fail('empty required value accepted'); -if (JSON.stringify(store.dataOf('content.vi')) !== JSON.stringify(before)) fail('rejected edit mutated draft'); +if (JSON.stringify(store.dataOf('profile.vi')) !== JSON.stringify(before)) + fail('rejected edit mutated draft'); // 3. Delete removes the structure record AND both text entries — no orphan. const del = store.deleteRecord('project', { id: firstProject }); if (del !== null) fail(`delete rejected: ${JSON.stringify(del)}`); const stillListed = (store.dataOf('projects') as { id: string }[]).some((p) => p.id === firstProject); if (stillListed) fail('project still in structure after delete'); -const vi = store.dataOf('content.vi') as Record>; -const en = store.dataOf('content.en') as Record>; -if (vi.projects[firstProject]) fail('vi text orphan after delete'); -if (en.projects[firstProject]) fail('en text orphan after delete'); +const viText = store.dataOf('projects.vi') as Record; +const enText = store.dataOf('projects.en') as Record; +if (viText[firstProject]) fail('vi text orphan after delete'); +if (enText[firstProject]) fail('en text orphan after delete'); const issues = store.validate(); if (issues.length > 0) fail(`validate after delete: ${JSON.stringify(issues)}`); @@ -61,37 +64,37 @@ if (!same) fail('restored draft differs from saved snapshot'); const store2 = new DraftStore(structuredClone(bases)); store2.setValue('vi', `projects.${firstProject}.summary`, 'MINE'); const driftedBase = structuredClone(bases); -(driftedBase['content.vi'].data as Record>).projects[firstProject].summary = 'THEIRS'; -store2.resetBase('content.vi', driftedBase['content.vi']); -const rebaseIssues = store2.rebase('content.vi'); +(driftedBase['projects.vi'].data as Record>)[firstProject].summary = 'THEIRS'; +store2.resetBase('projects.vi', driftedBase['projects.vi']); +const rebaseIssues = store2.rebase('projects.vi'); if (rebaseIssues === null) fail('rebase silently took one side on a real conflict'); -store2.discardDocument('content.vi'); -if (store2.isPathDirty(`projects.${firstProject}.summary`)) fail('take-theirs left draft residue'); +store2.discardDocument('projects.vi'); +if (store2.changedPaths('projects.vi').includes(`${firstProject}.summary`)) + fail('take-theirs left draft residue'); // 7. Clean rebase: base changed at a DIFFERENT path → draft edit survives. const store3 = new DraftStore(structuredClone(bases)); store3.setValue('vi', `projects.${firstProject}.summary`, 'MINE'); const otherBase = structuredClone(bases); const otherId = projects[1].id; -(otherBase['content.vi'].data as Record>).projects[otherId].summary = 'THEIRS'; -store3.resetBase('content.vi', otherBase['content.vi']); -const clean = store3.rebase('content.vi'); +(otherBase['projects.vi'].data as Record>)[otherId].summary = 'THEIRS'; +store3.resetBase('projects.vi', otherBase['projects.vi']); +const clean = store3.rebase('projects.vi'); if (clean !== null) fail(`clean rebase rejected: ${JSON.stringify(clean)}`); -const merged = (store3.dataOf('content.vi') as Record>).projects; -if (merged[firstProject].summary !== 'MINE') fail('rebase lost the draft edit'); -if (merged[otherId].summary !== 'THEIRS') fail('rebase lost the base edit'); +const mergedText = store3.dataOf('projects.vi') as Record>; +if (mergedText[firstProject].summary !== 'MINE') fail('rebase lost the draft edit'); +if (mergedText[otherId].summary !== 'THEIRS') fail('rebase lost the base edit'); // 8. A text document that does not hold an array field yet (an older target // branch — the field still lives in the structure document) must gain a real // array when a [0] path is committed; an object-keyed pseudo-array crashed // TagListEditor's items.map on the re-render after the first tag edit. const store4 = new DraftStore(structuredClone(bases)); -const baseVi = store4.dataOf('content.vi') as Record>; -delete baseVi.profile.currentInterests; +const baseVi = store4.dataOf('profile.vi') as Record>; +delete baseVi.currentInterests; const tagEdit = store4.setValue('vi', 'profile.currentInterests[0]', 'NEW TAG'); if (tagEdit !== null) fail(`tag edit rejected: ${JSON.stringify(tagEdit)}`); -const arr = (store4.dataOf('content.vi') as Record>).profile - .currentInterests; +const arr = (store4.dataOf('profile.vi') as Record>).currentInterests; if (!Array.isArray(arr)) fail(`setPath made ${JSON.stringify(arr)}, not an array`); if (arr[0] !== 'NEW TAG') fail('array element not set'); diff --git a/scripts/validate-content.ts b/scripts/validate-content.ts index 20e5fce..f41ba5f 100644 --- a/scripts/validate-content.ts +++ b/scripts/validate-content.ts @@ -1,23 +1,42 @@ -// CLI over the shared validator (spec-v4 §3.6): the CI build gate and, from -// Phase 3 on, the save gate. A malformed content document fails here with -// exact document paths, so the last good deploy stays live. +// CLI over the shared validator (spec-v4 §3.6, spec-v4-data-organization §5.1): +// the CI build gate and, from Phase 3 on, the save gate. A malformed content +// or manifest document fails here with exact file paths, so the last good +// deploy stays live. import { experiences } from '../src/data/experience'; import { profile } from '../src/data/profile'; import { projects } from '../src/data/projects'; import { skillGroups } from '../src/data/skills'; -import contentEnJson from '../src/i18n/locales/en/content.json'; -import contentViJson from '../src/i18n/locales/vi/content.json'; +import experienceEnJson from '../src/i18n/locales/en/content/experience.json'; +import experienceViJson from '../src/i18n/locales/vi/content/experience.json'; +import profileEnJson from '../src/i18n/locales/en/content/profile.json'; +import profileViJson from '../src/i18n/locales/vi/content/profile.json'; +import projectsEnJson from '../src/i18n/locales/en/content/projects.json'; +import projectsViJson from '../src/i18n/locales/vi/content/projects.json'; +import skillsEnJson from '../src/i18n/locales/en/content/skills.json'; +import skillsViJson from '../src/i18n/locales/vi/content/skills.json'; +import { UI } from '../src/i18n'; import type { ContentEn, ContentVi } from '../src/i18n/dict-types'; -import { collectContentIssues } from '../src/i18n/validate'; +import { collectContentIssues, collectManifestIssues } from '../src/i18n/validate'; -const contentVi: ContentVi = contentViJson; -const contentEn: ContentEn = contentEnJson; +const contentVi: ContentVi = { + profile: profileViJson, + skills: skillsViJson, + experience: experienceViJson, + projects: projectsViJson, +}; +const contentEn: ContentEn = { + profile: profileEnJson, + skills: skillsEnJson, + experience: experienceEnJson, + projects: projectsEnJson, +}; -const issues = collectContentIssues( - { profile, skills: skillGroups, experience: experiences, projects }, - contentVi, - contentEn, -); +const structures = { profile, skills: skillGroups, experience: experiences, projects }; + +const issues = [ + ...collectContentIssues(structures, contentVi, contentEn), + ...collectManifestIssues(structures, contentVi, contentEn, Object.keys(UI.vi)), +]; if (issues.length > 0) { console.error(`content validation failed (${issues.length} issue(s)):`); diff --git a/src/App.css b/src/App.css index 15f3d4e..0e475d4 100644 --- a/src/App.css +++ b/src/App.css @@ -2229,6 +2229,11 @@ white-space: nowrap; } +.edit-bar-appears { + color: var(--text-muted); + font-size: 12px; +} + .edit-bar-conflicts { margin-top: 10px; display: grid; @@ -2265,142 +2270,6 @@ color: var(--success); } -.json-panel { - position: fixed; - top: 0; - right: 0; - bottom: 0; - z-index: 950; - width: min(620px, 100%); - background: var(--bg-elevated); - border-left: 1px solid var(--border-strong); - padding: 14px 16px; - overflow-y: auto; - display: flex; - flex-direction: column; - gap: 10px; - font-size: 13px; -} - -.json-panel-head { - display: flex; - align-items: center; - justify-content: space-between; -} - -.json-panel-tabs { - display: flex; - flex-wrap: wrap; - gap: 6px; -} - -.json-panel-tab { - background: transparent; - border: 1px solid var(--border); - border-radius: 6px; - padding: 4px 8px; - color: var(--text-secondary); - font: inherit; - font-size: 12px; - cursor: pointer; -} - -.json-panel-tab.is-active { - border-color: var(--accent); - color: var(--accent); -} - -.json-panel-conflict-flag { - color: var(--warning); -} - -.json-panel-shape { - margin: 0; - padding: 8px 10px; - background: var(--bg-surface); - border: 1px solid var(--border); - border-radius: 8px; - color: var(--text-muted); - font-size: 12px; - white-space: pre-wrap; -} - -.json-panel-tools, -.json-panel-records { - display: flex; - flex-wrap: wrap; - align-items: center; - gap: 8px; -} - -.json-panel-record { - display: inline-flex; - align-items: center; - gap: 6px; - border: 1px solid var(--border); - border-radius: 6px; - padding: 3px 8px; - color: var(--text-secondary); -} - -.json-panel-readonly { - color: var(--text-muted); -} - -.json-panel-section-add select { - background: var(--bg-surface); - color: var(--text-primary); - border: 1px solid var(--border-strong); - border-radius: 6px; - padding: 4px 6px; - font: inherit; - font-size: 12px; -} - -.json-panel-merge { - display: grid; - gap: 6px; - border: 1px solid var(--warning); - border-radius: 8px; - padding: 8px 10px; -} - -.json-panel-merge textarea { - min-height: 140px; -} - -.json-panel-editor { - flex: 1; - min-height: 300px; - background: var(--bg-surface); - color: var(--text-primary); - border: 1px solid var(--border-strong); - border-radius: 8px; - padding: 10px; - font-family: ui-monospace, 'Cascadia Mono', 'Consolas', monospace; - font-size: 12.5px; - line-height: 1.5; - resize: vertical; -} - -.json-panel-editor:focus-visible { - outline: 2px solid var(--accent); - outline-offset: 1px; -} - -.json-panel-issues { - margin: 0; - padding: 0; - list-style: none; - display: grid; - gap: 3px; - color: var(--error); -} - -.json-panel-status { - color: var(--text-muted); -} - /* Inline editing affordances (§5.3): outline only — the element itself stays the site's own, so the page keeps its exact rendering outside edit mode. */ .editable-text { @@ -2682,10 +2551,6 @@ } @media (max-width: 768px) { - .json-panel { - width: 100%; - } - .edit-bar-actions { margin-left: 0; } diff --git a/src/components/layout/EditBar.tsx b/src/components/layout/EditBar.tsx index 2186d58..15a802f 100644 --- a/src/components/layout/EditBar.tsx +++ b/src/components/layout/EditBar.tsx @@ -7,7 +7,8 @@ // the whole-document operations. import { useState } from 'react'; import { useI18n } from '@/i18n/provider'; -import { DRAFT_DOCS } from '@/i18n/draft'; +import { DRAFT_DOCS, entityOfDoc } from '@/i18n/draft'; +import { manifestsClaiming, recordEntity } from '@/data/pages'; import { DEFAULT_BRANCH } from '@/i18n/edit-mode'; import type { ConflictField, DocSaveResult, DraftDocId } from '@/i18n/draft'; import type { ContentIssue } from '@/i18n/validate'; @@ -33,7 +34,7 @@ type EditBarProps = { onTakeTheirs: (id: DraftDocId) => void; onResolveField: (id: DraftDocId, path: string, side: 'mine' | 'theirs') => void; onDiscardDoc: (id: DraftDocId) => void; - onRevertPath: (path: string) => void; + onRevertPath: (id: DraftDocId, path: string) => void; }; function fileOf(id: DraftDocId): string { @@ -81,6 +82,19 @@ export function EditBar({ ? s.conflictStatus : `${s.failed} (${result.http ?? 0})`; + // "appears on" annotation (spec-v4-data-organization §6.3): the pages whose + // manifest claims this document-relative path — grouping is computed from + // the manifests, never from component code. + const appearsOn = (docId: DraftDocId, path: string): string | null => { + const entity = entityOfDoc(docId); + if (!entity) return null; + const pages = manifestsClaiming(recordEntity(entity), path); + if (pages.length === 0) return null; + return pages + .map((m) => (m.id === 'resume' ? s.appearsResume : m.id === 'home' ? s.appearsHome : m.route)) + .join(', '); + }; + return (