@jackens/nnn 2025.9.3 → 2025.9.4

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 (3) hide show
  1. package/nnn.d.ts +53 -47
  2. package/package.json +1 -1
  3. package/readme.md +78 -72
package/nnn.d.ts CHANGED
@@ -1,63 +1,66 @@
1
1
  /**
2
- * The type of arguments of the `c` helper.
2
+ * Argument type for the `c` helper.
3
3
  */
4
4
  export type C_Node = {
5
5
  [attribute_or_selector: string]: string | number | C_Node | undefined;
6
6
  };
7
7
  /**
8
- * The type of arguments of the `c` helper.
8
+ * Argument type for the `c` helper.
9
9
  */
10
10
  export type C_Root = Record<PropertyKey, C_Node>;
11
11
  /**
12
- * A simple JS-to-CSS (aka CSS-in-JS) helper.
12
+ * A minimal JS-to-CSS (CSS‑in‑JS) helper.
13
13
  *
14
- * The `root` parameter provides a hierarchical description of CSS rules.
14
+ * The `root` object describes a hierarchy of CSS rules.
15
15
  *
16
- * - Keys of sub-objects whose values are NOT objects are treated as CSS attribute, and values are treated as values of those CSS attributes; the concatenation of keys of all parent objects is a CSS rule.
17
- * - All keys ignore the part starting with a splitter (default: `$$`) sign until the end of the key (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
18
- * - In keys specifying CSS attribute, all uppercase letters are replaced by lowercase letters with an additional `-` character preceding them (e.g. `fontFamily` → `font-family`), while all `_` characters are replaced by `-` character (e.g. `font_family` → `font-family`).
19
- * - Commas in keys that makes a CSS rule cause it to “split” and create separate rules for each part (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
20
- * - Top-level keys that begin with `@` are not concatenated with sub-object keys.
16
+ * - Keys whose values are not objects are treated as CSS property names; their values become property values. The concatenation of parent keys produces a selector.
17
+ * - For every key, the substring starting with the splitter (default: `$$`) to the end is ignored (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
18
+ * - In property keys, uppercase letters are converted to lowercase and prefixed with `-` (e.g. `fontFamily` → `font-family`); underscores are converted to `-` (e.g. `font_family` → `font-family`).
19
+ * - Commas inside selector keys cause them to expand into multiple selectors (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
20
+ * - Top-level keys beginning with `@` (at-rules) are not concatenated with parent keys.
21
21
  */
22
22
  export declare const c: (root: C_Root, splitter?: string) => string;
23
23
  /**
24
- * A tiny helper for parsing CSV.
24
+ * A tiny CSV parsing helper.
25
25
  */
26
26
  export declare const csv_parse: (csv: string, separator?: string) => string[][];
27
27
  /**
28
- * The type of arguments of the `escape_values` and `escape` helpers.
28
+ * Argument type accepted by the `escape_values` and `escape` helpers.
29
29
  */
30
30
  export type Escape_Map = Map<unknown, (value?: unknown) => string>;
31
31
  /**
32
- * A generic helper for escaping `values` by given `escape_map`.
32
+ * Escapes array `values` using the provided `escape_map`.
33
33
  */
34
34
  export declare const escape_values: (escape_map: Escape_Map, values: unknown[]) => string[];
35
35
  /**
36
- * A generic helper for escaping `values` by given `escape_map` (in *TemplateStrings* flavor).
36
+ * Escapes interpolated template `values` using the provided `escape_map`.
37
37
  */
38
38
  export declare const escape: (escape_map: Escape_Map, template: TemplateStringsArray, ...values: unknown[]) => string;
39
39
  /**
40
- * A helper that implements typographic corrections specific to Polish typography.
40
+ * Applies Polish‑specific typographic corrections.
41
41
  */
42
42
  export declare const fix_typography: (node: Node) => void;
43
43
  /**
44
- * The type of arguments of the `h` and `s` helpers.
44
+ * Argument type for the `h` and `s` helpers.
45
45
  */
46
46
  export type H_Args_1 = Record<PropertyKey, unknown> | null | undefined | Node | string | number | H_Args;
