flet-box 1.0.3 → 1.0.5

package/docs/widget/FloatingActionButton.md

@@ -0,0 +1,120 @@
+# FloatingActionButton
+
+A circular, elevated button that floats over content and can expand into a labeled pill.
+
+## When to use it
+
+Use FloatingActionButton for the single most important action on a screen, such as compose or create.
+
+## Quick start
+
+```javascript
+import { FloatingActionButton } from "flet-box";
+
+const add = FloatingActionButton({
+  icon: "add",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `icon` | `string \| Widget` | Name of the icon to render. |
+| `label` | `string` | Label or caption shown near the control. |
+| `onPress` | `() => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
+| `foregroundColor` | `Color` | Color of the icon and label. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `mini` | `boolean` | Renders the small variant of the floating action button. |
+| `extended` | `boolean` | Extends the FAB to show a label next to the icon. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `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 { FloatingActionButton } from "flet-box";
+
+const compose = FloatingActionButton({
+  icon: "edit",
+  onPress: () => console.log("compose"),
+});
+```
+
+### Full
+
+```javascript
+import { FloatingActionButton } from "flet-box";
+
+const create = FloatingActionButton({
+  icon: "add",
+  label: "New project",
+  extended: true,
+  backgroundColor: "#2563eb",
+  foregroundColor: "#ffffff",
+  elevation: 8,
+  margin: 24,
+  onPress: () => console.log("create"),
+});
+```
+
+## Tips
+
+- Keep one FloatingActionButton per screen; extended: true with a label makes the action explicit.
+- mini: true shrinks the button for secondary floating actions.
+
+## Accessibility
+
+- A bare icon button needs a label; prefer extended: true with a visible label, or wrap it in a Tooltip so the action is discoverable.
+
+## Behavior
+
+- When onPress is set the button gains a click listener and a hover scale; both the scale and pointer style are disabled when disabled is true.
+- The icon prop accepts either an icon name or an already-built Icon widget.
+
+## Related widgets
+
+- [Button](Button.md)
+- [Icon](Icon.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Skeleton](Skeleton.md)
+- **Next:** [Pagination](Pagination.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 4 · Feedback and overlays** (9 of 10).

package/docs/widget/GridView.md

@@ -0,0 +1,140 @@
+# GridView
+
+Grid layout built on ListView's virtualization. It lays items out in a fixed number of columns and gives every cell the same height.
+
+## When to use it
+
+Use GridView for image galleries, product catalogs, and dashboards of equal-sized tiles.
+
+## Quick start
+
+```javascript
+import { GridView, Text, grid } from "flet-box";
+
+const grid = GridView({
+  data: ["A", "B", "C", "D"],
+  renderItem: (item) => Text({ text: item }),
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `expand` | `boolean \| number` | Lets a flex child grow to fill available space. |
+| `bufferSize` | `number` | How many extra items to render beyond the viewport. |
+| `showsScrollIndicator` | `boolean` | Shows the native scrollbar. |
+| `ListEmptyComponent` | `(() => Widget) \| Widget` | Widget or builder shown when there is no data. |
+| `ListFooterComponent` | `(() => Widget) \| Widget` | Widget or builder rendered below the list content. |
+| `ListHeaderComponent` | `(() => Widget) \| Widget` | Widget or builder rendered above the list content. |
+| `onRefresh` | `(done: () => void) => void` | Pull-to-refresh handler; call the provided `done()` when finished. |
+| `onEndReachedThreshold` | `number` | How close to the end (in items or px) triggers `onEndReached`. |
+| `onEndReached` | `() => void` | Fired when the list scrolls near its end, for infinite loading. |
+| `gap` | `number` | Space between children along the layout axis. |
+| `itemSize` | `number` | Height of each list item. |
+| `width` | `number \| string` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `number \| string` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `renderItem` | `(item: any, index: number) => Widget` | Builds one child from an item: `(item, index) => Widget`. |
+| `data` | `any[]` | Array of values or `{ label, value }` slices. |
+| `columns` | `number` | Number of grid columns. |
+| `spacing` | `number` | Space between grid items. |
+| `itemHeight` | `number` | Height of each grid cell. |
+
+### 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, GridView, Text, grid } from "flet-box";
+
+const grid = GridView({
+  data: products,
+  columns: 3,
+  spacing: 12,
+  itemHeight: 160,
+  renderItem: (item) => Card({ child: Text({ text: item.name }) }),
+});
+```
+
+### Full
+
+```javascript
+import { Container, GridView, Text, grid } from "flet-box";
+
+const grid = GridView({
+  data: products,
+  columns: 2,
+  spacing: 16,
+  itemHeight: 180,
+  gap: 16,
+  height: 480,
+  showsScrollIndicator: true,
+  onEndReached: () => loadMore(),
+  ListEmptyComponent: () => Text({ text: "No products" }),
+  renderItem: (item) => Container({
+    bgColor: "#ffffff",
+    borderRadius: 12,
+    child: Text({ text: item.name }),
+  }),
+});
+```
+
+## Tips
+
+- `columns` sets the number of columns and `spacing` sets the gap between cells.
+- `itemHeight` fixes each cell's height, which is what makes virtualization possible.
+- It accepts the same `data` and `renderItem` contract as ListView.
+
+## Accessibility
+
+- Announce the grid's purpose with a heading and keep each tile's tap target large enough to hit.
+
+## Behavior
+
+- GridView is implemented as ListView with grid wrapping enabled, so it shares the same scrolling and update APIs.
+- Rows outside the viewport are removed, so keep per-tile state out of the DOM and in widget state when needed.
+
+## Related widgets
+
+- [ListView](ListView.md)
+- [Container](Container.md)
+- [Card](Card.md)
+- [Image](Image.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [ListView](ListView.md)
+- **Next:** [Avatar](Avatar.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 3 · Layout, cards and lists** (5 of 8).

package/docs/widget/Icon.md

@@ -0,0 +1,117 @@
+# Icon
+
+Material icon glyph rendered as a span. `name` is required and maps to a Material Icons ligature.
+
+## When to use it
+
+Use Icon for compact actions, status indicators, and decoration next to a label.
+
+## Quick start
+
+```javascript
+import { Icon } from "flet-box";
+
+const settings = Icon({
+  name: "settings",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The `name` value for the widget. |
+| `size` | `number` | Overall size preset or pixel value, depending on the widget. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `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 { Icon } from "flet-box";
+
+const settings = Icon({
+  name: "settings",
+  size: 28,
+  color: "#111827",
+});
+```
+
+### Full
+
+```javascript
+import { Icon } from "flet-box";
+
+const action = Icon({
+  name: "notifications",
+  size: 24,
+  color: "#2563eb",
+  bgColor: "#eff6ff",
+  padding: 8,
+  borderRadius: 999,
+  className: "icon-button",
+  onPress: () => console.log("notifications"),
+});
+```
+
+## Tips
+
+- `size` defaults to 24 and `color` falls back to the theme's secondary text color.
+- Pass a Material Icons name such as `"settings"` or `"chevron_right"`.
+- Pair an icon with a visible label when it carries meaning, because the glyph alone is not descriptive.
+
+## Accessibility
+
+- Do not rely on the glyph to convey meaning on its own; add an adjacent text label for important actions.
+
+## Behavior
+
+- The icon renders as an inline-flex span using the Material Icons class, and it is non-selectable by default.
+- Supplying `onPress` makes the icon interactive; `size` accepts a number of pixels or a CSS size string.
+
+## Related widgets
+
+- [Button](Button.md)
+- [Text](Text.md)
+- [Row](Row.md)
+- [ListTile](ListTile.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Stack](Stack.md)
+- **Next:** [Image](Image.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 1 · First steps: the core mental model** (6 of 7).

package/docs/widget/Image.md

@@ -0,0 +1,125 @@
+# Image
+
+Renders an image element from a URL or path. Supports fixed sizing, object-fit modes, and a circular crop for avatars.
+
+## When to use it
+
+Use it whenever you need to show a photo, banner, thumbnail, or icon asset.
+
+## Quick start
+
+```javascript
+import { Image } from "flet-box";
+
+const photo = Image({
+  src: "/photo.jpg",
+  alt: "Profile photo",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `src` | `string` | Resource URL for the image, audio, or video. |
+| `alt` | `string` | Alternative text for an image, for accessibility. |
+| `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. |
+| `fit` | `'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'` | How the image fits its box (CSS `object-fit`). |
+| `circular` | `boolean` | Clips the image into a circle. |
+| `onLoad` | `(widget: Widget) => void` | Fired when the media finishes loading. |
+| `onError` | `(widget: Widget) => void` | Fired when the media fails to load. |
+| `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 { Image } from "flet-box";
+
+const cover = Image({
+  src: "/banner.jpg",
+  alt: "Launch banner",
+  width: 320,
+  height: 180,
+  fit: "cover",
+  borderRadius: 12,
+});
+```
+
+### Full
+
+```javascript
+import { Image } from "flet-box";
+
+const teamPhoto = Image({
+  src: "/team/anna.jpg",
+  alt: "Anna at the keynote",
+  width: 96,
+  height: 96,
+  fit: "cover",
+  circular: true,
+  onLoad: () => console.log("loaded"),
+  onError: () => console.error("failed"),
+  onPress: () => console.log("open profile"),
+});
+```
+
+## Tips
+
+- Set both width and height with fit: "cover" to avoid stretched or squashed art.
+- Use circular: true instead of a full borderRadius when you want a perfect avatar crop.
+
+## Accessibility
+
+- Always pass alt so screen readers can describe the image; alt: "" marks it decorative.
+
+## Behavior
+
+- onLoad fires once the image decodes; onError fires when the src fails to load.
+- onPress is attached to the wrapper, so the image behaves like a tappable tile.
+
+## Related widgets
+
+- [Avatar](Avatar.md)
+- [Card](Card.md)
+- [Icon](Icon.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Icon](Icon.md)
+- **Next:** [Button](Button.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 1 · First steps: the core mental model** (7 of 7).

package/docs/widget/Input.md

@@ -0,0 +1,151 @@
+# Input
+
+A text field that handles labels, placeholder text, input types, icons, validation, and change events in one widget.
+
+## When to use it
+
+Use it for any free-form text entry such as names, emails, passwords, or search.
+
+## Quick start
+
+```javascript
+import { Input } from "flet-box";
+
+const name = Input({
+  placeholder: "Your name",
+});
+```
+
+> 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. |
+| `placeholder` | `string` | Fallback text shown while the ad is unavailable. |
+| `type` | `'text' \| 'email' \| 'password' \| 'number' \| 'tel' \| 'search' \| 'url'` | Kind or mode of the widget. |
+| `label` | `string` | Label or caption shown near the control. |
+| `error` | `boolean \| string` | Error flag or message shown under the field. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `readonly` | `boolean` | Makes the field read-only while keeping it focusable. |
+| `required` | `boolean` | Marks the field as required and validates it. |
+| `size` | `'small' \| 'medium' \| 'large'` | Overall size preset or pixel value, depending on the widget. |
+| `variant` | `'outlined' \| 'filled' \| 'underlined'` | Visual variation or style preset. |
+| `fullWidth` | `boolean` | Stretches the widget to the full width of its parent. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `validation` | `'none' \| 'letters' \| 'numbers' \| 'email' \| 'alphanumeric' \| 'safe' \| 'custom'` | Built-in validation rule, such as `email` or `numbers`. |
+| `maxLength` | `number` | Maximum number of characters accepted. |
+| `iconLeft` | `string` | Icon shown to the left of the label. |
+| `iconRight` | `string` | Icon shown to the right of the label. |
+| `iconColor` | `Color` | Color of the field icons. |
+| `iconSize` | `number` | Size of the field icons. |
+| `onIconPress` | `() => void` | Fired when a field icon is pressed. |
+| `clearable` | `boolean` | Shows a button that clears the field. |
+| `passwordToggle` | `boolean` | Shows a button that reveals or hides a password. |
+| `showValidationMessage` | `boolean` | Shows the validation message under the field. |
+| `showValidationIcon` | `boolean` | Shows a valid/invalid icon inside the field. |
+| `customPattern` | `string` | Regular expression used by `validation: "custom"`. |
+| `onValidated` | `(isValid: boolean, message: string) => void` | Fired with `(isValid, message)` after validation. |
+| `onChange` | `(value: string, event?: Event) => void` | Fired when the value changes. |
+| `onInput` | `(value: string, event?: Event) => void` | Fired on every keystroke while typing. |
+| `onFocus` | `(event: Event) => void` | Fired when the control gains focus. |
+| `onBlur` | `(event: Event) => void` | Fired when the control loses focus. |
+| `onEnter` | `(value: string, event: Event) => void` | Fired when Enter is pressed in the field. |
+
+### 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 { Input } from "flet-box";
+
+const email = Input({
+  label: "Email",
+  type: "email",
+  placeholder: "you@example.com",
+  onChange: (value) => console.log(value),
+});
+```
+
+### Full
+
+```javascript
+import { Input } from "flet-box";
+
+const password = Input({
+  label: "Password",
+  type: "password",
+  placeholder: "Enter a password",
+  variant: "outlined",
+  size: "medium",
+  fullWidth: true,
+  borderRadius: 8,
+  required: true,
+  clearable: true,
+  passwordToggle: true,
+  iconLeft: "lock",
+  validation: "safe",
+  maxLength: 32,
+  showValidationMessage: true,
+  onChange: (value) => console.log(value),
+  onValidated: (isValid, message) => console.log(isValid, message),
+});
+```
+
+## Tips
+
+- Match type to the data (email, password, search) so mobile keyboards adapt.
+- Set validation and showValidationMessage to get inline feedback without extra code.
+
+## Accessibility
+
+- Always give a label or placeholder so the field has an accessible name.
+- error text is announced alongside the field when validation fails.
+
+## Behavior
+
+- onChange fires on every keystroke; onEnter fires when the user presses Enter.
+- clearable and passwordToggle add trailing controls that manage the value for you.
+
+## Related widgets
+
+- [Dropdown](Dropdown.md)
+- [Switch](Switch.md)
+- [Button](Button.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Button](Button.md)
+- **Next:** [Checkbox](Checkbox.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 2 · Interaction basics** (2 of 8).