@design-edito/tools 0.2.39 → 0.2.40

package/agnostic/sanitization/html/index.d.ts

@@ -0,0 +1,61 @@
+import type { SanitizeHtmlOptions } from '../types.js';
+/**
+ * Default sanitization options.
+ *
+ * Only sets a default recursion depth of 20.
+ */
+export declare const defaultOptions: SanitizeHtmlOptions;
+/**
+ * Sanitizes an HTML string according to the provided options.
+ *
+ * @deprecated
+ * @security
+ * ⚠️ SECURITY WARNING
+ * This function is **not a hardened or complete HTML sanitizer**.
+ * It does not guarantee protection against XSS or other injection attacks.
+ *
+ * Correctness and safety depend entirely on strict caller configuration.
+ * In particular, unsafe usage may occur if:
+ * - Wildcards (`'*'`) are used for allowed tags or attributes
+ * - URL-based attributes (`href`, `src`, `xlink:href`, etc.) are insufficiently constrained
+ * - Event handler attributes (`on*`) are not explicitly forbidden
+ * - SVG or MathML content is allowed
+ *
+ * This API must not be used as a security boundary for untrusted HTML.
+ * For security-critical sanitization, use a dedicated, security-audited library.
+ *
+ * @param {string} inputStr - The HTML string to sanitize.
+ * @param {SanitizeHtmlOptions} [options=defaultOptions] - Sanitization configuration.
+ * @returns {string} The sanitized HTML string.
+ *
+ * @throws Will throw an error if no document object is available for creating elements.
+ */
+export declare function sanitizeHtml(inputStr: string, options?: SanitizeHtmlOptions): string;
+/**
+ * Recursively sanitizes a DOM element and its descendants according to the provided options.
+ *
+ * @deprecated
+ * @security
+ * ⚠️ SECURITY WARNING
+ * This function is **not a hardened or complete HTML sanitizer**.
+ * It does not guarantee protection against XSS or other injection attacks.
+ *
+ * Correctness and safety depend entirely on strict caller configuration.
+ * In particular, unsafe usage may occur if:
+ * - Wildcards (`'*'`) are used for allowed tags or attributes
+ * - URL-based attributes (`href`, `src`, `xlink:href`, etc.) are insufficiently constrained
+ * - Event handler attributes (`on*`) are not explicitly forbidden
+ * - SVG or MathML content is allowed
+ *
+ * This API must not be used as a security boundary for untrusted HTML.
+ * For security-critical sanitization, use a dedicated, security-audited library.
+ *
+ * @param {Element} element - The DOM element to sanitize.
+ * @param {SanitizeHtmlOptions} [options=defaultOptions] - Sanitization configuration.
+ * @returns {Element | null}
+ * - A sanitized clone of the original element with allowed attributes and children.
+ * - `null` if the element is forbidden or maximum recursion depth is reached.
+ *
+ * @throws Will throw an error if no document object is available for creating elements.
+ */
+export declare function sanitizeElement(element: Element, options?: SanitizeHtmlOptions): Element | null;

package/agnostic/sanitization/html/index.js

