flet-box 0.0.0-stage → 1.0.2

package/src/animations/animate.js

@@ -0,0 +1,332 @@
+/**
+ * animate.js - Imperative animation utilities for DOM widgets.
+ *
+ * Provides two tiers of animation helpers:
+ * - **Fire-and-forget** (`animate`, `fadeOut`, `fadeIn`, `pulse`): start an
+ *   animation and move on — no way to await completion.
+ * - **Async/awaitable** (`animateAsync`, `fadeOutAsync`, `fadeInAsync`,
+ *   `pulseAsync`): return a Promise that resolves when the animation finishes,
+ *   allowing sequential composition with `await`.
+ *
+ * All functions drive the browser's `requestAnimationFrame` loop directly and
+ * do not rely on CSS transitions or the Web Animations API.
+ *
+ * @module animations/animate
+ */
+
+// ========== INTERPOLATION HELPERS ==========
+
+/**
+ * Interpolates between two values at a given progress point.
+ * Handles three value types:
+ * - `number → number`: straight numeric lerp.
+ * - `"#rrggbb" → string`: delegates to {@link interpolateColor}.
+ * - `"16px" → string`: parses the numeric part, lerps it, re-attaches the unit.
+ *
+ * @param {number|string} from     - Starting value.
+ * @param {number|string} to       - Ending value.
+ * @param {number}        progress - Interpolation factor in [0, 1].
+ * @returns {number|string} Interpolated value.
+ */
+const interpolate = (from, to, progress) => {
+  // Number to number
+  if (typeof from === "number" && typeof to === "number") {
+    return from + (to - from) * progress;
+  }
+  // Color to color (hex → rgb)
+  if (typeof from === "string" && from.startsWith("#")) {
+    return interpolateColor(from, to, progress);
+  }
+  // String with units (e.g., "16px", "2rem")
+  if (typeof from === "string") {
+    const fromNum = parseFloat(from);
+    const toNum = parseFloat(to);
+    const unit = from.replace(fromNum.toString(), "");
+    return fromNum + (toNum - fromNum) * progress + unit;
+  }
+  return to;
+};
+
+/**
+ * Linearly interpolates between two hex color values, returning an `rgb()` string.
+ *
+ * @param {string} color1   - Starting color as a hex string (e.g. `"#ff0000"`).
+ * @param {string} color2   - Ending color as a hex string.
+ * @param {number} progress - Interpolation factor in [0, 1].
+ * @returns {string} Interpolated color as `"rgb(r, g, b)"`.
+ */
+const interpolateColor = (color1, color2, progress) => {
+  const rgb1 = hexToRgb(color1);
+  const rgb2 = hexToRgb(color2);
+  const r = Math.round(rgb1.r + (rgb2.r - rgb1.r) * progress);
+  const g = Math.round(rgb1.g + (rgb2.g - rgb1.g) * progress);
+  const b = Math.round(rgb1.b + (rgb2.b - rgb1.b) * progress);
+  return `rgb(${r}, ${g}, ${b})`;
+};
+
+/**
+ * Parses a hex color string into its red, green, and blue components.
+ *
+ * @param {string} hex - Hex color string (with or without leading `#`).
+ * @returns {{ r: number, g: number, b: number }} RGB components in [0, 255].
+ *   Returns `{ r: 0, g: 0, b: 0 }` if the string cannot be parsed.
+ */
+const hexToRgb = (hex) => {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result
+    ? {
+        r: parseInt(result[1], 16),
+        g: parseInt(result[2], 16),
+        b: parseInt(result[3], 16),
+      }
+    : { r: 0, g: 0, b: 0 };
+};
+
+// ========== EASING FUNCTIONS ==========
+
+/**
+ * Applies a named easing curve to a linear progress value.
+ * Falls back to linear if `type` is not recognized.
+ *
+ * @param {"linear"|"easeIn"|"easeOut"|"easeInOut"} type - Easing curve name.
+ * @param {number} t - Raw linear progress in [0, 1].
+ * @returns {number} Eased progress value in [0, 1].
+ */
+const getEasing = (type, t) => {
+  const easings = {
+    linear: (t) => t,
+    easeIn: (t) => t * t,
+    easeOut: (t) => t * (2 - t),
+    easeInOut: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+  };
+  return easings[type]?.(t) ?? t;
+};
+
+/**
+ * Reads the current animated value of a property from a widget.
+ * For `"scale"`, returns `1` as a safe default since scale is stored
+ * inside a `transform` string rather than as a standalone property.
+ *
+ * @param {HTMLElement|object} widget   - The target widget or DOM element.
+ * @param {string}             property - The property to read.
+ * @returns {number|string} The current value, or `1` for `"scale"`.
+ */
+const readAnimatedValue = (widget, property) => {
+  if (property === "scale") return 1;
+  if (widget?.style && property in widget.style) {
+    return widget.style[property];
+  }
+  return widget?.[property];
+};
+
+/**
+ * Writes an animated value to a widget property.
+ * - `"scale"` is written as `transform: scale(value)`.
+ * - Numeric values for style properties that require a unit get `"px"` appended
+ *   (unitless properties such as `opacity`, `zIndex`, etc. are exempt).
+ * - Falls back to setting the property directly on the widget object for
+ *   non-style properties.
+ *
+ * @param {HTMLElement|object} widget   - The target widget or DOM element.
+ * @param {string}             property - The property to write.
+ * @param {number|string}      value    - The value to assign.
+ * @returns {void}
+ */
+const writeAnimatedValue = (widget, property, value) => {
+  if (!widget) return;
+  if (property === "scale") {
+    widget.style.transform = `scale(${value})`;
+    return;
+  }
+  if (widget.style && property in widget.style) {
+    const unitlessProperties = new Set([
+      "opacity",
+      "zIndex",
+      "fontWeight",
+      "lineHeight",
+      "flexGrow",
+      "flexShrink",
+    ]);
+    widget.style[property] =
+      typeof value === "number" && !unitlessProperties.has(property)
+        ? `${value}px`
+        : value;
+    return;
+  }
+  widget[property] = value;
+};
+
+// ========== FIRE AND FORGET (No Promise) ==========
+
+/**
+ * Animates a single property of a widget from one value to another.
+ * Fire-and-forget: returns immediately without waiting for the animation to end.
+ * Use {@link animateAsync} when you need to sequence animations.
+ *
+ * @param {HTMLElement|object} widget        - The target widget or DOM element.
+ * @param {string}             property      - The CSS property (or `"scale"`) to animate.
+ * @param {number|string}      from          - Starting value. If `undefined`, the current
+ *   value is read from the widget via {@link readAnimatedValue}.
+ * @param {number|string}      to            - Ending value.
+ * @param {number}             [duration=300] - Animation duration in milliseconds.
+ * @param {string}             [easing="linear"] - Easing curve name (see {@link getEasing}).
+ * @returns {void}
+ */
+export const animate = (
+  widget,
+  property,
+  from,
+  to,
+  duration = 300,
+  easing = "linear",
+) => {
+  const startTime = performance.now();
+  const startValue = from !== undefined ? from : readAnimatedValue(widget, property);
+  const endValue = to;
+
+  const step = (currentTime) => {
+    const elapsed = currentTime - startTime;
+    const progress = Math.min(1, elapsed / duration);
+    const easedProgress = getEasing(easing, progress);
+    const currentValue = interpolate(startValue, endValue, easedProgress);
+
+    writeAnimatedValue(widget, property, currentValue);
+
+    if (progress < 1) {
+      requestAnimationFrame(step);
+    }
+  };
+
+  requestAnimationFrame(step);
+};
+
+// ========== ASYNC ANIMATION (Returns Promise) ==========
+
+/**
+ * Animates a single property of a widget from one value to another.
+ * Returns a Promise that resolves with the widget once the animation completes.
+ * Use this when you need to `await` the end of an animation before starting the next.
+ *
+ * @param {HTMLElement|object} widget        - The target widget or DOM element.
+ * @param {string}             property      - The CSS property (or `"scale"`) to animate.
+ * @param {number|string}      from          - Starting value. If `undefined`, the current
+ *   value is read from the widget via {@link readAnimatedValue}.
+ * @param {number|string}      to            - Ending value.
+ * @param {number}             [duration=300] - Animation duration in milliseconds.
+ * @param {string}             [easing="linear"] - Easing curve name (see {@link getEasing}).
+ * @returns {Promise<HTMLElement|object>} Resolves with `widget` when the animation finishes.
+ */
+export const animateAsync = (
+  widget,
+  property,
+  from,
+  to,
+  duration = 300,
+  easing = "linear",
+) => {
+  return new Promise((resolve) => {
+    const startTime = performance.now();
+    const startValue = from !== undefined ? from : readAnimatedValue(widget, property);
+    const endValue = to;
+
+    const step = (currentTime) => {
+      const elapsed = currentTime - startTime;
+      const progress = Math.min(1, elapsed / duration);
+      const easedProgress = getEasing(easing, progress);
+      const currentValue = interpolate(startValue, endValue, easedProgress);
+
+      writeAnimatedValue(widget, property, currentValue);
+
+      if (progress < 1) {
+        requestAnimationFrame(step);
+      } else {
+        resolve(widget);
+      }
+    };
+
+    requestAnimationFrame(step);
+  });
+};
+
+// ========== HELPER FUNCTIONS (Fire and Forget) ==========
+
+/**
+ * Fades a widget out by animating its `opacity` from `1` to `0`.
+ * Fire-and-forget — does not return a Promise.
+ *
+ * @param {HTMLElement|object} widget        - The target widget.
+ * @param {number}             [duration=300] - Fade duration in milliseconds.
+ * @returns {void}
+ */
+export const fadeOut = (widget, duration = 300) => {
+  animate(widget, "opacity", 1, 0, duration);
+};
+
+/**
+ * Fades a widget in by animating its `opacity` from `0` to `1`.
+ * Fire-and-forget — does not return a Promise.
+ *
+ * @param {HTMLElement|object} widget        - The target widget.
+ * @param {number}             [duration=300] - Fade duration in milliseconds.
+ * @returns {void}
+ */
+export const fadeIn = (widget, duration = 300) => {
+  animate(widget, "opacity", 0, 1, duration);
+};
+
+/**
+ * Scales a widget up then back to its original size (a "pulse" effect).
+ * Fire-and-forget — does not return a Promise. For an awaitable version use
+ * {@link pulseAsync}.
+ *
+ * @param {HTMLElement|object} widget        - The target widget.
+ * @param {number}             [duration=300] - Total pulse duration in milliseconds
+ *   (split evenly between scale-up and scale-down).
+ * @returns {void}
+ */
+export const pulse = (widget, duration = 300) => {
+  animate(widget, "scale", 1, 1.1, duration / 2);
+  setTimeout(() => {
+    animate(widget, "scale", 1.1, 1, duration / 2);
+  }, duration / 2);
+};
+
+// ========== ASYNC HELPER FUNCTIONS (Returns Promise) ==========
+
+/**
+ * Fades a widget out by animating its `opacity` from `1` to `0`.
+ * Returns a Promise that resolves when the fade completes.
+ *
+ * @param {HTMLElement|object} widget        - The target widget.
+ * @param {number}             [duration=300] - Fade duration in milliseconds.
+ * @returns {Promise<HTMLElement|object>} Resolves with `widget` on completion.
+ */
+export const fadeOutAsync = (widget, duration = 300) => {
+  return animateAsync(widget, "opacity", 1, 0, duration);
+};
+
+/**
+ * Fades a widget in by animating its `opacity` from `0` to `1`.
+ * Returns a Promise that resolves when the fade completes.
+ *
+ * @param {HTMLElement|object} widget        - The target widget.
+ * @param {number}             [duration=300] - Fade duration in milliseconds.
+ * @returns {Promise<HTMLElement|object>} Resolves with `widget` on completion.
+ */
+export const fadeInAsync = (widget, duration = 300) => {
+  return animateAsync(widget, "opacity", 0, 1, duration);
+};
+
+/**
+ * Scales a widget up then back to its original size, awaiting each phase.
+ * Use this when subsequent code must run only after the full pulse finishes.
+ *
+ * @param {HTMLElement|object} widget        - The target widget.
+ * @param {number}             [duration=300] - Total pulse duration in milliseconds
+ *   (split evenly between scale-up and scale-down).
+ * @returns {Promise<void>} Resolves when both phases of the pulse have completed.
+ */
+export const pulseAsync = async (widget, duration = 300) => {
+  await animateAsync(widget, "scale", 1, 1.1, duration / 2);
+  await animateAsync(widget, "scale", 1.1, 1, duration / 2);
+};

