flet-box 1.0.3 → 1.0.5

package/docs/widget/COMMON_PROPS.md

@@ -0,0 +1,150 @@
+# Common props
+
+Every FletBox widget — `Text`, `Container`, `Button`, and all the rest — accepts
+the shared props below in addition to its own widget-specific props. They are
+defined once in the framework's central prop database
+([src/widget-factory/translateProps.js](../../src/widget-factory/translateProps.js)),
+so they behave identically everywhere.
+
+Widget pages link here instead of repeating this table. Read this page once and
+you will recognize these props on every widget.
+
+## Values and units
+
+- **Numbers are pixels.** A numeric value such as `padding: 20` renders as `20px`.
+  Internally FletBox converts it to `rem` on a 16px base (`20 / 16 = 1.25rem`), so
+  spacing and sizes scale if you change the root font size. The exception is
+  `borderWidth`, which is applied as raw pixels.
+- **Strings pass through.** A string such as `width: "50%"`, `margin: "8px auto"`,
+  or `padding: "10px 18px"` is used as-is, so any valid CSS value works.
+- **Unitless props** (`opacity`, `zIndex`, `weight`, colors, `flex`, …) take their
+  value directly with no unit appended.
+
+## Aliases (multi-dialect props)
+
+FletBox intentionally accepts several spellings for the same thing, so developers
+coming from Flet, Flutter, React, or vanilla JavaScript can write what feels
+natural. Each group below maps to the same underlying style or behavior:
+
+| Canonical | Aliases | Applies to |
+| --- | --- | --- |
+| `width` | `w` | CSS `width` |
+| `height` | `h` | CSS `height` |
+| `minWidth` / `maxWidth` | `minW` / `maxW` | CSS min/max width |
+| `minHeight` / `maxHeight` | `minH` / `maxH` | CSS min/max height |
+| `padding` | `p` | CSS `padding` |
+| `margin` | `m` | CSS `margin` |
+| `paddingTop/Right/Bottom/Left` | `pt` / `pr` / `pb` / `pl` | per-side padding |
+| `marginTop/Right/Bottom/Left` | `mt` / `mr` / `mb` / `ml` | per-side margin |
+| `backgroundColor` | `bgColor`, `bg` | CSS `background-color` |
+| `color` | `textColor` | CSS `color` (foreground/text) |
+| `fontSize` | `size` | CSS `font-size` |
+| `fontWeight` | `weight` | CSS `font-weight` |
+| `borderRadius` | `rounded` | CSS `border-radius` |
+| `boxShadow` | `shadow` | CSS `box-shadow` |
+| `position` | `pos` | CSS `position` |
+| `zIndex` | `z` | CSS `z-index` |
+| `flexDirection` | `direction` | CSS `flex-direction` |
+| `justifyContent` | `justify` | CSS `justify-content` |
+| `alignItems` | `align` | CSS `align-items` |
+| `flexWrap` | `wrap` | CSS `flex-wrap` |
+| `lineHeight` | `lineH` | CSS `line-height` |
+| `letterSpacing` | `letterSpace` | CSS `letter-spacing` |
+| `onClick` | `onPress`, `onclick` | click handler |
+
+> Note: some widgets reuse a common name for a widget-specific meaning. For
+> example, in [`Text`](Text.md) the `align` prop sets **text alignment**
+> (`textAlign`), while in layout widgets like [`Row`](Row.md) and
+> [`Column`](Column.md) `align` sets **`alignItems`**. Always check the widget
+> page for its own props.
+
+## Shorthand spacing
+
+These expand to two sides at once (numeric values are pixels):
+
+- `px` / `paddingHorizontal` → left + right padding
+- `py` / `paddingVertical` → top + bottom padding
+- `mx` / `marginHorizontal` → left + right margin
+- `my` / `marginVertical` → top + bottom margin
+
+## Layout and display
+
+`display`, `flexDirection` (`direction`), `justifyContent` (`justify`),
+`alignItems` (`align`), `flexWrap` (`wrap`), `flex`, `flexGrow`, `flexShrink`,
+`flexBasis`, `gap`, `boxSizing`, `overflow`, `overflowX`, `overflowY`,
+`position` (`pos`), `top`, `right`, `bottom`, `left`, `inset`, `zIndex` (`z`).
+
+## Size and spacing
+
+`width` (`w`), `height` (`h`), `minWidth`/`maxWidth`, `minHeight`/`maxHeight`,
+`padding` (`p`) and per-side variants, `margin` (`m`) and per-side variants,
+`gap`, and the horizontal/vertical shorthands above.
+
+## Color and background
+
+`backgroundColor` (`bgColor`, `bg`), `color` (`textColor`), `opacity`,
+`gradient` (CSS `background`), `bgImage`, `bgSize`, `bgPosition`, `bgRepeat`.
+
+## Typography
+
+`fontSize` (`size`), `fontWeight` (`weight`), `fontFamily`, `textAlign`,
+`lineHeight` (`lineH`), `letterSpacing` (`letterSpace`), `textDecoration`,
+`textTransform`, `whiteSpace`, `wordBreak`, `textOverflow`.
+
+## Border, radius and shadow
+
+`border`, `borderColor`, `borderWidth`, `borderStyle`, `borderTop`, `borderRight`,
+`borderBottom`, `borderLeft`, `borderRadius` (`rounded`), and the corner
+shorthands `roundedTop`, `roundedBottom`, `roundedLeft`, `roundedRight`, plus
+`boxShadow` (`shadow`) and `elevation`.
+
+> `elevation` is widget-specific on some components (for example
+> [`Button`](Button.md) maps `0`–`5` to preset shadows). As a common style prop it
+> is treated as a `box-shadow` value.
+
+## Animation and transform
+
+`transition`, `animation`, `transform`, `cursor`, `visibility`, `pointerEvents`,
+`userSelect`, `touchAction`.
+
+## Text content
+
+These set the element's text: `text`, `label`, `title`, `caption`, `description`,
+`message`, `buttonText`, and `textContent`.
+
+## HTML attributes
+
+`id`, `className` (`class`), `name`, `type`, `href`, `src`, `alt`, `disabled`,
+`readOnly`, `required`, `checked`, `selected`, `placeholder`, `min`, `max`,
+`step`, `pattern`, `role`, `lang`, `dir`, `tabIndex`, `draggable`, `hidden`,
+`for` (`htmlFor`), `autofocus`, `autocomplete`, `spellcheck`. Any `data-*` or
+`aria-*` attribute is also passed through.
+
+## Events
+
+`onClick` (`onPress`, `onclick`), `onDoublePress`, `onRightClick`, `onHover`,
+`onHoverEnd`, `onFocus`, `onBlur`, `onChange`, `onInput`, `onScroll`, `onKeyDown`,
+`onKeyUp`, `onKeyPress`, `onMouseDown`, `onMouseUp`, `onMouseMove`,
+`onTouchStart`, `onTouchMove`, `onTouchEnd`. Any other `on<Event>` prop with a
+function value is attached as a native listener.
+
+## Structure and refs
+
+- `child`: a single child widget.
+- `children`: an array of child widgets.
+- `ref`: a callback that receives the underlying DOM node — `ref: (el) => (myRef = el)`.
+
+> There is intentionally **no `style` prop**. FletBox uses flat, aliased CSS
+> props instead. Passing `style: { ... }` is rejected with a console warning;
+> write the same declarations flat (`backgroundColor`, `padding`, `flexDirection`, …).
+
+## Reactivity
+
+Most style, spacing, color, typography, and text props are **reactive**: when they
+are bound to state via [`useState`](../guides/state.md), the widget updates in
+place when the value changes, without a full re-render.
+
+## Related
+
+- [Syntax philosophy](../guides/syntax-philosophy.md) — why aliases coexist.
+- [Widget index](README.md) — the full book of widgets.

