flet-box 0.0.0-stage → 1.0.2

package/src/tools/index.js

@@ -0,0 +1,38 @@
+// src/tools/index.js
+export { animation } from "./animation.js";
+export { shuffle, reverse, sort, unique, chunk } from "./array.js";
+export { border } from "./border.js";
+export { clipboard } from "./clipboard.js";
+export { color } from "./color.js";
+export { createList } from "./createList.js";
+export { delay, withMinDelay, retry } from "./delay.js";
+export { device } from "./device.js";
+export { dimensions, width, height } from "./dimensions.js";
+export { filter } from "./filter.js";
+export { flex } from "./flex.js";
+export { default as gradient } from "./gradient.js";
+export { grid } from "./grid.js";
+export { default as margin } from "./margin.js";
+export { mapList, repeat, range } from "./mapList.js";
+export { memo, memoWithKey, clearMemo } from "./memo.js";
+export { os } from "./os.js";
+export { default as padding } from "./padding.js";
+export { print } from "./print.js";
+export { random } from "./random.js";
+export { default as rgba } from "./rgba.js";
+export { default as shadow } from "./shadow.js";
+export {
+  capitalize,
+  capitalizeWords,
+  lowerCase,
+  upperCase,
+  reverseString,
+  truncate,
+} from "./string.js";
+export { formatDate, relativeTime, sleep, now } from "./time.js";
+export { transform } from "./transform.js";
+export { transition } from "./transition.js";
+export { useState, useWatchState } from "./useState.js";
+export { uuid, shortId, numericId, timestampId } from "./uuid.js";
+export { dict, emptyDict, fromJSON, fromEntries, Dict } from "./dict.js";
+export { ref } from "./ref.js";

package/src/tools/mapList.js

@@ -0,0 +1,107 @@
+// tools/mapList.js
+
+/**
+ * Maps an array, a numeric length, or a plain object to an array of widgets or
+ * any other value produced by the mapping function.
+ *
+ * - **Array**: iterates with `(item, index)`.
+ * - **Number**: treats the value as an array length and iterates with `(null, index)`.
+ * - **Object**: iterates over `Object.entries` with `(value, key, index)`.
+ *
+ * @param {Array|number|Object} list - Source collection.
+ * @param {Function} fn - Mapping function. Signature depends on source type:
+ *   - Array: `(item, index) => widget`
+ *   - Number: `(null, index) => widget`
+ *   - Object: `(value, key, index) => widget`
+ * @returns {Array} Array of mapped values.
+ *
+ * @example
+ * // Map array to widgets
+ * mapList(users, (user, i) => Text({ text: user.name }))
+ *
+ * @example
+ * // Generateste N widgets from a number
+ * mapList(5, (_, i) => Skeleton({ variant: 'text' }))
+ *
+ * @example
+ * // Map object values
+ * mapList({ a: 1, b: 2, c: 3 }, (value, key) => Text({ text: `${key}: ${value}` }))
+ */
+export const mapList = (list, fn) => {
+  // Handle number — create a virtual array of that length
+  if (typeof list === "number") {
+    const arr = [];
+    for (let i = 0; i < list; i++) {
+      arr.push(fn(null, i));
+    }
+    return arr;
+  }
+
+  // Handle array
+  if (Array.isArray(list)) {
+    return list.map((item, index) => fn(item, index));
+  }
+
+  // Handle plain object — iterate over its entries
+  if (typeof list === "object" && list !== null) {
+    return Object.entries(list).map(([key, value], index) =>
+      fn(value, key, index),
+    );
+  }
+
+  return [];
+};
+
+/**
+ * Repeats a widget (or calls a factory function) `count` times and returns the
+ * resulting array.
+ *
+ * @param {number} count - Number of repetitions.
+ * @param {Function|*} widget - Widget instance to repeat, or a `(index) => widget`
+ *   factory function called on each iteration.
+ * @returns {Array} Array of widgets.
+ *
+ * @example
+ * repeat(3, Button({ text: 'Click' }))
+ * repeat(5, (i) => Text({ text: `Item ${i}` }))
+ */
+export const repeat = (count, widget) => {
+  const result = [];
+  for (let i = 0; i < count; i++) {
+    if (typeof widget === "function") {
+      result.push(widget(i));
+    } else {
+      result.push(widget);
+    }
+  }
+  return result;
+};
+
+/**
+ * Generates an array of numbers in the half-open interval `[start, end)` with
+ * a configurable step. Mirrors Python's `range()`.
+ *
+ * When called with a single argument, the range starts at `0`.
+ *
+ * @param {number} start - Start value (inclusive), or the exclusive end when `end` is omitted.
+ * @param {number} [end] - End value (exclusive). If omitted, `start` becomes the end and `0` is used as start.
+ * @param {number} [step=1] - Increment between values.
+ * @returns {number[]} Array of numbers.
+ *
+ * @example
+ * range(5)        // [0, 1, 2, 3, 4]
+ * range(1, 5)     // [1, 2, 3, 4]
+ * range(0, 10, 2) // [0, 2, 4, 6, 8]
+ */
+export const range = (start, end, step = 1) => {
+  const result = [];
+  const actualStart = end === undefined ? 0 : start;
+  const actualEnd = end === undefined ? start : end;
+
+  for (let i = actualStart; i < actualEnd; i += step) {
+    result.push(i);
+  }
+  return result;
+};
+
+export default { mapList, repeat, range };

