flet-box 1.0.4 → 1.0.5

package/docs/widget/START_HERE.md

@@ -0,0 +1,146 @@
+# Start here
+
+Welcome to FletBox. This guide is for anyone who has never used FletBox before.
+
+## The simple idea
+
+A FletBox app is made from widgets. A widget is a small piece of the screen:
+
+- `Text` writes words.
+- `Button` gives the user something to press.
+- `Container` creates a box for grouping and styling.
+- `Row` places things from left to right.
+- `Column` places things from top to bottom.
+- `Image` displays a picture.
+- `Input` lets the user type.
+
+You combine these pieces to make a complete screen.
+
+## Your first widget
+
+Every widget is called like a JavaScript function. The object inside `({ ... })` contains its props.
+
+```javascript
+import { Text } from "flet-box";
+
+const title = Text({
+  text: "Hello FletBox",
+  size: 28,
+  color: "#111827",
+});
+```
+
+Read this as: create a text widget, write these words, make them this size, and use this color.
+
+## Put widgets inside widgets
+
+Use `child` for one child and `children` for a list of children.
+
+```javascript
+import { Column, Text } from "flet-box";
+
+const page = Column({
+  gap: 12,
+  children: [
+    Text({ text: "First line" }),
+    Text({ text: "Second line" }),
+  ],
+});
+```
+
+The `Column` places the two text widgets one below the other. A `Row` would place them next to each other.
+
+## Make a styled box
+
+```javascript
+import { Container, Text } from "flet-box";
+
+const card = Container({
+  width: 320,
+  padding: 20,
+  margin: "16px auto",
+  bgColor: "#eff6ff",
+  borderRadius: 12,
+  child: Text({ text: "A comfortable blue card" }),
+});
+```
+
+Common values:
+
+- A number such as `20` means pixels: `20px`.
+- A string such as `"100%"` uses a CSS size.
+- `padding` is space inside the widget.
+- `margin` is space outside the widget.
+- `bgColor` is the background color.
+- `color` is usually the text or foreground color.
+- `gap` is the space between children.
+
+## Add an action
+
+```javascript
+import { Button } from "flet-box";
+
+const saveButton = Button({
+  text: "Save",
+  bgColor: "#2563eb",
+  color: "#ffffff",
+  padding: "10px 18px",
+  onPress: () => {
+    console.log("The user pressed Save");
+  },
+});
+```
+
+The function after `onPress` runs when the user presses the button.
+
+## Build a small screen
+
+```javascript
+import { Button, Column, Container, Text } from "flet-box";
+
+const screen = Container({
+  width: "100%",
+  padding: 24,
+  bgColor: "#f8fafc",
+  child: Column({
+    gap: 16,
+    children: [
+      Text({ text: "Profile", type: "h1", size: 32, weight: "bold" }),
+      Text({ text: "Update your information below." }),
+      Button({
+        text: "Continue",
+        onPress: () => console.log("continue"),
+      }),
+    ],
+  }),
+});
+```
+
+This is the main FletBox pattern: create a parent, place children inside it, and describe each part with props.
+
+## What to read next
+
+The widget docs are organized as a book that goes from basic to advanced. Start at
+page 1 and follow the **Continue reading** links at the bottom of each page:
+
+1. Begin with [Text](Text.md), the first page of [Chapter 1](../README.md#the-reading-path).
+2. Read its small example first, then its full prop list.
+3. Copy the example and change one value.
+4. Follow **Next** to [Container](Container.md), then combine it with `Row` or `Column`.
+5. Use the [widget index](README.md) to jump anywhere in the book.
+
+When your screen needs an app bar, a drawer, bottom tabs, or a side bar, **Chapter 8 · App navigation** shows how those widgets compose the shell and talk to the [router](../guides/router.md).
+
+Every widget page uses the same structure, so learning one page helps you understand the others. Beyond their own props, all widgets share a common set of layout, spacing, color, and event props — see [Common props](COMMON_PROPS.md).
+
+FletBox intentionally supports friendly aliases for developers coming from Flet, Flutter, React, or vanilla JavaScript. Read the [syntax philosophy](../guides/syntax-philosophy.md) to see why equivalent styles such as `bgColor` / `backgroundColor`, `onPress` / `onClick`, and `child` / `children` can coexist.
+
+When you are ready to build a real application, continue with [State](../guides/state.md), [Routing](../guides/router.md), and [Utilities](../guides/utilities.md).
+
+---
+
+## Continue reading
+
+- **Previous:** [Your first FletBox app, step by step](../guides/first-app.md) — Chapter 0
+- **Next:** [Text](Text.md) — Chapter 1, page 1 of the widget book
+- **Index:** [The FletBox Book](../README.md)

package/docs/widget/Scaffold.md

@@ -0,0 +1,152 @@
+# Scaffold
+
+## Overview
+`Scaffold` is the application shell: a full-viewport flex column (`height: 100vh`, `overflow: hidden`) that mounts an optional `appBar` on top, a main content area in the middle, and a `bottomBar` at the bottom. It can also host a `fab` (absolutely positioned bottom-right), a `drawer` (slide-in panel), and fixed `leftNavBar`/`rightNavBar` side columns. When you pass `routes` — or put a route map in `body` — `Scaffold` turns into a **router shell**: it initializes the router, re-renders the body on navigation, and lets each route override the surrounding bars.
+
+Because it is an `HTMLElement`, you mount the whole app with `runApp(Scaffold({ ... }), "root")`.
+
+## When to use
+- Build the skeleton of a real application: top bar, content, bottom bar, and side navigation in one element.
+- Use its router mode to render the right screen per URL **and** swap the bars per route.
+- Give the app a fixed background and wrap a full-height layout without managing `height: 100vh` yourself.
+
+## Import
+
+```javascript
+import { Scaffold, AppBar, Text, colors } from "flet-box";
+```
+
+## Basic example
+
+The smallest useful version. Start here if this widget is new to you.
+
+```javascript
+import { Scaffold, AppBar, Text } from "flet-box";
+
+const app = Scaffold({
+  appBar: AppBar({ title: "My App" }),
+  body: Text({ text: "Welcome", size: 24, padding: 24 }),
+});
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `appBar` | Widget or boolean | — | Top bar. Pass `AppBar(...)`. `false` hides the top slot and any per-route top bar. |
+| `body` | Widget or route map | — | The main content. Pass a widget, **or** a `{ path: route }` map to enable router mode. |
+| `bottomBar` | Widget or boolean | — | Bottom bar (e.g. `BottomNavigation`). `false` hides it. |
+| `fab` | Widget or boolean | — | Floating action button slot, positioned `16px` from the bottom-right. |
+| `drawer` | Widget | — | A `Drawer` instance to embed; also auto-wired to a `menu` icon in the app bar. |
+| `leftNavBar` | Widget | — | Fixed left side column; the main area is narrowed by `leftNavBarWidth`. |
+| `leftNavBarWidth` | number | `260` | Width in pixels of the left column. |
+| `rightNavBar` | Widget | — | Fixed right side column, narrowed by `rightNavBarWidth`. |
+| `rightNavBarWidth` | number | `260` | Width in pixels of the right column. |
+| `navSideBar` | Widget | — | Legacy alias: routes to `leftNavBar` (or `rightNavBar` when `navSideBarPosition` is `"right"`). |
+| `navSideBarWidth` | number | `260` | Legacy width for `navSideBar`. |
+| `navSideBarPosition` | `'left'`/`'right'` | `'left'` | Legacy side for `navSideBar`. |
+| `routes` | object | — | `{ path: route }` map. Enables router mode (same as passing the map as `body`). |
+| `basePath` | string | auto | Deployment prefix the router prepends to every route, e.g. `"/flet-box-docs"`. Detected from the current URL when omitted. |
+| `backgroundColor` | Color | `colors.background` | Background of the shell. |
+| `closeDrawerOnNavigate` | boolean | `false` | When router mode navigates, close the drawer automatically. |
+
+These are the props specific to `Scaffold`. It also accepts every [common prop](COMMON_PROPS.md); extra props are applied to the root container.
+
+## Router mode
+
+If you pass a **route map** (via `routes` or as `body`), each route config is an object:
+
+```javascript
+import { Scaffold, AppBar, Text } from "flet-box";
+
+Scaffold({
+  routes: {
+    "/": { body: Text({ text: "Home" }), appBar: AppBar({ title: "Home" }) },
+    "/settings": {
+      body: Text({ text: "Settings" }),
+      appBar: false, // no top bar on this route
+    },
+  },
+});
+```
+
+Per-route keys the shell understands: `body` (the screen), `appBar`, `bottomBar`, `fab`, `leftNavBar`, `rightNavBar` — each can be a widget or `false`. Omitted keys fall back to the top-level props, and `undefined` values inherit the shell defaults.
+
+> Router mode calls `initRouter(routes, currentUrl)` once and subscribes the shell to router changes, so the body re-renders on `goTo`/back/forward. Read the [Routing guide](../guides/router.md) for the navigation helpers.
+
+## Instance methods
+
+- `updateLeftNavBar(cfg)` — show (`cfg` truthy), hide (`false`), or swap (`widget`) the left column.
+- `updateRightNavBar(cfg)` — same for the right column.
+- `setLeftNavBarWidth(width)` — resize the left column (pixels or CSS).
+- `setRightNavBarWidth(width)` — resize the right column.
+- `openDrawer()` / `closeDrawer()` — control the embedded drawer (when one was passed via `drawer`).
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { runApp, Scaffold, AppBar, BottomNavigation, Text } from "flet-box";
+
+const app = Scaffold({
+  appBar: AppBar({ title: "Store" }),
+  body: Text({ text: "Catalog" }),
+  bottomBar: BottomNavigation({
+    items: [
+      { icon: "home", label: "Home" },
+      { icon: "shopping_cart", label: "Cart" },
+    ],
+    useRouter: false,
+  }),
+});
+
+runApp(app, "root");
+```
+
+### Full example
+
+```javascript
+import { runApp, Scaffold, AppBar, DrawerItem, Drawer, Text, Icon } from "flet-box";
+
+const app = Scaffold({
+  appBar: AppBar({
+    title: "Menu",
+    leading: Icon({ name: "menu" }), // tapping it opens the drawer
+  }),
+  drawer: Drawer({
+    header: Text({ text: "Account", size: 18, weight: "bold", padding: 16 }),
+    body: [DrawerItem({ icon: "home", label: "Home", route: "/" })],
+  }),
+  leftNavBar: Icon({ name: "dashboard" }),
+  body: Text({ text: "Main content" }),
+});
+
+runApp(app, "root");
+```
+
+## Notes
+
+- The shell is a `<div>` with `display: flex; flex-direction: column; width: 100%; height: 100vh; position: relative; overflow: hidden` — mount it inside a container that fills the screen.
+- Side columns and the bottom bar are separate flex slots, not overlays; the content area is `overflow: auto` and expands to the remaining height.
+- A `menu` icon in the app bar closes the loop with the drawer: `Scaffold` finds the menu icon (`.material-icons` with text `menu`) and opens the drawer on click, after running any existing handler.
+- Route config objects with `body` only (no route keys) work too — the config itself is treated as the screen.
+- When a route is missing or a `goTo` targets an unknown path, the router console-logs an error (see the [Routing guide](../guides/router.md) for `*`/`/404` fallbacks).
+- `Scaffold` registers a `MutationObserver` on itself and wires `_cleanup` to disconnect it, unsubscribe from the router, and tear down every slot — listeners and observers do not leak when the shell is removed.
+
+## Related widgets
+- [AdaptiveScaffold](AdaptiveScaffold.md)
+- [AppBar](AppBar.md)
+- [Drawer](Drawer.md)
+- [BottomNavigation](BottomNavigation.md)
+- [CollapsibleSideBar](CollapsibleSideBar.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [DroppBox](DroppBox.md) — end of Chapter 7
+- **Next:** [AdaptiveScaffold](AdaptiveScaffold.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 8 · App navigation** (1 of 8).

package/docs/widget/Skeleton.md

@@ -0,0 +1,130 @@
+# Skeleton
+
+Skeleton renders animated placeholder blocks that stand in for content while it loads. It supports text, circular, avatar, image, card, listTile and button shapes.
+
+## When to use it
+
+Reach for it to keep layout stable and communicate loading instead of showing an empty screen or a spinner.
+
+## Quick start
+
+```javascript
+import { Skeleton } from "flet-box";
+
+const line = Skeleton({
+  width: "100%",
+  height: 16,
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `variant` | `'text' \| 'circular' \| 'avatar' \| 'image' \| 'card' \| 'listTile' \| 'button'` | Visual variation or style preset. |
+| `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. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `animation` | `'pulse' \| 'wave' \| 'none'` | The `animation` value for the widget. |
+| `count` | `number` | The `count` value for the widget. |
+| `gap` | `number` | Space between children along the layout axis. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `highlightColor` | `Color` | Color used for the highlight. |
+| `shimmerColor` | `Color` | Color used for the shimmer. |
+| `pulseDuration` | `string` | Duration for the pulse, in milliseconds. |
+| `waveDuration` | `string` | Duration for the wave, in milliseconds. |
+
+### 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 { Skeleton, pulse } from "flet-box";
+
+const article = Skeleton({
+  variant: "text",
+  width: "80%",
+  height: 14,
+  count: 3,
+  gap: 8,
+  animation: "pulse",
+});
+```
+
+### Full
+
+```javascript
+import { Skeleton } from "flet-box";
+
+const cardPlaceholder = Skeleton({
+  variant: "card",
+  width: 320,
+  height: 180,
+  borderRadius: 12,
+  animation: "wave",
+  bgColor: "#e5e7eb",
+  highlightColor: "#f3f4f6",
+  shimmerColor: "#ffffff",
+  gap: 12,
+});
+```
+
+## Tips
+
+- Match the skeleton variant and height to the real content so the layout does not jump when data arrives.
+- Set count together with gap to mock a list of rows instead of nesting many Skeleton widgets.
+- Use animation: "none" when many placeholders would otherwise distract or hurt performance.
+
+## Accessibility
+
+- Wrap the loading region with a status label so screen readers know content is still pending.
+- Prefer animation: "none" when the user has requested reduced motion.
+
+## Behavior
+
+- The pulse/wave shimmer runs as a CSS animation and is cleaned up automatically when the widget unmounts.
+- Changing variant, width or height through the reactive setter re-renders the placeholder in place.
+
+## Related widgets
+
+- [ProgressBar](ProgressBar.md)
+- [CircularBar](CircularBar.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [CircularBar](CircularBar.md)
+- **Next:** [FloatingActionButton](FloatingActionButton.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 4 · Feedback and overlays** (8 of 10).

package/docs/widget/Slider.md

@@ -0,0 +1,146 @@
+# Slider
+
+A draggable range input that selects a numeric value along a track between min and max.
+
+## When to use it
+
+Use Slider when a value benefits from direct manipulation, such as volume, price or opacity.
+
+## Quick start
+
+```javascript
+import { Slider } from "flet-box";
+
+const volume = Slider({
+  value: 40,
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value` | `number` | Current value controlled by the widget. |
+| `min` | `number` | Minimum allowed value. |
+| `max` | `number` | Maximum value used to compute the ratio. |
+| `step` | `number` | Increment between allowed slider values. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `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. |
+| `thumbSize` | `number` | Size of the slider thumb. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `trackColor` | `Color` | Color of the slider track. |
+| `orientation` | `'horizontal' \| 'vertical'` | Orientation of the widget or control. |
+| `inverted` | `boolean` | Reverses the direction of the control. |
+| `showValue` | `boolean` | Shows the numeric value next to the indicator. |
+| `valuePrefix` | `string` | Text prepended before the displayed value. |
+| `valueSuffix` | `string` | Text appended after the displayed value. |
+| `showMarks` | `boolean` | Controls whether the marks is shown. |
+| `marks` | `Array<{ value: number; label?: string; color?: Color; size?: number }>` | The `marks` value for the widget. |
+| `striped` | `boolean` | Draws diagonal stripes across the bar. |
+| `animatedStripes` | `boolean` | Animates the stripes on the bar. |
+| `stripeColor` | `string` | Color used for the stripe. |
+| `glow` | `boolean` | Adds a glow around the widget. |
+| `onPress` | `(value: number) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onChanged` | `(value: number) => void` | Event handler for the `onChanged` event. |
+| `onChangeEnd` | `(value: number) => void` | Event handler for the `onChangeEnd` event. |
+
+### 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 { Slider } from "flet-box";
+
+const volume = Slider({
+  value: 60,
+  min: 0,
+  max: 100,
+  step: 5,
+  onChanged: (value) => console.log("volume:", value),
+});
+```
+
+### Full
+
+```javascript
+import { Slider } from "flet-box";
+
+const price = Slider({
+  value: 250,
+  min: 0,
+  max: 1000,
+  step: 50,
+  color: "#2563eb",
+  trackColor: "#e2e8f0",
+  thumbSize: 24,
+  showValue: true,
+  valuePrefix: "$",
+  showMarks: true,
+  marks: [
+    { value: 0, label: "$0" },
+    { value: 500, label: "$500" },
+    { value: 1000, label: "$1000" },
+  ],
+  onChanged: (value) => console.log("price:", value),
+  onChangeEnd: (value) => console.log("final:", value),
+});
+```
+
+## Tips
+
+- onChanged fires continuously while dragging; use onChangeEnd for the value to commit, such as a filter request.
+- Set step to snap to meaningful increments instead of every integer.
+
+## Accessibility
+
+- A slider needs a visible label or value text; showValue displays the current value so it is not conveyed by thumb position alone.
+
+## Behavior
+
+- Dragging the track or thumb updates the value and fires onChanged; releasing fires onChangeEnd once.
+- The returned element exposes value, min, max, step, setValue() and getValue(), and disconnects its ResizeObserver on unmount.
+
+## Related widgets
+
+- [Rating](Rating.md)
+- [ProgressBar](ProgressBar.md)
+- [Input](Input.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Switch](Switch.md)
+- **Next:** [Dropdown](Dropdown.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 2 · Interaction basics** (6 of 8).

package/docs/widget/SnackBar.md

@@ -0,0 +1,102 @@
+# SnackBar
+
+A transient toast that appears at the edge of the screen, reports a short message, and dismisses itself.
+
+## When to use it
+
+Use SnackBar to confirm a completed action or surface a brief, non-blocking notice.
+
+## Quick start
+
+```javascript
+import { SnackBar } from "flet-box";
+
+const toast = SnackBar({
+  message: "Saved",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `message` | `string` | Body text or notification content. |
+| `action` | `string` | The `action` value for the widget. |
+| `onAction` | `() => void` | Event handler for the `onAction` event. |
+| `duration` | `number` | How long the transient element stays visible, in milliseconds. |
+| `type` | `'normal' \| 'success' \| 'error' \| 'warning' \| 'info'` | Kind or mode of the widget. |
+| `position` | `'bottom' \| 'top'` | CSS `position` value, or `stack` for centered stacking. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
+| `textColor` | `Color` | Color of the button label. |
+| `actionColor` | `Color` | Color used for the action. |
+| `dismissible` | `boolean` | The `dismissible` value for the widget. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `padding` | `number \| string` | Space inside the widget, between its content and its border. |
+| `margin` | `number \| string` | Space outside the widget, between it and its neighbors. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `animationDuration` | `number` | Duration for the animation, in milliseconds. |
+| `zIndex` | `number` | Index used for the z. |
+| `onShow` | `() => void` | Event handler for the `onShow` event. |
+| `onClose` | `() => void` | Fired when the overlay closes. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { SnackBar } from "flet-box";
+
+const toast = SnackBar({
+  message: "Changes saved",
+  type: "success",
+  duration: 3000,
+});
+```
+
+### Full
+
+```javascript
+import { SnackBar } from "flet-box";
+
+const toast = SnackBar({
+  message: "Could not reach the server",
+  type: "error",
+  duration: 5000,
+  bgColor: "#1e293b",
+  color: "#ffffff",
+  borderRadius: 12,
+  elevation: 3,
+});
+```
+
+## Tips
+
+- Keep message short and use SnackBar for confirmations, not for information the user must act on.
+- A duration of 0 keeps the toast open until you call close(); otherwise it auto-dismisses.
+
+## Accessibility
+
+- A SnackBar disappears on its own, so make sure the same information is available elsewhere and never required reading.
+
+## Behavior
+
+- The element is appended to document.body and auto-removed after duration; the returned controller has show(), close() and getElement().
+- Calling close() early cancels the pending dismissal timer and slides the toast out.
+
+## Related widgets
+
+- [AlertDialog](AlertDialog.md)
+- [Modal](Modal.md)
+- [Button](Button.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [BottomSheet](BottomSheet.md)
+- **Next:** [Tooltip](Tooltip.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 4 · Feedback and overlays** (4 of 10).