@naturalcycles/js-lib 14.256.0 → 14.257.0

package/cfg/frontend/tsconfig.json

@@ -0,0 +1,67 @@
+//
+// @naturalcycles/js-lib/cfg/frontend/tsconfig.json
+//
+// Shared tsconfig for Frontend applications
+//
+{
+  "compilerOptions": {
+    // Target/module
+    "target": "es2020", // es2020+ browsers, adjust to your requirements!
+    "lib": ["esnext", "dom", "dom.iterable"],
+    "module": "esnext",
+    "moduleResolution": "node",
+    "moduleDetection": "force",
+    // specifying these explicitly for better IDE compatibility (but they're on by default with module=nodenext)
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    // Faster compilation in general
+    // Support for external compilers (e.g esbuild)
+    // Speedup in Jest by using "isolatedModules" in 'ts-jest' config
+    "isolatedModules": true,
+
+    // Emit
+    "sourceMap": false,
+    "declaration": false,
+    // Otherwise since es2022 it defaults to true
+    // and starts to produce different/unexpected behavior
+    // https://angular.schule/blog/2022-11-use-define-for-class-fields
+    "useDefineForClassFields": false,
+    "importHelpers": true,
+
+    // Strictness
+    "strict": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "suppressImplicitAnyIndexErrors": false,
+    "noUncheckedIndexedAccess": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitOverride": true,
+
+    // Enabled should be faster, but will catch less errors
+    // "skipLibCheck": true,
+
+    // Disabled because of https://github.com/Microsoft/TypeScript/issues/29172
+    // Need to be specified in the project tsconfig
+    // "outDir": "dist",
+    // "rootDir": "./src",
+    //  "baseUrl": "./",
+    //  "paths": {
+    //    "@src/*": ["src/*"]
+    //  },
+    // "typeRoots": [
+    //   "node_modules/@types",
+    //   "src/@types"
+    // ],
+
+    // Other
+    "jsx": "preserve",
+    "pretty": true,
+    "newLine": "lf",
+    "experimentalDecorators": true,
+    // "emitDecoratorMetadata": true // use if needed
+  },
+  // Need to be specified in the project tsconfig
+  // "include": ["src"],
+  // "exclude": ["**/__exclude", "**/@linked"]
+}

package/dist/browser/adminService.d.ts

@@ -0,0 +1,69 @@
+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;
+}
+/**
+ * @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 declare class AdminService {
+    constructor(cfg?: AdminModeCfg);
+    cfg: Required<AdminModeCfg>;
+    adminMode: boolean;
+    private listening;
+    /**
+     * Start listening to keyboard events to toggle AdminMode when detected.
+     */
+    startListening(): void;
+    stopListening(): void;
+    private keydownListener;
+    toggleRedDot(): Promise<void>;
+    private toggleRedDotVisibility;
+    private getRedDotElement;
+}

