@tolgee/web 4.9.3-rc.128edeb.0

package/src/observers/general/GeneralObserver.ts

@@ -0,0 +1,133 @@
+import {
+  FallbackNSTranslation,
+  TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE,
+  TranslationOnClick,
+  WrapperInterface,
+  ObserverRunProps,
+  ObserverOptions,
+} from '@tolgee/core';
+
+import { DomHelper } from './DomHelper';
+import { initNodeMeta } from './ElementMeta';
+import { ElementRegistry } from './ElementRegistry';
+import { getNodeText, setNodeText, xPathEvaluate } from './helpers';
+import { NodeHandler } from './NodeHandler';
+
+export const GeneralObserver = (
+  wrapper: WrapperInterface,
+  options: ObserverOptions,
+  onClick: TranslationOnClick
+) => {
+  let isObserving = false;
+
+  const domHelper = DomHelper(options);
+  const nodeHandler = NodeHandler(options, wrapper);
+  const elementRegistry = ElementRegistry(options, onClick);
+
+  function handleNodes(nodes: Array<Text | Attr>) {
+    for (const textNode of nodes) {
+      const oldTextContent = getNodeText(textNode);
+      const result = oldTextContent ? wrapper.unwrap(oldTextContent) : null;
+      if (result) {
+        const { text, keys } = result;
+        setNodeText(textNode, text);
+        const nodeMeta = initNodeMeta(oldTextContent!, keys);
+        const parentElement = domHelper.getSuitableParent(textNode);
+        elementRegistry.register(parentElement, textNode, nodeMeta);
+      }
+    }
+  }
+
+  const handleKeyAttribute = (node: Node) => {
+    const xPath = `./descendant-or-self::*[@${TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE}]`;
+    const elements = xPathEvaluate(xPath, node) as Element[];
+    elements.forEach((element) => {
+      const node = element.getAttributeNode(TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE);
+      const parentElement = domHelper.getSuitableParent(node as Node);
+      elementRegistry.register(parentElement, node as Node, {
+        oldTextContent: '',
+        keys: [{ key: getNodeText(node as Node)! }],
+        keyAttributeOnly: true,
+      });
+    });
+  };
+
+  const createMutationObserver = () => {
+    return new MutationObserver((mutationsList: MutationRecord[]) => {
+      if (!isObserving) {
+        return;
+      }
+      for (const mutation of mutationsList) {
+        let result: (Attr | Text)[] = [];
+        switch (mutation.type) {
+          case 'characterData':
+            result = nodeHandler.handleText(mutation.target);
+            break;
+
+          case 'childList':
+            handleKeyAttribute(mutation.target);
+            result = nodeHandler.handleChildList(mutation.target);
+            break;
+
+          case 'attributes':
+            handleKeyAttribute(mutation.target);
+            result = nodeHandler.handleAttributes(mutation.target);
+            break;
+        }
+        handleNodes(result);
+        elementRegistry.refreshAll();
+      }
+    });
+  };
+
+  let observer: MutationObserver;
+
+  const run = ({ mouseHighlight }: ObserverRunProps) => {
+    if (!observer) {
+      observer = createMutationObserver();
+    }
+    const targetElement = options.targetElement || document.body;
+    isObserving = true;
+    elementRegistry.run(mouseHighlight);
+
+    // initially go through all elements
+    handleKeyAttribute(targetElement);
+    handleNodes(nodeHandler.handleChildList(targetElement));
+
+    // then observe for changes
+    observer.observe(options.targetElement || document.body, {
+      attributes: true,
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+  };
+
+  const stop = () => {
+    isObserving = false;
+    elementRegistry.stop();
+    observer.disconnect();
+  };
+
+  const highlight = (key?: string, ns?: FallbackNSTranslation) => {
+    const elements = elementRegistry.findAll(key, ns);
+    elements.forEach((el) => el.highlight?.());
+
+    return {
+      unhighlight() {
+        elements.forEach((el) => el.unhighlight?.());
+      },
+    };
+  };
+
+  return Object.freeze({
+    run,
+    stop,
+    wrap: wrapper.wrap,
+    unwrap: wrapper.unwrap,
+    forEachElement: elementRegistry.forEachElement,
+    highlight,
+  });
+};
+
+export type GeneralObserverType = ReturnType<typeof GeneralObserver>;

package/src/observers/general/MouseEventHandler.ts

@@ -0,0 +1,199 @@
+import { TolgeeElement } from '../../types';
+import { ModifierKey } from '@tolgee/core';
+import { DEVTOOLS_ID } from '../../constants';
+import { ElementStoreType } from './ElementStore';
+
+const eCapture = {
+  capture: true,
+};
+
+const ePassive = {
+  capture: true,
+  passive: true,
+};
+
+type Coordinates = {
+  x: number;
+  y: number;
+};
+
+type Props = {
+  highlightKeys: ModifierKey[];
+  elementStore: ElementStoreType;
+  onClick: (event: MouseEvent, el: TolgeeElement) => void;
+};
+
+export const MouseEventHandler = ({
+  highlightKeys,
+  elementStore,
+  onClick,
+}: Props) => {
+  let keysDown = new Set<ModifierKey>();
+  let highlighted: TolgeeElement | undefined;
+  // let mouseOnChanged = new EventEmitterImpl<Element>();
+  // let keysChanged: EventEmitterImpl<boolean> =
+  //   new EventEmitterImpl<boolean>();
+  let cursorPosition: Coordinates | undefined;
+
+  const highlight = (el: TolgeeElement | undefined) => {
+    if (highlighted !== el) {
+      unhighlight();
+      const meta = elementStore.get(el);
+      if (meta) {
+        meta.preventClean = true;
+        meta.highlight?.();
+        highlighted = el;
+        // mouseOnChanged.emit(el);
+      }
+    }
+  };
+
+  const unhighlight = () => {
+    const meta = elementStore.get(highlighted);
+    if (meta) {
+      meta.preventClean = false;
+      meta.unhighlight?.();
+      highlighted = undefined;
+      // mouseOnChanged.emit(highlighted);
+    }
+  };
+
+  function updateHighlight() {
+    const position = cursorPosition;
+
+    let newHighlighted: TolgeeElement | undefined;
+    if (position && areKeysDown()) {
+      const element = document.elementFromPoint(position.x, position.y);
+      if (element) {
+        newHighlighted = getClosestTolgeeElement(element);
+      }
+    }
+    highlight(newHighlighted);
+  }
+
+  function updateCursorPosition(position: Coordinates) {
+    cursorPosition = position;
+    updateHighlight();
+  }
+
+  const blockEvents = (e: MouseEvent) => {
+    if (areKeysDown() && !isInUiDialog(e.target as Element)) {
+      e.stopPropagation();
+      e.preventDefault();
+    }
+  };
+  const onMouseMove = (e: MouseEvent) => {
+    updateCursorPosition({ x: e.clientX, y: e.clientY });
+  };
+  const onBlur = () => {
+    keysDown = new Set();
+    // keysChanged.emit(areKeysDown());
+    updateHighlight();
+  };
+  const onKeyDown = (e: KeyboardEvent) => {
+    const modifierKey = e.key as unknown as ModifierKey;
+    if (modifierKey !== undefined) {
+      keysDown.add(modifierKey);
+      // keysChanged.emit(areKeysDown());
+    }
+    updateHighlight();
+  };
+  const onKeyUp = (e: KeyboardEvent) => {
+    keysDown.delete(e.key as unknown as ModifierKey);
+    // keysChanged.emit(areKeysDown());
+    updateHighlight();
+  };
+  const onScroll = () => {
+    const meta = elementStore.get(highlighted);
+    meta?.highlight?.();
+  };
+  const handleClick = (e: MouseEvent) => {
+    blockEvents(e);
+    if (areKeysDown()) {
+      const element = getClosestTolgeeElement(e.target as TolgeeElement);
+      if (element && element === highlighted) {
+        onClick(e, element);
+        unhighlight();
+      }
+    }
+  };
+
+  function initEventListeners() {
+    window.addEventListener('blur', onBlur, eCapture);
+    window.addEventListener('keydown', onKeyDown, eCapture);
+    window.addEventListener('keyup', onKeyUp, eCapture);
+    window.addEventListener('mousemove', onMouseMove, ePassive);
+    window.addEventListener('scroll', onScroll, ePassive);
+    window.addEventListener('click', handleClick, eCapture);
+
+    window.addEventListener('mouseenter', blockEvents, eCapture);
+    window.addEventListener('mouseover', blockEvents, eCapture);
+    window.addEventListener('mouseout', blockEvents, eCapture);
+    window.addEventListener('mouseleave', blockEvents, eCapture);
+    window.addEventListener('mousedown', blockEvents, eCapture);
+    window.addEventListener('mouseup', blockEvents, eCapture);
+  }
+
+  function removeEventListeners() {
+    window.removeEventListener('blur', onBlur, eCapture);
+    window.removeEventListener('keydown', onKeyDown, eCapture);
+    window.removeEventListener('keyup', onKeyUp, eCapture);
+    window.removeEventListener('mousemove', onMouseMove, ePassive);
+    window.removeEventListener('scroll', onScroll, ePassive);
+    window.removeEventListener('click', handleClick, eCapture);
+
+    window.removeEventListener('mouseenter', blockEvents, eCapture);
+    window.removeEventListener('mouseover', blockEvents, eCapture);
+    window.removeEventListener('mouseout', blockEvents, eCapture);
+    window.removeEventListener('mouseleave', blockEvents, eCapture);
+    window.removeEventListener('mousedown', blockEvents, eCapture);
+    window.removeEventListener('mouseup', blockEvents, eCapture);
+  }
+
+  function isInUiDialog(element: Element) {
+    return Boolean(findAncestor(element, (el) => el.id === DEVTOOLS_ID));
+  }
+
+  function getClosestTolgeeElement(
+    element: Element
+  ): TolgeeElement | undefined {
+    return findAncestor(element, (el) =>
+      elementStore.get(el as TolgeeElement)
+    ) as TolgeeElement;
+  }
+
+  function findAncestor(
+    element: Element,
+    func: (el: Element) => any
+  ): Element | undefined {
+    if (func(element)) {
+      return element;
+    }
+    if (element?.parentElement) {
+      return findAncestor(element.parentElement, func);
+    }
+    return undefined;
+  }
+
+  function areKeysDown() {
+    for (const key of highlightKeys) {
+      if (!keysDown.has(key)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  function stop() {
+    removeEventListeners();
+  }
+
+  function run() {
+    initEventListeners();
+  }
+
+  return Object.freeze({
+    run,
+    stop,
+  });
+};

package/src/observers/general/NodeHandler.ts

@@ -0,0 +1,39 @@
+import { WrapperInterface, ObserverOptions } from '@tolgee/core';
+import { xPathEvaluate } from './helpers';
+
+export const NodeHandler = (
+  options: ObserverOptions,
+  wrapper: WrapperInterface
+) => {
+  const handleText = (node: Node) => {
+    const xPath = wrapper.getTextXPath();
+    const nodes = xPathEvaluate(xPath, node);
+    return nodes as Text[];
+  };
+
+  const handleAttributes = (node: Node) => {
+    let result: Attr[] = [];
+    for (const [tag, attributes] of Object.entries(options.tagAttributes)) {
+      for (const attribute of attributes) {
+        const expression = wrapper.getAttributeXPath({ tag, attribute });
+        const nodes = xPathEvaluate(expression, node) as Attr[];
+        result = [...result, ...nodes];
+      }
+    }
+    return result;
+  };
+
+  const handleChildList = (node: Node) => {
+    let result: (Attr | Text)[] = [];
+    result = result.concat(handleAttributes(node));
+    result = result.concat(handleText(node));
+    // wrappedHandler(node);
+    return result;
+  };
+
+  return Object.freeze({
+    handleAttributes,
+    handleChildList,
+    handleText,
+  });
+};

package/src/observers/general/helpers.ts

@@ -0,0 +1,65 @@
+import { KeyDescriptorInternal } from '@tolgee/core';
+
+export function xPathEvaluate<T extends Node>(
+  expression: string,
+  targetNode: Node
+): Node[] {
+  let node: Node | null;
+  const evaluated = document?.evaluate(
+    expression,
+    targetNode,
+    undefined,
+    XPathResult.ANY_TYPE
+  );
+  const result: Node[] = [];
+  while ((node = evaluated?.iterateNext?.())) {
+    result.push(node as T);
+  }
+  return result;
+}
+
+export function closestElement(node: Element | Text) {
+  if (node instanceof Text) {
+    return node.parentElement;
+  }
+  return node;
+}
+
+export function getNodeText(node: Node) {
+  return node.textContent;
+}
+
+export function setNodeText(node: Node, text: string) {
+  node.textContent = text;
+}
+
+export function nodeContains(descendant: Node, node: Node) {
+  if (descendant.contains(node)) {
+    return true;
+  }
+  if (node instanceof Attr) {
+    const ownerContainsAttr =
+      node.ownerElement &&
+      Object.values(node.ownerElement.attributes).indexOf(node) > -1;
+    if (descendant.contains(node.ownerElement) && ownerContainsAttr) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export const compareDescriptors = (
+  descriptor: KeyDescriptorInternal,
+  criteria: KeyDescriptorInternal
+) => {
+  const keyMatches =
+    descriptor.key === undefined ||
+    criteria.key === undefined ||
+    criteria.key === descriptor.key;
+  const nsMatches =
+    descriptor.ns === undefined ||
+    criteria.ns === undefined ||
+    descriptor.ns?.findIndex((ns) => criteria.ns?.includes(ns)) !== -1;
+
+  return keyMatches && nsMatches;
+};

package/src/observers/invisible/InvisibleWrapper.test.ts

@@ -0,0 +1,17 @@
+jest.autoMockOff();
+import { InvisibleWrapper } from './InvisibleWrapper';
+
+describe('invisible wrapper', () => {
+  it('wraps and unwraps', () => {
+    const wrapper = InvisibleWrapper();
+    const key = 'hello';
+    const translation = 'world';
+    const defaultValue = '!';
+
+    const wrapped = wrapper.wrap({ key, translation, defaultValue });
+    const unwraped = wrapper.unwrap(wrapped);
+    expect(unwraped.text).toEqual(translation);
+    expect(unwraped.keys[0].key).toEqual(key);
+    expect(unwraped.keys[0].defaultValue).toEqual(defaultValue);
+  });
+});

package/src/observers/invisible/InvisibleWrapper.ts

@@ -0,0 +1,96 @@
+import type {
+  WrapperAttributeXPathGetter,
+  KeyAndParams,
+  Unwrapped,
+  WrapperInterface,
+  WrapperWrapFunction,
+  TranslateProps,
+} from '@tolgee/core';
+import {
+  decodeFromText,
+  encodeMessage,
+  INVISIBLE_CHARACTERS,
+  removeSecrets,
+  stringToCodePoints,
+} from './secret';
+
+import { ValueMemory } from './ValueMemory';
+
+type EncodeValue = {
+  // key
+  k: string;
+  // namespaces
+  n: string[] | string | undefined;
+  // default value
+  d: string | undefined;
+};
+
+export const InvisibleWrapper = (): WrapperInterface => {
+  const keyMemory = ValueMemory();
+
+  const unwrap = (text: string): Unwrapped => {
+    const keysAndParams = [] as KeyAndParams[];
+    const messages = decodeFromText(text);
+
+    messages.forEach((msg: string) => {
+      const [valueCode] = stringToCodePoints(msg);
+      const encodedValue = keyMemory.numberToValue(valueCode);
+      const { k: key, d: defaultValue, n: ns } = decodeValue(encodedValue);
+      keysAndParams.push({
+        key,
+        defaultValue,
+        ns,
+      });
+    });
+
+    const result = removeSecrets(text);
+
+    return { text: result, keys: keysAndParams };
+  };
+
+  const encodeValue = (data: TranslateProps) => {
+    const value: EncodeValue = {
+      k: data.key,
+      n: data.ns,
+      d: data.defaultValue,
+    };
+    return JSON.stringify(value);
+  };
+
+  const decodeValue = (value: string) => {
+    return JSON.parse(value) as EncodeValue;
+  };
+
+  const wrap: WrapperWrapFunction = ({
+    key,
+    defaultValue,
+    translation,
+    ns,
+  }) => {
+    const encodedValue = encodeValue({ key, ns, defaultValue });
+    const code = keyMemory.valueToNumber(encodedValue);
+
+    const value = translation || '';
+    const invisibleMark = encodeMessage(String.fromCodePoint(code));
+
+    return typeof value === 'string' ? value + invisibleMark : value;
+  };
+
+  const getTextXPath = () => {
+    return `./descendant-or-self::text()[contains(., '${INVISIBLE_CHARACTERS[0]}${INVISIBLE_CHARACTERS[0]}') or contains(., '${INVISIBLE_CHARACTERS[1]}${INVISIBLE_CHARACTERS[0]}')]`;
+  };
+
+  const getAttributeXPath: WrapperAttributeXPathGetter = ({
+    tag,
+    attribute,
+  }) => {
+    return `descendant-or-self::${tag}/@${attribute}[contains(., '${INVISIBLE_CHARACTERS[0]}${INVISIBLE_CHARACTERS[0]}') or contains(., '${INVISIBLE_CHARACTERS[1]}${INVISIBLE_CHARACTERS[0]}')]`;
+  };
+
+  return Object.freeze({
+    unwrap,
+    wrap,
+    getTextXPath,
+    getAttributeXPath,
+  });
+};

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

@@ -0,0 +1,25 @@
+jest.dontMock('./ValueMemory');
+import { ValueMemory, ValueMemoryInstance } from './ValueMemory';
+
+describe('Value memory', () => {
+  let valueMemory: ValueMemoryInstance;
+
+  beforeEach(() => {
+    valueMemory = 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/observers/invisible/ValueMemory.ts

@@ -0,0 +1,20 @@
+export const ValueMemory = () => {
+  const values: string[] = [];
+
+  const valueToNumber = (key: string) => {
+    let index = values.indexOf(key);
+    if (index === -1) {
+      index = values.length;
+      values.push(key);
+    }
+    return index;
+  };
+
+  const numberToValue = (num: number) => {
+    return values[num];
+  };
+
+  return Object.freeze({ valueToNumber, numberToValue });
+};
+
+export type ValueMemoryInstance = ReturnType<typeof ValueMemory>;

package/src/observers/invisible/encoderPolyfill.ts

@@ -0,0 +1,96 @@
+// TextEncoder/TextDecoder polyfills for utf-8 - an implementation of TextEncoder/TextDecoder APIs
+// Written in 2013 by Viktor Mukhachev <vic99999@yandex.ru>
+// To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty.
+// You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+// Some important notes about the polyfill below:
+// Native TextEncoder/TextDecoder implementation is overwritten
+// String.prototype.codePointAt polyfill not included, as well as String.fromCodePoint
+// TextEncoder.prototype.encode returns a regular array instead of Uint8Array
+// No options (fatal of the TextDecoder constructor and stream of the TextDecoder.prototype.decode method) are supported.
+// TextDecoder.prototype.decode does not valid byte sequences
+// This is a demonstrative implementation not intended to have the best performance
+
+// http://encoding.spec.whatwg.org/#textencoder
+
+// http://encoding.spec.whatwg.org/#textencoder
+
+function PTextEncoder() {}
+
+PTextEncoder.prototype.encode = function (string: string) {
+  const octets = [];
+  const length = string.length;
+  let i = 0;
+  while (i < length) {
+    const codePoint = string.codePointAt(i)!;
+    let c = 0;
+    let bits = 0;
+    if (codePoint <= 0x0000007f) {
+      c = 0;
+      bits = 0x00;
+    } else if (codePoint <= 0x000007ff) {
+      c = 6;
+      bits = 0xc0;
+    } else if (codePoint <= 0x0000ffff) {
+      c = 12;
+      bits = 0xe0;
+    } else if (codePoint <= 0x001fffff) {
+      c = 18;
+      bits = 0xf0;
+    }
+    octets.push(bits | (codePoint >> c));
+    c -= 6;
+    while (c >= 0) {
+      octets.push(0x80 | ((codePoint >> c) & 0x3f));
+      c -= 6;
+    }
+    i += codePoint >= 0x10000 ? 2 : 1;
+  }
+  return octets;
+};
+
+function PTextDecoder() {}
+
+PTextDecoder.prototype.decode = function (octets: any[]) {
+  let string = '';
+  let i = 0;
+  while (i < octets.length) {
+    let octet = octets[i];
+    let bytesNeeded = 0;
+    let codePoint = 0;
+    if (octet <= 0x7f) {
+      bytesNeeded = 0;
+      codePoint = octet & 0xff;
+    } else if (octet <= 0xdf) {
+      bytesNeeded = 1;
+      codePoint = octet & 0x1f;
+    } else if (octet <= 0xef) {
+      bytesNeeded = 2;
+      codePoint = octet & 0x0f;
+    } else if (octet <= 0xf4) {
+      bytesNeeded = 3;
+      codePoint = octet & 0x07;
+    }
+    if (octets.length - i - bytesNeeded > 0) {
+      let k = 0;
+      while (k < bytesNeeded) {
+        octet = octets[i + k + 1];
+        codePoint = (codePoint << 6) | (octet & 0x3f);
+        k += 1;
+      }
+    } else {
+      codePoint = 0xfffd;
+      bytesNeeded = octets.length - i;
+    }
+    string += String.fromCodePoint(codePoint);
+    i += bytesNeeded + 1;
+  }
+  return string;
+};
+
+export const Encoder = (typeof TextEncoder === 'undefined'
+  ? PTextEncoder
+  : TextEncoder) as unknown as typeof TextEncoder;
+export const Decoder = (typeof TextDecoder === 'undefined'
+  ? PTextDecoder
+  : TextDecoder) as unknown as typeof TextDecoder;