@tolgee/core 4.9.2 → 4.10.0-rc.14ca700.0

package/src/__test/namespacesFallback.test.ts

@@ -0,0 +1,74 @@
+import { Tolgee } from '../Tolgee';
+
+describe('namespaces fallback', () => {
+  test('works with multiple and default', () => {
+    const tolgee = Tolgee({
+      language: 'en',
+      staticData: {
+        en: { '0': 'noNamespace' },
+        'en:first': { '1': 'first' },
+        'en:second': { '2': 'second' },
+      },
+      fallbackNs: ['first', 'second'],
+    });
+
+    expect(tolgee.t({ key: '0' })).toEqual('noNamespace');
+    expect(tolgee.t({ key: '1' })).toEqual('first');
+    expect(tolgee.t({ key: '2' })).toEqual('second');
+    expect(tolgee.t({ key: '4' })).toEqual('4');
+    expect(tolgee.t({ key: '4', orEmpty: true })).toEqual('');
+  });
+
+  test('works when no fallback specified', () => {
+    const tolgee = Tolgee({
+      language: 'en',
+      staticData: {
+        en: { '0': 'noNamespace' },
+        'en:second': { '2': 'second' },
+      },
+      fallbackNs: ['first', 'second'],
+    });
+
+    expect(tolgee.t({ key: '0' })).toEqual('noNamespace');
+    expect(tolgee.t({ key: '1' })).toEqual('1');
+    expect(tolgee.t({ key: '2' })).toEqual('second');
+    expect(tolgee.t({ key: '4' })).toEqual('4');
+    expect(tolgee.t({ key: '4', orEmpty: true })).toEqual('');
+  });
+
+  test('works when data present but no fallback', () => {
+    const tolgee = Tolgee({
+      language: 'en',
+      staticData: {
+        en: { '0': 'noNamespace' },
+        'en:first': { '1': 'first' },
+        'en:second': { '2': 'second' },
+      },
+      fallbackNs: ['second'],
+    });
+
+    expect(tolgee.t({ key: '0' })).toEqual('noNamespace');
+    expect(tolgee.t({ key: '1' })).toEqual('1');
+    expect(tolgee.t({ key: '2' })).toEqual('second');
+    expect(tolgee.t({ key: '4' })).toEqual('4');
+    expect(tolgee.t({ key: '4', orEmpty: true })).toEqual('');
+  });
+
+  test('works with override', () => {
+    const tolgee = Tolgee({
+      language: 'en',
+      staticData: {
+        en: { '0': 'noNamespace' },
+        'en:first': { '1': 'first' },
+        'en:second': { '2': 'second' },
+      },
+      fallbackNs: ['second'],
+    });
+
+    expect(tolgee.t({ key: '1' })).toEqual('1');
+    expect(tolgee.t({ key: '1', ns: 'first' })).toEqual('first');
+    expect(tolgee.t({ key: '0', ns: 'first' })).toEqual('0');
+    expect(tolgee.t({ key: '2', ns: 'first' })).toEqual('2');
+    expect(tolgee.t({ key: '2', ns: 'second' })).toEqual('second');
+  });
+});

package/src/__test/plugins.test.ts

