tiny-essentials 1.24.3 → 1.24.5

package/dist/v1/TinySimpleDice.min.js

@@ -1 +1 @@
-(()=>{"use strict";var e={d:(r,o)=>{for(var a in o)e.o(o,a)&&!e.o(r,a)&&Object.defineProperty(r,a,{enumerable:!0,get:o[a]})},o:(e,r)=>Object.prototype.hasOwnProperty.call(e,r)},r={};e.d(r,{TinySimpleDice:()=>o});const o=class{static rollArrayIndex(e){const r=Array.isArray(e),o=e instanceof Set;if(!r&&!o)throw new TypeError("rollArrayIndex expects an array or Set.");return Math.floor(Math.random()*(r?e.length:e.size))}#e;#r;get maxValue(){return this.#e}set maxValue(e){if(!Number.isInteger(e)||e<0)throw new TypeError("maxValue must be an integer greater than -1.");this.#e=e}get allowZero(){return this.#r}set allowZero(e){if("boolean"!=typeof e)throw new TypeError("allowZero must be a boolean.");this.#r=e}constructor({maxValue:e,allowZero:r=!0}){if("boolean"!=typeof r)throw new TypeError("allowZero must be an boolean.");if(!Number.isInteger(e)||e<0)throw new TypeError("maxValue must be an integer greater than -1.");this.#e=e,this.#r=r}roll(){const e=this.#r?0:1;return Math.floor(Math.random()*(this.#e-e+1))+e}};window.TinySimpleDice=r.TinySimpleDice})();
+(()=>{"use strict";var e={d:(r,t)=>{for(var o in t)e.o(t,o)&&!e.o(r,o)&&Object.defineProperty(r,o,{enumerable:!0,get:t[o]})},o:(e,r)=>Object.prototype.hasOwnProperty.call(e,r)},r={};function t(e){return null!==e&&"object"==typeof e&&!Array.isArray(e)&&"[object Object]"===Object.prototype.toString.call(e)}e.d(r,{TinySimpleDice:()=>n});class o{static _safeEvaluate(e){if(!/^[\d+\-*/%.()\s^]+$/.test(e))throw new Error(`Invalid characters in expression: "${e}"`);const r=e.replace(/\^/g,"**");try{return Function(`"use strict"; return (${r})`)()}catch(r){if(!(r instanceof Error))throw new Error("Unknown Error");throw new Error(`Invalid expression "${e}": ${r.message}`)}}static replaceValues(e,r){let t=0;return e.replace(/(\d*)d(\d+)/g,(e,o)=>{const n=o?Number(o):1;let s=0;for(let e=0;e<n;e++){const e=r[t++];s+=void 0!==e?e:0}return String(s)})}static tokenizeValues(e,r){const t=o.replaceValues(e,r),n=[],s=/\d+|[()+\-*/]/g;let a;for(;null!==(a=s.exec(t));)/^\d+$/.test(a[0])?n.push(Number(a[0])):n.push(a[0]);return{tokens:n,text:t}}static parseString(e){if("string"!=typeof e)throw new TypeError("Input must be a string.");const r=e.split(",").map(e=>e.trim()).filter(Boolean),t=[],o=[];if(r.forEach((e,r)=>{const n=/\b(?:(\d+)?d(\d+))\b/g;let s;const a=[],i=e.replace(/\(([^()]+?\|[^()]+?)\)/g,(e,r)=>{const t="string"==typeof r?r.split("|").map(e=>e.trim()).filter(Boolean):[];if(0===t.length)throw new Error(`Invalid random-choice group: "${e}"`);return t[Math.floor(Math.random()*t.length)]});for(;null!==(s=n.exec(i));){const e=parseInt(s[1]||"1",10),t=parseInt(s[2],10);if(isNaN(t))throw new Error(`Invalid dice sides in expression "${s[0]}" at position ${r+1}.`);a.push({count:e,sides:t})}if(0===a.length&&Number.isNaN(parseFloat(i)))throw new Error(`Invalid dice expression at position ${r+1}: "${e}"`);t.push(...a),o.push({index:r,original:e,expression:i})}),0===t.length)throw new Error("Invalid dice amount.");return{sides:t,modifiers:o}}static applyModifiers(e,r){if(!Array.isArray(e)||!e.every(e=>"number"==typeof e&&!Number.isNaN(e)||t(e)&&"number"==typeof e.value&&!Number.isNaN(e.value)&&"number"==typeof e.sides&&!Number.isNaN(e.sides)))throw new TypeError("Bases must be a valid numbers.");if(!Array.isArray(r))throw new TypeError("Modifiers must be an array of modifier objects.");let n=0;const s=[],a=[...e];for(const e in r){const i=r[e];if("string"!=typeof i.expression)throw new Error("Each modifier must include an expression string.");const l=i.original,u=i.expression,c=[],p=[],f=[],h=e=>e.match(/\(\s*[^()]+\|\s*[^()]+\s*\)|\b\d*d\d+\b|[-+]?\d+(?:\.\d+)?|[+\-*/%^()]/g)||[],d=h(u),m=h(l),w=[...d],b=[],y=u.replace(/\b\d*d\d+\b/g,e=>{const r=e.split("d"),o=()=>{for(const r in d)if(d[r]===e&&b.indexOf(r)<0){b.push(r),f.push(Number(r));break}},n=e=>{if(e.value>e.sides)throw new Error(`Invalid dice roll: value (${e.value}) must be between 1 and ${e.sides}.`)};if(0===r[0].trim().length){const r=a.shift(),s="number"==typeof r?r:t(r)?r.value:0;t(r)&&n(r),c.push([s]);for(const r in w)if(w[r]===e){w[r]=String(s),p.push(Number(r));break}return o(),s}const s=[],i=Number(r[0]),l=["("];let u="(";for(let e=0;e<i;e++){const r=a.shift(),o="number"==typeof r?r:t(r)?r.value:0;t(r)&&n(r),l.push(String(o));const c=e<i-1?" + ":")";l.push(c),u+=`${o}${c}`,s.push(o)}for(const r in w){const t=Number(r);if(w[t]===e){w.splice(t,1,...l);let e=1;for(let r=0;r<i;r++)p.push(t+r+e),e++;break}}return c.push(s),o(),u});let g;try{g=o._safeEvaluate(y)}catch(e){if(!(e instanceof Error))throw new Error("Unknown Error");throw new Error(`Error evaluating expression "${y}" (from "${u}"): ${e.message}`)}s.push({rawTokensP:d,rawTokens:m,tokens:w,rawDiceTokenSlots:f,diceTokenSlots:p,dicesResult:c,total:g}),n+=g}return{final:n,steps:s}}static rollArrayIndex(e){const r=Array.isArray(e),t=e instanceof Set;if(!r&&!t)throw new TypeError("rollArrayIndex expects an array or Set.");return Math.floor(Math.random()*(r?e.length:e.size))}#e;#r;get maxValue(){return this.#e}set maxValue(e){if(!Number.isInteger(e)||e<0)throw new TypeError("maxValue must be an integer greater than -1.");this.#e=e}get allowZero(){return this.#r}set allowZero(e){if("boolean"!=typeof e)throw new TypeError("allowZero must be a boolean.");this.#r=e}constructor({maxValue:e,allowZero:r=!0}){if("boolean"!=typeof r)throw new TypeError("allowZero must be an boolean.");if(!Number.isInteger(e)||e<0)throw new TypeError("maxValue must be an integer greater than -1.");this.#e=e,this.#r=r}roll(){const e=this.#r?0:1;return Math.floor(Math.random()*(this.#e-e+1))+e}}const n=o;window.TinySimpleDice=r.TinySimpleDice})();

package/dist/v1/libs/TinyHtml/index.cjs

@@ -5,6 +5,13 @@ var TinyHtmlResetInput = require('./input/button/TinyHtmlResetInput.cjs');
 var TinyHtmlSubmitInput = require('./input/button/TinyHtmlSubmitInput.cjs');
 var TinyHtmlNumberInput = require('./input/number/TinyHtmlNumberInput.cjs');
 var TinyHtmlRangeInput = require('./input/number/TinyHtmlRangeInput.cjs');
+var TinyHtmlCheckboxInput = require('./input/check/TinyHtmlCheckboxInput.cjs');
+var TinyHtmlRadioInput = require('./input/check/TinyHtmlRadioInput.cjs');
+var TinyHtmlDateInput = require('./input/date/TinyHtmlDateInput.cjs');
+var TinyHtmlDateTimeInput = require('./input/date/TinyHtmlDateTimeInput.cjs');
+var TinyHtmlMonthInput = require('./input/date/TinyHtmlMonthInput.cjs');
+var TinyHtmlTimeInput = require('./input/date/TinyHtmlTimeInput.cjs');
+var TinyHtmlWeekInput = require('./input/date/TinyHtmlWeekInput.cjs');
 var TinyHtmlEmailInput = require('./input/text/TinyHtmlEmailInput.cjs');
 var TinyHtmlPasswordInput = require('./input/text/TinyHtmlPasswordInput.cjs');
 var TinyHtmlSearchInput = require('./input/text/TinyHtmlSearchInput.cjs');
@@ -100,11 +107,25 @@ class TinyHtmlElems {
   static SubmitInput = TinyHtmlSubmitInput;
 
   /////////////////////////////////////////////////////
+
   static NumberInput = TinyHtmlNumberInput;
   static RangerInput = TinyHtmlRangeInput;
 
   //////////////////////////////////////////////////
 
+  static CheckboxInput = TinyHtmlCheckboxInput;
+  static RadioInput = TinyHtmlRadioInput;
+
+  //////////////////////////////////////////////////
+
+  static DateInput = TinyHtmlDateInput;
+  static DateTimeInput = TinyHtmlDateTimeInput;
+  static MonthInput = TinyHtmlMonthInput;
+  static TimeInput = TinyHtmlTimeInput;
+  static WeekInput = TinyHtmlWeekInput;
+
+  //////////////////////////////////////////////////
+
   static EmailInput = TinyHtmlEmailInput;
   static PasswordInput = TinyHtmlPasswordInput;
   static SearchInput = TinyHtmlSearchInput;
@@ -163,6 +184,18 @@ export {
   TinyHtmlNumberInput,
   TinyHtmlRangeInput,
   //////////////////////////////////////////////////
+
+  TinyHtmlCheckboxInput;
+  TinyHtmlRadioInput;
+
+  //////////////////////////////////////////////////
+
+  TinyHtmlDateInput;
+  TinyHtmlDateTimeInput;
+  TinyHtmlMonthInput;
+  TinyHtmlTimeInput;
+  TinyHtmlWeekInput;
+
   TinyHtmlEmailInput,
   TinyHtmlPasswordInput,
   TinyHtmlSearchInput,

package/dist/v1/libs/TinyHtml/index.d.mts

@@ -11,6 +11,13 @@ declare class TinyHtmlElems {
     static SubmitInput: typeof TinyHtmlSubmitInput;
     static NumberInput: typeof TinyHtmlNumberInput;
     static RangerInput: typeof TinyHtmlRangeInput;
+    static CheckboxInput: typeof TinyHtmlCheckboxInput;
+    static RadioInput: typeof TinyHtmlRadioInput;
+    static DateInput: typeof TinyHtmlDateInput;
+    static DateTimeInput: typeof TinyHtmlDateTimeInput;
+    static MonthInput: typeof TinyHtmlMonthInput;
+    static TimeInput: typeof TinyHtmlTimeInput;
+    static WeekInput: typeof TinyHtmlWeekInput;
     static EmailInput: typeof TinyHtmlEmailInput;
     static PasswordInput: typeof TinyHtmlPasswordInput;
     static SearchInput: typeof TinyHtmlSearchInput;
@@ -71,6 +78,13 @@ import TinyHtmlSource from './media/TinyHtmlSource.mjs';
 import TinyHtmlButtonInput from './input/button/TinyHtmlButtonInput.mjs';
 import TinyHtmlSubmitInput from './input/button/TinyHtmlSubmitInput.mjs';
 import TinyHtmlRangeInput from './input/number/TinyHtmlRangeInput.mjs';
+import TinyHtmlCheckboxInput from './input/check/TinyHtmlCheckboxInput.mjs';
+import TinyHtmlRadioInput from './input/check/TinyHtmlRadioInput.mjs';
+import TinyHtmlDateInput from './input/date/TinyHtmlDateInput.mjs';
+import TinyHtmlDateTimeInput from './input/date/TinyHtmlDateTimeInput.mjs';
+import TinyHtmlMonthInput from './input/date/TinyHtmlMonthInput.mjs';
+import TinyHtmlTimeInput from './input/date/TinyHtmlTimeInput.mjs';
+import TinyHtmlWeekInput from './input/date/TinyHtmlWeekInput.mjs';
 import TinyHtmlEmailInput from './input/text/TinyHtmlEmailInput.mjs';
 import TinyHtmlPasswordInput from './input/text/TinyHtmlPasswordInput.mjs';
 import TinyHtmlSearchInput from './input/text/TinyHtmlSearchInput.mjs';

package/dist/v1/libs/TinyHtml/index.mjs

@@ -6,6 +6,15 @@ import TinyHtmlSubmitInput from './input/button/TinyHtmlSubmitInput.mjs';
 import TinyHtmlNumberInput from './input/number/TinyHtmlNumberInput.mjs';
 import TinyHtmlRangeInput from './input/number/TinyHtmlRangeInput.mjs';
 //////////////////////////////////////////////////
+import TinyHtmlCheckboxInput from './input/check/TinyHtmlCheckboxInput.mjs';
+import TinyHtmlRadioInput from './input/check/TinyHtmlRadioInput.mjs';
+//////////////////////////////////////////////////
+import TinyHtmlDateInput from './input/date/TinyHtmlDateInput.mjs';
+import TinyHtmlDateTimeInput from './input/date/TinyHtmlDateTimeInput.mjs';
+import TinyHtmlMonthInput from './input/date/TinyHtmlMonthInput.mjs';
+import TinyHtmlTimeInput from './input/date/TinyHtmlTimeInput.mjs';
+import TinyHtmlWeekInput from './input/date/TinyHtmlWeekInput.mjs';
+//////////////////////////////////////////////////
 import TinyHtmlEmailInput from './input/text/TinyHtmlEmailInput.mjs';
 import TinyHtmlPasswordInput from './input/text/TinyHtmlPasswordInput.mjs';
 import TinyHtmlSearchInput from './input/text/TinyHtmlSearchInput.mjs';
@@ -99,6 +108,15 @@ class TinyHtmlElems {
     static NumberInput = TinyHtmlNumberInput;
     static RangerInput = TinyHtmlRangeInput;
     //////////////////////////////////////////////////
+    static CheckboxInput = TinyHtmlCheckboxInput;
+    static RadioInput = TinyHtmlRadioInput;
+    //////////////////////////////////////////////////
+    static DateInput = TinyHtmlDateInput;
+    static DateTimeInput = TinyHtmlDateTimeInput;
+    static MonthInput = TinyHtmlMonthInput;
+    static TimeInput = TinyHtmlTimeInput;
+    static WeekInput = TinyHtmlWeekInput;
+    //////////////////////////////////////////////////
     static EmailInput = TinyHtmlEmailInput;
     static PasswordInput = TinyHtmlPasswordInput;
     static SearchInput = TinyHtmlSearchInput;
@@ -148,6 +166,18 @@ export {
   TinyHtmlNumberInput,
   TinyHtmlRangeInput,
   //////////////////////////////////////////////////
+
+  TinyHtmlCheckboxInput;
+  TinyHtmlRadioInput;
+
+  //////////////////////////////////////////////////
+
+  TinyHtmlDateInput;
+  TinyHtmlDateTimeInput;
+  TinyHtmlMonthInput;
+  TinyHtmlTimeInput;
+  TinyHtmlWeekInput;
+
   TinyHtmlEmailInput,
   TinyHtmlPasswordInput,
   TinyHtmlSearchInput,

package/dist/v1/libs/TinySimpleDice.cjs

@@ -1,5 +1,45 @@
 'use strict';
 
+var objChecker = require('../basics/objChecker.cjs');
+
+/**
+ * Represents a list of values used in dice modifier operations.
+ *
+ * Each entry can be either:
+ * - A number (representing a fixed numeric value), or
+ * - An object describing a dice roll, containing:
+ *   - `value`: The rolled result.
+ *   - `sides`: The number of sides of the die (e.g., 6 for a d6).
+ *
+ * Examples of valid entries:
+ * - `5`                   → a direct numeric value
+ * - `{ value: 3, sides: 6 }` → result of rolling a d6
+ *
+ * @typedef {(number | { value: number; sides: number })[]} DiceModifiersValues
+ */
+
+/**
+ * Represents the result after applying all dice modifiers to a roll.
+ *
+ * @typedef {Object} ApplyDiceModifiersResult
+ * @property {number} final - The final computed value after all modifiers and dice results are processed.
+ * @property {ApplyDiceModifiersStep[]} steps - A detailed, ordered list of steps describing how the final value was obtained.
+ */
+
+/**
+ * Represents a single step in the dice-modification process.
+ *
+ * @typedef {Object} ApplyDiceModifiersStep
+ * @property {string[]} tokens - The parsed tokens used in this step after normalization.
+ * @property {string[]} rawTokensP - The raw tokens preserved in their partially processed state.
+ * @property {string[]} rawTokens - The original unprocessed tokens extracted from the expression.
+ * @property {number[]} rawDiceTokenSlots - Index references pointing to where each raw dice token appears in the original expression.
+ * @property {number[]} diceTokenSlots - Index references for processed/normalized dice tokens within the final evaluation sequence.
+ * @property {number} total - The computed subtotal for this step, before aggregation in later steps.
+ * @property {Array<number[]>} dicesResult - A list containing the result set of each dice roll.
+ *    Each entry represents a single dice token and contains an array with the rolled numbers.
+ */
+
 /**
  * TinySimpleDice
  *
@@ -8,6 +48,394 @@
  * values suitable for indexing arrays or Sets.
  */
 class TinySimpleDice {
+  /**
+   * Safely evaluates a mathematical expression (supports +, -, *, /, %, **, parentheses, fractions and decimals).
+   * This function ensures only valid math characters are processed.
+   *
+   * @param {string} expression - Mathematical expression to evaluate.
+   * @returns {number} The calculated numeric result.
+   * @private
+   */
+  static _safeEvaluate(expression) {
+    // Sanitize and validate only allowed math-safe characters
+    if (!/^[\d+\-*/%.()\s^]+$/.test(expression)) {
+      throw new Error(`Invalid characters in expression: "${expression}"`);
+    }
+
+    // Normalize power operator: allow both ** and ^ for exponentiation
+    const normalized = expression.replace(/\^/g, '**');
+
+    try {
+      // Create isolated, safe Function (no variables, only math ops)
+      return Function(`"use strict"; return (${normalized})`)();
+    } catch (err) {
+      if (!(err instanceof Error)) throw new Error('Unknown Error');
+      throw new Error(`Invalid expression "${expression}": ${err.message}`);
+    }
+  }
+
+  /**
+   * Replaces dice patterns such as `d6`, `d32`, or multi-dice patterns like `3d6`
+   * using sequential values from the provided array.
+   *
+   * - `d6` consumes 1 value from the array.
+   * - `3d6` consumes 3 values from the array and replaces the pattern with their sum.
+   *
+   * If there are not enough values available, missing rolls default to 0.
+   *
+   * @param {string} input - The input string containing dice patterns.
+   * @param {number[]} values - Sequential numeric values used to replace each dice roll.
+   * @returns {string} The resulting string where each dice expression is replaced by its computed value.
+   *
+   * @example
+   * replaceValues("You deal d6 damage", [4]);
+   * // → "You deal 4 damage"
+   *
+   * @example
+   * replaceValues("Roll 3d6 for strength", [3, 5, 2]);
+   * // → "Roll 10 for strength"
+   *
+   * @example
+   * replaceValues("Attack: 2d4 + d8", [1, 3, 7]);
+   * // → "Attack: 4 + 7"
+   */
+  static replaceValues(input, values) {
+    let index = 0;
+
+    return input.replace(/(\d*)d(\d+)/g, (match, qty) => {
+      const count = qty ? Number(qty) : 1; // default is 1dX
+      let total = 0;
+
+      for (let i = 0; i < count; i++) {
+        const value = values[index++];
+        total += value !== undefined ? value : 0;
+      }
+
+      return String(total);
+    });
+  }
+
+  /**
+   * Tokenizes an expression string while replacing dice patterns (`d6`, `3d6`, etc.)
+   * with numeric values taken sequentially from the provided array.
+   *
+   * This function performs two operations:
+   * 1. Dice replacement:
+   *    - `d6` consumes 1 value.
+   *    - `3d6` consumes 3 values and returns their sum.
+   *    - Missing values default to 0.
+   *
+   * 2. Tokenization:
+   *    - Numbers become numeric tokens.
+   *    - Operators (`+`, `-`, `*`, `/`, `(`, `)`) become string tokens.
+   *
+   * Example:
+   * Input:  "2d6 + 4 - d8"
+   * Values: [3, 4, 5]
+   * Output: [7, "+", 4, "-", 5]
+   *
+   * @param {string} input - The input string containing dice expressions.
+   * @param {number[]} values - Sequential numbers used to replace each dice roll.
+   * @returns {{ tokens: (string|number)[], text: string }} A tokenized list where dice expressions become numbers.
+   *
+   * @example
+   * tokenizeValues("You deal d6 + 2", [4]);
+   * // → [4, "+", 2]
+   *
+   * @example
+   * tokenizeValues("3d6 + d4", [3, 5, 2, 1]);
+   * // → [10, "+", 1]
+   *
+   * @example
+   * tokenizeValues("2d4 - 1d8 + 7", [1, 3, 7]);
+   * // → [4, "-", 7, "+", 7]
+   */
+  static tokenizeValues(input, values) {
+    // Tokenizer: numbers become numbers, operators become strings.
+    const replaced = TinySimpleDice.replaceValues(input, values);
+    const tokens = [];
+    const regex = /\d+|[()+\-*/]/g;
+    let match;
+
+    while ((match = regex.exec(replaced)) !== null) {
+      if (/^\d+$/.test(match[0])) {
+        tokens.push(Number(match[0]));
+      } else {
+        tokens.push(match[0]);
+      }
+    }
+
+    return { tokens, text: replaced };
+  }
+
+  /**
+   * Parses a dice configuration string supporting notations like "6d" (one d6) or "3d6" (three d6).
+   * Extracts all valid dice expressions and keeps their full context as modifiers.
+   *
+   * @param {string} input - Comma-separated dice expressions.
+   * @returns {{
+   *   sides: { count: number, sides: number }[],
+   *   modifiers: { index: number, original: string, expression: string }[]
+   * }}
+   */
+  static parseString(input) {
+    if (typeof input !== 'string') {
+      throw new TypeError('Input must be a string.');
+    }
+
+    const parts = input
+      .split(',')
+      .map((p) => p.trim())
+      .filter(Boolean);
+
+    /** @type {{ count: number, sides: number }[]} */
+    const sides = [];
+
+    /** @type {{ index: number, original: string, expression: string }[]} */
+    const modifiers = [];
+
+    parts.forEach((part, i) => {
+      // ✅ Match dice patterns:
+      // - 6d  → one d6
+      // - 3d6 → three d6
+      // - 12d100 → twelve d100
+      const regex = /\b(?:(\d+)?d(\d+))\b/g;
+      let match;
+      const foundDice = [];
+
+      // --- 🔸 Resolve random choice groups like (0 | 1 | d1)
+      const finalPart = part.replace(/\(([^()]+?\|[^()]+?)\)/g, (match, inner) => {
+        const options =
+          typeof inner === 'string'
+            ? inner
+                .split('|')
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : [];
+
+        if (options.length === 0) throw new Error(`Invalid random-choice group: "${match}"`);
+
+        const chosen = options[Math.floor(Math.random() * options.length)];
+        return chosen;
+      });
+
+      while ((match = regex.exec(finalPart)) !== null) {
+        const count = parseInt(match[1] || '1', 10); // Default to 1 if not specified (e.g. "d6" or "6d")
+        const sidesCount = parseInt(match[2], 10);
+
+        if (isNaN(sidesCount)) {
+          throw new Error(`Invalid dice sides in expression "${match[0]}" at position ${i + 1}.`);
+        }
+
+        foundDice.push({ count, sides: sidesCount });
+      }
+
+      if (foundDice.length === 0 && Number.isNaN(parseFloat(finalPart))) {
+        throw new Error(`Invalid dice expression at position ${i + 1}: "${part}"`);
+      }
+
+      // Add all found dice
+      sides.push(...foundDice);
+
+      // Store full expression
+      modifiers.push({
+        index: i,
+        original: part,
+        expression: finalPart,
+      });
+    });
+
+    if (sides.length === 0) throw new Error(`Invalid dice amount.`);
+
+    return { sides, modifiers };
+  }
+
+  /**
+   * Applies parsed modifiers (expressions) to a base number.
+   * Replaces only the first number in the expression with the current result
+   * before evaluation. Returns an object containing a step-by-step history.
+   *
+   * @param {DiceModifiersValues} values - Starting number (e.g., dice base value).
+   * @param {{ expression: string, original: string }[]} modifiers - Parsed modifiers from TinySimpleDice.parseString.
+   * @returns {ApplyDiceModifiersResult}
+   */
+  static applyModifiers(values, modifiers) {
+    if (
+      !Array.isArray(values) ||
+      !values.every(
+        (n) =>
+          (typeof n === 'number' && !Number.isNaN(n)) ||
+          (objChecker.isJsonObject(n) &&
+            typeof n.value === 'number' &&
+            !Number.isNaN(n.value) &&
+            typeof n.sides === 'number' &&
+            !Number.isNaN(n.sides)),
+      )
+    )
+      throw new TypeError('Bases must be a valid numbers.');
+
+    if (!Array.isArray(modifiers))
+      throw new TypeError('Modifiers must be an array of modifier objects.');
+
+    let result = 0;
+
+    /** @type {ApplyDiceModifiersStep[]} */
+    const steps = [];
+    /** @type {DiceModifiersValues} */
+    const iv = [...values];
+
+    for (const index in modifiers) {
+      const mod = modifiers[index];
+      if (typeof mod.expression !== 'string') {
+        throw new Error('Each modifier must include an expression string.');
+      }
+
+      const originalExp = mod.original;
+      const expression = mod.expression;
+
+      /** @type {Array<number[]>} */
+      const dices = [];
+
+      /** @type {number[]} */
+      const diceTokenSlots = [];
+      /** @type {number[]} */
+      const rawDiceTokenSlots = [];
+
+      /**
+       * Tokenize expression for manipulation or display.
+       * Supports dice, numbers, parentheses, math ops, and choice groups.
+       * Ensures (0 | 1 | d1) is treated as ONE token.
+       * @param {string} value
+       * @returns {string[]}
+       */
+      const matchTokens = (value) =>
+        value.match(/\(\s*[^()]+\|\s*[^()]+\s*\)|\b\d*d\d+\b|[-+]?\d+(?:\.\d+)?|[+\-*/%^()]/g) ||
+        [];
+
+      const rawTokens = matchTokens(expression);
+      const rawTokensOriginal = matchTokens(originalExp);
+      const tokens = [...rawTokens];
+      /** @type {string[]} */
+      const rawSlotsUsed = [];
+
+      // ✅ Replace the first numeric literal (integer/decimal) that may be inside parentheses
+      // @ts-ignore
+      const replacedExpr = expression.replace(/\b\d*d\d+\b/g, (m0) => {
+        // Parse dice numbers
+        const diceParsed = m0.split('d');
+        const getRawTokenSlot = () => {
+          for (const index in rawTokens) {
+            if (rawTokens[index] === m0 && rawSlotsUsed.indexOf(index) < 0) {
+              rawSlotsUsed.push(index);
+              rawDiceTokenSlots.push(Number(index));
+              break;
+            }
+          }
+        };
+
+        /**
+         * Validates that the dice value does not exceed the number of sides.
+         * @param {{ value: number; sides: number }} r - The dice roll result and the number of sides.
+         * @throws {Error} If the value is greater than the number of sides.
+         */
+        const diceValidator = (r) => {
+          if (r.value > r.sides)
+            throw new Error(
+              `Invalid dice roll: value (${r.value}) must be between 1 and ${r.sides}.`,
+            );
+        };
+
+        // 1dn
+        if (diceParsed[0].trim().length === 0) {
+          const r = iv.shift();
+          const rv = typeof r === 'number' ? r : objChecker.isJsonObject(r) ? r.value : 0;
+          if (objChecker.isJsonObject(r)) diceValidator(r);
+
+          dices.push([rv]);
+
+          for (const index in tokens) {
+            if (tokens[index] === m0) {
+              tokens[index] = String(rv);
+              diceTokenSlots.push(Number(index));
+              break;
+            }
+          }
+
+          getRawTokenSlot();
+          return rv;
+        }
+
+        // ndn
+        /** @type {number[]} */
+        const dices2 = [];
+        const diceAmount = Number(diceParsed[0]);
+
+        const newTokensInsert = ['('];
+        let total = '(';
+        for (let i = 0; i < diceAmount; i++) {
+          const r = iv.shift();
+          const rv = typeof r === 'number' ? r : objChecker.isJsonObject(r) ? r.value : 0;
+          if (objChecker.isJsonObject(r)) diceValidator(r);
+
+          newTokensInsert.push(String(rv));
+
+          const finishSpace = i < diceAmount - 1 ? ' + ' : ')';
+          newTokensInsert.push(finishSpace);
+
+          total += `${rv}${finishSpace}`;
+          dices2.push(rv);
+        }
+
+        for (const index in tokens) {
+          const i = Number(index);
+          if (tokens[i] === m0) {
+            tokens.splice(i, 1, ...newTokensInsert);
+            // Each new item a new string is added
+            let amount = 1;
+            for (let i2 = 0; i2 < diceAmount; i2++) {
+              diceTokenSlots.push(i + i2 + amount);
+              amount++;
+            }
+            break;
+          }
+        }
+        dices.push(dices2);
+
+        getRawTokenSlot();
+        return total;
+      });
+
+      /** @type {number} */
+      let evaluated;
+      try {
+        evaluated = TinySimpleDice._safeEvaluate(replacedExpr);
+      } catch (err) {
+        if (!(err instanceof Error)) throw new Error('Unknown Error');
+        throw new Error(
+          `Error evaluating expression "${replacedExpr}" (from "${expression}"): ${err.message}`,
+        );
+      }
+
+      steps.push({
+        rawTokensP: rawTokens,
+        rawTokens: rawTokensOriginal,
+        tokens,
+        rawDiceTokenSlots,
+        diceTokenSlots,
+        dicesResult: dices,
+        total: evaluated,
+      });
+
+      result += evaluated;
+    }
+
+    // Complete
+    return {
+      final: result,
+      steps,
+    };
+  }
+
   /**
    * Rolls a dice specifically for choosing an array or Set index.
    * @param {any[]|Set<any>} arr - The array or Set to get a random index from.