package/src/tools/margin.js

@@ -0,0 +1,93 @@
+// tools/margin.js
+
+/**
+ * Generates a CSS `margin` shorthand string from a number, a plain CSS string,
+ * or a configuration object.
+ *
+ * When all resolved sides are equal the output is a single value (e.g. `"20px"`).
+ * When only top/bottom differ from left/right the two-value shorthand is used
+ * (e.g. `"10px 20px"`). Otherwise the full four-value form is returned.
+ *
+ * Object option keys (all optional, resolved in priority order per side):
+ * - `all` — applies to every side.
+ * - `horizontal` — applies to `left` and `right`.
+ * - `vertical` — applies to `top` and `bottom`.
+ * - `top`, `right`, `bottom`, `left` — individual side overrides.
+ *
+ * @param {number|string|Object} value
+ *   A number (converted to `px`), a raw CSS string, or an options object.
+ * @returns {string} CSS margin value.
+ *
+ * @example
+ * margin(20)                                        // "20px"
+ * margin({ all: 20 })                               // "20px"
+ * margin({ horizontal: 20, vertical: 10 })          // "10px 20px"
+ * margin({ top: 10, right: 20, bottom: 10, left: 20 }) // "10px 20px"
+ * margin({ left: 20, right: 20 })                   // "0px 20px"
+ * margin({ top: 10, bottom: 10 })                   // "10px 0px"
+ */
+export const margin = (value) => {
+  // A number or raw CSS string applies uniformly to all sides
+  if (typeof value === "number" || typeof value === "string") {
+    const px = typeof value === "number" ? `${value}px` : value;
+    return px;
+  }
+
+  // Object form — resolve each side independently
+  if (typeof value === "object") {
+    const top =
+      value.top !== undefined
+        ? value.top
+        : value.vertical !== undefined
+          ? value.vertical
+          : value.all !== undefined
+            ? value.all
+            : 0;
+    const right =
+      value.right !== undefined
+        ? value.right
+        : value.horizontal !== undefined
+          ? value.horizontal
+          : value.all !== undefined
+            ? value.all
+            : 0;
+    const bottom =
+      value.bottom !== undefined
+        ? value.bottom
+        : value.vertical !== undefined
+          ? value.vertical
+          : value.all !== undefined
+            ? value.all
+            : 0;
+    const left =
+      value.left !== undefined
+        ? value.left
+        : value.horizontal !== undefined
+          ? value.horizontal
+          : value.all !== undefined
+            ? value.all
+            : 0;
+
+    const topPx = typeof top === "number" ? `${top}px` : top;
+    const rightPx = typeof right === "number" ? `${right}px` : right;
+    const bottomPx = typeof bottom === "number" ? `${bottom}px` : bottom;
+    const leftPx = typeof left === "number" ? `${left}px` : left;
+
+    // All sides equal — return a single value
+    if (topPx === rightPx && rightPx === bottomPx && bottomPx === leftPx) {
+      return topPx;
+    }
+
+    // Only horizontal and vertical differ — use two-value shorthand
+    if (topPx === bottomPx && rightPx === leftPx) {
+      return `${topPx} ${rightPx}`;
+    }
+
+    // Full four-value form
+    return `${topPx} ${rightPx} ${bottomPx} ${leftPx}`;
+  }
+
+  return "0px";
+};
+
+export default margin;

