lumen-lib 0.0.0-stage → 2.1.0

package/assets/site/site.js

@@ -0,0 +1,239 @@
+/* lumen-lib site bundle — docs demo with bundled helpers */
+(function () {
+  "use strict";
+
+  /* ---- bundled helpers (mirrors index.cjs exports) ---- */
+
+  function cn() {
+    var out = [];
+    for (var i = 0; i < arguments.length; i++) {
+      var c = arguments[i];
+      if (c) out.push(c);
+    }
+    return out.join(" ");
+  }
+
+  function formatBytes(bytes, decimals) {
+    decimals = decimals === undefined ? 1 : decimals;
+    var n = Number(bytes);
+    if (!isFinite(n) || n < 0) return "0 B";
+    if (n === 0) return "0 B";
+    var units = ["B", "KB", "MB", "GB", "TB", "PB"];
+    var i = Math.min(Math.floor(Math.log(n) / Math.log(1024)), units.length - 1);
+    var v = n / Math.pow(1024, i);
+    return (v >= 100 || i === 0 ? Math.round(v) : v.toFixed(decimals)) + " " + units[i];
+  }
+
+  function formatCompact(n) {
+    var v = Number(n);
+    if (!isFinite(v)) return String(n == null ? "" : n);
+    var abs = Math.abs(v);
+    var units = [[1e12, "T"], [1e9, "B"], [1e6, "M"], [1e3, "K"]];
+    for (var i = 0; i < units.length; i++) {
+      if (abs >= units[i][0]) {
+        var r = v / units[i][0];
+        return (r >= 100 ? Math.round(r) : r.toFixed(1).replace(/\.0$/, "")) + units[i][1];
+      }
+    }
+    return String(v);
+  }
+
+  function timeAgo(date, now) {
+    now = now === undefined ? Date.now() : now;
+    var then = date instanceof Date ? date.getTime() : new Date(date).getTime();
+    if (!isFinite(then)) return "";
+    var diff = Math.max(0, now - then);
+    var units = [
+      ["year", 31536000000], ["month", 2592000000], ["week", 604800000],
+      ["day", 86400000], ["hour", 3600000], ["minute", 60000], ["second", 1000],
+    ];
+    for (var i = 0; i < units.length; i++) {
+      var v = Math.floor(diff / units[i][1]);
+      if (v >= 1) return v + " " + units[i][0] + (v === 1 ? "" : "s") + " ago";
+    }
+    return "just now";
+  }
+
+  function debounce(fn, ms) {
+    ms = ms === undefined ? 200 : ms;
+    var t = null;
+    var d = function () {
+      var args = arguments, self = this;
+      clearTimeout(t);
+      t = setTimeout(function () { fn.apply(self, args); }, ms);
+    };
+    d.cancel = function () { clearTimeout(t); };
+    return d;
+  }
+
+  window.lumen-lib = {
+    cn: cn,
+    formatBytes: formatBytes,
+    formatCompact: formatCompact,
+    timeAgo: timeAgo,
+    debounce: debounce,
+  };
+
+  /* ---- api reference table ---- */
+
+  var API = [
+    ["cn", "cn(...classes)", "Join class names, ignoring falsy values.", "classnames"],
+    ["capitalize", "capitalize(s)", "Uppercase the first character.", "strings"],
+    ["kebabCase", "kebabCase(s)", "Convert to kebab-case.", "strings"],
+    ["camelCase", "camelCase(s)", "Convert to camelCase.", "strings"],
+    ["truncate", "truncate(s, max, ellipsis)", "Cut a string to length with an ellipsis.", "strings"],
+    ["stripHtml", "stripHtml(s)", "Remove all HTML tags.", "strings"],
+    ["formatBytes", "formatBytes(bytes, decimals)", "Human-readable byte sizes: 1.5 MB.", "formatting"],
+    ["formatNumber", "formatNumber(n, locale)", "Locale-aware number grouping.", "formatting"],
+    ["formatCompact", "formatCompact(n)", "Compact notation: 1.2K, 3.4M.", "formatting"],
+    ["timeAgo", "timeAgo(date, now)", "Relative time: \"3 hours ago\".", "formatting"],
+    ["clamp", "clamp(n, min, max)", "Constrain a number to a range.", "math"],
+    ["lerp", "lerp(a, b, t)", "Linear interpolation between two numbers.", "math"],
+    ["randomInt", "randomInt(min, max)", "Random integer in an inclusive range.", "math"],
+    ["mapRange", "mapRange(n, inMin, inMax, outMin, outMax)", "Remap a value between ranges.", "math"],
+    ["deepMerge", "deepMerge(target, ...sources)", "Recursive merge for plain objects.", "objects"],
+    ["omit", "omit(obj, keys)", "Copy an object minus the given keys.", "objects"],
+    ["pick", "pick(obj, keys)", "Copy an object with only the given keys.", "objects"],
+    ["chunk", "chunk(arr, size)", "Split an array into fixed-size chunks.", "arrays"],
+    ["unique", "unique(arr)", "Deduplicate an array.", "arrays"],
+    ["groupBy", "groupBy(arr, fn)", "Group items by a computed key.", "arrays"],
+    ["debounce", "debounce(fn, ms)", "Invoke after a quiet period. Cancelable.", "functions"],
+    ["throttle", "throttle(fn, ms)", "Invoke at most once per interval.", "functions"],
+    ["once", "once(fn)", "Only the first call runs.", "functions"],
+    ["sleep", "sleep(ms)", "Promise-based delay.", "functions"],
+    ["retry", "retry(fn, tries, delay)", "Retry an async fn with backoff.", "functions"],
+    ["isEmail", "isEmail(s)", "Loose email format check.", "validation"],
+    ["isUrl", "isUrl(s)", "Loose URL / domain check.", "validation"],
+    ["isNonEmptyString", "isNonEmptyString(v)", "Type guard for non-empty strings.", "validation"],
+    ["uid", "uid(length)", "Random id, crypto-backed when available.", "ids"],
+  ];
+
+  var GROUP_LABEL = {
+    classnames: "classnames",
+    strings: "strings",
+    formatting: "formatting",
+    math: "math",
+    objects: "objects & arrays",
+    arrays: "objects & arrays",
+    functions: "functions",
+    validation: "validation",
+    ids: "ids",
+  };
+
+  function esc(s) {
+    return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  }
+
+  function mount() {
+    /* api table */
+    var tbody = document.getElementById("api-rows");
+    if (tbody) {
+      var lastGroup = null;
+      API.forEach(function (row) {
+        if (GROUP_LABEL[row[3]] !== lastGroup) {
+          lastGroup = GROUP_LABEL[row[3]];
+          var h = document.createElement("tr");
+          var hc = document.createElement("td");
+          hc.colSpan = 3;
+          hc.className = "group";
+          hc.textContent = lastGroup;
+          h.appendChild(hc);
+          tbody.appendChild(h);
+        }
+        var tr = document.createElement("tr");
+        tr.innerHTML =
+          '<td class="name">' + esc(row[0]) + "</td>" +
+          '<td class="sig">' + esc(row[1]) + "</td>" +
+          '<td class="what">' + esc(row[2]) + "</td>";
+        tbody.appendChild(tr);
+      });
+    }
+
+    /* demos */
+    var set = function (id, text) {
+      var el = document.getElementById(id);
+      if (el) el.textContent = text;
+    };
+
+    set(
+      "demo-cn",
+      'cn("btn", isActive && "btn--active", className)\n' +
+        "=> \"" +
+        cn("btn", true && "btn--active", "ml-2") +
+        '"'
+    );
+
+    set(
+      "demo-fmt",
+      "formatBytes(1536)      => " + formatBytes(1536) + "\n" +
+        "formatBytes(248291048) => " + formatBytes(248291048) + "\n" +
+        "formatCompact(3400000) => " + formatCompact(3400000)
+    );
+
+    var now = Date.now();
+    set(
+      "demo-time",
+      "timeAgo(now - 45s)  => " + timeAgo(now - 45000, now) + "\n" +
+        "timeAgo(now - 3h)   => " + timeAgo(now - 3 * 3600000, now) + "\n" +
+        "timeAgo(now - 2d)   => " + timeAgo(now - 2 * 86400000, now)
+    );
+
+    var calls = 0;
+    var debounced = debounce(function () { calls++; }, 300);
+    debounced(); debounced(); debounced();
+    set(
+      "demo-deb",
+      "debounced() x3 in one tick\n" +
+        "=> fn fires once after 300ms quiet\n" +
+        "calls so far: " + calls
+    );
+    setTimeout(function () {
+      var el = document.getElementById("demo-deb");
+      if (el)
+        el.textContent =
+          "debounced() x3 in one tick\n" +
+          "=> fn fired exactly once\n" +
+          "calls: " + calls;
+    }, 450);
+
+    /* copy install button */
+    var btn = document.getElementById("copy-install");
+    if (btn) {
+      btn.addEventListener("click", function () {
+        var text = "npm install lumen-lib";
+        var done = function () {
+          btn.textContent = "copied";
+          btn.classList.add("done");
+          setTimeout(function () {
+            btn.textContent = "copy";
+            btn.classList.remove("done");
+          }, 1400);
+        };
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          navigator.clipboard.writeText(text).then(done, fallback);
+        } else {
+          fallback();
+        }
+        function fallback() {
+          var ta = document.createElement("textarea");
+          ta.value = text;
+          ta.style.position = "fixed";
+          ta.style.opacity = "0";
+          document.body.appendChild(ta);
+          ta.select();
+          try {
+            document.execCommand("copy");
+          } catch (e) {}
+          document.body.removeChild(ta);
+          done();
+        }
+      });
+    }
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", mount);
+  } else {
+    mount();
+  }
+})();

