flet-box 0.0.0-stage → 1.0.2

package/src/tools/transform.js

@@ -0,0 +1,68 @@
+// tools/transform.js
+
+/**
+ * Generate CSS transform string
+ * @param {Object} options - Transform options
+ * @returns {string} CSS transform value
+ *
+ * @example
+ * transform({ translate: [10, 20], rotate: 45, scale: 1.5 })
+ * // "translate(10px, 20px) rotate(45deg) scale(1.5)"
+ *
+ * @example
+ * transform({ translateX: 10, translateY: 20, rotate: 45 })
+ * // "translateX(10px) translateY(20px) rotate(45deg)"
+ */
+export const transform = (options = {}) => {
+  const parts = [];
+
+  // Translate
+  if (options.translate) {
+    const [x, y] = options.translate;
+    parts.push(
+      `translate(${typeof x === "number" ? x + "px" : x}, ${typeof y === "number" ? y + "px" : y})`,
+    );
+  }
+  if (options.translateX)
+    parts.push(
+      `translateX(${typeof options.translateX === "number" ? options.translateX + "px" : options.translateX})`,
+    );
+  if (options.translateY)
+    parts.push(
+      `translateY(${typeof options.translateY === "number" ? options.translateY + "px" : options.translateY})`,
+    );
+  if (options.translateZ)
+    parts.push(
+      `translateZ(${typeof options.translateZ === "number" ? options.translateZ + "px" : options.translateZ})`,
+    );
+
+  // Rotate
+  if (options.rotate) parts.push(`rotate(${options.rotate}deg)`);
+  if (options.rotateX) parts.push(`rotateX(${options.rotateX}deg)`);
+  if (options.rotateY) parts.push(`rotateY(${options.rotateY}deg)`);
+  if (options.rotateZ) parts.push(`rotateZ(${options.rotateZ}deg)`);
+
+  // Scale
+  if (options.scale) parts.push(`scale(${options.scale})`);
+  if (options.scaleX) parts.push(`scaleX(${options.scaleX})`);
+  if (options.scaleY) parts.push(`scaleY(${options.scaleY})`);
+
+  // Skew
+  if (options.skew) parts.push(`skew(${options.skew}deg)`);
+  if (options.skewX) parts.push(`skewX(${options.skewX}deg)`);
+  if (options.skewY) parts.push(`skewY(${options.skewY}deg)`);
+
+  // Matrix
+  if (options.matrix) parts.push(`matrix(${options.matrix.join(", ")})`);
+  if (options.matrix3d) parts.push(`matrix3d(${options.matrix3d.join(", ")})`);
+
+  // Perspective
+  if (options.perspective)
+    parts.push(
+      `perspective(${typeof options.perspective === "number" ? options.perspective + "px" : options.perspective})`,
+    );
+
+  return parts.join(" ");
+};
+
+export default transform;

package/src/tools/transition.js

@@ -0,0 +1,48 @@
+// tools/transition.js
+
+/**
+ * Generates a CSS `transition` shorthand string from a single options object or
+ * an array of options objects.
+ *
+ * Each options object can specify:
+ * - `property` — CSS property to animate (default: `"all"`).
+ * - `duration` — Duration in seconds (default: `0.3`).
+ * - `timing` — Timing function (default: `"ease"`).
+ * - `delay` — Delay in seconds before the transition starts (default: `0`).
+ *
+ * When an array is passed, each item is converted individually and the results
+ * are joined with `", "` to produce a multi-transition value.
+ *
+ * @param {Object|Array<Object>} options - Transition options or an array of them.
+ * @param {string} [options.property="all"] - CSS property to animate.
+ * @param {number} [options.duration=0.3] - Transition duration in seconds.
+ * @param {string} [options.timing="ease"] - CSS timing function.
+ * @param {number} [options.delay=0] - Delay before the transition starts, in seconds.
+ * @returns {string} CSS transition value.
+ *
+ * @example
+ * transition({ property: 'all', duration: 0.3, timing: 'ease', delay: 0.1 })
+ * // "all 0.3s ease 0.1s"
+ *
+ * @example
+ * transition([
+ *   { property: 'opacity', duration: 0.2 },
+ *   { property: 'transform', duration: 0.3, timing: 'ease-out' }
+ * ])
+ * // "opacity 0.2s ease 0s, transform 0.3s ease-out 0s"
+ */
+export const transition = (options) => {
+  // Handle array of transitions — convert each and join
+  if (Array.isArray(options)) {
+    return options.map((opt) => transition(opt)).join(", ");
+  }
+
+  const property = options.property || "all";
+  const duration = options.duration || 0.3;
+  const timing = options.timing || "ease";
+  const delay = options.delay || 0;
+
+  return `${property} ${duration}s ${timing} ${delay}s`;
+};
+
+export default transition;