package/src/tools/memo.js

@@ -0,0 +1,60 @@
+// tools/memo.js
+
+/**
+ * Memoize a function (cache results)
+ * @param {Function} fn - Function to memoize
+ * @returns {Function} Memoized function
+ * @example
+ * const expensiveFn = memo((n) => { ... })
+ */
+export const memo = (fn) => {
+  const cache = new Map();
+
+  const memoized = (...args) => {
+    const key = JSON.stringify(args);
+    if (cache.has(key)) {
+      return cache.get(key);
+    }
+    const result = fn(...args);
+    cache.set(key, result);
+    return result;
+  };
+
+  memoized.cache = cache;
+  return memoized;
+};
+
+/**
+ * Memoize with custom key generator
+ * @param {Function} fn - Function to memoize
+ * @param {Function} keyFn - Key generator function
+ * @returns {Function} Memoized function
+ */
+export const memoWithKey = (fn, keyFn) => {
+  const cache = new Map();
+
+  const memoized = (...args) => {
+    const key = keyFn(...args);
+    if (cache.has(key)) {
+      return cache.get(key);
+    }
+    const result = fn(...args);
+    cache.set(key, result);
+    return result;
+  };
+
+  memoized.cache = cache;
+  return memoized;
+};
+
+/**
+ * Clear memo cache
+ * @param {Function} memoizedFn - Memoized function
+ */
+export const clearMemo = (memoizedFn) => {
+  if (memoizedFn.cache) {
+    memoizedFn.cache.clear();
+  }
+};
+
+export default { memo, memoWithKey, clearMemo };

package/src/tools/os.js

