flet-box 0.0.0-stage → 1.0.2

package/src/utils/units.js

@@ -0,0 +1,87 @@
+// src/modules/FletBox/utils/units.js
+// import { toREM, setBaseFontSize, toPX } from './utils/units.js';
+//
+// // Global configuration (optional)
+// setBaseFontSize(16);  // 1rem = 16px (default)
+//
+// // Automatic conversions
+// toREM(16)    // "1rem"
+// toREM(24)    // "1.5rem"
+// toREM(8)     // "0.5rem"
+//
+// // Strings pass through as-is
+// toREM('16px')  // "16px"
+// toREM('1rem')  // "1rem"
+// toREM('50%')   // "50%"
+//
+// // For exact pixels
+// toPX(16)     // "16px"
+// toPX(24)     // "24px"
+// toPX('1rem') // "1rem"
+
+let BASE_FONT_SIZE = 16;
+
+/**
+ * Sets the base font size for rem conversion
+ * @param {number} size - Base size in pixels (default 16)
+ * @example
+ * setBaseFontSize(16); // 1rem = 16px
+ * setBaseFontSize(20); // 1rem = 20px
+ */
+export const setBaseFontSize = (size) => {
+  BASE_FONT_SIZE = size;
+  document.documentElement.style.fontSize = `${size}px`;
+};
+
+/**
+ * Converts a numeric value to rem, or keeps strings as they are
+ * @param {number|string} value - Value to convert
+ * @returns {string} Converted value (e.g. "1rem", "16px", "50%")
+ * @example
+ * toREM(16)     // "1rem"
+ * toREM(8)      // "0.5rem"
+ * toREM('16px') // "16px"
+ * toREM('1rem') // "1rem"
+ * toREM('50%')  // "50%"
+ */
+export const toREM = (value) => {
+  if (value === undefined || value === null) return undefined;
+
+  // If it is a number, convert to rem
+  if (typeof value === "number") {
+    return `${value / BASE_FONT_SIZE}rem`;
+  }
+
+  // If it is a string, return it as-is
+  if (typeof value === "string") {
+    return value;
+  }
+
+  // For other types (objects, booleans, etc.)
+  return String(value);
+};
+
+/**
+ * Converts a value to pixels if it is a number, or keeps strings
+ * @param {number|string} value - Value to convert
+ * @returns {string} Value in pixels or original string
+ * @example
+ * toPX(16)     // "16px"
+ * toPX('1rem') // "1rem"
+ * toPX('50%')  // "50%"
+ */
+export const toPX = (value) => {
+  if (value === undefined || value === null) return undefined;
+
+  if (typeof value === "number") {
+    return `${value}px`;
+  }
+
+  return value;
+};
+
+/**
+ * Gets the current base size
+ * @returns {number} Base size in pixels
+ */
+export const getBaseFontSize = () => BASE_FONT_SIZE;

package/src/utils/visualEffects.js

