tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/libs/sw/browser/plugins/TabManager.mjs

@@ -0,0 +1,274 @@
+import TinyServiceWorker from '../TinyServiceWorker.mjs';
+/** @typedef {import('../../../tools/TinyDebugger.mjs').DebuggerConstructor} DebuggerConstructor - The constructor function for a debugger instance. */
+/**
+ * @typedef {(() => any)} ExtraDataFn - A function that returns custom data.
+ */
+/**
+ * Options of the new instance.
+ * @typedef {Object} ConstructorOptions - Configuration options.
+ * @property {boolean} [trackFocus=true] - Whether to track tab focus status.
+ * @property {boolean} [allowTabClosing=true] - Whether the tab allows the SW to request tab closure.
+ * @property {ExtraDataFn} [getExtraData] - Optional function that returns custom data to be cached in the SW.
+ * @property {Partial<DebuggerConstructor>} [lgConfig] - Debugger configuration.
+ */
+/**
+ * @typedef {Object} TabFocusPayload
+ * @property {boolean} isFocused - Whether the tab is currently active and focused.
+ */
+/**
+ * @typedef {Object} TabInfo
+ * @property {string} id - The unique Client ID.
+ * @property {string} url - The current URL.
+ * @property {string} title - The document title.
+ * @property {boolean} isFocused - Whether the tab currently has window focus.
+ * @property {any} [data] - Custom data provided by the client.
+ */
+/**
+ * @typedef {Object} TabList
+ * @property {number} count - Total number of open tabs.
+ * @property {TabInfo[]} tabs - Array of tab information.
+ */
+/**
+ * Controller to be used in the main thread to communicate with the TabManagerPlugin.
+ */
+class TinySwTabsLayer extends TinyServiceWorker.TinyPluginLayer {
+    /** @type {TinyServiceWorker<any, any>} - The TinyServiceWorker instance used for communication. */
+    #sw;
+    /** @type {boolean} - Indicates whether tab focus tracking is enabled. */
+    #trackFocus;
+    /** @type {boolean} - Indicates whether the tab allows closure requests from the SW. */
+    #allowTabClosing;
+    /** @type {ExtraDataFn|null} - The function used to retrieve custom data for the tab. */
+    #extraDataFn;
+    /**
+     * Gets the current status of the focus tracking configuration.
+     * @returns {boolean} - Whether the tab focus tracking is enabled.
+     */
+    get trackFocus() {
+        return this.#trackFocus;
+    }
+    /**
+     * Gets whether the tab allows closure requests from the Service Worker.
+     * @returns {boolean} - Whether the tab allows closure requests.
+     */
+    get allowTabClosing() {
+        return this.#allowTabClosing;
+    }
+    /**
+     * Determines if the tab is truly active (visible and focused).
+     * @returns {boolean} - True if the tab is visible and has focus.
+     */
+    #getIsTabActive() {
+        const isHidden = 'hidden' in document
+            ? document.hidden
+            : 'mozHidden' in document
+                ? // @ts-ignore
+                    document.mozHidden
+                : 'webkitHidden' in document
+                    ? // @ts-ignore
+                        document.webkitHidden
+                    : false;
+        return !isHidden && document.hasFocus();
+    }
+    /**
+     * Initializes event listeners to detect navigation, visibility, and focus changes.
+     */
+    #initListeners() {
+        // Detect URL/Title changes (Navigation)
+        window.addEventListener('popstate', () => this.#reportStatus());
+        // Detect Tab Closing (Most reliable event for closing/navigating away)
+        window.addEventListener('pagehide', () => this.#reportStatus(true));
+        // Focus and Visibility Tracking
+        if (this.#trackFocus) {
+            const visibilityEvents = ['visibilitychange', 'focus', 'blur', 'pageshow', 'pagehide'];
+            visibilityEvents.forEach((event) => {
+                window.addEventListener(event, () => this.#reportStatus(false));
+            });
+        }
+    }
+    /**
+     * Reports the current status and permissions of this tab to the Service Worker.
+     * @param {boolean} isUnregistering - If true, tells the SW this tab is closing.
+     * @returns {Promise<void>} - A promise that resolves when the status report is complete.
+     */
+    async #reportStatus(isUnregistering = false) {
+        await this.#sw.waitForReady();
+        if (isUnregistering) {
+            return this.#sw.emitApi('tab:unregister');
+        }
+        return this.#sw.emitApi('tab:register', {
+            url: window.location.href,
+            title: document.title,
+            isFocused: this.#trackFocus ? this.#getIsTabActive() : false,
+            data: typeof this.#extraDataFn === 'function' ? await this.#extraDataFn() : undefined,
+            permissions: {
+                allowFocusTracking: this.#trackFocus,
+                allowTabClosing: this.#allowTabClosing,
+            },
+        });
+    }
+    /**
+     * Updates the tab's permissions and synchronizes with the Service Worker.
+     * @param {Object} options - The new permission configuration.
+     * @param {boolean} [options.trackFocus] - New focus tracking permission.
+     * @param {boolean} [options.allowTabClosing] - New tab closing permission.
+     * @returns {Promise<void>} - A promise that resolves when the status report is complete.
+     * @throws {TypeError} If options is not an object or properties are not booleans.
+     */
+    async setPermissions(options = {}) {
+        if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+            throw new TypeError('[TinySwTabsLayer] setPermissions: options must be an object.');
+        }
+        if (options.trackFocus !== undefined && typeof options.trackFocus !== 'boolean') {
+            throw new TypeError('[TinySwTabsLayer] setPermissions: trackFocus must be a boolean.');
+        }
+        if (options.allowTabClosing !== undefined && typeof options.allowTabClosing !== 'boolean') {
+            throw new TypeError('[TinySwTabsLayer] setPermissions: allowTabClosing must be a boolean.');
+        }
+        if (options.trackFocus !== undefined)
+            this.#trackFocus = options.trackFocus;
+        if (options.allowTabClosing !== undefined)
+            this.#allowTabClosing = options.allowTabClosing;
+        return this.#reportStatus();
+    }
+    /**
+     * Initializes a new instance of the TinySwTabsLayer.
+     * @param {TinyServiceWorker<any, any>} sw - The TinyServiceWorker instance used for communication.
+     * @param {ConstructorOptions} [options] - Configuration options.
+     * @throws {TypeError} If sw is not an instance of TinyServiceWorker or options are invalid.
+     */
+    constructor(sw, options = {}) {
+        super({
+            logCfg: {
+                id: '[_main_class_TinySW-Tabs_reset_]',
+                logger: options.lgConfig?.logger ?? console,
+                debugMode: options.lgConfig?.debugMode ?? false,
+                useLogColors: options.lgConfig?.useLogColors ?? false,
+            },
+        });
+        if (!(sw instanceof TinyServiceWorker)) {
+            throw new TypeError('[TinySwTabsLayer] Constructor: sw must be an instance of TinyServiceWorker.');
+        }
+        // Deep validation of ConstructorOptions
+        if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+            throw new TypeError('[TinySwTabsLayer] Constructor: options must be an object.');
+        }
+        if (options.trackFocus !== undefined && typeof options.trackFocus !== 'boolean') {
+            throw new TypeError('[TinySwTabsLayer] Constructor: trackFocus must be a boolean.');
+        }
+        if (options.allowTabClosing !== undefined && typeof options.allowTabClosing !== 'boolean') {
+            throw new TypeError('[TinySwTabsLayer] Constructor: allowTabClosing must be a boolean.');
+        }
+        if (options.getExtraData !== undefined && typeof options.getExtraData !== 'function') {
+            throw new TypeError('[TinySwTabsLayer] Constructor: getExtraData must be a function.');
+        }
+        this.#sw = sw;
+        this.#trackFocus = options.trackFocus ?? true;
+        this.#allowTabClosing = options.allowTabClosing ?? true;
+        this.#extraDataFn = options.getExtraData ?? null;
+        sw.onApi('tab:close', async () => {
+            if (!this.#allowTabClosing) {
+                return { authorized: false };
+            }
+            window.close();
+            return { authorized: true };
+        });
+        this.#initListeners();
+        this.#sw.waitForReady().then(() => this.register());
+    }
+    /**
+     * Registers this tab in the manager.
+     * @returns {Promise<void>} - A promise that resolves when the registration is complete.
+     */
+    async register() {
+        this.#reportStatus();
+    }
+    /**
+     * Explicitly requests the current list of all open tabs.
+     * @returns {Promise<TabList>} - A promise that resolves with the current list of tabs.
+     */
+    async getTabList() {
+        return this.#sw.emitApi('tab:get_list');
+    }
+    /**
+     * Retrieves the information for a specific tab by its unique ID.
+     * @param {string} id - The unique identifier of the tab.
+     * @returns {Promise<TabInfo|null>} - The tab information if found, or null if the tab does not exist.
+     * @throws {TypeError} If the provided id is not a string.
+     */
+    async getTab(id) {
+        if (typeof id !== 'string')
+            throw new TypeError('[TinySwTabsLayer] getTab: id must be a string.');
+        return (await this.#sw.emitApi('tab:get_tab', { id })) ?? null;
+    }
+    /**
+     * Closes a specific tab by its ID.
+     * @param {string} id - The ID of the tab to close.
+     * @returns {Promise<{ closed: boolean }>} - A promise that resolves with the result of the close request.
+     */
+    closeTab(id) {
+        if (typeof id !== 'string')
+            throw new TypeError('[TinySwTabsLayer] closeTab: id must be a string.');
+        return this.#sw.emitApi('tab:close_single', { id });
+    }
+    /**
+     * Closes multiple tabs by their IDs.
+     * @param {string[]} ids - Array of tab IDs.
+     * @returns {Promise<{ closed: (-1|0|1)[] }>} (-1: no permission | 0: no closed | 1: closed)
+     */
+    closeTabs(ids) {
+        if (!Array.isArray(ids))
+            throw new TypeError('[TinySwTabsLayer] closeTabs: ids must be an array.');
+        return this.#sw.emitApi('tab:close_multiple', { ids });
+    }
+    /**
+     * Closes all registered tabs.
+     * @returns {Promise<void>} - A promise that resolves when all tabs have been requested to close.
+     */
+    closeAllTabs() {
+        return this.#sw.emitApi('tab:close_all');
+    }
+    /**
+     * Sets a callback to be executed whenever the tab list changes.
+     * @param {(list: TabList) => void} callback - The function to execute when the tab list changes.
+     */
+    onUpdate(callback) {
+        this.#sw.on('tab:list_updated', callback);
+    }
+    /**
+     * Removes a callback from tab list change events.
+     * @param {(list: TabList) => void} callback - The callback function to remove.
+     */
+    offUpdate(callback) {
+        this.#sw.off('tab:list_updated', callback);
+    }
+}
+/**
+ * A plugin for TinyServiceWorker that manages a centralized registry of all open website tabs.
+ * @type {import('../TinyServiceWorker.mjs').SwPluginInstaller<TinySwTabsLayer, 'TabManager', '1.0.0', [ConstructorOptions]|[]>}
+ */
+const TinyTabManagerPlugin = (instance, lgConfig = {}) => {
+    const engine = instance.engine;
+    instance.id = 'TabManager';
+    instance.version = '1.0.0';
+    instance.description = 'Advanced tab manager.';
+    instance.authors = ['JasminDreasond'];
+    instance.contributors = ['JasminDreasond'];
+    instance.categories = ['tab-manager'];
+    instance.tags = ['management'];
+    instance.allowedGets = [
+        'onUpdate',
+        'offUpdate',
+        'getTabList',
+        'getTab',
+        'register',
+        'closeTab',
+        'closeTabs',
+        'closeAllTabs',
+        'trackFocus',
+    ];
+    if (!(engine instanceof TinyServiceWorker))
+        throw new TypeError('Plugin requires a TinyServiceWorker instance to function.');
+    return new TinySwTabsLayer(engine, lgConfig);
+};
+export default TinyTabManagerPlugin;

