refactor: separate elements logic into a standalone package (#9285)

packages/common/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["../eslintrc.base.json"]
+}

packages/common/README.md

@@ -0,0 +1,19 @@
+# @excalidraw/common
+
+## Install
+
+```bash
+npm install @excalidraw/common
+```
+
+If you prefer Yarn over npm, use this command to install the Excalidraw utils package:
+
+```bash
+yarn add @excalidraw/common
+```
+
+With PNPM, similarly install the package with this command:
+
+```bash
+pnpm add @excalidraw/common
+```

packages/common/global.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="vite/client" />
+import "@excalidraw/excalidraw/global";
+import "@excalidraw/excalidraw/css";

packages/common/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@excalidraw/common",
+  "version": "0.1.0",
+  "type": "module",
+  "types": "./dist/types/common/index.d.ts",
+  "main": "./dist/prod/index.js",
+  "module": "./dist/prod/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/common/index.d.ts",
+      "development": "./dist/dev/index.js",
+      "production": "./dist/prod/index.js",
+      "default": "./dist/prod/index.js"
+    },
+    "./*": {
+      "types": "./../common/dist/types/common/*"
+    }
+  },
+  "files": [
+    "dist/*"
+  ],
+  "description": "Excalidraw common functions, constants, etc.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "keywords": [
+    "excalidraw",
+    "excalidraw-utils"
+  ],
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not ie <= 11",
+      "not op_mini all",
+      "not safari < 12",
+      "not kaios <= 2.5",
+      "not edge < 79",
+      "not chrome < 70",
+      "not and_uc < 13",
+      "not samsung < 10"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "dependencies": {
+    "es6-promise-pool": "2.5.0",
+    "nanoid": "3.3.3",
+    "open-color": "1.9.1",
+    "roughjs": "4.6.4"
+  },
+  "devDependencies": {
+    "typescript": "4.9.4"
+  },
+  "bugs": "https://github.com/excalidraw/excalidraw/issues",
+  "repository": "https://github.com/excalidraw/excalidraw",
+  "scripts": {
+    "gen:types": "rm -rf types && tsc",
+    "build:esm": "rm -rf dist && node ../../scripts/buildBase.js && yarn gen:types"
+  }
+}

packages/common/src/binary-heap.ts

@@ -0,0 +1,105 @@
+export class BinaryHeap<T> {
+  private content: T[] = [];
+
+  constructor(private scoreFunction: (node: T) => number) {}
+
+  sinkDown(idx: number) {
+    const node = this.content[idx];
+    while (idx > 0) {
+      const parentN = ((idx + 1) >> 1) - 1;
+      const parent = this.content[parentN];
+      if (this.scoreFunction(node) < this.scoreFunction(parent)) {
+        this.content[parentN] = node;
+        this.content[idx] = parent;
+        idx = parentN; // TODO: Optimize
+      } else {
+        break;
+      }
+    }
+  }
+
+  bubbleUp(idx: number) {
+    const length = this.content.length;
+    const node = this.content[idx];
+    const score = this.scoreFunction(node);
+
+    while (true) {
+      const child2N = (idx + 1) << 1;
+      const child1N = child2N - 1;
+      let swap = null;
+      let child1Score = 0;
+
+      if (child1N < length) {
+        const child1 = this.content[child1N];
+        child1Score = this.scoreFunction(child1);
+        if (child1Score < score) {
+          swap = child1N;
+        }
+      }
+
+      if (child2N < length) {
+        const child2 = this.content[child2N];
+        const child2Score = this.scoreFunction(child2);
+        if (child2Score < (swap === null ? score : child1Score)) {
+          swap = child2N;
+        }
+      }
+
+      if (swap !== null) {
+        this.content[idx] = this.content[swap];
+        this.content[swap] = node;
+        idx = swap; // TODO: Optimize
+      } else {
+        break;
+      }
+    }
+  }
+
+  push(node: T) {
+    this.content.push(node);
+    this.sinkDown(this.content.length - 1);
+  }
+
+  pop(): T | null {
+    if (this.content.length === 0) {
+      return null;
+    }
+
+    const result = this.content[0];
+    const end = this.content.pop()!;
+
+    if (this.content.length > 0) {
+      this.content[0] = end;
+      this.bubbleUp(0);
+    }
+
+    return result;
+  }
+
+  remove(node: T) {
+    if (this.content.length === 0) {
+      return;
+    }
+
+    const i = this.content.indexOf(node);
+    const end = this.content.pop()!;
+
+    if (i < this.content.length) {
+      this.content[i] = end;
+
+      if (this.scoreFunction(end) < this.scoreFunction(node)) {
+        this.sinkDown(i);
+      } else {
+        this.bubbleUp(i);
+      }
+    }
+  }
+
+  size(): number {
+    return this.content.length;
+  }
+
+  rescoreElement(node: T) {
+    this.sinkDown(this.content.indexOf(node));
+  }
+}

packages/common/src/colors.ts

