tiny-essentials 1.13.1 β†’ 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/dist/v1/TinyBasicsEs.js +256 -15
  2. package/dist/v1/TinyBasicsEs.min.js +1 -1
  3. package/dist/v1/TinyDragger.js +210 -15
  4. package/dist/v1/TinyEssentials.js +496 -15
  5. package/dist/v1/TinyEssentials.min.js +1 -1
  6. package/dist/v1/TinyNotifications.js +408 -0
  7. package/dist/v1/TinyNotifications.min.js +1 -0
  8. package/dist/v1/TinyUploadClicker.js +211 -15
  9. package/dist/v1/basics/html.cjs +213 -15
  10. package/dist/v1/basics/html.d.mts +59 -5
  11. package/dist/v1/basics/html.mjs +192 -13
  12. package/dist/v1/basics/index.cjs +4 -0
  13. package/dist/v1/basics/index.d.mts +5 -1
  14. package/dist/v1/basics/index.mjs +3 -3
  15. package/dist/v1/basics/text.cjs +43 -0
  16. package/dist/v1/basics/text.d.mts +16 -0
  17. package/dist/v1/basics/text.mjs +37 -0
  18. package/dist/v1/build/TinyNotifications.cjs +7 -0
  19. package/dist/v1/build/TinyNotifications.d.mts +3 -0
  20. package/dist/v1/build/TinyNotifications.mjs +2 -0
  21. package/dist/v1/index.cjs +6 -0
  22. package/dist/v1/index.d.mts +6 -1
  23. package/dist/v1/index.mjs +4 -3
  24. package/dist/v1/libs/TinyNotifications.cjs +238 -0
  25. package/dist/v1/libs/TinyNotifications.d.mts +106 -0
  26. package/dist/v1/libs/TinyNotifications.mjs +211 -0
  27. package/docs/v1/README.md +4 -3
  28. package/docs/v1/basics/array.md +16 -43
  29. package/docs/v1/basics/html.md +199 -33
  30. package/docs/v1/basics/text.md +44 -14
  31. package/docs/v1/libs/TinyNotifications.md +189 -0
  32. package/package.json +1 -1
package/docs/v1/basics/text.md CHANGED
@@ -43,32 +43,24 @@ toTitleCaseLowerFirst('hello world'); // β†’ "hello World"
43
43
 
44
44
  Enables a keyboard shortcut (`Ctrl + Alt + [key]`) that toggles a CSS class on the `<body>` element. Useful for marking or highlighting AI-generated content dynamically.
45
45
 
46
- ---
47
-
48
46
  ### πŸ”€ Syntax
49
47
 
50
48
  ```js
51
49
  addAiMarkerShortcut(key)
52
50
  ```
53
51
 
54
- ---
55
-
56
52
  ### 🧾 Parameters
57
53
 
58
54
  | Name | Type | Default | Description |
59
55
  | ----- | -------- | ------- | ---------------------------------------------------------------------------- |
60
56
  | `key` | `string` | `'a'` | The character key to use in combination with `Ctrl + Alt`. Case-insensitive. |
61
57
 
62
- ---
63
-
64
58
  ### βš™οΈ Behavior
65
59
 
66
60
  * ⌨️ When the user presses `Ctrl + Alt + [key]`, the function toggles the CSS class `detect-made-by-ai` on the `<body>` element.
67
61
  * 🧠 The shortcut only works in environments where the DOM is available (e.g., browsers).
