@rcarls/rc-virtual-canvas 0.0.0-next-20260921045401

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# @rcarls/rc-virtual-canvas
+
+## 0.0.0-next-20260921045401
+
+## 0.6.0
+
+### Patch Changes
+
+- 57370e4: Align component metadata, aggregate framework typings, development-time native-child
+  validation, controlled menu state, package declarations, and public documentation before the
+  next release.
+
+## 0.5.0
+
+## 0.4.2
+
+## 0.4.1
+
+## 0.4.0
+
+### Patch Changes
+
+- 037b1b3: Add try/catch for ResizeObserver.observe() for WebKit TypeError
+- d49cde9: Fix `contentWidth`/`contentHeight` so their HTML attributes are `content-width`/`content-height`,
+  matching every other multi-word attribute in the library. They previously had no kebab-case
+  mapping, so `<rc-virtual-canvas content-width="...">` was silently ignored.
+
+## 0.3.2
+
+## 0.3.1
+
+## 0.3.0
+
+### Added
+
+- Add read-only `canvasScaleX` and `canvasScaleY` getters.
+
+### Changed
+
+- Update package metadata, README intro, and docs links.
+
+## 0.2.0

package/README.md

@@ -0,0 +1,190 @@
+# `@rcarls/rc-virtual-canvas`
+
+<!-- markdownlint-disable MD013 -->
+
+Scrollable virtual canvas for rendering large coordinate-space content.
+
+Docs: [https://richardcarls.github.io/rc-webcomponents/components/rc-virtual-canvas](https://richardcarls.github.io/rc-webcomponents/components/rc-virtual-canvas).
+
+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.
+
+---
+
+## 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 `content-width` and `content-height` 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"
+  content-width="4000"
+  content-height="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`     | `content-width`      | `number`                                        | `0`            | Total pixel width of the virtual content                                |
+| `contentHeight`    | `content-height`     | `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`   |
+
+### Read-only properties
+
+| Property       | Type     | Description                                                                                                                  |
+| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `canvasScaleX` | `number` | Ratio of canvas backing-store pixels to CSS pixels along the x-axis (≈ `devicePixelRatio` when `autoResizeCanvas` is `true`) |
+| `canvasScaleY` | `number` | Ratio of canvas backing-store pixels to CSS pixels along the y-axis                                                          |
+
+### 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`) |