vue-canvas-frame-headless 4.4.0 → 4.5.0

package/README.md

@@ -5,7 +5,7 @@
 [![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).
 
@@ -19,10 +19,14 @@ Design notes live in [the specs](https://github.com/Esposter/Esposter/tree/main/
 
 ## <a name="getting-started">🚀 Getting Started</a>
 
+1. Install the package.
+
 ```bash
 pnpm i vue-canvas-frame-headless
 ```
 
+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";
@@ -51,14 +55,14 @@ const { frameBody, frameStyle } = useCanvasFrame({
 
 ## <a name="key-exports">🧩 Key Exports</a>
 
-| Export                | Kind       | Purpose                                                                                  |
-| --------------------- | ---------- | ---------------------------------------------------------------------------------------- |
-| `CANVAS_FRAME_SRCDOC` | const      | The document every frame starts from, before its page's markup is teleported into it     |
-| `getFrameScale`       | function   | The scale that fits a frame to a pane, never above 1, and 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     |
+| 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                  |
 
-`getFrameWidth` and `getFrameScale` are the pure geometry the composable uses, exported on their own.
+`getFrameWidth` and `getFrameScale` are the pure geometry that `useCanvasFrame` uses. They are exported on their own.
 
 ## <a name="license">⚖️ License</a>
 

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+export declare const useCanvasFrame: ({ css, fill, frame, pane, width }: {
+  css: MaybeRefOrGetter<string>;
+  fill?: MaybeRefOrGetter<boolean>;
+  frame: Ref<HTMLIFrameElement | null | undefined>;
+  pane: Ref<HTMLElement | null | undefined>;
+  width: MaybeRefOrGetter<number>;
+}) => {
+  frameBody: ComputedRef<HTMLElement | undefined>;
+  frameStyle: ComputedRef<Record<string, string>>;
+  loaded: Promise<void>;
+};
+export declare const CANVAS_FRAME_SRCDOC = "<!doctype html><html><head></head><body></body></html>";
+export declare const getFrameScale: (paneWidth: number, frameWidth: number) => number;
+export declare const getFrameWidth: (width: number, fill: boolean, paneWidth: number) => number;

package/dist/index.js

@@ -0,0 +1,70 @@
+import { computed, onMounted, onScopeDispose, shallowRef, toValue, watch } from "vue";
+// src/services/getFrameScale.ts
+const getFrameScale = (paneWidth, frameWidth) => paneWidth > 0 ? Math.min(1, paneWidth / frameWidth) : 1;
+// src/services/getFrameWidth.ts
+const getFrameWidth = (width, fill, paneWidth) => fill ? Math.max(paneWidth, width) : width;
+// src/composables/useCanvasFrame.ts
+const useCanvasFrame = ({ css, fill, frame, pane, width }) => {
+	const { promise: loaded, resolve: resolveLoaded } = Promise.withResolvers();
+	const frameDocument = shallowRef();
+	const frameStyleSheet = shallowRef();
+	const paneHeight = shallowRef(0);
+	const paneWidth = shallowRef(0);
+	const frameBody = computed(() => frameDocument.value?.body);
+	const frameWidth = computed(() => getFrameWidth(toValue(width), toValue(fill ?? false), paneWidth.value));
+	const frameScale = computed(() => getFrameScale(paneWidth.value, frameWidth.value));
+	const frameStyle = computed(() => ({
+		height: `${paneHeight.value / frameScale.value}px`,
+		transform: `scale(${frameScale.value})`,
+		transformOrigin: "0 0",
+		width: `${frameWidth.value}px`
+	}));
+	const updatePaneSize = (paneElement) => {
+		paneWidth.value = paneElement.clientWidth;
+		paneHeight.value = paneElement.clientHeight;
+	};
+	let resizeObserver;
+	onMounted(() => {
+		const paneElement = pane.value;
+		if (!paneElement) return;
+		updatePaneSize(paneElement);
+		resizeObserver = new ResizeObserver(() => {
+			updatePaneSize(paneElement);
+		});
+		resizeObserver.observe(paneElement);
+	});
+	onScopeDispose(() => resizeObserver?.disconnect());
+	const handleLoad = () => {
+		const contentWindow = frame.value?.contentWindow;
+		const contentDocument = frame.value?.contentDocument;
+		if (!contentWindow || !contentDocument) return;
+		const styleSheet = new contentWindow.CSSStyleSheet();
+		contentDocument.adoptedStyleSheets = [styleSheet];
+		frameStyleSheet.value = styleSheet;
+		frameDocument.value = contentDocument;
+		resolveLoaded();
+	};
+	watch(frame, (frameElement, _previousFrameElement, onCleanup) => {
+		frameElement?.addEventListener("load", handleLoad);
+		onCleanup(() => {
+			frameElement?.removeEventListener("load", handleLoad);
+		});
+	}, {
+		flush: "sync",
+		immediate: true
+	});
+	watch([frameStyleSheet, () => toValue(css)], ([styleSheet, cssText], _previous, onCleanup) => {
+		const styleFrame = requestAnimationFrame(() => styleSheet?.replaceSync(cssText));
+		onCleanup(() => {
+			cancelAnimationFrame(styleFrame);
+		});
+	});
+	return {
+		frameBody,
+		frameStyle,
+		loaded
+	};
+};
+// src/services/constants.ts
+const CANVAS_FRAME_SRCDOC = "<!doctype html><html><head></head><body></body></html>";
+export { CANVAS_FRAME_SRCDOC, getFrameScale, getFrameWidth, useCanvasFrame };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-canvas-frame-headless",
-  "version": "4.4.0",
+  "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",
@@ -43,13 +43,14 @@
     "typecheck": "tsrs --fast"
   },
   "devDependencies": {
-    "@esposter/configuration": "4.4.0",
+    "@esposter/configuration": "4.5.0",
+    "@types/node": "^26.6.6",
     "@vue/test-utils": "^2.5.1",
     "happy-dom": "^21.0.4",
-    "tsdown": "0.23.2"
+    "tsdown": "^0.23.5"
   },
   "peerDependencies": {
     "vue": "^3.5.44"
   },
-  "gitHead": "e1a416c4b91da69cc2aa259b50a4d656f204d272"
+  "gitHead": "e30c001f3b4b15693e75fb53092d62a97ade4d2b"
 }