flet-box 1.0.6 → 1.0.8

package/docs/tools/markdown.md

@@ -24,9 +24,9 @@ import { parseMarkdown, markdownToWidgets, escapeHtml } from "flet-box";
 | `parseMarkdown` | `parseMarkdown(text)` | `string` | Reserved API: currently returns the input unchanged. Use `markdownToWidgets`. |
 | `parseInlineMarkdown` | `parseInlineMarkdown(text)` | `string` | Reserved API: currently returns the input unchanged. Use `parseInlineToWidgets`. |
 | `tokenize` | `tokenize(code)` | `{ type, value }[]` | Split code into token objects. |
-| `generateHighlightedHtml` | `generateHighlightedHtml(code)` | `string` | Code → highlighted HTML. |
+| `generateHighlightedHtml` | `generateHighlightedHtml(code, palette?)` | `string` | Code → highlighted HTML. Picks the light or dark token map automatically; pass a map to override. |
 | `escapeHtml` | `escapeHtml(text)` | `string` | Escape `<`, `>`, `&`, quotes so text is safe as HTML. |
-| `highlightColors` | const | `Record<string, string>` | The token color map used by the highlighter. |
+| `highlightColors` | const | `Record<string, string>` | The dark-theme token map (One Dark scale). |
 
 `markdownToWidgets` options: `{ codeMaxHeight?: number, codeFontSize?: number }`.
 
@@ -61,7 +61,7 @@ const safe = escapeHtml(userInput); // safe to put into innerHTML
 - `markdownToWidgets` builds real widget elements (headings, paragraphs, code blocks, lists) that you can place inside any container — this is what the `Markdown` widget uses.
 - `parseMarkdown` and `parseInlineMarkdown` are reserved placeholders that currently pass text through unchanged; the widget rendering is `markdownToWidgets`/`parseInlineToWidgets`.
 - `escapeHtml` should be used for **any** text you insert into the DOM that you did not write yourself. Never trust raw input.
-- `tokenize` returns flat token objects and is the base for custom highlighters; `highlightColors` lets you theme them.
+- `tokenize` returns flat token objects and is the base for custom highlighters; `generateHighlightedHtml` reads the active theme, and its second argument accepts a token map when you paint your own surface.
 
 ## Related pages
 - [Themes](theme.md) — previous chapter.

package/docs/tools/theme.md

@@ -11,7 +11,7 @@ FletBox ships a built-in color system: `colors` is the palette of the current th
 ## Import
 
 ```javascript
-import { colors, setTheme, toggleTheme, subscribeTheme, ThemeProvider } from "flet-box";
+import { colors, setTheme, registerPalette, toggleTheme, subscribeTheme, ThemeProvider } from "flet-box";
 ```
 
 ## Functions
@@ -19,6 +19,7 @@ import { colors, setTheme, toggleTheme, subscribeTheme, ThemeProvider } from "fl
 | Function | Signature | Returns | Description |
 | --- | --- | --- | --- |
 | `setTheme` | `setTheme('light' \| 'dark')` | `Record<string, string>` | Switch the active palette. |
+| `registerPalette` | `registerPalette(themeName, palette)` | `Record<string, string>` | Merge brand tokens into a named palette and repaint the page. |
 | `getTheme` | `getTheme()` | `string` | The active theme name. |
 | `toggleTheme` | `toggleTheme()` | `string` | Flip light/dark and return the new name. |
 | `getColor` | `getColor(name, opacity?)` | `string` | Resolve a token (optionally with alpha). |
@@ -38,9 +39,47 @@ Every token is available on `colors`:
 - **Surfaces:** `background`, `surface`, `card`, `overlay`.
 - **Text:** `text`, `textSecondary`, `textDisabled`, `divider`, `border`, `shadow`.
 - **Tints:** `gray50` … `gray900`, plus the soft backgrounds `errorBg`, `successBg`, `warningBg`, `infoBg`.
+- **Glass:** `glass` (the translucent surface) and `glassBorder` (its rim), meant to pair with `backdropFilter`. Light is white glass, dark is a slate pane with a light rim.
 
 The `dark` palette overrides the surface/text tokens; `gray*` and brand colors also shift to keep contrast. Read [the palette walkthrough](../guides/utilities.md) for usage patterns.
 
