tiny-essentials 1.20.3 → 1.21.0

package/docs/v1/libs/TinyArrayPaginator.md

@@ -0,0 +1,150 @@
+# 📚 TinyArrayPaginator
+
+A small but powerful utility for **paginating arrays or sets** 🔄.
+It allows you to filter data using **objects**, **functions**, or **regular expressions**, and retrieve paginated results along with useful metadata.
+
+---
+
+## 🔍 GetFilter — Predicate Function
+
+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`.
+
+```js
+/**
+ * @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}   - `true` to include the element, `false` to exclude it.
+ */
+```
+
+---
+
+## 🛠 Class: `TinyArrayPaginator`
+
+### ✨ Features
+
+* **Immutable source safety** — The original array/set is never modified.
+* **Flexible filtering** — Supports:
+
+  * Object key-value filters
+  * Custom filter functions
+  * RegExp matching
+* **Pagination metadata** — Returns total items, total pages, and navigation info.
+
+---
+
+### 🏗 Constructor
+
+```js
+new TinyArrayPaginator(data)
+```
+
+**Parameters:**
+
+* `data` (`any[] | Set<any>`) — The data source to paginate.
+
+**Throws:**
+
+* `TypeError` if `data` is not an array or set.
+
+---
+
+### 📥 `.data` (Getter)
+
+Gets the current stored array/set.
+
+**Returns:**
+`any[] | Set<any>`
+
+---
+
+### 📤 `.data` (Setter)
+
+Replaces the current data source.
+
+**Parameters:**
+
+* `value` (`any[] | Set<any>`) — The new data source.
+
+**Throws:**
+
+* `TypeError` if the value is not an array or set.
+
+---
+
+### 📏 `.size`
+
+Gets the total number of items in the current data source.
+
+**Returns:**
+`number`
+
+---
+
+### 📄 `.get({ page, perPage, filter })`
+
+Filters and paginates the stored data.
+
+**Parameters:**
+
+* `page` (`number`) — The page number (1-based).
+* `perPage` (`number`) — Number of items per page.
+* `filter` (`Record<string, any> | GetFilter`, optional) — Filtering criteria:
+
+  * **Object** — Key-value pairs for exact match, substring match, or RegExp.
+  * **RegExp** values in the object are matched using `.test()`.
+
+**Returns:**
+
+```ts
+{
+  items: any[],       // Items for the current page
+  page: number,       // Current page number (validated)
+  perPage: number,    // Items per page
+  totalItems: number, // Total filtered items
+  totalPages: number, // Total available pages
+  hasPrev: boolean,   // True if a previous page exists
+  hasNext: boolean    // True if a next page exists
+}
+```
+
+**Throws:**
+
+* `RangeError` if `page` or `perPage` is not a positive integer.
+* `TypeError` if `filter` is neither an object nor a function.
+
+---
+
+### 📌 Example Usage
+
+```js
+import TinyArrayPaginator from './TinyArrayPaginator.js';
+
+const paginator = new TinyArrayPaginator([
+  { id: 1, category: 'fruit' },
+  { id: 2, category: 'vegetable' },
+  { id: 3, category: 'fruit' },
+  { id: 4, category: 'grain' }
+]);
+
+// Example: Filter only fruits and get the first page
+const result = paginator.get({
+  page: 1,
+  perPage: 2,
+  filter: { category: 'fruit' }
+});
+
+console.log(result);
+// {
+//   items: [{ id: 1, category: 'fruit' }, { id: 3, category: 'fruit' }],
+//   page: 1,
+//   perPage: 2,
+//   totalItems: 2,
+//   totalPages: 1,
+//   hasPrev: false,
+//   hasNext: false
+// }
+```

package/docs/v1/libs/TinyCookieConsent.md

@@ -0,0 +1,152 @@
+# 🍪 TinyCookieConsent
+
+A flexible and customizable **cookie consent manager** for the web.
+It displays a consent bar, lets users manage categories, and stores preferences in `localStorage`.
+
+---
+
+## ✨ Features
+
+* 📊 Displays a **consent bar** with customizable text and buttons
+* 🗂️ Supports **multiple categories** (required, analytics, ads, etc.)
+* 💾 Stores preferences in **localStorage**
+* 🔔 Provides **callbacks** when preferences are saved
+* 🎨 Fully customizable with **custom renderers**
+* 🎬 Smooth **animations** for showing/hiding elements
+
+---
+
+## 📦 Typedefs
+
+### 🗂️ `Category`
+
+| Property   | Type      | Description                                          |
+| ---------- | --------- | ---------------------------------------------------- |
+| `label`    | `string`  | Category label displayed to the user                 |
+| `required` | `boolean` | If `true`, category cannot be disabled               |
+| `default`  | `boolean` | Default state (`true = enabled`, `false = disabled`) |
+
+---
+
+### ⚙️ `Config`
+
+| Property            | Type                                   | Description                                     |
+| ------------------- | -------------------------------------- | ----------------------------------------------- |
+| `message`           | `string`                               | Consent message shown in the bar                |
+| `acceptText`        | `string`                               | Text for the **"Accept All"** button            |
+| `rejectText`        | `string`                               | Text for the **"Reject All"** button            |
+| `settingsText`      | `string`                               | Text for the **"Manage Settings"** button       |
+| `categories`        | `Category[]`                           | List of cookie categories                       |
+| `storageKey`        | `string`                               | Key used in `localStorage`                      |
+| `onSave`            | `(preferences: Object) => void`        | Callback fired when preferences are saved       |
+| `animationDuration` | `number` (default: `400`)              | Animation duration in milliseconds              |
+| `renderBar`         | `((config: Config) => string) \| null` | Optional custom HTML renderer for the **bar**   |
+| `renderModal`       | `((config: Config) => string) \| null` | Optional custom HTML renderer for the **modal** |
+
+---
+
+## 🏗️ Class: `TinyCookieConsent`
+
+### 🔑 Constructor
+
+```js
+new TinyCookieConsent(config: Config)
+```
+
+* Creates a new cookie consent manager instance.
+* Automatically loads stored preferences, or shows the consent bar if none are saved.
+
+Throws:
+
+* `TypeError` if `config` is not a valid object.
+
+---
+
+### 📖 Properties
+
+| Property      | Type                      | Description                                        |
+| ------------- | ------------------------- | -------------------------------------------------- |
+| `preferences` | `Record<string, boolean>` | Returns stored preferences (or `{}` if none exist) |
+| `config`      | `Config`                  | Returns the current configuration                  |
+
+---
+
+### 🛠️ Methods
+
+#### 🔍 `validateConfig(config: Partial<Config>): void`
+
+Validates a config object.
+Throws `TypeError` if any field is invalid.
+
+---
+
+#### 🗂️ `validateCategory(cat: Category, index: number): void`
+
+Ensures a category object is valid.
+Throws if fields are missing or of the wrong type.
+
+---
+
+#### 💾 `loadPreferences(): Record<string, boolean> \| null`
+
+Loads preferences from `localStorage`.
+Returns `null` if no preferences are saved.
+
+---
+
+#### 🎬 `removeWithAnimation(el: HTMLElement): void`
+
+Removes an element with a fade/slide animation.
+Uses `config.animationDuration`.
+
+---
+
+#### 💾 `savePreferences(prefs: Record<string, boolean>): void`
+
+Saves preferences to `localStorage` and fires the `onSave` callback.
+
+---
+
+#### 📊 `showConsentBar(): void`
+
+Displays the initial **consent bar**.
+Includes buttons:
+
+* ✅ Accept All
+* ❌ Reject All
+* ⚙️ Manage Settings
+
+---
+
+#### ⚙️ `showSettingsModal(bar: HTMLElement): void`
+
+Displays a modal for fine-grained category control.
+Allows toggling each category, then saving preferences.
+
+---
+
+#### 🔎 `isAllowed(category: string): boolean`
+
+Checks whether a given category is enabled.
+Returns `false` if preferences are missing or category is not allowed.
+
+---
+
+## 🧩 Example Usage
+
+```js
+import TinyCookieConsent from './TinyCookieConsent.mjs';
+
+const consent = new TinyCookieConsent({
+  message: "We use cookies to personalize your experience.",
+  acceptText: "Accept All",
+  rejectText: "Reject All",
+  settingsText: "Cookie Settings",
+  categories: [
+    { label: "Essential", required: true, default: true },
+    { label: "Analytics", required: false, default: false },
+    { label: "Ads", required: false, default: false }
+  ],
+  onSave: (prefs) => console.log("Saved preferences:", prefs),
+});
+```