package/dist/browser/adminService.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdminService = void 0;
+const tslib_1 = require("tslib");
+const memo_decorator_1 = require("../decorators/memo.decorator");
+const env_1 = require("../env");
+const stringify_1 = require("../string/stringify");
+const RED_DOT_ID = '__red-dot__';
+const NOOP = () => { };
+/**
+ * @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
+ */
+class AdminService {
+    constructor(cfg) {
+        this.adminMode = false;
+        this.listening = false;
+        this.cfg = {
+            predicate: e => e.ctrlKey && e.key === 'L',
+            persistToLocalStorage: true,
+            localStorageKey: '__adminMode__',
+            onRedDotClick: NOOP,
+            onChange: NOOP,
+            beforeEnter: () => true,
+            beforeExit: () => true,
+            ...cfg,
+        };
+    }
+    /**
+     * Start listening to keyboard events to toggle AdminMode when detected.
+     */
+    startListening() {
+        if (this.listening || (0, env_1.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() {
+        if ((0, env_1.isServerSide)())
+            return;
+        document.removeEventListener('keydown', this.keydownListener);
+        this.listening = false;
+    }
+    async keydownListener(e) {
+        // console.log(e)
+        if (!this.cfg.predicate(e))
+            return;
+        await this.toggleRedDot();
+    }
+    async toggleRedDot() {
+        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((0, stringify_1._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);
+    }
+    toggleRedDotVisibility() {
+        this.getRedDotElement().style.display = this.adminMode ? 'block' : 'none';
+    }
+    getRedDotElement() {
+        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;
+    }
+}
+exports.AdminService = AdminService;
+tslib_1.__decorate([
+    (0, memo_decorator_1._Memo)()
+], AdminService.prototype, "getRedDotElement", null);

package/dist/browser/analytics.util.d.ts

@@ -0,0 +1,12 @@
+declare global {
+    interface Window {
+        dataLayer: any[];
+        gtag: (...args: any[]) => void;
+    }
+}
+/**
+ * Pass enabled = false to only init window.gtag, but not load actual gtag script (e.g in dev mode).
+ */
+export declare function loadGTag(gtagId: string, enabled?: boolean): Promise<void>;
+export declare function loadGTM(gtmId: string, enabled?: boolean): Promise<void>;
+export declare function loadHotjar(hjid: number): void;

package/dist/browser/analytics.util.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadGTag = loadGTag;
+exports.loadGTM = loadGTM;
+exports.loadHotjar = loadHotjar;
+const js_lib_1 = require("@naturalcycles/js-lib");
+const script_util_1 = require("./script.util");
+/* 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).
+ */
+async function loadGTag(gtagId, enabled = true) {
+    if ((0, js_lib_1.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 (0, script_util_1.loadScript)(`https://www.googletagmanager.com/gtag/js?id=${gtagId}`);
+}
+async function loadGTM(gtmId, enabled = true) {
+    if ((0, js_lib_1.isServerSide)())
+        return;
+    window.dataLayer ||= [];
+    window.dataLayer.push({
+        'gtm.start': Date.now(),
+        event: 'gtm.js',
+    });
+    if (!enabled)
+        return;
+    await (0, script_util_1.loadScript)(`https://www.googletagmanager.com/gtm.js?id=${gtmId}`);
+}
+function loadHotjar(hjid) {
+    if ((0, js_lib_1.isServerSide)())
+        return;
+    ;
+    ((h, o, t, j, a, r) => {
+        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/dist/browser/i18n/fetchTranslationLoader.d.ts

@@ -0,0 +1,13 @@
+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 declare class FetchTranslationLoader implements TranslationLoader {
+    fetcher: Fetcher;
+    constructor(fetcher: Fetcher);
+    load(locale: string): Promise<StringMap>;
+}

package/dist/browser/i18n/fetchTranslationLoader.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FetchTranslationLoader = void 0;
+/**
+ * Use `baseUrl` to prefix your language files.
+ * Example URL structure:
+ * ${baseUrl}/${locale}.json
+ */
+class FetchTranslationLoader {
+    constructor(fetcher) {
+        this.fetcher = fetcher;
+    }
+    async load(locale) {
+        return await this.fetcher.get(`${locale}.json`);
+    }
+}
+exports.FetchTranslationLoader = FetchTranslationLoader;

package/dist/browser/i18n/translation.service.d.ts

@@ -0,0 +1,53 @@
+import { StringMap } from '../../types';
+export type MissingTranslationHandler = (key: string, params?: StringMap<any>) => string;
+export declare const defaultMissingTranslationHandler: MissingTranslationHandler;
+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;
+}
+export interface TranslationLoader {
+    load: (locale: string) => Promise<StringMap>;
+}
+export declare class TranslationService {
+    constructor(cfg: TranslationServiceCfg, preloadedLocales?: StringMap<StringMap>);
+    cfg: TranslationServiceCfgComplete;
+    /**
+     * Cache of loaded locales
+     */
+    locales: StringMap<StringMap>;
+    currentLocale: string;
+    /**
+     * Manually set locale data, bypassing the TranslationLoader.
+     */
+    setLocale(localeName: string, locale: StringMap): void;
+    getLocale(locale: string): StringMap | undefined;
+    /**
+     * Loads locale(s) (if not already cached) via configured TranslationLoader.
+     * Resolves promise when done (ready to be used).
+     */
+    loadLocale(locale: string | string[]): Promise<void>;
+    /**
+     * 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;
+    /**
+     * Does NOT invoke `missingTranslationHandler`, returns `undefined` instead.
+     */
+    translateIfExists(key: string, _params?: StringMap): string | undefined;
+}

package/dist/browser/i18n/translation.service.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranslationService = exports.defaultMissingTranslationHandler = void 0;
+const pMap_1 = require("../../promise/pMap");
+const defaultMissingTranslationHandler = key => {
+    console.warn(`[tr] missing: ${key}`);
+    return `[${key}]`;
+};
+exports.defaultMissingTranslationHandler = defaultMissingTranslationHandler;
+class TranslationService {
+    constructor(cfg, preloadedLocales = {}) {
+        this.cfg = {
+            ...cfg,
+            missingTranslationHandler: exports.defaultMissingTranslationHandler,
+        };
+        this.locales = {
+            ...preloadedLocales,
+        };
+        this.currentLocale = cfg.currentLocale || cfg.defaultLocale;
+    }
+    /**
+     * Manually set locale data, bypassing the TranslationLoader.
+     */
+    setLocale(localeName, locale) {
+        this.locales[localeName] = locale;
+    }
+    getLocale(locale) {
+        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) {
+        const locales = Array.isArray(locale) ? locale : [locale];
+        await (0, pMap_1.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, params) {
+        return this.translateIfExists(key, params) || this.cfg.missingTranslationHandler(key, params);
+    }
+    /**
+     * Does NOT invoke `missingTranslationHandler`, returns `undefined` instead.
+     */
+    translateIfExists(key, _params) {
+        // todo: support params
+        return this.locales[this.currentLocale]?.[key] || this.locales[this.cfg.defaultLocale]?.[key];
+    }
+}
+exports.TranslationService = TranslationService;

package/dist/browser/imageFitter.d.ts

@@ -0,0 +1,60 @@
+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 declare class ImageFitter {
+    constructor(cfg: FitImagesCfg);
+    cfg: Required<FitImagesCfg>;
+    resizeObserver: ResizeObserver;
+    containerWidth: number;
+    stop(): void;
+    private update;
+    private doLayout;
+    private getHeigth;
+    private setHeight;
+}

package/dist/browser/imageFitter.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImageFitter = void 0;
+/**
+ * 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
+ */
+class ImageFitter {
+    constructor(cfg) {
+        this.containerWidth = -1;
+        this.cfg = {
+            maxHeight: 300,
+            margin: 8,
+            ...cfg,
+        };
+        this.resizeObserver = new ResizeObserver(entries => this.update(entries));
+        this.resizeObserver.observe(cfg.containerElement);
+    }
+    stop() {
+        this.resizeObserver.disconnect();
+    }
+    update(entries) {
+        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);
+    }
+    doLayout(imgs) {
+        if (imgs.length === 0)
+            return; // nothing to do
+        const { maxHeight } = this.cfg;
+        let imgNodes = imgs.slice(0);
+        w: while (imgNodes.length > 0) {
+            let slice;
+            let h;
+            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;
+        }
+    }
+    getHeigth(images) {
+        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
+    setHeight(images, height) {
+        images.forEach(img => {
+            img.fitWidth = Math.floor(height * img.aspectRatio);
+            img.fitHeight = Math.floor(height);
+        });
+    }
+}
+exports.ImageFitter = ImageFitter;

package/dist/browser/script.util.d.ts

@@ -0,0 +1,14 @@
+export type LoadScriptOptions = Partial<HTMLScriptElement>;
+export type LoadCSSOptions = Partial<HTMLLinkElement>;
+/**
+ * opt.async defaults to `true`.
+ * No other options are set by default.
+ */
+export declare function loadScript(src: string, opt?: LoadScriptOptions): Promise<void>;
+/**
+ * Default options:
+ * rel: 'stylesheet'
+ *
+ * No other options are set by default.
+ */
+export declare function loadCSS(href: string, opt?: LoadCSSOptions): Promise<void>;

package/dist/browser/script.util.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadScript = loadScript;
+exports.loadCSS = loadCSS;
+const env_1 = require("../env");
+const types_1 = require("../types");
+/**
+ * opt.async defaults to `true`.
+ * No other options are set by default.
+ */
+async function loadScript(src, opt) {
+    if ((0, env_1.isServerSide)())
+        return;
+    return await new Promise((resolve, reject) => {
+        const s = (0, types_1._objectAssign)(document.createElement('script'), {
+            src,
+            async: true,
+            ...opt,
+            onload: resolve,
+            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.
+ */
+async function loadCSS(href, opt) {
+    if ((0, env_1.isServerSide)())
+        return;
+    return await new Promise((resolve, reject) => {
+        const link = (0, types_1._objectAssign)(document.createElement('link'), {
+            href,
+            rel: 'stylesheet',
+            // type seems to be unnecessary: https://stackoverflow.com/a/5409146/4919972
+            // type: 'text/css',
+            ...opt,
+            onload: resolve,
+            onerror: (_event, _source, _lineno, _colno, err) => {
+                reject(err || new Error(`loadCSS failed: ${href}`));
+            },
+        });
+        document.head.append(link);
+    });
+}

package/dist/browser/topbar.d.ts

@@ -0,0 +1,23 @@
+export interface TopBarOptions {
+    /**
+     * @default true
+     */
+    autoRun?: boolean;
+    /**
+     * @default 5
+     */
+    barThickness?: number;
+    barColors?: any;
+    shadowColor?: any;
+    /**
+     * @default 10
+     */
+    shadowBlur?: number;
+}
+export declare const topbar: {
+    config(opts: TopBarOptions): void;
+    set(show: boolean, opts?: TopBarOptions): void;
+    show(opts?: TopBarOptions): void;
+    progress(to: number | string): any;
+    hide(): void;
+};