@jackens/nnn 2026.10.1 → 2026.11.17

package/README.md

@@ -1,6 +1,6 @@
 # nnn
 
-A collection of Jackens’ JavaScript helper utilities (version: `2026.10.1`).
+A collection of Jackens’ JavaScript helper utilities (version: `2026.11.17`).
 
 ## Installation
 
@@ -18,9 +18,9 @@ npm i @jackens/nnn
 
 ```js
 import {
-  CNode,
-  HArgs,
-  HArgs1,
+  type CNode,
+  type HArgs,
+  type HArgs1,
   c,
   h,
   rwd,
@@ -52,7 +52,7 @@ import {
 
 ```ts
 type CNode = {
-  [attributeOrSelector: string]: string | number | CNode | undefined
+  [attributeOrSelector: string]: string | number | CNode | null | undefined
 }
 ```
 
@@ -87,14 +87,20 @@ A minimal CSS-in-JS helper that converts a JavaScript object hierarchy into a CS
 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 belongs to the next alternative, so like a leading space of the first one it makes a descendant combinator when nested (e.g. `' .b, .c'` → `a .b,a .c`, `'.b, .c'` → `a.b,a .c`); leading whitespace of a resulting selector is ignored (e.g. `'h1, h2'` → `h1,h2`, `'.b, &:hover'` → `a.b,a:hover`).
+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.
 
 #### 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
 
@@ -169,7 +175,7 @@ const actual = c({
   '@font-face$$1': {
     'font-family': 'Jackens',
     src$$1: 'url(otf/jackens.otf)',
-    src$$2: "url(otf/jackens.otf) format('opentype')," + "url(svg/jackens.svg) format('svg')",
+    src$$2: "url(otf/jackens.otf) format('opentype'),url(svg/jackens.svg) format('svg')",
     'font-weight': 'normal',
     'font-style': 'normal',
   },
@@ -405,13 +411,156 @@ const expected = `
 expect(actual).toBe(expected)
 ```
 
+`&` is replaced with the parent selector:
+
+```ts
+const actual = c({
+  a: {
+    color: 'red',
+    '&:hover': { color: 'blue' },
+    '.dark &': { color: 'white' },
+    '.b,& .c': { margin: 1 },
+  },
+})
+
+const expected = `
+  a{
+    color:red
+  }
+  a:hover{
+    color:blue
+  }
+  .dark a{
+    color:white
+  }
+  a.b,a .c{
+    margin:1
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+Commas inside brackets or quotes do not split selectors:
+
+```ts
+const actual = c({
+  ':is(.a,.b)': {
+    '.c,.d': { margin: 1 },
+    '[title="x,y"]': { margin: 2 },
+  },
+})
+
+const expected = `
+  :is(.a,.b).c,:is(.a,.b).d{
+    margin:1
+  }
+  :is(.a,.b)[title="x,y"]{
+    margin:2
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+Whitespace after a comma is kept, but leading whitespace of a resulting selector is ignored:
+
+```ts
+const actual = c({
+  'h1, h2': {
+    margin: 0,
+    ' .a, .b': { margin: 1 },
+    '.c, .d , &:hover': { margin: 2 },
+  },
+})
+
+const expected = `
+  h1,h2{
+    margin:0
+  }
+  h1 .a,h1 .b,h2 .a,h2 .b{
+    margin:1
+  }
+  h1.c,h1 .d,h1:hover,h2.c,h2 .d,h2:hover{
+    margin:2
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+At-rules nested in selectors wrap these selectors:
+
+```ts
+const actual = c({
+  a: {
+    color: 'red',
+    '@media(min-width:600px)': {
+      color: 'blue',
+      '.b': { margin: 1 },
+    },
+  },
+})
+
+const expected = `
+  a{
+    color:red
+  }
+  @media(min-width:600px){
+    a{
+      color:blue
+    }
+    a.b{
+      margin:1
+    }
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+Declarations without a selector are separated from subsequent rules:
+
+```ts
+expect(c({ color: 'red', margin: 0 })).toBe('color:red;margin:0')
+
+expect(c({ color: 'red', a: { margin: 0 }, padding: 0 })).toBe('color:red;a{margin:0}padding:0')
+```
+
+`null` and `undefined` values are skipped:
+
+```ts
+const actual = c({
+  a: {
+    color: 'red',
+    margin: null,
+    padding: undefined,
+    '.b': null,
+  },
+  ':root': {
+    '--': { bg: null, fg: 'black' },
+  },
+})
+
+expect(actual).toBe('a{color:red}:root{--fg:black}')
+```
+
+Custom splitter (an empty one disables splitting):
+
+```ts
+expect(c({ a: { 'src#1': 'url(a.otf)', 'src#2': 'url(a.woff)' } }, '#')).toBe('a{src:url(a.otf);src:url(a.woff)}')
+
+expect(c({ a: { b$$c: 1 } }, '')).toBe('a{b$$c:1}')
+```
+
 ### h
 
 ```ts
 const h: {
   <T extends keyof HTMLElementTagNameMap>(tag: T, ...args: HArgs1[]): HTMLElementTagNameMap[T]
   <N extends Node>(node: N, ...args: HArgs1[]): N
-  (tagOrNode: string | Node, ...args: HArgs1[]): Node
+  (tag: string, ...args: HArgs1[]): HTMLElement
+  (node: Node, ...args: HArgs1[]): Node
 }
 ```
 
@@ -427,9 +576,9 @@ If a `Node`, that node is modified in place.
 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.
@@ -453,13 +602,11 @@ const i = h('i', 'text')
 h(b, i)
 
 expect(i.outerHTML).toBe('<i>text</i>')
-
 expect(b.outerHTML).toBe('<b><i>text</i></b>')
 
 h(i, { $className: 'some class' })
 
 expect(i.outerHTML).toBe('<i class="some class">text</i>')
-
 expect(b.outerHTML).toBe('<b><i class="some class">text</i></b>')
 ```
 
