flet-box 1.0.3 → 1.0.5

package/src/index.js

@@ -280,6 +280,7 @@ export {
   ParallaxBox,
   animate,
   animateAsync,
+  stopAnimation,
   fadeIn,
   fadeOut,
   pulse,

package/src/navigations/AdaptiveScaffold.js

@@ -81,7 +81,10 @@ export const AdaptiveScaffold = (props) => {
       // button to drawerInstance.open().
       drawerInstance = Drawer({
         header: null,
-        body: [content],
+        // `body` is an array of widgets, and `leftNavBar` may itself be one, so
+        // the content is flattened here. A nested array would reach `children`
+        // as a single item and break the append.
+        body: Array.isArray(content) ? content : [content],
         footer: null,
         position: "left",
         width: leftNavBarWidth,
@@ -125,6 +128,12 @@ export const AdaptiveScaffold = (props) => {
       widthExpanded: rightNavBarWidth,
       widthCollapsed: 50,
       bgColor: colors.surface,
+      // FIX: CollapsibleSideBar aplica `borderRight` por defecto (default
+      // `1px solid ${colors.border}`), así que un sidebar derecho acababa
+      // con doble borde: `borderRight` (heredado del default) + `borderLeft`
+      // (el que pedimos aquí). Forzamos `borderRight: "none"` para que solo
+      // tenga el borde izquierdo (el que da al contenido central).
+      borderRight: "none",
       borderLeft: `1px solid ${colors.border}`,
       children: content,
     });
@@ -146,4 +155,4 @@ export const AdaptiveScaffold = (props) => {
   });
 };
 
-export default AdaptiveScaffold;
+export default AdaptiveScaffold;

package/src/navigations/AppBar.js

@@ -277,9 +277,15 @@ export const AppBar = (props) => {
       lastScrollY = currentScrollY;
     };
     window.addEventListener("scroll", handleScroll);
-    // Store the remover so _cleanup can deregister the listener.
-    appBar._cleanupScroll = () =>
+    // Register the remover through BOTH teardown paths. `_cleanup` is only called
+    // by runApp's teardownTree / Scaffold, while a plain DOM disconnect goes
+    // through the lifecycle observer, which never calls `_cleanup` — so without
+    // `onUnmount` this listener (and the detached bar) stayed alive forever.
+    // `removeEventListener` is idempotent, so running both is harmless.
+    const removeScroll = () =>
       window.removeEventListener("scroll", handleScroll);
+    appBar._cleanupScroll = removeScroll;
+    appBar.onUnmount(removeScroll);
   }
 
   // ========== PUBLIC API ==========

package/src/navigations/BottomNavigation.js

