@jackens/nnn 2023.11.3 → 2023.11.4

package/nnn.js

@@ -1,26 +1,6 @@
 const _COLORS = ['#e22', '#e73', '#fc3', '#ad4', '#4d9', '#3be', '#45d', '#c3e']
 
 /**
- * A helper for creating a chart based on a table (conf. <https://jackens.github.io/nnn/chartable/>).
- *
- * Options:
- * - `bottom`: bottom padding (for X axis labels)
- * - `gapX`: X axis spacing
- * - `gapY`: Y axis spacing
- * - `headerColumn`: flag indicating that `table` has a header column (with X axis labels)
- * - `headerRow`: flag indicating that `table` has a header row (with data series labels)
- * - `id`: chart id
- * - `left`: left padding (for data series labels)
- * - `maxY`: number of Y axis lines
- * - `right`: right padding (for data series labels)
- * - `singleScale`: flag to force single scale
- * - `table`: `HTMLTableElement` to extract data, data series labels and X axis labels
- * - `title`: chart title
- * - `top`: top padding (for the title)
- * - `xLabels`: X axis labels
- * - `zLabels`: data series labels
- * - `zxY`: chart data
- *
  * @param {{
  *   bottom?: number;
  *   gapX?: number;
@@ -209,9 +189,6 @@ export const chartable = ({
   )
 }
 
-/**
- * A helper that checks equality of the given arguments.
- */
 export const eq = /** @return {boolean} */ (/** @type {any} */ x, /** @type {any} */ y) => {
   if (x === y) {
     return true
@@ -256,21 +233,13 @@ export const eq = /** @return {boolean} */ (/** @type {any} */ x, /** @type {any
 
 /**
  * @typedef {Map<any, (value?: any) => string>} EscapeMap
- *
- * The type of arguments of the `escapeValues` and `escape` helpers.
  */
 
-/**
- * A generic helper for escaping `values` by given `escapeMap`.
- */
 export const escapeValues = (
   /** @type {EscapeMap} */ escapeMap,
   /** @type {any[]}     */ values
 ) => values.map(value => (escapeMap.get(value?.constructor) ?? escapeMap.get(undefined))?.(value) ?? '')
 
-/**
- * A generic helper for escaping `values` by given `escapeMap` (in *TemplateStrings* flavor).
- */
 export const escape = (
   /** @type {EscapeMap}            */ escapeMap,
   /** @type {TemplateStringsArray} */ template,
@@ -279,9 +248,6 @@ export const escape = (
 
 const _TAGS_TO_SKIP = { IFRAME: 1, NOSCRIPT: 1, PRE: 1, SCRIPT: 1, STYLE: 1, TEXTAREA: 1 }
 
-/**
- * A helper that implements typographic corrections specific to Polish typography.
- */
 export const fixTypography = (/** @type {Node} */ node) => {
   const /** @type {Node[]} */ queue = [node]
 
@@ -327,8 +293,6 @@ export const fixTypography = (/** @type {Node} */ node) => {
  *   string | Node,
  *   ...(Record<string, any> | null | undefined | Node | string | number | HArgs)[]
  * ]} HArgs
- *
- * The type of arguments of the `h` and `s` helpers.
  */
 
 const /** @type {Record<string, string>} */ _NS = {
@@ -425,48 +389,13 @@ const _h = (/** @type {string?=} */ namespaceURI) => {
   return h
 }
 
-/**
- * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
- *
- * - The first argument of type `string` specifies the tag of the element to be created.
- * - The first argument of type `Node` specifies the element to be modified.
- * - All other arguments of type `Record<string, any>` are mappings of attributes and properties.
- *   Keys starting with `$` specify *properties* (without the leading `$`) to be set on the element being created or modified.
- *   (Note that `$` is not a valid attribute name character.)
- *   All other keys specify *attributes* to be set by `setAttribute`.
- *   An attribute equal to `false` causes the attribute to be removed by `removeAttribute`.
- * - All other arguments of type `null` or `undefined` are simply ignored.
- * - All other arguments of type `Node` are appended to the element being created or modified.
- * - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
- * - All other arguments of type `HArgs` are passed to `h` and the results are appended to the element being created or modified.
- */
 export const h = _h()
 
-/**
- * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
- *
- * - The first argument of type `string` specifies the tag of the element to be created.
- * - The first argument of type `Node` specifies the element to be modified.
- * - All other arguments of type `Record<string, any>` are mappings of attributes and properties.
- *   Keys starting with `$` specify *properties* (without the leading `$`) to be set on the element being created or modified.
- *   (Note that `$` is not a valid attribute name character.)
- *   All other keys specify *attributes* to be set by `setAttributeNS`.
- *   An attribute equal to `false` causes the attribute to be removed by `removeAttributeNS`.
- * - All other arguments of type `null` or `undefined` are simply ignored.
- * - All other arguments of type `Node` are appended to the element being created or modified.
- * - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
- * - All other arguments of type `HArgs` are passed to `s` and the results are appended to the element being created or modified.
- */
 export const s = _h('http://www.w3.org/2000/svg')
 
-/**
- * A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
- */
 export const has = (/** @type {any} */ key, /** @type {any} */ ref) => (is(String, key) || is(Number, key) || is(Symbol, key)) && Object.hasOwnProperty.call(ref ?? Object, key)
 
 /**
- * A helper that checks if the given argument is of a certain type.
- *
  * @template {abstract new (...args: any[]) => any} T
  *
  * @type {{
@@ -487,14 +416,10 @@ export const is = (/** @type {T} */ type, /** @type {any} */ arg) => arg?.constr
  * @typedef {{
  *   [attributeOrSelector: string]: string | number | JcssNode;
  * }} JcssNode
- *
- * The type of arguments of the `jcss` helper.
  */
 
 /**
  * @typedef {Record<string, JcssNode>} JcssRoot
- *
- * The type of arguments of the `jcss` helper.
  */
 
 const _jcss = (
@@ -551,17 +476,6 @@ const _jcss = (
   }
 }
 
-/**
- * A simple CSS-in-JS helper.
- *
- * The `root` parameter provides a hierarchical description of CSS rules.
- *
- * - Keys of sub-objects whose values are NOT objects are treated as CSS attribute, and values are treated as values of those CSS attributes; the concatenation of keys of all parent objects is a CSS rule.
- * - All keys ignore the part starting with a splitter (default: `$$`) sign until the end of the key (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
- * - In keys specifying CSS attribute, all uppercase letters are replaced by lowercase letters with an additional `-` character preceding them (e.g. `fontFamily` → `font-family`).
- * - Commas in keys that makes a CSS rule cause it to “split” and create separate rules for each part (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
- * - Top-level keys that begin with `@` are not concatenated with sub-object keys.
- */
 export const jcss = (/** @type {JcssRoot} */ root, splitter = '$$') => {
   const split = (/** @type {string} */ text) => text.split(splitter)[0]
   const /** @type {string[]} */ result = []
@@ -581,21 +495,6 @@ export const jcss = (/** @type {JcssRoot} */ root, splitter = '$$') => {
   return result.join('')
 }
 
-/**
- * `JSON.parse` with “JavaScript turned on”.
- *
- * Objects having *exactly* one property which is present in the `handlers` map, i.e. objects of the form:
- *
- * ```js
- * { "«handlerName»": [«params»] }
- * ```
- *
- * are replaced by the result of call
- *
- * ```js
- * handlers['«handlerName»'](...«params»)
- * ```
- */
 export const jsOnParse = (
   /** @type {Record<string, Function>} */ handlers,
   /** @type {string}                   */ text
@@ -636,9 +535,6 @@ const _locale = (
   return is(String, t) ? t : text
 }
 
-/**
- * Language translations helper.
- */
 export const locale = (
   /** @type {Record<string, Record<string, string | Record<string, string>>>} */ locales,
   /** @type {string} */ defaultLanguage,
@@ -655,9 +551,6 @@ export const locale = (
   return _locale.bind(0, locales, defaultLanguage)
 }
 
-/**
- * A generic helper for syntax highlighting (see also `nanolightJs`).
- */
 export const nanolight = (
   /** @type {RegExp} */ pattern,
   /** @type {((chunk: string, index: number) => import('./h.js').HArgs[1])[]} */ highlighters,
@@ -675,9 +568,6 @@ export const nanolight = (
   return result
 }
 
-/**
- * A helper for highlighting JavaScript.
- */
 // @ts-expect-error
 export const nanolightJs = nanolight.bind(0,
   /('.*?'|".*?"|`[\s\S]*?`)|(\/\/.*?\n|\/\*[\s\S]*?\*\/)|(break|case|catch|const|continue|debugger|default|delete|do|else|eval|export\s+type|export|extends|false|finally|for|from|function|goto|if|import|in|instanceof|is|keyof|let|NaN|new|null|package|return|super|switch|this|throw|true|try|typeof|undefined|var|void|while|with|yield)(?!\w)|([<>=.?:&|!~*/%+-])|(0x[\dabcdef]+|0o[01234567]+|0b[01]+|\d+(?:\.[\d_]+)?(?:e[+-]?[\d_]+)?)|([$\w]+)(?=\()|([$\wąćęłńóśżźĄĆĘŁŃÓŚŻŹ]+)/,
@@ -693,9 +583,6 @@ export const nanolightJs = nanolight.bind(0,
   ]
 )
 
-/**
- * A helper for choosing the correct singular and plural.
- */
 export const plUral = (
   /** @type {string} */ singular,
   /** @type {string} */ plural2,
@@ -714,9 +601,6 @@ export const plUral = (
         : plural5
 }
 
-/**
- * A helper that protect calls to nested properties by `Proxy` which initializes non-existent values with an empty object.
- */
 // @ts-expect-error
 export const pro = (/** @type {any} */ ref) => new Proxy(ref, {
   get (target, key) {
@@ -724,11 +608,6 @@ export const pro = (/** @type {any} */ ref) => new Proxy(ref, {
   }
 })
 
-/**
- * A helper that provides information about the given `refs`.
- *
- * It returns an array of triples: `[«name», «prototype-name», «array-of-own-property-names»]`.
- */
 export const refsInfo = (/** @type {any[]} */ ...refs) => {
   const /** @type {Set<Function>} */ fns = new Set()
 
@@ -749,12 +628,6 @@ export const refsInfo = (/** @type {any[]} */ ...refs) => {
 const ZEROS = '0'.repeat(16)
 let counter = 0
 
-/**
- * A helper that generates a UUID v1 identifier (with a creation timestamp).
- *
- * - The optional `node` parameter should have the format `/^[0123456789abcdef]+$/`.
- *   Its value will be trimmed to last 12 characters and left padded with zeros.
- */
 export const uuid1 = ({
   date = new Date(),
   node = Math.random().toString(16).slice(2)
@@ -774,4 +647,4 @@ export const uuid1 = ({
     (ZEROS + (counter & 4095).toString(16)).slice(-3),
     '-',
     (ZEROS + node).slice(-12))
-}
+}

package/package.json

@@ -40,5 +40,5 @@
   "types": "nnn.d.ts",
   "name": "@jackens/nnn",
   "type": "module",
-  "version": "2023.11.3"
+  "version": "2023.11.4"
 }