flet-box 1.0.4 → 1.0.6

package/docs/widget/Avatar.md

@@ -0,0 +1,119 @@
+# Avatar
+
+A compact identity chip that shows a profile image, the person's initials, or a fallback icon. It falls back gracefully when no image is available.
+
+## When to use it
+
+Reach for it in headers, comments, list rows, and any place a user needs a face.
+
+## Quick start
+
+```javascript
+import { Avatar } from "flet-box";
+
+const user = Avatar({
+  name: "Ada Lovelace",
+});
+```
+
+> 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. |
+| `name` | `string` | The `name` value for the widget. |
+| `icon` | `string` | Name of the icon to render. |
+| `size` | `number` | Overall size preset or pixel value, depending on the widget. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `textColor` | `Color` | Color of the button label. |
+| `shape` | `'circle' \| 'rounded' \| 'square'` | The `shape` value for the widget. |
+| `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 { Avatar } from "flet-box";
+
+const user = Avatar({
+  src: "/avatars/ada.png",
+  name: "Ada Lovelace",
+  size: 48,
+  shape: "circle",
+});
+```
+
+### Full
+
+```javascript
+import { Avatar } from "flet-box";
+
+const user = Avatar({
+  src: "/avatars/ada.png",
+  name: "Ada Lovelace",
+  size: 64,
+  shape: "rounded",
+  bgColor: "#2563eb",
+  textColor: "#ffffff",
+  onPress: () => console.log("open profile"),
+});
+```
+
+## Tips
+
+- Provide both src and name so initials render if the image fails.
+- Use shape: "circle" for people and shape: "rounded" for organizations or bots.
+
+## Accessibility
+
+- The name prop is announced as the label, so always give a meaningful name.
+
+## Behavior
+
+- When src is missing or errors, the widget automatically shows initials from name.
+- onPress makes the whole avatar interactive, which is useful for opening profiles.
+
+## Related widgets
+
+- [Image](Image.md)
+- [ListTile](ListTile.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [GridView](GridView.md)
+- **Next:** [Badge](Badge.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 3 · Layout, cards and lists** (6 of 8).

package/docs/widget/Badge.md

@@ -0,0 +1,128 @@
+# Badge
+
+Wraps a child widget and overlays a small count or status marker at one of its corners. Commonly used for notification counts.
+
+## When to use it
+
+Use it to signal unseen items or status on an icon, avatar, or button.
+
+## Quick start
+
+```javascript
+import { Badge, Icon } from "flet-box";
+
+const badge = Badge({
+  value: 5,
+  child: Icon({ name: "notifications" }),
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value` | `string \| number` | Current value controlled by the widget. |
+| `child` | `Widget` | A single child widget. Alias: `children` for a list. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `size` | `number` | Overall size preset or pixel value, depending on the widget. |
+| `position` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | CSS `position` value, or `stack` for centered stacking. |
+| `offset` | `number` | The `offset` value for the widget. |
+| `borderWidth` | `number` | Width of the border. |
+| `borderColor` | `Color` | Color used for the border. |
+| `showZero` | `boolean` | Controls whether the zero is shown. |
+| `max` | `number` | Maximum value used to compute the ratio. |
+
+### 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 { Badge, Icon } from "flet-box";
+
+const inbox = Badge({
+  value: 12,
+  max: 99,
+  bgColor: "#dc2626",
+  color: "#ffffff",
+  child: Icon({ name: "mail" }),
+});
+```
+
+### Full
+
+```javascript
+import { Badge, Icon } from "flet-box";
+
+const inbox = Badge({
+  value: 120,
+  max: 99,
+  bgColor: "#dc2626",
+  color: "#ffffff",
+  size: 18,
+  position: "top-right",
+  offset: 4,
+  borderWidth: 2,
+  borderColor: "#ffffff",
+  showZero: false,
+  child: Icon({ name: "mail", size: 28 }),
+});
+```
+
+## Tips
+
+- Set max so large counts collapse to "99+" style displays.
+- Use position and offset to place the marker precisely on irregular shapes.
+
+## Accessibility
+
+- The badge value is visual only; add a Text or title nearby to convey the count.
+
+## Behavior
+
+- showZero: false hides the marker entirely when value is 0.
+- A borderWidth with a matching borderColor creates a clean cutout against the child.
+
+## Related widgets
+
+- [Avatar](Avatar.md)
+- [Icon](Icon.md)
+- [Chip](Chip.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Avatar](Avatar.md)
+- **Next:** [Chip](Chip.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 3 · Layout, cards and lists** (7 of 8).

package/docs/widget/BottomNavigation.md

@@ -0,0 +1,116 @@
+# BottomNavigation
+
+## Overview
+`BottomNavigation` renders a bottom tab bar as a `<nav>` flex row. Each `item` shows an `icon` (and an optional `label` below it). With `useRouter: true` (the default) tapping a tab calls `goTo(route)` and the active state follows the URL; with `useRouter: false` the bar keeps its own `currentIndex` and reports changes through `onTabChange`. It is sticky-sized for the bottom of a [Scaffold](Scaffold.md)'s `bottomBar` slot.
+
+## When to use
+- Give a phone-style app its primary navigation at the bottom.
+- Keep the active tab in sync with the router so deep links highlight the right tab.
+
+## Import
+
+```javascript
+import { BottomNavigation } from "flet-box";
+```
+
+## Basic example
+
+The smallest useful version. Start here if this widget is new to you.
+
+```javascript
+import { BottomNavigation } from "flet-box";
+
+BottomNavigation({
+  items: [
+    { icon: "home", label: "Home" },
+    { icon: "shopping_cart", label: "Cart" },
+  ],
+  useRouter: false,
+});
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | array | `[]` | Tab descriptors: `{ icon, label?, route?, onPress? }`. Only `icon` is required. |
+| `currentIndex` | number | `0` | Initial active tab (used only when `useRouter` is false). |
+| `onTabChange` | function | — | Called with the active index after a change (and, in router mode, with the synced index). |
+| `useRouter` | boolean | `true` | When true, taps call `goTo(route)` and selection follows the current path. |
+| `backgroundColor` | Color | `colors.surface` | Bar background. |
+| `selectedColor` | Color | `colors.primary` | Icon/label color of the active tab. |
+| `unselectedColor` | Color | `colors.textSecondary` | Color of inactive tabs. |
+| `showLabels` | boolean | `true` | Show the label under each icon. |
+| `iconSize` | number | `24` | Icon size in pixels. |
+| `height` | number | `65` | Bar height in pixels. |
+| `margin`/`marginTop`/… | number or string | `0` | Outer spacing (the bar shrinks to `calc(100% - margins)`). |
+| `padding` | number or string | `0` | Inner padding. |
+| `borderRadius` | number or string | `0` | Corner radius. |
+| `shadow` | boolean or string | `true` | `true` uses the shadow map for `elevation`; a CSS string is applied directly; `false` removes it. |
+| `elevation` | number (0-5) | `2` | Shadow level used when `shadow` is `true`. |
+
+These are the props specific to `BottomNavigation`. Item routes default to `/${label?.toLowerCase()}`, so `{ icon: "home", label: "Home" }` targets `/home`.
+
+## Instance methods
+
+- `setActiveIndex(index)` — select a tab programmatically. In router mode it navigates to the item's route; otherwise it switches and fires `onTabChange`/`onPress`.
+- `getActiveIndex()` — the current index.
+- `getCurrentRoute()` — the current router path (always `null` when `useRouter` is false).
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { BottomNavigation } from "flet-box";
+
+BottomNavigation({
+  items: [
+    { icon: "home", label: "Home" },
+    { icon: "search", label: "Search" },
+    { icon: "person", label: "Profile" },
+  ],
+  useRouter: false,
+  onTabChange: (index) => console.log("tab", index),
+});
+```
+
+### Full example
+
+```javascript
+import { runApp, Scaffold, Text, BottomNavigation } from "flet-box";
+
+const app = Scaffold({
+  body: Text({ text: "Main screen" }),
+  bottomBar: BottomNavigation({
+    items: [
+      { icon: "home", label: "Home", route: "/", onPress: () => console.log("tap home") },
+      { icon: "settings", label: "Settings", route: "/settings" },
+    ],
+  }),
+});
+
+runApp(app, "root");
+```
+
+## Notes
+
+- In router mode the bar subscribes to router changes and re-highlights on `goTo`, back, and forward navigation — one source of truth for the active tab.
+- The active item gets `font-weight: 500` on its label and the selected/unselected colors on both icon and label.
+- Item `onPress` fires after navigation (router mode) or after the local switch (non-router mode).
+- `_cleanup` unsubscribes from the router, so removing the bar never leaves stale listeners.
+
+## Related widgets
+- [Scaffold](Scaffold.md)
+- [Tabs](Tabs.md)
+- [Drawer](Drawer.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [DrawerItem](DrawerItem.md)
+- **Next:** [Tabs](Tabs.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 8 · App navigation** (6 of 8).

package/docs/widget/BottomSheet.md

@@ -0,0 +1,125 @@
+# BottomSheet
+
+A panel that slides up from the bottom of the screen over a dimmed overlay.
+
+## When to use it
+
+Use BottomSheet for short, task-focused panels such as filters, share sheets or quick forms.
+
+## Quick start
+
+```javascript
+import { BottomSheet, Text } from "flet-box";
+
+const sheet = BottomSheet({
+  content: Text({ text: "Choose an action" }),
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `content` | `Widget` | Main content of the overlay. |
+| `title` | `string` | Title text shown in the header. |
+| `actions` | `Widget[]` | Widgets rendered in the overlay footer. |
+| `height` | `number \| string` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `maxHeight` | `number \| string` | Maximum height the widget may grow to. |
+| `showDragHandle` | `boolean` | Shows the drag handle above the sheet. |
+| `closeOnOverlayClick` | `boolean` | Closes the overlay when the backdrop is clicked. |
+| `closeOnDragDown` | `boolean` | Closes the sheet when dragged down. |
+| `showCloseButton` | `boolean` | Shows a close button in the header. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
+| `overlayColor` | `Color` | Color of the dimmed backdrop behind the overlay. |
+| `dragHandleColor` | `Color` | Color used for the drag handle. |
+| `headerTextColor` | `Color` | Text color of the header row. |
+| `headerBorderColor` | `Color` | Border color for the header. |
+| `actionBorderColor` | `Color` | Border color for the action. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `headerPadding` | `Padding` | Padding for the header. |
+| `contentPadding` | `Padding` | Padding for the content. |
+| `actionPadding` | `Padding` | Padding for the action. |
+| `dragHandlePadding` | `Padding` | Padding for the drag handle. |
+| `dragHandleWidth` | `number` | Width of the drag handle. |
+| `dragHandleHeight` | `number` | Height of the drag handle. |
+| `animationDuration` | `number` | Duration for the animation, in milliseconds. |
+| `zIndex` | `number` | Index used for the z. |
+| `overlayZIndex` | `number` | Index used for the overlay z. |
+| `onOpen` | `() => void` | Fired when the overlay opens. |
+| `onClose` | `() => void` | Fired when the overlay closes. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { BottomSheet, Text } from "flet-box";
+
+const sheet = BottomSheet({
+  title: "Share",
+  content: Text({ text: "Share this document with your team." }),
+  closeOnOverlayClick: true,
+  onClose: () => console.log("closed"),
+});
+```
+
+### Full
+
+```javascript
+import { BottomSheet, Button, Checkbox, Column, Switch, rgba } from "flet-box";
+
+const filters = BottomSheet({
+  title: "Filters",
+  height: "60%",
+  showDragHandle: true,
+  closeOnDragDown: true,
+  closeOnOverlayClick: true,
+  showCloseButton: true,
+  backgroundColor: "#ffffff",
+  overlayColor: "rgba(15, 23, 42, 0.4)",
+  borderRadius: 20,
+  content: Column({
+    gap: 12,
+    children: [Switch({ label: "In stock" }), Checkbox({ label: "On sale" })],
+  }),
+  actions: [
+    Button({ text: "Reset", variant: "text" }),
+    Button({ text: "Apply", onPress: () => filters.close() }),
+  ],
+  onOpen: () => console.log("opened"),
+  onClose: () => console.log("closed"),
+});
+```
+
+## Tips
+
+- Reach for BottomSheet for lightweight panels and Modal when the content needs the user's full attention.
+- closeOnDragDown only works together with a drag handle, so keep showDragHandle: true when enabling it.
+
+## Accessibility
+
+- Give the sheet a title so the panel has an accessible name, and keep the close action reachable by keyboard.
+
+## Behavior
+
+- Returns a controller with open, close, toggle and destroy; the overlay stays hidden until open() is called.
+- Overlay clicks and Escape close the sheet, onOpen/onClose fire as it animates, and destroy() releases the listeners.
+
+## Related widgets
+
+- [Modal](Modal.md)
+- [AlertDialog](AlertDialog.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Modal](Modal.md)
+- **Next:** [SnackBar](SnackBar.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 4 · Feedback and overlays** (3 of 10).

package/docs/widget/Button.md

@@ -0,0 +1,137 @@
+# Button
+
+Interactive button with filled, outlined, and text variants, size presets, optional icons, and press feedback.
+
+## When to use it
+
+Use Button for actions such as submit, save, confirm, or any primary and secondary command.
+
+## Quick start
+
+```javascript
+import { Button } from "flet-box";
+
+const save = Button({
+  text: "Save",
+});
+```
+
+> 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. |
+| `onPress` | `() => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `variant` | `'filled' \| 'outlined' \| 'text'` | Visual variation or style preset. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `gradient` | `string` | CSS gradient used as the fill. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `textColor` | `Color` | Color of the button label. |
+| `size` | `'small' \| 'medium' \| 'large'` | Overall size preset or pixel value, depending on the widget. |
+| `fullWidth` | `boolean` | Stretches the widget to the full width of its parent. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `icon` | `string` | Name of the icon to render. |
+| `iconLeft` | `string` | Icon shown to the left of the label. |
+| `iconRight` | `string` | Icon shown to the right of the label. |
+| `iconTop` | `string` | Icon shown above the label. |
+| `iconBottom` | `string` | Icon shown below the label. |
+| `iconPosition` | `'left' \| 'right' \| 'top' \| 'bottom'` | Where the icon sits relative to the label. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | 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 { Button } from "flet-box";
+
+const save = Button({
+  text: "Save",
+  bgColor: "#2563eb",
+  color: "#ffffff",
+  borderRadius: 8,
+  onPress: () => console.log("saved"),
+});
+```
+
+### Full
+
+```javascript
+import { Button } from "flet-box";
+
+const checkout = Button({
+  text: "Checkout",
+  variant: "filled",
+  size: "large",
+  gradient: "linear-gradient(90deg, #2563eb, #7c3aed)",
+  color: "#ffffff",
+  icon: "shopping_cart",
+  iconPosition: "right",
+  borderRadius: 28,
+  elevation: 3,
+  fullWidth: true,
+  onPress: () => console.log("checkout"),
+});
+```
+
+## Tips
+
+- `variant` defaults to `"filled"`; switch to `"outlined"` or `"text"` for secondary actions.
+- Place icons with `icon` and `iconPosition`, or use the explicit `iconLeft`, `iconRight`, `iconTop`, `iconBottom` props.
+- Setting `disabled` also drops the click handler, not just the styling.
+
+## Accessibility
+
+- Always pass `text` so the button has an accessible name, and use `disabled` rather than only dimming colors.
+
+## Behavior
+
+- Size presets control padding, font size, and icon size; `fullWidth` stretches the button to 100%.
+- `onPress` receives no arguments and is wired to the native click; `elevation` picks a shadow level.
+
+## Related widgets
+
+- [Icon](Icon.md)
+- [Row](Row.md)
+- [Column](Column.md)
+- [FloatingActionButton](FloatingActionButton.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Image](Image.md)
+- **Next:** [Input](Input.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 2 · Interaction basics** (1 of 8).