flet-box 0.0.0-stage → 1.0.2

package/src/tools/random.js

@@ -0,0 +1,299 @@
+/**
+ * @file random.js
+ * Faker-style random data generators for prototyping and testing.
+ *
+ * All generators are grouped under the `random` namespace object.
+ * Functions that accept no arguments choose sensible defaults so you can
+ * call them without configuration for quick mocks.
+ *
+ * Important: the `firstNames` and `lastNames` arrays are intentionally
+ * Spanish-language sample data — they are runtime content, not developer
+ * comments, and are left unchanged.
+ *
+ * @module tools/random
+ */
+
+// ========== BASE DATA ==========
+// Sample name pools used by firstName / lastName / fullName / email generators.
+const firstNames = [
+  "Ana",
+  "Juan",
+  "María",
+  "Carlos",
+  "Laura",
+  "Pedro",
+  "Sofía",
+  "Luis",
+  "Elena",
+  "Miguel",
+  "Carmen",
+  "José",
+  "Isabel",
+  "Francisco",
+  "Marta",
+  "David",
+  "Lucía",
+  "Javier",
+  "Paula",
+  "Daniel",
+];
+
+const lastNames = [
+  "García",
+  "Pérez",
+  "López",
+  "Martínez",
+  "Sánchez",
+  "Rodríguez",
+  "Fernández",
+  "González",
+  "Díaz",
+  "Moreno",
+  "Jiménez",
+  "Ruiz",
+  "Hernández",
+  "Álvarez",
+  "Romero",
+  "Navarro",
+  "Torres",
+  "Domínguez",
+];
+
+const domains = [
+  "gmail.com",
+  "yahoo.com",
+  "hotmail.com",
+  "outlook.com",
+  "icloud.com",
+  "protonmail.com",
+  "example.com",
+  "mail.com",
+];
+
+// Helper to pad numbers with leading zeros
+const pad = (num, length = 2) => String(num).padStart(length, "0");
+
+export const random = {
+  // ========== NUMBERS ==========
+  /**
+   * Generate a random number between min and max (inclusive)
+   * @param {number} min - Minimum value (default: 0)
+   * @param {number} max - Maximum value (default: 100)
+   * @returns {number}
+   */
+  number: (min = 0, max = 100) =>
+    Math.floor(Math.random() * (max - min + 1)) + min,
+
+  // ========== STRINGS ==========
+  /**
+   * Generate a random string of specified length
+   * @param {number} length - Length of the string (default: 8)
+   * @returns {string}
+   */
+  string: (length = 8) =>
+    Math.random()
+      .toString(36)
+      .substring(2, 2 + length),
+
+  // ========== NAMES ==========
+  /**
+   * Random first name
+   * @returns {string}
+   */
+  firstName: () => firstNames[Math.floor(Math.random() * firstNames.length)],
+
+  /**
+   * Random last name
+   * @returns {string}
+   */
+  lastName: () => lastNames[Math.floor(Math.random() * lastNames.length)],
+
+  /**
+   * Random full name
+   * @returns {string} Example: "Juan Pérez"
+   */
+  fullName: () => `${random.firstName()} ${random.lastName()}`,
+
+  /**
+   * Generate random email from name
+   * @param {string} name - Optional name (if not provided, generates one)
+   * @returns {string} Example: "juan.perez123@gmail.com"
+   */
+  email: (name = null) => {
+    const fullName = name || random.fullName();
+
+    let base = fullName
+      .toLowerCase()
+      .normalize("NFD")
+      .replace(/[\u0300-\u036f]/g, "")
+      .replace(/[^a-z]/g, ".");
+
+    base = base.replace(/\.+/g, ".");
+
+    const code = random.number(100, 999);
+    const domain = domains[Math.floor(Math.random() * domains.length)];
+
+    return `${base}${code}@${domain}`;
+  },
+
+  // ========== DATES & TIMES ==========
+  /**
+   * Generate a random date between two dates
+   * @param {Date|string} start - Start date (default: 1 year ago)
+   * @param {Date|string} end - End date (default: today)
+   * @returns {Date}
+   */
+  date: (start = null, end = null) => {
+    const startDate = start ? new Date(start) : new Date();
+    startDate.setFullYear(startDate.getFullYear() - 1);
+
+    const endDate = end ? new Date(end) : new Date();
+
+    const startTime = startDate.getTime();
+    const endTime = endDate.getTime();
+    const randomTime = startTime + Math.random() * (endTime - startTime);
+
+    return new Date(randomTime);
+  },
+
+  /**
+   * Generate a random date as ISO string
+   * @param {Date|string} start - Start date (default: 1 year ago)
+   * @param {Date|string} end - End date (default: today)
+   * @returns {string} ISO format: "2024-01-15"
+   */
+  dateString: (start = null, end = null) => {
+    const date = random.date(start, end);
+    return date.toISOString().split("T")[0];
+  },
+
+  /**
+   * Generate a random time (HH:MM:SS)
+   * @returns {string} Example: "14:32:18"
+   */
+  time: () => {
+    const hours = random.number(0, 23);
+    const minutes = random.number(0, 59);
+    const seconds = random.number(0, 59);
+    return `${pad(hours)}:${pad(minutes)}:${pad(seconds)}`;
+  },
+
+  /**
+   * Generate a random time with AM/PM format
+   * @returns {string} Example: "02:32:18 PM"
+   */
+  timeAmPm: () => {
+    let hours = random.number(0, 23);
+    const minutes = random.number(0, 59);
+    const seconds = random.number(0, 59);
+    const ampm = hours >= 12 ? "PM" : "AM";
+    hours = hours % 12 || 12;
+    return `${pad(hours)}:${pad(minutes)}:${pad(seconds)} ${ampm}`;
+  },
+
+  /**
+   * Generate a random datetime (ISO string)
+   * @returns {string} Example: "2024-01-15T14:32:18.123Z"
+   */
+  datetime: () => {
+    const date = random.date();
+    return date.toISOString();
+  },
+
+  /**
+   * Generate a random timestamp (Unix timestamp in milliseconds)
+   * @returns {number}
+   */
+  timestamp: () => random.date().getTime(),
+
+  /**
+   * Generate a random day of week
+   * @returns {string} Monday, Tuesday, etc.
+   */
+  dayOfWeek: () => {
+    const days = [
+      "Monday",
+      "Tuesday",
+      "Wednesday",
+      "Thursday",
+      "Friday",
+      "Saturday",
+      "Sunday",
+    ];
+    return random.choice(days);
+  },
+
+  /**
+   * Generate a random month
+   * @returns {string} January, February, etc.
+   */
+  month: () => {
+    const months = [
+      "January",
+      "February",
+      "March",
+      "April",
+      "May",
+      "June",
+      "July",
+      "August",
+      "September",
+      "October",
+      "November",
+      "December",
+    ];
+    return random.choice(months);
+  },
+
+  // ========== OTHER UTILITIES ==========
+  /**
+   * Random age between 18 and 65
+   * @returns {number}
+   */
+  age: () => random.number(18, 65),
+
+  /**
+   * Random boolean (true/false)
+   * @returns {boolean}
+   */
+  boolean: () => Math.random() > 0.5,
+
+  /**
+   * Pick a random element from an array
+   * @param {Array} array - The array to pick from
+   * @returns {*}
+   */
+  choice: (array) => array[Math.floor(Math.random() * array.length)],
+
+  /**
+   * Generate a random ID (8-10 characters)
+   * @returns {string}
+   */
+  id: () => Math.random().toString(36).substring(2, 10),
+
+  /**
+   * Generate a random hex color
+   * @returns {string} Example: "#3a7bd5"
+   */
+  hexColor: () => {
+    return (
+      "#" +
+      Math.floor(Math.random() * 16777215)
+        .toString(16)
+        .padStart(6, "0")
+    );
+  },
+
+  /**
+   * Generate a random RGB color
+   * @returns {string} Example: "rgb(58, 123, 213)"
+   */
+  rgbColor: () => {
+    const r = random.number(0, 255);
+    const g = random.number(0, 255);
+    const b = random.number(0, 255);
+    return `rgb(${r}, ${g}, ${b})`;
+  },
+};
+
+export default random;

