flet-box 1.0.4 → 1.0.6

package/src/tools/useState.js

@@ -1,6 +1,10 @@
 // src/tools/useState.js
 import { saveRam, getRam, subscribeRam } from "../services/RamStore.js";
-import { createReactiveValue, setImperativeReadListener } from "../widget-factory/reactiveValue.js";
+import {
+  createReactiveValue,
+  isStructuralRead,
+  resetStructuralReads,
+} from "../widget-factory/reactiveValue.js";
 
 // Store callbacks for each state key
 const subscribers = new Map();
@@ -8,13 +12,6 @@ const subscribers = new Map();
 // 🔥 Store widgets by state key for automatic updates
 const widgetsByKey = new Map();
 
-// Keys the component reads *structurally* — inside a template literal, a
-// conditional, a list. Those need the app render even when a widget is bound to
-// the key, because a surgical prop patch cannot change what the component
-// computes. A key passed straight into a prop is never listed here.
-const imperativeKeys = new Set();
-setImperativeReadListener((key) => imperativeKeys.add(key));
-
 // Global render function (set by runApp)
 let globalRender = null;
 let renderTimeout = null;
@@ -81,10 +78,10 @@ const ensureRamDispatcher = () => {
     // 2. Notify the manual subscribers.
     callbacks.forEach((callback) => callback(newValue, oldValue));
 
-    // 3. Re-render the app when nothing was bound, or when the component also
-    // reads this key structurally (a template literal, a conditional, a list):
-    // the surgical patch above cannot change what the component computes.
-    if (handled === 0 || imperativeKeys.has(changedKey)) triggerRender();
+    // 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") {
@@ -131,38 +128,21 @@ export const registerWidget = (key, widget, propName) => {
   if (already) return;
 
   // Release the binding through `onUnmount`, which the framework fires on BOTH
-  // teardown paths. Patching `_cleanup` here (the previous approach) leaked: the
+  // 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 map = widgetsByKey.get(key);
-    const props = map && map.get(widget);
+    const perWidget = widgetsByKey.get(key);
+    const props = perWidget && perWidget.get(widget);
     if (!props) return;
     props.delete(propName);
-    if (props.size === 0) map.delete(widget);
+    if (props.size === 0) perWidget.delete(widget);
+    if (perWidget.size === 0) widgetsByKey.delete(key);
   };
 
-  if (typeof widget.onUnmount === "function") {
-    widget.onUnmount(release);
-  } else {
-    const originalCleanup = widget._cleanup;
-    widget._cleanup = () => {
-      release();
-      if (originalCleanup) originalCleanup();
-    };
-  }
-};
-
-/**
- * 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 perWidget = widgetsByKey.get(key);
-  if (perWidget) perWidget.delete(widget);
+  // The factory installs lifecycle hooks before it binds reactive props, so a
+  // widget reaching this point always owns `onUnmount`.
+  widget.onUnmount(release);
 };
 
 /**
@@ -184,11 +164,12 @@ 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,
+    );
   }
 
   // Register the key so the shared dispatcher knows it has listeners. Previously
@@ -212,19 +193,18 @@ export const useState = (key, initialState, widget = null, propName = null) => {
    * @returns {void}
    */
   const setState = (newValueOrUpdater) => {
-    const oldValue = currentValue;
-    let newValue;
-
-    if (typeof newValueOrUpdater === "function") {
-      newValue = newValueOrUpdater(oldValue);
-    } else {
-      newValue = newValueOrUpdater;
-    }
-
-    if (oldValue !== newValue) {
-      currentValue = newValue;
-      saveRam(key, currentValue);
-    }
+    // 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 (oldValue !== newValue) saveRam(key, newValue);
   };
 
   /**
@@ -239,9 +219,7 @@ 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);
     };
   };
 
@@ -268,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);
+  };
 };
 
 /**
@@ -286,7 +266,7 @@ export const cleanupUseState = () => {
   }
   subscribers.clear();
   widgetsByKey.clear();
-  imperativeKeys.clear();
+  resetStructuralReads();
   // The dispatcher was unsubscribed above, so a later call must reinstall it.
   ramDispatcherReady = false;
   globalRender = null;
@@ -297,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/widget-factory/assignProps.js

@@ -59,6 +59,28 @@ const applySpecial = (widget, key, value) => {
     case "variant":
       widget.dataset.variant = val;
       break;
+    case "visible": {
+      // Hiding must not destroy the `display` the widget's own styles chose
+      // (`flex` for a Row, `inline-flex` for an Input…), so the previous inline
+      // value is stashed and handed back on show. The stash is only reused while
+      // we are still the reason the element is hidden: if an update set a new
+      // `display` in the meantime, that value is the truth and is left alone.
+      if (val) {
+        if (
+          widget._hiddenByVisibleProp !== undefined &&
+          widget.style.display === "none"
+        ) {
+          widget.style.display = widget._hiddenByVisibleProp;
+        }
+        delete widget._hiddenByVisibleProp;
+      } else if (widget.style.display !== "none") {
+        if (widget._hiddenByVisibleProp === undefined) {
+          widget._hiddenByVisibleProp = widget.style.display;
+        }
+        widget.style.display = "none";
+      }
+      break;
+    }
   }
 };
 
@@ -72,7 +94,7 @@ const applySpecial = (widget, key, value) => {
  *    `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`).
+ * 5. **special** – delegated to `applySpecial` (`value`, `variant`, `visible`).
  *
  * 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

package/src/widget-factory/processProps.js

@@ -1,5 +1,5 @@
 // core/processProps.js
-import { getPropDefinition, ATTRIBUTE_DOM_SET } from "./translateProps.js";
+import { getPropDefinition, ATTRIBUTE_DOM_SET, PASSTHROUGH_PREFIXES } from "./translateProps.js";
 import { toREM } from "./remTool.js"; // Centralized REM conversion utility
 import { resolveReactive } from "./reactiveValue.js";
 
@@ -53,6 +53,7 @@ export const processProps = (props, tag = "div", widgetName = null) => {
           // Shorthands may fan out to several CSS props (e.g. `px` →
           // paddingLeft + paddingRight). Everything else writes to its domProp.
           const cssValue = applyUnit(def, value);
+          if (cssValue === undefined) break;
           const targets = def.targets || [def.domProp];
           for (const target of targets) style[target] = cssValue;
           break;
@@ -84,7 +85,7 @@ export const processProps = (props, tag = "div", widgetName = null) => {
       }
     } else {
       // Unknown prop → intelligent fallback
-      if (key.startsWith("data-") || key.startsWith("aria-")) {
+      if (PASSTHROUGH_PREFIXES.some((prefix) => key.startsWith(prefix))) {
         attributes[key] = value;
       } else if (key.startsWith("on") && typeof value === "function") {
         const eventName = key.slice(2).toLowerCase();
@@ -103,6 +104,9 @@ export const processProps = (props, tag = "div", widgetName = null) => {
 /**
  * Applies the correct CSS unit to a numeric value based on the prop definition.
  *
+ * - A prop with `boolValues` maps `true`/`false` to the CSS the property
+ *   actually accepts (e.g. `wrap: true` → `flex-wrap: wrap`); an `undefined`
+ *   mapping skips the assignment.
  * - `true` / `false` are coerced to `1` / `0` (unitless).
  * - Non-numeric values pass through unchanged.
  * - `unit: "none"` returns the raw number without a suffix.
@@ -111,9 +115,12 @@ export const processProps = (props, tag = "div", widgetName = null) => {
  *
  * @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.
+ * @returns {string|number|undefined} Value with the correct CSS unit applied.
  */
 function applyUnit(def, value) {
+  if (def.boolValues && typeof value === "boolean") {
+    return def.boolValues[String(value)];
+  }
   if (value === true) return 1;
   if (value === false) return 0;
   if (typeof value !== "number") return value;

package/src/widget-factory/reactiveValue.js

@@ -38,28 +38,48 @@ let resolving = false;
  */
 let renderPassDepth = 0;
 
-/** Called with the state key when the component reads a reactive value. */
-let onImperativeRead = null;
-
 /**
- * Registers the listener told about structural reads. The state module uses it to
- * know which keys still need the app render in addition to the surgical patch.
+ * Keys the component read structurally during the pass that just finished.
  *
- * @param {(key: string) => void} listener
- * @returns {void}
+ * Rebuilt by every render pass: a component re-reads everything it consumes, so
+ * what the last pass saw is the complete picture. Keeping the keys of *earlier*
+ * passes instead would pin the app to full re-renders forever after one
+ * conditional read, which is exactly what the surgical binding exists to avoid.
  */
-export const setImperativeReadListener = (listener) => {
-  onImperativeRead = listener;
-};
+let structuralKeys = new Set();
+
+/** The keys collected by the pass currently running, or `null` between passes. */
+let passKeys = null;
 
 /** Marks the start of a component-render pass. */
 export const beginRenderPass = () => {
+  if (renderPassDepth === 0) passKeys = new Set();
   renderPassDepth++;
 };
 
-/** Marks the end of a component-render pass. */
+/** Marks the end of a component-render pass and publishes what it observed. */
 export const endRenderPass = () => {
-  if (renderPassDepth > 0) renderPassDepth--;
+  if (renderPassDepth === 0) return;
+  renderPassDepth--;
+  if (renderPassDepth === 0) {
+    if (passKeys) structuralKeys = passKeys;
+    passKeys = null;
+  }
+};
+
+/**
+ * True when the last render pass consumed `key` structurally, so a change to it
+ * needs an app render on top of the surgical prop patch.
+ *
+ * @param {string} key
+ * @returns {boolean}
+ */
+export const isStructuralRead = (key) => structuralKeys.has(key);
+
+/** Forgets every observed key. Used by hot-reload teardown. */
+export const resetStructuralReads = () => {
+  structuralKeys = new Set();
+  passKeys = renderPassDepth > 0 ? new Set() : null;
 };
 
 /**
@@ -90,11 +110,15 @@ export const reactiveKeyOf = (val) => (isReactive(val) ? val._stateKey ?? null :
  */
 export const resolveReactive = (val) => {
   if (typeof val === "function" && val._isReactive) {
+    // Save and restore instead of clearing: a reactive whose `valueOf` reads
+    // another one would otherwise leave the inner read flagged as the factory's
+    // and the outer one reported as a structural read.
+    const wasResolving = resolving;
     resolving = true;
     try {
       return val();
     } finally {
-      resolving = false;
+      resolving = wasResolving;
     }
   }
   if (val && typeof val === "object" && val._isReactive === true) {
@@ -111,9 +135,9 @@ export const resolveReactive = (val) => {
  * arithmetic work) and a `_value` getter (so the legacy `state._value` read
  * keeps working — now live instead of frozen).
  *
- * Every read that the component itself performs during a render pass is reported
- * through `onImperativeRead`, because such a read means the value is consumed
- * structurally and the app must re-render too.
+ * Every read that the component itself performs during a render pass is recorded
+ * in the pass's structural-key set, because such a read means the value is
+ * consumed structurally and the app must re-render too.
  *
  * @param {() => *} read - Reads the current value from the store.
  * @param {string} key - The state key this value is bound to.
@@ -122,7 +146,7 @@ export const resolveReactive = (val) => {
 export const createReactiveValue = (read, key) => {
   const live = () => {
     const value = read();
-    if (!resolving && renderPassDepth > 0 && onImperativeRead) onImperativeRead(key);
+    if (!resolving && passKeys) passKeys.add(key);
     return value;
   };
   live._isReactive = true;
@@ -141,7 +165,8 @@ export default {
   reactiveKeyOf,
   resolveReactive,
   createReactiveValue,
-  setImperativeReadListener,
+  isStructuralRead,
+  resetStructuralReads,
   beginRenderPass,
   endRenderPass,
 };