@design-edito/tools 0.2.37 → 0.2.40

package/agnostic/misc/lorem-ipsum/index.d.ts

@@ -1,5 +1,3 @@
-export declare namespace LoremIpsum {
-    const words: string[];
-    const generateSentence: (wordCount: number) => string;
-    const generateSentences: (sentencesCount: number, maxSentenceLength?: number, minSentenceLength?: number) => string[];
-}
+export declare const words: string[];
+export declare const generateSentence: (wordCount: number) => string;
+export declare const generateSentences: (sentencesCount: number, maxSentenceLength?: number, minSentenceLength?: number) => string[];

package/agnostic/misc/lorem-ipsum/index.js

@@ -1,26 +1,190 @@
 import {
-  LoremIpsum
-} from "../../../chunks/chunk-63J76ST6.js";
-import "../../../chunks/chunk-OVG5RGI3.js";
-import "../../../chunks/chunk-75BICI4L.js";
-import "../../../chunks/chunk-OGBUSUE6.js";
-import "../../../chunks/chunk-D3ERTRDW.js";
-import "../../../chunks/chunk-73UGWJYI.js";
-import "../../../chunks/chunk-AQBJ6HNB.js";
-import "../../../chunks/chunk-TIER4TF4.js";
-import "../../../chunks/chunk-FR5H2OCV.js";
-import "../../../chunks/chunk-S2NMAH7K.js";
-import "../../../chunks/chunk-LV2VMOWR.js";
-import "../../../chunks/chunk-RLJOYG64.js";
-import "../../../chunks/chunk-WH6BPDAC.js";
-import "../../../chunks/chunk-QHLQVR3E.js";
-import "../../../chunks/chunk-FENXVJYO.js";
-import "../../../chunks/chunk-6RGDWX4A.js";
-import "../../../chunks/chunk-RCO57B6F.js";
-import "../../../chunks/chunk-VJJIYJMY.js";
-import "../../../chunks/chunk-YS6WMSWC.js";
-import "../../../chunks/chunk-RLAZR3NL.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+  randomInt
+} from "../../../chunks/chunk-D3ERTRDW.js";
+import {
+  randomPick
+} from "../../../chunks/chunk-K5UF634H.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/misc/lorem-ipsum/index.ts
+var words = [
+  "a",
+  "ac",
+  "accumsan",
+  "adipiscing",
+  "aenean",
+  "aliquam",
+  "aliquet",
+  "amet",
+  "ante",
+  "arcu",
+  "at",
+  "auctor",
+  "augue",
+  "bibendum",
+  "blandit",
+  "condimentum",
+  "consectetur",
+  "consequat",
+  "convallis",
+  "cras",
+  "curabitur",
+  "cursus",
+  "dapibus",
+  "diam",
+  "dictum",
+  "dictumst",
+  "dignissim",
+  "dolor",
+  "donec",
+  "dui",
+  "duis",
+  "efficitur",
+  "egestas",
+  "eget",
+  "eleifend",
+  "elementum",
+  "elit",
+  "enim",
+  "erat",
+  "eros",
+  "est",
+  "et",
+  "eu",
+  "euismod",
+  "ex",
+  "facilisis",
+  "faucibus",
+  "felis",
+  "feugiat",
+  "finibus",
+  "fringilla",
+  "fusce",
+  "gravida",
+  "habitasse",
+  "hac",
+  "hendrerit",
+  "iaculis",
+  "id",
+  "imperdiet",
+  "in",
+  "integer",
+  "interdum",
+  "ipsum",
+  "justo",
+  "lacinia",
+  "lacus",
+  "laoreet",
+  "lectus",
+  "leo",
+  "libero",
+  "ligula",
+  "lobortis",
+  "lorem",
+  "luctus",
+  "maecenas",
+  "magna",
+  "malesuada",
+  "massa",
+  "mattis",
+  "mauris",
+  "maximus",
+  "metus",
+  "mi",
+  "molestie",
+  "mollis",
+  "morbi",
+  "nam",
+  "nec",
+  "neque",
+  "nibh",
+  "nisi",
+  "nisl",
+  "non",
+  "nulla",
+  "nullam",
+  "nunc",
+  "odio",
+  "orci",
+  "ornare",
+  "pellentesque",
+  "pharetra",
+  "phasellus",
+  "placerat",
+  "platea",
+  "porta",
+  "porttitor",
+  "posuere",
+  "praesent",
+  "pulvinar",
+  "purus",
+  "quam",
+  "quis",
+  "quisque",
+  "risus",
+  "rutrum",
+  "sagittis",
+  "sapien",
+  "sed",
+  "sem",
+  "semper",
+  "sit",
+  "sodales",
+  "sollicitudin",
+  "suscipit",
+  "suspendisse",
+  "tellus",
+  "tempor",
+  "tempus",
+  "tincidunt",
+  "tortor",
+  "tristique",
+  "turpis",
+  "ultrices",
+  "ultricies",
+  "urna",
+  "ut",
+  "vehicula",
+  "vel",
+  "velit",
+  "venenatis",
+  "vestibulum",
+  "vitae",
+  "vivamus",
+  "viverra",
+  "volutpat",
+  "vulputate"
+];
+var generateSentence = (wordCount) => {
+  const resultArr = [];
+  let currentWordCound = wordCount;
+  for (let i = 0; i < currentWordCound; i++) {
+    const picked = randomPick(words);
+    if (typeof picked === "string") resultArr.push(picked);
+    else {
+      currentWordCound += 1;
+    }
+  }
+  const [firstWord, ...otherWords] = resultArr;
+  if (firstWord === void 0) return "";
+  const capFirstLetter = firstWord?.charAt(0).toUpperCase();
+  const restOfFirstWord = firstWord?.slice(1);
+  const sentence = [
+    `${capFirstLetter}${restOfFirstWord}`,
+    ...otherWords
+  ].join(" ");
+  return `${sentence}.`;
+};
+var generateSentences = (sentencesCount, maxSentenceLength = 12, minSentenceLength = 4) => {
+  const sentences = [];
+  for (let i = 0; i < sentencesCount; i++) {
+    const length = randomInt(maxSentenceLength, minSentenceLength) ?? 8;
+    sentences.push(generateSentence(length));
+  }
+  return sentences;
+};
 export {
-  LoremIpsum
+  generateSentence,
+  generateSentences,
+  words
 };

