flet-box 0.0.0-stage → 1.0.2

package/src/widget-factory/effects.js

@@ -0,0 +1,132 @@
+// core/effects.js
+
+/**
+ * Applies interactive visual effects to a widget that has a click handler.
+ *
+ * On every call, previously registered effect listeners are removed before new
+ * ones are attached, so calling `applyEffects` again after an `update` is safe
+ * and idempotent.
+ *
+ * **Base effects (always applied):**
+ * - `-webkit-tap-highlight-color` set to `transparent` to suppress the default
+ *   mobile tap flash.
+ * - `outline` removed for a cleaner focused appearance.
+ *
+ * **Press / hover effects (only when a click handler is present and
+ * `disableTransform !== true`):**
+ * - On press start (`mousedown` / `touchstart`): scales the widget to `0.98`
+ *   and removes the box shadow.
+ * - On press end (`mouseup` / `touchend` / `mouseleave` / `touchcancel`):
+ *   restores the original scale and shadow.
+ * - On hover enter (`mouseenter`): translates the widget up by `0.5px` and
+ *   enhances the box shadow when one was present.
+ * - On hover leave (`mouseleave`): restores the original translate and shadow.
+ * - Sets `cursor: pointer`.
+ *
+ * The `scale` and `translate` CSS properties are modified independently to
+ * avoid overwriting any `transform` set by `stackPosition` or other consumers.
+ *
+ * @param {HTMLElement} widget - The widget to apply effects to. Must have
+ *   `_originalProps` and `_effectListeners` properties (set up by
+ *   `WidgetFactory`).
+ * @returns {HTMLElement} The same widget (for chaining).
+ */
+export const applyEffects = (widget) => {
+  // Remove previously registered effect listeners before re-attaching.
+  if (widget._effectListeners) {
+    widget._effectListeners.forEach(({ event, handler }) => {
+      widget.removeEventListener(event, handler);
+    });
+    widget._effectListeners = [];
+  }
+
+  widget.style.webkitTapHighlightColor = "transparent";
+  widget.style.outline = "none";
+
+  const hasClick = widget.onclick && typeof widget.onclick === "function";
+  if (!hasClick) return widget;
+
+  // Store the current shadow so it can be restored after press / hover effects.
+  widget._originalShadow = widget.style.boxShadow || "";
+
+  const disableTransform = widget._originalProps?.disableTransform === true;
+  const listeners = [];
+
+  if (!disableTransform) {
+    let isPressed = false;
+
+    /**
+     * Handles press-start events (mousedown / touchstart).
+     * Scales the widget down and removes its shadow.
+     */
+    const onStart = () => {
+      if (isPressed) return;
+      isPressed = true;
+      // Use the independent `scale` property to avoid conflicting with stackPosition.
+      widget.style.scale = "0.98";
+      widget.style.boxShadow = "none";
+    };
+
+    /**
+     * Handles press-end events (mouseup / touchend / mouseleave / touchcancel).
+     * Restores scale and shadow without touching `transform`.
+     */
+    const onEnd = () => {
+      if (!isPressed) return;
+      isPressed = false;
+      // Restore scale without touching transform.
+      widget.style.scale = "";
+      widget.style.boxShadow = widget._originalShadow || "";  
+    };
+
+    const pressStart = ["mousedown", "touchstart"];
+    const pressEnd = ["mouseup", "touchend", "mouseleave", "touchcancel"];
+
+    pressStart.forEach((ev) => {
+      widget.addEventListener(ev, onStart, { passive: true });
+      listeners.push({ event: ev, handler: onStart });
+    });
+    pressEnd.forEach((ev) => {
+      widget.addEventListener(ev, onEnd, { passive: true });
+      listeners.push({ event: ev, handler: onEnd });
+    });
+
+    /**
+     * Handles hover-enter (`mouseenter`).
+     * Lifts the widget slightly and enhances its shadow when one is present.
+     * No-ops while the widget is pressed to avoid conflicting with `onStart`.
+     */
+    const onHoverEnter = () => {
+      if (isPressed) return;
+      // Use the independent `translate` property.
+      widget.style.translate = "0 -0.5px";
+      if (widget._originalShadow && widget._originalShadow !== "none") {
+        widget.style.boxShadow = "0 8px 16px rgba(0,0,0,0.2)";
+      }
+    };
+
+    /**
+     * Handles hover-leave (`mouseleave`).
+     * Restores translate and shadow without touching `transform`.
+     * No-ops while the widget is pressed.
+     */
+    const onHoverLeave = () => {
+      if (isPressed) return;
+      // Restore translate without touching transform.
+      widget.style.translate = "";
+      widget.style.boxShadow = widget._originalShadow || "";
+    };
+
+    widget.addEventListener("mouseenter", onHoverEnter, { passive: true });
+    widget.addEventListener("mouseleave", onHoverLeave, { passive: true });
+    listeners.push({ event: "mouseenter", handler: onHoverEnter });
+    listeners.push({ event: "mouseleave", handler: onHoverLeave });
+
+    widget.style.cursor = "pointer";
+  }
+
+  widget._effectListeners = listeners;
+  return widget;
+};
+
+export default applyEffects;

