vue-canvas-frame-headless 4.3.3 → 4.5.0

package/README.md

@@ -5,33 +5,42 @@
 [![NPM downloads][badge-npm-downloads]][url-npm]
 [![NPM Unpacked Size (with version)][badge-npm-unpacked-size]][url-npm]
 
-A headless canvas frame: `useCanvasFrame` draws its content in an isolated document at a width, scales it down to fit a narrower pane, and adopts a stylesheet into that document, with no styling of its own.
+This package is a headless canvas frame with no styling of its own. `useCanvasFrame` draws content in an isolated document at a width, scales it down to fit a narrower pane, and adopts a stylesheet into that document.
+
+Design notes live in [the specs](https://github.com/Esposter/Esposter/tree/main/openspec/specs).
 
 ## Table of Contents
 
 - 🚀 [Getting Started](#getting-started)
-- 📖 [Usage](#usage)
-- 📖 [Documentation](#documentation)
-- 🧪 [Tests](#tests)
+- 🧩 [Key Exports](#key-exports)
 - ⚖️ [License](#license)
 
 ---
 
 ## <a name="getting-started">🚀 Getting Started</a>
 
+1. Install the package.
+
 ```bash
 pnpm i vue-canvas-frame-headless
 ```
 
-## <a name="usage">📖 Usage</a>
+2. Create a component from this code. The slot content appears inside the frame.
 
 ```vue
 <script setup lang="ts">
 import { CANVAS_FRAME_SRCDOC, useCanvasFrame } from "vue-canvas-frame-headless";
-
-const frame = useTemplateRef("frame");
-const pane = useTemplateRef("pane");
-const { frameBody, frameStyle } = useCanvasFrame({ css: pageCss, fill: true, frame, pane, width: 992 });
+import { useTemplateRef } from "vue";
+
+const frame = useTemplateRef<HTMLIFrameElement>("frame");
+const pane = useTemplateRef<HTMLElement>("pane");
+const { frameBody, frameStyle } = useCanvasFrame({
+  css: "body { margin: 0; font-family: sans-serif; }",
+  fill: true,
+  frame,
+  pane,
+  width: 992,
+});
 </script>
 
 <template>
@@ -44,15 +53,16 @@ const { frameBody, frameStyle } = useCanvasFrame({ css: pageCss, fill: true, fra
 </template>
 ```
 
-`getFrameWidth` and `getFrameScale` are the pure geometry the composable uses, exported on their own.
-
-## <a name="documentation">📖 Documentation</a>
-
-We highly recommend you take a look at the [documentation](https://github.com/Esposter/Esposter/tree/main/openspec/specs) to level up.
+## <a name="key-exports">🧩 Key Exports</a>
 
-## <a name="tests">🧪 Tests</a>
+| Export                | Kind       | Purpose                                                                                               |
+| --------------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
+| `CANVAS_FRAME_SRCDOC` | const      | The document that every frame starts from, before the page markup is teleported into it               |
+| `getFrameScale`       | function   | The scale that fits a frame to a pane. It is never above 1, and it is 1 while the pane is unmeasured. |
+| `getFrameWidth`       | function   | The frame's width: its least width, or the pane's width when it fills a wider pane                    |
+| `useCanvasFrame`      | composable | Draws content in an isolated document at a width, scaled down to fit a narrower pane                  |
 
-`pnpm test` runs the unit tests under happy-dom. `pnpm test:browser` runs the browser tests in a real browser, on the shared browser configuration, with no Nuxt.
+`getFrameWidth` and `getFrameScale` are the pure geometry that `useCanvasFrame` uses. They are exported on their own.
 
 ## <a name="license">⚖️ License</a>
 

package/dist/index.js

@@ -28,7 +28,9 @@ const useCanvasFrame = ({ css, fill, frame, pane, width }) => {
 		const paneElement = pane.value;
 		if (!paneElement) return;
 		updatePaneSize(paneElement);
-		resizeObserver = new ResizeObserver(() => updatePaneSize(paneElement));
+		resizeObserver = new ResizeObserver(() => {
+			updatePaneSize(paneElement);
+		});
 		resizeObserver.observe(paneElement);
 	});
 	onScopeDispose(() => resizeObserver?.disconnect());
@@ -42,20 +44,21 @@ const useCanvasFrame = ({ css, fill, frame, pane, width }) => {
 		frameDocument.value = contentDocument;
 		resolveLoaded();
 	};
-	watch(frame, (frameElement, previousFrameElement) => {
-		previousFrameElement?.removeEventListener("load", handleLoad);
+	watch(frame, (frameElement, _previousFrameElement, onCleanup) => {
 		frameElement?.addEventListener("load", handleLoad);
+		onCleanup(() => {
+			frameElement?.removeEventListener("load", handleLoad);
+		});
 	}, {
 		flush: "sync",
 		immediate: true
 	});
-	onScopeDispose(() => frame.value?.removeEventListener("load", handleLoad));
-	let styleFrame = 0;
-	watch([frameStyleSheet, () => toValue(css)], ([styleSheet, cssText]) => {
-		cancelAnimationFrame(styleFrame);
-		styleFrame = requestAnimationFrame(() => styleSheet?.replaceSync(cssText));
+	watch([frameStyleSheet, () => toValue(css)], ([styleSheet, cssText], _previous, onCleanup) => {
+		const styleFrame = requestAnimationFrame(() => styleSheet?.replaceSync(cssText));
+		onCleanup(() => {
+			cancelAnimationFrame(styleFrame);
+		});
 	});
-	onScopeDispose(() => cancelAnimationFrame(styleFrame));
 	return {
 		frameBody,
 		frameStyle,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-canvas-frame-headless",
-  "version": "4.3.3",
+  "version": "4.5.0",
   "description": "A headless canvas frame: an isolated document at a width, scaled down to fit a narrower pane, with its styles adopted into it, and no styling of its own.",
   "keywords": [
     "headless",
@@ -40,16 +40,17 @@
     "lint:fix": "eslint --fix .",
     "test": "vitest",
     "test:browser": "vitest --config vitest.browser.config.ts",
-    "typecheck": "tsc"
+    "typecheck": "tsrs --fast"
   },
   "devDependencies": {
-    "@esposter/configuration": "4.3.3",
+    "@esposter/configuration": "4.5.0",
+    "@types/node": "^26.6.6",
     "@vue/test-utils": "^2.5.1",
     "happy-dom": "^21.0.4",
-    "tsdown": "^0.23.1"
+    "tsdown": "^0.23.5"
   },
   "peerDependencies": {
     "vue": "^3.5.44"
   },
-  "gitHead": "955bbc130ad9b28877fd4ae8efc73a045141ce01"
+  "gitHead": "e30c001f3b4b15693e75fb53092d62a97ade4d2b"
 }