@difizen/libro-common 0.3.4 → 1.0.0

package/src/l10n/l10n/index.ts

@@ -0,0 +1,319 @@
+/* eslint-disable @typescript-eslint/unified-signatures */
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { locale } from './platform';
+/**
+ * forked from vscode l10n
+ */
+
+/**
+ * @public
+ * The format of a message in a bundle.
+ */
+export type l10nJsonMessageFormat =
+  | string
+  | {
+      message: string;
+      comment: string[];
+    };
+
+export type LangChangeEvent = (lang: L10nLang) => void;
+
+/**
+ * @public
+ * The format of package.nls.json and l10n bundle files.
+ */
+export type l10nJsonFormat = Record<string, l10nJsonMessageFormat>;
+
+export type LanguageBundles = Record<L10nLang, l10nJsonFormat>;
+
+export enum L10nLang {
+  zhCN = 'zh-CN',
+  enUS = 'en-US',
+}
+
+function getDefaultlang() {
+  let localeValue = locale;
+  if (typeof navigator === 'object') {
+    localeValue = localStorage?.getItem('locale') || locale;
+  }
+  const localeStr = localeValue.toLowerCase();
+  if (localeStr === 'zh' || localeStr.startsWith('zh-')) {
+    return L10nLang.zhCN;
+  }
+  return L10nLang.enUS;
+}
+
+export class Localization {
+  static create(name: string) {
+    return new Localization(name);
+  }
+
+  protected moduleName: string | undefined;
+
+  protected bundle: l10nJsonFormat | undefined;
+
+  protected bundles: Map<L10nLang, l10nJsonFormat> = new Map();
+
+  protected lang = getDefaultlang();
+
+  protected deps: Localization[] = [];
+
+  get name() {
+    return this.moduleName;
+  }
+
+  constructor(name?: string) {
+    this.moduleName = name;
+  }
+
+  protected langChangeHandlers: LangChangeEvent[] = [];
+
+  onLangChange(handler: LangChangeEvent) {
+    this.langChangeHandlers.push(handler);
+  }
+
+  /**
+   * 被依赖的l10n会同步主包的lang, 语言包是独立的
+   * 建议模块级别的l10n作为默认l10n的依赖，这样使用默认l10n可以统一的切换语言
+   * @param modules
+   */
+  dependOn(...modules: Localization[]) {
+    this.deps.push(...modules);
+    this.syncDepsLang();
+  }
+
+  /**
+   *
+   */
+  syncDepsLang() {
+    this.deps.forEach((dep) => {
+      dep.changeLang(this.lang);
+      dep.syncDepsLang();
+    });
+  }
+
+  getLang() {
+    return this.lang;
+  }
+
+  /**
+   * 加载语言文件包
+   * @param bundles
+   */
+  loadLangBundles(bundles: LanguageBundles) {
+    for (const lang in bundles) {
+      this.loadLang(lang as L10nLang, { contents: bundles[lang as L10nLang] });
+    }
+  }
+
+  /**
+   * 加载单一语言
+   * @param lang
+   * @param option
+   */
+  loadLang(lang: L10nLang, option: { contents: string | l10nJsonFormat }) {
+    const bundle = this.load(option);
+    if (bundle) {
+      if (this.bundles.has(lang)) {
+        const current = this.bundles.get(lang);
+        this.bundles.set(lang, { ...current, ...bundle });
+      } else {
+        this.bundles.set(lang, bundle);
+      }
+    }
+
+    this.changeLang(this.lang);
+  }
+
+  changeLang(lang: L10nLang) {
+    localStorage.setItem('locale', lang);
+    const bundle = this.bundles.get(lang);
+    this.lang = lang;
+    this.bundle = bundle;
+    this.syncDepsLang();
+    this.langChangeHandlers.forEach((handler) => handler(this.lang));
+  }
+
+  removeLang(lang: L10nLang) {
+    this.bundles.delete(lang);
+  }
+
+  /**
+   * Loads the bundle from the given contents. Must be run before the first call to any `l10n.t()` variant.
+   * **Note** The best way to set this is to pass the value of the VS Code API `vscode.l10n.contents`
+   * to the process that uses `@vscode/l10n`.
+   * @param option - An object that contains one property, contents, which should contain the contents of the bundle.
+   */
+  protected load(option: {
+    contents: string | l10nJsonFormat;
+  }): l10nJsonFormat | undefined {
+    let bundle: l10nJsonFormat | undefined;
+    if ('contents' in option) {
+      if (typeof option.contents === 'string') {
+        bundle = JSON.parse(option.contents);
+      } else {
+        bundle = option.contents;
+      }
+    }
+    return bundle;
+  }
+
+  /**
+   * @public
+   * Marks a string for localization. If the bundle has a localized value for this message, then that localized
+   * value will be returned (with injected `args` values for any templated values).
+   * @param message - The message to localize. Supports index templating where strings like `{0}` and `{1}` are
+   * replaced by the item at that index in the `args` array.
+   * @param args - The arguments to be used in the localized string. The index of the argument is used to
+   * match the template placeholder in the localized string.
+   * @returns localized string with injected arguments.
+   * @example `l10n.localize('hello', 'Hello {0}!', 'World');`
+   */
+  t(message: string, ...args: L10nReplacement[]): string;
+  /**
+   * @public
+   * Marks a string for localization. If the bundle has a localized value for this message, then that localized
+   * value will be returned (with injected `args` values for any templated values).
+   * @param message - The message to localize. Supports named templating where strings like `{foo}` and `{bar}` are
+   * replaced by the value in the Record for that key (foo, bar, etc).
+   * @param args - The arguments to be used in the localized string. The name of the key in the record is used to
+   * match the template placeholder in the localized string.
+   * @returns localized string with injected arguments.
+   * @example `l10n.t('Hello {name}', { name: 'Erich' });`
+   */
+  t(message: string, args: Record<string, L10nReplacement>): string;
+
+  /**
+   * @public
+   * Marks a string for localization. This function signature is made for usage
+   * with tagged template literals.
+   *
+   * The more verbose overload should still be used if comments are required.
+   * @example
+   * ```
+   * l10n.t`Hello ${name}!`
+   * ```
+   * @param message - String message components
+   * @param args - Replacement components in the string
+   * @returns localized string with injected arguments.
+   */
+  t(strs: TemplateStringsArray, ...replacements: L10nReplacement[]): string;
+
+  /**
+   * @public
+   * Marks a string for localization. If the bundle has a localized value for this message, then that localized
+   * value will be returned (with injected args values for any templated values).
+   * @param options - The options to use when localizing the message.
+   * @returns localized string with injected arguments.
+   */
+  t(options: {
+    /**
+     * The message to localize. If `args` is an array, this message supports index templating where strings like
+     * `{0}` and `{1}` are replaced by the item at that index in the `args` array. If `args` is a `Record<string, any>`,
+     * this supports named templating where strings like `{foo}` and `{bar}` are replaced by the value in
+     * the Record for that key (foo, bar, etc).
+     */
+    message: string;
+    /**
+     * The arguments to be used in the localized string. As an array, the index of the argument is used to
+     * match the template placeholder in the localized string. As a Record, the key is used to match the template
+     * placeholder in the localized string.
+     */
+    args?: (string | number | boolean)[] | Record<string, any>;
+    /**
+     * A comment to help translators understand the context of the message.
+     */
+    comment: string | string[];
+  }): string;
+  t(
+    ...args:
+      | [str: string, ...args: (string | number | boolean)[]]
+      | [message: string, args: Record<string, any>]
+      | [message: TemplateStringsArray, ...args: L10nReplacement[]]
+      | [
+          options: {
+            message: string;
+            args?: (string | number | boolean)[] | Record<string, any>;
+            comment?: string | string[];
+          },
+        ]
+  ): string {
+    const firstArg = args[0];
+    let key: string;
+    let message: string;
+    let formatArgs: (string | number)[] | Record<string, any> | undefined;
+    if (typeof firstArg === 'string') {
+      key = firstArg;
+      message = firstArg;
+      args.splice(0, 1);
+      formatArgs = !args || typeof args[0] !== 'object' ? args : args[0];
+    } else if (firstArg instanceof Array) {
+      const replacements = args.slice(1) as L10nReplacement[];
+      if (firstArg.length !== replacements.length + 1) {
+        throw new Error('expected a string as the first argument to l10n.t');
+      }
+
+      let str = firstArg[0]!; // implied strs.length > 0 since replacements.length >= 0
+      for (let i = 1; i < firstArg.length; i++) {
+        str += `{${i - 1}}` + firstArg[i];
+      }
+
+      return this.t(str, ...replacements);
+    } else {
+      message = firstArg.message;
+      key = message;
+      if (firstArg.comment && firstArg.comment.length > 0) {
+        // in the format: message/commentcommentcomment
+        key += `/${
+          Array.isArray(firstArg.comment) ? firstArg.comment.join('') : firstArg.comment
+        }`;
+      }
+      formatArgs = (firstArg.args as any[]) ?? {};
+    }
+
+    const messageFromBundle = this.bundle?.[key];
+    if (!messageFromBundle) {
+      return format(message, formatArgs as Record<string, unknown>);
+    }
+
+    if (typeof messageFromBundle === 'string') {
+      return format(messageFromBundle, formatArgs as Record<string, unknown>);
+    }
+
+    if (messageFromBundle.comment) {
+      return format(messageFromBundle.message, formatArgs as Record<string, unknown>);
+    }
+    console.info('format', message, formatArgs);
+    return format(message, formatArgs as Record<string, unknown>);
+  }
+}
+
+/**
+ * @public
+ * Type that can be used as replacements in `l10n.t()` calls.
+ */
+export type L10nReplacement = string | number | boolean;
+
+const _format2Regexp = /{([^}]+)}/g;
+
+/**
+ * Helper to create a string from a template and a string record.
+ * Similar to `format` but with objects instead of positional arguments.
+ *
+ * Copied from https://github.com/microsoft/vscode/blob/5dfca53892a1061b1c103542afe49d51f1041778/src/vs/base/common/strings.ts#L44
+ */
+function format(template: string, values: Record<string, unknown>): string {
+  return template.replace(
+    _format2Regexp,
+    (match, group) => (values[group] ?? match) as string,
+  );
+}
+
+/**
+ * 默认的l10n
+ */
+export const l10n = new Localization();

