@univerjs-pro/embed-ui 1.0.0-alpha.3

package/lib/types/services/embed-runtime-host-lease.service.d.ts

@@ -0,0 +1,24 @@
+import type { IEmbedDescriptor } from '@univerjs-pro/embed';
+import type { IDisposable } from '@univerjs/core';
+import type { IEmbedMountSession } from '../types/embed-ui';
+import { EmbedMountService } from './embed-mount.service';
+export interface IEmbedRuntimeHostLease extends IDisposable {
+    readonly session: IEmbedMountSession;
+    readonly ownsSession: boolean;
+}
+/**
+ * Temporarily lends a single Embed runtime to another DOM host without creating
+ * a duplicate child session. This is a host-lifecycle bridge, not a global
+ * interaction policy; consumers remain responsible for their local input rules.
+ *
+ * If passive runtime hosting becomes common outside presentation, promote the
+ * capability into EmbedMountService instead of adding more DOM relocation paths.
+ */
+export declare class EmbedRuntimeHostLeaseService {
+    private readonly _mountService;
+    private readonly _leases;
+    constructor(_mountService: EmbedMountService);
+    acquire(descriptor: IEmbedDescriptor, targetHost: HTMLElement): IEmbedRuntimeHostLease;
+    private _relocateExistingSession;
+    private _mountOwnedSession;
+}

package/lib/types/services/embed-runtime-policy.service.d.ts

@@ -0,0 +1,28 @@
+import type { IEmbedDescriptor } from '@univerjs-pro/embed';
+import type { IDisposable } from '@univerjs/core';
+export interface IEmbedRuntimeAncestor {
+    hostUnitId: string;
+    embedId: string;
+    childUnitId: string;
+}
+export interface IEmbedRuntimeMountDecision {
+    allowed: boolean;
+    reason?: 'max-depth' | 'cycle';
+    ancestry: readonly IEmbedRuntimeAncestor[];
+}
+export interface IEmbedRuntimePolicyConfig {
+    maxDepth?: number;
+}
+type EmbedRuntimeDescriptor = Pick<IEmbedDescriptor, 'hostUnitId' | 'embedId'> & {
+    childUnitId: string;
+};
+export declare class EmbedRuntimePolicyService {
+    private readonly _childUnitAncestry;
+    private readonly _maxDepth;
+    constructor(config?: IEmbedRuntimePolicyConfig);
+    canMount(descriptor: EmbedRuntimeDescriptor): IEmbedRuntimeMountDecision;
+    registerMountedRuntime(descriptor: EmbedRuntimeDescriptor): IDisposable;
+    getAncestryForHostUnit(hostUnitId: string): readonly IEmbedRuntimeAncestor[];
+    getParentEmbedId(hostUnitId: string): string | undefined;
+}
+export {};

package/lib/types/services/embed-runtime-scope-dom.d.ts

@@ -0,0 +1,15 @@
+import type { UniverInstanceType } from '@univerjs/core';
+export declare const EMBED_FLOAT_DOM_ATTRIBUTE = "data-embed-float-dom";
+export declare const EMBED_ID_ATTRIBUTE = "data-embed-id";
+export declare const EMBED_HOST_UNIT_ID_ATTRIBUTE = "data-embed-host-unit-id";
+export declare const EMBED_CHILD_UNIT_ID_ATTRIBUTE = "data-embed-child-unit-id";
+export declare const EMBED_CHILD_TYPE_ATTRIBUTE = "data-embed-child-type";
+export interface IEmbedRuntimeDomScope {
+    embedId: string;
+    hostUnitId?: string;
+    childUnitId?: string;
+    childType?: UniverInstanceType;
+}
+export declare function resolveEmbedRuntimeDomScope(element: HTMLElement | null | undefined): IEmbedRuntimeDomScope | undefined;
+export declare function resolveActiveEmbedRuntimeDomScope(ownerDocument?: Document): IEmbedRuntimeDomScope | undefined;
+export declare function resolveEmbedFloatDomContainer(element: HTMLElement | null | undefined, embedId?: string): HTMLElement | undefined;

package/lib/types/services/embed-scene-canvas-capture.service.d.ts

