flet-box 0.0.0-stage → 1.0.2

package/src/tools/device.js

@@ -0,0 +1,138 @@
+// tools/device.js
+
+/**
+ * Device detection and responsive utilities.
+ *
+ * Uses `navigator.userAgent` and window geometry — not media queries — so results
+ * are synchronous and available before the DOM is ready. All methods are pure reads
+ * and never mutate global state; the listener helpers return cleanup functions so
+ * callers can unsubscribe easily.
+ *
+ * @namespace device
+ */
+export const device = {
+  /**
+   * Detect whether the current device is a mobile phone.
+   *
+   * Matches common mobile UA strings including Android phones, iOS devices,
+   * BlackBerry, Windows Phone (IEMobile), and Opera Mini.
+   *
+   * @returns {boolean} `true` if the UA string looks like a mobile phone
+   */
+  isMobile: () => {
+    return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(
+      navigator.userAgent,
+    );
+  },
+
+  /**
+   * Detect whether the current device is a tablet.
+   *
+   * Identifies iPads and Android tablets (Android UA without "Mobile" in the string).
+   *
+   * @returns {boolean} `true` if the UA string looks like a tablet
+   */
+  isTablet: () => {
+    return /iPad|Android(?!.*Mobile)/i.test(navigator.userAgent);
+  },
+
+  /**
+   * Detect whether the current device is a desktop/laptop.
+   *
+   * Returns `true` when neither `isMobile()` nor `isTablet()` match —
+   * i.e. the catch-all for any device that is not a phone or tablet.
+   *
+   * @returns {boolean} `true` if the device is not mobile and not a tablet
+   */
+  isDesktop: () => {
+    return !device.isMobile() && !device.isTablet();
+  },
+
+  /**
+   * Get the current screen orientation.
+   *
+   * Compares `window.innerHeight` vs `window.innerWidth` rather than relying on
+   * `screen.orientation`, which is less widely supported and may be locked by the OS.
+   *
+   * @returns {"portrait"|"landscape"} Current orientation string
+   */
+  orientation: () => {
+    return window.innerHeight > window.innerWidth ? "portrait" : "landscape";
+  },
+
+  /**
+   * Detect whether the device supports touch input.
+   *
+   * Checks both the `ontouchstart` event property and the `maxTouchPoints` API,
+   * so it works across older and newer browsers consistently.
+   *
+   * @returns {boolean} `true` if the device supports touch events
+   */
+  isTouch: () => {
+    return "ontouchstart" in window || navigator.maxTouchPoints > 0;
+  },
+
+  /**
+   * Detect whether the device supports multi-touch gestures (e.g. pinch-to-zoom).
+   *
+   * The `gesturestart` event is a non-standard WebKit extension primarily present
+   * on iOS Safari. Use this to conditionally enable gesture-based interactions.
+   *
+   * @returns {boolean} `true` if gesture events are supported
+   */
+  hasGesture: () => {
+    return "ongesturestart" in window;
+  },
+
+  /**
+   * Subscribe to device orientation changes.
+   *
+   * Fires `callback` with the new orientation string (`"portrait"` or `"landscape"`)
+   * whenever the device is rotated. Returns a cleanup function — call it to remove
+   * the listener and avoid memory leaks.
+   *
+   * @param {function(orientation: "portrait"|"landscape"): void} callback - Called on each orientation change
+   * @returns {function(): void} Cleanup function that removes the event listener
+   *
+   * @example
+   * const unsub = device.onOrientationChange((o) => console.log('Now:', o));
+   * // Later, when the component unmounts:
+   * unsub();
+   */
+  onOrientationChange: (callback) => {
+    const handler = () => callback(device.orientation());
+    window.addEventListener("orientationchange", handler);
+    return () => window.removeEventListener("orientationchange", handler);
+  },
+
+  /**
+   * Subscribe to window resize events.
+   *
+   * Fires `callback` with the updated viewport dimensions and orientation on every
+   * resize. Returns a cleanup function to unsubscribe. Prefer this over reading
+   * `window.innerWidth` inline to avoid layout thrashing in tight loops.
+   *
+   * @param {function({ width: number, height: number, orientation: "portrait"|"landscape" }): void} callback
+   *   Called with the new dimensions and orientation on each resize event
+   * @returns {function(): void} Cleanup function that removes the event listener
+   *
+   * @example
+   * const unsub = device.onResize(({ width, height, orientation }) => {
+   *   console.log(`Viewport: ${width}×${height} (${orientation})`);
+   * });
+   * // Later:
+   * unsub();
+   */
+  onResize: (callback) => {
+    const handler = () =>
+      callback({
+        width: window.innerWidth,
+        height: window.innerHeight,
+        orientation: device.orientation(),
+      });
+    window.addEventListener("resize", handler);
+    return () => window.removeEventListener("resize", handler);
+  },
+};
+
+export default device;