@@ -0,0 +1,171 @@
+import oc from "open-color";
+
+import type { Merge } from "./utility-types";
+
+// FIXME can't put to utils.ts rn because of circular dependency
+const pick = <R extends Record<string, any>, K extends readonly (keyof R)[]>(
+  source: R,
+  keys: K,
+) => {
+  return keys.reduce((acc, key: K[number]) => {
+    if (key in source) {
+      acc[key] = source[key];
+    }
+    return acc;
+  }, {} as Pick<R, K[number]>) as Pick<R, K[number]>;
+};
+
+export type ColorPickerColor =
+  | Exclude<keyof oc, "indigo" | "lime">
+  | "transparent"
+  | "bronze";
+export type ColorTuple = readonly [string, string, string, string, string];
+export type ColorPalette = Merge<
+  Record<ColorPickerColor, ColorTuple>,
+  { black: "#1e1e1e"; white: "#ffffff"; transparent: "transparent" }
+>;
+
+// used general type instead of specific type (ColorPalette) to support custom colors
+export type ColorPaletteCustom = { [key: string]: ColorTuple | string };
+export type ColorShadesIndexes = [number, number, number, number, number];
+
+export const MAX_CUSTOM_COLORS_USED_IN_CANVAS = 5;
+export const COLORS_PER_ROW = 5;
+
+export const DEFAULT_CHART_COLOR_INDEX = 4;
+
+export const DEFAULT_ELEMENT_STROKE_COLOR_INDEX = 4;
+export const DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX = 1;
+export const ELEMENTS_PALETTE_SHADE_INDEXES = [0, 2, 4, 6, 8] as const;
+export const CANVAS_PALETTE_SHADE_INDEXES = [0, 1, 2, 3, 4] as const;
+
+export const getSpecificColorShades = (
+  color: Exclude<
+    ColorPickerColor,
+    "transparent" | "white" | "black" | "bronze"
+  >,
+  indexArr: Readonly<ColorShadesIndexes>,
+) => {
+  return indexArr.map((index) => oc[color][index]) as any as ColorTuple;
+};
+
+export const COLOR_PALETTE = {
+  transparent: "transparent",
+  black: "#1e1e1e",
+  white: "#ffffff",
+  // open-colors
+  gray: getSpecificColorShades("gray", ELEMENTS_PALETTE_SHADE_INDEXES),
+  red: getSpecificColorShades("red", ELEMENTS_PALETTE_SHADE_INDEXES),
+  pink: getSpecificColorShades("pink", ELEMENTS_PALETTE_SHADE_INDEXES),
+  grape: getSpecificColorShades("grape", ELEMENTS_PALETTE_SHADE_INDEXES),
+  violet: getSpecificColorShades("violet", ELEMENTS_PALETTE_SHADE_INDEXES),
+  blue: getSpecificColorShades("blue", ELEMENTS_PALETTE_SHADE_INDEXES),
+  cyan: getSpecificColorShades("cyan", ELEMENTS_PALETTE_SHADE_INDEXES),
+  teal: getSpecificColorShades("teal", ELEMENTS_PALETTE_SHADE_INDEXES),
+  green: getSpecificColorShades("green", ELEMENTS_PALETTE_SHADE_INDEXES),
+  yellow: getSpecificColorShades("yellow", ELEMENTS_PALETTE_SHADE_INDEXES),
+  orange: getSpecificColorShades("orange", ELEMENTS_PALETTE_SHADE_INDEXES),
+  // radix bronze shades 3,5,7,9,11
+  bronze: ["#f8f1ee", "#eaddd7", "#d2bab0", "#a18072", "#846358"],
+} as ColorPalette;
+
+const COMMON_ELEMENT_SHADES = pick(COLOR_PALETTE, [
+  "cyan",
+  "blue",
+  "violet",
+  "grape",
+  "pink",
+  "green",
+  "teal",
+  "yellow",
+  "orange",
+  "red",
+]);
+
+// -----------------------------------------------------------------------------
+// quick picks defaults
+// -----------------------------------------------------------------------------
+
+// ORDER matters for positioning in quick picker
+export const DEFAULT_ELEMENT_STROKE_PICKS = [
+  COLOR_PALETTE.black,
+  COLOR_PALETTE.red[DEFAULT_ELEMENT_STROKE_COLOR_INDEX],
+  COLOR_PALETTE.green[DEFAULT_ELEMENT_STROKE_COLOR_INDEX],
+  COLOR_PALETTE.blue[DEFAULT_ELEMENT_STROKE_COLOR_INDEX],
+  COLOR_PALETTE.yellow[DEFAULT_ELEMENT_STROKE_COLOR_INDEX],
+] as ColorTuple;
+
+// ORDER matters for positioning in quick picker
+export const DEFAULT_ELEMENT_BACKGROUND_PICKS = [
+  COLOR_PALETTE.transparent,
+  COLOR_PALETTE.red[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+  COLOR_PALETTE.green[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+  COLOR_PALETTE.blue[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+  COLOR_PALETTE.yellow[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+] as ColorTuple;
+
+// ORDER matters for positioning in quick picker
+export const DEFAULT_CANVAS_BACKGROUND_PICKS = [
+  COLOR_PALETTE.white,
+  // radix slate2
+  "#f8f9fa",
+  // radix blue2
+  "#f5faff",
+  // radix yellow2
+  "#fffce8",
+  // radix bronze2
+  "#fdf8f6",
+] as ColorTuple;
+
+// -----------------------------------------------------------------------------
+// palette defaults
+// -----------------------------------------------------------------------------
+
+export const DEFAULT_ELEMENT_STROKE_COLOR_PALETTE = {
+  // 1st row
+  transparent: COLOR_PALETTE.transparent,
+  white: COLOR_PALETTE.white,
+  gray: COLOR_PALETTE.gray,
+  black: COLOR_PALETTE.black,
+  bronze: COLOR_PALETTE.bronze,
+  // rest
+  ...COMMON_ELEMENT_SHADES,
+} as const;
+
+// ORDER matters for positioning in pallete (5x3 grid)s
+export const DEFAULT_ELEMENT_BACKGROUND_COLOR_PALETTE = {
+  transparent: COLOR_PALETTE.transparent,
+  white: COLOR_PALETTE.white,
+  gray: COLOR_PALETTE.gray,
+  black: COLOR_PALETTE.black,
+  bronze: COLOR_PALETTE.bronze,
+
+  ...COMMON_ELEMENT_SHADES,
+} as const;
+
+// -----------------------------------------------------------------------------
+// helpers
+// -----------------------------------------------------------------------------
+
+// !!!MUST BE WITHOUT GRAY, TRANSPARENT AND BLACK!!!
+export const getAllColorsSpecificShade = (index: 0 | 1 | 2 | 3 | 4) =>
+  [
+    // 2nd row
+    COLOR_PALETTE.cyan[index],
+    COLOR_PALETTE.blue[index],
+    COLOR_PALETTE.violet[index],
+    COLOR_PALETTE.grape[index],
+    COLOR_PALETTE.pink[index],
+
+    // 3rd row
+    COLOR_PALETTE.green[index],
+    COLOR_PALETTE.teal[index],
+    COLOR_PALETTE.yellow[index],
+    COLOR_PALETTE.orange[index],
+    COLOR_PALETTE.red[index],
+  ] as const;
+
+export const rgbToHex = (r: number, g: number, b: number) =>
+  `#${((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1)}`;
+
+// -----------------------------------------------------------------------------

packages/common/src/constants.ts

@@ -0,0 +1,471 @@
+import type {
+  ExcalidrawElement,
+  FontFamilyValues,
+} from "@excalidraw/element/types";
+import type { AppProps, AppState } from "@excalidraw/excalidraw/types";
+
+import { COLOR_PALETTE } from "./colors";
+
+export const isDarwin = /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+export const isWindows = /^Win/.test(navigator.platform);
+export const isAndroid = /\b(android)\b/i.test(navigator.userAgent);
+export const isFirefox =
+  "netscape" in window &&
+  navigator.userAgent.indexOf("rv:") > 1 &&
+  navigator.userAgent.indexOf("Gecko") > 1;
+export const isChrome = navigator.userAgent.indexOf("Chrome") !== -1;
+export const isSafari =
+  !isChrome && navigator.userAgent.indexOf("Safari") !== -1;
+export const isIOS =
+  /iPad|iPhone/.test(navigator.platform) ||
+  // iPadOS 13+
+  (navigator.userAgent.includes("Mac") && "ontouchend" in document);
+// keeping function so it can be mocked in test
+export const isBrave = () =>
+  (navigator as any).brave?.isBrave?.name === "isBrave";
+
+export const supportsResizeObserver =
+  typeof window !== "undefined" && "ResizeObserver" in window;
+
+export const APP_NAME = "Excalidraw";
+
+// distance when creating text before it's considered `autoResize: false`
+// we're using higher threshold so that clicks that end up being drags
+// don't unintentionally create text elements that are wrapped to a few chars
+// (happens a lot with fast clicks with the text tool)
+export const TEXT_AUTOWRAP_THRESHOLD = 36; // px
+export const DRAGGING_THRESHOLD = 10; // px
+export const LINE_CONFIRM_THRESHOLD = 8; // px
+export const ELEMENT_SHIFT_TRANSLATE_AMOUNT = 5;
+export const ELEMENT_TRANSLATE_AMOUNT = 1;
+export const TEXT_TO_CENTER_SNAP_THRESHOLD = 30;
+export const SHIFT_LOCKING_ANGLE = Math.PI / 12;
+export const DEFAULT_LASER_COLOR = "red";
+export const CURSOR_TYPE = {
+  TEXT: "text",
+  CROSSHAIR: "crosshair",
+  GRABBING: "grabbing",
+  GRAB: "grab",
+  POINTER: "pointer",
+  MOVE: "move",
+  AUTO: "",
+};
+export const POINTER_BUTTON = {
+  MAIN: 0,
+  WHEEL: 1,
+  SECONDARY: 2,
+  TOUCH: -1,
+  ERASER: 5,
+} as const;
+
+export const POINTER_EVENTS = {
+  enabled: "all",
+  disabled: "none",
+  // asserted as any so it can be freely assigned to React Element
+  // "pointerEnvets" CSS prop
+  inheritFromUI: "var(--ui-pointerEvents)" as any,
+} as const;
+
+export enum EVENT {
+  COPY = "copy",
+  PASTE = "paste",
+  CUT = "cut",
+  KEYDOWN = "keydown",
+  KEYUP = "keyup",
+  MOUSE_MOVE = "mousemove",
+  RESIZE = "resize",
+  UNLOAD = "unload",
+  FOCUS = "focus",
+  BLUR = "blur",
+  DRAG_OVER = "dragover",
+  DROP = "drop",
+  GESTURE_END = "gestureend",
+  BEFORE_UNLOAD = "beforeunload",
+  GESTURE_START = "gesturestart",
+  GESTURE_CHANGE = "gesturechange",
+  POINTER_MOVE = "pointermove",
+  POINTER_DOWN = "pointerdown",
+  POINTER_UP = "pointerup",
+  STATE_CHANGE = "statechange",
+  WHEEL = "wheel",
+  TOUCH_START = "touchstart",
+  TOUCH_END = "touchend",
+  HASHCHANGE = "hashchange",
+  VISIBILITY_CHANGE = "visibilitychange",
+  SCROLL = "scroll",
+  // custom events
+  EXCALIDRAW_LINK = "excalidraw-link",
+  MENU_ITEM_SELECT = "menu.itemSelect",
+  MESSAGE = "message",
+  FULLSCREENCHANGE = "fullscreenchange",
+}
+
+export const YOUTUBE_STATES = {
+  UNSTARTED: -1,
+  ENDED: 0,
+  PLAYING: 1,
+  PAUSED: 2,
+  BUFFERING: 3,
+  CUED: 5,
+} as const;
+
+export const ENV = {
+  TEST: "test",
+  DEVELOPMENT: "development",
+};
+
+export const CLASSES = {
+  SHAPE_ACTIONS_MENU: "App-menu__left",
+  ZOOM_ACTIONS: "zoom-actions",
+  SEARCH_MENU_INPUT_WRAPPER: "layer-ui__search-inputWrapper",
+};
+
+export const CJK_HAND_DRAWN_FALLBACK_FONT = "Xiaolai";
+export const WINDOWS_EMOJI_FALLBACK_FONT = "Segoe UI Emoji";
+
+/**
+ * // TODO: shouldn't be really `const`, likely neither have integers as values, due to value for the custom fonts, which should likely be some hash.
+ *
+ * Let's think this through and consider:
+ * - https://developer.mozilla.org/en-US/docs/Web/CSS/generic-family
+ * - https://drafts.csswg.org/css-fonts-4/#font-family-prop
+ * - https://learn.microsoft.com/en-us/typography/opentype/spec/ibmfc
+ */
+export const FONT_FAMILY = {
+  Virgil: 1,
+  Helvetica: 2,
+  Cascadia: 3,
+  // leave 4 unused as it was historically used for Assistant (which we don't use anymore) or custom font (Obsidian)
+  Excalifont: 5,
+  Nunito: 6,
+  "Lilita One": 7,
+  "Comic Shanns": 8,
+  "Liberation Sans": 9,
+};
+
+export const FONT_FAMILY_FALLBACKS = {
+  [CJK_HAND_DRAWN_FALLBACK_FONT]: 100,
+  [WINDOWS_EMOJI_FALLBACK_FONT]: 1000,
+};
+
+export const getFontFamilyFallbacks = (
+  fontFamily: number,
+): Array<keyof typeof FONT_FAMILY_FALLBACKS> => {
+  switch (fontFamily) {
+    case FONT_FAMILY.Excalifont:
+      return [CJK_HAND_DRAWN_FALLBACK_FONT, WINDOWS_EMOJI_FALLBACK_FONT];
+    default:
+      return [WINDOWS_EMOJI_FALLBACK_FONT];
+  }
+};
+
+export const THEME = {
+  LIGHT: "light",
+  DARK: "dark",
+} as const;
+
+export const FRAME_STYLE = {
+  strokeColor: "#bbb" as ExcalidrawElement["strokeColor"],
+  strokeWidth: 2 as ExcalidrawElement["strokeWidth"],
+  strokeStyle: "solid" as ExcalidrawElement["strokeStyle"],
+  fillStyle: "solid" as ExcalidrawElement["fillStyle"],
+  roughness: 0 as ExcalidrawElement["roughness"],
+  roundness: null as ExcalidrawElement["roundness"],
+  backgroundColor: "transparent" as ExcalidrawElement["backgroundColor"],
+  radius: 8,
+  nameOffsetY: 3,
+  nameColorLightTheme: "#999999",
+  nameColorDarkTheme: "#7a7a7a",
+  nameFontSize: 14,
+  nameLineHeight: 1.25,
+};
+
+export const MIN_FONT_SIZE = 1;
+export const DEFAULT_FONT_SIZE = 20;
+export const DEFAULT_FONT_FAMILY: FontFamilyValues = FONT_FAMILY.Excalifont;
+export const DEFAULT_TEXT_ALIGN = "left";
+export const DEFAULT_VERTICAL_ALIGN = "top";
+export const DEFAULT_VERSION = "{version}";
+export const DEFAULT_TRANSFORM_HANDLE_SPACING = 2;
+
+export const SIDE_RESIZING_THRESHOLD = 2 * DEFAULT_TRANSFORM_HANDLE_SPACING;
+// a small epsilon to make side resizing always take precedence
+// (avoids an increase in renders and changes to tests)
+export const EPSILON = 0.00001;
+export const DEFAULT_COLLISION_THRESHOLD =
+  2 * SIDE_RESIZING_THRESHOLD - EPSILON;
+
+export const COLOR_WHITE = "#ffffff";
+export const COLOR_CHARCOAL_BLACK = "#1e1e1e";
+// keep this in sync with CSS
+export const COLOR_VOICE_CALL = "#a2f1a6";
+
+export const CANVAS_ONLY_ACTIONS = ["selectAll"];
+
+export const DEFAULT_GRID_SIZE = 20;
+export const DEFAULT_GRID_STEP = 5;
+
+export const IMAGE_MIME_TYPES = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  bmp: "image/bmp",
+  ico: "image/x-icon",
+  avif: "image/avif",
+  jfif: "image/jfif",
+} as const;
+
+export const MIME_TYPES = {
+  text: "text/plain",
+  html: "text/html",
+  json: "application/json",
+  // excalidraw data
+  excalidraw: "application/vnd.excalidraw+json",
+  excalidrawlib: "application/vnd.excalidrawlib+json",
+  // image-encoded excalidraw data
+  "excalidraw.svg": "image/svg+xml",
+  "excalidraw.png": "image/png",
+  // binary
+  binary: "application/octet-stream",
+  // image
+  ...IMAGE_MIME_TYPES,
+} as const;
+
+export const ALLOWED_PASTE_MIME_TYPES = [
+  MIME_TYPES.text,
+  MIME_TYPES.html,
+  ...Object.values(IMAGE_MIME_TYPES),
+] as const;
+
+export const EXPORT_IMAGE_TYPES = {
+  png: "png",
+  svg: "svg",
+  clipboard: "clipboard",
+} as const;
+
+export const EXPORT_DATA_TYPES = {
+  excalidraw: "excalidraw",
+  excalidrawClipboard: "excalidraw/clipboard",
+  excalidrawLibrary: "excalidrawlib",
+  excalidrawClipboardWithAPI: "excalidraw-api/clipboard",
+} as const;
+
+export const EXPORT_SOURCE =
+  window.EXCALIDRAW_EXPORT_SOURCE || window.location.origin;
+
+// time in milliseconds
+export const IMAGE_RENDER_TIMEOUT = 500;
+export const TAP_TWICE_TIMEOUT = 300;
+export const TOUCH_CTX_MENU_TIMEOUT = 500;
+export const TITLE_TIMEOUT = 10000;
+export const VERSION_TIMEOUT = 30000;
+export const SCROLL_TIMEOUT = 100;
+export const ZOOM_STEP = 0.1;
+export const MIN_ZOOM = 0.1;
+export const MAX_ZOOM = 30;
+export const HYPERLINK_TOOLTIP_DELAY = 300;
+
+// Report a user inactive after IDLE_THRESHOLD milliseconds
+export const IDLE_THRESHOLD = 60_000;
+// Report a user active each ACTIVE_THRESHOLD milliseconds
+export const ACTIVE_THRESHOLD = 3_000;
+
+// duplicates --theme-filter, should be removed soon
+export const THEME_FILTER = "invert(93%) hue-rotate(180deg)";
+
+export const URL_QUERY_KEYS = {
+  addLibrary: "addLibrary",
+} as const;
+
+export const URL_HASH_KEYS = {
+  addLibrary: "addLibrary",
+} as const;
+
+export const DEFAULT_UI_OPTIONS: AppProps["UIOptions"] = {
+  canvasActions: {
+    changeViewBackgroundColor: true,
+    clearCanvas: true,
+    export: { saveFileToDisk: true },
+    loadScene: true,
+    saveToActiveFile: true,
+    toggleTheme: null,
+    saveAsImage: true,
+  },
+  tools: {
+    image: true,
+  },
+};
+
+// breakpoints
+// -----------------------------------------------------------------------------
+// md screen
+export const MQ_MAX_WIDTH_PORTRAIT = 730;
+export const MQ_MAX_WIDTH_LANDSCAPE = 1000;
+export const MQ_MAX_HEIGHT_LANDSCAPE = 500;
+// sidebar
+export const MQ_RIGHT_SIDEBAR_MIN_WIDTH = 1229;
+// -----------------------------------------------------------------------------
+
+export const MAX_DECIMALS_FOR_SVG_EXPORT = 2;
+
+export const EXPORT_SCALES = [1, 2, 3];
+export const DEFAULT_EXPORT_PADDING = 10; // px
+
+export const DEFAULT_MAX_IMAGE_WIDTH_OR_HEIGHT = 1440;
+
+export const MAX_ALLOWED_FILE_BYTES = 4 * 1024 * 1024;
+
+export const SVG_NS = "http://www.w3.org/2000/svg";
+
+export const ENCRYPTION_KEY_BITS = 128;
+
+export const VERSIONS = {
+  excalidraw: 2,
+  excalidrawLibrary: 2,
+} as const;
+
+export const BOUND_TEXT_PADDING = 5;
+export const ARROW_LABEL_WIDTH_FRACTION = 0.7;
+export const ARROW_LABEL_FONT_SIZE_TO_MIN_WIDTH_RATIO = 11;
+
+export const VERTICAL_ALIGN = {
+  TOP: "top",
+  MIDDLE: "middle",
+  BOTTOM: "bottom",
+};
+
+export const TEXT_ALIGN = {
+  LEFT: "left",
+  CENTER: "center",
+  RIGHT: "right",
+};
+
+export const ELEMENT_READY_TO_ERASE_OPACITY = 20;
+
+// Radius represented as 25% of element's largest side (width/height).
+// Used for LEGACY and PROPORTIONAL_RADIUS algorithms, or when the element is
+// below the cutoff size.
+export const DEFAULT_PROPORTIONAL_RADIUS = 0.25;
+// Fixed radius for the ADAPTIVE_RADIUS algorithm. In pixels.
+export const DEFAULT_ADAPTIVE_RADIUS = 32;
+// roundness type (algorithm)
+export const ROUNDNESS = {
+  // Used for legacy rounding (rectangles), which currently works the same
+  // as PROPORTIONAL_RADIUS, but we need to differentiate for UI purposes and
+  // forwards-compat.
+  LEGACY: 1,
+
+  // Used for linear elements & diamonds
+  PROPORTIONAL_RADIUS: 2,
+
+  // Current default algorithm for rectangles, using fixed pixel radius.
+  // It's working similarly to a regular border-radius, but attemps to make
+  // radius visually similar across differnt element sizes, especially
+  // very large and very small elements.
+  //
+  // NOTE right now we don't allow configuration and use a constant radius
+  // (see DEFAULT_ADAPTIVE_RADIUS constant)
+  ADAPTIVE_RADIUS: 3,
+} as const;
+
+export const ROUGHNESS = {
+  architect: 0,
+  artist: 1,
+  cartoonist: 2,
+} as const;
+
+export const STROKE_WIDTH = {
+  thin: 1,
+  bold: 2,
+  extraBold: 4,
+} as const;
+
+export const DEFAULT_ELEMENT_PROPS: {
+  strokeColor: ExcalidrawElement["strokeColor"];
+  backgroundColor: ExcalidrawElement["backgroundColor"];
+  fillStyle: ExcalidrawElement["fillStyle"];
+  strokeWidth: ExcalidrawElement["strokeWidth"];
+  strokeStyle: ExcalidrawElement["strokeStyle"];
+  roughness: ExcalidrawElement["roughness"];
+  opacity: ExcalidrawElement["opacity"];
+  locked: ExcalidrawElement["locked"];
+} = {
+  strokeColor: COLOR_PALETTE.black,
+  backgroundColor: COLOR_PALETTE.transparent,
+  fillStyle: "solid",
+  strokeWidth: 2,
+  strokeStyle: "solid",
+  roughness: ROUGHNESS.artist,
+  opacity: 100,
+  locked: false,
+};
+
+export const LIBRARY_SIDEBAR_TAB = "library";
+export const CANVAS_SEARCH_TAB = "search";
+
+export const DEFAULT_SIDEBAR = {
+  name: "default",
+  defaultTab: LIBRARY_SIDEBAR_TAB,
+} as const;
+
+export const LIBRARY_DISABLED_TYPES = new Set([
+  "iframe",
+  "embeddable",
+  "image",
+] as const);
+
+// use these constants to easily identify reference sites
+export const TOOL_TYPE = {
+  selection: "selection",
+  rectangle: "rectangle",
+  diamond: "diamond",
+  ellipse: "ellipse",
+  arrow: "arrow",
+  line: "line",
+  freedraw: "freedraw",
+  text: "text",
+  image: "image",
+  eraser: "eraser",
+  hand: "hand",
+  frame: "frame",
+  magicframe: "magicframe",
+  embeddable: "embeddable",
+  laser: "laser",
+} as const;
+
+export const EDITOR_LS_KEYS = {
+  OAI_API_KEY: "excalidraw-oai-api-key",
+  // legacy naming (non)scheme
+  MERMAID_TO_EXCALIDRAW: "mermaid-to-excalidraw",
+  PUBLISH_LIBRARY: "publish-library-data",
+} as const;
+
+/**
+ * not translated as this is used only in public, stateless API as default value
+ * where filename is optional and we can't retrieve name from app state
+ */
+export const DEFAULT_FILENAME = "Untitled";
+
+export const STATS_PANELS = { generalStats: 1, elementProperties: 2 } as const;
+
+export const MIN_WIDTH_OR_HEIGHT = 1;
+
+export const ARROW_TYPE: { [T in AppState["currentItemArrowType"]]: T } = {
+  sharp: "sharp",
+  round: "round",
+  elbow: "elbow",
+};
+
+export const DEFAULT_REDUCED_GLOBAL_ALPHA = 0.3;
+export const ELEMENT_LINK_KEY = "element";
+
+/** used in tests */
+export const ORIG_ID = Symbol.for("__test__originalId__");
+
+export enum UserIdleState {
+  ACTIVE = "active",
+  AWAY = "away",
+  IDLE = "idle",
+}

packages/common/src/font-metadata.ts

@@ -0,0 +1,170 @@
+import type {
+  ExcalidrawTextElement,
+  FontFamilyValues,
+} from "@excalidraw/element/types";
+
+import { FONT_FAMILY, FONT_FAMILY_FALLBACKS } from "./constants";
+
+/**
+ * Encapsulates font metrics with additional font metadata.
+ * */
+export interface FontMetadata {
+  /** for head & hhea metrics read the woff2 with https://fontdrop.info/ */
+  metrics: {
+    /** head.unitsPerEm metric */
+    unitsPerEm: 1000 | 1024 | 2048;
+    /** hhea.ascender metric */
+    ascender: number;
+    /** hhea.descender metric */
+    descender: number;
+    /** harcoded unitless line-height, https://github.com/excalidraw/excalidraw/pull/6360#issuecomment-1477635971 */
+    lineHeight: number;
+  };
+  /** flag to indicate a deprecated font */
+  deprecated?: true;
+  /** flag to indicate a server-side only font */
+  serverSide?: true;
+  /** flag to indiccate a local-only font */
+  local?: true;
+  /** flag to indicate a fallback font */
+  fallback?: true;
+}
+
+export const FONT_METADATA: Record<number, FontMetadata> = {
+  [FONT_FAMILY.Excalifont]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 886,
+      descender: -374,
+      lineHeight: 1.25,
+    },
+  },
+  [FONT_FAMILY.Nunito]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 1011,
+      descender: -353,
+      lineHeight: 1.35,
+    },
+  },
+  [FONT_FAMILY["Lilita One"]]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 923,
+      descender: -220,
+      lineHeight: 1.15,
+    },
+  },
+  [FONT_FAMILY["Comic Shanns"]]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 750,
+      descender: -250,
+      lineHeight: 1.25,
+    },
+  },
+  [FONT_FAMILY.Virgil]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 886,
+      descender: -374,
+      lineHeight: 1.25,
+    },
+    deprecated: true,
+  },
+  [FONT_FAMILY.Helvetica]: {
+    metrics: {
+      unitsPerEm: 2048,
+      ascender: 1577,
+      descender: -471,
+      lineHeight: 1.15,
+    },
+    deprecated: true,
+    local: true,
+  },
+  [FONT_FAMILY.Cascadia]: {
+    metrics: {
+      unitsPerEm: 2048,
+      ascender: 1900,
+      descender: -480,
+      lineHeight: 1.2,
+    },
+    deprecated: true,
+  },
+  [FONT_FAMILY["Liberation Sans"]]: {
+    metrics: {
+      unitsPerEm: 2048,
+      ascender: 1854,
+      descender: -434,
+      lineHeight: 1.15,
+    },
+    serverSide: true,
+  },
+  [FONT_FAMILY_FALLBACKS.Xiaolai]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 880,
+      descender: -144,
+      lineHeight: 1.15,
+    },
+    fallback: true,
+  },
+  [FONT_FAMILY_FALLBACKS["Segoe UI Emoji"]]: {
+    metrics: {
+      // reusing Excalifont metrics
+      unitsPerEm: 1000,
+      ascender: 886,
+      descender: -374,
+      lineHeight: 1.25,
+    },
+    local: true,
+    fallback: true,
+  },
+};
+
+/** Unicode ranges defined by google fonts */
+export const GOOGLE_FONTS_RANGES = {
+  LATIN:
+    "U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD",
+  LATIN_EXT:
+    "U+0100-02AF, U+0304, U+0308, U+0329, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF",
+  CYRILIC_EXT:
+    "U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F",
+  CYRILIC: "U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116",
+  VIETNAMESE:
+    "U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB",
+};
+
+/** local protocol to skip the local font from registering or inlining */
+export const LOCAL_FONT_PROTOCOL = "local:";
+
+/**
+ * Calculates vertical offset for a text with alphabetic baseline.
+ */
+export const getVerticalOffset = (
+  fontFamily: ExcalidrawTextElement["fontFamily"],
+  fontSize: ExcalidrawTextElement["fontSize"],
+  lineHeightPx: number,
+) => {
+  const { unitsPerEm, ascender, descender } =
+    FONT_METADATA[fontFamily]?.metrics ||
+    FONT_METADATA[FONT_FAMILY.Excalifont].metrics;
+
+  const fontSizeEm = fontSize / unitsPerEm;
+  const lineGap =
+    (lineHeightPx - fontSizeEm * ascender + fontSizeEm * descender) / 2;
+
+  const verticalOffset = fontSizeEm * ascender + lineGap;
+  return verticalOffset;
+};
+
+/**
+ * Gets line height for a selected family.
+ */
+export const getLineHeight = (fontFamily: FontFamilyValues) => {
+  const { lineHeight } =
+    FONT_METADATA[fontFamily]?.metrics ||
+    FONT_METADATA[FONT_FAMILY.Excalifont].metrics;
+
+  return lineHeight as ExcalidrawTextElement["lineHeight"];
+};