@@ -0,0 +1,98 @@
+import { Tolgee } from '../Tolgee';
+import {
+  FinalFormatterInterface,
+  FormatterInterface,
+  FormatterInterfaceFormatParams,
+  ObserverInterface,
+  TolgeePlugin,
+  WrapperWrapFunction,
+} from '../types';
+
+const testObserver =
+  (outputNotFormattable: boolean): ObserverInterface =>
+  () => {
+    const wrap: WrapperWrapFunction = ({ key, translation }) => {
+      return `${key}|${translation}`;
+    };
+    const unwrap = (input: string) => {
+      const [key, text] = input.split('|');
+      return { text, keys: [{ key }] };
+    };
+
+    const stop = () => {};
+    const run = () => {};
+
+    const retranslate = () => {};
+
+    return Object.freeze({
+      wrap,
+      unwrap,
+      run,
+      stop,
+      retranslate,
+      highlight: () => ({ unhighlight: () => {} }),
+      outputNotFormattable,
+    });
+  };
+
+const testFormatter1: FormatterInterface = {
+  format: ({ translation }: FormatterInterfaceFormatParams) => {
+    return `(1${translation})`;
+  },
+};
+
+const testFormatter2: FormatterInterface = {
+  format: ({ translation }: FormatterInterfaceFormatParams) => {
+    return `(2${translation})`;
+  },
+};
+
+const testFinalFormatter: FinalFormatterInterface = {
+  format: ({ translation }: FormatterInterfaceFormatParams) => {
+    return { final: translation };
+  },
+};
+
+const observerPlugin =
+  (outputNotFormattable: boolean): TolgeePlugin =>
+  (tolgee, tools) => {
+    tools.setObserver(testObserver(outputNotFormattable));
+    return tolgee;
+  };
+
+const formattersPlugin: TolgeePlugin = (tolgee, tools) => {
+  tools.addFormatter(testFormatter1);
+  tools.addFormatter(testFormatter2);
+  tools.setFinalFormatter(testFinalFormatter);
+  return tolgee;
+};
+
+describe('plugins', () => {
+  it('wraps and formats translation', () => {
+    const tolgee = Tolgee({
+      language: 'en',
+      staticData: { en: { hello: 'world' } },
+    });
+    tolgee.use(observerPlugin(false));
+    tolgee.run();
+    expect(tolgee.t({ key: 'hello' })).toEqual('hello|world');
+
+    tolgee.use(formattersPlugin);
+    expect(tolgee.t({ key: 'hello' })).toEqual({ final: '(2(1hello|world))' });
+    tolgee.stop();
+  });
+
+  it("won't format when observer doesn't return formattable text", () => {
+    const tolgee = Tolgee({
+      language: 'en',
+      staticData: { en: { hello: 'world' } },
+    });
+    tolgee.use(observerPlugin(true));
+    tolgee.run();
+    expect(tolgee.t({ key: 'hello' })).toEqual('hello|world');
+
+    tolgee.use(formattersPlugin);
+    expect(tolgee.t({ key: 'hello' })).toEqual('hello|world');
+    tolgee.stop();
+  });
+});

package/src/__test/testTools.ts

