Skip to content
Merged
Show file tree
Hide file tree
Changes from 20 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
8262013
added documentation for Editor
codevory Jan 16, 2026
64b7916
added css property to overide the default pointer events by browser
codevory Jan 16, 2026
32e2c6a
added tests for Editor in index.js
codevory Jan 16, 2026
35c4ffc
added tests for EditorHelmt
codevory Jan 16, 2026
747791d
added touch gestures , pinch zoom , color toggle on click,image drag etc
codevory Jan 16, 2026
54936bc
Format Editor component spacing
codevory Jan 16, 2026
f6ff879
addd error handling block
codevory Jan 16, 2026
bb9f181
implemented the issues pointed out
codevory Jan 16, 2026
2aea399
improved the docs
codevory Jan 16, 2026
f5b5e18
improved the lint
codevory Jan 16, 2026
902e54d
Merge branch 'main' into modified
codevory Jan 16, 2026
e395037
improved docs structure & implemented feedback
codevory Jan 17, 2026
adc347c
Merge branch 'modified' of https://github.com/codevory/Img2Num into m…
codevory Jan 17, 2026
60fbf31
disabled toggle color on click/tap
codevory Jan 19, 2026
b7ae588
removed toggle color & refactored the docs
codevory Jan 19, 2026
1d1f187
formatted structure
codevory Jan 19, 2026
3809fdd
Merge branch 'main' into modified
codevory Jan 19, 2026
7e029c8
formatted with prettier
codevory Jan 19, 2026
c0da3ed
formatted with prettier
codevory Jan 19, 2026
cf25e03
Merge branch 'modified' of https://github.com/codevory/Img2Num into m…
codevory Jan 19, 2026
ef4cc28
Merge branch 'main' into modified
Ryan-Millard Jan 19, 2026
e1c421e
condensed the docs content to make it ease to read
codevory Jan 20, 2026
b3046e3
Merge branch 'modified' of https://github.com/codevory/Img2Num into m…
codevory Jan 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 193 additions & 0 deletions docs/docs/reference/react/pages/Editor/index.md

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is quite a large file and the contents on the right sidebar go over the fold (see the image below). Please would you condense the contents of this file to make it faster to read through. It isn't a very complex piece of code, and new users will likely get frustrated by having to sift through large amounts of text to find what they're looking for.

There's nothing terribly wrong with your documentation, but this is a UX problem that will draw people away and possibly lead to poor quality PRs because they're too lazy to read. I've already encountered a fair amount of PRs like that.

Image

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have condensed the docs content and now it looks better

Original file line number Diff line number Diff line change
@@ -0,0 +1,193 @@
---
title: Editor Page
description: Interactive SVG editor page with pan/zoom and a “color reveal” mode for inspecting generated SVG regions.
keywords: [editor, svg, pan, zoom, pinch, pointer events, react-router, Img2Num]
sidebar_label: Editor
---

# Editor Page

The Editor page renders the SVG generated by Img2Num’s processing pipeline and provides:

- Pan + zoom (mouse wheel, drag, pinch)
- A **Color mode** that hides fills until a shape is tapped/clicked (reveal is one-way; shapes stay colored once revealed)
- A **Preview mode** that disables interaction but preserves the current “revealed” state

## Source files