package/src/tools/ref.js

@@ -0,0 +1,70 @@
+// src/tools/ref.js
+//
+// Usage:
+//   const display = ref();
+//   Text({ ref: display });
+//   display.update({ text: 'Goodbye' });
+
+/**
+ * Creates a ref function that can be attached to a widget via its `ref` prop.
+ *
+ * When the framework assigns a widget instance to the ref, the ref function:
+ * 1. Stores the widget instance internally.
+ * 2. Copies all of the widget's methods directly onto the ref function so they
+ *    can be called as `display.someMethod()` without going through `.get()`.
+ * 3. Exposes non-function properties via `Object.defineProperty` getters/setters
+ *    so reads and writes are forwarded to the live widget.
+ *
+ * @returns {Function} A ref function with an additional `.update(props)` method.
+ *
+ * @example
+ * const display = ref();
+ * Text({ ref: display });           // framework assigns the widget
+ * display.update({ text: 'Hello' }); // directly updates the widget prop
+ */
+export const ref = () => {
+  let _widget = null;
+
+  /**
+   * Called by the framework with the widget instance when the widget is mounted.
+   * Also callable manually to point the ref at a different widget.
+   *
+   * @param {Object|null} widget - The widget instance to bind.
+   * @returns {Object|null} The same widget, for convenience.
+   */
+  const refFn = (widget) => {
+    _widget = widget;
+
+    // Mirror all methods and properties from the widget onto the ref function
+    // so callers can use `display.method()` directly
+    if (widget) {
+      Object.keys(widget).forEach((key) => {
+        if (typeof widget[key] === "function") {
+          refFn[key] = widget[key].bind(widget);
+        } else {
+          Object.defineProperty(refFn, key, {
+            get: () => widget[key],
+            set: (v) => {
+              widget[key] = v;
+            },
+            configurable: true,
+          });
+        }
+      });
+    }
+    return widget;
+  };
+
+  /**
+   * Calls the bound widget's `update` method with the given props, if the widget
+   * is mounted and supports updates.
+   *
+   * @param {Object} props - Props to pass to `widget.update(props)`.
+   * @returns {void}
+   */
+  refFn.update = (props) => {
+    if (_widget && _widget.update) _widget.update(props);
+  };
+
+  return refFn;
+};

