flet-box 1.1.2 → 1.1.3

package/src/widgets/Menu.js

@@ -0,0 +1,340 @@
+/**
+ * @file Menu.js
+ * @description A trigger that opens an anchored menu of actions (kebab menu).
+ */
+import { colors } from "../utils/themes.js";
+import { composeUpdate } from "../utils/composeUpdate.js";
+import { Container } from "./Container.js";
+import { Row } from "./Row.js";
+import { Column } from "./Column.js";
+import { Text } from "./Text.js";
+import { Icon } from "./Icon.js";
+import { Button } from "./Button.js";
+import { TAP_MINIMUM } from "../tools/index.js";
+import { trapFocus } from "../utils/focusScope.js";
+
+/**
+ * Props owned by the closure. They are routed to `update()` and never to the
+ * factory: `items` is an array of records, not something the DOM can receive.
+ */
+const MENU_PROP_KEYS = ["items", "disabled", "label"];
+
+/** The panel is a portal on `document.body`, so the trigger points at it by id. */
+let menuIdSeed = 0;
+
+/**
+ * A kebab (or any icon) trigger with a menu of actions. It is the widget a row
+ * uses for "rename / delete" without spending two permanent buttons on it.
+ *
+ * The panel is a real menu, not a list of links: the trigger keeps the Tab stop
+ * and the arrow keys move focus through `role="menuitem"` rows. `Escape` closes
+ * and returns focus; `Tab` closes and lets the page continue. Every listener it
+ * adds is released when the widget unmounts.
+ */
+export const Menu = (inputProps = {}) => {
+  const {
+    items = [],
+    label = "Open menu",
+    icon = "more_vert",
+    width = 200,
+    align = "end",
+    disabled = false,
+    portal = true,
+    bgColor = colors.surface,
+    borderRadius = 8,
+    size = TAP_MINIMUM,
+    ...rest
+  } = inputProps;
+
+  let currentItems = Array.isArray(items) ? [...items] : [];
+  let currentLabel = String(label);
+  let currentDisabled = Boolean(disabled);
+  let isOpen = false;
+  let panel = null;
+  let itemNodes = [];
+  let outsideClickListener = null;
+  let positionListener = null;
+  let releaseFocus = null;
+
+  const baseId =
+    typeof rest.id === "string" && rest.id ? rest.id : `fletbox-menu-${++menuIdSeed}`;
+  const panelId = `${baseId}-panel`;
+
+  const trigger = Button({
+    icon,
+    variant: "text",
+    width: size,
+    height: size,
+    padding: 8,
+    borderRadius,
+    color: colors.textSecondary,
+    bgColor: "transparent",
+    "aria-label": currentLabel,
+    "aria-haspopup": "menu",
+    "aria-expanded": "false",
+    onPress: () => {
+      if (isOpen) closeMenu(true);
+      else openMenu();
+    },
+  });
+
+  const root = Container({
+    widgetName: "Menu",
+    position: "relative",
+    width: "auto",
+    display: "inline-flex",
+    bgColor: "transparent",
+    ...rest,
+    children: [trigger],
+  });
+
+  const enabledNodes = () =>
+    itemNodes.filter((node) => node.getAttribute("aria-disabled") !== "true");
+
+  const focusNode = (node) => {
+    if (node) node.focus();
+  };
+
+  /** Close first, then run the action: a modal opened by the action takes the
+   *  focus after the trigger has already got it back. */
+  const activate = (index) => {
+    const item = currentItems[index];
+    if (!item || item.disabled || currentDisabled) return;
+    closeMenu(true);
+    item.onPress?.();
+  };
+
+  const buildPanel = () => {
+    const node = Column({
+      id: panelId,
+      role: "menu",
+      "aria-label": currentLabel,
+      zIndex: 10000,
+      width,
+      maxHeight: 320,
+      padding: 4,
+      gap: 4,
+      overflow: "auto",
+      bgColor,
+      border: `1px solid ${colors.border}`,
+      borderRadius,
+      boxShadow: "0 12px 32px rgba(15,23,42,0.16)",
+      boxSizing: "border-box",
+    });
+
+    currentItems.forEach((item, index) => {
+      const danger = Boolean(item.danger);
+      const itemDisabled = Boolean(item.disabled) || currentDisabled;
+      const ink = danger ? colors.dangerStrong : colors.text;
+      const row = Row({
+        role: "menuitem",
+        tabIndex: -1,
+        // A menu item is reached with the arrows, never with Tab: the trigger is
+        // the control, and the panel is a list of actions it owns.
+        "aria-disabled": itemDisabled ? "true" : undefined,
+        minHeight: TAP_MINIMUM,
+        paddingVertical: 8,
+        paddingHorizontal: 12,
+        gap: 8,
+        borderRadius: 4,
+        alignItems: "center",
+        cursor: itemDisabled ? "not-allowed" : "pointer",
+        opacity: itemDisabled ? 0.5 : 1,
+        disableTransform: true,
+        bgColor: "transparent",
+        onclick: itemDisabled ? undefined : () => activate(index),
+        children: [
+          item.icon
+            ? Icon({
+                name: item.icon,
+                size: 18,
+                color: danger ? colors.dangerStrong : colors.textSecondary,
+              })
+            : null,
+          Text({
+            text: item.text || "",
+            size: 14,
+            color: ink,
+            flex: 1,
+            minWidth: 0,
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+            whiteSpace: "nowrap",
+          }),
+        ].filter(Boolean),
+      });
+      row.onmouseenter = () => {
+        if (!itemDisabled) row.style.backgroundColor = colors.border;
+      };
+      row.onmouseleave = () => {
+        row.style.backgroundColor = "transparent";
+      };
+      node.appendChild(row);
+      itemNodes.push(row);
+    });
+
+    return node;
+  };
+
+  /** The panel is measured in px because it is already laid out: this is the
+   *  one place a pixel is the truth (viewport geometry), not a frozen size. */
+  const positionPanel = () => {
+    if (!panel) return;
+    const rect = trigger.getBoundingClientRect();
+    const panelRect = panel.getBoundingClientRect();
+    const left =
+      align === "end" ? rect.right - panelRect.width : rect.left;
+    const topCandidate = rect.bottom + 4;
+    const fitsBelow = topCandidate + panelRect.height <= window.innerHeight - 8;
+    const top = fitsBelow
+      ? topCandidate
+      : Math.max(8, rect.top - panelRect.height - 4);
+    panel.style.position = "fixed";
+    panel.style.left = `${Math.max(8, Math.min(left, window.innerWidth - panelRect.width - 8))}px`;
+    panel.style.top = `${Math.max(8, Math.min(top, window.innerHeight - 8))}px`;
+  };
+
+  const onPanelKeyDown = (event) => {
+    const nodes = enabledNodes();
+    const index = nodes.indexOf(document.activeElement);
+
+    if (event.key === "Escape") {
+      event.preventDefault();
+      event.stopPropagation();
+      closeMenu(true);
+      return;
+    }
+    if (event.key === "Tab") {
+      // Release before the trap's own listener reads the key: a menu closes on
+      // Tab, it does not keep the reader inside a panel they asked to leave.
+      if (releaseFocus) {
+        releaseFocus();
+        releaseFocus = null;
+      }
+      closeMenu(false);
+      return;
+    }
+    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+      if (!nodes.length) return;
+      event.preventDefault();
+      const step = event.key === "ArrowDown" ? 1 : -1;
+      const next = index < 0
+        ? (step > 0 ? 0 : nodes.length - 1)
+        : (index + step + nodes.length) % nodes.length;
+      focusNode(nodes[next]);
+      return;
+    }
+    if (event.key === "Home") {
+      event.preventDefault();
+      focusNode(nodes[0]);
+      return;
+    }
+    if (event.key === "End") {
+      event.preventDefault();
+      focusNode(nodes[nodes.length - 1]);
+    }
+  };
+
+  const openMenu = () => {
+    if (currentDisabled || isOpen) return;
+    isOpen = true;
+    panel = buildPanel();
+    if (portal) document.body.appendChild(panel);
+    else root.appendChild(panel);
+    positionPanel();
+    // The panel holds Tab while it is open and gives focus back on close; this
+    // is the same scope the three overlays use, not a second listener.
+    releaseFocus = trapFocus(panel);
+    // Capture: the Tab branch above has to release the trap before the trap's
+    // own listener runs, or the browser swallows the key and the panel closes
+    // without the focus moving on.
+    panel.addEventListener("keydown", onPanelKeyDown, true);
+
+    trigger.setAttribute("aria-expanded", "true");
+    trigger.setAttribute("aria-controls", panelId);
+    focusNode(enabledNodes()[0]);
+
+    outsideClickListener = (event) => {
+      if (root.contains(event.target)) return;
+      if (panel && panel.contains(event.target)) return;
+      closeMenu(false);
+    };
+    positionListener = () => positionPanel();
+    document.addEventListener("click", outsideClickListener);
+    window.addEventListener("resize", positionListener);
+    window.addEventListener("scroll", positionListener, true);
+  };
+
+  const closeMenu = (returnFocus) => {
+    if (!isOpen) return;
+    isOpen = false;
+    if (panel) {
+      panel.removeEventListener("keydown", onPanelKeyDown, true);
+      panel.remove();
+    }
+    panel = null;
+    itemNodes = [];
+    if (releaseFocus) {
+      releaseFocus();
+      releaseFocus = null;
+    }
+    trigger.setAttribute("aria-expanded", "false");
+    trigger.removeAttribute("aria-controls");
+    if (outsideClickListener) {
+      document.removeEventListener("click", outsideClickListener);
+      outsideClickListener = null;
+    }
+    if (positionListener) {
+      window.removeEventListener("resize", positionListener);
+      window.removeEventListener("scroll", positionListener, true);
+      positionListener = null;
+    }
+    if (returnFocus) trigger.focus();
+  };
+
+  // ArrowDown/ArrowUp open the menu from the trigger, the way a native menu
+  // button does. Enter and Space are the engine's own press path.
+  const onTriggerKeyDown = (event) => {
+    if (event.target !== trigger || currentDisabled || isOpen) return;
+    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+      event.preventDefault();
+      openMenu();
+      const nodes = enabledNodes();
+      focusNode(event.key === "ArrowDown" ? nodes[0] : nodes[nodes.length - 1]);
+    }
+  };
+  trigger.addEventListener("keydown", onTriggerKeyDown);
+
+  const update = (newProps) => {
+    if (newProps.items !== undefined) {
+      currentItems = Array.isArray(newProps.items) ? [...newProps.items] : [];
+      if (isOpen) {
+        closeMenu(false);
+        openMenu();
+      }
+    }
+    if (newProps.label !== undefined) {
+      currentLabel = String(newProps.label);
+      trigger.setAttribute("aria-label", currentLabel);
+    }
+    if (newProps.disabled !== undefined) {
+      currentDisabled = Boolean(newProps.disabled);
+      trigger.update({ disabled: currentDisabled });
+      if (currentDisabled) closeMenu(false);
+    }
+  };
+
+  composeUpdate(root, MENU_PROP_KEYS, update);
+
+  root.open = openMenu;
+  root.close = () => closeMenu(false);
+
+  root.onUnmount(() => {
+    closeMenu(false);
+    trigger.removeEventListener("keydown", onTriggerKeyDown);
+  });
+
+  return root;
+};
+
+export default Menu;