packages/common/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./binary-heap";
+export * from "./colors";
+export * from "./constants";
+export * from "./font-metadata";
+export * from "./queue";
+export * from "./keys";
+export * from "./points";
+export * from "./promise-pool";
+export * from "./random";
+export * from "./url";
+export * from "./utils";

packages/common/src/keys.ts

@@ -0,0 +1,151 @@
+import { isDarwin } from "./constants";
+
+import type { ValueOf } from "./utility-types";
+
+export const CODES = {
+  EQUAL: "Equal",
+  MINUS: "Minus",
+  NUM_ADD: "NumpadAdd",
+  NUM_SUBTRACT: "NumpadSubtract",
+  NUM_ZERO: "Numpad0",
+  BRACKET_RIGHT: "BracketRight",
+  BRACKET_LEFT: "BracketLeft",
+  ONE: "Digit1",
+  TWO: "Digit2",
+  THREE: "Digit3",
+  NINE: "Digit9",
+  QUOTE: "Quote",
+  ZERO: "Digit0",
+  SLASH: "Slash",
+  C: "KeyC",
+  D: "KeyD",
+  H: "KeyH",
+  V: "KeyV",
+  Z: "KeyZ",
+  Y: "KeyY",
+  R: "KeyR",
+  S: "KeyS",
+} as const;
+
+export const KEYS = {
+  ARROW_DOWN: "ArrowDown",
+  ARROW_LEFT: "ArrowLeft",
+  ARROW_RIGHT: "ArrowRight",
+  ARROW_UP: "ArrowUp",
+  PAGE_UP: "PageUp",
+  PAGE_DOWN: "PageDown",
+  BACKSPACE: "Backspace",
+  ALT: "Alt",
+  CTRL_OR_CMD: isDarwin ? "metaKey" : "ctrlKey",
+  DELETE: "Delete",
+  ENTER: "Enter",
+  ESCAPE: "Escape",
+  QUESTION_MARK: "?",
+  SPACE: " ",
+  TAB: "Tab",
+  CHEVRON_LEFT: "<",
+  CHEVRON_RIGHT: ">",
+  PERIOD: ".",
+  COMMA: ",",
+  SUBTRACT: "-",
+  SLASH: "/",
+
+  A: "a",
+  C: "c",
+  D: "d",
+  E: "e",
+  F: "f",
+  G: "g",
+  H: "h",
+  I: "i",
+  L: "l",
+  O: "o",
+  P: "p",
+  Q: "q",
+  R: "r",
+  S: "s",
+  T: "t",
+  V: "v",
+  X: "x",
+  Y: "y",
+  Z: "z",
+  K: "k",
+  W: "w",
+
+  0: "0",
+  1: "1",
+  2: "2",
+  3: "3",
+  4: "4",
+  5: "5",
+  6: "6",
+  7: "7",
+  8: "8",
+  9: "9",
+} as const;
+
+export type Key = keyof typeof KEYS;
+
+// defines key code mapping for matching codes as fallback to respective keys on non-latin keyboard layouts
+export const KeyCodeMap = new Map<ValueOf<typeof KEYS>, ValueOf<typeof CODES>>([
+  [KEYS.Z, CODES.Z],
+  [KEYS.Y, CODES.Y],
+]);
+
+export const isLatinChar = (key: string) => /^[a-z]$/.test(key.toLowerCase());
+
+/**
+ * Used to match key events for any keyboard layout, especially on Windows and Linux,
+ * where non-latin character with modified (CMD) is not substituted with latin-based alternative.
+ *
+ * Uses `event.key` when it's latin, otherwise fallbacks to `event.code` (if mapping exists).
+ *
+ * Example of pressing "z" on different layouts, with the chosen key or code highlighted in []:
+ *
+ * Layout                | Code  | Key | Comment
+ * --------------------- | ----- | --- | -------
+ * U.S.                  |  KeyZ  | [z] |
+ * Czech                 |  KeyY  | [z] |
+ * Turkish               |  KeyN  | [z] |
+ * French                |  KeyW  | [z] |
+ * Macedonian            | [KeyZ] |  з  | z with cmd; з is Cyrillic equivalent of z
+ * Russian               | [KeyZ] |  я  | z with cmd
+ * Serbian               | [KeyZ] |  ѕ  | z with cmd
+ * Greek                 | [KeyZ] |  ζ  | z with cmd; also ζ is Greek equivalent of z
+ * Hebrew                | [KeyZ] |  ז  | z with cmd; also ז is Hebrew equivalent of z
+ * Pinyin - Simplified   |  KeyZ  | [z] | due to IME
+ * Cangije - Traditional | [KeyZ] |  重 | z with cmd
+ * Japanese              | [KeyZ] |  つ | z with cmd
+ * 2-Set Korean          | [KeyZ] |  ㅋ | z with cmd
+ *
+ * More details in https://github.com/excalidraw/excalidraw/pull/5944
+ */
+export const matchKey = (
+  event: KeyboardEvent | React.KeyboardEvent<Element>,
+  key: ValueOf<typeof KEYS>,
+): boolean => {
+  // for latin layouts use key
+  if (key === event.key.toLowerCase()) {
+    return true;
+  }
+
+  // non-latin layouts fallback to code
+  const code = KeyCodeMap.get(key);
+  return Boolean(code && !isLatinChar(event.key) && event.code === code);
+};
+
+export const isArrowKey = (key: string) =>
+  key === KEYS.ARROW_LEFT ||
+  key === KEYS.ARROW_RIGHT ||
+  key === KEYS.ARROW_DOWN ||
+  key === KEYS.ARROW_UP;
+
+export const shouldResizeFromCenter = (event: MouseEvent | KeyboardEvent) =>
+  event.altKey;
+
+export const shouldMaintainAspectRatio = (event: MouseEvent | KeyboardEvent) =>
+  event.shiftKey;
+
+export const shouldRotateWithDiscreteAngle = (
+  event: MouseEvent | KeyboardEvent | React.PointerEvent<HTMLCanvasElement>,
+) => event.shiftKey;

