snapshot of https://github.com/dream-num/univer.git (dev, 2026-09-16; blobs > 131072B omitted)

packages/ui-adapter-web-component/README.md

@@ -0,0 +1,49 @@
+# @univerjs/ui-adapter-web-component
+
+[![npm version](https://img.shields.io/npm/v/@univerjs/ui-adapter-web-component?style=flat-square)](https://npmjs.com/package/@univerjs/ui-adapter-web-component)
+[![license](https://img.shields.io/npm/l/@univerjs/ui-adapter-web-component?style=flat-square)](https://npmjs.com/package/@univerjs/ui-adapter-web-component)
+[![downloads](https://img.shields.io/npm/dm/@univerjs/ui-adapter-web-component?style=flat-square)](https://npmjs.com/package/@univerjs/ui-adapter-web-component)
+
+`@univerjs/ui-adapter-web-component` adapts Univer UI services for Web Component integrations.
+
+## Package Overview
+
+| Package | UMD global | CSS | Locales | Facade entry |
+| --- | --- | :---: | :---: | :---: |
+| `@univerjs/ui-adapter-web-component` | `UniverUiAdapterWebComponent` | No | No | No |
+
+## Installation
+
+```sh
+pnpm add @univerjs/ui-adapter-web-component
+# or
+npm install @univerjs/ui-adapter-web-component
+```
+
+Keep all `@univerjs/*` packages on the same version.
+
+## Usage
+
+```ts
+import { UniverWebComponentAdapterPlugin } from '@univerjs/ui-adapter-web-component';
+
+univer.registerPlugin(UniverWebComponentAdapterPlugin);
+```
+
+Register custom elements with the `web-component` framework option. Runtime props are assigned to the created element as DOM properties, which supports object values such as `data` and `extraProps`.
+
+```ts
+class MyPopup extends HTMLElement {
+    set data(value: { label?: string } | undefined) {
+        this.textContent = value?.label ?? '';
+    }
+}
+
+univerAPI.registerComponent('my-popup', MyPopup, { framework: 'web-component' });
+```
+
+## Resources
+
+- [Documentation](https://docs.univer.ai)
+- [NPM package](https://npmjs.com/package/@univerjs/ui-adapter-web-component)
+- [GitHub repository](https://github.com/dream-num/univer)

packages/ui-adapter-web-component/package.json

@@ -0,0 +1,75 @@
+{
+    "name": "@univerjs/ui-adapter-web-component",
+    "version": "1.0.0-rc.0",
+    "private": false,
+    "description": "Web Component adapter for Univer UI services.",
+    "author": "DreamNum Co., Ltd. <developer@univer.ai>",
+    "license": "Apache-2.0",
+    "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/univer"
+    },
+    "homepage": "https://univer.ai",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/dream-num/univer"
+    },
+    "bugs": {
+        "url": "https://github.com/dream-num/univer/issues"
+    },
+    "keywords": [
+        "univer",
+        "ui",
+        "web-components",
+        "adapter",
+        "plugin"
+    ],
+    "exports": {
+        ".": "./src/index.ts",
+        "./*": "./src/*"
+    },
+    "main": "./src/index.ts",
+    "types": "./lib/types/index.d.ts",
+    "publishConfig": {
+        "access": "public",
+        "main": "./lib/es/index.js",
+        "module": "./lib/es/index.js",
+        "exports": {
+            ".": {
+                "import": "./lib/es/index.js",
+                "require": "./lib/cjs/index.js",
+                "types": "./lib/types/index.d.ts"
+            },
+            "./*": {
+                "import": "./lib/es/*",
+                "require": "./lib/cjs/*",
+                "types": "./lib/types/index.d.ts"
+            },
+            "./lib/*": "./lib/*"
+        }
+    },
+    "directories": {
+        "lib": "lib"
+    },
+    "files": [
+        "lib"
+    ],
+    "scripts": {
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "coverage": "vitest run --coverage",
+        "typecheck": "tsc --noEmit",
+        "build:bundle": "univer-cli build",
+        "build:types": "tsc -p tsconfig.node.json",
+        "build": "pnpm run build:bundle && pnpm run build:types"
+    },
+    "dependencies": {
+        "@univerjs/core": "workspace:*",
+        "@univerjs/ui": "workspace:*"
+    },
+    "devDependencies": {
+        "@univerjs-infra/shared": "workspace:*",
+        "typescript": "^6.0.3",
+        "vitest": "^5.0.0"
+    }
+}

packages/ui-adapter-web-component/src/config/config.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const UI_ADAPTER_WEB_COMPONENT_PLUGIN_CONFIG_KEY = 'ui-adapter-web-component.config';
+
+export const configSymbol = Symbol(UI_ADAPTER_WEB_COMPONENT_PLUGIN_CONFIG_KEY);
+
+export interface IUniverWebComponentAdapterConfig {}
+
+export const defaultPluginConfig: IUniverWebComponentAdapterConfig = {};

packages/ui-adapter-web-component/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { UI_ADAPTER_WEB_COMPONENT_PLUGIN_CONFIG_KEY } from './config/config';
+export type { IUniverWebComponentAdapterConfig } from './config/config';
+export { UniverWebComponentAdapterPlugin } from './plugin';

packages/ui-adapter-web-component/src/plugin.ts

@@ -0,0 +1,105 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { IComponent } from '@univerjs/ui';
+import type { IUniverWebComponentAdapterConfig } from './config/config';
+import { IConfigService, Inject, Injector, merge, Plugin } from '@univerjs/core';
+import { ComponentManager } from '@univerjs/ui';
+import pkg from '../package.json';
+import { defaultPluginConfig, UI_ADAPTER_WEB_COMPONENT_PLUGIN_CONFIG_KEY } from './config/config';
+
+/**
+ * The plugin that allows Univer to use web components as UI components.
+ */
+
+export class UniverWebComponentAdapterPlugin extends Plugin {
+    static override pluginName = 'UNIVER_UI_ADAPTER_WEB_COMPONENT_PLUGIN';
+    static override packageName = pkg.name;
+    static override version = pkg.version;
+
+    constructor(
+        private readonly _config: Partial<IUniverWebComponentAdapterConfig> = defaultPluginConfig,
+        @Inject(Injector) protected readonly _injector: Injector,
+        @IConfigService private readonly _configService: IConfigService,
+        @Inject(ComponentManager) protected readonly _componentManager: ComponentManager
+    ) {
+        super();
+
+        const { ...rest } = merge(
+            {},
+            defaultPluginConfig,
+            this._config
+        );
+        this._configService.setConfig(UI_ADAPTER_WEB_COMPONENT_PLUGIN_CONFIG_KEY, rest);
+    }
+
+    override onStarting(): void {
+        const { createElement, useEffect, useRef } = this._componentManager.reactUtils;
+
+        this._componentManager.setHandler('web-component', (component: IComponent['component'], name?: string) => {
+            return (props: Record<string, unknown>) => createElement(WebComponentComponentWrapper, {
+                component,
+                props: {
+                    name,
+                    componentProps: props,
+                },
+                reactUtils: { createElement, useEffect, useRef },
+            });
+        });
+    }
+}
+
+export function WebComponentComponentWrapper(options: {
+    component: CustomElementConstructor;
+    props?: {
+        name?: string;
+        componentProps?: Record<string, unknown>;
+    };
+    reactUtils: typeof ComponentManager.prototype.reactUtils;
+}) {
+    const { component, props, reactUtils } = options;
+    const { name, componentProps = {} } = props ?? {};
+    const { createElement, useEffect, useRef } = reactUtils;
+
+    if (!name) {
+        throw new Error('WebComponentComponentWrapper requires a name prop to define the custom element.');
+    }
+
+    if (!customElements.get(name)) {
+        customElements.define(name, component);
+    }
+
+    const domRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        if (!domRef.current) return;
+
+        const webComponent = document.createElement(name) as HTMLElement;
+        const webComponentWithProps = webComponent as HTMLElement & Record<string, unknown>;
+        Object.entries(componentProps).forEach(([key, value]) => {
+            if (key !== 'key') {
+                webComponentWithProps[key] = value;
+            }
+        });
+        domRef.current.appendChild(webComponent);
+
+        return () => {
+            domRef.current?.removeChild(webComponent);
+        };
+    }, [componentProps]);
+
+    return createElement('div', { ref: domRef });
+}

packages/ui-adapter-web-component/tsconfig.json

@@ -0,0 +1,8 @@
+{
+    "extends": "@univerjs-infra/shared/tsconfigs/base",
+    "compilerOptions": {
+        "rootDir": "src",
+        "outDir": "lib/types"
+    },
+    "include": ["src"]
+}

packages/ui-adapter-web-component/tsconfig.node.json

@@ -0,0 +1,18 @@
+{
+    "extends": "@univerjs-infra/shared/tsconfigs/node",
+    "compilerOptions": {
+        "rootDir": "src",
+        "declaration": true,
+        "emitDeclarationOnly": true,
+        "noEmit": false,
+        "outDir": "lib/types"
+    },
+    "include": [
+        "src"
+    ],
+    "exclude": [
+        "src/**/__tests__/**",
+        "src/**/*.spec.ts",
+        "src/**/*.test.ts"
+    ]
+}

packages/ui-adapter-web-component/vitest.config.ts

@@ -0,0 +1,3 @@
+import createConfig from '@univerjs-infra/shared/vitest';
+
+export default createConfig();