@jackens/nnn 2026.9.9 → 2026.9.29

package/nnn.d.ts

@@ -1,244 +1,220 @@
-/**
- * Represents a CSS rule node for the {@link c} helper. Keys
- * are CSS properties or nested selectors.
- */
+/** 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;
-};
+  [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.
+ * 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.
+ * Nested selectors are appended to the parent selector as is (e.g. `'.c'` inside `a` → `a.c`), so a leading space is needed for a descendant combinator (e.g. `' .c'` → `a .c`).
+ * 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'`).
+ * Top-level at-rules (e.g. `'@media …'`) wrap their nested rules; inside a top-level `:root` rule nested keys are concatenated into property names (e.g. `{ ':root': { '--': { bg: 'red' } } }` → `:root{--bg:red}`).
+ * `null`/`undefined` values are skipped.
+ *
+ * @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;
+export declare const c: (node: CNode, splitter?: string) => string
 /**
- * Creates a tag function for escaping interpolated values
- * in template literals.
+ * Options of a {@link createLexer} spec controlling the lexer state stack.
+ *
+ * @property in
+ *
+ * State(s) in which the spec is active (default: `'root'`).
+ *
+ * @property pop
  *
- * @param escapeFn A function that takes a value and returns
- *   its escaped string representation.
+ * Whether to pop the current state off the stack after a match (the `'root'` state at the bottom is never popped).
  *
- * @returns A tag function that escapes interpolated values
- *   using the provided escape function.
+ * @property push
+ *
+ * State to push onto the stack after a match (applied after `pop`).
  */
-export declare const createEscape: (escapeFn: (value: any) => string) => (template: TemplateStringsArray, ...values: unknown[]) => string;
+export type LexerSpecOptions = {
+  in?: string | string[]
+  pop?: boolean
+  push?: string
+}
+/** A {@link createLexer} spec: a `[metadata, pattern, options?]` tuple. */
+export type LexerSpec<M> = [metadata: M, pattern: string | RegExp, options?: LexerSpecOptions]
 /**
- * A helper for building simple tokenizers (see also
- * {@link nanolightTs}).
+ * A helper for building simple stateful lexers (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.
- *
- * @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.
+ * 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.
+ * 4. Only specs active in the current state (the top of the state stack, initially `'root'`) are considered.
+ * 5. Patterns are matched against the whole input, so `^`, `$`, `\b` and lookbehinds see the text around the current position; a sticky (`y`) `RegExp` matches only at the current position.
+ * 6. Empty matches are ignored.
  *
- * Supports quoted fields with escaped double quotes (`""`).
- * Carriage returns are normalized.
+ * @param decorator
  *
- * @param csv The CSV string to parse.
- * @param separator The field delimiter (default: `','`).
+ * A function that wraps each chunk of the input.
+ * It receives the matched text (`chunk`) and the `metadata` of the spec whose pattern produced the match.
+ * For unmatched text between matches, `metadata` is `undefined`.
  *
- * @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.
- *
- * This function prevents orphaned conjunctions
- * (single-letter words like “a”, “i”, “o”, “u”, “w”, “z”)
- * 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;
-/**
- * Single argument type for the {@link h} and {@link s}
- * helpers.
- */
-export type HArgs1 = Record<PropertyKey, unknown> | null | undefined | Node | string | number | HArgs;
-/**
- * Tuple argument type for the {@link h} and {@link s}
- * helpers.
+ * @param specs
+ *
+ * An array of tuples `[metadata, pattern, options?]` where:
+ *
+ * - `metadata`: arbitrary data (e.g., a CSS class name) passed to `decorator` when the pattern matches.
+ * - `pattern`: a `string` (matched literally) or `RegExp` to match against the input.
+ * - `options`: optional {@link LexerSpecOptions} (states in which the spec is active and state transitions).
+ *
+ * @returns
+ *
+ * A lexer function that accepts an input string and returns an array of decorated chunks covering the whole input (in order).
  */
