@lowdefy/docs-content 6.0.0 → 7.0.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 (285) 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 +5 -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/setstate.md +2 -0
  31. package/content/actions/validate.md +7 -4
  32. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  33. package/content/agents/agent-endpoint-tools.md +24 -0
  34. package/content/agents/agent-properties.md +13 -3
  35. package/content/agents/agent-server-hooks.md +1 -1
  36. package/content/agents/agentchat.md +41 -4
  37. package/content/agents/agentconversations.md +42 -8
  38. package/content/agents/agents-introduction.md +107 -0
  39. package/content/callback-reference/auth0logoutcallback.md +54 -0
  40. package/content/concepts/ai-agent-docs.md +455 -106
  41. package/content/concepts/blocks.md +150 -0
  42. package/content/concepts/connections-and-requests.md +402 -0
  43. package/content/concepts/custom-html.md +42 -0
  44. package/content/concepts/custom-styling.md +50 -5
  45. package/content/concepts/dynamic-page-content.md +309 -0
  46. package/content/concepts/events-and-actions.md +185 -2
  47. package/content/concepts/four-primitives.md +31 -0
  48. package/content/concepts/html-attributes.md +293 -0
  49. package/content/concepts/i18n.md +12 -3
  50. package/content/concepts/keyboard-shortcuts.md +2 -2
  51. package/content/concepts/layout-overview.md +1 -1
  52. package/content/concepts/logger.md +99 -0
  53. package/content/concepts/lowdefy-api.md +1319 -0
  54. package/content/concepts/lowdefy-schema.md +144 -3
  55. package/content/concepts/menus.md +8 -7
  56. package/content/concepts/module-authoring.md +76 -5
  57. package/content/concepts/modules.md +3 -1
  58. package/content/concepts/notifications.md +180 -0
  59. package/content/concepts/operators.md +7 -0
  60. package/content/concepts/page-and-app-state.md +252 -0
  61. package/content/concepts/page-paths.md +209 -0
  62. package/content/concepts/theming.md +582 -0
  63. package/content/connections/aigateway.md +375 -0
  64. package/content/connections/anthropic.md +169 -2
  65. package/content/connections/awss3.md +178 -2
  66. package/content/connections/axioshttp.md +181 -0
  67. package/content/connections/google.md +169 -2
  68. package/content/connections/mongodb.md +1014 -3
  69. package/content/connections/openai-connection.md +169 -2
  70. package/content/connections/sendgridmail.md +3 -0
  71. package/content/connections/smtp.md +16 -0
  72. package/content/connections/treg.md +329 -0
  73. package/content/container-blocks/affix.md +47 -7
  74. package/content/container-blocks/alert.md +76 -24
  75. package/content/container-blocks/badge.md +100 -24
  76. package/content/container-blocks/box.md +9 -9
  77. package/content/container-blocks/card.md +132 -27
  78. package/content/container-blocks/carousel.md +60 -7
  79. package/content/container-blocks/collapse.md +153 -9
  80. package/content/container-blocks/configprovider.md +35 -13
  81. package/content/container-blocks/confirmmodal.md +69 -23
  82. package/content/container-blocks/content.md +62 -98
  83. package/content/container-blocks/descriptions.md +45 -4
  84. package/content/container-blocks/drawer.md +139 -28
  85. package/content/container-blocks/dropdownmenu.md +119 -31
  86. package/content/container-blocks/flex.md +40 -62
  87. package/content/container-blocks/footer.md +15 -11
  88. package/content/container-blocks/googlemapsheatmap.md +1 -1
  89. package/content/container-blocks/googlemapsscript.md +2 -2
  90. package/content/container-blocks/header.md +71 -36
  91. package/content/container-blocks/label.md +34 -7
  92. package/content/container-blocks/layout.md +52 -34
  93. package/content/container-blocks/masonry.md +17 -71
  94. package/content/container-blocks/mobilemenu.md +131 -88
  95. package/content/container-blocks/modal.md +161 -26
  96. package/content/container-blocks/pageheadermenu.md +138 -31
  97. package/content/container-blocks/pagesidebarlayout.md +230 -27
  98. package/content/container-blocks/pagesidermenu.md +153 -43
  99. package/content/container-blocks/popover.md +34 -31
  100. package/content/container-blocks/result.md +32 -21
  101. package/content/container-blocks/sider.md +85 -122
  102. package/content/container-blocks/span.md +7 -7
  103. package/content/container-blocks/spinner.md +3 -3
  104. package/content/container-blocks/splitter.md +150 -68
  105. package/content/container-blocks/tabs.md +64 -12
  106. package/content/container-blocks/tooltip.md +22 -46
  107. package/content/container-blocks/watermark.md +22 -4
  108. package/content/controls/parallel_for.md +21 -2
  109. package/content/controls/reject.md +26 -3
  110. package/content/controls/return.md +17 -1
  111. package/content/controls/throw.md +30 -2
  112. package/content/controls/try.md +24 -2
  113. package/content/controls/while.md +46 -0
  114. package/content/deployment/deployment-environments.md +146 -0
  115. package/content/deployment/docker.md +23 -7
  116. package/content/deployment/node-server.md +4 -0
  117. package/content/deployment/vercel.md +25 -19
  118. package/content/display-blocks/aggrid.md +33 -16
  119. package/content/display-blocks/anchor.md +16 -15
  120. package/content/display-blocks/avatar.md +57 -37
  121. package/content/display-blocks/breadcrumb.md +70 -21
  122. package/content/display-blocks/button.md +93 -19
  123. package/content/display-blocks/calendar.md +12 -0
  124. package/content/display-blocks/clickablehtml.md +239 -0
  125. package/content/display-blocks/dangeroushtml.md +1 -1
  126. package/content/display-blocks/difflist.md +1 -1
  127. package/content/display-blocks/difftimeline.md +1 -1
  128. package/content/display-blocks/divider.md +64 -3
  129. package/content/display-blocks/dropdownbutton.md +81 -30
  130. package/content/display-blocks/echart.md +35 -1
  131. package/content/display-blocks/eventlog.md +363 -0
  132. package/content/display-blocks/floatbutton.md +129 -42
  133. package/content/display-blocks/html.md +61 -1
  134. package/content/display-blocks/icon.md +250 -67
  135. package/content/display-blocks/img.md +2 -2
  136. package/content/display-blocks/menu.md +146 -73
  137. package/content/display-blocks/message.md +38 -124
  138. package/content/display-blocks/notification.md +94 -222
  139. package/content/display-blocks/paragraph.md +59 -9
  140. package/content/display-blocks/pollingtimer.md +263 -0
  141. package/content/display-blocks/progress.md +96 -17
  142. package/content/display-blocks/qrcode.md +19 -4
  143. package/content/display-blocks/s3download.md +1 -1
  144. package/content/display-blocks/search.md +19 -9
  145. package/content/display-blocks/skeletonbutton.md +1 -0
  146. package/content/display-blocks/skeletoninput.md +1 -0
  147. package/content/display-blocks/statistic.md +75 -17
  148. package/content/display-blocks/steps.md +58 -25
  149. package/content/display-blocks/table.md +2527 -0
  150. package/content/display-blocks/tablelight.md +621 -0
  151. package/content/display-blocks/tag.md +102 -17
  152. package/content/display-blocks/title.md +50 -11
  153. package/content/display-blocks/tour.md +33 -23
  154. package/content/input-blocks/autocomplete.md +81 -9
  155. package/content/input-blocks/buttonselector.md +45 -8
  156. package/content/input-blocks/captcha.md +40 -0
  157. package/content/input-blocks/checkboxselector.md +97 -7
  158. package/content/input-blocks/checkboxswitch.md +33 -3
  159. package/content/input-blocks/colorselector.md +63 -14
  160. package/content/input-blocks/daterangeselector.md +165 -45
  161. package/content/input-blocks/dateselector.md +139 -41
  162. package/content/input-blocks/datetimeselector.md +158 -49
  163. package/content/input-blocks/inputgallery.md +3 -3
  164. package/content/input-blocks/intentinput.md +207 -0
  165. package/content/input-blocks/monthselector.md +120 -52
  166. package/content/input-blocks/multipleselector.md +150 -39
  167. package/content/input-blocks/numberinput.md +98 -12
  168. package/content/input-blocks/pagination.md +70 -14
  169. package/content/input-blocks/paragraphinput.md +51 -37
  170. package/content/input-blocks/passwordinput.md +60 -6
  171. package/content/input-blocks/phonenumberinput.md +59 -26
  172. package/content/input-blocks/placesautocomplete.md +319 -0
  173. package/content/input-blocks/radioselector.md +83 -7
  174. package/content/input-blocks/ratingslider.md +57 -26
  175. package/content/input-blocks/s3uploadbutton.md +24 -24
  176. package/content/input-blocks/s3uploaddragger.md +3 -3
  177. package/content/input-blocks/s3uploadphoto.md +5 -5
  178. package/content/input-blocks/segmentedselector.md +72 -32
  179. package/content/input-blocks/selector.md +109 -21
  180. package/content/input-blocks/switch.md +65 -17
  181. package/content/input-blocks/tableinput.md +445 -0
  182. package/content/input-blocks/tagmultipleselector.md +114 -0
  183. package/content/input-blocks/tagselector.md +114 -0
  184. package/content/input-blocks/textarea.md +32 -3
  185. package/content/input-blocks/textinput.md +70 -29
  186. package/content/input-blocks/tiptapinput.md +1 -1
  187. package/content/input-blocks/tiptapmentioninput.md +2 -2
  188. package/content/input-blocks/titleinput.md +39 -12
  189. package/content/input-blocks/treeinput.md +49 -25
  190. package/content/input-blocks/treemultipleselector.md +127 -10
  191. package/content/input-blocks/treeselector.md +97 -9
  192. package/content/input-blocks/upload.md +64 -15
  193. package/content/input-blocks/uploaddragger.md +17 -1
  194. package/content/input-blocks/uploadphoto.md +18 -1
  195. package/content/input-blocks/weekselector.md +120 -55
  196. package/content/learn/introduction.md +27 -0
  197. package/content/learn/quickstart.md +53 -0
  198. package/content/learn/showcase.md +8 -0
  199. package/content/list-blocks/controlledlist.md +24 -15
  200. package/content/list-blocks/list.md +11 -11
  201. package/content/list-blocks/masonrylist.md +7 -34
  202. package/content/migration/auth-upgrade.md +337 -0
  203. package/content/migration/upgrade-guide.md +1 -0
  204. package/content/migration/v3-to-v4.md +417 -0
  205. package/content/migration/v6-to-v7.md +620 -0
  206. package/content/operators/_agent.md +155 -0
  207. package/content/operators/_app.md +2 -1
  208. package/content/operators/_array.md +122 -1
  209. package/content/operators/_build.md +1 -0
  210. package/content/operators/_credential.md +57 -0
  211. package/content/operators/_cron.md +292 -0
  212. package/content/operators/_date.md +2 -0
  213. package/content/operators/_error.md +196 -0
  214. package/content/operators/_get.md +6 -6
  215. package/content/operators/_hmac.md +78 -0
  216. package/content/operators/_js.md +2 -1
  217. package/content/operators/_location.md +1 -1
  218. package/content/operators/_media.md +13 -0
  219. package/content/operators/_module.md +56 -2
  220. package/content/operators/_operator.md +17 -3
  221. package/content/operators/_path_params.md +82 -0
  222. package/content/operators/_ref.md +258 -0
  223. package/content/operators/_request.md +1 -1
  224. package/content/operators/_request_details.md +6 -0
  225. package/content/operators/_type.md +14 -3
  226. package/content/operators/_url_query.md +2 -0
  227. package/content/operators/_user.md +3 -3
  228. package/content/plugins/plugins-actions.md +10 -0
  229. package/content/plugins/plugins-connections.md +25 -0
  230. package/content/plugins/plugins-dev.md +66 -0
  231. package/content/plugins/plugins-icon-sets.md +267 -0
  232. package/content/plugins/plugins-introduction.md +27 -1
  233. package/content/plugins/plugins.md +19 -0
  234. package/content/plugins/posthog.md +359 -0
  235. package/content/provider-reference/auth-js-providers.md +107 -0
  236. package/content/provider-reference/openidconnectprovider.md +44 -0
  237. package/content/recipes/recipes.md +16 -0
  238. package/content/reference/actions-reference.md +31 -0
  239. package/content/reference/blocks-reference.md +35 -0
  240. package/content/reference/cli.md +403 -0
  241. package/content/reference/connections-reference.md +23 -0
  242. package/content/reference/operators-reference.md +47 -0
  243. package/content/reference/reference.md +16 -0
  244. package/content/reference/schema-reference.md +12 -0
  245. package/content/testing/config-tests.md +677 -0
  246. package/content/testing/e2e-configuration.md +31 -1
  247. package/content/testing/e2e-getting-started.md +1 -1
  248. package/content/testing/e2e-introduction.md +1 -1
  249. package/content/testing/e2e-writing-tests.md +12 -1
  250. package/content/testing/explore-pull-request.md +136 -0
  251. package/content/testing/journey-data-sets.md +326 -0
  252. package/content/tutorial/tutorial-actions-operators.md +2 -2
  253. package/content/tutorial/tutorial-add-blocks.md +2 -2
  254. package/content/tutorial/tutorial-create-page.md +48 -2
  255. package/content/tutorial/tutorial-display-data-page.md +3 -3
  256. package/content/tutorial/tutorial-requests-api.md +155 -0
  257. package/content/tutorial/tutorial-requests-sql.md +153 -0
  258. package/content/tutorial/tutorial-start.md +66 -1
  259. package/content/user-authentication/auth-configuration.md +267 -0
  260. package/content/user-authentication/auth-providers.md +24 -0
  261. package/content/user-authentication/auth-steps.md +141 -0
  262. package/content/user-authentication/login-and-logout.md +160 -8
  263. package/content/user-authentication/mcp-oauth.md +424 -0
  264. package/content/user-authentication/organizations.md +246 -0
  265. package/content/user-authentication/protected-pages-apis.md +97 -0
  266. package/content/user-authentication/roles.md +49 -0
  267. package/content/user-authentication/two-factor.md +229 -0
  268. package/content/user-authentication/user-object.md +58 -0
  269. package/content/user-authentication/users-introduction.md +8 -0
  270. package/content/websockets/websocket-publish.md +105 -0
  271. package/content/websockets/websocket-subscriptions.md +136 -0
  272. package/content/websockets/websockets-introduction.md +101 -0
  273. package/hazards.json +56 -0
  274. package/index.json +3472 -14
  275. package/package.json +10 -1
  276. package/scripts/extractAgentDocs.js +41 -30
  277. package/scripts/hashDocSources.js +38 -0
  278. package/scripts/isRedirectPage.js +26 -0
  279. package/scripts/recordSourceHashes.js +97 -0
  280. package/scripts/resolvePageSections.js +42 -0
  281. package/scripts/sectionKind.js +27 -0
  282. package/content/concepts/cli.md +0 -223
  283. package/content/other/introduction.md +0 -39
  284. package/content/other/next-auth-providers.md +0 -3
  285. /package/content/{other → actions}/updatesession.md +0 -0