packages/common/src/points.ts

@@ -0,0 +1,80 @@
+import {
+  pointFromPair,
+  type GlobalPoint,
+  type LocalPoint,
+} from "@excalidraw/math";
+
+import type { NullableGridSize } from "@excalidraw/excalidraw/types";
+
+export const getSizeFromPoints = (
+  points: readonly (GlobalPoint | LocalPoint)[],
+) => {
+  const xs = points.map((point) => point[0]);
+  const ys = points.map((point) => point[1]);
+  return {
+    width: Math.max(...xs) - Math.min(...xs),
+    height: Math.max(...ys) - Math.min(...ys),
+  };
+};
+
+/** @arg dimension, 0 for rescaling only x, 1 for y */
+export const rescalePoints = <Point extends GlobalPoint | LocalPoint>(
+  dimension: 0 | 1,
+  newSize: number,
+  points: readonly Point[],
+  normalize: boolean,
+): Point[] => {
+  const coordinates = points.map((point) => point[dimension]);
+  const maxCoordinate = Math.max(...coordinates);
+  const minCoordinate = Math.min(...coordinates);
+  const size = maxCoordinate - minCoordinate;
+  const scale = size === 0 ? 1 : newSize / size;
+
+  let nextMinCoordinate = Infinity;
+
+  const scaledPoints = points.map((point): Point => {
+    const newCoordinate = point[dimension] * scale;
+    const newPoint = [...point];
+    newPoint[dimension] = newCoordinate;
+    if (newCoordinate < nextMinCoordinate) {
+      nextMinCoordinate = newCoordinate;
+    }
+    return newPoint as Point;
+  });
+
+  if (!normalize) {
+    return scaledPoints;
+  }
+
+  if (scaledPoints.length === 2) {
+    // we don't translate two-point lines
+    return scaledPoints;
+  }
+
+  const translation = minCoordinate - nextMinCoordinate;
+
+  const nextPoints = scaledPoints.map((scaledPoint) =>
+    pointFromPair<Point>(
+      scaledPoint.map((value, currentDimension) => {
+        return currentDimension === dimension ? value + translation : value;
+      }) as [number, number],
+    ),
+  );
+
+  return nextPoints;
+};
+
+// TODO: Rounding this point causes some shake when free drawing
+export const getGridPoint = (
+  x: number,
+  y: number,
+  gridSize: NullableGridSize,
+): [number, number] => {
+  if (gridSize) {
+    return [
+      Math.round(x / gridSize) * gridSize,
+      Math.round(y / gridSize) * gridSize,
+    ];
+  }
+  return [x, y];
+};