package/src/tools/useState.js

@@ -0,0 +1,268 @@
+// src/tools/useState.js
+import { saveRam, getRam, subscribeRam } from "../services/RamStore.js";
+
+// Store callbacks for each state key
+const subscribers = new Map();
+
+// 🔥 Store widgets by state key for automatic updates
+const widgetsByKey = new Map();
+
+// Global render function (set by runApp)
+let globalRender = null;
+let renderTimeout = null;
+
+/**
+ * Sets the global render function used to trigger re-renders when state changes.
+ * Called by `runApp` to register the application's root render callback.
+ *
+ * @param {Function} renderFn - The root render function to invoke on state change.
+ * @returns {void}
+ */
+export const setGlobalRender = (renderFn) => {
+  globalRender = renderFn;
+};
+
+/**
+ * Schedules a debounced global re-render to prevent multiple renders firing in
+ * rapid succession within the same synchronous execution frame.
+ *
+ * @returns {void}
+ */
+const triggerRender = () => {
+  if (renderTimeout) clearTimeout(renderTimeout);
+  renderTimeout = setTimeout(() => {
+    if (globalRender) globalRender();
+  }, 0);
+};
+
+/**
+ * Registers a widget instance so it receives automatic prop updates whenever
+ * the state value associated with `key` changes.
+ *
+ * @param {string} key - The state key to watch.
+ * @param {Object} widget - The widget instance that exposes an `update` method.
+ * @param {string} propName - The prop name on the widget to update with the new value.
+ * @returns {void}
+ */
+export const registerWidget = (key, widget, propName) => {
+  if (!widgetsByKey.has(key)) {
+    widgetsByKey.set(key, new Set());
+  }
+  widgetsByKey.get(key).add({ widget, propName });
+
+  // Set initial value if the state already exists
+  const currentValue = getRam(key);
+  if (currentValue !== undefined && widget && widget.update) {
+    widget.update({ [propName]: currentValue });
+  }
+
+  // Patch the widget's cleanup to also remove it from the registry when destroyed
+  const originalCleanup = widget._cleanup;
+  widget._cleanup = () => {
+    const widgets = widgetsByKey.get(key);
+    if (widgets) {
+      for (const item of widgets) {
+        if (item.widget === widget) {
+          widgets.delete(item);
+          break;
+        }
+      }
+    }
+    if (originalCleanup) originalCleanup();
+  };
+};
+
+/**
+ * Removes a specific widget from the automatic-update registry for a given key.
+ *
+ * @param {string} key - The state key the widget was registered under.
+ * @param {Object} widget - The widget instance to unregister.
+ * @returns {void}
+ */
+export const unregisterWidget = (key, widget) => {
+  const widgets = widgetsByKey.get(key);
+  if (widgets) {
+    for (const item of widgets) {
+      if (item.widget === widget) {
+        widgets.delete(item);
+        break;
+      }
+    }
+  }
+};
+
+/**
+ * React-style state hook backed by the persistent RamStore.
+ *
+ * Creates (or reuses) a keyed state value that survives re-renders.
+ * Returns a reactive value object, a setter, and a subscribe function.
+ *
+ * @param {string} key - Unique key used to store and retrieve the state value.
+ * @param {*|Function} initialState - Initial value, or a factory function that returns it.
+ * @param {Object|null} [widget=null] - Optional widget to auto-update when state changes.
+ * @param {string|null} [propName=null] - The prop name on the widget to receive the new value.
+ * @returns {[Object, Function, Function]} Tuple of [reactiveValue, setState, subscribe].
+ *
+ * @example
+ * const [count, setCount, onCount] = useState('counter', 0);
+ * setCount(count + 1);
+ * onCount((newVal) => console.log('Counter changed to', newVal));
+ */
+export const useState = (key, initialState, widget = null, propName = null) => {
+  // Initialize the state in RamStore if it does not exist yet
+  let currentValue = getRam(key);
+  if (currentValue === undefined || currentValue === null) {
+    currentValue =
+      typeof initialState === "function" ? initialState() : initialState;
+    saveRam(key, currentValue);
+  }
+
+  // Set up a single RamStore subscriber per key
+  if (!subscribers.has(key)) {
+    subscribers.set(key, new Set());
+
+    // Listen to RamStore changes for this key
+    const unsubscribe = subscribeRam((changedKey, newValue, oldValue) => {
+      if (changedKey === key) {
+        // 🔥 Push the new value to all registered widgets for this key
+        const widgets = widgetsByKey.get(key);
+        if (widgets) {
+          widgets.forEach(({ widget, propName }) => {
+            if (widget && widget.update) {
+              widget.update({ [propName]: newValue });
+            }
+          });
+        }
+
+        // Notify all subscriber callbacks
+        const callbacks = subscribers.get(key);
+        callbacks.forEach((callback) => callback(newValue, oldValue));
+
+        // Trigger a global re-render
+        triggerRender();
+      }
+    });
+
+    // Track the unsubscribe handle for hot-reload cleanup
+    if (!window._useStateCleanups) window._useStateCleanups = [];
+    window._useStateCleanups.push(unsubscribe);
+  }
+
+  // 🔥 Register the widget for automatic updates if one was provided
+  if (widget && propName) {
+    registerWidget(key, widget, propName);
+  }
+
+  /**
+   * Updates the state value. Accepts either a new value directly or an updater
+   * function that receives the current value and returns the next value.
+   *
+   * @param {*|Function} newValueOrUpdater - New value or `(prevValue) => nextValue` updater.
+   * @returns {void}
+   */
+  const setState = (newValueOrUpdater) => {
+    const oldValue = currentValue;
+    let newValue;
+
+    if (typeof newValueOrUpdater === "function") {
+      newValue = newValueOrUpdater(oldValue);
+    } else {
+      newValue = newValueOrUpdater;
+    }
+
+    if (oldValue !== newValue) {
+      currentValue = newValue;
+      saveRam(key, currentValue);
+    }
+  };
+
+  /**
+   * Subscribes a callback to state changes for this key.
+   *
+   * @param {Function} callback - Called with `(newValue, oldValue)` on every change.
+   * @returns {Function} Unsubscribe function.
+   */
+  const subscribe = (callback) => {
+    if (!subscribers.has(key)) {
+      subscribers.set(key, new Set());
+    }
+    subscribers.get(key).add(callback);
+    return () => {
+      if (subscribers.has(key)) {
+        subscribers.get(key).delete(callback);
+      }
+    };
+  };
+
+  // 🔥 Create a reactive value object so WidgetFactory can detect state bindings automatically
+  const reactiveValue = {
+    _isReactive: true,
+    _stateKey: key,
+    _value: currentValue,
+    valueOf() {
+      return this._value;
+    },
+    toString() {
+      return String(this._value);
+    },
+  };
+
+  // Return an array matching React's useState pattern: [value, setter, subscriber]
+  return [reactiveValue, setState, subscribe];
+};
+
+/**
+ * Watches a state key and invokes the callback whenever its value changes.
+ * Useful for side effects that should not trigger a full re-render.
+ *
+ * @param {string} key - The state key to watch.
+ * @param {Function} callback - Called with `(newValue, oldValue)` on every change.
+ * @returns {Function} Unsubscribe function.
+ */
+export const useWatchState = (key, callback) => {
+  if (!subscribers.has(key)) {
+    subscribers.set(key, new Set());
+  }
+  subscribers.get(key).add(callback);
+  return () => subscribers.get(key).delete(callback);
+};
+
+/**
+ * Cleans up all state subscriptions, widget registrations, and pending render
+ * timers. Should be called during hot-reload to reset the module to a clean state.
+ *
+ * @returns {void}
+ */
+export const cleanupUseState = () => {
+  if (window._useStateCleanups) {
+    window._useStateCleanups.forEach((cleanup) => {
+      if (typeof cleanup === "function") cleanup();
+    });
+    window._useStateCleanups = [];
+  }
+  subscribers.clear();
+  widgetsByKey.clear();
+  globalRender = null;
+  if (renderTimeout) clearTimeout(renderTimeout);
+};
+
+/**
+ * Returns diagnostic statistics about the current state of the useState module.
+ * Useful for debugging subscription leaks or widget registration issues.
+ *
+ * @returns {{ subscribersCount: number, widgetsCount: number, globalRender: boolean }}
+ */
+export const getUseStateStats = () => {
+  return {
+    subscribersCount: subscribers.size,
+    widgetsCount: widgetsByKey.size,
+    globalRender: !!globalRender,
+  };
+};
+
+// Re-export RamStore functions under convenience aliases
+export {
+  saveRam as saveState,
+  getRam as getState,
+  subscribeRam as subscribeState,
+};

