@tolgee/core 4.9.2 → 4.9.3-rc.128edeb.0

package/src/types.ts

@@ -1,96 +1,295 @@
-export interface TextInputElementData {
-  oldValue: string;
-  valueInputs: string[];
-  touched: boolean;
-  oldPlaceholder: string;
-  placeholderInputs: string[];
-}
+import type { Options } from './Controller/State/initState';
+import type { ObserverOptions } from './Controller/State/initObserverOptions';
 
-export type TreeTranslationsData = {
-  [key: string]: string | TreeTranslationsData;
-};
+export type { State, Options } from './Controller/State/initState';
+export type {
+  ObserverOptions,
+  ModifierKey,
+} from './Controller/State/initObserverOptions';
 
-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 { EventEmitterInstance } from './Controller/Events/EventEmitter';
+export type { EventEmitterSelectiveInstance } from './Controller/Events/EventEmitterSelective';
 
-export type TranslateProps = {
-  key: string;
-  defaultValue?: string;
-  params?: TranslationParams;
+export type FallbackGeneral = undefined | false | string | string[];
+
+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;
+  options: ObserverOptions;
+};
+
+export type HighlightInterface = (
+  key?: string,
+  ns?: FallbackNSTranslation
+) => {
+  unhighlight(): void;
+};
+
+export type ObserverRunProps = {
+  mouseHighlight: boolean;
+};
+
+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 LanguageDetectorProps = {
+  availableLanguages: string[];
+};
+
+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 TranslationTags<T> = string | T[];
+export type DevCredentials =
+  | undefined
+  | {
+      apiUrl?: string;
+      apiKey?: string;
+    };
 
-export type NodeWithMeta = Node & {
-  _tolgee: NodeMeta;
+export type BackendDevProps = {
+  apiUrl?: string;
+  apiKey?: string;
+  projectId?: number;
 };
 
-export type NodeWithLock = Node & {
-  _tolgee: NodeLock;
+export type BackendGetRecordProps = {
+  language: string;
+  namespace?: string;
+};
+
+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 ElementWithMeta = Element &
-  ElementCSSInlineStyle & {
-    _tolgee: ElementMeta;
-  };
+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;
+  setObserverOptions: (options: Partial<ObserverOptions>) => TolgeeInstance;
+}>;
+
+export type PluginServicePublic = Readonly<{
+  setFinalFormatter: (formatter: FinalFormatterInterface | undefined) => void;
+  addFormatter: (formatter: FormatterInterface | undefined) => void;
+  setObserver: (observer: ObserverInterface | undefined) => void;
+  hasObserver: () => boolean;
+  setUi: (ui: UiLibInterface | undefined) => void;
+  hasUi: () => boolean;
+  addBackend: (backend: BackendInterface | undefined) => void;
+  setDevBackend: (backend: BackendInterface | undefined) => void;
+  setLanguageDetector: (
+    languageDetector: LanguageDetectorInterface | undefined
+  ) => void;
+  setLanguageStorage: (
+    languageStorage: LanguageStorageInterface | undefined
+  ) => void;
+  overrideCredentials: (credentials: DevCredentials) => 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 +303,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;
+};

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);
-}

package/dist/Observer.d.ts

@@ -1,14 +0,0 @@
-import { Properties } from './Properties';
-import { ElementRegistrar } from './services/ElementRegistrar';
-import { AbstractWrapper } from './wrappers/AbstractWrapper';
-export declare class Observer {
-    private properties;
-    private textWrapper;
-    private nodeRegistrar;
-    constructor(properties: Properties, textWrapper: AbstractWrapper, nodeRegistrar: ElementRegistrar);
-    private _observer;
-    private _observing;
-    private get observer();
-    observe(): void;
-    stopObserving(): void;
-}

package/dist/Observer.test.d.ts

@@ -1,2 +0,0 @@
-import '@testing-library/jest-dom/extend-expect';
-import 'regenerator-runtime/runtime.js';

package/dist/Properties.d.ts

