flet-box 1.1.1 → 1.1.3

package/docs/widget/QRCode.md

@@ -35,11 +35,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. |
@@ -49,11 +102,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/README.md

@@ -25,7 +25,7 @@ _layout and the core mental model_
 2. [Container](Container.md) — General-purpose surface box
 3. [Row](Row.md) — Horizontal flex layout that places its children side by side
 4. [Column](Column.md) — Vertical flex layout that stacks its children one below another
-5. [Stack](Stack.md) — Overlay container that lets children occupy the same box
+5. [Stack](Stack.md) — Overlay container: every child after the first paints in the same box, anchored by a nine-point `alignment` or by its own edges.
 6. [Icon](Icon.md) — Material icon glyph rendered as a span
 7. [Image](Image.md) — Renders an image element from a URL or path
 
@@ -41,85 +41,87 @@ _the widgets users click and type into_
 13. [Slider](Slider.md) — A draggable range input that selects a numeric value along a track between min and max.
 14. [Dropdown](Dropdown.md) — A select control that shows the current choice and opens a menu of options when clicked.
 15. [Rating](Rating.md) — A row of star icons that captures or displays a score up to max
+16. [ThemePicker](ThemePicker.md) — A row of two-tone squares, one per accent family, that picks the color the screen paints its buttons, icons and plates with.
 
 ### Chapter 3 · Layout, cards and lists
 
 _cards, lists, grids and content rows_
 
-16. [Card](Card.md) — A rounded, optionally elevated surface that groups related content into a single tappable unit.
-17. [Divider](Divider.md) — A thin horizontal or vertical line that separates sections of content
-18. [ListTile](ListTile.md) — A single row with leading, title, subtitle, and trailing slots
-19. [ListView](ListView.md) — Virtualized scrollable list that keeps only the visible rows plus a buffer in the DOM, so large datasets stay responsive.
-20. [GridView](GridView.md) — Grid layout built on ListView's virtualization
-21. [Avatar](Avatar.md) — A compact identity chip that shows a profile image, the person's initials, or a fallback icon
-22. [Badge](Badge.md) — Wraps a child widget and overlays a small count or status marker at one of its corners
-23. [Chip](Chip.md) — A compact, pill-shaped label for tags, filters, and selections
+17. [Card](Card.md) — A rounded, optionally elevated surface that groups related content into a single tappable unit.
+18. [Divider](Divider.md) — A thin horizontal or vertical line that separates sections of content
+19. [ListTile](ListTile.md) — A single row with leading, title, subtitle, and trailing slots
+20. [ListView](ListView.md) — Virtualized scrollable list that keeps only the visible rows plus a buffer in the DOM, so large datasets stay responsive.
+21. [GridView](GridView.md) — Grid layout built on ListView's virtualization
+22. [Avatar](Avatar.md) — A compact identity chip that shows a profile image, the person's initials, or a fallback icon
+23. [Badge](Badge.md) — Wraps a child widget and overlays a small count or status marker at one of its corners
+24. [Chip](Chip.md) — A compact, pill-shaped label for tags, filters, and selections
 
 ### Chapter 4 · Feedback and overlays
 
 _dialogs, sheets, notifications and progress_
 
