@rcarls/rc-virtual-canvas 0.1.0

package/README.md

@@ -0,0 +1,171 @@
+# `@rcarls/rc-virtual-canvas`
+
+A virtualized scrollable canvas component. Overlays a transparent scrollable div on top of a slotted `<canvas>` element, dispatching `rc-virtual-canvas-render` events with the current viewport and content rectangles. Consumers draw only what is visible. Built with [Lit 3](https://lit.dev).
+
+---
+
+## Installation
+
+```bash
+npm install @rcarls/rc-virtual-canvas
+```
+
+## Import
+
+```js
+import '@rcarls/rc-virtual-canvas';                              // side-effect: registers <rc-virtual-canvas>
+import { RCVirtualCanvas } from '@rcarls/rc-virtual-canvas';    // named class export
+```
+
+---
+
+## Basic usage
+
+Place a `<canvas>` inside the component. Set `contentWidth` and `contentHeight` to the total size of your virtual content. On each `rc-virtual-canvas-render` event, use `detail.viewRect` to determine which portion of that content is visible and draw accordingly.
+
+```html
+<rc-virtual-canvas
+  id="vc"
+  contentWidth="4000"
+  contentHeight="3000"
+  style="width: 800px; height: 600px;"
+>
+  <canvas id="canvas" width="800" height="600"></canvas>
+</rc-virtual-canvas>
+
+<script>
+  const ctx = document.querySelector('#canvas').getContext('2d');
+
+  document.querySelector('#vc').addEventListener('rc-virtual-canvas-render', (e) => {
+    const { time, viewRect } = e.detail;
+
+    ctx.clearRect(0, 0, viewRect.width, viewRect.height);
+
+    // Draw only content within viewRect.x / viewRect.y offset
+    drawScene(ctx, viewRect);
+  });
+</script>
+```
+
+The canvas element should match the component's rendered size (set via CSS). The virtual content is larger — scrolling is handled by an absolutely-positioned transparent `<div>` that triggers native scroll events.
+
+---
+
+## API
+
+### Properties / attributes
+
+| Property | Attribute | Type | Default | Description |
+|---|---|---|---|---|
+| `contentWidth` | `contentWidth` | `number` | `0` | Total pixel width of the virtual content |
+| `contentHeight` | `contentHeight` | `number` | `0` | Total pixel height of the virtual content |
+| `autoResizeCanvas` | `auto-resize-canvas` | `boolean` | `true` | Keeps the slotted canvas backing store aligned to the measured viewport |
+| `renderMode` | `render-mode` | `'continuous' \| 'viewport-change' \| 'manual'` | `'continuous'` | Controls when render events are dispatched |
+| `imageRendering` | `image-rendering` | `'auto' \| 'crisp-edges' \| 'pixelated'` | `'auto'` | Convenience value applied to the slotted canvas via `image-rendering` |
+
+### Methods
+
+| Method | Description |
+|---|---|
+| `getViewRect()` | Returns an immutable snapshot of the current viewport rectangle |
+| `scrollToContent(x, y, options?)` | Scrolls so the content coordinate is at the viewport origin |
+| `centerOnContent(x, y, options?)` | Scrolls so the content coordinate is centered in the viewport |
+| `clientToContent(clientX, clientY)` | Converts browser client coordinates to content coordinates using the current backing-store scale |
+| `contentToClient(x, y)` | Converts content coordinates back to browser client coordinates |
+| `requestRender(reason?)` | Queues a render event; required when `renderMode` is `'manual'` |
+
+### CSS custom properties
+
+| Property | Default | Description |
+|---|---|---|
+| `--rc-virtual-canvas-image-rendering` | `auto` | Fallback styling hook for the slotted canvas `image-rendering` value |
+
+### CSS parts
+
+| Part | Description |
+|---|---|
+| `scroller` | Internal scroll container that owns the virtual content scroll range |
+| `overlay` | Viewport-positioned overlay container rendered inside the scroll container |
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| *(default)* | A single `<canvas>` element. Non-canvas slotted elements are ignored by the component but rendered. |
+| `overlay` | Optional viewport-positioned content rendered over the canvas inside the scroll container. |
+
+### Events
+
+| Event | Bubbles | Cancelable | Detail | When |
+|---|---|---|---|---|
+| `rc-virtual-canvas-render` | Yes (composed) | No | `{ time: DOMHighResTimeStamp, reason: RenderReason, viewRect: ViewRect, contentRect: ViewRect }` | When the active render mode schedules a frame and a canvas is slotted |
+
+**`ViewRect` shape:**
+
+```ts
+type ViewRect = {
+  x: number;      // Scroll offset — the x origin of the visible window in content space
+  y: number;      // Scroll offset — the y origin of the visible window in content space
+  width: number;  // Visible width in device pixels (from ResizeObserver devicePixelContentBoxSize)
+  height: number; // Visible height in device pixels
+};
+```
+
+`viewRect` is the visible window into the virtual content. `contentRect` is the full content bounds (`x: 0, y: 0, width: contentWidth, height: contentHeight`).
+
+`viewRect` and `contentRect` are frozen snapshots for the dispatched frame. Keep the object if you need it later; it will not be mutated by future scroll or resize work.
+
+**Render modes:**
+
+| Mode | Behavior |
+|---|---|
+| `'continuous'` | Dispatches on every animation frame while connected and a canvas is slotted |
+| `'viewport-change'` | Dispatches after scroll, resize, content-size changes, and canvas replacement |
+| `'manual'` | Dispatches only after `requestRender()` |
+
+---
+
+## Coordinate system
+
+The component maps scroll position directly to content coordinates:
+
+- `viewRect.x` = `scrollLeft` of the internal scroll container
+- `viewRect.y` = `scrollTop` of the internal scroll container
+- `viewRect.width` / `viewRect.height` = canvas dimensions in device pixels (high-DPI aware)
+
+When drawing, offset your scene by `viewRect.x` and `viewRect.y` to align the visible portion with the canvas origin:
+
+```js
+ctx.translate(-viewRect.x, -viewRect.y);
+drawEntireScene(ctx);
+ctx.resetTransform();
+```
+
+Pointer input can be mapped through the same coordinate system:
+
+```js
+vc.addEventListener('pointerdown', (event) => {
+  const point = vc.clientToContent(event.clientX, event.clientY);
+
+  selectThingAt(point.x, point.y);
+});
+```
+
+---
+
+## Accessibility
+
+`rc-virtual-canvas` is a rendering surface. A `<canvas>` element has no inherent semantics — it is a bitmap, not a document. If your canvas renders interactive or informational content, you are responsible for providing supplemental accessibility:
+
+- Add an accessible `<div>` or `<table>` alternative outside the canvas with the same information (hidden visually with `clip-path` or similar, not `display: none`).
+- Use `aria-label` or `aria-labelledby` on the `<canvas>` to describe what it shows.
+- For interactive canvas content (hit-testing, drag-and-drop), implement keyboard equivalents on a separate focusable element.
+
+---
+
+## Browser support
+
+| Feature | Requirement |
+|---|---|
+| Core | Chrome 67+, Firefox 63+, Safari 12.1+ (Web Components) |
+| Device-pixel-accurate sizing | Chrome 84+, Firefox 93+, Safari 15.4+ (ResizeObserver `devicePixelContentBoxSize`) |

package/dist/custom-elements.json

@@ -0,0 +1,531 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/define.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "rc-virtual-canvas",
+          "declaration": {
+            "name": "RCVirtualCanvas",
+            "module": "/src/index.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "module": "src/index.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "module": "src/rc-virtual-canvas"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/rc-virtual-canvas.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "An accessible virtual scrollable canvas component.",
+          "name": "RCVirtualCanvas",
+          "slots": [
+            {
+              "description": "The HTMLCanvasElement",
+              "name": ""
+            },
+            {
+              "description": "Optional viewport-positioned content rendered inside the scroll container above the canvas.",
+              "name": "overlay"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "_rafHandle",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "_pendingRenderReason",
+              "type": {
+                "text": "RCVirtualCanvasRenderReason | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "_handledPointerEvents",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new WeakSet<Event>()"
+            },
+            {
+              "kind": "field",
+              "name": "_boundUpdate",
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "_boundPointerEvent",
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "contentWidth",
+              "description": "Pixel width of the virtual content",
+              "attribute": "contentWidth"
+            },
+            {
+              "kind": "field",
+              "name": "_contentWidth",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "protected",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "contentHeight",
+              "description": "Pixel height of the virtual content",
+              "attribute": "contentHeight"
+            },
+            {
+              "kind": "field",
+              "name": "_contentHeight",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "protected",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "autoResizeCanvas",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "When true, keep the slotted canvas backing store aligned to the viewport.",
+              "attribute": "auto-resize-canvas"
+            },
+            {
+              "kind": "field",
+              "name": "renderMode",
+              "type": {
+                "text": "RCVirtualCanvasRenderMode"
+              },
+              "default": "'continuous'",
+              "description": "Controls when render events are dispatched.",
+              "attribute": "render-mode"
+            },
+            {
+              "kind": "field",
+              "name": "imageRendering",
+              "type": {
+                "text": "RCVirtualCanvasImageRendering"
+              },
+              "default": "'auto'",
+              "description": "Convenience image-rendering value applied to the slotted canvas.",
+              "attribute": "image-rendering"
+            },
+            {
+              "kind": "field",
+              "name": "_$root",
+              "type": {
+                "text": "HTMLDivElement"
+              },
+              "privacy": "protected"
+            },
+            {
+              "kind": "field",
+              "name": "_$placeholder",
+              "type": {
+                "text": "HTMLDivElement"
+              },
+              "privacy": "protected"
+            },
+            {
+              "kind": "field",
+              "name": "_$canvas",
+              "type": {
+                "text": "HTMLCanvasElement | null"
+              },
+              "privacy": "protected",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_viewRect",
+              "type": {
+                "text": "object"
+              },
+              "privacy": "protected",
+              "default": "{ x: 0, y: 0, width: 0, height: 0, }"
+            },
+            {
+              "kind": "field",
+              "name": "_contentRect",
+              "type": {
+                "text": "object"
+              },
+              "privacy": "protected",
+              "default": "{ x: 0, y: 0, width: 0, height: 0, }"
+            },
+            {
+              "kind": "field",
+              "name": "_resizeObserver",
+              "privacy": "protected",
+              "default": "new ResizeObserver( (entries: ResizeObserverEntry[]) => { for (const entry of entries) { const devicePixelBoxSize = Array.isArray( entry.devicePixelContentBoxSize, ) ? entry.devicePixelContentBoxSize[0] : entry.devicePixelContentBoxSize; this._viewRect.width = this._getMeasuredCanvasWidth( devicePixelBoxSize?.inlineSize ?? Math.round(entry.contentRect.width * window.devicePixelRatio), ); this._viewRect.height = this._getMeasuredCanvasHeight( devicePixelBoxSize?.blockSize ?? Math.round(entry.contentRect.height * window.devicePixelRatio), ); this._syncCanvasBackingStore(); this._scheduleRender('viewport-change'); } }, )"
+            },
+            {
+              "kind": "method",
+              "name": "_onScroll",
+              "privacy": "protected"
+            },
+            {
+              "kind": "method",
+              "name": "_onSlotChange",
+              "privacy": "protected",
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "getViewRect"
+            },
+            {
+              "kind": "method",
+              "name": "scrollToContent",
+              "parameters": [
+                {
+                  "name": "x",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "y",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "options",
+                  "default": "{}",
+                  "type": {
+                    "text": "ScrollOptions"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "centerOnContent",
+              "parameters": [
+                {
+                  "name": "x",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "y",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "options",
+                  "default": "{}",
+                  "type": {
+                    "text": "ScrollOptions"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "clientToContent",
+              "parameters": [
+                {
+                  "name": "clientX",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "clientY",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "contentToClient",
+              "parameters": [
+                {
+                  "name": "x",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "y",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "requestRender",
+              "parameters": [
+                {
+                  "name": "reason",
+                  "default": "'manual'",
+                  "type": {
+                    "text": "RCVirtualCanvasRenderReason"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_onPointerEvent",
+              "privacy": "protected",
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "PointerEvent | MouseEvent"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_isOverlayEvent",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_update",
+              "privacy": "protected",
+              "parameters": [
+                {
+                  "name": "time",
+                  "type": {
+                    "text": "DOMHighResTimeStamp"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_scheduleRender",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "reason",
+                  "type": {
+                    "text": "RCVirtualCanvasRenderReason"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_syncCanvasBackingStore",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_getCanvasClientRect",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_getMeasuredCanvasWidth",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "fallbackWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_getMeasuredCanvasHeight",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "fallbackHeight",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_getViewportScaleX",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "canvasRect",
+                  "type": {
+                    "text": "DOMRect"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_getViewportScaleY",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "canvasRect",
+                  "type": {
+                    "text": "DOMRect"
+                  }
+                }
+              ]
+            }
+          ],
+          "events": [
+            {
+              "name": "rc-virtual-canvas-pointer",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fires pointer/mouse input mapped to virtual content coordinates."
+            },
+            {
+              "name": "rc-virtual-canvas-render",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fires with viewport data when the canvas should redraw."
+            }
+          ],
+          "attributes": [
+            {
+              "name": "contentWidth",
+              "description": "Pixel width of the virtual content",
+              "fieldName": "contentWidth"
+            },
+            {
+              "name": "contentHeight",
+              "description": "Pixel height of the virtual content",
+              "fieldName": "contentHeight"
+            },
+            {
+              "name": "auto-resize-canvas",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "When true, keep the slotted canvas backing store aligned to the viewport.",
+              "fieldName": "autoResizeCanvas"
+            },
+            {
+              "name": "render-mode",
+              "type": {
+                "text": "RCVirtualCanvasRenderMode"
+              },
+              "default": "'continuous'",
+              "description": "Controls when render events are dispatched.",
+              "fieldName": "renderMode"
+            },
+            {
+              "name": "image-rendering",
+              "type": {
+                "text": "RCVirtualCanvasImageRendering"
+              },
+              "default": "'auto'",
+              "description": "Convenience image-rendering value applied to the slotted canvas.",
+              "fieldName": "imageRendering"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "rc-virtual-canvas",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "RCVirtualCanvas",
+          "declaration": {
+            "name": "RCVirtualCanvas",
+            "module": "src/rc-virtual-canvas.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "RCVirtualCanvas",
+            "module": "src/rc-virtual-canvas.ts"
+          }
+        }
+      ]
+    }
+  ]
+}