package/src/widget-factory/index.js

@@ -0,0 +1,7 @@
+// core/index.js
+// ============================================================
+// 📦 PUBLIC EXPORTS FOR THE WIDGET FACTORY MODULE
+// ============================================================
+// Re-exports the top-level WidgetFactory so consumers can import from the
+// module root without knowing the internal file structure.
+export { WidgetFactory } from "./widgetFactory.js";

package/src/widget-factory/lifecycle.js

@@ -0,0 +1,210 @@
+/**
+ * @file lifecycle.js
+ * @description
+ * Lifecycle management for widgets via a shared MutationObserver.
+ *
+ * A single global observer watches `document.body` for DOM mutations and
+ * triggers mount / unmount callbacks on all registered widgets. Widgets are
+ * automatically pruned from the registry when they are permanently removed from
+ * the DOM, preventing memory leaks.
+ *
+ * Exported API:
+ * - `addLifecycle(widget)` – attaches lifecycle hooks to a widget.
+ * - `reregister(widget)` – re-adds a previously pruned (never-mounted) widget.
+ * - `_debugRegistrySize()` – internal diagnostic helper (not part of public API).
+ */
+
+const registeredWidgets = new Set();
+let globalObserver = null;
+
+/**
+ * Internal diagnostic hook (not part of the public API).
+ * Allows tests to assert that the registry is pruned correctly and has no leaks.
+ *
+ * @returns {number} Current number of widgets in the lifecycle registry.
+ */
+export const _debugRegistrySize = () => registeredWidgets.size;
+
+/**
+ * Disconnects the global MutationObserver when there are no more widgets to
+ * observe. Called after every registry deletion to avoid idle overhead.
+ *
+ * @returns {void}
+ */
+const stopObserverIfIdle = () => {
+  if (registeredWidgets.size === 0 && globalObserver) {
+    globalObserver.disconnect();
+    globalObserver = null;
+  }
+};
+
+/**
+ * Iterates over all registered widgets and fires mount or unmount callbacks
+ * based on each widget's current connection state.
+ *
+ * Pruning strategy:
+ * - A widget that is disconnected after being mounted is unmarked and its
+ *   unmount callbacks are fired. A `setTimeout(0)` defers the actual registry
+ *   deletion so synchronous reparenting (e.g. drag-and-drop) does not
+ *   accidentally unregister a widget that is immediately re-attached.
+ * - A widget that was created but never mounted and is still disconnected
+ *   (`_orphanScheduled`) is removed from the registry after one tick without
+ *   clearing its handlers, allowing a late `appendChild` to re-mount it via
+ *   `reregister`.
+ *
+ * @returns {void}
+ */
+const checkAllStates = () => {
+  registeredWidgets.forEach((widget) => {
+    const isConnected = document.body.contains(widget);
+    if (isConnected && !widget._mounted) {
+      widget._mounted = true;
+      widget._orphanScheduled = false;
+      widget._mountFns.forEach((fn) => fn(widget));
+    } else if (!isConnected && widget._mounted) {
+      widget._mounted = false;
+      // Fired but NOT drained: a quick reparent (drag & drop) re-attaches the
+      // widget before the prune timeout, and the disposers must still be there
+      // for the next disconnect. Because `_cleanup` drains the same array, a
+      // disposer can run from both paths — they must be idempotent.
+      widget._unmountFns.forEach((fn) => {
+        try {
+          fn(widget);
+        } catch (_) {}
+      });
+
+      // Prune: if the widget is still disconnected after this tick, its lifecycle
+      // is complete. Remove it from the registry to avoid or(n) sweeps and leaks.
+      // The setTimeout lets synchronous reparenting (drag & drop) complete first.
+      setTimeout(() => {
+        if (!document.body.contains(widget)) {
+          registeredWidgets.delete(widget);
+          widget._mountFns = [];
+          widget._unmountFns = [];
+          stopObserverIfIdle();
+        }
+      }, 0);
+    } else if (!isConnected && !widget._mounted && !widget._orphanScheduled) {
+      // Orphan prune: widget was created but never mounted and is still
+      // disconnected. Remove it from the registry without clearing handlers so
+      // that a late appendChild → reregister can still mount it.
+      widget._orphanScheduled = true;
+      setTimeout(() => {
+        widget._orphanScheduled = false;
+        if (!widget._mounted && !document.body.contains(widget)) {
+          registeredWidgets.delete(widget);
+          stopObserverIfIdle();
+        }
+      }, 0);
+    }
+  });
+};
+
+/**
+ * Starts the global MutationObserver if it is not already running.
+ * Observes `document.body` for child-list mutations at any depth.
+ *
+ * @returns {void}
+ */
+const ensureObserver = () => {
+  if (!globalObserver && typeof MutationObserver !== "undefined" && document.body) {
+    globalObserver = new MutationObserver(checkAllStates);
+    globalObserver.observe(document.body, { childList: true, subtree: true });
+  }
+};
+
+/**
+ * Attaches lifecycle hooks to a widget and registers it with the global
+ * MutationObserver.
+ *
+ * After this call the widget exposes:
+ * - `onMount(fn)` – registers a callback fired when the widget is inserted into
+ *   the live DOM.
+ * - `onUnmount(fn)` – registers a callback fired when the widget is removed from
+ *   the live DOM.
+ * - `triggerMount()` – synchronously fires mount callbacks if the widget is
+ *   already connected (useful when called right after `appendChild`). The
+ *   observer will not duplicate the call because `_mounted` is set to `true`.
+ * - `_cleanup()` – removes the widget from the registry and disconnects the
+ *   observer if the registry becomes empty.
+ *
+ * @param {HTMLElement} widget - The widget to attach lifecycle hooks to.
+ * @returns {HTMLElement} The same widget (for chaining).
+ */
+export const addLifecycle = (widget) => {
+  widget._mountFns = [];
+  widget._unmountFns = [];
+  widget._mounted = false;
+
+  widget.onMount = (fn) => typeof fn === "function" && widget._mountFns.push(fn);
+  widget.onUnmount = (fn) => typeof fn === "function" && widget._unmountFns.push(fn);
+
+  /**
+   * Synchronously fires mount callbacks when the widget is already in the DOM.
+   * `runApp` / `insertBy` call this immediately after appending the widget so
+   * consumers get the mount event without waiting for the observer's next tick.
+   * The observer does not duplicate the call because `_mounted` is already `true`.
+   *
+   * @returns {HTMLElement} The widget itself (for chaining).
+   */
+  widget.triggerMount = () => {
+    if (!widget._mounted && document.body.contains(widget)) {
+      widget._mounted = true;
+      widget._mountFns.forEach((fn) => fn(widget));
+    }
+    return widget;
+  };
+
+  ensureObserver();
+  registeredWidgets.add(widget);
+  queueMicrotask(checkAllStates);
+
+  /**
+   * Removes the widget from the lifecycle registry, stops the observer if the
+   * registry becomes empty, and releases the widget's resources.
+   *
+   * Any pending `onUnmount` callbacks are drained (the array is swapped out
+   * *before* running them, so the guard also covers a concurrent global-observer
+   * fire) and executed exactly once. This makes `onUnmount` the single hook that
+   * runs on every teardown path: DOM disconnect (global observer), tree rebuild
+   * (`runApp.teardownTree`) and direct `_cleanup()` calls (Scaffold observer).
+   *
+   * Disposers registered through `onUnmount` MUST be idempotent — they can be
+   * triggered by either path, though never twice in practice thanks to the drain.
+   *
+   * @returns {void}
+   */
+  widget._cleanup = () => {
+    const unmountFns = widget._unmountFns;
+    widget._unmountFns = [];
+    registeredWidgets.delete(widget);
+    stopObserverIfIdle();
+    widget._mountFns = [];
+    unmountFns.forEach((fn) => {
+      try {
+        fn(widget);
+      } catch (_) {}
+    });
+  };
+
+  return widget;
+};
+
+/**
+ * Re-registers a previously pruned (never-mounted) widget into the lifecycle
+ * registry. Intended to be called when a widget that was built before being
+ * appended to the DOM is finally attached via `appendChild`.
+ *
+ * No-ops when the widget is already mounted or already in the registry.
+ *
+ * @param {HTMLElement} widget - The widget to re-register.
+ * @returns {void}
+ */
+export const reregister = (widget) => {
+  if (!widget || widget._mounted) return;
+  if (registeredWidgets.has(widget)) return;
+  widget._orphanScheduled = false;
+  ensureObserver();
+  registeredWidgets.add(widget);
+  queueMicrotask(checkAllStates);
+};

