flet-box 0.0.0-stage → 1.0.2

package/src/widget-factory/reactivity.js

@@ -0,0 +1,98 @@
+// core/reactivity.js
+import { REACTIVE_PROPS } from "./translateProps.js";
+
+/**
+ * Tags where `width` and `height` are native IDL attributes with their own
+ * semantics (intrinsic size, aspect-ratio, etc.). Overriding them with a custom
+ * `defineProperty` accessor would break that native behaviour, so these props
+ * are NOT shadowed on these tags.
+ *
+ * @type {Set<string>}
+ */
+const REPLACED_ELEMENT_TAGS = new Set([
+  "img",
+  "canvas",
+  "video",
+  "iframe",
+  "embed",
+  "object",
+  "source",
+]);
+
+/**
+ * Props that must NEVER be shadowed with a custom accessor because the browser
+ * maintains live, user-controlled state for them. For example, shadowing `value`
+ * on an `<input>` would disconnect `widget.value` from what the user is actually
+ * typing.
+ *
+ * @type {Set<string>}
+ */
+const NEVER_SHADOW = new Set(["value"]);
+
+/**
+ * Installs reactive property accessors on a widget for every prop in
+ * `REACTIVE_PROPS`, excluding those guarded by `NEVER_SHADOW` and those that
+ * conflict with native IDL attributes on replaced elements.
+ *
+ * Each accessor follows this contract:
+ * - **getter** – returns the prop's current value from `_originalProps`.
+ * - **setter** – writes the new value to `_originalProps` and calls `updateFn`
+ *   with a partial change object `{ [prop]: newValue }` only when the value
+ *   actually changed (strict equality check prevents redundant updates).
+ *
+ * Additionally, for `<input>`, `<textarea>`, and `<select>` elements, syncs the
+ * DOM's own `value` back into `_originalProps` on every `input` and `change`
+ * event so that the stored props always reflect the live field content.
+ *
+ * @param {HTMLElement} widget - The widget to make reactive.
+ * @param {function(Object): void} updateFn - Callback invoked with the changed
+ *   partial props whenever a reactive prop is set. Typically calls
+ *   `widget.update(changedProps)`.
+ * @returns {HTMLElement} The same widget (for chaining).
+ */
+export const makeReactive = (widget, updateFn) => {
+  const tag = widget.tagName ? widget.tagName.toLowerCase() : "";
+
+  REACTIVE_PROPS.forEach((prop) => {
+    if (NEVER_SHADOW.has(prop)) return;
+
+    if (
+      (prop === "width" || prop === "height") &&
+      REPLACED_ELEMENT_TAGS.has(tag)
+    ) {
+      return;
+    }
+
+    Object.defineProperty(widget, prop, {
+      get() {
+        return widget._originalProps ? widget._originalProps[prop] : undefined;
+      },
+      set(newValue) {
+        if (!widget._originalProps) return;
+        const current = widget._originalProps[prop];
+        if (current === newValue) return;
+
+        widget._originalProps[prop] = newValue;
+        updateFn({ [prop]: newValue });
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  });
+
+  // For form elements, keep _originalProps in sync with the live DOM value so
+  // that getProps() always returns what the user has typed.
+  if (tag === "input" || tag === "textarea" || tag === "select") {
+    const syncValueFromDOM = () => {
+      if (widget._originalProps) {
+        widget._originalProps.value = widget.value;
+      }
+    };
+    widget.addEventListener("input", syncValueFromDOM);
+    widget.addEventListener("change", syncValueFromDOM);
+  }
+
+  return widget;
+};
+
+export default { makeReactive, REACTIVE_PROPS };

package/src/widget-factory/remTool.js

@@ -0,0 +1,34 @@
+/**
+ * REM TOOL - Only converts numbers to REM
+ */
+
+/**
+ * Converts a number to REM
+ * @param {number} value - Number to convert
+ * @param {number} baseFontSize - Base root font size (default: 16)
+ * @returns {string} - Value in REM
+ */
+export const toREM = (value, baseFontSize = 16) => {
+  if (typeof value !== "number") return value;
+  return `${value / baseFontSize}rem`;
+};
+
+/**
+ * Applies REM to a styles object
+ * @param {Object} styles - Styles with numbers
+ * @param {number} baseFontSize - Base root font size (default: 16)
+ * @returns {Object} - Styles with REM
+ */
+export const applyREM = (styles, baseFontSize = 16) => {
+  const result = {};
+
+  for (const [key, value] of Object.entries(styles)) {
+    if (typeof value === "number") {
+      result[key] = toREM(value, baseFontSize);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+};

package/src/widget-factory/stackPosition.js

@@ -0,0 +1,87 @@
+// core/stackPosition.js
+import { toREM } from "./remTool.js";
+
+/**
+ * Applies positioning for Stack layout
+ * @param {HTMLElement} widget - The widget to position
+ * @param {Object} props - Widget props
+ * @returns {HTMLElement} The widget with position applied
+ *
+ * @example
+ * stackPosition(element, { position: 'stack', top: 10, left: 20 })
+ * // → element.style.position = 'absolute'
+ * // → element.style.top = '0.625rem'
+ * // → element.style.left = '1.25rem'
+ */
+export const stackPosition = (widget, props) => {
+  // Numeric offsets follow the framework-wide rule: numbers are pixels on a
+  // 16px base, emitted as rem so they scale with the root font size.
+  const offset = (value) => (typeof value === "number" ? toREM(value) : value);
+
+  // Only apply if position is 'stack'
+  if (props.position !== "stack") {
+    return widget;
+  }
+
+  // Absolute positioning
+  widget.style.position = "absolute";
+
+  // Process each position prop
+  for (const [key, value] of Object.entries(props)) {
+    if (key === "position") continue;
+
+    switch (key) {
+      case "top":
+        widget.style.top = offset(value);
+        break;
+      case "right":
+        widget.style.right = offset(value);
+        break;
+      case "bottom":
+        widget.style.bottom = offset(value);
+        break;
+      case "left":
+        widget.style.left = offset(value);
+        break;
+      case "start":
+        widget.style.left = offset(value);
+        break;
+      case "end":
+        widget.style.right = offset(value);
+        break;
+      case "centerX":
+        widget.style.left = "50%";
+        widget.style.transform = "translateX(-50%)";
+        break;
+      case "centerY":
+        widget.style.top = "50%";
+        widget.style.transform = "translateY(-50%)";
+        break;
+      case "center":
+        widget.style.top = "50%";
+        widget.style.left = "50%";
+        widget.style.transform = "translate(-50%, -50%)";
+        break;
+      case "fullWidth":
+        widget.style.width = "100%";
+        widget.style.left = "0";
+        widget.style.right = "0";
+        break;
+      case "fullHeight":
+        widget.style.height = "100%";
+        widget.style.top = "0";
+        widget.style.bottom = "0";
+        break;
+      case "full":
+        widget.style.width = "100%";
+        widget.style.height = "100%";
+        widget.style.top = "0";
+        widget.style.left = "0";
+        break;
+    }
+  }
+
+  return widget;
+};
+
+export default stackPosition;

package/src/widget-factory/stringTool.js

@@ -0,0 +1,26 @@
+/**
+ * STRING TOOL - Only keeps props that are strings
+ */
+
+/**
+ * Filters and keeps only string values
+ * @param {Object} styles - Styles object
+ * @returns {Object} - Only string props
+ *
+ * @example
+ * keepStrings({ padding: 16, color: 'red', display: 'flex', zIndex: 10 })
+ * // → { color: 'red', display: 'flex' }
+ */
+export const keepStrings = (styles) => {
+  const result = {};
+
+  for (const [key, value] of Object.entries(styles)) {
+    if (typeof value === "string") {
+      result[key] = value;
+    }
+  }
+
+  return result;
+};
+
+export default keepStrings;

package/src/widget-factory/tools.js

@@ -0,0 +1,249 @@
+// ============================================================
+// 📋 READ: Get styles
+// ============================================================
+
+/**
+ * Reads one or all inline styles from a DOM element.
+ *
+ * @param {HTMLElement|null} el - The target element.
+ * @param {string} [prop] - CSS property name. When provided, returns only that
+ *   property's value (or `null` when absent). When omitted, returns an object
+ *   containing every non-empty inline style.
+ * @returns {string|Object|null} The property value, a styles object, or `null`
+ *   when `el` is falsy or the property is not set.
+ */
+export function getStyles(el, prop) {
+  if (!el) return null;
+  if (prop) return el.style[prop] || null;
+
+  const styles = {};
+  for (let i = 0; i < el.style.length; i++) {
+    const p = el.style[i];
+    const v = el.style[p];
+    if (v !== "") styles[p] = v;
+  }
+  return styles;
+}
+
+// ============================================================
+// ➕ CREATE / UPDATE: Assign styles
+// ============================================================
+
+/**
+ * Converts a raw prop value to a CSS-ready string or number.
+ *
+ * Conversion rules:
+ * - **Array** → space-separated string (e.g. `[12, 24]` → `"12px 24px"`).
+ * - **Number** on a unitless prop (flex, zIndex, opacity, etc.) → returned
+ *   as-is without a suffix.
+ * - **Number** on any other prop → suffixed with `"px"`.
+ * - **String** → returned unchanged.
+ * - `undefined` / `null` → returned as `null` (caller should skip assignment).
+ *
+ * @param {string} key - The CSS property name (camelCase).
+ * @param {*} value - The raw value to convert.
+ * @returns {string|number|null} The CSS-ready value, or `null` to skip.
+ */
+const toCSSValue = (key, value) => {
+  if (value === undefined || value === null) return null;
+
+  // Array → "12px 24px"
+  if (Array.isArray(value)) {
+    return value.map((v) => (typeof v === "number" ? `${v}px` : v)).join(" ");
+  }
+
+  // Number → apply unit or no unit
+  if (typeof value === "number") {
+    // Props that must NOT receive a unit suffix
+    const noUnitProps = new Set([
+      "flex",
+      "flexGrow",
+      "flexShrink",
+      "order",
+      "zIndex",
+      "opacity",
+      "fontWeight",
+      "lineHeight",
+      "scale",
+      "rotate",
+      "rotateX",
+      "rotateY",
+      "rotateZ",
+    ]);
+
+    if (noUnitProps.has(key)) {
+      return value; // No unit
+    }
+    return `${value}px`; // Add px
+  }
+
+  // String → keep as is
+  return value;
+};
+
+/**
+ * Applies one or more styles to a DOM element.
+ *
+ * Supports two call signatures:
+ * 1. `setStyles(el, propName, value)` – sets a single CSS property.
+ * 2. `setStyles(el, stylesObject)` – applies every key/value pair in the object.
+ *
+ * Values are converted via `toCSSValue` before assignment. Invalid CSS
+ * assignments (e.g. read-only properties) are silently ignored.
+ *
+ * @param {HTMLElement} el - The target element.
+ * @param {string|Object} prop - CSS property name (camelCase) or an object of
+ *   property–value pairs.
+ * @param {*} [value] - The value to assign. Required when `prop` is a string.
+ * @returns {HTMLElement} The element (for chaining).
+ */
+export function setStyles(el, prop, value) {
+  // Validateste element
+  if (!el || !el.style) return el;
+
+  // Case 1: string (prop + value)
+  if (typeof prop === "string") {
+    const cssValue = toCSSValue(prop, value);
+    if (cssValue !== null) {
+      try {
+        el.style[prop] = cssValue;
+      } catch (e) {
+        // Silently ignore errors
+      }
+    }
+    return el;
+  }
+
+  // Case 2: styles object
+  if (typeof prop === "object" && prop !== null) {
+    for (const [key, val] of Object.entries(prop)) {
+      const cssValue = toCSSValue(key, val);
+      if (cssValue !== null) {
+        try {
+          el.style[key] = cssValue;
+        } catch (e) {
+          // Silently ignore errors
+        }
+      }
+    }
+  }
+
+  return el;
+}
+
+// ============================================================
+// 🔄 TOGGLE: Toggle styles
+// ============================================================
+
+/**
+ * Toggles a CSS property between two values.
+ *
+ * If the property currently equals `val1` it is set to `val2`, and vice versa.
+ * Useful for toggling visibility, themes, or active states without external
+ * boolean tracking.
+ *
+ * @param {HTMLElement} el - The target element.
+ * @param {string} prop - CSS property name (camelCase).
+ * @param {*} val1 - First value (the one to switch away from when current).
+ * @param {*} val2 - Second value (the one to switch away from when current).
+ * @returns {HTMLElement} The element (for chaining).
+ */
+export function updateStyle(el, prop, val1, val2) {
+  if (!el || !prop) return el;
+
+  const current = el.style[prop] || "";
+  const newValue = current === val1 ? val2 : val1;
+  const cssValue = toCSSValue(prop, newValue);
+
+  if (cssValue !== null) {
+    try {
+      el.style[prop] = cssValue;
+    } catch (e) {
+      // Silently ignore errors
+    }
+  }
+
+  return el;
+}
+
+// ============================================================
+// 🗑️ DELETE: Remove styles
+// ============================================================
+
+/**
+ * Removes one or more inline styles from a DOM element by setting them to an
+ * empty string (which causes the browser to fall back to inherited / default
+ * values).
+ *
+ * - `string` → removes that single property.
+ * - `Array<string>` → removes every listed property.
+ * - `undefined` → removes ALL currently set inline styles.
+ *
+ * @param {HTMLElement} el - The target element.
+ * @param {string|string[]|undefined} [prop] - Property or properties to remove.
+ *   Omit to remove all inline styles.
+ * @returns {HTMLElement} The element (for chaining).
+ */
+export function removeStyles(el, prop) {
+  if (!el) return el;
+
+  if (typeof prop === "string") {
+    try {
+      el.style[prop] = "";
+    } catch (e) {}
+  } else if (Array.isArray(prop)) {
+    prop.forEach((p) => {
+      try {
+        el.style[p] = "";
+      } catch (e) {}
+    });
+  } else if (prop === undefined) {
+    const styles = getStyles(el);
+    Object.keys(styles).forEach((p) => {
+      try {
+        el.style[p] = "";
+      } catch (e) {}
+    });
+  }
+  return el;
+}
+
+// ============================================================
+// 🔍 UTILITY: Check styles
+// ============================================================
+
+/**
+ * Checks whether a specific inline style is set on an element.
+ *
+ * @param {HTMLElement|null} el - The target element.
+ * @param {string} prop - CSS property name (camelCase).
+ * @returns {boolean} `true` if the property has a non-empty inline value.
+ */
+export function hasStyle(el, prop) {
+  if (!el || !prop) return false;
+  return el.style[prop] !== "";
+}
+
+/**
+ * Logs all inline styles of an element to the console in a readable format.
+ * Useful for debugging style issues during development.
+ *
+ * @param {HTMLElement|null} el - The target element.
+ * @param {string} [label="Styles"] - Label prefix shown in the console output.
+ * @returns {Object|null} The styles object (same as `getStyles(el)`), or `null`
+ *   when `el` is falsy.
+ */
+export function logStyles(el, label = "Styles") {
+  if (!el) {
+    console.warn("⚠️ Invalid element");
+    return null;
+  }
+  const styles = getStyles(el);
+  console.log(`📋 ${label}:`);
+  if (Object.keys(styles).length === 0) {
+    console.log("  (No inline styles)");
+  } else {
+    Object.entries(styles).forEach(([p, v]) => console.log(`  ${p}: ${v}`));
+  }
+  return styles;
+}