@@ -467,11 +614,9 @@ Text content from strings, numbers and `$innerText`:
 
 ```ts
 expect(h('span', 'text').outerHTML).toBe('<span>text</span>')
-
 expect(h('span', { $innerText: 'text' }).outerHTML).toBe('<span>text</span>')
 
 expect(h('span', '42').outerHTML).toBe('<span>42</span>')
-
 expect(h('span', 42).outerHTML).toBe('<span>42</span>')
 ```
 
@@ -479,9 +624,7 @@ expect(h('span', 42).outerHTML).toBe('<span>42</span>')
 
 ```ts
 expect(h('div', { style: 'margin:0;padding:0' }).outerHTML).toBe('<div style="margin:0;padding:0"></div>')
-
 expect(h('div', { $style: 'margin:0;padding:0' }).outerHTML).toBe('<div style="margin: 0px; padding: 0px;"></div>')
-
 expect(h('div', { $style: { margin: 0, padding: 0 } }).outerHTML).toBe(
   '<div style="margin: 0px; padding: 0px;"></div>'
 )
@@ -517,14 +660,13 @@ expect(checkbox1.checked).toBe(true)
 expect(checkbox2.checked).toBe(true)
 
 expect(checkbox1.outerHTML).toBe('<input type="checkbox" checked="">')
-
 expect(checkbox2.outerHTML).toBe('<input type="checkbox">')
 ```
 
 Object values of `$`-prefixed properties are merged:
 
 ```ts
-const div = h('div')
+const div = h('div') as any
 
 expect(div.key).toBeUndefined()
 
@@ -555,6 +697,46 @@ const elemWithNested = h('div', ['span', 'hello'], ['b', 'world'])
 expect(elemWithNested.outerHTML).toBe('<div><span>hello</span><b>world</b></div>')
 ```
 
+`false` removes an attribute, `null` and `undefined` leave it unchanged:
+
+```ts
+const input = h('input', { type: 'checkbox', checked: true, title: 'title' })
+
+h(input, { checked: false, title: null, type: undefined })
+
+expect(input.outerHTML).toBe('<input type="checkbox" title="title">')
+```
+
+Only plain objects are merged into `$`-prefixed properties:
+
+```ts
+const date = new Date(0)
+const div = h('div', { $date: date, $list: [1, 2] }) as any
+
+expect(div.date).toBe(date)
+
+h(div, { $list: [3] })
+
+expect(div.list).toEqual([3])
+```
+
+Namespaced attributes:
+
+```ts
+const div = h('div', { 'xml:lang': 'pl', 'ng:x': 1 })
+
+expect(div.getAttributeNS('http://www.w3.org/XML/1998/namespace', 'lang')).toBe('pl')
+expect(div.getAttribute('ng:x')).toBe('1')
+```
+
+Return types:
+
+```ts
+expectTypeOf(h('input')).toEqualTypeOf<HTMLInputElement>()
+expectTypeOf(h('my-element')).toEqualTypeOf<HTMLElement>()
+expectTypeOf(h(document.createTextNode(''))).toEqualTypeOf<Text>()
+```
+
 ### rwd
 
 ```ts
@@ -563,7 +745,7 @@ const rwd: (
   selector: string,
   cellWidthPx: number,
   cellHeightPx: number,
-  ...specs: [number, number?, number?][]
+  ...specs: [columns: number, width?: number, height?: number][]
 ) => void
 ```
 