package/src/widget-factory/makeParentable.js

@@ -0,0 +1,89 @@
+// core/makeParentable.js
+import { reregister } from "./lifecycle.js";
+
+/**
+ * Extends a widget with parent–child relationship tracking.
+ *
+ * After this call the widget gains:
+ * - `_children` – live array of direct child nodes (both widget and non-widget).
+ * - `_isWidget` – branding flag used by other modules to identify flet-box widgets.
+ * - `parent` – a managed accessor backed by a private variable. Readable from
+ *   anywhere; written automatically by the overridden `appendChild` and
+ *   `removeChild`.
+ * - `appendChild(child)` – overrides the native method to track `_children`,
+ *   set `child.parent`, and re-register orphaned child widgets with the
+ *   lifecycle system.
+ * - `removeChild(child)` – overrides the native method to splice `_children`
+ *   and clear `child.parent`.
+ * - `getChildren()` – returns a shallow copy of `_children`.
+ *
+ * @param {HTMLElement} widget - The DOM element to extend with parent tracking.
+ * @returns {HTMLElement} The same widget (for chaining).
+ */
+export const makeParentable = (widget) => {
+  let _parent = null;
+  widget._children = [];
+  widget._isWidget = true;  // Branding flag to identify flet-box widgets
+
+  Object.defineProperty(widget, "parent", {
+    get: () => _parent,
+    set: (p) => { _parent = p; },
+    enumerable: true,
+    configurable: true,
+  });
+
+  const originalAppend = widget.appendChild;
+
+  /**
+   * Overrides the native `appendChild` to:
+   * 1. Set `child.parent` when the child is a widget.
+   * 2. Re-register the child with the lifecycle observer if it was previously
+   *    pruned as an orphan (built before being attached to the DOM).
+   * 3. Track the child in `_children` (avoids duplicates).
+   *
+   * @param {Node} child - The node to append.
+   * @returns {Node} The appended child (mirrors native behaviour).
+   */
+  widget.appendChild = function (child) {
+    if (child && child._isWidget === true) {
+      child.parent = this;
+      reregister(child);
+    }
+    if (!this._children.includes(child)) {
+      this._children.push(child);
+    }
+    return originalAppend.call(this, child);
+  };
+
+  /**
+   * Returns a shallow copy of the widget's direct children array.
+   *
+   * @returns {Array<Node>} Snapshot of `_children`.
+   */
+  widget.getChildren = () => [...widget._children];
+
+  const originalRemoveChild = widget.removeChild;
+
+  /**
+   * Overrides the native `removeChild` to:
+   * 1. Splice the child out of `_children`.
+   * 2. Clear `child.parent` when the child is a widget.
+   *
+   * @param {Node} child - The node to remove.
+   * @returns {Node} The removed child (mirrors native behaviour).
+   */
+  widget.removeChild = function (child) {
+    const index = this._children.indexOf(child);
+    if (index !== -1) {
+      this._children.splice(index, 1);
+      if (child && child._isWidget === true) {
+        child.parent = null;
+      }
+    }
+    return originalRemoveChild.call(this, child);
+  };
+
+  return widget;
+};
+
+export default makeParentable;

