@jackens/nnn 2026.9.30 → 2026.11.16

package/nnn.d.ts

@@ -1,6 +1,6 @@
 /** 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 | null | undefined
 }
 /**
  * A minimal CSS-in-JS helper that converts a JavaScript object hierarchy into a CSS string.
@@ -10,76 +10,25 @@ export type CNode = {
  * 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`).
+ * If a nested selector contains `&`, every `&` is replaced with the parent selector instead (e.g. `'&:hover'` → `a:hover`, `'.c &'` → `.c a`).
  * 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}`).
+ * Commas inside brackets or quotes (e.g. `':is(.b,.c)'`, `'[title="b,c"]'`) do not separate alternatives; whitespace after a separating comma is ignored (use `&` for a descendant combinator in a non-first alternative, e.g. `'.b,& .c'` → `a.b,a .c`).
+ * At-rules (e.g. `'@media …'`) wrap their nested rules; an at-rule nested in a selector wraps that selector (e.g. `{ a: { '@media(…)': { color: 'red' } } }` → `@media(…){a{color:red}}`).
+ * Inside a top-level `:root` rule nested keys are concatenated into property names (e.g. `{ ':root': { '--': { bg: 'red' } } }` → `:root{--bg:red}`).
+ * Properties without a selector (top-level or directly in a top-level at-rule, e.g. `@font-face`) are emitted as bare declarations.
  * `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`).
+ * An empty `splitter` disables this feature.
  *
  * @returns
  *
  * A CSS string representing the compiled rules.
  */
 export declare const c: (node: CNode, splitter?: string) => string
-/**
- * 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
- *
- * Whether to pop the current state off the stack after a match (the `'root'` state at the bottom is never popped).
- *
- * @property push
- *
- * State to push onto the stack after a match (applied after `pop`).
- */
-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 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.
- * 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.
- *
- * @param decorator
- *
- * 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`.
- *
- * @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 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. */
@@ -97,9 +46,9 @@ export type HArgs = [string | Node, ...HArgs1[]]
  * 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.
+ *   - Keys starting with `$` set element properties (without the `$` prefix); if the value is a plain object (created by `{…}` or `Object.create(null)`), it is shallow-merged into the existing property instead of replacing it (useful e.g. for `$style`), other values (including arrays and class instances) replace the property.
+ *   - Other keys set attributes: a key prefixed with `xlink:`, `xml:` or `xmlns:` sets the attribute via `setAttributeNS` in the corresponding namespace; any other key sets it via `setAttribute`.
+ *     A value of `true` sets an empty attribute (e.g. `checked=""`), a value of `false` removes the attribute, a value of `null`/`undefined` leaves the attribute unchanged.
  * - `null`/`undefined`: ignored.
  * - `Node`: appended as a child.
  * - `string`/`number`: converted to a `Text` node and appended.
@@ -111,6 +60,7 @@ export type HArgs = [string | Node, ...HArgs1[]]
  */
 export declare const h: {
   <T extends keyof HTMLElementTagNameMap>(tag: T, ...args: HArgs1[]): HTMLElementTagNameMap[T]
+  (tag: string, ...args: HArgs1[]): HTMLElement
   <N extends Node>(node: N, ...args: HArgs1[]): N
   (tagOrNode: string | Node, ...args: HArgs1[]): Node
 }
@@ -127,9 +77,9 @@ export declare const h: {
  * 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.
+ *   - Keys starting with `$` set element properties (without the `$` prefix); if the value is a plain object (created by `{…}` or `Object.create(null)`), it is shallow-merged into the existing property instead of replacing it, other values (including arrays and class instances) replace the property.
+ *   - Other keys set attributes: a key prefixed with `xlink:`, `xml:` or `xmlns:` sets the attribute via `setAttributeNS` in the corresponding namespace (e.g. `xml:lang`); any other key sets it via `setAttribute`.
+ *     A value of `true` sets an empty attribute, a value of `false` removes the attribute, a value of `null`/`undefined` leaves the attribute unchanged.
  * - `null`/`undefined`: ignored.
  * - `Node`: appended as a child.
  * - `string`/`number`: converted to a `Text` node and appended.
@@ -141,6 +91,7 @@ export declare const h: {
  */
 export declare const s: {
   <T extends keyof SVGElementTagNameMap>(tag: T, ...args: HArgs1[]): SVGElementTagNameMap[T]
+  (tag: string, ...args: HArgs1[]): SVGElement
   <N extends Node>(node: N, ...args: HArgs1[]): N
   (tagOrNode: string | Node, ...args: HArgs1[]): Node
 }
@@ -150,7 +101,7 @@ export declare const s: {
  * Equivalent to:
  *
  * ```ts
- * s('svg', ['use', { 'xlink:href': '#' + id }], ...args)
+ * s('svg', ['use', { href: '#' + id }], ...args)
  * ```
  *
  * @param id
@@ -166,23 +117,6 @@ export declare const s: {
  * An `SVGSVGElement` containing a `<use>` element.
  */
 export declare const svgUse: (id: string, ...args: HArgs1[]) => SVGSVGElement
-/**
- * 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
-/**
- * A TypeScript/JavaScript syntax highlighting lexer built using {@link createLexer}.
- *
- * @param code
- *
- * 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 nanolightTs: (code: string) => HArgs1[]
 /**
  * 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.
@@ -197,24 +131,28 @@ export declare const nanolightTs: (code: string) => HArgs1[]
  *
  * @param cellWidthPx
  *
- * The base cell width in pixels.
+ * The base cell width in pixels (a positive number).
  *
  * @param cellHeightPx
  *
- * The base cell height in pixels.
+ * The base cell height in pixels (a positive number).
  *
  * @param specs
  *
- * An array of breakpoint specifications, each a tuple of:
+ * An array of breakpoint specifications, each a tuple of positive integers:
  *
- * - `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.
+ * - `columns`: number of cells per row; the breakpoint is `min-width: cellWidthPx * columns` (`1` modifies the base rule).
+ * - `width` (optional, default `1`, at most `columns`): number of horizontal cells the element spans.
  * - `height` (optional, default `1`): number of vertical cells the element spans.
+ *
+ * @throws
+ *
+ * A `RangeError` if any of the numeric arguments is out of range.
  */
 export declare const rwd: (
   root: CNode,
   selector: string,
   cellWidthPx: number,
   cellHeightPx: number,
-  ...specs: [number, number?, number?][]
+  ...specs: [columns: number, width?: number, height?: number][]
 ) => void