@naturalcycles/js-lib 14.255.0 → 14.257.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.255.0",
+  "version": "14.257.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",
@@ -36,6 +36,7 @@
   "files": [
     "dist",
     "dist-esm",
+    "cfg",
     "src",
     "!src/test",
     "!src/**/*.test.*",

package/src/bot.ts

@@ -0,0 +1,155 @@
+// Relevant material:
+// https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+
+import { isServerSide } from './env'
+
+export interface BotDetectionServiceCfg {
+  /**
+   * Defaults to false.
+   * If true - the instance will memoize (remember) the results of the detection
+   * and won't re-run it.
+   */
+  memoizeResults?: boolean
+
+  /**
+   * Defaults to false.
+   * If set to true: `getBotReason()` would return BotReason.CDP if CDP is detected.
+   * Otherwise - `getBotReason()` will not perform the CDP check.
+   */
+  treatCDPAsBotReason?: boolean
+}
+
+/**
+ * Service to detect bots and CDP (Chrome DevTools Protocol).
+ *
+ * @experimental
+ */
+export class BotDetectionService {
+  constructor(public cfg: BotDetectionServiceCfg = {}) {}
+
+  // memoized results
+  private botReason: BotReason | null | undefined
+  private cdp: boolean | undefined
+
+  isBotOrCDP(): boolean {
+    return !!this.getBotReason() || this.isCDP()
+  }
+
+  isBot(): boolean {
+    return !!this.getBotReason()
+  }
+
+  /**
+   * Returns null if it's not a Bot,
+   * otherwise a truthy BotReason.
+   */
+  getBotReason(): BotReason | null {
+    if (this.cfg.memoizeResults && this.botReason !== undefined) {
+      return this.botReason
+    }
+
+    this.botReason = this.detectBotReason()
+    return this.botReason
+  }
+
+  private detectBotReason(): BotReason | null {
+    // SSR - not a bot
+    if (isServerSide()) return null
+    const { navigator } = globalThis
+    if (!navigator) return BotReason.NoNavigator
+    const { userAgent } = navigator
+    if (!userAgent) return BotReason.NoUserAgent
+
+    if (/bot|headless|electron|phantom|slimer/i.test(userAgent)) {
+      return BotReason.UserAgent
+    }
+
+    if (navigator.webdriver) {
+      return BotReason.WebDriver
+    }
+
+    // Kirill: commented out, as it's no longer seems reliable,
+    // e.g generates false positives with latest Android clients (e.g. Chrome 129)
+    // if (navigator.plugins?.length === 0) {
+    //   return BotReason.ZeroPlugins // Headless Chrome
+    // }
+
+    if ((navigator.languages as any) === '') {
+      return BotReason.EmptyLanguages // Headless Chrome
+    }
+
+    // isChrome is true if the browser is Chrome, Chromium or Opera
+    // this is "the chrome test" from https://intoli.com/blog/not-possible-to-block-chrome-headless/
+    // this property is for some reason not present by default in headless chrome
+    // Kirill: criterium removed due to false positives with Android
+    // if (userAgent.includes('Chrome') && !(globalThis as any).chrome) {
+    //   return BotReason.ChromeWithoutChrome // Headless Chrome
+    // }
+
+    if (this.cfg.treatCDPAsBotReason && this.detectCDP()) {
+      return BotReason.CDP
+    }
+
+    return null
+  }
+
+  /**
+   * CDP stands for Chrome DevTools Protocol.
+   * This function tests if the current environment is a CDP environment.
+   * If it's true - it's one of:
+   *
+   * 1. Bot, automated with CDP, e.g Puppeteer, Playwright or such.
+   * 2. Developer with Chrome DevTools open.
+   *
+   * 2 is certainly not a bot, but unfortunately we can't distinguish between the two.
+   * That's why this function is not part of `isBot()`, because it can give "false positive" with DevTools.
+   *
+   * Based on: https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+   */
+  isCDP(): boolean {
+    if (this.cfg.memoizeResults && this.cdp !== undefined) {
+      return this.cdp
+    }
+
+    this.cdp = this.detectCDP()
+    return this.cdp
+  }
+
+  private detectCDP(): boolean {
+    if (isServerSide()) return false
+    let cdpCheck1 = false
+    try {
+      /* eslint-disable */
+      // biome-ignore lint/suspicious/useErrorMessage: ok
+      const e = new window.Error()
+      window.Object.defineProperty(e, 'stack', {
+        configurable: false,
+        enumerable: false,
+        // biome-ignore lint/complexity/useArrowFunction: ok
+        get: function () {
+          cdpCheck1 = true
+          return ''
+        },
+      })
+      // This is part of the detection and shouldn't be deleted
+      window.console.debug(e)
+      /* eslint-enable */
+    } catch {}
+    return cdpCheck1
+  }
+}
+
+export enum BotReason {
+  NoNavigator = 1,
+  NoUserAgent = 2,
+  UserAgent = 3,
+  WebDriver = 4,
+  // ZeroPlugins = 5,
+  EmptyLanguages = 6,
+  // ChromeWithoutChrome = 7,
+  /**
+   * This is when CDP is considered to be a reason to be a Bot.
+   * By default it's not.
+   */
+  CDP = 8,
+}

package/src/browser/adminService.ts

@@ -0,0 +1,157 @@
+import { _Memo } from '../decorators/memo.decorator'
+import { isServerSide } from '../env'
+import { _stringify } from '../string/stringify'
+import { Promisable } from '../typeFest'
+
+export interface AdminModeCfg {
+  /**
+   * Function (predicate) to detect if needed keys are pressed.
+   *
+   * @example
+   * predicate: e => e.ctrlKey && e.key === 'L'
+   *
+   * @default
+   * Detects Ctrl+Shift+L
+   */
+  predicate?: (e: KeyboardEvent) => boolean
+
+  /**
+   * Called when RedDot is clicked. Implies that AdminMode is enabled.
+   */
+  onRedDotClick?: () => any
+
+  /**
+   * Called when AdminMode was changed.
+   */
+  onChange?: (adminMode: boolean) => any
+
+  /**
+   * Called BEFORE entering AdminMode.
+   * Serves as a predicate that can cancel entering AdminMode if false is returned.
+   * Return true to allow.
+   * Function is awaited before proceeding.
+   */
+  beforeEnter?: () => Promisable<boolean>
+
+  /**
+   * Called BEFORE exiting AdminMode.
+   * Serves as a predicate that can cancel exiting AdminMode if false is returned.
+   * Return true to allow.
+   * Function is awaited before proceeding.
+   */
+  beforeExit?: () => Promisable<boolean>
+
+  /**
+   * @default true
+   * If true - it will "persist" the adminMode state in LocalStorage
+   */
+  persistToLocalStorage?: boolean
+
+  /**
+   * The key for LocalStorage persistence.
+   *
+   * @default '__adminMode__'
+   */
+  localStorageKey?: string
+}
+
+const RED_DOT_ID = '__red-dot__'
+const NOOP = (): void => {}
+
+/**
+ * @experimental
+ *
+ * Allows to listen for AdminMode keypress combination (Ctrl+Shift+L by default) to toggle AdminMode,
+ * indicated by RedDot DOM element.
+ *
+ * todo: help with Authentication
+ */
+export class AdminService {
+  constructor(cfg?: AdminModeCfg) {
+    this.cfg = {
+      predicate: e => e.ctrlKey && e.key === 'L',
+      persistToLocalStorage: true,
+      localStorageKey: '__adminMode__',
+      onRedDotClick: NOOP,
+      onChange: NOOP,
+      beforeEnter: () => true,
+      beforeExit: () => true,
+      ...cfg,
+    }
+  }
+
+  cfg: Required<AdminModeCfg>
+
+  adminMode = false
+
+  private listening = false
+
+  /**
+   * Start listening to keyboard events to toggle AdminMode when detected.
+   */
+  startListening(): void {
+    if (this.listening || isServerSide()) return
+
+    this.adminMode = !!localStorage.getItem(this.cfg.localStorageKey)
+
+    if (this.adminMode) this.toggleRedDotVisibility()
+
+    document.addEventListener('keydown', this.keydownListener.bind(this), { passive: true })
+
+    this.listening = true
+  }
+
+  stopListening(): void {
+    if (isServerSide()) return
+    document.removeEventListener('keydown', this.keydownListener)
+    this.listening = false
+  }
+
+  private async keydownListener(e: KeyboardEvent): Promise<void> {
+    // console.log(e)
+    if (!this.cfg.predicate(e)) return
+    await this.toggleRedDot()
+  }
+
+  async toggleRedDot(): Promise<void> {
+    try {
+      const allow = await this.cfg[this.adminMode ? 'beforeExit' : 'beforeEnter']()
+      if (!allow) return // no change
+    } catch (err) {
+      console.error(err)
+      // ok to show alert to Admins, it's not user-facing
+      alert(_stringify(err))
+      return // treat as "not allowed"
+    }
+
+    this.adminMode = !this.adminMode
+
+    this.toggleRedDotVisibility()
+
+    if (this.cfg.persistToLocalStorage) {
+      const { localStorageKey } = this.cfg
+      if (this.adminMode) {
+        localStorage.setItem(localStorageKey, '1')
+      } else {
+        localStorage.removeItem(localStorageKey)
+      }
+    }
+
+    this.cfg.onChange(this.adminMode)
+  }
+
+  private toggleRedDotVisibility(): void {
+    this.getRedDotElement().style.display = this.adminMode ? 'block' : 'none'
+  }
+
+  @_Memo()
+  private getRedDotElement(): HTMLElement {
+    const el = document.createElement('div')
+    el.id = RED_DOT_ID
+    el.style.cssText =
+      'position:fixed;width:24px;height:24px;margin-top:-12px;background-color:red;opacity:0.5;top:50%;left:0;z-index:9999999;cursor:pointer;border-radius:0 3px 3px 0'
+    el.addEventListener('click', () => this.cfg.onRedDotClick())
+    document.body.append(el)
+    return el
+  }
+}

package/src/browser/analytics.util.ts

@@ -0,0 +1,68 @@
+import { isServerSide } from '@naturalcycles/js-lib'
+import { loadScript } from './script.util'
+
+declare global {
+  interface Window {
+    dataLayer: any[]
+    gtag: (...args: any[]) => void
+  }
+}
+
+/* eslint-disable unicorn/prefer-global-this */
+
+/**
+ * Pass enabled = false to only init window.gtag, but not load actual gtag script (e.g in dev mode).
+ */
+export async function loadGTag(gtagId: string, enabled = true): Promise<void> {
+  if (isServerSide()) return
+
+  window.dataLayer ||= []
+  window.gtag ||= function gtag() {
+    // biome-ignore lint/complexity/useArrowFunction: ok
+    // biome-ignore lint/style/noArguments: ok
+    window.dataLayer.push(arguments)
+  }
+  window.gtag('js', new Date())
+  window.gtag('config', gtagId)
+
+  if (!enabled) return
+
+  await loadScript(`https://www.googletagmanager.com/gtag/js?id=${gtagId}`)
+}
+
+export async function loadGTM(gtmId: string, enabled = true): Promise<void> {
+  if (isServerSide()) return
+
+  window.dataLayer ||= []
+  window.dataLayer.push({
+    'gtm.start': Date.now(),
+    event: 'gtm.js',
+  })
+
+  if (!enabled) return
+
+  await loadScript(`https://www.googletagmanager.com/gtm.js?id=${gtmId}`)
+}
+
+export function loadHotjar(hjid: number): void {
+  if (isServerSide()) return
+
+  /* eslint-disable */
+  // prettier-ignore
+  ;
+  ;((h: any, o, t, j, a?: any, r?: any) => {
+    h.hj =
+      h.hj ||
+      function hj() {
+        // biome-ignore lint/style/noArguments: ok
+        ;(h.hj.q = h.hj.q || []).push(arguments)
+      }
+    h._hjSettings = { hjid, hjsv: 6 }
+    a = o.querySelectorAll('head')[0]
+    r = o.createElement('script')
+    r.async = 1
+    r.src = t + h._hjSettings.hjid + j + h._hjSettings.hjsv
+    a.append(r)
+  })(window, document, 'https://static.hotjar.com/c/hotjar-', '.js?sv=')
+  /* eslint-enable */
+}

package/src/browser/i18n/fetchTranslationLoader.ts

@@ -0,0 +1,16 @@
+import { Fetcher } from '../../http/fetcher'
+import { StringMap } from '../../types'
+import { TranslationLoader } from './translation.service'
+
+/**
+ * Use `baseUrl` to prefix your language files.
+ * Example URL structure:
+ * ${baseUrl}/${locale}.json
+ */
+export class FetchTranslationLoader implements TranslationLoader {
+  constructor(public fetcher: Fetcher) {}
+
+  async load(locale: string): Promise<StringMap> {
+    return await this.fetcher.get(`${locale}.json`)
+  }
+}

package/src/browser/i18n/translation.service.ts

@@ -0,0 +1,102 @@
+import { pMap } from '../../promise/pMap'
+import { StringMap } from '../../types'
+
+export type MissingTranslationHandler = (key: string, params?: StringMap<any>) => string
+
+export const defaultMissingTranslationHandler: MissingTranslationHandler = key => {
+  console.warn(`[tr] missing: ${key}`)
+  return `[${key}]`
+}
+
+export interface TranslationServiceCfg {
+  defaultLocale: string
+  supportedLocales: string[]
+
+  /**
+   * It is allowed to set it later. Will default to `defaultLocale` in that case.
+   */
+  currentLocale?: string
+
+  translationLoader: TranslationLoader
+
+  /**
+   * Defaults to `defaultMissingTranslationHandler` that returns `[${key}]` and emits console warning.
+   */
+  missingTranslationHandler?: MissingTranslationHandler
+}
+
+export interface TranslationServiceCfgComplete extends TranslationServiceCfg {
+  missingTranslationHandler: MissingTranslationHandler // non-optional
+}
+
+export interface TranslationLoader {
+  load: (locale: string) => Promise<StringMap>
+}
+
+export class TranslationService {
+  constructor(cfg: TranslationServiceCfg, preloadedLocales: StringMap<StringMap> = {}) {
+    this.cfg = {
+      ...cfg,
+      missingTranslationHandler: defaultMissingTranslationHandler,
+    }
+
+    this.locales = {
+      ...preloadedLocales,
+    }
+
+    this.currentLocale = cfg.currentLocale || cfg.defaultLocale
+  }
+
+  cfg: TranslationServiceCfgComplete
+
+  /**
+   * Cache of loaded locales
+   */
+  locales: StringMap<StringMap>
+
+  currentLocale: string
+
+  /**
+   * Manually set locale data, bypassing the TranslationLoader.
+   */
+  setLocale(localeName: string, locale: StringMap): void {
+    this.locales[localeName] = locale
+  }
+
+  getLocale(locale: string): StringMap | undefined {
+    return this.locales[locale]
+  }
+
+  /**
+   * Loads locale(s) (if not already cached) via configured TranslationLoader.
+   * Resolves promise when done (ready to be used).
+   */
+  async loadLocale(locale: string | string[]): Promise<void> {
+    const locales = Array.isArray(locale) ? locale : [locale]
+
+    await pMap(locales, async locale => {
+      if (this.locales[locale]) return // already loaded
+      this.locales[locale] = await this.cfg.translationLoader.load(locale)
+      // console.log(`[tr] locale loaded: ${locale}`)
+    })
+  }
+
+  /**
+   * Will invoke `missingTranslationHandler` on missing tranlation.
+   *
+   * Does NOT do any locale loading. The locale needs to be loaded beforehand:
+   * either pre-loaded and passed to the constructor,
+   * or `await loadLocale(locale)`.
+   */
+  translate(key: string, params?: StringMap): string {
+    return this.translateIfExists(key, params) || this.cfg.missingTranslationHandler(key, params)
+  }
+
+  /**
+   * Does NOT invoke `missingTranslationHandler`, returns `undefined` instead.
+   */
+  translateIfExists(key: string, _params?: StringMap): string | undefined {
+    // todo: support params
+    return this.locales[this.currentLocale]?.[key] || this.locales[this.cfg.defaultLocale]?.[key]
+  }
+}

package/src/browser/imageFitter.ts

@@ -0,0 +1,128 @@
+export interface FitImagesCfg {
+  /**
+   * Container of the images
+   */
+  containerElement: HTMLElement
+
+  /**
+   * Array of image metadatas (most notably: aspectRatio).
+   */
+  images: FitImage[]
+
+  /**
+   * Will be called on each layout change.
+   * Should be listened to to update the width/height of the images in your DOM.
+   */
+  onChange: (images: FitImage[]) => any
+
+  /**
+   * Max image height in pixels.
+   *
+   * @default 300
+   */
+  maxHeight?: number
+
+  /**
+   * Margin between images.
+   *
+   * @default 8
+   */
+  margin?: number
+}
+
+export interface FitImage {
+  src: string
+
+  /**
+   * width divided by height
+   */
+  aspectRatio: number
+
+  /**
+   * Calculated image width to fit the layout.
+   */
+  fitWidth?: number
+  /**
+   * Calculated image height to fit the layout.
+   */
+  fitHeight?: number
+}
+
+/**
+ * Calculates the width/height of the images to fit in the layout.
+ *
+ * Currently does not mutate the cfg.images array, but DOES mutate individual images with .fitWidth, .fitHeight properties.
+ *
+ * @experimental
+ */
+export class ImageFitter {
+  constructor(cfg: FitImagesCfg) {
+    this.cfg = {
+      maxHeight: 300,
+      margin: 8,
+      ...cfg,
+    }
+    this.resizeObserver = new ResizeObserver(entries => this.update(entries))
+    this.resizeObserver.observe(cfg.containerElement)
+  }
+
+  cfg!: Required<FitImagesCfg>
+  resizeObserver: ResizeObserver
+  containerWidth = -1
+
+  stop(): void {
+    this.resizeObserver.disconnect()
+  }
+
+  private update(entries: ResizeObserverEntry[]): void {
+    const width = Math.floor(entries[0]!.contentRect.width)
+    if (width === this.containerWidth) return // we're only interested in width changes
+    this.containerWidth = width
+
+    console.log(`resize ${width}`)
+    this.doLayout(this.cfg.images)
+    this.cfg.onChange(this.cfg.images)
+  }
+
+  private doLayout(imgs: readonly FitImage[]): void {
+    if (imgs.length === 0) return // nothing to do
+    const { maxHeight } = this.cfg
+
+    let imgNodes = imgs.slice(0)
+
+    w: while (imgNodes.length > 0) {
+      let slice: FitImage[]
+      let h: number
+
+      for (let i = 1; i <= imgNodes.length; i++) {
+        slice = imgNodes.slice(0, i)
+        h = this.getHeigth(slice)
+
+        if (h < maxHeight) {
+          this.setHeight(slice, h)
+          imgNodes = imgNodes.slice(i)
+          continue w
+        }
+      }
+
+      this.setHeight(slice!, Math.min(maxHeight, h!))
+      break
+    }
+  }
+
+  private getHeigth(images: readonly FitImage[]): number {
+    const width = this.containerWidth - images.length * this.cfg.margin
+    let r = 0
+    images.forEach(img => (r += img.aspectRatio))
+
+    return width / r // have to round down because Firefox will automatically roundup value with number of decimals > 3
+  }
+
+  // mutates/sets images' fitWidth, fitHeight properties
+  private setHeight(images: readonly FitImage[], height: number): void {
+    images.forEach(img => {
+      img.fitWidth = Math.floor(height * img.aspectRatio)
+      img.fitHeight = Math.floor(height)
+    })
+  }
+}

package/src/browser/script.util.ts

@@ -0,0 +1,52 @@
+import { isServerSide } from '../env'
+import { _objectAssign } from '../types'
+
+export type LoadScriptOptions = Partial<HTMLScriptElement>
+export type LoadCSSOptions = Partial<HTMLLinkElement>
+
+/**
+ * opt.async defaults to `true`.
+ * No other options are set by default.
+ */
+export async function loadScript(src: string, opt?: LoadScriptOptions): Promise<void> {
+  if (isServerSide()) return
+
+  return await new Promise<void>((resolve, reject) => {
+    const s = _objectAssign(document.createElement('script'), {
+      src,
+      async: true,
+      ...opt,
+      onload: resolve as any,
+      onerror: (_event, _source, _lineno, _colno, err) => {
+        reject(err || new Error(`loadScript failed: ${src}`))
+      },
+    })
+    document.head.append(s)
+  })
+}
+
+/**
+ * Default options:
+ * rel: 'stylesheet'
+ *
+ * No other options are set by default.
+ */
+export async function loadCSS(href: string, opt?: LoadCSSOptions): Promise<void> {
+  if (isServerSide()) return
+
+  return await new Promise<void>((resolve, reject) => {
+    const link = _objectAssign(document.createElement('link'), {
+      href,
+      rel: 'stylesheet',
+      // type seems to be unnecessary: https://stackoverflow.com/a/5409146/4919972
+      // type: 'text/css',
+      ...opt,
+      onload: resolve as any,
+      onerror: (_event, _source, _lineno, _colno, err) => {
+        reject(err || new Error(`loadCSS failed: ${href}`))
+      },
+    })
+
+    document.head.append(link)
+  })
+}