-24. [AlertDialog](AlertDialog.md) — A pre-styled confirmation dialog built on Modal, with a variant icon, message and confirm/cancel buttons.
-25. [Modal](Modal.md) — A centered dialog over a dimmed overlay that holds a title, content and a row of actions.
-26. [BottomSheet](BottomSheet.md) — A panel that slides up from the bottom of the screen over a dimmed overlay.
-27. [SnackBar](SnackBar.md) — A transient toast that appears at the edge of the screen, reports a short message, and dismisses itself.
-28. [Tooltip](Tooltip.md) — Wraps a child widget and shows a labeled overlay bubble on hover or focus
-29. [ProgressBar](ProgressBar.md) — A horizontal bar that visualizes completion from zero to max
-30. [CircularBar](CircularBar.md) — A circular or radial progress indicator drawn on canvas
-31. [Skeleton](Skeleton.md) — Renders animated placeholder blocks that stand in for content while it loads
-32. [FloatingActionButton](FloatingActionButton.md) — A circular, elevated button that floats over content and can expand into a labeled pill.
-33. [Pagination](Pagination.md) — Renders page controls derived from totalItems and pageSize, with optional first/last and prev/next buttons
+25. [AlertDialog](AlertDialog.md) — A pre-styled confirmation dialog built on Modal, with a variant icon, message and confirm/cancel buttons.
+26. [Modal](Modal.md) — A centered dialog over a dimmed overlay that holds a title, content and a row of actions.
+27. [BottomSheet](BottomSheet.md) — A panel that slides up from the bottom of the screen over a dimmed overlay.
+28. [SnackBar](SnackBar.md) — A transient toast that appears at the edge of the screen, reports a short message, and dismisses itself.
+29. [Tooltip](Tooltip.md) — Wraps a child widget and shows a labeled overlay bubble on hover or focus
+30. [Menu](Menu.md) — A trigger button that opens an anchored menu of actions
+31. [ProgressBar](ProgressBar.md) — A horizontal bar that visualizes completion from zero to max
+32. [CircularBar](CircularBar.md) — A circular or radial progress indicator drawn on canvas
+33. [Skeleton](Skeleton.md) — Renders animated placeholder blocks that stand in for content while it loads
+34. [FloatingActionButton](FloatingActionButton.md) — A circular, elevated button that floats over content and can expand into a labeled pill.
+35. [Pagination](Pagination.md) — Renders page controls derived from totalItems and pageSize, with optional first/last and prev/next buttons
 
 ### Chapter 5 · Navigation and flows
 
 _multi-step flows, trees and rotating content_
 
-34. [Stepper](Stepper.md) — A multi-step progress indicator that shows each step as a circle, number or icon and reveals the active step's content.
-35. [Accordion](Accordion.md) — A collapsible panel that hides a title bar with expandable content beneath it
-36. [TreeView](TreeView.md) — Renders a collapsible hierarchy from nodes, each with an id, label, optional icon, badge and children
-37. [Carousel](Carousel.md) — Cycles through items one at a time with optional arrows, dots and autoplay
-38. [InstallButton](InstallButton.md) — A floating button that appears only when the browser is ready to install the app as a PWA
+36. [Stepper](Stepper.md) — A multi-step progress indicator that shows each step as a circle, number or icon and reveals the active step's content.
+37. [Accordion](Accordion.md) — A collapsible panel that hides a title bar with expandable content beneath it
+38. [TreeView](TreeView.md) — Renders a collapsible hierarchy from nodes, each with an id, label, optional icon, badge and children
+39. [Carousel](Carousel.md) — Cycles through items one at a time with optional arrows, dots and autoplay
+40. [InstallButton](InstallButton.md) — A floating button that appears only when the browser is ready to install the app as a PWA
 
 ### Chapter 6 · Data, rich content & effects
 
 _tables, charts, rich text, ads and motion_
 
