flet-box 1.0.6 → 1.0.8

package/src/utils/syntaxHighlight.js

@@ -1,4 +1,6 @@
 // utils/syntaxHighlight.js
+import { color } from "../tools/color.js";
+import { getTheme } from "./themes.js";
 
 // ========== FLETBOX COLORS ==========
 const fletboxColors = {
@@ -118,22 +120,83 @@ const TokenType = {
   PUNCTUATION: "punctuation",
   FLETBOX_COLOR: "fletbox-color",
   FLETBOX_WIDGET: "fletbox-widget",
+  /** Anything the tokenizer did not classify, e.g. `=`, `=>`, `+`. */
+  TEXT: "text",
 };
 
 // ========== COLORS PER TOKEN ==========
-export const highlightColors = {
+// Two palettes, chosen by the surface the code sits on. One Dark's values were
+// designed for a dark pane and measure 1.6–2.3:1 on the light theme's #F4F4F5
+// code block — the green string and the amber widget were the worst offenders.
+// The light map is GitHub's light scale, which clears AA on that grey.
+const DARK_HIGHLIGHT_COLORS = {
   [TokenType.KEYWORD]: "#c678dd", // purple
   [TokenType.STRING]: "#98c379", // green
   [TokenType.NUMBER]: "#d19a66", // orange
-  [TokenType.COMMENT]: "#5c6370", // gray
+  // One Dark's #5C6370 measures 2.73:1 on the dark code block; a comment still
+  // has to be read, so the grey is the one GitHub paints comments with.
+  [TokenType.COMMENT]: "#8b949e",
   [TokenType.PROPERTY]: "#e06c75", // red
   [TokenType.FUNCTION]: "#61afef", // blue
   [TokenType.BRACKET]: "#abb2bf", // light gray
   [TokenType.PUNCTUATION]: "#abb2bf", // light gray
   [TokenType.FLETBOX_COLOR]: "#56b6c2", // cyan
   [TokenType.FLETBOX_WIDGET]: "#e5c07b", // yellow
+  // Raw characters used to inherit the page ink, which vanishes when the pane
+  // is painted in the opposite theme. They now carry the pane's own ink.
+  [TokenType.TEXT]: "#fafafa",
+  /** Muted ink for line numbers and similar chrome (not a token colour). */
+  muted: "#a1a1aa",
 };
 
+const LIGHT_HIGHLIGHT_COLORS = {
+  [TokenType.KEYWORD]: "#cf222e", // red
+  [TokenType.STRING]: "#0a3069", // navy
+  [TokenType.NUMBER]: "#0550ae", // blue
+  [TokenType.COMMENT]: "#57606a", // gray
+  [TokenType.PROPERTY]: "#953800", // brown
+  [TokenType.FUNCTION]: "#8250df", // purple
+  [TokenType.BRACKET]: "#57606a", // gray
+  [TokenType.PUNCTUATION]: "#57606a", // gray
+  [TokenType.FLETBOX_COLOR]: "#0e7490", // teal
+  [TokenType.FLETBOX_WIDGET]: "#116329", // green
+  [TokenType.TEXT]: "#09090b",
+  muted: "#52525b",
+};
+
+export const highlightPalettes = {
+  light: LIGHT_HIGHLIGHT_COLORS,
+  dark: DARK_HIGHLIGHT_COLORS,
+};
+
+/**
+ * The map the highlighter exported before it became theme-aware. It is the dark
+ * palette, and it is still what a caller receives when it passes none.
+ */
+export const highlightColors = DARK_HIGHLIGHT_COLORS;
+
+const SOLID_BACKGROUND = /^(#[0-9a-f]{3,8}|rgba?\(\s*\d)/i;
+
+/**
+ * Picks the syntax palette for the surface the code is painted on, by that
+ * surface's own lightness. A dark block on the light theme still gets readable
+ * spans, and the widget default (`colors.gray100`) lands on the right map in
+ * both themes. Falls back to the active theme when the background is not a
+ * solid colour this module can measure (a gradient, a CSS variable) — guessing
+ * there is worse than the theme's answer.
+ * @param {string} [background] - CSS background colour of the code block.
+ * @returns {Record<string, string>} Token colour map.
+ */
+export const syntaxPaletteFor = (background) => {
+  if (typeof background === "string" && SOLID_BACKGROUND.test(background)) {
+    return color(background).isDark()
+      ? DARK_HIGHLIGHT_COLORS
+      : LIGHT_HIGHLIGHT_COLORS;
+  }
+  return highlightPalettes[getTheme()] || DARK_HIGHLIGHT_COLORS;
+};
+
+
 // ========== DETECT FLETBOX COLORS ==========
 /**
  * Returns `true` when the given word represents a FletBox color token.
@@ -284,7 +347,7 @@ export const tokenize = (code) => {
     }
 
     // ========== ANY OTHER CHARACTER ==========
-    tokens.push({ type: "text", value: char });
+    tokens.push({ type: TokenType.TEXT, value: char });
     i++;
   }
 
@@ -294,12 +357,17 @@ export const tokenize = (code) => {
 // ========== GENERATE HTML WITH COLORS ==========
 /**
  * Tokenizes `code` and wraps each token in a `<span>` with an inline `color`
- * style matching {@link highlightColors}. Whitespace and unrecognized tokens
- * are emitted without a wrapper.
+ * style from `palette`. Whitespace and unrecognized tokens are emitted without
+ * a wrapper.
  * @param {string} code - Source code to highlight.
+ * @param {Record<string, string>} [palette] - Token colour map; defaults to the
+ *   palette of the active theme.
  * @returns {string} HTML string safe for insertion into `innerHTML`.
  */
-export const generateHighlightedHtml = (code) => {
+export const generateHighlightedHtml = (
+  code,
+  palette = syntaxPaletteFor(),
+) => {
   const tokens = tokenize(code);
   let html = "";
 
@@ -307,9 +375,9 @@ export const generateHighlightedHtml = (code) => {
     if (token.type === "whitespace") {
       html += token.value;
     } else {
-      const color = highlightColors[token.type];
-      if (color) {
-        html += `<span style="color: ${color};">${escapeHtml(token.value)}</span>`;
+      const tokenColor = palette[token.type];
+      if (tokenColor) {
+        html += `<span style="color: ${tokenColor};">${escapeHtml(token.value)}</span>`;
       } else {
         html += escapeHtml(token.value);
       }
@@ -336,4 +404,4 @@ const escapeHtml = (text) => {
     .replace(/'/g, "&#39;");
 };
 
-export default { tokenize, generateHighlightedHtml, highlightColors };
+export default { tokenize, generateHighlightedHtml, highlightColors, highlightPalettes, syntaxPaletteFor };

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";
   }