flet-box 1.0.6 → 1.0.8

package/docs/widget/Dropdown.md

@@ -53,10 +53,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
@@ -112,6 +116,7 @@ const country = Dropdown({
 
 - Pass objects with value/label when the value sent to onChange must differ from the text shown, such as an id versus a name.
 - Set clearable: true to give users an explicit way back to no selection.
+- Bind a useState value to `value` to move the selection from code, such as auto-picking a default after a lookup; pass `''` to clear it back to the placeholder.
 
 ## Accessibility
 
@@ -121,6 +126,7 @@ const country = Dropdown({
 
 - The option menu is portaled to document.body by default and repositions on scroll/resize; set portal: false to keep it inline.
 - The returned element exposes value, open(), close() and update(), and removes its listeners on unmount.
+- A value applied from outside — a bound state change or `dropdown.value = x` — re-fires onChange when it differs from the current selection, and is ignored when it is the same, so a state → value → onChange → state loop settles after one pass.
 
 ## Related widgets
 

package/docs/widget/DroppBox.md

@@ -61,10 +61,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
@@ -149,4 +153,4 @@ const zone = DroppBox({
 - **Next:** [Scaffold](Scaffold.md) — Chapter 8 · App navigation
 - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
 
-You are reading **Chapter 7 · Media and drag & drop** (4 of 4).
+You are reading **Chapter 7 · Media and drag & drop** (5 of 5).

package/docs/widget/FloatingActionButton.md

@@ -45,10 +45,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/GridView.md

@@ -54,10 +54,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Icon.md

@@ -39,10 +39,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Image.md

@@ -1,6 +1,6 @@
 # Image
 
-Renders an image element from a URL or path. Supports fixed sizing, object-fit modes, and a circular crop for avatars.
+Renders an image element from a URL or path. Supports fixed sizing, object-fit modes, a circular crop for avatars, and saving on click.
 
 ## When to use it
 
@@ -29,6 +29,8 @@ const photo = Image({
 | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
 | `fit` | `'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'` | How the image fits its box (CSS `object-fit`). |
 | `circular` | `boolean` | Clips the image into a circle. |
+| `downloadable` | `boolean` | Makes a click on the image save it. |
+| `downloadFileName` | `string` | File name suggested when saving; defaults to the name in the URL. |
 | `onLoad` | `(widget: Widget) => void` | Fired when the media finishes loading. |
 | `onError` | `(widget: Widget) => void` | Fired when the media fails to load. |
 | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
@@ -45,10 +47,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
@@ -82,12 +88,14 @@ const cover = Image({
 import { Image } from "flet-box";
 
 const teamPhoto = Image({
-  src: "/team/anna.jpg",
+  src: "/team/anna.jpg?v=3",
   alt: "Anna at the keynote",
   width: 96,
   height: 96,
   fit: "cover",
   circular: true,
+  downloadable: true,
+  downloadFileName: "anna-keynote.jpg",
   onLoad: () => console.log("loaded"),
   onError: () => console.error("failed"),
   onPress: () => console.log("open profile"),
@@ -98,6 +106,7 @@ const teamPhoto = Image({
 
 - Set both width and height with fit: "cover" to avoid stretched or squashed art.
 - Use circular: true instead of a full borderRadius when you want a perfect avatar crop.
+- downloadable only saves the file when the image is same-origin or CORS-served; anything else opens in a new tab instead of replacing your app.
 
 ## Accessibility
 
@@ -106,7 +115,9 @@ const teamPhoto = Image({
 ## Behavior
 
 - onLoad fires once the image decodes; onError fires when the src fails to load.
-- onPress is attached to the wrapper, so the image behaves like a tappable tile.
+- onPress is attached to the image itself, so the image behaves like a tappable tile.
+- With downloadable: true a click saves the image under downloadFileName, or under the file name in the URL when that prop is absent.
+- Both download props stay live: update() can turn the offer on or off and rename it, and a downloadable bound to a useState key follows the store.
 
 ## Related widgets
 

package/docs/widget/Input.md

@@ -65,10 +65,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Inspector.md

@@ -23,7 +23,7 @@ const debug = Inspector({
 | Prop | Type | Description |
 | --- | --- | --- |
 | `widget` | `Widget` | The DOM node or widget to inspect. |
-| `indent` | `number` | Indentation depth used when printing nested structures. |
+| `indent` | `number` | Starting indentation depth of the printout; each level is two spaces. |
 
 ## Examples
 
@@ -37,7 +37,7 @@ const debug = Inspector({
     padding: 16,
     child: Text({ text: "Profile" }),
   }),
-  indent: 16,
+  indent: 1,
 });
 ```
 

package/docs/widget/InstallButton.md

@@ -43,10 +43,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/ListTile.md

@@ -54,10 +54,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/ListView.md

@@ -53,10 +53,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Maps.md

@@ -0,0 +1,191 @@
+# Maps
+
+An interactive map — pan, zoom, markers and polylines — with no map library behind it. The Web Mercator projection and the XYZ tile grid are implemented inside the widget, so any provider that answers `{z}/{x}/{y}` works and nothing needs an API key, a CDN or a build step.
+
+## When to use it
+
+Use it to show a venue, plot delivery stops, draw a route, or let a picker return a coordinate.
+
+## Quick start
+
+```javascript
+import { Maps } from "flet-box";
+
+const place = Maps({
+  center: [40.4168, -3.7038],
+  zoom: 12,
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `center` | `LatLng` | View centre as `[lat, lng]`, `{lat, lng}` or `{latitude, longitude}`. |
+| `zoom` | `number` | Integer zoom level: `0` shows the whole world, each step doubles the scale. |
+| `minZoom` | `number` | Lowest zoom level the user can reach. |
+| `maxZoom` | `number` | Highest zoom level the user can reach, usually the provider's last tile level. |
+| `markers` | `Array<MapMarker \| LatLng>` | Pins to draw: bare positions or `{position, label, color, id, rotation, clickable, data}` records. |
+| `markerColor` | `Color` | Colour of the pins that do not set a `color` of their own. |
+| `polylines` | `Array<MapPolyline \| LatLng[]>` | Stroked paths: bare position lists or `{points, color, width, opacity, dashed, id}` records. |
+| `polylineColor` | `Color` | Stroke of the lines that do not set a `color` of their own. |
+| `tileUrl` | `string` | `{z}/{x}/{y}` tile template of the provider. |
+| `attribution` | `string` | Credit line shown in the corner; most tile providers require one. |
+| `showAttribution` | `boolean` | Shows the credit line. |
+| `showZoomControl` | `boolean` | Shows the ± zoom buttons in the top-right corner. |
+| `interactive` | `boolean` | Lets the user pan and zoom. When false, only the imperative API moves the view. |
+| `scrollZoom` | `boolean` | Zooms with the mouse wheel, centred on the cursor. |
+| `doubleClickZoom` | `boolean` | Zooms on double-click; `Shift` + double-click zooms out. |
+| `showUserLocation` | `boolean` | Draws the browser's position; asks for permission on the first paint. |
+| `followUser` | `boolean` | Keeps the view centred on the browser's position, asking for fresh high-accuracy fixes. |
+| `onMapClick` | `(point: MapClick, event: PointerEvent) => void` | Fired with `{ lat, lng, zoom }` when the map is clicked without panning. |
+| `onMarkerClick` | `(marker: MapMarker, event: MouseEvent) => void` | Fired with the clicked marker. |
+| `onMoveEnd` | `(state: MapState) => void` | Fired with `{ center, zoom, bounds }` once the view stops changing. |
+| `onUserUpdate` | `(fix: MapFix) => void` | Fired with `{ lat, lng, accuracy }` on each position the watcher reports. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { Maps, colors } from "flet-box";
+
+const stops = Maps({
+  center: [40.4168, -3.7038],
+  zoom: 13,
+  height: 420,
+  markerColor: colors.primary,
+  polylineColor: colors.primary,
+  markers: [
+    { position: [40.4168, -3.7038], label: "Sol" },
+    { position: [40.4308, -3.693], label: "Chueca", color: "#0ea5e9" },
+  ],
+  polylines: [
+    [[40.4168, -3.7038], [40.424, -3.698], [40.4308, -3.693]],
+  ],
+  onMarkerClick: (marker) => pick(marker),
+});
+```
+
+### Full
+
+```javascript
+import { Maps, colors } from "flet-box";
+
+const picker = Maps({
+  center: [40.4168, -3.7038],
+  zoom: 14,
+  minZoom: 5,
+  maxZoom: 18,
+  height: 480,
+  borderRadius: 12,
+  tileUrl: "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
+  attribution: "© OpenStreetMap contributors",
+  showAttribution: true,
+  showZoomControl: true,
+  interactive: true,
+  scrollZoom: true,
+  doubleClickZoom: true,
+  showUserLocation: true,
+  followUser: false,
+  markers: stops.map((stop) => ({ id: stop.id, position: stop.at, label: stop.name })),
+  polylines: [
+    { id: "route", points: route.geometry, color: colors.primary, width: 5 },
+    { id: "track", points: breadcrumbs, dashed: true, opacity: 0.7 },
+  ],
+  onMapClick: (point) => setPicked(point),
+  onMarkerClick: (marker) => setPicked(marker.position),
+  onMoveEnd: (view) => saveView(view),
+  onUserUpdate: (fix) => breadcrumbs.push([fix.lat, fix.lng]),
+});
+
+picker.fitBounds(route.geometry);
+picker.addMarker({ position: [40.42, -3.7], label: "Dropped" });
+picker.setMarker({ id: "taxi", position: [40.42, -3.7], rotation: 128, clickable: false });
+picker.addPolyline({ id: "leg", points: [picked, stop.at] });
+picker.locate();
+picker.setFollowUser(true);
+```
+
+## Tips
+
+- The default tile server is OpenStreetMap and its credit line renders by default; when you change tileUrl, change attribution in the same breath.
+- Match maxZoom to the provider. Asking level 20 from a server that stops at 18 shows the offline notice instead of a map.
+- `locate()` takes `{ timeout, maximumAge, highAccuracy, setCenter, zoom }`. Desktop laptops can need more than the 10 s default for a first fix, and a slow fix (code 3) is not the same failure as a denied permission (code 1) — branch on `error.code` in the rejected handler instead of reporting one generic error.
+- Give markers an id: the pin node is then reused across updates instead of rebuilt, which matters for a list that moves often.
+- `setMarker({id, ...})` replaces the pin with that id instead of stacking another under it — that is the call to make on every GPS fix, and `addMarker()` is the one that grows the list forever. The reused node restates what it shows, so a new `label`, `color` or `rotation` reaches the screen, the tooltip and the accessibility name.
+- `rotation` is degrees clockwise from north, the compass convention `onUserUpdate` reports as `fix.heading`. The pin turns around its own tip, so the point it marks never moves, and its caption stays upright to read.
+- `clickable: false` makes a pin transparent to the pointer: the tap reaches `onMapClick` with the coordinate under it. A vehicle drawn at the centre of the view would otherwise cover that whole spot, and every attempt to pick a pick-up point would answer with the car.
+- A polyline needs two usable points; `addPolyline()` returns null for one-point input rather than drawing a speck that looks like a broken route. Lines are stroked on a canvas above the tiles and below the pins, so a long route costs no DOM nodes — but it also means a line is not clickable; put an invisible marker on each stop you want tappable.
+- `fitBounds(pointList)` frames a route in one call: pass the coordinates and it picks the zoom and centre. Feed it the geometry an OSRM or GraphHopper reply returns, and keep the distance and duration from that same reply for the readout.
+- A track grows by re-passing `polylines` with the fixes collected so far, or by keeping one line with an id and calling `update()`. `onUserUpdate` is the source of those fixes: it fires for every watched position, following or not.
+- `followUser` is a different promise from `showUserLocation`: it recentres the view on every fix and asks the browser for fresh high-accuracy ones, so it is the option that costs battery. Turn it off when the user pans away to look at something else.
+- The widget defaults to 400 tall and full width. Any size you give it is fine — a ResizeObserver repaints the tiles when the box changes.
+- Wheel zoom is one level per gesture and follows the cursor, so a long trackpad flick does not throw the view across the world.
+
+## Accessibility
+
+- The map is focusable and keyboard-driven: arrows pan, + and - zoom, and the ± buttons carry aria-labels.
+- Each marker is a real button, so it is reachable with Tab and announced with its label.
+- A map cannot be read by a screen reader, so keep the same places in a list next to it.
+
+## Behavior
+
+- Tiles are pooled per zoom level and the previous level is kept until the new one is on screen, so a zoom step never flashes an empty grid.
+- onMoveEnd is debounced — it fires once the view settles, not on every pan frame.
+- Lines are redrawn from their geographic points on every frame, so a polyline follows the pan and the zoom instead of being pinned to the screen. A line whose bounding box misses the viewport is skipped before any coordinate is projected.
+- Whether a press was a drag is judged by how far the pointer ended up from the point it went down on, not by the length of the path it walked: a trembling finger keeps its click and never nudges the view.
+- A press on a pin answers onMarkerClick only; the map never reports the same press twice.
+- A press on the widget's own chrome — the ± buttons or the credit link — is not a click on the map underneath, so onMapClick reports only the bare map surface.
+- Props bound with useState patch this widget alone — the map subscribes to the key and redraws without re-rendering the app.
+- Nothing is fetched until the widget enters the DOM; unmount cancels the frame, the observer and the geolocation watch.
+- When every visible tile fails, a notice appears over the map instead of a blank panel.
+
+## Related widgets
+
+- [Card](Card.md)
+- [Button](Button.md)
+- [ListView](ListView.md)
+- [Image](Image.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Video](Video.md)
+- **Next:** [DraggBox](DraggBox.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 7 · Media and drag & drop** (3 of 5).

package/docs/widget/Markdown.md

@@ -79,10 +79,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/MatrixRain.md

@@ -41,10 +41,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Pagination.md

@@ -50,10 +50,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/ParallaxBox.md

@@ -45,10 +45,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/ProgressBar.md

@@ -48,10 +48,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/QRCode.md

@@ -41,10 +41,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/README.md

@@ -102,21 +102,22 @@ _audio, video and drag-and-drop_
 
 52. [Audio](Audio.md) — A thin wrapper around the native <audio> element with reliable duration detection, progress callbacks, and an imperative playback API
 53. [Video](Video.md) — Renders a native <video> element with proper media attributes and a convenient playback API
-54. [DraggBox](DraggBox.md) — Wraps a child so it can be dragged with the native drag-and-drop API
-55. [DroppBox](DroppBox.md) — A drop target for DraggBox items
+54. [Maps](Maps.md) — An interactive map — pan, zoom, markers and polylines — with no map library behind it
+55. [DraggBox](DraggBox.md) — Wraps a child so it can be dragged with the native drag-and-drop API
+56. [DroppBox](DroppBox.md) — A drop target for DraggBox items
 
 ### Chapter 8 · App navigation
 
 _Build the shell of a real application and wire it to the router._
 
-56. [Scaffold](Scaffold.md) — the app shell: app bar, body, drawer, side bars
-57. [AdaptiveScaffold](AdaptiveScaffold.md) — the same shell, adapted to phone and desktop
-58. [AppBar](AppBar.md) — a top bar for titles, actions, and back navigation
-59. [Drawer](Drawer.md) — a panel that slides in from the side
-60. [DrawerItem](DrawerItem.md) — a router-aware row for a drawer or side bar
-61. [BottomNavigation](BottomNavigation.md) — a bottom tab bar synced with the router
-62. [Tabs](Tabs.md) — switch panes inside a screen
-63. [CollapsibleSideBar](CollapsibleSideBar.md) — a side panel that collapses to icons
+57. [Scaffold](Scaffold.md) — the app shell: app bar, body, drawer, side bars
+58. [AdaptiveScaffold](AdaptiveScaffold.md) — the same shell, adapted to phone and desktop
+59. [AppBar](AppBar.md) — a top bar for titles, actions, and back navigation
+60. [Drawer](Drawer.md) — a panel that slides in from the side
+61. [DrawerItem](DrawerItem.md) — a router-aware row for a drawer or side bar
+62. [BottomNavigation](BottomNavigation.md) — a bottom tab bar synced with the router
+63. [Tabs](Tabs.md) — switch panes inside a screen
+64. [CollapsibleSideBar](CollapsibleSideBar.md) — a side panel that collapses to icons
 
 Then continue with [State, Router & Services](../guides/state.md) — Chapter 9.
 
@@ -163,6 +164,7 @@ Then continue with [State, Router & Services](../guides/state.md) — Chapter 9.
 - [InstallButton](InstallButton.md)
 - [ListTile](ListTile.md)
 - [ListView](ListView.md)
+- [Maps](Maps.md)
 - [Markdown](Markdown.md)
 - [MatrixRain](MatrixRain.md)
 - [Modal](Modal.md)

package/docs/widget/Radio.md

@@ -44,10 +44,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
@@ -99,7 +103,7 @@ const option = Radio({
 
 ## Accessibility
 
-- The circle carries no visible label on its own; render a Text beside it and never rely on color alone.
+- The `label` prop renders the words beside the ring inside the same pressable row; never rely on color alone to convey the selection.
 
 ## Behavior
 

package/docs/widget/Rating.md

@@ -50,10 +50,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |