flet-box 1.0.7 → 1.0.8

package/src/utils/themes.js

@@ -2,11 +2,37 @@
 
 // ========== DEFAULT COLORS (static, safe) ==========
 const DEFAULT_COLORS = {
-  primary: "#6366f1",
+  // #6366f1 put white on 4.47:1 — a hair under AA for a button label. Two units
+  // darker measures 4.55:1, the same indigo, and every brand button passes.
+  primary: "#6165ef",
   secondary: "#8b5cf6",
   success: "#10b981",
   warning: "#f59e0b",
+  // The readable greens and ambers, same rule as the red below: #10b981 and
+  // #f59e0b carry white at 2.54:1 and 2.15:1, so they are dots and borders. These
+  // are the ones a person can read or press — 5.48:1 and 5.02:1, both directions.
+  successStrong: "#047857",
+  warningStrong: "#b45309",
+  // #ef4444 is the error *signal*: a badge, an icon, a border. As words on a
+  // white page it measures 3.76:1, which is not AA, and white on it is 3.76 too.
   danger: "#ef4444",
+  // The red a person can read and press: 6.47:1 against white in both directions,
+  // so it is legal as the label of a delete and as the plate under white words.
+  dangerStrong: "#b91c1c",
+  // `*Strong` answers "what may I write words in?" and its answer moves with the
+  // theme; `*Plate` answers "what may I fill, with white words on it?" and stays
+  // deep everywhere. On a light page the two are the same red — #b91c1c reads at
+  // 6.47:1 and carries white at 6.47:1 — so the light values below coincide with
+  // the Strong ones on purpose. On a dark page they part: the readable red is
+  // light, the plate behind white has to be dark.
+  successPlate: "#047857",
+  warningPlate: "#b45309",
+  dangerPlate: "#b91c1c",
+  // `info` had no readable sibling and it showed: a filled chip, a selected page
+  // or a tooltip that asks for `colors.info` paints white on #3b82f6, which is
+  // 3.68:1. This is the blue that carries the label — 6.70:1 in both directions.
+  infoStrong: "#1d4ed8",
+  infoPlate: "#1d4ed8",
   info: "#3b82f6",
   background: "#ffffff",
   surface: "#f8fafc",
@@ -14,6 +40,19 @@ const DEFAULT_COLORS = {
   text: "#0f172a",
   textSecondary: "#64748b",
   textDisabled: "#94a3b8",
+  // What to write on a `primary` fill. White measures 4.55:1 on #6165ef.
+  onPrimary: "#ffffff",
+  // What to write on a `secondary` fill (badges, tooltips). Neutral secondary is
+  // a dark plate in both themes, so its ink is white as well.
+  onSecondary: "#ffffff",
+  // The soft brand tint a card or icon chip uses instead of `primary + '15'`.
+  primaryBg: "#eef2ff",
+  // Glass is a translucent surface meant to sit over content with
+  // `backdropFilter`. It is a token and not an `rgba()` in the app for the same
+  // reason as every other color: the theme has to be able to move it, and the
+  // app's clean-UI gate rejects a hand-written literal (`RAW_COLOR`).
+  glass: "rgba(255, 255, 255, 0.66)",
+  glassBorder: "rgba(255, 255, 255, 0.75)",
   border: "#e2e8f0",
   gray50: "#f8fafc",
   gray100: "#f1f5f9",
@@ -41,58 +80,133 @@ export let colors = { ...DEFAULT_COLORS };
 // ========== PALETTES ==========
 export const palettes = {
   light: {
-    primary: "#00A5FF",
-    secondary: "#8b5cf6",
+    // Chakra's neutral scale: a white page, #09090B ink, #E4E4E7 hairlines,
+    // #FAFAFA panels and a near-black solid for everything selected or primary.
+    // `primary` is the plate under a checked box, an active page, a filled chip
+    // and the slider fill, so it has to be dark enough to carry its label:
+    // #18181B measures 17.3:1 with white, and reads as ink on the page too.
+    primary: "#18181b",
+    secondary: "#52525b",
     success: "#10b981",
     warning: "#f59e0b",
     danger: "#ef4444",
+    dangerStrong: "#b91c1c",
+    successStrong: "#047857",
+    warningStrong: "#b45309",
+    // On a white page the readable red and the plate under white words are the
+    // same red, so the plates repeat the Strong values rather than inventing a
+    // fourth tone that no one would notice the difference from.
+    dangerPlate: "#b91c1c",
+    successPlate: "#047857",
+    warningPlate: "#b45309",
+    infoStrong: "#1d4ed8",
+    infoPlate: "#1d4ed8",
     info: "#3b82f6",
     background: "#ffffff",
-    surface: "#f8fafc",
+    surface: "#fafafa",
     card: "#ffffff",
-    text: "#0f172a",
-    textSecondary: "#64748b",
-    textDisabled: "#94a3b8",
-    border: "#e2e8f0",
-    gray50: "#f8fafc",
-    gray100: "#f1f5f9",
-    gray200: "#e2e8f0",
-    gray300: "#cbd5e1",
-    gray400: "#94a3b8",
-    gray500: "#64748b",
-    gray600: "#475569",
-    gray700: "#334155",
-    gray800: "#1e293b",
-    gray900: "#0f172a",
-    overlay: "rgba(0, 0, 0, 0.4)",
-    shadow: "rgba(0, 0, 0, 0.1)",
+    text: "#09090b",
+    // What to write on a `primary` fill. This is the theme's answer, not the
+    // widget's: `#18181B` is dark, so its ink is white.
+    onPrimary: "#ffffff",
+    // Badges and tooltips sit on `secondary` (#52525B), dark enough for white.
+    onSecondary: "#ffffff",
+    // The soft neutral tint a card or icon chip uses instead of `primary + '15'`.
+    primaryBg: "#f4f4f5",
+    glass: "rgba(255, 255, 255, 0.78)",
+    glassBorder: "rgba(9, 9, 11, 0.10)",
+    textSecondary: "#52525b",
+    textDisabled: "#a1a1aa",
+    border: "#e4e4e7",
+    gray50: "#fafafa",
+    gray100: "#f4f4f5",
+    gray200: "#e4e4e7",
+    gray300: "#d4d4d8",
+    gray400: "#a1a1aa",
+    gray500: "#71717a",
+    gray600: "#52525b",
+    gray700: "#3f3f46",
+    gray800: "#27272a",
+    gray900: "#18181b",
+    divider: "#e4e4e7",
+    overlay: "rgba(0, 0, 0, 0.5)",
+    shadow: "rgba(0, 0, 0, 0.08)",
   },
   dark: {
-    primary: "#00AFBC",
-    secondary: "#a78bfa",
+    // The same zinc ladder read from the other end: #09090B page, #18181B cards
+    // and bars, #27272A hairlines, #A1A1AA secondary words. Every surface token
+    // is a true grey, so any widget that paints `surface`, `card`, `gray*` or
+    // `border` lands on the same black/grey/white hierarchy; only the semantic
+    // signals below keep a hue.
+    //
+    // `primary` is the inverse of the light theme: a near-white solid whose
+    // labels are the page ink (#09090B on #FAFAFA = 17.4:1). That is the same
+    // solid Chakra paints in dark mode, and it only works because a widget that
+    // writes on a primary fill asks the theme — `colors.onPrimary` — instead of
+    // assuming white.
+    primary: "#fafafa",
+    secondary: "#71717a",
     success: "#10b981",
     warning: "#fbbf24",
     danger: "#f87171",
+    // On this page "the tone a person can read" is the light one, because the
+    // page is dark: #fca5a5 measures 9.33:1 on a card, 10.48:1 on the page, and
+    // the base signal #f87171 is already readable at 6.40:1. `*Strong` keeps its
+    // promise here — the red you may write words in — it just points the other
+    // way down the ladder than it does on a white page.
+    dangerStrong: "#fca5a5",
+    successStrong: "#34d399",
+    warningStrong: "#fcd34d",
+    // The deep plates are the tokens that used to hide inside `*Strong`. A badge
+    // or a completed step is a fill carrying white words, which on this page means
+    // going dark: white on #7f1d1d is 10.02:1, on #14532d 9.11:1, on #78350f 9.07:1.
+    dangerPlate: "#7f1d1d",
+    successPlate: "#14532d",
+    warningPlate: "#78350f",
+    // The same pair for the blue: #93c5fd is the word a person reads on this page
+    // (11.03:1), #1e40af is the plate a white label sits on (8.72:1).
+    infoStrong: "#93c5fd",
+    infoPlate: "#1e40af",
+    // The alert tints are a *fill*, and a pale pink fill is the wrong answer on a
+    // black page: `#fafafa` on `#ffe5e5` measures 1.14:1, so an error card that
+    // used to be painted from the boot value went unreadable in dark mode. These
+    // are the same deep tints a generated app's own palette declares, so an app
+    // that themes its alert the framework way and one that themes it by hand land
+    // on one number: the Strong ink of that hue sits on them at 6.04–10.51:1.
+    error: "#f87171",
+    errorBg: "#3b1113",
+    successBg: "#0c2f22",
+    warningBg: "#33230a",
+    infoBg: "#12263c",
     info: "#60a5fa",
-    background: "#0f172a",
-    surface: "#1e293b",
-    card: "#1e293b",
-    text: "#f1f5f9",
-    textSecondary: "#94a3b8",
-    textDisabled: "#64748b",
-    border: "#334155",
-    gray50: "#1e293b",
-    gray100: "#334155",
-    gray200: "#475569",
-    gray300: "#64748b",
-    gray400: "#94a3b8",
-    gray500: "#cbd5e1",
-    gray600: "#e2e8f0",
-    gray700: "#f1f5f9",
-    gray800: "#f8fafc",
-    gray900: "#ffffff",
-    overlay: "rgba(0, 0, 0, 0.6)",
-    shadow: "rgba(0, 0, 0, 0.3)",
+    background: "#09090b",
+    surface: "#18181b",
+    card: "#18181b",
+    text: "#fafafa",
+    onPrimary: "#09090b",
+    // `secondary` stays a mid grey so badges and tooltips can carry white
+    // (4.6:1 on #71717A) while it still reads as ink on the surface.
+    onSecondary: "#ffffff",
+    primaryBg: "#27272a",
+    // A dark pane with a light rim, at the same alpha as the light token.
+    glass: "rgba(24, 24, 27, 0.72)",
+    glassBorder: "rgba(250, 250, 250, 0.12)",
+    textSecondary: "#a1a1aa",
+    textDisabled: "#52525b",
+    border: "#27272a",
+    gray50: "#111111",
+    gray100: "#1f1f1f",
+    gray200: "#27272a",
+    gray300: "#3f3f46",
+    gray400: "#52525b",
+    gray500: "#71717a",
+    gray600: "#a1a1aa",
+    gray700: "#d4d4d8",
+    gray800: "#e4e4e7",
+    gray900: "#fafafa",
+    divider: "#27272a",
+    overlay: "rgba(0, 0, 0, 0.72)",
+    shadow: "rgba(0, 0, 0, 0.6)",
   },
 };
 
@@ -134,13 +248,14 @@ const notifyThemeChange = () => {
 
 // ========== THEME FUNCTIONS ==========
 /**
- * Applies a named theme palette to the global `colors` object, updates all
- * CSS custom properties on `:root`, persists the choice to `localStorage`,
- * and notifies all subscribers.
- * @param {string} themeName - Name of the palette to apply (e.g. `"light"` or `"dark"`).
- * @returns {Object} The updated `colors` object after the theme is applied.
+ * Copies a registered palette onto the live `colors` object and refreshes the
+ * CSS custom properties. Shared by `setTheme` and `registerPalette`; it does not
+ * persist anything, because "this is the palette now" and "the user picked this
+ * theme" are two different sentences.
+ * @param {string} themeName
+ * @returns {Object} the updated `colors` object
  */
-export const setTheme = (themeName) => {
+const applyPalette = (themeName) => {
   const palette = palettes[themeName];
   if (palette) {
     Object.keys(palette).forEach((key) => {
@@ -160,17 +275,58 @@ export const setTheme = (themeName) => {
     // Silently fail in non-browser environments
   }
 
-  // Save preference
+  notifyThemeChange();
+  return colors;
+};
+
+/**
+ * Applies a named theme palette to the global `colors` object, updates all
+ * CSS custom properties on `:root`, persists the choice to `localStorage`,
+ * and notifies all subscribers.
+ * @param {string} themeName - Name of the palette to apply (e.g. `"light"` or `"dark"`).
+ * @returns {Object} The updated `colors` object after the theme is applied.
+ */
+export const setTheme = (themeName) => {
+  // Persist before repainting: applyPalette notifies subscribers synchronously,
+  // and a subscriber that reads `getTheme()` while it rebuilds (a toggle button
+  // labelling itself, a theme-aware screen) has to see the theme it is being
+  // rebuilt for, not the one being replaced.
   try {
     localStorage.setItem("fletbox-theme", themeName);
   } catch (e) {
     // Silently fail
   }
 
-  notifyThemeChange();
+  applyPalette(themeName);
   return colors;
 };
 
+/**
+ * Merges an app's own tokens into a named palette and, when that palette is the
+ * one currently on screen, repaints with it. An app that only declares a
+ * `colors` object changes nothing: every widget reads the framework's live
+ * `colors`, so the tokens have to be registered to reach the page.
+ *
+ * Unlike `setTheme` this never writes the theme preference — an app supplying
+ * its brand colors is not the user choosing light or dark.
+ *
+ * @param {string} themeName - Palette to extend, usually `"light"` or `"dark"`.
+ * @param {Object} palette - Token names to override; unknown keys are ignored.
+ * @returns {Object} The registered palette.
+ */
+export const registerPalette = (themeName, palette) => {
+  if (!themeName || !palette || typeof palette !== "object") return palettes;
+  // A token the framework never heard of is seeded onto `colors` first:
+  // applyPalette only copies keys that already exist — that filter is what stops
+  // a palette which leaves one out (both built-ins do) from blanking it.
+  Object.keys(palette).forEach((key) => {
+    if (!colors.hasOwnProperty(key)) colors[key] = palette[key];
+  });
+  palettes[themeName] = { ...(palettes[themeName] || {}), ...palette };
+  if (getTheme() === themeName) applyPalette(themeName);
+  return palettes[themeName];
+};
+
 /**
  * Returns the currently active theme name.
  * Reads from `localStorage` first; falls back to the OS
@@ -215,7 +371,10 @@ export const applySystemTheme = () => {
         .matches
         ? "dark"
         : "light";
-      setTheme(systemTheme);
+      // applyPalette, not setTheme: painting what the OS asked for is not the
+      // reader choosing a theme. Persisting here would pin the first answer and
+      // make watchSystemTheme's own savedTheme check bail forever.
+      applyPalette(systemTheme);
       return systemTheme;
     }
     return savedTheme;
@@ -236,8 +395,9 @@ export const watchSystemTheme = () => {
     const handler = (e) => {
       const savedTheme = localStorage.getItem("fletbox-theme");
       if (!savedTheme) {
-        const theme = e.matches ? "dark" : "light";
-        setTheme(theme);
+        // Same rule as applySystemTheme: the OS changing its mind is not the
+        // reader choosing a theme, so it must not be written down as one.
+        applyPalette(e.matches ? "dark" : "light");
       }
     };
     mediaQuery.addEventListener("change", handler);
@@ -312,13 +472,16 @@ const initTheme = () => {
   try {
     const savedTheme = localStorage.getItem("fletbox-theme");
     if (savedTheme && (savedTheme === "light" || savedTheme === "dark")) {
-      setTheme(savedTheme);
+      applyPalette(savedTheme);
     } else {
       const systemTheme = window.matchMedia("(prefers-color-scheme: dark)")
         .matches
         ? "dark"
         : "light";
-      setTheme(systemTheme);
+      // applyPalette, not setTheme: this runs the first time the module is
+      // imported, so persisting here wrote the OS answer down as a reader
+      // choice — and every later watcher then refused to follow the OS.
+      applyPalette(systemTheme);
     }
     watchSystemTheme();
   } catch (e) {

package/src/utils/units.js

@@ -9,10 +9,12 @@
 // toREM(24)    // "1.5rem"
 // toREM(8)     // "0.5rem"
 //
-// // Strings pass through as-is
-// toREM('16px')  // "16px"
-// toREM('1rem')  // "1rem"
-// toREM('50%')   // "50%"
+// // A length written in pixels is re-written in rem; anything else is left alone
+// toREM('16px')         // "1rem"
+// toREM('8px 12px')     // "0.5rem 0.75rem"
+// toREM('1rem')         // "1rem"
+// toREM('50%')          // "50%"
+// toREM('2px solid red')// "2px solid red"
 //
 // // For exact pixels
 // toPX(16)     // "16px"
@@ -35,15 +37,30 @@ export const setBaseFontSize = (size) => {
 
 /**
  * Converts a numeric value to rem, or keeps strings as they are
+ *
+ * A number always becomes rem: `40` is `2.5rem`, so it grows with the reader's
+ * base font the same way the rest of the page does.
+ *
+ * A string is usually a CSS value the framework should not touch (`"50%"`,
+ * `"calc(100% - 8px)"`, `"2px solid red"`) and passes through unchanged. The one
+ * exception is a length shorthand made only of pixels — `"8px 12px"`, `"0 16px"`,
+ * `"-4px -8px"`. That shape is a widget writing a framework number by hand
+ * (`padding: \`${v}px ${h}px\``), and if it passes through, the whole rule set
+ * still scales except for the one line that spelled its units out. So every
+ * token of it is converted: `"8px 12px"` → `"0.5rem 0.75rem"`.
+ *
  * @param {number|string} value - Value to convert
- * @returns {string} Converted value (e.g. "1rem", "16px", "50%")
+ * @returns {string} Converted value (e.g. "1rem", "0.5rem 0.75rem", "50%")
  * @example
- * toREM(16)     // "1rem"
- * toREM(8)      // "0.5rem"
- * toREM('16px') // "16px"
- * toREM('1rem') // "1rem"
- * toREM('50%')  // "50%"
+ * toREM(16)        // "1rem"
+ * toREM(8)         // "0.5rem"
+ * toREM('8px 12px')// "0.5rem 0.75rem"
+ * toREM('16px')    // "1rem"
+ * toREM('50%')     // "50%"
+ * toREM('2px solid red') // unchanged: "solid" is not a length
  */
+const PX_TOKEN = /^-?\d+(?:\.\d+)?px$/;
+
 export const toREM = (value) => {
   if (value === undefined || value === null) return undefined;
 
@@ -54,7 +71,12 @@ export const toREM = (value) => {
 
   // If it is a string, return it as-is
   if (typeof value === "string") {
-    return value;
+    const parts = value.trim().split(/\s+/);
+    const allPixels = parts.every((part) => PX_TOKEN.test(part));
+    if (!allPixels) return value;
+    return parts
+      .map((part) => `${parseFloat(part) / BASE_FONT_SIZE}rem`)
+      .join(" ");
   }
 
   // For other types (objects, booleans, etc.)

package/src/widget-factory/effects.js

@@ -1,5 +1,42 @@
 // core/effects.js
 
+import { SHADOW_LEVELS } from "../tools/shadow.js";
+
+/**
+ * The three geometry numbers of a CSS shadow: x, y and blur.
+ * The colour is stripped first, because the scale writes `0 3px 6px` while the
+ * browser serialises the live style as `0px 3px 6px 0px` — matching numbers
+ * instead of tokens is what lets both forms compare equal.
+ */
+const shadowGeometry = (value) => {
+  const numbers = String(value ?? "")
+    .replace(/rgba?\([^)]*\)/g, "")
+    .trim()
+    .split(/\s+/)
+    .map(parseFloat);
+  return numbers.length >= 3 && numbers.every(Number.isFinite)
+    ? numbers.slice(0, 3)
+    : null;
+};
+
+/**
+ * The next `SHADOW_LEVELS` entry above `value`, or `null` when the shadow is not
+ * one of the scale's levels. Matching is by geometry, not by string: the browser
+ * serialises "0 3px 6px rgba(0,0,0,0.16)" as "rgba(0, 0, 0, 0.16) 0px 3px 6px",
+ * so comparing the literals would never find a level.
+ */
+const nextElevation = (value) => {
+  const geometry = shadowGeometry(value);
+  if (!geometry) return null;
+  const level = Object.keys(SHADOW_LEVELS).find((key) => {
+    const candidate = shadowGeometry(SHADOW_LEVELS[key]);
+    return candidate && candidate.every((n, i) => Math.abs(n - geometry[i]) < 0.01);
+  });
+  if (level === undefined) return null;
+  return SHADOW_LEVELS[Number(level) + 1] ?? null;
+};
+
+
 /**
  * Applies interactive visual effects to a widget that has a click handler.
  *
@@ -19,7 +56,8 @@
  * - On press end (`mouseup` / `touchend` / `mouseleave` / `touchcancel`):
  *   restores the original scale and shadow.
  * - On hover enter (`mouseenter`): translates the widget up by `0.5px` and
- *   enhances the box shadow when one was present.
+ *   raises the box shadow by one `SHADOW_LEVELS` step when the widget already
+ *   carries a shadow from that scale.
  * - On hover leave (`mouseleave`): restores the original translate and shadow.
  * - Sets `cursor: pointer`.
  *
@@ -47,7 +85,12 @@ export const applyEffects = (widget) => {
   if (!hasClick) return widget;
 
   // Store the current shadow so it can be restored after press / hover effects.
-  widget._originalShadow = widget.style.boxShadow || "";
+  //
+  // Skipped while the pointer is over the widget: `update()` re-runs
+  // `applyEffects`, and capturing the lifted hover shadow as the base would make
+  // every update climb one more elevation step.
+  if (!widget._hovering) widget._originalShadow = widget.style.boxShadow || "";
+  const hoverShadow = nextElevation(widget._originalShadow);
 
   const disableTransform = widget._originalProps?.disableTransform === true;
   const listeners = [];
@@ -98,11 +141,10 @@ export const applyEffects = (widget) => {
      */
     const onHoverEnter = () => {
       if (isPressed) return;
+      widget._hovering = true;
       // Use the independent `translate` property.
       widget.style.translate = "0 -0.5px";
-      if (widget._originalShadow && widget._originalShadow !== "none") {
-        widget.style.boxShadow = "0 8px 16px rgba(0,0,0,0.2)";
-      }
+      if (hoverShadow) widget.style.boxShadow = hoverShadow;
     };
 
     /**
@@ -115,6 +157,7 @@ export const applyEffects = (widget) => {
       // Restore translate without touching transform.
       widget.style.translate = "";
       widget.style.boxShadow = widget._originalShadow || "";
+      widget._hovering = false;
     };
 
     widget.addEventListener("mouseenter", onHoverEnter, { passive: true });
@@ -122,6 +165,14 @@ export const applyEffects = (widget) => {
     listeners.push({ event: "mouseenter", handler: onHoverEnter });
     listeners.push({ event: "mouseleave", handler: onHoverLeave });
 
+    // An update re-applies the props' own shadow and translate, which cancels a
+    // hover that is still in progress. Re-assert it, from the same base, so a
+    // reactive update neither drops the lift nor climbs another step.
+    if (widget._hovering) {
+      widget.style.translate = "0 -0.5px";
+      if (hoverShadow) widget.style.boxShadow = hoverShadow;
+    }
+
     widget.style.cursor = "pointer";
   }
 

package/src/widget-factory/processProps.js

@@ -123,8 +123,17 @@ function applyUnit(def, value) {
   }
   if (value === true) return 1;
   if (value === false) return 0;
-  if (typeof value !== "number") return value;
   const unit = def.unit || "px";
+  // A rem prop written as a pixel *string* ("8px 12px") is the same framework
+  // number written a different way, so it converts like the number does. `toREM`
+  // only rewrites strings made entirely of pixel lengths, which leaves "100%",
+  // "auto", "calc(100% - 16px)" and "2px solid red" exactly as they were.
+  if (unit === "rem" && typeof value === "string") return toREM(value);
+  // A rem prop written as a *list* (`padding: [8, 16]`) is the same pair of
+  // framework units again; the generic formatter would suffix each item with px.
+  if (unit === "rem" && Array.isArray(value))
+    return value.map((item) => toREM(item)).join(" ");
+  if (typeof value !== "number") return value;
   if (unit === "none") return value;
   
   // Use the dynamic REM converter instead of a hard-coded division.

package/src/widget-factory/remTool.js

@@ -1,34 +1,20 @@
 /**
- * REM TOOL - Only converts numbers to REM
+ * @file remTool.js
+ * @description The engine's entry point to the framework's one unit converter.
+ *
+ * This file used to keep its own copy of the rule — `value / 16` for numbers,
+ * strings passed through untouched. Two converters in one framework means two
+ * meanings for one number: a widget that called `src/utils/units.js` honoured
+ * `setBaseFontSize()` and an engine-routed prop did not, so the same `40` painted
+ * 40px in one place and 50px in another. Both halves now call the same function,
+ * and a length written as pixels ("8px", "4px 12px") converts like the number
+ * that produced it instead of freezing at that size.
  */
+import { toREM as convert } from "../utils/units.js";
 
 /**
- * Converts a number to REM
- * @param {number} value - Number to convert
- * @param {number} baseFontSize - Base root font size (default: 16)
- * @returns {string} - Value in REM
+ * @param {number|string} value - A framework number, or a CSS length/value.
+ * @returns {string|*} `40` → `"2.5rem"`; `"8px 12px"` → `"0.5rem 0.75rem"`;
+ *   anything that is not a pixel length (`"50%"`, `"auto"`) is returned as given.
  */
-export const toREM = (value, baseFontSize = 16) => {
-  if (typeof value !== "number") return value;
-  return `${value / baseFontSize}rem`;
-};
-
-/**
- * Applies REM to a styles object
- * @param {Object} styles - Styles with numbers
- * @param {number} baseFontSize - Base root font size (default: 16)
- * @returns {Object} - Styles with REM
- */
-export const applyREM = (styles, baseFontSize = 16) => {
-  const result = {};
-
-  for (const [key, value] of Object.entries(styles)) {
-    if (typeof value === "number") {
-      result[key] = toREM(value, baseFontSize);
-    } else {
-      result[key] = value;
-    }
-  }
-
-  return result;
-};
+export const toREM = (value) => convert(value);

package/src/widget-factory/stackPosition.js

@@ -26,9 +26,16 @@ export const stackPosition = (widget, props) => {
   // Absolute positioning
   widget.style.position = "absolute";
 
+  // `centerX` + `centerY` must compose: writing each transform as it is found
+  // would let the second one erase the first.
+  const transforms = [];
+
   // Process each position prop
   for (const [key, value] of Object.entries(props)) {
     if (key === "position") continue;
+    // The placement shorthands are booleans: a present `false` means "do not
+    // apply", not "the key exists".
+    if (value === false) continue;
 
     switch (key) {
       case "top":
@@ -51,16 +58,16 @@ export const stackPosition = (widget, props) => {
         break;
       case "centerX":
         widget.style.left = "50%";
-        widget.style.transform = "translateX(-50%)";
+        transforms.push("translateX(-50%)");
         break;
       case "centerY":
         widget.style.top = "50%";
-        widget.style.transform = "translateY(-50%)";
+        transforms.push("translateY(-50%)");
         break;
       case "center":
         widget.style.top = "50%";
         widget.style.left = "50%";
-        widget.style.transform = "translate(-50%, -50%)";
+        transforms.push("translate(-50%, -50%)");
         break;
       case "fullWidth":
         widget.style.width = "100%";
@@ -81,6 +88,14 @@ export const stackPosition = (widget, props) => {
     }
   }
 
+  if (transforms.length) {
+    // `center` already covers both axes; mixing it with a single-axis shorthand
+    // must not shift the widget twice.
+    widget.style.transform = transforms.includes("translate(-50%, -50%)")
+      ? "translate(-50%, -50%)"
+      : transforms.join(" ");
+  }
+
   return widget;
 };