@gkucmierz/utils 5.1.0 → 5.4.1

package/main.mjs

@@ -41,6 +41,9 @@ import {
 import {
   
 } from './src/developer-utils/get-type.mjs'
+import {
+  detectGridColumns, navigateGrid
+} from './src/developer-utils/grid-navigation.mjs'
 import {
   measurePerformance
 } from './src/developer-utils/measure-performance.mjs'
@@ -50,6 +53,9 @@ import {
 import {
   naturalSearch
 } from './src/developer-utils/natural-search.mjs'
+import {
+  QUORUM_CONFIG, QUORUM_DEFAULT_K, QUORUM_DEFAULT_N, QUORUM_MAX_RELATIVE_ERROR, QUORUM_MAX_RELATIVE_ERROR_PCT, QUORUM_ZERO_FLOOR_EPSILON, computeRelativeError, evaluateQuorum, evaluateQuorum4of5, isQuorumEqual
+} from './src/developer-utils/quorum.mjs'
 import {
   randNormal
 } from './src/developer-utils/rand-normal.mjs'
@@ -60,17 +66,20 @@ import {
   setSafeInterval
 } from './src/developer-utils/set-safe-interval.mjs'
 import {
-  Type, Types, is, of, same
+  Type, Types, is, isCallable, of, same
 } from './src/developer-utils/type.mjs'
 import {
   barycentricCoordinates
 } from './src/geometry/barycentric.mjs'
 import {
-  axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball
+  applyScreenDragQuat, axisAngleToMatrix4, axisAngleToQuat, crossProduct, dotProduct, eulerYXZToQuat, getRotationMatrixFromVectors, matToEulerYXZ, matToQuat, multiplyMatrix4, multiplyQuat, normalize, normalizeQuat, projectToTrackball, quatToMat, rotateVecByQuat, slerp
 } from './src/geometry/math3d.mjs'
 import {
   matrixAsArray
 } from './src/geometry/matrix.mjs'
+import {
+  OrthoSet, containsPoint1D, containsPointNd, diffBox, diffRange, formatRange, measureBox, measureRange, mutualBox, mutualRange, parseRange, range, sharedMeasureNd, sumBox, sumRange, xorBox, xorRange
+} from './src/geometry/range-set.mjs'
 import {
   egcd
 } from './src/number-theory/egcd.mjs'
@@ -140,6 +149,12 @@ import {
 import {
   formatBigNumber, formatBigNumberBI, wrapFn
 } from './src/string-arrays/format-big-number.mjs'
+import {
+  parseHeading
+} from './src/string-arrays/parse-heading.mjs'
+import {
+  slugify
+} from './src/string-arrays/slugify.mjs'
 
 export * from './src/automata/langtons-ant.mjs';
 export * from './src/combinatorics/combinations.mjs';
@@ -155,9 +170,11 @@ export * from './src/data-structures/list-node.mjs';
 export * from './src/developer-utils/binary-search.mjs';
 export * from './src/developer-utils/consume-iterator.mjs';
 export * from './src/developer-utils/get-type.mjs';
+export * from './src/developer-utils/grid-navigation.mjs';
 export * from './src/developer-utils/measure-performance.mjs';
 export * from './src/developer-utils/memoize.mjs';
 export * from './src/developer-utils/natural-search.mjs';
+export * from './src/developer-utils/quorum.mjs';
 export * from './src/developer-utils/rand-normal.mjs';
 export * from './src/developer-utils/range-array.mjs';
 export * from './src/developer-utils/set-safe-interval.mjs';
@@ -165,6 +182,7 @@ export * from './src/developer-utils/type.mjs';
 export * from './src/geometry/barycentric.mjs';
 export * from './src/geometry/math3d.mjs';
 export * from './src/geometry/matrix.mjs';
+export * from './src/geometry/range-set.mjs';
 export * from './src/number-theory/egcd.mjs';
 export * from './src/number-theory/factors.mjs';
 export * from './src/number-theory/gcd.mjs';
@@ -188,7 +206,9 @@ export * from './src/string-arrays/bijective-numeration.mjs';
 export * from './src/string-arrays/chunks.mjs';
 export * from './src/string-arrays/copy-case.mjs';
 export * from './src/string-arrays/format-big-number.mjs';
+export * from './src/string-arrays/parse-heading.mjs';
+export * from './src/string-arrays/slugify.mjs';
 
 export default [
-  createLangtonsAnt, createUnlimitedGrid, combinations, combinationsIterator, bin2gray, gray2bin, nChooseK, permutations, permutationsIterator, ConflatingQueue, SetCnt, Stack, Trie, Heap, ListNode, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, measurePerformance, memoize, naturalSearch, randNormal, array2range, range2array, setSafeInterval, Type, Types, is, of, same, barycentricCoordinates, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, egcd, factors, factorsBI, gcd, gcdBI, lcm, lcmBI, lucasLehmerBI, mobius, mobiusBI, mod, modBI, phi, phiBI, powMod, powModBI, tonelliShanksBI, nelderMead, particleSwarmOptimization, simulatedAnnealing, goldenRatio, goldenRatioBI, goldenRatioStr, gpn, gpnBI, heronsFormula, heronsFormulaBI, squareRoot, squareRootBI, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, chunks, chunksAsyncIterator, chunksIterator, copyCase, formatBigNumber, formatBigNumberBI, wrapFn
+  createLangtonsAnt, createUnlimitedGrid, combinations, combinationsIterator, bin2gray, gray2bin, nChooseK, permutations, permutationsIterator, ConflatingQueue, SetCnt, Stack, Trie, Heap, ListNode, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, detectGridColumns, navigateGrid, measurePerformance, memoize, naturalSearch, QUORUM_CONFIG, QUORUM_DEFAULT_K, QUORUM_DEFAULT_N, QUORUM_MAX_RELATIVE_ERROR, QUORUM_MAX_RELATIVE_ERROR_PCT, QUORUM_ZERO_FLOOR_EPSILON, computeRelativeError, evaluateQuorum, evaluateQuorum4of5, isQuorumEqual, randNormal, array2range, range2array, setSafeInterval, Type, Types, is, isCallable, of, same, barycentricCoordinates, applyScreenDragQuat, axisAngleToMatrix4, axisAngleToQuat, crossProduct, dotProduct, eulerYXZToQuat, getRotationMatrixFromVectors, matToEulerYXZ, matToQuat, multiplyMatrix4, multiplyQuat, normalize, normalizeQuat, projectToTrackball, quatToMat, rotateVecByQuat, slerp, matrixAsArray, OrthoSet, containsPoint1D, containsPointNd, diffBox, diffRange, formatRange, measureBox, measureRange, mutualBox, mutualRange, parseRange, range, sharedMeasureNd, sumBox, sumRange, xorBox, xorRange, egcd, factors, factorsBI, gcd, gcdBI, lcm, lcmBI, lucasLehmerBI, mobius, mobiusBI, mod, modBI, phi, phiBI, powMod, powModBI, tonelliShanksBI, nelderMead, particleSwarmOptimization, simulatedAnnealing, goldenRatio, goldenRatioBI, goldenRatioStr, gpn, gpnBI, heronsFormula, heronsFormulaBI, squareRoot, squareRootBI, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, chunks, chunksAsyncIterator, chunksIterator, copyCase, formatBigNumber, formatBigNumberBI, wrapFn, parseHeading, slugify
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkucmierz/utils",
-  "version": "5.1.0",
+  "version": "5.4.1",
   "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [
@@ -74,7 +74,7 @@
     "docs:build": "jsdoc -c jsdoc.json && cp -r docs/@gkucmierz/utils/*/* docs/ && rm -rf docs/@gkucmierz",
     "docs:open": "open docs/index.html",
     "lint": "eslint .",
-    "prepare": "husky"
+    "prepare": "git config core.hooksPath .githooks || true"
   },
   "repository": {
     "type": "git",
@@ -88,7 +88,6 @@
     "docdash": "^2.0.2",
     "eslint": "^10.1.0",
     "globals": "^17.4.0",
-    "husky": "^8.0.3",
     "jasmine": "^4.4.0",
     "jsdoc": "^4.0.4",
     "lz-string": "^1.5.0",

package/src/developer-utils/grid-navigation.mjs

@@ -0,0 +1,291 @@
+/**
+ * @module developer-utils
+ */
+
+/**
+ * Builds a 2D occupancy matrix `rows[r][c] = itemIndex` (or `-1` for empty gap)
+ * when `spanLastRow` or `colSpans` is enabled.
+ *
+ * @param {number} totalItems
+ * @param {number} cols
+ * @param {Object} opts
+ * @returns {{ matrix: number[][], itemPos: Array<{ row: number, cols: number[] }> }}
+ */
+const buildSpannedGridMatrix = (totalItems, cols, opts = {}) => {
+  const spanLastRow = Boolean(opts.spanLastRow);
+  const colSpans = opts.colSpans || null;
+  const matrix = [];
+  const itemPos = Array.from({ length: totalItems }, () => ({ row: 0, cols: [] }));
+
+  let curRow = new Array(cols).fill(-1);
+  let c = 0;
+
+  for (let i = 0; i < totalItems; i += 1) {
+    let span = 1;
+    if (colSpans) {
+      const rawSpan = Array.isArray(colSpans) ? colSpans[i] : colSpans[i];
+      if (Number.isFinite(Number(rawSpan)) && Number(rawSpan) >= 1) {
+        span = Math.min(cols, Math.floor(Number(rawSpan)));
+      }
+    }
+    if (c + span > cols) {
+      matrix.push(curRow);
+      curRow = new Array(cols).fill(-1);
+      c = 0;
+    }
+    if (spanLastRow && i === totalItems - 1 && c < cols) {
+      span = cols - c;
+    }
+    const rowIdx = matrix.length;
+    itemPos[i].row = rowIdx;
+    for (let k = 0; k < span && c < cols; k += 1) {
+      curRow[c] = i;
+      itemPos[i].cols.push(c);
+      c += 1;
+    }
+    if (c >= cols) {
+      matrix.push(curRow);
+      curRow = new Array(cols).fill(-1);
+      c = 0;
+    }
+  }
+
+  if (c > 0) {
+    matrix.push(curRow);
+  }
+
+  return { matrix, itemPos };
+};
+
+/**
+ * Resolves the next 0-based index when navigating a 2D grid (matrix) that may contain
+ * trailing gaps in its last row (`totalItems` not divisible by `columns`) or spanned cells
+ * (`spanLastRow: true` / `colSpans` / `preferredCol`).
+ *
+ * Pure mathematical/index function — completely independent of the DOM.
+ *
+ * Wrapping configuration hierarchy:
+ * - `wrap` (boolean, default `true`): master default for both axes.
+ * - `wrapHoriz` / `wrapHorizontal` (boolean, optional): overrides `wrap` for horizontal movement (`left` / `right`).
+ * - `wrapVert` / `wrapVertical` (boolean, optional): overrides `wrap` for vertical movement (`up` / `down`).
+ * - `rowStrict` (boolean, default `false`): when `true`, horizontal movement wraps/clamps strictly within the current row instead of reading order.
+ * - `spanLastRow` (boolean, default `false`): when `true`, the final item (`totalItems - 1`) spans all remaining columns in the last row (e.g. a 2x3 grid where row 2 has a full-width card `[4, 4]`).
+ * - `colSpans` (number[]|Object, optional): explicit column span per item index (`>= 1`).
+ * - `preferredCol` (number, optional): preferred column index (`0 <= preferredCol < columns`) preserved when stepping vertically out of a multi-column spanned item.
+ *
+ * When `columns === 1` (single-column layout), `right` behaves identically to `down`
+ * and `left` behaves identically to `up`.
+ *
+ * @param {number} currentIndex - Current active 0-based index (`0 <= currentIndex < totalItems`).
+ * @param {number} totalItems - Total number of items in the grid ($N \ge 0$).
+ * @param {'left'|'right'|'up'|'down'|'ArrowLeft'|'ArrowRight'|'ArrowUp'|'ArrowDown'} direction - Movement direction.
+ * @param {number|Object} [columnsOrOptions=1] - Column count ($C \ge 1$) or options object.
+ * @param {Object} [maybeOptions={}] - Optional configuration when 4th argument is a column count.
+ * @returns {number} Next 0-based index, or `-1` if `totalItems <= 0`.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IHYEMBuIDm64CmA4jCACYIC+CAZjFGAgEQACOA1gK4DGYIBMAF4B6TnBAAbAM5MA3MGAZseQiXLygA|▶ Try it live in Instacode}
+ */
+export const navigateGrid = (
+  currentIndex,
+  totalItems,
+  direction,
+  columnsOrOptions = 1,
+  maybeOptions = {}
+) => {
+  if (!Number.isFinite(totalItems) || totalItems <= 0) {
+    return -1;
+  }
+
+  const isObj = columnsOrOptions !== null && typeof columnsOrOptions === 'object';
+  const opts = isObj ? columnsOrOptions : (maybeOptions || {});
+  const rawCols = isObj ? opts.columns : columnsOrOptions;
+  const cols = Math.max(1, Math.floor(Number(rawCols) || 1));
+
+  const cur =
+    Number.isFinite(currentIndex) && currentIndex >= 0 && currentIndex < totalItems
+      ? Math.floor(currentIndex)
+      : 0;
+
+  const baseWrap = typeof opts.wrap === 'boolean' ? opts.wrap : true;
+  const wrapHoriz =
+    typeof opts.wrapHorizontal === 'boolean'
+      ? opts.wrapHorizontal
+      : typeof opts.wrapHoriz === 'boolean'
+        ? opts.wrapHoriz
+        : baseWrap;
+  const wrapVert =
+    typeof opts.wrapVertical === 'boolean'
+      ? opts.wrapVertical
+      : typeof opts.wrapVert === 'boolean'
+        ? opts.wrapVert
+        : baseWrap;
+  const rowStrict = Boolean(opts.rowStrict);
+  const hasSpans = Boolean(opts.spanLastRow || opts.colSpans);
+
+  const row = Math.floor(cur / cols);
+  const col = cur % cols;
+
+  let deltaH = 0;
+  let deltaV = 0;
+
+  switch (direction) {
+  case 'right':
+  case 'ArrowRight':
+    deltaH = 1;
+    break;
+  case 'left':
+  case 'ArrowLeft':
+    deltaH = -1;
+    break;
+  case 'down':
+  case 'ArrowDown':
+    deltaV = 1;
+    break;
+  case 'up':
+  case 'ArrowUp':
+    deltaV = -1;
+    break;
+  default:
+    return cur;
+  }
+
+  // Horizontal movement (left / right)
+  if (deltaH !== 0) {
+    if (rowStrict) {
+      if (hasSpans && cols > 1) {
+        const { matrix, itemPos } = buildSpannedGridMatrix(totalItems, cols, opts);
+        const curRowIdx = itemPos[cur]?.row ?? 0;
+        const rowItems = [];
+        for (const cellItem of matrix[curRowIdx] || []) {
+          if (cellItem >= 0 && !rowItems.includes(cellItem)) {
+            rowItems.push(cellItem);
+          }
+        }
+        const posInRow = rowItems.indexOf(cur);
+        if (posInRow < 0 || rowItems.length <= 0) return cur;
+        const nextPos = posInRow + deltaH;
+        if (nextPos >= 0 && nextPos < rowItems.length) {
+          return rowItems[nextPos];
+        }
+        if (wrapHoriz) {
+          return rowItems[((nextPos % rowItems.length) + rowItems.length) % rowItems.length];
+        }
+        return cur;
+      }
+      const rowStart = row * cols;
+      const rowLen = Math.min(cols, totalItems - rowStart);
+      if (rowLen <= 0) return cur;
+      const nextCol = col + deltaH;
+      if (nextCol >= 0 && nextCol < rowLen) {
+        return rowStart + nextCol;
+      }
+      if (wrapHoriz) {
+        return rowStart + (((nextCol % rowLen) + rowLen) % rowLen);
+      }
+      return cur;
+    }
+
+    const nextIdx = cur + deltaH;
+    if (nextIdx >= 0 && nextIdx < totalItems) {
+      return nextIdx;
+    }
+    if (wrapHoriz) {
+      return ((nextIdx % totalItems) + totalItems) % totalItems;
+    }
+    return cur;
+  }
+
+  // Vertical movement (up / down) when spanned cells are configured
+  if (hasSpans && cols > 1) {
+    const { matrix, itemPos } = buildSpannedGridMatrix(totalItems, cols, opts);
+    const curInfo = itemPos[cur] || { row: 0, cols: [0] };
+    const occupiedCols = curInfo.cols.length > 0 ? curInfo.cols : [0];
+    let targetCol = occupiedCols[0];
+    if (occupiedCols.length > 1 && Number.isFinite(Number(opts.preferredCol))) {
+      const pref = Math.max(0, Math.min(cols - 1, Math.floor(Number(opts.preferredCol))));
+      if (occupiedCols.includes(pref)) {
+        targetCol = pref;
+      }
+    }
+
+    const validRowsForCol = [];
+    for (let r = 0; r < matrix.length; r += 1) {
+      if (matrix[r][targetCol] >= 0) {
+        validRowsForCol.push(r);
+      }
+    }
+    if (validRowsForCol.length === 0) return cur;
+
+    const curRowPos = validRowsForCol.indexOf(curInfo.row);
+    const baseRowPos = curRowPos >= 0 ? curRowPos : 0;
+    const nextRowPos = baseRowPos + deltaV;
+    if (nextRowPos >= 0 && nextRowPos < validRowsForCol.length) {
+      return matrix[validRowsForCol[nextRowPos]][targetCol];
+    }
+    if (wrapVert) {
+      const wrappedPos =
+        ((nextRowPos % validRowsForCol.length) + validRowsForCol.length) %
+        validRowsForCol.length;
+      return matrix[validRowsForCol[wrappedPos]][targetCol];
+    }
+    return cur;
+  }
+
+  // Vertical movement (up / down) along column `col` (handling incomplete last row gaps)
+  const colRows = col < totalItems ? Math.floor((totalItems - 1 - col) / cols) + 1 : 0;
+  if (colRows <= 0) return cur;
+
+  const nextRow = row + deltaV;
+  if (nextRow >= 0 && nextRow < colRows) {
+    return nextRow * cols + col;
+  }
+  if (wrapVert) {
+    const wrappedRow = ((nextRow % colRows) + colRows) % colRows;
+    return wrappedRow * cols + col;
+  }
+  return cur;
+};
+
+/**
+ * Pure higher-order geometric utility that detects the number of columns in the first row
+ * of a 2D layout from an iterable of items and a row-offset projector function.
+ *
+ * Counts how many consecutive leading items share the same row coordinate (`y` / `top`)
+ * within the given `tolerance`. Completely independent of the DOM.
+ *
+ * @param {Iterable<*>} items - Iterable of numbers (row offsets) or arbitrary items.
+ * @param {Function|number} [getRowOffset=(x) => x] - Pure projector `(item, index) => number` (or numeric tolerance if 2nd arg is a number).
+ * @param {number} [tolerance=0] - Maximum allowed absolute difference between an item's row offset and the first item's offset.
+ * @returns {number} Detected number of columns in the first row ($\ge 1$).
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4ICYFM7oMZwOIwioDCUANgK5gB2AzggL4IBmMUYCARAAIDmA1hWxgQ6GAC8A9BTggytTgG5gwDFlwEipSjVrKgA|▶ Try it live in Instacode}
+ */
+export const detectGridColumns = (items, getRowOffset = (x) => x, tolerance = 0) => {
+  if (!items || typeof items[Symbol.iterator] !== 'function') {
+    return 1;
+  }
+
+  const isFn = typeof getRowOffset === 'function';
+  const projector = isFn ? getRowOffset : (x) => x;
+  const tol = Math.max(0, Number(isFn ? tolerance : getRowOffset) || 0);
+
+  let firstOffset = null;
+  let firstRowCount = 0;
+  let idx = 0;
+
+  for (const item of items) {
+    const raw = projector(item, idx++);
+    const offset = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isFinite(offset)) {
+      continue;
+    }
+    if (firstOffset === null) {
+      firstOffset = offset;
+      firstRowCount = 1;
+    } else if (Math.abs(offset - firstOffset) <= tol) {
+      firstRowCount += 1;
+    } else {
+      break;
+    }
+  }
+
+  return Math.max(1, firstRowCount);
+};