package/src/tools/dict.js

@@ -0,0 +1,297 @@
+// src/tools/dict.js
+// Python-like dictionary utilities
+
+/**
+ * A wrapper around a plain JavaScript object that exposes a Python-inspired
+ * dictionary API (`.get()`, `.keys()`, `.values()`, `.items()`, etc.).
+ */
+export class Dict {
+  /**
+   * @param {Object} [obj={}] - Initial key-value pairs.
+   */
+  constructor(obj = {}) {
+    this._data = { ...obj };
+  }
+
+  /**
+   * Returns the value for `key`, or `defaultValue` if the key is absent.
+   * Mirrors Python's `dict.get(key, default)`.
+   *
+   * @param {string} key - Key to look up.
+   * @param {*} [defaultValue=null] - Fallback value when the key is missing.
+   * @returns {*} The stored value or `defaultValue`.
+   */
+  get(key, defaultValue = null) {
+    return this._data[key] !== undefined ? this._data[key] : defaultValue;
+  }
+
+  /**
+   * Sets a key to a value and returns `this` for chaining.
+   * Mirrors Python's assignment `d[key] = value`.
+   *
+   * @param {string} key - Key to set.
+   * @param {*} value - Value to store.
+   * @returns {Dict} This instance.
+   */
+  set(key, value) {
+    this._data[key] = value;
+    return this;
+  }
+
+  /**
+   * Returns `true` if `key` exists in the dictionary.
+   * Mirrors Python's `key in d`.
+   *
+   * @param {string} key - Key to check.
+   * @returns {boolean}
+   */
+  has(key) {
+    return key in this._data;
+  }
+
+  /**
+   * Returns an array of all keys in the dictionary.
+   * Mirrors Python's `dict.keys()`.
+   *
+   * @returns {string[]}
+   */
+  keys() {
+    return Object.keys(this._data);
+  }
+
+  /**
+   * Returns an array of all values in the dictionary.
+   * Mirrors Python's `dict.values()`.
+   *
+   * @returns {*[]}
+   */
+  values() {
+    return Object.values(this._data);
+  }
+
+  /**
+   * Returns an array of `[key, value]` pairs.
+   * Mirrors Python's `dict.items()`.
+   *
+   * @returns {Array<[string, *]>}
+   */
+  items() {
+    return Object.entries(this._data);
+  }
+
+  /**
+   * Deletes a key from the dictionary and returns `this` for chaining.
+   * Mirrors Python's `del d[key]`.
+   *
+   * @param {string} key - Key to remove.
+   * @returns {Dict} This instance.
+   */
+  delete(key) {
+    delete this._data[key];
+    return this;
+  }
+
+  /**
+   * The number of entries in the dictionary.
+   * Mirrors Python's `len(d)`.
+   *
+   * @type {number}
+   */
+  get size() {
+    return Object.keys(this._data).length;
+  }
+
+  /**
+   * Removes all entries and returns `this` for chaining.
+   * Mirrors Python's `dict.clear()`.
+   *
+   * @returns {Dict} This instance.
+   */
+  clear() {
+    this._data = {};
+    return this;
+  }
+
+  /**
+   * Returns a shallow copy of this dictionary as a new `Dict` instance.
+   * Mirrors Python's `dict.copy()`.
+   *
+   * @returns {Dict} A new `Dict` with the same entries.
+   */
+  copy() {
+    return new Dict({ ...this._data });
+  }
+
+  /**
+   * Merges another object or `Dict` into this dictionary, overwriting existing keys.
+   * Mirrors Python's `dict.update(other)`.
+   *
+   * @param {Object|Dict} other - Source of additional key-value pairs.
+   * @returns {Dict} This instance.
+   */
+  update(other) {
+    Object.assign(this._data, other instanceof Dict ? other._data : other);
+    return this;
+  }
+
+  /**
+   * Returns the internal data as a plain JavaScript object.
+   *
+   * @returns {Object}
+   */
+  toObject() {
+    return { ...this._data };
+  }
+
+  /**
+   * Serializes the dictionary to a JSON string.
+   *
+   * @returns {string}
+   */
+  toJSON() {
+    return JSON.stringify(this._data);
+  }
+
+  /**
+   * Returns a debug-friendly string representation.
+   * Mirrors Python's `__str__`.
+   *
+   * @returns {string} e.g. `Dict({"key":"value"})`
+   */
+  toString() {
+    return `Dict(${JSON.stringify(this._data)})`;
+  }
+
+  /**
+   * Reads a nested value using dot-notation path, returning `defaultValue` if any
+   * segment along the path is absent.
+   *
+   * @param {string} path - Dot-separated key path, e.g. `"user.address.city"`.
+   * @param {*} [defaultValue=null] - Fallback when the path does not exist.
+   * @returns {*} The nested value or `defaultValue`.
+   *
+   * @example
+   * dict.getNested("user.address.city", "Unknown")
+   */
+  getNested(path, defaultValue = null) {
+    const keys = path.split(".");
+    let result = this._data;
+    for (const key of keys) {
+      if (result?.[key] === undefined) return defaultValue;
+      result = result[key];
+    }
+    return result;
+  }
+
+  /**
+   * Sets a nested value at the given dot-notation path, creating intermediate
+   * objects as needed. Returns `this` for chaining.
+   *
+   * @param {string} path - Dot-separated key path, e.g. `"user.address.city"`.
+   * @param {*} value - Value to set at the path.
+   * @returns {Dict} This instance.
+   *
+   * @example
+   * dict.setNested("user.address.city", "New York")
+   */
+  setNested(path, value) {
+    const keys = path.split(".");
+    const lastKey = keys.pop();
+    let target = this._data;
+    for (const key of keys) {
+      if (target[key] === undefined) target[key] = {};
+      target = target[key];
+    }
+    target[lastKey] = value;
+    return this;
+  }
+
+  /**
+   * Iterates over all entries, calling `callback(value, key)` for each.
+   *
+   * @param {Function} callback - Called with `(value, key)` for each entry.
+   * @returns {void}
+   */
+  forEach(callback) {
+    Object.entries(this._data).forEach(([key, value]) => callback(value, key));
+  }
+
+  /**
+   * Maps over all entries and returns an array of the results.
+   *
+   * @param {Function} callback - Called with `(value, key)` for each entry; return the mapped value.
+   * @returns {Array<*>}
+   */
+  map(callback) {
+    return Object.entries(this._data).map(([key, value]) =>
+      callback(value, key),
+    );
+  }
+
+  /**
+   * Returns a new `Dict` containing only entries for which `callback` returns truthy.
+   *
+   * @param {Function} callback - Predicate called with `(value, key)`.
+   * @returns {Dict} Filtered dictionary.
+   */
+  filter(callback) {
+    const result = {};
+    Object.entries(this._data).forEach(([key, value]) => {
+      if (callback(value, key)) result[key] = value;
+    });
+    return new Dict(result);
+  }
+}
+
+/**
+ * Factory function — creates a new `Dict` instance from a plain object.
+ * Mirrors Python's `dict()` constructor.
+ *
+ * @param {Object} [obj={}] - Initial key-value pairs.
+ * @returns {Dict}
+ *
+ * @example
+ * const d = dict({ name: "Alice", age: 30 });
+ * d.get("name"); // "Alice"
+ */
+export const dict = (obj = {}) => {
+  return new Dict(obj);
+};
+
+/**
+ * Creates and returns an empty `Dict`.
+ *
+ * @returns {Dict}
+ */
+export const emptyDict = () => new Dict({});
+
+/**
+ * Parses a JSON string and wraps the result in a `Dict`.
+ * Returns an empty `Dict` on parse failure.
+ *
+ * @param {string} jsonStr - JSON-encoded object string.
+ * @returns {Dict}
+ */
+export const fromJSON = (jsonStr) => {
+  try {
+    return new Dict(JSON.parse(jsonStr));
+  } catch {
+    return new Dict({});
+  }
+};
+
+/**
+ * Creates a `Dict` from an array of `[key, value]` pairs.
+ * Mirrors Python's `dict([(key, value), ...])`.
+ *
+ * @param {Array<[string, *]>} entries - Array of key-value pairs.
+ * @returns {Dict}
+ *
+ * @example
+ * fromEntries([["a", 1], ["b", 2]]) // Dict { a: 1, b: 2 }
+ */
+export const fromEntries = (entries) => {
+  return new Dict(Object.fromEntries(entries));
+};
+
+export default dict;

