flet-box 1.1.0 → 1.1.2

package/src/widget-factory/effects.js

@@ -37,6 +37,72 @@ const nextElevation = (value) => {
 };
 
 
+/**
+ * The tags HTML already makes reachable: they are on the Tab path, they answer to
+ * Enter or Space, and a screen reader already knows what they are. Nothing here
+ * has to be done for them, and nothing here may be done *to* them — a native
+ * `<button>` given `role="button"` and a second key handler fires its action
+ * twice.
+ *
+ * @type {Set<string>}
+ */
+const NATIVELY_REACHABLE = new Set([
+  "A",
+  "BUTTON",
+  "INPUT",
+  "SELECT",
+  "TEXTAREA",
+]);
+
+/**
+ * Makes an element that only answers to a mouse answer to a keyboard too.
+ *
+ * `onPress` is routed to `click`, and a `click` on a `div` is not something a
+ * keyboard can produce: the widget was invisible to Tab, had no name for an
+ * assistive technology, and did nothing on Enter. This is the whole of the
+ * contract the framework owes — the same three things HTML would have given the
+ * widget for free had it been built from a `button`.
+ *
+ * Everything is conditional on the app not having said so already: an explicit
+ * `role` or `tabIndex` is a decision, and `-1` ("keep this off the Tab path") is
+ * a decision the engine must not overwrite.
+ *
+ * @param {HTMLElement} widget - The pressable element.
+ * @param {Array<{event: string, handler: Function}>} listeners - The effect
+ *   listener list, so the key handler is released by the next update like every
+ *   other effect here.
+ * @returns {void}
+ */
+const makeKeyboardPressable = (widget, listeners) => {
+  if (NATIVELY_REACHABLE.has(widget.tagName)) return;
+  if (widget.disabled === true || widget.getAttribute("aria-disabled") === "true") {
+    return;
+  }
+
+  if (!widget.hasAttribute("role")) widget.setAttribute("role", "button");
+  if (!widget.hasAttribute("tabindex")) widget.tabIndex = 0;
+
+  /**
+   * Enter and Space are what a press is for someone with no pointer.
+   */
+  const onKeyDown = (event) => {
+    // A nested control owns its own keys: pressing Enter on a Button inside a
+    // clickable Card must open the card as well as fire the button.
+    if (event.target !== widget) return;
+    if (event.key !== "Enter" && event.key !== " " && event.key !== "Spacebar") {
+      return;
+    }
+    // Held down, Space is one press, not sixty.
+    if (event.repeat) return;
+    // Space would otherwise scroll the page instead of pressing the control.
+    event.preventDefault();
+    if (typeof widget.onclick === "function") widget.onclick(event);
+  };
+
+  widget.addEventListener("keydown", onKeyDown);
+  listeners.push({ event: "keydown", handler: onKeyDown });
+};
+
 /**
  * Applies interactive visual effects to a widget that has a click handler.
  *
@@ -47,7 +113,11 @@ const nextElevation = (value) => {
  * **Base effects (always applied):**
  * - `-webkit-tap-highlight-color` set to `transparent` to suppress the default
  *   mobile tap flash.
- * - `outline` removed for a cleaner focused appearance.
+ *
+ * The focus ring is **not** touched here. It used to be: this function wrote
+ * `outline: none` onto every widget, which read as a cleaner screenshot and cost
+ * every keyboard user the answer to "where am I". The ring is the document's
+ * own rule (`src/utils/focusRing.js`) and an inline `outline` would outrank it.
  *
  * **Press / hover effects (only when a click handler is present and
  * `disableTransform !== true`):**
@@ -79,11 +149,15 @@ export const applyEffects = (widget) => {
   }
 
   widget.style.webkitTapHighlightColor = "transparent";
-  widget.style.outline = "none";
 
   const hasClick = widget.onclick && typeof widget.onclick === "function";
   if (!hasClick) return widget;
 
+  // Declared here because reachability is not a transform: a widget with
+  // `disableTransform` still has to be operable without a mouse.
+  const listeners = [];
+  makeKeyboardPressable(widget, listeners);
+
   // Store the current shadow so it can be restored after press / hover effects.
   //
   // Skipped while the pointer is over the widget: `update()` re-runs
@@ -93,7 +167,6 @@ export const applyEffects = (widget) => {
   const hoverShadow = nextElevation(widget._originalShadow);
 
   const disableTransform = widget._originalProps?.disableTransform === true;
-  const listeners = [];
 
   if (!disableTransform) {
     let isPressed = false;

package/src/widget-factory/reactiveValue.js

@@ -76,12 +76,6 @@ export const endRenderPass = () => {
  */
 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).
  *
