Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

feat(ui): add generic unit presence adapters (#7431)

Univere47c8faf3048
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 8a9a37aa94..5d15c01e79 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -118,6 +118,16 @@ export { BuiltInUIPart, IUIPartsService, UIPartsService } from './services/parts
export { IPlatformService, PlatformService } from './services/platform/platform.service';
export { CanvasPopupService, ICanvasPopupService } from './services/popup/canvas-popup.service';
export type { IPopup, IPopupWithExtraProps } from './services/popup/canvas-popup.service';
+export type {
+ ILocalUnitPresenceState,
+ IRemoteUnitPresenceState,
+ IUnitPresencePoint,
+ IUnitPresenceUIAdapter,
+} from './services/presence/unit-presence-ui-adapter.service';
+export {
+ IUnitPresenceUIAdapterRegistry,
+ UnitPresenceUIAdapterRegistry,
+} from './services/presence/unit-presence-ui-adapter.service';
export { IRibbonOverrideService, RibbonOverrideService } from './services/ribbon/ribbon-override.service';
export type { IRibbonOverride } from './services/ribbon/ribbon-override.service';
export { DesktopRibbonService, IRibbonService } from './services/ribbon/ribbon.service';
diff --git a/packages/ui/src/plugin.ts b/packages/ui/src/plugin.ts
index e680a4c652..2c99c19693 100644
--- a/packages/ui/src/plugin.ts
+++ b/packages/ui/src/plugin.ts
@@ -66,6 +66,10 @@ import { INotificationService } from './services/notification/notification.servi
import { IUIPartsService, UIPartsService } from './services/parts/parts.service';
import { IPlatformService, PlatformService } from './services/platform/platform.service';
import { CanvasPopupService, ICanvasPopupService } from './services/popup/canvas-popup.service';
+import {
+ IUnitPresenceUIAdapterRegistry,
+ UnitPresenceUIAdapterRegistry,
+} from './services/presence/unit-presence-ui-adapter.service';
import { IRibbonOverrideService, RibbonOverrideService } from './services/ribbon/ribbon-override.service';
import { DesktopRibbonService, IRibbonService } from './services/ribbon/ribbon.service';
import { IUIRuntimeScopeService, UIRuntimeScopeService } from './services/runtime-scope/ui-runtime-scope.service';
@@ -128,6 +132,7 @@ export class UniverUIPlugin extends Plugin {
[IRibbonOverrideService, { useClass: RibbonOverrideService }],
[IShortcutService, { useClass: ShortcutService }],
[IPlatformService, { useClass: PlatformService }],
+ [IUnitPresenceUIAdapterRegistry, { useClass: UnitPresenceUIAdapterRegistry }],
[IMenuManagerService, { useClass: MenuManagerService }],
[IContextMenuHostService, { useClass: ContextMenuHostService }],
[IContextMenuService, { useClass: ContextMenuService }],
diff --git a/packages/ui/src/services/presence/__tests__/unit-presence-ui-adapter.service.spec.ts b/packages/ui/src/services/presence/__tests__/unit-presence-ui-adapter.service.spec.ts
new file mode 100644
index 0000000000..813eeb21b7
--- /dev/null
+++ b/packages/ui/src/services/presence/__tests__/unit-presence-ui-adapter.service.spec.ts
@@ -0,0 +1,81 @@
+/**
+ * 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 { IUnitPresenceUIAdapter } from '../unit-presence-ui-adapter.service';
+import { Injector, UniverInstanceType } from '@univerjs/core';
+import { NEVER, of } from 'rxjs';
+import { describe, expect, it } from 'vitest';
+import {
+ IUnitPresenceUIAdapterRegistry,
+ UnitPresenceUIAdapterRegistry,
+} from '../unit-presence-ui-adapter.service';
+
+function createRegistry() {
+ const injector = new Injector();
+ injector.add([IUnitPresenceUIAdapterRegistry, { useClass: UnitPresenceUIAdapterRegistry }]);
+ return {
+ injector,
+ registry: injector.get(IUnitPresenceUIAdapterRegistry),
+ };
+}
+
+function createAdapter(unitType: UniverInstanceType): IUnitPresenceUIAdapter {
+ return {
+ unitType,
+ presenceKind: `unit-presence-${unitType}`,
+ active$: of(false),
+ localPresence$: NEVER,
+ activate: () => ({ dispose: () => undefined }),
+ isActive: () => false,
+ getLocalPresence: () => null,
+ getRemotePresences$: () => NEVER,
+ setRemotePresence: () => undefined,
+ removeRemotePresence: () => undefined,
+ clearRemotePresences: () => undefined,
+ };
+}
+
+describe('UnitPresenceUIAdapterRegistry', () => {
+ it('registers and disposes adapters while publishing immutable snapshots', () => {
+ const { injector, registry } = createRegistry();
+ const snapshots: Array<readonly IUnitPresenceUIAdapter[]> = [];
+ const subscription = registry.adapters$.subscribe((adapters) => snapshots.push(adapters));
+ const adapter = createAdapter(UniverInstanceType.UNIVER_BOARD);
+
+ const disposable = registry.register(adapter);
+
+ expect(registry.get(UniverInstanceType.UNIVER_BOARD)).toBe(adapter);
+ expect(registry.getAll()).toEqual([adapter]);
+ expect(Object.isFrozen(registry.getAll())).toBe(true);
+
+ disposable.dispose();
+
+ expect(registry.get(UniverInstanceType.UNIVER_BOARD)).toBeNull();
+ expect(registry.getAll()).toEqual([]);
+ expect(snapshots).toHaveLength(3);
+ subscription.unsubscribe();
+ injector.dispose();
+ });
+
+ it('rejects duplicate host registrations', () => {
+ const { injector, registry } = createRegistry();
+ registry.register(createAdapter(UniverInstanceType.UNIVER_SLIDE));
+
+ expect(() => registry.register(createAdapter(UniverInstanceType.UNIVER_SLIDE)))
+ .toThrow('A unit presence adapter is already registered');
+ injector.dispose();
+ });
+});
diff --git a/packages/ui/src/services/presence/unit-presence-ui-adapter.service.ts b/packages/ui/src/services/presence/unit-presence-ui-adapter.service.ts
new file mode 100644
index 0000000000..6b7ffbe921
--- /dev/null
+++ b/packages/ui/src/services/presence/unit-presence-ui-adapter.service.ts
@@ -0,0 +1,111 @@
+/**
+ * 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 { IDisposable, UniverInstanceType } from '@univerjs/core';
+import type { Observable } from 'rxjs';
+import { createIdentifier, Disposable, toDisposable } from '@univerjs/core';
+import { BehaviorSubject } from 'rxjs';
+
+export interface IUnitPresencePoint {
+ x: number;
+ y: number;
+}
+
+export interface ILocalUnitPresenceState {
+ unitId: string;
+ subUnitId: string;
+ selectedIds: readonly string[];
+ focusedId: string | null;
+ pointer: IUnitPresencePoint | null;
+ shareInterval: number;
+}
+
+export interface IRemoteUnitPresenceState extends Omit<ILocalUnitPresenceState, 'shareInterval'> {
+ memberId: string;
+ color: string;
+ name: string;
+}
+
+export interface IUnitPresenceUIAdapter {
+ readonly unitType: UniverInstanceType;
+ readonly presenceKind: string;
+ readonly active$: Observable<boolean>;
+ readonly localPresence$: Observable<ILocalUnitPresenceState>;
+ activate(): IDisposable;
+ isActive(): boolean;
+ getLocalPresence(unitId: string): ILocalUnitPresenceState | null;
+ getRemotePresences$(unitId: string): Observable<ReadonlyMap<string, IRemoteUnitPresenceState>>;
+ setRemotePresence(state: IRemoteUnitPresenceState): void;
+ removeRemotePresence(unitId: string, memberId: string): void;
+ clearRemotePresences(unitId: string): void;
+ readonly statusUIPart?: string;
+}
+
+export interface IUnitPresenceUIAdapterRegistry {
+ readonly adapters$: Observable<readonly IUnitPresenceUIAdapter[]>;
+ register(adapter: IUnitPresenceUIAdapter): IDisposable;
+ get(unitType: UniverInstanceType): IUnitPresenceUIAdapter | null;
+ getAll(): readonly IUnitPresenceUIAdapter[];
+}
+
+export const IUnitPresenceUIAdapterRegistry = createIdentifier<IUnitPresenceUIAdapterRegistry>(
+ 'ui.unit-presence-adapter-registry'
+);
+
+const EMPTY_ADAPTERS: readonly IUnitPresenceUIAdapter[] = Object.freeze([]);
+
+export class UnitPresenceUIAdapterRegistry extends Disposable implements IUnitPresenceUIAdapterRegistry {
+ private readonly _adapters = new Map<UniverInstanceType, IUnitPresenceUIAdapter>();
+ private readonly _adapters$ = new BehaviorSubject<readonly IUnitPresenceUIAdapter[]>(EMPTY_ADAPTERS);
+
+ readonly adapters$ = this._adapters$.asObservable();
+
+ override dispose(): void {
+ this._adapters.clear();
+ this._adapters$.complete();
+ super.dispose();
+ }
+
+ register(adapter: IUnitPresenceUIAdapter): IDisposable {
+ if (this._adapters.has(adapter.unitType)) {
+ throw new Error(`A unit presence adapter is already registered for UniverInstanceType "${adapter.unitType}".`);
+ }
+
+ this._adapters.set(adapter.unitType, adapter);
+ this._emitAdapters();
+
+ return toDisposable(() => {
+ if (this._adapters.get(adapter.unitType) !== adapter) {
+ return;
+ }
+
+ this._adapters.delete(adapter.unitType);
+ this._emitAdapters();
+ });
+ }
+
+ get(unitType: UniverInstanceType): IUnitPresenceUIAdapter | null {
+ return this._adapters.get(unitType) ?? null;
+ }
+
+ getAll(): readonly IUnitPresenceUIAdapter[] {
+ return this._adapters$.getValue();
+ }
+
+ private _emitAdapters(): void {
+ this._adapters$.next(Object.freeze(Array.from(this._adapters.values())));
+ }
+}