@weapp-vite/glass-easel-web-adapter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ice breaker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @weapp-vite/glass-easel-web-adapter
+
+实验性的 glass-easel Web 组件后端。它复用 glass-easel 官方组件树、模板编译和浏览器 backend，向 weapp-vite Web host 提供受控的组件挂载、数据更新、事件和生命周期桥接。
+
+该包不会替换 `@weapp-vite/web`，也不实现页面路由、WXSS/rpx、微信 API 或全部原生组件。调用方必须显式创建 adapter；当前默认 Web runtime 不受影响。
+
+`mountComponent` 的第四个参数可传入 `slots`，用于将受控 HTML 投影到模板中的 `<slot />`。这是 PoC 的 DOM 桥接，复杂 slot 关系仍需由后续组件树适配器实现。
+
+## 验证
+
+```bash
+pnpm --filter @weapp-vite/glass-easel-web-adapter typecheck
+pnpm --filter @weapp-vite/glass-easel-web-adapter test
+pnpm --filter @weapp-vite/glass-easel-web-adapter test:types
+pnpm --filter @weapp-vite/glass-easel-web-adapter test:browser
+pnpm --filter @weapp-vite/glass-easel-web-adapter build
+```

package/dist/index.d.mts

@@ -0,0 +1,53 @@
+//#region src/index.d.ts
+export interface GlassEaselWebHost {
+  createElement?: (tagName: string) => HTMLElement;
+  dispatchEvent?: (event: Event, context: unknown) => void;
+  warn?: (message: string) => void;
+}
+export interface GlassEaselComponentDefinition {
+  name: string;
+  template: string;
+  properties?: Record<string, unknown>;
+  methods?: Record<string, (...args: unknown[]) => unknown>;
+  lifetimes?: Record<string, (...args: unknown[]) => void>;
+}
+export interface GlassEaselWebAdapterOptions {
+  host?: GlassEaselWebHost;
+  strict?: boolean;
+}
+export interface GlassEaselWebSnapshot {
+  name: string;
+  props: Record<string, unknown>;
+  html: string;
+  lifecycle: string[];
+  disposed: boolean;
+}
+export interface GlassEaselWebAdapter {
+  registerComponent: (definition: GlassEaselComponentDefinition) => void;
+  mountComponent: (name: string, container: Element, props?: Record<string, unknown>, slots?: Record<string, string>) => GlassEaselWebInstance;
+  updateComponent: (instance: unknown, props: Record<string, unknown>) => void;
+  triggerEvent: (instance: unknown, name: string, detail?: unknown) => void;
+  unmountComponent: (instance: unknown) => void;
+  getSnapshot: (instance: unknown) => GlassEaselWebSnapshot;
+  dispose: () => void;
+}
+/** 使用官方 ComponentSpace API 创建可复用的 glass-easel 组件定义。 */
+export declare function createGlassEaselComponentDefinition(definition: GlassEaselComponentDefinition): unknown;
+export interface GlassEaselWebInstance {
+  root: HTMLElement;
+  definition: GlassEaselComponentDefinition;
+  props: Record<string, unknown>;
+  disposed: boolean;
+  native?: any;
+  backendContext?: any;
+  lifecycle: string[];
+}
+export declare function createGlassEaselWebAdapter(options?: GlassEaselWebAdapterOptions): GlassEaselWebAdapter;
+export interface GlassEaselRuntimeInfo {
+  version: string;
+  hasDomBackend: boolean;
+  hasTemplateCompiler: boolean;
+}
+/** 返回当前安装的 glass-easel 能力探针，供宿主决定是否启用实验后端。 */
+export declare function getGlassEaselRuntimeInfo(): GlassEaselRuntimeInfo;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,135 @@
+import * as glassEasel from "glass-easel";
+import { wxml } from "glass-easel-template-compiler";
+//#region src/index.ts
+/** 使用官方 ComponentSpace API 创建可复用的 glass-easel 组件定义。 */
+function createGlassEaselComponentDefinition(definition) {
+	const space = glassEasel.getDefaultComponentSpace();
+	const params = { template: wxml(definition.template) };
+	if (definition.properties) params.properties = definition.properties;
+	if (definition.methods) params.methods = definition.methods;
+	if (definition.lifetimes) params.lifetimes = definition.lifetimes;
+	return space.define().definition(params).registerComponent();
+}
+function render(template, props, host) {
+	const root = host.createElement?.("div") ?? document.createElement("div");
+	root.innerHTML = template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, key) => String(key.split(".").reduce((value, part) => value?.[part], props) ?? ""));
+	return root;
+}
+function createGlassEaselWebAdapter(options = {}) {
+	const definitions = /* @__PURE__ */ new Map();
+	const instances = /* @__PURE__ */ new Set();
+	if (options.strict && !getGlassEaselRuntimeInfo().hasDomBackend) throw new Error("glass-easel Web backend is unavailable in this environment");
+	return {
+		registerComponent(definition) {
+			if (!definition.name || !definition.template) throw new TypeError("glass-easel component requires name and template");
+			if (definitions.has(definition.name)) throw new Error(`component already registered: ${definition.name}`);
+			definitions.set(definition.name, {
+				...definition,
+				native: createGlassEaselComponentDefinition(definition)
+			});
+		},
+		mountComponent(name, container, props = {}, slots = {}) {
+			const definition = definitions.get(name);
+			if (!definition) throw new Error(`component is not registered: ${name}`);
+			let root;
+			let native;
+			let backendContext;
+			if (definition.native && getGlassEaselRuntimeInfo().hasDomBackend) {
+				const placeholder = document.createElement("glass-easel-placeholder");
+				container.append(placeholder);
+				backendContext = new glassEasel.CurrentWindowBackendContext();
+				backendContext.onEvent(glassEasel.Event.triggerBackendEvent);
+				native = glassEasel.Component.createWithContext(name, definition.native, backendContext, (component) => {
+					component.setData(props);
+				});
+				glassEasel.Element.replaceDocumentElement(native, placeholder.parentNode, placeholder);
+				root = container.firstElementChild;
+				projectSlots(root, slots);
+			} else {
+				root = render(definition.template, props, options.host ?? {});
+				container.append(root);
+			}
+			const instance = {
+				root,
+				definition,
+				props: { ...props },
+				disposed: false,
+				native,
+				backendContext,
+				lifecycle: []
+			};
+			for (const name of [
+				"created",
+				"attached",
+				"ready",
+				"detached"
+			]) instance.native?.addLifetimeListener?.(name, () => instance.lifecycle.push(name));
+			instances.add(instance);
+			return instance;
+		},
+		updateComponent(value, props) {
+			const instance = value;
+			if (instance.disposed) throw new Error("cannot update a disposed glass-easel component");
+			instance.props = {
+				...instance.props,
+				...props
+			};
+			if (instance.native) instance.native.setData(props);
+			else {
+				const replacement = render(instance.definition.template, instance.props, options.host ?? {});
+				instance.root.replaceWith(replacement);
+				instance.root = replacement;
+			}
+		},
+		triggerEvent(value, name, detail) {
+			const instance = value;
+			if (instance.disposed) throw new Error("cannot trigger an event on a disposed glass-easel component");
+			if (instance.native) instance.native.triggerEvent(name, detail);
+			options.host?.dispatchEvent?.(new CustomEvent(name, { detail }), instance);
+		},
+		unmountComponent(value) {
+			const instance = value;
+			if (!instances.delete(instance) || instance.disposed) return;
+			instance.native?.triggerLifetime?.("detached");
+			if (!instance.native) instance.lifecycle.push("detached");
+			instance.root?.remove();
+			instance.disposed = true;
+		},
+		getSnapshot(value) {
+			const instance = value;
+			return {
+				name: instance.definition.name,
+				props: { ...instance.props },
+				html: instance.root.innerHTML,
+				lifecycle: [...instance.lifecycle],
+				disposed: instance.disposed
+			};
+		},
+		dispose() {
+			for (const instance of [...instances]) this.unmountComponent(instance);
+			definitions.clear();
+		}
+	};
+}
+/** 将受控 PoC slot 内容投影到官方 backend 生成的 DOM。复杂 slot 仍需由宿主组件树实现。 */
+function projectSlots(root, slots) {
+	let projected = false;
+	for (const slot of Array.from(root.querySelectorAll("slot"))) {
+		const content = slots[slot.getAttribute("name") || "default"];
+		if (content === void 0) continue;
+		const fragment = document.createRange().createContextualFragment(content);
+		slot.replaceWith(fragment);
+		projected = true;
+	}
+	if (!projected && slots.default !== void 0) (root.firstElementChild ?? root).insertAdjacentHTML("beforeend", slots.default);
+}
+/** 返回当前安装的 glass-easel 能力探针，供宿主决定是否启用实验后端。 */
+function getGlassEaselRuntimeInfo() {
+	return {
+		version: "1.2.0",
+		hasDomBackend: typeof glassEasel.CurrentWindowBackendContext === "function",
+		hasTemplateCompiler: typeof wxml === "function"
+	};
+}
+//#endregion
+export { createGlassEaselComponentDefinition, createGlassEaselWebAdapter, getGlassEaselRuntimeInfo };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@weapp-vite/glass-easel-web-adapter",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Experimental glass-easel component backend for weapp-vite Web runtime",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "glass-easel": "^1.2.0",
+    "glass-easel-miniprogram-adapter": "^1.2.0"
+  },
+  "dependencies": {
+    "glass-easel-template-compiler": "1.2.0"
+  },
+  "devDependencies": {
+    "playwright": "1.63.0",
+    "tsd": "0.33.0",
+    "tsdown": "0.23.0",
+    "tsx": "4.23.13",
+    "typescript": "^6.0.3",
+    "vite": "8.3.0",
+    "vitest": "~5.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:browser": "pnpm build && tsx test/browser.e2e.ts",
+    "typecheck": "tsc --noEmit",
+    "test:types": "pnpm build && tsd --typings dist/index.d.mts --files test-d/public-api.test-d.ts"
+  }
+}