generated from coulomb/repo-seed
CE-WP-0006/0007: Capture view polish, workplans, and UX refinements
- Blob URL stability, scroll centre, strip-only visual guide - Focus-gated linking, unlink clears overlay, field badge tooltips - Capture layout (viewer centre), grey guide lines, Add field button - Workplans CE-WP-0006 (done) and CE-WP-0007 (T01-T09 done, T10-T12 todo) - Integration tests and viewer-url helpers
This commit is contained in:
330
workplans/CE-WP-0007-capture-view-polish.md
Normal file
330
workplans/CE-WP-0007-capture-view-polish.md
Normal file
@@ -0,0 +1,330 @@
|
||||
---
|
||||
id: CE-WP-0007
|
||||
type: workplan
|
||||
title: "Capture view polish — scroll stability, linking UX, layout, rename"
|
||||
domain: citation_evidence
|
||||
repo: citation-evidence
|
||||
repo_id: a677c189-b4e2-4f2a-9e48-faa482c277e6
|
||||
topic_slug: citation_evidence_mvp
|
||||
topic_id: 96fa8e80-9f74-40f2-84cd-644e9747b9ec
|
||||
status: active
|
||||
owner: Bernd
|
||||
created: 2026-06-07
|
||||
updated: 2026-06-08
|
||||
depends_on_workplan: CE-WP-0006
|
||||
planning_order: 7
|
||||
planning_priority: high
|
||||
spec_refs:
|
||||
- wiki/ProductRequirementsDocument.md
|
||||
- workplans/CE-WP-0006-forms-ux-refinements.md
|
||||
state_hub_workstream_id: "988ee7c6-752a-492a-9ef9-76d33af9b2d6"
|
||||
---
|
||||
|
||||
# CE-WP-0007 — Capture View Polish
|
||||
|
||||
Follow-on UX fixes after CE-WP-0006 manual demo use. Renames the Forms
|
||||
mode tab to **Capture**, recentres the document column, and tightens linking
|
||||
and visual-guide behaviour.
|
||||
|
||||
## User requirements (locked)
|
||||
|
||||
1. **Scroll stability** — selecting evidence further down the document must
|
||||
not jump the viewport back to the beginning.
|
||||
2. **Focus-gated linking** — only when a form field has focus does clicking
|
||||
evidence in the strip link directly (no evidence-first staging flow).
|
||||
3. **Unlink clears visualization** — removing a link removes the connection
|
||||
lines immediately.
|
||||
4. **Field badge tooltips** — mouseover on a field's evidence-count badge
|
||||
shows the first 80 characters of linked evidence, with trailing `…` when
|
||||
truncated.
|
||||
5. **Softer guide lines** — connection indicator lines are grey and thinner.
|
||||
6. **Centred document column** — Capture layout matches Review: collection |
|
||||
**viewer (centre)** | form pane (right).
|
||||
7. **Rename Forms → Capture** — top-bar tab label and user-facing copy.
|
||||
8. **Add Field** — button to append new form fields to the demo schema.
|
||||
9. **Field type + label on add/edit** — when adding a capture field, choose
|
||||
`text` | `textarea` | `date` and set the label; existing fields expose a
|
||||
✎ edit control (same interaction pattern as evidence cards in
|
||||
`EvidenceSidebar`).
|
||||
|
||||
## Dependency order
|
||||
|
||||
```
|
||||
T01 (scroll stability)
|
||||
T02 (focus-gated linking) ─┬─ T03 (unlink clears viz)
|
||||
└─ T04 (field badge tooltips)
|
||||
T05 (grey guide lines) — parallel
|
||||
T06 (layout swap) ── T07 (rename Capture)
|
||||
T08 (Add Field) — after T06/T07
|
||||
T09 (integration tests + README)
|
||||
T10 (add-field type + label) ── T11 (field edit icon)
|
||||
└─ T12 (tests)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T01 — Fix viewport jump on evidence select
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T01
|
||||
priority: critical
|
||||
status: done
|
||||
state_hub_task_id: "23f8e8d0-4ccd-48e9-958c-cc8b756dcaec"
|
||||
```
|
||||
|
||||
**Problem:** clicking an evidence item far down the PDF resets scroll to the
|
||||
document start before (or instead of) centring the passage.
|
||||
|
||||
**Fix:**
|
||||
|
||||
- Harden `centerHighlightInViewer` with retried rAF passes until highlight
|
||||
DOM rects are available.
|
||||
- Ensure scroll requests do not remount `PdfSpikeViewer`.
|
||||
- Avoid duplicate/conflicting scroll triggers from auto-activation + card click.
|
||||
|
||||
**Acceptance:** click evidence items on page 2+ — viewport stays near the
|
||||
cited passage, never snaps to page 1 top.
|
||||
|
||||
---
|
||||
|
||||
## T02 — Link only when a form field has focus
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T02
|
||||
priority: high
|
||||
status: done
|
||||
depends_on: [T01]
|
||||
state_hub_task_id: "289bed30-0bb0-42b7-ab6f-8c218133d3df"
|
||||
```
|
||||
|
||||
**Remove** evidence-first staging (click card → click field). **Keep**
|
||||
field-focus-gated direct link:
|
||||
|
||||
- Field receives focus → user clicks evidence card → immediate
|
||||
`linkEvidenceToTarget`.
|
||||
- Evidence click without focused field → activate + scroll only.
|
||||
|
||||
Remove evidence-staged banner and `stagedEvidenceId` state paths.
|
||||
|
||||
**Acceptance:** focus Summary → click strip card → link created. Click card
|
||||
with no field focused → no link, no staging banner.
|
||||
|
||||
---
|
||||
|
||||
## T03 — Unlink removes connection visualization
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T03
|
||||
priority: high
|
||||
status: done
|
||||
depends_on: [T02]
|
||||
state_hub_task_id: "328e8936-454f-4092-802b-9b0030d54ce5"
|
||||
```
|
||||
|
||||
On `EvidenceLinkRemoved`, if the active triple no longer has a valid link
|
||||
between field and evidence, clear `activeEvidenceItemId` / `activeAnnotationId`
|
||||
(or select the next remaining link on the field).
|
||||
|
||||
**Acceptance:** unlink via strip badge → SVG paths disappear immediately.
|
||||
|
||||
---
|
||||
|
||||
## T04 — Field evidence badge hover preview
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T04
|
||||
priority: medium
|
||||
status: done
|
||||
depends_on: [T02]
|
||||
state_hub_task_id: "af6a0c73-c323-4e24-85f7-64403658ae51"
|
||||
```
|
||||
|
||||
On each field's `N evidence` chip in `FormRenderer`, set `title` to the
|
||||
first 80 characters of the first linked evidence quote (italic), append `…`
|
||||
when longer. Multiple links: join previews or show first link only (document
|
||||
choice in commit).
|
||||
|
||||
**Acceptance:** hover field badge → tooltip shows truncated quote.
|
||||
|
||||
---
|
||||
|
||||
## T05 — Grey, thinner visual-guide lines
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T05
|
||||
priority: low
|
||||
status: done
|
||||
state_hub_task_id: "a415f7df-f641-49d8-9c21-13eb70684c64"
|
||||
```
|
||||
|
||||
Update `Overlay` defaults (or Capture-mode props): stroke `#999` (or similar
|
||||
grey), width `1` px. Update `Overlay.dom.test.tsx` if it asserts colour/width.
|
||||
|
||||
**Acceptance:** connection lines are visibly grey and thinner than before.
|
||||
|
||||
---
|
||||
|
||||
## T06 — Capture layout: document in centre column
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T06
|
||||
priority: high
|
||||
status: done
|
||||
state_hub_task_id: "1fa3cd2c-c264-4599-9e8a-bd1d74ac1faa"
|
||||
```
|
||||
|
||||
Reorder `FormsApp` columns to match `ReviewLayout`:
|
||||
|
||||
```
|
||||
Collection | ViewerShell | FormPane
|
||||
```
|
||||
|
||||
Evidence strip remains full-width footer.
|
||||
|
||||
**Acceptance:** PDF viewer is the centre pane in Capture mode.
|
||||
|
||||
---
|
||||
|
||||
## T07 — Rename Forms view to Capture
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T07
|
||||
priority: medium
|
||||
status: done
|
||||
depends_on: [T06]
|
||||
state_hub_task_id: "7c326eaa-839c-45ad-bef6-aab77b324332"
|
||||
```
|
||||
|
||||
- Top-bar tab: `Forms` → `Capture`.
|
||||
- User-facing strings in Capture mode (banners, empty hints).
|
||||
- Internal route slug may remain `forms` for deep-link compat; update tests
|
||||
that query the tab by visible label.
|
||||
|
||||
**Acceptance:** tab reads "Capture"; integration tests updated.
|
||||
|
||||
---
|
||||
|
||||
## T08 — Add Field button
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T08
|
||||
priority: medium
|
||||
status: done
|
||||
depends_on: [T06]
|
||||
state_hub_task_id: "04586602-491b-46c2-9ced-48258d11bfed"
|
||||
```
|
||||
|
||||
Add **Add field** control above the form. Appends a new `text` field with
|
||||
auto-generated id (`field_<n>`) and editable label placeholder. Schema held
|
||||
in React state (seeded from `DEMO_SCHEMA`); rect registry and linking use
|
||||
dynamic field ids.
|
||||
|
||||
**Acceptance:** click Add field → new row appears; can link evidence to it.
|
||||
|
||||
---
|
||||
|
||||
## T09 — Tests and README index
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T09
|
||||
priority: high
|
||||
status: done
|
||||
depends_on: [T03, T04, T05, T07, T08]
|
||||
state_hub_task_id: "823d4986-892d-467e-819e-54f0f2a363e8"
|
||||
```
|
||||
|
||||
- Update integration tests for Capture label, layout, focus-gated linking.
|
||||
- Add/adjust tests for unlink visualization and field badge tooltip.
|
||||
- Update `workplans/README.md` with CE-WP-0007.
|
||||
|
||||
**Acceptance:** `npm run test` green.
|
||||
|
||||
---
|
||||
|
||||
## T10 — Add-field dialog: type selection + label
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T10
|
||||
priority: medium
|
||||
status: todo
|
||||
depends_on: [T08]
|
||||
state_hub_task_id: "dab723e6-66a6-4587-8ab7-e0c5e4cb5d0a"
|
||||
```
|
||||
|
||||
**Current:** **Add field** immediately appends a `text` field with a
|
||||
generated label (`New field N`).
|
||||
|
||||
**Implement:**
|
||||
|
||||
- Click **Add field** → lightweight inline form or small modal (match
|
||||
`EvidenceFormBody` / `InlineCaptureForm` styling, not a new design system).
|
||||
- User picks field type: `text` | `textarea` | `date` (same union as
|
||||
`FormFieldSchema`).
|
||||
- User enters/edits the label before confirm.
|
||||
- **Add** inserts the field; **Cancel** discards.
|
||||
- Stable auto-id (`field_<n>`); label is user-facing only.
|
||||
|
||||
**Acceptance:** add a `date` field labelled "Hearing date" — row renders with
|
||||
correct input type and label.
|
||||
|
||||
---
|
||||
|
||||
## T11 — Field edit icon (evidence-sidebar pattern)
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T11
|
||||
priority: medium
|
||||
status: todo
|
||||
depends_on: [T10]
|
||||
state_hub_task_id: "c55541c7-57e2-4f5d-a4ef-ed54c470cbd9"
|
||||
```
|
||||
|
||||
Mirror `EvidenceSidebar` edit UX (`✎` button, `data-testid` hooks,
|
||||
inline editor, save/cancel):
|
||||
|
||||
- Each `FieldRow` in `FormRenderer` gets an upper-right **edit** control
|
||||
(pencil icon, `aria-label`, stop propagation on click).
|
||||
- Edit mode shows type selector + label input (reuse T10 controls).
|
||||
- **Save** updates schema state in `FormsApp`; **Cancel** reverts.
|
||||
- Changing type swaps the rendered input; field `id` stays stable so
|
||||
existing `EvidenceLink` targets and rect registrations remain valid.
|
||||
- Demo-schema seed fields are editable too.
|
||||
|
||||
**Acceptance:** edit "Summary of the matter" → rename + switch to `text`;
|
||||
links and visual guide still resolve by field id.
|
||||
|
||||
---
|
||||
|
||||
## T12 — Tests for field add/edit UX
|
||||
|
||||
```task
|
||||
id: CE-WP-0007-T12
|
||||
priority: high
|
||||
status: todo
|
||||
depends_on: [T10, T11]
|
||||
state_hub_task_id: "585b054e-eb5e-410e-90ee-84e698b13f7f"
|
||||
```
|
||||
|
||||
Happy-dom integration or `FormRenderer` DOM tests:
|
||||
|
||||
- Add field with chosen type + custom label.
|
||||
- Edit existing field label and type via pencil icon.
|
||||
- Link to an added/edited field still works (focus-gated linking).
|
||||
|
||||
**Acceptance:** `npm run test` green.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance for the workplan
|
||||
|
||||
After CE-WP-0007:
|
||||
|
||||
1. Evidence select does not jump viewport to document start.
|
||||
2. Linking requires focused field; evidence click links directly.
|
||||
3. Unlink clears visual guide lines.
|
||||
4. Field badges show 80-char quote preview on hover.
|
||||
5. Guide lines are grey and thin.
|
||||
6. Capture mode centres the document viewer.
|
||||
7. Tab reads "Capture".
|
||||
8. Users can add form fields dynamically.
|
||||
9. Add-field flow picks type and label; existing fields edit via ✎ control.
|
||||
Reference in New Issue
Block a user