package/dist/v1/libs/sw/browser/utils.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * Requests permission from the user to display notifications.
+ *
+ * @returns {Promise<'granted' | 'denied' | 'default'>} The resulting permission status.
+ * @throws {Error} If the Notification API is not supported by the browser.
+ */
+const requestNotificationPermission = async () => {
+  if (!('Notification' in window)) {
+    throw new Error('Notification API is not supported in this browser.');
+  }
+
+  // If permission is already 'granted', return immediately.
+  if (Notification.permission === 'granted') {
+    return 'granted';
+  }
+
+  // If 'denied', the user has blocked it and we cannot prompt again via code.
+  if (Notification.permission === 'denied') {
+    return 'denied';
+  }
+
+  const permission = await Notification.requestPermission();
+  return permission;
+};
+
+exports.requestNotificationPermission = requestNotificationPermission;

package/dist/v1/libs/sw/browser/utils.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Requests permission from the user to display notifications.
+ *
+ * @returns {Promise<'granted' | 'denied' | 'default'>} The resulting permission status.
+ * @throws {Error} If the Notification API is not supported by the browser.
+ */
+export declare const requestNotificationPermission: () => Promise<'granted' | 'denied' | 'default'>;
+//# sourceMappingURL=utils.d.mts.map

package/dist/v1/libs/sw/browser/utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.mts","sourceRoot":"","sources":["../../../../../src/v1/libs/sw/browser/utils.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,QAH7B,OAAO,CAAC,SAAS,GAAG,QAAQ,GAAG,SAAS,CAoBpD,CAAC"}