-export type HArgs = [string | Node, ...HArgs1[]];
+export declare const createLexer: <M, T>(
+  decorator: (chunk: string, metadata?: M) => T,
+  ...specs: LexerSpec<M>[]
+) => (code: string) => T[]
+/** Single argument type for the {@link h} and {@link s} helpers. */
+export type HArgs1 = Record<PropertyKey, unknown> | null | undefined | Node | string | number | HArgs
+/** Tuple argument type for the {@link h} and {@link s} helpers. */
+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); 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`.
+ * 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 `true` sets an empty attribute (e.g. `checked=""`), 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 (creates or modifies a child node and appends it).
+ *
+ * @returns
+ *
+ * The created `HTMLElement` or the modified node.
  */
 export declare const h: {
-    <T extends keyof HTMLElementTagNameMap>(tag: T, ...args1: HArgs1[]): HTMLElementTagNameMap[T];
-    <N extends Node>(node: N, ...args1: HArgs1[]): N;
-    (tagOrNode: string | Node, ...args1: HArgs1[]): Node;
-};
+  <T extends keyof HTMLElementTagNameMap>(tag: T, ...args: HArgs1[]): HTMLElementTagNameMap[T]
+  <N extends Node>(node: N, ...args: HArgs1[]): N
+  (tagOrNode: string | Node, ...args: 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); 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`.
+ * 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 `true` sets an empty attribute (e.g. `checked=""`), 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 (creates or modifies a child node and appends it).
+ *
+ * @returns
+ *
+ * The created `SVGElement` or the modified node.
  */
 export declare const s: {
-    <T extends keyof SVGElementTagNameMap>(tag: T, ...args1: HArgs1[]): SVGElementTagNameMap[T];
-    <N extends Node>(node: N, ...args1: HArgs1[]): N;
-    (tagOrNode: string | Node, ...args1: HArgs1[]): Node;
-};
+  <T extends keyof SVGElementTagNameMap>(tag: T, ...args: HArgs1[]): SVGElementTagNameMap[T]
+  <N extends Node>(node: N, ...args: HArgs1[]): N
+  (tagOrNode: string | Node, ...args: 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 a symbol (e.g. an icon) by ID.
  *
  * Equivalent to:
  *
  * ```ts
- * s(
- *   'svg',
- *   ['use', { 'xlink:href': '#' + id }],
- *   ...args
- * )
+ * 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.
+ * @param id
+ *
+ * The ID of the symbol to reference (without the `#` prefix).
+ *
+ * @param args
+ *
+ * Additional arguments passed to the outer `<svg>` element.
+ *
+ * @returns
  *
- * @returns An `SVGSVGElement` containing a `<use>` element.
+ * An `SVGSVGElement` containing a `<use>` element.
  */
-export declare const svgUse: (id: string, ...args: HArgs1[]) => SVGSVGElement;
+export declare const svgUse: (id: string, ...args: HArgs1[]) => SVGSVGElement
 /**
- * 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} lexer.
+ * It styles `pre` and `code>span` elements with the class names produced by {@link nanolightTs} (with light, dark and print variants).
  */
-export declare const monokai: CNode;
+export declare const monokai: CNode
 /**
- * A TypeScript/JavaScript syntax highlighting tokenizer
- * built using {@link createTokenizer}.
+ * A TypeScript/JavaScript syntax highlighting lexer built using {@link createLexer}.
  *
- * @param code The source code string to tokenize.
+ * @param code
  *
- * @returns An array of {@link HArgs1} elements suitable for
- *   rendering with {@link h}.
- */
-export declare const nanolightTs: (code: string) => HArgs1[];
-/**
- * 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.
+ * The source code string to tokenize.
+ *
+ * @returns
+ *
+ * An array of {@link HArgs1} elements suitable for rendering with {@link h}: plain `string`s for unrecognized text (e.g. whitespace) and `['span', { class }, chunk]` tuples for recognized tokens (class names are styled by {@link monokai}).
  */
-export declare const rwd: (root: CNode, selector: string, cellWidthPx: number, cellHeightPx: number, ...specs: [number, number?, number?][]) => void;
+export declare const nanolightTs: (code: string) => HArgs1[]
 /**
- * Generates a UUID v1 (time-based) identifier.
+ * A responsive web design helper that generates CSS rules for a grid-like layout of floating elements.
+ * It modifies `root` in place: it sets base styles for `selector` and adds a `@media(min-width:…px)` rule for each breakpoint.
+ *
+ * @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
  *
- * @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.
+ * An array of breakpoint specifications, each a tuple of:
  *
- * @returns A UUID v1 `string` in the standard format
- *   `xxxxxxxx-xxxx-1xxx-xxxx-xxxxxxxxxxxx`.
+ * - `maxWidth`: number of cells per row; the breakpoint is `min-width: cellWidthPx * maxWidth` (`1` modifies the base rule).
+ * - `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 uuidV1: (date?: Date, node?: string) => string;
+export declare const rwd: (
+  root: CNode,
+  selector: string,
+  cellWidthPx: number,
+  cellHeightPx: number,
+  ...specs: [number, number?, number?][]
+) => void