flet-box 1.0.4 → 1.0.6

package/docs/widget/QRCode.md

@@ -0,0 +1,117 @@
+# QRCode
+
+QRCode renders a scannable QR image for a string value. It lets you tune size, colors and the error-correction level.
+
+## When to use it
+
+Use it to share URLs, pairing codes or contact data that a phone camera can scan.
+
+## Quick start
+
+```javascript
+import { QRCode } from "flet-box";
+
+const qr = QRCode({
+  value: "https://fletbox.dev",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Current value controlled by the widget. |
+| `size` | `number` | Overall size preset or pixel value, depending on the widget. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `fgColor` | `Color` | Color used for the fg. |
+| `errorCorrection` | `'L' \| 'M' \| 'Q' \| 'H'` | The `errorCorrection` value for the widget. |
+| `margin` | `number` | Space outside the widget, between it and its neighbors. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `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. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { QRCode } from "flet-box";
+
+const qr = QRCode({
+  value: "https://fletbox.dev/download",
+  size: 220,
+  errorCorrection: "M",
+});
+```
+
+### Full
+
+```javascript
+import { QRCode } from "flet-box";
+
+const qr = QRCode({
+  value: "https://fletbox.dev/invite?team=core",
+  size: 320,
+  bgColor: "#ffffff",
+  fgColor: "#0f172a",
+  margin: 8,
+  errorCorrection: "H",
+});
+```
+
+## Tips
+
+- Keep size large enough to scan comfortably; very small codes fail on low-resolution cameras.
+- Raise errorCorrection to H when the code may be printed small, dirty or partially covered.
+- Keep fgColor dark and bgColor light for reliable contrast.
+
+## Accessibility
+
+- Also show the encoded value as text so users who cannot scan it can still read or type it.
+- Maintain strong foreground and background contrast for camera and screen legibility.
+
+## Behavior
+
+- The QR image re-encodes whenever value or errorCorrection changes.
+- margin adds a quiet-zone border around the code, which scanners expect.
+
+## Related widgets
+
+- [Image](Image.md)
+- [CodeViewer](CodeViewer.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [CodeViewer](CodeViewer.md)
+- **Next:** [Inspector](Inspector.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 6 · Data, rich content & effects** (6 of 13).

package/docs/widget/README.md

@@ -0,0 +1,188 @@
+# Widgets: the FletBox book
+
+This directory is a book. Read it in order to go from your first widget to complete, data-rich compositions. Every page links to the previous and next page, so you can follow it like a tutorial — or jump straight to a widget from the alphabetical index below.
+
+If you have never used FletBox, begin with [Start here](START_HERE.md), then follow the reading path.
+
+## How to read this book
+
+- Chapters go from **basic to advanced**. Read them top to bottom the first time.
+- Every widget page ends with a **Continue reading** block: previous page, next page, and a link back here.
+- Every widget also accepts the [common props](COMMON_PROPS.md) — layout, spacing, color, typography, borders, events and aliases.
+- Related widgets at the bottom of each page are clickable, so you can branch off whenever you are curious.
+
+Related guides: [Build your first FletBox app](../guides/app-templates.md) · [Routing with FletBox](../guides/router.md) · [FletBox CLI](../cli/README.md).
+
+## The reading path
+
+### Chapter 1 · First steps: the core mental model
+
+_layout and the core mental model_
+
+1. [Text](Text.md) — Renders a string as inline text or as a heading, with control over size, weight, color, alignment, and inline styles.
+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
+6. [Icon](Icon.md) — Material icon glyph rendered as a span
+7. [Image](Image.md) — Renders an image element from a URL or path
+
+### Chapter 2 · Interaction basics
+
+_the widgets users click and type into_
+
+8. [Button](Button.md) — Interactive button with filled, outlined, and text variants, size presets, optional icons, and press feedback.
+9. [Input](Input.md) — A text field that handles labels, placeholder text, input types, icons, validation, and change events in one widget.
+10. [Checkbox](Checkbox.md) — A square checkbox with a check mark that represents an independent true/false choice.
+11. [Radio](Radio.md) — A single-selection control that renders a circular radio button
+12. [Switch](Switch.md) — An iOS-style toggle switch with a sliding knob that represents an on/off state.
+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
+
+### 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
+
+### 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
+
+### 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
+
+### 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
+
+### 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. [DraggBox](DraggBox.md) — Wraps a child so it can be dragged with the native drag-and-drop API
+55. [DroppBox](DroppBox.md) — A drop target for DraggBox items
+
+### Chapter 8 · App navigation
+
+_Build the shell of a real application and wire it to the router._
+
+56. [Scaffold](Scaffold.md) — the app shell: app bar, body, drawer, side bars
+57. [AdaptiveScaffold](AdaptiveScaffold.md) — the same shell, adapted to phone and desktop
+58. [AppBar](AppBar.md) — a top bar for titles, actions, and back navigation
+59. [Drawer](Drawer.md) — a panel that slides in from the side
+60. [DrawerItem](DrawerItem.md) — a router-aware row for a drawer or side bar
+61. [BottomNavigation](BottomNavigation.md) — a bottom tab bar synced with the router
+62. [Tabs](Tabs.md) — switch panes inside a screen
+63. [CollapsibleSideBar](CollapsibleSideBar.md) — a side panel that collapses to icons
+
+Then continue with [State, Router & Services](../guides/state.md) — Chapter 9.
+
+## Alphabetical index
+
+- [Accordion](Accordion.md)
+- [AdMob](AdMob.md)
+- [AdSense](AdSense.md)
+- [AdaptiveScaffold](AdaptiveScaffold.md)
+- [AlertDialog](AlertDialog.md)
+- [AnimatedBox](AnimatedBox.md)
+- [AnimatedText](AnimatedText.md)
+- [AppBar](AppBar.md)
+- [Audio](Audio.md)
+- [Avatar](Avatar.md)
+- [Badge](Badge.md)
+- [BottomNavigation](BottomNavigation.md)
+- [BottomSheet](BottomSheet.md)
+- [Button](Button.md)
+- [Card](Card.md)
+- [Carousel](Carousel.md)
+- [Chart](Chart.md)
+- [Checkbox](Checkbox.md)
+- [Chip](Chip.md)
+- [CircularBar](CircularBar.md)
+- [CircularChart](CircularChart.md)
+- [CodeViewer](CodeViewer.md)
+- [CollapsibleSideBar](CollapsibleSideBar.md)
+- [Column](Column.md)
+- [Container](Container.md)
+- [DataTable](DataTable.md)
+- [Divider](Divider.md)
+- [DraggBox](DraggBox.md)
+- [Drawer](Drawer.md)
+- [DrawerItem](DrawerItem.md)
+- [Dropdown](Dropdown.md)
+- [DroppBox](DroppBox.md)
+- [FloatingActionButton](FloatingActionButton.md)
+- [GridView](GridView.md)
+- [Icon](Icon.md)
+- [Image](Image.md)
+- [Input](Input.md)
+- [Inspector](Inspector.md)
+- [InstallButton](InstallButton.md)
+- [ListTile](ListTile.md)
+- [ListView](ListView.md)
+- [Markdown](Markdown.md)
+- [MatrixRain](MatrixRain.md)
+- [Modal](Modal.md)
+- [Pagination](Pagination.md)
+- [ParallaxBox](ParallaxBox.md)
+- [ProgressBar](ProgressBar.md)
+- [QRCode](QRCode.md)
+- [Radio](Radio.md)
+- [Rating](Rating.md)
+- [Row](Row.md)
+- [Scaffold](Scaffold.md)
+- [Skeleton](Skeleton.md)
+- [Slider](Slider.md)
+- [SnackBar](SnackBar.md)
+- [Stack](Stack.md)
+- [Stepper](Stepper.md)
+- [Switch](Switch.md)
+- [Tabs](Tabs.md)
+- [Text](Text.md)
+- [Tooltip](Tooltip.md)
+- [TreeView](TreeView.md)
+- [Video](Video.md)
+

package/docs/widget/Radio.md

@@ -0,0 +1,123 @@
+# Radio
+
+A single-selection control that renders a circular radio button. Radios sharing the same name form a group where only one can stay selected.
+
+## When to use it
+
+Use Radio when the user must pick exactly one option from a short, always-visible list.
+
+## Quick start
+
+```javascript
+import { Radio } from "flet-box";
+
+const plan = Radio({
+  label: "Monthly",
+  name: "billing",
+  onSelect: (value) => console.log(value),
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `selected` | `boolean` | Current selected state. |
+| `onSelect` | `(selected: boolean) => void` | Fired when the widget or an option is selected. |
+| `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. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `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. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { Radio } from "flet-box";
+
+const monthly = Radio({
+  label: "Monthly plan",
+  name: "billing",
+  selected: true,
+  activeColor: "#2563eb",
+  onSelect: (value) => console.log("billing:", value),
+});
+```
+
+### Full
+
+```javascript
+import { Radio } from "flet-box";
+
+const option = Radio({
+  label: "Express shipping",
+  name: "shipping",
+  selected: false,
+  disabled: false,
+  activeColor: "#16a34a",
+  size: 24,
+  onSelect: (value) => {
+    console.log("shipping changed:", value);
+  },
+});
+```
+
+## 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.
+
+## Accessibility
+
+- The circle carries no visible label on its own; render a Text beside it and never rely on color alone.
+
+## Behavior
+
+- Clicking an already-selected Radio is a no-op, so onSelect only fires when the selection actually changes.
+- The returned element exposes select(), unselect() and isSelected() for programmatic control.
+
+## Related widgets
+
+- [Switch](Switch.md)
+- [Checkbox](Checkbox.md)
+- [Dropdown](Dropdown.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Checkbox](Checkbox.md)
+- **Next:** [Switch](Switch.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 2 · Interaction basics** (4 of 8).

package/docs/widget/Rating.md

@@ -0,0 +1,131 @@
+# Rating
+
+A row of star icons that captures or displays a score up to max. It supports half-star selection and an inline numeric readout.
+
+## When to use it
+
+Use it for product reviews, feedback forms, or any quick qualitative score.
+
+## Quick start
+
+```javascript
+import { Rating } from "flet-box";
+
+const rating = Rating({
+  value: 4,
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value` | `number` | Current value controlled by the widget. |
+| `max` | `number` | Maximum value used to compute the ratio. |
+| `size` | `number` | Overall size preset or pixel value, depending on the widget. |
+| `allowHalf` | `boolean` | Allows half-star ratings. |
+| `activeColor` | `Color` | Color used in the active state. |
+| `inactiveColor` | `Color` | Color used in the inactive state. |
+| `showValue` | `boolean` | Shows the numeric value next to the indicator. |
+| `valueColor` | `Color` | Color used for the value. |
+| `valueSize` | `number` | Size of the value. |
+| `readOnly` | `boolean` | Makes the control read-only. |
+| `gap` | `number` | Space between children along the layout axis. |
+| `iconActive` | `string` | The `iconActive` value for the widget. |
+| `iconInactive` | `string` | The `iconInactive` value for the widget. |
+| `iconHalf` | `string` | The `iconHalf` value for the widget. |
+| `onChange` | `(value: number) => void` | Fired when the value changes. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `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. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { Rating } from "flet-box";
+
+const rating = Rating({
+  value: 4,
+  max: 5,
+  size: 24,
+  activeColor: "#f59e0b",
+  onChange: (value) => console.log(value),
+});
+```
+
+### Full
+
+```javascript
+import { Rating } from "flet-box";
+
+const rating = Rating({
+  value: 3.5,
+  max: 5,
+  size: 28,
+  allowHalf: true,
+  gap: 4,
+  activeColor: "#f59e0b",
+  inactiveColor: "#d1d5db",
+  showValue: true,
+  valueColor: "#374151",
+  valueSize: 16,
+  onChange: (value) => console.log("rated", value),
+});
+```
+
+## Tips
+
+- Set readOnly: true to display an aggregate score that users cannot change.
+- Use allowHalf: true for finer-grained ratings like 3.5 stars.
+
+## Accessibility
+
+- Provide a nearby Text label or showValue so the chosen score is readable, not just stars.
+
+## Behavior
+
+- onChange receives the numeric value each time the user picks a rating.
+- readOnly disables onChange while keeping the current value visible.
+
+## Related widgets
+
+- [ProgressBar](ProgressBar.md)
+- [Slider](Slider.md)
+- [Chip](Chip.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Dropdown](Dropdown.md)
+- **Next:** [Card](Card.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 2 · Interaction basics** (8 of 8).

package/docs/widget/Row.md

@@ -0,0 +1,131 @@
+# Row
+
+Horizontal flex layout that places its children side by side. It is full width and leaves height at auto by default.
+
+## When to use it
+
+Use Row for toolbars, button groups, and any set of items that should sit in a horizontal line.
+
+## Quick start
+
+```javascript
+import { Row, Text } from "flet-box";
+
+const row = Row({
+  gap: 8,
+  children: [
+    Text({ text: "Left" }),
+    Text({ text: "Right" }),
+  ],
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `gap` | `number \| string` | Space between children along the layout axis. |
+| `justifyContent` | `ContainerProps['justifyContent']` | Aligns children along the main axis (CSS `justify-content`). |
+| `alignItems` | `ContainerProps['alignItems']` | Aligns children across the cross axis (CSS `align-items`). |
+| `wrap` | `boolean \| 'wrap' \| 'nowrap' \| 'wrap-reverse'` | Lets children wrap onto multiple lines. |
+| `children` | `Widget[]` | An array of child widgets. Alias: `child` for a single child. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `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. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { Button, Row, Text } from "flet-box";
+
+const row = Row({
+  gap: 12,
+  justifyContent: "space-between",
+  alignItems: "center",
+  children: [
+    Text({ text: "Update your profile" }),
+    Button({ text: "Save", onPress: () => console.log("saved") }),
+  ],
+});
+```
+
+### Full
+
+```javascript
+import { Button, Icon, Row, Text } from "flet-box";
+
+const row = Row({
+  gap: 16,
+  justifyContent: "center",
+  alignItems: "center",
+  wrap: true,
+  padding: 16,
+  bgColor: "#f8fafc",
+  borderRadius: 12,
+  children: [
+    Icon({ name: "person" }),
+    Text({ text: "Jane Doe" }),
+    Button({ text: "Profile", variant: "outlined" }),
+  ],
+});
+```
+
+## Tips
+
+- `justifyContent` distributes free horizontal space and `alignItems` aligns children vertically.
+- Add `wrap: true` when children should flow onto additional lines instead of shrinking.
+- `gap` sets an even space between every child.
+
+## Accessibility
+
+- Keep the DOM order the same as the visual order so keyboard and screen-reader focus follow the layout.
+
+## Behavior
+
+- The element is `display: flex` with `flex-direction: row`; passing `onPress` makes the whole row interactive.
+- Children stay in the order given and can themselves be `expand` containers that share the row's width.
+
+## Related widgets
+
+- [Column](Column.md)
+- [Container](Container.md)
+- [Stack](Stack.md)
+- [Button](Button.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Container](Container.md)
+- **Next:** [Column](Column.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 1 · First steps: the core mental model** (3 of 7).