flet-box 1.0.3 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (172) hide show
  1. package/README.md +10 -0
  2. package/bin/cli.js +15 -0
  3. package/bin/commands/checkApi.js +761 -0
  4. package/bin/commands/create.js +77 -5
  5. package/bin/utils/dtsProps.js +191 -0
  6. package/bin/utils/moduleExports.js +165 -0
  7. package/bin/utils/neutralise.js +64 -0
  8. package/bin/utils/templates.js +366 -27
  9. package/docs/CONTRIBUTING.md +156 -0
  10. package/docs/README.md +68 -0
  11. package/docs/arquitectura.md +164 -0
  12. package/docs/cli/README.md +542 -0
  13. package/docs/guides/README.md +33 -0
  14. package/docs/guides/app-templates.md +197 -0
  15. package/docs/guides/compatibility.md +95 -0
  16. package/docs/guides/embedding.md +284 -0
  17. package/docs/guides/first-app.md +208 -0
  18. package/docs/guides/frontend-services.md +171 -0
  19. package/docs/guides/minification-and-protection.md +260 -0
  20. package/docs/guides/mobile-and-platforms.md +439 -0
  21. package/docs/guides/online-updates.md +196 -0
  22. package/docs/guides/router.md +282 -0
  23. package/docs/guides/state.md +283 -0
  24. package/docs/guides/syntax-philosophy.md +150 -0
  25. package/docs/guides/utilities.md +241 -0
  26. package/docs/guides/widget-structure.md +163 -0
  27. package/docs/server/README.md +68 -0
  28. package/docs/server/START_HERE.md +121 -0
  29. package/docs/server/api.md +225 -0
  30. package/docs/server/data-services.md +300 -0
  31. package/docs/server/deployment.md +113 -0
  32. package/docs/server/security.md +196 -0
  33. package/docs/services/README.md +79 -0
  34. package/docs/services/RamStore.md +84 -0
  35. package/docs/services/Session.md +84 -0
  36. package/docs/services/Storage.md +88 -0
  37. package/docs/services/http.md +86 -0
  38. package/docs/tools/README.md +138 -0
  39. package/docs/tools/animation.md +87 -0
  40. package/docs/tools/async-ids-log.md +80 -0
  41. package/docs/tools/device.md +132 -0
  42. package/docs/tools/introspection.md +67 -0
  43. package/docs/tools/lists.md +96 -0
  44. package/docs/tools/markdown.md +79 -0
  45. package/docs/tools/reactivity.md +288 -0
  46. package/docs/tools/state.md +103 -0
  47. package/docs/tools/styling.md +92 -0
  48. package/docs/tools/text-and-time.md +89 -0
  49. package/docs/tools/theme.md +102 -0
  50. package/docs/tools/validation.md +75 -0
  51. package/docs/tools/visual-effects.md +84 -0
  52. package/docs/widget/Accordion.md +144 -0
  53. package/docs/widget/AdMob.md +144 -0
  54. package/docs/widget/AdSense.md +133 -0
  55. package/docs/widget/AdaptiveScaffold.md +105 -0
  56. package/docs/widget/AlertDialog.md +103 -0
  57. package/docs/widget/AnimatedBox.md +130 -0
  58. package/docs/widget/AnimatedText.md +123 -0
  59. package/docs/widget/AppBar.md +118 -0
  60. package/docs/widget/Audio.md +135 -0
  61. package/docs/widget/Avatar.md +119 -0
  62. package/docs/widget/Badge.md +128 -0
  63. package/docs/widget/BottomNavigation.md +116 -0
  64. package/docs/widget/BottomSheet.md +125 -0
  65. package/docs/widget/Button.md +137 -0
  66. package/docs/widget/COMMON_PROPS.md +150 -0
  67. package/docs/widget/Card.md +125 -0
  68. package/docs/widget/Carousel.md +151 -0
  69. package/docs/widget/Chart.md +151 -0
  70. package/docs/widget/Checkbox.md +118 -0
  71. package/docs/widget/Chip.md +126 -0
  72. package/docs/widget/CircularBar.md +168 -0
  73. package/docs/widget/CircularChart.md +164 -0
  74. package/docs/widget/CodeViewer.md +130 -0
  75. package/docs/widget/CollapsibleSideBar.md +112 -0
  76. package/docs/widget/Column.md +129 -0
  77. package/docs/widget/Container.md +136 -0
  78. package/docs/widget/DataTable.md +150 -0
  79. package/docs/widget/Divider.md +109 -0
  80. package/docs/widget/DraggBox.md +129 -0
  81. package/docs/widget/Drawer.md +135 -0
  82. package/docs/widget/DrawerItem.md +98 -0
  83. package/docs/widget/Dropdown.md +139 -0
  84. package/docs/widget/DroppBox.md +152 -0
  85. package/docs/widget/FloatingActionButton.md +120 -0
  86. package/docs/widget/GridView.md +140 -0
  87. package/docs/widget/Icon.md +117 -0
  88. package/docs/widget/Image.md +125 -0
  89. package/docs/widget/Input.md +151 -0
  90. package/docs/widget/Inspector.md +92 -0
  91. package/docs/widget/InstallButton.md +128 -0
  92. package/docs/widget/ListTile.md +132 -0
  93. package/docs/widget/ListView.md +138 -0
  94. package/docs/widget/Markdown.md +175 -0
  95. package/docs/widget/MatrixRain.md +122 -0
  96. package/docs/widget/Modal.md +129 -0
  97. package/docs/widget/Pagination.md +135 -0
  98. package/docs/widget/ParallaxBox.md +128 -0
  99. package/docs/widget/ProgressBar.md +130 -0
  100. package/docs/widget/QRCode.md +117 -0
  101. package/docs/widget/README.md +188 -0
  102. package/docs/widget/Radio.md +123 -0
  103. package/docs/widget/Rating.md +131 -0
  104. package/docs/widget/Row.md +131 -0
  105. package/docs/widget/START_HERE.md +146 -0
  106. package/docs/widget/Scaffold.md +152 -0
  107. package/docs/widget/Skeleton.md +130 -0
  108. package/docs/widget/Slider.md +146 -0
  109. package/docs/widget/SnackBar.md +102 -0
  110. package/docs/widget/Stack.md +128 -0
  111. package/docs/widget/Stepper.md +145 -0
  112. package/docs/widget/Switch.md +118 -0
  113. package/docs/widget/Tabs.md +124 -0
  114. package/docs/widget/Text.md +133 -0
  115. package/docs/widget/Tooltip.md +145 -0
  116. package/docs/widget/TreeView.md +176 -0
  117. package/docs/widget/Video.md +127 -0
  118. package/docs/widget/_template.md +61 -0
  119. package/package.json +4 -2
  120. package/src/animations/AnimatedBox.js +32 -1
  121. package/src/animations/AnimatedText.js +7 -3
  122. package/src/animations/MatrixRain.js +37 -12
  123. package/src/animations/ParallaxBox.js +16 -3
  124. package/src/animations/animate.js +187 -58
  125. package/src/animations/index.js +1 -0
  126. package/src/core/runApp.js +13 -1
  127. package/src/create-index.sh +1 -1
  128. package/src/index.d.ts +227 -91
  129. package/src/index.js +1 -0
  130. package/src/navigations/AdaptiveScaffold.js +11 -2
  131. package/src/navigations/AppBar.js +8 -2
  132. package/src/navigations/BottomNavigation.js +24 -5
  133. package/src/navigations/DrawerItem.js +16 -3
  134. package/src/navigations/Scaffold.js +8 -1
  135. package/src/navigations/Tabs.js +40 -8
  136. package/src/tools/dimensions.js +11 -3
  137. package/src/tools/useState.js +139 -101
  138. package/src/utils/getWidgetProps.js +5 -3
  139. package/src/widget-factory/assignProps.js +30 -11
  140. package/src/widget-factory/processProps.js +17 -5
  141. package/src/widget-factory/reactiveValue.js +172 -0
  142. package/src/widget-factory/translateProps.js +777 -901
  143. package/src/widget-factory/warnings.js +15 -0
  144. package/src/widget-factory/widgetFactory.js +27 -0
  145. package/src/widgets/Accordion.js +6 -5
  146. package/src/widgets/AlertDialog.js +7 -5
  147. package/src/widgets/Audio.js +30 -8
  148. package/src/widgets/BottomSheet.js +24 -1
  149. package/src/widgets/Chart.js +4 -1
  150. package/src/widgets/Checkbox.js +16 -8
  151. package/src/widgets/CircularBar.js +12 -1
  152. package/src/widgets/CircularChart.js +4 -1
  153. package/src/widgets/CodeViewer.js +26 -8
  154. package/src/widgets/DataTable.js +11 -2
  155. package/src/widgets/Dropdown.js +5 -1
  156. package/src/widgets/FloatingActionButton.js +4 -7
  157. package/src/widgets/Image.js +7 -2
  158. package/src/widgets/Input.js +119 -6
  159. package/src/widgets/Inspector.js +16 -10
  160. package/src/widgets/ListView.js +80 -30
  161. package/src/widgets/Markdown.js +53 -8
  162. package/src/widgets/Modal.js +24 -1
  163. package/src/widgets/Pagination.js +6 -3
  164. package/src/widgets/ProgressBar.js +16 -13
  165. package/src/widgets/QRCode.js +9 -2
  166. package/src/widgets/Radio.js +11 -8
  167. package/src/widgets/Slider.js +26 -4
  168. package/src/widgets/SnackBar.js +20 -2
  169. package/src/widgets/Stack.js +36 -3
  170. package/src/widgets/Stepper.js +4 -3
  171. package/src/widgets/Switch.js +8 -5
  172. package/src/widgets/TreeView.js +3 -2
