flet-box 1.1.1 → 1.1.3

package/src/widget-factory/widgetFactory.js

@@ -7,9 +7,16 @@ import { makeReactive } from "./reactivity.js";
 import { processProps } from "./processProps.js";
 import { assignProps } from "./assignProps.js";
 import { stackPosition } from "./stackPosition.js";
-import { addChildren, removePropChildren } from "./addChildren.js";
+import { addChildren, takePropChildren } from "./addChildren.js";
 import { reactiveKeyOf } from "./reactiveValue.js";
 import { registerWidget } from "../tools/useState.js";
+import {
+  FAILURE_ATTR,
+  clearFailure,
+  paintFailure,
+  renderFailure,
+  reportFailure,
+} from "../utils/errorBoundary.js";
 
 /**
  * Auto-binds reactive props to their state key.
@@ -117,22 +124,29 @@ export function WidgetFactory(tag, customProps = {}) {
   // ============================================================
   // 4. APPLY INITIAL PROPS
   // ============================================================
-  const initialProps = processProps(finalProps, finalTag, widgetName);
-  assignProps(widget, initialProps);
-  bindReactiveProps(widget, finalProps);
-  stackPosition(widget, finalProps);
+  // A throw inside a widget must not take the screen with it. The widget
+  // paints a placeholder in its own place — the rest of the tree keeps
+  // working — and the error is reported with this widget's name.
+  try {
+    const initialProps = processProps(finalProps, finalTag, widgetName);
+    assignProps(widget, initialProps);
+    bindReactiveProps(widget, finalProps);
+    stackPosition(widget, finalProps);
 
-  if (finalProps.child !== undefined) {
-    addChildren(widget, finalProps.child);
-  }
-  if (finalProps.children !== undefined) {
-    addChildren(widget, finalProps.children);
-  }
+    if (finalProps.child !== undefined) {
+      addChildren(widget, finalProps.child);
+    }
+    if (finalProps.children !== undefined) {
+      addChildren(widget, finalProps.children);
+    }
 
-  applyEffects(widget);
+    applyEffects(widget);
 
-  if (finalProps.ref && typeof finalProps.ref === "function") {
-    finalProps.ref(widget);
+    if (finalProps.ref && typeof finalProps.ref === "function") {
+      finalProps.ref(widget);
+    }
+  } catch (error) {
+    renderFailure(widget, error, { widgetName, phase: "render" });
   }
 
   // ============================================================
@@ -160,6 +174,12 @@ export function WidgetFactory(tag, customProps = {}) {
 
     updateDepth++;
     try {
+      // A previous failure painted a placeholder. This update may be the retry
+      // that fixes it, so the placeholder goes before the real content comes
+      // back.
+      const hadFailure = Boolean(widget._failureBox);
+      clearFailure(widget);
+
       // Normalize: never allow child AND children simultaneously
       const normalized = { ...newProps };
       // Reserved: `widgetName` labels the widget for Inspector and must never
@@ -190,9 +210,22 @@ export function WidgetFactory(tag, customProps = {}) {
       stackPosition(widget, merged);
 
       if (hasChild || hasChildren) {
-        removePropChildren(widget);
-        if (hasChild) addChildren(widget, newProps.child);
-        if (hasChildren) addChildren(widget, newProps.children);
+        // The old content comes out first, but it is kept: if attaching the new
+        // content throws, the widget goes back to what it had instead of being
+        // left empty.
+        const previous = takePropChildren(widget);
+        try {
+          if (hasChild) addChildren(widget, newProps.child);
+          if (hasChildren) addChildren(widget, newProps.children);
+        } catch (error) {
+          addChildren(widget, previous);
+          throw error;
+        }
+      } else if (hadFailure) {
+        // The build failed before the children were attached, so this update is
+        // the retry: they go in now.
+        if (merged.child !== undefined) addChildren(widget, merged.child);
+        if (merged.children !== undefined) addChildren(widget, merged.children);
       }
 
       applyEffects(widget);
@@ -200,6 +233,15 @@ export function WidgetFactory(tag, customProps = {}) {
       if (newProps.ref && typeof newProps.ref === "function") {
         newProps.ref(widget);
       }
+    } catch (error) {
+      // The widget keeps the content it had: a failed refresh is stale, not
+      // empty, and the screen must not blank over it.
+      const failure = reportFailure(error, { widgetName, phase: "update" });
+      widget.setAttribute(FAILURE_ATTR, "update");
+      // A widget with nothing in it is a hole; one that says it failed is not.
+      if (!widget.firstChild) {
+        paintFailure(widget, failure, { widgetName, phase: "update" });
+      }
     } finally {
       updateDepth--;
     }

package/src/widgets/Accordion.js

@@ -38,7 +38,7 @@ const ACCORDION_PROP_KEYS = [
  * @param {HTMLElement|HTMLElement[]} props.children - Content rendered inside the expanded panel.
  * @param {boolean} [props.expanded=false] - Whether the accordion starts in the expanded state.
  * @param {Function} [props.onPress] - Callback fired when the expanded state changes. Receives `(isExpanded: boolean)`.
- * @param {Function} [props.onToggle] - @deprecated Use `onPress` instead. Kept as alias for backward compatibility.
+ * @param {Function} [props.onToggle] - @deprecated Use `onPress` instead.
  * @param {'contained'|'outlined'|'ghost'} [props.variant='contained'] - Visual style variant.
  * @param {number} [props.borderRadius=8] - Corner radius in pixels.
  * @param {string} [props.bgColor=colors.primaryBg] - Background color of the container (used in 'contained' variant).
@@ -70,6 +70,7 @@ export const Accordion = (props) => {
     title,
     children,
     expanded = false,
+    /** @deprecated Use `onPress` instead — it receives the same boolean. */
     onToggle,
     onPress,
     variant = "contained", // 'contained', 'outlined', 'ghost'