package/src/tools/dimensions.js

@@ -0,0 +1,118 @@
+// src/modules/FletBox/core/dimensions.js
+
+/**
+ * Dimensions - Provides the current window dimensions and a resize listener API.
+ * Similar in spirit to React Native's `Dimensions` module.
+ *
+ * @example
+ * import { width, height } from './core/dimensions.js';
+ * console.log(`Screen: ${width} x ${height}`);
+ *
+ * @example
+ * import { dimensions } from './core/dimensions.js';
+ * const remove = dimensions.addListener(({ width, height }) => {
+ *   console.log(`Window resized: ${width} x ${height}`);
+ * });
+ * // Call remove() to stop listening.
+ */
+
+let windowWidth = window.innerWidth;
+let windowHeight = window.innerHeight;
+
+// Live named exports — is-module live bindings: importers of { width, height }
+// always read the current value, kept in sync on resize.
+export let width = windowWidth;
+export let height = windowHeight;
+
+// Internal list of resize listener callbacks
+const listeners = [];
+
+/**
+ * Internal resize handler. Syncs the cached dimensions and notifies all
+ * registered listeners whenever the browser window is resized.
+ *
+ * @returns {void}
+ */
+const handleResize = () => {
+  windowWidth = window.innerWidth;
+  windowHeight = window.innerHeight;
+  width = windowWidth;
+  height = windowHeight;
+
+  // Notify all registered listeners with the updated dimensions
+  listeners.forEach((listener) => {
+    listener({ width: windowWidth, height: windowHeight });
+  });
+};
+
+window.addEventListener("resize", handleResize);
+
+/**
+ * Dimensions object — provides getter properties and listener management.
+ * Prefer the named `width` / `height` exports for simple reads; use this
+ * object when you need the full API.
+ */
+export const dimensions = {
+  /** Current window width in pixels. @type {number} */
+  get width() {
+    return windowWidth;
+  },
+
+  /** Current window height in pixels. @type {number} */
+  get height() {
+    return windowHeight;
+  },
+
+  /**
+   * Returns the current window dimensions as an object.
+   *
+   * @returns {{ width: number, height: number }}
+   */
+  get: () => ({ width: windowWidth, height: windowHeight }),
+
+  /**
+   * Returns the current window width in pixels.
+   *
+   * @returns {number}
+   */
+  getWidth: () => windowWidth,
+
+  /**
+   * Returns the current window height in pixels.
+   *
+   * @returns {number}
+   */
+  getHeight: () => windowHeight,
+
+  /**
+   * Registers a callback that is called whenever the window is resized.
+   *
+   * @param {Function} callback - Receives `{ width: number, height: number }` on each resize.
+   * @returns {Function} A cleanup function that removes this listener when called.
+   *
+   * @example
+   * const remove = dimensions.addListener(({ width }) => console.log(width));
+   * // Later:
+   * remove();
+   */
+  addListener: (callback) => {
+    listeners.push(callback);
+    return () => {
+      const index = listeners.indexOf(callback);
+      if (index > -1) listeners.splice(index, 1);
+    };
+  },
+
+  /**
+   * Removes a previously registered resize listener.
+   *
+   * @param {Function} callback - The same function reference passed to `addListener`.
+   * @returns {void}
+   */
+  removeListener: (callback) => {
+    const index = listeners.indexOf(callback);
+    if (index > -1) listeners.splice(index, 1);
+  },
+};
+
+export default dimensions;

