@jackens/nnn 2026.2.27 → 2026.4.11

package/nnn.d.ts

@@ -128,6 +128,24 @@ export declare const s: {
     <N extends Node>(node: N, ...args1: HArgs1[]): N;
     (tagOrNode: string | Node, ...args1: HArgs1[]): Node;
 };
+/**
+ * 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 svgUse: (id: string, ...args: HArgs1[]) => SVGSVGElement;
 /**
  * Checks whether an object has the specified key as its own property.
  *
@@ -381,24 +399,6 @@ export declare const pick: <T, K extends keyof T>(ref: T, keys: K[]) => Pick<T,
  * - `height` (optional, default `1`): number of vertical cells the element spans.
  */
 export declare const rwd: (root: CRoot, selector: string, cellWidthPx: number, cellHeightPx: number, ...specs: [number, number?, number?][]) => void;
-/**
- * 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 svgUse: (id: string, ...args: HArgs1[]) => SVGSVGElement;
 /**
  * Generates a UUID v1 (time-based) identifier.
  *

package/nnn.js

@@ -66,66 +66,64 @@ var csvParse = (csv, separator = ",") => {
 var isRecord = (arg) => typeof arg === "object" && arg != null && !isArray(arg);
 
 // src/nnn/h.ts
-var _h = (namespaceUri) => {
+var XLINK_NS = "http://www.w3.org/1999/xlink";
+var _h = (namespaceUri, tagOrNode, ...args) => {
   const createElement = namespaceUri == null ? (tag) => document.createElement(tag) : (tag) => document.createElementNS(namespaceUri, tag);
-  const h = (tagOrNode, ...args) => {
-    const node = isString(tagOrNode) ? createElement(tagOrNode) : tagOrNode;
-    args.forEach((arg) => {
-      let child = null;
-      if (arg instanceof Node) {
-        child = arg;
-      } else if (isArray(arg)) {
-        child = h(...arg);
-      } else if (isRecord(arg)) {
-        for (const name in arg) {
-          const value = arg[name];
-          if (name[0] === "$") {
-            const name1 = name.slice(1);
-            if (isRecord(value)) {
-              node[name1] ??= {};
-              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 ns = "http://www.w3.org/1999/xlink";
-                const basename = name.slice(indexOfColon + 1);
-                if (value === true) {
-                  node.setAttributeNS(ns, basename, "");
-                } else if (value === false) {
-                  node.removeAttributeNS(ns, basename);
-                } else {
-                  node.setAttributeNS(ns, basename, "" + value);
-                }
-              }
-            } else {
+  const node = isString(tagOrNode) ? createElement(tagOrNode) : tagOrNode;
+  args.forEach((arg) => {
+    let child = null;
+    if (arg instanceof Node) {
+      child = arg;
+    } else if (isArray(arg)) {
+      child = _h(namespaceUri, ...arg);
+    } else if (isRecord(arg)) {
+      for (const name in arg) {
+        const value = arg[name];
+        if (name[0] === "$") {
+          const name1 = name.slice(1);
+          if (isRecord(value)) {
+            node[name1] ??= {};
+            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.setAttribute(name, "");
+                node.setAttributeNS(XLINK_NS, basename, "");
               } else if (value === false) {
-                node.removeAttribute(name);
+                node.removeAttributeNS(XLINK_NS, basename);
               } else {
-                node.setAttribute(name, "" + value);
+                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);
+            }
           }
         }
-      } else if (isString(arg) || isNumber(arg)) {
-        child = document.createTextNode(arg);
-      }
-      if (child != null) {
-        node.appendChild(child);
       }
-    });
-    return node;
-  };
-  return h;
+    } else if (isString(arg) || isNumber(arg)) {
+      child = document.createTextNode(arg);
+    }
+    if (child != null) {
+      node.appendChild(child);
+    }
+  });
+  return node;
 };
-var h = /* @__PURE__ */ _h();
-var s = /* @__PURE__ */ _h("http://www.w3.org/2000/svg");
+var h = _h.bind(null, null);
+var s = _h.bind(null, "http://www.w3.org/2000/svg");
+var svgUse = (id, ...args) => s("svg", ["use", { "xlink:href": "#" + id }], ...args);
 
 // src/nnn/fixPlTypography.ts
 var TAGS_TO_SKIP = ["IFRAME", "NOSCRIPT", "PRE", "SCRIPT", "STYLE", "TEXTAREA"];