@@ -0,0 +1,121 @@
+import {
+  get
+} from "../../../chunks/chunk-ROWPCMQY.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/sanitization/html/index.ts
+var defaultOptions = { depth: 20 };
+function sanitizeHtml(inputStr, options = defaultOptions) {
+  const { document } = get();
+  const wrapperDiv = document.createElement("div");
+  const { inputFreeTransform } = options;
+  wrapperDiv.innerHTML = inputFreeTransform !== void 0 ? inputFreeTransform(inputStr) : inputStr;
+  const sanitizedWrapper = sanitizeElement(wrapperDiv, options);
+  const returned = sanitizedWrapper?.innerHTML;
+  return returned ?? "";
+}
+function sanitizeElement(element, options = defaultOptions) {
+  const { tagName, attributes, childNodes } = element;
+  const {
+    allowedTags = [],
+    allowedAttributes = {},
+    forbiddenTags = [],
+    forbiddenAttributes = {},
+    depth = 20,
+    verbose = false
+  } = options;
+  if (depth <= 0) {
+    console.warn("Max depth reached");
+    return null;
+  }
+  const normalizedTagName = tagName.toLowerCase().trim();
+  const tagIsInForbidden = forbiddenTags.includes("*") || forbiddenTags.includes(normalizedTagName);
+  if (tagIsInForbidden) {
+    if (verbose === true) console.warn(tagName, "tag is forbidden");
+    return null;
+  }
+  const tagIsInAllowed = allowedTags.includes("*") || allowedTags.includes(normalizedTagName);
+  if (!tagIsInAllowed) {
+    if (verbose === true) console.warn(tagName, "tag is not allowed");
+    return null;
+  }
+  const returnedElement = get().document.createElement(tagName);
+  const returnedAttributes = Array.from(attributes).filter(({ name: attributeName, value: attributeValue }) => {
+    const allTagsForbiddenAttributes = forbiddenAttributes["*"] ?? [];
+    const thisTagForbiddenAttributes = forbiddenAttributes[normalizedTagName] ?? [];
+    const mergedForbiddenAttributes = [...allTagsForbiddenAttributes, ...thisTagForbiddenAttributes];
+    const isInForbidden = mergedForbiddenAttributes.some(({
+      attributeName: nameTester,
+      attributeValues: valTesters
+    }) => {
+      if (typeof nameTester === "string" && nameTester !== "*" && attributeName !== nameTester) return false;
+      if (typeof nameTester !== "string" && !nameTester.test(attributeName)) return false;
+      if (valTesters === void 0) {
+        if (verbose === true) console.warn(attributeName, "attribute on", tagName, "tag is forbidden");
+        return true;
+      }
+      if (valTesters.includes("*")) {
+        if (verbose === true) console.warn(attributeName, "attribute on", tagName, "tag is forbidden");
+        return true;
+      }
+      return valTesters.some((valTester) => {
+        if (typeof valTester === "string" && attributeValue === valTester) {
+          if (verbose === true) console.warn(attributeValue, "value for", attributeName, "attribute on", tagName, "tag is forbidden. Rule:", valTester);
+          return true;
+        }
+        if (typeof valTester !== "string" && valTester.test(attributeValue)) {
+          if (verbose === true) console.warn(attributeValue, "value for", attributeName, "attribute on", tagName, "tag is forbidden. Rule:", valTester);
+          return true;
+        }
+        return false;
+      });
+    });
+    if (isInForbidden) return false;
+    const allTagsAllowedAttributes = allowedAttributes["*"] ?? [];
+    const thisTagAllowedAttributes = allowedAttributes[normalizedTagName] ?? [];
+    const mergedAllowedAttributes = [...allTagsAllowedAttributes, ...thisTagAllowedAttributes];
+    let latestNotAllowedReason = [tagName, "has no allowed attributes"];
+    const isInAllowed = mergedAllowedAttributes.some(({
+      attributeName: nameTester,
+      attributeValues: valTesters
+    }) => {
+      if (typeof nameTester === "string" && nameTester !== "*" && attributeName !== nameTester) {
+        latestNotAllowedReason = [attributeName, "attribute on", tagName, "tag is not allowed"];
+        return false;
+      }
+      if (typeof nameTester !== "string" && !nameTester.test(attributeName)) {
+        latestNotAllowedReason = [attributeName, "attribute on", tagName, "tag is not allowed"];
+        return false;
+      }
+      if (valTesters === void 0) return true;
+      if (valTesters.includes("*")) return true;
+      return valTesters.some((valTester) => {
+        if (typeof valTester === "string" && attributeValue === valTester) return true;
+        if (typeof valTester !== "string" && valTester.test(attributeValue)) return true;
+        latestNotAllowedReason = [attributeValue, "value for", attributeName, "attribute on", tagName, "tag is not allowed"];
+        return false;
+      });
+    });
+    if (!isInAllowed) {
+      if (verbose === true) console.warn(...latestNotAllowedReason);
+      return false;
+    }
+    return true;
+  });
+  returnedAttributes.forEach(({ name, value }) => {
+    returnedElement.setAttribute(name, value);
+  });
+  const sanitizedChildNodes = Array.from(childNodes).map((node) => {
+    if (node.nodeType === Node.ELEMENT_NODE) return sanitizeElement(node, { ...options, depth: depth - 1 });
+    else if (node.nodeType === Node.TEXT_NODE) return node;
+    else if (options.keepComments === true && node.nodeType === Node.COMMENT_NODE) return node;
+    return null;
+  }).filter((elt) => elt !== null);
+  returnedElement.replaceChildren(...sanitizedChildNodes);
+  return returnedElement;
+}
+export {
+  defaultOptions,
+  sanitizeElement,
+  sanitizeHtml
+};