packages/common/src/promise-pool.ts

@@ -0,0 +1,50 @@
+import Pool from "es6-promise-pool";
+
+// extending the missing types
+// relying on the [Index, T] to keep a correct order
+type TPromisePool<T, Index = number> = Pool<[Index, T][]> & {
+  addEventListener: (
+    type: "fulfilled",
+    listener: (event: { data: { result: [Index, T] } }) => void,
+  ) => (event: { data: { result: [Index, T] } }) => void;
+  removeEventListener: (
+    type: "fulfilled",
+    listener: (event: { data: { result: [Index, T] } }) => void,
+  ) => void;
+};
+
+export class PromisePool<T> {
+  private readonly pool: TPromisePool<T>;
+  private readonly entries: Record<number, T> = {};
+
+  constructor(
+    source: IterableIterator<Promise<void | readonly [number, T]>>,
+    concurrency: number,
+  ) {
+    this.pool = new Pool(
+      source as unknown as () => void | PromiseLike<[number, T][]>,
+      concurrency,
+    ) as TPromisePool<T>;
+  }
+
+  public all() {
+    const listener = (event: { data: { result: void | [number, T] } }) => {
+      if (event.data.result) {
+        // by default pool does not return the results, so we are gathering them manually
+        // with the correct call order (represented by the index in the tuple)
+        const [index, value] = event.data.result;
+        this.entries[index] = value;
+      }
+    };
+
+    this.pool.addEventListener("fulfilled", listener);
+
+    return this.pool.start().then(() => {
+      setTimeout(() => {
+        this.pool.removeEventListener("fulfilled", listener);
+      });
+
+      return Object.values(this.entries);
+    });
+  }
+}

