flet-box 1.0.8 → 1.0.9

package/README.md

@@ -23,6 +23,7 @@ Real DOM · No Virtual DOM · No build config to learn.
 <br><br>
 
 <a href="https://kuko53348.github.io/flet-box-docs/">📖 Docs</a> •
+<a href="https://kuko53348.github.io/flet-box-widgets-exemples/">🧪 Widget gallery</a> •
 <a href="#quick-start">Quick start</a> •
 <a href="https://www.youtube.com/@flet-box">▶ YouTube</a> •
 <a href="#support--sponsorship">❤️ Sponsor</a>
@@ -157,6 +158,8 @@ Read the docs online: **[The FletBox Book — kuko53348.github.io/flet-box-docs]
 
 They are **one continuous book** — the cover maps every page: [The FletBox Book source](docs/README.md).
 
+Rather than read, click: **[the live widget gallery](https://kuko53348.github.io/flet-box-widgets-exemples/)** gives every widget its own page, renders each example in the browser it was written for, and prints the exact call underneath it. The theme toggle in the corner shows the same screen in light and dark, which is the honest way to judge a default color.
+
 - [Your first app](docs/guides/first-app.md) — build a working todo app in 20 minutes
 - [The widget book](docs/widget/README.md) — every widget with property tables and examples
 - [State, Router & Services](docs/guides/state.md) — shared state, routing, storage, and HTTP

package/bin/utils/templates.js

@@ -1,5 +1,21 @@
 // bin/utils/templates.js
 
+/**
+ * The plate behind everything a reader sees before the app paints: the PWA
+ * splash (`manifest.json`), the Android and iOS launch screens, the adaptive
+ * icon background, and the static `<meta name="theme-color">`.
+ *
+ * It is the dark palette's `surface` — the zinc scale the 2026-10 design rebuild
+ * moved to, replacing the indigo shell color that stayed in the scaffold and kept
+ * showing on installed PWAs long after the app itself had changed color. One
+ * value because a native splash cannot follow a theme; `applyPalette()` writes
+ * the live palette onto `<meta name="theme-color">` at runtime, so the bars do.
+ */
+export const SHELL_BRAND = "#18181b";
+
+/** `SHELL_BRAND` as the channels the icon and splash scripts composite with. */
+export const SHELL_BRAND_RGB = { r: 24, g: 24, b: 27 };
+
 export const indexHtml = (appName = "FletBox App") => `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -19,7 +35,7 @@ export const indexHtml = (appName = "FletBox App") => `<!DOCTYPE html>
     <meta property="og:description" content="${appName} built with Flet-Box.">
     <meta property="og:type" content="website">
 
-    <meta name="theme-color" content="#1a1a2e">
+    <meta name="theme-color" content="${SHELL_BRAND}">
 
     <!-- ============================================================
          GOOGLE ADSENSE (optional — disabled by default)
@@ -904,7 +920,7 @@ export const capacitorConfig = (appName, appId) => `${JSON.stringify(
     appId,
     appName,
     webDir: "www",
-    backgroundColor: "#1a1a2e",
+    backgroundColor: SHELL_BRAND,
     server: { androidScheme: "https", iosScheme: "https" },
   },
   null,
@@ -960,7 +976,7 @@ const densities = [
   ["xxhdpi", 144],
   ["xxxhdpi", 192],
 ];
-const background = { r: 26, g: 26, b: 46 };
+const background = { r: ${SHELL_BRAND_RGB.r}, g: ${SHELL_BRAND_RGB.g}, b: ${SHELL_BRAND_RGB.b} };
 
 for (const [density, size] of densities) {
   const directory = path.join(androidRes, \`mipmap-\${density}\`);
@@ -998,7 +1014,7 @@ const backgroundColor = /(<color name="ic_launcher_background">)#(?:[A-Fa-f0-9]{
 if (!backgroundColor.test(xml)) {
   throw new Error(\`Invalid adaptive icon background resource: \${backgroundPath}\`);
 }
-await writeFile(backgroundPath, xml.replace(backgroundColor, "$1#1a1a2e$2"));
+await writeFile(backgroundPath, xml.replace(backgroundColor, "$1${SHELL_BRAND}$2"));
 
 // SPLASH SCREENS
 // The launch theme (AppTheme.NoActionBarLaunch) shows @drawable/splash while the
@@ -1066,8 +1082,8 @@ const infoPlistPath = path.join(nativeAppDir, "Info.plist");
 const launchScreenPath = path.join(nativeAppDir, "Base.lproj", "LaunchScreen.storyboard");
 const logoPath = path.join(projectRoot, "assets", "logo.png");
 
-// Brand background, the same #1a1a2e as theme-color in index.html and manifest.json.
-const background = { r: 26, g: 26, b: 46 };
+// Brand background, the same value as theme-color in index.html and manifest.json.
+const background = { r: ${SHELL_BRAND_RGB.r}, g: ${SHELL_BRAND_RGB.g}, b: ${SHELL_BRAND_RGB.b} };
 const backgroundComponent = (value) => Number((value / 255).toFixed(6));
 
 const requireExists = async (target) => {
@@ -1245,8 +1261,8 @@ export const manifest = (appName = "FletBox App") => `{
   "scope": "./",
   "display": "standalone",
   "display_override": ["window-controls-overlay"],
-  "theme_color": "#1a1a2e",
-  "background_color": "#1a1a2e",
+  "theme_color": "${SHELL_BRAND}",
+  "background_color": "${SHELL_BRAND}",
   "orientation": "any",
   "icons": [
     {
@@ -1739,7 +1755,7 @@ run \`npm run ios:open\`.
 
 Replace \`assets/logo.png\` with a 1024×1024 logo before distributing; the icon,
 the launch images and the launch background are all generated from it. The
-launch background is the app brand color \`#1a1a2e\`, which lives in
+launch background is the app brand color \`${SHELL_BRAND}\`, which lives in
 \`scripts/sync-ios-assets.mjs\`.
 
 Capacitor uses a local HTTPS origin (\`https://localhost\`) in the Android and

package/docs/README.md

@@ -4,6 +4,8 @@ FletBox is a tiny UI framework: you describe your screen with plain JavaScript *
 
 This documentation is one continuous book. Start at **Chapter 0** and follow the "Continue reading" links at the bottom of every page; each page teaches you something real and links to the next.
 
+> **Want to see before you read?** The [live widget gallery](https://kuko53348.github.io/flet-box-widgets-exemples/) runs in the browser: one page per widget, every example rendered, with the exact call printed under it and a light/dark toggle. It is the same code the chapters describe, so it doubles as the answer to "what does this look like when it is real?".
+
 ## The reading path
 
 | # | Chapter | What you learn | Level |

package/docs/cli/README.md

@@ -448,7 +448,7 @@ Capacitor template with different slots keeps working. It:
   status bar style ignored.
 
 The script is idempotent: running it twice leaves identical files. The brand
-color `#1a1a2e` is defined at the top of the script.
+color `#18181b` is defined at the top of the script.
 
 ## Convert asset images to PNG
 

package/docs/guides/mobile-and-platforms.md

@@ -331,6 +331,37 @@ A PWA needs:
 
 PWA installation depends on browser and platform support.
 
+### The browser chrome follows the theme
+
+Once installed, Android and iOS paint two more surfaces you do not control from
+CSS: the status bar at the top and the navigation bar at the bottom. Chrome takes
+both from `<meta name="theme-color">` in the document — a value it reads once per
+page, unless the page rewrites it.
+
+FletBox rewrites it. Every `setTheme`, `registerPalette` and system-preference
+change updates that single meta tag with the live `colors.surface`, the color the
+`AppBar` and the `BottomNavigation` are painted with, so the bars meet the app
+instead of sitting against it. It also sets `color-scheme` on the root element,
+which is what tells the operating system to draw dark scrollbars, dark form
+controls and light status-bar glyphs on a dark page.
+
+That means the colors in `manifest.json` are only the **splash screen** — the
+plate shown while the app boots:
+
+```json
+{
+  "theme_color": "#18181b",
+  "background_color": "#18181b"
+}
+```
+
+Leave them at the brand color generated by `flet-box create` (the dark palette's
+surface) and let the runtime handle the rest. There is no manifest field for a
+per-theme bar color, and an installed app keeps the manifest copy it was
+installed with, so editing these two lines does not recolor a home-screen icon
+that is already there — reinstall, or let the first paint of the new version
+update the document.
+
 ## Desktop options
 
 Capacitor targets Android and iOS. For desktop packaging, consider a desktop shell such as Electron or Tauri around the same `dist` output.

package/docs/tools/theme.md

@@ -122,6 +122,7 @@ runApp(ThemeProvider({ children: ThemedApp() }), "root");
 ## Notes
 
 - The shared palette tokens are updated across all widgets when you switch themes; widgets referencing `colors.*` at build time pick up the active palette.
+- Switching a theme also repaints the browser's own chrome: the `<meta name="theme-color">` the installed PWA takes for its status and navigation bars, and the root `color-scheme` that decides how the OS draws scrollbars and form controls. Both read the live palette, so an app that changes `colors.surface` changes its system bars with it — see [Mobile and platforms](../guides/mobile-and-platforms.md#the-browser-chrome-follows-the-theme).
 - `colors.glass` is genuinely see-through: its contrast depends on whatever is behind it, so use it over photography or gradients with a scrim, and keep body copy off the most colourful part of the backdrop. The dark token is a dark pane, not white glass.
 - `watchSystemTheme()` and `applySystemTheme()` read `prefers-color-scheme`; both return/need cleanup to release listeners.
 - `subscribeTheme(callback)` fires with the new palette object — remember to unsubscribe when a feature is destroyed.

package/docs/widget/README.md

@@ -13,6 +13,8 @@ If you have never used FletBox, begin with [Start here](START_HERE.md), then fol
 
 Related guides: [Build your first FletBox app](../guides/app-templates.md) · [Routing with FletBox](../guides/router.md) · [FletBox CLI](../cli/README.md).
 
+Every page here has a live twin: **[the widget gallery](https://kuko53348.github.io/flet-box-widgets-exemples/)** renders each example in the browser and prints the call that made it under the result, so you can read a property table and see the same prop move something.
+
 ## The reading path
 
 ### Chapter 1 · First steps: the core mental model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flet-box",
-  "version": "1.0.8",
+  "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",

package/src/utils/themes.js

@@ -1,4 +1,5 @@
 // src/components/flet-box/utils/themes.js
+import { readableInk } from "./readableInk.js";
 
 // ========== DEFAULT COLORS (static, safe) ==========
 const DEFAULT_COLORS = {
@@ -247,6 +248,41 @@ const notifyThemeChange = () => {
 };
 
 // ========== THEME FUNCTIONS ==========
+/**
+ * Moves the browser's own chrome — the PWA status bar and navigation bar, the
+ * scrollbar and form-control canvases — onto the palette that was just painted.
+ *
+ * An installed web app paints those bars from `<meta name="theme-color">`, which
+ * is a document-level value the page must rewrite itself: nothing in CSS reaches
+ * it. Left alone, the app keeps whatever literal the scaffold wrote — the indigo
+ * every FletBox PWA shipped before the zinc rebuild — and the reader sees a
+ * system bar from the old palette hanging over the new one. `color-scheme` is the
+ * same problem in the other direction: without it the OS draws light-mode
+ * scrollbars and form controls on a dark page.
+ *
+ * @private
+ */
+const syncBrowserChrome = () => {
+  try {
+    let meta = document.querySelector('meta[name="theme-color"]');
+    if (!meta) {
+      meta = document.createElement("meta");
+      meta.name = "theme-color";
+      document.head.appendChild(meta);
+    }
+    // The bars sit directly against the AppBar and the BottomNavigation, and
+    // both paint `surface` — matching `background` would put a band of the page
+    // color between two panels and look like a gap in the chrome.
+    meta.setAttribute("content", colors.surface);
+    // Whether the page is dark is read from its own background, not from the
+    // palette's name: `registerPalette` lets an app call a dark scale anything.
+    document.documentElement.style.colorScheme =
+      readableInk(colors.background, "#ffffff") === "#ffffff" ? "dark" : "light";
+  } catch (e) {
+    // Non-browser environments have no chrome to sync.
+  }
+};
+
 /**
  * Copies a registered palette onto the live `colors` object and refreshes the
  * CSS custom properties. Shared by `setTheme` and `registerPalette`; it does not
@@ -275,6 +311,8 @@ const applyPalette = (themeName) => {
     // Silently fail in non-browser environments
   }
 
+  syncBrowserChrome();
+
   notifyThemeChange();
   return colors;
 };
@@ -291,10 +329,16 @@ export const setTheme = (themeName) => {
   // 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
+  //
+  // `window` is the test, not a try/catch around the call: Node 22+ defines a
+  // global `localStorage` that only answers with a warning and then throws, so
+  // an import-time theme would print an ExperimentalWarning on every server run.
+  if (typeof window !== "undefined") {
+    try {
+      localStorage.setItem("fletbox-theme", themeName);
+    } catch (e) {
+      // Silently fail
+    }
   }
 
   applyPalette(themeName);