package/agnostic/sanitization/path/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sanitizes a path string by sanitizing each path segment.
+ *
+ * - Removes empty segments and `..` segments to prevent path traversal.
+ * - Sanitizes each segment using `sanitizeFileName`.
+ * - Ensures the returned path starts with a `/`.
+ *
+ * @param {string} targetPath - The path to sanitize.
+ * @returns {string | null} Sanitized absolute path, or null if invalid/empty.
+ */
+export declare function sanitizePath(targetPath: string): string | null;

package/agnostic/sanitization/path/index.js

@@ -0,0 +1,14 @@
+import {
+  sanitizeFileName
+} from "../../../chunks/chunk-HYPEWMYZ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/sanitization/path/index.ts
+function sanitizePath(targetPath) {
+  const sanitized = targetPath.split("/").filter((chunk) => chunk !== "").map((chunk) => sanitizeFileName(chunk) ?? "").filter((chunk) => chunk !== "" && chunk !== "..").join("/");
+  if (sanitized === "") return null;
+  return sanitized.startsWith("/") ? sanitized : `/${sanitized}`;
+}
+export {
+  sanitizePath
+};

package/agnostic/sanitization/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Represents an attribute filtering rule for sanitization.
+ *
+ * - `attributeName`: The attribute name to match, either as a string or a RegExp.
+ * - `attributeValues` (optional): Array of allowed or forbidden values for the attribute,
+ *   each being a string or a RegExp. If omitted, all values are affected.
+ */
+export type AttributeNameValPair = {
+    attributeName: string | RegExp;
+    attributeValues?: Array<string | RegExp>;
+};
+/**
+ * Configuration options for HTML sanitization.
+ *
+ * - `inputFreeTransform` (optional): Function applied to input HTML string before sanitization.
+ * - `keepComments` (optional): Whether to preserve comment nodes. Default is `false`.
+ * - `allowedTags` (optional): Array of allowed tag names. `'*'` allows all tags.
+ * - `forbiddenTags` (optional): Array of forbidden tag names. `'*'` forbids all tags.
+ * - `allowedAttributes` (optional): Object mapping tag names to allowed attributes (`AttributeNameValPair` arrays).
+ * - `forbiddenAttributes` (optional): Object mapping tag names to forbidden attributes (`AttributeNameValPair` arrays).
+ * - `depth` (optional): Maximum recursion depth for nested elements. Default is 20.
+ * - `verbose` (optional): Enables console warnings for forbidden elements/attributes. Default is `false`.
+ */
+export type SanitizeHtmlOptions = {
+    inputFreeTransform?: (input: string) => string;
+    keepComments?: boolean;
+    allowedTags?: string[];
+    forbiddenTags?: string[];
+    allowedAttributes?: {
+        [tagName: string]: AttributeNameValPair[];
+    };
+    forbiddenAttributes?: {
+        [tagName: string]: AttributeNameValPair[];
+    };
+    depth?: number;
+    verbose?: boolean;
+};