@@ -149,6 +149,7 @@ export const BottomNavigation = (props) => {
     if (!useRouter) return;
 
     const currentPath = getCurrentPath();
+    const previousIndex = activeIndex;
 
     buttons.forEach((btnData, idx) => {
       const isSelected = btnData.route === currentPath;
@@ -163,7 +164,10 @@ export const BottomNavigation = (props) => {
       if (isSelected) activeIndex = idx;
     });
 
-    if (onTabChange) onTabChange(activeIndex);
+    // Fire only when the route actually moved the selection. A consumer that
+    // navigates from `onTabChange` (the normal case) would otherwise recurse:
+    // route change -> callback -> goTo -> route change, until the stack blows.
+    if (activeIndex !== previousIndex && onTabChange) onTabChange(activeIndex);
   };
 
   // ========== BUILD TAB BUTTONS ==========
@@ -214,8 +218,11 @@ export const BottomNavigation = (props) => {
 
     let labelWidget = null;
     if (showLabels && item.label) {
+      // FIX: `value` es una prop `special` que `applySpecial` solo maneja
+      // en <input>/<textarea>. En un <span> no hace nada → el label quedaba
+      // vacío. La prop correcta para contenido de texto es `text`.
       labelWidget = Text({
-        value: item.label,
+        text: item.label,
         size: 11,
         color: isActive ? selectedColor : unselectedColor,
         fontWeight: isActive ? "500" : "400",
@@ -285,14 +292,26 @@ export const BottomNavigation = (props) => {
     return getCurrentPath();
   };
 
-  // Cleanup: unsubscribe from the router when the bar is removed from the DOM.
+  // Cleanup: release the router subscription on EITHER teardown path. `_cleanup`
+  // is only run by runApp's teardownTree / Scaffold; the lifecycle observer that
+  // fires on a plain DOM disconnect never calls it, so without `onUnmount` the
+  // router kept invoking `updateColorsFromRouter()` (and `onTabChange`) on a
+  // detached bar forever. The disposer is idempotent because both paths can run.
+  let unsubscribed = false;
+  const dispose = () => {
+    if (unsubscribed) return;
+    unsubscribed = true;
+    if (unsubscribe) unsubscribe();
+  };
+  container.onUnmount(dispose);
+
   const originalCleanup = container._cleanup;
   container._cleanup = () => {
-    if (unsubscribe) unsubscribe();
+    dispose();
     if (originalCleanup) originalCleanup();
   };
 
   return container;
 };
 
-export default BottomNavigation;
+export default BottomNavigation;

package/src/navigations/DrawerItem.js

@@ -246,11 +246,24 @@ export const DrawerItem = (props) => {
   // Apply the initial visual state now that DOM refs are set.
   updateUI();
 
-  // Cleanup: unsubscribe from router and selection events to prevent memory leaks.
-  const originalCleanup = container._cleanup;
-  container._cleanup = () => {
+  // Cleanup: release the router subscription and the selection listener on EITHER
+  // teardown path. `_cleanup` is only run by runApp's teardownTree / Scaffold; the
+  // lifecycle observer that fires on a plain DOM disconnect never calls it, so
+  // without `onUnmount` every removed item kept a live router callback (retaining
+  // its DOM refs) plus a listener on the shared selection EventTarget. The
+  // disposer is idempotent because both paths can run.
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
     if (unsubscribeRouter) unsubscribeRouter();
     if (unsubscribeGlobal) unsubscribeGlobal();
+  };
+  container.onUnmount(dispose);
+
+  const originalCleanup = container._cleanup;
+  container._cleanup = () => {
+    dispose();
     if (originalCleanup) originalCleanup();
   };
 

package/src/navigations/Scaffold.js

@@ -494,8 +494,15 @@ export const Scaffold = (props) => {
     clearContainer(fabContainer);
     clearContainer(leftNavBarContainer);
     clearContainer(rightNavBarContainer);
-    if (container._drawer?.parentNode)
+    // `destroy()` releases the viewport-resize listener, the Escape key handler
+    // and the pending close timer, then removes the node itself. Removing only
+    // the node (the previous behaviour) left all three behind, so every rebuilt
+    // scaffold leaked one more listener and one more body child.
+    if (typeof container._drawer?.destroy === "function") {
+      container._drawer.destroy();
+    } else if (container._drawer?.parentNode) {
       container._drawer.parentNode.removeChild(container._drawer);
+    }
     if (originalCleanup) originalCleanup();
   };
 

package/src/navigations/Tabs.js

@@ -67,7 +67,11 @@ export const Tabs = (props) => {
     size = "medium",
     color = colors.primary,
     textColor = colors.text,
-    activeTextColor = colors.white,
+    // FIX: `colors.white` no existe en themes.js → caía a `undefined`
+    // y el tab activo no se distinguía visualmente. Uso `colors.background`
+    // (que es "#ffffff" en el tema claro y "#0f172a" en el oscuro, que es
+    // lo correcto: contraste sobre el fondo del tab activo).
+    activeTextColor = colors.background,
     bgColor = colors.gray100,
     buttonColor = colors.secondary,
     alignment = "left",
@@ -318,6 +322,11 @@ export const Tabs = (props) => {
     updateContent();
   };
 
+  // Mount the initially active pane during construction. Without this the pane
+  // area stayed empty until the user clicked a *different* tab, even though the
+  // first tab already rendered as `aria-selected="true"`.
+  updateContent();
+
   // Defer the initial slider position calculation by one frame so the DOM
   // has been laid out and getBoundingClientRect() returns real values.
   let initialPositionTimer = setTimeout(() => {
@@ -341,18 +350,41 @@ export const Tabs = (props) => {
 
   // Also observe the tab bar element itself so the thumb repositions when
   // the container resizes independently of the window (e.g. sidebar toggle).
-  if (typeof ResizeObserver !== "undefined") {
+  // Only the slider variant has a thumb, so skip it for the other variants.
+  if (variant === "slider" && typeof ResizeObserver !== "undefined") {
     resizeObserver = new ResizeObserver(() => updateSliderPosition());
     if (tabsWrapperRef) resizeObserver.observe(tabsWrapperRef);
   }
 
-  // Cleanup: cancel timers and remove listeners when the component is unmounted.
+  // Cleanup: release the timers, the window listener and the observer on EITHER
+  // teardown path. `_cleanup` is only run by runApp's teardownTree / Scaffold; a
+  // plain DOM disconnect goes through the lifecycle observer, which never calls
+  // it — so without `onUnmount` the resize listener stayed registered and the
+  // ResizeObserver kept observing (and retaining) a detached tab bar. The
+  // disposer is idempotent because both paths can run.
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    if (initialPositionTimer) {
+      clearTimeout(initialPositionTimer);
+      initialPositionTimer = null;
+    }
+    if (resizeTimeout) {
+      clearTimeout(resizeTimeout);
+      resizeTimeout = null;
+    }
+    window.removeEventListener("resize", handleResize);
+    if (resizeObserver) {
+      resizeObserver.disconnect();
+      resizeObserver = null;
+    }
+  };
+  container.onUnmount(dispose);
+
   const originalCleanup = container._cleanup;
   container._cleanup = () => {
-    if (initialPositionTimer) clearTimeout(initialPositionTimer);
-    if (resizeTimeout) clearTimeout(resizeTimeout);
-    window.removeEventListener("resize", handleResize);
-    if (resizeObserver) resizeObserver.disconnect();
+    dispose();
     if (originalCleanup) originalCleanup();
   };
 
@@ -381,4 +413,4 @@ export const Tabs = (props) => {
   return container;
 };
 
-export default Tabs;
+export default Tabs;

package/src/tools/dimensions.js

@@ -16,8 +16,14 @@
  * // Call remove() to stop listening.
  */
 
-let windowWidth = window.innerWidth;
-let windowHeight = window.innerHeight;
+// SSR / Node guard: this module must stay importable where `window` does not
+// exist (SSR, test runners, build tooling). Reading `window.innerWidth` at
+// module scope used to throw a ReferenceError on import. Same convention as
+// `src/core/pwa.js`.
+const hasWindow = typeof window !== "undefined";
+
+let windowWidth = hasWindow ? window.innerWidth : 0;
+let windowHeight = hasWindow ? window.innerHeight : 0;
 
 // Live named exports — is-module live bindings: importers of { width, height }
 // always read the current value, kept in sync on resize.
@@ -45,7 +51,9 @@ const handleResize = () => {
   });
 };
 
-window.addEventListener("resize", handleResize);
+// Only subscribe inside a browser; in Node the listener list stays inert and
+// `addListener` / `removeListener` keep working without throwing.
+if (hasWindow) window.addEventListener("resize", handleResize);
 
 /**
  * Dimensions object — provides getter properties and listener management.

package/src/tools/useState.js

@@ -1,5 +1,10 @@
 // src/tools/useState.js
 import { saveRam, getRam, subscribeRam } from "../services/RamStore.js";
+import {
+  createReactiveValue,
+  isStructuralRead,
+  resetStructuralReads,
+} from "../widget-factory/reactiveValue.js";
 
 // Store callbacks for each state key
 const subscribers = new Map();
@@ -35,6 +40,56 @@ const triggerRender = () => {
   }, 0);
 };
 
+let ramDispatcherReady = false;
+
+/**
+ * Installs **one** RamStore subscriber that dispatches to the widgets and
+ * callbacks registered for the key that actually changed.
+ *
+ * RamStore walks a flat subscriber array on every `saveRam`, so registering one
+ * subscriber per key made a single state change cost O(number of keys) — with
+ * every callback immediately rejecting the key. One dispatcher makes the lookup
+ * O(1), and the work proportional to what the key really has bound.
+ *
+ * @returns {void}
+ */
+const ensureRamDispatcher = () => {
+  if (ramDispatcherReady) return;
+  ramDispatcherReady = true;
+
+  const unsubscribe = subscribeRam((changedKey, newValue, oldValue) => {
+    const callbacks = subscribers.get(changedKey);
+    // A key nobody ever passed to `useState` has no listeners: ignore it.
+    if (!callbacks) return;
+
+    // 1. Surgical update: patch only the widgets bound to this key.
+    const bound = widgetsByKey.get(changedKey);
+    let handled = 0;
+    if (bound) {
+      bound.forEach((propNames, widget) => {
+        if (!widget || typeof widget.update !== "function") return;
+        propNames.forEach((propName) => {
+          widget.update({ [propName]: newValue });
+          handled++;
+        });
+      });
+    }
+
+    // 2. Notify the manual subscribers.
+    callbacks.forEach((callback) => callback(newValue, oldValue));
+
+    // 3. Re-render the app when nothing was bound, or when the last render pass
+    // also read this key structurally (a template literal, a conditional, a
+    // list): the surgical patch above cannot change what the component computes.
+    if (handled === 0 || isStructuralRead(changedKey)) triggerRender();
+  });
+
+  if (typeof window !== "undefined") {
+    if (!window._useStateCleanups) window._useStateCleanups = [];
+    window._useStateCleanups.push(unsubscribe);
+  }
+};
+
 /**
  * Registers a widget instance so it receives automatic prop updates whenever
  * the state value associated with `key` changes.
@@ -45,50 +100,49 @@ const triggerRender = () => {
  * @returns {void}
  */
 export const registerWidget = (key, widget, propName) => {
-  if (!widgetsByKey.has(key)) {
-    widgetsByKey.set(key, new Set());
+  // Two levels — key -> widget -> prop names — so looking a widget up is O(1).
+  // A flat Set with a linear scan made registering N widgets on the same key
+  // O(N^2): 1,600 widgets on one key cost ~44 ms.
+  let perWidget = widgetsByKey.get(key);
+  if (!perWidget) {
+    perWidget = new Map();
+    widgetsByKey.set(key, perWidget);
+  }
+  let propNames = perWidget.get(widget);
+  if (!propNames) {
+    propNames = new Set();
+    perWidget.set(widget, propNames);
   }
-  widgetsByKey.get(key).add({ widget, propName });
+  // Idempotent: rebuilding the same widget position must not stack duplicates.
+  const already = propNames.has(propName);
+  propNames.add(propName);
 
-  // Set initial value if the state already exists
+  // Push the current value straight away when the widget can already take it.
+  // (During construction `update` does not exist yet — the value has just been
+  // applied by the factory, so there is nothing to push.)
   const currentValue = getRam(key);
   if (currentValue !== undefined && widget && widget.update) {
     widget.update({ [propName]: currentValue });
   }
 
-  // Patch the widget's cleanup to also remove it from the registry when destroyed
-  const originalCleanup = widget._cleanup;
-  widget._cleanup = () => {
-    const widgets = widgetsByKey.get(key);
-    if (widgets) {
-      for (const item of widgets) {
-        if (item.widget === widget) {
-          widgets.delete(item);
-          break;
-        }
-      }
-    }
-    if (originalCleanup) originalCleanup();
+  if (already) return;
+
+  // Release the binding through `onUnmount`, which the framework fires on BOTH
+  // teardown paths. Patching `_cleanup` (the previous approach) leaked: the
+  // lifecycle observer never calls `_cleanup`, so a widget removed without a full
+  // app rebuild stayed registered forever and kept receiving updates.
+  const release = () => {
+    const perWidget = widgetsByKey.get(key);
+    const props = perWidget && perWidget.get(widget);
+    if (!props) return;
+    props.delete(propName);
+    if (props.size === 0) perWidget.delete(widget);
+    if (perWidget.size === 0) widgetsByKey.delete(key);
   };
-};
 
-/**
- * Removes a specific widget from the automatic-update registry for a given key.
- *
- * @param {string} key - The state key the widget was registered under.
- * @param {Object} widget - The widget instance to unregister.
- * @returns {void}
- */
-export const unregisterWidget = (key, widget) => {
-  const widgets = widgetsByKey.get(key);
-  if (widgets) {
-    for (const item of widgets) {
-      if (item.widget === widget) {
-        widgets.delete(item);
-        break;
-      }
-    }
-  }
+  // The factory installs lifecycle hooks before it binds reactive props, so a
+  // widget reaching this point always owns `onUnmount`.
+  widget.onUnmount(release);
 };
 
 /**
@@ -110,43 +164,21 @@ export const unregisterWidget = (key, widget) => {
  */
 export const useState = (key, initialState, widget = null, propName = null) => {
   // Initialize the state in RamStore if it does not exist yet
-  let currentValue = getRam(key);
-  if (currentValue === undefined || currentValue === null) {
-    currentValue =
-      typeof initialState === "function" ? initialState() : initialState;
-    saveRam(key, currentValue);
+  const existing = getRam(key);
+  if (existing === undefined || existing === null) {
+    saveRam(
+      key,
+      typeof initialState === "function" ? initialState() : initialState,
+    );
   }
 
-  // Set up a single RamStore subscriber per key
-  if (!subscribers.has(key)) {
-    subscribers.set(key, new Set());
-
-    // Listen to RamStore changes for this key
-    const unsubscribe = subscribeRam((changedKey, newValue, oldValue) => {
-      if (changedKey === key) {
-        // 🔥 Push the new value to all registered widgets for this key
-        const widgets = widgetsByKey.get(key);
-        if (widgets) {
-          widgets.forEach(({ widget, propName }) => {
-            if (widget && widget.update) {
-              widget.update({ [propName]: newValue });
-            }
-          });
-        }
-
-        // Notify all subscriber callbacks
-        const callbacks = subscribers.get(key);
-        callbacks.forEach((callback) => callback(newValue, oldValue));
-
-        // Trigger a global re-render
-        triggerRender();
-      }
-    });
-
-    // Track the unsubscribe handle for hot-reload cleanup
-    if (!window._useStateCleanups) window._useStateCleanups = [];
-    window._useStateCleanups.push(unsubscribe);
-  }
+  // Register the key so the shared dispatcher knows it has listeners. Previously
+  // every key installed its OWN RamStore subscriber, and RamStore notifies all of
+  // them on every save — so one state change cost O(number of keys), each callback
+  // rejecting the key immediately. One dispatcher makes it O(1) + the work for the
+  // key that actually changed.
+  if (!subscribers.has(key)) subscribers.set(key, new Set());
+  ensureRamDispatcher();
 
   // 🔥 Register the widget for automatic updates if one was provided
   if (widget && propName) {
@@ -161,19 +193,18 @@ export const useState = (key, initialState, widget = null, propName = null) => {
    * @returns {void}
    */
   const setState = (newValueOrUpdater) => {
-    const oldValue = currentValue;
-    let newValue;
+    // Read the store rather than a value captured when the hook ran: a setter
+    // kept across renders would otherwise compare against a stale `oldValue` and
+    // skip the dispatch when an external `saveState` had already moved the key to
+    // the value being set — leaving the store, the widgets and the callbacks
+    // disagreeing about what the state is.
+    const oldValue = getRam(key);
+    const newValue =
+      typeof newValueOrUpdater === "function"
+        ? newValueOrUpdater(oldValue)
+        : newValueOrUpdater;
 
-    if (typeof newValueOrUpdater === "function") {
-      newValue = newValueOrUpdater(oldValue);
-    } else {
-      newValue = newValueOrUpdater;
-    }
-
-    if (oldValue !== newValue) {
-      currentValue = newValue;
-      saveRam(key, currentValue);
-    }
+    if (oldValue !== newValue) saveRam(key, newValue);
   };
 
   /**
@@ -188,24 +219,15 @@ export const useState = (key, initialState, widget = null, propName = null) => {
     }
     subscribers.get(key).add(callback);
     return () => {
-      if (subscribers.has(key)) {
-        subscribers.get(key).delete(callback);
-      }
+      subscribers.get(key)?.delete(callback);
     };
   };
 
-  // 🔥 Create a reactive value object so WidgetFactory can detect state bindings automatically
-  const reactiveValue = {
-    _isReactive: true,
-    _stateKey: key,
-    _value: currentValue,
-    valueOf() {
-      return this._value;
-    },
-    toString() {
-      return String(this._value);
-    },
-  };
+  // 🔥 A LIVE reactive value: reads the store on every access (so it never goes
+  // stale) and carries the key, so WidgetFactory can auto-bind any prop it is
+  // passed to. That binding is what makes a state change update **only the widget
+  // that uses it** instead of rebuilding the app.
+  const reactiveValue = createReactiveValue(() => getRam(key), key);
 
   // Return an array matching React's useState pattern: [value, setter, subscriber]
   return [reactiveValue, setState, subscribe];
@@ -224,7 +246,9 @@ export const useWatchState = (key, callback) => {
     subscribers.set(key, new Set());
   }
   subscribers.get(key).add(callback);
-  return () => subscribers.get(key).delete(callback);
+  return () => {
+    subscribers.get(key)?.delete(callback);
+  };
 };
 
 /**
@@ -242,6 +266,9 @@ export const cleanupUseState = () => {
   }
   subscribers.clear();
   widgetsByKey.clear();
+  resetStructuralReads();
+  // The dispatcher was unsubscribed above, so a later call must reinstall it.
+  ramDispatcherReady = false;
   globalRender = null;
   if (renderTimeout) clearTimeout(renderTimeout);
 };
@@ -250,12 +277,23 @@ export const cleanupUseState = () => {
  * Returns diagnostic statistics about the current state of the useState module.
  * Useful for debugging subscription leaks or widget registration issues.
  *
- * @returns {{ subscribersCount: number, widgetsCount: number, globalRender: boolean }}
+ * @returns {{ stateKeys: number, boundWidgets: number, watchers: number, globalRender: boolean }}
  */
 export const getUseStateStats = () => {
+  // `widgetsByKey` maps key -> widget -> prop names, so its size is the number of
+  // watched *keys*, not of widgets. Count one per widget.
+  let boundWidgets = 0;
+  let watchers = 0;
+  widgetsByKey.forEach((perWidget) => {
+    boundWidgets += perWidget.size;
+  });
+  subscribers.forEach((callbacks) => {
+    watchers += callbacks.size;
+  });
   return {
-    subscribersCount: subscribers.size,
-    widgetsCount: widgetsByKey.size,
+    stateKeys: subscribers.size,
+    boundWidgets,
+    watchers,
     globalRender: !!globalRender,
   };
 };

package/src/utils/getWidgetProps.js

@@ -10,7 +10,9 @@
  * // { text: 'Click', variant: 'filled', color: '#007aff' }
  */
 export const getWidgetProps = (widget) => {
-  return { ...(widget._props || {}) };
+  // The factory stores props in `_originalProps`. `_props` was never written by
+  // anything, so this always returned `{}` — Inspector printed no props at all.
+  return { ...(widget._originalProps || {}) };
 };
 
 /**
@@ -20,7 +22,7 @@ export const getWidgetProps = (widget) => {
  * @returns {any} Prop value or undefined
  */
 export const getWidgetProp = (widget, propName) => {
-  return widget._props ? widget._props[propName] : undefined;
+  return widget._originalProps ? widget._originalProps[propName] : undefined;
 };
 
 /**
@@ -29,7 +31,7 @@ export const getWidgetProp = (widget, propName) => {
  * @returns {string} Formatted props string
  */
 export const stringifyWidgetProps = (widget) => {
-  return JSON.stringify(widget._props || {}, null, 2);
+  return JSON.stringify(widget._originalProps || {}, null, 2);
 };
 
 export default { getWidgetProps, getWidgetProp, stringifyWidgetProps };