flet-box 1.0.9 → 1.1.1

package/src/widgets/Rating.js

@@ -31,10 +31,18 @@ export const Rating = (props) => {
   } = props;
 
   // Colors from theme
+  //
+  // Both inks are the readable end of their own hue, for the same reason Radio's
+  // off-ring is: `colors.border` measured 1.27:1 on a white card and 1.19:1 on a
+  // dark one, so the empty stars were not a dim state but an absent one, and
+  // `colors.warning` (#F59E0B) measured 2.15:1 on white, which made a 4-out-of-5
+  // score harder to see than the label next to it. `gray500` is the neutral
+  // control outline (4.83:1 light, 3.67:1 dark) and `warningStrong` is the amber
+  // the palette already declares for words (5.02:1 light, 12.29:1 dark).
   let activeColor =
-    propActiveColor !== undefined ? propActiveColor : colors.warning;
+    propActiveColor !== undefined ? propActiveColor : colors.warningStrong;
   let inactiveColor =
-    propInactiveColor !== undefined ? propInactiveColor : colors.border;
+    propInactiveColor !== undefined ? propInactiveColor : colors.gray500;
   let currentValue = Math.min(Math.max(value, 0), max);
 
   let starIcons = []; // stores the SPAN elements of each star
@@ -43,6 +51,9 @@ export const Rating = (props) => {
   let unsubscribeTheme = null;
   let touchActive = false; // to avoid conflicts with mouse
 
+  /** The score as one sentence, which is what the group is named by. */
+  const groupLabel = () => `${currentValue} out of ${max}`;
+
   // Update all stars according to currentValue
   const updateStars = () => {
     for (let i = 0; i < max; i++) {
@@ -77,6 +88,20 @@ export const Rating = (props) => {
     if (valueTextRef && showValue) {
       valueTextRef.update({ text: currentValue.toFixed(1) });
     }
+
+    // The announced state and the roving stop follow the drawn stars, so a score
+    // set from the keyboard, from a pointer or by `rating.value = 3` is heard the
+    // same way.
+    if (!readOnly) {
+      const selected = Math.round(currentValue);
+      for (let i = 0; i < max; i++) {
+        const wrapper = starWrappers[i];
+        if (!wrapper) continue;
+        wrapper.setAttribute("aria-checked", String(selected === i + 1));
+        wrapper.tabIndex = tabIndexFor(i);
+      }
+    }
+    if (starsContainer) starsContainer.setAttribute("aria-label", groupLabel());
   };
 
   // Change the actual value (persistent)
@@ -111,6 +136,33 @@ export const Rating = (props) => {
   };
 
   // ========== STAR CREATION ==========
+  /**
+   * The star a keyboard stop sits on: the one carrying the score, or the first
+   * when nothing is chosen yet. A group where every star is a stop makes Tab
+   * walk five times through one control.
+   */
+  const tabIndexFor = (i) =>
+    i === (currentValue > 0 ? Math.min(Math.round(currentValue), max) - 1 : 0)
+      ? 0
+      : -1;
+
+  /**
+   * Pick star `i + 1`. With `allowHalf`, pressing the star that is already the
+   * whole score turns it into the half between it and the last one.
+   */
+  const pickStar = (i) => {
+    let newValue = i + 1;
+    if (allowHalf && currentValue === newValue) newValue -= 0.5;
+    setValue(newValue);
+  };
+
+  /** Move the keyboard and the score to star `index`. */
+  const focusStar = (index) => {
+    const clamped = Math.min(Math.max(index, 0), max - 1);
+    starWrappers[clamped]?.focus();
+    setValue(clamped + 1);
+  };
+
   for (let i = 0; i < max; i++) {
     const icon = Icon({
       name: iconInactive,
@@ -130,6 +182,45 @@ export const Rating = (props) => {
       ...(readOnly
         ? { padding: 4 }
         : { minWidth: TAP_MINIMUM, minHeight: TAP_MINIMUM }),
+      // A score shown as filled stars is the only place that state lives: the
+      // glyph is decorative and the number is not rendered when `showValue` is
+      // off. Each star is one choice of a group, which is what `radio` means.
+      ...(readOnly
+        ? {}
+        : {
+            role: "radio",
+            "aria-label": `Star ${i + 1} of ${max}`,
+            "aria-checked": "false",
+            tabIndex: tabIndexFor(i),
+            // The press is a prop, so the engine turns Enter and Space into this
+            // click instead of leaving a star only a finger can light up. The
+            // gesture stays the widget's own `scale(1.15)` above: the engine's
+            // press scale would overwrite it on the same frame.
+            disableTransform: true,
+            onclick: () => pickStar(i),
+            onKeyDown: (e) => {
+              switch (e.key) {
+                case "ArrowRight":
+                case "ArrowDown":
+                  e.preventDefault();
+                  focusStar(i + 1);
+                  break;
+                case "ArrowLeft":
+                case "ArrowUp":
+                  e.preventDefault();
+                  focusStar(i - 1);
+                  break;
+                case "Home":
+                  e.preventDefault();
+                  focusStar(0);
+                  break;
+                case "End":
+                  e.preventDefault();
+                  focusStar(max - 1);
+                  break;
+              }
+            },
+          }),
     });
 
     starIcons.push(icon);
@@ -147,17 +238,9 @@ export const Rating = (props) => {
         wrapper.style.transform = "scale(1)";
         restoreFromPreview();
       });
-      wrapper.addEventListener("click", () => {
-        if (touchActive) return;
-        let newValue = i + 1;
-        if (allowHalf) {
-          if (currentValue === newValue) newValue = newValue - 0.5;
-          else if (currentValue === newValue - 0.5) newValue = newValue;
-          else newValue = newValue;
-        }
-        setValue(newValue);
-      });
-
+      // The click itself is the `onclick` prop above — that is what lets the
+      // engine reach this star without a pointer, and a listener here would run
+      // the same pick twice.
       // ----- TOUCH EVENTS -----
       wrapper.addEventListener("touchstart", (e) => {
         e.preventDefault();
@@ -207,7 +290,7 @@ export const Rating = (props) => {
         }
         touchActive = false;
       });
-      wrapper.addEventListener("touchcancel", (e) => {
+      wrapper.addEventListener("touchcancel", () => {
         wrapper.style.transform = "scale(1)";
         restoreFromPreview();
         touchActive = false;
@@ -221,6 +304,11 @@ export const Rating = (props) => {
     gap: gap,
     flexWrap: "wrap",
     children: starWrappers,
+    // One control, not five stops: the group is what a reader lands on and the
+    // score is what they hear there. A read-only rating has no choice to make,
+    // so it is a picture of a number rather than a group of radios.
+    role: readOnly ? "img" : "radiogroup",
+    "aria-label": groupLabel(),
   });
 
   // Ensure initial state
@@ -253,8 +341,8 @@ export const Rating = (props) => {
   // Dynamic theme
   if (propActiveColor === undefined || propInactiveColor === undefined) {
     unsubscribeTheme = subscribeTheme(() => {
-      if (propActiveColor === undefined) activeColor = colors.warning;
-      if (propInactiveColor === undefined) inactiveColor = colors.border;
+      if (propActiveColor === undefined) activeColor = colors.warningStrong;
+      if (propInactiveColor === undefined) inactiveColor = colors.gray500;
       updateStars();
     });
   }

package/src/widgets/Skeleton.js

@@ -21,13 +21,11 @@ export const Skeleton = (props) => {
     // Color props for consistency
     bgColor = colors.gray200,
     highlightColor = colors.gray100,
-    shimmerColor = colors.gray300,
+    shimmerColor,
 
     // Animation timing
     pulseDuration = "1.5s",
     waveDuration = "1.5s",
-
-    ...rest
   } = props;
 
   // Default dimensions based on variant
@@ -70,9 +68,15 @@ export const Skeleton = (props) => {
       };
     }
     if (animation === "wave") {
+      // `shimmerColor` names the band the wave carries; `highlightColor` is the
+      // token it falls back to, so either prop alone paints the shimmer.
+      const band = shimmerColor ?? highlightColor;
       return {
-        background: `linear-gradient(90deg, ${bgColor} 25%, ${highlightColor} 50%, ${bgColor} 75%)`,
-        backgroundSize: "200% 100%",
+        // `gradient` and `bgSize` are the registered names for `background` and
+        // `background-size`. A raw CSS name still paints — the factory falls back
+        // to writing it as an inline style — but warns on every placeholder built.
+        gradient: `linear-gradient(90deg, ${bgColor} 25%, ${band} 50%, ${bgColor} 75%)`,
+        bgSize: "200% 100%",
         animation: `skeleton-wave ${waveDuration} ease-in-out infinite`,
       };
     }

package/src/widgets/Slider.js

@@ -7,6 +7,7 @@ import { WidgetFactory } from "../widget-factory/index.js";
 import { colors } from "../utils/themes.js";
 import { composeUpdate } from "../utils/composeUpdate.js";
 import { injectKeyframes } from "../utils/styleInjector.js";
+import { markMotionLoop } from "../animations/motion.js";
 
 /**
  * Props owned by the Slider's closure state. Routed to the widget's `update`
@@ -24,6 +25,12 @@ const SLIDER_PROP_KEYS = [
   "onChanged", "onPress", "onChangeEnd",
 ];
 
+// The fill eases for a value that changes *by itself* — a key press, `setValue`,
+// an `update({ value })`. During a gesture it is switched off (see `onStart`):
+// an ease that restarts on every pointer move never catches up, so the bar spends
+// the whole drag chasing the thumb instead of moving with it.
+const FILL_EASE = "width 0.1s ease, height 0.1s ease";
+
 export const Slider = (props) => {
   let {
     // Basic values
@@ -77,9 +84,11 @@ export const Slider = (props) => {
   let displayPercent = inverted ? 1 - rawPercent : rawPercent;
 
   let isHorizontal = orientation === "horizontal";
-  let trackSize = isHorizontal ? height : width;
-  let trackLength =
-    toREM(trackSize);
+  // `height` is the rail's thickness and `width` its length in both orientations:
+  // a vertical slider is the same box turned 90°, so its vertical extent comes from
+  // `width` (the root below) while the rail stays `height` thin. Reading the
+  // thickness from `width` here painted a 160-unit rail 160 units *wide*.
+  let trackLength = toREM(height);
   let thumbSizeNum = typeof thumbSize === "number" ? thumbSize : 24;
 
   // Positioning retries while the track still measures 0 (hidden parent, not laid
@@ -102,6 +111,16 @@ export const Slider = (props) => {
   const container = WidgetFactory({
     tag: "div",
     widgetName: "Slider",
+    // The root is the control: what a reader meets, what Tab stops on and what
+    // answers the arrow keys. The thumb is the picture of the value, not a second
+    // stop — and one element is where `updateUI` can keep `aria-valuenow` honest.
+    role: "slider",
+    tabIndex: disabled ? -1 : 0,
+    "aria-valuemin": String(currentMin),
+    "aria-valuemax": String(currentMax),
+    "aria-valuenow": String(currentValue),
+    "aria-orientation": isHorizontal ? "horizontal" : "vertical",
+    "aria-disabled": String(Boolean(disabled)),
     width: isHorizontal ? width : "auto",
     height: !isHorizontal ? width : "auto",
     opacity: disabled ? 0.5 : 1,
@@ -170,7 +189,7 @@ export const Slider = (props) => {
     position: "absolute",
     backgroundColor: color,
     borderRadius: trackLength,
-    transition: disabled ? "none" : "width 0.1s ease, height 0.1s ease",
+    transition: disabled ? "none" : FILL_EASE,
     ...(isHorizontal
       ? {
           width: `${displayPercent * 100}%`,
@@ -189,10 +208,15 @@ export const Slider = (props) => {
   if (striped) {
     fill.style.backgroundImage = `repeating-linear-gradient(45deg, ${stripeColor} 0px, ${stripeColor} 8px, transparent 8px, transparent 16px)`;
     fill.style.backgroundSize = "16px 16px";
-    if (animatedStripes)
+    if (animatedStripes) {
       fill.style.animation = "slider-stripes 0.5s linear infinite";
+      markMotionLoop(fill);
+    }
+  }
+  if (glow) {
+    fill.style.animation = "slider-glow 1.5s ease-in-out infinite";
+    markMotionLoop(fill);
   }
-  if (glow) fill.style.animation = "slider-glow 1.5s ease-in-out infinite";
   track.appendChild(fill);
 
   // ---------- Thumb (knob) ----------
@@ -288,7 +312,7 @@ export const Slider = (props) => {
         const label = WidgetFactory({
           tag: "span",
           textContent: mark.label,
-          fontSize: "10px",
+          fontSize: "12px",
           color: colors.textSecondary,
           position: "absolute",
           ...(isHorizontal
@@ -329,6 +353,13 @@ export const Slider = (props) => {
     rawPercent = (currentValue - currentMin) / (currentMax - currentMin);
     displayPercent = inverted ? 1 - rawPercent : rawPercent;
 
+    // The number a reader hears is the one the thumb is drawn at, so both are
+    // written from the same function: a state that only the drag path updates is a
+    // state that goes stale the first time `setValue` or `update({ min })` runs.
+    container.setAttribute("aria-valuenow", String(currentValue));
+    container.setAttribute("aria-valuemin", String(currentMin));
+    container.setAttribute("aria-valuemax", String(currentMax));
+
     if (isHorizontal) {
       fill.style.width = `${displayPercent * 100}%`;
     } else {
@@ -433,6 +464,7 @@ export const Slider = (props) => {
     document.removeEventListener("touchmove", onMove);
     document.removeEventListener("touchend", onEnd);
     thumb.style.cursor = "grab";
+    fill.style.transition = disabled ? "none" : FILL_EASE;
     if (wrapper.style) wrapper.style.touchAction = "";
   };
 
@@ -441,6 +473,9 @@ export const Slider = (props) => {
     e.preventDefault();
     dragging = true;
     hasMoved = false;
+    // Before the first value write: with the ease still on, the jump to the press
+    // point animates and every later move restarts that animation.
+    fill.style.transition = "none";
     thumb.style.cursor = "grabbing";
     if (e.pointerId !== undefined) {
       currentPointerId = e.pointerId;
@@ -471,6 +506,50 @@ export const Slider = (props) => {
   thumb.addEventListener("mousedown", onStart);
   thumb.addEventListener("touchstart", onStart);
 
+  // ---------- Keyboard ----------
+  // `role="slider"` is a promise of arrow keys: a handle you can drag but not nudge
+  // is announced to a keyboard user as something they cannot move. One step for an
+  // arrow, a coarse one for Page keys, the ends for Home and End — the same set a
+  // native range input answers.
+  const bigStep = () =>
+    Math.max(currentStep, (currentMax - currentMin) / 10);
+
+  const onKeyDown = (e) => {
+    if (disabled) return;
+    let next = null;
+    switch (e.key) {
+      case "ArrowRight":
+      case "ArrowUp":
+        next = currentValue + currentStep;
+        break;
+      case "ArrowLeft":
+      case "ArrowDown":
+        next = currentValue - currentStep;
+        break;
+      case "PageUp":
+        next = currentValue + bigStep();
+        break;
+      case "PageDown":
+        next = currentValue - bigStep();
+        break;
+      case "Home":
+        next = currentMin;
+        break;
+      case "End":
+        next = currentMax;
+        break;
+      default:
+        return;
+    }
+    // Without this, the arrows on a vertical slider scroll the page instead of
+    // moving the value.
+    e.preventDefault();
+    // `triggerEnd` — the same sentence a released drag says, so an app that
+    // commits on `onChangeEnd` commits on a key too.
+    setValue(next, true, true);
+  };
+  container.addEventListener("keydown", onKeyDown);
+
   // ---------- ResizeObserver to reposition thumb ----------
   let resizeObserver = null;
   if (typeof ResizeObserver !== "undefined") {
@@ -542,6 +621,7 @@ export const Slider = (props) => {
     track.removeEventListener("touchstart", onStart);
     thumb.removeEventListener("mousedown", onStart);
     thumb.removeEventListener("touchstart", onStart);
+    container.removeEventListener("keydown", onKeyDown);
     document.removeEventListener("mousemove", onMove);
     document.removeEventListener("mouseup", onEnd);
     document.removeEventListener("touchmove", onMove);

package/src/widgets/SnackBar.js

@@ -129,9 +129,15 @@ export function SnackBar(options) {
   const show = () => {
     if (closed) return;
     if (rafId !== null) cancelAnimationFrame(rafId);
+    // Empty it here, fill it on the frame after: that gap is the whole reason the
+    // toast is heard. A live region that arrives with its words already inside is
+    // a new landmark, not a change, and a reader who is already on the page is
+    // told nothing. Clearing first also makes a second `show()` speak again.
+    announcer.textContent = "";
     rafId = requestAnimationFrame(() => {
       rafId = null;
       if (closed) return;
+      announcer.textContent = message;
       snackbar.style.opacity = "1";
       snackbar.style.transform = "translateY(0)";
     });
@@ -156,6 +162,7 @@ export function SnackBar(options) {
         : `translateY(calc(-100% - ${toREM(margin)}))`;
     setTimeout(() => {
       if (snackbar.parentNode) snackbar.parentNode.removeChild(snackbar);
+      if (announcer.parentNode) announcer.parentNode.removeChild(announcer);
       if (onClose) onClose();
     }, animationDuration);
   };
@@ -164,11 +171,29 @@ export function SnackBar(options) {
   const messageEl = WidgetFactory({
     tag: "span",
     flex: 1,
-    text: message,
     wordBreak: "break-word",
+    text: message,
   });
   snackbar.appendChild(messageEl);
 
+  // The thing that speaks is not the bar. An error or a warning interrupts the
+  // sentence a reader is in the middle of; a confirmation waits for it to end.
+  // `opacity: 0` and one unit of size, because a `display: none` region is not
+  // read at all, and the bar's own animation is what the eye follows.
+  const announcer = WidgetFactory({
+    tag: "div",
+    role: type === "error" || type === "warning" ? "alert" : "status",
+    "aria-live": type === "error" || type === "warning" ? "assertive" : "polite",
+    position: "fixed",
+    bottom: 0,
+    left: 0,
+    width: 1,
+    height: 1,
+    opacity: 0,
+    overflow: "hidden",
+    pointerEvents: "none",
+  });
+
   // Action button
   let actionBtn = null;
   if (action) {
@@ -214,6 +239,9 @@ export function SnackBar(options) {
       opacity: 0.7,
       transition: "opacity 0.2s ease",
       textContent: "✕",
+      // The glyph is not a name. A reader hears "multiplication sign" and has to
+      // guess that this is the thing that dismisses the message.
+      "aria-label": "Dismiss notification",
       onclick: close,
     });
     closeBtn.addEventListener("mouseenter", () => {
@@ -227,6 +255,7 @@ export function SnackBar(options) {
 
   // Add to DOM
   document.body.appendChild(snackbar);
+  document.body.appendChild(announcer);
   // Force reflow
   snackbar.offsetHeight;
 

package/src/widgets/Stack.js

@@ -1,15 +1,19 @@
 /**
  * @file Stack.js
- * @description Positioning container for overlaying children (relative by default,
- * use `position: "stack"` for absolute centering). Supports a nine-point
- * `alignment` that anchors its children inside the box.
+ * @description Positioning container that paints its children in the same box.
+ * The first child stays in the flow and gives the stack its size; every child
+ * after it floats over that box, anchored by `alignment` or by its own edges.
  */
 import { WidgetFactory } from "../widget-factory/index.js";
+import { ensureStackLayout } from "../utils/stackLayout.js";
 
 /**
  * Nine-point grid → [vertical anchor, horizontal anchor].
  * `alignment` turns the stack into a column flex container, so `justifyContent`
  * carries the top/center/bottom anchor and `alignItems` the left/center/right one.
+ * Those same two rules are what places a floating child: an absolutely
+ * positioned child of a flex container takes its static position from them, so
+ * one map anchors both the in-flow child and every layer above it.
  */
 const ALIGNMENTS = {
   "top-left": ["flex-start", "flex-start"],
@@ -37,26 +41,34 @@ export const Stack = (props = {}) => {
     ...rest
   } = props;
 
-  const preset = alignment ? ALIGNMENTS[alignment] : undefined;
+  // The corner a child with no edges of its own lands on. Flet's stack puts the
+  // first control in the top-left, and a stack that anchored nothing would place
+  // its floating children wherever the flow would have put them — which is the
+  // bug this widget is meant to fix, not a default.
+  const preset = ALIGNMENTS[alignment] ?? ALIGNMENTS["top-left"];
 
   // The preset sits before `...rest`, so an explicit `flexDirection`,
   // `justifyContent` or `alignItems` from the caller always overrides it;
   // `alignment` only fills the axes nobody claimed.
-  return WidgetFactory({
+  const stack = WidgetFactory({
     tag: "div",
     widgetName: "Stack",
     position: position,
-    display: display ?? (preset ? "flex" : "block"),
+    display: display ?? "flex",
     boxSizing: boxSizing,
-    ...(preset
-      ? {
-          flexDirection: "column",
-          justifyContent: preset[0],
-          alignItems: preset[1],
-        }
-      : null),
+    flexDirection: "column",
+    justifyContent: preset[0],
+    alignItems: preset[1],
     ...rest,
   });
+
+  // The marker is what `stackLayout.js` floats every child but the first against.
+  // It goes on the root, not on the children, because `update({ children })`
+  // replaces the nodes and would take any per-node flag with it.
+  ensureStackLayout();
+  stack.setAttribute("data-fb-stack", "");
+
+  return stack;
 };
 
 export default Stack;