@jackens/nnn 2026.9.1 → 2026.9.2

package/nnn.d.ts

@@ -1,78 +1,101 @@
 /**
- * A helper for building simple tokenizers
- * (see also {@link nanolightTs}).
- *
- * @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.
+ * Represents a CSS rule node for the {@link c} helper. Keys
+ * are CSS properties or nested selectors.
+ */
+export type CNode = {
+    [attributeOrSelector: string]: string | number | CNode | undefined;
+};
+/**
+ * A minimal CSS-in-JS helper that converts a JavaScript
+ * object hierarchy into a CSS string.
+ *
+ * @param node An object describing CSS rules. Keys are
+ *   selectors or at-rules; values are either CSS property
+ *   values or nested rule objects. A selector key may
+ *   contain comma-separated alternatives (e.g. `'.b,.c'`);
+ *   when nested, each alternative is combined with each
+ *   parent alternative (cartesian product), producing a
+ *   comma-joined selector list (e.g. `'a.b,a.c'`).
+ * @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 A CSS string representing the compiled rules.
+ */
+export declare const c: (node: CNode, splitter?: string) => string;
+/**
+ * Creates a tag function for escaping interpolated values
+ * in template literals.
  *
- * @returns
+ * @param escapeFn A function that takes a value and returns
+ *   its escaped string representation.
  *
- * A tokenizer function that accepts a code string
- * and returns an array of decorated tokens.
+ * @returns A tag function that escapes interpolated values
+ *   using the provided escape function.
+ */
+export declare const createEscape: (escapeFn: (value: any) => string) => (template: TemplateStringsArray, ...values: unknown[]) => string;
+/**
+ * A helper for building simple tokenizers (see also
+ * {@link nanolightTs}).
  *
  * @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.
+ *   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.
+ *
+ * @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.
  */
 export declare const createTokenizer: <M, T>(decorator: (chunk: string, metadata?: M) => T, ...specs: [M, string | RegExp][]) => (code: string) => T[];
 /**
- * Parses a CSV string
- * into a two-dimensional array of strings.
+ * 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: `','`).
+ * @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.
+ * @returns A 2D array where each inner array represents a
+ *   row of fields.
  */
 export declare const csvParse: (csv: string, separator?: string) => string[][];
 /**
- * Applies Polish-specific typographic corrections
- * to a DOM subtree.
+ * 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.
+ * and the em dash (“—”) from appearing at the end of a
+ * line. It wraps each such character together with the
+ * whitespace that follows it in a `white-space:nowrap`
+ * span, removing the only line-break opportunity between it
+ * and the next word so the two stay glued together. 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 fixPlTypography: (node: Node) => void;
 /**
@@ -86,33 +109,31 @@ export type HArgs1 = Record<PropertyKey, unknown> | null | undefined | Node | st
  */
 export type HArgs = [string | Node, ...HArgs1[]];
 /**
- * A lightweight *HyperScript*-style helper
- * for creating and modifying `HTMLElement`s
- * (see also {@link s}).
- *
- * @param tagOrNode
- *
- * If a `string`, it is treated as the tag name
- * for a new element.
- * If a `Node`, that node is modified in place.
- *
- * @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`.
+ * A lightweight _HyperScript_-style helper for creating and
+ * modifying `HTMLElement`s (see also {@link s}).
+ *
+ * @param tagOrNode If a `string`, it is treated as the tag
+ *   name for a new element. If a `Node`, that node is
+ *   modified in place.
+ * @param args Additional arguments processed as follows:
+ *
+ *   - `Object`: maps attributes/properties. Keys starting
+ *     with `$` set element properties (without the `$`
+ *     prefix); if the value is a plain object, it is
+ *     shallow-merged into the existing property instead of
+ *     replacing it (useful e.g. for `$style`). Other keys
+ *     set attributes: a key prefixed with `xlink:` sets the
+ *     attribute via `setAttributeNS` in the XLink
+ *     namespace; any other key (without a colon) sets it
+ *     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];
@@ -120,33 +141,30 @@ export declare const h: {
     (tagOrNode: string | Node, ...args1: HArgs1[]): Node;
 };
 /**
- * A lightweight *HyperScript*-style helper
- * for creating and modifying `SVGElement`s
- * (see also {@link h}).
- *
- * @param tagOrNode
- *
- * If a `string`, it is treated as the tag name
- * for a new element.
- * If a `Node`, that node is modified in place.
- *
- * @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`.
+ * A lightweight _HyperScript_-style helper for creating and
+ * modifying `SVGElement`s (see also {@link h}).
+ *
+ * @param tagOrNode If a `string`, it is treated as the tag
+ *   name for a new element. If a `Node`, that node is
+ *   modified in place.
+ * @param args Additional arguments processed as follows:
+ *
+ *   - `Object`: maps attributes/properties. Keys starting
+ *     with `$` set element properties (without the `$`
+ *     prefix); if the value is a plain object, it is
+ *     shallow-merged into the existing property instead of
+ *     replacing it. Other keys set attributes: a key
+ *     prefixed with `xlink:` sets the attribute via
+ *     `setAttributeNS` in the XLink namespace; any other
+ *     key (without a colon) sets it 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 `SVGElement`.
  */
 export declare const s: {
     <T extends keyof SVGElementTagNameMap>(tag: T, ...args1: HArgs1[]): SVGElementTagNameMap[T];
@@ -154,298 +172,123 @@ export declare const s: {
     (tagOrNode: string | Node, ...args1: HArgs1[]): Node;
 };
 /**
- * Shorthand for creating an SVG element
- * with a `<use>` child referencing an icon by ID.
+ * 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).
+ * ```ts
+ * s(
+ *   'svg',
+ *   ['use', { 'xlink:href': '#' + id }],
+ *   ...args
+ * )
+ * ```
  *
- * @param args
+ * @param id The ID of the symbol to reference (without the
+ *   `#` prefix).
+ * @param args Additional arguments passed to the outer
+ *   `<svg>` element.
  *
- * Additional arguments passed to the outer `<svg>` element.
- *
- * @returns
- *
- * An `SVGSVGElement` containing a `<use>` element.
+ * @returns An `SVGSVGElement` containing a `<use>` element.
  */
 export declare const svgUse: (id: string, ...args: HArgs1[]) => SVGSVGElement;
 /**
- * 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 hasOwn: (ref: unknown, key: unknown) => boolean;
-/**
- * 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 isArray: (arg: unknown) => arg is unknown[];
-/**
- * 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 isNumber: (arg: unknown) => arg is number;
-/**
- * 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 isFiniteNumber: (arg: unknown) => arg is number;
-/**
- * Checks whether the argument is an integer number.
- *
- * @param arg
- *
- * The value to check.
- *
- * @returns
- *
- * `true` if `arg` is an integer number, `false` otherwise.
- */
-export declare const isInteger: (arg: unknown) => arg is number;
-/**
- * Checks whether the argument is a string.
- *
- * @param arg
- *
- * The value to check.
- *
- * @returns
- *
- * `true` if `typeof arg === 'string'`, `false` otherwise.
- */
-export declare const isString: (arg: unknown) => arg is string;
-/**
- * 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 isRecord: (arg: unknown) => arg is Record<PropertyKey, unknown>;
-/**
- * Parses JSON with support for
- * handler-based value transformation (“JavaScript ON”).
- *
- * 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.
- *
- * @param handlers
- *
- * An object mapping handler names to functions.
- *
- * @param text
- *
- * The JSON string to parse.
- *
- * @returns
- *
- * The parsed value with handler substitutions applied.
- */
-export declare const jsOnParse: (handlers: Record<PropertyKey, Function>, text: string) => any;
-/**
- * A Monokai-inspired color scheme
- * for use with the {@link c} helper
- * and {@link nanolightTs} tokenizer.
+ * A Monokai-inspired color scheme for use with the {@link c}
+ * helper and {@link nanolightTs} tokenizer.
  */
 export declare const monokai: CNode;
 /**
  * A TypeScript/JavaScript syntax highlighting tokenizer
  * built using {@link createTokenizer}.
  *
- * @param code
+ * @param code The source code string to tokenize.
  *
- * The source code string to tokenize.
- *
- * @returns
- *
- * An array of {@link HArgs1} elements
- * suitable for rendering with {@link h}.
+ * @returns An array of {@link HArgs1} elements suitable for
+ *   rendering with {@link h}.
  */
 export declare const nanolightTs: (code: string) => HArgs1[];
 /**
- * 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.
+ * 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.
+ * @param cellWidthPx The base cell width in pixels.
+ * @param cellHeightPx The base cell height in pixels.
+ * @param specs An array of breakpoint specifications, each
+ *   a tuple of:
+ *
+ *   - `maxWidth`: 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 omit: <T, K extends keyof T>(ref: T, keys: unknown[]) => Omit<T, K>;
+export declare const rwd: (root: CNode, selector: string, cellWidthPx: number, cellHeightPx: number, ...specs: [number, number?, number?][]) => void;
 /**
- * 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.
+ * Generates a UUID v1 (time-based) identifier.
  *
- * @returns
+ * @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.
  *
- * A new object with only the specified keys.
+ * @returns A UUID v1 `string` in the standard format
+ *   `xxxxxxxx-xxxx-1xxx-xxxx-xxxxxxxxxxxx`.
  */
-export declare const pick: <T, K extends keyof T>(ref: T, keys: unknown[]) => Pick<T, K>;
+export declare const uuidV1: (date?: Date, node?: string) => string;
 /**
- * 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.
+ * A Proxy-based helper for auto-vivification of nested
+ * object structures.
  *
- * @param cellWidthPx
+ * Accessing, assigning, or deleting any nested property on
+ * the returned proxy automatically creates intermediate
+ * objects (or arrays for numeric-string keys matching
+ * `^(0|[1-9]\d*)$`) as needed, allowing deep operations
+ * without explicit null checks.
  *
- * The base cell width in pixels.
+ * Intermediates of the last level in a get-only property
+ * chain are NOT auto-created. For example,
+ * `vivify(ref).one.two` will create `ref.one` as `{}`, but
+ * will NOT create `ref.one.two`. Only when a deeper access,
+ * assignment, or deletion occurs, e.g.
  *
- * @param cellHeightPx
+ * ```ts
+ * delete vivify(ref).one.two.three
+ * ```
  *
- * The base cell height in pixels.
+ * or
  *
- * @param specs
+ * ```ts
+ * vivify(ref).one.two.three = 4
+ * ```
  *
- * An array of breakpoint specifications, each a tuple of:
- * - `maxWidth`: 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: CNode, selector: string, cellWidthPx: number, cellHeightPx: number, ...specs: [number, number?, number?][]) => void;
-/**
- * Generates a UUID v1 (time-based) identifier.
+ * Will `ref.one.two` be materialized.
  *
- * @param date
+ * When traversal reaches a primitive value, no
+ * auto-creation happens; the primitive’s own property is
+ * returned instead (e.g. accessing `.toString.name` on a
+ * number yields `'toString'` without modifying the
+ * underlying structure).
  *
- * The date to use for the timestamp portion
- * (default: current date/time).
+ * Deletion on a non-existing intermediate path will
+ * auto-create intermediates up to the parent of the deleted
+ * key, e.g.
  *
- * @param node
+ * ```ts
+ * delete vivify(ref).one.two.three
+ * ```
  *
- * 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.
+ * Will create `ref.one.two` as `{}` if it does not exist.
  *
- * @returns
+ * @param ref The root object to wrap.
  *
- * A UUID v1 `string` in the standard format
- * `xxxxxxxx-xxxx-1xxx-xxxx-xxxxxxxxxxxx`.
- */
-export declare const uuidV1: (date?: Date, node?: string) => string;
-/**
- * A Proxy-based helper for auto-vivification
- * of nested object structures.
- *
- * Accessing, assigning, or deleting any nested property
- * on the returned proxy
- * automatically creates intermediate objects
- * (or arrays for numeric-string keys matching
- * `^(0|[1-9]\d*)$`) as needed,
- * allowing deep operations without explicit null checks.
- *
- * Intermediates of the last level
- * in a get-only property chain are NOT auto-created.
- * For example, `vivify(ref).one.two` will create
- * `ref.one` as `{}`, but will NOT create `ref.one.two`.
- * Only when a deeper access, assignment, or deletion occurs
- * (e.g. `delete vivify(ref).one.two.three`
- * or `vivify(ref).one.two.three = 4`)
- * will `ref.one.two` be materialized.
- *
- * When traversal reaches a primitive value,
- * no auto-creation happens;
- * the primitive’s own property is returned instead
- * (e.g. accessing `.toString.name` on a number yields
- * `'toString'` without modifying the underlying structure).
- *
- * Deletion on a non-existing intermediate path
- * will auto-create intermediates up to the parent
- * of the deleted key
- * (e.g. `delete vivify(ref).one.two.three`
- * will create `ref.one.two` as `{}` if it does not exist).
- *
- * @param ref
- *
- * The root object to wrap.
- *
- * @returns
- *
- * A proxy that auto-creates nested objects/arrays
- * on property access.
+ * @returns A proxy that auto-creates nested objects/arrays
+ *   on property access.
  */
 export declare const vivify: (ref: unknown) => any;