@@ -351,8 +349,6 @@ var rwd = (root, selector, cellWidthPx, cellHeightPx, ...specs) => {
     node.height = `${cellHeightPx * height}px`;
   }
 };
-// src/nnn/svgUse.ts
-var svgUse = (id, ...args) => s("svg", ["use", { "xlink:href": "#" + id }], ...args);
 // src/nnn/uuidV1.ts
 var ZEROS = /* @__PURE__ */ "0".repeat(16);
 var counter = 0;

package/package.json

@@ -44,5 +44,5 @@
   "name": "@jackens/nnn",
   "type": "module",
   "types": "nnn.d.ts",
-  "version": "2026.2.27"
+  "version": "2026.4.11"
 }

package/readme.md

@@ -1,6 +1,6 @@
 # nnn
 
-A collection of Jackens’ JavaScript helper utilities (version: `2026.2.27`).
+A collection of Jackens’ JavaScript helper utilities (version: `2026.4.11`).
 
 ## Installation
 
@@ -149,8 +149,8 @@ const actual1 = c({
     color: 'red',
     margin: 1,
     '.c': { margin: 2, padding: 2 },
-    padding: 1
-  }
+    padding: 1,
+  },
 })
 
 const expected1 = `
@@ -174,9 +174,9 @@ const actual2 = c({
       color: 'red',
       margin: 1,
       '.c': { margin: 2, padding: 2 },
-      padding: 1
-    }
-  }
+      padding: 1,
+    },
+  },
 })
 
 const expected2 = `
@@ -201,26 +201,26 @@ const actual3 = c({
     src$$2: "url(otf/jackens.otf) format('opentype')," +
       "url(svg/jackens.svg) format('svg')",
     font_weight: 'normal',
-    'font-style': 'normal'
+    'font-style': 'normal',
   },
   '@font-face$$2': {
     font_family: 'C64',
-    src: 'url(fonts/C64_Pro_Mono-STYLE.woff)'
+    src: 'url(fonts/C64_Pro_Mono-STYLE.woff)',
   },
   '@keyframes spin': {
     '0%': { transform: 'rotate(0deg)' },
-    '100%': { transform: 'rotate(360deg)' }
+    '100%': { transform: 'rotate(360deg)' },
   },
   div: {
     border: 'solid red 1px',
     '.c1': { 'background-color': '#000' },
     ' .c1': { background_color: 'black' },
-    '.c2': { backgroundColor: 'rgb(0,0,0)' }
+    '.c2': { backgroundColor: 'rgb(0,0,0)' },
   },
   '@media(min-width:200px)': {
     div: { margin: 0, padding: 0 },
-    span: { color: '#000' }
-  }
+    span: { color: '#000' },
+  },
 })
 
 const expected3 = `
@@ -272,10 +272,10 @@ const actual4 = c({
     '.b,.c': {
       margin: 1,
       '.d': {
-        margin: 2
-      }
-    }
-  }
+        margin: 2,
+      },
+    },
+  },
 })
 
 const expected4 = `
@@ -292,9 +292,9 @@ const actual5 = c({
   '.b,.c': {
     margin: 1,
     '.d': {
-      margin: 2
-    }
-  }
+      margin: 2,
+    },
+  },
 })
 
 const expected5 = `
@@ -311,9 +311,9 @@ const actual6 = c({
   '.a,.b': {
     margin: 1,
     '.c,.d': {
-      margin: 2
-    }
-  }
+      margin: 2,
+    },
+  },
 })
 
 const expected6 = `
