Files
cv/docs/design/specs/v4/spec-v4-inline-editing.md
T
dong.nguyen fbf75d8ffa 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.
2026-10-23 00:52:55 +07:00

14 KiB
Raw Blame History

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.

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–9 Implementation §5 ⬜ TODO
— Acceptance §6 ⬜ TODO