package/dist/v1/libs/sw/browser/utils.mjs

@@ -0,0 +1,21 @@
+/**
+ * Requests permission from the user to display notifications.
+ *
+ * @returns {Promise<'granted' | 'denied' | 'default'>} The resulting permission status.
+ * @throws {Error} If the Notification API is not supported by the browser.
+ */
+export const requestNotificationPermission = async () => {
+    if (!('Notification' in window)) {
+        throw new Error('Notification API is not supported in this browser.');
+    }
+    // If permission is already 'granted', return immediately.
+    if (Notification.permission === 'granted') {
+        return 'granted';
+    }
+    // If 'denied', the user has blocked it and we cannot prompt again via code.
+    if (Notification.permission === 'denied') {
+        return 'denied';
+    }
+    const permission = await Notification.requestPermission();
+    return permission;
+};

package/dist/v1/libs/sw/service/TinyPushRouter.cjs

@@ -0,0 +1,222 @@
+'use strict';
+
+var utils = require('../utils.cjs');
+
+/**
+ * @file Routes a normalized push message to a handler, based on `message.type`.
+ *
+ * The router is transport agnostic: it never touches the Notification API. That
+ * responsibility belongs to the handler, which keeps the class testable in Node.
+ */
+
+/**
+ * Describes the mutable state shared between the router and the active handler
+ * during a single dispatch cycle.
+ *
+ * @typedef {Object} TinyPushContext
+ * @property {PushEvent} event - The native push event.
+ * @property {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+ * @property {import('./TinyServiceWorkerEngine.mjs').default} engine - The engine that received the push.
+ * @property {boolean} handled - Set to `true` to stop the chain.
+ * @property {boolean} notificationShown - Set to `true` when a notification was displayed.
+ */
+
+/**
+ * Handles a normalized push message that matched a route.
+ *
+ * @callback TinyPushHandler
+ * @param {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+ * @param {TinyPushContext} context - The dispatch context.
+ * @returns {Promise<boolean|void>|boolean|void} Return `false` to fall through to the next handler.
+ */
+
+/**
+ * Decides whether a normalized push message is allowed to reach a handler.
+ *
+ * @callback TinyPushGuard
+ * @param {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+ * @param {TinyPushContext} context - The dispatch context.
+ * @returns {Promise<boolean>|boolean} Return `false` to drop the message.
+ */
+
+/**
+ * Routes normalized push messages to registered handlers based on `message.type`.
+ *
+ * @beta
+ */
+class TinyPushRouter {
+  static #PUSH_TYPE = utils.PUSH_TYPE;
+  static get PUSH_TYPE() {
+    return TinyPushRouter.#PUSH_TYPE;
+  }
+
+  /** @type {Map<string, TinyPushHandler>} */
+  #exact = new Map();
+
+  /** @type {Array<{ source: string, regex: RegExp, handler: TinyPushHandler }>} */
+  #patterns = [];
+
+  /** @type {TinyPushGuard[]} */
+  #guards = [];
+
+  /** @type {TinyPushHandler|null} */
+  #fallback = null;
+
+  /** @type {((error: unknown, message: unknown) => void)|null} */
+  #onError = null;
+
+  /**
+   * Registers a guard. Every guard runs before the handler.
+   *
+   * A guard that returns `false` drops the message: no handler runs and the
+   * `push` promise resolves with `true`, so the browser does not show a
+   * generic "This site has been updated in the background" notification.
+   *
+   * @param {TinyPushGuard} guard - The guard to register.
+   * @returns {this} The router, for chaining.
+   * @throws {TypeError} If `guard` is not a function.
+   */
+  use(guard) {
+    if (typeof guard !== 'function') {
+      throw new TypeError('[TinyPushRouter] use: guard must be a function.');
+    }
+    this.#guards.push(guard);
+    return this;
+  }
+
+  /**
+   * Registers a handler for an exact `message.type`.
+   *
+   * @param {string} type - The type to match.
+   * @param {TinyPushHandler} handler - The handler.
+   * @returns {this} The router, for chaining.
+   * @throws {TypeError} If `type` is not a non-empty string or `handler` is not a function.
+   */
+  on(type, handler) {
+    if (typeof type !== 'string' || type.trim() === '') {
+      throw new TypeError('[TinyPushRouter] on: type must be a non-empty string.');
+    }
+    if (typeof handler !== 'function') {
+      throw new TypeError('[TinyPushRouter] on: handler must be a function.');
+    }
+    this.#exact.set(type, handler);
+    return this;
+  }
+
+  /**
+   * Registers a handler for every `message.type` that matches a regular expression.
+   *
+   * @param {RegExp} pattern - The pattern applied to `message.type`.
+   * @param {TinyPushHandler} handler - The handler.
+   * @returns {this} The router, for chaining.
+   * @throws {TypeError} If `pattern` is not a RegExp or `handler` is not a function.
+   */
+  onMatch(pattern, handler) {
+    if (!(pattern instanceof RegExp)) {
+      throw new TypeError('[TinyPushRouter] onMatch: pattern must be a RegExp.');
+    }
+    if (typeof handler !== 'function') {
+      throw new TypeError('[TinyPushRouter] onMatch: handler must be a function.');
+    }
+    this.#patterns.push({ source: pattern.source, regex: pattern, handler });
+    return this;
+  }
+
+  /**
+   * Registers the handler used when no other handler matches.
+   *
+   * @param {TinyPushHandler} handler - The fallback handler.
+   * @returns {this} The router, for chaining.
+   * @throws {TypeError} If `handler` is not a function.
+   */
+  otherwise(handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('[TinyPushRouter] otherwise: handler must be a function.');
+    }
+    this.#fallback = handler;
+    return this;
+  }
+
+  /**
+   * Registers an error handler.
+   *
+   * @param {(error: unknown, message: unknown) => void} handler - The error handler.
+   * @returns {this} The router, for chaining.
+   * @throws {TypeError} If `handler` is not a function.
+   */
+  catch(handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('[TinyPushRouter] catch: handler must be a function.');
+    }
+    this.#onError = handler;
+    return this;
+  }
+
+  /**
+   * Reports whether a handler is registered for the given type.
+   *
+   * @param {string} type - The type to look up.
+   * @returns {boolean} `true` when a handler is registered.
+   */
+  has(type) {
+    if (this.#exact.has(type)) return true;
+    return this.#patterns.some(({ regex }) => regex.test(type));
+  }
+
+  /** @returns {number} The number of registered handlers. */
+  get size() {
+    return this.#exact.size + this.#patterns.length;
+  }
+
+  /**
+   * Dispatches a message to the first matching handler.
+   *
+   * @param {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+   * @param {TinyPushContext} context - The dispatch context.
+   * @returns {Promise<boolean>} `true` when a handler claimed the message.
+   * @throws {TypeError} If `message` or `context` are invalid.
+   */
+  async dispatch(message, context) {
+    if (typeof message !== 'object' || message === null) {
+      throw new TypeError('[TinyPushRouter] dispatch: message must be a non-null object.');
+    }
+    if (typeof context !== 'object' || context === null) {
+      throw new TypeError('[TinyPushRouter] dispatch: context must be a non-null object.');
+    }
+
+    try {
+      for (const guard of this.#guards) {
+        const allowed = await guard(message, context);
+        if (allowed === false) return true;
+      }
+
+      const handler = this.#exact.get(message.type);
+
+      if (handler) {
+        const result = await handler(message, context);
+        if (result !== false) return true;
+      }
+
+      for (const { regex, handler: patternHandler } of this.#patterns) {
+        if (!regex.test(message.type)) continue;
+        const result = await patternHandler(message, context);
+        if (result !== false) return true;
+      }
+
+      if (this.#fallback) {
+        await this.#fallback(message, context);
+        return true;
+      }
+
+      return false;
+    } catch (error) {
+      if (this.#onError) {
+        this.#onError(error, message);
+        return true;
+      }
+      throw error;
+    }
+  }
+}
+
+module.exports = TinyPushRouter;