@difizen/libro-common 0.3.4 → 1.0.0

package/src/core/menu/menu-registry.ts

@@ -0,0 +1,271 @@
+import type { MaybePromise } from '../../common/index.js';
+import { Disposable } from '../../common/index.js';
+import type { Contribution } from '../../ioc/index.js';
+import { contrib, inject, singleton, Syringe } from '../../ioc/index.js';
+
+import { ApplicationContribution } from '../application/application';
+import { CommandRegistry } from '../command/command-registry';
+
+import type {
+  MenuOptions,
+  MenuPath,
+  ActionMenuNode,
+  GeneralMenuItem,
+} from './menu-protocol';
+import { CommandMenuNode, ExecutableMenuNode } from './menu-protocol';
+import {
+  GeneralMenuItemFactory,
+  MenuNode,
+  MenuItem,
+  ActionMenuItemFactory,
+} from './menu-protocol';
+
+export const MenuContribution = Syringe.defineToken('MenuContribution');
+
+export type MenuContribution = {
+  /**
+   * Register menus.
+   * @param menus the menu registry.
+   */
+  registerMenus: (menus: MenuRegistry) => void;
+};
+
+/**
+ * Register and unregister menus, submenus and actions
+ */
+@singleton({ contrib: ApplicationContribution })
+export class MenuRegistry implements ApplicationContribution {
+  protected readonly root: GeneralMenuItem;
+  protected readonly contributions: Contribution.Provider<MenuContribution>;
+  protected readonly generalItemFactory: GeneralMenuItemFactory;
+  protected readonly actionItemFactory: ActionMenuItemFactory;
+  protected readonly commands: CommandRegistry;
+
+  constructor(
+    @contrib(MenuContribution) contributions: Contribution.Provider<MenuContribution>,
+    @inject(GeneralMenuItemFactory) generalItemFactory: GeneralMenuItemFactory,
+    @inject(ActionMenuItemFactory) actionItemFactory: ActionMenuItemFactory,
+    @inject(CommandRegistry) commands: CommandRegistry,
+  ) {
+    this.contributions = contributions;
+    this.generalItemFactory = generalItemFactory;
+    this.actionItemFactory = actionItemFactory;
+    this.commands = commands;
+    this.root = generalItemFactory({ id: '' }, []);
+  }
+
+  onStart(): void {
+    for (const contribution of this.contributions.getContributions()) {
+      contribution.registerMenus(this);
+    }
+  }
+
+  /**
+   * Adds the given menu action to the menu denoted by the given path.
+   *
+   * @returns a disposable which, when called, will remove the menu action again.
+   */
+  registerMenuAction(menuPath: MenuPath, item: ActionMenuNode): Disposable {
+    const menuNode = this.actionItemFactory(item, menuPath);
+    const parent = this.getOrCreateGroup(menuPath);
+    return parent.addNode(menuNode);
+  }
+
+  /**
+   * Adds the given menu node to the menu denoted by the given path.
+   *
+   * @returns a disposable which, when called, will remove the menu node again.
+   */
+  registerMenuNode(menuPath: MenuPath, item: MenuNode): Disposable {
+    const menuNode = this.generalItemFactory(item, menuPath);
+    const parent = this.getOrCreateGroup(menuPath);
+    return parent.addNode(menuNode);
+  }
+
+  registerGroupMenu(menuPath: MenuPath, options: MenuOptions = {}): Disposable {
+    if (menuPath.length === 0) {
+      throw new Error('The group menu path cannot be empty.');
+    }
+    const index = menuPath.length - 1;
+    const menuId = menuPath[index];
+    const groupPath = index === 0 ? [] : menuPath.slice(0, index);
+    const parent = this.getOrCreateGroup(groupPath, options);
+    let groupNode = this.getOrCreateSub(parent, menuId, options);
+    if (!groupNode) {
+      groupNode = this.generalItemFactory({ id: menuId, ...options }, parent.path);
+      return parent.addNode(groupNode);
+    }
+    if (options.label) {
+      groupNode.label = options.label;
+    }
+    if (options.icon) {
+      groupNode.icon = options.icon;
+    }
+    if (options.order) {
+      groupNode.order = options.order;
+    }
+    return Disposable.NONE;
+  }
+
+  /**
+   * Register a new menu at the given path with the given label.
+   * (If the menu already exists without a label, iconClass or order this method can be used to set them.)
+   *
+   * @param menuPath the path for which a new submenu shall be registered.
+   * @param label the label to be used for the new submenu.
+   * @param options optionally allows to set an icon class and specify the order of the new menu.
+   *
+   * @returns if the menu was successfully created a disposable will be returned which,
+   * when called, will remove the menu again. If the menu already existed a no-op disposable
+   * will be returned.
+   *
+   * Note that if the menu already existed and was registered with a different label an error
+   * will be thrown.
+   */
+  registerSubmenu(menuPath: MenuPath, options: MenuOptions = {}): Disposable {
+    if (menuPath.length === 0) {
+      throw new Error('The sub menu path cannot be empty.');
+    }
+    const index = menuPath.length - 1;
+    const menuId = menuPath[index];
+    const groupPath = index === 0 ? [] : menuPath.slice(0, index);
+    const parent = this.getOrCreateGroup(groupPath, options);
+    let groupNode = this.getOrCreateSub(parent, menuId, options);
+    if (!groupNode) {
+      groupNode = this.generalItemFactory({ id: menuId, ...options }, parent.path);
+      return parent.addNode(groupNode);
+    }
+    if (options.label) {
+      groupNode.label = options.label;
+    }
+    if (options.icon) {
+      groupNode.icon = options.icon;
+    }
+    if (options.order) {
+      groupNode.order = options.order;
+    }
+    return Disposable.NONE;
+  }
+
+  /**
+   * Unregister all menu nodes with the same id as the given menu action.
+   *
+   * @param item the item whose id will be used.
+   * @param menuPath if specified only nodes within the path will be unregistered.
+   */
+  unregisterMenuAction(item: ActionMenuNode, menuPath?: MenuPath): void;
+  /**
+   * Unregister all menu nodes with the given id.
+   *
+   * @param id the id which shall be removed.
+   * @param menuPath if specified only nodes within the path will be unregistered.
+   */
+  // eslint-disable-next-line @typescript-eslint/unified-signatures
+  unregisterMenuAction(id: string, menuPath?: MenuPath): void;
+  unregisterMenuAction(
+    itemOrCommandOrId: ActionMenuNode | string,
+    menuPath?: MenuPath,
+  ): void {
+    const id = MenuNode.is(itemOrCommandOrId)
+      ? itemOrCommandOrId.id
+      : itemOrCommandOrId;
+
+    if (menuPath) {
+      const parent = this.getOrCreateGroup(menuPath);
+      parent.removeNode(id);
+      return;
+    }
+
+    this.unregisterMenuNode(id);
+  }
+
+  /**
+   * Recurse all menus, removing any menus matching the `id`.
+   *
+   * @param id technical identifier of the `MenuNode`.
+   */
+  unregisterMenuNode(id: string): void {
+    const recurse = (root: GeneralMenuItem) => {
+      root.children.forEach((node) => {
+        if (MenuItem.isGeneralMenuItem(node)) {
+          node.removeNode(id);
+          recurse(node);
+        }
+      });
+    };
+    recurse(this.root);
+  }
+
+  protected getOrCreateGroup(
+    menuPath: MenuPath,
+    options?: MenuOptions,
+  ): GeneralMenuItem {
+    let currentMenu = this.root;
+    for (const segment of menuPath) {
+      currentMenu = this.getOrCreateSub(currentMenu, segment, options);
+    }
+    return currentMenu;
+  }
+
+  protected getOrCreateSub(
+    current: GeneralMenuItem,
+    menuId: string,
+    options: MenuOptions = {},
+  ): GeneralMenuItem {
+    const sub = current.children.find((e) => e.id === menuId);
+    if (MenuItem.isGeneralMenuItem(sub)) {
+      return sub;
+    }
+    if (sub) {
+      throw new Error(`'${menuId}' is not a menu group.`);
+    }
+    const newSub = this.generalItemFactory({ id: menuId, ...options }, current.path);
+    current.addNode(newSub);
+    return newSub;
+  }
+
+  /**
+   * Returns the menu at the given path.
+   *
+   * @param menuPath the path specifying the menu to return. If not given the empty path will be used.
+   *
+   * @returns the root menu when `menuPath` is empty. If `menuPath` is not empty the specified menu is
+   * returned if it exists, otherwise an error is thrown.
+   */
+  getMenu(menuPath: MenuPath = []): GeneralMenuItem {
+    return this.getOrCreateGroup(menuPath);
+  }
+
+  isVisible(item: MenuItem, ...args: any[]): boolean {
+    if (ExecutableMenuNode.is(item)) {
+      if (item.isVisible) {
+        return item.isVisible(...args);
+      }
+    }
+    if (CommandMenuNode.is(item)) {
+      return this.commands.isVisible(item.command, ...args);
+    }
+    return true;
+  }
+
+  isEnabled(item: MenuItem, ...args: any[]): boolean {
+    if (ExecutableMenuNode.is(item)) {
+      if (item.isEnabled) {
+        return item.isEnabled(...args);
+      }
+    }
+    if (CommandMenuNode.is(item)) {
+      return this.commands.isVisible(item.command, ...args);
+    }
+    return true;
+  }
+
+  execute(item: MenuItem, ...args: any[]): MaybePromise<void> {
+    if (ExecutableMenuNode.is(item)) {
+      return item.execute(...args);
+    }
+    if (CommandMenuNode.is(item)) {
+      return this.commands.executeCommand(item.command, ...args);
+    }
+  }
+}