package/agnostic/sanitization/user-input/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Recursively sanitizes user input to prevent XSS.
+ *
+ * - Strings are sanitized using `xss`.
+ * - Arrays and objects are sanitized recursively.
+ * - Circular references are safely handled via a `WeakSet`.
+ *
+ * @template T
+ * @param input - Input value to sanitize (string, object, or array).
+ * @param [seen] - Internal set to track circular references.
+ * @returns Sanitized input with the same structure as the original.
+ */
+export declare const sanitizeUserInput: <T>(input: T, seen?: WeakSet<WeakKey>) => T;

package/agnostic/sanitization/user-input/index.js

@@ -0,0 +1,23 @@
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/sanitization/user-input/index.ts
+import xss from "xss";
+var sanitizeUserInput = (input, seen = /* @__PURE__ */ new WeakSet()) => {
+  if (typeof input === "string") return xss(input);
+  if (Array.isArray(input)) {
+    if (seen.has(input)) return input;
+    seen.add(input);
+    return input.map((item) => sanitizeUserInput(item, seen));
+  }
+  if (input !== null && typeof input === "object") {
+    if (seen.has(input)) return input;
+    seen.add(input);
+    const entries = Object.entries(input);
+    const sanitizedEntries = entries.map(([key, value]) => [xss(key), sanitizeUserInput(value, seen)]);
+    return Object.fromEntries(sanitizedEntries);
+  }
+  return input;
+};
+export {
+  sanitizeUserInput
+};

package/agnostic/strings/char-codes/index.d.ts

@@ -1,17 +1,82 @@
-export declare namespace CharCodes {
-    type CharCode = number;
-    type B36CharCode = string;
-    function charCodeToB36(charCode: CharCode): B36CharCode;
-    function b36CharCodeToCharCode(b36CharCode: B36CharCode): CharCode;
-    function charToCharCode(char: string): CharCode;
-    function charToB36CharCode(char: string): B36CharCode;
-    function charFromCharCode(charCode: CharCode): string;
-    function charFromB36CharCode(b36CharCode: B36CharCode): string;
-    function toCharCodes(string: string): Array<CharCode>;
-    function toB36CharCodes(string: string): Array<B36CharCode>;
-    function fromCharCodes(charCodes: Array<CharCode>): string;
-    function fromB36CharCodes(b36CharCodes: Array<B36CharCode>): string;
-    function serialize(charCodes: Array<CharCode | B36CharCode>): string;
-    function deserialize(serializedCharCodes: string): Array<CharCode>;
-    function fromSerialized(serializedCharCodes: string): string;
-}
+/** A standard Unicode character code (number). */
+export type CharCode = number;
+/** A base-36 encoded character code (string). */
+export type B36CharCode = string;
+/**
+ * Converts a Unicode character code to a base-36 string.
+ * @param charCode - The character code to convert.
+ * @returns Base-36 encoded character code.
+ */
+export declare function charCodeToB36(charCode: CharCode): B36CharCode;
+/**
+ * Converts a base-36 character code string back to a Unicode character code.
+ * @param b36CharCode - Base-36 encoded character code.
+ * @returns Unicode character code.
+ */
+export declare function b36CharCodeToCharCode(b36CharCode: B36CharCode): CharCode;
+/**
+ * Converts a single character to its Unicode character code.
+ * @param char - The character to convert.
+ * @returns Unicode character code.
+ */
+export declare function charToCharCode(char: string): CharCode;
+/**
+ * Converts a single character to its base-36 encoded character code.
+ * @param char - The character to convert.
+ * @returns Base-36 character code.
+ */
+export declare function charToB36CharCode(char: string): B36CharCode;
+/**
+ * Returns the character corresponding to a Unicode character code.
+ * @param charCode - Unicode character code.
+ * @returns Single-character string.
+ */
+export declare function charFromCharCode(charCode: CharCode): string;
+/**
+ * Returns the character corresponding to a base-36 encoded character code.
+ * @param b36CharCode - Base-36 character code.
+ * @returns Single-character string.
+ */
+export declare function charFromB36CharCode(b36CharCode: B36CharCode): string;
+/**
+ * Converts a string into an array of Unicode character codes.
+ * @param string - Input string.
+ * @returns Array of character codes.
+ */
+export declare function toCharCodes(string: string): Array<CharCode>;
+/**
+ * Converts a string into an array of base-36 encoded character codes.
+ * @param string - Input string.
+ * @returns Array of base-36 character codes.
+ */
+export declare function toB36CharCodes(string: string): Array<B36CharCode>;
+/**
+ * Converts an array of Unicode character codes back to a string.
+ * @param charCodes - Array of character codes.
+ * @returns Reconstructed string.
+ */
+export declare function fromCharCodes(charCodes: Array<CharCode>): string;
+/**
+ * Converts an array of base-36 encoded character codes back to a string.
+ * @param b36CharCodes - Array of base-36 character codes.
+ * @returns Reconstructed string.
+ */
+export declare function fromB36CharCodes(b36CharCodes: Array<B36CharCode>): string;
+/**
+ * Serializes an array of character codes (Unicode or base-36) into a string.
+ * @param charCodes - Array of character codes to serialize.
+ * @returns Serialized string representation.
+ */
+export declare function serialize(charCodes: Array<CharCode | B36CharCode>): string;
+/**
+ * Deserializes a string of base-36 character codes into an array of Unicode character codes.
+ * @param serializedCharCodes - Serialized string.
+ * @returns Array of Unicode character codes.
+ */
+export declare function deserialize(serializedCharCodes: string): Array<CharCode>;
+/**
+ * Deserializes a string of base-36 character codes and reconstructs the original string.
+ * @param serializedCharCodes - Serialized string.
+ * @returns Original string.
+ */
+export declare function fromSerialized(serializedCharCodes: string): string;