@@ -166,7 +160,6 @@ export default {
   resolveReactive,
   createReactiveValue,
   isStructuralRead,
-  resetStructuralReads,
   beginRenderPass,
   endRenderPass,
 };

package/src/widget-factory/tools.js

@@ -1,29 +1,8 @@
-// ============================================================
-// 📋 READ: Get styles
-// ============================================================
-
-/**
- * Reads one or all inline styles from a DOM element.
- *
- * @param {HTMLElement|null} el - The target element.
- * @param {string} [prop] - CSS property name. When provided, returns only that
- *   property's value (or `null` when absent). When omitted, returns an object
- *   containing every non-empty inline style.
- * @returns {string|Object|null} The property value, a styles object, or `null`
- *   when `el` is falsy or the property is not set.
- */
-export function getStyles(el, prop) {
-  if (!el) return null;
-  if (prop) return el.style[prop] || null;
-
-  const styles = {};
-  for (let i = 0; i < el.style.length; i++) {
-    const p = el.style[i];
-    const v = el.style[p];
-    if (v !== "") styles[p] = v;
-  }
-  return styles;
-}
+// The engine owns the reduced-motion contract: a widget that writes an
+// `infinite` CSS animation through these helpers is marked so the injected
+// `@media (prefers-reduced-motion: reduce)` rule can reach it, even when the
+// reader flips the OS setting long after the element was built.
+import { markMotionLoop } from "../animations/motion.js";
 
 // ============================================================
 // ➕ CREATE / UPDATE: Assign styles
@@ -81,6 +60,23 @@ const toCSSValue = (key, value) => {
   return value;
 };
 
