@tolgee/core 5.0.0-rc.9be0f0e.0 → 5.0.0

package/src/Controller/State/State.ts

@@ -1,21 +1,30 @@
 import {
   CacheDescriptor,
   CacheDescriptorInternal,
-  EventEmitterType,
-  FallbackNSTranslation,
+  DevCredentials,
+  NsFallback,
+  NsType,
 } from '../../types';
+
 import { decodeCacheKey } from '../Cache/helpers';
-import { getFallbackArray, getFallbackFromStruct, unique } from './helpers';
-import { initState, Options } from './initState';
+import { EventEmitterInstance } from '../Events/EventEmitter';
+import {
+  getFallbackArray,
+  getFallbackFromStruct,
+  sanitizeUrl,
+  unique,
+} from '../../helpers';
+import { initState, TolgeeOptions } from './initState';
 
 export const State = (
-  onLanguageChange: EventEmitterType<string>,
-  onPendingLanguageChange: EventEmitterType<string>,
-  onRunningChange: EventEmitterType<boolean>
+  onLanguageChange: EventEmitterInstance<string>,
+  onPendingLanguageChange: EventEmitterInstance<string>,
+  onRunningChange: EventEmitterInstance<boolean>
 ) => {
   let state = initState();
+  let devCredentials: DevCredentials = undefined;
 
-  function init(options?: Partial<Options>) {
+  function init(options?: Partial<TolgeeOptions>) {
     state = initState(options, state);
   }
 
@@ -42,14 +51,6 @@ export const State = (
     return state.language || state.initialOptions.language;
   }
 
-  function getLanguageOrFail() {
-    const language = state.language || state.initialOptions.language;
-    if (!language) {
-      throw new Error(`No language set`);
-    }
-    return language;
-  }
-
   function setLanguage(language: string) {
     if (state.language !== language) {
       state.language = language;
@@ -69,10 +70,10 @@ export const State = (
   }
 
   function getInitialOptions() {
-    return state.initialOptions;
+    return { ...state.initialOptions, ...devCredentials };
   }
 
-  function addActiveNs(ns: FallbackNSTranslation) {
+  function addActiveNs(ns: NsFallback) {
     const namespaces = getFallbackArray(ns);
     namespaces.forEach((namespace) => {
       const value = state.activeNamespaces.get(namespace);
@@ -84,7 +85,7 @@ export const State = (
     });
   }
 
-  function removeActiveNs(ns: FallbackNSTranslation) {
+  function removeActiveNs(ns: NsFallback) {
     const namespaces = getFallbackArray(ns);
     namespaces.forEach((namespace) => {
       const value = state.activeNamespaces.get(namespace);
@@ -99,6 +100,7 @@ export const State = (
   function getRequiredNamespaces() {
     return unique([
       ...(state.initialOptions.ns || [state.initialOptions.defaultNs]),
+      ...getFallbackArray(state.initialOptions.fallbackNs),
       ...state.activeNamespaces.keys(),
     ]);
   }
@@ -114,11 +116,12 @@ export const State = (
     ]);
   }
 
-  function getFallbackNamespaces() {
-    const defaultNs = state.initialOptions.defaultNs;
-    const fallbackNs = state.initialOptions.fallbackNs;
-    const fallbackNamespaces = typeof defaultNs === 'string' ? [defaultNs] : [];
-    return unique([...fallbackNamespaces, ...getFallbackArray(fallbackNs)]);
+  function getFallbackNs() {
+    return getFallbackArray(state.initialOptions.fallbackNs);
+  }
+
+  function getDefaultNs(ns?: NsType) {
+    return ns === undefined ? state.initialOptions.defaultNs : ns;
   }
 
   function getAvailableLanguages() {
@@ -142,6 +145,17 @@ export const State = (
     };
   }
 
+  function overrideCredentials(credentials: DevCredentials) {
+    if (credentials) {
+      devCredentials = {
+        ...credentials,
+        apiUrl: sanitizeUrl(credentials.apiUrl),
+      };
+    } else {
+      devCredentials = undefined;
+    }
+  }
+
   return Object.freeze({
     init,
     isRunning,
@@ -149,7 +163,6 @@ export const State = (
     isInitialLoading,
     setInitialLoading,
     getLanguage,
-    getLanguageOrFail,
     setLanguage,
     getPendingLanguage,
     setPendingLanguage,
@@ -158,8 +171,12 @@ export const State = (
     removeActiveNs,
     getRequiredNamespaces,
     getFallbackLangs,
-    getFallbackNamespaces,
+    getFallbackNs,
+    getDefaultNs,
     getAvailableLanguages,
     withDefaultNs,
+    overrideCredentials,
   });
 };
+
+export type StateInstance = ReturnType<typeof State>;

package/src/Controller/State/initState.ts

@@ -1,57 +1,111 @@
 import {
+  FallbackGeneral,
   FallbackLanguageOption,
-  FallbackNS,
   TreeTranslationsData,
+  OnFormatError,
 } from '../../types';
+import { sanitizeUrl } from '../../helpers';
+import {
+  defaultObserverOptions,
+  ObserverOptions,
+  ObserverOptionsInternal,
+} from './observerOptions';
+
+export const DEFAULT_FORMAT_ERROR = 'invalid';
 
-export type Options = {
+export type TolgeeStaticData = {
+  [key: string]: TreeTranslationsData | (() => Promise<TreeTranslationsData>);
+};
+
+export type TolgeeOptionsInternal = {
   /**
    * Initial language
    */
   language?: string;
+
+  /**
+   * Tolgee instance url (e.g. https://app.tolgee.io)
+   */
   apiUrl?: string;
+
+  /**
+   * Project API key (PAK) or Personal Access Token (PAT)
+   */
   apiKey?: string;
-  projectId?: number;
+
+  /**
+   * Project id is necessary if you are using PAT
+   */
+  projectId?: number | string;
+
   /**
    * Used when auto detection is not available or is turned off
    */
   defaultLanguage?: string;
+
   /**
    * Languages which can be used for language detection
    * and also limits which values can be stored
    */
   availableLanguages?: string[];
+
   /**
    * Language which is used when no translation is available for current one
    */
   fallbackLanguage?: FallbackLanguageOption;
-  /**
-   * Store user language in localStorage (default: true)
-   */
-  enableLanguageStore?: boolean;
+
   /**
    * Namespaces which should be always fetched
    */
   ns?: string[];
+
   /**
    * Namespaces to be used to find translation when no explicit namespace set.
    */
-  fallbackNs?: FallbackNS;
+  fallbackNs?: FallbackGeneral;
+
   /**
    * Default namespace when no namespace defined (default: '')
    */
   defaultNs: string;
+
   /**
-   * Prefix used for fetching languages (default: 'i18n/')
+   * These data go directly to cache or you can specify async
+   * function which will be used to get the data. Use `:` to add namespace:
+   *
+   * ```ts
+   * {
+   *   'locale': <translations | async function>
+   *   'locale:namespace': <translations | async function>
+   * }
+   * ```
    */
-  filesUrlPrefix: string;
-  staticData?: {
-    [key: string]: TreeTranslationsData | (() => Promise<TreeTranslationsData>);
-  };
+  staticData?: TolgeeStaticData;
+
+  /**
+   * Switches between invisible and text observer. (Default: invisible)
+   */
+  observerType: 'invisible' | 'text';
+
+  /**
+   * Observer options object.
+   */
+  observerOptions: ObserverOptionsInternal;
+
+  /**
+   * Define what to display in case of formatting error. (Default: 'invalid')
+   */
+  onFormatError: OnFormatError;
+};
+
+export type TolgeeOptions = Partial<
+  Omit<TolgeeOptionsInternal, 'observerOptions'>
+> & {
+  observerOptions?: ObserverOptions;
 };
 
 export type State = {
-  initialOptions: Options;
+  initialOptions: TolgeeOptionsInternal;
   activeNamespaces: Map<string, number>;
   language: string | undefined;
   pendingLanguage: string | undefined;
@@ -59,24 +113,42 @@ export type State = {
   isRunning: boolean;
 };
 
-const defaultValues: Options = {
-  enableLanguageStore: true,
+const defaultValues: TolgeeOptionsInternal = {
   defaultNs: '',
-  filesUrlPrefix: 'i18n/',
+  observerOptions: defaultObserverOptions,
+  observerType: 'invisible',
+  onFormatError: DEFAULT_FORMAT_ERROR,
+};
+
+export const combineOptions = <T extends TolgeeOptions>(
+  ...states: (T | undefined)[]
+) => {
+  let result = {} as T;
+  states.forEach((state) => {
+    result = {
+      ...result,
+      ...state,
+      observerOptions: {
+        ...result.observerOptions,
+        ...state?.observerOptions,
+      },
+    };
+  });
+  return result;
 };
 
 export const initState = (
-  options?: Partial<Options>,
+  options?: Partial<TolgeeOptions>,
   previousState?: State
 ): State => {
-  const initialOptions = {
-    ...defaultValues,
-    ...previousState?.initialOptions,
-    ...options,
-  };
+  const initialOptions = combineOptions(
+    defaultValues,
+    previousState?.initialOptions,
+    options
+  ) as TolgeeOptionsInternal;
+
   // remove extra '/' from url end
-  const apiUrl = initialOptions.apiUrl;
-  initialOptions.apiUrl = apiUrl ? apiUrl.replace(/\/+$/, '') : apiUrl;
+  initialOptions.apiUrl = sanitizeUrl(initialOptions.apiUrl);
 
   return {
     initialOptions,

package/src/Controller/State/observerOptions.ts

@@ -0,0 +1,66 @@
+export type ObserverOptionsInternal = {
+  /**
+   * Attributes that are observed on html elements
+   */
+  tagAttributes: Record<string, string[]>;
+
+  /**
+   * Key(s) which trigger in-context translating (default: ['Alt'])
+   */
+  highlightKeys: ModifierKey[];
+
+  /**
+   * Color used for key highlighting (default: 'rgb(255, 0, 0)')
+   */
+  highlightColor: string;
+
+  /**
+   * Highliter border width (default: 5)
+   */
+  highlightWidth: number;
+
+  /**
+   * Root element which will be observed (default: document.body)
+   */
+  targetElement?: HTMLElement;
+
+  /**
+   * Elements which are not observed (default: ['script', 'style'])
+   */
+  restrictedElements: string[];
+
+  /**
+   * Text observer prefix (default: '%-%tolgee:')
+   */
+  inputPrefix: string;
+
+  /**
+   * Text observer suffix (default: '%-%')
+   */
+  inputSuffix: string;
+
+  /**
+   * Html elements which will pass click listener to their parent (default: ['option', 'optgroup'])
+   */
+  passToParent: (keyof HTMLElementTagNameMap)[] | ((node: Element) => boolean);
+};
+
+export type ObserverOptions = Partial<ObserverOptionsInternal>;
+
+export type ModifierKey = 'Alt' | 'Control' | 'Shift' | 'Meta';
+
+export const defaultObserverOptions: ObserverOptionsInternal = {
+  tagAttributes: {
+    textarea: ['placeholder'],
+    input: ['value', 'placeholder'],
+    img: ['alt'],
+    '*': ['aria-label', 'title'],
+  },
+  restrictedElements: ['script', 'style'],
+  highlightKeys: ['Alt'] as ModifierKey[],
+  highlightColor: 'rgb(255, 0, 0)',
+  highlightWidth: 5,
+  inputPrefix: '%-%tolgee:',
+  inputSuffix: '%-%',
+  passToParent: ['option', 'optgroup'],
+};

package/src/Controller/ValueObserver.ts

@@ -2,7 +2,7 @@ export const ValueObserver = <T = any>(
   initialValue: T,
   valueGetter: () => T,
   handler: (value: T) => void
-) => {
+): ValueObserverInstance<T> => {
   let previousValue: T = initialValue;
   function init(value: T) {
     previousValue = value;
@@ -20,4 +20,7 @@ export const ValueObserver = <T = any>(
   });
 };
 
-export type ValueObserverInstance<T> = ReturnType<typeof ValueObserver<T>>;
+export type ValueObserverInstance<T> = {
+  readonly init: (value: T) => void;
+  readonly notify: () => void;
+};

package/src/FormatSimple/FormatError.ts

@@ -0,0 +1,26 @@
+export const ERROR_PARAM_EMPTY = 0,
+  ERROR_UNEXPECTED_CHAR = 1,
+  ERROR_UNEXPECTED_END = 2;
+
+export type ErrorCode =
+  | typeof ERROR_PARAM_EMPTY
+  | typeof ERROR_UNEXPECTED_CHAR
+  | typeof ERROR_UNEXPECTED_END;
+
+export class FormatError extends Error {
+  public readonly code: ErrorCode;
+  public readonly index: number;
+  constructor(code: ErrorCode, index: number, text: string) {
+    let error: string;
+    if (code === ERROR_PARAM_EMPTY) {
+      error = 'Empty parameter';
+    } else if (code === ERROR_UNEXPECTED_CHAR) {
+      error = 'Unexpected character';
+    } else {
+      error = 'Unexpected end';
+    }
+    super(`Tolgee parser: ${error} at ${index} in "${text}"`);
+    this.code = code;
+    this.index = index;
+  }
+}

package/src/FormatSimple/FormatSimple.ts

@@ -0,0 +1,13 @@
+import { formatter } from './formatter';
+import { FinalFormatterMiddleware, TolgeePlugin } from '../types';
+
+function createFormatSimple(): FinalFormatterMiddleware {
+  return {
+    format: ({ translation, params }) => formatter(translation, params),
+  };
+}
+
+export const FormatSimple = (): TolgeePlugin => (tolgee, tools) => {
+  tools.setFinalFormatter(createFormatSimple());
+  return tolgee;
+};

package/src/FormatSimple/formatParser.ts

@@ -0,0 +1,133 @@
+import {
+  ErrorCode,
+  ERROR_PARAM_EMPTY,
+  ERROR_UNEXPECTED_CHAR,
+  ERROR_UNEXPECTED_END,
+  FormatError,
+} from './FormatError';
+
+function isWhitespace(ch: string) {
+  return /\s/.test(ch);
+}
+
+const STATE_TEXT = 0,
+  STATE_ESCAPE_MAYBE = 1,
+  STATE_ESCAPE = 2,
+  STATE_PARAM = 3,
+  STATE_PARAM_AFTER = 4;
+
+type State =
+  | typeof STATE_TEXT
+  | typeof STATE_ESCAPE_MAYBE
+  | typeof STATE_ESCAPE
+  | typeof STATE_PARAM
+  | typeof STATE_PARAM_AFTER;
+
+const END_STATES = new Set<State>([
+  STATE_ESCAPE,
+  STATE_ESCAPE_MAYBE,
+  STATE_TEXT,
+]);
+const CHAR_ESCAPE = "'";
+const ESCAPABLE = new Set(['{', '}', CHAR_ESCAPE]);
+
+const isAllowedInParam = (char: string) => {
+  return /[0-9a-zA-Z_]/.test(char);
+};
+
+export function formatParser(translation: string) {
+  let state: State = STATE_TEXT;
+  let text = '';
+  let param = '';
+  let ch = '';
+  const texts: string[] = [];
+  const params: string[] = [];
+
+  let i = 0;
+
+  function parsingError(code: ErrorCode): never {
+    throw new FormatError(code, i, translation);
+  }
+
+  const addText = () => {
+    texts.push(text);
+    text = '';
+  };
+
+  const addParamChar = () => {
+    if (!isAllowedInParam(ch)) {
+      parsingError(ERROR_UNEXPECTED_CHAR);
+    }
+    param += ch;
+  };
+
+  const addParam = () => {
+    if (param === '') {
+      parsingError(ERROR_PARAM_EMPTY);
+    }
+    params.push(param);
+    param = '';
+  };
+
+  for (i = 0; i < translation.length; i++) {
+    ch = translation[i];
+    switch (state) {
+      case STATE_TEXT:
+        if (ch === CHAR_ESCAPE) {
+          text += ch;
+          state = STATE_ESCAPE_MAYBE;
+        } else if (ch === '{') {
+          addText();
+          state = STATE_PARAM;
+        } else {
+          text += ch;
+          state = STATE_TEXT;
+        }
+        break;
+
+      case STATE_ESCAPE_MAYBE:
+        if (ESCAPABLE.has(ch)) {
+          text = text.slice(0, -1) + ch;
+          state = STATE_ESCAPE;
+        } else {
+          text += ch;
+          state = STATE_TEXT;
+        }
+        break;
+      case STATE_ESCAPE:
+        if (ch === CHAR_ESCAPE) {
+          state = STATE_TEXT;
+        } else {
+          text += ch;
+          state = STATE_ESCAPE;
+        }
+        break;
+      case STATE_PARAM:
+        if (ch === '}') {
+          addParam();
+          state = STATE_TEXT;
+        } else if (!isWhitespace(ch)) {
+          addParamChar();
+          state = STATE_PARAM;
+        } else if (param !== '') {
+          addParam();
+          state = STATE_PARAM_AFTER;
+        }
+
+        break;
+      case STATE_PARAM_AFTER:
+        if (ch == '}') {
+          state = STATE_TEXT;
+        } else if (isWhitespace(ch)) {
+          state = STATE_PARAM_AFTER;
+        } else {
+          parsingError(ERROR_UNEXPECTED_CHAR);
+        }
+    }
+  }
+  if (!END_STATES.has(state)) {
+    parsingError(ERROR_UNEXPECTED_END);
+  }
+  addText();
+  return [texts, params];
+}