package/src/widgets/Modal.js

@@ -468,6 +468,10 @@ export const Modal = (props = {}) => {
   });
 
   // Public API
+  // FIX [MODAL-3]: track the "live" content so setLoading(false) restores
+  // whatever updateContent last set, not the original construction value.
+  let currentContent = content;
+
   const instance = {
     open: handleOpen,
     close: handleClose,
@@ -484,6 +488,8 @@ export const Modal = (props = {}) => {
 
     // Methods for dynamic updates
     updateContent: (newContent) => {
+      // Track the most recent content so setLoading(false) can restore it
+      currentContent = newContent;
       if (contentElement) {
         while (contentElement.firstChild) {
           contentElement.removeChild(contentElement.firstChild);
@@ -548,7 +554,7 @@ export const Modal = (props = {}) => {
 
         instance.updateContent(loadingEl);
       } else {
-        instance.updateContent(content);
+        instance.updateContent(currentContent);
       }
     },
   };

package/src/widgets/Pagination.js

@@ -28,7 +28,12 @@ export const Pagination = (props) => {
     ...rest
   } = props;
 
-  const totalPages = Math.ceil(totalItems / pageSize);
+  // FIX [PAGINATION-1]: pageSize:0 → division by zero → totalPages=Infinity.
+  // maxButtons:0 → getPageNumbers returns [] but the ellipsis logic still adds
+  // boundary buttons. Guard both.
+  const safePageSize = pageSize > 0 ? pageSize : 1;
+  const safeMaxButtons = maxButtons > 0 ? maxButtons : 1;
+  const totalPages = Math.ceil(totalItems / safePageSize);
   if (totalPages <= 1) return null;
 
   let current = Math.min(Math.max(currentPage, 1), totalPages);
@@ -43,11 +48,11 @@ export const Pagination = (props) => {
 
   const getPageNumbers = () => {
     const pages = [];
-    let start = Math.max(1, current - Math.floor(maxButtons / 2));
-    let end = Math.min(totalPages, start + maxButtons - 1);
+    let start = Math.max(1, current - Math.floor(safeMaxButtons / 2));
+    let end = Math.min(totalPages, start + safeMaxButtons - 1);
 
-    if (end - start + 1 < maxButtons) {
-      start = Math.max(1, end - maxButtons + 1);
+    if (end - start + 1 < safeMaxButtons) {
+      start = Math.max(1, end - safeMaxButtons + 1);
     }
 
     for (let i = start; i <= end; i++) {

package/src/widgets/ProgressBar.js

@@ -28,7 +28,8 @@ export const ProgressBar = (props) => {
   } = props;
 
   let progressValue = Math.min(Math.max(value, 0), max);
-  let percentage = (progressValue / max) * 100;
+  // Guard against max === 0 to avoid NaN% in the fill and the aria attribute.
+  let percentage = max > 0 ? (progressValue / max) * 100 : 0;
   const finalBorderRadius =
     borderRadius !== undefined ? borderRadius : height / 2;
   const isColumn = valuePosition === "top" || valuePosition === "bottom";
@@ -122,8 +123,8 @@ export const ProgressBar = (props) => {
 
   // Value percentage.
   // FIX: guardo referencia directa al span del valor (`valueElRef`) en vez de
-  // buscarlo con `querySelector("span:last-child")` — la versión anterior
-  // podía escribir el porcentaje dentro del label (si el label estaba a la
+  // querySelector("span:last-child") - the old version could
+  // write the percentage inside the label (if the label was at the
   // derecha, era el último span) y el check `valueEl !== label` nunca fallaba
   // porque `label` era un string.
   let valueElRef = null;
@@ -174,7 +175,7 @@ export const ProgressBar = (props) => {
   const updateProgress = (newValue) => {
     if (indeterminate) return;
     progressValue = Math.min(Math.max(newValue, 0), max);
-    percentage = (progressValue / max) * 100;
+    percentage = max > 0 ? (progressValue / max) * 100 : 0;
     fill.style.width = `${percentage}%`;
     // The announced number has to be the drawn number: a reader kept on the build
     // value would hear "0%" while the bar filled.

package/src/widgets/QRCode.js

@@ -216,6 +216,10 @@ function buildQRMatrix(text, ecLevel = "M") {
     for (let aj = 0; aj < ap.length; aj++) {
       const r = ap[ai], c = ap[aj];
       if (reserved[r][c]) continue; // skip if overlaps finder
+      // FIX [QR-2]: also skip patterns centred on timing rows/cols (row 6 or
+      // col 6). An alignment pattern centred at (6,x) or (x,6) would corrupt
+      // the timing pattern. ISO 18004 §7.3.6 excludes those positions.
+      if (r === 6 || c === 6) continue;
       for (let dr = -2; dr <= 2; dr++) {
         for (let dc = -2; dc <= 2; dc++) {
           const v = (Math.abs(dr) === 2 || Math.abs(dc) === 2) ? 1

package/src/widgets/Radio.js

@@ -10,6 +10,7 @@ import { TAP_MINIMUM, LABEL_TEXT } from "../tools/index.js";
 export const Radio = (props) => {
   const {
     selected = false,
+    /** @deprecated Use `onPress` instead — it receives the same boolean. */
     onSelect,
     onPress: onPressProp,
     disabled = false,
@@ -20,8 +21,6 @@ export const Radio = (props) => {
     ...rest
   } = props;
 
-  /** @deprecated Use onPress instead */
-  // onSelect kept as alias for backward compatibility
   const onPress = onPressProp || onSelect;
 
   let internalSelected = selected;

package/src/widgets/Rating.js

@@ -8,6 +8,7 @@ import { Text } from "./Text.js";
 import { Icon } from "./Icon.js";
 import { colors, subscribeTheme } from "../utils/themes.js";
 import { TAP_MINIMUM } from "../tools/index.js";
+import { composeUpdate } from "../utils/composeUpdate.js";
 
 export const Rating = (props) => {
   const {
@@ -355,6 +356,14 @@ export const Rating = (props) => {
   ratingContainer.getValue = () => currentValue;
   ratingContainer.updateStars = updateStars;
 
+  // FIX [RATING-1]: expose `update({value})` via composeUpdate so the checker's
+  // no-update-overwrite rule is satisfied and `rating.update({value: 3})` works.
+  const RATING_PROP_KEYS = ["value"];
+  const ratingUpdate = (newProps) => {
+    if (newProps.value !== undefined) setValue(newProps.value);
+  };
+  composeUpdate(ratingContainer, RATING_PROP_KEYS, ratingUpdate);
+
   Object.defineProperty(ratingContainer, "value", {
     get: () => currentValue,
     set: (newValue) => setValue(newValue),

package/src/widgets/Slider.js

@@ -415,7 +415,10 @@ export const Slider = (props) => {
     }
     if (inverted) percent = 1 - percent;
     let raw = currentMin + percent * (currentMax - currentMin);
-    let stepped = Math.round(raw / currentStep) * currentStep;
+    // FIX [SLIDER-3]: snap relative to `min`, not to zero.
+    // `Math.round(raw / step) * step` snapped to 0, step, 2*step, …
+    // For min=1, step=2 that gave 2, 4, 6 instead of 1, 3, 5.
+    let stepped = Math.round((raw - currentMin) / currentStep) * currentStep + currentMin;
     return Math.min(Math.max(stepped, currentMin), currentMax);
   }
 

package/src/widgets/SnackBar.js

@@ -10,7 +10,7 @@ import { readableInk } from "../utils/readableInk.js";
 import { toREM } from "../utils/units.js";
 
 /**
- * SnackBar - Notificación temporal
+ * SnackBar - Temporary notification
  * @param {Object} options
  * @returns {Object} { close, show, getElement }
  */
@@ -84,7 +84,7 @@ export function SnackBar(options) {
   const finalAction =
     customAction || (customBg ? finalText : preset.action);
 
-  // Createste main container
+  // Creates the main container
   const snackbar = WidgetFactory({
     tag: "div",
     position: "fixed",

package/src/widgets/Switch.js

@@ -11,6 +11,7 @@ import { PILL, TAP_MINIMUM, LABEL_TEXT } from "../tools/index.js";
 export const Switch = (props) => {
   const {
     value = false,
+    /** @deprecated Use `onPress` instead — it receives the same boolean. */
     onToggle,
     onPress: onPressProp,
     disabled = false,
@@ -20,8 +21,6 @@ export const Switch = (props) => {
     ...rest
   } = props;
 
-  /** @deprecated Use onPress instead */
-  // onToggle kept as alias for backward compatibility
   const onPress = onPressProp || onToggle;
 
   // Sizes. Track height is knob + 2 x pad, so the knob can never be asked to sit

package/src/widgets/Text.js

@@ -45,6 +45,10 @@ export const Text = (props) => {
   };
   if (type && headingTags[type]) baseTag = headingTags[type];
 
+  // FIX [TEXT-1]: guard against `styles: null` — Array.isArray(null) is false
+  // but `[...null]` throws; an explicit null means "no styles", same as [].
+  const safeStyles = Array.isArray(textStyles) ? textStyles : [];
+
   const cssStyles = {
     fontSize: size,
     fontWeight: weight,
@@ -59,13 +63,13 @@ export const Text = (props) => {
   if (type === "p") cssStyles.marginBottom = "1em";
 
   if (
-    textStyles.includes("underline") &&
-    textStyles.includes("strikethrough")
+    safeStyles.includes("underline") &&
+    safeStyles.includes("strikethrough")
   ) {
     cssStyles.textDecoration = "underline line-through";
-  } else if (textStyles.includes("underline")) {
+  } else if (safeStyles.includes("underline")) {
     cssStyles.textDecoration = "underline";
-  } else if (textStyles.includes("strikethrough")) {
+  } else if (safeStyles.includes("strikethrough")) {
     cssStyles.textDecoration = "line-through";
   }
 
@@ -78,7 +82,7 @@ export const Text = (props) => {
     ...rest,
   });
 
-  const orderedStyles = [...textStyles].reverse();
+  const orderedStyles = [...safeStyles].reverse();
   for (const style of orderedStyles) {
     const tag = styleMap[style];
     if (tag && style !== "underline" && style !== "strikethrough") {