+/**
+ * Whether a style assignment puts an endless animation on the element.
+ *
+ * Only a loop is marked: a one-shot entrance finishes on its own, and the
+ * reduced-motion rule would then only be noise.
+ *
+ * @param {string} prop - The CSS property being written.
+ * @param {*} value - The value being written.
+ * @returns {boolean} True when this write starts an `infinite` animation.
+ */
+const isLoopingAnimation = (prop, value) => {
+  if (typeof value !== "string") return false;
+  if (prop === "animation") return value.includes("infinite");
+  if (prop === "animationIterationCount") return value.trim() === "infinite";
+  return false;
+};
+
 /**
  * Applies one or more styles to a DOM element.
  *
@@ -110,12 +106,14 @@ export function setStyles(el, prop, value) {
       } catch (e) {
         // Silently ignore errors
       }
+      if (isLoopingAnimation(prop, cssValue)) markMotionLoop(el);
     }
     return el;
   }
 
   // Case 2: styles object
   if (typeof prop === "object" && prop !== null) {
+    let loops = false;
     for (const [key, val] of Object.entries(prop)) {
       const cssValue = toCSSValue(key, val);
       if (cssValue !== null) {
@@ -124,126 +122,11 @@ export function setStyles(el, prop, value) {
         } catch (e) {
           // Silently ignore errors
         }
+        if (isLoopingAnimation(key, cssValue)) loops = true;
       }
     }
+    if (loops) markMotionLoop(el);
   }
 
   return el;
 }
-
-// ============================================================
-// 🔄 TOGGLE: Toggle styles
-// ============================================================
-
-/**
- * Toggles a CSS property between two values.
- *
- * If the property currently equals `val1` it is set to `val2`, and vice versa.
- * Useful for toggling visibility, themes, or active states without external
- * boolean tracking.
- *
- * @param {HTMLElement} el - The target element.
- * @param {string} prop - CSS property name (camelCase).
- * @param {*} val1 - First value (the one to switch away from when current).
- * @param {*} val2 - Second value (the one to switch away from when current).
- * @returns {HTMLElement} The element (for chaining).
- */
-export function updateStyle(el, prop, val1, val2) {
-  if (!el || !prop) return el;
-
-  const current = el.style[prop] || "";
-  const newValue = current === val1 ? val2 : val1;
-  const cssValue = toCSSValue(prop, newValue);
-
-  if (cssValue !== null) {
-    try {
-      el.style[prop] = cssValue;
-    } catch (e) {
-      // Silently ignore errors
-    }
-  }
-
-  return el;
-}
-
-// ============================================================
-// 🗑️ DELETE: Remove styles
-// ============================================================
-
-/**
- * Removes one or more inline styles from a DOM element by setting them to an
- * empty string (which causes the browser to fall back to inherited / default
- * values).
- *
- * - `string` → removes that single property.
- * - `Array<string>` → removes every listed property.
- * - `undefined` → removes ALL currently set inline styles.
- *
- * @param {HTMLElement} el - The target element.
- * @param {string|string[]|undefined} [prop] - Property or properties to remove.
- *   Omit to remove all inline styles.
- * @returns {HTMLElement} The element (for chaining).
- */
-export function removeStyles(el, prop) {
-  if (!el) return el;
-
-  if (typeof prop === "string") {
-    try {
-      el.style[prop] = "";
-    } catch (e) {}
-  } else if (Array.isArray(prop)) {
-    prop.forEach((p) => {
-      try {
-        el.style[p] = "";
-      } catch (e) {}
-    });
-  } else if (prop === undefined) {
-    const styles = getStyles(el);
-    Object.keys(styles).forEach((p) => {
-      try {
-        el.style[p] = "";
-      } catch (e) {}
-    });
-  }
-  return el;
-}
-
-// ============================================================
-// 🔍 UTILITY: Check styles
-// ============================================================
-
-/**
- * Checks whether a specific inline style is set on an element.
- *
- * @param {HTMLElement|null} el - The target element.
- * @param {string} prop - CSS property name (camelCase).
- * @returns {boolean} `true` if the property has a non-empty inline value.
- */
-export function hasStyle(el, prop) {
-  if (!el || !prop) return false;
-  return el.style[prop] !== "";
-}
-
-/**
- * Logs all inline styles of an element to the console in a readable format.
- * Useful for debugging style issues during development.
- *
- * @param {HTMLElement|null} el - The target element.
- * @param {string} [label="Styles"] - Label prefix shown in the console output.
- * @returns {Object|null} The styles object (same as `getStyles(el)`), or `null`
- *   when `el` is falsy.
- */
-export function logStyles(el, label = "Styles") {
-  if (!el) {
-    console.warn("⚠️ Invalid element");
-    return null;
-  }
-  const styles = getStyles(el);
-  console.log(`📋 ${label}:`);
-  if (Object.keys(styles).length === 0) {
-    console.log("  (No inline styles)");
-  } else {
-    Object.entries(styles).forEach(([p, v]) => console.log(`  ${p}: ${v}`));
-  }
-  return styles;
-}

package/src/widget-factory/translateProps.js

