Repository navigation
Add touch gestures to editor page #226
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
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 64b7916
added css property to overide the default pointer events by browser
codevory 32e2c6a
added tests for Editor in index.js
codevory 35c4ffc
added tests for EditorHelmt
codevory 747791d
added touch gestures , pinch zoom , color toggle on click,image drag etc
codevory 54936bc
Format Editor component spacing
codevory f6ff879
addd error handling block
codevory bb9f181
implemented the issues pointed out
codevory 2aea399
improved the docs
codevory f5b5e18
improved the lint
codevory 902e54d
Merge branch 'main' into modified
codevory e395037
improved docs structure & implemented feedback
codevory adc347c
Merge branch 'modified' of https://github.com/codevory/Img2Num into m…
codevory 60fbf31
disabled toggle color on click/tap
codevory b7ae588
removed toggle color & refactored the docs
codevory 1d1f187
formatted structure
codevory 3809fdd
Merge branch 'main' into modified
codevory 7e029c8
formatted with prettier
codevory c0da3ed
formatted with prettier
codevory cf25e03
Merge branch 'modified' of https://github.com/codevory/Img2Num into m…
codevory ef4cc28
Merge branch 'main' into modified
Ryan-Millard e1c421e
condensed the docs content to make it ease to read
codevory b3046e3
Merge branch 'modified' of https://github.com/codevory/Img2Num into m…
codevory File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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" | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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