flet-box 1.0.6 → 1.0.8

package/src/navigations/Scaffold.js

@@ -40,6 +40,8 @@ import { initRouter, getCurrentRoute, subscribe } from "./Router.js";
  *   - `updateLeftNavBar(cfg)` / `updateRightNavBar(cfg)` — replace sidebar content.
  *   - `setLeftNavBarWidth(w)` / `setRightNavBarWidth(w)` — resize a sidebar at runtime.
  */
+import { toREM } from "../utils/units.js";
+
 export const Scaffold = (props) => {
   const {
     appBar: originalAppBar,
@@ -106,11 +108,15 @@ export const Scaffold = (props) => {
    * Normalises a prop value to an HTMLElement.
    * Accepts an HTMLElement directly, a factory function, or null/undefined.
    *
-   * @param {HTMLElement|Function|null} item
+   * A boolean is the documented "show / hide this slot" value, never a widget,
+   * so it resolves to an empty slot instead of reaching appendChild() and
+   * throwing on a non-Node.
+   *
+   * @param {HTMLElement|Function|boolean|null} item
    * @returns {HTMLElement|null}
    */
   const toElement = (item) => {
-    if (!item) return null;
+    if (!item || typeof item === "boolean") return null;
     if (item instanceof HTMLElement) return item;
     if (typeof item === "function") return item();
     return item;
@@ -283,7 +289,7 @@ export const Scaffold = (props) => {
     if (widget) {
       leftNavBarContainer.appendChild(widget);
       if (mainContentContainer)
-        mainContentContainer.style.width = `calc(100% - ${leftNavBarWidth}px)`;
+        mainContentContainer.style.width = `calc(100% - ${toREM(leftNavBarWidth)})`;
     }
   };
 
@@ -359,9 +365,17 @@ export const Scaffold = (props) => {
       if (closeDrawerOnNavigate && drawerInstance && drawerInstance.close) {
         drawerInstance.close();
       }
-    } else if (body) {
-      const bodyWidget = makeFullSize(toElement(body));
-      if (bodyWidget) mainContentContainer.appendChild(bodyWidget);
+    } else {
+      if (body) {
+        const bodyWidget = makeFullSize(toElement(body));
+        if (bodyWidget) mainContentContainer.appendChild(bodyWidget);
+      }
+      // Static mode mounts the shell zones too. They used to be router-only, so
+      // the documented `Scaffold({ appBar, body })` example rendered the body
+      // with no top bar, bottom bar or FAB at all.
+      updateAppBar(originalAppBar !== false);
+      updateBottomBar(originalBottomBar !== false);
+      updateFab(originalFab !== false);
     }
   };
 
@@ -389,7 +403,7 @@ export const Scaffold = (props) => {
 
     if (finalLeftNavBar) {
       leftNavBarContainer = document.createElement("div");
-      leftNavBarContainer.style.width = `${leftNavBarWidth}px`;
+      leftNavBarContainer.style.width = toREM(leftNavBarWidth);
       leftNavBarContainer.style.flexShrink = "0";
       leftNavBarContainer.style.overflow = "auto";
       leftNavBarContainer.style.height = "100%";
@@ -409,7 +423,7 @@ export const Scaffold = (props) => {
 
     if (finalRightNavBar) {
       rightNavBarContainer = document.createElement("div");
-      rightNavBarContainer.style.width = `${rightNavBarWidth}px`;
+      rightNavBarContainer.style.width = toREM(rightNavBarWidth);
       rightNavBarContainer.style.flexShrink = "0";
       rightNavBarContainer.style.overflow = "auto";
       rightNavBarContainer.style.height = "100%";
@@ -425,8 +439,8 @@ export const Scaffold = (props) => {
     // FAB slot — absolutely positioned so it floats above content.
     fabContainer = document.createElement("div");
     fabContainer.style.position = "absolute";
-    fabContainer.style.bottom = "16px";
-    fabContainer.style.right = "16px";
+    fabContainer.style.bottom = toREM(16);
+    fabContainer.style.right = toREM(16);
     fabContainer.style.zIndex = "10";
     container.appendChild(fabContainer);
 
@@ -528,7 +542,7 @@ export const Scaffold = (props) => {
    */
   container.setLeftNavBarWidth = (w) => {
     if (leftNavBarContainer)
-      leftNavBarContainer.style.width = typeof w === "number" ? `${w}px` : w;
+      leftNavBarContainer.style.width = toREM(w);
   };
 
   /**
@@ -538,7 +552,7 @@ export const Scaffold = (props) => {
    */
   container.setRightNavBarWidth = (w) => {
     if (rightNavBarContainer)
-      rightNavBarContainer.style.width = typeof w === "number" ? `${w}px` : w;
+      rightNavBarContainer.style.width = toREM(w);
   };
 
   return container;

package/src/navigations/Tabs.js

@@ -2,9 +2,11 @@
 import { WidgetFactory } from "../widget-factory/index.js";
 import { colors } from "../utils/themes.js";
 import { Container } from "../widgets/Container.js";
+import { Column } from "../widgets/Column.js";
 import { Row } from "../widgets/Row.js";
 import { Text } from "../widgets/Text.js";
 import { Icon } from "../widgets/Icon.js";
+import { toREM } from "../utils/units.js";
 
 /**
  * @typedef {Object} TabDefinition
@@ -66,14 +68,16 @@ export const Tabs = (props) => {
     variant = "underline",
     size = "medium",
     color = colors.primary,
-    textColor = colors.text,
-    // FIX: `colors.white` no existe en themes.js → caía a `undefined`
-    // y el tab activo no se distinguía visualmente. Uso `colors.background`
-    // (que es "#ffffff" en el tema claro y "#0f172a" en el oscuro, que es
-    // lo correcto: contraste sobre el fondo del tab activo).
-    activeTextColor = colors.background,
+    textColor = colors.textSecondary,
+    // `background` made the active label the page color, so it vanished on a
+    // transparent tab bar (2.4:1 in light, 1.3:1 in dark). Resolved per variant
+    // below: the slider sits on a secondary thumb and needs the ink color.
+    activeTextColor,
     bgColor = colors.gray100,
-    buttonColor = colors.secondary,
+    // The thumb carries the accent, and its label is the ink color in both
+    // themes. `secondary` missed AA on the light thumb (4.23:1); primary is
+    // 6.65:1 with ink, 6.68:1 in dark.
+    buttonColor = color,
     alignment = "left",
     fullWidth = true,
     showDivider = true,
@@ -86,7 +90,7 @@ export const Tabs = (props) => {
   } = props;
 
   let currentIndex = activeIndex;
-  let sliderIndicator = null;
+  let activeIndicator = null;
   let tabsWrapperRef = null;
   let tabButtonsRef = [];
 
@@ -99,6 +103,16 @@ export const Tabs = (props) => {
   };
   const sz = sizes[size] || sizes.medium;
 
+  const resolvedActiveTextColor =
+    activeTextColor ?? (variant === "slider" ? colors.onPrimary : colors.text);
+
+  const tabBackground = (isActive) => {
+    if (!isActive) return "transparent";
+    if (variant === "pills") return `${color}1A`;
+    if (variant === "filled") return colors.card;
+    return "transparent";
+  };
+
   /** Extract display label from a tab definition or plain string. */
   const getLabel = (t) =>
     typeof t === "object" ? t.label || t.title : String(t);
@@ -157,43 +171,64 @@ export const Tabs = (props) => {
     const badge = getBadge(idx);
     const isActive = currentIndex === idx;
 
-    // Build the row of content inside each tab button.
-    const content = [];
-    if (showIcon && icon && iconPosition === "left") {
-      content.push(
-        Icon({
-          name: icon,
-          size: iconSize || sz.i,
-          color: isActive ? activeTextColor : textColor,
-        }),
-      );
-    }
-    if (label) {
-      content.push(
-        Text({
+    // Build the content inside each tab button. Every documented value of
+    // `iconPosition` keeps the icon: "left" puts it before the label, "right"
+    // after it, and "top"/"bottom" stack it above/below the label row.
+    const iconWidget =
+      showIcon && icon
+        ? Icon({
+            name: icon,
+            size: iconSize || sz.i,
+            color: isActive ? resolvedActiveTextColor : textColor,
+          })
+        : null;
+    const labelWidget = label
+      ? Text({
           text: label,
           size: sz.f,
-          color: isActive ? activeTextColor : textColor,
+          color: isActive ? resolvedActiveTextColor : textColor,
           weight: isActive ? "500" : "400",
-        }),
-      );
-    }
-    if (badge) {
-      content.push(
-        Container({
+        })
+      : null;
+    const badgeWidget = badge
+      ? Container({
           backgroundColor: colors.danger,
           borderRadius: 10,
           padding: "2px 6px",
           marginLeft: 4,
           child: Text({ text: String(badge), size: 10, color: "#fff" }),
-        }),
-      );
+        })
+      : null;
+
+    const line = [labelWidget, badgeWidget].filter(Boolean);
+    if (iconWidget && iconPosition !== "top" && iconPosition !== "bottom") {
+      if (iconPosition === "left") line.unshift(iconWidget);
+      else line.push(iconWidget);
     }
+    const labelRow = Row({
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 4,
+      children: line,
+    });
+    const stacked =
+      iconWidget && (iconPosition === "top" || iconPosition === "bottom");
+    const content = stacked
+      ? Column({
+          alignItems: "center",
+          justifyContent: "center",
+          gap: 4,
+          children:
+            iconPosition === "top"
+              ? [iconWidget, labelRow]
+              : [labelRow, iconWidget],
+        })
+      : labelRow;
 
     const btn = Container({
       borderRadius: variant === "slider" ? 20 : variant === "pills" ? 20 : 0,
-      backgroundColor: "transparent",
-      color: isActive ? activeTextColor : textColor,
+      backgroundColor: tabBackground(isActive),
+      color: isActive ? resolvedActiveTextColor : textColor,
       display: "flex",
       alignItems: "center",
       justifyContent: "center",
@@ -220,12 +255,7 @@ export const Tabs = (props) => {
           }
         }
       },
-      child: Row({
-        alignItems: "center",
-        justifyContent: "center",
-        gap: 4,
-        children: content,
-      }),
+      child: content,
     });
 
     btn.onclick = () => {
@@ -242,20 +272,34 @@ export const Tabs = (props) => {
   tabButtonsRef = tabButtons;
 
   // The slider variant uses an absolutely positioned "thumb" div that
-  // animates to the active tab's position via CSS transform.
-  if (variant === "slider") {
-    sliderIndicator = WidgetFactory({
+  // animates to the active tab's position via CSS transform. The default
+  // `underline` variant needs the same moving element: without it the active
+  // tab had no cue besides its label color.
+  const usesIndicator = variant === "slider" || variant === "underline";
+  if (usesIndicator) {
+    activeIndicator = WidgetFactory({
       tag: "div",
       position: "absolute",
-      top: "4px",
-      left: "4px",
-      height: "calc(100% - 8px)",
-      backgroundColor: buttonColor,
-      borderRadius: 20,
+      ...(variant === "slider"
+        ? {
+            top: "4px",
+            left: "4px",
+            height: "calc(100% - 8px)",
+            backgroundColor: buttonColor,
+            borderRadius: 20,
+          }
+        : {
+            bottom: "0",
+            left: "0",
+            height: "2px",
+            backgroundColor: color,
+            borderRadius: "2px 2px 0 0",
+          }),
       transition: "transform 0.3s ease, width 0.3s ease",
+      pointerEvents: "none",
       zIndex: 1,
     });
-    tabsWrapper.appendChild(sliderIndicator);
+    tabsWrapper.appendChild(activeIndicator);
   }
 
   tabBar.appendChild(tabsWrapper);
@@ -263,7 +307,7 @@ export const Tabs = (props) => {
 
   const contentContainer = Container({
     display: "flex",
-    padding: `${sz.cp}px 0`,
+    padding: `${toREM(sz.cp)} 0`,
     width: "100%",
     overflow: "auto",
   });
@@ -284,13 +328,13 @@ export const Tabs = (props) => {
    * Reads live DOM rectangles so it stays accurate after layout changes.
    */
   const updateSliderPosition = () => {
-    if (!sliderIndicator || !tabButtonsRef[currentIndex]) return;
+    if (!activeIndicator || !tabButtonsRef[currentIndex]) return;
     const btn = tabButtonsRef[currentIndex];
     const wrapperRect = tabsWrapperRef.getBoundingClientRect();
     const btnRect = btn.getBoundingClientRect();
     const left = btnRect.left - wrapperRect.left;
-    sliderIndicator.style.width = `${btnRect.width}px`;
-    sliderIndicator.style.transform = `translateX(${left}px)`;
+    activeIndicator.style.width = `${btnRect.width}px`;
+    activeIndicator.style.transform = `translateX(${left}px)`;
   };
 
   /**
@@ -308,14 +352,15 @@ export const Tabs = (props) => {
 
       const textSpan = btn.querySelector("span:not(.material-icons)");
       if (textSpan) {
-        textSpan.style.color = isActive ? activeTextColor : textColor;
+        textSpan.style.color = isActive ? resolvedActiveTextColor : textColor;
         textSpan.style.fontWeight = isActive ? "500" : "400";
       }
       const iconEl = btn.querySelector(".material-icons");
       if (iconEl) {
-        iconEl.style.color = isActive ? activeTextColor : textColor;
+        iconEl.style.color = isActive ? resolvedActiveTextColor : textColor;
       }
-      btn.style.color = isActive ? activeTextColor : textColor;
+      btn.style.color = isActive ? resolvedActiveTextColor : textColor;
+      btn.style.backgroundColor = tabBackground(isActive);
     });
 
     updateSliderPosition();
@@ -341,17 +386,17 @@ export const Tabs = (props) => {
   const handleResize = () => {
     clearTimeout(resizeTimeout);
     resizeTimeout = setTimeout(() => {
-      if (sliderIndicator && tabButtonsRef[currentIndex]) {
+      if (activeIndicator && tabButtonsRef[currentIndex]) {
         updateSliderPosition();
       }
     }, 100);
   };
   window.addEventListener("resize", handleResize);
 
-  // Also observe the tab bar element itself so the thumb repositions when
+  // Also observe the tab bar element itself so the indicator repositions when
   // the container resizes independently of the window (e.g. sidebar toggle).
-  // Only the slider variant has a thumb, so skip it for the other variants.
-  if (variant === "slider" && typeof ResizeObserver !== "undefined") {
+  // Only slider and underline render an indicator, so skip it for the others.
+  if (usesIndicator && typeof ResizeObserver !== "undefined") {
     resizeObserver = new ResizeObserver(() => updateSliderPosition());
     if (tabsWrapperRef) resizeObserver.observe(tabsWrapperRef);
   }

package/src/tools/color.js

@@ -291,6 +291,60 @@ class Color {
     return this.isDark() ? "#ffffff" : "#000000";
   }
 
+  /**
+   * Relative luminance of the color, as WCAG 2.1 defines it.
+   *
+   * Each channel is sRGB-decoded (the linear branch below 0.04045 is the one
+   * that matters for dark colors, where `isDark()`'s BT.601 luma is a poor
+   * proxy) and weighted 0.2126 / 0.7152 / 0.0722. Alpha is ignored: this is the
+   * luminance of the color itself, so a translucent color must be composited
+   * over its background before being measured.
+   *
+   * @returns {number} 0 for black, 1 for white
+   */
+  luminance() {
+    const channel = (value) => {
+      const c = value / 255;
+      return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    };
+    return (
+      0.2126 * channel(this.r) + 0.7152 * channel(this.g) + 0.0722 * channel(this.b)
+    );
+  }
+
+  /**
+   * Contrast ratio between this color and another, in WCAG terms.
+   *
+   * Returns the ratio of the lighter luminance to the darker one, from 1
+   * (identical) to 21 (black on white). This is what the readability thresholds
+   * are written against: 4.5 for body text, 3 for large text (>= 24px, or 19px
+   * bold) and for a control's own outline against the surface it sits on.
+   *
+   * @param {string|Color} other - The second color (any form `color()` parses).
+   * @returns {number} Contrast ratio, >= 1
+   * @example
+   * color('#64748b').contrastRatio('#ffffff'); // 4.76 — the textSecondary token, passes
+   * color('#94a3b8').contrastRatio('#ffffff'); // 2.56 — the textDisabled token, fails
+   */
+  contrastRatio(other) {
+    const a = this.luminance();
+    const b = other instanceof Color ? other.luminance() : color(other).luminance();
+    const light = Math.max(a, b);
+    const dark = Math.min(a, b);
+    return (light + 0.05) / (dark + 0.05);
+  }
+
+  /**
+   * Whether this color and another clear a WCAG contrast threshold.
+   *
+   * @param {string|Color} other - The color it is read against.
+   * @param {number} [minimum=4.5] - The ratio required: 4.5 body text, 3 large text.
+   * @returns {boolean} `true` when the pair is at or above `minimum`
+   */
+  meetsContrast(other, minimum = 4.5) {
+    return this.contrastRatio(other) >= minimum;
+  }
+
   /**
    * Invert the color by complementing each RGB channel.
    *

package/src/tools/index.js

@@ -20,7 +20,15 @@ export { default as padding } from "./padding.js";
 export { print } from "./print.js";
 export { random } from "./random.js";
 export { default as rgba } from "./rgba.js";
-export { default as shadow } from "./shadow.js";
+export {
+  SPACING_SCALE,
+  RADIUS_SCALE,
+  TYPE_SCALE,
+  TAP_MINIMUM,
+  PILL,
+  LABEL_TEXT,
+} from "./scale.js";
+export { default as shadow, SHADOW_LEVELS } from "./shadow.js";
 export {
   capitalize,
   capitalizeWords,

package/src/tools/scale.js

@@ -0,0 +1,41 @@
+// scale.js - The framework's design scales: the numbers every widget default is drawn from.
+
+/**
+ * The clean-UI contract, expressed as data instead of prose.
+ *
+ * These are the same scales `flet-box check-ui` enforces against an app's own
+ * source. They live here because a gate that only reads the app cannot make the
+ * app clean: it can reject a `padding: 21`, but the widget defaults the app never
+ * typed already decide the rhythm, the radius and the tap size of every screen.
+ * A default below the Fitts floor is a rule the framework breaks on the user's
+ * behalf, and no amount of app-side linting can undo it.
+ *
+ * Units are framework units, not CSS pixels. A numeric length prop goes through
+ * the factory's `toREM` (`src/utils/units.js`), so `40` is emitted as `2.5rem`:
+ * 40px at the 16px base, and *bigger* when the reader raises their browser font.
+ * That is the point — a tap target written in rem obeys the accessibility
+ * setting, while the 44px the guidelines quote is a fixed-pixel floor that
+ * shrinks in relative terms the moment the type grows.
+ *
+ * Depth is the exception: `SHADOW_LEVELS` ships raw `px` inside the box-shadow
+ * string on purpose, because a shadow that scales with the reader's font size
+ * stops matching the surface it lifts.
+ */
+
+/** A radius this large clamps to half the box: a pill, whatever the widget's size. */
+export const PILL = 999;
+
+/** The 8-based rhythm, with the two steps a real layout needs (18 for field text, 96 for hero gutters). */
+export const SPACING_SCALE = new Set([0, 4, 8, 12, 16, 18, 24, 32, 40, 48, 64, 96]);
+
+/** Corner radii. `999` is a pill, `0` a flush edge — both are decisions, not omissions. */
+export const RADIUS_SCALE = new Set([0, 4, 8, 12, 16, PILL]);
+
+/** Type sizes. Two steps per jump: a 15 next to a 16 reads as a mistake, not as hierarchy. */
+export const TYPE_SCALE = new Set([12, 14, 16, 18, 24, 32, 40, 48]);
+
+/** Fitts: the smallest pressable box a finger reliably hits. */
+export const TAP_MINIMUM = 40;
+
+/** The reading size a control's own label may not fall under. */
+export const LABEL_TEXT = 14;

package/src/tools/shadow.js

@@ -20,4 +20,24 @@
 const shadow = (x, y, blur, spread, color) =>
   `${x}px ${y}px ${blur}px ${spread}px ${color}`;
 
+/**
+ * The framework's depth scale, shared by every widget that lifts off the page.
+ *
+ * The engine routes `elevation` straight into `style.boxShadow`, so a bare
+ * number is an invalid declaration the browser drops without a word: a widget
+ * that forwards `elevation` instead of one of these strings looks configured and
+ * paints flat. A widget that wants a numeric depth reads the level here and
+ * passes the resulting string.
+ *
+ * `0` is deliberately `none` — a flush surface is a decision, not a missing one.
+ */
+export const SHADOW_LEVELS = {
+  0: "none",
+  1: "0 1px 3px rgba(0,0,0,0.12)",
+  2: "0 3px 6px rgba(0,0,0,0.16)",
+  3: "0 6px 12px rgba(0,0,0,0.2)",
+  4: "0 10px 20px rgba(0,0,0,0.25)",
+  5: "0 15px 30px rgba(0,0,0,0.3)",
+};
+
 export default shadow;

package/src/utils/index.js

@@ -25,6 +25,7 @@
 export {
   colors,
   setTheme,
+  registerPalette,
   getTheme,
   toggleTheme,
   subscribeTheme,

package/src/utils/readableInk.js

@@ -0,0 +1,19 @@
+import { color } from "../tools/color.js";
+
+const SOLID_COLOR =
+  /^(#[0-9a-f]{3,8}|rgba?\(\s*\d|hsla?\(\s*\d|black|white|red|green|blue|yellow|cyan|magenta|gray|darkgray|lightgray)$/i;
+
+/**
+ * Black or white, whichever reads better on `background` by WCAG contrast.
+ * Falls back when the fill is not a solid color this code can measure (a
+ * gradient, a CSS variable) — guessing there is worse than the caller's choice.
+ */
+export const readableInk = (background, fallback) => {
+  if (typeof background !== "string" || !SOLID_COLOR.test(background)) {
+    return fallback;
+  }
+  const bg = color(background);
+  return bg.contrastRatio("#ffffff") >= bg.contrastRatio("#000000")
+    ? "#ffffff"
+    : "#000000";
+};