@difizen/libro-common 0.3.16 → 1.0.1

package/src/core/view/utils.tsx

@@ -0,0 +1,48 @@
+import { getOrigin } from '../../observable/index.js';
+import React from 'react';
+/**
+ * hack
+ * @param component react component
+ * @returns
+ */
+export const isForwardRefComponent = (
+  component: any,
+): component is React.ForwardRefExoticComponent<any> => {
+  return !!(
+    component &&
+    component.$$typeof !== undefined &&
+    component.render !== undefined
+  );
+};
+/**
+ * hack
+ * @param component react component
+ * @returns
+ */
+export const isMemoComponent = (
+  component: any,
+): component is React.ForwardRefExoticComponent<any> => {
+  return !!(
+    component &&
+    component.$$typeof !== undefined &&
+    component.type !== undefined
+  );
+};
+
+export function renderNode(nodeOrFC: React.ReactNode | React.FC) {
+  if (typeof nodeOrFC === 'string') {
+    return <span>{nodeOrFC}</span>;
+  }
+  if (React.isValidElement(nodeOrFC)) {
+    return getOrigin(nodeOrFC);
+  }
+  if (
+    typeof nodeOrFC === 'function' ||
+    isForwardRefComponent(nodeOrFC) ||
+    isMemoComponent(nodeOrFC)
+  ) {
+    const FC = nodeOrFC;
+    return <FC />;
+  }
+  return <></>;
+}

package/src/core/view/view-application.ts

@@ -0,0 +1,70 @@
+import { inject, singleton } from '../../ioc/index.js';
+
+import { ApplicationContribution } from '../application';
+
+import { SlotViewManager } from './slot-view-manager';
+import { ViewManager } from './view-manager';
+import type { ViewPreference } from './view-protocol';
+import { RootViewId } from './view-protocol';
+import { ViewStorage } from './view-storage';
+
+@singleton({ contrib: ApplicationContribution })
+export class ViewApplication implements ApplicationContribution {
+  protected readonly viewManager: ViewManager;
+  protected readonly slotViewManager: SlotViewManager;
+  protected readonly viewStorage: ViewStorage;
+
+  constructor(
+    @inject(ViewManager) viewManager: ViewManager,
+    @inject(SlotViewManager) slotViewManager: SlotViewManager,
+    @inject(ViewStorage) viewStorage: ViewStorage,
+  ) {
+    this.viewManager = viewManager;
+    this.slotViewManager = slotViewManager;
+    this.viewStorage = viewStorage;
+  }
+
+  async onStart() {
+    const rootView = await this.viewManager.getOrCreateView(RootViewId);
+    this.viewManager.root = rootView;
+  }
+
+  async onViewStart() {
+    const view = await this.tryRestoreView();
+    if (!view || this.viewStorage.onlyRootView) {
+      this.initView();
+    }
+  }
+
+  protected async tryRestoreView(): Promise<boolean> {
+    const savedView = await this.viewStorage.getSavedView();
+    if (savedView && this.viewStorage.canStoreView) {
+      return !!this.viewStorage.restoreView(savedView);
+    }
+    return false;
+  }
+
+  initView() {
+    const preferenceMap = this.viewManager.getPreferenceMap();
+    for (const factoryId of preferenceMap.keys()) {
+      const preference = preferenceMap.get(factoryId);
+      if (preference && preference.autoCreate) {
+        this.doCreateView(factoryId, preference);
+      }
+    }
+  }
+
+  onWillStop() {
+    if (this.viewStorage.canStoreView) {
+      this.viewStorage.saveViews();
+    }
+    return true;
+  }
+
+  protected async doCreateView(factoryId: string, preference: ViewPreference) {
+    const view = await this.viewManager.getOrCreateView(factoryId, preference.options);
+    if (preference.slot) {
+      await this.slotViewManager.addView(view, preference.slot, preference.openOptions);
+    }
+  }
+}

