vue-canvas-frame-headless 4.3.1 → 4.4.0

package/README.md

@@ -7,12 +7,12 @@
 
 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.
 
+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)
 
 ---
@@ -23,15 +23,20 @@ A headless canvas frame: `useCanvasFrame` draws its content in an isolated docum
 pnpm i vue-canvas-frame-headless
 ```
 
-## <a name="usage">📖 Usage</a>
-
 ```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 +49,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="key-exports">🧩 Key Exports</a>
 
-## <a name="documentation">📖 Documentation</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     |
 
-We highly recommend you take a look at the [documentation](https://github.com/Esposter/Esposter/tree/main/openspec/specs) to level up.
-
-## <a name="tests">🧪 Tests</a>
-
-`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 the composable uses, exported on their own.
 
 ## <a name="license">⚖️ License</a>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-canvas-frame-headless",
-  "version": "4.3.1",
+  "version": "4.4.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,16 @@
     "lint:fix": "eslint --fix .",
     "test": "vitest",
     "test:browser": "vitest --config vitest.browser.config.ts",
-    "typecheck": "tsc"
+    "typecheck": "tsrs --fast"
   },
   "devDependencies": {
-    "@esposter/configuration": "4.3.1",
+    "@esposter/configuration": "4.4.0",
     "@vue/test-utils": "^2.5.1",
     "happy-dom": "^21.0.4",
-    "tsdown": "^0.23.1"
+    "tsdown": "0.23.2"
   },
   "peerDependencies": {
     "vue": "^3.5.44"
   },
-  "gitHead": "777a39636b789c13af33ed13370246ccf6dbaf31"
+  "gitHead": "e1a416c4b91da69cc2aa259b50a4d656f204d272"
 }

package/dist/index.d.ts

@@ -1,23 +0,0 @@
-import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
-//#region src/composables/useCanvasFrame.d.ts
-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>;
-};
-//#endregion
-//#region src/services/constants.d.ts
-export declare const CANVAS_FRAME_SRCDOC = "<!doctype html><html><head></head><body></body></html>";
-//#endregion
-//#region src/services/getFrameScale.d.ts
-export declare const getFrameScale: (paneWidth: number, frameWidth: number) => number;
-//#endregion
-//#region src/services/getFrameWidth.d.ts
-export declare const getFrameWidth: (width: number, fill: boolean, paneWidth: number) => number;
-//#endregion

package/dist/index.js

@@ -1,71 +0,0 @@
-import { computed, onMounted, onScopeDispose, shallowRef, toValue, watch } from "vue";
-//#region src/services/getFrameScale.ts
-const getFrameScale = (paneWidth, frameWidth) => paneWidth > 0 ? Math.min(1, paneWidth / frameWidth) : 1;
-//#endregion
-//#region src/services/getFrameWidth.ts
-const getFrameWidth = (width, fill, paneWidth) => fill ? Math.max(paneWidth, width) : width;
-//#endregion
-//#region 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) => {
-		previousFrameElement?.removeEventListener("load", handleLoad);
-		frameElement?.addEventListener("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));
-	});
-	onScopeDispose(() => cancelAnimationFrame(styleFrame));
-	return {
-		frameBody,
-		frameStyle,
-		loaded
-	};
-};
-//#endregion
-//#region src/services/constants.ts
-const CANVAS_FRAME_SRCDOC = "<!doctype html><html><head></head><body></body></html>";
-//#endregion
-export { CANVAS_FRAME_SRCDOC, getFrameScale, getFrameWidth, useCanvasFrame };