package/src/core/menu/module.ts

@@ -0,0 +1,32 @@
+import { ManaModule } from '../module';
+
+import { DefaultActionMenuItem, DefaultGeneralMenuItem } from './default-menu-node';
+import type { MenuNode } from './menu-protocol';
+import { GeneralMenuItemFactory } from './menu-protocol';
+import { ActionMenuItemFactory } from './menu-protocol';
+import { MenuSymbol } from './menu-protocol';
+import { MenuRegistry, MenuContribution } from './menu-registry';
+
+export const MenuModule = ManaModule.create()
+  .contribution(MenuContribution)
+  .register(MenuRegistry, DefaultGeneralMenuItem, DefaultActionMenuItem)
+  .register({
+    token: GeneralMenuItemFactory,
+    useDynamic: (ctx) => {
+      return (item: MenuNode) => {
+        const child = ctx.container.createChild();
+        child.register({ token: MenuSymbol.MenuNodeSymbol, useValue: item });
+        return child.get(DefaultGeneralMenuItem);
+      };
+    },
+  })
+  .register({
+    token: ActionMenuItemFactory,
+    useDynamic: (ctx) => {
+      return (item: MenuNode) => {
+        const child = ctx.container.createChild();
+        child.register({ token: MenuSymbol.ActionMenuNodeSymbol, useValue: item });
+        return child.get(DefaultActionMenuItem);
+      };
+    },
+  });

