docs: add JSDoc documentation to core modules (directus, i18n, router, helpers)

js/utils/helpers.js

@@ -1,8 +1,15 @@
+/**
+ * Utility helper functions
+ * @module utils/helpers
+ */
+
 /**
  * Escape HTML special characters to prevent XSS
  * Use for any user-generated content rendered via innerHTML
  * @param {string} str - Untrusted string
- * @returns {string} - Escaped string safe for innerHTML
+ * @returns {string} Escaped string safe for innerHTML
+ * @example
+ * escapeHTML('<script>alert("XSS")</script>') // '&lt;script&gt;...'
  */
 export function escapeHTML(str) {
     if (str === null || str === undefined) return '';
@@ -17,8 +24,11 @@ export function escapeHTML(str) {
 /**
  * Format price with currency symbol
  * @param {number} price - Price value
- * @param {string} currency - Currency code (EUR, USD, CHF, XMR)
- * @returns {string} - Formatted price string
+ * @param {string} [currency='EUR'] - Currency code (EUR, USD, CHF, XMR)
+ * @returns {string} Formatted price string
+ * @example
+ * formatPrice(99.5, 'EUR') // '€ 99.50'
+ * formatPrice(0.5, 'XMR')  // '0.5000 ɱ'
  */
 export function formatPrice(price, currency = 'EUR') {
     if (price === null || price === undefined) return '–';
@@ -40,10 +50,13 @@ export function formatPrice(price, currency = 'EUR') {
 }
 
 /**
- * Format relative time (e.g., "vor 2 Stunden")
+ * Format relative time (e.g., "vor 2 Stunden", "2 hours ago")
+ * Uses Intl.RelativeTimeFormat for localization
  * @param {Date|string} date - Date to format
- * @param {string} locale - Locale code
- * @returns {string} - Relative time string
+ * @param {string} [locale='de'] - Locale code
+ * @returns {string} Relative time string
+ * @example
+ * formatRelativeTime(new Date(Date.now() - 3600000), 'de') // 'vor 1 Stunde'
  */
 export function formatRelativeTime(date, locale = 'de') {
     const now = new Date();
@@ -65,8 +78,10 @@ export function formatRelativeTime(date, locale = 'de') {
 /**
  * Debounce function calls
  * @param {Function} fn - Function to debounce
- * @param {number} delay - Delay in ms
- * @returns {Function} - Debounced function
+ * @param {number} [delay=300] - Delay in ms
+ * @returns {Function} Debounced function
+ * @example
+ * const debouncedSearch = debounce((q) => search(q), 500)
  */
 export function debounce(fn, delay = 300) {
     let timeoutId;
@@ -79,8 +94,10 @@ export function debounce(fn, delay = 300) {
 /**
  * Truncate string with ellipsis
  * @param {string} str - String to truncate
- * @param {number} maxLength - Maximum length
- * @returns {string} - Truncated string
+ * @param {number} [maxLength=100] - Maximum length
+ * @returns {string} Truncated string
+ * @example
+ * truncate('Hello World', 5) // 'Hell…'
  */
 export function truncate(str, maxLength = 100) {
     if (!str || str.length <= maxLength) return str;