flet-box 1.0.3 → 1.0.5

package/docs/widget/AlertDialog.md

@@ -0,0 +1,103 @@
+# AlertDialog
+
+A pre-styled confirmation dialog built on Modal, with a variant icon, message and confirm/cancel buttons.
+
+## When to use it
+
+Use AlertDialog when you need an explicit confirm or cancel decision from the user.
+
+## Quick start
+
+```javascript
+import { AlertDialog } from "flet-box";
+
+const alert = AlertDialog({
+  title: "Delete file?",
+  message: "This action cannot be undone.",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | Title text shown in the header. |
+| `message` | `string` | Body text or notification content. |
+| `confirmText` | `string` | Label of the confirm button. |
+| `cancelText` | `string` | Label of the cancel button. |
+| `onConfirm` | `() => void` | Fired when the confirm action is pressed. |
+| `onCancel` | `() => void` | Fired when the cancel action is pressed. |
+| `onClose` | `() => void` | Fired when the overlay closes. |
+| `variant` | `'normal' \| 'danger' \| 'warning' \| 'success'` | Visual variation or style preset. |
+| `showCancel` | `boolean` | Shows the cancel button. |
+| `width` | `number` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { AlertDialog } from "flet-box";
+
+const alert = AlertDialog({
+  title: "Remove item",
+  message: "The item will be moved to trash.",
+  confirmText: "Remove",
+  cancelText: "Keep",
+  onConfirm: () => console.log("removed"),
+  onCancel: () => console.log("kept"),
+});
+```
+
+### Full
+
+```javascript
+import { AlertDialog } from "flet-box";
+
+const alert = AlertDialog({
+  title: "Delete account",
+  message: "All data will be permanently erased.",
+  variant: "danger",
+  confirmText: "Delete",
+  cancelText: "Cancel",
+  showCancel: true,
+  width: 360,
+  borderRadius: 20,
+  onConfirm: () => console.log("confirmed"),
+  onCancel: () => console.log("cancelled"),
+  onClose: () => console.log("closed"),
+});
+```
+
+## Tips
+
+- Pick the variant that matches intent: danger for destructive actions, success for confirmations, warning when the user should pause.
+- Set showCancel: false only for acknowledgements; most confirmations should let the user back out.
+
+## Accessibility
+
+- State the consequence in message and name the buttons by action such as Delete and Cancel instead of a generic OK.
+
+## Behavior
+
+- AlertDialog is a preset Modal: it returns { open, close, modal } and must be shown by calling open().
+- onConfirm and onCancel run before the dialog closes; onClose fires for every dismissal, including Escape or overlay click.
+
+## Related widgets
+
+- [Modal](Modal.md)
+- [SnackBar](SnackBar.md)
+- [Button](Button.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Chip](Chip.md)
+- **Next:** [Modal](Modal.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 4 · Feedback and overlays** (1 of 10).

package/docs/widget/AnimatedBox.md

@@ -0,0 +1,130 @@
+# AnimatedBox
+
+Wraps a single child and plays a sequence of CSS animations described by effect/from/to steps. It handles keyframes, timing, and fill mode for you.
+
+## When to use it
+
+Use it to animate a widget's position, transform, color, or size without hand-writing CSS keyframes.
+
+## Quick start
+
+```javascript
+import { AnimatedBox, Text, pulse } from "flet-box";
+
+const pulse = AnimatedBox({
+  child: Text({ text: "Hello" }),
+  animations: [{ effect: "scale", from: 1, to: 1.2 }],
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `animations` | `AnimationStep[]` | Animations to apply, as a name or an array of names. |
+| `child` | `Widget` | A single child widget. Alias: `children` for a list. |
+| `timing` | `string` | Timing function for the animation. |
+| `delay` | `string` | Delay before the animation starts, in milliseconds. |
+| `fillMode` | `string` | How styles persist before and after the animation (CSS `fill-mode`). |
+| `top` | `number \| string` | The `top` value for the widget. |
+| `right` | `number \| string` | The `right` value for the widget. |
+| `bottom` | `number \| string` | The `bottom` value for the widget. |
+| `left` | `number \| string` | The `left` value for the widget. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { AnimatedBox, Card, Text } from "flet-box";
+
+const hero = AnimatedBox({
+  child: Card({ child: Text({ text: "FletBox" }) }),
+  animations: [
+    { effect: "opacity", from: 0, to: 1 },
+    { effect: "translateY", from: 20, to: 0 },
+  ],
+  timing: "ease-out",
+});
+```
+
+### Full
+
+```javascript
+import { AnimatedBox, Text } from "flet-box";
+
+const toast = AnimatedBox({
+  child: Text({ text: "Saved" }),
+  animations: [{ effect: "opacity", from: 0, to: 1 }],
+  timing: "ease-in-out",
+  delay: "200ms",
+  fillMode: "forwards",
+  top: 16,
+  right: 16,
+});
+```
+
+## Tips
+
+- Each animation is { effect, from, to } where effect is a CSS property like opacity,
+- scale, translateY, or backgroundColor.
+- Set timing (ease, ease-out, linear) and delay at the widget level; per-step reverse
+- cycles the animation back instead of running it once.
+- top, right, bottom, and left are forwarded to the child as positioning hints for
+- layout systems.
+
+## Accessibility
+
+- Honor prefers-reduced-motion by keeping animations subtle or giving users a way to
+- disable them.
+
+## Behavior
+
+- The first animation step is applied as an inline style immediately, so there is no
+- flash of the final state before the keyframes run.
+- Generated @keyframes are injected once per sequence and reused, so repeated
+- animations stay cheap.
+
+## Related widgets
+
+- [AnimatedText](AnimatedText.md)
+- [Text](Text.md)
+- [Container](Container.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [AdMob](AdMob.md)
+- **Next:** [AnimatedText](AnimatedText.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 6 · Data, rich content & effects** (10 of 13).

package/docs/widget/AnimatedText.md

@@ -0,0 +1,123 @@
+# AnimatedText
+
+Splits a Text widget into individual characters and animates each one, optionally staggering the start of every letter for a cascade effect.
+
+## When to use it
+
+Use it for headline entrances, logo reveals, or any place letter-by-letter motion adds polish.
+
+## Quick start
+
+```javascript
+import { AnimatedText, Text } from "flet-box";
+
+const title = AnimatedText({
+  child: Text({ text: "FletBox" }),
+  animations: [{ effect: "translateY", from: 16, to: 0 }],
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `child` | `Widget` | A single child widget. Alias: `children` for a list. |
+| `animations` | `AnimationStep[]` | Animations to apply, as a name or an array of names. |
+| `sameTime` | `boolean` | Runs child animations at the same time. |
+| `delayBetween` | `number` | Stagger delay between each child animation. |
+| `orientation` | `'row' \| 'column'` | Orientation of the widget or 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 { AnimatedText, Text } from "flet-box";
+
+const title = AnimatedText({
+  child: Text({ text: "Hello world" }),
+  animations: [{ effect: "opacity", from: 0, to: 1 }],
+  sameTime: false,
+  delayBetween: 0.08,
+});
+```
+
+### Full
+
+```javascript
+import { AnimatedText, Text } from "flet-box";
+
+const title = AnimatedText({
+  child: Text({ text: "Welcome" }),
+  animations: [
+    { effect: "scale", from: 0.5, to: 1 },
+    { effect: "rotate", from: -8, to: 0 },
+  ],
+  sameTime: true,
+  orientation: "column",
+});
+```
+
+## Tips
+
+- child must be a Text widget, because its text is split into single-character
+- widgets that inherit the original props.
+- Set sameTime: false and control delayBetween to create a wave; use sameTime: true
+- for a synchronized pop.
+- orientation: "column" stacks the letters vertically for vertical-word effects.
+
+## Accessibility
+
+- The animated letters remain ordinary text, so screen readers still read the full
+- word; avoid animating for longer than a moment.
+
+## Behavior
+
+- Spaces are rendered as fixed-width spacers rather than animated characters, keeping
+- word breaks intact.
+- If animations is empty the original child is returned unchanged, so you can branch
+- cheaply.
+
+## Related widgets
+
+- [AnimatedBox](AnimatedBox.md)
+- [Text](Text.md)
+- [Container](Container.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [AnimatedBox](AnimatedBox.md)
+- **Next:** [MatrixRain](MatrixRain.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 6 · Data, rich content & effects** (11 of 13).

package/docs/widget/AppBar.md

@@ -0,0 +1,118 @@
+# AppBar
+
+## Overview
+`AppBar` renders a top bar as a `<header>` flex row (`min-height: 56px`). It has three zones: a left **leading** slot (icon), a **title** (string or widget), and a right **actions** slot (a row of widgets). `sticky` keeps it attached to the top of the viewport; `hideOnScroll` collapses it when you scroll down. When `showBackButton` is set, `AppBar` builds an automatic back arrow that goes back in history (or to `backButtonRoute`), and it can be wired to open a `Scaffold` drawer through a `menu` leading icon.
+
+## When to use
+- Give a screen a title and a place for commands (search, refresh, avatar).
+- Show breadcrumb-style navigation with an automatic back arrow.
+- Put a persistent header above scrollable content with `sticky: true`.
+
+## Import
+
+```javascript
+import { AppBar, Text } from "flet-box";
+```
+
+## Basic example
+
+The smallest useful version. Start here if this widget is new to you.
+
+```javascript
+import { AppBar } from "flet-box";
+
+AppBar({ title: "Profile" });
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | string or Widget | — | The title text, or a custom element to render. |
+| `leading` | Widget | `null` | Left slot (e.g. a `menu` `Icon`). Must be an `HTMLElement` to be shown. |
+| `actions` | Widget[] | `[]` | Right slot items; only elements pass the filter in. |
+| `actionsGap` | number | `12` | Spacing between the action items. |
+| `backgroundColor` | Color | `colors.surface` | Bar background. |
+| `gradient` | string | `null` | A CSS `background` image (from the `gradient(...)` helper) — overrides `backgroundColor`. |
+| `titleColor` | Color | `colors.text` | Title color. |
+| `iconColor` | Color | `titleColor` | Color of the leading/back icon. |
+| `titleSize` | number | `20` | Title font size. |
+| `titleWeight` | string | `"500"` | Title font weight. |
+| `centerTitle` | boolean | `false` | Center the title instead of left-aligning it. |
+| `elevation` | number (0-5) | `2` | Shadow level used when `shadow` is `true`. |
+| `shadow` | boolean or string | `true` | `true` uses the shadow map for `elevation`; a CSS string is applied directly; `false` removes it. |
+| `showBackButton` | boolean | `false` | Add an automatic `arrow_back` leading icon that navigates back. |
+| `backButtonRoute` | string | `null` | The back icon goes to this route instead of `goBack()`. |
+| `onBackPress` | function | `null` | Custom handler for the back icon (wins over the route). |
+| `sticky` | boolean | `true` | `position: sticky; top: 0` so the bar stays on top. |
+| `hideOnScroll` | boolean | `false` | Slide the bar up and fade it when scrolling down past `scrollThreshold`. |
+| `scrollThreshold` | number | `100` | Scroll distance (px) at which `hideOnScroll` kicks in. |
+| `margin`/`marginTop`/… | number or string | `0` | Outer spacing. |
+| `padding`/`paddingTop`/… | number or string | left `4`, right `24`, others `0` | Inner padding of the bar. |
+| `borderRadius` | number or string | `0` | Corner radius. |
+
+These are the props specific to `AppBar`. It also accepts every [common prop](COMMON_PROPS.md); extra props are applied to the `header` element.
+
+## Instance methods
+
+- `setTitle(text)` — replace the title string in place.
+- `setBackgroundColor(color)` — set a solid color, or a `gradient` string (detected automatically).
+- `show()` — make the bar visible again.
+- `hide()` — hide the bar (`display: none`).
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { AppBar, Button, Icon } from "flet-box";
+
+AppBar({
+  title: "Inbox",
+  leading: Icon({ name: "menu", onPress: () => console.log("open menu") }),
+  actions: [
+    Icon({ name: "search", onPress: () => console.log("search") }),
+    Icon({ name: "notifications" }),
+  ],
+});
+```
+
+### Full example
+
+```javascript
+import { AppBar, Icon } from "flet-box";
+
+AppBar({
+  title: "Articles",
+  showBackButton: true,
+  onBackPress: () => console.log("back"),
+  actions: [Icon({ name: "star_border" })],
+  centerTitle: true,
+  backgroundColor: "#eff6ff",
+  elevation: 4,
+  sticky: true,
+});
+```
+
+## Notes
+
+- The bar renders a hidden spacer in the right zone when `actions` is empty, so the title center stays aligned.
+- `leading` and `actions` items that are not `HTMLElement`s are dropped — build them with widgets in the same call so they mount.
+- The automatic back arrow wiring: tap → `onBackPress` if set, else `goTo(backButtonRoute)` if a route is set, else `goBack()`.
+- `hideOnScroll` adds a `window` scroll listener; `_cleanup` removes it, so the bar is safe to tear down.
+- In a `Scaffold`, a leading icon named `menu` (`.material-icons` with text `menu`) opens the embedded drawer automatically.
+
+## Related widgets
+- [Scaffold](Scaffold.md)
+- [Icon](Icon.md)
+- [BottomNavigation](BottomNavigation.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [AdaptiveScaffold](AdaptiveScaffold.md)
+- **Next:** [Drawer](Drawer.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 8 · App navigation** (3 of 8).

package/docs/widget/Audio.md

@@ -0,0 +1,135 @@
+# Audio
+
+A thin wrapper around the native <audio> element with reliable duration detection, progress callbacks, and an imperative playback API. It can play without visible controls.
+
+## When to use it
+
+Use it for background music, podcasts, or any audio player where you build your own transport controls.
+
+## Quick start
+
+```javascript
+import { Audio } from "flet-box";
+
+const track = Audio({
+  src: "/media/song.mp3",
+});
+```
+
+> 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. |
+| `autoplay` | `boolean` | Starts playback automatically. |
+| `controls` | `boolean` | Shows the native media playback controls. |
+| `loop` | `boolean` | Restarts playback when it reaches the end. |
+| `muted` | `boolean` | Starts playback with the audio muted. |
+| `volume` | `number` | Initial volume from 0 to 1. |
+| `onPlay` | `() => void` | Fired when playback starts. |
+| `onPause` | `() => void` | Fired when playback is paused. |
+| `onEnd` | `() => void` | Fired when playback reaches the end. |
+| `onTimeUpdate` | `(current: number, duration: number, percent: number) => void` | Fired repeatedly as the playback position changes. |
+| `onProgress` | `(percent: number) => void` | Fired as the media buffers. |
+| `onLoad` | `(duration: number) => void` | Fired when the media finishes loading. |
+| `ref` | `(audio: HTMLAudioElement) => void` | Callback that receives the underlying DOM node. |
+
+### 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 { Audio } from "flet-box";
+
+const track = Audio({
+  src: "/media/song.mp3",
+  controls: true,
+  volume: 0.8,
+  onEnd: () => console.log("finished"),
+});
+```
+
+### Full
+
+```javascript
+import { Audio } from "flet-box";
+
+const track = Audio({
+  src: "/media/podcast.mp3",
+  autoplay: false,
+  controls: false,
+  loop: false,
+  muted: false,
+  volume: 0.7,
+  onPlay: () => console.log("playing"),
+  onPause: () => console.log("paused"),
+  onTimeUpdate: (current, duration, percent) => console.log(percent),
+  onLoad: (duration) => console.log(duration),
+  ref: (audio) => audio.playAudio(),
+});
+```
+
+## Tips
+
+- controls defaults to false, so set controls: true for the native player or build a
+- custom one from the element's playback methods.
+- onTimeUpdate receives (current, duration, percent) while onProgress receives only
+- the percent, so pick the callback with the shape you need.
+- Duration detection polls the element and can fall back to decoding the file with
+- AudioContext when the browser reports an unknown duration.
+
+## Accessibility
+
+- When controls: false there is no visual affordance, so pair it with visible
+- play/pause buttons for assistive technology users.
+
+## Behavior
+
+- onLoad fires exactly once, when the duration is first resolved, which can arrive
+- after loadedmetadata for some formats.
+- The duration polling interval is cleared on unmount, and the fetch-based duration
+- fallback runs only if the duration is still unknown after two seconds.
+
+## Related widgets
+
+- [Video](Video.md)
+- [Slider](Slider.md)
+- [Icon](Icon.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [ParallaxBox](ParallaxBox.md)
+- **Next:** [Video](Video.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 7 · Media and drag & drop** (1 of 4).