Annotation editor: outlines per step line, highlight in reading view (#12) #26

Merged
miko merged 5 commits from feature/12-annotation-editor into development 2026-11-02 11:21:00 +01:00
Owner

Closes #12

Summary

Each Annotation is an outline on a Step Image that belongs to one coloured Step Line and takes its colour (ADR-0011, superseding ADR-0004). Positions are percent of the cropped image and drawn as SVG over it.

 Step
   StepLine            # keeps its id across saves now
+    Annotation[]      # required stepLineId, cascade
   StepImage
+    Annotation[]      # shape, x/y/w/h in percent, cascade (re-crop discards)
<StepWorkspace>                       (edit)
  <StepImagesEditor>
    <AnnotationDialog>                # pick line, draw/move/resize, 8 px-sized handles
  <StepLinesEditor>                   # UUID per new line; asks before dropping annotations
  <RichTextEditor>                    # Editor.js now loads (own element per mount)

<GuideSteps>                          (read)
  <StepFigure> state: shown image, highlighted line
    <StepImageViewer> <AnnotationOverlay>
    <StepLines>                       # click a line → its annotations stand out

Also: saving a step updates lines by id instead of replacing them, and drops annotations of lines that are no longer coloured bullets. Editor.js follows the theme, uses the full width and no longer offers checklists (ADR-0005).

Evidence

  • Before: no annotations; step content field empty because Editor.js never mounted (React dev double mount tore it down).
    After: npm test → 184 passed (coordinate conversion, draw/move/resize from all 8 handles, submission checks, line ids, reading-view SVG overlay and highlight toggles); typecheck and lint clean. Checked in the browser: dialog with line picker, edge-handle resize, reassigning to another line, Editor.js “+” menu and inline toolbar, highlight in the reading view.

Merge Danger

Door: one-way

Migrations add Annotation, then replace its color with a required stepLineId; existing annotations move to the first line of their colour, unmatched ones are deleted.

Blast Radius: steps

Step saves now upsert lines by id; a bug there would affect every step's lines. Editor.js theming touches the guide description editor too.

🤖 Generated with Claude Code

Closes #12 ## Summary Each **Annotation** is an outline on a **Step Image** that belongs to one coloured **Step Line** and takes its colour (ADR-0011, superseding ADR-0004). Positions are percent of the cropped image and drawn as SVG over it. ```diff Step StepLine # keeps its id across saves now + Annotation[] # required stepLineId, cascade StepImage + Annotation[] # shape, x/y/w/h in percent, cascade (re-crop discards) ``` ```text <StepWorkspace> (edit) <StepImagesEditor> <AnnotationDialog> # pick line, draw/move/resize, 8 px-sized handles <StepLinesEditor> # UUID per new line; asks before dropping annotations <RichTextEditor> # Editor.js now loads (own element per mount) <GuideSteps> (read) <StepFigure> state: shown image, highlighted line <StepImageViewer> <AnnotationOverlay> <StepLines> # click a line → its annotations stand out ``` Also: saving a step updates lines by id instead of replacing them, and drops annotations of lines that are no longer coloured bullets. Editor.js follows the theme, uses the full width and no longer offers checklists (ADR-0005). ## Evidence - **Before:** no annotations; step content field empty because Editor.js never mounted (React dev double mount tore it down). **After:** `npm test` → 184 passed (coordinate conversion, draw/move/resize from all 8 handles, submission checks, line ids, reading-view SVG overlay and highlight toggles); typecheck and lint clean. Checked in the browser: dialog with line picker, edge-handle resize, reassigning to another line, Editor.js “+” menu and inline toolbar, highlight in the reading view. ## Merge Danger **Door:** one-way Migrations add `Annotation`, then replace its `color` with a required `stepLineId`; existing annotations move to the first line of their colour, unmatched ones are deleted. **Blast Radius:** steps Step saves now upsert lines by id; a bug there would affect every step's lines. Editor.js theming touches the guide description editor too. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Annotations are coloured rectangles and circles stored in percent of the
cropped image (ADR-0004); circles are round in the 4:3 frame, so their
height is 4/3 of their width. A dialog per step image draws them by
dragging, selects, moves, resizes and deletes them and picks a palette
colour (no black); they are saved as a whole set per image. The reading
view and the editor's thumbnails draw them as an SVG over the image, with a
fixed stroke width that scales with it. Re-cropping discards them through
the cascade on the replaced image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Focus follows the selection, so Delete and the arrow keys act on the
  annotation just clicked or drawn.
- Shift and arrow keys resize by one axis (resizeAnnotationBy), so circles
  can shrink too; resizing stops at the image's edges.
- Read the drawn annotation from a ref at pointer-up, so a quick drag is
  not lost; Escape cannot close the dialog during a save.
- Share the annotation colours (palette.ts) and the limit message; avoid
  "shape" for an annotation itself; clearer helper type names.
- ADR-0004: record percent storage and the 4/3 circle height.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every annotation now references one coloured bullet line of its step and
takes its colour (ADR-0011, superseding ADR-0004). Step lines keep their ids
across saves: the editor gives a new line a UUID, saving updates lines by
id, and lines that are removed, blackened or turned into icon lines lose
their annotations; the editor asks first. The migration moves existing
annotations to the first line of their colour.

The annotation dialog picks a line instead of a colour and shows the
selection as a thin frame with eight small handles of fixed pixel size;
every handle resizes, and circles stay round.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Clicking a step line that has annotations highlights them on the images
  (thicker, the others faded), switching to an image that has some; the
  bullet is a toggle button for keyboard and screen reader users.
- Editor.js never appeared: React's development double mount let the first,
  asynchronously created editor tear down the second one's UI. Each mount
  now gets its own element.
- Editor.js uses the field's full width, keeps its toolbar inside the
  border and follows the theme in light and dark mode; the list tool no
  longer offers checklists, which the renderer does not know (ADR-0005).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Ask before removing or blanking a line added in this session that has
  annotations (its key is its id), and before saving a step whose
  annotated lines were emptied, which drops them with their annotations.
- Derive "annotatable" from the palette in the step save, map stored
  annotations to line ids once, share the annotated-line set and the
  handle sides, and name test lines as lines, not colours.
- The selection frame is white on dark instead of the accent, which stays
  off step lines (ADR-0010); no short-circuits as control flow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
miko merged commit 3e9e507ab6 into development 2026-11-02 11:21:00 +01:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
MassiveDynamic/kataba!26
No description provided.