package/agnostic/misc/normalize-extension/index.d.ts

@@ -1 +1,11 @@
+/**
+ * Normalizes a file extension to its canonical form, using an optional alias map.
+ *
+ * Converts the extension to lowercase, removes a leading dot if present,
+ * and applies alias mapping if defined.
+ *
+ * @param {string} extWithoutDot - File extension to normalize (may include or omit leading dot).
+ * @param {Record<string, string>} [aliasesWithoutDot=defaultAliases] - Optional mapping of aliases to canonical extensions.
+ * @returns {string} The normalized file extension, without leading dot.
+ */
 export declare function normalizeExtension(extWithoutDot: string, aliasesWithoutDot?: Record<string, string>): string;

package/agnostic/misc/normalize-extension/index.js

@@ -1,4 +1,4 @@
-import "../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
 
 // src/agnostic/misc/normalize-extension/index.ts
 var defaultAliases = {

package/agnostic/misc/outcome/index.d.ts

@@ -1,15 +1,56 @@
-export declare namespace Outcome {
-    type Success<Payload extends any = any> = {
-        success: true;
-        payload: Payload;
-    };
-    type Failure<Error extends any = any> = {
-        success: false;
-        error: Error;
-    };
-    type Either<Payload extends any = any, Error extends any = any> = Success<Payload> | Failure<Error>;
-    function makeSuccess<Payload extends any>(payload: Payload): Success<Payload>;
-    function makeFailure<Error extends any>(error: Error): Failure<Error>;
-    function make<Payload extends any>(success: true, payload: Payload): Success<Payload>;
-    function make<Error extends any>(success: false, error: Error): Failure<Error>;
-}
+/**
+ * Represents a successful outcome.
+ *
+ * @template Payload - The type of the success payload.
+ * @property {true} success - Always `true`.
+ * @property {Payload} payload - The success value.
+ */
+export type Success<Payload extends any = any> = {
+    success: true;
+    payload: Payload;
+};
+/**
+ * Represents a failed outcome.
+ *
+ * @template Error - The type of the error.
+ * @property {false} success - Always `false`.
+ * @property {Error} error - The error value.
+ */
+export type Failure<Error extends any = any> = {
+    success: false;
+    error: Error;
+};
+/**
+ * Represents either a success or a failure outcome.
+ *
+ * @template Payload - Type of success payload.
+ * @template Error - Type of error.
+ */
+export type Either<Payload extends any = any, Error extends any = any> = Success<Payload> | Failure<Error>;
+/**
+ * Creates a success outcome with the given payload.
+ *
+ * @template Payload
+ * @param {Payload} payload - The success value.
+ * @returns {Success<Payload>} A success outcome object.
+ */
+export declare function makeSuccess<Payload extends any>(payload: Payload): Success<Payload>;
+/**
+ * Creates a failure outcome with the given error.
+ *
+ * @template Error
+ * @param {Error} error - The error value.
+ * @returns {Failure<Error>} A failure outcome object.
+ */
+export declare function makeFailure<Error extends any>(error: Error): Failure<Error>;
+/**
+ * Creates either a success or failure outcome based on a boolean flag.
+ *
+ * @template Payload
+ * @template Error
+ * @param {boolean} success - `true` to create a success, `false` to create a failure.
+ * @param {Payload | Error} payloadOrError - The payload if success, or the error if failure.
+ * @returns {Either<Payload, Error>} The resulting outcome.
+ */
+export declare function make<Payload extends any>(success: true, payload: Payload): Success<Payload>;
+export declare function make<Error extends any>(success: false, error: Error): Failure<Error>;

package/agnostic/misc/outcome/index.js

@@ -1,7 +1,11 @@
 import {
-  Outcome
-} from "../../../chunks/chunk-JMU5PDBD.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+  make,
+  makeFailure,
+  makeSuccess
+} from "../../../chunks/chunk-QEKI6WGQ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
 export {
-  Outcome
+  make,
+  makeFailure,
+  makeSuccess
 };