@@ -580,20 +762,24 @@ The CSS selector for the grid item.
 
 #### cellWidthPx
 
-The base cell width in pixels.
+The base cell width in pixels (a positive number).
 
 #### cellHeightPx
 
-The base cell height in pixels.
+The base cell height in pixels (a positive number).
 
 #### 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.
+
 #### Usage Examples
 
 Responsive grid cell widths and heights with media queries:
@@ -643,13 +829,59 @@ expect(style).toEqual({
 })
 ```
 
+Widths that divide evenly do not use `calc`; existing at-rules are extended:
+
+```ts
+const style: CNode = {
+  '@media(min-width:400px)': {
+    '.r2': { margin: 0 },
+  },
+}
+
+rwd(style, '.r2', 100, 40, [4, 2], [2, 2, 3])
+
+expect(style).toEqual({
+  '@media(min-width:400px)': {
+    '.r2': {
+      margin: 0,
+      width: '50%',
+      height: '40px',
+    },
+  },
+  '.r2': {
+    'box-sizing': 'border-box',
+    display: 'block',
+    float: 'left',
+    width: '100%',
+    height: '40px',
+  },
+  '@media(min-width:200px)': {
+    '.r2': {
+      width: '100%',
+      height: '120px',
+    },
+  },
+})
+```
+
+Invalid arguments throw a `RangeError`:
+
+```ts
+expect(() => rwd({}, '.x', 0, 50)).toThrow(RangeError)
+expect(() => rwd({}, '.x', 100, Infinity)).toThrow(RangeError)
+expect(() => rwd({}, '.x', 100, 50, [0])).toThrow(RangeError)
+expect(() => rwd({}, '.x', 100, 50, [2, 3])).toThrow(RangeError)
+expect(() => rwd({}, '.x', 100, 50, [2, 1, 1.5])).toThrow(RangeError)
+```
+
 ### s
 
 ```ts
 const s: {
   <T extends keyof SVGElementTagNameMap>(tag: T, ...args: HArgs1[]): SVGElementTagNameMap[T]
   <N extends Node>(node: N, ...args: HArgs1[]): N
-  (tagOrNode: string | Node, ...args: HArgs1[]): Node
+  (tag: string, ...args: HArgs1[]): SVGElement
+  (node: Node, ...args: HArgs1[]): Node
 }
 ```
 
@@ -665,9 +897,9 @@ If a `Node`, that node is modified in place.
 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.
@@ -679,6 +911,16 @@ The created `SVGElement` or the modified node.
 
 #### Usage Examples
 
+Elements (including nested ones) are created in the SVG namespace:
+
+```ts
+const svg = s('svg', ['g', ['circle', { r: 1 }]])
+
+expect(svg.namespaceURI).toBe('http://www.w3.org/2000/svg')
+expect(svg.querySelector('circle')?.namespaceURI).toBe('http://www.w3.org/2000/svg')
+expect(svg.outerHTML).toBe('<svg><g><circle r="1"></circle></g></svg>')
+```
+
 Namespaced `xlink:` attribute set to `true` gets an empty value:
 
 ```ts