package/src/widget-factory/pixTool.js

@@ -0,0 +1,40 @@
+/**
+ * PX TOOL - Converts numbers to PX
+ */
+
+/**
+ * Converts a number to PX
+ * @param {number} value - Number to convert
+ * @returns {string} - Value in PX
+ *
+ * @example
+ * toPX(16) → '16px'
+ * toPX(24) → '24px'
+ */
+export const toPX = (value) => {
+  if (typeof value !== "number") return value;
+  return `${value}px`;
+};
+
+/**
+ * Applies PX to a styles object
+ * @param {Object} styles - Styles with numbers
+ * @returns {Object} - Styles with PX
+ *
+ * @example
+ * applyPX({ padding: 16, fontSize: 24, color: 'red' })
+ * // → { padding: '16px', fontSize: '24px', color: 'red' }
+ */
+export const applyPX = (styles) => {
+  const result = {};
+
+  for (const [key, value] of Object.entries(styles)) {
+    if (typeof value === "number") {
+      result[key] = toPX(value);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+};

package/src/widget-factory/processProps.js

@@ -0,0 +1,122 @@
+// core/processProps.js
+import { getPropDefinition, ATTRIBUTE_DOM_SET } from "./translateProps.js";
+import { toREM } from "./remTool.js"; // Centralized REM conversion utility
+
+/**
+ * Processes raw props and classifies them into:
+ * - style       : CSS properties
+ * - events      : DOM event listeners
+ * - attributes  : HTML attributes
+ * - textContent : text content
+ * - special     : special props (like value for inputs) that need custom handling
+ *
+ * @param {Object} props - Raw props object
+ * @param {string} tag - HTML tag of the widget (e.g., 'div', 'span', 'input')
+ * @param {string} [widgetName] - Real FletBox widget name (e.g., 'QRCode'),
+ *   used only to produce readable warnings. Falls back to the capitalized tag.
+ * @returns {{ style: Object, events: Object, attributes: Object, textContent: *, special: Object }}
+ */
+export const processProps = (props, tag = "div", widgetName = null) => {
+  const style = {};
+  const events = {};
+  const attributes = {};
+  const special = {};
+  let textContent = null;
+
+  // Derive widget name from tag (e.g., 'div' → 'Div', 'span' → 'Span')
+  const name = widgetName || tag.charAt(0).toUpperCase() + tag.slice(1);
+
+  for (const [key, value] of Object.entries(props)) {
+    if (value === undefined || value === null) continue;
+
+    // `style` is deliberately NOT part of the API: FletBox uses flat, aliased
+    // CSS props. Fail loudly instead of silently ignoring the object.
+    if (key === "style") {
+      console.warn(
+        `⚠️ [${name}] The \`style\` prop is not supported. Pass CSS props flat ` +
+          `(e.g. backgroundColor, padding, flexDirection).`,
+      );
+      continue;
+    }
+
+    // Pass widget name context for better warnings
+    const def = getPropDefinition(key, { widgetName: name });
+
+    if (def) {
+      switch (def.type) {
+        case "style": {
+          // Shorthands may fan out to several CSS props (e.g. `px` →
+          // paddingLeft + paddingRight). Everything else writes to its domProp.
+          const cssValue = applyUnit(def, value);
+          const targets = def.targets || [def.domProp];
+          for (const target of targets) style[target] = cssValue;
+          break;
+        }
+        case "attribute":
+          attributes[def.domProp] = value;
+          break;
+        case "event":
+          events[def.domProp] = value;
+          break;
+        case "text":
+          // 'value' on input-like elements must be handled as a special prop,
+          // not as text content, to avoid conflicting with the DOM's own value.
+          if (
+            key === "value" &&
+            ["input", "textarea", "select"].includes(tag)
+          ) {
+            special[def.domProp] = value;
+          } else {
+            textContent = value;
+          }
+          break;
+        case "special":
+          // Store special props so assignProps can handle them with custom logic.
+          special[def.domProp] = value;
+          break;
+        default:
+          console.warn(`⚠️ Unknown type "${def.type}" for prop "${key}"`);
+      }
+    } else {
+      // Unknown prop → intelligent fallback
+      if (key.startsWith("data-") || key.startsWith("aria-")) {
+        attributes[key] = value;
+      } else if (key.startsWith("on") && typeof value === "function") {
+        const eventName = key.slice(2).toLowerCase();
+        events[eventName] = value;
+      } else if (ATTRIBUTE_DOM_SET.has(key)) {
+        attributes[key] = value;
+      } else {
+        style[key] = value;
+      }
+    }
+  }
+
+  return { style, events, attributes, textContent, special };
+};
+
+/**
+ * Applies the correct CSS unit to a numeric value based on the prop definition.
+ *
+ * - `true` / `false` are coerced to `1` / `0` (unitless).
+ * - Non-numeric values pass through unchanged.
+ * - `unit: "none"` returns the raw number without a suffix.
+ * - `unit: "rem"` delegates to the centralized `toREM` converter.
+ * - All other units default to `"px"`.
+ *
+ * @param {Object} def - Prop definition from the prop database (see `translateProps.js`).
+ * @param {*} value - The value to convert.
+ * @returns {string|number} Value with the correct CSS unit applied.
+ */
+function applyUnit(def, value) {
+  if (value === true) return 1;
+  if (value === false) return 0;
+  if (typeof value !== "number") return value;
+  const unit = def.unit || "px";
+  if (unit === "none") return value;
+  
+  // Use the dynamic REM converter instead of a hard-coded division.
+  if (unit === "rem") return toREM(value); 
+  
+  return `${value}px`;
+}