package/src/core/module/index.ts

@@ -0,0 +1,3 @@
+export * from './module-protocol';
+export * from './mana-module';
+export * from './mana-module-context';

package/src/core/module/mana-module-context.ts

@@ -0,0 +1,40 @@
+import type { Syringe } from '../../ioc/index.js';
+
+import { ManaModule } from './mana-module';
+
+export class ManaContext implements Syringe.Context {
+  container: Syringe.Container;
+  constructor(container: Syringe.Container) {
+    this.container = container;
+  }
+  load = async (module: Syringe.Module) => {
+    if (ManaModule.is(module)) {
+      const { dependencies, preload, canload } = module.toLoader();
+      if (canload && (await canload(module)) === false) {
+        module.load.catch(() => {
+          //
+        });
+        module.loadDefer.reject(
+          `Load ManaModule ${
+            module.name && `"${module.name}"`
+          } failed: canload return false`,
+        );
+        return;
+      }
+      if (dependencies) {
+        for (const dep of dependencies) {
+          await this.load(await dep);
+        }
+      }
+      if (preload) {
+        await preload(this);
+      }
+    } else {
+      console.warn('Unsupported module.', module);
+    }
+    this.container.load(module, false, false);
+    if (ManaModule.is(module)) {
+      module.loadDefer.resolve();
+    }
+  };
+}

package/src/core/module/mana-module.test.ts