package/src/animations/index.js

@@ -0,0 +1,25 @@
+/**
+ * animations/index.js - Public entry point for the animations module.
+ *
+ * Re-exports all animation widgets and imperative animation utilities so
+ * consumers can import from a single path:
+ *
+ * @example
+ * import { AnimatedBox, animate, fadeInAsync } from "./animations/index.js";
+ *
+ * @module animations
+ */
+export { ParallaxBox } from "./ParallaxBox.js";
+export { AnimatedBox } from "./AnimatedBox.js";
+export { AnimatedText } from "./AnimatedText.js";
+export { MatrixRain } from "./MatrixRain.js";
+export {
+	animate,
+	animateAsync,
+	fadeOut,
+	fadeIn,
+	pulse,
+	fadeOutAsync,
+	fadeInAsync,
+	pulseAsync,
+} from "./animate.js";

package/src/app.js

@@ -0,0 +1,41 @@
+// app.js - Direct reactive property assignment demo
+import { runApp, Container, colors, Button } from "./index.js";
+
+/**
+ * Root application component.
+ *
+ * Demonstrates FletBox's reactive widget model: instead of triggering a full
+ * tree rebuild, individual widget properties (e.g. `text`, `bgColor`) are
+ * assigned directly on the returned widget instance. The framework detects the
+ * assignment and patches only the affected element in the DOM.
+ *
+ * @returns {HTMLElement} A full-viewport centered container holding the demo button.
+ */
+const App = () => {
+  let clickCount = 0;
+
+  const miBoton = Button({
+    text: "Click me hello",
+    bgColor: colors.surface,
+    onPress: () => {
+      clickCount++;
+
+      // ✅ Directly assign to the reactive widget — no re-render needed
+      miBoton.text = `Clicked ${clickCount} times`;
+
+      if (clickCount >= 5) {
+        miBoton.bgColor = "#ff4444";
+        miBoton.textColor = "white";
+      }
+    },
+  });
+
+  return Container({
+    justifyContent: "center",
+    alignItems: "center",
+    height: "100vh",
+    child: miBoton,
+  });
+};
+
+runApp(App, "root");