@@ -687,10 +929,12 @@ const svg = s('svg', { 'xlink:href': true })
 expect(svg.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('')
 ```
 
-Namespaced `xlink:` attribute set to `false` is not set:
+Namespaced `xlink:` attribute set to `false` is removed:
 
 ```ts
-const svg = s('svg', { 'xlink:href': false })
+const svg = s('svg', { 'xlink:href': '#id' })
+
+s(svg, { 'xlink:href': false })
 
 expect(svg.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBeNull()
 ```
@@ -711,6 +955,22 @@ const svg = s('svg', { 'xlink:title': 42 })
 expect(svg.getAttributeNS('http://www.w3.org/1999/xlink', 'title')).toBe('42')
 ```
 
+Namespaced `xml:` and `xmlns:` attributes:
+
+```ts
+const svg = s('svg', { 'xml:lang': 'pl', 'xmlns:xlink': 'http://www.w3.org/1999/xlink' })
+
+expect(svg.getAttributeNS('http://www.w3.org/XML/1998/namespace', 'lang')).toBe('pl')
+expect(svg.getAttributeNS('http://www.w3.org/2000/xmlns/', 'xlink')).toBe('http://www.w3.org/1999/xlink')
+```
+
+Return types:
+
+```ts
+expectTypeOf(s('circle')).toEqualTypeOf<SVGCircleElement>()
+expectTypeOf(s('my-element')).toEqualTypeOf<SVGElement>()
+```
+
 ### svgUse
 
 ```ts
@@ -722,7 +982,7 @@ Shorthand for creating an `<svg>` element with a `<use>` child referencing a sym
 Equivalent to:
 
 ```ts
-s('svg', ['use', { 'xlink:href': '#' + id }], ...args)
+s('svg', ['use', { href: '#' + id }], ...args)
 ```
 
 #### id
@@ -739,46 +999,28 @@ An `SVGSVGElement` containing a `<use>` element.
 
 #### Usage Examples
 
-SVG `use` element referencing a symbol, with extra attributes:
+SVG `use` element referencing a symbol:
 
 ```ts
 const svg = svgUse('icon-home')
 
-expect(svg.children.length).toBe(1)
-
-const useElement = svg.children[0]
-
-expect(useElement.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('#icon-home')
-
-const svgWithViewBox = svgUse('icon-star', { viewBox: '0 0 24 24' })
-
-expect(svgWithViewBox.getAttribute('viewBox')).toBe('0 0 24 24')
-
-const useViewBox = svgWithViewBox.children[0]
-
-expect(useViewBox.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('#icon-star')
-
-const svgWithClass = svgUse('icon-menu', { class: 'icon-btn' })
-
-expect(svgWithClass.getAttribute('class')).toBe('icon-btn')
-
-expect(svgWithClass.children.length).toBe(1)
-
-const useClass = svgWithClass.children[0]
-
-expect(useClass.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('#icon-menu')
+expect(svg.outerHTML).toBe('<svg><use href="#icon-home"></use></svg>')
+```
 
-const svgWithMultipleAttrs = svgUse('icon-settings', { width: 24, height: 24, class: 'icon' })
+Additional attributes are set on the outer `svg` element:
 
-expect(svgWithMultipleAttrs.getAttribute('width')).toBe('24')
+```ts
+const svg = svgUse('icon-settings', { width: 24, height: 24, class: 'icon' })
 
-expect(svgWithMultipleAttrs.getAttribute('height')).toBe('24')
+expect(svg.outerHTML).toBe('<svg width="24" height="24" class="icon"><use href="#icon-settings"></use></svg>')
+```
 
-expect(svgWithMultipleAttrs.getAttribute('class')).toBe('icon')
+Additional children are appended to the outer `svg` element:
 
-const useMultiple = svgWithMultipleAttrs.children[0]
+```ts
+const svg = svgUse('icon-star', ['title', 'Star'])
 
-expect(useMultiple.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('#icon-settings')
+expect(svg.outerHTML).toBe('<svg><use href="#icon-star"></use><title>Star</title></svg>')
 ```
 
 ## License

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,14 +10,20 @@ 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 belongs to the next alternative, so like a leading space of the first one it makes a descendant combinator when nested (e.g. `' .b, .c'` → `a .b,a .c`, `'.b, .c'` → `a.b,a .c`); leading whitespace of a resulting selector is ignored (e.g. `'h1, h2'` → `h1,h2`, `'.b, &:hover'` → `a.b,a:hover`).
+ * 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
  *
@@ -41,9 +47,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.
@@ -56,7 +62,8 @@ export type HArgs = [string | Node, ...HArgs1[]]
 export declare const h: {
   <T extends keyof HTMLElementTagNameMap>(tag: T, ...args: HArgs1[]): HTMLElementTagNameMap[T]
   <N extends Node>(node: N, ...args: HArgs1[]): N
-  (tagOrNode: string | Node, ...args: HArgs1[]): Node
+  (tag: string, ...args: HArgs1[]): HTMLElement
+  (node: Node, ...args: HArgs1[]): Node
 }
 /**
  * A lightweight _HyperScript_-style helper for creating and modifying `SVGElement`s (see also {@link h}).
@@ -71,9 +78,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.
@@ -86,7 +93,8 @@ export declare const h: {
 export declare const s: {
   <T extends keyof SVGElementTagNameMap>(tag: T, ...args: HArgs1[]): SVGElementTagNameMap[T]
   <N extends Node>(node: N, ...args: HArgs1[]): N
-  (tagOrNode: string | Node, ...args: HArgs1[]): Node
+  (tag: string, ...args: HArgs1[]): SVGElement
+  (node: Node, ...args: HArgs1[]): Node
 }
 /**
  * Shorthand for creating an `<svg>` element with a `<use>` child referencing a symbol (e.g. an icon) by ID.
@@ -94,7 +102,7 @@ export declare const s: {
  * Equivalent to:
  *
  * ```ts
- * s('svg', ['use', { 'xlink:href': '#' + id }], ...args)
+ * s('svg', ['use', { href: '#' + id }], ...args)
  * ```
  *
  * @param id
@@ -124,24 +132,28 @@ export declare const svgUse: (id: string, ...args: HArgs1[]) => SVGSVGElement
  *
  * @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

package/nnn.js

@@ -1,114 +1,174 @@
-// src/nnn/c.ts
+// src/c.ts
 var DEFAULT_SPLITTER = "$$";
-var combinePrefixAndName = (prefix, name) => {
-  const prefixes = prefix === "" ? [""] : prefix.split(",");
-  const names = name.split(",");
-  const combined = [];
-  for (const p of prefixes) {
-    for (const n of names) {
-      combined.push(p + n);
+var OPENING_BRACKETS = "([";
+var CLOSING_BRACKETS = ")]";
+var scan = (selector, onChar) => {
+  let depth = 0;
+  let quote = "";
+  for (const char of selector) {
+    if (quote !== "") {
+      if (char === quote) {
+        quote = "";
+      }
+    } else if (char === '"' || char === "'") {
+      quote = char;
+    } else if (OPENING_BRACKETS.includes(char)) {
+      ++depth;
+    } else if (CLOSING_BRACKETS.includes(char)) {
+      --depth;
+    }
+    onChar(char, quote === "" && depth === 0);
+  }
+};
+var splitSelectorList = (selectorList) => {
+  const selectors = [""];
+  scan(selectorList, (char, topLevel) => {
+    if (topLevel && char === ",") {
+      selectors.push("");
+    } else {
+      selectors[selectors.length - 1] += char;
+    }
+  });
+  return selectors.map((selector) => selector.trimEnd());
+};
+var nestSelector = (parent, selector) => {
+  let nested = "";
+  let ampersandFound = false;
+  scan(selector, (char, topLevel) => {
+    if (char === "&" && topLevel) {
+      nested += parent;
+      ampersandFound = true;
+    } else {
+      nested += char;
+    }
+  });
+  return (ampersandFound ? nested : parent + selector).trimStart();
+};
+var stripSplitter = (key, splitter) => {
+  const splitterIndex = splitter === "" ? -1 : key.indexOf(splitter);
+  return splitterIndex < 0 ? key : key.slice(0, splitterIndex);
+};
+var cProperties = (node, splitter, prefix) => {
+  const out = [];
+  for (const [key, value] of Object.entries(node)) {
+    if (value != null) {
+      const name = prefix + stripSplitter(key, splitter);
+      if (typeof value === "object") {
+        out.push(...cProperties(value, splitter, name));
+      } else {
+        out.push(`${name}:${value}`);
+      }
     }
   }
-  return combined.join(",");
+  return out;
 };
-var _c = (node, splitter = DEFAULT_SPLITTER, prefix = "", flatten = false) => {
+var cRules = (node, splitter, selectors) => {
   const out = [];
-  let buffer = [];
+  let declarations = [];
   const flush = () => {
-    if (buffer.length === 0) {
-      return;
+    if (declarations.length > 0) {
+      out.push(selectors.length === 0 ? `${declarations.join(";")};` : `${selectors.join(",")}{${declarations.join(";")}}`);
+      declarations = [];
     }
-    out.push(prefix === "" ? buffer.join(";") : `${prefix}{${buffer.join(";")}}`);
-    buffer = [];
   };
-  for (const [rawKey, value] of Object.entries(node)) {
+  for (const [key, value] of Object.entries(node)) {
     if (value == null) {
       continue;
     }
-    const splitterIndex = rawKey.indexOf(splitter);
-    const name = splitterIndex < 0 ? rawKey : rawKey.slice(0, splitterIndex);
-    if (typeof value === "number" || typeof value === "string") {
-      if (flatten) {
-        out.push(`${prefix + name}:${value}`);
-      } else {
-        buffer.push(`${name}:${value}`);
-      }
-      continue;
-    }
-    if (flatten) {
-      out.push(_c(value, splitter, prefix + name, true));
+    const name = stripSplitter(key, splitter);
+    if (typeof value !== "object") {
+      declarations.push(`${name}:${value}`);
       continue;
     }
     flush();
-    if (prefix === "" && (name === ":root" || name[0] === "@")) {
-      out.push(`${name}{${_c(value, splitter, "", name === ":root")}}`);
+    if (name[0] === "@") {
+      out.push(`${name}{${cRules(value, splitter, selectors)}}`);
+    } else if (selectors.length === 0 && name === ":root") {
+      out.push(`:root{${cProperties(value, splitter, "").join(";")}}`);
     } else {
-      out.push(_c(value, splitter, combinePrefixAndName(prefix, name), false));
+      const alternatives = splitSelectorList(name);
+      const parents = selectors.length === 0 ? [""] : selectors;
+      out.push(cRules(value, splitter, parents.flatMap((parent) => alternatives.map((selector) => nestSelector(parent, selector)))));
     }
   }
   flush();
-  return out.join(flatten ? ";" : "");
+  const css = out.join("");
+  return css.endsWith(";") ? css.slice(0, -1) : css;
+};
+var c = (node, splitter = DEFAULT_SPLITTER) => cRules(node, splitter, []);
+// src/h.ts
+var SVG_NS = "http://www.w3.org/2000/svg";
+var NAMESPACES = {
+  xlink: "http://www.w3.org/1999/xlink",
+  xml: "http://www.w3.org/XML/1998/namespace",
+  xmlns: "http://www.w3.org/2000/xmlns/"
+};
+var isPlainObject = (value) => {
+  if (typeof value !== "object" || value == null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype == null;
+};
+var setAttribute = (element, name, value) => {
+  if (value == null) {
+    return;
+  }
+  const indexOfColon = name.indexOf(":");
+  const namespace = indexOfColon < 0 ? undefined : NAMESPACES[name.slice(0, indexOfColon)];
+  if (namespace == null) {
+    if (value === false) {
+      element.removeAttribute(name);
+    } else {
+      element.setAttribute(name, value === true ? "" : String(value));
+    }
+  } else if (value === false) {
+    element.removeAttributeNS(namespace, name.slice(indexOfColon + 1));
+  } else {
+    element.setAttributeNS(namespace, name, value === true ? "" : String(value));
+  }
 };
-var c = (node, splitter = DEFAULT_SPLITTER) => _c(node, splitter);
-// src/nnn/h.ts
-var XLINK_NS = "http://www.w3.org/1999/xlink";
-var _h = (createElement, tagOrNode, ...args) => {
+var hyperscript = (createElement, tagOrNode, ...args) => {
   const node = typeof tagOrNode === "string" ? createElement(tagOrNode) : tagOrNode;
-  args.forEach((arg) => {
-    let child = null;
+  for (const arg of args) {
     if (arg instanceof Node) {
-      child = arg;
+      node.appendChild(arg);
     } else if (Array.isArray(arg)) {
-      child = _h(createElement, ...arg);
+      node.appendChild(hyperscript(createElement, ...arg));
     } else if (typeof arg === "string" || typeof arg === "number") {
-      child = document.createTextNode(arg);
-    } else if (typeof arg === "object" && arg != null) {
+      node.appendChild(document.createTextNode(String(arg)));
+    } else if (arg != null) {
       for (const name in arg) {
         const value = arg[name];
         if (name[0] === "$") {
           const name1 = name.slice(1);
-          if (typeof value === "object" && value != null && !Array.isArray(value)) {
+          if (isPlainObject(value)) {
             Object.assign(node[name1] ??= {}, value);
           } else {
             node[name1] = value;
           }
         } else if (node instanceof Element) {
-          const indexOfColon = name.indexOf(":");
-          if (indexOfColon >= 0) {
-            const nsKey = name.slice(0, indexOfColon);
-            if (nsKey === "xlink") {
-              const basename = name.slice(indexOfColon + 1);
-              if (value === true) {
-                node.setAttributeNS(XLINK_NS, basename, "");
-              } else if (value === false) {
-                node.removeAttributeNS(XLINK_NS, basename);
-              } else {
-                node.setAttributeNS(XLINK_NS, basename, "" + value);
-              }
-            }
-          } else {
-            if (value === true) {
-              node.setAttribute(name, "");
-            } else if (value === false) {
-              node.removeAttribute(name);
-            } else {
-              node.setAttribute(name, "" + value);
-            }
-          }
+          setAttribute(node, name, value);
         }
       }
     }
-    if (child != null) {
-      node.appendChild(child);
-    }
-  });
+  }
   return node;
 };
-var h = _h.bind(null, (tag) => document.createElement(tag));
-var s = _h.bind(null, (tag) => document.createElementNS("http://www.w3.org/2000/svg", tag));
-var svgUse = (id, ...args) => s("svg", ["use", { "xlink:href": "#" + id }], ...args);
-// src/nnn/rwd.ts
+var h = hyperscript.bind(null, (tag) => document.createElement(tag));
+var s = hyperscript.bind(null, (tag) => document.createElementNS(SVG_NS, tag));
+var svgUse = (id, ...args) => s("svg", ["use", { href: "#" + id }], ...args);
+// src/rwd.ts
+var isPositiveInteger = (value) => Number.isInteger(value) && value > 0;
 var rwd = (root, selector, cellWidthPx, cellHeightPx, ...specs) => {
+  if (!(cellWidthPx > 0 && cellHeightPx > 0 && Number.isFinite(cellWidthPx) && Number.isFinite(cellHeightPx))) {
+    throw new RangeError(`rwd: cell size must be positive: ${cellWidthPx}×${cellHeightPx}`);
+  }
+  for (const [columns, width = 1, height = 1] of specs) {
+    if (!isPositiveInteger(columns) || !isPositiveInteger(width) || !isPositiveInteger(height) || width > columns) {
+      throw new RangeError(`rwd: invalid spec: [${columns}, ${width}, ${height}]`);
+    }
+  }
   const main = root[selector] ??= {};
   main["box-sizing"] = "border-box";
   main.display = "block";
@@ -116,18 +176,16 @@ var rwd = (root, selector, cellWidthPx, cellHeightPx, ...specs) => {
   main.width = "100%";
   main.height = `${cellHeightPx}px`;
   specs.sort(([a], [b]) => a - b);
-  for (let [maxWidth, width, height] of specs) {
-    const atRule = `@media(min-width:${cellWidthPx * maxWidth}px)`;
-    const node = maxWidth === 1 ? main : (root[atRule] ??= {})[selector] ??= {};
-    width ??= 1;
-    height ??= 1;
+  for (const [columns, width = 1, height = 1] of specs) {
+    const atRule = `@media(min-width:${cellWidthPx * columns}px)`;
+    const node = columns === 1 ? main : (root[atRule] ??= {})[selector] ??= {};
     let gcd = 100 * width;
-    let tmp = maxWidth;
+    let tmp = columns;
     while (tmp > 0) {
       [gcd, tmp] = [tmp, gcd % tmp];
     }
     const widthOverGcd = 100 * width / gcd;
-    node.width = maxWidth === gcd ? `${widthOverGcd}%` : `calc(${widthOverGcd}% / ${maxWidth / gcd})`;
+    node.width = columns === gcd ? `${widthOverGcd}%` : `calc(${widthOverGcd}% / ${columns / gcd})`;
     node.height = `${cellHeightPx * height}px`;
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackens/nnn",
-  "version": "2026.10.1",
+  "version": "2026.11.17",
   "description": "Jackens’ JavaScript helpers.",
   "keywords": [
     "CSS-in-JS",
@@ -14,5 +14,16 @@
   "author": "Jackens",
   "type": "module",
   "main": "nnn.js",
-  "types": "nnn.d.ts"
+  "types": "nnn.d.ts",
+  "exports": {
+    ".": {
+      "types": "./nnn.d.ts",
+      "default": "./nnn.js"
+    }
+  },
+  "files": [
+    "nnn.d.ts",
+    "nnn.js"
+  ],
+  "sideEffects": false
 }