flet-box 0.0.0-stage → 1.0.2

package/src/utils/navigation.js

@@ -0,0 +1,263 @@
+// components/flet-box/utils/navigation.js
+
+/**
+ * Adds full navigation capabilities to a widget:
+ * - parent (go up)
+ * - children (go down, by index)
+ * - findById (search by id)
+ * - siblings (siblings)
+ * - tree (tree view)
+ * - path (full path to the root)
+ */
+
+const navigated = new WeakSet();
+
+/**
+ * Augments a widget object with a full tree-navigation API.
+ *
+ * The following properties and methods are added (all non-destructive —
+ * already-present members are left untouched):
+ *
+ * **Traversal properties** (all enumerable, computed on access):
+ * - `parent`       — direct parent widget (readable/writable)
+ * - `children`     — array of direct children (readable/writable)
+ * - `firstChild`   — first element of `children`, or `null`
+ * - `lastChild`    — last element of `children`, or `null`
+ * - `siblings`     — all siblings excluding this widget
+ * - `nextSibling`  — next sibling in parent's children list, or `null`
+ * - `prevSibling`  — previous sibling in parent's children list, or `null`
+ * - `index`        — zero-based position among siblings (`-1` if no parent)
+ * - `root`         — topmost ancestor with no parent
+ * - `path`         — array of `{name, id, index}` objects from root to this widget
+ * - `depth`        — distance from this widget to the root (0 = root)
+ * - `tree`         — ASCII tree string of the entire sub-tree (useful for debugging)
+ *
+ * **Search methods**:
+ * - `findById(id)`          — depth-first search for a descendant by `id`
+ * - `findAll(widgetName)`   — collects all descendants whose `_widgetName` matches
+ *
+ * Already-navigated widgets (tracked by a `WeakSet`) are returned unchanged,
+ * making the function safe to call multiple times on the same object.
+ *
+ * @param {Object} widget - The widget instance to augment.
+ * @returns {Object} The same `widget` reference, now enriched with navigation.
+ */
+export const addNavigation = (widget) => {
+  if (!widget || navigated.has(widget)) return widget;
+  navigated.add(widget);
+
+  // ========================================================================
+  // 1. PARENT (you already have it in parentable, we include it here too)
+  // ========================================================================
+  if (!widget.hasOwnProperty("parent")) {
+    let _parent = null;
+    Object.defineProperty(widget, "parent", {
+      get: () => _parent,
+      set: (p) => {
+        _parent = p;
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  }
+
+  // ========================================================================
+  // 2. CHILDREN (array of direct children)
+  // ========================================================================
+  if (!widget._children) {
+    widget._children = [];
+  }
+
+  Object.defineProperty(widget, "children", {
+    get: () => widget._children,
+    set: (arr) => {
+      widget._children = arr;
+    },
+    enumerable: true,
+    configurable: true,
+  });
+
+  // ========================================================================
+  // 3. FIRST CHILD / LAST CHILD (shortcuts)
+  // ========================================================================
+  Object.defineProperty(widget, "firstChild", {
+    get: () => widget._children[0] || null,
+    enumerable: true,
+  });
+
+  Object.defineProperty(widget, "lastChild", {
+    get: () => widget._children[widget._children.length - 1] || null,
+    enumerable: true,
+  });
+
+  // ========================================================================
+  // 4. SIBLINGS (excluding itself)
+  // ========================================================================
+  Object.defineProperty(widget, "siblings", {
+    get: () => {
+      if (!widget.parent || !widget.parent._children) return [];
+      return widget.parent._children.filter((c) => c !== widget);
+    },
+    enumerable: true,
+  });
+
+  // ========================================================================
+  // 5. NEXT SIBLING / PREV SIBLING
+  // ========================================================================
+  Object.defineProperty(widget, "nextSibling", {
+    get: () => {
+      if (!widget.parent) return null;
+      const idx = widget.parent._children.indexOf(widget);
+      return widget.parent._children[idx + 1] || null;
+    },
+    enumerable: true,
+  });
+
+  Object.defineProperty(widget, "prevSibling", {
+    get: () => {
+      if (!widget.parent) return null;
+      const idx = widget.parent._children.indexOf(widget);
+      return widget.parent._children[idx - 1] || null;
+    },
+    enumerable: true,
+  });
+
+  // ========================================================================
+  // 6. INDEX (position among siblings)
+  // ========================================================================
+  Object.defineProperty(widget, "index", {
+    get: () => {
+      if (!widget.parent) return -1;
+      return widget.parent._children.indexOf(widget);
+    },
+    enumerable: true,
+  });
+
+  // ========================================================================
+  // 7. ROOT (go up to the root)
+  // ========================================================================
+  Object.defineProperty(widget, "root", {
+    get: () => {
+      let current = widget;
+      while (current.parent) {
+        current = current.parent;
+      }
+      return current;
+    },
+    enumerable: true,
+  });
+
+  // ========================================================================
+  // 8. PATH (path from the root to the widget)
+  // ========================================================================
+  Object.defineProperty(widget, "path", {
+    get: () => {
+      const path = [];
+      let current = widget;
+      while (current) {
+        path.unshift({
+          name: current._widgetName || current.tagName?.toLowerCase(),
+          id: current.id || null,
+          index: current.index,
+        });
+        current = current.parent;
+      }
+      return path;
+    },
+    enumerable: true,
+  });
+
+  // ========================================================================
+  // 9. DEPTH (depth in the tree)
+  // ========================================================================
+  Object.defineProperty(widget, "depth", {
+    get: () => {
+      let depth = 0;
+      let current = widget.parent;
+      while (current) {
+        depth++;
+        current = current.parent;
+      }
+      return depth;
+    },
+    enumerable: true,
+  });
+
+  // ========================================================================
+  // 10. findById (downward search by id)
+  // ========================================================================
+  widget.findById = function (id) {
+    if (this.id === id) return this;
+    for (const child of this._children || []) {
+      if (child.findById) {
+        const found = child.findById(id);
+        if (found) return found;
+      }
+    }
+    return null;
+  };
+
+  // ========================================================================
+  // 11. findAll (downward search by widget name)
+  // ========================================================================
+  widget.findAll = function (widgetName) {
+    const results = [];
+    if (this._widgetName === widgetName) results.push(this);
+    for (const child of this._children || []) {
+      if (child.findAll) {
+        results.push(...child.findAll(widgetName));
+      }
+    }
+    return results;
+  };
+
+  // ========================================================================
+  // 12. TREE (tree view for debugging)
+  // ========================================================================
+  widget._generateTree = function (indent = 0, isLast = true, prefix = "") {
+    const connector = indent === 0 ? "" : isLast ? "└── " : "├── ";
+    const continuation = indent === 0 ? "" : isLast ? "    " : "│   ";
+
+    const name = this._widgetName || this.tagName?.toLowerCase() || "widget";
+    const id = this.id ? ` #${this.id}` : "";
+    const props = this._getTreeProps ? this._getTreeProps() : "";
+
+    let tree = `${prefix}${connector}${name}${id}${props}\n`;
+
+    if (this._children && this._children.length > 0) {
+      this._children.forEach((child, index) => {
+        const childIsLast = index === this._children.length - 1;
+        if (child._generateTree) {
+          tree += child._generateTree(
+            indent + 1,
+            childIsLast,
+            prefix + continuation,
+          );
+        }
+      });
+    }
+
+    return tree;
+  };
+
+  Object.defineProperty(widget, "tree", {
+    get: () => widget._generateTree(),
+    enumerable: true,
+  });
+
+  // ========================================================================
+  // 13. _getTreeProps (overridable by each widget to display props)
+  // ========================================================================
+  widget._getTreeProps = function () {
+    const name = this._widgetName || "";
+    const propsMap = {
+      Text: () => (this.textContent ? ` [${this.textContent}]` : ""),
+      Image: () => (this.src ? ` [${this.src.split("/").pop()}]` : ""),
+      Container: () => "",
+      GestureDetector: () => "",
+    };
+    return propsMap[name] ? propsMap[name]() : "";
+  };
+
+  return widget;
+};

package/src/utils/scriptInjector.js

@@ -0,0 +1,73 @@
+/**
+ * @file scriptInjector.js
+ * @description
+ * Shared, idempotent external `<script>` loading.
+ *
+ * Like `@keyframes`, a third-party SDK script is global to the document: it must
+ * be loaded exactly once even if several widgets request it (for example a page
+ * with multiple ad units sharing one vendor SDK). Widgets therefore must not
+ * each append their own `<script>` tag — this module centralises the injection
+ * and returns the same promise for the same URL.
+ *
+ * @module scriptInjector
+ */
+
+/** URL → Promise<HTMLScriptElement> for scripts already requested. */
+const pending = new Map();
+
+/**
+ * Loads an external script once and resolves when it is ready.
+ *
+ * @param {string} src - Absolute script URL.
+ * @param {Object} [options]
+ * @param {boolean} [options.async=true] - Set the `async` attribute.
+ * @param {string} [options.crossOrigin] - Value for the `crossorigin` attribute.
+ * @param {Record<string,string>} [options.attrs] - Extra attributes to stamp on
+ *   the tag (e.g. `{ "data-flet-adsense": "ca-pub-…" }`).
+ * @returns {Promise<HTMLScriptElement|null>} Resolves with the script element,
+ *   or `null` outside a DOM environment. Rejects when the script fails to load.
+ */
+export function injectScript(src, options = {}) {
+  if (typeof document === "undefined") return Promise.resolve(null);
+  if (pending.has(src)) return pending.get(src);
+
+  const promise = new Promise((resolve, reject) => {
+    const existing = document.querySelector(`script[src="${src}"]`);
+    if (existing) {
+      // A script already in the document was not created by this module (our
+      // own tags are cached in `pending`), so it comes from the host page. We
+      // cannot observe its load state retroactively, and command-queue SDKs
+      // (AdSense) tolerate pushes before the script finishes loading, so treat
+      // it as ready instead of hanging on an already-fired `load` event.
+      resolve(existing);
+      return;
+    }
+
+    const script = document.createElement("script");
+    script.src = src;
+    script.async = options.async !== false;
+    if (options.crossOrigin) script.crossOrigin = options.crossOrigin;
+    for (const [name, value] of Object.entries(options.attrs || {})) {
+      script.setAttribute(name, value);
+    }
+    script.addEventListener(
+      "load",
+      () => {
+        script.dataset.fletLoaded = "true";
+        resolve(script);
+      },
+      { once: true },
+    );
+    script.addEventListener(
+      "error",
+      () => reject(new Error(`Failed to load script: ${src}`)),
+      { once: true },
+    );
+    document.head.appendChild(script);
+  });
+
+  pending.set(src, promise);
+  return promise;
+}
+
+export default injectScript;

package/src/utils/stackPosition.js

@@ -0,0 +1,31 @@
+// utils/stackPosition.js
+
+/**
+ * Reads `top`, `right`, `bottom`, and `left` from `props` and stores them as
+ * `dataset` attributes on the widget element so that a parent `Stack` widget
+ * can position this child absolutely at render time.
+ *
+ * @param {HTMLElement} widget - The widget element to annotate.
+ * @param {Object} props - Props object that may contain `top`, `right`, `bottom`, and/or `left`.
+ * @param {number|string} [props.top]    - Distance from the top edge (px or CSS string).
+ * @param {number|string} [props.right]  - Distance from the right edge (px or CSS string).
+ * @param {number|string} [props.bottom] - Distance from the bottom edge (px or CSS string).
+ * @param {number|string} [props.left]   - Distance from the left edge (px or CSS string).
+ * @returns {HTMLElement} The same `widget` reference, with dataset attributes set.
+ */
+export const stackPosition = (widget, props) => {
+  const top = props.top;
+  const right = props.right;
+  const bottom = props.bottom;
+  const left = props.left;
+
+  // Store position in dataset so the parent Stack can read it later
+  if (top !== undefined) widget.dataset.top = top;
+  if (right !== undefined) widget.dataset.right = right;
+  if (bottom !== undefined) widget.dataset.bottom = bottom;
+  if (left !== undefined) widget.dataset.left = left;
+
+  return widget;
+};
+
+export default stackPosition;

package/src/utils/stopWebRefresh.js

@@ -0,0 +1,77 @@
+// utils/stopWebRefresh.js
+
+/**
+ * Disables common browser refresh gestures so that the FletBox app behaves
+ * more like a native application.
+ *
+ * Three mechanisms are blocked:
+ * 1. **Keyboard shortcuts** — F5, Ctrl+R, and Cmd+R are intercepted via a
+ *    `keydown` listener and their default action is prevented.
+ * 2. **Context menu** — Right-click is suppressed on `document.body` to
+ *    prevent the browser's "Reload" option from appearing.
+ * 3. **Pull-to-refresh** (mobile) — A `touchmove` listener prevents the
+ *    native pull-to-refresh gesture when the page is scrolled to the top and
+ *    the touch is not inside a scrollable child element.
+ *
+ * All listeners are attached permanently for the lifetime of the page.
+ * Call this function once, typically at app startup.
+ */
+export const stopWebRefresh = () => {
+  // 1. Block refresh keys (F5, Ctrl+R, Cmd+R)
+  window.addEventListener("keydown", (e) => {
+    if (
+      e.key === "F5" ||
+      (e.ctrlKey && (e.key === "r" || e.key === "R")) ||
+      (e.metaKey && (e.key === "r" || e.key === "R"))
+    ) {
+      e.preventDefault();
+      console.log("🚫 Refresh disabled (keyboard)");
+    }
+  });
+
+  // 2. Block right-click (context menu)
+  document.body.addEventListener("contextmenu", (e) => {
+    e.preventDefault();
+  });
+
+  // 3. Block pull-to-refresh on mobile selectively
+  let touchStartY = 0;
+  let isAtTop = false;
+
+  window.addEventListener(
+    "touchstart",
+    (e) => {
+      touchStartY = e.touches[0].clientY;
+      // Check if we are at the top of the document
+      isAtTop =
+        window.scrollY === 0 && document.documentElement.scrollTop === 0;
+    },
+    { passive: true },
+  ); // passive: true improves performance
+
+  window.addEventListener(
+    "touchmove",
+    (e) => {
+      const deltaY = e.touches[0].clientY - touchStartY;
+      // Only prevent if: we are at the top, the movement is downward (deltaY > 0),
+      // and the event does not occur inside an element with its own scroll.
+      if (isAtTop && deltaY > 0) {
+        // Try to block only if the target is not a scrolling element
+        let target = e.target;
+        while (target && target !== document.body) {
+          const overflowY = window.getComputedStyle(target).overflowY;
+          if (overflowY === "auto" || overflowY === "scroll") {
+            // The touch is inside a scrolling container, allow movement
+            return;
+          }
+          target = target.parentElement;
+        }
+        // If we get here, there's no internal scroll in the way → block pull-to-refresh
+        e.preventDefault();
+      }
+    },
+    { passive: false },
+  );
+};
+
+export default stopWebRefresh;

package/src/utils/styleInjector.js

@@ -0,0 +1,38 @@
+/**
+ * @file styleInjector.js
+ * @description
+ * Shared, idempotent `@keyframes` injection.
+ *
+ * Keyframes are global by nature (CSS cannot scope them to an element), so
+ * widgets must not each append their own `<style>` tag to `document.head` —
+ * that duplicates tags and makes ownership unclear. This module centralises the
+ * injection and guarantees each animation name is defined exactly once.
+ *
+ * @module styleInjector
+ */
+
+/** Animation names already injected in this document. */
+const injected = new Set();
+
+/**
+ * Injects `@keyframes <name> { <frames> }` into `<head>` the first time the
+ * given name is requested. Subsequent calls for the same name are no-ops.
+ *
+ * @param {string} name - The animation name (e.g. `"skeleton-pulse"`).
+ * @param {string} frames - The keyframe body, without the `@keyframes` wrapper
+ *   (e.g. `"0% { opacity: 1; } 100% { opacity: 0.5; }"`).
+ * @param {string} [styleId] - Optional `id` for the injected `<style>` tag.
+ *   Older docs/widgets referenced ids like `#skeleton-styles` / `#indeterminate-progress-style`.
+ * @returns {void}
+ */
+export function injectKeyframes(name, frames, styleId) {
+  if (injected.has(name) || typeof document === "undefined") return;
+  injected.add(name);
+  const style = document.createElement("style");
+  style.setAttribute("data-flet-keyframes", name);
+  if (styleId) style.setAttribute("id", styleId);
+  style.textContent = `@keyframes ${name} { ${frames} }`;
+  document.head.appendChild(style);
+}
+
+export default injectKeyframes;