@@ -0,0 +1,169 @@
+// utils/visualEffects.js
+/**
+ * Visual Effects - Reusable visual effects for widgets
+ * @module utils/visualEffects
+ */
+
+// Cache for injected keyframes
+const injectedKeyframes = new Set();
+
+/**
+ * Inject CSS keyframes if not already injected
+ * @param {string} name - Animation name
+ * @param {string} keyframes - CSS keyframes
+ */
+export const injectKeyframes = (name, keyframes) => {
+  if (injectedKeyframes.has(name)) return;
+  const style = document.createElement("style");
+  style.textContent = `@keyframes ${name} { ${keyframes} }`;
+  document.head.appendChild(style);
+  injectedKeyframes.add(name);
+};
+
+/**
+ * Apply stripe pattern to an element
+ * @param {HTMLElement} element - Target element
+ * @param {Object} options - Stripe options
+ */
+export const applyStripes = (element, options = {}) => {
+  const {
+    color = "rgba(255, 255, 255, 0.15)",
+    size = 10,
+    angle = 45,
+    animated = false,
+    duration = "0.5s",
+  } = options;
+
+  const stripePattern = `repeating-linear-gradient(
+        ${angle}deg,
+        ${color} 0px,
+        ${color} ${size}px,
+        transparent ${size}px,
+        transparent ${size * 2}px
+    )`;
+
+  element.style.backgroundImage = stripePattern;
+  element.style.backgroundSize = `${size * 2}px ${size * 2}px`;
+
+  if (animated) {
+    element.style.animation = `progress-stripes ${duration} linear infinite`;
+
+    injectKeyframes(
+      "progress-stripes",
+      `
+            0% { background-position: 0 0; }
+            100% { background-position: ${size * 2}px 0; }
+        `,
+    );
+  }
+};
+
+/**
+ * Remove stripe pattern from element
+ */
+export const removeStripes = (element) => {
+  element.style.backgroundImage = "";
+  element.style.animation = "";
+};
+
+/**
+ * Apply shimmer/skeleton effect
+ */
+export const applyShimmer = (element, options = {}) => {
+  const {
+    highlightColor = "rgba(255, 255, 255, 0.3)",
+    baseColor = "rgba(0, 0, 0, 0.05)",
+    duration = "1.5s",
+  } = options;
+
+  element.style.background = `linear-gradient(
+        110deg,
+        ${baseColor} 0%,
+        ${baseColor} 35%,
+        ${highlightColor} 50%,
+        ${baseColor} 65%,
+        ${baseColor} 100%
+    )`;
+  element.style.backgroundSize = "200% 100%";
+  element.style.animation = `shimmer ${duration} ease-in-out infinite`;
+
+  injectKeyframes(
+    "shimmer",
+    `
+        0% { background-position: 200% 0; }
+        100% { background-position: -200% 0; }
+    `,
+  );
+};
+
+/**
+ * Apply glow effect
+ */
+export const applyGlow = (element, options = {}) => {
+  const {
+    color = "rgba(0, 122, 255, 0.5)",
+    intensity = 10,
+    duration = "2s",
+  } = options;
+
+  element.style.transition = "box-shadow 0.2s ease";
+  element.style.animation = `glow-pulse ${duration} ease-in-out infinite`;
+
+  injectKeyframes(
+    "glow-pulse",
+    `
+        0% { box-shadow: 0 0 0 ${color}; }
+        50% { box-shadow: 0 0 ${intensity}px ${color}; }
+        100% { box-shadow: 0 0 0 ${color}; }
+    `,
+  );
+};
+
+/**
+ * Apply indeterminate loading animation
+ */
+export const applyIndeterminate = (element, options = {}) => {
+  const { duration = "1.5s", width = "50%" } = options;
+
+  element.style.position = "relative";
+  element.style.width = width;
+  element.style.animation = `indeterminate-progress ${duration} ease-in-out infinite`;
+
+  injectKeyframes(
+    "indeterminate-progress",
+    `
+        0% { transform: translateX(-100%); }
+        50% { transform: translateX(0%); }
+        100% { transform: translateX(100%); }
+    `,
+  );
+};
+
+/**
+ * Apply pulse animation
+ */
+export const applyPulse = (element, options = {}) => {
+  const { scale = 1.05, duration = "0.3s" } = options;
+
+  element.style.transition = `transform ${duration} ease`;
+  element.style.animation = `pulse ${duration} ease-in-out`;
+
+  injectKeyframes(
+    "pulse",
+    `
+        0% { transform: scale(1); }
+        50% { transform: scale(${scale}); }
+        100% { transform: scale(1); }
+    `,
+  );
+};
+
+export default {
+  injectKeyframes,
+  applyStripes,
+  removeStripes,
+  applyShimmer,
+  applyGlow,
+  applyIndeterminate,
+  applyPulse,
+};

package/src/widget-factory/addChildren.js

