flet-box 1.0.5 → 1.0.7

package/src/core/hmr-client.js

@@ -1,4 +1,5 @@
 // src/core/hmr-client.js
+import { getAllRam, saveRam } from "../services/RamStore.js";
 
 /** @type {WebSocket|null} Active WebSocket connection to the HMR server. */
 let ws = null;
@@ -11,6 +12,83 @@ let ws = null;
  */
 let modules = new Map();
 
+/** sessionStorage key that carries `useState` RAM across a hot reload. */
+const STATE_KEY = "__fletbox_hmr_state";
+
+/** How many seconds to keep retrying after the server drops the socket. */
+const MAX_RETRIES = 30;
+
+let retries = 0;
+let everOpened = false;
+let retryTimer = null;
+
+/**
+ * The live state, JSON-safe.
+ *
+ * `useState` lives in a plain Map, so a value that cannot cross a page reload
+ * (a DOM node, a circular graph, a function) is skipped rather than poisoning
+ * the whole snapshot.
+ *
+ * @returns {Object}
+ */
+const snapshotRam = () => {
+  const snapshot = {};
+  for (const [key, value] of Object.entries(getAllRam())) {
+    try {
+      JSON.stringify(value);
+      snapshot[key] = value;
+    } catch (e) {
+      // Not serialisable: this key starts from its default on the next page.
+    }
+  }
+  return snapshot;
+};
+
+/**
+ * Reload the page without losing the developer's place: state is written to
+ * sessionStorage first and put back by `initHMR` on the next load.
+ *
+ * @returns {void}
+ */
+const reloadKeepingState = () => {
+  try {
+    sessionStorage.setItem(STATE_KEY, JSON.stringify(snapshotRam()));
+  } catch (e) {
+    // Private mode, quota, no sessionStorage: reload anyway.
+  }
+  window.location.reload();
+};
+
+/**
+ * Push a previous snapshot back into the RAM store.
+ *
+ * Runs after the app module has already rendered, which is fine: `saveRam`
+ * notifies subscribers, so every `useState` binding repaints with the value it
+ * had before the reload.
+ *
+ * @returns {number} keys restored
+ */
+const restoreRam = () => {
+  let raw = null;
+  try {
+    raw = sessionStorage.getItem(STATE_KEY);
+  } catch (e) {
+    return 0;
+  }
+  if (!raw) return 0;
+  let saved;
+  try {
+    saved = JSON.parse(raw);
+  } catch (e) {
+    return 0;
+  }
+  let restored = 0;
+  for (const [key, value] of Object.entries(saved)) {
+    if (saveRam(key, value)) restored++;
+  }
+  return restored;
+};
+
 /**
  * Initialises the Hot Module Replacement (HMR) client.
  *
@@ -23,19 +101,44 @@ let modules = new Map();
  * - `hmr` — a file changed; delegates to `handleHMR`.
  * - `reload` — the server requests a full page reload.
  *
- * On disconnect the client waits 500 ms then reloads the page so the
- * developer always sees a fresh state.
+ * A dropped socket is retried, not reloaded: reloading into a server that is
+ * still restarting (or a tunnel that closed an idle socket) produced an error
+ * page and then a reload loop. When the connection *re*-establishes, the code
+ * the page runs is stale and the page reloads — with its state.
+ *
+ * @returns {void}
  */
 export const initHMR = () => {
+  const restored = restoreRam();
+  if (restored) console.log(`♻️ HMR restored ${restored} state key(s)`);
+  connect();
+};
+
+/**
+ * @returns {void}
+ */
+const connect = () => {
   const protocol = location.protocol === "https:" ? "wss:" : "ws:";
   ws = new WebSocket(`${protocol}//${location.host}`);
 
   ws.onopen = () => {
+    retries = 0;
+    if (everOpened) {
+      console.log("🔥 HMR reconnected — the page is stale, reloading");
+      reloadKeepingState();
+      return;
+    }
+    everOpened = true;
     console.log("🔥 HMR connected");
   };
 
   ws.onmessage = (event) => {
-    const data = JSON.parse(event.data);
+    let data;
+    try {
+      data = JSON.parse(event.data);
+    } catch (e) {
+      return; // a proxy or tunnel injecting a non-JSON frame must not kill the client
+    }
 
     if (data.type === "request-modules") {
       // Send the list of registered module URLs back to the server.
@@ -50,14 +153,19 @@ export const initHMR = () => {
     }
 
     if (data.type === "reload") {
-      console.log("🔄 Full reload triggered");
-      window.location.reload();
+      console.log("🔄 Reload triggered by the server");
+      reloadKeepingState();
     }
   };
 
   ws.onclose = () => {
-    console.log("🔄 HMR disconnected, reloading...");
-    setTimeout(() => window.location.reload(), 500);
+    if (retries >= MAX_RETRIES) {
+      console.warn("🔌 HMR gave up: the dev server is unreachable. Refresh to retry.");
+      return;
+    }
+    retries++;
+    clearTimeout(retryTimer);
+    retryTimer = setTimeout(connect, 1000);
   };
 };
 
@@ -68,16 +176,13 @@ export const initHMR = () => {
  *
  * - `css` — hot-reloads matching `<link>` stylesheets by appending a cache-
  *   busting timestamp to their `href`, avoiding a full page reload.
- * - `exports-changed` — the module's public API changed in a way that cannot
- *   be patched in-place; triggers a full reload.
- * - anything else — re-imports the changed module via a dynamic `import()` and
- *   dispatches an `hmr:update` CustomEvent so components can react. Falls back
- *   to a full reload if the import fails.
+ * - anything else — the module graph cannot be rebound in place, so the page
+ *   reloads and the `useState` RAM is restored from the snapshot.
  *
  * @param {{ file: string, changeType: string }} data - The HMR payload from the server.
  * @param {string} data.file - Relative path of the changed file.
- * @param {string} data.changeType - The kind of change (`"css"`,
- *   `"exports-changed"`, or any other string for a JS hot-swap).
+ * @param {string} data.changeType - The kind of change (`"css"`, or any other
+ *   string for a reload with the state kept).
  */
 const handleHMR = (data) => {
   const { file, changeType } = data;
@@ -97,26 +202,16 @@ const handleHMR = (data) => {
     return;
   }
 
-  if (changeType === "exports-changed") {
-    console.log(`📦 Exports changed in ${file}, reloading...`);
-    window.location.reload();
-    return;
-  }
-
-  // JS code change — attempt a hot swap via dynamic import.
-  console.log(`🔥 Hot reloading: ${file}`);
-  const url = `/${file}?t=${Date.now()}`;
-  import(url)
-    .then((module) => {
-      // Notify any listening components that the module was updated.
-      window.dispatchEvent(
-        new CustomEvent("hmr:update", { detail: { file, module } }),
-      );
-    })
-    .catch((err) => {
-      console.error("HMR import failed:", err);
-      window.location.reload();
-    });
+  if (changeType === "exports-changed") console.log(`📦 Exports changed in ${file}`);
+  // A JS change reloads the page and puts the state back.
+  //
+  // Re-importing the file is not a swap: a widget that already closed over the
+  // old function keeps the old function, and the fresh module instance nobody
+  // references changes nothing on screen. What the developer should see is the
+  // new code, so the module graph is re-fetched — and because `useState` RAM
+  // survives the reload, that is not paid for with the form you were filling.
+  console.log(`🔥 Reload with state: ${file}`);
+  reloadKeepingState();
 };
 
 /**

package/src/index.d.ts

@@ -341,6 +341,8 @@ declare module 'flet-box' {
     height?: Size;
     fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
     circular?: boolean;
+    downloadable?: boolean;
+    downloadFileName?: string;
     onLoad?: (widget: Widget) => void;
     onError?: (widget: Widget) => void;
     onPress?: (widget: Widget) => void;
@@ -355,6 +357,8 @@ declare module 'flet-box' {
     bgColor?: Color;
     textColor?: Color;
     shape?: 'circle' | 'rounded' | 'square';
+    online?: boolean;
+    badgeColor?: Color;
     onPress?: (widget: Widget) => void;
   }
   export function Avatar(props: AvatarProps): Widget & {
@@ -1363,6 +1367,8 @@ declare module 'flet-box' {
     child: Widget;
     position?: 'top' | 'bottom' | 'left' | 'right';
     delay?: number;
+    /** @deprecated Alias of `delay`. */
+    tooltipDelay?: number;
     bgColor?: Color;
     textColor?: Color;
     fontSize?: number;
@@ -1700,6 +1706,132 @@ declare module 'flet-box' {
     getSource(): string;
   };
 
+  // =========================================================================
+  // Maps
+  // =========================================================================
+
+  /** A point on the map: `[lat, lng]`, `{lat, lng}` or `{latitude, longitude}`. */
+  export type LatLng = [number, number] | { lat: number; lng: number } | { latitude: number; longitude: number };
+
+  /** `[[south, west], [north, east]]`, a named box, or the points to enclose. */
+  export type MapBounds = [[number, number], [number, number]] | { south: number; west: number; north: number; east: number } | LatLng[];
+
+  /** A pin. A bare `LatLng` is also accepted wherever a marker is expected. */
+  export interface MapMarker {
+    position: LatLng;
+    label?: string;
+    color?: Color;
+    /** Keeps the pooled pin node across updates; auto-generated when omitted. */
+    id?: string | number;
+    /** Degrees clockwise from north, the bearing a GPS fix reports. Turns the pin around its own tip. */
+    rotation?: number;
+    /** `false` lets a tap fall through to the map: a tracked vehicle must not block picking a point. */
+    clickable?: boolean;
+    data?: any;
+  }
+
+  /** Payload of `onMapClick`: the geographic point under the cursor. */
+  export interface MapClick {
+    lat: number;
+    lng: number;
+    zoom: number;
+  }
+
+  /** Payload of `onMoveEnd`: the view once it stops changing. */
+  export interface MapState {
+    center: { lat: number; lng: number };
+    zoom: number;
+    bounds: { south: number; west: number; north: number; east: number };
+  }
+
+  /**
+   * A stroked path — a route, a track, a boundary. Needs at least two usable
+   * points. A bare `LatLng[]` is also accepted wherever a polyline is expected.
+   */
+  export interface MapPolyline {
+    points: LatLng[];
+    /** Stroke colour. Defaults to `polylineColor`. */
+    color?: Color;
+    /** Stroke width in CSS pixels. Defaults to `4`. */
+    width?: number;
+    opacity?: number;
+    dashed?: boolean;
+    /** Identifies the line to `removePolyline()`; auto-generated when omitted. */
+    id?: string | number;
+  }
+
+  /** Payload of `onUserUpdate`: one fix from the watcher, in degrees and metres. */
+  export interface MapFix {
+    lat: number;
+    lng: number;
+    /** Radius of 68% confidence in metres, or null when the browser hides it. */
+    accuracy: number | null;
+    /** Degrees clockwise from true north, or null when the device reports none. */
+    heading: number | null;
+  }
+
+  export interface MapsProps extends CommonProps {
+    /** Initial view centre. Defaults to `[20, 0]`. */
+    center?: LatLng;
+    /** Integer zoom level, 0 = the whole world. Defaults to `2`. */
+    zoom?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    /** Positions and/or `{position, label, color, id, data}` records. */
+    markers?: Array<MapMarker | LatLng>;
+    /** Colour of the pins that do not set their own. Defaults to `colors.primary`. */
+    markerColor?: Color;
+    /** Position lists and/or `{points, color, width, opacity, dashed, id}` records. */
+    polylines?: Array<MapPolyline | LatLng[]>;
+    /** Stroke of the lines that do not set their own. Defaults to `colors.primary`. */
+    polylineColor?: Color;
+    /** `{z}/{x}/{y}` tile template. Defaults to OpenStreetMap. */
+    tileUrl?: string;
+    /** Credit line; most providers require one. */
+    attribution?: string;
+    showAttribution?: boolean;
+    showZoomControl?: boolean;
+    /** When false the view only moves through the imperative API. */
+    interactive?: boolean;
+    scrollZoom?: boolean;
+    doubleClickZoom?: boolean;
+    /** Draws the browser position; asks for permission on the first map paint. */
+    showUserLocation?: boolean;
+    /**
+     * Keeps the view centred on the browser position. Implies the dot and asks
+     * the browser for fresh high-accuracy fixes instead of a cached one.
+     */
+    followUser?: boolean;
+    onMapClick?: (point: MapClick, event: PointerEvent) => void;
+    onMarkerClick?: (marker: MapMarker, event: MouseEvent) => void;
+    onMoveEnd?: (state: MapState) => void;
+    /** Fires on each watched fix, including the ones while `followUser` is off. */
+    onUserUpdate?: (fix: MapFix) => void;
+  }
+  export function Maps(props: MapsProps): Widget & {
+    setCenter(position: LatLng, zoom?: number): Widget;
+    getCenter(): { lat: number; lng: number };
+    getZoom(): number;
+    zoomTo(zoom: number): Widget;
+    panBy(dx: number, dy: number): Widget;
+    fitBounds(bounds: MapBounds, padding?: number): Widget;
+    getState(): MapState;
+    addMarker(marker: MapMarker | LatLng): MapMarker | null;
+    /** Replace the marker with the same id, or append it when that id is new. */
+    setMarker(marker: MapMarker | LatLng): MapMarker | null;
+    removeMarker(idOrMarker: string | number | MapMarker): Widget;
+    clearMarkers(): Widget;
+    getMarkers(): MapMarker[];
+    addPolyline(line: MapPolyline | LatLng[]): MapPolyline | null;
+    removePolyline(idOrLine: string | number | MapPolyline): Widget;
+    clearPolylines(): Widget;
+    getPolylines(): MapPolyline[];
+    setFollowUser(on: boolean): Widget;
+    locate(settings?: { setCenter?: boolean; zoom?: number; timeout?: number; maximumAge?: number; highAccuracy?: boolean }): Promise<{ lat: number; lng: number }> | null;
+    setUserPosition(position: LatLng | number[] | null, settings?: { setCenter?: boolean; zoom?: number }): Widget;
+    render(): Widget;
+  };
+
   // =========================================================================
   // Core
   // =========================================================================

package/src/index.js

@@ -175,6 +175,7 @@ export {
   TreeView,
   Chart,
   QRCode,
+  Maps,
   DraggBox,
   DroppBox,
   DataTable,

package/src/navigations/AppBar.js

@@ -189,15 +189,20 @@ export const AppBar = (props) => {
 
   // ========== LEFT SECTION ==========
   // Fixed minimum width ensures the center title stays visually centered
-  // even when no leading widget is present.
+  // even when no leading widget is present. That balance is only meaningful
+  // for a centered title: with `centerTitle: false` the title is flush-left,
+  // so reserving the empty 48px zone would push it past the page's content
+  // edge. Same reasoning for the title zone's 8px gutter.
+  const hasLeading = finalLeading instanceof HTMLElement;
+  const balanceZones = centerTitle || hasLeading;
   const leftSection = Container({
     display: "flex",
     alignItems: "center",
     bgColor: "transparent",
     justifyContent: "flex-start",
-    minWidth: 48,
+    minWidth: balanceZones ? 48 : 0,
     flexShrink: 0,
-    child: finalLeading instanceof HTMLElement ? finalLeading : null,
+    child: hasLeading ? finalLeading : null,
   });
   appBar.appendChild(leftSection);
 
@@ -224,9 +229,15 @@ export const AppBar = (props) => {
     // pushes the actions past the viewport edge on narrow screens.
     flex: 1,
     display: "flex",
+    // Container defaults to `flex-direction: column`, which silently rewrites
+    // the two axes: `alignItems: center` becomes horizontal centring and
+    // `justifyContent` (the flag that carries `centerTitle`) becomes vertical.
+    // A string title hid this because its Text fills the width; an
+    // auto-width widget title got centred no matter what `centerTitle` said.
+    flexDirection: "row",
     alignItems: "center",
     justifyContent: centerTitle ? "center" : "flex-start",
-    padding: "0 8px",
+    padding: balanceZones ? "0 8px" : "0",
     bgColor: "transparent",
     overflow: "hidden",
     minWidth: 0,

package/src/navigations/Drawer.js

@@ -173,7 +173,15 @@ export const Drawer = (props = {}) => {
           paddingBottom: 8,
           overflow: "auto",
           backgroundColor: bgColor,
-          children: body,
+          // This body is a scroll container inside a fixed-height flex column,
+          // and every child defaults to `flex-shrink: 1`. Left alone, a short
+          // drawer squeezed its rows down to their own padding (a DrawerItem
+          // collapsed to ~24px) instead of overflowing. Pinning the children
+          // keeps them at content height so the body scrolls as intended.
+          children: body.map((child) => {
+            if (child && child.style) child.style.flexShrink = "0";
+            return child;
+          }),
         }),
 
       footer &&

package/src/widget-factory/translateProps.js

@@ -480,6 +480,7 @@ export const ALL_PROPS = [
   { prop: "widthExpanded", domProp: "widthExpanded", type: "special" },
   { prop: "widthCollapsed", domProp: "widthCollapsed", type: "special" },
   { prop: "showTooltip", domProp: "showTooltip", type: "special" },
+  // Legacy alias of `delay`, still honoured by Tooltip.
   { prop: "tooltipDelay", domProp: "tooltipDelay", type: "special" },
 
   // ---- ListView / GridView ----
@@ -702,6 +703,7 @@ export const ALL_PROPS = [
   // ---- Avatar / Badge / Icon / Chip ----
   { prop: "icon", domProp: "icon", type: "special" },
   { prop: "shape", domProp: "shape", type: "special" },
+  // Presence dot: `online` shows it on Avatar, `badgeColor` paints it.
   { prop: "online", domProp: "online", type: "special" },
   { prop: "badge", domProp: "badge", type: "special" },
   { prop: "badgeColor", domProp: "badgeColor", type: "special" },
@@ -732,9 +734,12 @@ export const ALL_PROPS = [
   { prop: "headingColor", domProp: "headingColor", type: "special" },
   { prop: "allowDangerousHtml", domProp: "allowDangerousHtml", type: "special" },
 
-  // ---- InstallButton ----
+  // ---- Image ----
+  // `downloadable` turns a click into a save, `downloadFileName` names the file.
   { prop: "downloadable", domProp: "downloadable", type: "special" },
   { prop: "downloadFileName", domProp: "downloadFileName", type: "special" },
+
+  // ---- InstallButton ----
   { prop: "onInstalled", domProp: "onInstalled", type: "special" },
 
   // ---- MatrixRain ----
@@ -748,6 +753,32 @@ export const ALL_PROPS = [
   { prop: "fgColor", domProp: "fgColor", type: "special" },
   { prop: "errorCorrection", domProp: "errorCorrection", type: "special" },
 
+  // ---- Maps ----
+  // `center` and `markers` are already registered above; the rest are Maps-only.
+  // All are inert here: Maps destructures them before the factory sees them and
+  // re-applies them through `composeUpdate`, so the registry entry only has to
+  // keep them out of the unknown-prop fallback (an invalid inline style for a
+  // `{lat, lng}` object, a bogus `mapclick` listener for `onMapClick`).
+  { prop: "zoom", domProp: "zoom", type: "special" },
+  { prop: "minZoom", domProp: "minZoom", type: "special" },
+  { prop: "maxZoom", domProp: "maxZoom", type: "special" },
+  { prop: "markerColor", domProp: "markerColor", type: "special" },
+  { prop: "polylines", domProp: "polylines", type: "special" },
+  { prop: "polylineColor", domProp: "polylineColor", type: "special" },
+  { prop: "tileUrl", domProp: "tileUrl", type: "special" },
+  { prop: "attribution", domProp: "attribution", type: "special" },
+  { prop: "showAttribution", domProp: "showAttribution", type: "special" },
+  { prop: "showZoomControl", domProp: "showZoomControl", type: "special" },
+  { prop: "interactive", domProp: "interactive", type: "special" },
+  { prop: "scrollZoom", domProp: "scrollZoom", type: "special" },
+  { prop: "doubleClickZoom", domProp: "doubleClickZoom", type: "special" },
+  { prop: "showUserLocation", domProp: "showUserLocation", type: "special" },
+  { prop: "followUser", domProp: "followUser", type: "special" },
+  { prop: "onMapClick", domProp: "onMapClick", type: "special" },
+  { prop: "onMarkerClick", domProp: "onMarkerClick", type: "special" },
+  { prop: "onMoveEnd", domProp: "onMoveEnd", type: "special" },
+  { prop: "onUserUpdate", domProp: "onUserUpdate", type: "special" },
+
   // ---- Image fit ----
   { prop: "fit", domProp: "objectFit", type: "style", unit: "none", reactive: true },
   { prop: "objectFit", domProp: "objectFit", type: "style", unit: "none", reactive: true },