package/agnostic/numbers/absolute-modulo/index.d.ts

@@ -1 +1,8 @@
+/**
+ * Computes the modulo of a number, always returning a non-negative result.
+ *
+ * @param {number} nbr - The number to modulo.
+ * @param {number} modulo - The modulus.
+ * @returns {number} The non-negative remainder of `nbr` modulo `modulo`.
+ */
 export declare function absoluteModulo(nbr: number, modulo: number): number;

package/agnostic/numbers/absolute-modulo/index.js

@@ -1,7 +1,7 @@
 import {
   absoluteModulo
 } from "../../../chunks/chunk-DNIOWD7K.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
 export {
   absoluteModulo
 };

package/agnostic/numbers/clamp/index.d.ts

@@ -1 +1,9 @@
+/**
+ * Restricts a number to lie within a specified range.
+ *
+ * @param {number} num - The number to clamp.
+ * @param {number} bound1 - One end of the range.
+ * @param {number} bound2 - The other end of the range.
+ * @returns {number} The number constrained between the minimum and maximum of the two bounds.
+ */
 export declare function clamp(num: number, bound1: number, bound2: number): number;

package/agnostic/numbers/clamp/index.js

@@ -1,7 +1,7 @@
 import {
   clamp
 } from "../../../chunks/chunk-OSAXBA7G.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
 export {
   clamp
 };