@@ -0,0 +1,104 @@
+// tools/os.js
+
+/**
+ * Operating system detection utilities.
+ *
+ * Parses `navigator.userAgent` to identify the host OS and its version.
+ * All methods are synchronous reads — no side effects, no caching.
+ *
+ * Note: UA-string detection is a best-effort heuristic. Browsers, WebViews,
+ * and some privacy settings can spoof or omit UA data. Use these results for
+ * progressive enhancement, not security decisions.
+ *
+ * @namespace os
+ */
+export const os = {
+  /**
+   * Get the name of the host operating system.
+   *
+   * Detection order matters: Android is checked before Linux because Android
+   * UAs also contain "Linux". ChromeOS (CrOS) is checked last as a subset
+   * of Linux-like UAs.
+   *
+   * @returns {"Windows"|"macOS"|"Android"|"iOS"|"Linux"|"ChromeOS"|"Unknown"}
+   *   Normalized OS name, or `"Unknown"` when no known pattern matches
+   *
+   * @example
+   * os.name() // "macOS" on a Mac, "Android" on an Android phone
+   */
+  name: () => {
+    const ua = navigator.userAgent;
+
+    if (/Windows/i.test(ua)) return "Windows";
+    if (/Mac OS|MacIntel|MacPPC|Mac68K/i.test(ua)) return "macOS";
+    if (/Android/i.test(ua)) return "Android";
+    if (/iOS|iPhone|iPad|iPod/i.test(ua)) return "iOS";
+    if (/Linux/i.test(ua)) return "Linux";
+    if (/CrOS/i.test(ua)) return "ChromeOS";
+
+    return "Unknown";
+  },
+
+  /**
+   * Get the version string of the host operating system.
+   *
+   * Extracts the version from the UA string using OS-specific regex patterns.
+   * On macOS, underscore separators in the UA are normalized to dots
+   * (e.g. `"10_15_7"` → `"10.15.7"`).
+   *
+   * @returns {string} Version string (e.g. `"10.0"`, `"14_2"` normalized to `"14.2"`)
+   *   or `"Unknown"` when the pattern does not match
+   *
+   * @example
+   * os.version() // "14.1" on macOS Sonoma, "13.0" on Windows 11
+   */
+  version: () => {
+    const ua = navigator.userAgent;
+    const osName = os.name();
+
+    if (osName === "Windows") {
+      const match = ua.match(/Windows NT (\d+\.\d+)/);
+      if (match) return match[1];
+    }
+    if (osName === "macOS") {
+      const match = ua.match(/Mac OS X (\d+[._]\d+[._]\d+)/);
+      if (match) return match[1].replace(/_/g, ".");
+    }
+    if (osName === "Android") {
+      const match = ua.match(/Android (\d+\.\d+)/);
+      if (match) return match[1];
+    }
+    if (osName === "iOS") {
+      const match = ua.match(/OS (\d+[._]\d+[._]?\d*)/);
+      if (match) return match[1].replace(/_/g, ".");
+    }
+
+    return "Unknown";
+  },
+
+  /**
+   * Detect whether the host OS is a mobile operating system.
+   *
+   * Returns `true` for Android and iOS. Use this when you need OS-level
+   * behavior differences rather than viewport-size differences (prefer
+   * `device.isMobile()` for viewport-based branching).
+   *
+   * @returns {boolean} `true` if the OS is Android or iOS
+   */
+  isMobile: () => {
+    return os.name() === "Android" || os.name() === "iOS";
+  },
+
+  /**
+   * Detect whether the host OS is a desktop operating system.
+   *
+   * The inverse of `os.isMobile()`.
+   *
+   * @returns {boolean} `true` if the OS is not Android or iOS
+   */
+  isDesktop: () => {
+    return !os.isMobile();
+  },
+};
+
+export default os;

package/src/tools/padding.js

@@ -0,0 +1,93 @@
+// tools/padding.js
+
+/**
+ * Generates a CSS `padding` shorthand string from a number, a plain CSS string,
+ * or a configuration object.
+ *
+ * When all resolved sides are equal the output is a single value (e.g. `"20px"`).
+ * When only top/bottom differ from left/right the two-value shorthand is used
+ * (e.g. `"10px 20px"`). Otherwise the full four-value form is returned.
+ *
+ * Object option keys (all optional, resolved in priority order per side):
+ * - `all` — applies to every side.
+ * - `horizontal` — applies to `left` and `right`.
+ * - `vertical` — applies to `top` and `bottom`.
+ * - `top`, `right`, `bottom`, `left` — individual side overrides.
+ *
+ * @param {number|string|Object} value
+ *   A number (converted to `px`), a raw CSS string, or an options object.
+ * @returns {string} CSS padding value.
+ *
+ * @example
+ * padding(20)                                        // "20px"
+ * padding({ all: 20 })                               // "20px"
+ * padding({ horizontal: 20, vertical: 10 })          // "10px 20px"
+ * padding({ top: 10, right: 20, bottom: 10, left: 20 }) // "10px 20px"
+ * padding({ left: 20, right: 20 })                   // "0px 20px"
+ * padding({ top: 10, bottom: 10 })                   // "10px 0px"
+ */
+export const padding = (value) => {
+  // A number or raw CSS string applies uniformly to all sides
+  if (typeof value === "number" || typeof value === "string") {
+    const px = typeof value === "number" ? `${value}px` : value;
+    return px;
+  }
+
+  // Object form — resolve each side independently
+  if (typeof value === "object") {
+    const top =
+      value.top !== undefined
+        ? value.top
+        : value.vertical !== undefined
+          ? value.vertical
+          : value.all !== undefined
+            ? value.all
+            : 0;
+    const right =
+      value.right !== undefined
+        ? value.right
+        : value.horizontal !== undefined
+          ? value.horizontal
+          : value.all !== undefined
+            ? value.all
+            : 0;
+    const bottom =
+      value.bottom !== undefined
+        ? value.bottom
+        : value.vertical !== undefined
+          ? value.vertical
+          : value.all !== undefined
+            ? value.all
+            : 0;
+    const left =
+      value.left !== undefined
+        ? value.left
+        : value.horizontal !== undefined
+          ? value.horizontal
+          : value.all !== undefined
+            ? value.all
+            : 0;
+
+    const topPx = typeof top === "number" ? `${top}px` : top;
+    const rightPx = typeof right === "number" ? `${right}px` : right;
+    const bottomPx = typeof bottom === "number" ? `${bottom}px` : bottom;
+    const leftPx = typeof left === "number" ? `${left}px` : left;
+
+    // All sides equal — return a single value
+    if (topPx === rightPx && rightPx === bottomPx && bottomPx === leftPx) {
+      return topPx;
+    }
+
+    // Only horizontal and vertical differ — use two-value shorthand
+    if (topPx === bottomPx && rightPx === leftPx) {
+      return `${topPx} ${rightPx}`;
+    }
+
+    // Full four-value form
+    return `${topPx} ${rightPx} ${bottomPx} ${leftPx}`;
+  }
+
+  return "0px";
+};
+
+export default padding;

