@knime/utils 1.0.0

package/README.md

@@ -0,0 +1,23 @@
+# ![Image](https://www.knime.com/sites/default/files/knime_logo_github_40x40_4layers.png) @knime/utils
+
+Internal utility functions and constants shared across `@knime` packages.
+
+## Installation
+
+To install the `@knime/utils` package, you can use npm:
+
+```bash
+npm install @knime/utils
+```
+
+## Usage
+
+To use it in your project, you can import it as follows:
+
+```javascript
+import { copyText } from "@knime/utils";
+```
+
+# Join the Community!
+
+- [KNIME Forum](https://forum.knime.com/)

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@knime/utils",
+  "version": "1.0.0",
+  "description": "Internal utility functions and constants shared across @knime packages.",
+  "homepage": "https://knime.github.io/webapps-common/",
+  "license": "GPL 3 and Additional Permissions according to Sec. 7 (SEE the file LICENSE)",
+  "author": "KNIME AG, Zurich, Switzerland",
+  "type": "module",
+  "scripts": {
+    "test:unit": "TZ='Europe/Berlin' vitest"
+  },
+  "dependencies": {
+    "@knime/styles": "1.0.0",
+    "consola": "2.15.3",
+    "date-fns": "2.30.0",
+    "date-fns-tz": "2.0.0"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "files": [
+    "src",
+    "!src/__tests__",
+    "test-utils",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    },
+    "./globals.d.ts": {
+      "import": "./src/config/globals.d.ts"
+    },
+    "./test-utils": {
+      "import": "./test-utils/index.ts"
+    }
+  },
+  "devDependencies": {
+    "flush-promises": "^1.0.2"
+  }
+}

package/src/capitalize.js

@@ -0,0 +1,33 @@
+/**
+ * Uppercases first letter of string
+ * @param {String} str to be capitalized first string, e.g. 'workflow'
+ * @return {String} Capitalized String, e.g. Workflow
+ */
+export const capitalize = (str) =>
+  str.charAt(0).toUpperCase() + str.substring(1);
+
+const formats = {
+  customFormat: (str, delimiter) =>
+    capitalize(str.replace(delimiter, " ").toLowerCase()),
+  kebabFormat: (str) => formats.customFormat(str, "-"),
+  snakeFormat: (str) => formats.customFormat(str, "_"),
+  camelPascalCase: (str) =>
+    capitalize(
+      str
+        .match(/([A-Z]?[^A-Z]*)/g)
+        .slice(0, -1)
+        .join(" ")
+        .toLowerCase(),
+    ),
+  [undefined]: (str) => capitalize(str), // eslint-disable-line no-undefined
+};
+
+export const caseFormatter = ({ string, delimiter, format }) => {
+  if (delimiter) {
+    return formats.customFormat(string, delimiter);
+  }
+  if (formats) {
+    return formats[format](string);
+  }
+  return capitalize(string);
+};

package/src/config/globals.d.ts

@@ -0,0 +1,3 @@
+/* eslint-disable one-var */
+
+declare const consola: import("consola").Consola;

package/src/copyText.js

@@ -0,0 +1,10 @@
+export const copyText = (text) => {
+  let tmpElement = document.createElement("textarea");
+  tmpElement.style = "position:fixed;pointer-events:none;opacity:0;";
+  tmpElement.setAttribute("readonly", "");
+  tmpElement.value = text;
+  document.body.appendChild(tmpElement);
+  tmpElement.select();
+  document.execCommand("copy");
+  document.body.removeChild(tmpElement);
+};

package/src/dateMinMaxCheck.js