package/agnostic/numbers/interpolate/index.d.ts

@@ -1,2 +1,21 @@
+/**
+ * Performs linear interpolation between two bounds based on a ratio.
+ *
+ * @param {number} ratio - The interpolation factor, typically between 0 and 1.
+ * @param {number} bound1 - The start value.
+ * @param {number} bound2 - The end value.
+ * @returns {number} The interpolated value between `bound1` and `bound2`.
+ */
 export declare function interpolate(ratio: number, bound1: number, bound2: number): number;
-export declare function exterpolate(value: number, bound1: number, bound2?: number): number;
+/**
+ * Performs inverse linear interpolation (also called "unlerp") of a value relative to one or two bounds.
+ *
+ * If only `bound1` is provided, returns the ratio of `value / bound1`.
+ * If both bounds are provided, returns the normalized position of `value` between `bound1` and `bound2`.
+ *
+ * @param {number} value - The value to normalize.
+ * @param {number} bound1 - The lower bound (or single reference value if `bound2` is omitted).
+ * @param {number} [bound2] - The upper bound (optional).
+ * @returns {number} A ratio representing the relative position of `value`.
+ */
+export declare function unlerp(value: number, bound1: number, bound2?: number): number;

package/agnostic/numbers/interpolate/index.js

@@ -1,9 +1,14 @@
-import {
-  exterpolate,
-  interpolate
-} from "../../../chunks/chunk-BJAYUP7M.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/numbers/interpolate/index.ts
+function interpolate(ratio, bound1, bound2) {
+  return bound1 + ratio * (bound2 - bound1);
+}
+function unlerp(value, bound1, bound2) {
+  if (bound2 === void 0) return value / bound1;
+  return (value - bound1) / (bound2 - bound1);
+}
 export {
-  exterpolate,
-  interpolate
+  interpolate,
+  unlerp
 };