package/src/core/App.js

@@ -0,0 +1,44 @@
+// src/core/App.js
+// FletBox Kids - Ultra simple: only receives ONE widget
+
+/**
+ * Mounts a single widget into the application root element.
+ *
+ * Looks for an existing `#root` element in the document. If none is found, a
+ * new `<div id="root">` is created and appended to `document.body` — the body
+ * itself is never cleared so that host scripts and markup are preserved.
+ *
+ * The root is reset on every call (via `innerHTML = ""`), making this function
+ * suitable for simple, single-widget apps that do not need the full lifecycle
+ * management provided by `runApp`.
+ *
+ * @param {HTMLElement} widget - The widget element to render inside the root.
+ *   Must be a valid DOM element (`nodeType === 1`). When provided, its width is
+ *   stretched to fill the root container.
+ * @returns {HTMLElement} The root container element.
+ */
+export const App = (widget) => {
+  let root = document.getElementById("root");
+  if (!root) {
+    // Never clear document.body (it would wipe the host's scripts/markup);
+    // create a dedicated root container instead.
+    root = document.createElement("div");
+    root.id = "root";
+    document.body.appendChild(root);
+  }
+  root.innerHTML = "";
+  root.style.margin = "0";
+  root.style.padding = "0";
+
+  root.style.width = "100%";
+  root.style.minHeight = "100vh";
+
+  if (widget && widget.nodeType === 1) {
+    widget.style.width = "100%";
+    root.appendChild(widget);
+  }
+
+  return root;
+};
+
+export default App;