packages/common/src/queue.ts

@@ -0,0 +1,48 @@
+import { promiseTry, resolvablePromise } from ".";
+
+import type { ResolvablePromise } from ".";
+
+import type { MaybePromise } from "./utility-types";
+
+type Job<T, TArgs extends unknown[]> = (...args: TArgs) => MaybePromise<T>;
+
+type QueueJob<T, TArgs extends unknown[]> = {
+  jobFactory: Job<T, TArgs>;
+  promise: ResolvablePromise<T>;
+  args: TArgs;
+};
+
+export class Queue {
+  private jobs: QueueJob<any, any[]>[] = [];
+  private running = false;
+
+  private tick() {
+    if (this.running) {
+      return;
+    }
+    const job = this.jobs.shift();
+    if (job) {
+      this.running = true;
+      job.promise.resolve(
+        promiseTry(job.jobFactory, ...job.args).finally(() => {
+          this.running = false;
+          this.tick();
+        }),
+      );
+    } else {
+      this.running = false;
+    }
+  }
+
+  push<TValue, TArgs extends unknown[]>(
+    jobFactory: Job<TValue, TArgs>,
+    ...args: TArgs
+  ): Promise<TValue> {
+    const promise = resolvablePromise<TValue>();
+    this.jobs.push({ jobFactory, promise, args });
+
+    this.tick();
+
+    return promise;
+  }
+}

