flet-box 1.1.0 → 1.1.2

package/src/widgets/Stepper.js

@@ -13,6 +13,11 @@ import { colors } from "../utils/themes.js";
 
 import { toREM } from "../utils/units.js";
 
+// Nodes already reported by the shared-content warning below. A screen that
+// reuses one `steps` array steals it once per stepper per render, and a wall of
+// identical warnings is a warning nobody reads.
+const warnedContent = new WeakSet();
+
 export const Stepper = (props) => {
   const {
     steps = [],
@@ -41,6 +46,9 @@ export const Stepper = (props) => {
   } = props;
 
   let currentStep = Math.min(Math.max(activeStep, 0), steps.length - 1);
+  // The two orientations share the marker, the state and the press, and disagree
+  // about everything else — so the branch is decided once, here.
+  const vertical = orientation !== "horizontal";
   let stepsContainer = null;
   let contentContainer = null;
   let navContainer = null;
@@ -92,7 +100,7 @@ export const Stepper = (props) => {
           justifyContent: "center",
           alignItems: "center",
           child: isCompleted
-            ? Icon({ name: "check", size: 18, color: "#fff" })
+            ? Icon({ name: "check", size: 18, color: colors.onSecondary })
             : Text({
                 text: String(idx + 1),
                 size: 14,
@@ -117,59 +125,104 @@ export const Stepper = (props) => {
         });
       }
 
-      // Label
+      // The label, in the ink the stage decides, placed where the orientation
+      // puts it: under the marker in the horizontal track, beside it in the
+      // vertical one. Both branches used to draw their own, so a vertical step
+      // read "Account" twice — once under the circle and once stranded at the far
+      // edge of a row the marker column had already stretched across.
+      const labelColor = isActive ? colors.primary : colors.textSecondary;
       const label = showLabels
-        ? Text({
-            text: step.label,
-            size: 12,
-            color: isActive ? colors.primary : colors.textSecondary,
-            marginTop: 4,
-            align: "center",
-          })
+        ? vertical
+          ? Text({ text: step.label, size: 14, color: labelColor })
+          : Text({
+              text: step.label,
+              size: 12,
+              color: labelColor,
+              marginTop: 4,
+              align: "center",
+            })
         : null;
 
-      const stepColumn = Column({
-        alignItems: "center",
-        flex: needsWrap ? "auto" : 1,
-        minWidth: needsWrap ? "80px" : "0",
+      // The number, the check and the accent carry the stage, and all three are
+      // drawn: the check is a decorative glyph and the label alone does not say
+      // whether the step is behind, ahead or where you are. The state goes in
+      // the name, and `aria-current` marks the step you are on. The press lives
+      // on this box, so the whole strip answers — not only the circle.
+      const press = {
         cursor: "pointer",
+        "aria-label": `${step.label || `Step ${idx + 1}`} (${
+          isCompleted ? "completed" : isActive ? "current" : "upcoming"
+        })`,
+        "aria-current": isActive ? "step" : undefined,
         onclick: () => goToStep(idx),
-        children: [indicator, label].filter(Boolean),
-      });
-
-      if (orientation === "horizontal") {
-        stepsContainer.appendChild(stepColumn);
-        if (!isLast && !needsWrap) {
-          const connector = Container({
-            flex: 1,
-            height: "2px",
-            minWidth: "10px",
-            backgroundColor:
-              idx < currentStep ? colors.success : colors.gray300,
-          });
-          stepsContainer.appendChild(connector);
-        } else if (!isLast && needsWrap) {
-          const spacer = Container({ width: 8 });
-          stepsContainer.appendChild(spacer);
-        }
-      } else {
-        const verticalStep = Row({
-          gap: 12,
-          alignItems: "center",
-          children: [stepColumn, Text({ text: step.label, size: 14 })],
-        });
-        stepsContainer.appendChild(verticalStep);
+      };
+
+      stepsContainer.appendChild(
+        vertical
+          ? Row({
+              alignItems: "center",
+              gap: 12,
+              width: "100%",
+              ...press,
+              children: [indicator, label].filter(Boolean),
+            })
+          : Column({
+              alignItems: "center",
+              flex: needsWrap ? "auto" : 1,
+              minWidth: needsWrap ? "80px" : "0",
+              ...press,
+              children: [indicator, label].filter(Boolean),
+            }),
+      );
+
+      // Only the horizontal track links its markers; a vertical list is already
+      // read in order, and the Column's own gap is the separation.
+      if (!vertical && !isLast) {
+        stepsContainer.appendChild(
+          needsWrap
+            ? Container({ width: 8 })
+            : Container({
+                flex: 1,
+                height: "2px",
+                minWidth: "10px",
+                backgroundColor:
+                  idx < currentStep ? colors.success : colors.gray300,
+              }),
+        );
       }
     });
 
-    // Update content
+    // Update content. One place owns the slot, and it only rewrites it when the
+    // node already there is not this step's: `appendChild` of the node that is
+    // already the child is a detach and a re-attach, which throws away the
+    // content's layout, the caret of a field being typed in, and any transition
+    // it was mid-way through.
     if (contentContainer) {
-      while (contentContainer.firstChild) {
-        contentContainer.removeChild(contentContainer.firstChild);
-      }
       const stepContent = steps[currentStep]?.content;
-      if (stepContent) {
-        contentContainer.appendChild(stepContent);
+      if (contentContainer.firstChild !== stepContent) {
+        while (contentContainer.firstChild) {
+          contentContainer.removeChild(contentContainer.firstChild);
+        }
+        if (stepContent) {
+          // A DOM node has one parent, so the same `content` cannot show in two
+          // steppers: the second `appendChild` moves it and leaves the first with
+          // an empty slot that reads as "the widget is invisible". Nothing else
+          // says so, and the stepper that lost it looks like it never rendered.
+          if (
+            stepContent.parentElement &&
+            stepContent.parentElement !== contentContainer &&
+            !warnedContent.has(stepContent)
+          ) {
+            warnedContent.add(stepContent);
+            console.warn(
+              "Stepper: this step's content is already mounted in another tree, " +
+                "so that stepper is now empty — a widget node has one parent. Build " +
+                "the steps array where the Stepper is built; do not share one array " +
+                "between steppers.",
+            );
+          }
+          contentContainer.appendChild(stepContent);
+        }
       }
     }
 
@@ -189,24 +242,17 @@ export const Stepper = (props) => {
           }),
         );
       }