package/src/core/hmr-client.js

@@ -0,0 +1,142 @@
+// src/core/hmr-client.js
+
+/** @type {WebSocket|null} Active WebSocket connection to the HMR server. */
+let ws = null;
+
+/**
+ * Registry of modules tracked by HMR.
+ * Keys are module URLs; values are the imported module objects.
+ *
+ * @type {Map<string, Object>}
+ */
+let modules = new Map();
+
+/**
+ * Initialises the Hot Module Replacement (HMR) client.
+ *
+ * Opens a WebSocket connection to the current host using the appropriate
+ * protocol (`ws:` or `wss:` depending on whether the page is served over
+ * HTTPS). Handles three server message types:
+ *
+ * - `request-modules` — the server asks which modules this client has
+ *   registered; responds with a `register-modules` message.
+ * - `hmr` — a file changed; delegates to `handleHMR`.
+ * - `reload` — the server requests a full page reload.
+ *
+ * On disconnect the client waits 500 ms then reloads the page so the
+ * developer always sees a fresh state.
+ */
+export const initHMR = () => {
+  const protocol = location.protocol === "https:" ? "wss:" : "ws:";
+  ws = new WebSocket(`${protocol}//${location.host}`);
+
+  ws.onopen = () => {
+    console.log("🔥 HMR connected");
+  };
+
+  ws.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+
+    if (data.type === "request-modules") {
+      // Send the list of registered module URLs back to the server.
+      const moduleUrls = Array.from(modules.keys());
+      ws.send(
+        JSON.stringify({ type: "register-modules", modules: moduleUrls }),
+      );
+    }
+
+    if (data.type === "hmr") {
+      handleHMR(data);
+    }
+
+    if (data.type === "reload") {
+      console.log("🔄 Full reload triggered");
+      window.location.reload();
+    }
+  };
+
+  ws.onclose = () => {
+    console.log("🔄 HMR disconnected, reloading...");
+    setTimeout(() => window.location.reload(), 500);
+  };
+};
+
+/**
+ * Handles an individual HMR update from the server.
+ *
+ * Three change types are supported:
+ *
+ * - `css` — hot-reloads matching `<link>` stylesheets by appending a cache-
+ *   busting timestamp to their `href`, avoiding a full page reload.
+ * - `exports-changed` — the module's public API changed in a way that cannot
+ *   be patched in-place; triggers a full reload.
+ * - anything else — re-imports the changed module via a dynamic `import()` and
+ *   dispatches an `hmr:update` CustomEvent so components can react. Falls back
+ *   to a full reload if the import fails.
+ *
+ * @param {{ file: string, changeType: string }} data - The HMR payload from the server.
+ * @param {string} data.file - Relative path of the changed file.
+ * @param {string} data.changeType - The kind of change (`"css"`,
+ *   `"exports-changed"`, or any other string for a JS hot-swap).
+ */
+const handleHMR = (data) => {
+  const { file, changeType } = data;
+
+  if (changeType === "css") {
+    // Reload CSS without a full page refresh by replacing each matching <link>
+    // element with a clone that has a cache-busting timestamp in its href.
+    const links = document.querySelectorAll(
+      `link[href*="${file.replace(/\\/g, "/")}"]`,
+    );
+    links.forEach((link) => {
+      const newLink = link.cloneNode();
+      newLink.href = link.href.split("?")[0] + "?t=" + Date.now();
+      link.parentNode.replaceChild(newLink, link);
+    });
+    console.log(`🎨 Hot reloaded CSS: ${file}`);
+    return;
+  }
+
+  if (changeType === "exports-changed") {
+    console.log(`📦 Exports changed in ${file}, reloading...`);
+    window.location.reload();
+    return;
+  }
+
+  // JS code change — attempt a hot swap via dynamic import.
+  console.log(`🔥 Hot reloading: ${file}`);
+  const url = `/${file}?t=${Date.now()}`;
+  import(url)
+    .then((module) => {
+      // Notify any listening components that the module was updated.
+      window.dispatchEvent(
+        new CustomEvent("hmr:update", { detail: { file, module } }),
+      );
+    })
+    .catch((err) => {
+      console.error("HMR import failed:", err);
+      window.location.reload();
+    });
+};
+
+/**
+ * Registers a module URL in the local HMR module registry so the server can
+ * track which modules this client is using.
+ *
+ * @param {string} url - The URL (path) of the module to register.
+ * @param {Object} module - The imported module object.
+ */
+export const registerModule = (url, module) => {
+  modules.set(url, module);
+};
+
+/**
+ * Returns the current WebSocket connection used by the HMR client, or `null`
+ * if `initHMR` has not been called yet.
+ *
+ * @returns {WebSocket|null} The active WebSocket instance.
+ */
+// ✅ Added the getHMR function to match the export in index.js
+export const getHMR = () => ws;
+
+export default { initHMR, registerModule, getHMR };

package/src/core/index.js

@@ -0,0 +1,34 @@
+/**
+ * @module core
+ *
+ * Public entry point for the FletBox core layer.
+ *
+ * Re-exports every symbol that consumers of the framework need to bootstrap an
+ * application, manage the DOM, use HMR in development, and work with PWA APIs.
+ *
+ * @see {@link ./runApp.js}   - Application mounting and DOM helpers.
+ * @see {@link ./App.js}      - Minimal single-widget mount helper.
+ * @see {@link ./hmr-client.js} - Hot Module Replacement WebSocket client.
+ * @see {@link ./pwa.js}      - Progressive Web App install / update / remove utilities.
+ */
+
+// Application bootstrap and DOM placement helpers
+export {
+  runApp,
+  createApp,
+  insertBy,
+  prependBy,
+  insertBefore,
+  insertAfter,
+  replaceBy,
+  mountAll,
+} from "./runApp.js";
+
+// Minimal single-widget mount helper
+export { App } from "./App.js";
+
+// HMR client (development only)
+export { initHMR, getHMR } from "./hmr-client.js";
+
+// PWA utilities
+export { installPWA, updatePWA, removePWA, isPWAInstalled } from "./pwa.js";