package/src/tools/print.js

@@ -0,0 +1,69 @@
+// tools/print.js
+// Simple and clean logging system
+
+/**
+ * A thin wrapper around `console` that adds icons, optional timestamps, and
+ * optional labels to log output. Objects are serialized to pretty-printed JSON.
+ *
+ * @param {*} message - Value to log. Objects are serialized with `JSON.stringify`.
+ * @param {"log"|"warn"|"error"|"info"|"success"|"debug"} [type="log"] - Log level.
+ *   Can also be passed as an options object for backwards compatibility.
+ * @param {Object} [options={}] - Additional formatting options.
+ * @param {boolean} [options.timestamp=false] - Prepend the current time.
+ * @param {string} [options.label=""] - Bracket-wrapped label inserted before the message.
+ * @param {boolean} [options.prefix=true] - Whether to prepend the level icon.
+ * @returns {void}
+ *
+ * @example
+ * print('Hello world')
+ * print('User logged in', 'success')
+ * print('Something went wrong', 'error')
+ * print('Loading...', 'info', { timestamp: true })
+ */
+export const print = (message, type = "log", options = {}) => {
+  // Allow the second argument to be an options object for backwards compatibility
+  if (typeof type === "object") {
+    options = type;
+    type = "log";
+  }
+
+  const { timestamp = false, label = "", prefix = true } = options;
+
+  const styles = {
+    log: { color: "#94a3b8", icon: "📝", method: "log" },
+    warn: { color: "#fbbf24", icon: "⚠️", method: "warn" },
+    error: { color: "#f87171", icon: "❌", method: "error" },
+    info: { color: "#60a5fa", icon: "ℹ️", method: "info" },
+    success: { color: "#34d399", icon: "✅", method: "log" },
+    debug: { color: "#c084fc", icon: "🐛", method: "debug" },
+  };
+
+  const config = styles[type] || styles.log;
+
+  // Serialize objects to readable JSON
+  let formattedMessage = message;
+  if (typeof message === "object" && message !== null) {
+    formattedMessage = JSON.stringify(message, null, 2);
+  }
+
+  const parts = [];
+  if (timestamp) parts.push(`[${new Date().toLocaleTimeString()}]`);
+  if (prefix) parts.push(config.icon);
+  if (label) parts.push(`[${label}]`);
+  parts.push(formattedMessage);
+
+  const finalMessage = parts.join(" ");
+
+  // Dispatch to the appropriate console method for the log level
+  console[config.method](finalMessage);
+};
+
+// Shorthand aliases (uncomment to enable individual exports):
+// export const log = (msg) => print(msg, "log");
+// export const warn = (msg) => print(msg, "warn");
+// export const error = (msg) => print(msg, "error");
+// export const info = (msg) => print(msg, "info");
+// export const success = (msg) => print(msg, "success");
+// export const debug = (msg) => print(msg, "debug");
+
+export default print;