packages/common/src/random.ts

@@ -0,0 +1,16 @@
+import { nanoid } from "nanoid";
+import { Random } from "roughjs/bin/math";
+
+import { isTestEnv } from "./utils";
+
+let random = new Random(Date.now());
+let testIdBase = 0;
+
+export const randomInteger = () => Math.floor(random.next() * 2 ** 31);
+
+export const reseed = (seed: number) => {
+  random = new Random(seed);
+  testIdBase = 0;
+};
+
+export const randomId = () => (isTestEnv() ? `id${testIdBase++}` : nanoid());

packages/common/src/url.ts

@@ -0,0 +1,37 @@
+import { sanitizeUrl } from "@braintree/sanitize-url";
+
+import { escapeDoubleQuotes } from "./utils";
+
+export const normalizeLink = (link: string) => {
+  link = link.trim();
+  if (!link) {
+    return link;
+  }
+  return sanitizeUrl(escapeDoubleQuotes(link));
+};
+
+export const isLocalLink = (link: string | null) => {
+  return !!(link?.includes(location.origin) || link?.startsWith("/"));
+};
+
+/**
+ * Returns URL sanitized and safe for usage in places such as
+ * iframe's src attribute or <a> href attributes.
+ */
+export const toValidURL = (link: string) => {
+  link = normalizeLink(link);
+
+  // make relative links into fully-qualified urls
+  if (link.startsWith("/")) {
+    return `${location.origin}${link}`;
+  }
+
+  try {
+    new URL(link);
+  } catch {
+    // if link does not parse as URL, assume invalid and return blank page
+    return "about:blank";
+  }
+
+  return link;
+};

packages/common/src/utility-types.ts

