mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-23 00:20:40 +07:00
perf(edit): read only the documents the current route needs
Edit-mode document scope comes from the page manifests (src/i18n/edit-scope.ts): an entity's structure document and its two text documents are read as one unit, the category labels only where a project renders. A route change fetches only the still-missing documents and adopts them through DraftStore.adoptBase, which refuses a document the draft has already changed. A bundle-seeded baseline is never PUT over the branch: saveDraft reads the branch first and reports a conflict. Every manifest now claims profile.name, which the footer renders on every route.
This commit is contained in:
1 parent
ee1d524bd0
commit
5c71b52d81
13 files changed
+320
-71
No files matched your search
@@ -76,7 +76,7 @@ Content is split once, at authoring time, into language-neutral **structure docu
|
||||
- `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/{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.<id>.{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
|
||||
- Content ids and the category values a project uses are **generated**, never hand-maintained (spec: `docs/design/specs/v5/spec-v5-generated-content-ids.md`): `scripts/generate-content-types.ts` reads the four structure documents and writes `src/types/content-ids.ts` (gitignored) under `predev` / `prebuild` / `prepare`; `src/types/index.ts` re-exports those unions type-only and keeps only the code-owned ones (`Language`, `Palette`, `SocialId`, `PageId`, manifest types). A content add or delete touches JSON only — a text entry left behind by a deleted record is a `tsc` error (`TS2741`), never a stale union member — and a category with no label in either language is a validator error naming both `ui/projects.json` files (rule 7)
|
||||
- `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/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`. A manifest describes the whole page, chrome included — the footer renders `profile.name` on every route, so every manifest claims it. 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<Language, Resolved…>`; `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
|
||||
@@ -87,7 +87,9 @@ Content is split once, at authoring time, into language-neutral **structure docu
|
||||
|
||||
## Live Edit Mode (`?edit`, v4)
|
||||
|
||||
- Entry and persistence: any route with `?edit` — `MaybeEditMode` in `App.tsx` lazy-mounts `EditModeShell` (its own chunk; visitors never load edit code) when the query is present **or** the session flag is set. The mode is a session, not a URL state: while it is active every route change re-attaches `?edit` (a replace-navigation in `EditModeShell`), so clicking any link keeps edit mode and a reload reopens it — only the EditBar's Exit returns to the visitor site (it clears the flag, which unmounts the shell, and strips the query). The shell's initialization runs once per mount (entry URL from a ref, `stripEditQuery` reads `window.location`), so navigation never re-authenticates, re-fetches, or re-restores the draft. The shell authenticates, fetches the live branch documents through the proxy, and re-wraps the tree in an `I18nProvider` override — the seven routes ARE the preview
|
||||
- Entry and persistence: any route with `?edit` — `MaybeEditMode` in `App.tsx` lazy-mounts `EditModeShell` (its own chunk; visitors never load edit code) when the query is present **or** the session flag is set. The mode is a session, not a URL state: while it is active every route change re-attaches `?edit` (a replace-navigation in `EditModeShell`), so clicking any link keeps edit mode and a reload reopens it — only the EditBar's Exit returns to the visitor site (it clears the flag, which unmounts the shell, and strips the query). The shell's initialization runs once per mount (entry URL from a ref, `stripEditQuery` reads `window.location`), so navigation never re-authenticates, re-fetches, or re-restores the draft. The shell authenticates, reads the live branch documents the current route needs (see the next bullet), and re-wraps the tree in an `I18nProvider` override — the seven routes ARE the preview
|
||||
|
||||
- Document scope (`src/i18n/edit-scope.ts`): the documents a session reads come from the page manifests, never from component code — a claim names a joined record, and an entity owns its structure document plus its two text documents, which are always read as one unit (a half-loaded entity would make the validator compare a live document against a bundled one). Entry = the entry route's scope plus anything a restored draft already touched (those need a real blob sha). A route change reads only the documents still missing — each is adopted through `DraftStore.adoptBase`, which refuses a document the draft has already changed — and the category labels only where a project renders. A document still on its bundled baseline is never PUT over the branch: `saveDraft` sees the empty sha, reads the branch, and hands it to the conflict flow. The bundled copy stays the offline fallback, never a silent substitute for a live read
|
||||
- Target branch (spec D10): `?edit=<branch>` 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-session.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 and nothing else. The `?edit` parsing, the session flag `portfolio-edit`, the branch flag and `portfolio-draft` key live in `src/i18n/edit-session.ts` — a module with no imports, because `App.tsx` reads the mode gate from it and must not pull the auth probe (and through it `draft.ts`) into the entry chunk. A failed probe (401 or cancelled prompt) clears the flag and strips `?edit` → normal visitor site
|
||||
- `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). Edit mode writes JSON only: the id-union leg was deleted when spec-v5 made the unions generated, and the store is handed the branch's category labels (read-only `ui/projects.json` fetches) for rule 7 — `null` when they cannot be read, in which case the rule is skipped and the EditBar says so
|
||||
@@ -106,7 +108,7 @@ src/
|
||||
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, 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-session.ts (`?edit`/flag/branch state, dependency-free), edit-mode.ts (Basic-auth probe), locales/{vi,en}/content/{profile,skills,experience,projects}.json + ui/{group}.json (14 chrome groups)
|
||||
i18n/ — index.ts (loader), dict-types.ts, validate.ts, provider.tsx, draft.ts (DraftStore + save pipeline), edit-scope.ts (manifest-derived read scope), edit-session.ts (`?edit`/flag/branch state, dependency-free), edit-mode.ts (Basic-auth probe), 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; content-ids.ts (generated id unions, gitignored)
|
||||
@@ -137,7 +139,7 @@ src/
|
||||
|
||||
- `scripts/generate-resume.ts` — Playwright-based PDF resume generator (bilingual en/vi)
|
||||
- `scripts/generate-content-types.ts` — writes `src/types/content-ids.ts` from the four structure documents (`pnpm generate:ids`, wired as `predev` / `prebuild` / `prepare`): the id unions and the project category values in document order, `never` for an emptied document, a duplicate id refused with the file named
|
||||
- `scripts/smoke-draft.ts` — regression check of the draft-store semantics (`pnpm tsx scripts/smoke-draft.ts`): accept/reject paths, empty-required rejection, orphan-free record delete, template creation, id re-sluging on rename, snapshot round-trip, conflict detection, clean rebase, the category-label rule
|
||||
- `scripts/smoke-draft.ts` — regression check of the draft-store semantics (`pnpm tsx scripts/smoke-draft.ts`): accept/reject paths, empty-required rejection, orphan-free record delete, template creation, id re-sluging on rename, snapshot round-trip, conflict detection, clean rebase, the category-label rule, and the scoped-baseline rules of spec-v4-live-edit §5.1 (an adopted baseline replaces an untouched document only; a bundle-seeded document is never PUT over the branch)
|
||||
- `scripts/smoke-generated-ids.ts` — regression check of the generator (`pnpm tsx scripts/smoke-generated-ids.ts`): the shipped module equals the shipped documents, byte-stable output, `never` for emptied documents, malformed documents refused with the file named
|
||||
|
||||
## Deployment
|
||||
|
||||
Reference in new issue
Block a user