@@ -0,0 +1,57 @@
+import { isAfter, isBefore } from "date-fns";
+import updateTime from "./updateTime";
+import updateDate from "./updateDate";
+
+/**
+ * Check if date is before min.
+ * @param {Date} date
+ * @param {Date | null} min
+ * @param {Boolean} checkDate - check date part (year, day, month).
+ * @param {Boolean} checkTime - check time part (hour, minutes etc.).
+ * @returns {Boolean} whether limit is kept or not.
+ */
+export const isBeforeMinDate = (date, min, checkDate, checkTime) => {
+  if (min) {
+    if (checkTime && checkDate) {
+      return isBefore(date, min);
+    }
+    if (checkTime) {
+      // only time is visible so ignore date: use same datre as base
+      const base = new Date(0);
+      return isBefore(updateTime(base, date), updateTime(base, min));
+    }
+    if (checkDate) {
+      // only date is visible so ignore time: use same time as base
+      const base = new Date(0);
+      return isBefore(updateDate(base, date), updateDate(base, min));
+    }
+  }
+  return false;
+};
+
+/**
+ * Check
+ * @param {Date} date - date to check.
+ * @param {Date | null} max - maximum date.
+ * @param {Boolean} checkDate - check date part (year, day, month).
+ * @param {Boolean} checkTime - check time part (hour, minutes etc.).
+ * @returns {Boolean} whether limit is kept or not.
+ */
+export const isAfterMaxDate = (date, max, checkDate, checkTime) => {
+  if (max) {
+    if (checkTime && checkDate) {
+      return isAfter(date, max);
+    }
+    if (checkTime) {
+      // only time is visible so ignore date: use same datre as base
+      const base = new Date(0);
+      return isAfter(updateTime(base, date), updateTime(base, max));
+    }
+    if (checkDate) {
+      // use same time base
+      const base = new Date(0);
+      return isAfter(updateDate(base, date), updateDate(base, max));
+    }
+  }
+  return false;
+};

package/src/debounce.ts

@@ -0,0 +1,28 @@
+// Use this method to reduce many method calls to a few.
+// It's an 'immediate' implementation, so it will call the callbackindex: number once immediately an then again after the given wait.
+
+type CallbackFunc<T> = (value: T, index: number) => void;
+
+const debounce = <T>(callback: CallbackFunc<T>, wait: number) => {
+  let timer: ReturnType<typeof setTimeout>;
+  let lastCall = 0;
+
+  return (...args: Parameters<typeof callback>) => {
+    const [value, index] = args;
+    clearTimeout(timer);
+    const now = Date.now();
+    const timeFromLastCall = now - lastCall;
+
+    if (timeFromLastCall > wait) {
+      lastCall = now;
+      callback(value, index);
+    } else {
+      timer = setTimeout(() => {
+        lastCall = now;
+        callback(value, index);
+      }, wait);
+    }
+  };
+};
+
+export default debounce;

package/src/fileTypeIcons.ts

@@ -0,0 +1,41 @@
+import csvIcon from "@knime/styles/img/icons/file-csv.svg";
+import docxIcon from "@knime/styles/img/icons/file-docx.svg";
+import htmlIcon from "@knime/styles/img/icons/file-html.svg";
+import mdIcon from "@knime/styles/img/icons/file-md.svg";
+import odpIcon from "@knime/styles/img/icons/file-odp.svg";
+import odsIcon from "@knime/styles/img/icons/file-ods.svg";
+import odtIcon from "@knime/styles/img/icons/file-odt.svg";
+import pdfIcon from "@knime/styles/img/icons/file-pdf.svg";
+import pptxIcon from "@knime/styles/img/icons/file-pptx.svg";
+import psIcon from "@knime/styles/img/icons/file-ps.svg";
+import xlsIcon from "@knime/styles/img/icons/file-xls.svg";
+import xlsxIcon from "@knime/styles/img/icons/file-xlsx.svg";
+import xmlIcon from "@knime/styles/img/icons/file-xml.svg";
+import zipIcon from "@knime/styles/img/icons/file-zip.svg";
+import exeIcon from "@knime/styles/img/icons/file-zip-exe.svg";
+import txtIcon from "@knime/styles/img/icons/file-text.svg";
+import fileIcon from "@knime/styles/img/icons/file-question.svg";
+
+export const icons = {
+  csvIcon,
+  docxIcon,
+  htmlIcon,
+  mdIcon,
+  odpIcon,
+  odsIcon,
+  odtIcon,
+  pdfIcon,
+  pptxIcon,
+  psIcon,
+  xlsIcon,
+  xlsxIcon,
+  xmlIcon,
+  zipIcon,
+  exeIcon,
+  txtIcon,
+  fileIcon,
+};
+
+export const isIconExisting = function (iconName: string): boolean {
+  return icons.hasOwnProperty(iconName);
+};

