@tolgee/core 4.7.0 → 4.7.2

package/src/types.ts

@@ -0,0 +1,146 @@
+export interface TextInputElementData {
+  oldValue: string;
+  valueInputs: string[];
+  touched: boolean;
+  oldPlaceholder: string;
+  placeholderInputs: string[];
+}
+
+export type TreeTranslationsData = {
+  [key: string]: string | TreeTranslationsData;
+};
+
+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 TranslateProps = {
+  key: string;
+  defaultValue?: string;
+  params?: TranslationParams;
+  noWrap?: boolean;
+  orEmpty?: boolean;
+};
+export type TranslatePropsTags<T> = {
+  key: string;
+  defaultValue?: string;
+  params?: TranslationParamsTags<T>;
+  noWrap?: boolean;
+  orEmpty?: boolean;
+};
+
+export type InstantProps = {
+  key: string;
+  defaultValue?: string;
+  params?: TranslationParams;
+  noWrap?: boolean;
+  orEmpty?: boolean;
+};
+export type InstantPropsTags<T> = {
+  key: string;
+  defaultValue?: string;
+  params?: TranslationParamsTags<T>;
+  noWrap?: boolean;
+  orEmpty?: boolean;
+};
+
+export type KeyAndParams = {
+  key: string;
+  params: TranslationParams;
+  defaultValue?: string;
+};
+export type KeyAndParamsTags<T> = {
+  key: string;
+  params: TranslationParamsTags<T>;
+  defaultValue?: string;
+};
+
+export type TranslatedWithMetadata = {
+  translated: string;
+  key: string;
+  params: TranslationParams;
+  defaultValue: string | undefined;
+};
+export type TranslatedWithMetadataTags<T> = {
+  translated: TranslationTags<T>;
+  key: string;
+  params: TranslationParamsTags<T>;
+  defaultValue: string | undefined;
+};
+
+export type TranslationTags<T> = string | T[];
+
+export type NodeWithMeta = Node & {
+  _tolgee: NodeMeta;
+};
+
+export type NodeWithLock = Node & {
+  _tolgee: NodeLock;
+};
+
+export type ElementWithMeta = Element &
+  ElementCSSInlineStyle & {
+    _tolgee: ElementMeta;
+  };
+
+export type ElementMeta = {
+  wrappedWithElementOnlyKey?: string;
+  wrappedWithElementOnlyDefaultHtml?: string;
+  nodes: Set<NodeWithMeta>;
+  highlightEl?: HTMLDivElement;
+  highlight?: () => void;
+  unhighlight?: () => void;
+  /**
+   * Stops removing of element's inactive nodes and
+   * unregistering from ElementRegistrar.
+   *
+   * It's used when user has mouse on the element, so there is
+   * potential, that element highlight will be triggered.
+   *
+   * 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 NodeLock = {
+  locked?: boolean;
+};
+
+export type Scope =
+  | 'translations.edit'
+  | 'translations.view'
+  | 'keys.edit'
+  | 'screenshots.upload'
+  | 'screenshots.view'
+  | 'screenshots.delete';
+
+export type Mode = 'development' | 'production';
+
+export type Unwrapped = { text: string; keys: KeyAndParamsTags<any>[] };
+
+export interface Formatter {
+  format: FormatFunction;
+}
+
+interface FormatterStatic {
+  type: 'formatter';
+  new (): Formatter;
+}
+
+export type TolgeeModule = FormatterStatic;
+
+export type FormatFunction = (props: {
+  translation: string;
+  params: Record<string, any>;
+  language: string;
+}) => string | any[];

package/src/wrappers/AbstractWrapper.ts

@@ -0,0 +1,14 @@
+import { TranslationTags, TranslationParamsTags, Unwrapped } from '../types';
+
+export interface AbstractWrapper {
+  handleText(node: Element): Promise<void>;
+  handleSubtree(node: Element): Promise<void>;
+  handleAttribute(node: Element): Promise<void>;
+  wrap: (
+    key: string,
+    params?: TranslationParamsTags<any>,
+    defaultValue?: string | undefined,
+    translation?: TranslationTags<any>
+  ) => TranslationTags<any>;
+  unwrap(text: string): Unwrapped;
+}

package/src/wrappers/NodeHandler.ts

@@ -0,0 +1,143 @@
+import { NodeHelper } from '../helpers/NodeHelper';
+import { Properties } from '../Properties';
+import {
+  ElementMeta,
+  ElementWithMeta,
+  KeyAndParamsTags,
+  NodeLock,
+  NodeMeta,
+  NodeWithLock,
+  NodeWithMeta,
+} from '../types';
+import { ElementRegistrar } from '../services/ElementRegistrar';
+import {
+  RESTRICTED_ASCENDANT_ATTRIBUTE,
+  TOLGEE_ATTRIBUTE_NAME,
+} from '../Constants/Global';
+import { AbstractWrapper } from './AbstractWrapper';
+
+export class NodeHandler {
+  constructor(
+    private properties: Properties,
+    private elementRegistrar: ElementRegistrar,
+    private wrapper: AbstractWrapper
+  ) {}
+
+  static initParentElement(element: Element): ElementWithMeta {
+    if (element[TOLGEE_ATTRIBUTE_NAME] === undefined) {
+      element[TOLGEE_ATTRIBUTE_NAME] = {
+        nodes: new Set(),
+      } as ElementMeta;
+      element.setAttribute(TOLGEE_ATTRIBUTE_NAME, '');
+    }
+
+    return element as ElementWithMeta;
+  }
+
+  filterRestricted<T extends Element | Text>(nodes: T[]) {
+    const restrictedElements = this.properties.config.restrictedElements;
+    return nodes.filter((n) => {
+      const e = NodeHelper.closestElement(n);
+      if (!e) {
+        return false;
+      }
+      return (
+        restrictedElements.indexOf(e.tagName.toLowerCase()) === -1 &&
+        e.closest(`[${RESTRICTED_ASCENDANT_ATTRIBUTE}="true"]`) === null
+      );
+    });
+  }
+
+  async handleNodes(nodes: Array<Text | Attr>) {
+    for (const textNode of nodes) {
+      if (textNode[TOLGEE_ATTRIBUTE_NAME] === undefined) {
+        textNode[TOLGEE_ATTRIBUTE_NAME] = {} as NodeLock;
+      }
+      const tolgeeData = textNode[TOLGEE_ATTRIBUTE_NAME] as
+        | NodeMeta
+        | NodeLock
+        | undefined;
+      if (tolgeeData?.locked !== true) {
+        this.lockNode(textNode);
+        const result = await this.wrapper.unwrap(
+          NodeHelper.getNodeText(textNode)
+        );
+        if (result) {
+          const { text, keys } = result;
+          const translatedNode = this.translateChildNode(textNode, text, keys);
+          const parentElement = this.getParentElement(translatedNode);
+          parentElement._tolgee.nodes.add(translatedNode);
+          this.elementRegistrar.register(parentElement);
+        }
+        this.unlockNode(textNode);
+      }
+    }
+  }
+
+  translateChildNode(
+    node: Text | Attr,
+    newValue,
+    keys: KeyAndParamsTags<any>[]
+  ) {
+    node[TOLGEE_ATTRIBUTE_NAME] = {
+      oldTextContent: NodeHelper.getNodeText(node),
+      keys,
+    };
+    NodeHelper.setNodeText(node, newValue);
+    return node as Node as NodeWithMeta;
+  }
+
+  private lockNode(node: Node | Attr): NodeWithLock {
+    if (node[TOLGEE_ATTRIBUTE_NAME] === undefined) {
+      node[TOLGEE_ATTRIBUTE_NAME] = {} as NodeLock;
+    }
+
+    const tolgeeData = node[TOLGEE_ATTRIBUTE_NAME] as NodeMeta | NodeLock;
+    if (tolgeeData?.locked !== true) {
+      tolgeeData.locked = true;
+    }
+
+    return node as NodeWithLock;
+  }
+
+  private unlockNode(node: Node | Attr) {
+    if (node[TOLGEE_ATTRIBUTE_NAME]) {
+      node[TOLGEE_ATTRIBUTE_NAME].locked = false;
+    }
+  }
+
+  private getParentElement(node: Node) {
+    const parent = this.getSuitableParent(node);
+    return NodeHandler.initParentElement(parent);
+  }
+
+  private getSuitableParent(node: Node): Element {
+    const domParent = NodeHelper.getParentElement(node);
+
+    if (domParent === undefined) {
+      // eslint-disable-next-line no-console
+      console.error(node);
+      throw new Error('No suitable parent found for node above.');
+    }
+
+    if (!this.properties.config.passToParent) {
+      return domParent;
+    }
+
+    if (Array.isArray(this.properties.config.passToParent)) {
+      const tagNameEquals = (elementTagName: string) =>
+        domParent.tagName.toLowerCase() === elementTagName.toLowerCase();
+      if (this.properties.config.passToParent.findIndex(tagNameEquals) === -1) {
+        return domParent;
+      }
+    }
+
+    if (typeof this.properties.config.passToParent === 'function') {
+      if (!this.properties.config.passToParent(domParent)) {
+        return domParent;
+      }
+    }
+
+    return this.getSuitableParent(domParent);
+  }
+}

package/src/wrappers/WrappedHandler.ts

@@ -0,0 +1,28 @@
+import { NodeHelper } from '../helpers/NodeHelper';
+import { NodeHandler } from './NodeHandler';
+import { ElementRegistrar } from '../services/ElementRegistrar';
+import { TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE } from '../Constants/Global';
+
+export class WrappedHandler {
+  constructor(
+    private elementRegistrar: ElementRegistrar,
+    private nodeHandler: NodeHandler
+  ) {}
+
+  async handle(node: Node): Promise<void> {
+    const xPath = `./descendant-or-self::*[@${TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE}]`;
+    const nodes = NodeHelper.evaluate(xPath, node);
+    const filtered: Element[] = this.nodeHandler.filterRestricted(
+      nodes as Element[]
+    );
+    filtered.forEach((element) => {
+      const elementWithMeta = NodeHandler.initParentElement(element);
+      elementWithMeta._tolgee.wrappedWithElementOnlyKey = element.getAttribute(
+        TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE
+      );
+      elementWithMeta._tolgee.wrappedWithElementOnlyDefaultHtml =
+        element.innerHTML;
+      this.elementRegistrar.register(elementWithMeta);
+    });
+  }
+}

package/src/wrappers/invisible/AttributeHandler.ts

@@ -0,0 +1,23 @@
+import { NodeHandler } from '../NodeHandler';
+import { Properties } from '../../Properties';
+import { NodeHelper } from '../../helpers/NodeHelper';
+import { INVISIBLE_CHARACTERS } from '../../helpers/secret';
+
+export class AttributeHandler {
+  constructor(
+    private properties: Properties,
+    private nodeHandler: NodeHandler
+  ) {}
+
+  async handle(node: Element) {
+    for (const [tag, attributes] of Object.entries(
+      this.properties.config.tagAttributes
+    )) {
+      for (const attribute of attributes) {
+        const expression = `descendant-or-self::${tag}/@${attribute}[contains(., '${INVISIBLE_CHARACTERS[0]}')]`;
+        const nodes: Array<Attr | Text> = NodeHelper.evaluate(expression, node);
+        await this.nodeHandler.handleNodes(nodes);
+      }
+    }
+  }
+}

package/src/wrappers/invisible/Coder.ts

@@ -0,0 +1,65 @@
+import {
+  decodeFromText,
+  encodeMessage,
+  removeSecrets,
+  stringToCodePoints,
+} from '../../helpers/secret';
+import {
+  KeyAndParams,
+  TranslationTags,
+  TranslationParamsTags,
+  Unwrapped,
+} from '../../types';
+import { ValueMemory } from './ValueMemory';
+
+export class Coder {
+  private keyMemory = new ValueMemory();
+  private defaultMemory = new ValueMemory();
+
+  unwrap(text: string): Unwrapped {
+    const keysAndParams = [] as KeyAndParams[];
+    const messages = decodeFromText(text);
+
+    messages.forEach((msg) => {
+      const [keyCode, defaultCode] = stringToCodePoints(msg);
+      const key = this.keyMemory.numberToValue(keyCode);
+      const defaultValue =
+        defaultCode !== undefined
+          ? this.defaultMemory.numberToValue(defaultCode)
+          : undefined;
+      keysAndParams.push({
+        key: key,
+        params: undefined,
+        defaultValue,
+      });
+    });
+
+    const result = removeSecrets(text);
+
+    if (keysAndParams.length) {
+      return { text: result, keys: keysAndParams };
+    }
+    return undefined;
+  }
+
+  public wrap(
+    key: string,
+    _params: TranslationParamsTags<any> = {},
+    defaultValue: string | undefined = undefined,
+    translation: string | any[] | undefined = undefined
+  ): TranslationTags<any> {
+    const codes = [this.keyMemory.valueToNumber(key)];
+    if (defaultValue) {
+      codes.push(this.defaultMemory.valueToNumber(defaultValue));
+    }
+
+    const value = translation || '';
+    const invisibleMark = encodeMessage(String.fromCodePoint(...codes));
+
+    return typeof value === 'string'
+      ? value + invisibleMark
+      : Array.isArray(value)
+      ? [...value, invisibleMark]
+      : [value, invisibleMark];
+  }
+}

package/src/wrappers/invisible/ContentHandler.ts

@@ -0,0 +1,15 @@
+import { NodeHelper } from '../../helpers/NodeHelper';
+import { INVISIBLE_CHARACTERS } from '../../helpers/secret';
+import { NodeHandler } from '../NodeHandler';
+
+export class ContentHandler {
+  constructor(private nodeHandler: NodeHandler) {}
+
+  async handle(node: Node): Promise<void> {
+    const xPath = `./descendant-or-self::text()[contains(., '${INVISIBLE_CHARACTERS[0]}')]`;
+    const nodes = NodeHelper.evaluate(xPath, node);
+    const filtered: Text[] = this.nodeHandler.filterRestricted(nodes as Text[]);
+
+    await this.nodeHandler.handleNodes(filtered);
+  }
+}

package/src/wrappers/invisible/CoreHandler.ts

@@ -0,0 +1,17 @@
+import { ContentHandler } from './ContentHandler';
+import { AttributeHandler } from './AttributeHandler';
+import { WrappedHandler } from '../WrappedHandler';
+
+export class CoreHandler {
+  constructor(
+    private textHandler: ContentHandler,
+    private attributeHandler: AttributeHandler,
+    private wrappedHandler: WrappedHandler
+  ) {}
+
+  public async handleSubtree(target: Element) {
+    await this.attributeHandler.handle(target);
+    await this.textHandler.handle(target);
+    await this.wrappedHandler.handle(target);
+  }
+}

package/src/wrappers/invisible/InvisibleWrapper.ts

@@ -0,0 +1,59 @@
+import { Properties } from '../../Properties';
+import { ElementRegistrar } from '../../services/ElementRegistrar';
+import { TranslationParams } from '../../types';
+import { NodeHandler } from '../NodeHandler';
+import { AttributeHandler } from './AttributeHandler';
+import { Coder } from './Coder';
+import { CoreHandler } from './CoreHandler';
+import { ContentHandler } from './ContentHandler';
+import { WrappedHandler } from '../WrappedHandler';
+import { AbstractWrapper } from '../AbstractWrapper';
+
+export class InvisibleWrapper implements AbstractWrapper {
+  private coder: Coder;
+  private coreHandler: CoreHandler;
+  private attributeHandler: AttributeHandler;
+  private wrappedHandler: WrappedHandler;
+  private textHandler: ContentHandler;
+  private nodeHandler: any;
+  constructor(properties: Properties, elementRegistrar: ElementRegistrar) {
+    this.coder = new Coder();
+    this.nodeHandler = new NodeHandler(properties, elementRegistrar, this);
+    this.textHandler = new ContentHandler(this.nodeHandler);
+    this.attributeHandler = new AttributeHandler(properties, this.nodeHandler);
+    this.wrappedHandler = new WrappedHandler(
+      elementRegistrar,
+      this.nodeHandler
+    );
+    this.coreHandler = new CoreHandler(
+      this.textHandler,
+      this.attributeHandler,
+      this.wrappedHandler
+    );
+  }
+
+  public handleText(node: Element) {
+    return this.textHandler.handle(node);
+  }
+
+  public handleSubtree(node: Element) {
+    return this.coreHandler.handleSubtree(node);
+  }
+
+  public handleAttribute(node: Element) {
+    return this.attributeHandler.handle(node);
+  }
+
+  public wrap(
+    key: string,
+    params: TranslationParams = {},
+    defaultValue: string | undefined = undefined,
+    translation = ''
+  ) {
+    return this.coder.wrap(key, params, defaultValue, translation);
+  }
+
+  public unwrap(text: string) {
+    return this.coder.unwrap(text);
+  }
+}

package/src/wrappers/invisible/ValueMemory.test.ts

@@ -0,0 +1,25 @@
+jest.dontMock('./ValueMemory');
+import { ValueMemory } from './ValueMemory';
+
+describe('Value memory', () => {
+  let valueMemory: ValueMemory;
+
+  beforeEach(() => {
+    valueMemory = new ValueMemory();
+  });
+
+  it('stores key correctly', () => {
+    const num = valueMemory.valueToNumber('abcd');
+    expect(num).toEqual(0);
+    expect(valueMemory.valueToNumber('abcd')).toEqual(0);
+  });
+
+  it('retrieves key correctly', () => {
+    const num = valueMemory.valueToNumber('abcd');
+    expect(valueMemory.numberToValue(num)).toEqual('abcd');
+  });
+
+  it('retrieves missing key correctly', () => {
+    expect(valueMemory.numberToValue(100)).toEqual(undefined);
+  });
+});

package/src/wrappers/invisible/ValueMemory.ts

@@ -0,0 +1,16 @@
+export class ValueMemory {
+  private values: string[] = [];
+
+  public valueToNumber(key: string) {
+    let index = this.values.indexOf(key);
+    if (index === -1) {
+      index = this.values.length;
+      this.values.push(key);
+    }
+    return index;
+  }
+
+  public numberToValue(num: number) {
+    return this.values[num];
+  }
+}

package/src/wrappers/text/AttributeHandler.test.ts

@@ -0,0 +1,117 @@
+jest.dontMock('./AttributeHandler');
+jest.dontMock('./TextWrapper');
+jest.dontMock('../NodeHandler');
+jest.dontMock('../../services/EventService');
+jest.dontMock('../../helpers/NodeHelper.ts');
+jest.dontMock('../../services/DependencyService');
+jest.dontMock('../../TolgeeConfig');
+
+import { Properties } from '../../Properties';
+import { AttributeHandler } from './AttributeHandler';
+import { ElementWithMeta, NodeWithMeta, Unwrapped } from '../../types';
+import { NodeHelper } from '../../helpers/NodeHelper';
+import { createTestDom } from '@testFixtures/createTestDom';
+import { getMockedInstance } from '@testFixtures/mocked';
+import { ElementRegistrar } from '../../services/ElementRegistrar';
+import { DependencyService } from '../../services/DependencyService';
+import { Coder } from './Coder';
+
+describe('AttributeHandler', () => {
+  let attributeHandler: AttributeHandler;
+
+  const mockedKeys = [
+    {
+      key: 'dummyKey',
+      params: { dummyParam: 'dummyValue' },
+    },
+  ];
+
+  const mockedTranslateInner = (text) => {
+    return {
+      text: text.replace(/{{(.*?)}}/gs, '$1'),
+      keys: mockedKeys,
+    } as Unwrapped;
+  };
+
+  const gv = (key) => mockedTranslateInner(key).text;
+  const mockedTranslate = jest.fn(mockedTranslateInner);
+  let c: ReturnType<typeof createTestDom>;
+
+  beforeEach(() => {
+    c = createTestDom(document);
+    const dependencyService = new DependencyService();
+    dependencyService.init({});
+    // @ts-ignore
+    attributeHandler = dependencyService.wrapper.attributeHandler;
+    getMockedInstance(Properties).config = {
+      inputPrefix: '{{',
+      inputSuffix: '}}',
+      restrictedElements: [],
+      tagAttributes: {
+        '*': ['aria-label'],
+      },
+      passToParent: ['option'],
+    };
+
+    getMockedInstance(Coder).unwrap = (...args) => mockedTranslate(...args);
+  });
+
+  afterEach(async () => {
+    jest.clearAllMocks();
+  });
+
+  describe('in production mode', () => {
+    let xPath: string;
+
+    beforeEach(async () => {
+      await attributeHandler.handle(document.body);
+      xPath = `./div/div/@aria-label[contains(., '${gv(c.ariaLabelKey)}')]`;
+    });
+
+    test('Can be created', () => {
+      expect(attributeHandler).not.toBeUndefined();
+    });
+
+    test('will handle text in aria-label attribute of div', async () => {
+      expect(xPath).toBeFoundIn(document.body);
+    });
+
+    describe("Node's _tolgee property", () => {
+      let node: NodeWithMeta;
+
+      beforeEach(() => {
+        node = NodeHelper.evaluateToSingle(
+          xPath,
+          document.body
+        ) as NodeWithMeta;
+      });
+
+      test('will be defined', () => {
+        expect(node._tolgee).toBeDefined();
+      });
+    });
+
+    describe("Parent element's _tolgee property", () => {
+      let element: ElementWithMeta;
+      let node: NodeWithMeta;
+
+      beforeEach(() => {
+        node = NodeHelper.evaluateToSingle(xPath, document.body);
+        element = (node as any as Attr).ownerElement as any as ElementWithMeta;
+      });
+
+      test('will be defined', () => {
+        expect(element._tolgee).toBeDefined();
+      });
+    });
+  });
+
+  test('will register the node', async () => {
+    await attributeHandler.handle(document.body);
+    const xPath = `./div/div/@aria-label[contains(., '${gv(c.ariaLabelKey)}')]`;
+    const node = NodeHelper.evaluateToSingle(xPath, document.body) as Attr;
+    expect(getMockedInstance(ElementRegistrar).register).toBeCalledWith(
+      node.ownerElement
+    );
+  });
+});