flet-box 1.1.2 → 1.1.3

package/docs/tools/theme.md

@@ -1,17 +1,31 @@
 # Themes
 
 ## Overview
-FletBox ships a built-in color system: `colors` is the palette of the current theme, `palettes` holds all named palettes, and the theme functions switch between light and dark, subscribe to changes, and follow the system preference. A `ThemeProvider` and the `useTheme()` hook wrap them for component-based apps.
+FletBox ships a built-in color system: `colors` is the palette of the current theme, `palettes` holds all named palettes, and the theme functions switch between light and dark, subscribe to changes, and follow the system preference. On top of that sit the accent presets — selectable hue families that paint `colors.primary`, its ink and its wash over whichever palette is active — and the theme functions carry them too. A `ThemeProvider` and the `useTheme()` hook wrap all of it for component-based apps.
 
 ## When to use
 - Style widgets with semantic tokens (`colors.surface`, `colors.primary`, `colors.error`) instead of hard-coded hex values.
 - Add a light/dark toggle that re-colors the whole app instantly.
 - Follow the OS dark/light setting automatically.
+- Let the reader pick the app's color — buttons, icons and plates and all — with [`ThemePicker`](../widget/ThemePicker.md) and `setAccent`.
 
 ## Import
 
 ```javascript
-import { colors, setTheme, registerPalette, toggleTheme, subscribeTheme, ThemeProvider } from "flet-box";
+import {
+  colors,
+  setTheme,
+  registerPalette,
+  toggleTheme,
+  subscribeTheme,
+  ThemeProvider,
+  registerAccent,
+  setAccent,
+  applyAccentPreference,
+  getAccent,
+  getAccentSurfaces,
+  listAccents,
+} from "flet-box";
 ```
 
 ## Functions
@@ -20,6 +34,13 @@ import { colors, setTheme, registerPalette, toggleTheme, subscribeTheme, ThemePr
 | --- | --- | --- | --- |
 | `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. |
+| `registerAccent` | `registerAccent({ id, label?, light, dark })` | `Accent \| null` | Add or replace one selectable accent. Each end of the pair is a hex or a five-stop ramp; `null` means the argument was unusable. |
+| `setAccent` | `setAccent(id \| null, { surfaces? })` | `Record<string, string>` | Lay an accent over the live palette and store the choice. `surfaces: true` paints the page and its panels from the same ramp. `null`, or an id nothing registered, takes it back off. |
+| `applyAccentPreference` | `applyAccentPreference(id, { surfaces? })` | `string \| null` | Paint the app's own brand at boot, and only when the reader has never picked one. Never stores anything. |
+| `getAccent` | `getAccent()` | `string \| null` | The accent id on screen, or `null` while the palette's own `primary` shows. |
+| `getAccentSurfaces` | `getAccentSurfaces()` | `boolean` | Whether the live accent also paints the surfaces, or only the brand. |
+| `listAccents` | `listAccents()` | `Accent[]` | Every selectable family, in registration order — `{ id, label, light, dark }`. |
+| `listAccentRamps` | `listAccentRamps()` | `Array` | The same families with all five stops of each theme beside them, for a swatch that shows the whole ramp. |
 | `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). |