@@ -0,0 +1,24 @@
+import type { IDisposable, UniverInstanceType } from '@univerjs/core';
+import type { IEmbedChildContainerContext } from '../types/embed-ui';
+export type EmbedSceneCanvasCaptureResult = string | HTMLCanvasElement | ImageBitmap;
+export interface IEmbedSceneCanvasCaptureProvider {
+    childType: UniverInstanceType;
+    capture(context: IEmbedChildContainerContext): Promise<EmbedSceneCanvasCaptureResult | null | undefined> | EmbedSceneCanvasCaptureResult | null | undefined;
+}
+export declare class EmbedSceneCanvasCaptureService {
+    private readonly _providers;
+    private readonly _contextsByEmbedId;
+    private readonly _contextsByHostAnchorId;
+    private readonly _contextsByChildUnitId;
+    register(provider: IEmbedSceneCanvasCaptureProvider): IDisposable;
+    get(childType: UniverInstanceType): IEmbedSceneCanvasCaptureProvider | undefined;
+    registerContext(context: IEmbedChildContainerContext): IDisposable;
+    getContextByEmbedId(embedId: string): IEmbedChildContainerContext | undefined;
+    getContextByHostAnchorId(hostAnchorId: string): IEmbedChildContainerContext | undefined;
+    getContextByChildUnitId(childUnitId: string): IEmbedChildContainerContext | undefined;
+    capture(context: IEmbedChildContainerContext): Promise<EmbedSceneCanvasCaptureResult | null | undefined>;
+    captureByEmbedId(embedId: string): Promise<EmbedSceneCanvasCaptureResult | null | undefined>;
+    captureByHostAnchorId(hostAnchorId: string): Promise<EmbedSceneCanvasCaptureResult | null | undefined>;
+    captureByChildUnitId(childUnitId: string): Promise<EmbedSceneCanvasCaptureResult | null | undefined>;
+}
+export declare function captureEmbedContextSceneCanvas(context: IEmbedChildContainerContext): string | undefined;

package/lib/types/services/embed-scene-passive-wheel.d.ts

@@ -0,0 +1,21 @@
+import type { IEmbedPassiveViewportWheelContext } from '../types/embed-ui';
+export declare function normalizePassiveWheelDelta(event: WheelEvent, scaleX?: number, scaleY?: number): {
+    offsetX: number;
+    offsetY: number;
+};
+export declare function scrollSceneViewportPassive(context: IEmbedPassiveViewportWheelContext, viewport: {
+    viewportScrollX?: number;
+    viewportScrollY?: number;
+    scrollToViewportPos?: (position: Partial<{
+        viewportScrollX: number;
+        viewportScrollY: number;
+    }>) => unknown;
+    scrollByViewportDeltaVal?: (delta: {
+        viewportScrollX: number;
+        viewportScrollY: number;
+    }) => unknown;
+} | null | undefined, scene?: {
+    scaleX?: number;
+    scaleY?: number;
+    makeDirty?: (force?: boolean) => void;
+}): boolean;

package/lib/types/services/embed-ui-contribution-register.d.ts

@@ -0,0 +1,5 @@
+import type { Injector } from '@univerjs/core';
+type EmbedUIContributionRegister = (injector: Injector) => void;
+export declare function registerEmbedUIContribution(injector: Injector, key: string, register: EmbedUIContributionRegister): void;
+export declare function flushPendingEmbedUIContributions(injector: Injector): void;
+export {};

package/lib/types/services/embed-undo-bridge.service.d.ts

@@ -0,0 +1,14 @@
+import type { IUndoRedoItem } from '@univerjs/core';
+import { EmbedFocusOwnerService } from '@univerjs-pro/embed';
+import { IUndoRedoService } from '@univerjs/core';
+export interface IEmbedUndoBridgeResult {
+    stackUnitId: string;
+    routedToHost: boolean;
+}
+export declare class EmbedUndoBridgeService {
+    private readonly _focusOwnerService;
+    private readonly _undoRedoService;
+    constructor(_focusOwnerService: EmbedFocusOwnerService, _undoRedoService: IUndoRedoService);
+    pushUndoRedoForChild(item: IUndoRedoItem): IEmbedUndoBridgeResult;
+    resolveStackUnitId(childUnitId: string): string;
+}

package/lib/types/services/react-root-disposal.d.ts