47
47
  /**
48
- * The type of arguments of the `h` and `s` helpers.
48
+ * Argument type for the `h` and `s` helpers.
49
49
  */
50
50
  export type H_Args = [string | Node, ...H_Args_1[]];
51
51
  /**
52
52
  * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
53
53
  *
54
- * - The first argument of type `string` specifies the tag of the element to be created.
55
- * - The first argument of type `Node` specifies the element to be modified.
56
- * - All other arguments of type `Record<PropertyKey, unknown>` are mappings of attributes and properties. Keys starting with `$` specify *properties* (without the leading `$`) to be set on the element being created or modified. (Note that `$` is not a valid attribute name character.) All other keys specify *attributes* to be set by `setAttribute`. An attribute equal to `false` causes the attribute to be removed by `removeAttribute`.
57
- * - All other arguments of type `null` or `undefined` are simply ignored.
58
- * - All other arguments of type `Node` are appended to the element being created or modified.
59
- * - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
60
- * - All other arguments of type `HArgs` are passed to `h` and the results are appended to the element being created or modified.
54
+ * - If the first argument is a `string`, it is treated as the tag name to create.
55
+ * - If the first argument is a `Node`, that node is modified.
56
+ * - Object arguments map attributes/properties:
57
+ * - Keys starting with `$` set element properties (without `$`).
58
+ * - Other keys set attributes via `setAttribute`.
59
+ * - Attributes with value `false` are removed via `removeAttribute`.
60
+ * - `null` / `undefined` are ignored.
61
+ * - `Node` arguments are appended.
62
+ * - `string` / `number` arguments become `Text` nodes.
63
+ * - `H_Args` arrays are processed recursively.
61
64
  */
