@lowdefy/docs-content 6.1.0 → 7.1.0

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 (284) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +7 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/validate.md +7 -4
  31. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  32. package/content/agents/agent-endpoint-tools.md +24 -0
  33. package/content/agents/agent-properties.md +13 -3
  34. package/content/agents/agent-server-hooks.md +1 -1
  35. package/content/agents/agentchat.md +43 -7
  36. package/content/agents/agentconversations.md +42 -8
  37. package/content/agents/agents-introduction.md +107 -0
  38. package/content/callback-reference/auth0logoutcallback.md +54 -0
  39. package/content/concepts/ai-agent-docs.md +455 -106
  40. package/content/concepts/blocks.md +150 -0
  41. package/content/concepts/connections-and-requests.md +402 -0
  42. package/content/concepts/custom-html.md +42 -0
  43. package/content/concepts/custom-styling.md +50 -5
  44. package/content/concepts/dynamic-page-content.md +309 -0
  45. package/content/concepts/events-and-actions.md +154 -2
  46. package/content/concepts/four-primitives.md +31 -0
  47. package/content/concepts/html-attributes.md +293 -0
  48. package/content/concepts/i18n.md +8 -3
  49. package/content/concepts/keyboard-shortcuts.md +2 -2
  50. package/content/concepts/layout-overview.md +1 -1
  51. package/content/concepts/logger.md +99 -0
  52. package/content/concepts/lowdefy-api.md +1319 -0
  53. package/content/concepts/lowdefy-schema.md +136 -3
  54. package/content/concepts/menus.md +8 -7
  55. package/content/concepts/module-authoring.md +76 -5
  56. package/content/concepts/modules.md +3 -1
  57. package/content/concepts/notifications.md +180 -0
  58. package/content/concepts/operators.md +7 -0
  59. package/content/concepts/page-and-app-state.md +252 -0
  60. package/content/concepts/page-paths.md +209 -0
  61. package/content/concepts/theming.md +582 -0
  62. package/content/connections/aigateway.md +375 -0
  63. package/content/connections/anthropic.md +169 -2
  64. package/content/connections/awss3.md +178 -2
  65. package/content/connections/axioshttp.md +181 -0
  66. package/content/connections/google.md +169 -2
  67. package/content/connections/mongodb.md +1014 -3
  68. package/content/connections/openai-connection.md +169 -2
  69. package/content/connections/sendgridmail.md +2 -0
  70. package/content/connections/smtp.md +3 -1
  71. package/content/connections/treg.md +329 -0
  72. package/content/container-blocks/affix.md +47 -7
  73. package/content/container-blocks/alert.md +76 -24
  74. package/content/container-blocks/badge.md +100 -24
  75. package/content/container-blocks/box.md +9 -9
  76. package/content/container-blocks/card.md +132 -27
  77. package/content/container-blocks/carousel.md +60 -7
  78. package/content/container-blocks/collapse.md +153 -9
  79. package/content/container-blocks/configprovider.md +35 -13
  80. package/content/container-blocks/confirmmodal.md +69 -23
  81. package/content/container-blocks/content.md +62 -98
  82. package/content/container-blocks/descriptions.md +45 -4
  83. package/content/container-blocks/drawer.md +139 -28
  84. package/content/container-blocks/dropdownmenu.md +119 -31
  85. package/content/container-blocks/flex.md +40 -62
  86. package/content/container-blocks/footer.md +15 -11
  87. package/content/container-blocks/googlemapsheatmap.md +1 -1
  88. package/content/container-blocks/googlemapsscript.md +2 -2
  89. package/content/container-blocks/header.md +71 -36
  90. package/content/container-blocks/label.md +34 -7
  91. package/content/container-blocks/layout.md +52 -34
  92. package/content/container-blocks/masonry.md +17 -71
  93. package/content/container-blocks/mobilemenu.md +131 -88
  94. package/content/container-blocks/modal.md +161 -26
  95. package/content/container-blocks/pageheadermenu.md +138 -31
  96. package/content/container-blocks/pagesidebarlayout.md +230 -27
  97. package/content/container-blocks/pagesidermenu.md +153 -43
  98. package/content/container-blocks/popover.md +34 -31
  99. package/content/container-blocks/result.md +32 -21
  100. package/content/container-blocks/sider.md +85 -122
  101. package/content/container-blocks/span.md +7 -7
  102. package/content/container-blocks/spinner.md +3 -3
  103. package/content/container-blocks/splitter.md +150 -68
  104. package/content/container-blocks/tabs.md +64 -12
  105. package/content/container-blocks/tooltip.md +22 -46
  106. package/content/container-blocks/watermark.md +22 -4
  107. package/content/controls/parallel_for.md +21 -2
  108. package/content/controls/reject.md +24 -3
  109. package/content/controls/return.md +17 -1
  110. package/content/controls/throw.md +1 -0
  111. package/content/controls/try.md +4 -2
  112. package/content/controls/while.md +46 -0
  113. package/content/deployment/deployment-environments.md +10 -7
  114. package/content/deployment/docker.md +22 -7
  115. package/content/deployment/node-server.md +4 -0
  116. package/content/deployment/vercel.md +17 -6
  117. package/content/display-blocks/aggrid.md +36 -19
  118. package/content/display-blocks/anchor.md +16 -15
  119. package/content/display-blocks/avatar.md +57 -37
  120. package/content/display-blocks/breadcrumb.md +70 -21
  121. package/content/display-blocks/button.md +93 -19
  122. package/content/display-blocks/calendar.md +12 -0
  123. package/content/display-blocks/clickablehtml.md +239 -0
  124. package/content/display-blocks/dangeroushtml.md +1 -1
  125. package/content/display-blocks/difflist.md +1 -1
  126. package/content/display-blocks/difftimeline.md +1 -1
  127. package/content/display-blocks/divider.md +64 -3
  128. package/content/display-blocks/dropdownbutton.md +81 -30
  129. package/content/display-blocks/echart.md +35 -1
  130. package/content/display-blocks/eventlog.md +363 -0
  131. package/content/display-blocks/floatbutton.md +129 -42
  132. package/content/display-blocks/html.md +61 -1
  133. package/content/display-blocks/icon.md +250 -67
  134. package/content/display-blocks/img.md +2 -2
  135. package/content/display-blocks/menu.md +146 -73
  136. package/content/display-blocks/message.md +38 -124
  137. package/content/display-blocks/notification.md +94 -222
  138. package/content/display-blocks/paragraph.md +59 -9
  139. package/content/display-blocks/pollingtimer.md +263 -0
  140. package/content/display-blocks/progress.md +96 -17
  141. package/content/display-blocks/qrcode.md +19 -4
  142. package/content/display-blocks/s3download.md +1 -1
  143. package/content/display-blocks/search.md +19 -9
  144. package/content/display-blocks/skeletonbutton.md +1 -0
  145. package/content/display-blocks/skeletoninput.md +1 -0
  146. package/content/display-blocks/statistic.md +75 -17
  147. package/content/display-blocks/steps.md +58 -25
  148. package/content/display-blocks/table.md +2527 -0
  149. package/content/display-blocks/tablelight.md +621 -0
  150. package/content/display-blocks/tag.md +102 -17
  151. package/content/display-blocks/title.md +50 -11
  152. package/content/display-blocks/tour.md +33 -23
  153. package/content/input-blocks/autocomplete.md +81 -9
  154. package/content/input-blocks/buttonselector.md +45 -8
  155. package/content/input-blocks/captcha.md +40 -0
  156. package/content/input-blocks/checkboxselector.md +97 -7
  157. package/content/input-blocks/checkboxswitch.md +33 -3
  158. package/content/input-blocks/colorselector.md +63 -14
  159. package/content/input-blocks/daterangeselector.md +165 -45
  160. package/content/input-blocks/dateselector.md +139 -41
  161. package/content/input-blocks/datetimeselector.md +158 -49
  162. package/content/input-blocks/inputgallery.md +3 -3
  163. package/content/input-blocks/intentinput.md +207 -0
  164. package/content/input-blocks/monthselector.md +120 -52
  165. package/content/input-blocks/multipleselector.md +150 -39
  166. package/content/input-blocks/numberinput.md +98 -12
  167. package/content/input-blocks/pagination.md +70 -14
  168. package/content/input-blocks/paragraphinput.md +51 -37
  169. package/content/input-blocks/passwordinput.md +60 -6
  170. package/content/input-blocks/phonenumberinput.md +59 -26
  171. package/content/input-blocks/placesautocomplete.md +319 -0
  172. package/content/input-blocks/radioselector.md +83 -7
  173. package/content/input-blocks/ratingslider.md +57 -26
  174. package/content/input-blocks/s3uploadbutton.md +24 -24
  175. package/content/input-blocks/s3uploaddragger.md +3 -3
  176. package/content/input-blocks/s3uploadphoto.md +5 -5
  177. package/content/input-blocks/segmentedselector.md +72 -32
  178. package/content/input-blocks/selector.md +109 -21
  179. package/content/input-blocks/switch.md +65 -17
  180. package/content/input-blocks/tableinput.md +445 -0
  181. package/content/input-blocks/tagmultipleselector.md +114 -0
  182. package/content/input-blocks/tagselector.md +114 -0
  183. package/content/input-blocks/textarea.md +32 -3
  184. package/content/input-blocks/textinput.md +70 -29
  185. package/content/input-blocks/tiptapinput.md +1 -1
  186. package/content/input-blocks/tiptapmentioninput.md +2 -2
  187. package/content/input-blocks/titleinput.md +39 -12
  188. package/content/input-blocks/treeinput.md +49 -25
  189. package/content/input-blocks/treemultipleselector.md +127 -10
  190. package/content/input-blocks/treeselector.md +97 -9
  191. package/content/input-blocks/upload.md +64 -15
  192. package/content/input-blocks/uploaddragger.md +17 -1
  193. package/content/input-blocks/uploadphoto.md +18 -1
  194. package/content/input-blocks/weekselector.md +120 -55
  195. package/content/learn/introduction.md +27 -0
  196. package/content/learn/quickstart.md +53 -0
  197. package/content/list-blocks/controlledlist.md +24 -15
  198. package/content/list-blocks/list.md +11 -11
  199. package/content/list-blocks/masonrylist.md +7 -34
  200. package/content/migration/auth-upgrade.md +337 -0
  201. package/content/migration/upgrade-guide.md +1 -0
  202. package/content/migration/v3-to-v4.md +417 -0
  203. package/content/migration/v6-to-v7.md +620 -0
  204. package/content/operators/_agent.md +155 -0
  205. package/content/operators/_app.md +2 -1
  206. package/content/operators/_array.md +122 -1
  207. package/content/operators/_build.md +1 -0
  208. package/content/operators/_credential.md +57 -0
  209. package/content/operators/_cron.md +292 -0
  210. package/content/operators/_date.md +2 -0
  211. package/content/operators/_error.md +24 -1
  212. package/content/operators/_get.md +6 -6
  213. package/content/operators/_hmac.md +78 -0
  214. package/content/operators/_js.md +2 -1
  215. package/content/operators/_location.md +1 -1
  216. package/content/operators/_media.md +13 -0
  217. package/content/operators/_module.md +56 -2
  218. package/content/operators/_operator.md +17 -3
  219. package/content/operators/_path_params.md +82 -0
  220. package/content/operators/_ref.md +258 -0
  221. package/content/operators/_request.md +1 -1
  222. package/content/operators/_request_details.md +6 -0
  223. package/content/operators/_type.md +14 -3
  224. package/content/operators/_url_query.md +2 -0
  225. package/content/operators/_user.md +3 -3
  226. package/content/plugins/plugins-actions.md +10 -0
  227. package/content/plugins/plugins-connections.md +25 -0
  228. package/content/plugins/plugins-dev.md +66 -0
  229. package/content/plugins/plugins-icon-sets.md +267 -0
  230. package/content/plugins/plugins-introduction.md +27 -1
  231. package/content/plugins/plugins.md +19 -0
  232. package/content/plugins/posthog.md +359 -0
  233. package/content/provider-reference/auth-js-providers.md +107 -0
  234. package/content/provider-reference/openidconnectprovider.md +44 -0
  235. package/content/recipes/recipes.md +16 -0
  236. package/content/reference/actions-reference.md +31 -0
  237. package/content/reference/blocks-reference.md +35 -0
  238. package/content/reference/cli.md +403 -0
  239. package/content/reference/connections-reference.md +23 -0
  240. package/content/reference/operators-reference.md +47 -0
  241. package/content/reference/reference.md +16 -0
  242. package/content/reference/schema-reference.md +12 -0
  243. package/content/testing/config-tests.md +677 -0
  244. package/content/testing/e2e-configuration.md +31 -1
  245. package/content/testing/e2e-getting-started.md +1 -1
  246. package/content/testing/e2e-introduction.md +1 -1
  247. package/content/testing/e2e-writing-tests.md +12 -1
  248. package/content/testing/explore-pull-request.md +136 -0
  249. package/content/testing/journey-data-sets.md +326 -0
  250. package/content/tutorial/tutorial-actions-operators.md +2 -2
  251. package/content/tutorial/tutorial-add-blocks.md +2 -2
  252. package/content/tutorial/tutorial-create-page.md +48 -2
  253. package/content/tutorial/tutorial-display-data-page.md +3 -3
  254. package/content/tutorial/tutorial-requests-api.md +155 -0
  255. package/content/tutorial/tutorial-requests-sql.md +153 -0
  256. package/content/tutorial/tutorial-start.md +66 -1
  257. package/content/user-authentication/auth-configuration.md +267 -0
  258. package/content/user-authentication/auth-providers.md +24 -0
  259. package/content/user-authentication/auth-steps.md +141 -0
  260. package/content/user-authentication/login-and-logout.md +160 -8
  261. package/content/user-authentication/mcp-oauth.md +424 -0
  262. package/content/user-authentication/organizations.md +246 -0
  263. package/content/user-authentication/protected-pages-apis.md +97 -0
  264. package/content/user-authentication/roles.md +49 -0
  265. package/content/user-authentication/two-factor.md +229 -0
  266. package/content/user-authentication/user-object.md +58 -0
  267. package/content/user-authentication/users-introduction.md +8 -0
  268. package/content/websockets/websocket-publish.md +105 -0
  269. package/content/websockets/websocket-subscriptions.md +136 -0
  270. package/content/websockets/websockets-introduction.md +101 -0
  271. package/hazards.json +44 -0
  272. package/index.json +3691 -14
  273. package/package.json +11 -1
  274. package/scripts/collectImportedFiles.js +80 -0
  275. package/scripts/extractAgentDocs.js +41 -30
  276. package/scripts/hashDocSources.js +38 -0
  277. package/scripts/isRedirectPage.js +26 -0
  278. package/scripts/recordSourceHashes.js +100 -0
  279. package/scripts/resolvePageSections.js +42 -0
  280. package/scripts/sectionKind.js +27 -0
  281. package/content/concepts/cli.md +0 -223
  282. package/content/other/introduction.md +0 -39
  283. package/content/other/next-auth-providers.md +0 -3
  284. /package/content/{other → actions}/updatesession.md +0 -0