-39. [DataTable](DataTable.md) — Renders tabular rows using a columns definition, with optional striping, hover and borders
-40. [Chart](Chart.md) — Draws bar, line, area or candlestick data onto a canvas, with optional labels, grid and value annotations
-41. [CircularChart](CircularChart.md) — A pie or donut chart drawn on canvas with per-slice value, label, and color
-42. [Markdown](Markdown.md) — Renders markdown source as styled HTML with scoped CSS, syntax-highlighted code blocks, copy buttons, tables, and blockquotes inside a scrollable surface.
-43. [CodeViewer](CodeViewer.md) — Shows a read-only code block with an optional header, line numbers and scrolling for long files
-44. [QRCode](QRCode.md) — Renders a scannable QR image for a string value
-45. [Inspector](Inspector.md) — Renders a read-only tree that drills into a widget's props, children and element structure
-46. [AdSense](AdSense.md) — Google AdSense display unit for the web
-47. [AdMob](AdMob.md) — Google AdMob banner and full-screen ads for native Capacitor builds
-48. [AnimatedBox](AnimatedBox.md) — Wraps a single child and plays a sequence of CSS animations described by effect/from/to steps
-49. [AnimatedText](AnimatedText.md) — Splits a Text widget into individual characters and animates each one, optionally staggering the start of every letter for a cascade effect.
-50. [MatrixRain](MatrixRain.md) — A canvas-based Matrix-style effect where random characters cascade down the screen
-51. [ParallaxBox](ParallaxBox.md) — A container that shifts its child in response to scroll, mouse position, or hover entry
+41. [DataTable](DataTable.md) — Renders tabular rows using a columns definition, with optional striping, hover and borders
+42. [Chart](Chart.md) — Draws bar, line, area or candlestick data onto a canvas, with optional labels, grid and value annotations
+43. [CircularChart](CircularChart.md) — A pie or donut chart drawn on canvas with per-slice value, label, and color
+44. [Markdown](Markdown.md) — Renders markdown source as styled HTML with scoped CSS, syntax-highlighted code blocks, copy buttons, tables, and blockquotes inside a scrollable surface.
+45. [CodeViewer](CodeViewer.md) — Shows a read-only code block with an optional header, line numbers and scrolling for long files
+46. [QRCode](QRCode.md) — Renders a scannable QR image for a string value
+47. [Inspector](Inspector.md) — Renders a read-only tree that drills into a widget's props, children and element structure
+48. [AdSense](AdSense.md) — Google AdSense display unit for the web
+49. [AdMob](AdMob.md) — Google AdMob banner and full-screen ads for native Capacitor builds
+50. [AnimatedBox](AnimatedBox.md) — Wraps a single child and plays a sequence of CSS animations described by effect/from/to steps
+51. [AnimatedText](AnimatedText.md) — Splits a Text widget into individual characters and animates each one, optionally staggering the start of every letter for a cascade effect.
+52. [MatrixRain](MatrixRain.md) — A canvas-based Matrix-style effect where random characters cascade down the screen
+53. [ParallaxBox](ParallaxBox.md) — A container that shifts its child in response to scroll, mouse position, or hover entry
 
 ### Chapter 7 · Media and drag & drop
 
 _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. [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
+54. [Audio](Audio.md) — A thin wrapper around the native <audio> element with reliable duration detection, progress callbacks, and an imperative playback API
+55. [Video](Video.md) — Renders a native <video> element with proper media attributes and a convenient playback API
+56. [Maps](Maps.md) — An interactive map — pan, zoom, markers and polylines — with no map library behind it
+57. [DraggBox](DraggBox.md) — Wraps a child so it can be dragged with the native drag-and-drop API
+58. [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._
 
-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
+59. [Scaffold](Scaffold.md) — the app shell: app bar, body, drawer, side bars
+60. [AdaptiveScaffold](AdaptiveScaffold.md) — the same shell, adapted to phone and desktop
+61. [AppBar](AppBar.md) — a top bar for titles, actions, and back navigation
+62. [Drawer](Drawer.md) — a panel that slides in from the side
+63. [DrawerItem](DrawerItem.md) — a router-aware row for a drawer or side bar
+64. [BottomNavigation](BottomNavigation.md) — a bottom tab bar synced with the router
+65. [Tabs](Tabs.md) — switch panes inside a screen
+66. [CollapsibleSideBar](CollapsibleSideBar.md) — a side panel that collapses to icons
 
 Then continue with [State, Router & Services](../guides/state.md) — Chapter 9.
 
@@ -169,6 +171,7 @@ Then continue with [State, Router & Services](../guides/state.md) — Chapter 9.
 - [Maps](Maps.md)
 - [Markdown](Markdown.md)
 - [MatrixRain](MatrixRain.md)
+- [Menu](Menu.md)
 - [Modal](Modal.md)
 - [Pagination](Pagination.md)
 - [ParallaxBox](ParallaxBox.md)
@@ -186,6 +189,7 @@ Then continue with [State, Router & Services](../guides/state.md) — Chapter 9.
 - [Switch](Switch.md)
 - [Tabs](Tabs.md)
 - [Text](Text.md)
+- [ThemePicker](ThemePicker.md)
 - [Tooltip](Tooltip.md)
 - [TreeView](TreeView.md)
 - [Video](Video.md)

package/docs/widget/Radio.md

@@ -14,7 +14,7 @@ import { Radio } from "flet-box";
 const plan = Radio({
   label: "Monthly",
   name: "billing",
-  onSelect: (value) => console.log(value),
+  onPress: (value) => console.log(value),
 });
 ```
 
@@ -25,12 +25,13 @@ const plan = Radio({
 | Prop | Type | Description |
 | --- | --- | --- |
 | `selected` | `boolean` | Current selected state. |
-| `onSelect` | `(selected: boolean) => void` | Fired when the widget or an option is selected. |
+| `onSelect` | `(selected: boolean) => void` | Deprecated alias of `onPress`. |
+| `onPress` | `(selected: boolean) => void` | Called with the new selected state (`true` or `false`). |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
 | `size` | `number` | Overall size preset or pixel value, depending on the widget. |
 | `activeColor` | `Color` | Color used in the active state. |
 | `label` | `string` | Label or caption shown near the control. |
-| `name` | `string` | The `name` value for the widget. |
+| `name` | `string` | Value this option submits when it is the selected one. |
 
 ### Common props
 
@@ -38,11 +39,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. |
@@ -52,11 +106,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 selected 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. |
@@ -74,7 +140,7 @@ const monthly = Radio({
   name: "billing",
   selected: true,
   activeColor: "#2563eb",
-  onSelect: (value) => console.log("billing:", value),
+  onPress: (value) => console.log("billing:", value),
 });
 ```
 
@@ -90,7 +156,7 @@ const option = Radio({
   disabled: false,
   activeColor: "#16a34a",
   size: 24,
-  onSelect: (value) => {
+  onPress: (value) => {
     console.log("shipping changed:", value);
   },
 });
@@ -99,7 +165,7 @@ const option = Radio({
 ## Tips
 
 - Give Radios that answer the same question the same name; selecting one clears the others in that group.
-- Set selected for the initial choice and let onSelect write the change back into your own state.
+- Set selected for the initial choice and let onPress write the change back into your own state.
 
 ## Accessibility
 
@@ -107,7 +173,7 @@ const option = Radio({
 
 ## Behavior
 
-- Clicking an already-selected Radio is a no-op, so onSelect only fires when the selection actually changes.
+- Clicking an already-selected Radio is a no-op, so onPress only fires when the selection actually changes.
 - The returned element exposes select(), unselect() and isSelected() for programmatic control.
 
 ## Related widgets
@@ -124,4 +190,4 @@ const option = Radio({
 - **Next:** [Switch](Switch.md)
 - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
 
-You are reading **Chapter 2 · Interaction basics** (4 of 8).
+You are reading **Chapter 2 · Interaction basics** (4 of 9).

package/docs/widget/Rating.md

@@ -44,11 +44,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. |
@@ -58,11 +111,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. |
@@ -117,8 +182,7 @@ const rating = Rating({
 
 - onChange receives the numeric value each time the user picks a rating.
 - readOnly disables onChange while keeping the current value visible.
-- An unfilled star uses the palette's control grey and a filled one its readable
-- amber, so both states clear 3:1 against the surface they sit on.
+- An unfilled star uses the palette's control grey and a filled one its readable amber, so both states clear 3:1 against the surface they sit on.
 
 ## Related widgets
 
@@ -131,7 +195,7 @@ const rating = Rating({
 ## Continue reading
 
 - **Previous:** [Dropdown](Dropdown.md)
-- **Next:** [Card](Card.md)
+- **Next:** [ThemePicker](ThemePicker.md)
 - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
 
-You are reading **Chapter 2 · Interaction basics** (8 of 8).
+You are reading **Chapter 2 · Interaction basics** (8 of 9).