@@ -0,0 +1,6 @@
+import type { ReactElement } from 'react';
+export interface IEmbedReactRoot {
+    render: (node: ReactElement) => void;
+}
+export declare function createEmbedReactRoot(container: Element): IEmbedReactRoot;
+export declare function disposeEmbedReactRoot(root: IEmbedReactRoot): void;

package/lib/types/types/embed-ui.d.ts

@@ -0,0 +1,292 @@
+import type { EmbedHostEntry, EmbedLayout, EmbedMenuBehavior, IEmbedDescriptor, IEmbedLayoutPolicies } from '@univerjs-pro/embed';
+import type { DependencyIdentifier, ICommandService, IDisposable, Injector, IUniverInstanceService, UniverInstanceType } from '@univerjs/core';
+import type { IMenuManagerService, IRibbonService } from '@univerjs/ui';
+import type { Observable } from 'rxjs';
+export interface IEmbedContainerContext {
+    descriptor: IEmbedDescriptor;
+    layout: EmbedLayout;
+    injector: Injector;
+    hostElement?: HTMLElement;
+    container?: HTMLElement;
+    hostUnitId: string;
+    embedId: string;
+    childUnitId: string;
+    childType: UniverInstanceType;
+}
+export interface IEmbedChildContainerContext extends IEmbedContainerContext {
+    hostElement: HTMLElement;
+    container: HTMLElement;
+    renderScope: IEmbedRenderScope;
+    runtimeScope: IEmbedChildRuntimeScope;
+}
+export interface IEmbedMenuOutlet {
+    container: HTMLElement;
+}
+export interface IEmbedRenderScope {
+    hostUnitId: string;
+    hostAnchorId: string;
+    embedId: string;
+    childUnitId: string;
+    childType: UniverInstanceType;
+    layout: EmbedLayout;
+    mode: 'tab' | 'float' | 'inline';
+    rootElement: HTMLElement;
+    contentRoot?: HTMLElement;
+    canvasRoot?: HTMLElement;
+    overlayRoot?: HTMLElement;
+    popupRoot?: HTMLElement;
+    menuOutlet?: IEmbedMenuOutlet;
+    active$: Observable<boolean>;
+    fullscreen?: boolean;
+}
+export interface IEmbedChildRuntimeScope {
+    descriptor: IEmbedDescriptor;
+    host: {
+        unitId: string;
+        type: UniverInstanceType;
+        anchorId: string;
+        entry: EmbedHostEntry;
+        layout: 'doc-flow' | 'float' | 'tab-peer';
+    };
+    child: {
+        unitId: string;
+        type: UniverInstanceType;
+    };
+    injector: Injector;
+    instanceService?: IUniverInstanceService;
+    commandService?: ICommandService;
+    menuManagerService?: IMenuManagerService;
+    roots: {
+        root: HTMLElement;
+        content: HTMLElement;
+        canvas?: HTMLElement;
+        overlay: HTMLElement;
+        popup: HTMLElement;
+        menuSlot?: HTMLElement;
+        footerSlot?: HTMLElement;
+    };
+    activate: () => void;
+    deactivate: () => void;
+    dispose: () => void;
+}
+export interface IEmbedHostMountResult {
+    hostElement?: HTMLElement;
+    runtimeRoots?: {
+        content?: HTMLElement;
+        canvas?: HTMLElement;
+        overlay?: HTMLElement;
+        popup?: HTMLElement;
+        menuSlot?: HTMLElement;
+        footerSlot?: HTMLElement;
+    };
+    disposable?: IDisposable;
+}
+export interface IEmbedHostContainerContribution {
+    hostType: UniverInstanceType;
+    entry: EmbedHostEntry;
+    layout: EmbedLayout;
+    supportedLayouts?: EmbedLayout[];
+    menuBehavior: EmbedMenuBehavior;
+    mount?: (context: IEmbedContainerContext) => IEmbedHostMountResult | IDisposable | void;
+}
+export interface IEmbedChildViewContribution {
+    childType: UniverInstanceType;
+    supportedLayouts: EmbedLayout[];
+    beforeDeactivate?: (context: IEmbedChildContainerContext) => void;
+    mount?: (context: IEmbedChildContainerContext) => IDisposable | void;
+}
+export interface IEmbedProductMenuContribution {
+    childType: UniverInstanceType;
+    surface?: EmbedProductMenuSurface;
+    menuSchema?: unknown;
+    id?: string;
+    order?: number;
+    scopedActionServiceTokens?: readonly DependencyIdentifier<unknown>[];
+    mountMenu?: (context: IEmbedProductMenuMountContext) => IDisposable | void;
+}
+export type EmbedProductMenuSurface = 'ribbon' | 'product-toolbar' | 'context-menu' | 'float-toolbar' | 'footer' | 'side-panel' | 'floating-menu';
+export interface IEmbedProductMenuMountContext {
+    container: HTMLElement;
+    portalContainer?: HTMLElement | null;
+    childType: UniverInstanceType;
+    surface?: EmbedProductMenuSurface;
+    childUnitId?: string;
+    embedId?: string;
+    injector: unknown;
+    menuSchema: unknown;
+    menuTitlePrefix?: string;
+    activeRibbonTab?: string;
+    headerMenu?: boolean;
+    toolbarOnly?: boolean;
+    ribbonHeaderClassName?: string;
+    scopedActionServiceTokens?: readonly DependencyIdentifier<unknown>[];
+}
+export interface IEmbedProductRibbonOverride {
+    mode?: EmbedHostChromeMode;
+    ribbonService: IRibbonService;
+    injector?: Pick<Injector, 'get' | 'has' | 'invoke'>;
+    portalContainer?: HTMLElement | null;
+    placeholderTitle?: string;
+    hideToolbar?: boolean;
+    disposable?: IDisposable;
+}
+export interface IEmbedProductRibbonOverrideContext {
+    childType: UniverInstanceType;
+    childUnitId?: string;
+    injector: unknown;
+    embedId: string;
+    hostUnitId: string;
+    entry: EmbedHostEntry;
+}
+export interface IEmbedBlockContribution {
+    childType: UniverInstanceType;
+    productName: string;
+    hostChromeMode?: EmbedHostChromeMode;
+    hostHeaderMode?: 'none' | 'placeholder';
+    layoutPolicy?: IEmbedLayoutPolicies;
+    createRibbonOverride?: (context: IEmbedProductRibbonOverrideContext) => IEmbedProductRibbonOverride | undefined;
+}
+export declare enum EmbedHostChromeMode {
+    RIBBON = "ribbon",
+    TITLE_ONLY = "title-only",
+    NONE = "none"
+}
+export type EmbedFloatingStage = 'inactive' | 'stage1' | 'stage2';
+export type EmbedInteractionFlow = 'floating-stage' | 'doc-block';
+export interface IEmbedFloatingActivation {
+    hostUnitId: string;
+    embedId: string;
+    childUnitId: string;
+    stage?: EmbedFloatingStage;
+}
+export interface IEmbedFloatingMenuMountContext extends IEmbedChildContainerContext {
+    active: IEmbedFloatingActivation | null;
+}
+export interface IEmbedFloatingMenuContribution {
+    hostType: UniverInstanceType;
+    entry: EmbedHostEntry;
+    childType?: UniverInstanceType;
+    mount: (context: IEmbedFloatingMenuMountContext) => IDisposable | void;
+}
+export interface IEmbedPassiveViewportWheelContext extends IEmbedChildContainerContext {
+    event: WheelEvent;
+    stage: EmbedFloatingStage;
+    source?: 'wheel' | 'host-scroll-sync';
+    viewportScrollX?: number;
+    viewportScrollY?: number;
+}
+export interface IEmbedPassiveViewportProvider {
+    childType: UniverInstanceType;
+    supportedLayouts?: EmbedLayout[];
+    handleWheel: (context: IEmbedPassiveViewportWheelContext) => boolean | void;
+}
+export interface IEmbedPassiveWheelHandlerContribution {
+    childType: UniverInstanceType;
+    order?: number;
+    supportedLayouts?: EmbedLayout[];
+    handleWheel: (context: IEmbedPassiveViewportWheelContext) => boolean | void;
+}
+export interface IEmbedContentSize {
+    height?: number;
+    width?: number;
+}
+export interface IEmbedContentSizeMeasureContext {
+    childType: UniverInstanceType;
+    childUnit?: unknown;
+    childUnitId: string;
+    viewportWidth?: number;
+}
+export interface IEmbedContentSizeProvider {
+    childType: UniverInstanceType;
+    measureContentSize: (context: IEmbedContentSizeMeasureContext) => IEmbedContentSize | undefined;
+}
+export interface IEmbedFullscreenSession {
+    hostUnitId: string;
+    embedId: string;
+    childUnitId: string;
+    childType: UniverInstanceType;
+    entry: EmbedHostEntry;
+    layout: EmbedLayout;
+}
+export interface IEmbedHostMenuOverride {
+    hostUnitId: string;
+    embedId: string;
+    childUnitId: string;
+    childType: UniverInstanceType;
+    entry: EmbedHostEntry;
+    reason: 'tab-active';
+    portalContainer?: HTMLElement | null;
+    hideHostFxBar?: boolean;
+    lockHostRibbon?: boolean;
+}
+export interface IEmbedMountSession {
+    hostUnitId: string;
+    embedId: string;
+    childUnitId: string;
+    childType: UniverInstanceType;
+    entry: EmbedHostEntry;
+    layout: EmbedLayout;
+    hostElement?: HTMLElement;
+    context?: IEmbedChildContainerContext;
+}
+export type EmbedFloatPreviewStatus = 'pending' | 'ready' | 'error' | 'stale';
+export type EmbedFloatPreviewReason = 'initial' | 'stage-exit' | 'resize' | 'content-change' | 'manual';
+export type EmbedFloatPreviewInvalidationReason = 'model-change' | 'view-state-change' | 'resize' | 'theme-change' | 'locale-change' | 'dispose';
+export type EmbedFloatPreviewRenderResult = string | HTMLCanvasElement | ImageBitmap;
+export interface IEmbedFloatPreviewEntry<TViewState = unknown> {
+    embedId: string;
+    childUnitId: string;
+    childType: UniverInstanceType;
+    status: EmbedFloatPreviewStatus;
+    image?: EmbedFloatPreviewRenderResult;
+    width: number;
+    height: number;
+    dpr: number;
+    viewState?: TViewState;
+    revision: number;
+    updatedAt: number;
+    error?: unknown;
+}
+export interface IEmbedFloatPreviewRenderRequest<TViewState = unknown> {
+    descriptor: IEmbedDescriptor;
+    childUnitId: string;
+    childType: UniverInstanceType;
+    width: number;
+    height: number;
+    dpr: number;
+    viewState?: TViewState;
+    reason: EmbedFloatPreviewReason;
+    context?: IEmbedChildContainerContext;
+}
+export interface IEmbedFloatPreviewInvalidationContext {
+    descriptor: IEmbedDescriptor;
+    childUnitId: string;
+    childType: UniverInstanceType;
+    reason: EmbedFloatPreviewInvalidationReason;
+}
+export interface IEmbedFloatPreviewProvider<TViewState = unknown> {
+    childType: UniverInstanceType;
+    collectViewState: (context: IEmbedChildContainerContext) => TViewState | Promise<TViewState>;
+    restoreViewState: (context: IEmbedChildContainerContext, state: TViewState) => void | Promise<void>;
+    renderPreview: (request: IEmbedFloatPreviewRenderRequest<TViewState>) => EmbedFloatPreviewRenderResult | null | undefined | Promise<EmbedFloatPreviewRenderResult | null | undefined>;
+    invalidateKeys?: (context: IEmbedFloatPreviewInvalidationContext) => string[];
+}
+export interface IEmbedReadonlyPreviewRoots {
+    root: HTMLElement;
+    content: HTMLElement;
+    canvas?: HTMLElement;
+}
+export interface IEmbedReadonlyPreviewContext<TViewState = unknown> extends IEmbedContainerContext {
+    roots: IEmbedReadonlyPreviewRoots;
+    viewState?: TViewState;
+    updateViewState: (viewState: TViewState) => void;
+}
+export interface IEmbedReadonlyPreviewWheelContext<TViewState = unknown> extends IEmbedReadonlyPreviewContext<TViewState> {
+    event: WheelEvent;
+}
+export interface IEmbedReadonlyPreviewProvider<TViewState = unknown> {
+    childType: UniverInstanceType;
+    supportedLayouts?: EmbedLayout[];
+    mount?: (context: IEmbedReadonlyPreviewContext<TViewState>) => IDisposable | void;
+    handleWheel?: (context: IEmbedReadonlyPreviewWheelContext<TViewState>) => boolean | void | Promise<boolean | void>;
+}