@@ -0,0 +1,114 @@
+// core/addChildren.js
+
+/**
+ * Tracks which child nodes were appended via props (`child` / `children`).
+ * Using a WeakSet (external to the nodes) works with any Node type, including
+ * plain Text nodes, which cannot carry extra properties.
+ *
+ * @type {WeakSet<Node>}
+ */
+const PROP_CHILDREN = new WeakSet();
+
+/**
+ * Appends one or more children to a parent widget.
+ *
+ * Accepts a single child or an array of children. Each item may be:
+ * - A DOM Node (appended directly).
+ * - A string or number (converted to a TextNode).
+ * - `null`, `undefined`, or `false` (skipped silently).
+ *
+ * When `markAsProp` is `true` (the default), every appended node is recorded
+ * in `PROP_CHILDREN` so that `removePropChildren` can selectively remove only
+ * those nodes later.
+ *
+ * @param {HTMLElement} parent - The parent widget to append children to.
+ * @param {Node|string|number|Array|null|undefined|false} children - Child or
+ *   array of children to append.
+ * @param {Object} [options={}] - Options.
+ * @param {boolean} [options.markAsProp=true] - Whether to mark appended nodes
+ *   as prop-managed so they can be cleaned up by `removePropChildren`.
+ * @returns {HTMLElement} The parent widget (for chaining).
+ */
+export const addChildren = (parent, children, options = {}) => {
+  if (!children && children !== 0) return parent;
+
+  const { markAsProp = true } = options;
+  const items = Array.isArray(children) ? children : [children];
+
+  items.forEach((child) => {
+    if (child === null || child === undefined || child === false) return;
+
+    let node = child;
+    if (typeof child === "string" || typeof child === "number") {
+      node = document.createTextNode(String(child));
+    }
+
+    if (markAsProp) {
+      PROP_CHILDREN.add(node);
+    }
+
+    parent.appendChild(node);
+  });
+
+  return parent;
+};
+
+/**
+ * Removes all children that were previously appended via props (i.e. tracked in
+ * `PROP_CHILDREN`).
+ *
+ * Handles two cases:
+ * 1. **Normal path** – the node is still a direct child of `parent`. The
+ *    overridden `removeChild` is used, which also updates `_children`.
+ * 2. **Fallback path** – the node was moved to a different parent (e.g. by
+ *    drag-and-drop). `_children` is updated manually and the widget's `parent`
+ *    reference is cleared.
+ *
+ * In both cases the node is removed from `PROP_CHILDREN` to allow future
+ * garbage collection.
+ *
+ * @param {HTMLElement} parent - The parent widget whose prop-children should be
+ *   removed.
+ * @returns {HTMLElement} The parent widget (for chaining).
+ */
+export const removePropChildren = (parent) => {
+  const toRemove = Array.from(parent.childNodes).filter((child) =>
+    PROP_CHILDREN.has(child)
+  );
+
+  toRemove.forEach((child) => {
+    if (child.parentNode === parent) {
+      // Normal path: removeChild override also cleans up _children.
+      parent.removeChild(child);
+    } else {
+      // Fallback: node was moved; manually clean up _children.
+      const idx = parent._children.indexOf(child);
+      if (idx !== -1) parent._children.splice(idx, 1);
+      if (child._isWidget) child.parent = null;
+    }
+    PROP_CHILDREN.delete(child);
+  });
+
+  return parent;
+};
+
+/**
+ * Removes ALL children from a parent widget, regardless of whether they were
+ * appended via props or programmatically.
+ *
+ * Resets `_children` to an empty array and clears every node from
+ * `PROP_CHILDREN` as it is removed.
+ *
+ * @param {HTMLElement} parent - The parent widget to clear.
+ * @returns {HTMLElement} The parent widget (for chaining).
+ */
+export const clearChildren = (parent) => {
+  while (parent.firstChild) {
+    PROP_CHILDREN.delete(parent.firstChild);
+    parent.removeChild(parent.firstChild);
+  }
+  parent._children = [];
+  return parent;
+};
+
+export default { addChildren, removePropChildren, clearChildren };

package/src/widget-factory/assignProps.js