package/src/tools/filter.js

@@ -0,0 +1,41 @@
+// tools/filter.js
+
+/**
+ * Generate CSS filter string
+ * @param {Object} options - Filter options
+ * @returns {string} CSS filter value
+ *
+ * @example
+ * filter({ blur: 5, brightness: 0.8, contrast: 1.2 })
+ * // "blur(5px) brightness(0.8) contrast(1.2)"
+ *
+ * @example
+ * filter({ grayscale: 1, sepia: 0.5, hueRotate: 90 })
+ * // "grayscale(1) sepia(0.5) hue-rotate(90deg)"
+ */
+export const filter = (options = {}) => {
+  const parts = [];
+
+  if (options.blur)
+    parts.push(
+      `blur(${typeof options.blur === "number" ? options.blur + "px" : options.blur})`,
+    );
+  if (options.brightness) parts.push(`brightness(${options.brightness})`);
+  if (options.contrast) parts.push(`contrast(${options.contrast})`);
+  if (options.dropShadow) {
+    const [x, y, blur, color] = options.dropShadow;
+    parts.push(`drop-shadow(${x}px ${y}px ${blur}px ${color})`);
+  }
+  if (options.grayscale) parts.push(`grayscale(${options.grayscale})`);
+  if (options.hueRotate) parts.push(`hue-rotate(${options.hueRotate}deg)`);
+  if (options.invert) parts.push(`invert(${options.invert})`);
+  if (options.opacity) parts.push(`opacity(${options.opacity})`);
+  if (options.saturate) parts.push(`saturate(${options.saturate})`);
+  if (options.sepia) parts.push(`sepia(${options.sepia})`);
+  if (options.backdrop)
+    parts.push(`backdrop-filter(${filter(options.backdrop)})`);
+
+  return parts.join(" ");
+};
+
+export default filter;