package/src/core/view/view-container.tsx

@@ -0,0 +1,91 @@
+import { ObservableContext, useInject } from '../../observable/index.js';
+import type { Syringe } from '../../ioc/index.js';
+import * as React from 'react';
+
+import { useMount, useUnmount } from '../utils/hooks';
+
+import { useViewSize } from './hooks';
+import { isForwardRefComponent } from './utils';
+import type { View } from './view-protocol';
+import type { ViewComponent } from './view-protocol';
+import { OriginViewComponent } from './view-protocol';
+import { ViewInstance } from './view-protocol';
+
+import './index.less';
+
+interface ViewContainerProps {
+  component: ViewComponent;
+  viewComponentProps: Record<string, any>;
+  children: React.ReactNode;
+}
+
+export const ViewContainer = React.forwardRef<HTMLDivElement, ViewContainerProps>(
+  function ViewContainer(props, containerRef) {
+    const { viewComponentProps = {}, children, component } = props;
+    const viewInstance = useInject<View>(ViewInstance);
+    const Component = component;
+    const className = viewInstance?.className ?? '';
+    useMount(() => {
+      if (typeof containerRef === 'object') {
+        viewInstance.container = containerRef;
+      }
+      viewInstance.isVisible = true;
+      viewInstance.onViewMount?.();
+    });
+    useUnmount(() => {
+      viewInstance.isVisible = false;
+      viewInstance.onViewUnmount?.();
+    });
+
+    useViewSize(viewInstance, containerRef);
+
+    if (isForwardRefComponent(Component)) {
+      return (
+        <Component ref={containerRef} className={className} {...viewComponentProps}>
+          {children}
+        </Component>
+      );
+    }
+    return (
+      <div ref={containerRef} className={`mana-view-container ${className}`}>
+        <Component {...viewComponentProps}>{children}</Component>
+      </div>
+    );
+  },
+);
+export const ViewWrapper = (
+  ViewComponent: React.FC | React.ForwardRefExoticComponent<any>,
+  container: Syringe.Container,
+) => {
+  const ViewWrapperRender: WrapperViewComponent = ({
+    children,
+    ...props
+  }: {
+    children: React.ReactNode;
+  }) => {
+    const containerRef = React.useRef<HTMLDivElement>(null);
+    return (
+      <ObservableContext.Provider value={{ getContainer: () => container }}>
+        <ViewContainer
+          ref={containerRef}
+          component={ViewComponent}
+          viewComponentProps={props}
+        >
+          {children}
+        </ViewContainer>
+      </ObservableContext.Provider>
+    );
+  };
+  ViewWrapperRender[OriginViewComponent] = ViewComponent;
+  return ViewWrapperRender;
+};
+
+type WrapperViewComponent = React.FC<{ children: React.ReactNode }> & {
+  [OriginViewComponent]?: React.FC | React.ForwardRefExoticComponent<any>;
+};
+
+export function isWrapperViewComponent(
+  component: any,
+): component is WrapperViewComponent {
+  return component && component[OriginViewComponent] !== undefined;
+}

package/src/core/view/view-context.tsx

@@ -0,0 +1,37 @@
+import { getOrigin, ObservableContext } from '../../observable/index.js';
+import * as React from 'react';
+
+import type { ManaContext } from '../module';
+
+import { ViewMeta } from './view-meta';
+import type { View } from './view-protocol';
+
+export interface ViewContextProps {
+  view: View;
+  children: React.ReactNode | React.ReactNode[];
+}
+
+interface ViewContextRenderProps {
+  context?: ManaContext;
+  children: React.ReactNode | React.ReactNode[];
+}
+
+const ViewContextRender = React.memo(function ViewContextRender(
+  props: ViewContextRenderProps,
+) {
+  const { context, children } = props;
+  if (context) {
+    return (
+      <ObservableContext.Provider value={{ getContainer: () => context.container }}>
+        {children}
+      </ObservableContext.Provider>
+    );
+  }
+  return <></>;
+});
+
+export const ViewContext = (props: ViewContextProps) => {
+  const { view, children } = props;
+  const manaContext = ViewMeta.getViewContext(getOrigin(view));
+  return <ViewContextRender context={manaContext}>{children}</ViewContextRender>;
+};

