feat: add api for ui and f-enum (#4406)

packages/core/src/facade/f-enum.ts

@@ -35,12 +35,31 @@ export class FEnum extends FBase {
         return instance;
     }
 
-    readonly UniverInstanceType = UniverInstanceType;
-    readonly LifecycleStages = LifecycleStages;
-
-    readonly DataValidationType = DataValidationType;
-    readonly DataValidationErrorStyle = DataValidationErrorStyle;
-    readonly DataValidationRenderMode = DataValidationRenderMode;
-    readonly DataValidationOperator = DataValidationOperator;
-    readonly DataValidationStatus = DataValidationStatus;
+    get UniverInstanceType() {
+        return UniverInstanceType;
+    }
+
+    get LifecycleStages() {
+        return LifecycleStages;
+    }
+
+    get DataValidationType() {
+        return DataValidationType;
+    }
+
+    get DataValidationErrorStyle() {
+        return DataValidationErrorStyle;
+    }
+
+    get DataValidationRenderMode() {
+        return DataValidationRenderMode;
+    }
+
+    get DataValidationOperator() {
+        return DataValidationOperator;
+    }
+
+    get DataValidationStatus() {
+        return DataValidationStatus;
+    }
 }

packages/core/src/facade/f-event.ts

@@ -54,8 +54,13 @@ export class FEventName extends FBase {
         return instance;
     }
 
