flet-box 1.0.1 → 1.0.3

package/bin/ota/loader.js

@@ -331,7 +331,12 @@ async function checkAndUpdate(shippedConfig, activeHash) {
 (async function main() {
   let shippedConfig = null;
   try {
-    shippedConfig = await fetchJson("./config.json");
+    // Anchored to this script, not the document: on a static host with SPA
+    // fallback (GitHub Pages) the app can boot from a deep URL, where a
+    // document-relative "./config.json" would resolve to the wrong folder.
+    shippedConfig = await fetchJson(
+      new URL("./config.json", import.meta.url).href,
+    );
   } catch (e) {
     warn("no shipped config.json:", e.message);
   }

package/bin/utils/templates.js

@@ -607,9 +607,13 @@ echo "✅ Bundle listo: \$TARGET/   Prueba: cd \$TARGET && bash run.sh"
 
 export const serviceWorkerJs = () => `// service-worker.js - PWA offline support
 const CACHE_NAME = 'fletbox-v2';
+// Deployment prefix: a worker's own URL always sits at the app root, so this
+// is '/' at the host root and '/repo-name/' on a GitHub Pages project site.
+// Hard-coded '/' entries would miss every file under a subpath.
+const BASE = new URL('./', self.location).pathname;
 // The shipped (baked-in) shell, precached so the app opens with no connection.
 // loader.js owns a SEPARATE cache ('fletbox-ota') for downloaded bundles.
-const PRECACHE = ['/', '/index.html', '/loader.js', '/config.json', '/src/app.js'];
+const PRECACHE = [BASE, BASE + 'index.html', BASE + 'loader.js', BASE + 'config.json', BASE + 'src/app.js'];
 
 self.addEventListener('install', event => {
   event.waitUntil(
@@ -690,7 +694,7 @@ self.addEventListener('fetch', event => {
         const cached = await cache.match(req);
         if (cached) return cached;
         if (req.mode === 'navigate') {
-          const shell = await cache.match('/index.html');
+          const shell = await cache.match(BASE + 'index.html');
           if (shell) return shell;
         }
         return Response.error();
@@ -1422,7 +1426,7 @@ enable: get an approved domain at https://www.google.com/adsense, put your
 publisher ID in the script, and delete the surrounding \`<!--\` / \`-->\` so the
 tag goes live. Ads only render on an approved domain, not on localhost. You can
 also drop the \`AdSense\` widget into any screen (see
-\`node_modules/flet-box/docs/widget/AdSense.md\`).
+https://github.com/kuko53348/flet-box/blob/refactory/docs/widget/AdSense.md).
 
 ### AdMob (Android / iOS)
 
@@ -1457,7 +1461,8 @@ also drop the \`AdSense\` widget into any screen (see
 
 4. Uncomment the \`AdMob\` import and the \`AdMob({...})\` widget in
    \`src/screens/HomeScreen.js\` (they are marked with ADMOB comments). Full
-   props in \`node_modules/flet-box/docs/widget/AdMob.md\`.
+   props in
+   https://github.com/kuko53348/flet-box/blob/refactory/docs/widget/AdMob.md.
 
 ## Over-the-air updates (OTA)
 

package/package.json

@@ -1,18 +1,25 @@
 {
   "name": "flet-box",
-  "version": "1.0.1",
-  "description": "Ultra-lightweight UI framework for vanilla JS web apps",
+  "version": "1.0.3",
+  "description": "Declarative, zero-dependency UI framework in vanilla JS — ship web, PWA, Android and iOS from one codebase",
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "flet-box": "bin/cli.js"
   },
   "scripts": {
     "dev": "node bin/cli.js run --hot",
     "build": "node bin/cli.js createBundle",
-    "test": "node scripts/check-widgets.mjs",
-    "prepublishOnly": "npm run build"
+    "release": "node bin/cli.js release",
+    "test": "node scripts/check-widgets.mjs"
   },
   "keywords": [
     "fletbox",
@@ -48,9 +55,6 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18.0.0"
-  },
-  "allowScripts": {
-    "esbuild@0.28.2": true
+    "node": ">=20.9.0"
   }
 }

package/src/create-index.sh

@@ -60,7 +60,7 @@ export {
     Scaffold, AppBar, Drawer, BottomNavigation, Tabs, DrawerItem,
     openDrawer, closeDrawer, toggleDrawer, destroyDrawer,
     initRouter, goTo, goBack, goForward, replace,
-    getCurrentPath, getCurrentRoute, getCurrentRouteConfig,
+    getCurrentPath, getBasePath, getCurrentRoute, getCurrentRouteConfig,
     getRoute, isActive, subscribe, useParams, useQueryParams,
     buildUrl, clearRouter
 } from './src/navigations/index.js';
@@ -178,7 +178,7 @@ export { Drawer, openDrawer, closeDrawer, toggleDrawer, destroyDrawer } from './
 export { BottomNavigation } from './BottomNavigation.js';
 export { Tabs } from './Tabs.js';
 export { DrawerItem } from './DrawerItem.js';
-export { initRouter, goTo, goBack, goForward, replace, getCurrentPath, getCurrentRoute, getCurrentRouteConfig, getRoute, isActive, subscribe, useParams, useQueryParams, buildUrl, clearRouter } from './Router.js';
+export { initRouter, goTo, goBack, goForward, replace, getCurrentPath, getBasePath, getCurrentRoute, getCurrentRouteConfig, getRoute, isActive, subscribe, useParams, useQueryParams, buildUrl, clearRouter } from './Router.js';
 EOF
 echo "✅ Created: src/navigations/index.js"
 

package/src/index.d.ts

@@ -977,12 +977,13 @@ declare module 'flet-box' {
   // =========================================================================
   // Router
   // =========================================================================
-  export function initRouter(routes: Record<string, any>, initialPath?: string): void;
+  export function initRouter(routes: Record<string, any>, initialPath?: string, options?: { base?: string }): void;
   export function goTo(path: string, params?: Record<string, any>): void;
   export function goBack(): void;
   export function goForward(): void;
   export function replace(path: string, params?: Record<string, any>): void;
   export function getCurrentPath(): string;
+  export function getBasePath(): string;
   export function getCurrentRoute(): any;
   export function getCurrentRouteConfig(): { route: any; params: Record<string, any>; query: Record<string, any>; path: string };
   export function getRoute(path: string): any;

package/src/index.js

@@ -208,6 +208,7 @@ export {
   goForward,
   replace,
   getCurrentPath,
+  getBasePath,
   getCurrentRoute,
   getCurrentRouteConfig,
   getRoute,

package/src/navigations/AppBar.js

@@ -165,6 +165,8 @@ export const AppBar = (props) => {
     display: "flex",
     alignItems: "center",
     justifyContent: "space-between",
+    width: "100%",
+    boxSizing: "border-box",
     minHeight: 56,
     borderRadius: finalBorderRadius,
     marginTop: finalMarginTop,
@@ -217,7 +219,10 @@ export const AppBar = (props) => {
   }
 
   const centerSection = Container({
-    flex: centerTitle ? 1 : "none",
+    // Always flex:1 so the title absorbs whatever the leading and action zones
+    // do not use. With flex:"none" a long title keeps its intrinsic width and
+    // pushes the actions past the viewport edge on narrow screens.
+    flex: 1,
     display: "flex",
     alignItems: "center",
     justifyContent: centerTitle ? "center" : "flex-start",
@@ -232,9 +237,11 @@ export const AppBar = (props) => {
   // ========== RIGHT SECTION (only rendered when there are valid actions) ==========
   if (validActions.length > 0) {
     const rightSection = Row({
+      // Row defaults to width:"100%", which inside the flex header demands the
+      // whole bar width and overflows it. The zone must be content-sized.
+      width: "auto",
       alignItems: "center",
       justifyContent: "flex-end",
-      paddingRight: paddingRight,
       gap: actionsGap,
       minWidth: 48,
       flexShrink: 0,

package/src/navigations/Router.js

@@ -7,6 +7,7 @@
  * - Dynamic segments: `/user/:id`, `/post/:slug/comments`
  * - Wildcard / 404 routes: `*` or `/404`
  * - Query string parameters
+ * - Deployment base paths (`/repo-name/`) for static hosts like GitHub Pages
  * - Browser history integration (pushState / popstate)
  * - Observer pattern (subscribe/notify) so layout shells like Scaffold can
  *   re-render when the route changes.
@@ -42,6 +43,15 @@ let currentQuery = {};
 /** @type {Function|null} Removes the popstate event listener; set during initRouter. */
 let removePopStateListener = null;
 
+/**
+ * Deployment base path the app is served under, e.g. "/flet-box-docs".
+ * Empty string means the app owns the host root. Router state stays
+ * app-relative; the base is only added when writing browser URLs.
+ *
+ * @type {string}
+ */
+let basePath = "";
+
 // ========== UTILITIES ==========
 
 /**
@@ -132,6 +142,93 @@ const findMatchingRoute = (path) => {
   return null;
 };
 
+// ========== DEPLOYMENT BASE PATH ==========
+
+/**
+ * Normalize a deployment base to "" or "/segment(s)" with no trailing slash.
+ *
+ * @param {string|null|undefined} base - e.g. "/", "flet-box-docs", "/flet-box-docs/".
+ * @returns {string} "" for a root-hosted app, otherwise a leading-slash prefix.
+ */
+const normalizeBase = (base) => {
+  if (!base) return "";
+  let out = String(base).trim();
+  if (!out.startsWith("/")) out = `/${out}`;
+  out = out.replace(/\/+$/, "");
+  return out === "/" ? "" : out;
+};
+
+/**
+ * Build a browser URL from an app-relative path by prefixing the base.
+ *
+ * @param {string} path - App-relative path, possibly with a query string.
+ * @returns {string} Path as seen by the browser.
+ */
+const withBase = (path) => `${basePath}${path}`;
+
+/**
+ * Remove the deployment base from a browser URL path.
+ *
+ * @param {string} path - Path as seen by the browser.
+ * @returns {string} App-relative path.
+ */
+const stripBase = (path) =>
+  basePath && path.startsWith(basePath)
+    ? path.slice(basePath.length) || "/"
+    : path;
+
+/**
+ * Work out which prefix of a browser path is the deployment base.
+ *
+ * Static hosts such as GitHub Pages serve a project site under
+ * `/<repo>/`, so `location.pathname` is `/<repo>/<route>` while the app's
+ * route map only knows `/<route>`. Scanning prefixes from the shortest one
+ * and returning the first whose remainder matches a registered route keeps
+ * root-hosted apps untouched (`base` resolves to "").
+ *
+ * @param {string} rawPath - Browser path, including any base prefix.
+ * @returns {string} Normalized base, or "" when no prefix yields a match.
+ */
+const detectBase = (rawPath) => {
+  const clean = cleanPath(rawPath);
+  if (findMatchingRoute(clean)) return "";
+
+  const segments = clean.split("/").filter(Boolean);
+  // i === segments.length covers the bare subpath root ("/repo/"), where the
+  // remainder is the app's own "/" route.
+  for (let i = 1; i <= segments.length; i++) {
+    const candidate = `/${segments.slice(0, i).join("/")}`;
+    const rest = segments.slice(i);
+    const remainder = rest.length ? `/${rest.join("/")}` : "/";
+    if (findMatchingRoute(remainder)) return normalizeBase(candidate);
+  }
+  return "";
+};
+
+/**
+ * Resolve the deployment base for the current document.
+ *
+ * Precedence: explicit `base` option > `window.__FLETBOX_BASE__` (only when
+ * the live URL actually sits under it, so the same bundle works when
+ * packaged by Capacitor at the origin root) > auto-detection from the URL.
+ *
+ * @param {string|null|undefined} explicitBase - Base passed to initRouter.
+ * @param {string} rawPath - Browser path the app is being entered on.
+ * @returns {string} Normalized base.
+ */
+const resolveBase = (explicitBase, rawPath) => {
+  const explicit = normalizeBase(explicitBase);
+  if (explicit) return explicit;
+
+  if (typeof window !== "undefined") {
+    const declared = normalizeBase(window.__FLETBOX_BASE__);
+    if (declared && (rawPath === `${declared}/` || rawPath.startsWith(`${declared}/`))) {
+      return declared;
+    }
+  }
+  return detectBase(rawPath);
+};
+
 // ========== INITIALIZATION ==========
 
 /**
@@ -146,8 +243,9 @@ const findMatchingRoute = (path) => {
  *
  * @param {Object.<string, *>} routesConfig - Map of path patterns to components/config.
  * @param {string|null} [initialPath=null] - Override the starting path; defaults to window.location.pathname.
+ * @param {{base?: string}} [options={}] - `base` pins the deployment prefix; auto-detected when omitted.
  */
-export const initRouter = (routesConfig, initialPath = null) => {
+export const initRouter = (routesConfig, initialPath = null, options = {}) => {
   routes = routesConfig;
 
   // Prefer the explicit initialPath; fall back to the live browser URL so
@@ -157,6 +255,11 @@ export const initRouter = (routesConfig, initialPath = null) => {
     urlPath = window.location.pathname;
   }
 
+  // Peel the deployment prefix off the browser URL before matching so a site
+  // served under /repo-name/ resolves to its routes instead of redirecting.
+  basePath = resolveBase(options.base, urlPath || "/");
+  if (urlPath) urlPath = stripBase(urlPath);
+
   // Last resort: use the first registered route or the root.
   if (!urlPath) {
     urlPath = Object.keys(routes)[0] || "/";
@@ -188,9 +291,13 @@ export const initRouter = (routesConfig, initialPath = null) => {
   // redirected to the first route above).
   if (
     typeof window !== "undefined" &&
-    window.location.pathname !== currentPath
+    window.location.pathname !== withBase(currentPath)
   ) {
-    window.history.replaceState({ path: currentPath }, "", currentPath);
+    window.history.replaceState(
+      { path: currentPath },
+      "",
+      withBase(currentPath),
+    );
   }
 
   // Listen for browser-native back/forward navigation so the router state
@@ -198,7 +305,8 @@ export const initRouter = (routesConfig, initialPath = null) => {
   if (typeof window !== "undefined") {
     if (removePopStateListener) removePopStateListener();
     const handlePopState = (event) => {
-      const path = event.state?.path || window.location.pathname;
+      const path =
+        event.state?.path || stripBase(window.location.pathname);
       if (path !== currentPath) {
         currentPath = path;
         const match = findMatchingRoute(currentPath);
@@ -243,7 +351,7 @@ export const goTo = (path, params = {}) => {
     currentQuery = { ...queryParams, ...params };
 
     if (typeof window !== "undefined") {
-      window.history.pushState({ path: currentPath }, "", path);
+      window.history.pushState({ path: currentPath }, "", withBase(path));
     }
     notify();
   } else {
@@ -278,7 +386,7 @@ export const replace = (path, params = {}) => {
     currentQuery = { ...queryParams, ...params };
 
     if (typeof window !== "undefined") {
-      window.history.replaceState({ path: currentPath }, "", path);
+      window.history.replaceState({ path: currentPath }, "", withBase(path));
     }
     notify();
   }
@@ -316,6 +424,15 @@ export const goForward = () => {
  */
 export const getCurrentPath = () => currentPath;
 
+/**
+ * Returns the deployment base the router resolved at init, e.g. "/flet-box-docs".
+ * Empty string for a root-hosted app. Use it to build asset or document URLs
+ * that must survive being served from a subpath.
+ *
+ * @returns {string}
+ */
+export const getBasePath = () => basePath;
+
 /**
  * Returns a shallow copy of the current dynamic route params.
  * Mutations to the returned object do not affect the router state.
@@ -454,6 +571,7 @@ export const clearRouter = () => {
   listeners = [];
   currentParams = {};
   currentQuery = {};
+  basePath = "";
 };
 
 export default {
@@ -463,6 +581,7 @@ export default {
   goBack,
   goForward,
   getCurrentPath,
+  getBasePath,
   getCurrentRoute,
   getCurrentRouteConfig,
   getRoute,

package/src/navigations/Scaffold.js

@@ -18,6 +18,7 @@ import { initRouter, getCurrentRoute, subscribe } from "./Router.js";
  * @property {number} [navSideBarWidth=260] - Legacy alias for leftNavBarWidth (deprecated).
  * @property {"left"|"right"} [navSideBarPosition="left"] - Legacy: which side navSideBar renders on.
  * @property {Object} [routes] - Route map object for router mode (path → component).
+ * @property {string} [basePath] - Deployment prefix, e.g. "/flet-box-docs". Auto-detected when omitted.
  * @property {string} [backgroundColor] - Background color of the scaffold shell.
  * @property {boolean} [closeDrawerOnNavigate=false] - Whether to close the drawer automatically on route change.
  */
@@ -54,6 +55,7 @@ export const Scaffold = (props) => {
     navSideBarWidth = 260,
     navSideBarPosition = "left",
     routes,
+    basePath,
     backgroundColor = colors.background,
     closeDrawerOnNavigate = false,
     ...rest
@@ -81,11 +83,12 @@ export const Scaffold = (props) => {
   }
 
   // Bootstrap the router with the current browser URL so deep-links work
-  // on first load without redirecting to "/".
+  // on first load without redirecting to "/". `basePath` pins the deployment
+  // prefix when the app is served from a subpath (e.g. GitHub Pages).
   if (isRouterMode && routesConfig) {
     const currentUrl =
       typeof window !== "undefined" ? window.location.pathname : "/";
-    initRouter(routesConfig, currentUrl);
+    initRouter(routesConfig, currentUrl, { base: basePath });
   }
 
   // Resolve the legacy navSideBar prop to the appropriate side.

package/src/navigations/index.js

@@ -36,6 +36,8 @@ export {
   replace,
   /** Returns the currently active path. */
   getCurrentPath,
+  /** Returns the deployment base path, e.g. "/flet-box-docs". */
+  getBasePath,
   /** Returns the component/config for the current route. */
   getCurrentRoute,
   /** Returns the full route state (route, params, query, path). */

package/bin/package.json

@@ -1,45 +0,0 @@
-{
-  "name": "flet-box",
-  "version": "1.0.0",
-  "description": "Ultra-lightweight UI framework for vanilla JS web apps",
-  "type": "module",
-  "main": "src/index.js",
-  "types": "src/index.d.ts",
-  "bin": {
-    "flet-box": "./bin/cli.js"
-  },
-  "scripts": {
-    "dev": "node bin/cli.js run --hot",
-    "build": "node bin/cli.js createBundle",
-    "test": "echo \"No tests yet\"",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "fletbox",
-    "flet-box",
-    "framework",
-    "ui",
-    "flutter-like",
-    "vanilla-js",
-    "lightweight",
-    "pwa",
-    "no-dependencies",
-    "zero-deps"
-  ],
-  "author": "Flet-Box Team",
-  "license": "MIT",
-  "devDependencies": {
-    "chokidar": "^4.0.3",
-    "esbuild": "^0.28.0",
-    "ws": "^8.21.0"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}