@@ -78,3 +78,261 @@ The file path to the referenced file, from the root of the project directory.
78
78
  > Within module content, the `module` field can reference a declared dependency name (from the module's `dependencies` in `module.lowdefy.yaml`). The build resolves abstract names to concrete entry IDs via the dependency wiring. From app-level config, `module` is always a concrete entry ID.
79
79
 
80
80
  #### Examples
81
+
82
+ ###### Reference pages:
83
+ ```yaml
84
+ # lowdefy.yaml
85
+ lowdefy: 6.1.0
86
+ pages:
87
+ - _ref: pages/page1.yaml
88
+ - _ref: pages/page2.yaml
89
+ ```
90
+ ```yaml
91
+ # pages/page1.yaml
92
+ id: page1
93
+ type: PageHeaderMenu
94
+ blocks:
95
+ # ...
96
+ ```
97
+ ```yaml
98
+ # pages/page2.yaml
99
+ id: page2
100
+ type: PageHeaderMenu
101
+ blocks:
102
+ # ...
103
+ ```
104
+ Returns:
105
+ ```
106
+ lowdefy: 6.1.0
107
+ pages:
108
+ - id: page1
109
+ type: PageHeaderMenu
110
+ blocks:
111
+ # ...
112
+ - id: page2
113
+ type: PageHeaderMenu
114
+ blocks:
115
+ # ...
116
+ ```
117
+
118
+ ###### Using a standardized input label template:
119
+ ```yaml
120
+ blocks:
121
+ - id: name
122
+ type: TextInput
123
+ properties:
124
+ label:
125
+ _ref:
126
+ path: label.yaml
127
+ vars:
128
+ title: Name
129
+ description: Your name and surname.
130
+ - id: age
131
+ type: NumberInput
132
+ properties:
133
+ label:
134
+ _ref:
135
+ path: label.yaml
136
+ vars:
137
+ title: Age
138
+ description: Your age.
139
+ ```
140
+ ```yaml
141
+ # label.yaml
142
+ title:
143
+ _var: title
144
+ extra:
145
+ _var: description
146
+ span: 8
147
+ colon: false
148
+ extraStyle:
149
+ color: '#546358'
150
+ ```
151
+ Returns:
152
+ ```yaml
153
+ blocks:
154
+ - id: name
155
+ type: TextInput
156
+ properties:
157
+ label:
158
+ title: Name
159
+ extra: Your name and surname.
160
+ span: 8
161
+ colon: false
162
+ extraStyle:
163
+ color: '#546358'
164
+ - id: age
165
+ type: NumberInput
166
+ properties:
167
+ label:
168
+ title: Age
169
+ extra: Your age.
170
+ span: 8
171
+ colon: false
172
+ extraStyle:
173
+ color: '#546358'
174
+ ```
175
+
176
+ ###### Use key:
177
+ ```yaml
178
+ # lowdefy.yaml
179
+ lowdefy: 6.1.0
180
+ version:
181
+ _ref:
182
+ path: package.json
183
+ field: version
184
+ ```
185
+ ```json
186
+ // package.json
187
+ {
188
+ "version": "1.0.0"
189
+ }
190
+ ```
191
+ Returns:
192
+ ```
193
+ lowdefy: 6.1.0
194
+ version: 1.0.0
195
+ ```
196
+
197
+ ###### Local or shared resolver:
198
+
199
+ This resolver function will first look for the configuration file in the current working directory, but if the file is not found it will be read from an adjacent "shared" directory. This pattern can be used to build apps that mostly use a shared configuration, with a few components that are customised per app.
200
+
201
+ ```js
202
+ // resolvers/useLocalOrSharedConfig.js
203
+ const fs = require('fs');
204
+ const path = require('path');
205
+ const { promisify } = require('util');
206
+
207
+ const readFilePromise = promisify(fs.readFile);
208
+
209
+ async function useLocalOrSharedConfig(refPath, vars, context) {
210
+ let fileContent
211
+ try {
212
+ fileContent = await readFilePromise(path.resolve(refPath), 'utf8');
213
+ return fileContent;
214
+ } catch (error) {
215
+ if (error.code === 'ENOENT') {
216
+ fileContent = readFilePromise(path.resolve('../shared', refPath), 'utf8');
217
+ return fileContent;
218
+ }
219
+ throw error;
220
+ }
221
+
222
+
223
+ }
224
+
225
+ module.exports = useLocalOrSharedConfig;
226
+ ```
227
+
228
+ ```yaml
229
+ // lowdefy.yaml
230
+ lowdefy: 6.1.0
231
+
232
+ cli:
233
+ refResolver: resolvers/useLocalOrSharedConfig.js
234
+
235
+ pages:
236
+ - _ref: pages/local-page.yaml
237
+ - _ref: pages/shared-page.yaml
238
+ ```
239
+
240
+ ###### This transformer adds a standard footer to each page:
241
+
242
+ ```js
243
+ // transformers/addFooter.js
244
+
245
+ function addFooter(page, vars) {
246
+ const footer = {
247
+ // ...
248
+ };
249
+ page.areas.footer = footer;
250
+ return page;
251
+ }
252
+ module.exports = addFooter;
253
+ ```
254
+ ```yaml
255
+ // lowdefy.yaml
256
+ lowdefy: 6.1.0
257
+
258
+ pages:
259
+ - _ref:
260
+ path: pages/page1.yaml
261
+ transformer: transformers/addFooter.js
262
+ ```
263
+ ###### Reference a module component:
264
+ ```yaml
265
+ blocks:
266
+ - _ref:
267
+ module: notifications
268
+ component: notification-badge
269
+ vars:
270
+ position: top-right
271
+ ```
272
+
273
+ ###### Data export with key extraction:
274
+ ```yaml
275
+ icon:
276
+ _ref:
277
+ module: events
278
+ component: event_types
279
+ key: login.icon
280
+ ```
281
+
282
+ ###### Cross-module component ref within a module:
283
+ ```yaml
284
+ # contacts module embedding companies' selector
285
+ blocks:
286
+ - _ref:
287
+ module: companies # abstract dependency name
288
+ component: company-selector
289
+ vars:
290
+ field_id: company_id
291
+ ```
292
+
293
+ ###### Module menu inside a MenuGroup:
294
+ ```yaml
295
+ menus:
296
+ - id: main
297
+ links:
298
+ - id: home
299
+ type: MenuLink
300
+ pageId: home
301
+ - id: team-admin
302
+ type: MenuGroup
303
+ properties:
304
+ title: Team Admin
305
+ links:
306
+ _ref:
307
+ module: team-users
308
+ menu: default
309
+ ```
310
+
311
+ ###### Using ES Modules with `.mjs` file extension:
312
+
313
+ ```js
314
+ // resolvers/useLocalOrSharedConfig.mjs
315
+ import fs from 'fs';
316
+ import path from 'path';
317
+ import { promisify } from 'util';
318
+
319
+ const readFilePromise = promisify(fs.readFile);
320
+
321
+ async function useLocalOrSharedConfig(refPath, vars, context) {
322
+ let fileContent
323
+ try {
324
+ fileContent = await readFilePromise(path.resolve(refPath), 'utf8');
325
+ return fileContent;
326
+ } catch (error) {
327
+ if (error.code === 'ENOENT') {
328
+ fileContent = readFilePromise(path.resolve('../shared', refPath), 'utf8');
329
+ return fileContent;
330
+ }
331
+ throw error;
332
+ }
333
+
334
+
335
+ }
336
+
337
+ export default useLocalOrSharedConfig;
338
+ ```
@@ -6,7 +6,7 @@
6
6
 
7
7
  The `_request` operator returns the response value of a request. If the request has not yet been called, or is still executing, the returned value is `null`. Dot notation and [block list indexes](/lists) are supported. A dot is always a separator unless it is escaped with `\.`, which makes it a literal character in the key — `a\.b` reads the key `a.b`; inside a double-quoted YAML string the escape must be written `\\.`. On an unescaped path each segment is tried as a plain key first, and a plain key that is present always wins: a nested `a.b.c` shadows a literal `a.b` key, and a present `a` blocks the literal key even when it holds a string or number rather than an object. A literal dotted key is only reached where the plain key is absent, so escape it to address one reliably. The leading segment of a `_request` path is the request id and is matched exactly, so the rule above applies to the part of the path after it. For more detailed information about a request, the [_request_details](/_request_details) operator can be used.
8
8
 
9
- If the request was called via the [`Request`](/Request) action with `holdValue: true`, `_request` returns the previous response while the new request is loading instead of returning `null`. Use `_request_details: <id>.loading` to detect that a new call is still in-flight, and `_request_details: <id>.error` to detect a failure.
9
+ If the request was called via the [`Request`](/Request) action with `holdValue: true`, `_request` returns the previous response while the new request is loading instead of returning `null`. Use `_request_details: <id>.0.loading` to detect that a new call is still in-flight, and `_request_details: <id>.0.error` to detect a failure (`0` is the latest call).
10
10
 
11
11
  #### Arguments
12
12
 
@@ -27,3 +27,9 @@ The id of the request.
27
27
  _request_details: my_request
28
28
  ```
29
29
  Returns: The details of the specified request.
30
+
31
+ ###### Whether the latest call is still loading:
32
+ ```yaml
33
+ _request_details: my_request.0.loading
34
+ ```
35
+ Returns: `true` while the latest call of the request awaits its response. The details are a list of the request's calls, latest first, so `0` is the latest call. Use it for a block's `loading`, for example a table's `loading` property.
@@ -29,6 +29,7 @@ The regex operator has shorthand argument definitions that can be used on web cl
29
29
  - `null`
30
30
  - `undefined`
31
31
  - `none` (`null` or `undefined`)
32
+ - `empty` (`null`, `undefined`, `''`, or `[]` - note that `0`, `false` and `{}` are not empty)
32
33
  - `primitive` (`undefined`, `null`, `string`, `number`, `boolean`, or `date`)
33
34
  - `on: any`: The value to test. One of `on` or `key` must be specified unless the operator is used in an input block.
34
35
  - `key: string`: The key of a value in `state` to test. One of `on` or `key` must be specified unless the operator is used in an input block.
@@ -60,13 +61,23 @@ Returns: `true` if a number.
60
61
  id: input
61
62
  type: TextInput
62
63
  validate:
63
- - message: This field id required.
64
+ - message: This field is required.
64
65
  status: error
65
66
  pass:
66
67
  _not:
67
- _type: none
68
+ _type: empty
68
69
  ```
69
- Returns: `true` if the input is none.
70
+ Returns: `true` if the input has a value. This is the test the `required` block field applies.
71
+
72
+ ###### Check if a value is empty:
73
+ ```yaml
74
+ _type:
75
+ type: empty
76
+ on:
77
+ _state: selected_tags
78
+ ```
79
+ Returns: `true` if `selected_tags` is `null`, `undefined`, `''` or `[]`, and `false` for any
80
+ other value, including `0`, `false` and `{}`.
70
81
 
71
82
  ###### Test if an id in the `urlQuery` is undefined or null:
72
83
  ```yaml
@@ -18,6 +18,8 @@ If the page is reloaded, the `urlQuery` is not lost. By using `urlQuery`, you ca
18
18
 
19
19
  `urlQuery` objects are serialized to JSON, allowing nested objects or arrays to be specified.
20
20
 
21
+ To put a value like a record id in the URL path instead, as in `/tickets/1234`, give the page a [`path`](/page-paths) with placeholders and read them with [`_path_params`](/_path_params). Path parameters never merge into `urlQuery`.
22
+
21
23
  Because the query string is user controlled, a key named `__proto__`, `constructor`, `prototype`, `__defineGetter__`, `__defineSetter__`, `__lookupGetter__` or `__lookupSetter__` is skipped while the rest of the query is parsed as usual — a URL of `?__proto__=1&my_key=2` gives a `urlQuery` of `{ my_key: 2 }`. A value that cannot be deserialized is kept as the raw string.
22
24
 
23
25
  #### Arguments
@@ -10,7 +10,7 @@
10
10
  }): any
11
11
  ```
12
12
 
13
- The `_user` operator gets a value from the [`user`](/user-object) object. The `user` object contains the data in the user idToken if OpenID Connect authentication is configured and a user is logged in.
13
+ The `_user` operator gets a value from the [`user`](/user-object) object — the caller Lowdefy resolves for the signed-in user in their active organization. It has a [fixed shape](/user-object); see that page for the available fields.
14
14
 
15
15
  #### Arguments
16
16
 
@@ -50,7 +50,7 @@ Returns: The entire `user` object.
50
50
  ###### Dot notation:
51
51
  Assuming user:
52
52
  ```yaml
53
- sub: abc123
53
+ id: abc123
54
54
  name: User Name
55
55
  my_object:
56
56
  subfield: 'Value'
@@ -76,7 +76,7 @@ Returns: The value of `might_not_exist`, or `"Default value"`.
76
76
  ###### Block list indices:
77
77
  Assuming `user`:
78
78
  ```yaml
79
- sub: abc123
79
+ id: abc123
80
80
  name: User Name
81
81
  my_array:
82
82
  - value: 0
@@ -18,6 +18,7 @@ The Lowdefy engine provides a context object to the action with the following pa
18
18
  - `getInput: function`: Get data from the Lowdefy input object.
19
19
  - `getLocale: function`: Return the active i18n locale code (or undefined when `config.i18n` is not configured).
20
20
  - `getPageId: function`: Get the pageId of the block that the action is defined on.
21
+ - `getPathParams: function`: Get data from the page's path parameters, the values of the placeholders in its [`path`](/page-paths).
21
22
  - `getRequestDetails: function`: Get data from Lowdefy requests.
22
23
  - `getState: function`: Get data from the Lowdefy state object.
23
24
  - `getUrlQuery: function`: Get data from the Lowdefy urlQuery object.
@@ -33,6 +34,11 @@ The Lowdefy engine provides a context object to the action with the following pa
33
34
  - `translate: function`: Look up a translation key (`(key, values?) => string`) — same lookup chain as the [`_t`](/_t) operator. See [i18n](/i18n) for the plugin-author contract.
34
35
  - `validate: function`: Call the Validate action.
35
36
  - `params: any`: The `params` defined by the user in the Lowdefy configuration. Operators are evaluated before the params are passed to the action. No validation is performed on this object.
37
+ - `trace: object`: Observe completed block and app events, for example to send them to an analytics tool.
38
+ - `subscribe: function`: `subscribe(listener, { state, replay }) => unsubscribe`. The listener is called once for every block or app event that ran its actions, after the event finished, with `{ scope, pageId, blockId, blockType, eventName, success, failure, debounceMs, actions, record, context }`. `scope` is `page` or `app`. `failure` is `null` for a successful event, else `{ actionId, actionType, configKey, errorName, invalidBlocks }`: ids only, never an error message or a value. An event with no actions, a bounced debounced event and an event an inner block already handled are not reported. Pass `{ state: true }` to also receive `stateBefore`, a copy of the page state before the actions ran. Pass `{ replay: true }` to also receive the failed events (`success: false`) that happened before anyone asked for replay, such as a failing app `onInit`: they are passed to the listener in order before `subscribe` returns. Lowdefy holds at most 20 of them, without `stateBefore`, and only the first subscriber that passes `replay` receives them. A listener that throws is logged once and never stops the event or the other listeners.
39
+ - `describeElement: function`: `describeElement(element)` returns the journey target a DOM element describes as: `{ page_id, block_id, block_type, row, column, text, nth, option, block_ids }`.
40
+ - `describeChain: function`: `describeChain(elementsChain)` returns the same target from a PostHog `$elements_chain` string, with `nth` always `null`.
41
+ - `pageIdOf: function`: `pageIdOf(url)` returns the page id a URL shows, or the configured home page at the app root.
36
42
 
37
43
  #### Examples
38
44
 
@@ -78,3 +84,7 @@ async function Confetti({ params }) {
78
84
 
79
85
  export default Confetti;
80
86
  ```
87
+ # next_page_title: Blocks
88
+ # next_page_id: plugins-blocks
89
+ next_page_title: Connections # while blocks is in progress
90
+ next_page_id: plugins-connections
@@ -67,6 +67,25 @@ FetchOrderWithUser.meta = {
67
67
  export default FetchOrderWithUser;
68
68
  ```
69
69
 
70
+ #### Journey data sets
71
+
72
+ A connection type declares how it behaves when a journey runs on a [data set](/journey-data-sets) with `meta.dataSet` on its connection export. The dev server reads it before any request on the connection runs:
73
+
74
+ - `'redirect'`: the dev server merges the run's `databaseUri` and `databaseName` over the connection properties. Declare it only when the type takes its database from those two properties and nothing else, honours `databaseName`, and keys any client it caches between requests by the URI it is given, never by connection id alone.
75
+ - `'walled'`: the type holds no database URI and reaches MongoDB only through the walled client: its requests call the resolver's `walled(connectionId)` argument and pass the result to `getWalledCollection` from `@lowdefy/connection-mongodb/walled`. The connection passes unchanged, and the walled connections it names take the run's database. A type that also calls an outside service declares `'external'`.
76
+ - `'external'`: the type reaches an outside service (an HTTP API, email, an AI provider) and holds none of the app's data. It keeps its real target.
77
+ - No declaration: requests on the connection are refused under a data set. Leave a data store the dev server cannot redirect undeclared.
78
+
79
+ A data set journey clicks a block only when every connection its events reach declares `'redirect'` or `'walled'`.
80
+
81
+ ```js
82
+ export default {
83
+ schema,
84
+ meta: { dataSet: 'external' },
85
+ requests: { AxiosHttp },
86
+ };
87
+ ```
88
+
70
89
  #### Schema Validation
71
90
 
72
91
  A [JSON Schema](https://json-schema.org/) schema can be used to validate the connection and request properties before they are passed to the request function. The [ajv-errors](https://ajv.js.org/packages/ajv-errors.html) package is used to provide useful error messages if the schema validation fails. Attached the json-schema to the request function with property `schema`, to validate request input before the request function is called.
@@ -96,3 +115,9 @@ AxiosHttp.meta = {
96
115
 
97
116
  export default AxiosHttp;
98
117
  ```
118
+ # previous_page_title: Blocks
119
+ # previous_page_id: plugins-blocks
120
+ previous_page_title: Actions # while blocks doesn't exist
121
+ previous_page_id: plugins-actions
122
+ next_page_title: Operators
123
+ next_page_id: plugins-operators
@@ -31,6 +31,7 @@ Lowdefy uses the [`exports`](https://nodejs.org/api/packages.html#exports) packa
31
31
  "./auth/providers": "./src/auth/providers.js",
32
32
  "./blocks": "./src/blocks.js",
33
33
  "./connections": "./src/connections.js",
34
+ "./iconSets": "./src/iconSets.js",
34
35
  "./metas": "./src/metas.js",
35
36
  "./operators/client": "./src/operators/client.js",
36
37
  "./operators/server": "./src/operators/server.js",
@@ -67,6 +68,7 @@ export default {
67
68
  },
68
69
  blocks: ['Block'],
69
70
  connections: ['Connection'],
71
+ iconSets: ['my-icons'],
70
72
  requests: ['Request'],
71
73
  operators: {
72
74
  build: ['_build_operator', '_shared_operator'],
@@ -76,6 +78,8 @@ export default {
76
78
  };
77
79
  ```
78
80
 
81
+ `iconSets` declares icon sets, which the `./iconSets` entry point exports as data. See [Icon Sets](/plugins-icon-sets).
82
+
79
83
  The type names do not need to be hard coded, and can be generated by importing the plugin types.
80
84
 
81
85
  ###### Example `types.js` for connections
@@ -111,6 +115,20 @@ export default extractBlockTypes(metas);
111
115
 
112
116
  The `extractBlockTypes` function returns `{ blocks, icons, blockMetas }` which the build pipeline uses to resolve plugin types without loading React components or heavy dependencies.
113
117
 
118
+ A block that runs actions itself, through events it registers with `methods.registerEvent`, lists those action types in `meta.actions` and the operators their params use in `meta.operators`. Each page loads only the plugin code it uses, so the build adds these types to every page that uses the block:
119
+
120
+ ```js
121
+ // src/blocks/MyUpload/meta.js
122
+ export default {
123
+ category: 'input',
124
+ icons: [],
125
+ // Registers { id: 'policy', type: 'Request', params: { _event: 'requestId' } }
126
+ actions: ['Request'],
127
+ operators: ['_event'],
128
+ // ...events, properties
129
+ };
130
+ ```
131
+
114
132
  See the [default Lowdefy block packages](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins/blocks) for full examples.
115
133
 
116
134
  ### Named export files
@@ -133,6 +151,54 @@ Most types are written as standard Javascript functions, and blocks are written
133
151
 
134
152
  Lowdefy uses object [destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) to provide parameters to the type functions. These parameters include the parameters or properties defined by the user in the Lowdefy configuration. Any operators used in the configuration will be evaluated before it is passed to the type function. Other relevant metadata and helper functions are also passed to the plugin function.
135
153
 
154
+ ### Lazy loading heavy blocks
155
+
156
+ A page loads the code of every block type it uses before it renders. A block that pulls in a large library, such as a chat, a chart engine or a rich text editor, can make that code much bigger, even when the block sits in a closed drawer, an unopened tab or a modal. `createLazyBlock` from `@lowdefy/block-utils` loads such a block's implementation only when the block first mounts.
157
+
158
+ Make a block lazy when it adds more than about 100 kB gzip to the page, **and** it is commonly off-screen at first paint or the page shows useful content without it. Otherwise keep it eager: a lazy block that is visible at first paint appears a moment later.
159
+
160
+ Move the block's component into a file named `*.lazy.js`, and export a wrapper in its place:
161
+
162
+ ```js
163
+ // src/blocks/MyChart/MyChart.js - exported from blocks.js as before
164
+ import { createLazyBlock } from '@lowdefy/block-utils';
165
+ import meta from './meta.js';
166
+ import MyChartFallback from './MyChartFallback.js';
167
+
168
+ export default createLazyBlock({
169
+ load: () => import('./MyChart.lazy.js'),
170
+ meta,
171
+ Fallback: MyChartFallback, // optional
172
+ });
173
+ ```
174
+
175
+ - `load` returns `import()` of the implementation, whose default export is the block component. Do not import the `*.lazy.js` file statically anywhere else, or it is bundled with the page again.
176
+ - `meta` is the block's `meta.js` object. The wrapper copies it to `.meta`.
177
+ - `Fallback` is optional. It renders while the implementation loads and receives the same props as the block. Use it to keep the block's size, or to show the part users see first, such as a launcher button. Without it the block renders nothing until it has loaded.
178
+
179
+ The wrapper also has a `preload()` function, which starts the load and returns its promise. A `Fallback` can call it on hover.
180
+
181
+ The `.lazy.js` name matters. In production, the Lowdefy server prefetches the `*.lazy.js` chunks of the blocks on a page, so the code is often in the browser cache by the time the block mounts. Other dynamic imports are never prefetched.
182
+
183
+ ###### Block methods
184
+
185
+ Declare every method the block registers with `methods.registerMethod` in `meta.methods`:
186
+
187
+ ```js
188
+ // src/blocks/MyChart/meta.js
189
+ export default {
190
+ category: 'display',
191
+ methods: {
192
+ reset: 'Reset the zoom.',
193
+ download: 'Download the chart as an image.',
194
+ },
195
+ };
196
+ ```
197
+
198
+ The wrapper registers these methods as soon as the block mounts, so `CallMethod` works before the implementation has loaded. Calls made before then wait in order and run once the implementation has registered its methods. After that, calls go straight to the block, as for any other block. A waiting call fails if the block never registers that method, if the load fails, or if the block is removed first. A method that is not declared in `meta.methods` cannot be called before the block loads, and the dev server logs a warning when the block registers it.
199
+
200
+ Do not spread the `methods` prop (`{ ...methods }`) in a lazy block's implementation; pass it on as it is.
201
+
136
202
  ### Localizing plugin strings
137
203
 
138
204
  Plugins can ship locale-keyed default messages so consumers see translated strings out-of-the-box, and translate strings at runtime via `methods.translate(key, values)` in block / action code. See [i18n](/i18n) for the full plugin-author contract — `./messages` export shape, `package.json` `exports` registration, namespacing convention, and merge precedence.