@jackens/nnn 2025.12.9 → 2025.12.11

package/nnn.d.ts

@@ -1,20 +1,34 @@
-/** Argument type for the `h` and `s` helpers. */
+/**
+ * Single argument type for the {@link h} and {@link s} helpers.
+ */
 export type HArgs1 = Record<PropertyKey, unknown> | null | undefined | Node | string | number | HArgs;
-/** Argument type for the `h` and `s` helpers. */
+/**
+ * Tuple argument type for the {@link h} and {@link s} helpers.
+ */
 export type HArgs = [string | Node, ...HArgs1[]];
 /**
- * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
+ * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper
+ * for creating and modifying `HTMLElement`s (see also {@link s}).
+ *
+ * @param tag_or_node
+ *
+ * If a `string`, it is treated as the tag name for a new element.
+ * If a `Node`, that node is modified in place.
  *
- * - If the first argument is a `string`, it is treated as the tag name to create.
- * - If the first argument is a `Node`, that node is modified.
- * - Object arguments map attributes/properties:
- *   - Keys starting with `$` set element properties (without `$`).
- *   - Other keys set attributes via `setAttribute`.
- *   - Attributes with value `false` are removed via `removeAttribute`.
- * - `null` / `undefined` are ignored.
- * - `Node` arguments are appended.
- * - `string` / `number` arguments become `Text` nodes.
- * - `HArgs` arrays are processed recursively.
+ * @param args
+ *
+ * Additional arguments processed as follows:
+ * - `Object`: Maps attributes/properties. Keys starting with `$` set element properties
+ *   (without the `$` prefix); other keys set attributes via `setAttribute`.
+ *   A value of `false` removes the attribute.
+ * - `null` / `undefined`: Ignored.
+ * - `Node`: Appended as a child.
+ * - `string` / `number`: Converted to a `Text` node and appended.
+ * - {@link HArgs} array: Processed recursively.
+ *
+ * @returns
+ *
+ * The created or modified `HTMLElement`.
  */
 export declare const h: {
     <T extends keyof HTMLElementTagNameMap>(tag: T, ...args1: HArgs1[]): HTMLElementTagNameMap[T];
@@ -22,117 +36,418 @@ export declare const h: {
     (tag_or_node: string | Node, ...args1: HArgs1[]): Node;
 };
 /**
- * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
+ * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper
+ * for creating and modifying `SVGElement`s (see also {@link h}).
+ *
+ * @param tag_or_node
+ *
+ * If a `string`, it is treated as the tag name for a new element.
+ * If a `Node`, that node is modified in place.
  *
- * - If the first argument is a `string`, it is treated as the tag name to create.
- * - If the first argument is a `Node`, that node is modified.
- * - Object arguments map attributes/properties:
- *   - Keys starting with `$` set element properties (without `$`).
- *   - Other keys set attributes via `setAttributeNS`.
- *   - Attributes with value `false` are removed via `removeAttributeNS`.
- * - `null` / `undefined` are ignored.
- * - `Node` arguments are appended.
- * - `string` / `number` arguments become `Text` nodes.
- * - `HArgs` arrays are processed recursively.
+ * @param args
+ *
+ * Additional arguments processed as follows:
+ * - `Object`: Maps attributes/properties. Keys starting with `$` set element properties
+ *   (without the `$` prefix); other keys set attributes via `setAttributeNS`.
+ *   A value of `false` removes the attribute.
+ * - `null` / `undefined`: Ignored.
+ * - `Node`: Appended as a child.
+ * - `string` / `number`: Converted to a `Text` node and appended.
+ * - {@link HArgs} array: Processed recursively.
+ *
+ * @returns
+ *
+ * The created or modified `SVGElement`.
  */
 export declare const s: {
     <T extends keyof SVGElementTagNameMap>(tag: T, ...args1: HArgs1[]): SVGElementTagNameMap[T];
     <N extends Node>(node: N, ...args1: HArgs1[]): N;
     (tag_or_node: string | Node, ...args1: HArgs1[]): Node;
 };
-/** Shorthand for: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`. */
+/**
+ * Shorthand for creating an SVG element with a `<use>` child referencing an icon by ID.
+ *
+ * Equivalent to: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
+ *
+ * @param id
+ *
+ * The ID of the symbol to reference (without the `#` prefix).
+ *
+ * @param args
+ *
+ * Additional arguments passed to the outer `<svg>` element.
+ *
+ * @returns
+ *
+ * An `SVGSVGElement` containing a `<use>` element.
+ */
 export declare const svg_use: (id: string, ...args: HArgs1[]) => SVGSVGElement;
 /**
- * Generic syntax highlighting helper (see also `nanolight_ts`).
+ * A helper for building simple tokenizers (see also {@link nanolight_ts}).
+ *
+ * @param decorator
+ *
+ * A function that wraps each matched chunk. It receives the matched text (`chunk`)
+ * and optionally the `metadata` associated with the pattern that produced the match.
+ * For unmatched text between patterns, `metadata` is `undefined`.
+ *
+ * @param specs
+ *
+ * An array of tuples `[metadata, pattern]` where:
+ * - `metadata`: Arbitrary data (e.g., a CSS class name) passed to `decorator` when the pattern matches.
+ * - `pattern`: A `string` or `RegExp` to match against the input.
+ *
+ * @returns
+ *
+ * A tokenizer function that accepts a code string and returns an array of decorated tokens.
+ *
+ * @remarks
+ *
+ * 1. Matches starting at an earlier position take precedence.
+ * 2. Among matches at the same position, the longer one wins.
+ * 3. Among matches of the same position and length, the one defined earlier wins.
+ */
+export declare const new_tokenizer: <M, T>(decorator: (chunk: string, metadata?: M) => T, ...specs: [M, string | RegExp][]) => (code: string) => T[];
+/**
+ * A TypeScript/JavaScript syntax highlighting tokenizer built using {@link new_tokenizer}.
  *
- * - The `decorator` is a function that wraps each matched chunk.
- *   It is called with the matched text and optionally the pattern name when a pattern matches.
- * - Each `config` argument is a mapping of pattern names to arrays of `string` or `RegExp` patterns.
- *   - For two matches at different positions, the one starting earlier takes precedence.
- *   - For two matches at the same position, the longer one takes precedence.
- *   - For two matches at the same position and of the same length, the one defined earlier takes precedence.
+ * @param code
+ *
+ * The source code string to tokenize.
+ *
+ * @returns
+ *
+ * An array of {@link HArgs1} elements suitable for rendering with {@link h} or {@link s}.
  */
-export declare const nanolight: <T>(decorator: (chunk: string, name?: string) => T, ...configs: Record<string, (string | RegExp)[]>[]) => (code: string) => T[];
-/** TypeScript syntax highlighting helper (built on `nanolight`). */
 export declare const nanolight_ts: (code: string) => HArgs1[];
-/** Applies Polish‑specific typographic corrections. */
+/**
+ * Applies Polish-specific typographic corrections to a DOM subtree.
+ *
+ * This function prevents orphaned conjunctions (single-letter words like “a”, “i”, “o”, “u”, “w”, “z”)
+ * from appearing at the end of a line by wrapping them with the following word in a non-breaking span.
+ * It also inserts zero-width spaces after slashes and dots to allow line breaks.
+ *
+ * @param node
+ *
+ * The root DOM node to process. All descendant text nodes are corrected recursively,
+ * except those inside `IFRAME`, `NOSCRIPT`, `PRE`, `SCRIPT`, `STYLE`, or `TEXTAREA` elements.
+ */
 export declare const fix_typography: (node: Node) => void;
-/** Argument type for the `c` helper. */
+/**
+ * Represents a CSS rule node for the {@link c} helper. Keys are CSS properties or nested selectors.
+ */
 export type CNode = {
     [attribute_or_selector: string]: string | number | CNode | undefined;
 };
-/** Argument type for the `c` helper. */
+/**
+ * Represents the root CSS object for the {@link c} helper. Keys are top-level selectors or at-rules.
+ */
 export type CRoot = Record<PropertyKey, CNode>;
 /**
- * A minimal JS-to-CSS (CSS‑in‑JS) helper.
+ * A minimal CSS-in-JS helper that converts a JavaScript object hierarchy into a CSS string.
+ *
+ * @param root
+ *
+ * An object describing CSS rules.
+ * Keys are selectors or at-rules; values are either CSS property values or nested rule objects.
+ *
+ * @param splitter
+ *
+ * A delimiter used to create unique keys (default: `'$$'`).
+ * The substring from `splitter` to the end of a key is ignored (e.g., `src$$1` → `src`).
+ *
+ * @returns
  *
- * The `root` object describes a hierarchy of CSS rules.
+ * A CSS string representing the compiled rules.
  *
- * - 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.
- * - For every key, the substring from the splitter (default: `$$`) to the end is ignored (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
- * - 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`).
- * - 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}`).
- * - Top-level keys beginning with `@` (at-rules) are not concatenated with parent keys.
+ * @remarks
+ *
+ * - Keys whose values are primitives (`string` | `number`) are treated as CSS properties.
+ * - In property keys, uppercase letters become lowercase with a `-` prefix (e.g., `fontFamily` → `font-family`);
+ *   underscores become hyphens (e.g., `font_family` → `font-family`).
+ * - Comma-separated selector keys expand into multiple selectors
+ *   (e.g., `{ div: { '.a,.b': { margin: 1 } } }` → `div.a,div.b{margin:1}`).
+ * - Top-level keys starting with `@` (at-rules) are not concatenated with child selectors.
  */
 export declare const c: (root: CRoot, splitter?: string) => string;
 /**
- * A responsive‑web‑design helper that generates CSS rules for a grid-like layout.
+ * A responsive web design helper that generates CSS rules for a grid-like layout.
+ *
+ * @param root
+ *
+ * The CSS root object to populate (see {@link c}).
+ *
+ * @param selector
+ *
+ * The CSS selector for the grid item.
  *
- * - `root` and `selector` specify where to apply the generated rules (see `c`).
- * - `cell_width_px` and `cell_height_px` specify the base cell dimensions in pixels.
- * - Each entry in `specs` is a tuple of:
- *   - `max_width`: maximum number of cells in a row (viewport width breakpoint).
- *   - `width` (optional, default: `1`): number of cells occupied by the element.
- *   - `height` (optional, default: `1`): number of cells the element occupies vertically.
+ * @param cell_width_px
+ *
+ * The base cell width in pixels.
+ *
+ * @param cell_height_px
+ *
+ * The base cell height in pixels.
+ *
+ * @param specs
+ *
+ * An array of breakpoint specifications, each a tuple of:
+ * - `max_width`: Maximum number of cells per row (defines the viewport breakpoint).
+ * - `width` (optional, default `1`): Number of horizontal cells the element spans.
+ * - `height` (optional, default `1`): Number of vertical cells the element spans.
  */
 export declare const rwd: (root: CRoot, selector: string, cell_width_px: number, cell_height_px: number, ...specs: [number, number?, number?][]) => void;
-/** Argument type accepted by the `escape_values` and `escape` helpers. */
+/**
+ * A map from value constructors (or `null`/`undefined`) to escape functions.
+ *
+ * Used by {@link escape_values} and {@link escape}.
+ */
 export type EscapeMap = Map<unknown, (value?: unknown) => string>;
-/** Escapes array `values` using the provided `escape_map`. */
+/**
+ * Escapes an array of values using the provided escape map.
+ *
+ * @param escape_map
+ *
+ * A map where keys are constructors (e.g., `String`, `Number`) and values are escape functions.
+ *
+ * @param values
+ *
+ * The array of values to escape.
+ *
+ * @returns
+ *
+ * An array of escaped strings.
+ */
 export declare const escape_values: (escape_map: EscapeMap, values: unknown[]) => string[];
-/** Escapes interpolated template `values` using the provided `escape_map`. */
+/**
+ * Escapes interpolated values in a tagged template literal using the provided escape map.
+ *
+ * @param escape_map
+ *
+ * A map where keys are constructors and values are escape functions.
+ *
+ * @param template
+ *
+ * The template strings array from the tagged template.
+ *
+ * @param values
+ *
+ * The interpolated values to escape.
+ *
+ * @returns
+ *
+ * The resulting string with all interpolated values escaped.
+ */
 export declare const escape: (escape_map: EscapeMap, template: TemplateStringsArray, ...values: unknown[]) => string;
-/** Chooses the appropriate Polish noun form based on a numeric value. */
+/**
+ * Returns the appropriate Polish noun form based on a numeric value.
+ *
+ * Polish has three plural forms depending on the number:
+ * - Singular: used for exactly 1.
+ * - “Plural 2-4”: used for 2, 3, 4, 22, 23, 24, etc. (but not 12, 13, 14).
+ * - “Plural 5+”: used for 0, 5–21, 25–31, etc.
+ *
+ * @param singular
+ *
+ * The singular form (e.g., ”auto” for “car”).
+ *
+ * @param plural_2
+ *
+ * The form for 2, 3, 4 (e.g., “auta”).
+ *
+ * @param plural_5
+ *
+ * The form for 5+ (e.g., “aut”).
+ *
+ * @param value
+ *
+ * The numeric value to evaluate.
+ *
+ * @returns
+ *
+ * The appropriate noun form for the given value.
+ */
 export declare const pl_ural: (singular: string, plural_2: string, plural_5: string, value: number) => string;
 /**
  * Generates a UUID v1 (time-based) identifier.
  *
- * - Optional `node` must match `/^[0-9a-f]*$/`; it is trimmed to the last 12 characters and left-padded with zeros.
+ * @param date
+ *
+ * The date to use for the timestamp portion (default: current date/time).
+ *
+ * @param node
+ *
+ * A hexadecimal `string` for the node portion (default: random).
+ * Must match `/^[0-9a-f]*$/`; it is trimmed to the last 12 characters and left-padded with zeros if shorter.
+ *
+ * @returns
+ *
+ * A UUID v1 `string` in the standard format `xxxxxxxx-xxxx-1xxx-xxxx-xxxxxxxxxxxx`.
  */
 export declare const uuid_v1: (date?: Date, node?: string) => string;
 /**
- * `JSON.parse` with “JavaScript turned on”.
+ * Parses JSON with support for handler-based value transformation (“JavaScript ON”).
  *
- * Objects having *exactly* one property whose name exists in `handlers`, i.e.:
+ * Objects with exactly one property whose key exists in `handlers` and whose value is an array
+ * are replaced by invoking the corresponding handler with the array elements as arguments.
  *
- * ```js
- * { "«handler_name»": [«params»] }
- * ```
+ * @param handlers
  *
- * are replaced with:
+ * An object mapping handler names to functions.
  *
- * ```js
- * handlers['«handler_name»'](...«params»)
- * ```
+ * @param text
+ *
+ * The JSON string to parse.
+ *
+ * @returns
+ *
+ * The parsed value with handler substitutions applied.
  */
 export declare const js_on_parse: (handlers: Record<PropertyKey, Function>, text: string) => any;
-/** Checks whether the argument is an array. */
+/**
+ * Checks whether the argument is an array.
+ *
+ * @param arg
+ *
+ * The value to check.
+ *
+ * @returns
+ *
+ * `true` if `arg` is an array, `false` otherwise.
+ */
 export declare const is_array: (arg: unknown) => arg is unknown[];
-/** Checks whether the argument is a finite number (excluding `±Infinity` and `NaN`). */
+/**
+ * Checks whether the argument is a finite number (excludes `±Infinity` and `NaN`).
+ *
+ * @param arg
+ *
+ * The value to check.
+ *
+ * @returns
+ *
+ * `true` if `arg` is a finite number, `false` otherwise.
+ */
 export declare const is_finite_number: (arg: unknown) => arg is number;
-/** Checks whether the argument is a number. */
+/**
+ * Checks whether the argument is of type `number` (includes `NaN` and `±Infinity`).
+ *
+ * @param arg
+ *
+ * The value to check.
+ *
+ * @returns
+ *
+ * `true` if `typeof arg === 'number'`, `false` otherwise.
+ */
 export declare const is_number: (arg: unknown) => arg is number;
-/** Checks whether the argument is a plain object record. */
+/**
+ * Checks whether the argument is a plain object (not `null` and not an array).
+ *
+ * @param arg
+ *
+ * The value to check.
+ *
+ * @returns
+ *
+ * `true` if `arg` is a plain object, `false` otherwise.
+ */
 export declare const is_record: (arg: unknown) => arg is Record<PropertyKey, unknown>;
-/** Checks whether the argument is a string. */
+/**
+ * Checks whether the argument is a string.
+ *
+ * @param arg
+ *
+ * The value to check.
+ *
+ * @returns
+ *
+ * `true` if `typeof arg === 'string'`, `false` otherwise.
+ */
 export declare const is_string: (arg: unknown) => arg is string;
-/** A replacement for the `in` operator (not to be confused with `for-in`). */
+/**
+ * Checks whether an object has the specified key as its own property.
+ *
+ * A null-safe wrapper around `Object.hasOwn`.
+ *
+ * @param ref
+ *
+ * The object to check.
+ *
+ * @param key
+ *
+ * The property key to look for.
+ *
+ * @returns
+ *
+ * `true` if `ref` is not nullish and has `key` as an own property, `false` otherwise.
+ */
 export declare const has_own: (ref: unknown, key: unknown) => boolean;
-/** A `Proxy`-based helper that safely creates nested structures on access and allows deep assignment without guards. */
+/**
+ * A Proxy-based helper for auto-vivification of nested object structures.
+ *
+ * Accessing any property on the returned proxy automatically creates an empty object if the property does not exist,
+ * allowing deep assignments without explicit null checks.
+ *
+ * @param ref
+ *
+ * The root object to wrap.
+ *
+ * @returns
+ *
+ * A proxy that auto-creates nested objects on property access.
+ */
 export declare const pro: (ref: unknown) => any;
-/** A tiny CSV parsing helper. */
+/**
+ * Parses a CSV string into a two-dimensional array of strings.
+ *
+ * Supports quoted fields with escaped double quotes (`""`). Carriage returns are normalized.
+ *
+ * @param csv
+ *
+ * The CSV string to parse.
+ *
+ * @param separator
+ *
+ * The field delimiter (default: `','`).
+ *
+ * @returns
+ *
+ * A 2D array where each inner array represents a row of fields.
+ */
 export declare const csv_parse: (csv: string, separator?: string) => string[][];
-/** Runtime implementation of TypeScript’s `Pick` (see also `omit`). */
+/**
+ * Creates a new object containing only the specified keys from the source object.
+ *
+ * A runtime equivalent of TypeScript’s `Pick<T, K>` utility type. See also {@link omit}.
+ *
+ * @param ref
+ *
+ * The source object.
+ *
+ * @param keys
+ *
+ * An array of keys to include in the result.
+ *
+ * @returns
+ *
+ * A new object with only the specified keys.
+ */
 export declare const pick: <T, K extends keyof T>(ref: T, keys: K[]) => Pick<T, K>;
-/** Runtime implementation of TypeScript’s `Omit` (see also `pick`). */
+/**
+ * Creates a new object excluding the specified keys from the source object.
+ *
+ * A runtime equivalent of TypeScript’s `Omit<T, K>` utility type. See also {@link pick}.
+ *
+ * @param ref
+ *
+ * The source object.
+ *
+ * @param keys
+ *
+ * An array of keys to exclude from the result.
+ *
+ * @returns
+ *
+ * A new object without the specified keys.
+ */
 export declare const omit: <T, K extends keyof T>(ref: T, keys: unknown[]) => Omit<T, K>;