package/src/l10n/l10n/platform.ts

@@ -0,0 +1,51 @@
+// This is also implemented in mana-common, but it will not be introduced for now.
+// Keep this package simple.
+
+export type IProcessEnvironment = Record<string, string>;
+interface INodeProcess {
+  platform: 'win32' | 'linux' | 'darwin';
+  env: IProcessEnvironment;
+  nextTick: () => void;
+  versions?: {
+    electron?: string;
+  };
+  sandboxed?: boolean; // Electron
+  type?: string;
+  cwd: () => string;
+}
+
+declare const process: INodeProcess;
+declare const global: any;
+
+interface INavigator {
+  userAgent: string;
+  language: string;
+  maxTouchPoints?: number;
+}
+declare const navigator: INavigator;
+declare const self: any;
+const _globals =
+  typeof self === 'object' ? self : typeof global === 'object' ? global : ({} as any);
+
+let nodeProcess: INodeProcess | undefined;
+if (typeof process !== 'undefined') {
+  // Native environment (non-sandboxed)
+  nodeProcess = process;
+} else if (typeof _globals.vscode !== 'undefined') {
+  // Native environment (sandboxed)
+  nodeProcess = _globals.vscode.process;
+}
+
+const isElectronRenderer =
+  typeof nodeProcess?.versions?.electron === 'string' &&
+  nodeProcess.type === 'renderer';
+
+let _locale: string | undefined = 'en';
+
+if (typeof navigator === 'object' && !isElectronRenderer) {
+  _locale = ((navigator as any).languages as string)
+    ? ((navigator as any).languages[0] as string)
+    : navigator.language || ((navigator as any).userLanguage as string);
+}
+
+export const locale = _locale;

