flet-box 1.0.3 → 1.0.5

package/src/widget-factory/assignProps.js

@@ -1,5 +1,6 @@
 // core/assignProps.js
 import { setStyles } from "./tools.js";
+import { resolveReactive } from "./reactiveValue.js";
 
 /**
  * Extracts the real value from a prop that may be a reactive accessor or a
@@ -14,15 +15,7 @@ import { setStyles } from "./tools.js";
  * @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;
-};
+const getValue = resolveReactive;
 
 /**
  * HTML attributes whose mere presence means "true". Writing them through
@@ -66,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;
+    }
   }
 };
 
@@ -79,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
@@ -110,7 +125,11 @@ export const assignProps = (widget, props) => {
     // ============================================================
     // 2. TEXT
     // ============================================================
-    if (props.textContent !== undefined) {
+    // `null` is `processProps`' sentinel for "this prop set carries no text".
+    // Only an explicitly present value (including "") may touch textContent:
+    // assigning null stringifies to "" and therefore REMOVES every child, which
+    // silently wiped widgets on any `update()` that did not re-pass `child`.
+    if (props.textContent !== undefined && props.textContent !== null) {
       const textValue = getValue(props.textContent);
       if (widget.tagName === "INPUT" || widget.tagName === "TEXTAREA") {
         if (widget.value !== textValue) widget.value = textValue;

package/src/widget-factory/processProps.js

@@ -1,6 +1,7 @@
 // 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";
 
 /**
  * Processes raw props and classifies them into:
@@ -26,8 +27,12 @@ export const processProps = (props, tag = "div", widgetName = null) => {
   // Derive widget name from tag (e.g., 'div' → 'Div', 'span' → 'Span')
   const name = widgetName || tag.charAt(0).toUpperCase() + tag.slice(1);
 
-  for (const [key, value] of Object.entries(props)) {
-    if (value === undefined || value === null) continue;
+  for (const [key, rawValue] of Object.entries(props)) {
+    if (rawValue === undefined || rawValue === null) continue;
+    // Resolve the reactive-prop protocol once, here. A live value must be READ
+    // now so `width: count` yields a number (and gets its px/rem unit), and a
+    // function must never reach a CSS assignment.
+    const value = resolveReactive(rawValue);
 
     // `style` is deliberately NOT part of the API: FletBox uses flat, aliased
     // CSS props. Fail loudly instead of silently ignoring the object.
@@ -48,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;
@@ -79,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();
@@ -98,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.
@@ -106,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

@@ -0,0 +1,172 @@
+/**
+ * @file reactiveValue.js
+ * @description
+ * The reactive-prop protocol shared by `useState`, the widget factory and the
+ * prop pipeline.
+ *
+ * A prop value may be a *reactive value*: an object or function flagged with
+ * `_isReactive` that reports the current value of a state key. The factory
+ * resolves it whenever the prop is applied, and — when the value carries a
+ * `_stateKey` — it also **subscribes** the widget to that key so a later change
+ * updates only this widget instead of re-rendering the whole app.
+ *
+ * Two shapes are supported:
+ *
+ *  - **Live** (what `useState` returns): a callable that reads the store on every
+ *    call. `valueOf`/`toString` also read live, so `${count}`, `count + 1` and
+ *    CSS assignment all get the current value.
+ *  - **Snapshot** (legacy): an object with a frozen `_value`. Still resolved, but
+ *    it cannot auto-subscribe because it has no live source.
+ *
+ * @module widget-factory/reactiveValue
+ */
+
+/**
+ * True while `resolveReactive` is reading a value on behalf of the factory.
+ *
+ * The distinction matters: a read the FACTORY performs (to fill a prop) is a
+ * direct binding, but a read the COMPONENT performs (`${count}`, `count > 3`,
+ * `count.valueOf()`) means the value also drives structure or computation, so the
+ * app has to re-run as well. Reconciling the two is what keeps
+ * `Text({ text: count })` surgical without breaking a sibling conditional.
+ */
+let resolving = false;
+
+/**
+ * Depth of the component-render pass, so reads in an event handler or a timer
+ * (which run outside the pass) do not mark a key as structurally read.
+ */
+let renderPassDepth = 0;
+
+/**
+ * Keys the component read structurally during the pass that just finished.
+ *
+ * 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.
+ */
+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 and publishes what it observed. */
+export const endRenderPass = () => {
+  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;
+};
+
+/**
+ * True when `val` is a reactive value (live or snapshot).
+ *
+ * @param {*} val
+ * @returns {boolean}
+ */
+export const isReactive = (val) => Boolean(val) && val._isReactive === true;
+
+/**
+ * The state key a reactive value is bound to, or `null` when it is not bound.
+ *
+ * @param {*} val
+ * @returns {string|null}
+ */
+export const reactiveKeyOf = (val) => (isReactive(val) ? val._stateKey ?? null : null);
+
+/**
+ * Resolves a reactive value to its current value. Plain values pass through.
+ *
+ * A live value is invoked, which is what makes it stay current: every time the
+ * prop is re-applied the store is read again. The read is flagged as a factory
+ * read so it is not mistaken for a structural one.
+ *
+ * @param {*} val
+ * @returns {*}
+ */
+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 = wasResolving;
+    }
+  }
+  if (val && typeof val === "object" && val._isReactive === true) {
+    return val._value !== undefined ? val._value : val.valueOf();
+  }
+  return val;
+};
+
+/**
+ * Builds the live reactive value returned by `useState`.
+ *
+ * It is a **function** (so `resolveReactive` calls it and always gets the
+ * current value) decorated with `valueOf`/`toString` (so template literals and
+ * 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 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.
+ * @returns {Function} The live reactive value.
+ */
+export const createReactiveValue = (read, key) => {
+  const live = () => {
+    const value = read();
+    if (!resolving && passKeys) passKeys.add(key);
+    return value;
+  };
+  live._isReactive = true;
+  live._stateKey = key;
+  live.valueOf = () => live();
+  live.toString = () => String(live());
+  Object.defineProperty(live, "_value", {
+    get: () => live(),
+    configurable: true,
+  });
+  return live;
+};
+
+export default {
+  isReactive,
+  reactiveKeyOf,
+  resolveReactive,
+  createReactiveValue,
+  isStructuralRead,
+  resetStructuralReads,
+  beginRenderPass,
+  endRenderPass,
+};