@@ -1,17 +0,0 @@
-import { TolgeeConfig } from './TolgeeConfig';
-import { Mode, Scope } from './types';
-export declare class Properties {
-    config: TolgeeConfig;
-    scopes?: Scope[];
-    projectId?: number;
-    permittedLanguageIds?: number[];
-    mode?: Mode;
-    _currentLanguage?: string;
-    get currentLanguage(): string;
-    set currentLanguage(language: string);
-    get preferredLanguages(): Set<string>;
-    set preferredLanguages(languages: Set<string>);
-    private getInitialLanguage;
-    private getStoredLanguage;
-    private getLanguageByNavigator;
-}

package/dist/Properties.test.d.ts

@@ -1 +0,0 @@
-import '@testing-library/jest-dom/extend-expect';

package/dist/Tolgee.d.ts

@@ -1,68 +0,0 @@
-import { TolgeeConfig } from './TolgeeConfig';
-import { InstantProps, InstantPropsTags, TolgeeModule, TranslateProps, TranslatePropsTags, TranslationTags, TranslationParams, TranslationParamsTags } from './types';
-export declare class Tolgee {
-    private dependencyService;
-    private constructor();
-    get properties(): import("./Properties").Properties;
-    get lang(): string;
-    /**
-     * This sets a new language.
-     *
-     * Using this setter can behave buggy when you change languages
-     * too fast, since it changes the language property before
-     * translations are actually loaded.
-     * @deprecated use asynchronous changeLanguage method.
-     */
-    set lang(newLanguage: string);
-    get defaultLanguage(): string;
-    get onLangChange(): import("./services/EventEmitter").EventEmitter<string>;
-    get onTranslationChange(): import("./services/EventEmitter").EventEmitter<import(".").TranslationData>;
-    /**
-     * Is emitted when language is loaded for the first time
-     */
-    get onLangLoaded(): import("./services/EventEmitter").EventEmitter<string>;
-    /**
-     * True if loading is needed to wait for Tolgee init.
-     * When translation data are provided statically (using import
-     * as staticData config property) then there is no need for translation
-     * fetching so initial loading is not needed at all.
-     */
-    get initialLoading(): boolean;
-    private get coreService();
-    static use(module: TolgeeModule): Tolgee;
-    static init(config: TolgeeConfig): Tolgee;
-    /**
-     * Sets the new language.
-     *
-     * Emits the onLangChange and onLangChangeAndLoad events after
-     * the translations are loaded.
-     *
-     * @return Promise<void> Resolves when translations are loaded
-     */
-    changeLanguage(newLanguage: string): Promise<void>;
-    use(module: TolgeeModule): this;
-    init(config: TolgeeConfig): this;
-    run(): Promise<void>;
-    refresh(): Promise<void>;
-    translate(props: TranslateProps): Promise<string>;
-    translate<T>(props: TranslatePropsTags<T>): Promise<TranslationTags<T>>;
-    translate(key: string, params?: TranslationParams, noWrap?: boolean, defaultValue?: string): Promise<string>;
-    translate<T>(key: string, params?: TranslationParamsTags<T>, noWrap?: boolean, defaultValue?: string): Promise<TranslationTags<T>>;
-    wrap(key: string, params?: TranslationParams, defaultValue?: string | undefined, translation?: string): string;
-    wrap<T>(key: string, params?: TranslationTags<T>, defaultValue?: string | undefined, translation?: TranslationTags<T>): TranslationTags<T>;
-    instant(key: string, params?: TranslationParams, noWrap?: boolean, orEmpty?: boolean, defaultValue?: string): string;
-    instant<T>(key: string, params?: TranslationParamsTags<T>, noWrap?: boolean, orEmpty?: boolean, defaultValue?: string): TranslationTags<T>;
-    instant(props: InstantProps): string;
-    instant<T>(props: InstantPropsTags<T>): TranslationTags<T>;
-    /**
-     * Get currently cached translations for all languages
-     */
-    getCachedTranslations(): Map<string, import("./types").Translations>;
-    /**
-     * Loads translations for given language or returns them from cache
-     * @returns Loaded translations
-     */
-    loadTranslations(lang: string): Promise<import("./types").Translations>;
-    stop: () => void;
-    private emitLangChangeEvent;
-}

package/dist/Tolgee.test.d.ts

@@ -1 +0,0 @@
-import '@testing-library/jest-dom/extend-expect';