package/src/tools/uuid.js

@@ -0,0 +1,42 @@
+// tools/uuid.js
+
+/**
+ * Generate a UUID v4
+ * @returns {string} UUID
+ */
+export const uuid = () => {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+};
+
+/**
+ * Generate a short ID (8 characters)
+ * @returns {string} Short ID
+ */
+export const shortId = () => {
+  return Math.random().toString(36).substring(2, 10);
+};
+
+/**
+ * Generate a numeric ID
+ * @param {number} length - Length of the ID
+ * @returns {string} Numeric ID
+ */
+export const numericId = (length = 6) => {
+  return Math.random()
+    .toString()
+    .slice(2, 2 + length);
+};
+
+/**
+ * Generate a timestamp-based ID
+ * @returns {string} Timestamp ID
+ */
+export const timestampId = () => {
+  return Date.now().toString(36) + Math.random().toString(36).substring(2, 6);
+};
+
+export default { uuid, shortId, numericId, timestampId };

package/src/utils/TextInputValidator.js

@@ -0,0 +1,256 @@
+// src/modules/FletBox/core/TextInputValidator.js
+
+/**
+ * TextInputValidator - Validates and sanitizes text inputs
+ *
+ * @description Provides functions to validate and sanitize inputs
+ * - onlyLetters()       → only letters A-Z a-z (with accents and Ñ)
+ * - onlyNumbers()       → only numbers 0-9
+ * - isEmail()           → valid email format
+ * - onlyAlphanumeric()  → letters and numbers
+ * - sanitize()          → removes malicious code (XSS protection)
+ * - escapeHtml()        → escapes HTML characters
+ * - safeText()          → combines sanitize + escapeHtml
+ * - isSafe()            → detects malicious patterns
+ * - filter()            → custom pattern filter
+ * - limitLength()       → limits text length
+ * - isOnlyLetters()     → validates if only letters
+ * - isOnlyNumbers()     → validates if only numbers
+ * - filterEmail()       → filters email characters
+ */
+
+export const TextInputValidator = {
+  /**
+   * Filters only letters (A-Z, a-z, with accents and Ñ)
+   * @param {string} value - Text to filter
+   * @returns {string} Only letters
+   */
+  onlyLetters: (value) => {
+    if (!value) return "";
+    return value.replace(/[^A-Za-záéíóúüñÁÉÍÓÚÜÑ\s]/g, "");
+  },
+
+  /**
+   * Filters only numbers (0-9)
+   * @param {string} value - Text to filter
+   * @returns {string} Only numbers
+   */
+  onlyNumbers: (value) => {
+    if (!value) return "";
+    return value.replace(/[^0-9]/g, "");
+  },
+
+  /**
+   * Validates email format
+   * @param {string} value - Email to validate
+   * @returns {boolean} true if valid email
+   */
+  isEmail: (value) => {
+    if (!value) return false;
+    const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+    return emailRegex.test(value);
+  },
+
+  /**
+   * Filters email (only allowed characters in email)
+   * @param {string} value - Text to filter
+   * @returns {string} Filtered email
+   */
+  filterEmail: (value) => {
+    if (!value) return "";
+    // Only allows: letters, numbers, @, ., _, -, +, %
+    return value.replace(/[^a-zA-Z0-9@._\-+%]/g, "");
+  },
+
+  /**
+   * Filters only letters and numbers
+   * @param {string} value - Text to filter
+   * @returns {string} Only alphanumeric
+   */
+  onlyAlphanumeric: (value) => {
+    if (!value) return "";
+    return value.replace(/[^a-zA-Z0-9]/g, "");
+  },
+
+  /**
+   * Custom pattern filter
+   * @param {string} value - Text to filter
+   * @param {string} pattern - Allowed characters (without ^)
+   * @returns {string} Filtered text
+   */
+  filter: (value, pattern) => {
+    if (!value) return "";
+    return value.replace(new RegExp(`[^${pattern}]`, "g"), "");
+  },
+
+  /**
+   * Limits text length
+   * @param {string} value - Text to limit
+   * @param {number} maxLength - Maximum length
+   * @returns {string} Truncated text
+   */
+  limitLength: (value, maxLength) => {
+    if (!value) return "";
+    return value.slice(0, maxLength);
+  },
+
+  /**
+   * Validates if text contains only letters
+   * @param {string} value - Text to validate
+   * @returns {boolean} true if only letters
+   */
+  isOnlyLetters: (value) => {
+    if (!value) return true;
+    return /^[A-Za-záéíóúüñÁÉÍÓÚÜÑ\s]+$/.test(value);
+  },
+
+  /**
+   * Validates if text contains only numbers
+   * @param {string} value - Text to validate
+   * @returns {boolean} true if only numbers
+   */
+  isOnlyNumbers: (value) => {
+    if (!value) return true;
+    return /^[0-9]+$/.test(value);
+  },
+
+  /**
+   * Sanitizes text to prevent XSS and malicious code
+   * Removes/escapes: <script>, javascript:, onload=, onerror=, etc.
+   * @param {string} value - Text to sanitize
+   * @returns {string} Safe text
+   */
+  sanitize: (value) => {
+    if (!value) return "";
+
+    let safe = String(value);
+
+    // Remove <script> tags and content
+    safe = safe.replace(
+      /<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi,
+      "",
+    );
+
+    // Remove javascript: protocol
+    safe = safe.replace(/javascript:/gi, "");
+
+    // Remove onload=, onerror=, onclick=, etc.
+    safe = safe.replace(/on\w+\s*=/gi, "");
+
+    // Remove alert(), confirm(), prompt()
+    safe = safe.replace(/alert\s*\(/gi, "");
+    safe = safe.replace(/confirm\s*\(/gi, "");
+    safe = safe.replace(/prompt\s*\(/gi, "");
+
+    // Remove eval()
+    safe = safe.replace(/eval\s*\(/gi, "");
+
+    // Remove document.write
+    safe = safe.replace(/document\.write/gi, "");
+
+    // Remove <iframe>
+    safe = safe.replace(
+      /<iframe\b[^<]*(?:(?!<\/iframe>)<[^<]*)*<\/iframe>/gi,
+      "",
+    );
+
+    // Remove <object>, <embed>
+    safe = safe.replace(/<\/?(object|embed)[^>]*>/gi, "");
+
+    // Remove <img> with onerror
+    safe = safe.replace(/<img[^>]+onerror\s*=[^>]*>/gi, "");
+
+    // Remove <link> with javascript
+    safe = safe.replace(
+      /<link[^>]+href\s*=\s*['"]javascript:[^'"]*['"][^>]*>/gi,
+      "",
+    );
+
+    // Remove <meta> with refresh or http-equiv
+    safe = safe.replace(/<meta[^>]+(refresh|http-equiv)[^>]*>/gi, "");
+
+    // Remove &{...} expressions (template injection)
+    safe = safe.replace(/&\{[^}]*\}/g, "");
+
+    // Remove {{...}} expressions (template injection)
+    safe = safe.replace(/\{\{[^}]*\}\}/g, "");
+
+    // Remove backticks with expressions
+    safe = safe.replace(/\${[^}]*}/g, "");
+
+    return safe;
+  },
+
+  /**
+   * Escapes HTML special characters
+   * Converts < > & " ' to HTML entities
+   * @param {string} value - Text to escape
+   * @returns {string} Escaped text safe for innerHTML
+   */
+  escapeHtml: (value) => {
+    if (!value) return "";
+
+    const htmlEntities = {
+      "&": "&amp;",
+      "<": "&lt;",
+      ">": "&gt;",
+      '"': "&quot;",
+      "'": "&#39;",
+      "/": "&#x2F;",
+      "`": "&#x60;",
+      "=": "&#x3D;",
+    };
+
+    return String(value).replace(/[&<>"'/`=]/g, (char) => htmlEntities[char]);
+  },
+
+  /**
+   * Complete sanitization for user input
+   * Combines sanitize() + escapeHtml()
+   * @param {string} value - Text to sanitize
+   * @returns {string} Completely safe text
+   */
+  safeText: (value) => {
+    if (!value) return "";
+    let safe = TextInputValidator.sanitize(value);
+    safe = TextInputValidator.escapeHtml(safe);
+    return safe;
+  },
+
+  /**
+   * Validates if text contains any malicious patterns
+   * @param {string} value - Text to check
+   * @returns {boolean} true if safe, false if contains malicious code
+   */
+  isSafe: (value) => {
+    if (!value) return true;
+
+    const maliciousPatterns = [
+      /<script\b/i,
+      /javascript:/i,
+      /on\w+\s*=/i,
+      /alert\s*\(/i,
+      /confirm\s*\(/i,
+      /prompt\s*\(/i,
+      /eval\s*\(/i,
+      /document\.write/i,
+      /<iframe\b/i,
+      /<object\b/i,
+      /<embed\b/i,
+      /<link[^>]+javascript:/i,
+      /<meta[^>]+refresh/i,
+      /&\{[^}]*\}/,
+      /\{\{[^}]*\}\}/,
+      /\${[^}]*}/,
+    ];
+
+    for (const pattern of maliciousPatterns) {
+      if (pattern.test(value)) {
+        return false;
+      }
+    }
+    return true;
+  },
+};
+
+export default TextInputValidator;