package/src/l10n/lang/bundle.l10n.en-US.json

@@ -0,0 +1,5 @@
+{
+  "关闭": "Close",
+  "更多": "More",
+  "文件": "File"
+}

package/src/l10n/lang/bundle.l10n.zh-CN.json

@@ -0,0 +1,5 @@
+{
+  "关闭": "关闭",
+  "更多": "更多",
+  "文件": "文件"
+}

package/src/l10n/lang/index.ts

@@ -0,0 +1,9 @@
+import type { LanguageBundles } from '../l10n';
+
+import langENUS from './bundle.l10n.en-US.json';
+import langZHCN from './bundle.l10n.zh-CN.json';
+
+export const langBundles: LanguageBundles = {
+  'zh-CN': langZHCN,
+  'en-US': langENUS,
+};

package/src/observable/async-event.spec.tsx

@@ -0,0 +1,64 @@
+import assert from 'assert';
+
+import { noop } from '../common/index.js';
+
+import { AsyncEmitter, AsyncCallbackList } from './async-event';
+
+describe('AsyncEvent', () => {
+  it('#callback list', (done) => {
+    try {
+      const list = new AsyncCallbackList();
+      list.invoke();
+      done();
+    } catch (e) {
+      done(e);
+    }
+  });
+
+  it('#event basic', (done) => {
+    let test = false;
+    let asyncTest = false;
+    const emitter = new AsyncEmitter<void>();
+    emitter.event(() => {
+      test = true;
+    });
+    emitter.eventAsync(() => {
+      asyncTest = true;
+    });
+    emitter.fire();
+    Promise.resolve()
+      .then(() => {
+        assert(test);
+        assert(asyncTest);
+        done();
+        return;
+      })
+      .catch((e) => done(e));
+  });
+  it('#event hooks', () => {
+    let added = false;
+    const emitter = new AsyncEmitter<void>({
+      onFirstListenerAdd: () => {
+        added = true;
+      },
+      onLastListenerRemove: () => {
+        added = false;
+      },
+    });
+    const toDispose = emitter.eventAsync(noop);
+    assert(added);
+    toDispose.dispose();
+    assert(!added);
+  });
+
+  it('#event dispose', () => {
+    let test = false;
+    const emitter = new AsyncEmitter<void>();
+    emitter.eventAsync(() => {
+      test = true;
+    });
+    emitter.dispose();
+    emitter.fire();
+    assert(!test);
+  });
+});