@@ -0,0 +1,256 @@
+// core/assignProps.js
+import { setStyles } from "./tools.js";
+
+/**
+ * Extracts the real value from a prop that may be a reactive accessor or a
+ * plain reactive object.
+ *
+ * - If the value is a function flagged with `_isReactive`, calls it to get the
+ *   current value.
+ * - If the value is a reactive object (has `_isReactive === true`), returns
+ *   `_value` when available, otherwise falls back to `valueOf()`.
+ * - Otherwise returns the value unchanged.
+ *
+ * @param {*} val - The raw prop value (may be reactive or plain).
+ * @returns {*} The resolved runtime value.
+ */
+const getValue = (val) => {
+  if (typeof val === "function" && val._isReactive) {
+    return val();
+  }
+  if (val && typeof val === "object" && val._isReactive === true) {
+    return val._value !== undefined ? val._value : val.valueOf();
+  }
+  return val;
+};
+
+/**
+ * HTML attributes whose mere presence means "true". Writing them through
+ * `setAttribute` with a falsy value is wrong — `setAttribute("readonly", false)`
+ * leaves the attribute present (`readonly="false"`) and the field stays
+ * read-only. These are written as DOM properties instead, so passing `false`
+ * removes the attribute.
+ *
+ * @type {Set<string>}
+ */
+const BOOLEAN_ATTRIBUTES = new Set([
+  "disabled",
+  "checked",
+  "selected",
+  "readOnly",
+  "required",
+  "autofocus",
+  "hidden",
+  "draggable",
+]);
+
+/**
+ * Applies a single "special" prop directly to the widget. Handles cases that
+ * are not pure CSS assignments, such as `value` for form elements and `variant`
+ * as a dataset attribute.
+ *
+ * @param {HTMLElement} widget - The target DOM element.
+ * @param {string} key - The special prop name (e.g. `'variant'`).
+ * @param {*} value - The raw value (resolved via `getValue` internally).
+ * @returns {void}
+ */
+const applySpecial = (widget, key, value) => {
+  const val = getValue(value);
+
+  switch (key) {
+    case "value":
+      if (widget.tagName === "INPUT" || widget.tagName === "TEXTAREA") {
+        if (widget.value !== val) widget.value = val;
+      }
+      break;
+    case "variant":
+      widget.dataset.variant = val;
+      break;
+  }
+};
+
+/**
+ * Applies a processed props object to a widget element.
+ *
+ * Handles five prop categories in order:
+ * 1. **style** – merged into the element's inline style via `setStyles`.
+ * 2. **textContent** – set as `value` on form elements, `textContent` elsewhere.
+ * 3. **events** – previous listeners are removed and the new set is attached.
+ *    `click` is assigned via `onclick` for reliable override behaviour.
+ * 4. **attributes** – applied with `setAttribute`, with special handling for
+ *    `className` and boolean attributes (`disabled`, `readOnly`, `hidden`, …).
+ * 5. **special** – delegated to `applySpecial` (e.g. `value`, `variant`).
+ *
+ * Any keys not in the known set are handled as a flat-prop fallback: `on*`
+ * functions become event listeners, common HTML attributes are set directly, and
+ * everything else is tried as an inline style.
+ *
+ * The `_updating` guard prevents re-entrant calls from triggering reactive
+ * side-effects during the assignment.
+ *
+ * @param {HTMLElement} widget - The target DOM element.
+ * @param {Object|null} props - Processed props object from `processProps`, or
+ *   `null` / `undefined` to no-op.
+ * @returns {HTMLElement} The same widget (for chaining).
+ */
+export const assignProps = (widget, props) => {
+  if (!props) return widget;
+
+  const wasUpdating = widget._updating;
+  widget._updating = true;
+
+  try {
+    // ============================================================
+    // 1. STYLES
+    // ============================================================
+    if (props.style && Object.keys(props.style).length > 0) {
+      setStyles(widget, props.style);
+    }
+
+    // ============================================================
+    // 2. TEXT
+    // ============================================================
+    if (props.textContent !== undefined) {
+      const textValue = getValue(props.textContent);
+      if (widget.tagName === "INPUT" || widget.tagName === "TEXTAREA") {
+        if (widget.value !== textValue) widget.value = textValue;
+      } else {
+        if (widget.textContent !== textValue) widget.textContent = textValue;
+      }
+    }
+
+    // ============================================================
+    // 3. EVENTS
+    // ============================================================
+    // Remove all previously registered listeners before adding the new ones.
+    if (widget._events && widget._events.length > 0) {
+      widget._events.forEach(({ event, handler }) => {
+        widget.removeEventListener(event, handler);
+      });
+      widget._events = [];
+    }
+    
+    widget.onclick = null;
+
+    if (props.events && Object.keys(props.events).length > 0) {
+      Object.entries(props.events).forEach(([event, handler]) => {
+        if (typeof handler !== "function") return;
+        if (event === "click") {
+          widget.onclick = handler;
+        } else {
+          widget.addEventListener(event, handler);
+          widget._events.push({ event, handler });
+        }
+      });
+    }
+
+    // ============================================================
+    // 4. ATTRIBUTES
+    // ============================================================
+    if (props.attributes && Object.keys(props.attributes).length > 0) {
+      Object.entries(props.attributes).forEach(([key, value]) => {
+        const finalValue = getValue(value);
+        try {
+          if (key === "className" || key === "class") {
+            widget.className = finalValue;
+          } else if (BOOLEAN_ATTRIBUTES.has(key)) {
+            widget[key] =
+              typeof finalValue === "boolean"
+                ? finalValue
+                : Boolean(finalValue);
+          } else {
+            widget.setAttribute(key, finalValue);
+          }
+        } catch (e) {
+          // Invalid attribute – silently skip
+        }
+      });
+    }
+
+    // ============================================================
+    // 5. SPECIALS
+    // ============================================================
+    if (props.special) {
+      for (const [key, value] of Object.entries(props.special)) {
+        applySpecial(widget, key, value);
+      }
+    }
+
+    // ============================================================
+    // 6. FALLBACK FOR FLAT PROPS
+    // ============================================================
+    // Props not belonging to any known category are handled here as a best-
+    // effort: event handlers, common HTML attributes, and inline CSS.
+    const knownKeys = new Set([
+      "style",
+      "events",
+      "attributes",
+      "textContent",
+      "special",
+      "child",
+      "children",
+      "ref",
+    ]);
+
+    const extraKeys = Object.keys(props).filter((key) => !knownKeys.has(key));
+    if (extraKeys.length > 0) {
+      for (const key of extraKeys) {
+        const value = props[key];
+        if (value === undefined || value === null) continue;
+
+        if (key.startsWith("on") && typeof value === "function") {
+          const eventName = key.slice(2).toLowerCase();
+          if (eventName === "click") {
+            widget.onclick = value;
+          } else {
+            widget.addEventListener(eventName, value);
+            widget._events.push({ event: eventName, handler: value });
+          }
+        } else if (
+          [
+            "className",
+            "class",
+            "id",
+            "type",
+            "href",
+            "src",
+            "alt",
+            "title",
+            "role",
+          ].includes(key)
+        ) {
+          const finalValue = getValue(value);
+          if (key === "className" || key === "class") {
+            widget.className = finalValue;
+          } else {
+            try {
+              widget.setAttribute(key, finalValue);
+            } catch (e) {}
+          }
+        } else if (key === "text" || key === "label" || key === "caption") {
+          const textValue = getValue(value);
+          if (widget.tagName === "INPUT" || widget.tagName === "TEXTAREA") {
+            if (widget.value !== textValue) widget.value = textValue;
+          } else {
+            if (widget.textContent !== textValue) widget.textContent = textValue;
+          }
+        } else {
+          const finalValue = getValue(value);
+          const cssValue =
+            typeof finalValue === "number" ? finalValue + "px" : finalValue;
+          try {
+            widget.style[key] = cssValue;
+          } catch (e) {}
+        }
+      }
+    }
+  } catch (error) {
+    console.error("❌ [assignProps] Error:", error);
+  } finally {
+    widget._updating = wasUpdating;
+  }
+
+  return widget;
+};
+
+export default assignProps;

package/src/widget-factory/createWidget.js

@@ -0,0 +1,28 @@
+// core/createWidget.js
+
+/**
+ * Creates a bare DOM element for use as a widget.
+ *
+ * This is the lowest-level factory step. It validates the tag, creates the
+ * element, and initialises the `_events` array that all higher-level modules
+ * rely on for listener tracking. No props are applied here — that is the
+ * responsibility of `assignProps`.
+ *
+ * @param {string} tag - HTML tag name for the element (e.g. `'div'`, `'button'`).
+ *   Defaults to `'div'` when the value is not a string.
+ * @param {Object} props - Reserved for future use; currently unused.
+ * @returns {HTMLElement} The newly created DOM element with `_events` initialised.
+ */
+export const createWidget = (tag, props) => {
+  // Validateste that tag is a string; fall back to 'div' when it is not.
+  let finalTag = tag;
+  if (typeof finalTag !== "string") {
+    console.warn("⚠️ createWidget: tag is not a string, using 'div'", finalTag);
+    finalTag = "div";
+  }
+
+  const widget = document.createElement(finalTag);
+  widget._events = [];
+
+  return widget;
+};