flet-box 1.0.2 → 1.0.4

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,
@@ -270,9 +277,15 @@ export const AppBar = (props) => {
       lastScrollY = currentScrollY;
     };
     window.addEventListener("scroll", handleScroll);
-    // Store the remover so _cleanup can deregister the listener.
-    appBar._cleanupScroll = () =>
+    // Register the remover through BOTH teardown paths. `_cleanup` is only called
+    // by runApp's teardownTree / Scaffold, while a plain DOM disconnect goes
+    // through the lifecycle observer, which never calls `_cleanup` — so without
+    // `onUnmount` this listener (and the detached bar) stayed alive forever.
+    // `removeEventListener` is idempotent, so running both is harmless.
+    const removeScroll = () =>
       window.removeEventListener("scroll", handleScroll);
+    appBar._cleanupScroll = removeScroll;
+    appBar.onUnmount(removeScroll);
   }
 
   // ========== PUBLIC API ==========

package/src/navigations/BottomNavigation.js

@@ -285,10 +285,22 @@ export const BottomNavigation = (props) => {
     return getCurrentPath();
   };
 
-  // Cleanup: unsubscribe from the router when the bar is removed from the DOM.
+  // Cleanup: release the router subscription on EITHER teardown path. `_cleanup`
+  // is only run by runApp's teardownTree / Scaffold; the lifecycle observer that
+  // fires on a plain DOM disconnect never calls it, so without `onUnmount` the
+  // router kept invoking `updateColorsFromRouter()` (and `onTabChange`) on a
+  // detached bar forever. The disposer is idempotent because both paths can run.
+  let unsubscribed = false;
+  const dispose = () => {
+    if (unsubscribed) return;
+    unsubscribed = true;
+    if (unsubscribe) unsubscribe();
+  };
+  container.onUnmount(dispose);
+
   const originalCleanup = container._cleanup;
   container._cleanup = () => {
-    if (unsubscribe) unsubscribe();
+    dispose();
     if (originalCleanup) originalCleanup();
   };
 

package/src/navigations/DrawerItem.js

@@ -246,11 +246,24 @@ export const DrawerItem = (props) => {
   // Apply the initial visual state now that DOM refs are set.
   updateUI();
 
-  // Cleanup: unsubscribe from router and selection events to prevent memory leaks.
-  const originalCleanup = container._cleanup;
-  container._cleanup = () => {
+  // Cleanup: release the router subscription and the selection listener on EITHER
+  // teardown path. `_cleanup` is only run by runApp's teardownTree / Scaffold; the
+  // lifecycle observer that fires on a plain DOM disconnect never calls it, so
+  // without `onUnmount` every removed item kept a live router callback (retaining
+  // its DOM refs) plus a listener on the shared selection EventTarget. The
+  // disposer is idempotent because both paths can run.
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
     if (unsubscribeRouter) unsubscribeRouter();
     if (unsubscribeGlobal) unsubscribeGlobal();
+  };
+  container.onUnmount(dispose);
+
+  const originalCleanup = container._cleanup;
+  container._cleanup = () => {
+    dispose();
     if (originalCleanup) originalCleanup();
   };
 

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.
@@ -491,8 +494,15 @@ export const Scaffold = (props) => {
     clearContainer(fabContainer);
     clearContainer(leftNavBarContainer);
     clearContainer(rightNavBarContainer);
-    if (container._drawer?.parentNode)
+    // `destroy()` releases the viewport-resize listener, the Escape key handler
+    // and the pending close timer, then removes the node itself. Removing only
+    // the node (the previous behaviour) left all three behind, so every rebuilt
+    // scaffold leaked one more listener and one more body child.
+    if (typeof container._drawer?.destroy === "function") {
+      container._drawer.destroy();
+    } else if (container._drawer?.parentNode) {
       container._drawer.parentNode.removeChild(container._drawer);
+    }
     if (originalCleanup) originalCleanup();
   };
 

package/src/navigations/Tabs.js

@@ -318,6 +318,11 @@ export const Tabs = (props) => {
     updateContent();
   };
 
+  // Mount the initially active pane during construction. Without this the pane
+  // area stayed empty until the user clicked a *different* tab, even though the
+  // first tab already rendered as `aria-selected="true"`.
+  updateContent();
+
   // Defer the initial slider position calculation by one frame so the DOM
   // has been laid out and getBoundingClientRect() returns real values.
   let initialPositionTimer = setTimeout(() => {
@@ -341,18 +346,41 @@ export const Tabs = (props) => {
 
   // Also observe the tab bar element itself so the thumb repositions when
   // the container resizes independently of the window (e.g. sidebar toggle).
-  if (typeof ResizeObserver !== "undefined") {
+  // Only the slider variant has a thumb, so skip it for the other variants.
+  if (variant === "slider" && typeof ResizeObserver !== "undefined") {
     resizeObserver = new ResizeObserver(() => updateSliderPosition());
     if (tabsWrapperRef) resizeObserver.observe(tabsWrapperRef);
   }
 
-  // Cleanup: cancel timers and remove listeners when the component is unmounted.
+  // Cleanup: release the timers, the window listener and the observer on EITHER
+  // teardown path. `_cleanup` is only run by runApp's teardownTree / Scaffold; a
+  // plain DOM disconnect goes through the lifecycle observer, which never calls
+  // it — so without `onUnmount` the resize listener stayed registered and the
+  // ResizeObserver kept observing (and retaining) a detached tab bar. The
+  // disposer is idempotent because both paths can run.
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    if (initialPositionTimer) {
+      clearTimeout(initialPositionTimer);
+      initialPositionTimer = null;
+    }
+    if (resizeTimeout) {
+      clearTimeout(resizeTimeout);
+      resizeTimeout = null;
+    }
+    window.removeEventListener("resize", handleResize);
+    if (resizeObserver) {
+      resizeObserver.disconnect();
+      resizeObserver = null;
+    }
+  };
+  container.onUnmount(dispose);
+
   const originalCleanup = container._cleanup;
   container._cleanup = () => {
-    if (initialPositionTimer) clearTimeout(initialPositionTimer);
-    if (resizeTimeout) clearTimeout(resizeTimeout);
-    window.removeEventListener("resize", handleResize);
-    if (resizeObserver) resizeObserver.disconnect();
+    dispose();
     if (originalCleanup) originalCleanup();
   };
 

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/src/tools/dimensions.js

@@ -16,8 +16,14 @@
  * // Call remove() to stop listening.
  */
 
-let windowWidth = window.innerWidth;
-let windowHeight = window.innerHeight;
+// SSR / Node guard: this module must stay importable where `window` does not
+// exist (SSR, test runners, build tooling). Reading `window.innerWidth` at
+// module scope used to throw a ReferenceError on import. Same convention as
+// `src/core/pwa.js`.
+const hasWindow = typeof window !== "undefined";
+
+let windowWidth = hasWindow ? window.innerWidth : 0;
+let windowHeight = hasWindow ? window.innerHeight : 0;
 
 // Live named exports — is-module live bindings: importers of { width, height }
 // always read the current value, kept in sync on resize.
@@ -45,7 +51,9 @@ const handleResize = () => {
   });
 };
 
-window.addEventListener("resize", handleResize);
+// Only subscribe inside a browser; in Node the listener list stays inert and
+// `addListener` / `removeListener` keep working without throwing.
+if (hasWindow) window.addEventListener("resize", handleResize);
 
 /**
  * Dimensions object — provides getter properties and listener management.