package/src/observable/async-event.ts

@@ -0,0 +1,110 @@
+import type { Disposable, Event } from '../common/index.js';
+import { Emitter, noop } from '../common/index.js';
+import { CallbackList } from '../common/index.js';
+
+type Callback = (...args: any[]) => any;
+
+export class AsyncCallbackList extends CallbackList {
+  protected called: Callback[] | undefined = undefined;
+
+  public override invoke(...args: any[]): any[] {
+    const ret: any[] = [];
+    if (!this._callbacks) {
+      return [];
+    }
+    if (!this.called) {
+      this.called = [];
+    }
+    const callbacks = this._callbacks?.slice(0);
+    for (const [callback, ctx] of callbacks) {
+      try {
+        let promise;
+        if (!this.called.includes(callback)) {
+          this.called.push(callback);
+          promise = Promise.resolve().then(() => {
+            callback.apply(ctx, args);
+            this.called = undefined;
+            return;
+          });
+        }
+        ret.push(promise);
+      } catch (e) {
+        console.error(e);
+      }
+    }
+    return ret;
+  }
+}
+
+export type EmitterOptions = {
+  onFirstListenerAdd?: (ctx: any) => void;
+  onLastListenerRemove?: (ctx: any) => void;
+};
+
+export class AsyncEmitter<T = any> extends Emitter {
+  protected _asyncCallbacks: CallbackList | undefined;
+  protected _eventAsync?: Event<T>;
+
+  /**
+   * For the public to allow to subscribe
+   * to events from this Emitter
+   */
+  get eventAsync(): Event<T> {
+    if (!this._eventAsync) {
+      this._eventAsync = (listener: (e: T) => any, context?: any) => {
+        const callbacks = () => {
+          if (!this._asyncCallbacks) {
+            this._asyncCallbacks = new AsyncCallbackList();
+          }
+          return this._asyncCallbacks;
+        };
+        const callbackList = callbacks();
+        if (
+          this._options &&
+          this._options.onFirstListenerAdd &&
+          callbackList.isEmpty()
+        ) {
+          this._options.onFirstListenerAdd(this);
+        }
+        callbackList.add(listener, context);
+
+        const result: Disposable = {
+          dispose: () => {
+            result.dispose = noop;
+            if (!this._disposed) {
+              callbacks().remove(listener, context);
+              result.dispose = noop;
+              if (
+                this._options &&
+                this._options.onLastListenerRemove &&
+                callbacks().isEmpty()
+              ) {
+                this._options.onLastListenerRemove(this);
+              }
+            }
+          },
+        };
+        return result;
+      };
+    }
+    return this._eventAsync;
+  }
+
+  /**
+   * fire an event to subscribers
+   */
+  override fire(event: T): any {
+    super.fire(event);
+    if (this._asyncCallbacks) {
+      this._asyncCallbacks.invoke(event);
+    }
+  }
+
+  override dispose(): void {
+    if (this._asyncCallbacks) {
+      this._asyncCallbacks.dispose();
+      this._asyncCallbacks = undefined;
+    }
+    super.dispose();
+  }
+}