+## Brand colors: `registerPalette`
+
+A generated app ships a `src/database/themes.js` with its own `lightColors` and
+`darkColors` objects. Assigning onto `colors` from that file changes nothing:
+every widget reads the framework's live `colors`, and the next theme switch
+re-applies a registered palette over whatever you wrote there. The call that
+reaches the page is `registerPalette`:
+
+```javascript
+import { registerPalette } from "flet-box";
+import { lightColors, darkColors } from "./database/themes.js";
+
+registerPalette("light", lightColors);
+registerPalette("dark", darkColors);
+```
+
+What it does:
+
+- **Merges**, it does not replace. Tokens you leave out keep the framework's
+  value, so a palette that only carries `primary` and `surface` stays legal.
+- **Repaints when that palette is on screen.** If the name matches the active
+  theme the tokens are applied, the `--color-*` custom properties are rewritten,
+  and theme subscribers are notified. Registering the other theme only stores it
+  for the next `setTheme`.
+- **Never writes the theme preference.** Supplying your brand is not the user
+  choosing light or dark; that is the one difference from `setTheme`.
+- **A token the framework has never heard of is added to `colors`**, so
+  `colors.brandSand` resolves in your own code. Widgets will still not use it —
+  they read the tokens they know — and because the built-in palettes do not
+  carry it, a custom key keeps its registered value across a theme switch unless
+  you register it in both palettes.
+
+Run it once, at startup, before the first screen renders. The generated app does
+it at the bottom of `src/database/themes.js` — the same file that declares
+`lightColors` and `darkColors` — so a project that edits its brand colors is
+already correct without touching `src/app.js`.
+
 ## Examples
 
 ### Everyday example
@@ -83,6 +122,7 @@ runApp(ThemeProvider({ children: ThemedApp() }), "root");
 ## Notes
 
 - The shared palette tokens are updated across all widgets when you switch themes; widgets referencing `colors.*` at build time pick up the active palette.
+- `colors.glass` is genuinely see-through: its contrast depends on whatever is behind it, so use it over photography or gradients with a scrim, and keep body copy off the most colourful part of the backdrop. The dark token is a dark pane, not white glass.
 - `watchSystemTheme()` and `applySystemTheme()` read `prefers-color-scheme`; both return/need cleanup to release listeners.
 - `subscribeTheme(callback)` fires with the new palette object — remember to unsubscribe when a feature is destroyed.
 

package/docs/widget/Accordion.md

@@ -58,10 +58,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/AdMob.md