package/src/tools/flex.js

@@ -0,0 +1,26 @@
+// tools/flex.js
+
+/**
+ * Generate CSS flex string (shorthand)
+ * @param {number|Object} grow - Flex grow value or options object
+ * @param {number} shrink - Flex shrink value
+ * @param {string} basis - Flex basis value
+ * @returns {string} CSS flex value
+ *
+ * @example
+ * flex(1)                    // "1 1 0%"
+ * flex(1, 0, 'auto')        // "1 0 auto"
+ * flex({ grow: 1, shrink: 0, basis: '200px' })
+ * // "1 0 200px"
+ */
+export const flex = (grow, shrink = 1, basis = "0%") => {
+  if (typeof grow === "object") {
+    const g = grow.grow ?? 1;
+    const s = grow.shrink ?? 1;
+    const b = grow.basis ?? "0%";
+    return `${g} ${s} ${b}`;
+  }
+  return `${grow} ${shrink} ${basis}`;
+};
+
+export default flex;

package/src/tools/gradient.js

@@ -0,0 +1,34 @@
+/**
+ * Generate a CSS gradient string.
+ *
+ * Supports linear, radial (circle), and conic gradient types.
+ * Use the returned string as a CSS `background` value on any element.
+ *
+ * @param {"linear"|"circle"|"conic"} type - Gradient type:
+ *   - `"linear"` → `linear-gradient(angleDeg, ...stops)`
+ *   - `"circle"` → `radial-gradient(circle, ...stops)`
+ *   - `"conic"`  → `conic-gradient(from angleDeg, ...stops)`
+ * @param {string[]} colors - Array of color stop values (any valid CSS color)
+ * @param {number} [angle=135] - Angle in degrees (used for linear and conic gradients)
+ * @returns {string} CSS gradient value
+ *
+ * @example
+ * // Use in a Container's background prop:
+ * gradient('linear', ['red', 'blue'])
+ * // "linear-gradient(135deg, red, blue)"
+ *
+ * gradient('circle', ['white', 'black'])
+ * // "radial-gradient(circle, white, black)"
+ *
+ * gradient('conic', ['red', 'yellow', 'blue'])
+ * // "conic-gradient(from 135deg, red, yellow, blue)"
+ */
+
+const gradient = (type, colors, angle = 135) => {
+  const stops = colors.join(", ");
+  if (type === "linear") return `linear-gradient(${angle}deg, ${stops})`;
+  if (type === "circle") return `radial-gradient(circle, ${stops})`;
+  return `conic-gradient(from ${angle}deg, ${stops})`;
+};
+
+export default gradient;

package/src/tools/grid.js

@@ -0,0 +1,57 @@
+// tools/grid.js
+
+/**
+ * Generate CSS grid template string
+ * @param {Object} options - Grid options
+ * @returns {string} CSS grid value
+ *
+ * @example
+ * grid({ columns: 3, gap: 16 })
+ * // "repeat(3, 1fr) / auto"
+ *
+ * @example
+ * grid({ columns: '200px 1fr', rows: 'auto 100px', gap: { row: 16, column: 8 } })
+ * // "200px 1fr / auto 100px"
+ */
+export const grid = (options = {}) => {
+  let columns = "";
+  let rows = "";
+
+  // Handle columns
+  if (options.columns) {
+    if (typeof options.columns === "number") {
+      columns = `repeat(${options.columns}, 1fr)`;
+    } else {
+      columns = options.columns;
+    }
+  } else {
+    columns = "1fr";
+  }
+
+  // Handle rows
+  if (options.rows) {
+    if (typeof options.rows === "number") {
+      rows = `repeat(${options.rows}, auto)`;
+    } else {
+      rows = options.rows;
+    }
+  } else {
+    rows = "auto";
+  }
+
+  // Handle gap
+  let gap = "";
+  if (options.gap) {
+    if (typeof options.gap === "number") {
+      gap = ` ${options.gap}px`;
+    } else if (typeof options.gap === "object") {
+      gap = ` ${options.gap.row || 0}px ${options.gap.column || 0}px`;
+    } else {
+      gap = ` ${options.gap}`;
+    }
+  }
+
+  return `${columns} / ${rows}${gap}`;
+};
+
+export default grid;