@@ -0,0 +1,122 @@
1
+ # MatrixRain
2
+
3
+ A canvas-based Matrix-style effect where random characters cascade down the screen. It runs a continuous animation loop with configurable speed and fade.
4
+
5
+ ## When to use it
6
+
7
+ Use it as a full-viewport backdrop or an ambient section background for a retro-tech aesthetic.
8
+
9
+ ## Quick start
10
+
11
+ ```javascript
12
+ import { MatrixRain } from "flet-box";
13
+
14
+ const rain = MatrixRain({});
15
+ ```
16
+
17
+ > The prop table is generated from `src/index.d.ts`; the examples use only documented props.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Description |
22
+ | --- | --- | --- |
23
+ | `chars` | `string` | Characters used by the matrix rain. |
24
+ | `fontSize` | `number` | Size of the font. |
25
+ | `speed` | `number` | Animation speed. |
26
+ | `fadeAmount` | `number` | How quickly trails fade each frame. |
27
+ | `resetProbability` | `number` | Chance a column resets to the top each frame. |
28
+ | `useDynamicColor` | `boolean` | Cycles colors instead of using a fixed color. |
29
+ | `position` | `'fixed' \| 'absolute'` | CSS `position` value, or `stack` for centered stacking. |
30
+ | `zIndex` | `number` | Index used for the z. |
31
+
32
+ ### Common props
33
+
34
+ Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
35
+
36
+ | Prop | Type | Description |
37
+ | --- | --- | --- |
38
+ | `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
39
+ | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
40
+ | `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
41
+ | `padding` | `Padding` | Space inside the widget, between its content and its border. |
42
+ | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
43
+ | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
44
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
45
+ | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
46
+ | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
47
+ | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
48
+ | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
49
+ | `visible` | `boolean` | Whether the widget is rendered and visible. |
50
+ | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
51
+ | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
52
+ | `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
53
+ | `id` | `string` | DOM `id` for the rendered element. |
54
+ | `className` | `string` | CSS class names applied to the rendered element. |
55
+ | `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
56
+ | `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
57
+
58
+ ## Examples
59
+
60
+ ### Everyday
61
+
62
+ ```javascript
63
+ import { MatrixRain } from "flet-box";
64
+
65
+ const rain = MatrixRain({
66
+ fontSize: 18,
67
+ speed: 0.6,
68
+ position: "fixed",
69
+ });
70
+ ```
71
+
72
+ ### Full
73
+
74
+ ```javascript
75
+ import { MatrixRain } from "flet-box";
76
+
77
+ const rain = MatrixRain({
78
+ chars: "01",
79
+ fontSize: 20,
80
+ speed: 0.8,
81
+ fadeAmount: 0.08,
82
+ resetProbability: 0.98,
83
+ useDynamicColor: true,
84
+ position: "fixed",
85
+ zIndex: 1,
86
+ });
87
+ ```
88
+
89
+ ## Tips
90
+
91
+ - position: "fixed" fills the viewport; "absolute" fills a positioned parent
92
+ - instead.
93
+ - Set zIndex low (1 or negative) so the rain renders behind your regular UI.
94
+ - Tune resetProbability closer to 1 to make trails longer or drops rarer.
95
+
96
+ ## Accessibility
97
+
98
+ - The rain is decorative canvas output; pair it with real content on top and make it
99
+ - pausable for motion-sensitive users.
100
+
101
+ ## Behavior
102
+
103
+ - The returned canvas runs its animation loop immediately and exposes _cleanup() to
104
+ - stop drawing and disconnect the ResizeObserver.
105
+ - Changing speed or fadeAmount only affects future frames; update them before mount
106
+ - for a clean start.
107
+
108
+ ## Related widgets
109
+
110
+ - [Container](Container.md)
111
+ - [Card](Card.md)
112
+ - [AnimatedBox](AnimatedBox.md)
113
+
114
+ ---
115
+
116
+ ## Continue reading
117
+
118
+ - **Previous:** [AnimatedText](AnimatedText.md)
119
+ - **Next:** [ParallaxBox](ParallaxBox.md)
120
+ - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
121
+
122
+ You are reading **Chapter 6 · Data, rich content & effects** (12 of 13).
@@ -0,0 +1,129 @@
1
+ # Modal
2
+
3
+ A centered dialog over a dimmed overlay that holds a title, content and a row of actions.
4
+
5
+ ## When to use it
6
+
7
+ Use Modal when the user must focus on a task or read something without leaving the page.
8
+
9
+ ## Quick start
10
+
11
+ ```javascript
12
+ import { Modal } from "flet-box";
13
+
14
+ const dialog = Modal({
15
+ title: "Welcome",
16
+ content: "Thanks for signing up.",
17
+ });
18
+ ```
19
+
20
+ > The prop table is generated from `src/index.d.ts`; the examples use only documented props.
21
+
22
+ ## Props
23
+
24
+ | Prop | Type | Description |
25
+ | --- | --- | --- |
26
+ | `title` | `string` | Title text shown in the header. |
27
+ | `content` | `Widget \| string` | Main content of the overlay. |
28
+ | `actions` | `Widget[]` | Widgets rendered in the overlay footer. |
29
+ | `closeOnOverlayClick` | `boolean` | Closes the overlay when the backdrop is clicked. |
30
+ | `closeOnEsc` | `boolean` | Closes the overlay when Escape is pressed. |
31
+ | `width` | `number \| string` | Width of the widget. A number is pixels; a string uses any CSS unit. |
32
+ | `minWidth` | `number` | Minimum width the widget may shrink to. |
33
+ | `maxWidth` | `number \| string` | Maximum width the widget may grow to. |
34
+ | `maxHeight` | `number \| string` | Maximum height the widget may grow to. |
35
+ | `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
36
+ | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
37
+ | `border` | `string` | The `border` value for the widget. |
38
+ | `borderColor` | `Color` | Color used for the border. |
39
+ | `borderWidth` | `number` | Width of the border. |
40
+ | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
41
+ | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
42
+ | `padding` | `Padding` | Space inside the widget, between its content and its border. |
43
+ | `contentBgColor` | `Color` | Background color for the content. |
44
+ | `contentElevation` | `number` | Elevation (shadow depth) of the content. |
45
+ | `headerBgColor` | `Color` | Background color of the header row. |
46
+ | `headerTextColor` | `Color` | Text color of the header row. |
47
+ | `headerBorder` | `string \| false` | The `headerBorder` value for the widget. |
48
+ | `headerPadding` | `Padding` | Padding for the header. |
49
+ | `headerElevation` | `number` | Elevation (shadow depth) of the header. |
50
+ | `footerBgColor` | `Color` | Background color for the footer. |
51
+ | `footerBorder` | `string \| false` | The `footerBorder` value for the widget. |
52
+ | `footerPadding` | `Padding` | Padding for the footer. |
53
+ | `footerElevation` | `number` | Elevation (shadow depth) of the footer. |
54
+ | `overlayColor` | `Color` | Color of the dimmed backdrop behind the overlay. |
55
+ | `showCloseButton` | `boolean` | Shows a close button in the header. |
56
+ | `zIndex` | `number` | Index used for the z. |
57
+ | `onOpen` | `() => void` | Fired when the overlay opens. |
58
+ | `onClose` | `() => void` | Fired when the overlay closes. |
59
+
60
+ ## Examples
61
+
62
+ ### Everyday
63
+
64
+ ```javascript
65
+ import { Modal } from "flet-box";
66
+
67
+ const profile = Modal({
68
+ title: "Profile",
69
+ content: "Update your account details.",
70
+ closeOnOverlayClick: true,
71
+ onClose: () => console.log("closed"),
72
+ });
73
+ ```
74
+
75
+ ### Full
76
+
77
+ ```javascript
78
+ import { Button, Column, Modal, Switch, rgba } from "flet-box";
79
+
80
+ const settings = Modal({
81
+ title: "Settings",
82
+ content: Column({
83
+ gap: 12,
84
+ children: [Switch({ label: "Dark mode" }), Switch({ label: "Compact" })],
85
+ }),
86
+ actions: [
87
+ Button({ text: "Cancel", variant: "text" }),
88
+ Button({ text: "Save", onPress: () => settings.close() }),
89
+ ],
90
+ closeOnOverlayClick: false,
91
+ closeOnEsc: true,
92
+ width: 480,
93
+ borderRadius: 16,
94
+ elevation: 8,
95
+ overlayColor: "rgba(15, 23, 42, 0.5)",
96
+ onOpen: () => console.log("opened"),
97
+ onClose: () => console.log("closed"),
98
+ });
99
+ ```
100
+
101
+ ## Tips
102
+
103
+ - Modal manages its own overlay and appends it to document.body; call the returned open() and close() to control visibility.
104
+ - Use closeOnOverlayClick: false for destructive or data-entry dialogs that should not be dismissed by a stray click.
105
+
106
+ ## Accessibility
107
+
108
+ - Modal does not move focus automatically; focus the first control or a close button when it opens.
109
+
110
+ ## Behavior
111
+
112
+ - Returns a controller with open, close, toggle, destroy and an isOpen getter, plus updateContent, updateTitle and setLoading helpers.
113
+ - onOpen and onClose fire on state changes, and closeOnEsc installs an Escape listener that destroy() removes.
114
+
115
+ ## Related widgets
116
+
117
+ - [BottomSheet](BottomSheet.md)
118
+ - [AlertDialog](AlertDialog.md)
119
+ - [Card](Card.md)
120
+
121
+ ---
122
+
123
+ ## Continue reading
124
+
125
+ - **Previous:** [AlertDialog](AlertDialog.md)
126
+ - **Next:** [BottomSheet](BottomSheet.md)
127
+ - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
128
+
129
+ You are reading **Chapter 4 · Feedback and overlays** (2 of 10).
@@ -0,0 +1,135 @@
1
+ # Pagination
2
+
3
+ Pagination renders page controls derived from totalItems and pageSize, with optional first/last and prev/next buttons. It reports the chosen page through onPageChange.
4
+
5
+ ## When to use it
6
+
7
+ Use it under long lists or tables so users can move through paged results.
8
+
9
+ ## Quick start
10
+
11
+ ```javascript
12
+ import { Pagination } from "flet-box";
13
+
14
+ const pages = Pagination({
15
+ totalItems: 100,
16
+ pageSize: 10,
17
+ onPageChange: (page) => console.log(page),
18
+ });
19
+ ```
20
+
21
+ > The prop table is generated from `src/index.d.ts`; the examples use only documented props.
22
+
23
+ ## Props
24
+
25
+ | Prop | Type | Description |
26
+ | --- | --- | --- |
27
+ | `totalItems` | `number` | Total number of items to paginate. |
28
+ | `pageSize` | `number` | Number of items per page. |
29
+ | `currentPage` | `number` | Currently active page. |
30
+ | `onPageChange` | `(page: number) => void` | Fired with the new page number. |
31
+ | `showFirstLast` | `boolean` | Shows first and last page buttons. |
32
+ | `showPrevNext` | `boolean` | Shows previous and next page buttons. |
33
+ | `maxButtons` | `number` | Maximum number of page buttons before truncation. |
34
+ | `variant` | `'outlined' \| 'filled' \| 'text'` | Visual variation or style preset. |
35
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
36
+ | `size` | `'small' \| 'medium' \| 'large'` | Overall size preset or pixel value, depending on the widget. |
37
+ | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
38
+ | `showTotal` | `boolean` | Controls whether the total is shown. |
39
+ | `label` | `string` | Label or caption shown near the control. |
40
+
41
+ ### Common props
42
+
43
+ Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
44
+
45
+ | Prop | Type | Description |
46
+ | --- | --- | --- |
47
+ | `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
48
+ | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
49
+ | `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
50
+ | `padding` | `Padding` | Space inside the widget, between its content and its border. |
51
+ | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
52
+ | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
53
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
54
+ | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
55
+ | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
56
+ | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
57
+ | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
58
+ | `visible` | `boolean` | Whether the widget is rendered and visible. |
59
+ | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
60
+ | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
61
+ | `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
62
+ | `id` | `string` | DOM `id` for the rendered element. |
63
+ | `className` | `string` | CSS class names applied to the rendered element. |
64
+ | `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
65
+ | `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
66
+
67
+ ## Examples
68
+
69
+ ### Everyday
70
+
71
+ ```javascript
72
+ import { Pagination } from "flet-box";
73
+
74
+ const pages = Pagination({
75
+ totalItems: 248,
76
+ pageSize: 20,
77
+ currentPage: 1,
78
+ showPrevNext: true,
79
+ showFirstLast: true,
80
+ onPageChange: (page) => loadPage(page),
81
+ });
82
+ ```
83
+
84
+ ### Full
85
+
86
+ ```javascript
87
+ import { Pagination } from "flet-box";
88
+
89
+ const pages = Pagination({
90
+ totalItems: 512,
91
+ pageSize: 25,
92
+ currentPage: 4,
93
+ maxButtons: 7,
94
+ variant: "filled",
95
+ size: "medium",
96
+ showFirstLast: true,
97
+ showPrevNext: true,
98
+ showTotal: true,
99
+ label: "Rows",
100
+ color: "#2563eb",
101
+ onPageChange: (page) => loadPage(page),
102
+ });
103
+ ```
104
+
105
+ ## Tips
106
+
107
+ - Provide totalItems and pageSize; the number of pages is computed for you.
108
+ - Control the active page with currentPage and update it inside onPageChange.
109
+ - Use maxButtons to limit how many page buttons appear before they collapse.
110
+
111
+ ## Accessibility
112
+
113
+ - Ensure the current page is distinguishable and that controls are reachable by keyboard.
114
+ - Pair pagination with a visible total by enabling showTotal so users know how much data exists.
115
+
116
+ ## Behavior
117
+
118
+ - Pages are recalculated whenever totalItems, pageSize or currentPage change.
119
+ - onPageChange fires with the new page number when the user navigates.
120
+
121
+ ## Related widgets
122
+
123
+ - [DataTable](DataTable.md)
124
+ - [ListView](ListView.md)
125
+ - [Button](Button.md)
126
+
127
+ ---
128
+
129
+ ## Continue reading
130
+
131
+ - **Previous:** [FloatingActionButton](FloatingActionButton.md)
132
+ - **Next:** [Stepper](Stepper.md)
133
+ - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
134
+
135
+ You are reading **Chapter 4 · Feedback and overlays** (10 of 10).
@@ -0,0 +1,128 @@
1
+ # ParallaxBox
2
+
3
+ A container that shifts its child in response to scroll, mouse position, or hover entry. It clamps movement to a max offset and eases with a transition.
4
+
5
+ ## When to use it
6
+
7
+ Use it to give hero sections or layered illustrations depth as the user scrolls or moves the pointer.
8
+
9
+ ## Quick start
10
+
11
+ ```javascript
12
+ import { ParallaxBox, Text } from "flet-box";
13
+
14
+ const scene = ParallaxBox({
15
+ child: Text({ text: "Scroll me" }),
16
+ });
17
+ ```
18
+
19
+ > The prop table is generated from `src/index.d.ts`; the examples use only documented props.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Description |
24
+ | --- | --- | --- |
25
+ | `child` | `Widget` | A single child widget. Alias: `children` for a list. |
26
+ | `type` | `'scroll' \| 'mouse' \| 'hover'` | Kind or mode of the widget. |
27
+ | `speed` | `number` | Animation speed. |
28
+ | `direction` | `'vertical' \| 'horizontal' \| 'both'` | Main-axis direction for layout widgets (`row` or `column`). |
29
+ | `maxOffset` | `number` | Maximum parallax offset in pixels. |
30
+ | `reverse` | `boolean` | Reverses the parallax direction. |
31
+ | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
32
+ | `onParallaxMove` | `(offset: { x: number; y: number }) => void` | Fired as the parallax offset changes. |
33
+ | `duration` | `number` | How long the transient element stays visible, in milliseconds. |
34
+ | `easing` | `string` | Easing curve for the parallax motion. |
35
+
36
+ ### Common props
37
+
38
+ Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
39
+
40
+ | Prop | Type | Description |
41
+ | --- | --- | --- |
42
+ | `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
43
+ | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
44
+ | `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
45
+ | `padding` | `Padding` | Space inside the widget, between its content and its border. |
46
+ | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
47
+ | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
48
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
49
+ | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
50
+ | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
51
+ | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
52
+ | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
53
+ | `visible` | `boolean` | Whether the widget is rendered and visible. |
54
+ | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
55
+ | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
56
+ | `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
57
+ | `id` | `string` | DOM `id` for the rendered element. |
58
+ | `className` | `string` | CSS class names applied to the rendered element. |
59
+ | `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
60
+ | `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
61
+
62
+ ## Examples
63
+
64
+ ### Everyday
65
+
66
+ ```javascript
67
+ import { Image, ParallaxBox } from "flet-box";
68
+
69
+ const scene = ParallaxBox({
70
+ child: Image({ src: "/artwork.jpg", alt: "Layer 1" }),
71
+ type: "scroll",
72
+ speed: 0.6,
73
+ });
74
+ ```
75
+
76
+ ### Full
77
+
78
+ ```javascript
79
+ import { Image, ParallaxBox } from "flet-box";
80
+
81
+ const scene = ParallaxBox({
82
+ child: Image({ src: "/team/hero.png", alt: "Hero layer" }),
83
+ type: "mouse",
84
+ speed: 0.4,
85
+ direction: "both",
86
+ maxOffset: 40,
87
+ reverse: true,
88
+ duration: 250,
89
+ easing: "ease-out",
90
+ onParallaxMove: (offset) => console.log(offset.x, offset.y),
91
+ });
92
+ ```
93
+
94
+ ## Tips
95
+
96
+ - type: "scroll" follows the window scroll; "mouse" tracks the pointer relative to
97
+ - the widget center; "hover" snaps on entry and resets on leave.
98
+ - Raise speed for a more pronounced shift, and keep maxOffset small so content never
99
+ - strays far from its layout box.
100
+ - Use reverse: true to invert the direction when the natural movement feels wrong.
101
+
102
+ ## Accessibility
103
+
104
+ - Parallax is decorative motion; make sure content stays readable without it and keep
105
+ - movement gentle.
106
+
107
+ ## Behavior
108
+
109
+ - The exposed element provides updateSpeed, updateDirection, setPosition, and reset
110
+ - for runtime control.
111
+ - Transforms are clamped to maxOffset and cleaned up via _cleanup(), which removes all
112
+ - event listeners on destroy.
113
+
114
+ ## Related widgets
115
+
116
+ - [AnimatedBox](AnimatedBox.md)
117
+ - [Image](Image.md)
118
+ - [Container](Container.md)
119
+
120
+ ---
121
+
122
+ ## Continue reading
123
+
124
+ - **Previous:** [MatrixRain](MatrixRain.md)
125
+ - **Next:** [Audio](Audio.md)
126
+ - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
127
+
128
+ You are reading **Chapter 6 · Data, rich content & effects** (13 of 13).
@@ -0,0 +1,130 @@
1
+ # ProgressBar
2
+
3
+ A horizontal bar that visualizes completion from zero to max. It can show a label and numeric value, or run as an indeterminate loader.
4
+
5
+ ## When to use it
6
+
7
+ Use it to report progress such as uploads, multi-step flows, or budget usage.
8
+
9
+ ## Quick start
10
+
11
+ ```javascript
12
+ import { ProgressBar } from "flet-box";
13
+
14
+ const progress = ProgressBar({
15
+ value: 60,
16
+ });
17
+ ```
18
+
19
+ > The prop table is generated from `src/index.d.ts`; the examples use only documented props.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Description |
24
+ | --- | --- | --- |
25
+ | `value` | `number` | Current value controlled by the widget. |
26
+ | `max` | `number` | Maximum value used to compute the ratio. |
27
+ | `height` | `number` | Height of the widget. A number is pixels; a string uses any CSS unit. |
28
+ | `width` | `number \| string` | Width of the widget. A number is pixels; a string uses any CSS unit. |
29
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
30
+ | `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
31
+ | `borderRadius` | `number` | Rounds the corners of the widget. |
32
+ | `label` | `string` | Label or caption shown near the control. |
33
+ | `showValue` | `boolean` | Shows the numeric value next to the indicator. |
34
+ | `valuePosition` | `'left' \| 'right' \| 'top' \| 'bottom'` | Where the value label is placed. |
35
+ | `indeterminate` | `boolean` | Shows an unknown-progress animation. |
36
+ | `striped` | `boolean` | Draws diagonal stripes across the bar. |
37
+ | `animatedStripes` | `boolean` | Animates the stripes on the bar. |
38
+
39
+ ### Common props
40
+
41
+ Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
42
+
43
+ | Prop | Type | Description |
44
+ | --- | --- | --- |
45
+ | `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
46
+ | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
47
+ | `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
48
+ | `padding` | `Padding` | Space inside the widget, between its content and its border. |
49
+ | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
50
+ | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
51
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
52
+ | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
53
+ | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
54
+ | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
55
+ | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
56
+ | `visible` | `boolean` | Whether the widget is rendered and visible. |
57
+ | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
58
+ | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
59
+ | `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
60
+ | `id` | `string` | DOM `id` for the rendered element. |
61
+ | `className` | `string` | CSS class names applied to the rendered element. |
62
+ | `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
63
+ | `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
64
+
65
+ ## Examples
66
+
67
+ ### Everyday
68
+
69
+ ```javascript
70
+ import { ProgressBar } from "flet-box";
71
+
72
+ const progress = ProgressBar({
73
+ value: 60,
74
+ max: 100,
75
+ height: 8,
76
+ color: "#2563eb",
77
+ backgroundColor: "#e2e8f0",
78
+ });
79
+ ```
80
+
81
+ ### Full
82
+
83
+ ```javascript
84
+ import { ProgressBar } from "flet-box";
85
+
86
+ const progress = ProgressBar({
87
+ value: 72,
88
+ max: 100,
89
+ width: "100%",
90
+ height: 12,
91
+ color: "#16a34a",
92
+ backgroundColor: "#e5e7eb",
93
+ borderRadius: 6,
94
+ label: "Upload",
95
+ showValue: true,
96
+ valuePosition: "right",
97
+ striped: true,
98
+ animatedStripes: true,
99
+ });
100
+ ```
101
+
102
+ ## Tips
103
+
104
+ - Set indeterminate: true when the duration is unknown and no numeric value applies.
105
+ - Combine showValue with valuePosition to place the percentage beside the bar.
106
+
107
+ ## Accessibility
108
+
109
+ - Include label so the bar is announced with context, not just as a length.
110
+
111
+ ## Behavior
112
+
113
+ - value is clamped against max, so 120 with max 100 renders as full.
114
+ - striped and animatedStripes add motion cues without changing the value.
115
+
116
+ ## Related widgets
117
+
118
+ - [CircularBar](CircularBar.md)
119
+ - [Skeleton](Skeleton.md)
120
+ - [Rating](Rating.md)
121
+
122
+ ---
123
+
124
+ ## Continue reading
125
+
126
+ - **Previous:** [Tooltip](Tooltip.md)
127
+ - **Next:** [CircularBar](CircularBar.md)
128
+ - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
129
+
130
+ You are reading **Chapter 4 · Feedback and overlays** (6 of 10).