62
65
  export declare const h: {
63
66
  <T extends keyof HTMLElementTagNameMap>(tag: T, ...args1: H_Args_1[]): HTMLElementTagNameMap[T];
@@ -67,13 +70,16 @@ export declare const h: {
67
70
  /**
68
71
  * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
69
72
  *
70
- * - The first argument of type `string` specifies the tag of the element to be created.
71
- * - The first argument of type `Node` specifies the element to be modified.
72
- * - All other arguments of type `Record<PropertyKey, unknown>` are mappings of attributes and properties. Keys starting with `$` specify *properties* (without the leading `$`) to be set on the element being created or modified. (Note that `$` is not a valid attribute name character.) All other keys specify *attributes* to be set by `setAttributeNS`. An attribute equal to `false` causes the attribute to be removed by `removeAttributeNS`.
73
- * - All other arguments of type `null` or `undefined` are simply ignored.
74
- * - All other arguments of type `Node` are appended to the element being created or modified.
75
- * - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
76
- * - All other arguments of type `HArgs` are passed to `s` and the results are appended to the element being created or modified.
73
+ * - If the first argument is a `string`, it is treated as the tag name to create.
74
+ * - If the first argument is a `Node`, that node is modified.
75
+ * - Object arguments map attributes/properties:
76
+ * - Keys starting with `$` set element properties (without `$`).
77
+ * - Other keys set attributes via `setAttributeNS`.
78
+ * - Attributes with value `false` are removed via `removeAttributeNS`.
79
+ * - `null` / `undefined` are ignored.
80
+ * - `Node` arguments are appended.
81
+ * - `string` / `number` arguments become `Text` nodes.
82
+ * - `H_Args` arrays are processed recursively.
77
83
  */
78
84
  export declare const s: {
79
85
  <T extends keyof SVGElementTagNameMap>(tag: T, ...args1: H_Args_1[]): SVGElementTagNameMap[T];
@@ -81,15 +87,15 @@ export declare const s: {
81
87
  (tag_or_node: string | Node, ...args1: H_Args_1[]): Node;
82
88
  };
83
89
  /**
84
- * A convenient shortcut for `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
90
+ * Shorthand for: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
85
91
  */
86
92
  export declare const svg_use: (id: string, ...args: H_Args_1[]) => SVGSVGElement;
87
93
  /**
88
- * A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
94
+ * A replacement to the `in` operator (not to be confused with `for-in`).
89
95
  */
90
96
  export declare const has_own: (ref: unknown, key: unknown) => boolean;
91
97
  /**
92
- * A helper that checks if the given argument is of type `any[]`.
98
+ * Checks whether the argument is an array.
93
99
  */
94
100
  export declare const is_array: (arg: any) => arg is any[];
95
101
  declare const FINITE_NUMBER: unique symbol;
@@ -97,32 +103,32 @@ type Finite_Number = number & {
97
103
  readonly [FINITE_NUMBER]: true;
98
104
  };
99
105
  /**
100
- * A helper that checks if the given argument is of type `number` but not `±Infinity` nor `NaN`.
106
+ * Checks whether the argument is a finite number (excluding `±Infinity` and `NaN`).
101
107
  */
102
108
  export declare const is_finite_number: ((arg: unknown) => arg is Finite_Number);
103
109
  /**
104
- * A helper that checks if the given argument is of type `number`.
110
+ * Checks whether the argument is a number.
105
111
  */
106
112
  export declare const is_number: (arg: unknown) => arg is number;
107
113
  /**
108
- * A helper that checks if the given argument is of type `Record<PropertyKey, unknown>`.
114
+ * Checks whether the argument is a plain object record.
109
115
  */
110
116
  export declare const is_record: (arg: unknown) => arg is Record<PropertyKey, unknown>;
111
117
  /**
112
- * A helper that checks if the given argument is of type `string`.
118
+ * Checks whether the argument is a string.
113
119
  */
114
120
  export declare const is_string: (arg: unknown) => arg is string;
115
121
  export {};
116
122
  /**
117
123
  * `JSON.parse` with “JavaScript turned on”.
118
124
  *
119
- * Objects having *exactly* one property which is present in the `handlers` map, i.e. objects of the form:
125
+ * Objects having *exactly* one property whose name exists in `handlers`, i.e.:
120
126
  *
121
127
  * ```js
122
128
  * { "«handler_name»": [«params»] }
123
129
  * ```
124
130
  *
125
- * are replaced by the result of call
131
+ * are replaced with:
126
132
  *
127
133
  * ```js
128
134
  * handlers['«handler_name»'](...«params»)
@@ -131,32 +137,32 @@ export {};
131
137
  export declare const js_on_parse: (handlers: Record<PropertyKey, Function>, text: string) => any;
132
138
  import type { H_Args_1 } from './h.js';
133
139
  /**
134
- * A generic helper for syntax highlighting (see also `nanolight_js`).
140
+ * Generic syntax highlighting helper (see also `nanolight_js`).
135
141
  */
136
142
  export declare const nanolight: (pattern: RegExp, highlighters: ((chunk: string, index: number) => H_Args_1)[], code: string) => H_Args_1[];
137
143
  /**
138
- * A helper for highlighting JavaScript (see also `nanolight`).
144
+ * JavaScript syntax highlighting helper (built on `nanolight`).
139
145
  */
140
146
  export declare const nanolight_js: (code: string) => H_Args_1[];
141
147
  /**
142
- * A helper that implements TypeScript’s `Pick` utility type (see also `omit`).
148
+ * Runtime implementation of TypeScript’s `Pick` (see also `omit`).
143
149
  */
144
150
  export declare const pick: <T, K extends keyof T>(ref: T, keys: K[]) => Pick<T, K>;
145
151
  /**
146
- * A helper that implements TypeScript’s `Omit` utility type (see also `pick`).
152
+ * Runtime implementation of TypeScript’s `Omit` (see also `pick`).
147
153
  */
148
154
  export declare const omit: <T, K extends keyof T>(ref: T, keys: unknown[]) => Omit<T, K>;
149
155
  /**
150
- * A helper for choosing the correct singular and plural.
156
+ * Chooses the appropriate Polish noun form based on a numeric value.
151
157
  */
152
158
  export declare const pl_ural: (singular: string, plural_2: string, plural_5: string, value: number) => string;
153
159
  /**
154
- * A helper that protects calls to nested properties by a `Proxy` that initializes non-existent values with an empty object.
160
+ * A `Proxy`-based helper that safely creates nested structures on access and allows deep assignment without guards.
155
161
  */
156
162
  export declare const pro: (ref: unknown) => any;
157
163
  /**
158
- * A helper that generates a UUID v1 identifier (with a creation timestamp).
164
+ * Generates a UUID v1 (time-based) identifier.
159
165
  *
160
- * - The optional `node` parameter should have the format `/^[0123456789abcdef]+$/`. Its value will be trimmed to last 12 characters and left padded with zeros.
166
+ * - Optional `node` must match `/^[0-9a-f]*$/`; it is trimmed to the last 12 characters and left-padded with zeros.
161
167
  */
162
168
  export declare const uuid_v1: (date?: Date, node?: string) => string;
package/package.json CHANGED
@@ -36,5 +36,5 @@
36
36
  "name": "@jackens/nnn",
37
37
  "type": "module",
38
38
  "types": "nnn.d.ts",
39
- "version": "2025.9.3"
39
+ "version": "2025.9.4"
40
40
  }
package/readme.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # nnn
2
2
 
3
- Jackens’ JavaScript helpers.
3
+ A collection of Jackens’ JavaScript helper utilities.
4
4
 
5
5
  ## Installation
6
6
 
@@ -28,33 +28,33 @@ import { «something» } from './node_modules/@jackens/nnn/nnn.js'
28
28
 
29
29
  ## Exports
30
30
 
31
- - `C_Node`: The type of arguments of the `c` helper.
32
- - `C_Root`: The type of arguments of the `c` helper.
33
- - `Escape_Map`: The type of arguments of the `escape_values` and `escape` helpers.
34
- - `H_Args`: The type of arguments of the `h` and `s` helpers.
35
- - `H_Args_1`: The type of arguments of the `h` and `s` helpers.
36
- - `c`: A simple JS-to-CSS (aka CSS-in-JS) helper.
37
- - `csv_parse`: A tiny helper for parsing CSV.
38
- - `escape`: A generic helper for escaping `values` by given `escape_map` (in *TemplateStrings* flavor).
39
- - `escape_values`: A generic helper for escaping `values` by given `escape_map`.
40
- - `fix_typography`: A helper that implements typographic corrections specific to Polish typography.
31
+ - `C_Node`: Argument type for the `c` helper.
32
+ - `C_Root`: Argument type for the `c` helper.
33
+ - `Escape_Map`: Argument type accepted by the `escape_values` and `escape` helpers.
34
+ - `H_Args`: Argument type for the `h` and `s` helpers.
35
+ - `H_Args_1`: Argument type for the `h` and `s` helpers.
36
+ - `c`: A minimal JS-to-CSS (CSS‑in‑JS) helper.
37
+ - `csv_parse`: A tiny CSV parsing helper.
38
+ - `escape`: Escapes interpolated template `values` using the provided `escape_map`.
39
+ - `escape_values`: Escapes array `values` using the provided `escape_map`.
40
+ - `fix_typography`: Applies Polish‑specific typographic corrections.
41
41
  - `h`: A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
42
- - `has_own`: A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
43
- - `is_array`: A helper that checks if the given argument is of type `any[]`.
44
- - `is_finite_number`: A helper that checks if the given argument is of type `number` but not `±Infinity` nor `NaN`.
45
- - `is_number`: A helper that checks if the given argument is of type `number`.
46
- - `is_record`: A helper that checks if the given argument is of type `Record<PropertyKey, unknown>`.
47
- - `is_string`: A helper that checks if the given argument is of type `string`.
42
+ - `has_own`: A replacement to the `in` operator (not to be confused with `for-in`).
43
+ - `is_array`: Checks whether the argument is an array.
44
+ - `is_finite_number`: Checks whether the argument is a finite number (excluding `±Infinity` and `NaN`).
45
+ - `is_number`: Checks whether the argument is a number.
46
+ - `is_record`: Checks whether the argument is a plain object record.
47
+ - `is_string`: Checks whether the argument is a string.
48
48
  - `js_on_parse`: `JSON.parse` with “JavaScript turned on”.
49
- - `nanolight`: A generic helper for syntax highlighting (see also `nanolight_js`).
50
- - `nanolight_js`: A helper for highlighting JavaScript (see also `nanolight`).
51
- - `omit`: A helper that implements TypeScript’s `Omit` utility type (see also `pick`).
52
- - `pick`: A helper that implements TypeScript’s `Pick` utility type (see also `omit`).
53
- - `pl_ural`: A helper for choosing the correct singular and plural.
54
- - `pro`: A helper that protects calls to nested properties by a `Proxy` that initializes non-existent values with an empty object.
49
+ - `nanolight`: Generic syntax highlighting helper (see also `nanolight_js`).
50
+ - `nanolight_js`: JavaScript syntax highlighting helper (built on `nanolight`).
51
+ - `omit`: Runtime implementation of TypeScript’s `Omit` (see also `pick`).
52
+ - `pick`: Runtime implementation of TypeScript’s `Pick` (see also `omit`).
53
+ - `pl_ural`: Chooses the appropriate Polish noun form based on a numeric value.
54
+ - `pro`: A `Proxy`-based helper that safely creates nested structures on access and allows deep assignment without guards.
55
55
  - `s`: A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
56
- - `svg_use`: A convenient shortcut for `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
57
- - `uuid_v1`: A helper that generates a UUID v1 identifier (with a creation timestamp).
56
+ - `svg_use`: Shorthand for: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
57
+ - `uuid_v1`: Generates a UUID v1 (time-based) identifier.
58
58
 
59
59
  ### C_Node
60
60
 
@@ -64,7 +64,7 @@ type C_Node = {
64
64
  };
65
65
  ```
66
66
 
67
- The type of arguments of the `c` helper.
67
+ Argument type for the `c` helper.
68
68
 
69
69
  ### C_Root
70
70
 
@@ -72,7 +72,7 @@ The type of arguments of the `c` helper.
72
72
  type C_Root = Record<PropertyKey, C_Node>;
73
73
  ```
74
74
 
75
- The type of arguments of the `c` helper.
75
+ Argument type for the `c` helper.
76
76
 
77
77
  ### Escape_Map
78
78
 
@@ -80,7 +80,7 @@ The type of arguments of the `c` helper.
80
80
  type Escape_Map = Map<unknown, (value?: unknown) => string>;
81
81
  ```
82
82
 
83
- The type of arguments of the `escape_values` and `escape` helpers.
83
+ Argument type accepted by the `escape_values` and `escape` helpers.
84
84
 
85
85
  ### H_Args
86
86
 
@@ -88,7 +88,7 @@ The type of arguments of the `escape_values` and `escape` helpers.
88
88
  type H_Args = [string | Node, ...H_Args_1[]];
89
89
  ```
90
90
 
91
- The type of arguments of the `h` and `s` helpers.
91
+ Argument type for the `h` and `s` helpers.
92
92
 
93
93
  ### H_Args_1
94
94
 
@@ -96,7 +96,7 @@ The type of arguments of the `h` and `s` helpers.
96
96
  type H_Args_1 = Record<PropertyKey, unknown> | null | undefined | Node | string | number | H_Args;
97
97
  ```
98
98
 
99
- The type of arguments of the `h` and `s` helpers.
99
+ Argument type for the `h` and `s` helpers.
100
100
 
101
101
  ### c
102
102
 
@@ -104,15 +104,15 @@ The type of arguments of the `h` and `s` helpers.
104
104
  const c: (root: C_Root, splitter?: string) => string;
105
105
  ```
106
106
 
107
- A simple JS-to-CSS (aka CSS-in-JS) helper.
107
+ A minimal JS-to-CSS (CSS‑in‑JS) helper.
108
108
 
109
- The `root` parameter provides a hierarchical description of CSS rules.
109
+ The `root` object describes a hierarchy of CSS rules.
110
110
 
111
- - Keys of sub-objects whose values are NOT objects are treated as CSS attribute, and values are treated as values of those CSS attributes; the concatenation of keys of all parent objects is a CSS rule.
112
- - All keys ignore the part starting with a splitter (default: `$$`) sign until the end of the key (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
113
- - In keys specifying CSS attribute, all uppercase letters are replaced by lowercase letters with an additional `-` character preceding them (e.g. `fontFamily` → `font-family`), while all `_` characters are replaced by `-` character (e.g. `font_family` → `font-family`).
114
- - Commas in keys that makes a CSS rule cause it to “split” and create separate rules for each part (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
115
- - Top-level keys that begin with `@` are not concatenated with sub-object keys.
111
+ - Keys whose values are not objects are treated as CSS property names; their values become property values. The concatenation of parent keys produces a selector.
112
+ - For every key, the substring starting with the splitter (default: `$$`) to the end is ignored (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
113
+ - In property keys, uppercase letters are converted to lowercase and prefixed with `-` (e.g. `fontFamily` → `font-family`); underscores are converted to `-` (e.g. `font_family` → `font-family`).
114
+ - Commas inside selector keys cause them to expand into multiple selectors (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
115
+ - Top-level keys beginning with `@` (at-rules) are not concatenated with parent keys.
116
116
 
117
117
  #### Usage Examples
118
118
 
@@ -316,7 +316,7 @@ expect(actual).to.deep.equal(expected)
316
316
  const csv_parse: (csv: string, separator?: string) => string[][];
317
317
  ```
318
318
 
319
- A tiny helper for parsing CSV.
319
+ A tiny CSV parsing helper.
320
320
 
321
321
  #### Usage Examples
322
322
 
@@ -342,7 +342,7 @@ expect(csv_parse(text)).to.deep.equal([
342
342
  const escape: (escape_map: Escape_Map, template: TemplateStringsArray, ...values: unknown[]) => string;
343
343
  ```
344
344
 
345
- A generic helper for escaping `values` by given `escape_map` (in *TemplateStrings* flavor).
345
+ Escapes interpolated template `values` using the provided `escape_map`.
346
346
 
347
347
  #### Usage Examples
348
348
 
@@ -377,7 +377,7 @@ expect(actual).to.deep.equal(expected)
377
377
  const escape_values: (escape_map: Escape_Map, values: unknown[]) => string[];
378
378
  ```
379
379
 
380
- A generic helper for escaping `values` by given `escape_map`.
380
+ Escapes array `values` using the provided `escape_map`.
381
381
 
382
382
  ### fix_typography
383
383
 
@@ -385,7 +385,7 @@ A generic helper for escaping `values` by given `escape_map`.
385
385
  const fix_typography: (node: Node) => void;
386
386
  ```
387
387
 
388
- A helper that implements typographic corrections specific to Polish typography.
388
+ Applies Polish‑specific typographic corrections.
389
389
 
390
390
  #### Usage Examples
391
391
 
@@ -411,13 +411,16 @@ const h: {
411
411
 
412
412
  A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
413
413
 
414
- - The first argument of type `string` specifies the tag of the element to be created.
415
- - The first argument of type `Node` specifies the element to be modified.
416
- - All other arguments of type `Record<PropertyKey, unknown>` are mappings of attributes and properties. Keys starting with `$` specify *properties* (without the leading `$`) to be set on the element being created or modified. (Note that `$` is not a valid attribute name character.) All other keys specify *attributes* to be set by `setAttribute`. An attribute equal to `false` causes the attribute to be removed by `removeAttribute`.
417
- - All other arguments of type `null` or `undefined` are simply ignored.
418
- - All other arguments of type `Node` are appended to the element being created or modified.
419
- - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
420
- - All other arguments of type `HArgs` are passed to `h` and the results are appended to the element being created or modified.
414
+ - If the first argument is a `string`, it is treated as the tag name to create.
415
+ - If the first argument is a `Node`, that node is modified.
416
+ - Object arguments map attributes/properties:
417
+ - Keys starting with `$` set element properties (without `$`).
418
+ - Other keys set attributes via `setAttribute`.
419
+ - Attributes with value `false` are removed via `removeAttribute`.
420
+ - `null` / `undefined` are ignored.
421
+ - `Node` arguments are appended.
422
+ - `string` / `number` arguments become `Text` nodes.
423
+ - `H_Args` arrays are processed recursively.
421
424
 
422
425
  #### Usage Examples
423
426
 
@@ -493,7 +496,7 @@ expect(div.key).to.deep.equal({ one: 1, two: 2 })
493
496
  const has_own: (ref: unknown, key: unknown) => boolean;
494
497
  ```
495
498
 
496
- A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
499
+ A replacement to the `in` operator (not to be confused with `for-in`).
497
500
 
498
501
  #### Usage Examples
499
502
 
@@ -538,7 +541,7 @@ type Finite_Number = number & {
538
541
  };
539
542
  ```
540
543
 
541
- A helper that checks if the given argument is of type `any[]`.
544
+ Checks whether the argument is an array.
542
545
 
543
546
  ### is_finite_number
544
547
 
@@ -546,7 +549,7 @@ A helper that checks if the given argument is of type `any[]`.
546
549
  const is_finite_number: ((arg: unknown) => arg is Finite_Number);
547
550
  ```
548
551
 
549
- A helper that checks if the given argument is of type `number` but not `±Infinity` nor `NaN`.
552
+ Checks whether the argument is a finite number (excluding `±Infinity` and `NaN`).
550
553
 
551
554
  ### is_number
552
555
 
@@ -554,7 +557,7 @@ A helper that checks if the given argument is of type `number` but not `±Infini
554
557
  const is_number: (arg: unknown) => arg is number;
555
558
  ```
556
559
 
557
- A helper that checks if the given argument is of type `number`.
560
+ Checks whether the argument is a number.
558
561
 
559
562
  ### is_record
560
563
 
@@ -562,7 +565,7 @@ A helper that checks if the given argument is of type `number`.
562
565
  const is_record: (arg: unknown) => arg is Record<PropertyKey, unknown>;
563
566
  ```
564
567
 
565
- A helper that checks if the given argument is of type `Record<PropertyKey, unknown>`.
568
+ Checks whether the argument is a plain object record.
566
569
 
567
570
  ### is_string
568
571
 
@@ -571,7 +574,7 @@ const is_string: (arg: unknown) => arg is string;
571
574
  export {};
572
575
  ```
573
576
 
574
- A helper that checks if the given argument is of type `string`.
577
+ Checks whether the argument is a string.
575
578
 
576
579
  ### js_on_parse
577
580
 
@@ -581,13 +584,13 @@ const js_on_parse: (handlers: Record<PropertyKey, Function>, text: string) => an
581
584
 
582
585
  `JSON.parse` with “JavaScript turned on”.
583
586
 
584
- Objects having *exactly* one property which is present in the `handlers` map, i.e. objects of the form:
587
+ Objects having *exactly* one property whose name exists in `handlers`, i.e.:
585
588
 
586
589
  ```js
587
590
  { "«handler_name»": [«params»] }
588
591
  ```
589
592
 
590
- are replaced by the result of call
593
+ are replaced with:
591
594
 
592
595
  ```js
593
596
  handlers['«handler_name»'](...«params»)
@@ -646,7 +649,7 @@ expect(actual).to.deep.equal(expected)
646
649
  const nanolight: (pattern: RegExp, highlighters: ((chunk: string, index: number) => H_Args_1)[], code: string) => H_Args_1[];
647
650
  ```
648
651
 
649
- A generic helper for syntax highlighting (see also `nanolight_js`).
652
+ Generic syntax highlighting helper (see also `nanolight_js`).
650
653
 
651
654
  ### nanolight_js
652
655
 
@@ -654,7 +657,7 @@ A generic helper for syntax highlighting (see also `nanolight_js`).
654
657
  const nanolight_js: (code: string) => H_Args_1[];
655
658
  ```
656
659
 
657
- A helper for highlighting JavaScript (see also `nanolight`).
660
+ JavaScript syntax highlighting helper (built on `nanolight`).
658
661
 
659
662
  #### Usage Examples
660
663
 
@@ -678,7 +681,7 @@ expect(nanolight_js(code_js)).to.deep.equal([
678
681
  const omit: <T, K extends keyof T>(ref: T, keys: unknown[]) => Omit<T, K>;
679
682
  ```
680
683
 
681
- A helper that implements TypeScript’s `Omit` utility type (see also `pick`).
684
+ Runtime implementation of TypeScript’s `Omit` (see also `pick`).
682
685
 
683
686
  #### Usage Examples
684
687
 
@@ -694,7 +697,7 @@ expect(omit(obj, ['c'])).to.deep.equal({ a: 42, b: '42' })
694
697
  const pick: <T, K extends keyof T>(ref: T, keys: K[]) => Pick<T, K>;
695
698
  ```
696
699
 
697
- A helper that implements TypeScript’s `Pick` utility type (see also `omit`).
700
+ Runtime implementation of TypeScript’s `Pick` (see also `omit`).
698
701
 
699
702
  #### Usage Examples
700
703
 
@@ -710,7 +713,7 @@ expect(pick(obj, ['a', 'b'])).to.deep.equal({ a: 42, b: '42' })
710
713
  const pl_ural: (singular: string, plural_2: string, plural_5: string, value: number) => string;
711
714
  ```
712
715
 
713
- A helper for choosing the correct singular and plural.
716
+ Chooses the appropriate Polish noun form based on a numeric value.
714
717
 
715
718
  #### Usage Examples
716
719
 
@@ -736,7 +739,7 @@ expect(car(42)).to.deep.equal('cars')
736
739
  const pro: (ref: unknown) => any;
737
740
  ```
738
741
 
739
- A helper that protects calls to nested properties by a `Proxy` that initializes non-existent values with an empty object.
742
+ A `Proxy`-based helper that safely creates nested structures on access and allows deep assignment without guards.
740
743
 
741
744
  #### Usage Examples
742
745
 
@@ -780,13 +783,16 @@ const s: {
780
783
 
781
784
  A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
782
785
 
783
- - The first argument of type `string` specifies the tag of the element to be created.
784
- - The first argument of type `Node` specifies the element to be modified.
785
- - All other arguments of type `Record<PropertyKey, unknown>` are mappings of attributes and properties. Keys starting with `$` specify *properties* (without the leading `$`) to be set on the element being created or modified. (Note that `$` is not a valid attribute name character.) All other keys specify *attributes* to be set by `setAttributeNS`. An attribute equal to `false` causes the attribute to be removed by `removeAttributeNS`.
786
- - All other arguments of type `null` or `undefined` are simply ignored.
787
- - All other arguments of type `Node` are appended to the element being created or modified.
788
- - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
789
- - All other arguments of type `HArgs` are passed to `s` and the results are appended to the element being created or modified.
786
+ - If the first argument is a `string`, it is treated as the tag name to create.
787
+ - If the first argument is a `Node`, that node is modified.
788
+ - Object arguments map attributes/properties:
789
+ - Keys starting with `$` set element properties (without `$`).
790
+ - Other keys set attributes via `setAttributeNS`.
791
+ - Attributes with value `false` are removed via `removeAttributeNS`.
792
+ - `null` / `undefined` are ignored.
793
+ - `Node` arguments are appended.
794
+ - `string` / `number` arguments become `Text` nodes.
795
+ - `H_Args` arrays are processed recursively.
790
796
 
791
797
  ### svg_use
792
798
 
@@ -794,7 +800,7 @@ A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style help
794
800
  const svg_use: (id: string, ...args: H_Args_1[]) => SVGSVGElement;
795
801
  ```
796
802
 
797
- A convenient shortcut for `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
803
+ Shorthand for: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
798
804
 
799
805
  ### uuid_v1
800
806
 
@@ -802,9 +808,9 @@ A convenient shortcut for `s('svg', ['use', { 'xlink:href': '#' + id }], ...args
802
808
  const uuid_v1: (date?: Date, node?: string) => string;
803
809
  ```
804
810
 
805
- A helper that generates a UUID v1 identifier (with a creation timestamp).
811
+ Generates a UUID v1 (time-based) identifier.
806
812
 
807
- - The optional `node` parameter should have the format `/^[0123456789abcdef]+$/`. Its value will be trimmed to last 12 characters and left padded with zeros.
813
+ - Optional `node` must match `/^[0-9a-f]*$/`; it is trimmed to the last 12 characters and left-padded with zeros.
808
814
 
809
815
  ## License
810
816