@@ -0,0 +1,161 @@
+import assert from 'assert';
+
+import { Container, singleton } from '../../ioc/index.js';
+
+import { ManaModule } from './mana-module';
+import { ManaContext } from './mana-module-context';
+
+describe('mana module', () => {
+  it('name', async () => {
+    @singleton()
+    class M {}
+    const moduleA = ManaModule.create('a').register(M);
+
+    assert(moduleA.name === 'a');
+
+    const context = new ManaContext(new Container());
+    await context.load(moduleA);
+
+    assert(context.container.get(M) instanceof M);
+  });
+
+  it('load', async () => {
+    @singleton()
+    class M {}
+    const moduleA = ManaModule.create('a').register(M);
+
+    const context = new ManaContext(new Container());
+    await context.load(moduleA);
+
+    return expect(moduleA.load).resolves.toEqual(undefined);
+  });
+
+  it('load false', async () => {
+    @singleton()
+    class M {}
+    const moduleA = ManaModule.create('a')
+      .register(M)
+      .canload(async () => false);
+
+    const context = new ManaContext(new Container());
+    await context.load(moduleA);
+
+    return expect(moduleA.load).rejects.toEqual(
+      'Load ManaModule "a" failed: canload return false',
+    );
+  });
+
+  it('canload: false', async () => {
+    @singleton()
+    class M {}
+
+    const moduleA = ManaModule.create('a')
+      .register(M)
+      .canload(async () => false);
+
+    const context = new ManaContext(new Container());
+
+    await context.load(moduleA);
+
+    expect(() => context.container.get(M)).toThrow(
+      'No matching bindings found for serviceIdentifier: M',
+    );
+  });
+
+  it('canload: true', async () => {
+    @singleton()
+    class P {}
+
+    const moduleB = ManaModule.create('a')
+      .register(P)
+      .canload(async () => true);
+
+    const context = new ManaContext(new Container());
+
+    await context.load(moduleB);
+
+    assert(context.container.get(P) instanceof P);
+  });
+
+  it('canload: param', async () => {
+    const canload = ['a'];
+
+    @singleton()
+    class P {}
+
+    let param: P | undefined = undefined;
+
+    const moduleB = ManaModule.create('a')
+      .register(P)
+      .canload(async (mod) => {
+        param = mod;
+        return mod.name ? canload.includes(mod.name) : true;
+      });
+
+    const context = new ManaContext(new Container());
+
+    await context.load(moduleB);
+
+    assert(context.container.get(P) instanceof P);
+    expect(param).toEqual(moduleB);
+  });
+
+  it('preload', async () => {
+    const mockFn = jest.fn();
+
+    @singleton()
+    class P {}
+
+    const moduleB = ManaModule.create('a')
+      .register(P)
+      .canload(async () => true)
+      .preload(mockFn);
+
+    const context = new ManaContext(new Container());
+
+    await context.load(moduleB);
+
+    assert(context.container.get(P) instanceof P);
+    expect(mockFn.mock.calls).toHaveLength(1);
+  });
+
+  it('deps', async () => {
+    @singleton()
+    class P {}
+
+    const moduleA = ManaModule.create('a')
+      .register(P)
+      .canload(async () => true);
+
+    const moduleB = ManaModule.create('b')
+      .canload(async () => true)
+      .dependOn(moduleA);
+
+    const context = new ManaContext(new Container());
+
+    await context.load(moduleB);
+
+    assert(context.container.get(P) instanceof P);
+  });
+
+  it('canload false block deps', async () => {
+    @singleton()
+    class P {}
+
+    const moduleA = ManaModule.create('a')
+      .register(P)
+      .canload(async () => true);
+
+    const moduleB = ManaModule.create('b')
+      .canload(async () => false)
+      .dependOn(moduleA);
+
+    const context = new ManaContext(new Container());
+
+    await context.load(moduleB);
+
+    expect(() => context.container.get(P)).toThrow(
+      'No matching bindings found for serviceIdentifier: P',
+    );
+  });
+});

package/src/core/module/mana-module.ts

