tiny-essentials 1.20.2 → 1.21.0

package/dist/v1/libs/TinyArrayPaginator.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * A predicate function used to determine whether an item should be included in the filtered results.
+ * Works similarly to the callback function of `Array.prototype.filter`.
+ *
+ * @callback GetFilter
+ * @param {any} value - The current element being processed in the array.
+ * @param {number} index - The index of the current element within the array.
+ * @param {any[]} array - The full array being processed.
+ * @returns {boolean} Returns `true` to include the element in the results, or `false` to exclude it.
+ */
+
+/**
+ * A encapsulated wrapper for array pagination.
+ * Provides methods to retrieve paginated results with metadata,
+ * while keeping the source array safe from direct modifications.
+ */
+class TinyArrayPaginator {
+  /**
+   * Internal storage for the paginated data source.
+   * @type {any[]|Set<any>}
+   */
+  #data;
+
+  /**
+   * Gets current stored array.
+   * @returns {any[]|Set<any>}
+   */
+  get data() {
+    return this.#data;
+  }
+
+  /**
+   * Replaces the current data array.
+   * @param {any[]|Set<any>} value - The new array to be used as the data source.
+   * @throws {TypeError} If the provided value is not an array.
+   */
+  set data(value) {
+    if (!Array.isArray(value) && !(value instanceof Set))
+      throw new TypeError('Paginator expects an array or Set as data source.');
+    this.#data = value;
+  }
+
+  /**
+   * Gets the total number of items in the current data array.
+   * @returns {number} Total number of stored items.
+   */
+  get size() {
+    return Array.isArray(this.#data) ? this.#data.length : this.#data.size;
+  }
+
+  /**
+   * Creates a new paginator instance for the given data array.
+   * @param {any[]|Set<any>} data - The array to be paginated.
+   * @throws {TypeError} If the provided data is not an array.
+   */
+  constructor(data) {
+    if (!Array.isArray(data) && !(data instanceof Set))
+      throw new TypeError('Paginator expects an array or Set as data source.');
+    this.#data = data;
+  }
+
+  /**
+   * Filters data according to a search query and returns paginated results.
+   * @param {Object} settings
+   * @param {number} settings.page - The page number (1-based index).
+   * @param {number} settings.perPage - Items per page.
+   * @param {Record<string, any> | GetFilter} [settings.filter=null] - Filtering criteria:
+   *   - Object: key-value pairs for exact match, substring match, or RegExp
+   *   - Function: custom filter function returning true for items to include
+   * @returns {{
+   *   items: any[],            // The subset of items for the requested page.
+   *   page: number,            // The current (validated) page number.
+   *   perPage: number,         // Number of items per page used in the calculation.
+   *   totalItems: number,      // Total number of items in the filtered data.
+   *   totalPages: number,      // Total number of pages available.
+   *   hasPrev: boolean,        // Whether a previous page exists.
+   *   hasNext: boolean         // Whether a next page exists.
+   * }}
+   */
+  get({ page, perPage, filter }) {
+    if (!Number.isInteger(page) || page < 1)
+      throw new RangeError('Page number must be a positive integer.');
+    if (!Number.isInteger(perPage) || perPage < 1)
+      throw new RangeError('Items per page must be a positive integer.');
+
+    const data = Array.isArray(this.#data) ? this.#data : Array.from(this.#data);
+    let dataToUse = data;
+
+    if (filter) {
+      if (typeof filter === 'function') {
+        dataToUse = data.filter((item, idx, arr) => filter(item, idx, arr));
+      } else if (typeof filter === 'object') {
+        dataToUse = data.filter((item) =>
+          Object.entries(filter).every(([key, value]) => {
+            const v = item[key];
+            if (value instanceof RegExp) return value.test(v);
+            return v === value;
+          }),
+        );
+      } else {
+        throw new TypeError('Filter must be an object or a function');
+      }
+    } else {
+      dataToUse = data;
+    }
+
+    const totalItems = dataToUse.length;
+    const totalPages = Math.max(1, Math.ceil(totalItems / perPage));
+
+    // Ensure page is within valid range
+    const safePage = Math.min(page, totalPages);
+
+    const start = (safePage - 1) * perPage;
+    const end = start + perPage;
+    const hasPrev = safePage > 1;
+    const hasNext = safePage < totalPages;
+
+    return {
+      items: dataToUse.slice(start, end),
+      page: safePage,
+      perPage,
+      totalItems,
+      totalPages,
+      hasPrev,
+      hasNext,
+    };
+  }
+}
+
+module.exports = TinyArrayPaginator;

package/dist/v1/libs/TinyArrayPaginator.d.mts

@@ -0,0 +1,78 @@
+export default TinyArrayPaginator;
+/**
+ * A predicate function used to determine whether an item should be included in the filtered results.
+ * Works similarly to the callback function of `Array.prototype.filter`.
+ */
+export type GetFilter = (value: any, index: number, array: any[]) => boolean;
+/**
+ * A predicate function used to determine whether an item should be included in the filtered results.
+ * Works similarly to the callback function of `Array.prototype.filter`.
+ *
+ * @callback GetFilter
+ * @param {any} value - The current element being processed in the array.
+ * @param {number} index - The index of the current element within the array.
+ * @param {any[]} array - The full array being processed.
+ * @returns {boolean} Returns `true` to include the element in the results, or `false` to exclude it.
+ */
+/**
+ * A encapsulated wrapper for array pagination.
+ * Provides methods to retrieve paginated results with metadata,
+ * while keeping the source array safe from direct modifications.
+ */
+declare class TinyArrayPaginator {
+    /**
+     * Creates a new paginator instance for the given data array.
+     * @param {any[]|Set<any>} data - The array to be paginated.
+     * @throws {TypeError} If the provided data is not an array.
+     */
+    constructor(data: any[] | Set<any>);
+    /**
+     * Replaces the current data array.
+     * @param {any[]|Set<any>} value - The new array to be used as the data source.
+     * @throws {TypeError} If the provided value is not an array.
+     */
+    set data(value: any[] | Set<any>);
+    /**
+     * Gets current stored array.
+     * @returns {any[]|Set<any>}
+     */
+    get data(): any[] | Set<any>;
+    /**
+     * Gets the total number of items in the current data array.
+     * @returns {number} Total number of stored items.
+     */
+    get size(): number;
+    /**
+     * Filters data according to a search query and returns paginated results.
+     * @param {Object} settings
+     * @param {number} settings.page - The page number (1-based index).
+     * @param {number} settings.perPage - Items per page.
+     * @param {Record<string, any> | GetFilter} [settings.filter=null] - Filtering criteria:
+     *   - Object: key-value pairs for exact match, substring match, or RegExp
+     *   - Function: custom filter function returning true for items to include
+     * @returns {{
+     *   items: any[],            // The subset of items for the requested page.
+     *   page: number,            // The current (validated) page number.
+     *   perPage: number,         // Number of items per page used in the calculation.
+     *   totalItems: number,      // Total number of items in the filtered data.
+     *   totalPages: number,      // Total number of pages available.
+     *   hasPrev: boolean,        // Whether a previous page exists.
+     *   hasNext: boolean         // Whether a next page exists.
+     * }}
+     */
+    get({ page, perPage, filter }: {
+        page: number;
+        perPage: number;
+        filter?: Record<string, any> | GetFilter | undefined;
+    }): {
+        items: any[];
+        page: number;
+        perPage: number;
+        totalItems: number;
+        totalPages: number;
+        hasPrev: boolean;
+        hasNext: boolean;
+    };
+    #private;
+}
+//# sourceMappingURL=TinyArrayPaginator.d.mts.map

package/dist/v1/libs/TinyArrayPaginator.mjs

@@ -0,0 +1,119 @@
+/**
+ * A predicate function used to determine whether an item should be included in the filtered results.
+ * Works similarly to the callback function of `Array.prototype.filter`.
+ *
+ * @callback GetFilter
+ * @param {any} value - The current element being processed in the array.
+ * @param {number} index - The index of the current element within the array.
+ * @param {any[]} array - The full array being processed.
+ * @returns {boolean} Returns `true` to include the element in the results, or `false` to exclude it.
+ */
+/**
+ * A encapsulated wrapper for array pagination.
+ * Provides methods to retrieve paginated results with metadata,
+ * while keeping the source array safe from direct modifications.
+ */
+class TinyArrayPaginator {
+    /**
+     * Internal storage for the paginated data source.
+     * @type {any[]|Set<any>}
+     */
+    #data;
+    /**
+     * Gets current stored array.
+     * @returns {any[]|Set<any>}
+     */
+    get data() {
+        return this.#data;
+    }
+    /**
+     * Replaces the current data array.
+     * @param {any[]|Set<any>} value - The new array to be used as the data source.
+     * @throws {TypeError} If the provided value is not an array.
+     */
+    set data(value) {
+        if (!Array.isArray(value) && !(value instanceof Set))
+            throw new TypeError('Paginator expects an array or Set as data source.');
+        this.#data = value;
+    }
+    /**
+     * Gets the total number of items in the current data array.
+     * @returns {number} Total number of stored items.
+     */
+    get size() {
+        return Array.isArray(this.#data) ? this.#data.length : this.#data.size;
+    }
+    /**
+     * Creates a new paginator instance for the given data array.
+     * @param {any[]|Set<any>} data - The array to be paginated.
+     * @throws {TypeError} If the provided data is not an array.
+     */
+    constructor(data) {
+        if (!Array.isArray(data) && !(data instanceof Set))
+            throw new TypeError('Paginator expects an array or Set as data source.');
+        this.#data = data;
+    }
+    /**
+     * Filters data according to a search query and returns paginated results.
+     * @param {Object} settings
+     * @param {number} settings.page - The page number (1-based index).
+     * @param {number} settings.perPage - Items per page.
+     * @param {Record<string, any> | GetFilter} [settings.filter=null] - Filtering criteria:
+     *   - Object: key-value pairs for exact match, substring match, or RegExp
+     *   - Function: custom filter function returning true for items to include
+     * @returns {{
+     *   items: any[],            // The subset of items for the requested page.
+     *   page: number,            // The current (validated) page number.
+     *   perPage: number,         // Number of items per page used in the calculation.
+     *   totalItems: number,      // Total number of items in the filtered data.
+     *   totalPages: number,      // Total number of pages available.
+     *   hasPrev: boolean,        // Whether a previous page exists.
+     *   hasNext: boolean         // Whether a next page exists.
+     * }}
+     */
+    get({ page, perPage, filter }) {
+        if (!Number.isInteger(page) || page < 1)
+            throw new RangeError('Page number must be a positive integer.');
+        if (!Number.isInteger(perPage) || perPage < 1)
+            throw new RangeError('Items per page must be a positive integer.');
+        const data = Array.isArray(this.#data) ? this.#data : Array.from(this.#data);
+        let dataToUse = data;
+        if (filter) {
+            if (typeof filter === 'function') {
+                dataToUse = data.filter((item, idx, arr) => filter(item, idx, arr));
+            }
+            else if (typeof filter === 'object') {
+                dataToUse = data.filter((item) => Object.entries(filter).every(([key, value]) => {
+                    const v = item[key];
+                    if (value instanceof RegExp)
+                        return value.test(v);
+                    return v === value;
+                }));
+            }
+            else {
+                throw new TypeError('Filter must be an object or a function');
+            }
+        }
+        else {
+            dataToUse = data;
+        }
+        const totalItems = dataToUse.length;
+        const totalPages = Math.max(1, Math.ceil(totalItems / perPage));
+        // Ensure page is within valid range
+        const safePage = Math.min(page, totalPages);
+        const start = (safePage - 1) * perPage;
+        const end = start + perPage;
+        const hasPrev = safePage > 1;
+        const hasNext = safePage < totalPages;
+        return {
+            items: dataToUse.slice(start, end),
+            page: safePage,
+            perPage,
+            totalItems,
+            totalPages,
+            hasPrev,
+            hasNext,
+        };
+    }
+}
+export default TinyArrayPaginator;

package/dist/v1/libs/TinyCookieConsent.cjs

@@ -0,0 +1,278 @@
+'use strict';
+
+/**
+ * @typedef {Object} Category
+ * @property {string} label - Category label displayed to the user
+ * @property {boolean} required - If true, cannot be disabled
+ * @property {boolean} default - Default state (true = enabled, false = disabled)
+ */
+
+/**
+ * @typedef {Object} Config
+ * @property {string} message - Consent message
+ * @property {string} acceptText - Text for "Accept All" button
+ * @property {string} rejectText - Text for "Reject All" button
+ * @property {string} settingsText - Text for "Manage Settings" button
+ * @property {Category[]} categories - List of cookie categories
+ * @property {string} storageKey - Key used to store preferences
+ * @property {(preferences: Object) => void} onSave - Callback when preferences are saved
+ * @property {number} [animationDuration=400] - Animation duration in ms
+ * @property {((config: Config) => string)|null} [renderBar] - Optional custom HTML renderer for consent bar
+ * @property {((config: Config) => string)|null} [renderModal] - Optional custom HTML renderer for modal
+ */
+
+/**
+ * CookieConsent
+ *
+ * A flexible and customizable cookie consent manager.
+ * Features:
+ * - Displays a consent bar with customizable text and buttons.
+ * - Allows defining multiple cookie categories (required, analytics, ads, etc.).
+ * - Stores user preferences in localStorage.
+ * - Provides callbacks for when user accepts or denies categories.
+ * - Fully customizable via configuration.
+ */
+class TinyCookieConsent {
+  /** @type {Record<string, boolean>} */
+  #preferences;
+
+  /** @type {Config} */
+  #config = {
+    message: 'We use cookies to improve your experience.',
+    acceptText: 'Accept All',
+    rejectText: 'Reject All',
+    settingsText: 'Manage Settings',
+    categories: [],
+    storageKey: 'cookie-consent-preferences',
+    onSave: (prefs) => console.log('Preferences saved:', prefs),
+    animationDuration: 400,
+    renderBar: null,
+    renderModal: null,
+  };
+
+  /** @type {Record<string, boolean>} */
+  get preferences() {
+    const saved = localStorage.getItem(this.#config.storageKey);
+    return saved ? JSON.parse(saved) : {};
+  }
+
+  /** @type {Config} */
+  get config() {
+    return { ...this.#config, categories: [...this.#config.categories] };
+  }
+
+  /** @param {Config} value */
+  set config(value) {
+    this.validateConfig(value);
+    this.#config = Object.assign(this.#config, value);
+  }
+
+  /**
+   * @param {Config} config
+   */
+  constructor(config) {
+    if (!config || typeof config !== 'object') throw new TypeError('Config must be an object.');
+    this.config = config;
+    const prefs = this.loadPreferences();
+    this.#preferences = prefs ?? {};
+    if (!prefs) this.showConsentBar();
+  }
+
+  /**
+   * Validates config object against jsDoc typedefs
+   * @param {Partial<Config>} config
+   */
+  validateConfig(config) {
+    if (typeof config.message !== 'undefined' && typeof config.message !== 'string')
+      throw new TypeError('Config.message must be a string.');
+
+    ['acceptText', 'rejectText', 'settingsText', 'storageKey'].forEach((key) => {
+      // @ts-ignore
+      if (typeof config[key] !== 'undefined' && typeof config[key] !== 'string') {
+        throw new TypeError(`Config.${key} must be a string.`);
+      }
+    });
+
+    if (typeof config.categories !== 'undefined') {
+      if (!Array.isArray(config.categories)) {
+        throw new TypeError('Config.categories must be an array of Category objects.');
+      }
+      config.categories.forEach((cat, i) => this.validateCategory(cat, i));
+    }
+
+    if (typeof config.onSave !== 'undefined' && typeof config.onSave !== 'function')
+      throw new TypeError('Config.onSave must be a function.');
+
+    if (typeof config.animationDuration !== 'undefined') {
+      if (typeof config.animationDuration !== 'number' || config.animationDuration < 0) {
+        throw new TypeError('Config.animationDuration must be a positive number.');
+      }
+    }
+
+    if (
+      typeof config.renderBar !== 'undefined' &&
+      config.renderBar !== null &&
+      typeof config.renderBar !== 'function'
+    )
+      throw new TypeError('Config.renderBar must be a function or null.');
+
+    if (
+      typeof config.renderModal !== 'undefined' &&
+      config.renderModal !== null &&
+      typeof config.renderModal !== 'function'
+    )
+      throw new TypeError('Config.renderModal must be a function or null.');
+  }
+
+  /**
+   * Validates a single category object
+   * @param {Category} cat
+   * @param {number} index
+   */
+  validateCategory(cat, index) {
+    if (!cat || typeof cat !== 'object')
+      throw new TypeError(`Category at index ${index} must be an object.`);
+    if (typeof cat.label !== 'string')
+      throw new TypeError(`Category.label at index ${index} must be a string.`);
+    if (typeof cat.required !== 'boolean')
+      throw new TypeError(`Category.required at index ${index} must be a boolean.`);
+    if (typeof cat.default !== 'boolean')
+      throw new TypeError(`Category.default at index ${index} must be a boolean.`);
+  }
+
+  /**
+   * Loads saved preferences from localStorage
+   * @returns {Record<string, boolean>|null}
+   */
+  loadPreferences() {
+    const saved = localStorage.getItem(this.#config.storageKey);
+    return saved ? JSON.parse(saved) : null;
+  }
+
+  /**
+   * Smoothly removes an element with fade-out/slide-out animation
+   * @param {HTMLElement} el
+   */
+  removeWithAnimation(el) {
+    if (!(el instanceof HTMLElement))
+      throw new TypeError('removeWithAnimation expects an HTMLElement.');
+    el.classList.add('closing');
+    setTimeout(() => el.remove(), this.#config.animationDuration);
+  }
+
+  /**
+   * Saves preferences to localStorage
+   *
+   * @param {Record<string, boolean>} prefs
+   */
+  savePreferences(prefs) {
+    if (!prefs || typeof prefs !== 'object') throw new TypeError('Preferences must be an object.');
+    localStorage.setItem(this.#config.storageKey, JSON.stringify(prefs));
+    this.#config.onSave(prefs);
+  }
+
+  /** Shows the initial consent bar */
+  showConsentBar() {
+    const bar = document.createElement('div');
+    bar.className = 'cookie-consent-bar';
+    bar.innerHTML = this.#config.renderBar
+      ? this.#config.renderBar(this.#config)
+      : `
+      <div><p>${this.#config.message}</p></div>
+      <div><button class="accept">${this.#config.acceptText}</button></div>
+      <div><button class="reject">${this.#config.rejectText}</button></div>
+      <div><button class="settings">${this.#config.settingsText}</button></div>
+    `;
+
+    document.body.appendChild(bar);
+
+    const accept = bar.querySelector('.accept');
+    if (accept instanceof HTMLElement) {
+      accept.onclick = () => {
+        /** @type {Record<string, boolean>} */
+        const prefs = {};
+        this.#config.categories.forEach((cat) => (prefs[cat.label] = true));
+        this.savePreferences(prefs);
+        this.removeWithAnimation(bar);
+      };
+    }
+
+    const reject = bar.querySelector('.reject');
+    if (reject instanceof HTMLElement) {
+      reject.onclick = () => {
+        /** @type {Record<string, boolean>} */
+        const prefs = {};
+        this.#config.categories.forEach((cat) => (prefs[cat.label] = cat.required));
+        this.savePreferences(prefs);
+        this.removeWithAnimation(bar);
+      };
+    }
+
+    const settings = bar.querySelector('.settings');
+    if (settings instanceof HTMLElement) {
+      settings.onclick = () => this.showSettingsModal(bar);
+    }
+  }
+
+  /**
+   * Shows settings modal for fine-grained control
+   *
+   * @param {HTMLElement} bar
+   */
+  showSettingsModal(bar) {
+    const modal = document.createElement('div');
+    modal.className = 'cookie-consent-modal';
+    modal.innerHTML = this.#config.renderModal
+      ? this.#config.renderModal(this.#config)
+      : `
+      <div class="modal-content">
+        <h2>Cookie Settings</h2>
+        <form class="settings-form">
+          ${this.#config.categories
+            .map(
+              (cat) => `
+            <label>
+              <input type="checkbox" name="${cat.label}" 
+                ${cat.default ? 'checked' : ''} 
+                ${cat.required ? 'disabled' : ''}>
+              ${cat.label}
+            </label>
+          `,
+            )
+            .join('')}
+        </form>
+        <button class="save">Save Preferences</button>
+      </div>
+    `;
+
+    document.body.appendChild(modal);
+
+    const save = modal.querySelector('.save');
+    if (save instanceof HTMLElement) {
+      save.onclick = () => {
+        /** @type {Record<string, boolean>} */
+        const prefs = {};
+        modal.querySelectorAll('input[type=checkbox]').forEach((input) => {
+          if (input instanceof HTMLInputElement) prefs[input.name] = input.checked;
+        });
+        this.savePreferences(prefs);
+        this.removeWithAnimation(modal);
+        if (bar) this.removeWithAnimation(bar);
+      };
+    }
+  }
+
+  /**
+   * Checks if a category is allowed
+   * @param {string} category
+   * @returns {boolean}
+   */
+  isAllowed(category) {
+    if (typeof category !== 'string')
+      throw new TypeError('isAllowed expects a string as category.');
+    if (!this.#preferences) return false;
+    return !!this.#preferences[category];
+  }
+}
+
+module.exports = TinyCookieConsent;