@@ -0,0 +1,70 @@
+export type Mutable<T> = {
+  -readonly [P in keyof T]: T[P];
+};
+
+export type ValueOf<T> = T[keyof T];
+
+export type Merge<M, N> = Omit<M, keyof N> & N;
+
+/** utility type to assert that the second type is a subtype of the first type.
+ * Returns the subtype. */
+export type SubtypeOf<Supertype, Subtype extends Supertype> = Subtype;
+
+export type ResolutionType<T extends (...args: any) => any> = T extends (
+  ...args: any
+) => Promise<infer R>
+  ? R
+  : any;
+
+// https://github.com/krzkaczor/ts-essentials
+export type MarkOptional<T, K extends keyof T> = Omit<T, K> &
+  Partial<Pick<T, K>>;
+
+export type MarkRequired<T, RK extends keyof T> = Exclude<T, RK> &
+  Required<Pick<T, RK>>;
+
+export type MarkNonNullable<T, K extends keyof T> = {
+  [P in K]-?: P extends K ? NonNullable<T[P]> : T[P];
+} & { [P in keyof T]: T[P] };
+
+export type NonOptional<T> = Exclude<T, undefined>;
+
+// -----------------------------------------------------------------------------
+// type getter for interface's callable type
+// src: https://stackoverflow.com/a/58658851/927631
+// -----------------------------------------------------------------------------
+export type SignatureType<T> = T extends (...args: infer R) => any ? R : never;
+export type CallableType<T extends (...args: any[]) => any> = (
+  ...args: SignatureType<T>
+) => ReturnType<T>;
+// --------------------------------------------------------------------------—
+
+// Type for React.forwardRef --- supply only the first generic argument T
+export type ForwardRef<T, P = any> = Parameters<
+  CallableType<React.ForwardRefRenderFunction<T, P>>
+>[1];
+
+export type ExtractSetType<T extends Set<any>> = T extends Set<infer U>
+  ? U
+  : never;
+
+export type SameType<T, U> = T extends U ? (U extends T ? true : false) : false;
+export type Assert<T extends true> = T;
+
+export type NestedKeyOf<T, K = keyof T> = K extends keyof T & (string | number)
+  ? `${K}` | (T[K] extends object ? `${K}.${NestedKeyOf<T[K]>}` : never)
+  : never;
+
+export type SetLike<T> = Set<T> | T[];
+export type ReadonlySetLike<T> = ReadonlySet<T> | readonly T[];
+
+export type MakeBrand<T extends string> = {
+  /** @private using ~ to sort last in intellisense */
+  [K in `~brand~${T}`]: T;
+};
+
+/** Maybe just promise or already fulfilled one! */
+export type MaybePromise<T> = T | Promise<T>;
+
+// get union of all keys from the union of types
+export type AllPossibleKeys<T> = T extends any ? keyof T : never;

packages/common/tests/keys.test.ts

@@ -0,0 +1,271 @@
+import { KEYS, matchKey } from "../src/keys";
+
+describe("key matcher", async () => {
+  it("should not match unexpected key", async () => {
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "N" }), KEYS.Y),
+    ).toBeFalsy();
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "Unidentified" }), KEYS.Z),
+    ).toBeFalsy();
+
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "z" }), KEYS.Y),
+    ).toBeFalsy();
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "y" }), KEYS.Z),
+    ).toBeFalsy();
+
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "Z" }), KEYS.Y),
+    ).toBeFalsy();
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "Y" }), KEYS.Z),
+    ).toBeFalsy();
+  });
+
+  it("should match key (case insensitive) when key is latin", async () => {
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "z" }), KEYS.Z),
+    ).toBeTruthy();
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "y" }), KEYS.Y),
+    ).toBeTruthy();
+
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "Z" }), KEYS.Z),
+    ).toBeTruthy();
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "Y" }), KEYS.Y),
+    ).toBeTruthy();
+  });
+
+  it("should match key on QWERTY, QWERTZ, AZERTY", async () => {
+    // QWERTY
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "y", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // QWERTZ
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyY" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "y", code: "KeyZ" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // AZERTY
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyW" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "y", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+  });
+
+  it("should match key on DVORAK, COLEMAK", async () => {
+    // DVORAK
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeySemicolon" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "y", code: "KeyF" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // COLEMAK
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "y", code: "KeyJ" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+  });
+
+  it("should match key on Turkish-Q", async () => {
+    // Turkish-Q
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyN" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "Y", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+  });
+
+  it("should not fallback when code is not defined", async () => {
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "я" }), KEYS.Z),
+    ).toBeFalsy();
+
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "卜" }), KEYS.Y),
+    ).toBeFalsy();
+  });
+
+  it("should not fallback when code is incorrect", async () => {
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeFalsy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "Y", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeFalsy();
+  });
+
+  it("should fallback to code when key is non-latin", async () => {
+    // Macedonian
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "з", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ѕ", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Russian
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "я", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "н", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Serbian
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ѕ", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "з", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Greek
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ζ", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "υ", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Hebrew
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ז", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ט", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Cangjie - Traditional
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "重", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "卜", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Japanese
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "つ", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ん", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // 2-Set Korean
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ㅋ", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ㅛ", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+  });
+});

packages/common/tests/queue.test.ts

@@ -0,0 +1,62 @@
+import { Queue } from "../src/queue";
+
+describe("Queue", () => {
+  const calls: any[] = [];
+
+  const createJobFactory =
+    <T>(
+      // for purpose of this test, Error object will become a rejection value
+      resolutionOrRejectionValue: T,
+      ms = 1,
+    ) =>
+    () => {
+      return new Promise<T>((resolve, reject) => {
+        setTimeout(() => {
+          if (resolutionOrRejectionValue instanceof Error) {
+            reject(resolutionOrRejectionValue);
+          } else {
+            resolve(resolutionOrRejectionValue);
+          }
+        }, ms);
+      }).then((x) => {
+        calls.push(x);
+        return x;
+      });
+    };
+
+  beforeEach(() => {
+    calls.length = 0;
+  });
+
+  it("should await and resolve values in order of enqueueing", async () => {
+    const queue = new Queue();
+
+    const p1 = queue.push(createJobFactory("A", 50));
+    const p2 = queue.push(createJobFactory("B"));
+    const p3 = queue.push(createJobFactory("C"));
+
+    expect(await p3).toBe("C");
+    expect(await p2).toBe("B");
+    expect(await p1).toBe("A");
+
+    expect(calls).toEqual(["A", "B", "C"]);
+  });
+
+  it("should reject a job if it throws, and not affect other jobs", async () => {
+    const queue = new Queue();
+
+    const err = new Error("B");
+
+    queue.push(createJobFactory("A", 50));
+    const p2 = queue.push(createJobFactory(err));
+    const p3 = queue.push(createJobFactory("C"));
+
+    const p2err = p2.catch((err) => err);
+
+    await p3;
+
+    expect(await p2err).toBe(err);
+
+    expect(calls).toEqual(["A", "C"]);
+  });
+});

packages/common/tests/url.test.tsx

@@ -0,0 +1,31 @@
+import { normalizeLink } from "../src/url";
+
+describe("normalizeLink", () => {
+  // NOTE not an extensive XSS test suite, just to check if we're not
+  // regressing in sanitization
+  it("should sanitize links", () => {
+    expect(
+      // eslint-disable-next-line no-script-url
+      normalizeLink(`javascript://%0aalert(document.domain)`).startsWith(
+        // eslint-disable-next-line no-script-url
+        `javascript:`,
+      ),
+    ).toBe(false);
+    expect(normalizeLink("ola")).toBe("ola");
+    expect(normalizeLink(" ola")).toBe("ola");
+
+    expect(normalizeLink("https://www.excalidraw.com")).toBe(
+      "https://www.excalidraw.com",
+    );
+    expect(normalizeLink("www.excalidraw.com")).toBe("www.excalidraw.com");
+    expect(normalizeLink("/ola")).toBe("/ola");
+    expect(normalizeLink("http://test")).toBe("http://test");
+    expect(normalizeLink("ftp://test")).toBe("ftp://test");
+    expect(normalizeLink("file://")).toBe("file://");
+    expect(normalizeLink("file://")).toBe("file://");
+    expect(normalizeLink("[test](https://test)")).toBe("[test](https://test)");
+    expect(normalizeLink("[[test]]")).toBe("[[test]]");
+    expect(normalizeLink("<test>")).toBe("<test>");
+    expect(normalizeLink("test&")).toBe("test&");
+  });
+});

packages/common/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist/types"
+  }
+}