@@ -0,0 +1,44 @@
+import type { MaybePromise } from '../../common/index.js';
+import { Deferred } from '../../common/index.js';
+import { SyringeModule } from '../../ioc/index.js';
+
+import type { CanloadModule, ModuleLoader, ModulePreload } from './module-protocol';
+
+export class ManaModule extends SyringeModule<MaybePromise<ManaModule>> {
+  protected preloadMethod?: ModulePreload;
+  protected canloadMethod?: CanloadModule;
+  /**
+   * @internal
+   */
+  loadDefer = new Deferred<void>();
+
+  get load() {
+    return this.loadDefer.promise;
+  }
+
+  canload(fn: CanloadModule) {
+    this.canloadMethod = fn;
+    return this;
+  }
+
+  preload(fn: ModulePreload) {
+    this.preloadMethod = fn;
+    return this;
+  }
+  override toLoader(): ModuleLoader {
+    return {
+      dependencies: this.dependencies.length > 0 ? this.dependencies : undefined,
+      preload: this.preloadMethod,
+      canload: this.canloadMethod,
+    };
+  }
+  static create(name?: string) {
+    return new ManaModule(name);
+  }
+}
+
+export namespace ManaModule {
+  export function is(data: Record<any, any> | undefined): data is ManaModule {
+    return !!data && typeof data === 'object' && 'toLoader' in data;
+  }
+}

package/src/core/module/module-protocol.ts

@@ -0,0 +1,12 @@
+import type { MaybePromise } from '../../common/index.js';
+import type { Syringe, SyringeModuleLoader } from '../../ioc/index.js';
+
+import type { ManaModule } from './mana-module';
+
+export type ModulePreload = (ctx: Syringe.Context) => Promise<void>;
+export type CanloadModule = (ctx: ManaModule) => Promise<boolean>;
+
+export interface ModuleLoader extends SyringeModuleLoader<MaybePromise<ManaModule>> {
+  canload?: CanloadModule | undefined;
+  preload?: ModulePreload | undefined;
+}

package/src/core/nls.ts

@@ -0,0 +1,46 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+export interface ILocalizeInfo {
+  key: string;
+  comment: string[];
+}
+
+/**
+ * Localize a message.
+ *
+ * `message` can contain `{n}` notation where it is replaced by the nth value in `...args`
+ * For example, `localize({ key: 'sayHello', comment: ['Welcomes user'] }, 'hello {0}', name)`
+ */
+export function localize(
+  info: ILocalizeInfo,
+  message: string,
+  ...args: (string | number | boolean | undefined | null)[]
+): string;
+
+/**
+ * Localize a message.
+ *
+ * `message` can contain `{n}` notation where it is replaced by the nth value in `...args`
+ * For example, `localize('sayHello', 'hello {0}', name)`
+ */
+export function localize(
+  // eslint-disable-next-line @typescript-eslint/unified-signatures
+  key: string,
+  message: string,
+  ...args: (string | number | boolean | undefined | null)[]
+): string;
+
+export function localize(
+  key: ILocalizeInfo | string,
+  message: string,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  ..._args: (string | number | boolean | undefined | null)[]
+): string {
+  if (typeof key === 'string') {
+    return key + message;
+  }
+  return key.comment + message;
+}

package/src/core/selection/index.ts

@@ -0,0 +1,7 @@
+import { ManaModule } from '../module';
+
+import { SelectionService } from './selection-service';
+
+export const SelectionModule = ManaModule.create().register(SelectionService);
+
+export * from './selection-service';

package/src/core/selection/selection-service.ts

@@ -0,0 +1,26 @@
+import type { Event } from '../../common/index.js';
+import { Emitter } from '../../common/index.js';
+import { singleton } from '../../ioc/index.js';
+
+export type SelectionProvider<T> = {
+  onSelectionChanged: Event<T | undefined>;
+};
+
+@singleton()
+export class SelectionService
+  implements SelectionProvider<Record<any, any> | undefined>
+{
+  private currentSelection: Record<any, any> | undefined;
+
+  protected readonly onSelectionChangedEmitter = new Emitter<any>();
+  readonly onSelectionChanged: Event<any> = this.onSelectionChangedEmitter.event;
+
+  get selection(): Record<any, any> | undefined {
+    return this.currentSelection;
+  }
+
+  set selection(selection: Record<any, any> | undefined) {
+    this.currentSelection = selection;
+    this.onSelectionChangedEmitter.fire(this.currentSelection);
+  }
+}