@@ -364,7 +364,7 @@ yyy",zzz
 expect(csvParse(text)).to.deep.equal([
   ['aaa\n"aaa"\naaa', 'bbb', 'ccc,ccc'],
   ['xxx,xxx', 'yyy\nyyy', 'zzz'],
-  [' 42 ', '42', ' 17']
+  [' 42 ', '42', ' 17'],
 ])
 ```
 
@@ -391,7 +391,7 @@ except those inside `IFRAME`, `NOSCRIPT`, `PRE`, `SCRIPT`, `STYLE`, or `TEXTAREA
 const p = h('p',
   'Pchnąć w tę łódź jeża lub ośm skrzyń fig (zob. https://pl.wikipedia.org/wiki/Pangram).',
   ['br'],
-  ['b', 'Zażółć gęślą jaźń.']
+  ['b', 'Zażółć gęślą jaźń.'],
 )
 
 fixPlTypography(p)
@@ -494,6 +494,19 @@ expect(div.key).to.deep.equal({ one: 1 })
 h(div, { $key: { two: 2 } })
 
 expect(div.key).to.deep.equal({ one: 1, two: 2 })
+
+const elemWithClass = h('div', { class: 'test' })
+
+expect(elemWithClass.getAttribute('class')).to.equal('test')
+
+const elemWithText = h('div', 'initial')
+
+h(elemWithText, ' more')
+expect(elemWithText.outerHTML).to.equal('<div>initial more</div>')
+
+const elemWithNested = h('div', ['span', 'hello'], ['b', 'world'])
+
+expect(elemWithNested.outerHTML).to.equal('<div><span>hello</span><b>world</b></div>')
 ```
 
 ### hasOwn
@@ -740,10 +753,10 @@ The parsed value with handler substitutions applied.
 const handlers = {
   $add: (a: number, b: number) => a + b,
   $hello: (name: string) => `Hello ${name}!`,
-  $foo: () => 'bar'
+  $foo: () => 'bar',
 }
 
-const actual = jsOnParse(handlers, `[
+const actual1 = jsOnParse(handlers, `[
   {
     "$add": [1, 2]
   },
@@ -767,23 +780,33 @@ const actual = jsOnParse(handlers, `[
   }
 ]`)
 
-const expected = [
+expect(actual1).to.deep.equal([
   3,
   'Hello World!',
   {
     nested: 'Hello nested World!',
     one: 1,
-    two: 2
+    two: 2,
   },
   'bar',
   {
     $foo: ['The parent object does not have exactly one property!'],
     one: 1,
-    two: 2
-  }
-]
+    two: 2,
+  },
+])
+
+const actual2 = jsOnParse({ $notFunc: 'handler not being a function' } as any, '{"$notFunc": [1, 2]}')
+
+expect(actual2).to.deep.equal({ $notFunc: [1, 2] })
+
+const actual3 = jsOnParse(handlers, '{"$unknown_handler_key": [1, 2]}')
 
-expect(actual).to.deep.equal(expected)
+expect(actual3).to.deep.equal({ $unknown_handler_key: [1, 2] })
+
+const actual4 = jsOnParse(handlers, '{"$add": {"not": "array"}}')
+
+expect(actual4).to.deep.equal({ $add: { not: 'array' } })
 ```
 
 ### monokai
@@ -834,7 +857,7 @@ expect(nanolightTs(codeJs)).to.deep.equal([
   ['span', { class: 'string' }, "'42'"],
   ['span', { class: 'punctuation' }, ']'],
   ' ',
-  ['span', { class: 'comment' }, '/* 42 */']
+  ['span', { class: 'comment' }, '/* 42 */'],
 ])
 ```
 
@@ -971,6 +994,99 @@ A tokenizer function that accepts a code string and returns an array of decorate
 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.
 
+#### Usage Examples
+
+```ts
+const tokenizer1 = newTokenizer(
+  (chunk, metadata) => ({ chunk, metadata }),
+  ['keyword', /\b(if|else|for)\b/],
+  ['string', /"[^"]*"/],
+)
+const result1 = tokenizer1('if "hello" else "world"')
+
+expect(result1).to.deep.equal([
+  { chunk: 'if', metadata: 'keyword' },
+  { chunk: ' ', metadata: undefined },
+  { chunk: '"hello"', metadata: 'string' },
+  { chunk: ' ', metadata: undefined },
+  { chunk: 'else', metadata: 'keyword' },
+  { chunk: ' ', metadata: undefined },
+  { chunk: '"world"', metadata: 'string' },
+])
+
+const tokenizer2 = newTokenizer(
+  (chunk, metadata) => `${metadata}:${chunk}`,
+  ['tag', 'BEGIN'],
+  ['end', 'END'],
+)
+const result2 = tokenizer2('aBEGINbENDc')
+
+expect(result2).to.deep.equal(['undefined:a', 'tag:BEGIN', 'undefined:b', 'end:END', 'undefined:c'])
+
+const tokenizer3 = newTokenizer(
+  (chunk) => chunk,
+  ['test', /test/],
+)
+const result3 = tokenizer3('')
+
+expect(result3).to.deep.equal([])
+
+const tokenizer4 = newTokenizer(
+  (chunk, metadata) => ({ chunk, metadata }),
+  ['start', /^test/],
+)
+const result4 = tokenizer4('test here')
+
+expect(result4).to.deep.equal([
+  { chunk: 'test', metadata: 'start' },
+  { chunk: ' here', metadata: undefined },
+])
+
+const tokenizer5 = newTokenizer(
+  (chunk, metadata) => metadata,
+  ['later', /x/],
+  ['earlier', /y/],
+)
+const result5 = tokenizer5('yx')
+
+expect(result5).to.deep.equal(['earlier', 'later'])
+
+const tokenizer6 = newTokenizer(
+  (chunk) => chunk,
+  ['short', 'a'],
+  ['long', 'abc'],
+)
+const result6 = tokenizer6('abc')
+
+expect(result6).to.deep.equal(['abc'])
+
+const tokenizer7 = newTokenizer(
+  (chunk) => chunk,
+  ['empty', ''],
+  ['word', /\w+/],
+)
+const result7 = tokenizer7('hello')
+
+expect(result7).to.deep.equal(['hello'])
+
+const tokenizer8 = newTokenizer(
+  (chunk) => chunk,
+  ['test', /xyz/],
+)
+const result8 = tokenizer8('abc')
+
+expect(result8).to.deep.equal(['abc'])
+
+const tokenizer9 = newTokenizer(
+  (chunk, metadata) => metadata,
+  ['a', 'a'],
+  ['b', 'b'],
+)
+const result9 = tokenizer9('aabb')
+
+expect(result9).to.deep.equal(['a', 'a', 'b', 'b'])
+```
+
 ### omit
 
 ```ts
@@ -1067,45 +1183,45 @@ An array of breakpoint specifications, each a tuple of:
 ```ts
 const style: CRoot = {
   body: {
-    margin: 0
+    margin: 0,
   },
   '.r6': {
     border: 'solid red 1px',
     '.no-border': {
-      border: 'none'
-    }
-  }
+      border: 'none',
+    },
+  },
 }
 
 rwd(style, '.r6', 200, 50, [6], [3], [1, 1, 2])
 
 expect(style).to.deep.equal({
   body: {
-    margin: 0
+    margin: 0,
   },
   '.r6': {
     border: 'solid red 1px',
     '.no-border': {
-      border: 'none'
+      border: 'none',
     },
     boxSizing: 'border-box',
     display: 'block',
     float: 'left',
     width: '100%',
-    height: '100px'
+    height: '100px',
   },
   '@media(min-width:600px)': {
     '.r6': {
       width: 'calc(100% / 3)',
-      height: '50px'
-    }
+      height: '50px',
+    },
   },
   '@media(min-width:1200px)': {
     '.r6': {
       width: 'calc(50% / 3)',
-      height: '50px'
-    }
-  }
+      height: '50px',
+    },
+  },
 })
 ```
 
@@ -1140,6 +1256,30 @@ Additional arguments processed as follows:
 
 The created or modified `SVGElement`.
 
+#### Usage Examples
+
+```ts
+const svg = s('svg')
+
+s(svg, { 'xlink:href': true })
+expect(svg.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).to.equal('')
+
+const svg2 = s('svg')
+
+s(svg2, { 'xlink:href': false })
+expect(svg2.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).to.be.null
+
+const svg3 = s('svg')
+
+s(svg3, { 'xlink:href': 'http://example.com' })
+expect(svg3.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).to.equal('http://example.com')
+
+const svg4 = s('svg')
+
+s(svg4, { 'xlink:title': 42 })
+expect(svg4.getAttributeNS('http://www.w3.org/1999/xlink', 'title')).to.equal('42')
+```
+
 ### svgUse
 
 ```ts
@@ -1162,6 +1302,49 @@ Additional arguments passed to the outer `<svg>` element.
 
 An `SVGSVGElement` containing a `<use>` element.
 
+#### Usage Examples
+
+```ts
+const XLINK_NS = 'http://www.w3.org/1999/xlink'
+
+const svg = svgUse('icon-home')
+
+expect(svg.tagName).to.equal('SVG')
+expect(svg.children.length).to.equal(1)
+
+const useElement = svg.children[0]
+
+expect(useElement.tagName).to.equal('USE')
+expect(useElement.getAttributeNS(XLINK_NS, 'href')).to.equal('#icon-home')
+
+const svgWithViewBox = svgUse('icon-star', { viewBox: '0 0 24 24' })
+
+expect(svgWithViewBox.getAttribute('viewBox')).to.equal('0 0 24 24')
+
+const useViewBox = svgWithViewBox.children[0]
+
+expect(useViewBox.getAttributeNS(XLINK_NS, 'href')).to.equal('#icon-star')
+
+const svgWithClass = svgUse('icon-menu', { class: 'icon-btn' })
+
+expect(svgWithClass.getAttribute('class')).to.equal('icon-btn')
+expect(svgWithClass.children.length).to.equal(1)
+
+const useClass = svgWithClass.children[0]
+
+expect(useClass.getAttributeNS(XLINK_NS, 'href')).to.equal('#icon-menu')
+
+const svgWithMultipleAttrs = svgUse('icon-settings', { width: 24, height: 24, class: 'icon' })
+
+expect(svgWithMultipleAttrs.getAttribute('width')).to.equal('24')
+expect(svgWithMultipleAttrs.getAttribute('height')).to.equal('24')
+expect(svgWithMultipleAttrs.getAttribute('class')).to.equal('icon')
+
+const useMultiple = svgWithMultipleAttrs.children[0]
+
+expect(useMultiple.getAttributeNS(XLINK_NS, 'href')).to.equal('#icon-settings')
+```
+
 ### uuidV1
 
 ```ts
@@ -1264,40 +1447,40 @@ vivify(ref).one.two[3][4]
 
 expect(ref).to.deep.equal({
   one: {
-    two: [undefined, undefined, undefined, []]
-  }
+    two: [undefined, undefined, undefined, []],
+  },
 })
 
 vivify(ref).one.two[3][4] = 5
 
 expect(ref).to.deep.equal({
   one: {
-    two: [undefined, undefined, undefined, [undefined, undefined, undefined, undefined, 5]]
-  }
+    two: [undefined, undefined, undefined, [undefined, undefined, undefined, undefined, 5]],
+  },
 })
 
 vivify(ref).one.two[3].length = 1
 
 expect(ref).to.deep.equal({
   one: {
-    two: [undefined, undefined, undefined, [undefined]]
-  }
+    two: [undefined, undefined, undefined, [undefined]],
+  },
 })
 
 vivify(ref).one.two[3] = 4
 
 expect(ref).to.deep.equal({
   one: {
-    two: [undefined, undefined, undefined, 4]
-  }
+    two: [undefined, undefined, undefined, 4],
+  },
 })
 
 expect(vivify(ref).one.two.length).to.equal(4)
 
 expect(ref).to.deep.equal({
   one: {
-    two: [undefined, undefined, undefined, 4]
-  }
+    two: [undefined, undefined, undefined, 4],
+  },
 })
 
 vivify(ref).one.two = 3