flet-box 1.0.4 → 1.0.5

package/docs/tools/validation.md

@@ -0,0 +1,75 @@
+# Input validation
+
+## Overview
+`TextInputValidator` is a rules object for cleaning and validating text as the user types. The `Input` widget's `validation` prop uses these very rules.
+
+## When to use
+- Restrict a field to letters, numbers, or alphanumerics.
+- Validate an email address or a safe-string before submit.
+- Sanitize text before storing it.
+
+## Import
+
+```javascript
+import { TextInputValidator } from "flet-box";
+```
+
+## Methods
+
+| Method | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `onlyLetters` | `onlyLetters(value)` | `string` | Remove anything that is not a letter. |
+| `onlyNumbers` | `onlyNumbers(value)` | `string` | Remove anything that is not a digit. |
+| `onlyAlphanumeric` | `onlyAlphanumeric(value)` | `string` | Keep letters and digits only. |
+| `filter` | `filter(value, pattern)` | `string` | Remove matches of a regex `pattern`. |
+| `filterEmail` | `filterEmail(value)` | `string` | Keep valid email characters. |
+| `isEmail` | `isEmail(value)` | `boolean` | Is this a valid email? |
+| `limitLength` | `limitLength(value, maxLength)` | `string` | Truncate to `maxLength`. |
+| `isOnlyLetters` | `isOnlyLetters(value)` | `boolean` | Contains only letters? |
+| `isOnlyNumbers` | `isOnlyNumbers(value)` | `boolean` | Contains only digits? |
+| `sanitize` | `sanitize(value)` | `string` | Clean unsafe characters / control text. |
+| `escapeHtml` | `escapeHtml(value)` | `string` | Escape HTML-significant characters. |
+| `safeText` | `safeText(value)` | `string` | Escape unsafe text for insertion. |
+| `isSafe` | `isSafe(value)` | `boolean` | Is the text safe as-is? |
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { TextInputValidator } from "flet-box";
+
+const phone = TextInputValidator.onlyNumbers("call 555-1234"); // "5551234"
+const email = TextInputValidator.isEmail("ada@example.com");  // true
+```
+
+### Full example
+
+```javascript
+import { TextInputValidator } from "flet-box";
+
+const name = TextInputValidator.onlyLetters("A1na 2");
+const short = TextInputValidator.limitLength("description here", 8);
+const safe = TextInputValidator.safeText("<script>alert(1)</script>");
+```
+
+## Notes
+
+- The cleaning methods are safe to call on every keystroke — they are used live by the `Input` widget.
+- Use `isEmail`/`isOnlyLetters`/`isOnlyNumbers`/`isSafe` for form validation before submit; use the cleaning methods to normalize while typing.
+- `escapeHtml`/`safeText` exist both here and as standalone helpers — prefer the standalone `escapeHtml` when you are not inside an `Input` flow.
+
+## Related pages
+- [Widget introspection](introspection.md) — previous chapter.
+- [Animation helpers](animation.md) — next chapter.
+- [Input widget](../widget/Input.md) — where validation is applied.
+
+---
+
+## Continue reading
+
+- **Previous:** [Widget introspection](introspection.md)
+- **Next:** [Animation helpers](animation.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (11 of 12).

package/docs/tools/visual-effects.md

@@ -0,0 +1,84 @@
+# Visual effects
+
+## Overview
+Apply ready-made visual treatments directly to an HTML element: stripes, shimmer, glow, an indeterminate progress sweep, and a pulse. `injectKeyframes` lets you add custom CSS keyframes globally.
+
+## When to use
+- Add a loading shimmer to placeholders.
+- Animate a progress feel with indeterminate or pulse.
+- Make an element glow or carry striped accents without writing CSS.
+
+## Import
+
+```javascript
+import { applyShimmer, applyGlow, removeStripes, injectKeyframes } from "flet-box";
+```
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `applyStripes` | `applyStripes(element, options?)` | `void` | Diagonal stripes overlay. |
+| `removeStripes` | `removeStripes(element)` | `void` | Remove the stripes. |
+| `applyShimmer` | `applyShimmer(element, options?)` | `void` | Animated shimmer sweep. |
+| `applyGlow` | `applyGlow(element, options?)` | `void` | Outer glow animation. |
+| `applyIndeterminate` | `applyIndeterminate(element, options?)` | `void` | Indeterminate progress sweep (like a loader). |
+| `applyPulse` | `applyPulse(element, options?)` | `void` | Pulsing scale animation. |
+| `injectKeyframes` | `injectKeyframes(name, keyframes)` | `void` | Register a global CSS keyframes rule. |
+
+Options object per effect:
+
+| Effect | Options |
+| --- | --- |
+| `applyStripes` | `{ color?, size?, angle?, animated?, duration? }` |
+| `applyShimmer` | `{ highlightColor?, baseColor?, duration? }` |
+| `applyGlow` | `{ color?, intensity?, duration? }` |
+| `applyIndeterminate` | `{ duration?, width? }` |
+| `applyPulse` | `{ scale?, duration? }` |
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { applyShimmer } from "flet-box";
+
+const skeleton = Container({ width: 200, height: 24, backgroundColor: "#e2e8f0" });
+
+applyShimmer(skeleton, { duration: "1.6s" });
+```
+
+### Full example
+
+```javascript
+import { Container, applyStripes, removeStripes, applyGlow } from "flet-box";
+
+const card = Container({ padding: 20, backgroundColor: "#fffbe6" });
+
+applyStripes(card, { color: "#f59e0b33", size: 12, animated: true });
+applyGlow(card, { color: "#f59e0b", intensity: 8 });
+
+// later, clean the stripes:
+removeStripes(card);
+```
+
+## Notes
+
+- Effects mutate the element's style in place; to fully revert the static ones use their matching `remove*` function.
+- Animated effects use injected keyframes — you can override durations through the options.
+- For the widget-level equivalents see [AnimatedBox/AnimatedText](animation.md), and use [Skeleton](../widget/Skeleton.md) for placeholders styled by props.
+
+## Related pages
+- [Markdown, code & HTML](markdown.md) — previous chapter.
+- [Widget introspection](introspection.md) — next chapter.
+- [Skeleton widget](../widget/Skeleton.md) — placeholder widgets.
+
+---
+
+## Continue reading
+
+- **Previous:** [Markdown, code & HTML](markdown.md)
+- **Next:** [Widget introspection](introspection.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (9 of 12).

package/docs/widget/Accordion.md

@@ -0,0 +1,144 @@
+# Accordion
+
+A collapsible panel that hides a title bar with expandable content beneath it. It animates open and closed and can report its state.
+
+## When to use it
+
+Use it for FAQs, advanced settings, or any content you want to tuck away by default.
+
+## Quick start
+
+```javascript
+import { Accordion, Text } from "flet-box";
+
+const faq = Accordion({
+  title: "What is FletBox?",
+  children: Text({ text: "A declarative UI framework." }),
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string \| Widget` | Title text shown in the header. |
+| `children` | `Widget` | An array of child widgets. Alias: `child` for a single child. |
+| `expanded` | `boolean` | The `expanded` value for the widget. |
+| `onToggle` | `(expanded: boolean) => void` | Fired with the new toggled state. |
+| `variant` | `'contained' \| 'outlined' \| 'ghost'` | Visual variation or style preset. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `expandedColor` | `Color` | Color used for the expanded. |
+| `titleColor` | `Color` | Color used for the title. |
+| `titleSize` | `number` | Size of the title. |
+| `titleWeight` | `string` | The `titleWeight` value for the widget. |
+| `titlePadding` | `string` | Padding for the title. |
+| `contentPadding` | `string` | Padding for the content. |
+| `iconCollapsed` | `string` | The `iconCollapsed` value for the widget. |
+| `iconExpanded` | `string` | The `iconExpanded` value for the widget. |
+| `iconColor` | `Color` | Color of the field icons. |
+| `iconSize` | `number` | Size of the field icons. |
+| `divider` | `boolean` | The `divider` value for the widget. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `animate` | `boolean` | The `animate` value for the widget. |
+| `animationDuration` | `number` | Duration for the animation, in milliseconds. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+
+### 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 { Accordion, Text } from "flet-box";
+
+const faq = Accordion({
+  title: "Shipping options",
+  expanded: false,
+  onToggle: (expanded) => console.log(expanded),
+  children: Text({ text: "Free shipping over $50." }),
+});
+```
+
+### Full
+
+```javascript
+import { Accordion, Text } from "flet-box";
+
+const faq = Accordion({
+  title: "Payment methods",
+  variant: "outlined",
+  borderRadius: 12,
+  bgColor: "#ffffff",
+  expandedColor: "#f8fafc",
+  titleColor: "#0f172a",
+  titleSize: 16,
+  titleWeight: "bold",
+  titlePadding: "16px",
+  contentPadding: "0 16px 16px",
+  iconColor: "#64748b",
+  iconSize: 22,
+  divider: true,
+  animate: true,
+  animationDuration: 250,
+  onToggle: (expanded) => console.log(expanded),
+  children: Text({ text: "We accept cards, PayPal, and bank transfer." }),
+});
+```
+
+## Tips
+
+- Vary variant: "outlined", "contained", or "ghost" to match the surrounding surface.
+- Set expanded to control the initial state when the panel mounts.
+
+## Accessibility
+
+- The title becomes the toggle label, so write it as a clear question or section name.
+
+## Behavior
+
+- onToggle receives the new expanded boolean whenever the header is activated.
+- disabled blocks toggling, and animate: false skips the open/close transition.
+
+## Related widgets
+
+- [Card](Card.md)
+- [ListTile](ListTile.md)
+- [Divider](Divider.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Stepper](Stepper.md)
+- **Next:** [TreeView](TreeView.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 5 · Navigation and flows** (2 of 5).

package/docs/widget/AdMob.md

@@ -0,0 +1,144 @@
+# AdMob
+
+Google AdMob banner and full-screen ads for native Capacitor builds. It renders a placeholder that reserves banner space, and (only when opted in via `autoInitialize: true`) drives the native plugin to show ads.
+
+## When to use it
+
+Use AdMob in Capacitor Android or iOS apps that need banner, interstitial, or rewarded ads over the native layer.
+
+## Quick start
+
+```javascript
+import { AdMob } from "flet-box";
+
+const banner = AdMob({
+  adId: "ca-app-pub-XXXXXXXXXXXXXXXX/YYYYYYYYYY",
+  isTesting: true,
+  autoInitialize: true,
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `adId` | `string` | AdMob ad unit id. |
+| `isTesting` | `boolean` | Requests test ads instead of live ones. |
+| `position` | `'top' \| 'bottom'` | CSS `position` value, or `stack` for centered stacking. |
+| `size` | `string` | Overall size preset or pixel value, depending on the widget. |
+| `margin` | `number` | Space outside the widget, between it and its neighbors. |
+| `interstitialId` | `string` | AdMob interstitial ad unit id. |
+| `rewardedId` | `string` | AdMob rewarded ad unit id. |
+| `autoShow` | `boolean` | Shows the ad automatically when it is ready. |
+| `autoInitialize` | `boolean` | The `autoInitialize` value for the widget. |
+| `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. |
+| `placeholder` | `boolean` | Fallback text shown while the ad is unavailable. |
+| `label` | `string` | Label or caption shown near the control. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `borderColor` | `Color` | Color used for the border. |
+| `plugin` | `object` | The `plugin` value for the widget. |
+| `onLoaded` | `(widget: Widget) => void` | Fired when the ad loads. |
+| `onFailed` | `(error: Error, widget: Widget) => void` | Fired when the ad fails to load. |
+| `onDismissed` | `() => void` | Fired when the ad is dismissed. |
+
+### 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 { AdMob } from "flet-box";
+
+const banner = AdMob({
+  adId: "ca-app-pub-XXXXXXXXXXXXXXXX/YYYYYYYYYY",
+  position: "bottom",
+  size: "ADAPTIVE_BANNER",
+  margin: 8,
+  isTesting: false,
+  autoInitialize: true,
+});
+```
+
+### Full
+
+```javascript
+import { AdMob } from "flet-box";
+
+const banner = AdMob({
+  adId: "ca-app-pub-XXXXXXXXXXXXXXXX/YYYYYYYYYY",
+  position: "bottom",
+  size: "ADAPTIVE_BANNER",
+  interstitialId: "ca-app-pub-XXXXXXXXXXXXXXXX/1111111111",
+  rewardedId: "ca-app-pub-XXXXXXXXXXXXXXXX/2222222222",
+  isTesting: true,
+  autoShow: true,
+  autoInitialize: true,
+  label: "AdMob banner",
+  bgColor: "#f8fafc",
+  onLoaded: (widget) => console.log("banner visible", widget),
+  onFailed: (error) => console.warn("AdMob error", error),
+  onDismissed: () => console.log("ad dismissed"),
+});
+```
+
+## Tips
+
+- Native ads are opt-in: mount ADMOB with `autoInitialize: true` and add the AdMob App ID to the native config (`GADApplicationIdentifier` in Info.plist on iOS, `APPLICATION_ID` meta-data in AndroidManifest.xml on Android). Google's SDK aborts the app when the App ID is missing, so until then the widget stays placeholder-only.
+- On the web with no Capacitor plugin it degrades to the placeholder and logs one warning, so development keeps working.
+- Keep `isTesting: true` until your real ad units are approved, then switch to production ids.
+- Choose `position: "top"` or `"bottom"` and use `margin` to offset the banner from the device edge.
+
+## Accessibility
+
+- Reserve the banner height with `height` so page content does not jump under a screen reader's cursor while the ad loads.
+
+## Behavior
+
+- Until `autoInitialize: true` is passed, the widget is placeholder-only and never touches the native plugin.
+- The returned element exposes `show()`, `hide()`, `showInterstitial()`, and `showRewarded()` for full-screen ads.
+- `onLoaded` fires after the banner is shown, `onFailed` on native errors, and `onDismissed` after a full-screen ad closes; unmount removes the banner.
+
+## Related widgets
+
+- [AdSense](AdSense.md)
+- [Container](Container.md)
+- [Stack](Stack.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [AdSense](AdSense.md)
+- **Next:** [AnimatedBox](AnimatedBox.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 6 · Data, rich content & effects** (9 of 13).

package/docs/widget/AdSense.md

@@ -0,0 +1,133 @@
+# AdSense
+
+Google AdSense display unit for the web. It renders a reserved ad slot, loads the adsbygoogle SDK once per publisher, and lets Google fill the slot.
+
+## When to use it
+
+Reach for AdSense when you ship a web, PWA, or webview build and want to monetize a page with a display slot.
+
+## Quick start
+
+```javascript
+import { AdSense } from "flet-box";
+
+const ad = AdSense({
+  client: "ca-pub-1234567890123456",
+  slot: "1234567890",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `client` | `string` | AdSense publisher id, such as `ca-pub-...`. |
+| `slot` | `string` | AdSense ad unit slot id. |
+| `format` | `string` | Ad format requested from the ad network. |
+| `responsive` | `boolean` | Lets the ad resize to fit its container. |
+| `test` | `boolean` | The `test` value for the widget. |
+| `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. |
+| `placeholder` | `boolean` | Fallback text shown while the ad is unavailable. |
+| `label` | `string` | Label or caption shown near the control. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `borderColor` | `Color` | Color used for the border. |
+| `onLoad` | `(widget: Widget) => void` | Fired when the media finishes loading. |
+| `onError` | `(error: Error, widget: Widget) => void` | Fired when the media fails to load. |
+| `children` | `Widget[]` | An array of child widgets. Alias: `child` for a single child. |
+
+### 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 { AdSense } from "flet-box";
+
+const ad = AdSense({
+  client: "ca-pub-1234567890123456",
+  slot: "1234567890",
+  format: "auto",
+  responsive: true,
+  height: 280,
+});
+```
+
+### Full
+
+```javascript
+import { AdSense } from "flet-box";
+
+const ad = AdSense({
+  client: "ca-pub-1234567890123456",
+  slot: "1234567890",
+  format: "fluid",
+  responsive: true,
+  width: "100%",
+  height: 320,
+  bgColor: "#f8fafc",
+  borderColor: "#e2e8f0",
+  label: "Sponsored",
+  onLoad: (widget) => console.log("ad ready", widget),
+  onError: (error) => console.warn("AdSense unavailable", error),
+});
+```
+
+## Tips
+
+- Both `client` and `slot` are required; until then the widget shows a dashed placeholder and requests no ad.
+- Self-sizing formats such as `fluid` and `autorelaxed` grow with the ad, while fixed formats keep the reserved `height`.
+- Set `test: true` only while developing; it must be off in production.
+
+## Accessibility
+
+- Give the surrounding section a heading so the slot is not the only content a screen reader encounters.
+
+## Behavior
+
+- `onLoad` fires after the SDK is ready and the unit is pushed; `onError` fires if the SDK fails to load.
+- The SDK is injected once per `client` and shared by every AdSense unit on the page; unmounting stops further loads.
+
+## Related widgets
+
+- [AdMob](AdMob.md)
+- [Container](Container.md)
+- [Stack](Stack.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Inspector](Inspector.md)
+- **Next:** [AdMob](AdMob.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 6 · Data, rich content & effects** (8 of 13).

package/docs/widget/AdaptiveScaffold.md

@@ -0,0 +1,105 @@
+# AdaptiveScaffold
+
+## Overview
+`AdaptiveScaffold` is the same application shell as [Scaffold](Scaffold.md), but it **adapts the left navigation to the screen**: on phones (or any viewport under `768px`) the `leftNavBar` becomes a slide-in [Drawer](Drawer.md), and on desktop it becomes a [CollapsibleSideBar](CollapsibleSideBar.md) pinned to the left. Everything else — `appBar`, `body`, `bottomBar`, `fab`, `drawer`, `routes` — is passed through to `Scaffold` unchanged.
+
+## When to use
+- Build one app shell that feels native on both phone and desktop without writing media queries.
+- Keep the router config in one place and let the shell decide how the menu is presented per device.
+
+## Import
+
+```javascript
+import { AdaptiveScaffold, AppBar, DrawerItem, Text } from "flet-box";
+```
+
+## Basic example
+
+The smallest useful version. Start here if this widget is new to you.
+
+```javascript
+import { AdaptiveScaffold, AppBar, Text } from "flet-box";
+
+const app = AdaptiveScaffold({
+  appBar: AppBar({ title: "My App" }),
+  body: Text({ text: "Hello", size: 24, padding: 24 }),
+});
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `appBar` | Widget | — | Top bar, forwarded to `Scaffold`. |
+| `body` | Widget or route map | — | The main content or a `{ path: route }` map (router mode). |
+| `bottomBar` | Widget | — | Bottom bar, forwarded to `Scaffold`. |
+| `fab` | Widget | — | Floating action button, forwarded to `Scaffold`. |
+| `drawer` | Widget | — | Explicit drawer to keep on every device, forwarded to `Scaffold`. |
+| `leftNavBar` | Widget or function | — | Side menu content. Mobile → `Drawer`, desktop → `CollapsibleSideBar`. |
+| `leftNavBarWidth` | number | `260` | Side menu width (drawer on mobile, collapsed sidebar uses `widthCollapsed` sized to its own defaults). |
+| `rightNavBar` | Widget or function | — | Right side content; shown only on desktop as a `CollapsibleSideBar`. |
+| `rightNavBarWidth` | number | `260` | Right column width on desktop. |
+| `routes` | object | — | Route map, forwarded to `Scaffold`. |
+| `backgroundColor` | Color | `colors.background` | Shell background. |
+| `forceMobile` | boolean | `false` | Force the mobile layout (drawer), even on a wide screen. |
+| `forceDesktop` | boolean | `false` | Force the desktop layout (side bar), even on a small screen. |
+
+These are the props specific to `AdaptiveScaffold`. It also accepts every [common prop](COMMON_PROPS.md); extra props are forwarded to the inner `Scaffold`.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { AdaptiveScaffold, AppBar, DrawerItem, Text } from "flet-box";
+
+const app = AdaptiveScaffold({
+  appBar: AppBar({ title: "Portal" }),
+  leftNavBar: [
+    DrawerItem({ icon: "home", label: "Home", route: "/" }),
+    DrawerItem({ icon: "settings", label: "Settings", route: "/settings" }),
+  ],
+  body: Text({ text: "Content" }),
+});
+```
+
+### Full example
+
+```javascript
+import { runApp, AdaptiveScaffold, AppBar, DrawerItem, Text } from "flet-box";
+
+const app = AdaptiveScaffold({
+  appBar: AppBar({ title: "Dashboard" }),
+  leftNavBar: () => [
+    DrawerItem({ icon: "dashboard", label: "Overview", route: "/" }),
+    DrawerItem({ icon: "bar_chart", label: "Reports", route: "/reports" }),
+  ],
+  body: Text({ text: "Data shown here" }),
+  forceDesktop: true,
+});
+
+runApp(app, "root");
+```
+
+## Notes
+
+- This is a **wrapper**: `AdaptiveScaffold` builds its decision once and returns a `Scaffold`. Every [Scaffold](Scaffold.md) prop and instance method applies to what you get back.
+- Which layout wins: `forceMobile` beats `forceDesktop`; otherwise the screen is mobile when `device.isMobile()` returns true **or** `window.innerWidth < 768`.
+- On mobile, the left menu drawer is created with `closeOnOverlayClick: true` and `closeOnEsc: true`, so the user can dismiss it like any drawer.
+- The sidebar content can be a function `() => [...]` so navigation items are rebuilt fresh for each layout; the sidebar receives the resolved element(s).
+
+## Related widgets
+- [Scaffold](Scaffold.md)
+- [AppBar](AppBar.md)
+- [Drawer](Drawer.md)
+- [CollapsibleSideBar](CollapsibleSideBar.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Scaffold](Scaffold.md)
+- **Next:** [AppBar](AppBar.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 8 · App navigation** (2 of 8).