package/docs/widget/Card.md

@@ -0,0 +1,125 @@
+# Card
+
+A rounded, optionally elevated surface that groups related content into a single tappable unit.
+
+## When to use it
+
+Use it to present a self-contained block such as a summary, product, or stat.
+
+## Quick start
+
+```javascript
+import { Card, Text } from "flet-box";
+
+const card = Card({
+  child: Text({ text: "Hello" }),
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `child` | `Widget` | A single child widget. Alias: `children` for a list. |
+| `children` | `Widget[]` | An array of child widgets. Alias: `child` for a single child. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `showBorder` | `boolean` | Controls whether the border is shown. |
+| `borderWidth` | `number` | Width of the border. |
+| `borderStyle` | `'solid' \| 'dashed' \| 'dotted'` | The `borderStyle` value for the widget. |
+| `borderColor` | `Color` | Color used for the border. |
+| `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 { Card, Text } from "flet-box";
+
+const card = Card({
+  elevation: 2,
+  padding: 16,
+  borderRadius: 12,
+  child: Text({ text: "Today's summary" }),
+});
+```
+
+### Full
+
+```javascript
+import { Card, Text } from "flet-box";
+
+const card = Card({
+  elevation: 3,
+  padding: 20,
+  borderRadius: 16,
+  showBorder: true,
+  borderColor: "#e2e8f0",
+  borderWidth: 1,
+  onPress: () => console.log("open report"),
+  children: [
+    Text({ text: "Weekly report", weight: "bold" }),
+    Text({ text: "Revenue is up 12% this week." }),
+  ],
+});
+```
+
+## Tips
+
+- Keep elevation subtle (1-3) so stacked cards do not look noisy.
+- Set showBorder: true for a flat look, or use elevation for a raised surface.
+
+## Accessibility
+
+- When onPress is set the whole card becomes a button; make its heading describe the action.
+
+## Behavior
+
+- Accepts either child for one widget or children for a stacked column of content.
+- onPress fires for clicks anywhere inside the card surface.
+
+## Related widgets
+
+- [Container](Container.md)
+- [ListTile](ListTile.md)
+- [Button](Button.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Rating](Rating.md)
+- **Next:** [Divider](Divider.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 3 · Layout, cards and lists** (1 of 8).

package/docs/widget/Carousel.md

@@ -0,0 +1,151 @@
+# Carousel
+
+Carousel cycles through items one at a time with optional arrows, dots and autoplay. Items may be widgets, image URLs or src/alt objects.
+
+## When to use it
+
+Use it to showcase a small set of images, banners or promo slides in limited space.
+
+## Quick start
+
+```javascript
+import { Carousel } from "flet-box";
+
+const hero = Carousel({
+  items: ["/banner-1.png", "/banner-2.png"],
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `items` | `(Widget \| string \| { src: string; alt?: string })[]` | Array of items rendered in a rotating or grouped widget. |
+| `autoPlay` | `boolean` | Advances automatically. |
+| `interval` | `number` | Delay between automatic advances, in milliseconds. |
+| `showArrows` | `boolean` | Shows previous/next arrows. |
+| `showDots` | `boolean` | Shows the dot indicators. |
+| `infinite` | `boolean` | Loops from the last item back to the first. |
+| `height` | `number \| string` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `width` | `number \| string` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `dotColor` | `Color` | Color used for the dot. |
+| `dotActiveColor` | `Color` | Color used for the dot active. |
+| `dotSize` | `number` | Size of the dot. |
+| `dotActiveSize` | `number` | Size of the dot active. |
+| `buttonBgColor` | `Color` | Background color for the button. |
+| `buttonIconColor` | `Color` | Color used for the button icon. |
+| `buttonSize` | `number` | Size of the button. |
+| `buttonIconSize` | `number` | Size of the button icon. |
+| `buttonTop` | `number \| string` | The `buttonTop` value for the widget. |
+| `onIndexChange` | `(index: number) => void` | Fired with the new active index. |
+
+### 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 { Carousel } from "flet-box";
+
+const hero = Carousel({
+  items: [
+    { src: "/sale.png", alt: "Summer sale" },
+    { src: "/launch.png", alt: "New launch" },
+  ],
+  autoPlay: true,
+  interval: 4000,
+  showDots: true,
+  showArrows: true,
+});
+```
+
+### Full
+
+```javascript
+import { Carousel, Text } from "flet-box";
+
+const hero = Carousel({
+  items: [
+    { src: "/sale.png", alt: "Summer sale" },
+    { src: "/launch.png", alt: "New launch" },
+    Text({ text: "Featured story" }),
+  ],
+  autoPlay: true,
+  interval: 5000,
+  infinite: true,
+  showArrows: true,
+  showDots: true,
+  height: 320,
+  width: "100%",
+  borderRadius: 16,
+  dotColor: "#cbd5e1",
+  dotActiveColor: "#2563eb",
+  dotSize: 8,
+  dotActiveSize: 10,
+  buttonBgColor: "#ffffff",
+  buttonIconColor: "#0f172a",
+  buttonSize: 40,
+  buttonIconSize: 20,
+  onIndexChange: (index) => console.log(index),
+});
+```
+
+## Tips
+
+- Enable autoPlay with a sensible interval and keep showDots on so users can jump to a slide.
+- Mix URL strings, src/alt objects and widgets in items to combine images with captions.
+- Use infinite for looping banners but turn it off when the sequence has a clear first and last slide.
+
+## Accessibility
+
+- Give image items meaningful alt text so each slide is described.
+- Provide pause and advance controls, and avoid autoplay for content that needs reading time.
+
+## Behavior
+
+- onIndexChange fires with the new slide index whenever the active item changes.
+- Autoplay is cleared automatically when the widget unmounts.
+
+## Related widgets
+
+- [Image](Image.md)
+- [Stack](Stack.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [TreeView](TreeView.md)
+- **Next:** [InstallButton](InstallButton.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 5 · Navigation and flows** (4 of 5).

package/docs/widget/Chart.md

@@ -0,0 +1,151 @@
+# Chart
+
+Chart draws bar, line, area or candlestick data onto a canvas, with optional labels, grid and value annotations. Numeric arrays drive bar/line/area while OHLC objects drive candle charts.
+
+## When to use it
+
+Use it to visualize trends and comparisons inline without pulling in a charting library.
+
+## Quick start
+
+```javascript
+import { Chart } from "flet-box";
+
+const totals = Chart({
+  type: "bar",
+  data: [12, 19, 7, 15],
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `type` | `'bar' \| 'line' \| 'area' \| 'candle'` | Kind or mode of the widget. |
+| `data` | `number[] \| Array<{ open: number; high: number; low: number; close: number }>` | Array of values or `{ label, value }` slices. |
+| `labels` | `string[]` | Axis or slice labels for the chart. |
+| `width` | `number \| string` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `number` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `padding` | `number \| { top: number; right: number; bottom: number; left: number }` | Space inside the widget, between its content and its border. |
+| `candleWidth` | `number` | Width of each candlestick. |
+| `candleSpacing` | `number` | The `candleSpacing` value for the widget. |
+| `barColor` | `Color` | Color used for the bar. |
+| `lineColor` | `Color` | Color used for the line. |
+| `areaColor` | `Color` | Color used for the area. |
+| `smooth` | `boolean` | Draws a smoothed line instead of straight segments. |
+| `areaGradient` | `boolean` | Fills the area under the line with a gradient. |
+| `areaGradientColors` | `[string, string]` | The `areaGradientColors` value for the widget. |
+| `candleUpColor` | `Color` | Color used for the candle up. |
+| `candleDownColor` | `Color` | Color used for the candle down. |
+| `axisColor` | `Color` | Color used for the axis. |
+| `textColor` | `Color` | Color of the button label. |
+| `yAxisColor` | `Color` | Color used for the y axis. |
+| `showGrid` | `boolean` | Shows the chart grid lines. |
+| `showLabels` | `boolean` | Shows chart labels. |
+| `showValues` | `boolean` | Controls whether the values is shown. |
+| `borderRadius` | `number` | Rounds the corners of 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 { Chart } from "flet-box";
+
+const revenue = Chart({
+  type: "line",
+  data: [12, 19, 7, 15, 22],
+  labels: ["Jan", "Feb", "Mar", "Apr", "May"],
+  height: 260,
+  showGrid: true,
+  showLabels: true,
+});
+```
+
+### Full
+
+```javascript
+import { Chart } from "flet-box";
+
+const trend = Chart({
+  type: "area",
+  data: [8, 14, 10, 21, 18, 26],
+  labels: ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
+  width: "100%",
+  height: 320,
+  smooth: true,
+  areaGradient: true,
+  areaGradientColors: ["#3b82f6", "#bfdbfe"],
+  lineColor: "#2563eb",
+  areaColor: "#93c5fd",
+  axisColor: "#94a3b8",
+  textColor: "#475569",
+  showGrid: true,
+  showLabels: true,
+  showValues: true,
+  borderRadius: 12,
+  bgColor: "#ffffff",
+  padding: 16,
+});
+```
+
+## Tips
+
+- Match data to type: pass numbers for bar/line/area and open/high/low/close objects for candle.
+- Provide labels so the x-axis is meaningful to readers.
+- Set an explicit height to reserve space and avoid layout shift while the chart initializes.
+
+## Accessibility
+
+- Add a text summary or table of the values near the chart since canvas content is not readable by screen readers.
+- Use sufficient contrast between data, axis and background colors.
+
+## Behavior
+
+- The canvas redraws when data, labels, type or styling props change.
+- Candle charts read open, high, low and close in that order from each data object.
+
+## Related widgets
+
+- [CircularChart](CircularChart.md)
+- [CircularBar](CircularBar.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [DataTable](DataTable.md)
+- **Next:** [CircularChart](CircularChart.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 6 · Data, rich content & effects** (2 of 13).

package/docs/widget/Checkbox.md

@@ -0,0 +1,118 @@
+# Checkbox
+
+A square checkbox with a check mark that represents an independent true/false choice.
+
+## When to use it
+
+Use Checkbox when several options can be selected at once, or when confirming a single item in a form.
+
+## Quick start
+
+```javascript
+import { Checkbox } from "flet-box";
+
+const terms = Checkbox({
+  label: "Accept terms",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `checked` | `boolean` | Current checked state. |
+| `onCheck` | `(checked: boolean) => void` | Fired with the new checked state. |
+| `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. |
+
+### 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 { Checkbox } from "flet-box";
+
+const remember = Checkbox({
+  checked: true,
+  label: "Remember me",
+  activeColor: "#2563eb",
+  onCheck: (checked) => console.log("remember:", checked),
+});
+```
+
+### Full
+
+```javascript
+import { Checkbox } from "flet-box";
+
+const updates = Checkbox({
+  checked: false,
+  label: "Email me product updates",
+  size: 24,
+  activeColor: "#7c3aed",
+  disabled: false,
+  onCheck: (checked) => {
+    console.log("updates:", checked);
+  },
+});
+```
+
+## Tips
+
+- Use Checkbox inside forms where several options may be true together; use Switch for one immediate on/off setting.
+- onCheck fires with the new boolean, so write it straight into your state.
+
+## Accessibility
+
+- The check box needs an adjacent visible label; assistive tech cannot infer meaning from the tick glyph alone.
+
+## Behavior
+
+- Uncontrolled when checked is omitted; the widget tracks its own state and reports changes through onCheck.
+- The returned element exposes setChecked(value) and getChecked() for programmatic control.
+
+## Related widgets
+
+- [Switch](Switch.md)
+- [Radio](Radio.md)
+- [ListTile](ListTile.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Input](Input.md)
+- **Next:** [Radio](Radio.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 2 · Interaction basics** (3 of 8).