- Page: [`src/pages/Editor/index.jsx`](https://github.com/Ryan-Millard/Img2Num/blob/main/src/pages/Editor/index.jsx)
- Helmet: [`src/pages/Editor/EditorHelmet.jsx`](https://github.com/Ryan-Millard/Img2Num/blob/main/src/pages/Editor/EditorHelmet.jsx)
- Styles: [`src/pages/Editor/Editor.module.css`](https://github.com/Ryan-Millard/Img2Num/blob/main/src/pages/Editor/Editor.module.css)

## Route and data flow

- Route: `/editor` (registered in [`src/App.jsx`](https://github.com/Ryan-Millard/Img2Num/blob/main/src/App.jsx))
- Input: the page expects an SVG **string** passed via React Router navigation state:

```jsx
navigate('/editor', { state: { svg } });
```

That navigation currently happens at the end of the image pipeline in [`src/components/WasmImageProcessor.jsx`](https://github.com/Ryan-Millard/Img2Num/blob/main/src/components/WasmImageProcessor.jsx).

### Empty state (direct navigation)

If the user loads `/editor` directly (no navigation state), `svg` is missing and the page renders a friendly “No SVG data found” message.

## Dependencies

- React: `useRef`, `useState`
- `react-router-dom`: `useLocation` (for `location.state.svg`)
- `html-react-parser`: converts the SVG string into React elements
- `lucide-react`: icons for the mode toggle
- UI components:
- `GlassCard` (layout container)
- `GlassSwitch` (mode toggle)
- Internal: `EditorHelmet`

## Rendering structure (mental model)

At a high level:

1. Outer `GlassCard` (page container)
2. Top-right mode switch (`GlassSwitch`)
3. Inner `GlassCard` viewport (captures pointer/wheel events)
4. A transformed wrapper (`div.inner`) that receives `translate + scale`
5. Parsed SVG element tree (`svgElements`)

The transform is applied to the wrapper, not directly to the `<svg>`, so the SVG keeps its natural size and is moved/scaled as a single unit.

## State and refs

### Mode

- `isColorMode` (boolean)
- `true`: shapes are “hidden” (filled white) until clicked
- `false`: preview mode; interactivity disabled

### Transform

- `transform = { scale, tx, ty }`
- `scale` is clamped to `[0.25, 6]`
- `tx/ty` represent translation in screen pixels

Applied as:

```js
transform: `translate(${tx}px, ${ty}px) scale(${scale})`;
```

### Pointer bookkeeping

The page uses Pointer Events to support mouse, touch, and pen:

- `viewportRef`: element that captures pointer events (`setPointerCapture`)
- `innerRef`: used to find the rendered `<svg>` root for hit-testing
- `activePointersRef`: `Map(pointerId -> {x,y})` for multi-touch (pinch)
- `pointerState`: drag bookkeeping (`dragging`, last coords, “moved” threshold)
- `pinchRef`: stores pinch start metrics and the **content point under the midpoint** to keep pinch behavior stable

## Interaction behavior

### Wheel zoom

- Trigger: `onWheel` on the viewport
- Behavior: adjusts `scale` only (does not currently zoom-to-cursor)
- Uses a fixed step (`1.12`) and clamps the resulting scale.

### Pan (single pointer)

- Trigger: `onPointerDown` + `onPointerMove` with exactly **one** active pointer
- A small movement threshold (~5px) prevents accidental “tap” toggles from turning into pans.
- Translation is updated incrementally: `tx += dx`, `ty += dy`.

### Pinch zoom (two pointers)

- Trigger: two active pointers
- Tracks:
- Start distance between pointers
- Start scale/translation
- The content-space coordinate under the midpoint at the start
- On move: computes `nextScale` from the distance ratio and updates `tx/ty` so the midpoint stays anchored.

This is the key idea:

$$
\text{nextTx} = m_x - c_x \cdot \text{nextScale},\quad \text{nextTy} = m_y - c_y \cdot \text{nextScale}
$$

where $(m_x, m_y)$ is the midpoint in screen coordinates and $(c_x, c_y)$ is the original content coordinate under that midpoint.

### Tap/click: add “original fill”

When the pointer is released:

- If the user **did not drag** and `isColorMode` is enabled:
1. Find the nearest shape under the pointer using `document.elementFromPoint(...).closest(SHAPE_SELECTOR)`
2. Verify the shape belongs to the SVG rendered in this page
3. Add `styles.coloredRegion` on that element

Once a shape is revealed it stays colored; repeated taps do not re-hide or toggle it off.

The selector currently targets:

```js
const SHAPE_SELECTOR = 'path,rect,circle,polygon,ellipse';
```

## Styling (Editor.module.css)

### Key classes

| Class | Purpose |
| --------------- | --------------------------------------------------------------------------------- |
| `viewport` | Clipped interaction surface; `touch-action: none` for consistent pointer handling |
| `inner` | Transform wrapper (`translate + scale`); uses `will-change: transform` |
| `grabbing` | Applied during drag to show a grabbing cursor |
| `colorMode` | Applied on the outer card when color mode is active |
| `previewMode` | Applied on the outer card when preview mode is active |
| `coloredRegion` | Added on shapes to reveal original fills |

### How “color reveal” works

In color mode, CSS forces the fill to white **unless** the element has `.coloredRegion`:

- `path:not(.coloredRegion)` (and friends) get `fill: white`
- When the user taps/clicks, the page adds `.coloredRegion` on that SVG element

This approach is intentionally simple:

- The SVG keeps its original `fill` values.
- CSS only overrides fill when the element is _not_ marked as revealed.

### Preview mode

Preview mode disables pointer interaction via:

- `pointer-events: none` on common SVG primitives

That preserves the user’s current reveal state while preventing accidental toggles during inspection.

### Extending shape support

If Img2Num emits additional SVG primitives (for example `line` or `polyline`), you’ll typically need to update:

1. `SHAPE_SELECTOR` in the page component
2. The CSS selectors in `Editor.module.css` for:
- the “fill white unless revealed” rule
- hover/interaction styling
- preview-mode pointer-events disabling

## Helmet and indexing (EditorHelmet.jsx)

The Editor page is treated as **non-indexable** because it’s essentially a workspace view:

- `<meta name="robots" content="noindex, nofollow" />`
- A descriptive `<title>` and `<meta name="description" />`

Note: even with `noindex`, a canonical URL is provided for consistency.

## Testing

- Page interactions and Helmet metadata are covered in [src/pages/Editor/Editor.test.jsx](../../../../src/pages/Editor/Editor.test.jsx) and [src/pages/Editor/EditorHelmet.test.jsx](../../../../src/pages/Editor/EditorHelmet.test.jsx).
- Additional guidance lives in [docs/docs/reference/pages/Editor/tests.md](./tests).
52 changes: 52 additions & 0 deletions docs/docs/reference/react/pages/Editor/tests.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
title: Editor Tests
description: Testing strategy and suggestions for the Editor page (pan/zoom, mode switching, and shape toggling).
keywords: [tests, vitest, testing-library, editor, svg, pointer events]
sidebar_label: Tests
---

# Editor Tests

The Editor page ([`src/pages/Editor/index.jsx`](https://github.com/Ryan-Millard/Img2Num/blob/main/src/pages/Editor/index.jsx)) is interaction-heavy, so coverage focuses on end-to-end behavior with **React Testing Library**.

## Current coverage

- [src/pages/Editor/Editor.test.jsx](../../../../src/pages/Editor/Editor.test.jsx):
- renders fallback when `location.state.svg` is missing
- renders provided SVG content
- adds `coloredRegion` on tap in color mode (one-way reveal)
- switches to preview mode (disables toggling) via the `GlassSwitch`
- [src/pages/Editor/EditorHelmet.test.jsx](../../../../src/pages/Editor/EditorHelmet.test.jsx): title, robots, description, and canonical meta.

## High-value behaviors to keep covered

- Empty state: direct navigation shows the “No SVG data found” panel.
- Mode switch: `aria-label` flips and the container class toggles between `colorMode` and `previewMode`.
- Shape reveal: tapping a supported primitive (`path`, `rect`, `circle`, `polygon`, `ellipse`) adds `coloredRegion` and keeps it applied on repeat taps (no toggle-off).

## Supplying SVG in tests

Render the page inside a router and pass state through `MemoryRouter` entries:

```jsx
render(
<MemoryRouter initialEntries={[{ pathname: '/editor', state: { svg: '<svg><path /></svg>' } }]}>
<Editor />
</MemoryRouter>
);
```

This avoids mocking `useLocation` and matches production usage.

## Pointer and wheel events (practical notes)

- `document.elementFromPoint` can be stubbed to return the shape you want to toggle; restore it after each test.
- Pan tests should move more than the ~5px threshold to be treated as a drag.
- Wheel zoom can be asserted by reading the inline `transform` on the wrapper.
- Pinch is multi-pointer; prefer unit-testing math in a helper if the logic is extracted.

## Common pitfalls

- Remember `act(...)` around pointer/wheel interactions that change React state.
- CSS modules hash class names; check `.classList.contains(styles.coloredRegion)` rather than string literals.
- Keep tests colocated under `src/pages/Editor/` (page-local) for discoverability.
10 changes: 10 additions & 0 deletions docs/docs/reference/react/pages/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"label": "Pages",
"position": 1,
"link": {
"type": "generated-index",
"title": "React Pages",
"description": "Reference for route-level React pages (screens) in Img2Num",
"slug": "/reference/react/pages"
}
}
21 changes: 21 additions & 0 deletions docs/docs/reference/react/pages/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
title: Pages
description: Reference documentation for Img2Num route-level pages (screens), their inputs, and key behaviors.
keywords: [reference, pages, routing, react-router, screens, Img2Num]
sidebar_label: Pages
sidebar_position: 1
---

# Pages

Route-level pages are the top-level screens rendered by React Router in [`src/App.jsx`](https://github.com/Ryan-Millard/Img2Num/blob/main/src/App.jsx).
This section documents what each page expects as input (URL params, `location.state`, etc.), what it renders, and any interaction logic worth knowing when contributing.

## Conventions

- Pages should be resilient to direct navigation (e.g., missing `location.state`) and show a friendly empty/error state.
- Page docs should call out:
- Route path
- Expected navigation state / inputs
- Main UI responsibilities
- Testing strategy (unit vs integration)
17 changes: 13 additions & 4 deletions src/pages/Editor/Editor.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
.viewport {
position: relative;
overflow: hidden;
touch-action: none;
user-select: none;
transition:
transform 180ms ease,
box-shadow 180ms ease;
Expand All @@ -12,15 +14,19 @@
cursor: grab;
background: transparent;
}
/* Default path appearance */
.colorMode .viewport svg path:not(.coloredRegion) {
/* Default shape appearance in color mode: hide original fills until revealed */
.colorMode .viewport svg path:not(.coloredRegion),
.colorMode .viewport svg rect:not(.coloredRegion),
.colorMode .viewport svg circle:not(.coloredRegion),
.colorMode .viewport svg polygon:not(.coloredRegion),
.colorMode .viewport svg ellipse:not(.coloredRegion) {
fill: white;
cursor: pointer;
transition: 150ms ease;
}

/* while dragging */
.viewport.grabbing {
/* while dragging (added via JS: styles.grabbing) */
.grabbing {
cursor: grabbing;
}

Expand Down Expand Up @@ -83,6 +89,9 @@

/* responsiveness */
@media (max-width: 800px) {
.grabbing {
cursor: move;
}
.viewport {
min-height: 240px;
}
Expand Down
Loading