@@ -137,6 +137,11 @@ export const ALL_PROPS = [
   { prop: "justify", domProp: "justifyContent", type: "style", unit: "none", reactive: true },
   { prop: "justifyContent", domProp: "justifyContent", type: "style", unit: "none", reactive: true },
   { prop: "alignItems", domProp: "alignItems", type: "style", unit: "none", reactive: true },
+  // The child's own answer to the parent's `alignItems`: a control that stays where
+  // it wants inside a row that stretches everything else. Routed by the engine, so
+  // it belongs to every widget that can be a flex child, not only to the layouts.
+  { prop: "alignSelf", domProp: "alignSelf", type: "style", unit: "none", reactive: true },
+  { prop: "selfAlign", domProp: "alignSelf", type: "style", unit: "none", reactive: true },
   { prop: "wrap", domProp: "flexWrap", type: "style", unit: "none", reactive: true, boolValues: { true: "wrap", false: "nowrap" } },
   { prop: "flexWrap", domProp: "flexWrap", type: "style", unit: "none", reactive: true, boolValues: { true: "wrap", false: "nowrap" } },
   { prop: "flex", domProp: "flex", type: "style", unit: "none", reactive: true },

package/src/widget-factory/widgetFactory.js

@@ -104,7 +104,7 @@ export function WidgetFactory(tag, customProps = {}) {
   // ============================================================
   // 3. CREATE BASE WIDGET
   // ============================================================
-  const widget = createWidget(finalTag, {});
+  const widget = createWidget(finalTag);
   widget._widgetName = widgetName;
   widget._updating = false;
   widget._events = [];

package/src/widgets/Accordion.js

@@ -41,7 +41,7 @@ const ACCORDION_PROP_KEYS = [
  * @param {Function} [props.onToggle] - @deprecated Use `onPress` instead. Kept as alias for backward compatibility.
  * @param {'contained'|'outlined'|'ghost'} [props.variant='contained'] - Visual style variant.
  * @param {number} [props.borderRadius=8] - Corner radius in pixels.
- * @param {string} [props.bgColor=colors.surface] - Background color of the container (used in 'contained' variant).
+ * @param {string} [props.bgColor=colors.primaryBg] - Background color of the container (used in 'contained' variant).
  * @param {string} [props.titleColor=colors.text] - Text color of the title when collapsed.
  * @param {string} [props.expandedColor=colors.primary] - Accent color applied to the title-bar background when expanded.
  * @param {string|null} [props.border=null] - Explicit CSS border shorthand. Overrides variant-based border logic.
@@ -63,6 +63,8 @@ const ACCORDION_PROP_KEYS = [
  * @param {number} [props.elevation=0] - Box-shadow depth level (0–4).
  * @returns {HTMLElement} The accordion container element, augmented with public methods.
  */
+let accordionIdSeed = 0;
+
 export const Accordion = (props) => {
   const {
     title,
@@ -73,7 +75,13 @@ export const Accordion = (props) => {
     variant = "contained", // 'contained', 'outlined', 'ghost'
     borderRadius = 8,
     // Colors
-    bgColor = colors.surface,
+    //
+    // A 'contained' panel is a plate, so it has to read as one. `colors.surface`
+    // is the card an accordion already sits on — 1.00:1 in dark, 1.04:1 in light —
+    // which made the variant indistinguishable from 'ghost'. `primaryBg` is the
+    // palette's raised plate: 1.19:1 over the dark card (the overlay Material
+    // uses for elevation) and the same near-white step in light.
+    bgColor = colors.primaryBg,
     titleColor = colors.text,
     expandedColor = colors.primary,
     // Borders
@@ -128,6 +136,16 @@ export const Accordion = (props) => {
   let currentElevation = elevation;
   let currentAnimationDuration = animationDuration;
 
+  // The header and its panel reference each other (`aria-controls` one way,
+  // `aria-labelledby` back), so both need ids. Derived from the caller's `id`
+  // when there is one, the way `Input` does it, so a re-render keeps the pairing.
+  const baseId =
+    typeof rest.id === "string" && rest.id
+      ? rest.id
+      : `fletbox-accordion-${++accordionIdSeed}`;
+  const headerId = `${baseId}-header`;
+  const panelId = `${baseId}-panel`;
+
   // DOM references populated during widget construction
   let contentWrapper = null;
   let contentInner = null;
@@ -172,6 +190,13 @@ export const Accordion = (props) => {
     titleBar.style.opacity = currentDisabled ? "0.5" : "1";
     titleBar.style.padding = toREM(currentTitlePadding);
 
+    // `update()` cannot re-run the factory for the header, so the state the
+    // header announces lives here: a `disabled: true` update has to take the
+    // hinge off the Tab path, and an `expanded` change has to be answered.
+    titleBar.setAttribute("aria-expanded", String(isExpanded));
+    titleBar.setAttribute("aria-disabled", String(Boolean(currentDisabled)));
+    titleBar.tabIndex = currentDisabled ? -1 : 0;
+
     // Tint the title bar background slightly when expanded (contained only)
     if (currentVariant === "contained") {
       titleBar.style.backgroundColor = isExpanded
@@ -181,12 +206,17 @@ export const Accordion = (props) => {
       titleBar.style.backgroundColor = "transparent";
     }
 
-    // Show/hide the horizontal divider between title and content
-    if (currentDivider && isExpanded) {
-      contentInner.style.borderTop = `1px solid ${currentDividerColor}`;
-    } else {
-      contentInner.style.borderTop = "none";
-    }
+    // The header's hairline is the only thing that says "this row is a panel".
+    // The default 'contained' variant paints `colors.surface`, which measures
+    // 1.00:1 against a dark card and 1.04:1 against a light one, `elevation`
+    // starts at 0 and the border belongs to 'outlined' — so a shut accordion used
+    // to be a sentence with a chevron on it, and nothing marked it as pressable.
+    // The line belongs to the header, not to the gap below it: it is there open
+    // or shut, so it never doubles when the content appears.
+    titleBar.style.borderBottom = currentDivider
+      ? `1px solid ${currentDividerColor}`
+      : "none";
+    contentInner.style.borderTop = "none";
 
     // Apply border according to priority: explicit > outlined variant > none
     if (currentBorder) {
@@ -271,6 +301,10 @@ export const Accordion = (props) => {
 
     isAnimating = true;
     isExpanded = true;
+    // The disclosure state is answered at the press, not when the height
+    // animation lands: `updateUI` runs at the end of the transition, and a reader
+    // told "collapsed" while the panel is already opening is told a lie.
+    titleBar.setAttribute("aria-expanded", "true");
 
     // Make the content visible before measuring it
     contentWrapper.style.display = "block";
@@ -307,6 +341,10 @@ export const Accordion = (props) => {
     if (!isExpanded) return;
 
     isAnimating = true;
+    isExpanded = false;
+    // Same as `expand`: the disclosure answers for the state the press caused,
+    // not for the height the transition has not finished animating.
+    titleBar.setAttribute("aria-expanded", "false");
 
     // Pin the height to a pixel value first — "auto" cannot be animated
     const currentHeight = contentInner.scrollHeight + "px";
@@ -395,6 +433,21 @@ export const Accordion = (props) => {
 
   // Clickable title bar that contains the text and icon
   titleBar = Row({
+    // The press is a prop, not an assignment made after `Row()` has returned:
+    // the engine reads `widget.onclick` while the widget is built, and a header
+    // wired afterwards is a hinge only a mouse can operate.
+    onPress: () => toggle(),
+    role: "button",
+    id: headerId,
+    // A disclosure has to say which way it opens. Without `aria-expanded` a reader
+    // hears the same words for a closed section and an open one.
+    "aria-expanded": String(isExpanded),
+    "aria-controls": panelId,
+    "aria-disabled": String(Boolean(currentDisabled)),
+    tabIndex: currentDisabled ? -1 : 0,
+    // A header spans the whole card; the 2% press scale would move the title and
+    // the chevron with it.
+    disableTransform: true,
     alignItems: "center",
     justifyContent: "space-between",
     gap: 8,
@@ -411,6 +464,11 @@ export const Accordion = (props) => {
   // Outer wrapper whose height is animated — starts hidden when collapsed
   contentWrapper = WidgetFactory({
     tag: "div",
+    id: panelId,
+    // The panel is a landmark a reader can jump to from the header; `aria-labelledby`
+    // is what names it, since the title lives in the button rather than in a heading.
+    role: "region",
+    "aria-labelledby": headerId,
     overflow: "hidden",
     transition: animate
       ? `height ${currentAnimationDuration}ms cubic-bezier(0.4, 0, 0.2, 1)`
@@ -436,9 +494,6 @@ export const Accordion = (props) => {
   // Sync all styles with current state
   updateUI();
 
-  // Wire up the click handler on the title bar
-  titleBar.onclick = () => toggle();
-
   // Start watching for content size changes
   setupResizeObserver();
 
@@ -491,7 +546,10 @@ export const Accordion = (props) => {
         }
       }
     }
-    if (newProps.disabled !== undefined) currentDisabled = newProps.disabled;
+    if (newProps.disabled !== undefined && newProps.disabled !== currentDisabled) {
+      currentDisabled = newProps.disabled;
+      needsUIUpdate = true;
+    }
     if (newProps.variant !== undefined) currentVariant = newProps.variant;
     if (newProps.bgColor !== undefined) currentBgColor = newProps.bgColor;
     if (newProps.expandedColor !== undefined)

package/src/widgets/AdMob.js

@@ -195,7 +195,7 @@ export const AdMob = (props) => {
       tag: "span",
       text: currentLabel.toUpperCase(),
       color,
-      fontSize: 11,
+      fontSize: 12,
       fontWeight: 600,
       letterSpacing: 2,
       userSelect: "none",

package/src/widgets/AdSense.js

@@ -176,7 +176,7 @@ export const AdSense = (props) => {
         tag: "span",
         text: label.toUpperCase(),
         color,
-        fontSize: 11,
+        fontSize: 12,
         fontWeight: 600,
         letterSpacing: 2,
         userSelect: "none",

package/src/widgets/AlertDialog.js

@@ -47,21 +47,24 @@ export const AlertDialog = (props) => {
     ...rest
   } = props;
 
-  // Map each variant to its icon name, icon color, and confirm-button color
+  // Map each variant to its icon name, icon colour, and confirm-button plate.
+  // The signal tones (`colors.danger` and friends) are words-on-a-page inks; a
+  // filled confirm carries a label, so it takes the plate that label can sit on
+  // and lets Button pick the ink from the fill (`readableInk`).
   const variantColors = {
     normal: { confirm: colors.primary, icon: "info", iconColor: colors.info },
     danger: {
-      confirm: colors.danger,
+      confirm: colors.dangerPlate,
       icon: "warning",
       iconColor: colors.danger,
     },
     warning: {
-      confirm: colors.warning,
+      confirm: colors.warningPlate,
       icon: "error",
       iconColor: colors.warning,
     },
     success: {
-      confirm: colors.success,
+      confirm: colors.successPlate,
       icon: "check_circle",
       iconColor: colors.success,
     },
@@ -109,9 +112,10 @@ export const AlertDialog = (props) => {
     actions.push(
       Button({
         text: cancelText,
-        borderColor: colors.danger,
-        variant: "filled",
-        color: colors.danger,
+        // Cancel is the way out, not the decision: a second filled plate made
+        // both answers shout, and the red label measured 3.61:1 on the surface.
+        variant: "text",
+        color: colors.dangerStrong,
         onPress: () => {
           if (onCancel) onCancel();
           closeModal();
@@ -125,8 +129,6 @@ export const AlertDialog = (props) => {
       text: confirmText,
       variant: "filled",
       bgColor: variantStyle.confirm,
-      color: colors.text,
-      borderColor: colors.surface,
       onPress: () => {
         if (onConfirm) onConfirm();
         closeModal();

package/src/widgets/Avatar.js

@@ -142,7 +142,16 @@ export const Avatar = (inputProps = {}) => {
   /** Chooses the child element for the props currently held. */
   const buildContent = () => {
     if (src) {
-      return Image({ src, width: "100%", height: "100%", fit: "cover" });
+      return Image({
+        src,
+        width: "100%",
+        height: "100%",
+        fit: "cover",
+        // The avatar is decoration around the person's name, which the screen
+        // reads somewhere else. An `alt` here repeats a name the reader already
+        // hears; the empty string is the decision, not the omission.
+        alt: "",
+      });
     }
     if (icon) return Icon({ name: icon, size: size * 0.5, color: textColor });
     if (name) {

package/src/widgets/Badge.js

@@ -149,10 +149,16 @@ export const Badge = (props) => {
     return badgeElement;
   }
 
-  // Wrap the child and the badge in a Stack so the badge is positioned relative to the child
+  // Wrap the child and the badge in a Stack so the badge is positioned relative to
+  // the child. The wrapper has to BE the child's box: `display: inline-block` only
+  // shrinks to fit inside a block parent, and the common parent here is a flex
+  // Column, whose default `align-items: stretch` pulled the anchor to the full row
+  // width — so a badge on a 28px icon landed 250px away from it, on the far edge of
+  // the card. `alignSelf` is what resists that stretch.
   const badgeStack = Stack({
     position: "relative",
     display: "inline-block",
+    alignSelf: "flex-start",
     children: [validChild, badgeElement],
     ...rest,
   });