@@ -0,0 +1,7 @@
+export const resolvablePromise = <T = any>() => {
+  let resolve: (value: T) => void;
+  const promise = new Promise<T>((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return [promise, resolve!] as const;
+};

package/src/{Constants/Global.ts → constants.ts}

@@ -1,9 +1,7 @@
 export const RESTRICTED_ASCENDANT_ATTRIBUTE = 'data-tolgee-restricted';
-
 export const TOLGEE_ATTRIBUTE_NAME = '_tolgee';
-export const TOLGEE_TARGET_ATTRIBUTE = '_tolgee-target';
-export const TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE = 'data-tolgee-key-only';
 export const TOLGEE_HIGHLIGHTER_CLASS = '_tolgee-highlighter';
+export const TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE = 'data-tolgee-key-only';
 
 // needs to be same as in @tolgee/ui package
 export const DEVTOOLS_ID = '__tolgee_dev_tools';

package/src/helpers.ts

@@ -0,0 +1,17 @@
+export function isPromise(value: any) {
+  return Boolean(value && typeof value.then === 'function');
+}
+
+export const valueOrPromise = <T, R>(
+  value: T | Promise<T>,
+  callback: (value: T) => R
+) => {
+  if (isPromise(value)) {
+    return Promise.resolve(value).then(callback);
+  } else {
+    return callback(value as T);
+  }
+};
+
+export const missingOptionError = (option: string) =>
+  `Tolgee: You need to specify '${option}' option`;

package/src/index.ts

@@ -1,10 +1,11 @@
 export { Tolgee } from './Tolgee';
-export { TolgeeConfig } from './TolgeeConfig';
-export { ModifierKey } from './Constants/ModifierKey';
-export { TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE } from './Constants/Global';
-export * from './modules';
-export * from './types/DTOs';
+export {
+  RESTRICTED_ASCENDANT_ATTRIBUTE,
+  DEVTOOLS_ID,
+  TOLGEE_ATTRIBUTE_NAME,
+  TOLGEE_HIGHLIGHTER_CLASS,
+  TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE,
+} from './constants';
 export * from './types';
-export * from './Constants/Global';
-export * from './helpers/NodeHelper';
-export * from './helpers/TextHelper';
+export { getTranslateParams } from './TranslateParams';
+export { getFallback, getFallbackArray } from './Controller/State/helpers';

package/src/types.ts

@@ -1,96 +1,279 @@
-export interface TextInputElementData {
-  oldValue: string;
-  valueInputs: string[];
-  touched: boolean;
-  oldPlaceholder: string;
-  placeholderInputs: string[];
-}
+import type { Options } from './Controller/State/initState';
 
-export type TreeTranslationsData = {
-  [key: string]: string | TreeTranslationsData;
-};
+export type { State, Options } from './Controller/State/initState';
+export type { EventEmitterType } from './Controller/Events/EventEmitter';
+export type { EventEmitterSelectiveType } from './Controller/Events/EventEmitterSelective';
 
-export type Translations = Record<string, string>;
-export type TranslationParams = {
-  [key: string]: string | number | bigint;
-};
-export type TranslationParamsTags<T> = {
-  [key: string]: string | number | bigint | ((value: T | T[]) => T);
-};
+export type FallbackGeneral = undefined | false | string | string[];
 
-export type TranslateProps = {
-  key: string;
-  defaultValue?: string;
-  params?: TranslationParams;
+export type FallbackNS = FallbackGeneral;
+
+export type NsType = string;
+
+export type KeyType = string;
+
+export type FallbackNSTranslation = undefined | NsType | NsType[];
+
+export type FallbackLanguage = FallbackGeneral;
+
+export type FallbackLanguageObject = Record<string, FallbackLanguage>;
+
+export type FallbackLanguageOption = FallbackLanguage | FallbackLanguageObject;
+
+export type TranslateOptions<T> = {
+  ns?: FallbackNSTranslation;
   noWrap?: boolean;
   orEmpty?: boolean;
+  params?: TranslateParams<T>;
 };
-export type TranslatePropsTags<T> = {
-  key: string;
+
+export type TranslateProps<T = DefaultParamType> = {
+  key: KeyType;
   defaultValue?: string;
-  params?: TranslationParamsTags<T>;
-  noWrap?: boolean;
-  orEmpty?: boolean;
+} & TranslateOptions<T>;
+
+export type TranslatePropsInternal = TranslateProps & {
+  translation?: string;
 };
 
-export type InstantProps = {
-  key: string;
-  defaultValue?: string;
-  params?: TranslationParams;
-  noWrap?: boolean;
-  orEmpty?: boolean;
+export type TranslationValue = string | undefined | null;
+
+export type TranslationsFlat = Map<string, TranslationValue>;
+
+export type TreeTranslationsData = {
+  [key: string]: TranslationValue | TreeTranslationsData;
 };
-export type InstantPropsTags<T> = {
-  key: string;
-  defaultValue?: string;
-  params?: TranslationParamsTags<T>;
-  noWrap?: boolean;
-  orEmpty?: boolean;
+
+export type CacheAsyncRequests = Map<
+  string,
+  Promise<TreeTranslationsData | undefined> | undefined
+>;
+
+export type CacheDescriptor = {
+  language: string;
+  namespace?: string;
+};
+
+export type CacheDescriptorInternal = {
+  language: string;
+  namespace: string;
+};
+
+export type CacheDescriptorWithKey = CacheDescriptorInternal & {
+  key?: string;
 };
 
 export type KeyAndParams = {
   key: string;
-  params: TranslationParams;
+  params?: TranslateParams;
   defaultValue?: string;
+  ns?: FallbackNSTranslation;
 };
-export type KeyAndParamsTags<T> = {
-  key: string;
-  params: TranslationParamsTags<T>;
-  defaultValue?: string;
+
+export type Unwrapped = { text: string; keys: KeyAndParams[] };
+
+type PropType<TObj> = TObj[keyof TObj];
+
+export type DefaultParamType = string | number | bigint;
+
+export type TranslateParams<T = DefaultParamType> = {
+  [key: string]: T;
 };
 
-export type TranslatedWithMetadata = {
-  translated: string;
-  key: string;
-  params: TranslationParams;
-  defaultValue: string | undefined;
+export type CombinedOptions<T> = TranslateOptions<T> & {
+  [key: string]: T | PropType<TranslateOptions<T>>;
 };
-export type TranslatedWithMetadataTags<T> = {
-  translated: TranslationTags<T>;
-  key: string;
-  params: TranslationParamsTags<T>;
-  defaultValue: string | undefined;
+
+export type TFnType<T = DefaultParamType, R = string> = {
+  (key: string, defaultValue?: string, options?: CombinedOptions<T>): R;
+  (key: string, options?: CombinedOptions<T>): R;
+  (props: TranslateProps<T>): R;
+};
+
+export type WrapperWrapProps = Pick<
+  TranslatePropsInternal,
+  'key' | 'params' | 'defaultValue' | 'ns' | 'translation'
+>;
+export type WrapperWrapFunction = (props: WrapperWrapProps) => string;
+export type WrapperUnwrapFunction = (text: string) => Unwrapped;
+
+export type WrapperAttributeXPathGetter = (props: {
+  tag: string;
+  attribute: string;
+}) => string;
+
+export type WrapperInterface = {
+  unwrap: WrapperUnwrapFunction;
+  wrap: WrapperWrapFunction;
+  getTextXPath: () => string;
+  getAttributeXPath: WrapperAttributeXPathGetter;
+};
+
+export type FormatterInterfaceFormatParams = {
+  translation: string;
+  language: string;
+  params: Record<string, any> | undefined;
+};
+
+export type FormatterInterface = {
+  format: (props: FormatterInterfaceFormatParams) => string;
+};
+
+export type FinalFormatterInterface = {
+  format: (props: FormatterInterfaceFormatParams) => any;
+};
+
+export type ObserverProps = {
+  translate: (params: TranslatePropsInternal) => string;
+  onClick: TranslationOnClick;
+};
+
+export type HighlightInterface = (
+  key?: string,
+  ns?: FallbackNSTranslation
+) => {
+  unhighlight(): void;
+};
+
+export type ObserverRunProps = {
+  mouseHighlight: boolean;
 };
 
-export type TranslationTags<T> = string | T[];
+export type ObserverInterface = (props: ObserverProps) => {
+  unwrap: (text: string) => Unwrapped;
+  wrap: WrapperWrapFunction;
+  retranslate: () => void;
+  stop: () => void;
+  run: (props: ObserverRunProps) => void;
+  highlight: HighlightInterface;
+  outputNotFormattable: boolean;
+};
 
-export type NodeWithMeta = Node & {
-  _tolgee: NodeMeta;
+export type LanguageDetectorProps = {
+  availableLanguages: string[];
 };
 
-export type NodeWithLock = Node & {
-  _tolgee: NodeLock;
+export type LanguageDetectorInterface = {
+  getLanguage: (
+    props: LanguageDetectorProps
+  ) => string | undefined | Promise<string | undefined>;
+};
+
+export type LanguageStorageInterface = {
+  getLanguage: () => string | undefined | Promise<string | undefined>;
+  setLanguage: (language: string) => void | Promise<void>;
+};
+
+export type BackendDevProps = {
+  apiUrl?: string;
+  apiKey?: string;
+  projectId?: number;
+};
+
+export type BackendGetRecordProps = {
+  language: string;
+  namespace?: string;
 };
 
-export type ElementWithMeta = Element &
-  ElementCSSInlineStyle & {
-    _tolgee: ElementMeta;
-  };
+export type BackendGetRecord = (
+  data: BackendGetRecordProps
+) => Promise<TreeTranslationsData | undefined> | undefined;
+
+export interface BackendInterface {
+  getRecord: BackendGetRecord;
+}
+
+export type BackendGetDevRecord = (
+  data: BackendGetRecordProps & BackendDevProps
+) => Promise<TreeTranslationsData | undefined> | undefined;
+
+export type BackendDevInterface = {
+  getRecord: BackendGetDevRecord;
+};
+
+export type TolgeeEvent =
+  | 'pendingLanguage'
+  | 'language'
+  | 'key'
+  | 'loading'
+  | 'fetching'
+  | 'initialLoad'
+  | 'running'
+  | 'cache'
+  | 'keyUpdate';
+
+export type TolgeeOn = {
+  (event: 'pendingLanguage', handler: ListenerHandler<string>): Listener;
+  (event: 'language', handler: ListenerHandler<string>): Listener;
+  (event: 'key', handler: ListenerHandler<string>): Listener;
+  (event: 'loading', handler: ListenerHandler<boolean>): Listener;
+  (event: 'fetching', handler: ListenerHandler<boolean>): Listener;
+  (event: 'initialLoad', handler: ListenerHandler<void>): Listener;
+  (event: 'running', handler: ListenerHandler<boolean>): Listener;
+  (event: 'keyUpdate', handler: ListenerHandler<void>): Listener;
+  (event: TolgeeEvent, handler: ListenerHandler<any>): Listener;
+};
+
+export type TolgeeInstance = Readonly<{
+  on: TolgeeOn;
+  onKeyUpdate: (handler: ListenerHandler<void>) => ListenerSelective;
+
+  use: (plugin: TolgeePlugin | undefined) => TolgeeInstance;
+
+  getLanguage: () => string | undefined;
+  getPendingLanguage: () => string | undefined;
+  changeLanguage: (language: string) => Promise<void>;
+  changeTranslation: ChangeTranslationInterface;
+  addActiveNs: (ns: FallbackNSTranslation, forget?: boolean) => Promise<void>;
+  removeActiveNs: (ns: FallbackNSTranslation) => void;
+  loadRecords: (descriptors: CacheDescriptor[]) => Promise<TranslationsFlat[]>;
+  loadRecord: (descriptors: CacheDescriptor) => Promise<TranslationsFlat>;
+  addStaticData: (data: Options['staticData']) => void;
+  getRecord: (descriptor: CacheDescriptor) => TranslationsFlat | undefined;
+  getAllRecords: () => CachePublicRecord[];
+  isInitialLoading: () => boolean;
+  isLoading: (ns?: FallbackNSTranslation) => boolean;
+  isLoaded: (ns?: FallbackNSTranslation) => boolean;
+  isFetching: (ns?: FallbackNSTranslation) => boolean;
+  isRunning: () => boolean;
+  highlight: HighlightInterface;
+  getInitialOptions: () => Options;
+  isDev: () => boolean;
+  init: (options: Partial<Options>) => TolgeeInstance;
+  run: () => Promise<void>;
+  stop: () => void;
+  t: TFnType;
+  wrap: (params: TranslatePropsInternal) => string | undefined;
+  unwrap: (text: string) => Unwrapped;
+}>;
+
+export type PluginServicePublic = Readonly<{
+  setFinalFormatter: (formatter: FinalFormatterInterface | undefined) => void;
+  addFormatter: (formatter: FormatterInterface | undefined) => void;
+  setObserver: (observer: ObserverInterface | undefined) => void;
+  getObserver: () => ReturnType<ObserverInterface> | undefined;
+  setUi: (ui: UiLibInterface | undefined) => void;
+  getUi: () => UiConstructor | undefined;
+  addBackend: (backend: BackendInterface | undefined) => void;
+  setDevBackend: (backend: BackendInterface | undefined) => void;
+  setLanguageDetector: (
+    languageDetector: LanguageDetectorInterface | undefined
+  ) => void;
+  setLanguageStorage: (
+    languageStorage: LanguageStorageInterface | undefined
+  ) => void;
+}>;
+
+export type NodeMeta = {
+  oldTextContent: string;
+  keys: KeyAndParams[];
+  keyAttributeOnly?: boolean;
+};
 
 export type ElementMeta = {
   wrappedWithElementOnlyKey?: string;
   wrappedWithElementOnlyDefaultHtml?: string;
-  nodes: Set<NodeWithMeta>;
+  nodes: Map<Node, NodeMeta>;
   highlightEl?: HTMLDivElement;
   highlight?: () => void;
   unhighlight?: () => void;
@@ -104,43 +287,92 @@ export type ElementMeta = {
    * Triggering highlight needs the metadata stored on element, so
    * we need the ability to prevent clean.
    */
+
   preventClean?: boolean;
 };
 
-export type NodeMeta = {
-  oldTextContent: string;
-  keys: KeyAndParamsTags<any>[];
-} & NodeLock;
+export type ChangeTranslationInterface = (
+  descriptor: CacheDescriptor,
+  key: string,
+  value: string
+) => { revert: () => void };
 
-export type NodeLock = {
-  locked?: boolean;
+export type UiProps = {
+  apiUrl: string;
+  apiKey: string;
+  highlight: HighlightInterface;
+  changeTranslation: ChangeTranslationInterface;
 };
 
-export type Scope =
-  | 'translations.edit'
-  | 'translations.view'
-  | 'keys.edit'
-  | 'screenshots.upload'
-  | 'screenshots.view'
-  | 'screenshots.delete';
+export interface UiInterface {
+  handleElementClick(
+    event: MouseEvent,
+    keysAndDefaults: UiKeyOption[]
+  ): Promise<void>;
+}
 
-export type Mode = 'development' | 'production';
+export type UiConstructor = new (props: UiProps) => UiInterface;
 
-export type Unwrapped = { text: string; keys: KeyAndParamsTags<any>[] };
+export type UiLibInterface = {
+  UI: UiConstructor;
+};
 
-export interface Formatter {
-  format: FormatFunction;
-}
+export type UiType = UiConstructor | UiLibInterface;
 
-interface FormatterStatic {
-  type: 'formatter';
-  new (): Formatter;
-}
+export type UiKeyOption = {
+  key: string;
+  defaultValue?: string;
+  ns: FallbackNSTranslation;
+  translation: string | undefined;
+};
 
-export type TolgeeModule = FormatterStatic;
+export type KeyWithDefault = {
+  key: string;
+  defaultValue?: string;
+  ns: FallbackNSTranslation;
+};
 
-export type FormatFunction = (props: {
-  translation: string;
-  params: Record<string, any>;
+export type TranslationOnClick = (
+  event: MouseEvent,
+  data: {
+    keysAndDefaults: KeyWithDefault[];
+    el: Element;
+    meta: ElementMeta;
+  }
+) => void;
+
+export type Listener = {
+  unsubscribe: () => void;
+};
+
+export type KeyDescriptorInternal = {
+  key?: string;
+  ns?: string[] | undefined;
+};
+
+export type KeyDescriptor = {
+  key: string;
+  ns?: string | string[];
+};
+
+export type ListenerSelective = {
+  unsubscribe: () => void;
+  subscribeNs: (ns: FallbackNSTranslation) => ListenerSelective;
+  unsubscribeNs: (ns: FallbackNSTranslation) => ListenerSelective;
+  subscribeKey: (descriptor: KeyDescriptor) => ListenerSelective;
+  unsubscribeKey: (descriptor: KeyDescriptor) => ListenerSelective;
+};
+
+export type ListenerHandlerEvent<T> = { value: T };
+export type ListenerHandler<T> = (e: ListenerHandlerEvent<T>) => void;
+
+export type TolgeePlugin = (
+  tolgee: TolgeeInstance,
+  tools: PluginServicePublic
+) => TolgeeInstance;
+
+export type CachePublicRecord = {
+  data: TranslationsFlat;
   language: string;
-}) => string | any[];
+  namespace: string;
+};