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,112 @@
1
+ # CollapsibleSideBar
2
+
3
+ ## Overview
4
+ `CollapsibleSideBar` is a vertical side panel that can expand and collapse with a 300 ms width transition. The expanded width is `widthExpanded` (default `260px`), the collapsed width is `widthCollapsed` (default `60px`), and a chevron button at the top toggles between them. The expanded/collapsed state is persisted through `useState` under a key (use `id` to give each sidebar its own stored state), so the choice survives route changes and re-renders.
5
+
6
+ ## When to use
7
+ - Provide a compact-to-full side navigation on desktop without a full drawer.
8
+ - Let users reclaim screen space when they do not need the menu.
9
+
10
+ ## Import
11
+
12
+ ```javascript
13
+ import { CollapsibleSideBar, DrawerItem } from "flet-box";
14
+ ```
15
+
16
+ ## Basic example
17
+
18
+ The smallest useful version. Start here if this widget is new to you.
19
+
20
+ ```javascript
21
+ import { CollapsibleSideBar, DrawerItem } from "flet-box";
22
+
23
+ CollapsibleSideBar({
24
+ children: [
25
+ DrawerItem({ icon: "home", label: "Home", route: "/" }),
26
+ DrawerItem({ icon: "settings", label: "Settings", route: "/settings" }),
27
+ ],
28
+ });
29
+ ```
30
+
31
+ ## Props
32
+
33
+ | Prop | Type | Default | Description |
34
+ | --- | --- | --- | --- |
35
+ | `children` | Widget | — | The sidebar content. |
36
+ | `expanded` | boolean | `true` | Initial expanded state. |
37
+ | `id` | string | `"collapsible-sidebar"` | State key — give each sidebar its own `id` so they keep separate collapsed states. |
38
+ | `widthExpanded` | number | `260` | Width in px when expanded. |
39
+ | `widthCollapsed` | number | `60` | Width in px when collapsed. |
40
+ | `iconSize` | number | `24` | Size of the chevron toggle button. |
41
+ | `onToggle` | function | — | Fired with the new boolean state after toggling. |
42
+ | `bgColor` | Color | `colors.surface` | Background. |
43
+ | `borderRight` | string | `1px solid colors.border` | Right border CSS. |
44
+
45
+ These are the props specific to `CollapsibleSideBar`. It also accepts every [common prop](COMMON_PROPS.md); extra props and `style` are applied to the container.
46
+
47
+ ## Instance methods
48
+
49
+ - `updateWidth(width)` — resize the panel directly (a number is treated as pixels; a string is passed through).
50
+
51
+ ## Examples
52
+
53
+ ### Everyday example
54
+
55
+ ```javascript
56
+ import { CollapsibleSideBar, DrawerItem } from "flet-box";
57
+
58
+ CollapsibleSideBar({
59
+ id: "main-sidebar",
60
+ children: [
61
+ DrawerItem({ icon: "dashboard", label: "Dashboard", route: "/" }),
62
+ DrawerItem({ icon: "report", label: "Reports", route: "/reports" }),
63
+ ],
64
+ });
65
+ ```
66
+
67
+ ### Full example
68
+
69
+ ```javascript
70
+ import { runApp, Scaffold, CollapsibleSideBar, DrawerItem, Text } from "flet-box";
71
+
72
+ const sidebar = CollapsibleSideBar({
73
+ id: "admin-sidebar",
74
+ widthExpanded: 280,
75
+ widthCollapsed: 64,
76
+ children: [
77
+ DrawerItem({ icon: "admin_panel_settings", label: "Admin", route: "/admin" }),
78
+ DrawerItem({ icon: "group", label: "Users", route: "/users" }),
79
+ ],
80
+ onToggle: (expanded) => console.log("sidebar", expanded ? "open" : "closed"),
81
+ });
82
+
83
+ const app = Scaffold({
84
+ leftNavBar: sidebar,
85
+ body: Text({ text: "Admin area" }),
86
+ });
87
+
88
+ runApp(app, "root");
89
+ ```
90
+
91
+ ## Notes
92
+
93
+ - When collapsed, the content fades to `opacity: 0` and `pointer-events: none`; the chevron flips direction (`chevron_left` ↔ `chevron_right`).
94
+ - The collapsed/expanded state is stored via `useState` under the `id` key, so it is shared by every sidebar with the same `id`. Give unique `id`s to separate sidebars.
95
+ - It is the desktop-side layout that [AdaptiveScaffold](AdaptiveScaffold.md) produces automatically from a `leftNavBar`.
96
+ - Place it in a fix-width flex column (like `Scaffold`'s `leftNavBar` or a `Row`) — its `flex-shrink: 0` keeps the rest of the layout from squishing.
97
+
98
+ ## Related widgets
99
+ - [AdaptiveScaffold](AdaptiveScaffold.md)
100
+ - [Scaffold](Scaffold.md)
101
+ - [DrawerItem](DrawerItem.md)
102
+ - [Drawer](Drawer.md)
103
+
104
+ ---
105
+
106
+ ## Continue reading
107
+
108
+ - **Previous:** [Tabs](Tabs.md)
109
+ - **Next:** [State with `useState`](../guides/state.md) — Chapter 9 · State, Router & Services
110
+ - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
111
+
112
+ You are reading **Chapter 8 · App navigation** (8 of 8).
@@ -0,0 +1,129 @@
1
+ # Column
2
+
3
+ Vertical flex layout that stacks its children one below another. It is full width and leaves height at auto by default.
4
+
5
+ ## When to use it
6
+
7
+ Use Column for forms, lists of blocks, and any content that reads from top to bottom.
8
+
9
+ ## Quick start
10
+
11
+ ```javascript
12
+ import { Column, Text } from "flet-box";
13
+
14
+ const column = Column({
15
+ gap: 8,
16
+ children: [
17
+ Text({ text: "First" }),
18
+ Text({ text: "Second" }),
19
+ ],
20
+ });
21
+ ```
22
+
23
+ > The prop table is generated from `src/index.d.ts`; the examples use only documented props.
24
+
25
+ ## Props
26
+
27
+ | Prop | Type | Description |
28
+ | --- | --- | --- |
29
+ | `gap` | `number \| string` | Space between children along the layout axis. |
30
+ | `justifyContent` | `ContainerProps['justifyContent']` | Aligns children along the main axis (CSS `justify-content`). |
31
+ | `alignItems` | `ContainerProps['alignItems']` | Aligns children across the cross axis (CSS `align-items`). |
32
+ | `children` | `Widget[]` | An array of child widgets. Alias: `child` for a single child. |
33
+ | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
34
+
35
+ ### Common props
36
+
37
+ Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
38
+
39
+ | Prop | Type | Description |
40
+ | --- | --- | --- |
41
+ | `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
42
+ | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
43
+ | `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
44
+ | `padding` | `Padding` | Space inside the widget, between its content and its border. |
45
+ | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
46
+ | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
47
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
48
+ | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
49
+ | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
50
+ | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
51
+ | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
52
+ | `visible` | `boolean` | Whether the widget is rendered and visible. |
53
+ | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
54
+ | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
55
+ | `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
56
+ | `id` | `string` | DOM `id` for the rendered element. |
57
+ | `className` | `string` | CSS class names applied to the rendered element. |
58
+ | `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
59
+ | `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
60
+
61
+ ## Examples
62
+
63
+ ### Everyday
64
+
65
+ ```javascript
66
+ import { Column, Text, flex } from "flet-box";
67
+
68
+ const column = Column({
69
+ gap: 12,
70
+ padding: 16,
71
+ alignItems: "flex-start",
72
+ children: [
73
+ Text({ text: "Account settings", type: "h3", weight: "bold" }),
74
+ Text({ text: "Update your profile details." }),
75
+ ],
76
+ });
77
+ ```
78
+
79
+ ### Full
80
+
81
+ ```javascript
82
+ import { Button, Column, Text, flex } from "flet-box";
83
+
84
+ const column = Column({
85
+ gap: 16,
86
+ justifyContent: "flex-start",
87
+ alignItems: "stretch",
88
+ padding: 24,
89
+ bgColor: "#ffffff",
90
+ borderRadius: 16,
91
+ children: [
92
+ Text({ text: "Sign in", type: "h2", weight: "bold" }),
93
+ Button({ text: "Continue", fullWidth: true, onPress: () => console.log("go") }),
94
+ Button({ text: "Cancel", variant: "text" }),
95
+ ],
96
+ });
97
+ ```
98
+
99
+ ## Tips
100
+
101
+ - `gap` controls the space between stacked children.
102
+ - Set `alignItems: "center"` to center children horizontally in the column.
103
+ - Give children `expand` to split the available height between them.
104
+
105
+ ## Accessibility
106
+
107
+ - Maintain reading order from top to bottom and avoid purely visual reordering of the children.
108
+
109
+ ## Behavior
110
+
111
+ - The element is `display: flex` with `flex-direction: column`; passing `onPress` makes the whole column interactive.
112
+ - Children stack in the order given, and `justifyContent` controls how leftover vertical space is used.
113
+
114
+ ## Related widgets
115
+
116
+ - [Row](Row.md)
117
+ - [Container](Container.md)
118
+ - [Stack](Stack.md)
119
+ - [ListView](ListView.md)
120
+
121
+ ---
122
+
123
+ ## Continue reading
124
+
125
+ - **Previous:** [Row](Row.md)
126
+ - **Next:** [Stack](Stack.md)
127
+ - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
128
+
129
+ You are reading **Chapter 1 · First steps: the core mental model** (4 of 7).
@@ -0,0 +1,136 @@
1
+ # Container
2
+
3
+ General-purpose surface box. It is a flex column by default and groups children while controlling spacing, background, sizing, and overflow.
4
+
5
+ ## When to use it
6
+
7
+ Reach for Container whenever you need a rectangular surface to group content or apply padding, background, and size.
8
+
9
+ ## Quick start
10
+
11
+ ```javascript
12
+ import { Container, Text } from "flet-box";
13
+
14
+ const panel = Container({
15
+ padding: 16,
16
+ bgColor: "#f8fafc",
17
+ child: Text({ text: "Hello FletBox" }),
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
+ | `direction` | `'row' \| 'column'` | Main-axis direction for layout widgets (`row` or `column`). |
28
+ | `gap` | `number \| string` | Space between children along the layout axis. |
29
+ | `justifyContent` | `'flex-start' \| 'center' \| 'flex-end' \| 'space-between' \| 'space-around' \| 'space-evenly'` | Aligns children along the main axis (CSS `justify-content`). |
30
+ | `alignItems` | `'flex-start' \| 'center' \| 'flex-end' \| 'stretch'` | Aligns children across the cross axis (CSS `align-items`). |
31
+ | `wrap` | `boolean \| 'wrap' \| 'nowrap' \| 'wrap-reverse'` | Lets children wrap onto multiple lines. |
32
+ | `child` | `Widget` | A single child widget. Alias: `children` for a list. |
33
+ | `children` | `Widget[]` | An array of child widgets. Alias: `child` for a single child. |
34
+ | `expand` | `boolean \| number` | Lets a flex child grow to fill available space. |
35
+ | `flex` | `number` | Flex grow/shrink/basis shorthand for a flex child. |
36
+ | `minHeight` | `Size` | Minimum height the widget may shrink to. |
37
+ | `maxHeight` | `Size` | Maximum height the widget may grow to. |
38
+ | `minWidth` | `Size` | Minimum width the widget may shrink to. |
39
+ | `maxWidth` | `Size` | Maximum width the widget may grow to. |
40
+ | `overflow` | `'auto' \| 'hidden' \| 'visible' \| 'scroll'` | How overflowing content is handled (`hidden`, `auto`, `scroll`). |
41
+
42
+ ### Common props
43
+
44
+ Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
45
+
46
+ | Prop | Type | Description |
47
+ | --- | --- | --- |
48
+ | `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
49
+ | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
50
+ | `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
51
+ | `padding` | `Padding` | Space inside the widget, between its content and its border. |
52
+ | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
53
+ | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
54
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
55
+ | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
56
+ | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
57
+ | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
58
+ | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
59
+ | `visible` | `boolean` | Whether the widget is rendered and visible. |
60
+ | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
61
+ | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
62
+ | `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
63
+ | `id` | `string` | DOM `id` for the rendered element. |
64
+ | `className` | `string` | CSS class names applied to the rendered element. |
65
+ | `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
66
+ | `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
67
+
68
+ ## Examples
69
+
70
+ ### Everyday
71
+
72
+ ```javascript
73
+ import { Container, Text } from "flet-box";
74
+
75
+ const panel = Container({
76
+ direction: "column",
77
+ gap: 12,
78
+ padding: 16,
79
+ borderRadius: 12,
80
+ child: Text({ text: "Account settings" }),
81
+ });
82
+ ```
83
+
84
+ ### Full
85
+
86
+ ```javascript
87
+ import { Container, Text } from "flet-box";
88
+
89
+ const panel = Container({
90
+ direction: "column",
91
+ gap: 16,
92
+ padding: 24,
93
+ margin: 16,
94
+ borderRadius: 16,
95
+ bgColor: "#ffffff",
96
+ elevation: 2,
97
+ maxWidth: 480,
98
+ overflow: "auto",
99
+ children: [
100
+ Text({ text: "Account settings", type: "h3", weight: "bold" }),
101
+ Text({ text: "Update your profile details." }),
102
+ ],
103
+ });
104
+ ```
105
+
106
+ ## Tips
107
+
108
+ - Container is a column by default; set `direction: "row"` to lay children out horizontally.
109
+ - `bgColor` defaults to the theme surface and `overflow` defaults to `"auto"`, so long content scrolls.
110
+ - Use `expand` or `flex` to let a container share free space inside a parent flex layout.
111
+
112
+ ## Accessibility
113
+
114
+ - Keep one logical section per Container so screen-reader navigation lands on meaningful groups.
115
+
116
+ ## Behavior
117
+
118
+ - One child uses `child`; several use `children`; `gap` controls the space between them.
119
+ - `minWidth`, `maxWidth`, `minHeight`, and `maxHeight` constrain the surface, while `overflow` decides how excess content behaves.
120
+
121
+ ## Related widgets
122
+
123
+ - [Row](Row.md)
124
+ - [Column](Column.md)
125
+ - [Stack](Stack.md)
126
+ - [Card](Card.md)
127
+
128
+ ---
129
+
130
+ ## Continue reading
131
+
132
+ - **Previous:** [Text](Text.md)
133
+ - **Next:** [Row](Row.md)
134
+ - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
135
+
136
+ You are reading **Chapter 1 · First steps: the core mental model** (2 of 7).
@@ -0,0 +1,150 @@
1
+ # DataTable
2
+
3
+ DataTable renders tabular rows using a columns definition, with optional striping, hover and borders. Column entries can be plain strings or DataTableColumn objects.
4
+
5
+ ## When to use it
6
+
7
+ Use it to present structured, comparable data such as reports, lists or admin grids.
8
+
9
+ ## Quick start
10
+
11
+ ```javascript
12
+ import { DataTable } from "flet-box";
13
+
14
+ const table = DataTable({
15
+ columns: ["Name", "Role"],
16
+ rows: [{ Name: "Ada", Role: "Engineer" }],
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
+ | `columns` | `(string \| DataTableColumn)[]` | Number of grid columns. |
27
+ | `rows` | `Record<string, any>[]` | Data rows rendered by the table. |
28
+ | `striped` | `boolean` | Draws diagonal stripes across the bar. |
29
+ | `hoverable` | `boolean` | Highlights rows on hover. |
30
+ | `bordered` | `boolean` | Draws borders around cells. |
31
+ | `onRowClick` | `(row: any, index: number) => void` | Fired with the clicked row. |
32
+ | `headerBgColor` | `Color` | Background color of the header row. |
33
+ | `headerTextColor` | `Color` | Text color of the header row. |
34
+ | `headerFontWeight` | `string` | The `headerFontWeight` value for the widget. |
35
+ | `headerFontSize` | `number` | Size of the header font. |
36
+ | `rowBgColor` | `Color` | Background color for the row. |
37
+ | `rowTextColor` | `Color` | Color used for the row text. |
38
+ | `rowFontSize` | `number` | Size of the row font. |
39
+ | `stripedRowBgColor` | `Color` | Background color for alternating rows. |
40
+ | `hoverRowBgColor` | `Color` | Background color for the hover row. |
41
+ | `borderColor` | `Color` | Color used for the border. |
42
+ | `borderWidth` | `number` | Width of the border. |
43
+ | `cellPadding` | `Padding` | Padding inside each cell. |
44
+ | `headerCellPadding` | `Padding` | Padding for the header cell. |
45
+
46
+ ### Common props
47
+
48
+ Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
49
+
50
+ | Prop | Type | Description |
51
+ | --- | --- | --- |
52
+ | `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
53
+ | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
54
+ | `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
55
+ | `padding` | `Padding` | Space inside the widget, between its content and its border. |
56
+ | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
57
+ | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
58
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
59
+ | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
60
+ | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
61
+ | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
62
+ | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
63
+ | `visible` | `boolean` | Whether the widget is rendered and visible. |
64
+ | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
65
+ | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
66
+ | `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
67
+ | `id` | `string` | DOM `id` for the rendered element. |
68
+ | `className` | `string` | CSS class names applied to the rendered element. |
69
+ | `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
70
+ | `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
71
+
72
+ ## Examples
73
+
74
+ ### Everyday
75
+
76
+ ```javascript
77
+ import { DataTable } from "flet-box";
78
+
79
+ const table = DataTable({
80
+ columns: ["Name", "Role", "Status"],
81
+ rows: [
82
+ { Name: "Ada", Role: "Engineer", Status: "Active" },
83
+ { Name: "Linus", Role: "Maintainer", Status: "Away" },
84
+ ],
85
+ striped: true,
86
+ hoverable: true,
87
+ onRowClick: (row) => console.log(row),
88
+ });
89
+ ```
90
+
91
+ ### Full
92
+
93
+ ```javascript
94
+ import { DataTable } from "flet-box";
95
+
96
+ const table = DataTable({
97
+ columns: ["Name", "Role", "Status"],
98
+ rows: [
99
+ { Name: "Ada", Role: "Engineer", Status: "Active" },
100
+ { Name: "Linus", Role: "Maintainer", Status: "Away" },
101
+ ],
102
+ striped: true,
103
+ hoverable: true,
104
+ bordered: true,
105
+ headerBgColor: "#f1f5f9",
106
+ headerTextColor: "#0f172a",
107
+ headerFontWeight: "600",
108
+ headerFontSize: 14,
109
+ rowFontSize: 13,
110
+ stripedRowBgColor: "#f8fafc",
111
+ hoverRowBgColor: "#eff6ff",
112
+ borderColor: "#e2e8f0",
113
+ borderWidth: 1,
114
+ cellPadding: 12,
115
+ headerCellPadding: 14,
116
+ onRowClick: (row, index) => console.log(row, index),
117
+ });
118
+ ```
119
+
120
+ ## Tips
121
+
122
+ - Use string column keys that match your row objects, or pass column objects for explicit headers.
123
+ - Turn on striped and hoverable on wide tables to keep rows readable.
124
+ - Attach onRowClick when rows should open details or a drill-down view.
125
+
126
+ ## Accessibility
127
+
128
+ - Keep header text descriptive so the table has a clear structure for assistive technology.
129
+ - Do not encode meaning in color alone, such as striping, and keep text contrast sufficient.
130
+
131
+ ## Behavior
132
+
133
+ - Rows render from rows in order and re-render when rows or columns change.
134
+ - onRowClick receives the row object and its index.
135
+
136
+ ## Related widgets
137
+
138
+ - [ListView](ListView.md)
139
+ - [Card](Card.md)
140
+ - [Pagination](Pagination.md)
141
+
142
+ ---
143
+
144
+ ## Continue reading
145
+
146
+ - **Previous:** [InstallButton](InstallButton.md)
147
+ - **Next:** [Chart](Chart.md)
148
+ - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
149
+
150
+ You are reading **Chapter 6 · Data, rich content & effects** (1 of 13).
@@ -0,0 +1,109 @@
1
+ # Divider
2
+
3
+ A thin horizontal or vertical line that separates sections of content. Its thickness, color, and spacing are all adjustable.
4
+
5
+ ## When to use it
6
+
7
+ Use it to break up lists, forms, or toolbars where whitespace alone is not enough.
8
+
9
+ ## Quick start
10
+
11
+ ```javascript
12
+ import { Divider } from "flet-box";
13
+
14
+ const divider = Divider({});
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
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
24
+ | `thickness` | `number` | The `thickness` value for the widget. |
25
+ | `margin` | `number \| { top?: number; right?: number; bottom?: number; left?: number }` | Space outside the widget, between it and its neighbors. |
26
+ | `orientation` | `'horizontal' \| 'vertical'` | Orientation of the widget or control. |
27
+
28
+ ### Common props
29
+
30
+ Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
31
+
32
+ | Prop | Type | Description |
33
+ | --- | --- | --- |
34
+ | `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
35
+ | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
36
+ | `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
37
+ | `padding` | `Padding` | Space inside the widget, between its content and its border. |
38
+ | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
39
+ | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
40
+ | `color` | `Color` | Foreground color, usually the text or icon color. |
41
+ | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
42
+ | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
43
+ | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
44
+ | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
45
+ | `visible` | `boolean` | Whether the widget is rendered and visible. |
46
+ | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
47
+ | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
48
+ | `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
49
+ | `id` | `string` | DOM `id` for the rendered element. |
50
+ | `className` | `string` | CSS class names applied to the rendered element. |
51
+ | `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
52
+ | `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
53
+
54
+ ## Examples
55
+
56
+ ### Everyday
57
+
58
+ ```javascript
59
+ import { Divider } from "flet-box";
60
+
61
+ const divider = Divider({
62
+ thickness: 1,
63
+ color: "#e5e7eb",
64
+ margin: 16,
65
+ });
66
+ ```
67
+
68
+ ### Full
69
+
70
+ ```javascript
71
+ import { Divider } from "flet-box";
72
+
73
+ const divider = Divider({
74
+ orientation: "vertical",
75
+ thickness: 2,
76
+ color: "#cbd5e1",
77
+ margin: { top: 8, bottom: 8, left: 12, right: 12 },
78
+ });
79
+ ```
80
+
81
+ ## Tips
82
+
83
+ - Use orientation: "vertical" inside Row layouts and horizontal elsewhere.
84
+ - margin accepts a number or an object with per-side values for fine spacing control.
85
+
86
+ ## Accessibility
87
+
88
+ - Dividers are purely decorative and are hidden from assistive technology.
89
+
90
+ ## Behavior
91
+
92
+ - Horizontal dividers stretch to the available width; vertical ones need a parent height.
93
+ - thickness sets the line weight and defaults to a hairline.
94
+
95
+ ## Related widgets
96
+
97
+ - [ListTile](ListTile.md)
98
+ - [Card](Card.md)
99
+ - [Container](Container.md)
100
+
101
+ ---
102
+
103
+ ## Continue reading
104
+
105
+ - **Previous:** [Card](Card.md)
106
+ - **Next:** [ListTile](ListTile.md)
107
+ - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
108
+
109
+ You are reading **Chapter 3 · Layout, cards and lists** (2 of 8).