@tolgee/core 4.9.2 → 5.0.0-rc.0b3e627.0

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,281 @@
-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 './Events/EventEmitter';
+export type { EventEmitterSelectiveType } from './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: CacheDescriptorInternal
+  ) => 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: (props: TranslatePropsInternal) => string;
+  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 +289,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: string[];
+  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;
+};

package/README.md

@@ -1,45 +0,0 @@
-# Tolgee core library
-
-![test workflow](https://github.com/tolgee/tolgee-js/actions/workflows/test.yml/badge.svg)
-![@tolgee/core version](https://img.shields.io/npm/v/@tolgee/core?label=%40tolgee%2Fcore)
-![types typescript](https://img.shields.io/badge/Types-Typescript-blue)
-[![twitter](https://img.shields.io/twitter/follow/Tolgee_i18n?style=social)](https://twitter.com/Tolgee_i18n)
-[![github stars](https://img.shields.io/github/stars/tolgee/tolgee-js?style=social)](https://github.com/tolgee/tolgee-js)
-
-[<img src="https://raw.githubusercontent.com/tolgee/documentation/main/tolgee_logo_text.svg" alt="Tolgee" width="200" />](https://tolgee.io)
-
-Core library of Tolgee localization toolkit. For more information about Tolgee Toolkit, visit our documentation website
-[toolkit.tolgee.io](https://toolkit.tolgee.io).
-
-## Installation
-
-    npm install @tolgee/core --save
-
-## Usage
-
-First, create a Tolgee instance and run it.
-
-    import {Tolgee} from "@tolgee/core";
-
-    const tg = Tolgee.init({
-        apiKey: "your_api_key",
-        apiUrl: "https://app.tolgee.io",
-    })
-
-    tg.run();
-
-Then, use it to translate your strings.
-
-    tg.onLangLoaded.subscribe(() => {
-        document.title = tg.translate("hello_world");
-    });
-
-## Features
-
-- All in One localization solution for your JS application 🙌
-- Out of box in-context localization 🎉
-- Automated screenshot generation 📷
-- Translation management platform 🎈
-- Open-source 🔥
-
-To learn more, check [Hello World example](https://toolkit.tolgee.io/docs/web/get_started/hello_world).

package/dist/Constants/Global.d.ts

@@ -1,6 +0,0 @@
-export declare const RESTRICTED_ASCENDANT_ATTRIBUTE = "data-tolgee-restricted";
-export declare const TOLGEE_ATTRIBUTE_NAME = "_tolgee";
-export declare const TOLGEE_TARGET_ATTRIBUTE = "_tolgee-target";
-export declare const TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE = "data-tolgee-key-only";
-export declare const TOLGEE_HIGHLIGHTER_CLASS = "_tolgee-highlighter";
-export declare const DEVTOOLS_ID = "__tolgee_dev_tools";

package/dist/Constants/ModifierKey.d.ts

@@ -1,6 +0,0 @@
-export declare enum ModifierKey {
-    Alt = 0,
-    Control = 1,
-    Shift = 2,
-    Meta = 3
-}

package/dist/Errors/ApiHttpError.d.ts

@@ -1,5 +0,0 @@
-export declare class ApiHttpError extends Error {
-    response: Response;
-    code?: string;
-    constructor(response: Response, code?: string);
-}