package/src/filters.ts

@@ -0,0 +1,114 @@
+/**
+ * These definitions can be used to filter an array. Each entry should contain a method normalize which can be used to
+ * compile any filter settings and a method "test" which takes the compiled result, additional settings and the item to
+ * be matched/filtered
+ * */
+interface FilterDefinition<SearchTerm, Normalized, Testable> {
+  id: string;
+  normalize: (
+    searchTerm: SearchTerm,
+    caseSensitiveSearch: boolean,
+  ) => Normalized;
+  test: (
+    text: Testable,
+    normalizedSearchTerm: Normalized,
+    caseSensitiveSearch: boolean,
+    inverseSearch: boolean,
+  ) => boolean;
+}
+
+interface StringTest {
+  test(str: string): boolean;
+}
+
+type SearchFilterDefinition = FilterDefinition<string, string, string>;
+type PatternFilterDefinition = FilterDefinition<
+  string,
+  RegExp | StringTest,
+  string
+>;
+type TypeFilterDefinition = FilterDefinition<
+  string[],
+  StringTest,
+  string | undefined
+>;
+
+const modeDefinitions = [
+  {
+    id: "search",
+    normalize(searchTerm, caseSensitiveSearch) {
+      return caseSensitiveSearch ? searchTerm : searchTerm.toLowerCase();
+    },
+    test(text, normalizedSearchTerm, caseSensitiveSearch, inverseSearch) {
+      const testText = caseSensitiveSearch ? text : text.toLowerCase();
+      const matches = testText.includes(normalizedSearchTerm);
+      return inverseSearch ? !matches : matches;
+    },
+  } satisfies SearchFilterDefinition,
+  {
+    id: "wildcard",
+    normalize(searchTerm, caseSensitiveSearch) {
+      // Do a regex search, explicitly matching start and end of the search term.
+      // All regex special character except from "* and ?" (wildcards) are escaped.
+      if (searchTerm.length > 0) {
+        const escapedSearchTerm = searchTerm.replace(
+          /[-[\]{}()+.,\\^$|#\s]/g,
+          "\\$&",
+        );
+        const wildcardSearchTerm = escapedSearchTerm
+          .replace(/\*/g, ".*")
+          .replace(/\?/g, ".?");
+        searchTerm = `^${wildcardSearchTerm}$`;
+      } else {
+        return { test: () => false };
+      }
+      try {
+        const flags = caseSensitiveSearch ? "" : "i";
+        return new RegExp(searchTerm, flags);
+      } catch (error) {
+        // In case of an invalid regular expression, an impossible
+        // regex is returned, not matching anything.
+        return /$^/;
+      }
+    },
+    test(text, normalizedSearchTerm, caseSensitiveSearch, inverseSearch) {
+      const matches = normalizedSearchTerm.test(text);
+      return inverseSearch ? !matches : matches;
+    },
+  } satisfies PatternFilterDefinition,
+  {
+    id: "regex",
+    normalize(searchTerm, caseSensitiveSearch) {
+      try {
+        const flags = caseSensitiveSearch ? "" : "i";
+        return new RegExp(`^(${searchTerm})$`, flags);
+      } catch (error) {
+        // In case of an invalid regular expression, an impossible
+        // regex is returned, not matching anything.
+        return /$^/;
+      }
+    },
+    test(text, normalizedSearchTerm, caseSensitiveSearch, inverseSearch) {
+      const matches = normalizedSearchTerm.test(text);
+      return inverseSearch ? !matches : matches;
+    },
+  } satisfies PatternFilterDefinition,
+  {
+    id: "type",
+    normalize(selectedTypes) {
+      return { test: (type: string) => selectedTypes.includes(type) };
+    },
+    test(type, normalizedSearchTerm) {
+      if (typeof type === "undefined") {
+        return false;
+      }
+      return normalizedSearchTerm.test(type);
+    },
+  } satisfies TypeFilterDefinition,
+];
+
+// convert [{id: "key1", text: "asdf"}, ...] to {"key1": {id:"key1", text: "asdf"} ... }
+export const filters: Record<
+  string,
+  FilterDefinition<any, any, any>
+> = Object.assign({}, ...modeDefinitions.map((obj) => ({ [obj.id]: obj })));

package/src/format.js

@@ -0,0 +1,70 @@
+import getLocalTimeZone from "./localTimezone";
+/**
+ * Converts the specified date String to human readable text containing the day, month, and year.
+ * Example: '2018-07-31T09:44:31+00:00' => 'Jul 31, 2018'
+ *
+ * @param {Boolean} useTimeZone to set the timeZone where the user is located, and display local date and time
+ * @param {String | number} dateString String representation of the Date to format
+ * @returns {String} human readable date String
+ */
+export const formatDateString = (dateString, useTimeZone = false) => {
+  let date = new Date(dateString);
+  if (isNaN(date)) {
+    throw Error("Invalid Date format");
+  }
+  // This only works for the default locale of en-US, as support of other locals in node js might not be available
+  // See for example this issue https://github.com/nodejs/node/issues/8500
+  let dateOptions = { day: "numeric", month: "short", year: "numeric" };
+  if (useTimeZone) {
+    dateOptions.timeZone = getLocalTimeZone();
+  }
+  return date.toLocaleDateString("en-US", dateOptions);
+};
+/**
+ * Converts the specified time String to human readable text containing the hour (12-hour) and minute.
+ * Example: '2018-07-31T09:44:31+00:00' => '9:44 AM'
+ *
+ * @param {Boolean} useTimeZone to set the timeZone where the user is located, and display local date and time
+ * @param {String | number} timeString String representation of the Date (including time) to format
+ * @returns {String} human readable time String
+ */
+export const formatTimeString = (timeString, useTimeZone = false) => {
+  let time = new Date(timeString);
+  if (isNaN(time)) {
+    throw Error("Invalid Date format");
+  }
+  // This only works for the default locale of en-US, as support of other locals in node js might not be available
+  // See for example this issue https://github.com/nodejs/node/issues/8500
+
+  let timeOptions = { hour: "numeric", minute: "2-digit" };
+  if (useTimeZone) {
+    timeOptions.timeZone = getLocalTimeZone();
+  }
+
+  return time.toLocaleTimeString("en-US", timeOptions);
+};
+/**
+ * Converts the specified time String to human readable text containing the date (day, month, year) and time (hour,
+ * minute; 12-hour).
+ * Example: '2018-07-31T09:44:31+00:00' => 'Jul 31, 2018 9:44 AM'
+ *
+ * @param {Boolean} useTimeZone to set the timeZone where the user is located, and display local date and time
+ * @param {String | number} dateTimeString String representation of the Date (including time and date) to format
+ * @returns {String} human readable date/time String
+ */
+export const formatDateTimeString = (dateTimeString, useTimeZone = false) => {
+  // eslint-disable-line arrow-body-style
+  return `${formatDateString(dateTimeString, useTimeZone)} ${formatTimeString(
+    dateTimeString,
+    useTimeZone,
+  )}`;
+};
+/**
+ * Converts the specified date and time to the user time zone with option to display (day, month, year) only or with time (hour,
+ * minute; 12-hour).
+ * @param {Boolean} showTime String representation of the Date to convert and format
+ * @param {String | number} date String representation of the Date to convert and format
+ * @returns {String} human readable date/time String converted to user time zone
+ */
+export const formatLocalDateTimeString = (date, showTime) =>
+  showTime ? formatDateTimeString(date, true) : formatDateString(date, true);

package/src/formatHotkeys.ts

@@ -0,0 +1,98 @@
+import { isMac } from "./navigator";
+
+type Keys =
+  | "F1"
+  | "F2"
+  | "F3"
+  | "F4"
+  | "F5"
+  | "F6"
+  | "F7"
+  | "F8"
+  | "F9"
+  | "F10"
+  | "F11"
+  | "F12"
+  | "PageUp"
+  | "PageDown"
+  | "ArrowUp"
+  | "ArrowRight"
+  | "ArrowDown"
+  | "ArrowLeft"
+  | "Delete"
+  | "Enter"
+  | "Backspace"
+  | "Home"
+  | "End"
+  | " "; // Space;
+
+type Modifiers = "CtrlOrCmd" | "Ctrl" | "Alt" | "Shift";
+
+// creates loose autocomplete by using a union of the passed-in type
+// and the entire `string` set *except* the passed-in type
+type LooseAutoComplete<T extends string> = T | Omit<string, T>;
+
+export type NumberRange = `${number}-${number}`;
+export type KnownHotkey = Keys | Modifiers | NumberRange;
+
+export type Hotkey = LooseAutoComplete<Keys | Modifiers>;
+
+const globalKeyMap = {
+  ArrowUp: "↑",
+  ArrowDown: "↓",
+  ArrowLeft: "←",
+  ArrowRight: "→",
+  Enter: "↵",
+  " ": "Space", // we use event.key and there space is an actual space not the code "Space"
+  CtrlOrCmd: "Ctrl",
+} as const;
+
+const MacOSkeyMap = {
+  Shift: "⇧",
+  Delete: "⌫",
+  CtrlOrCmd: "⌘",
+  Ctrl: "⌃",
+  Alt: "⌥",
+  Enter: "↩",
+} as const;
+
+type KeyFormatMap = typeof MacOSkeyMap | typeof globalKeyMap;
+
+/**
+ * Returns a string representation of a single hotkey. Replaces some special key names with symbols
+ */
+export const formatHotkey = (hotkey: Hotkey): string => {
+  /**
+   * Returns the symbol corresponding to the `key` based on the given
+   * `formatMap`. Otherwise, if not found, returns the same `key` value given
+   */
+  const mapSymbols = (formatMap: KeyFormatMap) => (key: Hotkey) =>
+    formatMap[key as keyof KeyFormatMap] ?? key;
+
+  /**
+   * Pipe function implementation. Receives a list of functions to execute in order
+   * and will pipe the parameter passed at the end to each function returning the final output
+   */
+  const pipe = <T extends () => any>(
+    ...fns: Array<(...args: any[]) => ReturnType<T>>
+  ) => fns.reduce((f, g) => (arg) => g(f(arg)));
+
+  const macKeyFormatter = pipe(
+    mapSymbols(MacOSkeyMap),
+    mapSymbols(globalKeyMap),
+  );
+
+  const generalKeyFormatter = mapSymbols(globalKeyMap);
+
+  return isMac() ? macKeyFormatter(hotkey) : generalKeyFormatter(hotkey);
+};
+
+export const getDefaultSeparator = () => " ";
+
+/**
+ * Returns a string representation of a list of hotkeys. Replaces some special key names with symbols
+ */
+export const formatHotkeys = (
+  hotkeys: Array<Hotkey>,
+  getSeparator = getDefaultSeparator,
+) => hotkeys.map(formatHotkey).join(getSeparator());

package/src/getWrappedAroundIndex.ts

@@ -0,0 +1,9 @@
+/**
+ * Since (a % b) yields a negative outcome for negative a, we need this method in order
+ *  to correctly compute wrapped around indices in lists
+ * @param {number} index an arbitrary integer
+ * @param {number} length a positive integer
+ * @returns {number} the non-negative modulo outcome
+ */
+export default (index: number, length: number) =>
+  ((index % length) + length) % length;

package/src/index.ts

@@ -0,0 +1,50 @@
+import { capitalize, caseFormatter } from "./capitalize";
+import { copyText } from "./copyText";
+import debounce from "./debounce";
+import { filters } from "./filters";
+import truncateString from "./truncateString";
+import getWrappedAroundIndex from "./getWrappedAroundIndex";
+import sleep from "./sleep";
+import { icons, isIconExisting } from "./fileTypeIcons";
+import svgWithTitle from "./svgWithTitle";
+import updateDate from "./updateDate";
+import { isAfterMaxDate, isBeforeMinDate } from "./dateMinMaxCheck";
+import {
+  formatDateString,
+  formatDateTimeString,
+  formatLocalDateTimeString,
+  formatTimeString,
+} from "./format";
+
+import getLocalTimeZone from "./localTimezone";
+import numIntegerDigits from "./numIntegerDigits";
+import { formatHotkeys } from "./formatHotkeys";
+import type { Hotkey, KnownHotkey } from "./formatHotkeys";
+import * as navigator from "./navigator";
+
+export type { Hotkey, KnownHotkey };
+
+export {
+  capitalize,
+  caseFormatter,
+  copyText,
+  debounce,
+  filters,
+  truncateString,
+  getWrappedAroundIndex,
+  sleep,
+  icons,
+  isIconExisting,
+  svgWithTitle,
+  formatDateString,
+  formatDateTimeString,
+  formatLocalDateTimeString,
+  formatTimeString,
+  updateDate,
+  isAfterMaxDate,
+  getLocalTimeZone,
+  isBeforeMinDate,
+  numIntegerDigits,
+  formatHotkeys,
+  navigator,
+};

package/src/localTimezone.js

@@ -0,0 +1,7 @@
+/**
+ * Get the users local timezone.
+ *
+ * @returns {String} current users timezone (browser based) tz db string (e. g. Europe/Berlin).
+ */
+// eslint-disable-next-line new-cap
+export default () => Intl.DateTimeFormat().resolvedOptions().timeZone;

package/src/navigator.ts

@@ -0,0 +1,11 @@
+/**
+ *
+ * @returns true when the platform of the user is Mac
+ */
+export const isMac = () => navigator?.userAgent?.toLowerCase()?.includes("mac");
+
+/**
+ *
+ * @returns name of the primary modifier key for the current platform
+ */
+export const getMetaOrCtrlKey = () => (isMac() ? "metaKey" : "ctrlKey");

package/src/numIntegerDigits.js

@@ -0,0 +1,7 @@
+/**
+ * Count the number of integer digits for a given number.
+ *
+ * @param {Number} x - input number.
+ * @returns {Number} - number of integer digits x has. 1234 = 4 but 1234.44 is also 4.
+ */
+export default (x) => Math.max(Math.floor(Math.log10(Math.abs(x))), 0) + 1;

package/src/sleep.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns promise that resolves after ms.
+ */
+export default function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/svgWithTitle.js

@@ -0,0 +1,31 @@
+import { h as createElement } from "vue";
+
+/**
+ * Higher order component that decorates a SVG component (loaded with vue-svg-loader) with a `<title>` element
+ * Note that `title` attributes have no effect on `<svg>` elements, so we need to inject a DOM element.
+ *
+ * @example
+ *
+ * import MyIcon from '~/icons/foo.svg';
+ * import svgWithTitle from '…';
+ * export default {
+ *   components: {
+ *       MyIcon: svgWithTitle(MyIcon, 'My Title')
+ *   }
+ * };
+ *
+ * @param { Vue.component } SvgComponent The component to decorate
+ * @param { String } title The title to insert
+ * @returns { Vue.component } The component with a title inserted as the first child of `<svg>`
+ */
+export default (SvgComponent, title) => ({
+  render() {
+    const renderedComponent = SvgComponent.render.apply(this, createElement);
+
+    const titleEl = createElement("title", title);
+    titleEl.ns = "svg";
+
+    renderedComponent.children.unshift(titleEl);
+    return renderedComponent;
+  },
+});

package/src/truncateString.js

@@ -0,0 +1,7 @@
+const defaultMaxLength = 160;
+
+// truncates a string to a given max length
+export default (string = "", maxLength = defaultMaxLength) => {
+  const dots = string.length > maxLength ? "…" : "";
+  return `${string.substring(0, maxLength - 1)}${dots}`;
+};