package/agnostic/strings/char-codes/index.js

@@ -1,7 +1,70 @@
-import {
-  CharCodes
-} from "../../../chunks/chunk-34U4HX4V.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/strings/char-codes/index.ts
+function charCodeToB36(charCode) {
+  if (charCode === null) return "\0";
+  return charCode.toString(36);
+}
+function b36CharCodeToCharCode(b36CharCode) {
+  if (b36CharCode === null) return 0;
+  const charCode = parseInt(b36CharCode, 36);
+  if (!Number.isInteger(charCode)) return 0;
+  return charCode;
+}
+function charToCharCode(char) {
+  const charCode = char.charCodeAt(0);
+  if (!Number.isInteger(charCode)) return 0;
+  return charCode;
+}
+function charToB36CharCode(char) {
+  const charCode = charToCharCode(char);
+  return charCodeToB36(charCode);
+}
+function charFromCharCode(charCode) {
+  return String.fromCharCode(charCode);
+}
+function charFromB36CharCode(b36CharCode) {
+  const charCode = parseInt(b36CharCode, 36);
+  if (!Number.isInteger(charCode)) return "\0";
+  return charFromCharCode(charCode);
+}
+function toCharCodes(string) {
+  const chars = string.split("");
+  return chars.map(charToCharCode);
+}
+function toB36CharCodes(string) {
+  const chars = string.split("");
+  return chars.map(charToB36CharCode);
+}
+function fromCharCodes(charCodes) {
+  return charCodes.map(charFromCharCode).map((char) => char === null ? "\0" : char).join("");
+}
+function fromB36CharCodes(b36CharCodes) {
+  return b36CharCodes.map(charFromB36CharCode).map((char) => char === null ? "\0" : char).join("");
+}
+function serialize(charCodes) {
+  return charCodes.map((c) => typeof c === "string" ? c : charCodeToB36(c)).join(",");
+}
+function deserialize(serializedCharCodes) {
+  const b36CharCodes = serializedCharCodes.split("");
+  return b36CharCodes.map(b36CharCodeToCharCode);
+}
+function fromSerialized(serializedCharCodes) {
+  const charCodes = deserialize(serializedCharCodes);
+  return fromCharCodes(charCodes);
+}
 export {
-  CharCodes
+  b36CharCodeToCharCode,
+  charCodeToB36,
+  charFromB36CharCode,
+  charFromCharCode,
+  charToB36CharCode,
+  charToCharCode,
+  deserialize,
+  fromB36CharCodes,
+  fromCharCodes,
+  fromSerialized,
+  serialize,
+  toB36CharCodes,
+  toCharCodes
 };