package/src/tools/rgba.js

@@ -0,0 +1,4 @@
+// RGBA.js - Así of simple
+const rgba = (r, g, b, a = 1) => `rgba(${r}, ${g}, ${b}, ${a})`;
+
+export default rgba;

package/src/tools/shadow.js

@@ -0,0 +1,23 @@
+// Shadow.js - Minimal box-shadow helper
+
+/**
+ * Generate a CSS box-shadow string from individual components.
+ *
+ * Keeps callers from having to manually concatenate pixel values and color strings.
+ * Every parameter maps 1-to-1 to the CSS `box-shadow` shorthand property.
+ *
+ * @param {number} x - Horizontal offset in pixels (positive = right, negative = left)
+ * @param {number} y - Vertical offset in pixels (positive = down, negative = up)
+ * @param {number} blur - Blur radius in pixels (0 = sharp edge)
+ * @param {number} spread - Spread radius in pixels (positive = larger shadow, negative = smaller)
+ * @param {string} color - Shadow color (any valid CSS color value, e.g. "rgba(0,0,0,0.3)")
+ * @returns {string} CSS box-shadow value
+ *
+ * @example
+ * shadow(0, 4, 8, 0, "rgba(0,0,0,0.2)")
+ * // "0px 4px 8px 0px rgba(0,0,0,0.2)"
+ */
+const shadow = (x, y, blur, spread, color) =>
+  `${x}px ${y}px ${blur}px ${spread}px ${color}`;
+
+export default shadow;

package/src/tools/string.js

@@ -0,0 +1,85 @@
+// tools/string.js
+export const startsWith = (str, prefix) => str.startsWith(prefix);
+export const endsWith = (str, suffix) => str.endsWith(suffix);
+export const includes = (str, substr) => str.includes(substr);
+export const split = (str, separator) => str.split(separator);
+export const join = (arr, separator) => arr.join(separator);
+export const trim = (str) => str.trim();
+
+/**
+ * Capitalize first letter of a string
+ * @param {string} str - Input string
+ * @returns {string} Capitalized string
+ * @example capitalize('hello') // "Hello"
+ */
+export const capitalize = (str) => {
+  if (!str) return "";
+  return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+};
+
+/**
+ * Capitalize each word in a string
+ * @param {string} str - Input string
+ * @returns {string} String with each word capitalized
+ * @example capitalizeWords('hello world') // "Hello World"
+ */
+export const capitalizeWords = (str) => {
+  if (!str) return "";
+  return str
+    .split(" ")
+    .map((word) => capitalize(word))
+    .join(" ");
+};
+
+/**
+ * Convert string to lowercase
+ * @param {string} str - Input string
+ * @returns {string} Lowercase string
+ */
+export const lowerCase = (str) => {
+  if (!str) return "";
+  return str.toLowerCase();
+};
+
+/**
+ * Convert string to uppercase
+ * @param {string} str - Input string
+ * @returns {string} Uppercase string
+ */
+export const upperCase = (str) => {
+  if (!str) return "";
+  return str.toUpperCase();
+};
+
+/**
+ * Reverse a string
+ * @param {string} str - Input string
+ * @returns {string} Reversed string
+ * @example reverse('hello') // "olleh"
+ */
+export const reverseString = (str) => {
+  if (!str) return "";
+  return str.split("").reverse().join("");
+};
+
+/**
+ * Truncate string to max length
+ * @param {string} str - Input string
+ * @param {number} length - Max length
+ * @param {string} suffix - Suffix to add (default: '...')
+ * @returns {string} Truncated string
+ */
+export const truncate = (str, length = 50, suffix = "...") => {
+  if (!str) return "";
+  if (str.length <= length) return str;
+  return str.slice(0, length) + suffix;
+};
+
+export default {
+  capitalize,
+  capitalizeWords,
+  lowerCase,
+  upperCase,
+  reverseString,
+  truncate,
+};