@@ -3,7 +3,7 @@
3
3
  Lowdefy provides several ways to style blocks and customize the look of your app:
4
4
 
5
5
  - **`class`** — Apply CSS class names (including Tailwind CSS utility classes) to blocks.
6
- - **`style`** — Apply inline CSS styles to blocks. Use `--`-prefixed keys to target specific parts (CSS slots).
6
+ - **`style`** — Apply inline CSS styles to blocks. Use `.`-prefixed keys to target specific parts (CSS slots).
7
7
  - **`properties.theme`** — Override antd design tokens per block. See [Theming](/theming) for details.
8
8
  - **`public/styles.css`** — A global CSS file for custom styles.
9
9
 
@@ -11,7 +11,7 @@ Lowdefy provides several ways to style blocks and customize the look of your app
11
11
 
12
12
  The `class` property applies CSS class names to a block. [Tailwind CSS](https://tailwindcss.com/) is always available in Lowdefy apps, so you can use any Tailwind utility classes directly.
13
13
 
14
- `class` can be a string, an array of strings, or an object keyed by the block's CSS keys:
14
+ `class` can be a string, an array of strings, an object keyed by the block's CSS keys, or an operator that computes the classes at runtime:
15
15
 
16
16
  ```yaml
17
17
  # String — applied to the block wrapper
@@ -27,15 +27,60 @@ The `class` property applies CSS class names to a block. [Tailwind CSS](https://
27
27
  - shadow-lg
28
28
  - rounded-xl
29
29
 
30
- # Object — target specific parts of the block using CSS keys (-- prefix)
30
+ # Object — target specific parts of the block using CSS keys (. prefix)
31
31
  - id: my_card
32
32
  type: Card
33
33
  class:
34
34
  .element: "shadow-lg"
35
35
  .header: "bg-gray-100"
36
36
  .body: "p-8"
37
+
38
+ # Operator — the block's classes are computed at runtime
39
+ - id: status_badge
40
+ type: Box
41
+ class:
42
+ _if:
43
+ test:
44
+ _eq:
45
+ - _state: status
46
+ - error
47
+ then: bg-red-100 text-red-700
48
+ else: bg-green-100 text-green-700
49
+ ```
50
+
51
+ An operator's result may be a string, an array of strings, or an object of `{ class: boolean }` where each class with a truthy value is applied:
52
+
53
+ ```yaml
54
+ - id: status_badge
55
+ type: Box
56
+ class:
57
+ _if:
58
+ test:
59
+ _eq:
60
+ - _state: status
61
+ - error
62
+ then:
63
+ bg-red-100: true
64
+ text-red-700: true
65
+ else: bg-green-100
37
66
  ```
38
67
 
68
+ An operator at the root of `class` computes the classes of the block wrapper. To compute a specific part's classes, place the operator under that CSS key:
69
+
70
+ ```yaml
71
+ - id: my_card
72
+ type: Card
73
+ class:
74
+ .header:
75
+ _if:
76
+ test:
77
+ _state: highlighted
78
+ then: bg-yellow-100
79
+ else: bg-gray-100
80
+ ```
81
+
82
+ > **Note:** An operator's result is never expanded into a map of CSS keys — a root operator always sets the block wrapper's classes. A result with dot-prefixed keys (`{ .element: p-4 }`) is reported as a config error, and those keys are not applied as classes.
83
+
39
84
  Tailwind responsive prefixes work as expected:
40
85
 
41
86
  ```yaml
@@ -58,7 +103,7 @@ See [Theming](/theming) for the full list of bridged tokens and how to add custo
58
103
 
59
104
  ## The `style` property
60
105
 
61
- The `style` property applies inline CSS styles to a block. When used with flat CSS properties (no `--` prefix), it targets the block's layout wrapper:
106
+ The `style` property applies inline CSS styles to a block. When used with flat CSS properties (no `.` prefix), it targets the block's layout wrapper:
62
107
 
63
108
  ```yaml
64
109
  - id: my_block
@@ -103,7 +148,7 @@ Each block's documentation page lists its supported CSS keys.
103
148
 
104
149
  Each block declares named style targets in its `meta.cssKeys`. For example, the [Card](/Card) block supports: `element`, `header`, `body`, `cover`, `actions`, `extra`.
105
150
 
106
- Both `class` (object form) and `style` use `--`-prefixed versions of these keys to target specific parts of a block. The `--` prefix mirrors CSS custom property convention and avoids confusion with CSS property names.
151
+ Both `class` (object form) and `style` use `.`-prefixed versions of these keys to target specific parts of a block. The `.` prefix mirrors CSS selector convention and avoids confusion with CSS property names.
107
152
 
108
153
  To find the CSS keys for a block, check the block's documentation page.
109
154
 
@@ -0,0 +1,309 @@
1
+ # Dynamic Page Content
2
+
3
+ Dynamic page content lets parts of a page — or a whole page — be resolved on the server at page load. You place a `Dynamic` block on a page and point it at an [API endpoint](/lowdefy-api). When the page is requested, the server calls the endpoint's routine in-process, the routine returns block config, and the server validates that config and splices it into the page before responding. The client renders the result like any other page.
4
+
5
+ Dynamic page content is useful when the structure of a page depends on runtime data:
6
+
7
+ - A dashboard whose sections depend on the user's role, plan, or feature flags.
8
+ - A form generated from a workflow definition stored in a database.
9
+ - A product page whose layout comes from a CMS record.
10
+ - Table views, kanban columns, or navigation derived from tenant configuration.
11
+
12
+ For content where only the _data_ changes, use [requests](/connections-and-requests) — they are cached, re-fetchable, and don't reset page state. Reach for dynamic page content when the _blocks themselves_ need to change per request.
13
+
14
+ ## How It Works
15
+
16
+ 1. A user requests a page containing a `Dynamic` block.
17
+ 2. The server checks page authorization as usual, then calls the endpoint configured on each `Dynamic` block — in-process, no HTTP. The endpoint's own auth is also checked against the user's session.
18
+ 3. The routine executes with a payload containing the block's `params`, the `pageId`, the `blockId`, and the page request's `urlQuery` and `pathParams`.
19
+ 4. The routine returns `{ blocks: [...] }` — ordinary Lowdefy block config.
20
+ 5. The server builds and validates the returned blocks: block, action and operator types must be in the app's client bundle, block properties are validated against each block type's schema, and `Request` actions must reference requests defined statically on the page.
21
+ 6. The validated blocks become the `Dynamic` block's content, and the page is sent to the client.
22
+
23
+ If resolution fails, the `Dynamic` block renders its `fallback` slot (or nothing) and the error is logged on the server — the page still loads. Set `required: true` to fail the whole page request instead.
24
+
25
+ ## The Dynamic Block
26
+
27
+ ```yaml
28
+ - id: insights
29
+ type: Dynamic
30
+ properties:
31
+ endpointId: resolve_insights # Required. The endpoint that resolves this content.
32
+ params: # Optional. Static values passed to the endpoint.
33
+ area: insights
34
+ required: false # Optional. true fails the page load on resolution failure.
35
+ types: # Optional. Extra types the endpoint may return.
36
+ blocks:
37
+ - Statistic
38
+ slots:
39
+ fallback: # Optional. Rendered when resolution fails.
40
+ blocks:
41
+ - id: insights_unavailable
42
+ type: Html
43
+ properties:
44
+ html: Insights are unavailable right now.
45
+ ```
46
+
47
+ `params` must not contain operators — the page config is static. Runtime values belong in the endpoint routine, which reads the payload with `_payload` and the session with `_user`.
48
+
49
+ A page that should be entirely dynamic is just a page whose body is a single `Dynamic` block.
50
+
51
+ ## The Resolver Endpoint
52
+
53
+ The endpoint is a normal API endpoint. Use `type: InternalApi` so it has no HTTP route — it is then only callable by the server itself.
54
+
55
+ The endpoint receives this payload:
56
+
57
+ - `params: object` - The `Dynamic` block's `params`, verbatim.
58
+ - `pageId: string` - The page being resolved.
59
+ - `blockId: string` - The `Dynamic` block's id.
60
+ - `urlQuery: object` - The query parameters of the page request.
61
+ - `pathParams: object` - The values of the placeholders in the page's [`path`](/page-paths), as strings. `{}` for a page without placeholders.
62
+
63
+ The routine must return an object with a `blocks` array:
64
+
65
+ ```yaml
66
+ api:
67
+ - id: resolve_insights
68
+ type: InternalApi
69
+ auth:
70
+ public: false
71
+ routine:
72
+ - id: get_sections
73
+ type: MongoDBFind
74
+ connectionId: mongodb
75
+ properties:
76
+ query:
77
+ roles:
78
+ $in:
79
+ _user: roles
80
+ area:
81
+ _payload: params.area
82
+ - :return:
83
+ blocks:
84
+ _array.map:
85
+ on:
86
+ _step: get_sections
87
+ callback:
88
+ _function:
89
+ __object.assign:
90
+ - id:
91
+ __args: 0.section_id
92
+ type: Statistic
93
+ properties:
94
+ title:
95
+ __args: 0.title
96
+ value:
97
+ __args: 0.value
98
+ ```
99
+
100
+ All operators registered on the server — including shared operators like `_state`, `_if` and `_string` — are evaluated during `:return` (`_state` reads the routine's own `:set_state` state). To defer an operator to the client instead, prefix it with one extra underscore, the same convention `_function` bodies use for `__args`:
101
+
102
+ ```yaml
103
+ - :return:
104
+ blocks:
105
+ - id: greeting
106
+ type: Html
107
+ properties:
108
+ html:
109
+ __state: name_input # unescaped to `_state` — evaluates on the client
110
+ ```
111
+
112
+ The server strips one leading underscore from `__`-prefixed keys in the returned config, so `__state` reaches the client as `_state` and binds to page state like any static block. Client-only operators (`_request`, `_global`, ...) have no server implementation and need no escaping, but the `__` form works for them too and is the consistent style.
113
+
114
+ > **Never place `_secret` in returned block config.** It evaluates during `:return` and the resulting value ships to the browser.
115
+
116
+ ### Data in the returned config is literal
117
+
118
+ While a Dynamic block's endpoint evaluates its `:return`, data read at runtime stays data. That covers step results, the payload, routine state, `:for` items, and values built from data, such as `_json.parse` of a stored string. Three rules apply:
119
+
120
+ - **Data cannot carry operators.** No operator may return a value that contains operators. A record holding `{ _request: ... }` or `{ __state: ... }` fails resolution, and the block renders its fallback. The error names the operator and where in its result the operator was found.
121
+ - **Data cannot be a block or an action.** Without a [dynamic blocks policy](#dynamic-blocks-policies), every block and action in the returned content must be written in the `:return` config. Data may fill values inside those blocks (an id, a title, a type, a list of options), but a block or action that is itself data an operator returned, or a copy of it, fails resolution. To render stored block config, check it with a `ValidateDynamic` step under a policy.
122
+ - **Data cannot become an operator by merging.** An object from data that `_object.assign` merges with other config must not be left with an operator key alone, for example next to a key whose value is a function or evaluates to undefined on the client.
123
+
124
+ Data may nest at most 200 levels deep; deeper data fails resolution with an error saying so. Only keys that name one of the app's operators count as operators. Data such as a search hit's `{ _score: 0.5 }` or `{ _source: { ... } }` stays data.
125
+
126
+ Write client operators in the `:return` config itself. Only operators that pass their own already-checked params through — `_if`, `_switch`, `_if_none`, `_get`, `_args`, `_function`, `_log`, `_array` and `_object` (except `_object.fromEntries` and `_object.defineProperty`) — may return them, so mapping data rows into blocks with `_array.map` and `_function` works as shown above.
127
+
128
+ These patterns return config through data and fail resolution:
129
+
130
+ - **Blocks built up in routine state** (`:set_state` in a loop, then `_state` in `:return`). Build the list inside `:return` with `_array.map` or `_array.concat`.
131
+ - **Blocks returned by a nested endpoint** and read with `_step`. Share block config with `_ref` instead.
132
+ - **A `:for` over a literal list of block configs**, read with `_item`. Map the list inside `:return`.
133
+ - **Blocks built by `_js` or `_jsonata`.** Return the data from them and map it into blocks inside `:return`.
134
+ - **Stored block config returned as it is**, whether read directly, picked out with `_get`, or copied or extended by an `_array.map` callback (`__args: 0`, `__object.assign`). Put the Dynamic block under a policy and return the content through `ValidateDynamic` (see [Rendering stored content under a policy](#rendering-stored-content-under-a-policy)).
135
+
136
+ ## Using urlQuery in the Routine
137
+
138
+ The page request's query string is forwarded to the resolver as `urlQuery` in the payload. A page loaded as `/products?category=shoes&sort=price` resolves with `urlQuery: { category: 'shoes', sort: 'price' }`:
139
+
140
+ ```yaml
141
+ api:
142
+ - id: resolve_products
143
+ type: InternalApi
144
+ routine:
145
+ - id: get_products
146
+ type: MongoDBFind
147
+ connectionId: mongodb
148
+ properties:
149
+ query:
150
+ category:
151
+ _payload: urlQuery.category
152
+ options:
153
+ sort:
154
+ - - _payload: urlQuery.sort
155
+ - 1
156
+ - :return:
157
+ blocks:
158
+ - id: product_count
159
+ type: Html
160
+ properties:
161
+ html:
162
+ _string.concat:
163
+ - 'Found '
164
+ - _array.length:
165
+ _step: get_products
166
+ - ' products in "'
167
+ - _payload: urlQuery.category
168
+ - '"'
169
+ ```
170
+
171
+ The resolver executes on every navigation to the page — a menu link, a `Link` action (including to the same page), or the browser back and forward buttons all re-resolve the content on the server. Dynamic page config is never served from a client cache.
172
+
173
+ ## Using pathParams in the Routine
174
+
175
+ On a page with a [`path`](/page-paths), the values of its placeholders are forwarded as `pathParams`, next to `urlQuery`. A page with `path: forms/{form_id}`, loaded as `/forms/F-17`, resolves with `pathParams: { form_id: 'F-17' }`, read with `_payload: pathParams.form_id`. Each set of values gets its own page instance, but a page with a `Dynamic` block still starts fresh on every visit.
176
+
177
+ ## Client Bundle Types
178
+
179
+ The client bundle is fixed at build time — resolved content can only use block, action and operator types the build included. Types used on static pages are always available. To use a type that appears _only_ in dynamic content, declare it on the `Dynamic` block:
180
+
181
+ ```yaml
182
+ - id: insights
183
+ type: Dynamic
184
+ properties:
185
+ endpointId: resolve_insights
186
+ types:
187
+ blocks:
188
+ - Statistic
189
+ - EChart
190
+ actions:
191
+ - CopyToClipboard
192
+ operators:
193
+ - _number
194
+ ```
195
+
196
+ The build bundles declared types into the client. If a routine returns a type that is not in the bundle, resolution fails with a clear error instead of a silently broken page.
197
+
198
+ ## Dynamic Blocks Policies
199
+
200
+ A dynamic blocks policy, declared under `policies.dynamicBlocks` in `lowdefy.yaml`, lets a Dynamic block render block config that is stored as data — a form built by a form builder, or config a model generated — within limits the app declares. The policy lists what the content may use. Anything unlisted fails, and the policy is checked twice with the same function: by a `ValidateDynamic` step before the content is stored, and on every page get before the content renders.
201
+
202
+ ```yaml
203
+ policies:
204
+ dynamicBlocks:
205
+ - id: generated_form
206
+ blocks:
207
+ - Title
208
+ - Paragraph
209
+ - TextInput
210
+ - Selector
211
+ actions:
212
+ - SetState
213
+ - CallAPI
214
+ operators:
215
+ - _state
216
+ - _eq
217
+ - _if
218
+ endpoints:
219
+ - submit_form_response
220
+ links:
221
+ pages:
222
+ - form_submitted
223
+ origins:
224
+ - https://example.com
225
+ state: form
226
+ ```
227
+
228
+ | Key | Default | Meaning |
229
+ | --------------- | --------- | ----------------------------------------------------------------------------------------------------------- |
230
+ | `id` | required | Policy id, referenced by Dynamic blocks and steps. |
231
+ | `blocks` | required | Block types the content may use. `Dynamic` cannot be listed. |
232
+ | `actions` | `[]` | Action types the content may use. |
233
+ | `operators` | `[]` | Client operator names. `_string` allows every `_string` method. `_operator` cannot be listed. |
234
+ | `endpoints` | `[]` | Endpoints a `CallAPI` action in the content may call. |
235
+ | `requests` | `[]` | Page requests a `Request` action may call. The build checks every page that hosts the policy defines them. |
236
+ | `links.pages` | `[]` | Page ids the content may link to. A link by app path, like `/form_submitted`, is matched to its page. |
237
+ | `links.origins` | `[]` | Exact origins (`https://example.com`) the content may link to or load from. |
238
+ | `state` | none | When set, input block ids, `SetState` keys and `_state` reads must sit under this state path. |
239
+ | `html` | `false` | When `false`, no string in the content may contain HTML tag syntax. |
240
+ | `limits` | see below | `depth` (10), `blocks` (500), `bytes` (262144) and `actionsPerEvent` (20). They can be raised, not removed. |
241
+
242
+ Besides the lists, a policy requires literal values wherever the content names a target: `properties`, `style`, events and action lists; the params of `Link`, `CallAPI`, `Request` and `SetState`; every `_state` key; and every `pageId` and URL. URLs must be app paths or use a listed origin — including image sources, markdown links and CSS `url()`. A block's properties schema marks which properties hold a URL (see [Plugins](/plugins-introduction)), so a URL property is checked whatever it is called, such as `Search` `indexUrl` or `QRCode` `icon`; every value no schema marks, including action params and the properties of blocks that mark none, is checked by its key (`url`, `href`, `src`, ...). URLs are read as the browser reads them, so surrounding spaces and embedded tabs or newlines do not hide one.
243
+
244
+ > With `html: false`, an operator that builds strings (`_string`, `_uri`, `_base64`, `_json`) can still assemble HTML at render time from content that passed the check. The build warns when a policy lists one. Leave them out of policies for generated content.
245
+
246
+ ### Rendering stored content under a policy
247
+
248
+ Put the policy on the Dynamic block, and return the content through a `ValidateDynamic` step with the same policy. Data stays literal in a Dynamic endpoint (see [Data in the returned config is literal](#data-in-the-returned-config-is-literal)); the blocks of a `ValidateDynamic` step that passed with the block's policy are the one exception.
249
+
250
+ ```yaml
251
+ pages:
252
+ - id: form
253
+ type: PageHeaderMenu
254
+ blocks:
255
+ - id: generated
256
+ type: Dynamic
257
+ properties:
258
+ endpointId: get_form_blocks
259
+ policy: generated_form
260
+ - id: submit
261
+ type: Button
262
+ properties:
263
+ title: Submit
264
+ events:
265
+ onClick:
266
+ - id: save
267
+ type: CallAPI
268
+ params:
269
+ endpointId: submit_form_response
270
+ payload:
271
+ answers:
272
+ _state: form
273
+
274
+ api:
275
+ - id: get_form_blocks
276
+ type: InternalApi
277
+ routine:
278
+ - id: get_form
279
+ type: MongoDBFindOne
280
+ connectionId: forms
281
+ properties:
282
+ query:
283
+ _id:
284
+ _payload: urlQuery.formId
285
+ - id: check
286
+ type: ValidateDynamic
287
+ properties:
288
+ policy: generated_form
289
+ blocks:
290
+ _step: get_form.blocks
291
+ - :return:
292
+ blocks:
293
+ _step: check.blocks
294
+ ```
295
+
296
+ The policy's types are bundled into the page, so a Dynamic block with `policy` does not declare `properties.types`. Content that breaks the policy at page get renders the fallback, and the log lists each violation.
297
+
298
+ ### Checking generated content
299
+
300
+ A generator calls `ValidateDynamic` with `throwOnInvalid: false` and feeds the errors back to the model. Each error has a `path` into the submitted content, a `rule` and a `message`. `DescribeDynamicPolicy` returns what the policy allows, with the properties schema of each block and the params schema of each action and operator, to build the prompt from. See [Validating Dynamic Content As A Routine Step](/lowdefy-api#validating-dynamic-content-as-a-routine-step).
301
+
302
+ ## Rules and Limitations
303
+
304
+ - **No `requests` in resolved content.** Request artifacts are written at build time. Resolved blocks reference requests defined statically on the page via `Request` actions, or call endpoints with `CallAPI`.
305
+ - **Nesting is allowed** — resolved content may contain further `Dynamic` blocks, up to 5 levels deep.
306
+ - **Page state resets per visit.** Dynamic pages build a fresh context on every navigation, since the server may resolve different content each time. Keep cross-navigation state in `_global` or `_url_query`.
307
+ - **Endpoint auth always applies.** A public page pointing at a role-protected endpoint renders the fallback for users without the role — useful for role-gated sections.
308
+ - **Data cannot carry operators or be blocks.** Operators in step results, payload or state returned into `:return` fail resolution, and so do blocks and actions that are data, except the blocks of a `ValidateDynamic` step under the block's policy. See [Data in the returned config is literal](#data-in-the-returned-config-is-literal) and [Dynamic Blocks Policies](#dynamic-blocks-policies).
309
+ - **`blockId` namespace is shared.** Resolved blocks share the page's state namespace, so `_state` binds across static and dynamic blocks. Keep blockIds unique, as on any page.
@@ -66,6 +66,7 @@ The schema for passing actions to Lowdefy events is:
66
66
  ```
67
67
  (eventName: (action | control)[])
68
68
  (eventName: {
69
+ bubble?: boolean,
69
70
  shortcut?: string | string[],
70
71
  debounce?: {
71
72
  ms?: number,
@@ -241,6 +242,47 @@ To control the debounce delay, set `debounce.ms` to the number of milliseconds t
241
242
  type: ActionType2
242
243
  ```
243
244
 
245
+ ## Nested blocks and event bubbling
246
+
247
+ A click, key press or other browser event starts on the element under the pointer and passes up through every block around it, like a `Button` inside a clickable `Card`, or a clickable `Box` in a `List` row. Lowdefy runs only the innermost event that handles it: once a block with actions for the event fires, the blocks around it skip that same browser event. Clicking the `Button` runs the button's `onClick`, not the card's. A block without an event for the interaction, like a `Paragraph` in the card, passes it on, so clicking the text still runs the card's `onClick`.
248
+
249
+ Set `bubble: true` on the inner event to also run the events of the blocks around it. `bubble` passes the browser event one handler further up; set it again on the outer event to pass it further still.
250
+
251
+ ###### Button in a clickable card example:
252
+ ```yaml
253
+ - id: order_card
254
+ type: Card
255
+ events:
256
+ onClick:
257
+ - id: open_order
258
+ type: Link
259
+ params: order-detail
260
+ blocks:
261
+ - id: delete_button
262
+ type: Button
263
+ properties:
264
+ title: Delete
265
+ events:
266
+ onClick:
267
+ - id: delete_order
268
+ type: Request
269
+ params: delete_order
270
+ - id: select_button
271
+ type: Button
272
+ properties:
273
+ title: Select and open
274
+ events:
275
+ onClick:
276
+ bubble: true # also runs the card's onClick
277
+ try:
278
+ - id: select_order
279
+ type: SetState
280
+ params:
281
+ selected: true
282
+ ```
283
+
284
+ Only blocks the browser event passed through, around the block that handled it, are skipped. Other blocks' events are never affected, nor are events that run from actions, requests or timers, or events of a block an action called a method on: a `Table` next to the button, or holding it in its toolbar, still fires `onSelectionChange` after the button's `CallMethod` cleared its selection. Inside an `AgGrid`, clicks on a cell's buttons, links, menus, inputs or selection checkbox fire only that control's event, never `onRowClick` or `onCellClick`.
285
+
244
286
  ## Keyboard Shortcuts
245
287
 
246
288
  Events can be triggered by keyboard shortcuts. Add a `shortcut` property to an event to bind a key combination — when pressed, the event fires as if the user clicked the block. See the [Keyboard Shortcuts](/keyboard-shortcuts) page for the full shortcut format, common shortcuts, recipes, and more.
@@ -256,9 +298,11 @@ events:
256
298
  searchOpen: true
257
299
  ```
258
300
 
259
- ## Page initialization events
301
+ ## Page lifecycle events
302
+
303
+ The first blocks on a page, usually a [`container`](/container) type block, can define page lifecycle events. The page initialization events `onInit` and `onInitAsync` are triggered when the page is first loaded, and the browser lifecycle events `onVisible`, `onHidden`, `onOnline`, `onOffline` and `onResize` are triggered while the page stays open. All blocks have `onMount` and `onMountAsync` events, that can be used to initialize the page or blocks.
260
304
 
261
- The first blocks on a page, usually a [`container`](/container) type block, can define `onInit` and `onInitAsync` events. All blocks have `onMount` and `onMountAsync` events, that can be used to initialize the page or blocks.
305
+ ### Page initialization events
262
306
 
263
307
  The `onInit` event is triggered the first time a page is loaded. This event blocks page render, in other words, the page __will__ remain in a loading state, rendering only the progress bar, until all the actions have completed execution. It can be used to set up [`state`](/page-and-app-state). Actions that take a long time to execute, like `Request`, should be used sparingly here for a better user experience.
264
308
 
@@ -268,6 +312,108 @@ The `onMount` event is triggered every time a block is rendered on a page. This
268
312
 
269
313
  The `onMountAsync` event is triggered every time a block is mounted, but does not render the block in loading.
270
314
 
315
+ ### Browser lifecycle events
316
+
317
+ The first blocks on a page can also define events that react to the browser: `onVisible`, `onHidden`, `onOnline`, `onOffline` and `onResize`. These are useful to refresh data that went stale while the user was away, instead of polling the server on a timer.
318
+
319
+ These events are only attached while the page is mounted, and are removed again when the user navigates away, so they never trigger for a page the user has left. They never trigger on the initial page load either — only a change after the page has loaded triggers them. Their action chains run like `onMountAsync`: they do not keep the page or block in a loading state.
320
+
321
+ The `onVisible` event is triggered when the browser tab becomes visible again, or when the window regains focus. Rapid pairs of these signals — a tab switch usually produces both — are coalesced over 300ms, so the event is only triggered once. The [`_event`](/_event) object contains `visible: true` and `reason`, which is `visibility` when the browser reported the tab becoming visible, or `focus` when the window regained focus.
322
+
323
+ ```yaml
324
+ events:
325
+ onVisible:
326
+ - id: refresh_tasks
327
+ type: Request
328
+ params: get_tasks
329
+ ```
330
+
331
+ The `onHidden` event is triggered when the browser tab is hidden, or when the window loses focus, coalesced in the same way. The `_event` object contains `visible: false` and the same `reason` field.
332
+
333
+ ```yaml
334
+ events:
335
+ onHidden:
336
+ - id: stop_refreshing
337
+ type: SetState
338
+ params:
339
+ live: false
340
+ ```
341
+
342
+ The `onOnline` and `onOffline` events are triggered when the browser reports that the network connection was regained or lost. The `_event` object contains `online: true` or `online: false`.
343
+
344
+ ```yaml
345
+ events:
346
+ onOnline:
347
+ - id: back_online
348
+ type: Message
349
+ params:
350
+ content: You are back online.
351
+ onOffline:
352
+ - id: went_offline
353
+ type: Message
354
+ params:
355
+ status: warning
356
+ content: You are offline, changes will not be saved.
357
+ ```
358
+
359
+ The `onResize` event is triggered when the window is resized, debounced by 150ms so that the actions only run once the user stops resizing. Blocks that use the [`_media`](/_media) operator are re-evaluated for the new window size before the `onResize` actions run. The `_event` object contains the `width` and `height` of the window.
360
+
361
+ ```yaml
362
+ events:
363
+ onResize:
364
+ - id: set_width
365
+ type: SetState
366
+ params:
367
+ window_width:
368
+ _event: width
369
+ ```
370
+
371
+ ## App events
372
+
373
+ Events can also be defined for the whole app, in the `events` object at the root of `lowdefy.yaml`. App events run once each time the app is loaded in the browser, whichever page is opened first, and do not run again when the user navigates between pages. Opening the app in a new tab, or reloading the browser, loads the app again. App events are a good place to set up [`global`](/page-and-app-state) values that every page uses, like user settings fetched from an [API endpoint](/lowdefy-api).
374
+
375
+ - `onInit`: Runs before the first page's own events. The page stays in its loading state, rendering only the progress bar, until the app `onInit` actions have finished, so the first page's `onInit` can read the values it set with [`_global`](/_global).
376
+ - `onInitAsync`: Runs once the app `onInit` has finished, without blocking the page. The first page's events do not wait for it, and pages re-render when it sets `global` values.
377
+
378
+ ###### Load user settings when the app loads:
379
+ ```yaml
380
+ # lowdefy.yaml
381
+ global:
382
+ settings: null
383
+ events:
384
+ onInit:
385
+ - id: set_user
386
+ type: SetGlobal
387
+ params:
388
+ userName:
389
+ _user: name
390
+ onInitAsync:
391
+ try:
392
+ - id: fetch_settings
393
+ type: CallAPI
394
+ params:
395
+ endpointId: user_settings
396
+ - id: set_settings
397
+ type: SetGlobal
398
+ params:
399
+ settings:
400
+ _actions: fetch_settings.response.response
401
+ catch:
402
+ - id: warn
403
+ type: DisplayMessage
404
+ params:
405
+ content: Could not load your settings.
406
+ status: warning
407
+ pages:
408
+ # ...
409
+ ```
410
+
411
+ App events run outside any page, so page state, inputs, requests, blocks and subscriptions are not available to them. The build fails if an app event uses the `CallMethod`, `Request`, `Reset`, `ResetValidation`, `SetFocus`, `SetState`, `Subscribe`, `Unsubscribe` or `Validate` actions, or the `_input`, `_request`, `_request_details`, `_state` or `_websocket` operators. Use [`CallAPI`](/CallAPI) to fetch data, [`SetGlobal`](/SetGlobal) to store it, and operators like [`_user`](/_user), [`_url_query`](/_url_query), [`_global`](/_global) and [`_actions`](/_actions) to read values. A [`Link`](/Link) action can redirect the user, for example to an onboarding page.
412
+
413
+ App event errors are handled like page event errors: the error message is displayed, the error is logged, and the `catch` actions run. A failed app `onInit` does not stop the page from loading, and the app `onInitAsync` still runs after it. App events do not support `shortcut`.
414
+
415
+ The app events config is sent to the browser with the rest of the app config, like `global`, so do not put secrets in it.
416
+
271
417
  ## Action types
272
418
 
273
419
  The following actions can be used:
@@ -295,8 +441,14 @@ See additional action type available under the Actions tab in the menu.
295
441
  - The [`_actions`](/_actions) operator is available for sequential actions to use the values returned from preceding actions in the chain.
296
442
  - Actions have a `skip` field that can be used to skip action execution.
297
443
  - Action lists also support the [`:if`](/:if), [`:switch`](/:switch) and [`:return`](/:return) controls — `skip` gates one action, `:if` gates a group, `:switch` picks between alternatives, and `:return` ends the event early.
444
+ - A browser event runs only the innermost block event that handles it. Set `bubble: true` on an event to also run the events of the blocks around it.
298
445
  - Events support `shortcut` to bind keyboard shortcuts to the event. The shortcut fires the event when the key combination is pressed.
299
446
  - The `onInit` event is triggered the first time a page is mounted and keeps the page in loading until all actions have finished.
300
447
  - The `onInitAsync` event is triggered the first time a page is mounted and does not keep the page in loading.
301
448
  - The `onMount` events is triggered the every time a block is mounted and keeps the block in loading until all actions have finished.
302
449
  - The `onMountAsync` event is triggered the every time a block is mounted, after `onMount` has completed, and does not keep the block in loading.
450
+ - The `onVisible` and `onHidden` events are triggered when the browser tab is shown or hidden, or when the window gains or loses focus, coalesced over 300ms.
451
+ - The `onOnline` and `onOffline` events are triggered when the browser reports that the network connection was regained or lost.
452
+ - The `onResize` event is triggered when the window is resized, debounced by 150ms.
453
+ - Browser lifecycle events are never triggered on the initial page load, and are removed when the user navigates away from the page.
454
+ - App events, defined in the root `events` object, run once per app load: the app `onInit` runs before the first page's events and keeps the page in loading, and the app `onInitAsync` runs after it without blocking the page.
@@ -0,0 +1,31 @@
1
+ # The Four Primitives
2
+
3
+ Every Lowdefy app is composed from four primitives. Learn these four ideas and you can read any Lowdefy app.
4
+
5
+ What the user sees. React components — inputs, tables, charts, containers — arranged into pages.
6
+
7
+ How the app thinks. Functions written in config that read state and shape data, re-evaluated on every change.
8
+
9
+ What happens next. Event handlers that run when users click, pages load, or values change.
10
+
11
+ Where the data lives. Server-side integrations to databases, APIs, and services, called through requests.
12
+
13
+ ## How they fit together
14
+
15
+ A page is a tree of **blocks**. Blocks hold values in page **state** — a `TextInput` writes what the user types, a `Selector` writes the chosen option.
16
+
17
+ **Operators** are functions evaluated in config. They read state and context — `_state`, `_user`, `_media` — and compute the values around them: a block's visibility, a title's text, a request's query. When state changes, operators re-evaluate and the page updates.
18
+
19
+ User interaction fires **events** — a click, a page load, an input change. Each event runs a list of **actions**: `SetState` writes state, `Link` navigates, `Request` calls the server.
20
+
21
+ **Connections** define the services your app talks to — a database, an HTTP API, an AI provider. **Requests** execute against them on the server, so credentials never reach the browser. Actions trigger requests; operators read their results.
22
+
23
+ One loop, four primitives: blocks render state → events fire actions → actions set state and call requests → operators re-evaluate → blocks re-render.
24
+
25
+ ## Where to go deeper
26
+
27
+ - [Blocks](/blocks) — the block object and the page tree.
28
+ - [Operators](/operators) — evaluation rules and where operators work.
29
+ - [Events and Actions](/events-and-actions) — event chains, error handling.
30
+ - [Connections and Requests](/connections-and-requests) — the server-side model.
31
+ - Or see everything in the [Reference](/reference).