mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
- EditableText: wrapper zone + pencil trigger (E6), inline validation errors, provenance tooltip + copy-chip (E7) - TagListEditor: per-chip edit/delete/move + ghost add over all six tag arrays, tagline emphasis toggle - RecordControls + AddGhost on About, AboutPage, Expertise, Experience, ExperiencePage, Projects, ProjectsListPage, ProjectDetailPage (incl. sections), PhilosophyPage; RecordSettings popover (featured, section list with type picker, variant, location, logo) - id-slug rename on committed record titles (E3); per-field conflict UI in EditBar; chrome CSS in App.css; labels in both ui.json - JsonPanel kept until the inline surface is verified in a real browser (spec progress row 8); acceptance §6 partial — build, validate:content, lint, smoke-draft pass 2026-10-23
119 lines
14 KiB
Markdown
119 lines
14 KiB
Markdown
# 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 `<button>` at the zone's end corner, `aria-label` from `ui.edit.fields` (already complete). The glyph is 16px; the button's hit area is ≥28px at desktop and a 44px target on touch — same target-size discipline as the nav controls.
|
||
- Click the pencil → the element becomes the inline editor (input for single-line: titles, company, duration, role; auto-grow textarea for prose: bio, summary, section content, responsibilities item, quote). Clicking the text does nothing.
|
||
- Commit rules unchanged (live-edit §5.3): blur for multi-line (Vietnamese IME safe), Enter for single-line, Esc cancels, empty required values rejected at commit.
|
||
- Validation errors surface **inline**: red ring + message under the field. No panel status line.
|
||
- Mobile: the pencil is always visible in edit mode (low opacity), because hover does not exist.
|
||
|
||
### 2.2 Tag arrays — `technologies`, `metrics`, `currentInterests`, `roles`, `keywords`, tagline segments
|
||
|
||
Each chip is an edit unit: pencil per chip (inline text edit), `×` on hover to delete, a ghost `+` chip at the list end to add, ↑/↓ to move. Tagline segments additionally carry an emphasis toggle button (`emphasis: true` renders the bold/italic treatment Hero already applies). Empty tags are rejected at commit; tag add never requires a dialog.
|
||
|
||
### 2.3 Collections — add and delete records
|
||
|
||
- Add: a ghost affordance at the end of each collection, on the page where the collection renders — "+ Dự án mới" (end of the projects grid), "+ Kinh nghiệm mới" (end of the timeline), "+ Nhóm kỹ năng mới" (expertise grid), "+ Luận điểm mới" on /about + the home About section (where philosophy cards actually render), "+ Đoạn mới" on /philosophy (appends to the fixed `profile.philosophyQuotes` array — a title + paragraphs, not a philosophy card), "+ Section" in project detail with a mini type picker (text / diagram / metrics / code). Creation runs the existing `draft.ts` templates (structure + both text documents in one validated step; quotes need no structure leg); the new record appears in the live preview immediately.
|
||
- Delete: trash icon on the card/entry, confirm-gated, using the existing orphan-free delete (structure + text documents in one step).
|
||
- ids per E3 — project section ids included, slugged from the section title at creation.
|
||
|
||
### 2.4 Record settings popover (E2)
|
||
|
||
Gear icon on cards/entries opens a small popover anchored to the record:
|
||
- project card: `featured` toggle, sections list (type picker, move, delete — add lives inline at §2.3);
|
||
- timeline entry: `variant` select (none / current / gap), `logo` path text input;
|
||
- nothing else needs a popover — every other field has an inline home.
|
||
|
||
The popover edits the draft through the same validated path as inline text; invalid values never reach the preview.
|
||
|
||
### 2.5 Social links (E4)
|
||
|
||
Contact cards (home + /contact) show handle text as editable (pencil per §2.1 rules) and the URL as derived, read-only. `profile.json` keeps `githubHandle`, `linkedinHandle`, `telegramHandle`, `email`; `githubUrl`/`linkedinUrl`/`telegramUrl` are produced by `profile.ts` from the handles. `email` stays a plain editable field.
|
||
|
||
### 2.6 Reorder (E5)
|
||
|
||
↑/↓ buttons appear beside the pencil on chips and on record cards/entries in edit mode. Up/down swap the array element in the owning document; first/last disable the respective button. Semantics identical to a JSON array move.
|
||
|
||
### 2.7 Field provenance (E7)
|
||
|
||
Every edit control knows its storage location — `draft.ts` keys every accepted edit by `(documentId, path)`. E7 renders it:
|
||
|
||
- **Before editing**: the pencil's `title` (and `aria-describedby` tooltip) shows `<document> → <pointer>`, the document named by its real repo path in short form: `locales/vi/content.json → profile.bio`, `data/projects.json → iot-dws-integration.featured` (structure documents carry no language suffix — they are language-neutral).
|
||
- **While editing**: a monospace chip (12–14px chrome size per the typography rules) attached to the editor's top edge shows the same `document → pointer`. Clicking the chip copies the full repo path plus pointer (`src/i18n/locales/vi/content.json` + `profile.bio`) to the clipboard, with a brief "copied" confirmation.
|
||
- **Where it appears**: the active text editor (§2.1), every tag chip incl. its array index (`locales/vi/content.json → profile.currentInterests[3]` — the index also teaches that array order is display order), every settings-popover control next to its label, and inline validation errors (the same descriptor the `validate:content` CLI prints, so app errors and CLI errors name the same location).
|
||
- **Layout-agnostic**: the descriptor is computed from the draft document registry (document id → repo path). When `spec-v4-data-organization.md` lands, the same code renders `locales/vi/content/profile.json → bio` with no change here.
|
||
- The language shown is the document of the language being edited — editing the VI page writes `locales/vi/content.json`, the EN page writes `locales/en/content.json`. After `spec-v4-data-organization.md` lands these become `locales/vi/content/profile.json` etc. automatically (line 61).
|
||
|
||
Implementation: a `describeField(documentId, path)` helper in `draft.ts` (registry lookup + JSON-pointer formatting) consumed by `EditableText`, `TagListEditor`, `RecordSettings`, and the move controls. No new state, no new validation.
|
||
|
||
## 3. EditBar, save, conflicts — unchanged
|
||
|
||
The EditBar keeps its role: per-path diff with revert, conflict resolution, per-document save status, resume-after-partial-failure, exit confirm. With E1 the panel disappears from it (`openPanel`/`closePanel` labels drop from `ui.edit`); **hand-merge becomes per-field**: on a 412 conflict the EditBar lists the conflicting paths, each showing the working value beside the remote value with a keep-mine / keep-theirs choice per field — finer granularity than the document-level JSON merge it replaces, and raw JSON never appears. Save remains sequential-PUT per touched document. The cross-document validator still runs on every accepted edit and before save — its feedback now arrives inline at the field (and in the EditBar as a blocked-save reason), never as a JSON status line.
|
||
|
||
Page manifests (`spec-v4-data-organization.md` §5) are **read-only in the app**: they are developer documents; the orphan-field validation rule is the enforcement. Wildcard claims (`"*"`, `sections.*`) mean adding records or sections never requires a manifest edit.
|
||
|
||
## 4. Component inventory
|
||
|
||
| Work | Component | Nature |
|
||
|---|---|---|
|
||
| Upgrade | `EditableText.tsx` | wrapper zone + pencil trigger (icon-only editing), inline error display, provenance tooltip + chip (E7) |
|
||
| New | `TagListEditor.tsx` | per-chip edit/delete/move + ghost add; emphasis toggle for tagline |
|
||
| New | `RecordSettings.tsx` | popover form: featured, variant, logo, section list |
|
||
| New | `AddRecord.tsx` | ghost affordance + template trigger + (sections) type picker |
|
||
| New | move controls | ↑/↓ buttons shared by `TagListEditor` and record cards |
|
||
| Delete | `JsonPanel.tsx` | removed outright — no fallback drawer, no advanced mode |
|
||
| Keep + extend | `EditBar.tsx`, `edit-mode.ts`, validator | unchanged except panel references |
|
||
| Extend | `draft.ts` | id-slug helper (E3) + `describeField()` provenance helper (E7) |
|
||
| Data | `profile.json` + `profile.ts` | drop `githubUrl`/`linkedinUrl`/`telegramUrl`; derive all three in the loader |
|
||
|
||
`ui.edit` loses `panel`/`openPanel`/`closePanel`/`handMerge`; gains labels for the new controls (`addProject`, `addExperience`, `addSkillGroup`, `addPhilosophyPoint`, `addQuote`, `addSection`, `settings`, `moveUp`, `moveDown`, `remove`, `emphasis`, `editField` if not already present), for provenance (`copyPath` tooltip on the chip, `pathCopied` confirmation), and for per-field conflicts (`keepMine`, `keepTheirs`).
|
||
|
||
## 5. Implementation order
|
||
|
||
1. `EditableText` upgrade (zone + pencil + inline errors); remove text-click editing.
|
||
2. Provenance: `describeField()` in `draft.ts` (registry lookup + pointer formatting), tooltip + chip in `EditableText`, clipboard copy + `ui.edit` labels; reused by every later control.
|
||
3. `profile.json` handle-only + URL derivation in `profile.ts` (resolved record shape unchanged — verify consumers byte-identical).
|
||
4. `TagListEditor` for all six tag arrays incl. tagline emphasis, chips carrying indexed provenance.
|
||
5. Add/delete/move for records (`AddRecord`, trash, ↑/↓) over the existing templates and orphan-free delete.
|
||
6. `RecordSettings` popover (featured, variant, logo, section list with type picker), pointer shown beside each control.
|
||
7. id-slug generator + collision suffixes in `draft.ts` record creation.
|
||
8. Remove `JsonPanel.tsx` + its EditBar hooks + `ui.edit` panel labels.
|
||
9. Docs: live-edit §5.1 superseded note, data-organization §6.4 superseded note, AGENTS.md Live Edit Mode section.
|
||
|
||
## 6. Acceptance criteria
|
||
|
||
- [ ] Every field previously editable in the JSON panel is editable on a page: text, tags (incl. tagline emphasis), featured, variant, logo, technologies, record add/delete, section add with type, record order.
|
||
- [ ] Clicking editable text never opens an editor; the pencil always does; keyboard path Tab→Enter works for every control.
|
||
- [ ] Hovering any pencil shows `document → pointer`; the active editor carries the chip; clicking the chip copies the full repo path; the descriptor matches the EditBar diff line and the `validate:content` error for the same field.
|
||
- [ ] `profile.json` without URL fields renders identical Contact/Footer/resume output (derived URLs match the previous literals, `t.me/dongdn` included).
|
||
- [ ] Save flow: edit text + add a chip + move a tag → EditBar lists the touched files → save commits land on the target branch; a 412 conflict resolves without raw JSON: rebase / take-theirs / per-field keep-mine–keep-theirs in the EditBar.
|
||
- [ ] `pnpm build`, `pnpm validate:content`, `pnpm lint` (no new warnings), `pnpm tsx scripts/smoke-draft.ts`, `pnpm build:resume-all` pass.
|
||
- [ ] Visitor rendering unchanged on all 7 routes, both languages.
|
||
|
||
## 7. Progress Tracking
|
||
|
||
| # | Task | Status |
|
||
|---|---|---|
|
||
| 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) |
|