-    UnitCreated = 'UnitCreated' as const;
-    LifeCycleChanged = 'LifeCycleChanged' as const;
+    get UnitCreated() {
+        return 'UnitCreated' as const;
+    }
+
+    get LifeCycleChanged() {
+        return 'LifeCycleChanged' as const;
+    }
 }
 
 export interface IEventParamConfig {

packages/core/src/facade/f-univer.ts

@@ -24,7 +24,7 @@ import { ICommandService } from '../services/command/command.service';
 import { IUniverInstanceService } from '../services/instance/instance.service';
 import { LifecycleService } from '../services/lifecycle/lifecycle.service';
 import { RedoCommand, UndoCommand } from '../services/undoredo/undoredo.service';
-import { toDisposable } from '../shared';
+import { ColorBuilder, toDisposable } from '../shared';
 import { Univer } from '../univer';
 import { FBaseInitialable } from './f-base';
 import { FBlob } from './f-blob';
@@ -190,6 +190,10 @@ export class FUniver extends FBaseInitialable {
         return this._injector.createInstance(FBlob);
     }
 
+    newColor(): ColorBuilder {
+        return new ColorBuilder();
+    }
+
     get Enum() {
         return FEnum.get();
     }

packages/sheets-conditional-formatting/src/facade/f-workbook.ts

@@ -18,6 +18,9 @@ import { ColorBuilder } from '@univerjs/core';
 import { FWorkbook } from '@univerjs/sheets/facade';
 
 export interface IFWorkbookConditionalFormattingMixin {
+    /**
+     * @deprecated use `univerAPI.newColor()` as instead.
+     */
     newColor(): ColorBuilder;
 }
 

packages/sheets/src/facade/f-event.ts

@@ -20,13 +20,13 @@ import type { FWorksheet } from './f-worksheet';
 import { FEventName } from '@univerjs/core';
 
 export interface IFSheetEventMixin {
-    SheetCreated: 'SheetCreated';
-    BeforeSheetCreate: 'BeforeSheetCreate';
+    get SheetCreated(): 'SheetCreated' ;
+    get BeforeSheetCreate(): 'BeforeSheetCreate';
 }
 
 export class FSheetEventName extends FEventName implements IFSheetEventMixin {
-    override readonly SheetCreated = 'SheetCreated' as const;
-    override readonly BeforeSheetCreate = 'BeforeSheetCreate' as const;
+    override get SheetCreated(): 'SheetCreated' { return 'SheetCreated' as const; }
+    override get BeforeSheetCreate(): 'BeforeSheetCreate' { return 'BeforeSheetCreate' as const; }
 }
 
 export interface IBeforeSheetCreateEventParams extends IEventBase {

packages/sheets/src/facade/f-univer.ts

@@ -29,12 +29,23 @@ export interface IFUniverSheetsMixin {
      *
      * @param {Partial<IWorkbookData>} data The snapshot of the spreadsheet.
      * @returns {FWorkbook} FWorkbook API instance.
+     * @example
+     * ```ts
+     * univerAPI.createUniverSheet({ id: 'Sheet1', name: 'Sheet1' });
+     * ```
      */
     createUniverSheet(data: Partial<IWorkbookData>): FWorkbook;
     /**
      * Get the currently focused Univer spreadsheet.
-     *
      * @returns {FWorkbook | null} The currently focused Univer spreadsheet.
+     * @example
+     * ```ts
+     * univerAPI.getActiveUniverSheet();
+     * ```
+     */
+    getActiveUniverSheet(): FWorkbook | null;
+    /**
+     * @deprecated use `getActiveUniverSheet` as instead.
      */
     getActiveWorkbook(): FWorkbook | null;
     /**
@@ -46,19 +57,23 @@ export interface IFUniverSheetsMixin {
     getUniverSheet(id: string): FWorkbook | null;
     /**
      * Get the PermissionInstance.
-     * @deprecated This function is deprecated and will be removed in version 0.6.0.
-     *             Please use the function with the same name on the `FWorkbook` instance instead.
-     * @returns {FPermission} - The PermissionInstance.
+     * @deprecated This function is deprecated and will be removed in version 0.6.0. Please use the function with the same name on the `FWorkbook` instance instead.
      */
     getPermission(): FPermission;
+
     /**
-     * Register a callback that will be triggered when a Univer Sheet is created.
+     * @deprecated Use `univerAPI.addEvent(univerAPI.Event.UnitCreated, () => {})`
      */
     onUniverSheetCreated(callback: (workbook: FWorkbook) => void): IDisposable;
 
     /**
      * Create a new defined name builder.
      * @returns {FDefinedNameBuilder} - The defined name builder.
+     *
+     * @example
+     * ```ts
+     * univerAPI.newDefinedName();
+     * ```
      */
     newDefinedName(): FDefinedNameBuilder;
 }
@@ -136,7 +151,7 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
         return this._injector.createInstance(FWorkbook, workbook);
     };
 
-    override getActiveWorkbook(): FWorkbook | null {
+    override getActiveUniverSheet(): FWorkbook | null {
         const workbook = this._univerInstanceService.getCurrentUnitForType<Workbook>(UniverInstanceType.UNIVER_SHEET);
         if (!workbook) {
             return null;
@@ -145,6 +160,10 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
         return this._injector.createInstance(FWorkbook, workbook);
     }
 
+    override getActiveWorkbook(): FWorkbook | null {
+        return this.getActiveUniverSheet();
+    }
+
     override getUniverSheet(id: string): FWorkbook | null {
         const workbook = this._univerInstanceService.getUnit<Workbook>(id, UniverInstanceType.UNIVER_SHEET);
         if (!workbook) {

packages/ui/src/facade/f-enum.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2023-present DreamNum Inc.
+ *
+ * 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 { FEnum } from '@univerjs/core';
+import { BuiltInUIPart } from '@univerjs/ui';
+
+interface IFUIEnumMixin {
+    get BuiltInUIPart(): typeof BuiltInUIPart;
+}
+
+export class FUIEnum extends FEnum implements IFUIEnumMixin {
+    override get BuiltInUIPart(): typeof BuiltInUIPart {
+        return BuiltInUIPart;
+    };
+}
+
+FEnum.extend(FUIEnum);
+
+declare module '@univerjs/core' {
+    // eslint-disable-next-line ts/naming-convention
+    interface FEnum extends IFUIEnumMixin {}
+}

packages/ui/src/facade/f-univer.ts

@@ -16,10 +16,10 @@
 
 import type { IDisposable } from '@univerjs/core';
 import type { IMessageProps } from '@univerjs/design';
-import type { IDialogPartMethodOptions, ISidebarMethodOptions } from '@univerjs/ui';
+import type { BuiltInUIPart, IDialogPartMethodOptions, ISidebarMethodOptions } from '@univerjs/ui';
 import type { IFacadeMenuItem, IFacadeSubmenuItem } from './f-menu-builder';
 import { FUniver } from '@univerjs/core';
-import { ComponentManager, CopyCommand, IDialogService, IMessageService, ISidebarService, PasteCommand } from '@univerjs/ui';
+import { ComponentManager, CopyCommand, IDialogService, IMessageService, ISidebarService, IUIPartsService, PasteCommand } from '@univerjs/ui';
 import { FMenu, FSubmenu } from './f-menu-builder';
 import { FShortcut } from './f-shortcut';
 
@@ -113,6 +113,29 @@ export interface IFUniverUIMixin {
      * ```
      */
     showMessage(options: IMessageProps): void;
+
+    /**
+     * Set the visibility of a built-in UI part.
+     * @param key the built-in UI part
+     * @param visible the visibility
+     * @returns the {@link FUniver} object
+     * example
+     * ```ts
+     * univerAPI.setUIVisible(BuiltInUIPart.HEADER, false);
+     * ```
+     */
+    setUIVisible(key: BuiltInUIPart, visible: boolean): FUniver;
+
+    /**
+     * Get the visibility of a built-in UI part.
+     * @param key the built-in UI part
+     * @returns the visibility
+     * example
+     * ```ts
+     * univerAPI.isUIVisible(BuiltInUIPart.HEADER);
+     * ```
+     */
+    isUIVisible(key: BuiltInUIPart): boolean;
 }
 
 export class FUniverUIMixin extends FUniver implements IFUniverUIMixin {
@@ -164,9 +187,21 @@ export class FUniverUIMixin extends FUniver implements IFUniverUIMixin {
         return this._injector.get(ComponentManager);
     }
 
-    override showMessage(options: IMessageProps): void {
+    override showMessage(options: IMessageProps): FUniver {
         const messageService = this._injector.get(IMessageService);
         messageService.show(options);
+        return this;
+    }
+
+    override setUIVisible(ui: BuiltInUIPart, visible: boolean): FUniver {
+        const uiPartService = this._injector.get(IUIPartsService);
+        uiPartService.setUIVisible(ui, visible);
+        return this;
+    }
+
+    override isUIVisible(ui: BuiltInUIPart): boolean {
+        const uiPartService = this._injector.get(IUIPartsService);
+        return uiPartService.isUIVisible(ui);
     }
 }
 

packages/ui/src/facade/index.ts

@@ -17,6 +17,7 @@
 import './f-univer';
 import './f-hooks';
 import './f-menu-builder';
+import './f-enum';
 
 export type * from './f-hooks';
 export type * from './f-menu-builder';

packages/ui/src/services/parts/parts.service.ts

@@ -19,7 +19,7 @@ import type { ComponentType } from '../../common/component-manager';
 import { createIdentifier, Disposable, toDisposable } from '@univerjs/core';
 import { type Observable, Subject } from 'rxjs';
 
-type ComponentRenderer = () => ComponentType;
+export type ComponentRenderer = () => ComponentType;
 type ComponentPartKey = BuiltInUIPart | string;
 
 export enum BuiltInUIPart {
@@ -36,9 +36,14 @@ export enum BuiltInUIPart {
 
 export interface IUIPartsService {
     componentRegistered$: Observable<ComponentPartKey>;
+    uiVisibleChange$: Observable<{ ui: ComponentPartKey; visible: boolean }>;
 
     registerComponent(part: ComponentPartKey, componentFactory: () => ComponentType): IDisposable;
     getComponents(part: ComponentPartKey): Set<ComponentRenderer>;
+
+    setUIVisible(part: ComponentPartKey, visible: boolean): void;
+
+    isUIVisible(part: ComponentPartKey): boolean;
 }
 
 export const IUIPartsService = createIdentifier<IUIPartsService>('ui.parts.service');
@@ -48,13 +53,25 @@ export class UIPartsService extends Disposable implements IUIPartsService {
 
     private readonly _componentRegistered$ = new Subject<ComponentPartKey>();
     readonly componentRegistered$ = this._componentRegistered$.asObservable();
+    private readonly _uiVisible = new Map<ComponentPartKey, boolean>();
+    private readonly _uiVisibleChange$ = new Subject<{ ui: ComponentPartKey; visible: boolean }>();
+    readonly uiVisibleChange$ = this._uiVisibleChange$.asObservable();
 
     override dispose(): void {
         super.dispose();
 
         this._componentRegistered$.complete();
     }
 
+    setUIVisible(part: ComponentPartKey, visible: boolean): void {
+        this._uiVisible.set(part, visible);
+        this._uiVisibleChange$.next({ ui: part, visible });
+    }
+
+    isUIVisible(part: ComponentPartKey): boolean {
+        return this._uiVisible.get(part) ?? true;
+    }
+
     registerComponent(part: ComponentPartKey, componentFactory: () => React.ComponentType): IDisposable {
         const componentType = componentFactory();
         const components = (

packages/ui/src/views/components/ComponentContainer.tsx

@@ -14,11 +14,12 @@
  * limitations under the License.
  */
 
-import { useDependency } from '@univerjs/core';
+import type { Injector } from '@univerjs/core';
 import type { ComponentType } from 'react';
+import type { ComponentRenderer } from '../../services/parts/parts.service';
+import { useDependency } from '@univerjs/core';
 import React, { useMemo, useRef } from 'react';
 import { debounceTime, filter, map, startWith } from 'rxjs';
-import type { Injector } from '@univerjs/core';
 import { useObservable } from '../../components/hooks/observable';
 import { IUIPartsService } from '../../services/parts/parts.service';
 
@@ -44,8 +45,11 @@ export function ComponentContainer(props: IComponentContainerProps) {
  * @param injector The injector to get the service. It is optional. However, you should not change this prop in a given
  * component.
  */
-export function useComponentsOfPart(part: string, injector?: Injector) {
+// eslint-disable-next-line react-refresh/only-export-components
+export function useComponentsOfPart(part: string, injector?: Injector): Set<ComponentRenderer> {
     const uiPartsService = injector?.get(IUIPartsService) ?? useDependency(IUIPartsService);
+    const uiVisibleChange$ = useMemo(() => uiPartsService.uiVisibleChange$.pipe(filter((ui) => ui.ui === part)), [part, uiPartsService]);
+    useObservable(uiVisibleChange$);
 
     const updateCounterRef = useRef<number>(0);
     const componentPartUpdateCount = useObservable(
@@ -61,5 +65,5 @@ export function useComponentsOfPart(part: string, injector?: Injector) {
     );
 
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    return useMemo(() => uiPartsService.getComponents(part), [componentPartUpdateCount]);
+    return useMemo(() => uiPartsService.isUIVisible(part) ? uiPartsService.getComponents(part) : new Set(), [componentPartUpdateCount]);
 }