@@ -27,7 +48,7 @@ import { colors, setTheme, registerPalette, toggleTheme, subscribeTheme, ThemePr
 | `applySystemTheme` | `applySystemTheme()` | `string` | Apply light/dark from the OS preference. |
 | `watchSystemTheme` | `watchSystemTheme()` | `() => void` | Follow the OS preference live; returns an unsubscribe function. |
 | `ThemeProvider` | `ThemeProvider({ children, theme? })` | `Widget` | Provide a theme (defaults to system) for a subtree. |
-| `useTheme` | `useTheme()` | object | `{ colors, setTheme, getTheme, toggleTheme, getColor, applySystemTheme }`. |
+| `useTheme` | `useTheme()` | object | `{ colors, setTheme, getTheme, toggleTheme, getColor, applySystemTheme, setAccent, getAccent, listAccents }`. |
 
 Plus the constants: `colors` (current palette) and `palettes` (all named palettes, keyed by name).
 
@@ -36,9 +57,10 @@ Plus the constants: `colors` (current palette) and `palettes` (all named palette
 Every token is available on `colors`:
 
 - **Brand:** `primary`, `secondary`, `info`, `success`, `warning`, `danger`, `error`.
+- **On a fill:** `onPrimary` — the ink the theme puts on a `primary` plate. Ask the theme for it; a literal `#ffffff` is a bug the moment the reader picks a pale accent.
 - **Surfaces:** `background`, `surface`, `card`, `overlay`.
 - **Text:** `text`, `textSecondary`, `textDisabled`, `divider`, `border`, `shadow`.
-- **Tints:** `gray50` … `gray900`, plus the soft backgrounds `errorBg`, `successBg`, `warningBg`, `infoBg`.
+- **Tints:** `gray50` … `gray900`, plus the soft backgrounds `primaryBg`, `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.
@@ -80,6 +102,118 @@ 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`.
 
+## Accent presets: `setAccent`
+
+`registerPalette` says what a theme is. An **accent** is what the reader picks
+inside it: one hue family painted over the palette's `primary`, its ink and its
+wash, so every button, icon and selected plate on the screen moves together.
+Twelve families ship (`listAccents()`), and each is a *pair* — the stop that hue
+wears on a light page and the stop it wears on a dark one — which is why a
+[`ThemePicker`](../widget/ThemePicker.md) swatch is split down the middle.
+Worn with `surfaces: true`, the same family paints the page and its panels too,
+and the picker is choosing a **theme** rather than a brand color; see
+[Worn as a theme](#worn-as-a-theme) below.
+
+```javascript
+import { ThemePicker, applyAccentPreference, listAccents } from "flet-box";
+
+// At boot: the app's own brand, and only if the reader has never chosen.
+applyAccentPreference("teal");
+
+// In a settings sheet: the reader's choice, which paints and persists.
+ThemePicker({
+  accents: listAccents().filter((a) => ["teal", "blue", "rose", "orange"].includes(a.id)),
+  size: 48,
+  onChange: (id) => console.log("accent:", id),
+});
+```
+
+What it does:
+
+- **It is a layer, not a second palette.** The one repaint funnel lays the
+  accent's `primary`, `onPrimary` and `primaryBg` over the theme's own tokens, so
+  a toggle, an OS flip or a `setTheme` from anywhere keeps the choice instead of
+  writing the brand back over it. The `--color-*` properties and the PWA status
+  bar move with it because they read the same tokens. Worn with `surfaces: true`
+  the same funnel lays five more tokens down — `background`, `surface`, `card`,
+  `border`, `divider` — and nothing else changes hands.
+- **`setAccent` is the reader's verb, `applyAccentPreference` is the app's.** The
+  first stores `"fletbox-accent"`, so the picker opens on the answer the reader
+  gave; the second paints without storing, so it is a default the reader can
+  overrule and never a choice written into their name. An unknown id changes
+  nothing, and `setAccent(null)` gives the palette its own brand back.
+- **A created app opens on `neutral`.** `flet-box create` writes
+  `applyAccentPreference("neutral")` at the bottom of `src/database/themes.js`,
+  beside the `registerPalette` calls that carry the same three values, so a new
+  project reads as paper and type rather than as somebody else's brand: the
+  accent is the page's own ink, near-black on a light page and near-white on a
+  dark one. The first thing a designer changes is that id — and the Preferences
+  screen already ships a `ThemePicker`, so a reader can change it without them.
+- **A family is measured before it ships.** Each pair clears the numbers a
+  hand-built palette has to as well: white or near-black words on the accent at
+  4.5:1, the accent as text on the page at 4.5:1 and as a glyph on a card at 3:1,
+  page ink, secondary ink and the accent itself on its wash at 4.5:1, and the
+  wash lifting off the background by 1.04 to 1.5. `#3b82f6` fails the first one —
+  white words measure 3.15:1 on it — which is why an accent is a stop on a ramp
+  and never the middle of one.
+- **A brand the list lacks is registered, not typed.**
+  `registerAccent` takes an `id`, a `label` and a `light`/`dark` pair: one hex
+  each, and the wash and `colors.onPrimary` are derived, or a five-stop ramp whose
+  stop 0 (light) and stop 1 (dark) are the ones painted. The call belongs in
+  `src/database/themes.js`, beside the palette it feeds.
+
+### Worn as a theme
+
+`setAccent(id, { surfaces: true })` is how an app lets the reader pick the color
+of the *page* and not only of its buttons. Five more tokens arrive off the same
+five stops the swatch paints, in the order a designer would build them by hand:
+
+| Token | Light, from the ramp | Dark, from the ramp |
+| --- | --- | --- |
+| `background` | `ramp[4]` — the palest stop | `ramp[3]` scaled to 10% |
+| `surface` | `ramp[3]` — the measured wash stop | `ramp[3]` scaled to 18% |
+| `card` | `#ffffff`, the way it lifts off `#fafafa` today | `ramp[3]` scaled to 28% |
+| `border`, `divider` | `ramp[3]` darkened 6% | `ramp[3]` scaled to 45% |
+
+Teal, measured: a light page `#f0fdfa` with `#ccfbf1` panels, white cards and
+`#c0ece3` hairlines; a dark page `#010c0b` with `#031514` panels, `#04211f`
+cards and `#073531` hairlines. `applyAccentPreference("teal", { surfaces: true })`
+boots an app in that theme for a reader who has never chosen.
+
+Three rules the derivation keeps, and every one of them is measured by
+`tests/regression.test.js` ("an accent worn as a theme keeps every ink on the
+surfaces it paints") for all twelve families in both themes:
+
+- **Only the surfaces move.** `text`, `textSecondary`, `textDisabled`, the brand
+  trio and every semantic signal — `success`, `danger`, their plates and alert
+  tints — answer the same values they had worn as a brand-only accent. The neutral
+  ink scale was measured against a near-white and a near-black page, and a tinted
+  stop of a saturated family sits within a few percent of both, so the text needs
+  re-measuring rather than re-deriving; and a tinted theme still has to be able to
+  say "this failed" in a hue that is not its own.
+- **Dark scales toward black, never toward white.** Multiplying a channel keeps the
+  hue exactly; mixing toward white washes it out, and `#042f2e` stops reading as
+  teal at all. The steps also have to be *visible*, and a WCAG ratio cannot see
+  them — near black, every pair compresses to about 1.0 — so the three dark depths
+  are separated in CIELAB `L*`: blue's land at 2.3, 4.5 and 8.6, which is the range
+  the shipped neutral dark palette already occupies (`#09090b` at 2.5, `#18181b` at
+  8.4).
+- **The plate keeps its own stop.** `primaryBg` still comes from the wash stop the
+  family was measured against, and on a light page that is now also the panel. A
+  selected row inside a panel is therefore the same color as its container, exactly
+  as it is in the neutral palette, where `#f4f4f5` sits on `#fafafa` at 1.05 — the
+  one place a tinted theme buys its tint by spending a layer.
+
+An accent registered as a bare pair of hexes has no lightness to walk, so it paints
+brand only: `{ surfaces: true }` is accepted and ignored, and the surfaces keep the
+palette's own values.
+
+The choice rides in one stored string — `"teal"` for a brand, `"teal+surfaces"`
+for a theme — which is why `getAccent()` and `getAccentSurfaces()` answer together.
+A bare id is what every app wrote before surfaces existed, so it still parses; and
+a picker needs both answers, because the family already on screen means two
+different things and moving between them is a repaint, not a no-op.
+
 ## Examples
 
 ### Everyday example
@@ -131,6 +265,7 @@ runApp(ThemeProvider({ children: ThemedApp() }), "root");
 - [Device & environment](device.md) — previous chapter.
 - [Markdown, code & HTML](markdown.md) — next chapter.
 - [Colors and utilities guide](../guides/utilities.md) — palette walkthrough.
+- [ThemePicker](../widget/ThemePicker.md) — the swatch grid that calls `setAccent`.
 
 ---
 

package/docs/widget/Accordion.md

@@ -26,12 +26,14 @@ const faq = Accordion({
 | `title` | `string \| Widget` | Title text shown in the header. |
 | `children` | `Widget` | An array of child widgets. Alias: `child` for a single child. |
 | `expanded` | `boolean` | The `expanded` value for the widget. |
-| `onToggle` | `(expanded: boolean) => void` | Fired with the new toggled state. |
+| `onToggle` | `(expanded: boolean) => void` | Deprecated alias of `onPress`. |
+| `onPress` | `(expanded: boolean) => void` | Called with the new expanded state (`true` or `false`). |
 | `variant` | `'contained' \| 'outlined' \| 'ghost'` | Visual variation or style preset. |
 | `borderRadius` | `number` | Rounds the corners of the widget. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
 | `expandedColor` | `Color` | Color used for the expanded. |
 | `titleColor` | `Color` | Color used for the title. |
+| `dividerColor` | `Color` | Color used for the divider. |
 | `titleSize` | `number` | Size of the title. |
 | `titleWeight` | `string` | The `titleWeight` value for the widget. |
 | `titlePadding` | `string` | Padding for the title. |
@@ -52,11 +54,64 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 
 | Prop | Type | Description |
 | --- | --- | --- |
+| `full` | `boolean` | Stretches the widget to fill its parent on both axes in stack mode. |
+| `fullHeight` | `boolean` | Stretches the widget to the full height of its parent in stack mode. |
+| `fullWidth` | `boolean` | Stretches the widget to the full width of its parent. |
+| `center` | `boolean` | Centres the widget on both axes in stack mode. |
+| `centerY` | `boolean` | Centres the widget vertically in stack mode. |
+| `centerX` | `boolean` | Centres the widget horizontally in stack mode. |
+| `zIndex` | `number` | Stacking order: a widget with a higher value paints above lower ones. |
+| `z` | `number` | Alias of `zIndex`. |
+| `end` | `Size` | Logical alias of `right`, used by the stack placement shorthands. |
+| `start` | `Size` | Logical alias of `left`, used by the stack placement shorthands. |
+| `inset` | `Size` | Shorthand for the four edge offsets (`top`/`right`/`bottom`/`left`). |
+| `left` | `Size` | Offset from the left edge. A number is pixels; a string uses any CSS unit. |
+| `bottom` | `Size` | Offset from the bottom edge. A number is pixels; a string uses any CSS unit. |
+| `right` | `Size` | Offset from the right edge. A number is pixels; a string uses any CSS unit. |
+| `top` | `Size` | Offset from the top edge. A number is pixels; a string uses any CSS unit. |
+| `pos` | `'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky' \| 'stack'` | Alias of `position`. |
+| `position` | `'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky' \| 'stack'` | CSS `position` value, or `stack` for centered stacking. |
 | `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. |
+| `flex` | `number` | Flex grow/shrink/basis shorthand for a flex child. |
+| `minWidth` | `Size` | Minimum width the widget may shrink to. |
+| `maxWidth` | `Size` | Maximum width the widget may grow to. |
+| `minHeight` | `Size` | Minimum height the widget may shrink to. |
+| `maxHeight` | `Size` | Maximum height the widget may grow to. |
+| `border` | `string` | CSS `border` shorthand for all four edges: width, style and color in one string. |
+| `borderTop` | `string` | The top edge of the border alone, for a widget whose rim differs per side. |
+| `borderBottom` | `string` | The bottom edge of the border alone, for a widget whose rim differs per side. |
+| `borderLeft` | `string` | The left edge of the border alone, for a widget whose rim differs per side. |
+| `borderRight` | `string` | The right edge of the border alone, for a widget whose rim differs per side. |
+| `cursor` | `string` | CSS `cursor` value: what the pointer becomes over the widget (`pointer`, `grab`, `not-allowed`). |
+| `display` | `string` | CSS `display` value for the container. |
+| `boxSizing` | `'border-box' \| 'content-box'` | Which box `width` and `height` measure: `border-box` keeps the size you asked for and pushes padding inward. |
+| `flexDirection` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | Main axis of a flex container: `row` places children side by side, `column` stacks them. |
+| `flexGrow` | `number` | Share of the leftover space this child takes, relative to its siblings. |
+| `flexShrink` | `number` | How readily the child gives space back when the row overflows; `0` keeps its size. |
+| `gap` | `number \| string` | Space between children along the layout axis. |
+| `fontSize` | `number` | Size of the font. |
+| `borderColor` | `Color` | Color used for the border. |
+| `borderWidth` | `number` | Width of the border. |
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `paddingTop` | `Size` | Space inside the widget, on the top edge only. |
+| `paddingRight` | `Size` | Space inside the widget, on the right edge only. |
+| `paddingBottom` | `Size` | Space inside the widget, on the bottom edge only. |
+| `paddingLeft` | `Size` | Space inside the widget, on the left edge only. |
+| `pt` | `Size` | Alias of `paddingTop`. |
+| `pr` | `Size` | Alias of `paddingRight`. |
+| `pb` | `Size` | Alias of `paddingBottom`. |
+| `pl` | `Size` | Alias of `paddingLeft`. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `marginTop` | `Size` | Space outside the widget, on the top edge only. |
+| `marginRight` | `Size` | Space outside the widget, on the right edge only. |
+| `marginBottom` | `Size` | Space outside the widget, on the bottom edge only. |
+| `marginLeft` | `Size` | Space outside the widget, on the left edge only. |
+| `mt` | `Size` | Alias of `marginTop`. |
+| `mr` | `Size` | Alias of `marginRight`. |
+| `mb` | `Size` | Alias of `marginBottom`. |
+| `ml` | `Size` | Alias of `marginLeft`. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
 | `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
@@ -66,11 +121,23 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `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. |
+| `bgImage` | `string` | Image painted behind the widget's content (CSS `background-image`), placed with `bgSize` and `bgPosition`. |
+| `bgSize` | `string` | How the background image fills its box (`cover`, `contain`, or a length). |
+| `bgPosition` | `string` | Where the background image is anchored (`center`, `top`, `50% 20%`). |
+| `bgRepeat` | `string` | Whether the background image tiles; `no-repeat` for a single cover. |
 | `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`. |
+| `onPress` | `(event?: Event) => void` | Called with the new expanded state (`true` or `false`). |
+| `onClick` | `(event?: Event) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `onclick` | `(event?: Event) => void` | Lowercase alias of `onClick`, kept because the shipped templates and the HTML habit write it. |
+| `alignSelf` | `AlignSelf` | Overrides the parent's `alignItems` for this child alone (CSS `align-self`). Alias: `selfAlign`. |
+| `selfAlign` | `AlignSelf` | Alias of `alignSelf`. |
+| `overflow` | `'auto' \| 'hidden' \| 'visible' \| 'scroll' \| 'clip'` | How overflowing content is handled (`hidden`, `auto`, `scroll`). |
+| `overflowX` | `'auto' \| 'hidden' \| 'visible' \| 'scroll' \| 'clip'` | The `overflowX` value for the widget. |
+| `overflowY` | `'auto' \| 'hidden' \| 'visible' \| 'scroll' \| 'clip'` | The `overflowY` value for the widget. |
+| `textOverflow` | `'clip' \| 'ellipsis' \| string` | The `textOverflow` value for the widget. |
+| `whiteSpace` | `'normal' \| 'nowrap' \| 'pre' \| 'pre-wrap' \| 'pre-line' \| string` | The `whiteSpace` value for the widget. |
 | `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. |
@@ -86,7 +153,7 @@ import { Accordion, Text } from "flet-box";
 const faq = Accordion({
   title: "Shipping options",
   expanded: false,
-  onToggle: (expanded) => console.log(expanded),
+  onPress: (expanded) => console.log(expanded),
   children: Text({ text: "Free shipping over $50." }),
 });
 ```
@@ -112,7 +179,7 @@ const faq = Accordion({
   divider: true,
   animate: true,
   animationDuration: 250,
-  onToggle: (expanded) => console.log(expanded),
+  onPress: (expanded) => console.log(expanded),
   children: Text({ text: "We accept cards, PayPal, and bank transfer." }),
 });
 ```
@@ -128,10 +195,9 @@ const faq = Accordion({
 
 ## Behavior
 
-- onToggle receives the new expanded boolean whenever the header is activated.
+- onPress receives the new expanded boolean whenever the header is activated.
 - disabled blocks toggling, and animate: false skips the open/close transition.
-- A shut panel still shows its edge: the header keeps the divider and the
-- 'contained' variant paints the raised plate, so it never reads as plain text.
+- A shut panel still shows its edge: the header keeps the divider and the 'contained' variant paints the raised plate, so it never reads as plain text.
 
 ## Related widgets
 

package/docs/widget/AdMob.md

@@ -26,7 +26,7 @@ const banner = AdMob({
 | --- | --- | --- |
 | `adId` | `string` | AdMob ad unit id. |
 | `isTesting` | `boolean` | Requests test ads instead of live ones. |
-| `position` | `'top' \| 'bottom'` | CSS `position` value, or `stack` for centered stacking. |
+| `position` | `'top' \| 'bottom'` | Pins the banner to the top or bottom of the viewport. |
 | `size` | `string` | Overall size preset or pixel value, depending on the widget. |
 | `margin` | `number` | Space outside the widget, between it and its neighbors. |
 | `interstitialId` | `string` | AdMob interstitial ad unit id. |
@@ -51,11 +51,64 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 
 | Prop | Type | Description |
 | --- | --- | --- |
+| `full` | `boolean` | Stretches the widget to fill its parent on both axes in stack mode. |
+| `fullHeight` | `boolean` | Stretches the widget to the full height of its parent in stack mode. |
+| `fullWidth` | `boolean` | Stretches the widget to the full width of its parent. |
+| `center` | `boolean` | Centres the widget on both axes in stack mode. |
+| `centerY` | `boolean` | Centres the widget vertically in stack mode. |
+| `centerX` | `boolean` | Centres the widget horizontally in stack mode. |
+| `zIndex` | `number` | Stacking order: a widget with a higher value paints above lower ones. |
+| `z` | `number` | Alias of `zIndex`. |
+| `end` | `Size` | Logical alias of `right`, used by the stack placement shorthands. |
+| `start` | `Size` | Logical alias of `left`, used by the stack placement shorthands. |
+| `inset` | `Size` | Shorthand for the four edge offsets (`top`/`right`/`bottom`/`left`). |
+| `left` | `Size` | Offset from the left edge. A number is pixels; a string uses any CSS unit. |
+| `bottom` | `Size` | Offset from the bottom edge. A number is pixels; a string uses any CSS unit. |
+| `right` | `Size` | Offset from the right edge. A number is pixels; a string uses any CSS unit. |
+| `top` | `Size` | Offset from the top edge. A number is pixels; a string uses any CSS unit. |
+| `pos` | `'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky' \| 'stack'` | Alias of `position`. |
+| `position` | `'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky' \| 'stack'` | Pins the banner to the top or bottom of the viewport. |
 | `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. |
+| `flex` | `number` | Flex grow/shrink/basis shorthand for a flex child. |
+| `minWidth` | `Size` | Minimum width the widget may shrink to. |
+| `maxWidth` | `Size` | Maximum width the widget may grow to. |
+| `minHeight` | `Size` | Minimum height the widget may shrink to. |
+| `maxHeight` | `Size` | Maximum height the widget may grow to. |
+| `border` | `string` | CSS `border` shorthand for all four edges: width, style and color in one string. |
+| `borderTop` | `string` | The top edge of the border alone, for a widget whose rim differs per side. |
+| `borderBottom` | `string` | The bottom edge of the border alone, for a widget whose rim differs per side. |
+| `borderLeft` | `string` | The left edge of the border alone, for a widget whose rim differs per side. |
+| `borderRight` | `string` | The right edge of the border alone, for a widget whose rim differs per side. |
+| `cursor` | `string` | CSS `cursor` value: what the pointer becomes over the widget (`pointer`, `grab`, `not-allowed`). |
+| `display` | `string` | CSS `display` value for the container. |
+| `boxSizing` | `'border-box' \| 'content-box'` | Which box `width` and `height` measure: `border-box` keeps the size you asked for and pushes padding inward. |
+| `flexDirection` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | Main axis of a flex container: `row` places children side by side, `column` stacks them. |
+| `flexGrow` | `number` | Share of the leftover space this child takes, relative to its siblings. |
+| `flexShrink` | `number` | How readily the child gives space back when the row overflows; `0` keeps its size. |
+| `gap` | `number \| string` | Space between children along the layout axis. |
+| `fontSize` | `number` | Size of the font. |
+| `borderColor` | `Color` | Color used for the border. |
+| `borderWidth` | `number` | Width of the border. |
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `paddingTop` | `Size` | Space inside the widget, on the top edge only. |
+| `paddingRight` | `Size` | Space inside the widget, on the right edge only. |
+| `paddingBottom` | `Size` | Space inside the widget, on the bottom edge only. |
+| `paddingLeft` | `Size` | Space inside the widget, on the left edge only. |
+| `pt` | `Size` | Alias of `paddingTop`. |
+| `pr` | `Size` | Alias of `paddingRight`. |
+| `pb` | `Size` | Alias of `paddingBottom`. |
+| `pl` | `Size` | Alias of `paddingLeft`. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `marginTop` | `Size` | Space outside the widget, on the top edge only. |
+| `marginRight` | `Size` | Space outside the widget, on the right edge only. |
+| `marginBottom` | `Size` | Space outside the widget, on the bottom edge only. |
+| `marginLeft` | `Size` | Space outside the widget, on the left edge only. |
+| `mt` | `Size` | Alias of `marginTop`. |
+| `mr` | `Size` | Alias of `marginRight`. |
+| `mb` | `Size` | Alias of `marginBottom`. |
+| `ml` | `Size` | Alias of `marginLeft`. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
 | `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
@@ -65,11 +118,23 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `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. |
+| `bgImage` | `string` | Image painted behind the widget's content (CSS `background-image`), placed with `bgSize` and `bgPosition`. |
+| `bgSize` | `string` | How the background image fills its box (`cover`, `contain`, or a length). |
+| `bgPosition` | `string` | Where the background image is anchored (`center`, `top`, `50% 20%`). |
+| `bgRepeat` | `string` | Whether the background image tiles; `no-repeat` for a single cover. |
 | `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`. |
+| `onPress` | `(event?: Event) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(event?: Event) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `onclick` | `(event?: Event) => void` | Lowercase alias of `onClick`, kept because the shipped templates and the HTML habit write it. |
+| `alignSelf` | `AlignSelf` | Overrides the parent's `alignItems` for this child alone (CSS `align-self`). Alias: `selfAlign`. |
+| `selfAlign` | `AlignSelf` | Alias of `alignSelf`. |
+| `overflow` | `'auto' \| 'hidden' \| 'visible' \| 'scroll' \| 'clip'` | How overflowing content is handled (`hidden`, `auto`, `scroll`). |
+| `overflowX` | `'auto' \| 'hidden' \| 'visible' \| 'scroll' \| 'clip'` | The `overflowX` value for the widget. |
+| `overflowY` | `'auto' \| 'hidden' \| 'visible' \| 'scroll' \| 'clip'` | The `overflowY` value for the widget. |
+| `textOverflow` | `'clip' \| 'ellipsis' \| string` | The `textOverflow` value for the widget. |
+| `whiteSpace` | `'normal' \| 'nowrap' \| 'pre' \| 'pre-wrap' \| 'pre-line' \| string` | The `whiteSpace` value for the widget. |
 | `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. |

package/docs/widget/AdSense.md

@@ -45,11 +45,64 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 
 | Prop | Type | Description |
 | --- | --- | --- |
+| `full` | `boolean` | Stretches the widget to fill its parent on both axes in stack mode. |
+| `fullHeight` | `boolean` | Stretches the widget to the full height of its parent in stack mode. |
+| `fullWidth` | `boolean` | Stretches the widget to the full width of its parent. |
+| `center` | `boolean` | Centres the widget on both axes in stack mode. |
+| `centerY` | `boolean` | Centres the widget vertically in stack mode. |
+| `centerX` | `boolean` | Centres the widget horizontally in stack mode. |
+| `zIndex` | `number` | Stacking order: a widget with a higher value paints above lower ones. |
+| `z` | `number` | Alias of `zIndex`. |
+| `end` | `Size` | Logical alias of `right`, used by the stack placement shorthands. |
+| `start` | `Size` | Logical alias of `left`, used by the stack placement shorthands. |
+| `inset` | `Size` | Shorthand for the four edge offsets (`top`/`right`/`bottom`/`left`). |
+| `left` | `Size` | Offset from the left edge. A number is pixels; a string uses any CSS unit. |
+| `bottom` | `Size` | Offset from the bottom edge. A number is pixels; a string uses any CSS unit. |
+| `right` | `Size` | Offset from the right edge. A number is pixels; a string uses any CSS unit. |
+| `top` | `Size` | Offset from the top edge. A number is pixels; a string uses any CSS unit. |
+| `pos` | `'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky' \| 'stack'` | Alias of `position`. |
+| `position` | `'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky' \| 'stack'` | CSS `position` value, or `stack` for centered stacking. |
 | `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. |
+| `flex` | `number` | Flex grow/shrink/basis shorthand for a flex child. |
+| `minWidth` | `Size` | Minimum width the widget may shrink to. |
+| `maxWidth` | `Size` | Maximum width the widget may grow to. |
+| `minHeight` | `Size` | Minimum height the widget may shrink to. |
+| `maxHeight` | `Size` | Maximum height the widget may grow to. |
+| `border` | `string` | CSS `border` shorthand for all four edges: width, style and color in one string. |
+| `borderTop` | `string` | The top edge of the border alone, for a widget whose rim differs per side. |
+| `borderBottom` | `string` | The bottom edge of the border alone, for a widget whose rim differs per side. |
+| `borderLeft` | `string` | The left edge of the border alone, for a widget whose rim differs per side. |
+| `borderRight` | `string` | The right edge of the border alone, for a widget whose rim differs per side. |
+| `cursor` | `string` | CSS `cursor` value: what the pointer becomes over the widget (`pointer`, `grab`, `not-allowed`). |
+| `display` | `string` | CSS `display` value for the container. |
+| `boxSizing` | `'border-box' \| 'content-box'` | Which box `width` and `height` measure: `border-box` keeps the size you asked for and pushes padding inward. |
+| `flexDirection` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | Main axis of a flex container: `row` places children side by side, `column` stacks them. |
+| `flexGrow` | `number` | Share of the leftover space this child takes, relative to its siblings. |
+| `flexShrink` | `number` | How readily the child gives space back when the row overflows; `0` keeps its size. |
+| `gap` | `number \| string` | Space between children along the layout axis. |
+| `fontSize` | `number` | Size of the font. |
+| `borderColor` | `Color` | Color used for the border. |
+| `borderWidth` | `number` | Width of the border. |
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `paddingTop` | `Size` | Space inside the widget, on the top edge only. |
+| `paddingRight` | `Size` | Space inside the widget, on the right edge only. |
+| `paddingBottom` | `Size` | Space inside the widget, on the bottom edge only. |
+| `paddingLeft` | `Size` | Space inside the widget, on the left edge only. |
+| `pt` | `Size` | Alias of `paddingTop`. |
+| `pr` | `Size` | Alias of `paddingRight`. |
+| `pb` | `Size` | Alias of `paddingBottom`. |
+| `pl` | `Size` | Alias of `paddingLeft`. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `marginTop` | `Size` | Space outside the widget, on the top edge only. |
+| `marginRight` | `Size` | Space outside the widget, on the right edge only. |
+| `marginBottom` | `Size` | Space outside the widget, on the bottom edge only. |
+| `marginLeft` | `Size` | Space outside the widget, on the left edge only. |
+| `mt` | `Size` | Alias of `marginTop`. |
+| `mr` | `Size` | Alias of `marginRight`. |
+| `mb` | `Size` | Alias of `marginBottom`. |
+| `ml` | `Size` | Alias of `marginLeft`. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
 | `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
@@ -59,11 +112,23 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `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. |
+| `bgImage` | `string` | Image painted behind the widget's content (CSS `background-image`), placed with `bgSize` and `bgPosition`. |
+| `bgSize` | `string` | How the background image fills its box (`cover`, `contain`, or a length). |
+| `bgPosition` | `string` | Where the background image is anchored (`center`, `top`, `50% 20%`). |
+| `bgRepeat` | `string` | Whether the background image tiles; `no-repeat` for a single cover. |
 | `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`. |
+| `onPress` | `(event?: Event) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(event?: Event) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `onclick` | `(event?: Event) => void` | Lowercase alias of `onClick`, kept because the shipped templates and the HTML habit write it. |
+| `alignSelf` | `AlignSelf` | Overrides the parent's `alignItems` for this child alone (CSS `align-self`). Alias: `selfAlign`. |
+| `selfAlign` | `AlignSelf` | Alias of `alignSelf`. |
+| `overflow` | `'auto' \| 'hidden' \| 'visible' \| 'scroll' \| 'clip'` | How overflowing content is handled (`hidden`, `auto`, `scroll`). |
+| `overflowX` | `'auto' \| 'hidden' \| 'visible' \| 'scroll' \| 'clip'` | The `overflowX` value for the widget. |
+| `overflowY` | `'auto' \| 'hidden' \| 'visible' \| 'scroll' \| 'clip'` | The `overflowY` value for the widget. |
+| `textOverflow` | `'clip' \| 'ellipsis' \| string` | The `textOverflow` value for the widget. |
+| `whiteSpace` | `'normal' \| 'nowrap' \| 'pre' \| 'pre-wrap' \| 'pre-line' \| string` | The `whiteSpace` value for the widget. |
 | `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. |

package/docs/widget/AlertDialog.md

@@ -100,4 +100,4 @@ const alert = AlertDialog({
 - **Next:** [Modal](Modal.md)
 - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
 
-You are reading **Chapter 4 · Feedback and overlays** (1 of 10).
+You are reading **Chapter 4 · Feedback and overlays** (1 of 11).