package/src/observable/async.spec.tsx

@@ -0,0 +1,142 @@
+import assert from 'assert';
+
+import type { ReactElement } from 'react';
+import renderer, { act } from 'react-test-renderer';
+
+import {
+  ObservableConfig,
+  prop,
+  useObserve,
+  Notifier,
+  observable,
+  watch,
+} from './index';
+
+describe('Async', () => {
+  beforeAll(() => {
+    ObservableConfig.async = true;
+  });
+  afterAll(() => {
+    ObservableConfig.async = false;
+  });
+
+  it('#async trigger', (done) => {
+    class Foo {
+      @prop() name?: string;
+    }
+    const foo = observable(new Foo());
+    let changedTimes = 0;
+    const notifier = Notifier.find(foo, 'name');
+    notifier?.onChange(() => {
+      changedTimes += 1;
+    });
+    Notifier.trigger(foo, 'name');
+    Notifier.trigger(foo, 'name');
+    Notifier.trigger(foo, 'name');
+    Promise.resolve()
+      .then(() => {
+        assert(changedTimes === 1);
+        done();
+        return;
+      })
+      .catch((e) => {
+        done(e);
+      });
+  });
+
+  it('#watch allways listen sync', (done) => {
+    class Foo {
+      @prop() name?: string;
+    }
+    const foo = observable(new Foo());
+    let changedTimes = 0;
+    let watchChangeTimes = 0;
+    const notifier = Notifier.find(foo, 'name');
+    notifier?.onChange(() => {
+      changedTimes += 1;
+    });
+    watch(foo, 'name', () => {
+      watchChangeTimes += 1;
+    });
+
+    Notifier.trigger(foo, 'name');
+    Notifier.trigger(foo, 'name');
+    Notifier.trigger(foo, 'name');
+    try {
+      assert(watchChangeTimes === 3);
+    } catch (e) {
+      done(e);
+    }
+    Promise.resolve()
+      .then(() => {
+        assert(changedTimes === 1);
+        done();
+        return;
+      })
+      .catch((e) => {
+        done(e);
+      });
+  });
+
+  it('#async trigger array', (done) => {
+    class Foo {
+      @prop() arr: number[] = [1, 2, 3];
+    }
+    const foo = observable(new Foo());
+    let times = 0;
+    const notifier = Notifier.find(foo, 'arr');
+    notifier?.onChange(() => {
+      times += 1;
+    });
+    foo.arr.push(1);
+    foo.arr.splice(1, 1);
+    Promise.resolve()
+      .then(() => {
+        assert(times === 1);
+        done();
+        return;
+      })
+      .catch((e) => {
+        done(e);
+      });
+  });
+  it('#async useObserve array', (done) => {
+    class Foo {
+      @prop() list: number[] = [1, 2, 3];
+    }
+    const foo = new Foo();
+    let renderTimes = 0;
+    const FooRender = () => {
+      const f = useObserve(foo);
+      renderTimes += 1;
+      return <div>{f.list.length}</div>;
+    };
+    let component: renderer.ReactTestRenderer;
+    act(() => {
+      const element = (
+        <>
+          <FooRender />
+        </>
+      );
+      component = renderer.create(element as ReactElement);
+      const json = component.toJSON();
+      assert(json === null);
+    });
+    // eslint-disable-next-line promise/catch-or-return
+    act(() => {
+      foo.list.push(1);
+      foo.list.splice(1, 1);
+    }).then(
+      (e) => {
+        assert(renderTimes === 2);
+        done();
+        return e;
+      },
+      (e) => {
+        console.error(e);
+        done(e);
+        return e;
+      },
+    );
+  });
+});