@zk-tech/base-ui-configuration-service 0.0.1-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,471 @@
+import { Disposable } from '@zk-tech/bedrock/dispose';
+import { IContainerService } from '@zk-tech/bedrock/di';
+import * as React$1 from 'react';
+import React__default, { ReactElement, FunctionComponent, Component, ErrorInfo } from 'react';
+import * as _zk_tech_bedrock_event from '@zk-tech/bedrock/event';
+import { Event } from '@zk-tech/bedrock/event';
+import { NavigateOptions, NavigateFunction } from 'react-router-dom';
+export { Navigate, NavigateOptions, matchPath, parsePath, resolvePath, useLocation, useSearchParams } from 'react-router-dom';
+import { LvErrorRef } from '@zk-tech/bedrock/error';
+
+type IUiManagerSymbol = string;
+/** 配置相关内容 */
+interface IBaseUiManager<T extends Record<string, any>> {
+    registerConfig: (configs: T[]) => void;
+    unRegisterConfig: (id: string) => void;
+    render: (...params: any) => React__default.ReactNode;
+}
+
+/**
+ * 全局配置项
+ */
+interface IBaseSetting {
+    /**
+     * workbench 命名空间(log 会进行区分)
+     */
+    namespace: string;
+    /**
+     * 是否开启调试模式，开启后将为每个 ActionPoint 打印调用信息
+     */
+    debugMode: boolean;
+    /** 控制服务的显隐规则, 默认展示。如果有特殊隐藏诉求可以传递覆盖 */
+    visible: boolean;
+}
+
+type IActionPointInfo = IUseMiddlewareOptions<any, any>['actionInfo'];
+/**
+ * @internal
+ */
+declare class ActionPointRunner<T> extends Function {
+    private readonly middlewares;
+    private readonly point;
+    private readonly _uiConfig;
+    private _rawArguments;
+    constructor(middlewares: ((...args: any[]) => any)[], point: IActionPointInfo, _uiConfig: T);
+    get isStop(): boolean;
+    private _isStop;
+    private index;
+    run(...args: unknown[]): any;
+    hasNext(): boolean;
+    private getNext;
+}
+
+/**
+ * Extract Function Type From Union Type T
+ */
+type ExtractFunction<T extends Function | any> = Extract<T, Function>;
+/**
+ * extract function property names from type T as an union type
+ */
+type FunctionPropertyNames<T> = Required<{
+    [K in keyof T]: ExtractFunction<T[K]> extends never ? never : K;
+}>[keyof T];
+type IUseMiddlewareOptions<UIManagerSymbol extends IUiManagerSymbol, MixinConfig extends Record<UIManagerSymbol, any[]>> = {
+    /**
+     * 禁止 handler 往下继续传递
+     * 如果想在中间件运行后确定返回值，则可以通过调用该函数跳过后续中间件的运行
+     */
+    stop: () => void;
+    actionInfo: {
+        /**
+         * 操作来源，通常为 Menu、Toolbar 等 UI 服务
+         */
+        from: UIManagerSymbol;
+        /**
+         * 操作对应配置名称
+         */
+        name: string;
+        /** 劫持的 action method */
+        trigger: string;
+    };
+    uiConfig: MixinConfig[UIManagerSymbol];
+    /** handler 自定义的参数内容 */
+    triggerArgs: any;
+};
+type IUseMiddlewareProps<UIManagerSymbol extends IUiManagerSymbol, MixinConfig extends Record<UIManagerSymbol, any[]>> = {
+    [T in UIManagerSymbol]: {
+        /** middleware 的规划 */
+        id: string;
+        /** 需要劫持的 UI Service */
+        trigger: T;
+        /** 需要劫持的方法 */
+        triggerMethod: FunctionPropertyNames<MixinConfig[T][number]>[];
+        handler: (options: IUseMiddlewareOptions<T, MixinConfig>) => any;
+        /**
+         * 中间件注册后需要有时机来 trigger 页面重渲.
+         * 中间件注册后会监听这个事件做 UI 的刷新渲染.
+         * */
+        freshTrigger: Event<[]>;
+    };
+}[UIManagerSymbol];
+type IBuildRunnerProps<UIManagerSymbol extends IUiManagerSymbol, MixinConfig extends Record<UIManagerSymbol, any[]>> = {
+    trigger: UIManagerSymbol;
+    method: string | number | symbol;
+    handler?: (...args: any[]) => any;
+    uiConfig: MixinConfig[UIManagerSymbol];
+};
+type IMiddlewareChange<UIManagerSymbol extends IUiManagerSymbol> = {
+    trigger: UIManagerSymbol;
+    method: string[];
+};
+interface IMiddlewareManager<UIManagerSymbol extends IUiManagerSymbol, MixinConfig extends Record<UIManagerSymbol, any[]>> {
+    onMiddlewareChange: Event<[IMiddlewareChange<UIManagerSymbol>]>;
+    buildRunner: (options: IBuildRunnerProps<UIManagerSymbol, MixinConfig>) => ActionPointRunner<MixinConfig[UIManagerSymbol]>;
+    /** 注册中间件能力 */
+    use: (props: IUseMiddlewareProps<UIManagerSymbol, MixinConfig>) => void;
+    /** 取消中间件的注册 */
+    unUse: (id: string) => void;
+}
+
+declare abstract class BaseUiConfigurationService<ISetting extends IBaseSetting, UIManagerSymbol extends IUiManagerSymbol, MixinConfig extends Record<UIManagerSymbol, any[]>, ISymbolAllManager extends Record<UIManagerSymbol, IBaseUiManager<any>>> extends Disposable {
+    private readonly _setting;
+    protected readonly _containerService: IContainerService;
+    readonly _serviceBrand: undefined;
+    get setting(): ISetting;
+    middleware: IMiddlewareManager<UIManagerSymbol, MixinConfig>;
+    abstract uiManager: ISymbolAllManager;
+    constructor(_setting: ISetting, _containerService: IContainerService);
+    abstract render(): React.ReactNode;
+    protected abstract _initAllManager(): void;
+    registerConfig(config: Partial<MixinConfig>): void;
+    useMiddleware(props: IUseMiddlewareProps<UIManagerSymbol, MixinConfig>): void;
+    protected _bootstrap(): void;
+}
+
+declare abstract class BaseSetting<T extends IBaseSetting> {
+    observableData: T;
+    constructor(options: {
+        setting: Partial<T>;
+    });
+    get namespace(): string;
+    get debugMode(): boolean;
+    get visible(): boolean;
+}
+
+type IContext<T extends BaseUiConfigurationService<any, any, any, any>> = {
+    uiConfigurationService: T;
+};
+declare const GlobalContext: React$1.Context<any>;
+
+declare abstract class BaseUiManager<TConfigSymbol extends IUiManagerSymbol, TConfig extends Record<string, any>> implements IBaseUiManager<TConfig> {
+    protected readonly _middlewareManager: IMiddlewareManager<TConfigSymbol, any>;
+    constructor(_middlewareManager: IMiddlewareManager<TConfigSymbol, any>);
+    abstract registerConfig(configs: TConfig[]): void;
+    unRegisterConfig(id: string): void;
+    abstract render(...params: any[]): React.ReactNode;
+    abstract _middlewareChange(props: IMiddlewareChange<TConfigSymbol>): void;
+    private _listenerMiddlewareChange;
+}
+
+declare class MiddlewareManager implements IMiddlewareManager<any, any> {
+    private readonly _registerById;
+    /** caller <-> middleware handler 的映射表 */
+    private readonly _registerByCaller;
+    private readonly _onMiddlewareChange;
+    private readonly _disposeMap;
+    onMiddlewareChange: Event<[IMiddlewareChange<any>]>;
+    buildRunner(options: IBuildRunnerProps<any, any>): ActionPointRunner<any>;
+    use<T>(props: IUseMiddlewareProps<any, any>): void;
+    unUse(id: string): void;
+    private _getCaller;
+}
+
+declare enum OrderLevel {
+    high = "high",
+    default = "default",
+    low = "low"
+}
+interface IOrderType {
+    /**
+     * 在 order 之上的排序规则
+     * 严格按照：high > default > low 顺序排序
+     * */
+    orderLevel?: OrderLevel;
+    /** 排序设置，默认为 0 */
+    order?: number;
+}
+/**
+ * 通用的排序函数，主要分作两类排序规则
+ * 优先使用 orderLevel 分组，后使用 order 排序
+ * 主要为了处理一些希望固定展示头部和底部的场景，而出现 order 争抢的 case
+ */
+declare function sortListBySettings<T extends IOrderType>({ list, filter, }: {
+    list: Array<T>;
+    filter?: (item: T) => T;
+}): Array<T>;
+
+/**
+ * @description 将传入的UI配置数组，通过打平整合到一个对象中
+ * @example
+ * input: [{ pageRoute: [xxx] }, {pageRoute: [xxx2]}]
+ * output: { pageRoute: [xxx, xxx2]  }
+ */
+declare const mergeUiConfigs: <T extends Record<string, Array<any>>>(configs: Array<Partial<T>>) => Partial<T>;
+
+declare function runnerBuilder({ middleware, trigger, method, handler, uiConfig, }: {
+    middleware: IMiddlewareManager<any, any>;
+    trigger: IUiManagerSymbol;
+    method: string;
+    handler?: (...args: any[]) => any;
+    uiConfig: any;
+}): ActionPointRunner<any>;
+
+/**
+ * 用于带默认值执行 config 的回调方法
+ * @param config - config 的回调
+ * @param defaultValue - 默认值
+ * @param args - 参数
+ * @internal
+ * @privateRemarks
+ * config类型改成 T | ((...params: any[]) =\> T)，ts认为不一定是callable
+ * https://github.com/microsoft/TypeScript/issues/37663
+ * 我们需要这个函数能成功的类型推断T
+ * 但是config设成any可能会产生错误，这里的类型推断只能由config产生
+ * 例如  evaluate\<TooltipConfig| string | undefined\>(tooltipConfig, undefined);
+ * 为什么写<T>是因为defaultValue是undefined
+ * 所以当T没有写，就会错误的由defaultValue推断T
+ * 还有一种可能是T写了就变成了强制类型转换，也会出错
+ * 即使改成issue里面说的方法，也没有办法限制defaultValue类型
+ */
+declare function evaluate<T>(config: any, defaultValue: T, ...args: any[]): T;
+
+interface ILayoutConfiguration {
+    hideTitleBar?: boolean;
+    hideSideMenu?: boolean;
+    hideSettingPanel?: boolean;
+    hideTopMenu?: boolean;
+    hideBottomMenu?: boolean;
+}
+interface IPageRouteConfig {
+    /** 唯一识别符 */
+    id: string;
+    /** 路径配置 */
+    path: string;
+    /** 作为 content 懒加载的标识. */
+    loading?: Promise<LvErrorRef>;
+    content?: () => React.ReactNode;
+    /** skeleton 路由没加载完之前的骨架屏 */
+    skeleton?: () => React.ReactNode;
+    /** 是否拦截跳转 */
+    shouldInterceptNavigate?: () => boolean;
+    /** 设置是否需要keep-alive缓存起路由组件 */
+    isNeedCache?: boolean | (() => boolean);
+    /** 设置该路由中的布局配置项 */
+    layoutConfiguration?: ILayoutConfiguration;
+    /** 页面是否展示的回调函数 */
+    onActiveChange?: (options: {
+        active: boolean;
+        /** 允许由其他业务模块透传传递到指定 contribution 中.实现特定业务逻辑 */
+        extraParams?: any | undefined;
+    }) => void;
+    index?: boolean;
+    _updateTime?: number;
+    /**
+     * Error Boundary 的 fallback 内容
+     * 建议纯组件，避免 fallback 组件内部仍有异常
+     */
+    errorElement?: ReactElement<unknown, string | FunctionComponent | typeof Component> | null;
+    /**
+     * Error Boundary 的 onError 回调
+     * 常用于上报问题
+     */
+    onError?: (error: Error, info: ErrorInfo) => void;
+}
+
+declare const PageRouteManagerSymbol = "PageRoute";
+interface IPageRouteObservableData {
+    currentRoute: string | undefined;
+    configs: IPageRouteConfig[];
+    keepAliveStatusMap: Record<string, IKeepAliveEventData>;
+    historyRoutes: string[];
+    containerWidth: number;
+}
+interface IGeneratePathOptions {
+    params?: Record<string, string>;
+    query?: Record<string, string> | string;
+}
+interface INavigateOptions extends IGeneratePathOptions, NavigateOptions {
+}
+declare enum KeepAliveStatus {
+    /** 激活态 */
+    Activated = "Activated",
+    /** 失活态 */
+    InActivated = "InActivated"
+}
+interface IKeepAliveEventData {
+    /** 当前激活状态对应的路由路径 */
+    pathName: string;
+    /** 当前激活状态对应的路由ID */
+    routeId: string;
+    /** 当前激活状态 */
+    status: KeepAliveStatus;
+    /** 当前激活状态的路由携带的信息 */
+    locationState: any;
+}
+type IPageRouteRenderOptions = {
+    layout: React__default.ReactNode;
+};
+type IPageRouteOutletOptions = {
+    routesConfig: IPageRouteConfig[];
+};
+interface IPageRouteManager extends IBaseUiManager<IPageRouteConfig> {
+    observableData: IPageRouteObservableData;
+    render: (options: IPageRouteRenderOptions) => React__default.ReactNode;
+    renderOutlet: (options: IPageRouteOutletOptions) => React__default.ReactNode;
+    /** 用于单向的路由跳转场景 */
+    renderSingleOutlet: (options: IPageRouteOutletOptions) => React__default.ReactNode;
+    /** 当前激活的路由信息 */
+    currentKeepAliveData: IKeepAliveEventData | undefined;
+    /** 等待待跳转的路由 */
+    pendingNavigateOptions: {
+        path: string;
+        options?: INavigateOptions;
+    } | undefined;
+    currentRoute: IPageRouteConfig | undefined;
+    /** 触发路由改变的回调 */
+    onWouldRouteChange: Event<[string | number, options?: NavigateOptions]>;
+    notifyPageRendered: (config: string | IPageRouteConfig) => void;
+    onPageRendered: Event<[IPageRouteConfig]>;
+    onPageContainerWidthChange: Event<[]>;
+    /** 路由配置发生变化时触发的事件 */
+    onRouteConfigChange: Event<[IPageRouteConfig[]]>;
+    getRouteConfigByPath: (path: string) => IPageRouteConfig | undefined;
+    /** 更新当前路由 */
+    updatePageRoute: (path: string) => void;
+    /** 生成路径 */
+    generatePath: (id: string, options?: IGeneratePathOptions | undefined) => string;
+    /** 路由到具体地址 */
+    navigate: (id: string, options?: INavigateOptions) => void;
+    /** 返回到上级页面
+     * @param {number} 默认是-1 即返回上一级页面
+     * */
+    navigateBack: (to?: number) => void;
+    /** 使用keep-alive之后，可监听keep-alive看当前那一个路由组件被激活了 */
+    onKeepAliveChange: Event<[IKeepAliveEventData]>;
+    /** 由外部去触发当前需要激活那一个路由 */
+    activateKeepAliveRoute: (activatePathName: string, locationState: any) => void;
+    updateContainerWidth: (width: number) => void;
+    /** 初始化完 pageRouteManager 可以进行navigate了 */
+    initDone: VoidFunction;
+}
+
+declare class PageRouteManager extends BaseUiManager<any, IPageRouteConfig> implements IBaseUiManager<IPageRouteConfig>, IPageRouteManager {
+    observableData: IPageRouteObservableData;
+    private readonly _locker;
+    private _pendingNavigateOptions;
+    private readonly _onWouldRouteChange;
+    onWouldRouteChange: _zk_tech_bedrock_event.Event<[string | number, options?: INavigateOptions | undefined]>;
+    private readonly _onKeepAliveChange;
+    onKeepAliveChange: _zk_tech_bedrock_event.Event<[IKeepAliveEventData]>;
+    private readonly _onPageRendered;
+    onPageRendered: _zk_tech_bedrock_event.Event<[IPageRouteConfig]>;
+    private readonly _onPageContainerWidthChange;
+    onPageContainerWidthChange: _zk_tech_bedrock_event.Event<[]>;
+    private readonly _onRouteConfigChange;
+    onRouteConfigChange: _zk_tech_bedrock_event.Event<[IPageRouteConfig[]]>;
+    get pendingNavigateOptions(): {
+        path: string;
+        options?: INavigateOptions;
+    } | undefined;
+    get currentRoute(): IPageRouteConfig | undefined;
+    registerConfig(configs: IPageRouteConfig[]): void;
+    updatePageRoute(path: string): void;
+    navigate(id: string, options?: INavigateOptions): void;
+    private _navigateByPath;
+    updateContainerWidth(width: number): void;
+    initDone(): void;
+    navigateBack(to?: number): void;
+    generatePath(id: string, options?: IGeneratePathOptions | undefined): string;
+    activateKeepAliveRoute(activatePathName: string, locationState: any): void;
+    private _updateKeepAliveStatus;
+    get currentKeepAliveData(): IKeepAliveEventData | undefined;
+    notifyPageRendered(config: string | IPageRouteConfig): void;
+    getRouteConfigByPath(path: string | undefined): IPageRouteConfig | undefined;
+    render(options: IPageRouteRenderOptions): React.ReactNode;
+    renderOutlet(options: IPageRouteOutletOptions): React$1.JSX.Element;
+    renderSingleOutlet(options: IPageRouteOutletOptions): React$1.JSX.Element;
+    _middlewareChange(props: IMiddlewareChange<'PageRoute'>): void;
+}
+
+type TEffectCallback = () => VoidFunction | void;
+/**
+ *  用于keep-alive路由组件的显隐的触发钩子
+ *  由于使用了keep-alive路由的组件，无法使用useEffect来表示组件是否可见，因此增加该hook来
+ *  帮助外部来判断当前组件是否可见，用法和useEffect类似，传入一个函数，该函数会在初始化时候的路由组件
+ *  被激活的时候触发，且该函数返回的函数会在失活的时候被触发
+ *  @example
+ *  ```
+ *   useKeepAliveEffect(() => {
+ *    console.log('我被激活啦！')
+ *    return () => {
+ *       console.log('我被失活啦！')
+ *    }
+ *   })
+ *  ```
+ */
+declare const useKeepAliveEffect: (cb: TEffectCallback) => void;
+declare const useKeepAliveLayoutEffect: (cb: TEffectCallback) => void;
+
+declare const usePageContainerWidth: () => number;
+
+/**
+ * 模块的全局设置，会被赋值到 setting store 上.
+ */
+type IPageRouteSettingObservableData = {
+    /** 基础路径,默认为 '/' */
+    baseRoute: string;
+    /** 当页面无任何内容命中时，自动执行重定向处理; 参数是 pageRoute 对应 id */
+    redirectRouteIdWhen404?: string;
+};
+type IPageRouteSetting = IPageRouteSettingObservableData & {
+    /** 可选的 observable 数据 */
+    observableData?: IPageRouteSettingObservableData;
+};
+
+type ITempUiConfigurationServiceContext = IContext<{
+    uiManager: {
+        [PageRouteManagerSymbol]: IPageRouteManager;
+    };
+    setting: IPageRouteSetting & IBaseSetting;
+}>;
+
+declare const useNavigateFactory: (uiConfigurationService: ITempUiConfigurationServiceContext["uiConfigurationService"]) => NavigateFunction;
+
+type IBlockContentSetting = void;
+
+/**
+ * blockContent 配置内容
+ * @public
+ */
+type IBlockContentConfig = {
+    /** 唯一识别符 */
+    id: string;
+    /** 允许自定义挂载 title bar 的自定义类名 */
+    className?: string | ((...args: any[]) => string);
+    /**
+     * 展示的内容，可以是 React 组件或字符串
+     */
+    content: React__default.ReactNode | (() => React__default.ReactNode | null) | null;
+    onHover?: (...args: any[]) => void;
+};
+
+declare const BlockContentManagerSymbol = "BlockContent";
+interface IBlockContentObservableData {
+    forceUpdate: number;
+    activeId: string | undefined;
+    configs: IBlockContentConfig[];
+}
+interface IBlockContentManager extends IBaseUiManager<IBlockContentConfig> {
+    observableData: IBlockContentObservableData;
+    changeActiveId: (activeId: string) => void;
+}
+
+declare class BlockContentManager extends BaseUiManager<any, IBlockContentConfig> implements IBlockContentManager {
+    observableData: IBlockContentObservableData;
+    registerConfig(configs: IBlockContentConfig[]): void;
+    changeActiveId(activeId: string | undefined): void;
+    render(): React$1.JSX.Element;
+    _middlewareChange(): void;
+}
+
+export { BaseSetting, BaseUiConfigurationService, BaseUiManager, BlockContentManager, BlockContentManagerSymbol, GlobalContext, type IBaseSetting, type IBaseUiManager, type IBlockContentConfig, type IBlockContentManager, type IBlockContentSetting, type IKeepAliveEventData, type IMiddlewareManager, type INavigateOptions, type IPageRouteConfig, type IPageRouteManager, type IPageRouteSetting, type IUseMiddlewareProps, KeepAliveStatus, MiddlewareManager, OrderLevel, PageRouteManager, PageRouteManagerSymbol, evaluate, mergeUiConfigs, runnerBuilder, sortListBySettings, useKeepAliveEffect, useKeepAliveLayoutEffect, useNavigateFactory, usePageContainerWidth };