package/agnostic/numbers/responsive-harmonics/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Computes the harmonic value at a specific level between a minimum and maximum over a number of steps.
+ *
+ * @param {number} min - The minimum value (must be non-zero).
+ * @param {number} max - The maximum value.
+ * @param {number} level - The current level (1-based).
+ * @param {number} steps - Total number of steps (must be ≥ 1).
+ * @returns {number} The computed harmonic value, or `NaN` if input is invalid.
+ */
 export declare function getHarmonic(min: number, max: number, level: number, steps: number): number;
 type ScaleDescriptor = {
     screenBounds: [number, number];
@@ -6,5 +15,16 @@ type ScaleDescriptor = {
     steps: number;
     clamp?: boolean;
 };
+/**
+ * Creates a scale function that maps a level to a CSS size value using harmonic interpolation.
+ *
+ * @param {ScaleDescriptor} descriptor - The scale configuration.
+ * @param {[number, number]} descriptor.screenBounds - The lower and upper bounds for screen width in pixels.
+ * @param {[number, number]} descriptor.lowLevel - Minimum and maximum values for the low level range.
+ * @param {[number, number]} descriptor.highLevel - Minimum and maximum values for the high level range.
+ * @param {number} descriptor.steps - Number of discrete steps in the scale.
+ * @param {boolean} [descriptor.clamp] - Whether to wrap the resulting CSS value in a `clamp()` function.
+ * @returns {(level: number) => string | undefined} A function mapping a level to a CSS value string.
+ */
 export declare function createScale(descriptor: ScaleDescriptor): (level: number) => string | undefined;
 export {};

package/agnostic/numbers/responsive-harmonics/index.js

@@ -1,9 +1,53 @@
 import {
-  createScale,
-  getHarmonic
-} from "../../../chunks/chunk-KXIA3YGF.js";
-import "../../../chunks/chunk-EOE2ODJR.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+  round
+} from "../../../chunks/chunk-QHEWBOQI.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/numbers/responsive-harmonics/index.ts
+function getHarmonic(min, max, level, steps) {
+  if (min === 0) {
+    console.warn("Cannot generate harmonics if min value is zero");
+    return NaN;
+  }
+  if (steps < 1) {
+    console.warn("Cannot generate harmonics if steps is lower than one");
+    return NaN;
+  }
+  const maxOverMin = max / min;
+  const oneOverSteps = 1 / parseInt(`${steps}`);
+  const factor = Math.pow(maxOverMin, oneOverSteps);
+  return min * Math.pow(factor, level);
+}
+function getAffineFunction(x1, y1, x2, y2) {
+  const slope = (y2 - y1) / (x2 - x1);
+  const yIntercept = y1 - x1 * slope;
+  return { slope, yIntercept };
+}
+function getCssValueFromAffine(affine) {
+  const { slope, yIntercept } = affine;
+  const roundedSlope = round(100 * slope, 3);
+  const roundedIntercept = round(yIntercept, 2);
+  return `calc(${roundedSlope}vw + ${roundedIntercept}px)`;
+}
+function createScale(descriptor) {
+  const {
+    screenBounds: [loBound, hiBound],
+    lowLevel: [loLevelMin, loLevelMax],
+    highLevel: [hiLevelMin, hiLevelMax],
+    steps,
+    clamp
+  } = descriptor;
+  return function scale(level) {
+    if (steps < 2) return;
+    const loBoundVal = getHarmonic(loLevelMin, hiLevelMin, level - 1, steps - 1);
+    const hiBoundVal = getHarmonic(loLevelMax, hiLevelMax, level - 1, steps - 1);
+    if (loBoundVal === void 0) return;
+    if (hiBoundVal === void 0) return;
+    const affine = getAffineFunction(loBound, loBoundVal, hiBound, hiBoundVal);
+    const cssFormula = getCssValueFromAffine(affine);
+    return clamp === true ? `clamp(${round(loBoundVal, 2)}px, ${cssFormula}, ${round(hiBoundVal, 2)}px)` : cssFormula;
+  };
+}
 export {
   createScale,
   getHarmonic

package/agnostic/numbers/round/index.d.ts

@@ -1,3 +1,24 @@
-export declare function round(number: number, nbDecimals: number): number;
-export declare function ceil(number: number, nbDecimals: number): number;
-export declare function floor(number: number, nbDecimals: number): number;
+/**
+ * Rounds a number to/down a specified number of decimal places.
+ *
+ * @param {number} number - The number to round.
+ * @param {number} nbDecimals - Number of decimal places. Defaults to 0
+ * @returns {number} The rounded number.
+ */
+export declare function round(number: number, nbDecimals?: number): number;
+/**
+ * Ceils a number up to a specified number of decimal places.
+ *
+ * @param {number} number - The number to round up.
+ * @param {number} nbDecimals - Number of decimal places. Defaults to 0
+ * @returns {number} The ceiled-up number.
+ */
+export declare function ceil(number: number, nbDecimals?: number): number;
+/**
+ * Floors a number down to a specified number of decimal places.
+ *
+ * @param {number} number - The number to round down.
+ * @param {number} nbDecimals - Number of decimal places. Defaults to 0
+ * @returns {number} The floored-down number.
+ */
+export declare function floor(number: number, nbDecimals?: number): number;

package/agnostic/numbers/round/index.js

@@ -2,8 +2,8 @@ import {
   ceil,
   floor,
   round
-} from "../../../chunks/chunk-EOE2ODJR.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+} from "../../../chunks/chunk-QHEWBOQI.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
 export {
   ceil,
   floor,

package/agnostic/objects/deep-get-property/index.d.ts

@@ -1 +1,9 @@
+/**
+ * Safely retrieves a nested property from an object using a dot-separated path string.
+ *
+ * @param {unknown} anythingThatHasProperties - The object (or record) to traverse.
+ * @param {string} pathString - Dot-separated path of the property to retrieve (e.g., `'a.b.c'`).
+ * @returns {any} The value at the specified path.
+ * @throws {string} `'PROPERTY_UNREACHABLE'` if any part of the path is inaccessible or not an object.
+ */
 export declare function deepGetProperty(anythingThatHasProperties: unknown, pathString: string): any;

package/agnostic/objects/deep-get-property/index.js

@@ -1,8 +1,27 @@
 import {
-  deepGetProperty
-} from "../../../chunks/chunk-SKMCIFS3.js";
-import "../../../chunks/chunk-YDIBNEGA.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+  isRecord
+} from "../../../chunks/chunk-YDIBNEGA.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/objects/deep-get-property/index.ts
+function deepGetProperty(anythingThatHasProperties, pathString) {
+  const pathChunks = pathString.split(".").map((e) => e.trim()).filter((e) => e !== "");
+  let currentObject = anythingThatHasProperties;
+  let returned = currentObject;
+  pathChunks.forEach((chunk, pos) => {
+    const isLast = pos === pathChunks.length - 1;
+    if (!isRecord(currentObject)) throw "PROPERTY_UNREACHABLE";
+    if (isLast) {
+      const val = currentObject[chunk];
+      returned = val;
+    } else {
+      const found = currentObject[chunk];
+      if (isRecord(found)) currentObject = found;
+      else throw "PROPERTY_UNREACHABLE";
+    }
+  });
+  return returned;
+}
 export {
   deepGetProperty
 };

package/agnostic/objects/enums/is-in-enum/index.d.ts

@@ -1 +1,11 @@
+/**
+ * Checks whether a value exists in a TypeScript enum.
+ *
+ * Works with both string and numeric enums, ignoring reverse mappings in numeric enums.
+ *
+ * @template E - The enum type.
+ * @param {E} enumObj - The enum object to check against.
+ * @param {string | number} value - The value to test.
+ * @returns {value is E[keyof E]} `true` if the value is a valid enum member, otherwise `false`.
+ */
 export declare function isInEnum<E extends Record<string, string | number>>(enumObj: E, value: string | number): value is E[keyof E];

package/agnostic/objects/enums/is-in-enum/index.js

@@ -1,7 +1,7 @@
 import {
   isInEnum
 } from "../../../../chunks/chunk-E6MSDKON.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../../chunks/chunk-XCBH6NLF.js";
 export {
   isInEnum
 };

package/agnostic/objects/flatten-getters/index.d.ts

@@ -1 +1,7 @@
+/**
+ * Returns a shallow copy of an object including values from its getter properties.
+ *
+ * @param {unknown} obj - The object to flatten.
+ * @returns {Record<string, unknown>} A new object containing all own properties and evaluated getter values.
+ */
 export declare function flattenGetters(obj: unknown): Record<string, unknown>;

package/agnostic/objects/flatten-getters/index.js

@@ -1,10 +1,25 @@
 import {
-  flattenGetters
-} from "../../../chunks/chunk-VFJYLXCI.js";
-import "../../../chunks/chunk-SNJJII7A.js";
+  toRecord
+} from "../../../chunks/chunk-HOFEVF7T.js";
 import "../../../chunks/chunk-QXAJXTXV.js";
 import "../../../chunks/chunk-HC6ZOHCS.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/objects/flatten-getters/index.ts
+function flattenGetters(obj) {
+  try {
+    const { entries, getOwnPropertyDescriptors } = Object;
+    const properties = toRecord(obj);
+    const getters = entries(getOwnPropertyDescriptors(obj)).filter(([_, desc]) => typeof desc.get === "function").map(([key]) => key);
+    const returned = { ...properties };
+    getters.forEach((getter) => {
+      returned[getter] = obj[getter];
+    });
+    return returned;
+  } catch (err) {
+    return {};
+  }
+}
 export {
   flattenGetters
 };