@@ -154,6 +155,10 @@ export const Accordion = (props) => {
   let iconElement = null;
   let resizeObserver = null;
   let isAnimating = false;
+  // Pending animation timer ids — cancelled in onUnmount so the callbacks never
+  // fire on a widget that has already left the DOM.
+  let animTimer1 = null;
+  let animTimer2 = null;
 
   // ========== UI UPDATE FUNCTIONS ==========
 
@@ -317,13 +322,15 @@ export const Accordion = (props) => {
 
     // Animate from 0 → measured height → "auto" (to stay responsive to content changes)
     setHeight("0px");
-    setTimeout(() => {
+    animTimer1 = setTimeout(() => {
+      animTimer1 = null;
       setHeight(targetHeight);
-      setTimeout(() => {
+      animTimer2 = setTimeout(() => {
+        animTimer2 = null;
         setHeight("auto", true);
         contentWrapper.style.overflow = "visible";
         isAnimating = false;
-        const expandCb = onToggle || onPress;
+        const expandCb = onPress || onToggle;
         if (triggerCallback && expandCb) expandCb(true);
         updateUI();
       }, currentAnimationDuration);
@@ -351,15 +358,17 @@ export const Accordion = (props) => {
     contentWrapper.style.overflow = "hidden";
     setHeight(currentHeight);
 
-    setTimeout(() => {
+    animTimer1 = setTimeout(() => {
+      animTimer1 = null;
       setHeight("0px");
       isExpanded = false;
-      setTimeout(() => {
+      animTimer2 = setTimeout(() => {
+        animTimer2 = null;
         contentWrapper.style.display = "none";
         contentWrapper.style.overflow = "";
         contentInner.style.display = "";
         isAnimating = false;
-        const collapseCb = onToggle || onPress;
+        const collapseCb = onPress || onToggle;
         if (triggerCallback && collapseCb) collapseCb(false);
         updateUI();
       }, currentAnimationDuration);
@@ -608,6 +617,11 @@ export const Accordion = (props) => {
    * Registered through `onUnmount` so it runs on every teardown path.
    */
   container.onUnmount(() => {
+    // Cancel any in-flight animation timers so the callbacks never fire on a
+    // widget that has already left the DOM.
+    if (animTimer1 !== null) { clearTimeout(animTimer1); animTimer1 = null; }
+    if (animTimer2 !== null) { clearTimeout(animTimer2); animTimer2 = null; }
+    isAnimating = false;
     if (resizeObserver) resizeObserver.disconnect();
     if (contentWrapper && contentWrapper._cleanup) contentWrapper._cleanup();
   });

package/src/widgets/Badge.js

@@ -37,6 +37,12 @@ import { toREM } from "../utils/units.js";
  * @returns {HTMLElement} The wrapped Stack element, or the child element directly if the badge is hidden.
  */
 export const Badge = (props) => {
+  // Track whether the caller explicitly passed these color props, BEFORE
+  // defaults are applied — the theme subscription should only fire when the
+  // caller left the colors to the theme.
+  const callerPassedBgColor = props.bgColor !== undefined;
+  const callerPassedColor = props.color !== undefined;
+
   const {
     value,
     child,
@@ -134,8 +140,11 @@ export const Badge = (props) => {
   });
 
   // Subscribe to theme changes to keep the badge color in sync when no explicit
-  // bgColor/color was provided by the caller
-  if (!bgColor && !color) {
+  // bgColor/color was provided by the caller.
+  // FIX [BODY-1]: compare against the caller's original intent, not the
+  // post-default values — `bgColor` and `color` both have defaults, so
+  // `!bgColor && !color` was always false and the subscription never ran.
+  if (!callerPassedBgColor && !callerPassedColor) {
     unsubscribeTheme = subscribeTheme(() => {
       badgeElement.style.backgroundColor = colors.danger;
     });

package/src/widgets/Button.js

@@ -109,9 +109,17 @@ function buildButtonChildren(text, textColor, fontSize, gap, iconElements) {
   const middleRow = [];
   if (iconElements.left) middleRow.push(iconElements.left);
   if (text) {
-    middleRow.push(
-      Text({ text, color: textColor, size: fontSize, weight: "bold" }),
-    );
+    const label = Text({ text, color: textColor, size: fontSize, weight: "bold" });
+    // A button label is a label, not a paragraph. Left loose, a long one wraps
+    // to three lines inside a fixed-height pill: the text outgrows the padding
+    // box and the capsule's rounded ends cut into the words. One line with an
+    // ellipsis keeps the shape; the full string stays the accessible name. A
+    // block of copy that needs to wrap is a card or a list tile, not a button.
+    label.style.whiteSpace = "nowrap";
+    label.style.overflow = "hidden";
+    label.style.textOverflow = "ellipsis";
+    label.style.minWidth = "0";
+    middleRow.push(label);
   }
   if (iconElements.right) middleRow.push(iconElements.right);
 
@@ -124,6 +132,10 @@ function buildButtonChildren(text, textColor, fontSize, gap, iconElements) {
         alignItems: "center",
         justifyContent: "center",
         gap,
+        // Without this the row refuses to shrink below the label's intrinsic
+        // width and the ellipsis never engages inside a constrained button.
+        minWidth: 0,
+        maxWidth: "100%",
         child: middleRow,
       }),
     );

package/src/widgets/Carousel.js

@@ -279,11 +279,16 @@ export const Carousel = (props) => {
   updatePosition(false);
   updateDots();
 
-  // Autoplay setup
+  // Autoplay setup — start from onMount, not from construction.
+  // If the widget is built but never inserted into the DOM, setInterval would
+  // run forever because lifecycle's orphan-prune never fires unmount on a node
+  // that was never mounted. Hover listeners must follow the same path.
   if (autoPlay) {
-    startAutoPlay();
-    container.addEventListener("mouseenter", stopAutoPlay);
-    container.addEventListener("mouseleave", startAutoPlay);
+    container.onMount(() => {
+      startAutoPlay();
+      container.addEventListener("mouseenter", stopAutoPlay);
+      container.addEventListener("mouseleave", startAutoPlay);
+    });
   }
 
   // Public methods
@@ -295,6 +300,9 @@ export const Carousel = (props) => {
   // Cleanup
   container.onUnmount(() => {
     stopAutoPlay();
+    // Remove hover listeners regardless of whether onMount ran
+    container.removeEventListener("mouseenter", stopAutoPlay);
+    container.removeEventListener("mouseleave", startAutoPlay);
   });
 
   return container;

package/src/widgets/Chart.js

@@ -104,7 +104,9 @@ export const Chart = (props) => {
     ...rest
   } = props;
 
-  if (!data.length) return null;
+  // FIX [CHART-2]: returning null for empty data prevents updateData() from
+  // ever working — the container doesn't exist. Render an empty canvas instead.
+  // if (!data.length) return null;
 
   let canvasRef = null;
   let context = null;
@@ -230,7 +232,10 @@ export const Chart = (props) => {
       ctx.fillStyle = barColor;
       ctx.fillRect(x, Math.min(y, baselineY), barWidth, barHeight);
 
-      if (showValues && labels[index]) {
+      // FIX [CHART-2]: `showValues` was gated on `labels[index]` — so values
+      // were never drawn when no labels array was provided. Show values
+      // independently of labels.
+      if (showValues) {
         ctx.fillStyle = textColor;
         ctx.font = "8px sans-serif";
         ctx.fillText(value, x + barWidth / 2 - 5, y - 2);

package/src/widgets/Checkbox.js

@@ -11,6 +11,7 @@ import { TAP_MINIMUM, LABEL_TEXT } from "../tools/index.js";
 export const Checkbox = (props) => {
   const {
     checked = false,
+    /** @deprecated Use `onPress` instead — it receives the same boolean. */
     onCheck,
     onPress: onPressProp,
     disabled = false,
@@ -22,8 +23,6 @@ export const Checkbox = (props) => {
     ...rest
   } = props;
 
-  /** @deprecated Use onPress instead */
-  // onCheck kept as alias for backward compatibility
   const onPress = onPressProp || onCheck;
 
   let internalChecked = checked;

package/src/widgets/Chip.js

@@ -10,6 +10,7 @@ import { Row } from "./Row.js";
 import { Text } from "./Text.js";
 import { Icon } from "./Icon.js";
 import { colors } from "../utils/themes.js";
+import { readableInk } from "../utils/readableInk.js";
 import { PILL, TAP_MINIMUM } from "../tools/index.js";
 
 /**
@@ -40,6 +41,12 @@ export const Chip = (props) => {
     onDelete,
     variant = "filled",
     color = colors.primary,
+    // The chip's own plate. It has to be taken out of `props` here: left in, it
+    // travels through `...rest` onto the outer wrapper — and the wrapper is the
+    // 40-unit tap target with no radius, so a chip that named its background
+    // painted a rectangle of it behind the pill.
+    bgColor,
+    backgroundColor,
     textColor,
     borderColor,
     borderRadius = PILL,
@@ -67,19 +74,25 @@ export const Chip = (props) => {
         ? { paddingVertical: padding, paddingHorizontal: padding * 2 }
         : { padding };
 
-  // Derive background, text, and border colors from the variant
-  let bgColor, txtColor, brdColor;
+  // Derive background, text, and border colors from the variant. A filled chip
+  // takes the plate its caller named; an outlined one keeps the variant's
+  // contract and stays transparent, the same answer `Button` gives when a
+  // `bgColor` is handed to `variant: "outlined"`. Either way the name is consumed
+  // here, so it never reaches the wrapper and paints a square plate.
+  const plate = bgColor || backgroundColor;
+  let pillColor, txtColor, brdColor;
 
   if (variant === "outlined") {
-    bgColor = "transparent";
+    pillColor = "transparent";
     txtColor = textColor || color;
     brdColor = borderColor || color;
   } else {
-    bgColor = color;
-    // The label sits on the primary plate, so its ink is the theme's, not a
-    // literal white: in dark mode a primary chip is near-white and white words
-    // would vanish.
-    txtColor = textColor || colors.onPrimary;
+    pillColor = plate || color;
+    // The label sits on the plate, so its ink follows the plate. On the default
+    // primary that is the theme's ink — in dark mode a primary chip is near-white
+    // and white words would vanish — and once the caller names a pale plate,
+    // picking the readable ink is what stops the label disappearing again.
+    txtColor = textColor || (plate ? readableInk(plate, colors.text) : colors.onPrimary);
     brdColor = "transparent";
   }
 
@@ -131,7 +144,7 @@ export const Chip = (props) => {
   const chipContent = Row({
     alignItems: "center",
     gap: gap,
-    backgroundColor: bgColor,
+    backgroundColor: pillColor,
     border: variant === "outlined" ? `1px solid ${brdColor}` : "none",
     borderRadius: borderRadius,
     ...chipPadding,
@@ -175,7 +188,8 @@ export const Chip = (props) => {
       if (variant === "filled") {
         chip.style.opacity = "1";
       } else if (chipContent) {
-        chipContent.style.backgroundColor = "transparent";
+        // Leaving restores the chip's own plate, which is not always transparent.
+        chipContent.style.backgroundColor = pillColor;
       }
     });
   }

package/src/widgets/CircularBar.js

@@ -125,9 +125,11 @@ export const CircularBar = (props) => {
 
   const getFormattedValue = () => {
     if (customValueFormatter) return customValueFormatter(currentValue, max);
+    // Guard: max === 0 would produce Infinity or NaN in every branch.
+    const safeMax = max > 0 ? max : 1;
     if (valueFormat === "percent") {
       const percent =
-        Math.round((currentValue / max) * 100 * Math.pow(10, valueDecimals)) /
+        Math.round((currentValue / safeMax) * 100 * Math.pow(10, valueDecimals)) /
         Math.pow(10, valueDecimals);
       return `${valuePrefix}${percent}${valueSuffix}`;
     }
@@ -243,7 +245,9 @@ export const CircularBar = (props) => {
   const drawStatic = () => {
     if (!ctx || !canvas) return;
     currentValue = value;
-    const angle = (value / max) * Math.PI * 2;
+    // Guard: max === 0 would produce Infinity radians → canvas draws nothing.
+    const safeMax = max > 0 ? max : 1;
+    const angle = (value / safeMax) * Math.PI * 2;
     ctx.clearRect(0, 0, currentWidth, currentWidth);
     drawBackground();
     drawProgress(angle);
@@ -261,7 +265,9 @@ export const CircularBar = (props) => {
     const elapsed = timestamp - startTime;
     const progress = Math.min(1, elapsed / animationDuration);
     currentValue = progress * value;
-    const angle = (currentValue / max) * Math.PI * 2;
+    // Guard: max === 0 → Infinity radians.
+    const safeMax = max > 0 ? max : 1;
+    const angle = (currentValue / safeMax) * Math.PI * 2;
     ctx.clearRect(0, 0, currentWidth, currentWidth);
     drawBackground();
     drawProgress(angle);

package/src/widgets/CircularChart.js

@@ -289,9 +289,11 @@ export const CircularChart = (props) => {
       ctx.font = `${labelSize}px system-ui`;
       ctx.fillStyle = labelInk(color);
       ctx.shadowBlur = 0;
-      const percent = Math.round(
-        (slice.value / (slice.end - slice.start)) * 100,
-      );
+      // FIX [CC-2]: percent was computed as value / (end-start) * 100, which
+      // divides by the slice's radian angle (~0.002 for small slices) and gives
+      // nonsense like 4775%. Divide by the total instead.
+      const total = data.reduce((s, d) => s + (d?.value || 0), 0);
+      const percent = total > 0 ? Math.round((slice.value / total) * 100) : 0;
       ctx.fillText(slice.original?.label || `${percent}%`, x, y);
     }
   };

package/src/widgets/Container.js

@@ -13,6 +13,7 @@ export const Container = (props = {}) => {
     overflow = "auto",
     boxSizing = "border-box",
     bgColor = colors.surface,
+    expand,
     flex,
     flexGrow,
     flexShrink,
@@ -28,6 +29,10 @@ export const Container = (props = {}) => {
       ? { flexShrink: 0 }
       : { flex, flexGrow, flexShrink };
 
+  // FIX [CONTAINER-1]: `expand` was documented but never applied.
+  // It maps to `flex: 1` so the container fills available space in its parent.
+  const expandProps = expand ? { flex: 1, flexShrink: 1 } : {};
+
   return WidgetFactory({
     tag: "div",
     widgetName: "Container",
@@ -37,6 +42,7 @@ export const Container = (props = {}) => {
     boxSizing: boxSizing,
     backgroundColor: bgColor,
     ...flexDefaults,
+    ...expandProps,
     ...rest,
   });
 };

package/src/widgets/Divider.js

@@ -7,7 +7,9 @@ import { colors } from "../utils/themes.js";
 
 export const Divider = (props = {}) => {
   const {
-    color = colors.surface,
+    // FIX [DIVIDER-1]: default was `colors.surface` — same color as the
+    // background — making every divider invisible unless explicitly colored.
+    color = colors.border,
     thickness = 1,
     margin = 16,
     orientation = "horizontal",

package/src/widgets/DraggBox.js

@@ -110,6 +110,15 @@ export const DraggBox = (props) => {
     if (onDragEnd) onDragEnd(e, data);
   });
 
+  // FIX [DRAGBOX-1]: if the widget is unmounted while a drag is in progress,
+  // `dragend` never fires and the clone stays in document.body forever.
+  wrapper.onUnmount(() => {
+    if (dragClone && dragClone.parentNode) {
+      dragClone.parentNode.removeChild(dragClone);
+      dragClone = null;
+    }
+  });
+
   return wrapper;
 };
 

package/src/widgets/Dropdown.js

@@ -60,8 +60,8 @@ export const Dropdown = (inputProps = {}) => {
   const {
     options = [],
     value = null,
+    /** @deprecated Use `onPress` instead — it receives the same value. */
     onChange,
-    /** @deprecated Use onPress instead */
     onPress: onPressProp,
     placeholder = "Select...",
     disabled = false,
@@ -276,7 +276,7 @@ export const Dropdown = (inputProps = {}) => {
         alignItems: "center",
         gap: 8,
         // minWidth: 0 para que un texto largo ENCOJA y no empuje al icono: sin
-        // él, el span no puede bajar de su ancho de contenido y el
+        // el span cannot shrink below its content width and the
         // expand_more sale del selector.
         flex: 1,
         minWidth: 0,
@@ -286,7 +286,7 @@ export const Dropdown = (inputProps = {}) => {
       // width "100%" por defecto, y con eso este bloque se apropiaba de casi
       // todo el ancho del selector: al no llevar justifyContent, el glifo
       // quedaba anclado a su borde izquierdo, pegado al texto, en vez de
-      // apartado a la derecha. flexShrink 0 evita además que se apriete cuando
+      // the right side. flexShrink 0 additionally prevents squeezing when
       // el texto es largo.
       Row({
         alignItems: "center",

package/src/widgets/DroppBox.js

@@ -149,6 +149,11 @@ export const DroppBox = (props) => {
     if (disabled) return;
     e.preventDefault();
 
+    // FIX [DROPBOX-1]: `dragleave` fires when the pointer moves onto a child
+    // element inside the drop zone. `relatedTarget` is the element being entered
+    // next; if it is still inside this wrapper the drag hasn't really left.
+    if (wrapper.contains(e.relatedTarget)) return;
+
     if (isActive) {
       isActive = false;
       removeActiveStyles();

package/src/widgets/FloatingActionButton.js

@@ -47,7 +47,7 @@ export const FloatingActionButton = (props) => {
     children.push(
       Text({
         // FIX: `value` es special y `applySpecial` solo lo aplica en inputs
-        // → en un <span> no hacía nada y el label quedaba vacío.
+        // a span did nothing and the label stayed empty.
         text: label,
         size: 14,
         fontWeight: "500",

package/src/widgets/Icon.js

@@ -13,6 +13,10 @@ export const Icon = (props) => {
     name,
     size = 24,
     color = colors.textSecondary,
+    // FIX [ICON-1]: extract className from rest so it can be merged with
+    // `material-icons` instead of replacing it. An app that passes className
+    // to add a custom style would otherwise break the ligature entirely.
+    className: extraClassName,
     ...rest
   } = props;
   const iconName = icon || name || "";
@@ -35,7 +39,7 @@ export const Icon = (props) => {
   return WidgetFactory({
     tag: "span",
     widgetName: "Icon",
-    className: "material-icons",
+    className: extraClassName ? `material-icons ${extraClassName}` : "material-icons",
     text: iconName, // ✅ CHANGED: text instead of textContent
     fontSize: toREM(size),
     color: color,

package/src/widgets/InstallButton.js

@@ -35,11 +35,13 @@ export const InstallButton = (props) => {
     if (deferredPrompt) {
       deferredPrompt.prompt();
       const { outcome } = await deferredPrompt.userChoice;
+      deferredPrompt = null;
       if (outcome === "accepted") {
-        if (onInstalled) onInstalled();
+        // FIX [INSTALL-1]: do NOT call onInstalled here — the browser fires
+        // `appinstalled` right after acceptance, and handleAppInstalled calls it
+        // there. Calling it in both places caused the double-fire.
         hideButton();
       }
-      deferredPrompt = null;
     }
     if (onClick) onClick();
   };