package/index.cjs

@@ -0,0 +1,324 @@
+"use strict";
+
+/**
+ * lumen-lib — tiny, dependency-free utilities for modern web apps.
+ *
+ * Everything is exported as a named ESM export. No runtime dependencies,
+ * no polyfills, works in browsers and Node >= 14.
+ */
+
+/* ------------------------------------------------------------------ */
+/* classnames                                                          */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Join class names, ignoring falsy values.
+ * @param {...(string | false | null | undefined)} classes
+ * @returns {string}
+ */
+function cn(...classes) {
+  return classes.filter(Boolean).join(" ");
+}
+
+/* ------------------------------------------------------------------ */
+/* strings                                                             */
+/* ------------------------------------------------------------------ */
+
+/** Capitalize the first character of a string. */
+function capitalize(s) {
+  const str = String(s ?? "");
+  return str ? str[0].toUpperCase() + str.slice(1) : "";
+}
+
+/** Convert a string to kebab-case. */
+function kebabCase(s) {
+  return String(s ?? "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-zA-Z0-9-]/g, "")
+    .toLowerCase();
+}
+
+/** Convert a string to camelCase. */
+function camelCase(s) {
+  return String(s ?? "")
+    .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""))
+    .replace(/^[A-Z]/, (c) => c.toLowerCase());
+}
+
+/** Truncate a string to `max` chars, appending an ellipsis when cut. */
+function truncate(s, max = 80, ellipsis = "…") {
+  const str = String(s ?? "");
+  if (str.length <= max) return str;
+  return str.slice(0, Math.max(0, max - ellipsis.length)) + ellipsis;
+}
+
+/** Strip all HTML tags from a string. */
+function stripHtml(s) {
+  return String(s ?? "").replace(/<[^>]*>/g, "");
+}
+
+/* ------------------------------------------------------------------ */
+/* formatting                                                          */
+/* ------------------------------------------------------------------ */
+
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB", "PB"];
+
+/** Format a byte count as a human-readable string (e.g. "1.5 MB"). */
+function formatBytes(bytes, decimals = 1) {
+  const n = Number(bytes);
+  if (!Number.isFinite(n) || n < 0) return "0 B";
+  if (n === 0) return "0 B";
+  const i = Math.min(Math.floor(Math.log(n) / Math.log(1024)), BYTE_UNITS.length - 1);
+  const v = n / 1024 ** i;
+  return `${v >= 100 || i === 0 ? Math.round(v) : v.toFixed(decimals)} ${BYTE_UNITS[i]}`;
+}
+
+/** Format a number with locale grouping (e.g. 1,234,567). */
+function formatNumber(n, locale = "en-US") {
+  const v = Number(n);
+  if (!Number.isFinite(v)) return String(n ?? "");
+  return v.toLocaleString(locale);
+}
+
+/** Compact number format: 1200 -> "1.2K", 3400000 -> "3.4M". */
+function formatCompact(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v)) return String(n ?? "");
+  const abs = Math.abs(v);
+  const units = [
+    [1e12, "T"],
+    [1e9, "B"],
+    [1e6, "M"],
+    [1e3, "K"],
+  ];
+  for (const [size, suffix] of units) {
+    if (abs >= size) {
+      const r = v / size;
+      return `${r >= 100 ? Math.round(r) : r.toFixed(1).replace(/\.0$/, "")}${suffix}`;
+    }
+  }
+  return String(v);
+}
+
+/** Relative time: timeAgo(date) -> "3 minutes ago". */
+function timeAgo(date, now = Date.now()) {
+  const then = date instanceof Date ? date.getTime() : new Date(date).getTime();
+  if (!Number.isFinite(then)) return "";
+  const diff = Math.max(0, now - then);
+  const units = [
+    ["year", 31536000000],
+    ["month", 2592000000],
+    ["week", 604800000],
+    ["day", 86400000],
+    ["hour", 3600000],
+    ["minute", 60000],
+    ["second", 1000],
+  ];
+  for (const [name, ms] of units) {
+    const v = Math.floor(diff / ms);
+    if (v >= 1) return `${v} ${name}${v === 1 ? "" : "s"} ago`;
+  }
+  return "just now";
+}
+
+/* ------------------------------------------------------------------ */
+/* math                                                                */
+/* ------------------------------------------------------------------ */
+
+/** Clamp `n` between `min` and `max`. */
+function clamp(n, min, max) {
+  return Math.min(Math.max(n, min), max);
+}
+
+/** Linear interpolation between `a` and `b` by `t` (0..1). */
+function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+
+/** Random integer in [min, max] inclusive. */
+function randomInt(min = 0, max = 1) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/** Map `n` from one range to another, optionally clamped. */
+function mapRange(n, inMin, inMax, outMin, outMax, clampResult = true) {
+  const t = (n - inMin) / (inMax - inMin);
+  const out = outMin + t * (outMax - outMin);
+  return clampResult ? clamp(out, Math.min(outMin, outMax), Math.max(outMin, outMax)) : out;
+}
+
+/* ------------------------------------------------------------------ */
+/* objects & arrays                                                    */
+/* ------------------------------------------------------------------ */
+
+/** Deep-merge plain objects; later sources win. Arrays are replaced. */
+function deepMerge(target, ...sources) {
+  const out = { ...(target && typeof target === "object" ? target : {}) };
+  for (const src of sources) {
+    if (!src || typeof src !== "object") continue;
+    for (const [k, v] of Object.entries(src)) {
+      const prev = out[k];
+      out[k] =
+        prev && v && typeof prev === "object" && typeof v === "object" &&
+        !Array.isArray(prev) && !Array.isArray(v)
+          ? deepMerge(prev, v)
+          : v;
+    }
+  }
+  return out;
+}
+
+/** Return a copy of `obj` without the listed keys. */
+function omit(obj, keys) {
+  const drop = new Set(Array.isArray(keys) ? keys : [keys]);
+  const out = {};
+  for (const [k, v] of Object.entries(obj ?? {})) if (!drop.has(k)) out[k] = v;
+  return out;
+}
+
+/** Return a new object with only the listed keys. */
+function pick(obj, keys) {
+  const want = new Set(Array.isArray(keys) ? keys : [keys]);
+  const out = {};
+  for (const k of want) if (obj && k in obj) out[k] = obj[k];
+  return out;
+}
+
+/** Split an array into chunks of `size`. */
+function chunk(arr, size = 1) {
+  const list = Array.isArray(arr) ? arr : [];
+  const n = Math.max(1, Math.floor(size));
+  const out = [];
+  for (let i = 0; i < list.length; i += n) out.push(list.slice(i, i + n));
+  return out;
+}
+
+/** Deduplicate an array (primitive-safe via SameValueZero). */
+function unique(arr) {
+  return [...new Set(Array.isArray(arr) ? arr : [])];
+}
+
+/** Group array items by the key returned from `fn`. */
+function groupBy(arr, fn) {
+  const out = {};
+  for (const item of Array.isArray(arr) ? arr : []) {
+    const k = fn(item);
+    (out[k] ??= []).push(item);
+  }
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/* functions                                                           */
+/* ------------------------------------------------------------------ */
+
+/** Debounce: call `fn` after `ms` of quiet. Returns a cancelable fn. */
+function debounce(fn, ms = 200) {
+  let t = null;
+  const debounced = (...args) => {
+    clearTimeout(t);
+    t = setTimeout(() => fn(...args), ms);
+  };
+  debounced.cancel = () => clearTimeout(t);
+  return debounced;
+}
+
+/** Throttle: call `fn` at most once per `ms`. Trailing edge by default. */
+function throttle(fn, ms = 200) {
+  let last = 0;
+  let timer = null;
+  return (...args) => {
+    const now = Date.now();
+    const run = () => {
+      last = Date.now();
+      fn(...args);
+    };
+    if (now - last >= ms) run();
+    else if (!timer) timer = setTimeout(() => { timer = null; run(); }, ms - (now - last));
+  };
+}
+
+/** Wrap `fn` so it only executes once; later calls return the first result. */
+function once(fn) {
+  let called = false;
+  let result;
+  return (...args) => {
+    if (!called) {
+      called = true;
+      result = fn(...args);
+    }
+    return result;
+  };
+}
+
+/** Resolve after `ms` milliseconds. */
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** Retry an async `fn` up to `tries` times with linear backoff. */
+async function retry(fn, tries = 3, delay = 250) {
+  let lastErr;
+  for (let i = 0; i < tries; i++) {
+    try {
+      return await fn(i);
+    } catch (e) {
+      lastErr = e;
+      if (i < tries - 1) await sleep(delay * (i + 1));
+    }
+  }
+  throw lastErr;
+}
+
+/* ------------------------------------------------------------------ */
+/* validation                                                          */
+/* ------------------------------------------------------------------ */
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** Loose email format check. */
+function isEmail(s) {
+  return EMAIL_RE.test(String(s ?? ""));
+}
+
+/** Loose URL check: accepts http(s) URLs or bare domains. */
+function isUrl(s) {
+  const str = String(s ?? "").trim();
+  if (!str) return false;
+  try {
+    const u = new URL(str.includes("://") ? str : `https://${str}`);
+    return !!u.hostname && u.hostname.includes(".");
+  } catch {
+    return false;
+  }
+}
+
+/** True for non-empty strings. */
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+/* ------------------------------------------------------------------ */
+/* ids                                                                 */
+/* ------------------------------------------------------------------ */
+
+const ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+
+/** Random id: uid(8) -> "k3j9x2ab". Prefers crypto.randomUUID when available. */
+function uid(length = 8) {
+  if (typeof crypto !== "undefined" && crypto.randomUUID && length === 36)
+    return crypto.randomUUID();
+  let out = "";
+  const bytes = new Uint8Array(length);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(bytes);
+    for (const b of bytes) out += ID_ALPHABET[b % ID_ALPHABET.length];
+  } else {
+    for (let i = 0; i < length; i++) out += ID_ALPHABET[randomInt(0, ID_ALPHABET.length - 1)];
+  }
+  return out;
+}
+
+
+module.exports = { cn, capitalize, kebabCase, camelCase, truncate, stripHtml, formatBytes, formatNumber, formatCompact, timeAgo, clamp, lerp, randomInt, mapRange, deepMerge, omit, pick, chunk, unique, groupBy, debounce, throttle, once, sleep, retry, isEmail, isUrl, isNonEmptyString, uid };

