flet-box 1.0.4 → 1.0.5

package/docs/widget/Stack.md

@@ -0,0 +1,128 @@
+# Stack
+
+Overlay container that lets children occupy the same box. It is relative by default so children can be positioned, and it supports a nine-point alignment.
+
+## When to use it
+
+Use Stack to layer badges, overlays, captions, or any elements that should sit on top of one another.
+
+## Quick start
+
+```javascript
+import { Stack, Text } from "flet-box";
+
+const stack = Stack({
+  children: [
+    Text({ text: "Base" }),
+    Text({ text: "Overlay" }),
+  ],
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | `Widget[]` | An array of child widgets. Alias: `child` for a single child. |
+| `position` | `'relative' \| 'absolute'` | CSS `position` value, or `stack` for centered stacking. |
+| `alignment` | `'top-left' \| 'top-center' \| 'top-right' \| 'center-left' \| 'center' \| 'center-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | How children are aligned inside the stack. |
+
+### 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 { Container, Stack, Text } from "flet-box";
+
+const stack = Stack({
+  width: 240,
+  height: 160,
+  alignment: "center",
+  children: [
+    Container({ bgColor: "#e0e7ff", child: Text({ text: "Background" }) }),
+    Text({ text: "Centered", weight: "bold" }),
+  ],
+});
+```
+
+### Full
+
+```javascript
+import { Container, Stack, Text } from "flet-box";
+
+const stack = Stack({
+  width: "100%",
+  height: 220,
+  position: "relative",
+  alignment: "bottom-right",
+  children: [
+    Container({ bgColor: "#f1f5f9", child: Text({ text: "Cover" }) }),
+    Container({
+      bgColor: "#2563eb",
+      borderRadius: 8,
+      padding: 8,
+      child: Text({ text: "New", color: "#ffffff" }),
+    }),
+  ],
+});
+```
+
+## Tips
+
+- Stack is `position: "relative"` by default, which makes it a positioning context for absolute children.
+- `alignment` anchors children at one of nine points from top-left to bottom-right.
+- Later children paint on top, so order them from back to front.
+
+## Accessibility
+
+- Make sure overlaid controls keep a logical tab order and that focus is never hidden behind another layer.
+
+## Behavior
+
+- The root is a plain block by default and children are laid out per `position` and `alignment`.
+- Set `width` and `height` (or `expand`) when the stack needs a definite size for layered content.
+
+## Related widgets
+
+- [Container](Container.md)
+- [Row](Row.md)
+- [Column](Column.md)
+- [Badge](Badge.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Column](Column.md)
+- **Next:** [Icon](Icon.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 1 · First steps: the core mental model** (5 of 7).

package/docs/widget/Stepper.md

@@ -0,0 +1,145 @@
+# Stepper
+
+A multi-step progress indicator that shows each step as a circle, number or icon and reveals the active step's content.
+
+## When to use it
+
+Use Stepper for guided flows such as checkout or onboarding where the user advances through ordered steps.
+
+## Quick start
+
+```javascript
+import { Stepper, Text } from "flet-box";
+
+const stepper = Stepper({
+  steps: [
+    { label: "Account", content: Text({ text: "Account details" }) },
+    { label: "Done", content: Text({ text: "All set" }) },
+  ],
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `steps` | `Array<{ label: string; content: Widget; icon?: string }>` | Step definitions rendered by the stepper. |
+| `activeStep` | `number` | Index of the currently active step. |
+| `onStepChange` | `(index: number) => void` | Fired with the new active step index. |
+| `orientation` | `'horizontal' \| 'vertical'` | Orientation of the widget or control. |
+| `variant` | `'circles' \| 'numbers' \| 'icons'` | Visual variation or style preset. |
+| `showLabels` | `boolean` | Shows chart labels. |
+| `showNavigation` | `boolean` | Controls whether the navigation is shown. |
+| `nextLabel` | `string` | Label for the next. |
+| `backLabel` | `string` | Label for the back. |
+| `finishLabel` | `string` | Label for the finish. |
+| `onFinish` | `() => void` | Event handler for the `onFinish` event. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `border` | `string` | The `border` value for the widget. |
+| `borderColor` | `Color` | Color used for the border. |
+| `borderWidth` | `number` | Width of the border. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `width` | `number \| string` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+
+### 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 { Stepper, Text } from "flet-box";
+
+const stepper = Stepper({
+  activeStep: 0,
+  steps: [
+    { label: "Cart", content: Text({ text: "Review your cart" }) },
+    { label: "Address", content: Text({ text: "Shipping address" }) },
+    { label: "Payment", content: Text({ text: "Payment method" }) },
+  ],
+  onStepChange: (index) => console.log("step:", index),
+});
+```
+
+### Full
+
+```javascript
+import { Stepper, Text } from "flet-box";
+
+const checkout = Stepper({
+  orientation: "vertical",
+  variant: "icons",
+  activeStep: 1,
+  showLabels: true,
+  showNavigation: true,
+  nextLabel: "Continue",
+  backLabel: "Previous",
+  finishLabel: "Place order",
+  steps: [
+    { label: "Cart", icon: "shopping_cart", content: Text({ text: "Your cart" }) },
+    { label: "Shipping", icon: "local_shipping", content: Text({ text: "Address" }) },
+    { label: "Payment", icon: "credit_card", content: Text({ text: "Payment" }) },
+  ],
+  onStepChange: (index) => console.log("step:", index),
+  onFinish: () => console.log("finished"),
+});
+```
+
+## Tips
+
+- Steps are clickable, so users can jump around; use onStepChange to validate a step before allowing the move.
+- variant: icons pulls each step's icon; circles and numbers ignore it.
+
+## Accessibility
+
+- Expose the current position beyond the highlight color; showLabels: true gives every step visible text.
+
+## Behavior
+
+- Clicking a step or the Next/Back buttons calls onStepChange; the final step swaps Next for Finish, which fires onFinish.
+- The returned element exposes goTo(index), next(), back() and getActiveStep() for imperative navigation.
+
+## Related widgets
+
+- [ProgressBar](ProgressBar.md)
+- [Button](Button.md)
+- [Container](Container.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Pagination](Pagination.md)
+- **Next:** [Accordion](Accordion.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 5 · Navigation and flows** (1 of 5).

package/docs/widget/Switch.md

@@ -0,0 +1,118 @@
+# Switch
+
+An iOS-style toggle switch with a sliding knob that represents an on/off state.
+
+## When to use it
+
+Use Switch for settings that take effect immediately, such as dark mode or notifications.
+
+## Quick start
+
+```javascript
+import { Switch } from "flet-box";
+
+const darkMode = Switch({
+  label: "Dark mode",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value` | `boolean` | Current value controlled by the widget. |
+| `onToggle` | `(value: boolean) => void` | Fired with the new toggled state. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `size` | `'small' \| 'medium' \| 'large'` | 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 { Switch } from "flet-box";
+
+const notifications = Switch({
+  value: true,
+  label: "Notifications",
+  activeColor: "#16a34a",
+  onToggle: (value) => console.log("notifications:", value),
+});
+```
+
+### Full
+
+```javascript
+import { Switch } from "flet-box";
+
+const wifi = Switch({
+  value: false,
+  label: "Wi-Fi",
+  size: "large",
+  activeColor: "#2563eb",
+  disabled: false,
+  onToggle: (value) => {
+    console.log("wifi toggled:", value);
+  },
+});
+```
+
+## Tips
+
+- Reserve Switch for immediate settings and use Checkbox when the choice is part of a form you submit.
+- onToggle receives the new boolean, so you can store it directly in your state.
+
+## Accessibility
+
+- Pair the switch with a nearby text label and expose the boolean state; do not encode on/off with color only.
+
+## Behavior
+
+- Switch works uncontrolled when value is omitted: clicking toggles the internal state and fires onToggle.
+- The returned element exposes getValue() and updateValue(v) to read or set the state without a click.
+
+## Related widgets
+
+- [Checkbox](Checkbox.md)
+- [Radio](Radio.md)
+- [ListTile](ListTile.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Radio](Radio.md)
+- **Next:** [Slider](Slider.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 2 · Interaction basics** (5 of 8).

package/docs/widget/Tabs.md

@@ -0,0 +1,124 @@
+# Tabs
+
+## Overview
+`Tabs` renders an in-page tab switcher: a row of tab buttons (`role="tab"`), one mounted `child` pane per tab, and several visual `variant`s — `underline`, `filled`, `slider` (a floating indicator that slides behind the active tab), and `pills`. Tabs accept plain strings or objects (`{ label, icon?, badge? }`), and `badges` can also be supplied as a separate array. Clicking (or pressing `Enter`/`Space`) switches the pane and fires `onChange(index)`.
+
+## When to use
+- Switch between panes inside one screen without leaving the page.
+- Segmented control / pill navigation for a settings page.
+
+## Import
+
+```javascript
+import { Tabs, Text } from "flet-box";
+```
+
+## Basic example
+
+The smallest useful version. Start here if this widget is new to you.
+
+```javascript
+import { Tabs, Text } from "flet-box";
+
+Tabs({
+  tabs: ["Info", "Activity"],
+  children: [
+    Text({ text: "Account info" }),
+    Text({ text: "Recent activity" }),
+  ],
+});
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tabs` | array | `[]` | Labels: strings or `{ label, icon?, badge? }` objects. |
+| `children` | array | `[]` | One pane per tab; the active pane is mounted at `children[activeIndex]`. |
+| `activeIndex` | number | `0` | The active tab (initial value; also the settable live value). |
+| `onChange` | function | — | Fired with the new index when the tab changes. |
+| `variant` | `'underline'`/`'filled'`/`'slider'`/`'pills'` | `'underline'` | Visual treatment of the tab bar. |
+| `size` | `'small'`/`'medium'`/`'large'` | `'medium'` | Font, padding, icon, and height presets. |
+| `textColor` | Color | `colors.text` | Inactive label/icon color. |
+| `activeTextColor` | Color | `colors.white` | Active label/icon color. |
+| `bgColor` | Color | `colors.gray100` | Bar background for `slider`/`filled` variants. |
+| `buttonColor` | Color | `colors.secondary` | Background of the `slider` indicator and `pills`. |
+| `dividerColor` | Color | `colors.border` | Bottom border for the `underline` variant (when `showDivider`). |
+| `fullWidth` | boolean | `true` | Tabs share the full width; otherwise they hug their content. |
+| `showDivider` | boolean | `true` | Bottom divider under an `underline` bar. |
+| `showIcon` | boolean | `false` | Show the per-tab `icon`. |
+| `iconPosition` | `'left'`/`'right'`/`'top'`/`'bottom'` | `'left'` | Where the icon sits: `'left'` places it before the label; any other value places it after. |
+| `iconSize` | number | `18` | Icon size in pixels. |
+| `badges` | array | `[]` | Badge values per tab (`badges[i]`), or set them inline via `{ badge }`. |
+| `alignment` | `'left'`/`'center'`/`'right'` | `'left'` | Accepted for API compatibility; currently has no visual effect. |
+| `color` | Color | `colors.primary` | Accepted for API compatibility; active styling uses `activeTextColor`/`buttonColor` instead. |
+
+These are the props specific to `Tabs`. It also accepts every [common prop](COMMON_PROPS.md).
+
+## Instance methods
+
+- `activeIndex` — getter/setter property: assign a new index to switch tabs and fire `onChange`.
+- `setActiveTab(index)` — same as writing `activeIndex`.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { Tabs, Text } from "flet-box";
+
+Tabs({
+  variant: "pills",
+  tabs: ["All", "Active", "Done"],
+  children: [
+    Text({ text: "Everything" }),
+    Text({ text: "In progress" }),
+    Text({ text: "Completed" }),
+  ],
+});
+```
+
+### Full example
+
+```javascript
+import { Tabs, Text } from "flet-box";
+
+const tabs = Tabs({
+  variant: "slider",
+  tabs: [
+    { label: "Inbox", icon: "mail", badge: 3 },
+    { label: "Archive", icon: "archive" },
+  ],
+  children: [Text({ text: "Inbox pane" }), Text({ text: "Archive pane" })],
+  showIcon: true,
+  bgColor: "#f8fafc",
+  buttonColor: "#2563eb",
+  activeTextColor: "#ffffff",
+  onChange: (index) => console.log("tab", index),
+});
+
+tabs.setActiveTab(1); // switch to the second tab
+```
+
+## Notes
+
+- Only the active pane is mounted in the DOM at a time — switching replaces the pane content.
+- The `slider` indicator animates its width/position (`transform`), and a `ResizeObserver` + window `resize` listener keep it aligned. All listeners and the indicator timer are released by `_cleanup`.
+- `badge` renders a small red pill after the label (from `colors.danger`, white text). Badges take the inline `{ badge }` value first, then the `badges` array.
+- Each tab is a real accessibility target: `role="tab"`, `aria-selected`, `tabIndex: 0`, keyboard activation with `Enter`/`Space`.
+- `children`/`tabs` length mismatch: panes are mounted by index; if there is no pane for the active index, the pane area stays empty.
+
+## Related widgets
+- [BottomNavigation](BottomNavigation.md)
+- [Badge](Badge.md)
+- [Icon](Icon.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [BottomNavigation](BottomNavigation.md)
+- **Next:** [CollapsibleSideBar](CollapsibleSideBar.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 8 · App navigation** (7 of 8).

package/docs/widget/Text.md

@@ -0,0 +1,133 @@
+# Text
+
+Renders a string as inline text or as a heading, with control over size, weight, color, alignment, and inline styles.
+
+## When to use it
+
+Use Text for every piece of copy, from body paragraphs and labels to page headings.
+
+## Quick start
+
+```javascript
+import { Text } from "flet-box";
+
+const title = Text({
+  text: "Welcome back",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `text` | `string` | Visible text content. |
+| `value` | `string` | Current value controlled by the widget. |
+| `children` | `string` | An array of child widgets. Alias: `child` for a single child. |
+| `size` | `number` | Overall size preset or pixel value, depending on the widget. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `weight` | `'normal' \| 'bold' \| number` | Font weight, such as `normal`, `bold`, or a number. |
+| `align` | `'left' \| 'center' \| 'right' \| 'justify'` | Horizontal text alignment. |
+| `italic` | `boolean` | Renders the text in italics. |
+| `decoration` | `'underline' \| 'line-through' \| 'overline'` | Text decoration such as `underline` or `line-through`. |
+| `lineHeight` | `number \| string` | Line height as a number multiplier or CSS value. |
+| `letterSpacing` | `number \| string` | Extra space between letters. |
+| `type` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'p'` | Kind or mode of the widget. |
+| `styles` | `Array<'bold' \| 'italic' \| 'underline' \| 'strikethrough' \| 'mark' \| 'small' \| 'code'>` | Extra inline styles applied to the text. |
+| `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 { Text } from "flet-box";
+
+const title = Text({
+  text: "Welcome back",
+  type: "h2",
+  size: 28,
+  weight: "bold",
+  color: "#111827",
+});
+```
+
+### Full
+
+```javascript
+import { Text } from "flet-box";
+
+const body = Text({
+  text: "Your subscription renews on Friday.",
+  type: "p",
+  size: 16,
+  weight: "normal",
+  color: "#374151",
+  align: "left",
+  lineHeight: 1.5,
+  letterSpacing: 0.2,
+  italic: false,
+  decoration: "underline",
+  styles: ["code"],
+  onPress: () => console.log("pressed"),
+});
+```
+
+## Tips
+
+- Pass content with `text`, `value`, or `children`; `type` maps to the `h1`-`h6` and `p` tags.
+- `styles` applies inline emphasis such as `bold`, `italic`, `underline`, `strikethrough`, `mark`, or `code`.
+- `weight` accepts `"normal"`, `"bold"`, or a numeric value.
+
+## Accessibility
+
+- Use heading `type` values in order so the document outline stays meaningful for screen readers.
+
+## Behavior
+
+- Heading types `h1`, `h2`, and `p` add a bottom margin; size and color fall back to theme defaults.
+- Inline `styles` wrap the element in semantic tags such as `strong`, `em`, and `code`.
+
+## Related widgets
+
+- [Icon](Icon.md)
+- [Button](Button.md)
+- [Container](Container.md)
+- [ListTile](ListTile.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Start here](START_HERE.md)
+- **Next:** [Container](Container.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 1 · First steps: the core mental model** (1 of 7).