package/src/core/view/view-decoration.ts

@@ -0,0 +1,160 @@
+/**
+ * Namespace for the decoration data and the styling refinements for the decorated widgets.
+ */
+export namespace ViewDecoration {
+  /**
+   * For the sake of simplicity, we have merged the `font-style`, `font-weight`, and the `text-decoration` together.
+   */
+  export type FontStyle =
+    | 'normal'
+    | 'bold'
+    | 'italic'
+    | 'oblique'
+    | 'underline'
+    | 'line-through';
+  /**
+   * A string that could be:
+   *
+   *  - one of the browser colors, (E.g.: `blue`, `red`, `magenta`),
+   *  - the case insensitive hexadecimal color code, (for instance, `#ee82ee`, `#20B2AA`, `#f09` ), or
+   *  - either the `rgb()` or the `rgba()` functions.
+   *
+   * For more details, see: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value.
+   *
+   * Note, it is highly recommended to use one of the predefined colors of Mana, so the desired color will
+   * look nice with both the `light` and the `dark` theme too.
+   */
+  export type Color = string;
+  /**
+   * Encapsulates styling information of the font.
+   */
+  export type FontData = {
+    /**
+     * Zero to any font style.
+     */
+    readonly style?: FontStyle | FontStyle[];
+    /**
+     * The color of the font.
+     */
+    readonly color?: Color;
+  };
+  /**
+   * Arbitrary information that has to be shown either before or after the caption as a prefix or a suffix.
+   */
+  export type CaptionAffix = {
+    /**
+     * The text content of the prefix or the suffix.
+     */
+    readonly data: string;
+    /**
+     * Font data for customizing the prefix of the suffix.
+     */
+    readonly fontData?: FontData;
+  };
+  export type BaseTailDecoration = {
+    /**
+     * Optional tooltip for the tail decoration.
+     */
+    readonly tooltip?: string;
+  };
+  /**
+   * Unlike caption suffixes, tail decorations appears right-aligned after the caption and the caption suffixes (is any).
+   */
+  export type TailDecoration = {
+    /**
+     * The text content of the tail decoration.
+     */
+    readonly data: string;
+    /**
+     * Font data for customizing the content.
+     */
+    readonly fontData?: FontData;
+  } & BaseTailDecoration;
+  export type TailDecorationIcon = {
+    /**
+     * This should be the name of the Font Awesome icon with out the `fa fa-` prefix, just the name, for instance `paw`.
+     * For the existing icons, see here: https://fontawesome.com/v4.7.0/icons/.
+     */
+    readonly icon: string;
+    /**
+     * The color of the icon.
+     */
+    readonly color?: Color;
+  } & BaseTailDecoration;
+  export type TailDecorationIconClass = {
+    /**
+     * This should be the entire Font Awesome class array, for instance ['fa', 'fa-paw']
+     * For the existing icons, see here: https://fontawesome.com/v4.7.0/icons/.
+     */
+    readonly iconClass: string[];
+    /**
+     * The color of the icon.
+     */
+    readonly color?: Color;
+  } & BaseTailDecoration;
+  /**
+   * Enumeration for the quadrant to overlay the image on.
+   */
+
+  /**
+   * A shape that can be optionally rendered behind the overlay icon. Can be used to further refine colors.
+   */
+  export type IconOverlayBackground = {
+    /**
+     * Either `circle` or `square`.
+     */
+    readonly shape: 'circle' | 'square';
+    /**
+     * The color of the background shape.
+     */
+    readonly color?: Color;
+  };
+
+  /**
+   * Encapsulates styling information that has to be applied on the widget which we decorate.
+   */
+  export type Data = {
+    /**
+     * The higher number has higher priority. If not specified, treated as `0`.
+     * When multiple decorators are available for the same item, and decoration data cannot be merged together,
+     * then the higher priority item will be applied on the decorated element and the lower priority will be ignored.
+     */
+    readonly priority?: number;
+    /**
+     * The font data for the caption.
+     */
+    readonly fontData?: FontData;
+    /**
+     * The background color of the entire row.
+     */
+    readonly backgroundColor?: Color;
+    /**
+     * Optional, leading prefixes right before the caption.
+     */
+    readonly captionPrefixes?: CaptionAffix[];
+    /**
+     * Suffixes that might come after the caption as an additional information.
+     */
+    readonly captionSuffixes?: CaptionAffix[];
+    /**
+     * Optional right-aligned decorations that appear after the widget caption and after the caption suffixes (is any).
+     */
+    readonly tailDecorations?: (
+      | TailDecoration
+      | TailDecorationIcon
+      | TailDecorationIconClass
+    )[];
+    /**
+     * Custom tooltip for the decorated item. Tooltip will be appended to the original tooltip, if any.
+     */
+    readonly tooltip?: string;
+    /**
+     * Sets the color of the icon. Ignored if the decorated item has no icon.
+     */
+    readonly iconColor?: Color;
+    /**
+     * A count badge for widgets.
+     */
+    readonly badge?: number;
+  };
+}