package/index.d.ts

@@ -0,0 +1,76 @@
+export declare function cn(
+  ...classes: Array<string | false | null | undefined>
+): string;
+
+export declare function capitalize(s: unknown): string;
+export declare function kebabCase(s: unknown): string;
+export declare function camelCase(s: unknown): string;
+export declare function truncate(
+  s: unknown,
+  max?: number,
+  ellipsis?: string
+): string;
+export declare function stripHtml(s: unknown): string;
+
+export declare function formatBytes(bytes: unknown, decimals?: number): string;
+export declare function formatNumber(n: unknown, locale?: string): string;
+export declare function formatCompact(n: unknown): string;
+export declare function timeAgo(
+  date: Date | string | number,
+  now?: number
+): string;
+
+export declare function clamp(n: number, min: number, max: number): number;
+export declare function lerp(a: number, b: number, t: number): number;
+export declare function randomInt(min?: number, max?: number): number;
+export declare function mapRange(
+  n: number,
+  inMin: number,
+  inMax: number,
+  outMin: number,
+  outMax: number,
+  clampResult?: boolean
+): number;
+
+export declare function deepMerge<T extends object>(
+  target: T,
+  ...sources: object[]
+): T;
+export declare function omit<T extends object, K extends keyof T>(
+  obj: T,
+  keys: K | K[]
+): Partial<T>;
+export declare function pick<T extends object, K extends keyof T>(
+  obj: T,
+  keys: K | K[]
+): Partial<T>;
+export declare function chunk<T>(arr: T[], size?: number): T[][];
+export declare function unique<T>(arr: T[]): T[];
+export declare function groupBy<T, K extends string | number>(
+  arr: T[],
+  fn: (item: T) => K
+): Record<K, T[]>;
+
+export declare function debounce<T extends (...args: never[]) => void>(
+  fn: T,
+  ms?: number
+): T & { cancel: () => void };
+export declare function throttle<T extends (...args: never[]) => void>(
+  fn: T,
+  ms?: number
+): T;
+export declare function once<T extends (...args: never[]) => unknown>(
+  fn: T
+): T;
+export declare function sleep(ms: number): Promise<void>;
+export declare function retry<T>(
+  fn: (attempt: number) => Promise<T>,
+  tries?: number,
+  delay?: number
+): Promise<T>;
+
+export declare function isEmail(s: unknown): boolean;
+export declare function isUrl(s: unknown): boolean;
+export declare function isNonEmptyString(v: unknown): v is string;
+
+export declare function uid(length?: number): string;

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "lumen-lib",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.1.0",
+  "description": "Small, dependency-free utilities for modern web apps \u2014 classnames, strings, formatting, math, objects, and async helpers.",
+  "main": "index.cjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.cjs",
+      "require": "./index.cjs"
+    }
+  },
+  "files": [
+    "index.cjs",
+    "index.d.ts",
+    "assets"
+  ],
+  "keywords": [
+    "utility",
+    "utilities",
+    "helpers",
+    "classname",
+    "cn",
+    "debounce",
+    "formatting",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  }
+}