68
62
  * 🚫 If `document.body` is not available when the shortcut is used (e.g., if the DOM hasn't finished loading), a warning is logged and nothing happens.
69
63
 
70
- ---
71
-
72
64
  ### ❗ Error Handling
73
65
 
74
66
  Two types of errors are handled:
@@ -85,8 +77,6 @@ Two types of errors are handled:
85
77
  [AiMarkerShortcut] <body> element not found. Cannot toggle class. Ensure the DOM is fully loaded when using the shortcut.
86
78
  ```
87
79
 
88
- ---
89
-
90
80
  ### πŸ§ͺ Example
91
81
 
92
82
  ```js
@@ -94,8 +84,6 @@ addAiMarkerShortcut(); // Uses default key 'a'
94
84
  // Pressing Ctrl + Alt + A toggles the class "detect-made-by-ai" on <body>
95
85
  ```
96
86
 
97
- ---
98
-
99
87
  ### 🎨 CSS Integration Example
100
88
 
101
89
  Define the class in your stylesheet to make the toggle visually meaningful:
@@ -107,8 +95,6 @@ body.detect-made-by-ai .ai-content {
107
95
  }
108
96
  ```
109
97
 
110
- ---
111
-
112
98
  ### πŸ’‘ Tip
113
99
 
114
100
  To avoid the `<body>` warning, make sure you only call the function after the DOM is ready:
@@ -127,3 +113,47 @@ You can use a pre-built CSS template for the `detect-made-by-ai` class, availabl
127
113
  * `/dist/v1/css/aiMarker.css` – The non-minified version for easier readability and customization.
128
114
 
129
115
  Simply include the appropriate file in your project to style the elements marked with the `detect-made-by-ai` class.
116
+
117
+ ---
118
+
119
+ ## 🎯 `safeTextTrim(text, limit, safeCutZone = 0.6)`
120
+
121
+ Trims a text string to a specified character limit, attempting to avoid cutting words in half. If a space is found before the limit and it’s not too far from the limit (at least a fraction controlled by `safeCutZone`), the cut is made at that space; otherwise, the text is hard-cut at the limit. If the input text is shorter than or equal to the limit, it is returned unchanged.
122
+
123
+ ### πŸ”€ Syntax
124
+
125
+ ```js
126
+ safeTextTrim(text, limit, safeCutZone = 0.6)
127
+ ```
128
+
129
+ ### 🧾 Parameters
130
+
131
+ | Name | Type | Default | Description |
132
+ | ------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
133
+ | `text` | `string` | β€” | The input text to be trimmed. Must be a string. |
134
+ | `limit` | `number` | β€” | The maximum number of characters allowed. Must be a positive integer. |
135
+ | `safeCutZone` | `number` | `0.6` | A decimal between 0 and 1 representing the minimal acceptable position (fraction of `limit`) to cut at a space. |
136
+
137
+ ### βš™οΈ Behavior
138
+
139
+ * If `text` length is less than or equal to `limit`, returns `text` unchanged.
140
+ * Attempts to cut at the last space character before `limit` but only if it’s within the `safeCutZone` (e.g., at least 60% of the `limit`).
141
+ * If no suitable space is found within the zone, the text is cut strictly at the `limit`.
142
+ * The resulting trimmed text ends with an ellipsis (`"..."`) if it was cut.
143
+ * Leading and trailing whitespace on input is trimmed before processing.
144
+
145
+ ### ❗ Error Handling
146
+
147
+ Throws a `TypeError` in these cases:
148
+
149
+ * If `text` is not a string.
150
+ * If `limit` is not a positive integer.
151
+ * If `safeCutZone` is not a number between 0 and 1 (inclusive).
152
+
153
+ ### πŸ§ͺ Example
154
+
155
+ ```js
156
+ const longText = "This is a sample sentence that will be trimmed properly.";
157
+ console.log(safeTextTrim(longText, 30));
158
+ // Output: "This is a sample sentence that..."
159
+ ```
package/docs/v1/libs/TinyNotifications.md ADDED
@@ -0,0 +1,189 @@
1
+ # πŸ“£ TinyNotifications
2
+
3
+ > A utility class to manage browser notifications with sound, custom icons, text truncation, and click behavior.
4
+
5
+ ---
6
+
7
+ ## πŸš€ Features
8
+
9
+ * βœ… Request and manage user permission for notifications
10
+ * πŸ”” Play a sound when a notification is shown
11
+ * πŸ–ΌοΈ Support for default avatar/icon
12
+ * βœ‚οΈ Automatic body text truncation
13
+ * πŸ’₯ Strong validation with `TypeError` and runtime checks
14
+ * ❗ Prevents use of `send()` before permission request
15
+
16
+ ---
17
+
18
+ ## πŸ—οΈ Constructor
19
+
20
+ ```js
21
+ new TinyNotifications(options?)
22
+ ```
23
+
24
+ ### Parameters
25
+
26
+ | Name | Type | Default | Description |
27
+ | ---------------- | ----------------------------------------- | ------- | -------------------------------------------------- |
28
+ | `audio` | `string` \| `HTMLAudioElement` \| `null` | `null` | Sound to be played with the notification |
29
+ | `defaultIcon` | `string` \| `null` | `null` | Default icon to use in notifications |
30
+ | `bodyLimit` | `number` | `100` | Maximum number of characters in body text |
31
+ | `defaultOnClick` | `(this: Notification, evt: Event) => any` | `fn` | Function executed when the notification is clicked |
32
+
33
+ ### Throws
34
+
35
+ * `TypeError` if any parameter is of invalid type.
36
+
37
+ ---
38
+
39
+ ## 🧠 Methods
40
+
41
+ ### πŸ” `requestPerm()`
42
+
43
+ ```js
44
+ requestPerm(): Promise<boolean>
45
+ ```
46
+
47
+ Requests permission from the browser to send notifications.
48
+
49
+ * Sets internal `#allowed` and `#permissionRequested` flags.
50
+ * Must be called before using `send()`.
51
+
52
+ **Returns:** `Promise<boolean>` β€” `true` if permission was granted.
53
+
54
+ ---
55
+
56
+ ### βš™οΈ `isCompatible()`
57
+
58
+ ```js
59
+ isCompatible(): boolean
60
+ ```
61
+
62
+ Checks if the current browser supports the Notification API.
63
+
64
+ **Returns:** `true` or `false`
65
+
66
+ ---
67
+
68
+ ### πŸ“€ `send(title, config?)`
69
+
70
+ ```js
71
+ send(title: string, config?: NotificationOptions): Notification | null
72
+ ```
73
+
74
+ Sends a notification to the user with optional configuration.
75
+ Truncates long body texts and plays a sound if set.
76
+
77
+ #### Parameters
78
+
79
+ * `title`: *(string)* β€” Title of the notification
80
+ * `config`: *(object)* β€” Optional notification settings (`body`, `icon`, `vibrate`, etc.)
81
+
82
+ #### Throws
83
+
84
+ * `Error` if `requestPerm()` was never called
85
+ * `TypeError` if `title` is not a string or `config` is not an object
86
+
87
+ #### Returns
88
+
89
+ * `Notification` instance if allowed
90
+ * `null` if permission was denied
91
+
92
+ ---
93
+
94
+ ## πŸ“₯ Getters & Setters
95
+
96
+ ### πŸ“Œ `wasPermissionRequested()`
97
+
98
+ ```js
99
+ wasPermissionRequested(): boolean
100
+ ```
101
+
102
+ Checks if `requestPerm()` was called.
103
+
104
+ ---
105
+
106
+ ### 🟒 `isAllowed()`
107
+
108
+ ```js
109
+ isAllowed(): boolean
110
+ ```
111
+
112
+ Checks if permission has been granted.
113
+
114
+ ---
115
+
116
+ ### πŸ”Š `getAudio()` / `setAudio(value)`
117
+
118
+ ```js
119
+ getAudio(): HTMLAudioElement | null
120
+ setAudio(value: HTMLAudioElement | string | null)
121
+ ```
122
+
123
+ Set or retrieve the notification sound.
124
+ **Throws:** `TypeError` if invalid type is used.
125
+
126
+ ---
127
+
128
+ ### πŸ“ `getBodyLimit()` / `setBodyLimit(value)`
129
+
130
+ ```js
131
+ getBodyLimit(): number
132
+ setBodyLimit(value: number)
133
+ ```
134
+
135
+ Set or retrieve the maximum number of characters in the notification body.
136
+ **Throws:** `TypeError` if value is not a non-negative number.
137
+
138
+ ---
139
+
140
+ ### πŸ–ΌοΈ `getDefaultAvatar()` / `setDefaultAvatar(value)`
141
+
142
+ ```js
143
+ getDefaultAvatar(): string | null
144
+ setDefaultAvatar(value: string | null)
145
+ ```
146
+
147
+ Get or set the default icon for notifications.
148
+ **Throws:** `TypeError` if value is not a string or `null`.
149
+
150
+ ---
151
+
152
+ ### πŸ–±οΈ `getDefaultOnClick()` / `setDefaultOnClick(value)`
153
+
154
+ ```js
155
+ getDefaultOnClick(): (this: Notification, evt: Event) => any
156
+ setDefaultOnClick(value: function)
157
+ ```
158
+
159
+ Set or retrieve the default click handler for all notifications.
160
+ **Throws:** `TypeError` if value is not a function.
161
+
162
+ ---
163
+
164
+ ## πŸ“¦ Example
165
+
166
+ ```js
167
+ import TinyNotifications from './TinyNotifications.js';
168
+
169
+ const notify = new TinyNotifications({
170
+ audio: '/sounds/ping.mp3',
171
+ defaultIcon: '/img/icon.png',
172
+ bodyLimit: 80
173
+ });
174
+
175
+ await notify.requestPerm();
176
+
177
+ notify.send('Hello World!', {
178
+ body: 'This message will be truncated if too long.',
179
+ vibrate: [100, 50, 100]
180
+ });
181
+ ```
182
+
183
+ ---
184
+
185
+ ## πŸ§ͺ Safety Notes
186
+
187
+ * Always call `requestPerm()` **before** using `send()`
188
+ * Invalid or unsafe inputs throw strong errors
189
+ * Compatible with all modern browsers that support `Notification` API
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tiny-essentials",
3
- "version": "1.13.1",
3
+ "version": "1.14.0",
4
4
  "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
5
5
  "scripts": {
6
6
  "test": "npm run test:mjs && npm run test:cjs && npm run test:js",