-      if (currentStep === steps.length - 1) {
-        buttons.push(
-          Button({
-            text: finishLabel,
-            variant: "filled",
-            bgColor: colors.success,
-            onPress: finish,
-          }),
-        );
-      } else {
-        buttons.push(
-          Button({
-            text: nextLabel,
-            variant: "filled",
-            onPress: next,
-          }),
-        );
-      }
+      // One filled call, not a filled call per branch: the last step swaps the
+      // label, the plate and the handler, and never paints two primaries.
+      const isLast = currentStep === steps.length - 1;
+      buttons.push(
+        Button({
+          text: isLast ? finishLabel : nextLabel,
+          variant: "filled",
+          bgColor: isLast ? colors.successPlate : colors.primary,
+          onPress: isLast ? finish : next,
+        }),
+      );
 
       const navRow = Row({
         justifyContent: "flex-end",
@@ -271,9 +317,11 @@ export const Stepper = (props) => {
 
   stepsWrapper.appendChild(stepsContainer);
 
-  // Content container
+  // Content container — built empty. `updateUI()` below is the only writer of
+  // this slot, so the first paint goes through the same code as every
+  // navigation, instead of mounting the node here and detaching it a line later
+  // to mount the same node again.
   contentContainer = Container({
-    child: steps[currentStep]?.content || null,
     width: "100%",
     overflow: "auto",
   });

package/src/widgets/Switch.js

@@ -43,6 +43,7 @@ export const Switch = (props) => {
   let knobRef = null;
 
   const updateUI = (newValue) => {
+    if (switchContainer) switchContainer.setAttribute("aria-checked", String(Boolean(newValue)));
     if (switchRef) {
       switchRef.style.backgroundColor = newValue ? activeColor : colors.gray300;
     }
@@ -52,10 +53,14 @@ export const Switch = (props) => {
   };
 
   // Createste knob
+  // The knob is a white plate in every theme: it sits on a track whose colour
+  // the caller picks (`activeColor`), so it cannot borrow `onPrimary` — in dark
+  // that token is page ink and the knob would vanish into the grey track.
+  // `onSecondary` is the palette's own answer for a white surface.
   const knob = WidgetFactory({
     width: sz.knob,
     height: sz.knob,
-    backgroundColor: "#ffffff",
+    backgroundColor: colors.onSecondary,
     borderRadius: "50%",
     transform: internalValue ? `translateX(${travel()})` : "translateX(0)",
     transition: "transform 0.2s ease",
@@ -89,6 +94,10 @@ export const Switch = (props) => {
 
   const switchContainer = WidgetFactory({
     widgetName: "Switch",
+    // A track and a knob say "toggle" to an eye and nothing at all to a screen
+    // reader; the role names the control and `aria-checked` is its state.
+    role: "switch",
+    "aria-checked": String(Boolean(internalValue)),
     display: "flex",
     flexDirection: "row",
     alignItems: "center",

package/src/widgets/Tooltip.js

@@ -1,6 +1,8 @@
 /**
  * @file Tooltip.js
  * @description Hover/focus tooltip rendered as a fixed-position portal on `document.body`.
+ * Hover only where a pointer can hover, and the bubble is placed inside the
+ * device's safe area.
  */
 import { WidgetFactory } from "../widget-factory/index.js";
 import { resolveReactive } from "../widget-factory/reactiveValue.js";
@@ -8,6 +10,40 @@ import { colors } from "../utils/themes.js";
 
 import { toREM } from "../utils/units.js";
 
+/** The bubble and the thing it describes have to be able to name each other. */
+let tooltipIdSeed = 0;
+
+/**
+ * The device's own edge insets, in CSS pixels.
+ *
+ * `env()` has no JavaScript getter — the only way to read it is to measure an
+ * element that uses it — and the placement below needs the number, not just the
+ * CSS: a bubble that clears the viewport by 10px still sits on the status bar of
+ * a notched phone. The probe is a child of the bubble it measures, so showing a
+ * tooltip never puts a second node in `document.body`, and it is re-read on every
+ * show because rotation moves the inset from the top edge to the sides.
+ */
+const makeInsetProbe = () => {
+  const probe = document.createElement("div");
+  // Out of the flow, so the bubble keeps the size its text gives it.
+  probe.style.cssText =
+    "position:absolute;top:0;left:0;width:0;height:0;visibility:hidden;pointer-events:none;" +
+    "padding-top:env(safe-area-inset-top,0px);padding-bottom:env(safe-area-inset-bottom,0px);" +
+    "padding-left:env(safe-area-inset-left,0px);padding-right:env(safe-area-inset-right,0px);";
+  return probe;
+};
+
+const readInsets = (probe) => {
+  if (!probe) return { top: 0, bottom: 0, left: 0, right: 0 };
+  const cs = getComputedStyle(probe);
+  return {
+    top: parseFloat(cs.paddingTop) || 0,
+    bottom: parseFloat(cs.paddingBottom) || 0,
+    left: parseFloat(cs.paddingLeft) || 0,
+    right: parseFloat(cs.paddingRight) || 0,
+  };
+};
+
 export const Tooltip = (props) => {
   let {
     text,
@@ -37,8 +73,6 @@ export const Tooltip = (props) => {
     borderColor = "transparent",
     borderWidth = 0,
     shadow = "0 2px 8px rgba(0,0,0,0.15)",
-
-    ...rest
   } = props;
 
   if (!child) return null;
@@ -51,6 +85,8 @@ export const Tooltip = (props) => {
   let timeoutId = null;
   let isVisible = false;
 
+  const tooltipId = `fletbox-tooltip-${++tooltipIdSeed}`;
+
   let scrollHandler = null;
   let resizeHandler = null;
 
@@ -98,6 +134,11 @@ export const Tooltip = (props) => {
 
     const tooltip = WidgetFactory({
       tag: "div",
+      // The bubble is what `aria-describedby` on the trigger points at, so the id
+      // and the role live on the element that is actually shown and hidden — its
+      // subtree is the sentence a reader hears.
+      id: tooltipId,
+      role: "tooltip",
       position: "fixed",
       zIndex: zIndex,
       opacity: 0,
@@ -106,6 +147,8 @@ export const Tooltip = (props) => {
       pointerEvents: "none",
     });
 
+    const probe = makeInsetProbe();
+    tooltip.appendChild(probe);
     tooltip.appendChild(content);
     if (arrow) tooltip.appendChild(arrow);
 
@@ -114,6 +157,7 @@ export const Tooltip = (props) => {
 
     tooltip._content = content;
     tooltip._arrow = arrow;
+    tooltip._probe = probe;
 
     return tooltip;
   };
@@ -121,10 +165,33 @@ export const Tooltip = (props) => {
   const positionTooltip = (targetRect, tooltipRect) => {
     if (!tooltipElement) return;
 
+    // The edge the bubble actually gets: the requested one when it fits, the
+    // opposite when it does not. Clamping a `top` bubble into the viewport used
+    // to park it at y=10 — over the iOS status bar, above the AppBar it
+    // describes — because "there is no room up here" and "put it at the top of
+    // the screen" are not the same instruction.
+    const MARGIN = 10;
+    const inset = readInsets(tooltipElement._probe);
+    const boxTop = inset.top + MARGIN;
+    const boxBottom = window.innerHeight - inset.bottom - MARGIN;
+    const boxLeft = inset.left + MARGIN;
+    const boxRight = window.innerWidth - inset.right - MARGIN;
+    const needed = tooltipRect.height + offset;
+    const wide = tooltipRect.width + offset;
+    const room = {
+      top: targetRect.top - boxTop,
+      bottom: boxBottom - targetRect.bottom,
+      left: targetRect.left - boxLeft,
+      right: boxRight - targetRect.right,
+    };
+    const flip = { top: "bottom", bottom: "top", left: "right", right: "left" };
+    const fits = { top: room.top >= needed, bottom: room.bottom >= needed, left: room.left >= wide, right: room.right >= wide };
+    const side = fits[position] ? position : fits[flip[position]] ? flip[position] : position;
+
     let top, left;
     let arrowTop, arrowLeft;
 
-    switch (position) {
+    switch (side) {
       case "top":
         top = targetRect.top - tooltipRect.height - offset;
         left = targetRect.left + targetRect.width / 2 - tooltipRect.width / 2;
@@ -175,11 +242,11 @@ export const Tooltip = (props) => {
         break;
     }
 
-    if (left < 10) left = 10;
-    if (left + tooltipRect.width > window.innerWidth - 10) {
-      left = window.innerWidth - tooltipRect.width - 10;
-    }
-    if (top < 10) top = 10;
+    // Keep the bubble inside the safe area on every axis. `Math.max(boxTop, …)`
+    // guards the other end for a bubble taller or wider than the screen, where
+    // the two bounds cross.
+    left = Math.min(Math.max(left, boxLeft), Math.max(boxLeft, boxRight - tooltipRect.width));
+    top = Math.min(Math.max(top, boxTop), Math.max(boxTop, boxBottom - tooltipRect.height));
 
     tooltipElement.style.top = `${top}px`;
     tooltipElement.style.left = `${left}px`;
@@ -205,6 +272,10 @@ export const Tooltip = (props) => {
       });
 
       isVisible = true;
+      // The link is made while the bubble is up and broken while it is not: an
+      // `aria-describedby` pointing at a hidden node is a control that claims a
+      // description it is not being given.
+      child.setAttribute("aria-describedby", tooltipId);
 
       scrollHandler = hideOnScrollOrResize;
       resizeHandler = hideOnScrollOrResize;
@@ -223,6 +294,7 @@ export const Tooltip = (props) => {
       tooltipElement.style.opacity = "0";
       tooltipElement.style.visibility = "hidden";
       isVisible = false;
+      child.removeAttribute("aria-describedby");
 
       if (scrollHandler) {
         window.removeEventListener("scroll", scrollHandler, true);
@@ -237,8 +309,19 @@ export const Tooltip = (props) => {
 
   const wrappedChild = child;
 
-  wrappedChild.addEventListener("mouseenter", showTooltip);
-  wrappedChild.addEventListener("mouseleave", hideTooltip);
+  // A device that cannot hover has no state a tooltip can live in. iOS WebKit
+  // fires a synthetic `mouseenter` for the first tap and never a matching
+  // `mouseleave`, so one tap pinned a bubble to the screen and a second tap on
+  // another control stacked a second one on top of it — measured: two bubbles
+  // visible at once, neither ever hidden. A pointer that does hover keeps the
+  // behaviour, and the keyboard path below stays open for everyone.
+  const canHover =
+    typeof window === "undefined" || !window.matchMedia || window.matchMedia("(hover: hover)").matches;
+
+  if (canHover) {
+    wrappedChild.addEventListener("mouseenter", showTooltip);
+    wrappedChild.addEventListener("mouseleave", hideTooltip);
+  }
   wrappedChild.addEventListener("focus", showTooltip);
   wrappedChild.addEventListener("blur", hideTooltip);
 

package/src/widgets/TreeView.js

@@ -6,7 +6,7 @@ import { WidgetFactory } from "../widget-factory/index.js";
 import { colors } from "../utils/themes.js";
 
 import { toREM } from "../utils/units.js";
-import { TAP_MINIMUM } from "../tools/index.js";
+import { PILL, TAP_MINIMUM } from "../tools/index.js";
 
 export const TreeView = (props) => {
   const {
@@ -219,12 +219,12 @@ export const TreeView = (props) => {
         // `danger` is the signal tone; the plate is the fill white words can
         // actually sit on (6.47:1 in the light theme, 10.02:1 in the dark one).
         backgroundColor: colors.dangerPlate,
-        borderRadius: "12px",
-        padding: "2px 8px",
+        borderRadius: PILL,
+        padding: "4px 8px",
         child: WidgetFactory({
           tag: "span",
-          fontSize: "10px",
-          color: "#ffffff",
+          fontSize: "12px",
+          color: colors.onSecondary,
           fontWeight: "bold",
           textContent: String(node.badge),
         }),