package/agnostic/strings/matches/index.d.ts

@@ -1,4 +1,28 @@
+/**
+ * A matcher can be a string, a regular expression, or a function that returns a boolean for a given input.
+ */
 export type Matcher = string | RegExp | ((input: string) => boolean);
+/**
+ * Checks whether a string matches a single matcher.
+ *
+ * @param input - The string to test.
+ * @param matcher - The matcher to test against.
+ * @returns `true` if the input matches, otherwise `false`.
+ */
 export declare function matches(input: string, matcher: Matcher): boolean;
+/**
+ * Checks whether a string matches at least one matcher in a list (or a single matcher).
+ *
+ * @param input - The string to test.
+ * @param matchers - A matcher or array of matchers.
+ * @returns `true` if the input matches at least one matcher, otherwise `false`.
+ */
 export declare function matchesSome(input: string, matchers: Matcher | Array<Matcher>): boolean;
+/**
+ * Checks whether a string matches every matcher in a list (or a single matcher).
+ *
+ * @param input - The string to test.
+ * @param matchers - A matcher or array of matchers.
+ * @returns `true` if the input matches all matchers, otherwise `false`.
+ */
 export declare function matchesEvery(input: string, matchers: Matcher | Array<Matcher>): boolean;

package/agnostic/strings/matches/index.js

@@ -3,7 +3,7 @@ import {
   matchesEvery,
   matchesSome
 } from "../../../chunks/chunk-R3AWQXMY.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
 export {
   matches,
   matchesEvery,

package/agnostic/strings/normalize-indent/index.d.ts

@@ -1 +1,23 @@
+/**
+ * Normalizes the indentation of a multi-line string.
+ *
+ * Removes all existing leading whitespace, replaces leading `|` characters with spaces,
+ * and applies a uniform indentation to all lines.
+ *
+ * @param input - The multi-line string to normalize.
+ * @param indentLevel - The number of spaces to prepend to each line after normalization. Defaults to `0`.
+ * @returns The input string with normalized indentation.
+ *
+ * @example
+ * const str = `
+ * |function test() {
+ * |  console.log('hi')
+ * |}`;
+ *
+ * console.log(normalizeIndent(str, 2));
+ * // Output:
+ * // "  function test() {
+ * //    console.log('hi')
+ * //  }"
+ */
 export declare function normalizeIndent(input: string, indentLevel?: number): string;

package/agnostic/strings/normalize-indent/index.js

@@ -1,7 +1,19 @@
-import {
-  normalizeIndent
-} from "../../../chunks/chunk-JQXNEJAP.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/strings/normalize-indent/index.ts
+function normalizeIndent(input, indentLevel = 0) {
+  const indent = " ".repeat(indentLevel);
+  const lines = input.split("\n");
+  const noIndentLines = lines.map((line) => line.replace(/^\s*/igm, ""));
+  const pipeReplacedLines = noIndentLines.map((line) => {
+    const nbPipeCharsOnLineStart = line.match(/^\|+/igm)?.[0].length ?? 0;
+    const noPipeLine = line.slice(nbPipeCharsOnLineStart);
+    const replacedPipes = " ".repeat(nbPipeCharsOnLineStart);
+    return replacedPipes + noPipeLine;
+  });
+  const normalizedLines = pipeReplacedLines.map((line) => indent + line);
+  return normalizedLines.join("\n");
+}
 export {
   normalizeIndent
 };