package/src/core/view/view-manager.ts

@@ -0,0 +1,271 @@
+/* eslint-disable @typescript-eslint/no-invalid-this */
+import type { MaybePromise, Event, Newable, Disposable } from '../../common/index.js';
+import { DisposableCollection } from '../../common/index.js';
+import { Priority, Emitter } from '../../common/index.js';
+import { prop } from '../../observable/index.js';
+import type { Contribution } from '../../ioc/index.js';
+import { contrib, inject, singleton } from '../../ioc/index.js';
+
+import { DebugService } from '../common/debug';
+import type { ManaContext } from '../module';
+
+import { ViewMeta } from './view-meta';
+import type { ViewPreference, View } from './view-protocol';
+import type { SlotView } from './view-protocol';
+import { ViewDefineToken } from './view-protocol';
+import { ViewFactory, ViewPreferenceContribution } from './view-protocol';
+
+export interface ViewCreateOptions {
+  factoryId: string;
+  options?: any;
+}
+
+export interface ViewEvent {
+  readonly view: View;
+  readonly factoryId: string;
+}
+/**
+ * 管理视图
+ * 为视图保存创建条件
+ */
+@singleton()
+export class ViewManager implements Disposable {
+  @prop()
+  root?: View;
+  protected factoryMap?: Map<string, ViewFactory> | undefined;
+  protected factories: string[] = [];
+  protected preferenceMap?: Map<string, ViewPreference> | undefined;
+  protected preferences: string[] = [];
+  protected readonly viewContextMap = new Map<View, ManaContext>();
+  protected readonly viewFactoryMap = new Map<View, string>();
+
+  protected readonly views = new Map<string, View>();
+  protected readonly viewPromises = new Map<string, MaybePromise<View>>();
+  protected readonly pendingViewPromises = new Map<string, MaybePromise<View>>();
+  protected readonly onWillCreateViewEmitter = new Emitter<ViewEvent>();
+
+  readonly onWillCreateView: Event<ViewEvent> = this.onWillCreateViewEmitter.event;
+
+  protected readonly onDidCreateViewEmitter = new Emitter<ViewEvent>();
+
+  readonly onDidCreateView: Event<ViewEvent> = this.onDidCreateViewEmitter.event;
+
+  readonly toDispose = new DisposableCollection();
+
+  protected readonly factoryProvider: Contribution.Provider<ViewFactory>;
+  protected readonly debugService: DebugService;
+  protected readonly preferenceProvider: Contribution.Provider<ViewPreferenceContribution>;
+  disposed?: boolean | undefined;
+
+  constructor(
+    @contrib(ViewFactory) factoryProvider: Contribution.Provider<ViewFactory>,
+    @inject(DebugService) debugService: DebugService,
+    @contrib(ViewPreferenceContribution)
+    preferenceProvider: Contribution.Provider<ViewPreferenceContribution>,
+  ) {
+    this.factoryProvider = factoryProvider;
+    this.debugService = debugService;
+    this.preferenceProvider = preferenceProvider;
+    this.toDispose.push(this.onDidCreateViewEmitter);
+    this.toDispose.push(this.onWillCreateViewEmitter);
+    this.toDispose.push(
+      this.factoryProvider.onChanged(() => {
+        this.factoryMap = undefined;
+      }),
+    );
+  }
+  dispose() {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.viewPromises.clear();
+    this.pendingViewPromises.clear();
+  }
+
+  getFactoryMap(): Map<string, ViewFactory> {
+    if (!this.factoryMap) {
+      this.factoryMap = new Map();
+      for (const factory of this.factoryProvider.getContributions()) {
+        if (factory.id) {
+          this.factoryMap.set(factory.id, factory);
+        }
+      }
+      this.factories = [];
+      for (const id of this.factoryMap.keys()) {
+        this.factories.push(id);
+      }
+    }
+    return this.factoryMap;
+  }
+
+  toFactoryId(view: Newable<View> | string): string {
+    if (typeof view === 'string') {
+      return view;
+    }
+    const factoryId = Reflect.getMetadata(ViewDefineToken, view);
+    return factoryId;
+  }
+
+  getPreferenceMap(): Map<string, ViewPreference> {
+    if (!this.preferenceMap) {
+      this.preferenceMap = new Map();
+      for (const viewPreference of this.preferenceProvider.getContributions()) {
+        viewPreference.forEach((item) => {
+          const { view } = item;
+          const factoryId = this.toFactoryId(view);
+          const currentPriority = item.priority ?? Priority.IDLE;
+          const last = this.preferenceMap?.get(factoryId);
+          if (!last || !last.priority || currentPriority > last.priority) {
+            this.preferenceMap?.set(factoryId, item);
+          }
+        });
+      }
+      this.preferences = [];
+      for (const id of this.preferenceMap.keys()) {
+        this.preferences.push(id);
+      }
+    }
+    return this.preferenceMap;
+  }
+
+  toKey(options: ViewCreateOptions): string {
+    return JSON.stringify(options);
+  }
+  fromKey(key: string): ViewCreateOptions {
+    return JSON.parse(key);
+  }
+  getView<T extends View>(
+    factoryOrView: string | Newable<View>,
+    options?: any,
+  ): MaybePromise<T> | undefined {
+    const factoryId = this.toFactoryId(factoryOrView);
+    const key = this.toKey({ factoryId, options });
+    const pendingView = this.doGetView<T>(key);
+    return pendingView;
+  }
+
+  getViewByKey(key: string) {
+    const pending = this.pendingViewPromises.get(key);
+    if (pending) {
+      return pending;
+    }
+    return this.views.get(key);
+  }
+
+  async getViews<T extends View>(factoryId: string): Promise<T[]> {
+    const views: T[] = [];
+    for (const [key] of this.views.entries()) {
+      if (this.fromKey(key).factoryId === factoryId) {
+        const pendingView = this.doGetView<T>(key);
+        const view = pendingView && (await pendingView);
+        if (view) {
+          views.push(view);
+        }
+      }
+    }
+    return views;
+  }
+
+  protected doGetView<T extends View>(key: string): MaybePromise<T> | undefined {
+    const pendingView = this.viewPromises.get(key) ?? this.pendingViewPromises.get(key);
+    if (pendingView) {
+      return pendingView as MaybePromise<T>;
+    }
+    return undefined;
+  }
+
+  getFactory(view: Newable<View> | Newable<SlotView>): ViewFactory | undefined {
+    const factoryId = this.toFactoryId(view);
+    const factories = this.getFactoryMap();
+    try {
+      return factories.get(factoryId);
+    } catch (ex) {
+      console.error(ex);
+      return;
+    }
+  }
+
+  getPrefer(factoryId: string): ViewPreference | undefined {
+    return this.getPreferenceMap().get(factoryId);
+  }
+
+  getFactoryIdByView(view: View): string | undefined {
+    return this.viewFactoryMap.get(view);
+  }
+
+  getViewOption(view: View) {
+    for (const [key, value] of this.views.entries()) {
+      if (value === view) {
+        return this.fromKey(key).options;
+      } else {
+        continue;
+      }
+    }
+  }
+
+  setViewContext(view: View, context: ManaContext) {
+    return ViewMeta.setViewContext(view, context);
+  }
+
+  getViewContext(view: View) {
+    return ViewMeta.getViewContext(view) as ManaContext;
+  }
+
+  removeViewContext(view: View) {
+    return ViewMeta.removeViewContext(view);
+  }
+
+  getViewKey(view: View) {
+    for (const [key, value] of this.views.entries()) {
+      if (value === view) {
+        return key;
+      }
+    }
+    return undefined;
+  }
+
+  protected mergeViewOption(options?: Record<any, any>, preference?: ViewPreference) {
+    if (!options && !preference?.options) {
+      return undefined;
+    }
+    return { ...preference?.options, ...options };
+  }
+
+  async getOrCreateView<T extends View, U extends Record<any, any> = any>(
+    factoryOrView: string | Newable<T>,
+    options?: U,
+  ): Promise<T> {
+    const factoryId = this.toFactoryId(factoryOrView);
+    const key = this.toKey({ factoryId, options });
+    const existingView = this.doGetView<T>(key);
+    if (existingView) {
+      return existingView;
+    }
+    const factory = this.getFactoryMap().get(factoryId);
+    if (!factory) {
+      throw Error(`No View factory '${factoryId}' has been registered.`);
+    }
+    try {
+      const preference = this.getPreferenceMap().get(factoryId);
+      const viewOption = this.mergeViewOption(options, preference);
+      const viewPromise = factory.createView(viewOption);
+      this.pendingViewPromises.set(key, viewPromise);
+      const view = await viewPromise;
+      this.onWillCreateViewEmitter.fire({ factoryId, view });
+      this.viewPromises.set(key, viewPromise);
+      this.views.set(key, view);
+      this.viewFactoryMap.set(view, factoryId);
+      view.onDisposed(() => {
+        this.views.delete(key);
+        this.viewPromises.delete(key);
+        this.viewFactoryMap.delete(view);
+        this.removeViewContext(view);
+      });
+      this.onDidCreateViewEmitter.fire({ factoryId, view });
+      return view as T;
+    } finally {
+      this.pendingViewPromises.delete(key);
+    }
+  }
+}

package/src/core/view/view-meta.ts

@@ -0,0 +1,24 @@
+import { getOrigin } from '../../observable/index.js';
+
+import type { ManaContext } from '../module';
+
+import type { View } from './view-protocol';
+import { ViewContextMetaKey } from './view-protocol';
+
+/**
+ * View metadata
+ * 提供静态方法，用于获取和设置视图的上下文
+ */
+export class ViewMeta {
+  static setViewContext(view: View, context: ManaContext) {
+    Reflect.defineMetadata(ViewContextMetaKey, getOrigin(context), getOrigin(view));
+  }
+
+  static getViewContext(view: View) {
+    return Reflect.getMetadata(ViewContextMetaKey, getOrigin(view)) as ManaContext;
+  }
+
+  static removeViewContext(view: View) {
+    Reflect.deleteMetadata(ViewContextMetaKey, getOrigin(view));
+  }
+}