@@ -31,7 +31,7 @@ const banner = AdMob({
 | `margin` | `number` | Space outside the widget, between it and its neighbors. |
 | `interstitialId` | `string` | AdMob interstitial ad unit id. |
 | `rewardedId` | `string` | AdMob rewarded ad unit id. |
-| `autoShow` | `boolean` | Shows the ad automatically when it is ready. |
+| `autoShow` | `boolean` | Shows the banner automatically on mount. false silences only the mount; show() still asks for the ad. |
 | `autoInitialize` | `boolean` | The `autoInitialize` value for the widget. |
 | `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. |
@@ -57,10 +57,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/AdSense.md

@@ -51,10 +51,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/AnimatedBox.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. |
@@ -95,9 +99,9 @@ const toast = AnimatedBox({
 ## Tips
 
 - Each animation is { effect, from, to } where effect is a CSS property like opacity,
-- scale, translateY, or backgroundColor.
-- Set timing (ease, ease-out, linear) and delay at the widget level; per-step reverse
-- cycles the animation back instead of running it once.
+- scale, translateY, or backgroundColor. It runs once and holds `to` at the end.
+- Set timing (ease, ease-out, linear) and delay at the widget level; add reverse: true
+- to cycle back to `from`, together with loop: true for a breathing pulse.
 - top, right, bottom, and left are forwarded to the child as positioning hints for
 - layout systems.
 

package/docs/widget/AnimatedText.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/Audio.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. |
@@ -132,4 +136,4 @@ const track = Audio({
 - **Next:** [Video](Video.md)
 - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
 
-You are reading **Chapter 7 · Media and drag & drop** (1 of 4).
+You are reading **Chapter 7 · Media and drag & drop** (1 of 5).

package/docs/widget/Avatar.md

@@ -1,6 +1,6 @@
 # Avatar
 
-A compact identity chip that shows a profile image, the person's initials, or a fallback icon. It falls back gracefully when no image is available.
+A compact identity chip that shows a profile image, the person's initials, or a fallback icon. It falls back gracefully when no image is available and can carry a presence dot.
 
 ## When to use it
 
@@ -29,6 +29,8 @@ const user = Avatar({
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
 | `textColor` | `Color` | Color of the button label. |
 | `shape` | `'circle' \| 'rounded' \| 'square'` | The `shape` value for the widget. |
+| `online` | `boolean` | Shows a presence dot in the corner of the avatar. |
+| `badgeColor` | `Color` | Color of the presence dot. |
 | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
 
 ### Common props
@@ -43,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. |
@@ -69,6 +75,7 @@ const user = Avatar({
   name: "Ada Lovelace",
   size: 48,
   shape: "circle",
+  online: true,
 });
 ```
 
@@ -84,14 +91,17 @@ const user = Avatar({
   shape: "rounded",
   bgColor: "#2563eb",
   textColor: "#ffffff",
+  online: true,
+  badgeColor: "#f59e0b",
   onPress: () => console.log("open profile"),
 });
 ```
 
 ## Tips
 
-- Provide both src and name so initials render if the image fails.
+- Provide both src and name so the initials are ready if you swap the image out.
 - Use shape: "circle" for people and shape: "rounded" for organizations or bots.
+- Leave badgeColor at its default for an available dot; pass another color to signal away or busy.
 
 ## Accessibility
 
@@ -99,8 +109,10 @@ const user = Avatar({
 
 ## Behavior
 
-- When src is missing or errors, the widget automatically shows initials from name.
+- Content is picked once, in order: src, then icon, then initials from name, then a generic person icon. A failing src does not swap the image for initials by itself.
 - onPress makes the whole avatar interactive, which is useful for opening profiles.
+- online draws a dot in the bottom-right corner. It sits inside the edge and is sized from the avatar, so a circular avatar clips it no more than a square one.
+- Every own prop applies again through update() or updateContent(), so an avatar bound to a state key changes without rebuilding the element.
 
 ## Related widgets
 

package/docs/widget/Badge.md

@@ -47,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. |

package/docs/widget/Button.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/COMMON_PROPS.md

@@ -74,6 +74,37 @@ These expand to two sides at once (numeric values are pixels):
 `flexBasis`, `gap`, `boxSizing`, `overflow`, `overflowX`, `overflowY`,
 `position` (`pos`), `top`, `right`, `bottom`, `left`, `inset`, `zIndex` (`z`).
 
+### Stack positioning
+
+`position: 'stack'` takes the widget out of normal flow and pins it to its
+nearest positioned ancestor. The placement shorthands below apply **only** in
+that mode; the plain offsets still work with any CSS `position` value.
+
+| Prop | Effect |
+| --- | --- |
+| `top` / `right` / `bottom` / `left` | Edge offsets. A number is pixels on the 16px base, written as rem. |
+| `start` / `end` | `left` / `right` under the logical names. |
+| `centerX` / `centerY` | Centre on one axis. |
+| `center` | Centre on both axes. |
+| `fullWidth` / `fullHeight` | Stretch to the parent's width / height. |
+| `full` | Stretch on both axes. |
+
+```js
+Stack({
+  width: "100%",
+  height: 320,
+  children: [
+    Image({ src: "cover.jpg", position: "stack", full: true, fit: "cover" }),
+    Text({ text: "Centred", position: "stack", center: true }),
+  ],
+});
+```
+
+A `false` shorthand means "do not apply", so `full: false` leaves the widget at
+its natural size. [`Button`](Button.md), [`Input`](Input.md) and
+[`Tabs`](Tabs.md) also read `fullWidth` as a plain layout prop, independent of
+`position`.
+
 ## Size and spacing
 
 `width` (`w`), `height` (`h`), `minWidth`/`maxWidth`, `minHeight`/`maxHeight`,
@@ -107,6 +138,27 @@ shorthands `roundedTop`, `roundedBottom`, `roundedLeft`, `roundedRight`, plus
 `transition`, `animation`, `transform`, `cursor`, `visibility`, `pointerEvents`,
 `userSelect`, `touchAction`.
 
+## Glass and filters
+
+`backdropFilter`, `filter`, `maskImage`. Each takes a raw CSS value string, not an
+object.
+
+```js
+Card({
+  bgColor: colors.glass,
+  borderColor: colors.glassBorder,
+  borderWidth: 1,
+  backdropFilter: 'blur(14px) saturate(160%)',
+});
+```
+
+> A translucent `bgColor` alone is only see-through. `backdropFilter` blurs what is
+> behind the widget, which is what makes the card read as frosted glass.
+> `backdropFilter` and `maskImage` also write their `-webkit-` twin, so the effect
+> reaches Safari and the `WKWebView` inside a wrapped iOS app.
+> `filter` affects the widget's own pixels; `backdropFilter` affects only the
+> backdrop, so the widget's text stays sharp.
+
 ## Text content
 
 These set the element's text: `text`, `label`, `title`, `caption`, `description`,

package/docs/widget/Card.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/Carousel.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/Chart.md

@@ -60,10 +60,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/Checkbox.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/Chip.md

@@ -47,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. |

package/docs/widget/CircularBar.md

@@ -72,10 +72,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/CircularChart.md

@@ -67,10 +67,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/CodeViewer.md

@@ -47,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. |

package/docs/widget/Column.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. |

package/docs/widget/Container.md

@@ -51,10 +51,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/DataTable.md

@@ -55,10 +55,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/Divider.md

@@ -37,10 +37,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/DraggBox.md

@@ -46,10 +46,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. |
@@ -122,8 +126,8 @@ const task = DraggBox({
 
 ## Continue reading
 
-- **Previous:** [Video](Video.md)
+- **Previous:** [Maps](Maps.md)
 - **Next:** [DroppBox](DroppBox.md)
 - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
 
-You are reading **Chapter 7 · Media and drag & drop** (3 of 4).
+You are reading **Chapter 7 · Media and drag & drop** (4 of 5).