flet-box 1.0.7 → 1.0.9

package/docs/widget/Tabs.md

@@ -39,19 +39,19 @@ Tabs({
 | `onChange` | function | — | Fired with the new index when the tab changes. |
 | `variant` | `'underline'`/`'filled'`/`'slider'`/`'pills'` | `'underline'` | Visual treatment of the tab bar. |
 | `size` | `'small'`/`'medium'`/`'large'` | `'medium'` | Font, padding, icon, and height presets. |
-| `textColor` | Color | `colors.text` | Inactive label/icon color. |
-| `activeTextColor` | Color | `colors.white` | Active label/icon color. |
+| `textColor` | Color | `colors.textSecondary` | Inactive label/icon color. |
+| `activeTextColor` | Color | ink on `slider`, `colors.text` otherwise | Active label/icon color. |
 | `bgColor` | Color | `colors.gray100` | Bar background for `slider`/`filled` variants. |
-| `buttonColor` | Color | `colors.secondary` | Background of the `slider` indicator and `pills`. |
+| `buttonColor` | Color | `color` | Background of the `slider` indicator. |
 | `dividerColor` | Color | `colors.border` | Bottom border for the `underline` variant (when `showDivider`). |
 | `fullWidth` | boolean | `true` | Tabs share the full width; otherwise they hug their content. |
 | `showDivider` | boolean | `true` | Bottom divider under an `underline` bar. |
 | `showIcon` | boolean | `false` | Show the per-tab `icon`. |
-| `iconPosition` | `'left'`/`'right'`/`'top'`/`'bottom'` | `'left'` | Where the icon sits: `'left'` places it before the label; any other value places it after. |
+| `iconPosition` | `'left'`/`'right'`/`'top'`/`'bottom'` | `'left'` | Where the icon sits: `'left'` before the label, `'right'` after it, `'top'`/`'bottom'` stacked above/below the label row. |
 | `iconSize` | number | `18` | Icon size in pixels. |
 | `badges` | array | `[]` | Badge values per tab (`badges[i]`), or set them inline via `{ badge }`. |
 | `alignment` | `'left'`/`'center'`/`'right'` | `'left'` | Accepted for API compatibility; currently has no visual effect. |
-| `color` | Color | `colors.primary` | Accepted for API compatibility; active styling uses `activeTextColor`/`buttonColor` instead. |
+| `color` | Color | `colors.primary` | Accent: the `underline` indicator, the `pills` tint, and the default `buttonColor`. |
 
 These are the props specific to `Tabs`. It also accepts every [common prop](COMMON_PROPS.md).
 

package/docs/widget/Text.md

@@ -54,6 +54,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Tooltip.md

@@ -62,6 +62,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/TreeView.md

@@ -77,6 +77,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Video.md

@@ -49,6 +49,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flet-box",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Declarative, zero-dependency UI framework in vanilla JS — ship web, PWA, Android and iOS from one codebase",
   "type": "module",
   "main": "src/index.js",
@@ -19,7 +19,7 @@
     "dev": "node bin/cli.js run --hot",
     "build": "node bin/cli.js createBundle",
     "release": "node bin/cli.js release",
-    "test": "node scripts/check-widgets.mjs && node scripts/check-prop-registry.mjs && node scripts/check-docs-props.mjs && node scripts/check-api-surface.mjs && node scripts/check-router-base.mjs && node scripts/check-ota-assets.mjs && node scripts/check-cli-install.mjs && python3 tools/snippets-creator-flet-box/build_snippets.py --check && node scripts/check-snippets.mjs",
+    "test": "node scripts/check-widgets.mjs && node scripts/check-widget-scale.mjs && node scripts/check-prop-registry.mjs && node scripts/check-docs-props.mjs && node scripts/check-api-surface.mjs && node scripts/check-api-propscan.mjs && node scripts/check-router-base.mjs && node scripts/check-clean-ui.mjs && node scripts/check-ota-assets.mjs && node scripts/check-pwa-shell.mjs && node scripts/check-cli-install.mjs && python3 tools/snippets-creator-flet-box/build_snippets.py --check && node scripts/check-snippets.mjs",
     "test:browser": "node scripts/run-browser-tests.mjs"
   },
   "keywords": [

package/src/animations/AnimatedBox.js

@@ -381,7 +381,10 @@ const generateKeyframes = (animations) => {
 
     animations.forEach((anim) => {
       const effect = effectMap[anim.effect] || anim.effect;
-      const { from, to, reverse = true } = anim;
+      // Straight `from → to` is the default: a one-shot entry animation must hold
+      // `to`. Cycling back is opt-in, or every documented `opacity 0 → 1` faded
+      // to invisible again at 100%.
+      const { from, to, reverse = false } = anim;
 
       // A descriptor without `from`/`to` is malformed. Skip it with a warning
       // rather than throwing a TypeError out of the caller's entire render.

package/src/animations/MatrixRain.js

@@ -219,8 +219,9 @@ export const MatrixRain = (props = {}) => {
   // above), because the canvas has no parent until the caller appends it.
 
   /**
-   * Stops the animation loop, removes event listeners, disconnects the
-   * ResizeObserver, and removes the canvas from the DOM.
+   * Stops the animation loop, removes the window listeners and disconnects the
+   * ResizeObserver. The canvas stays where it is: the caller owns the element and
+   * decides whether to remove it, which is what the module contract documents.
    *
    * @returns {void}
    */
@@ -228,7 +229,6 @@ export const MatrixRain = (props = {}) => {
     if (animationId) cancelAnimationFrame(animationId);
     window.removeEventListener("resize", handleResize);
     if (resizeObserver) resizeObserver.disconnect();
-    if (canvas && canvas.parentNode) canvas.parentNode.removeChild(canvas);
   };
 
   // Chain cleanup so any previously assigned _cleanup is also called

package/src/index.d.ts

@@ -30,10 +30,48 @@ declare module 'flet-box' {
     _cleanup(): void;
   }
 
+  // =========================================================================
+  // Posicionamiento
+  // =========================================================================
+  /**
+   * Positional props accepted by every widget.
+   *
+   * `position: 'stack'` takes the widget out of normal flow and places it
+   * against its nearest positioned ancestor; the `center*` / `full*` shorthands
+   * only take effect in that mode. Numeric offsets are framework units (pixels
+   * on the 16px base, emitted as rem).
+   *
+   * A few widgets give `position` their own meaning — the toast/badge/tooltip
+   * anchor — and therefore omit this declaration, as does `Maps` for `center`.
+   */
+  export interface StackPositionProps {
+    position?: 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky' | 'stack';
+    /** Alias of `position`. */
+    pos?: 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky' | 'stack';
+    top?: Size;
+    right?: Size;
+    bottom?: Size;
+    left?: Size;
+    inset?: Size;
+    /** Logical spelling of `left`. */
+    start?: Size;
+    /** Logical spelling of `right`. */
+    end?: Size;
+    /** Alias of `zIndex`. */
+    z?: number;
+    zIndex?: number;
+    centerX?: boolean;
+    centerY?: boolean;
+    center?: boolean;
+    fullWidth?: boolean;
+    fullHeight?: boolean;
+    full?: boolean;
+  }
+
   // =========================================================================
   // Props comunes (heredadas by todos the widgets)
   // =========================================================================
-  export interface CommonProps {
+  export interface CommonProps extends StackPositionProps {
     width?: Size;
     height?: Size;
     // `Size`, not `number`: for a Text this is a font size and for a Button it is
@@ -49,6 +87,12 @@ declare module 'flet-box' {
     borderRadius?: number | string;
     elevation?: number;
     shadow?: string;
+    // Glass and filters. A CSS value string, not an object: `backdropFilter` is
+    // what makes a translucent card frosted rather than merely see-through, and
+    // `maskImage` is what fades a list out at its end.
+    filter?: string;
+    backdropFilter?: string;
+    maskImage?: string;
     opacity?: number;
     visible?: boolean;
     disabled?: boolean;
@@ -242,7 +286,7 @@ declare module 'flet-box' {
 
   export interface StackProps extends CommonProps {
     children?: Widget[];
-    position?: 'relative' | 'absolute';
+    position?: 'relative' | 'absolute' | 'stack';
     alignment?: 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
   }
   export function Stack(props: StackProps): Widget;
@@ -489,7 +533,7 @@ declare module 'flet-box' {
     getElement(): Widget;
   };
 
-  export interface AdMobProps extends CommonProps {
+  export interface AdMobProps extends Omit<CommonProps, 'position'> {
     adId?: string;
     isTesting?: boolean;
     position?: 'top' | 'bottom';
@@ -520,7 +564,7 @@ declare module 'flet-box' {
     getPlugin(): object | null;
   };
 
-  export interface BadgeProps extends CommonProps {
+  export interface BadgeProps extends Omit<CommonProps, 'position'> {
     value: string | number;
     child: Widget;
     bgColor?: Color;
@@ -1282,9 +1326,14 @@ declare module 'flet-box' {
   };
 
   export interface InspectorProps {
+    /** The widget whose call is reconstructed and painted. */
     widget: Widget;
+    /** Starting indentation depth of the printout. */
     indent?: number;
   }
+  /** Paints the reconstructed call of a widget tree. */
+  export function Inspector(props: InspectorProps): Widget;
+  /** Rebuilds the call that made a widget, as a string. */
   export function Inspector(widget: Widget, indent?: number): string;
   export function printWidgetCode(widget: Widget): void;
   export function inspectWidget(widget: Widget): Widget;
@@ -1362,7 +1411,7 @@ declare module 'flet-box' {
     getCurrentIndex(): number;
   };
 
-  export interface TooltipProps extends CommonProps {
+  export interface TooltipProps extends Omit<CommonProps, 'position'> {
     text: string;
     child: Widget;
     position?: 'top' | 'bottom' | 'left' | 'right';
@@ -1770,7 +1819,7 @@ declare module 'flet-box' {
     heading: number | null;
   }
 
-  export interface MapsProps extends CommonProps {
+  export interface MapsProps extends Omit<CommonProps, 'center'> {
     /** Initial view centre. Defaults to `[20, 0]`. */
     center?: LatLng;
     /** Integer zoom level, 0 = the whole world. Defaults to `2`. */
@@ -1884,6 +1933,10 @@ declare module 'flet-box' {
   export const colors: Record<string, string>;
   export const palettes: Record<string, Record<string, string>>;
   export function setTheme(themeName: 'light' | 'dark'): Record<string, string>;
+  export function registerPalette(
+    themeName: string,
+    palette: Record<string, string>
+  ): Record<string, string>;
   export function getTheme(): string;
   export function toggleTheme(): string;
   export function getColor(colorName: string, opacity?: number): string;
@@ -2084,9 +2137,12 @@ declare module 'flet-box' {
     isDark(): boolean;
     isLight(): boolean;
     contrast(): string;
+    luminance(): number;
+    contrastRatio(other: string | ColorInstance): number;
+    meetsContrast(other: string | ColorInstance, minimum?: number): boolean;
   }
 
-  export const color: (value: string) => ColorInstance;
+  export const color: (value: string | ColorInstance) => ColorInstance;
   export function rgba(r: number, g: number, b: number, a?: number): string;
   export function stackPosition(widget: Widget, props: { top?: any; right?: any; bottom?: any; left?: any }): Widget;
   export function flex(grow: number | { grow?: number; shrink?: number; basis?: string }, shrink?: number, basis?: string): string;
@@ -2195,5 +2251,5 @@ declare module 'flet-box' {
   // =========================================================================
   export const highlightColors: Record<string, string>;
   export function tokenize(code: string): Array<{ type: string; value: string }>;
-  export function generateHighlightedHtml(code: string): string;
+  export function generateHighlightedHtml(code: string, palette?: Record<string, string>): string;
 }

package/src/index.js

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

package/src/navigations/AppBar.js

@@ -59,6 +59,9 @@ import { goBack, goTo } from "./Router.js";
  *   - `setBackgroundColor(color: string)` — swap the background color or gradient.
  *   - `show()` / `hide()` — toggle bar visibility.
  */
+import { toREM } from "../utils/units.js";
+import { SHADOW_LEVELS } from "../tools/shadow.js";
+
 export const AppBar = (props) => {
   const {
     title,
@@ -119,18 +122,10 @@ export const AppBar = (props) => {
   const finalPaddingRight = paddingRight || padding;
 
   const finalBorderRadius =
-    typeof borderRadius === "number" ? `${borderRadius}px` : borderRadius;
+    toREM(borderRadius);
 
-  // Material Design elevation → box-shadow lookup table.
-  const shadows = {
-    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)",
-  };
-  const boxShadow = shadow === true ? shadows[elevation] : shadow || "none";
+  // The framework's depth scale, not a local copy of it (src/tools/shadow.js).
+  const boxShadow = shadow === true ? SHADOW_LEVELS[elevation] : shadow || "none";
 
   // ========== LEADING SECTION ==========
   // Auto-create a back button if requested and no custom leading was supplied.
@@ -173,7 +168,7 @@ export const AppBar = (props) => {
     marginBottom: finalMarginBottom,
     marginLeft: finalMarginLeft,
     marginRight: finalMarginRight,
-    paddingTop: `calc(${finalPaddingTop}px + env(safe-area-inset-top, 0px))`,
+    paddingTop: `calc(${toREM(finalPaddingTop)} + env(safe-area-inset-top, 0px))`,
     paddingBottom: finalPaddingBottom,
     paddingLeft: finalPaddingLeft,
     paddingRight: finalPaddingRight,

package/src/navigations/BottomNavigation.js

@@ -53,6 +53,9 @@ import { getCurrentPath, subscribe, goTo } from "./Router.js";
  *   - `getActiveIndex(): number` — returns the currently active tab index.
  *   - `getCurrentRoute(): string|null` — returns the current router path (router mode only).
  */
+import { toREM } from "../utils/units.js";
+import { SHADOW_LEVELS } from "../tools/shadow.js";
+
 export const BottomNavigation = (props) => {
   const {
     items = [],
@@ -90,24 +93,16 @@ export const BottomNavigation = (props) => {
   const finalMarginLeft = marginLeft || margin;
   const finalMarginRight = marginRight || margin;
   const finalBorderRadius =
-    typeof borderRadius === "number" ? `${borderRadius}px` : borderRadius;
-  const finalPadding = typeof padding === "number" ? `${padding}px` : padding;
+    toREM(borderRadius);
+  const finalPadding = toREM(padding);
 
-  // Material Design elevation → box-shadow lookup table.
-  const shadows = {
-    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)",
-  };
-  const boxShadow = shadow === true ? shadows[elevation] : shadow || "none";
+  // The framework's depth scale, not a local copy of it (src/tools/shadow.js).
+  const boxShadow = shadow === true ? SHADOW_LEVELS[elevation] : shadow || "none";
 
   const container = WidgetFactory({
     tag: "nav",
     display: "flex",
-    width: `calc(100% - ${finalMarginLeft}px - ${finalMarginRight}px)`,
+    width: `calc(100% - ${toREM(finalMarginLeft)} - ${toREM(finalMarginRight)})`,
     height: height,
     backgroundColor: backgroundColor,
     borderRadius: finalBorderRadius,

package/src/navigations/CollapsibleSideBar.js

@@ -42,6 +42,8 @@ import { colors } from "../utils/themes.js";
  * @returns {HTMLElement} The sidebar container element, augmented with:
  *   - `updateWidth(w: number|string)` — resize the sidebar programmatically.
  */
+import { toREM } from "../utils/units.js";
+
 export const CollapsibleSideBar = ({
   children,
   expanded = true,
@@ -63,14 +65,33 @@ export const CollapsibleSideBar = ({
   );
   let expandedState = Boolean(stateValue.valueOf());
 
+  /**
+   * Paint the expanded/collapsed state onto the elements built below.
+   *
+   * The toggle has to do more than record the state: the width, the chevron
+   * glyph and the content's interactivity are all written once at build time,
+   * so without this the bar never moved.
+   *
+   * @param {boolean} isExpanded
+   * @returns {void}
+   */
+  const paint = (isExpanded) => {
+    container.style.width = toREM(isExpanded ? widthExpanded : widthCollapsed);
+    chevron.textContent = isExpanded ? "chevron_left" : "chevron_right";
+    contentWrapper.style.opacity = isExpanded ? "1" : "0";
+    contentWrapper.style.pointerEvents = isExpanded ? "auto" : "none";
+  };
+
   /**
    * Toggle the sidebar between expanded and collapsed states.
-   * Updates the persisted state and fires the `onToggle` callback.
+   * Updates the persisted state, repaints the bar and fires the `onToggle`
+   * callback.
    */
   const toggle = () => {
     const newState = !expandedState;
     expandedState = newState;
     setIsExpanded(newState);
+    paint(newState);
     if (onToggle) onToggle(newState);
   };
 
@@ -81,7 +102,7 @@ export const CollapsibleSideBar = ({
     tag: "div",
     id,
     width:
-      typeof currentWidth === "number" ? `${currentWidth}px` : currentWidth,
+      toREM(currentWidth),
     height: "100%",
     display: "flex",
     flexDirection: "column",
@@ -95,15 +116,16 @@ export const CollapsibleSideBar = ({
 
   // Toggle button — always visible so the user can expand/collapse regardless
   // of the current state. The icon flips direction to reflect the state.
+  const chevron = Icon({
+    name: expandedState ? "chevron_left" : "chevron_right",
+    size: iconSize,
+    color: colors.textSecondary,
+  });
   const toggleButton = Container({
     padding: 16,
     cursor: "pointer",
     onclick: toggle,
-    child: Icon({
-      name: expandedState ? "chevron_left" : "chevron_right",
-      size: iconSize,
-      color: colors.textSecondary,
-    }),
+    child: chevron,
   });
   container.appendChild(toggleButton);
 
@@ -130,7 +152,7 @@ export const CollapsibleSideBar = ({
    */
   container.updateWidth = (newWidth) => {
     container.style.width =
-      typeof newWidth === "number" ? `${newWidth}px` : newWidth;
+      toREM(newWidth);
   };
 
   return container;

package/src/navigations/Drawer.js

@@ -58,6 +58,8 @@ let drawerInstance = null;
  * @param {DrawerProps} [props={}]
  * @returns {DrawerInstance}
  */
+import { toREM } from "../utils/units.js";
+
 export const Drawer = (props = {}) => {
   const {
     header,
@@ -107,9 +109,9 @@ export const Drawer = (props = {}) => {
   // Sliding drawer panel.
   const drawerPanel = document.createElement("div");
   drawerPanel.style.position = "absolute";
-  drawerPanel.style.top = `${margin}px`;
-  drawerPanel.style.bottom = `${margin}px`;
-  drawerPanel.style.height = `calc(100% - ${margin * 2}px)`;
+  drawerPanel.style.top = toREM(margin);
+  drawerPanel.style.bottom = toREM(margin);
+  drawerPanel.style.height = `calc(100% - ${toREM(margin * 2)})`;
   drawerPanel.style.display = "flex";
   drawerPanel.style.flexDirection = "column";
   drawerPanel.style.backgroundColor = bgColor;
@@ -118,22 +120,22 @@ export const Drawer = (props = {}) => {
   // Apply border radius only to the corners that face away from the screen edge.
   // A left drawer gets rounded right corners; a right drawer gets rounded left corners.
   if (position === "left") {
-    drawerPanel.style.left = `${margin}px`;
+    drawerPanel.style.left = toREM(margin);
     drawerPanel.style.right = "auto";
-    drawerPanel.style.borderTopRightRadius = `${borderRadius}px`;
-    drawerPanel.style.borderBottomRightRadius = `${borderRadius}px`;
+    drawerPanel.style.borderTopRightRadius = toREM(borderRadius);
+    drawerPanel.style.borderBottomRightRadius = toREM(borderRadius);
     drawerPanel.style.borderTopLeftRadius = "0";
     drawerPanel.style.borderBottomLeftRadius = "0";
   } else {
-    drawerPanel.style.right = `${margin}px`;
+    drawerPanel.style.right = toREM(margin);
     drawerPanel.style.left = "auto";
-    drawerPanel.style.borderTopLeftRadius = `${borderRadius}px`;
-    drawerPanel.style.borderBottomLeftRadius = `${borderRadius}px`;
+    drawerPanel.style.borderTopLeftRadius = toREM(borderRadius);
+    drawerPanel.style.borderBottomLeftRadius = toREM(borderRadius);
     drawerPanel.style.borderTopRightRadius = "0";
     drawerPanel.style.borderBottomRightRadius = "0";
   }
 
-  drawerPanel.style.width = typeof width === "number" ? `${width}px` : width;
+  drawerPanel.style.width = toREM(width);
   // Start the panel off-screen so the entrance animation slides it in.
   drawerPanel.style.transform =
     position === "left" ? "translateX(-100%)" : "translateX(100%)";
@@ -160,8 +162,8 @@ export const Drawer = (props = {}) => {
       header &&
         Container({
           flexShrink: 0,
-          borderTopLeftRadius: position === "right" ? `${borderRadius}px` : "0",
-          borderTopRightRadius: position === "left" ? `${borderRadius}px` : "0",
+          borderTopLeftRadius: position === "right" ? toREM(borderRadius) : "0",
+          borderTopRightRadius: position === "left" ? toREM(borderRadius) : "0",
           overflow: "hidden",
           child: header,
         }),
@@ -188,9 +190,9 @@ export const Drawer = (props = {}) => {
         Container({
           flexShrink: 0,
           borderBottomLeftRadius:
-            position === "right" ? `${borderRadius}px` : "0",
+            position === "right" ? toREM(borderRadius) : "0",
           borderBottomRightRadius:
-            position === "left" ? `${borderRadius}px` : "0",
+            position === "left" ? toREM(borderRadius) : "0",
           overflow: "hidden",
           child: footer,
         }),

package/src/navigations/DrawerItem.js

@@ -143,6 +143,8 @@ export const DrawerItem = (props) => {
    * Order of operations: mark selected → fire callbacks → navigate → close drawer.
    */
   const handleClick = () => {
+    // `onSelect` marks the transition into the selected state — it is what an
+    // app counts to open a section once. `onPress` fires on every tap.
     if (!isSelected) {
       isSelected = true;
       updateUI();
@@ -150,8 +152,8 @@ export const DrawerItem = (props) => {
       selectionEvent.dispatchEvent(
         new CustomEvent("drawer-item-selected", { detail: { id: label } }),
       );
+      if (onSelect) onSelect();
     }
-    if (onSelect) onSelect();
     if (onPress) onPress();
     if (route) goTo(route);
     if (closeOnPress) closeDrawer();

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;