@lowdefy/docs-content 6.1.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 +43 -7
  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 +154 -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 +8 -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 +136 -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 +2 -0
  71. package/content/connections/smtp.md +3 -1
  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 +24 -3
  110. package/content/controls/return.md +17 -1
  111. package/content/controls/throw.md +1 -0
  112. package/content/controls/try.md +4 -2
  113. package/content/controls/while.md +46 -0
  114. package/content/deployment/deployment-environments.md +10 -7
  115. package/content/deployment/docker.md +22 -7
  116. package/content/deployment/node-server.md +4 -0
  117. package/content/deployment/vercel.md +17 -6
  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 +24 -1
  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 +3458 -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
@@ -7,6 +7,8 @@
7
7
 
8
8
  The `_date` operator returns a date object representing a single moment in time. It can take a string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, or a number that is the number of milliseconds since 1 January 1970 UTC (the [UNIX epoch](https://en.wikipedia.org/wiki/Unix_time)).
9
9
 
10
+ `_date` creates and reads dates but cannot format them with a pattern. To format a date for display, or to add, subtract or compare dates, use [`_dayjs`](/_dayjs).
11
+
10
12
  > This operator can be used as a [`_build`](/_build) operator method.
11
13
 
12
14
  #### Arguments
@@ -25,10 +25,11 @@ Dot notation is supported for reading fields of the error, such as `_error: stat
25
25
  Inside a `:catch`, `_error` is an Error rebuilt from the caught error with only these fields:
26
26
 
27
27
  - `name`: The error class name, such as `RequestError`.
28
- - `message`: The real error message, with the values of known secrets (`_secret` values, `CRON_SECRET` and `AUTH_SECRET`) replaced by `[REDACTED]`.
28
+ - `message`: The real error message, with the values of known secrets (`_secret` values, `CRON_SECRET`, `BETTER_AUTH_SECRET` and values marked with [`_credential`](/_credential)) replaced by `[REDACTED]`.
29
29
  - `code`: The error's `code`, if it has one.
30
30
  - `statusCode`: The error's HTTP status, if it has one.
31
31
  - `handled`: `true` once the server has logged the error.
32
+ - `retryAfter`: On a `ServiceError`, the wait the service asked for before a retry (seconds or an HTTP date), if it sent one.
32
33
  - `cause`: The error that caused this one, with the same fields, down the chain.
33
34
 
34
35
  A caught `UserError` (from a [`:throw`](/:throw) or a plugin) also keeps its `:cause` and `metaData`. The error carries no `received`, `source`, `config`, `configKey`, `location` or `stack`.
@@ -60,6 +61,28 @@ error:
60
61
 
61
62
  `code` and `statusCode` follow one rule across connection libraries. `code` is the error's own `code`, such as `ERR_BAD_REQUEST` from AxiosHttp or `11000` from MongoDB. `statusCode` is the first number among the error's `statusCode`, `status` and `response.status`. A request error takes both from the error the connection threw, so `_error: statusCode` reads the HTTP status of a failed `AxiosHttp` request without reading the cause.
62
63
 
64
+ ##### Service errors and rate limits
65
+
66
+ A request that fails because of the service it calls, not its config, is a `ServiceError`: a network failure, a timeout, a 5xx response, or a rate limit (HTTP 429, including a provider's throttling error). Every other request failure is a `RequestError`. A routine can tell a rate limit from a fault and try again later:
67
+
68
+ ```yaml
69
+ - :try:
70
+ - id: summarize
71
+ type: GenerateText
72
+ connectionId: claude
73
+ properties:
74
+ model: claude-haiku-4-5
75
+ prompt:
76
+ _payload: text
77
+ :catch:
78
+ - :if:
79
+ _eq: [{ _error: statusCode }, 429]
80
+ :then:
81
+ - :return:
82
+ status: busy
83
+ - :throw: Summary failed
84
+ ```
85
+
63
86
  #### Arguments
64
87
 
65
88
  ###### string
@@ -37,12 +37,12 @@ _get:
37
37
  key:
38
38
  _state: status
39
39
  from:
40
- new: AiTwoTonePlusCircle
41
- escalated: AiOutlineExclamationCircle
42
- investigation_started: AiTwoToneTool
43
- client_contacted: AiTwoToneSound
44
- awaiting_confirmation: AiOutlineLike
45
- closed: AiOutlineStop
40
+ new: add-circle
41
+ escalated: CircleAlert
42
+ investigation_started: Wrench
43
+ client_contacted: Volume2
44
+ awaiting_confirmation: ThumbsUp
45
+ closed: Ban
46
46
  ```
47
47
  Returns: The icon corresponding to the status in state.
48
48
 
@@ -0,0 +1,78 @@
1
+ # _hmac
2
+
3
+ The `_hmac` operator computes an [HMAC](https://en.wikipedia.org/wiki/HMAC) of a string under a key, returned as lower-case hex. Use it to sign what a routine sends (a webhook signature header, for example) or to derive a secret from a root secret. The key is usually a [`_secret`](/_secret), so `_hmac` runs only on the server and never reaches the browser.
4
+
5
+ The output of one call works as the `key` of the next, so one root secret can derive a secret per app, and that secret can sign a message.
6
+
7
+ To check a signature a sender sent, do not compare it to an `_hmac` output with `_eq`: a plain comparison stops at the first character that differs, so its timing tells a caller how much of a forged signature is right. Check it in a webhook endpoint's `verify` plugin with `crypto.timingSafeEqual` instead (see [Webhook Endpoints](/lowdefy-api)).
8
+
9
+ > This operator can be used as a [`_build`](/_build) operator method.
10
+
11
+ # Operator methods:
12
+
13
+ ## _hmac.sha256
14
+
15
+ ```
16
+ ({ key: string, data: string }): string
17
+ ```
18
+
19
+ The `_hmac.sha256` method computes the HMAC-SHA256 of `data` under `key`. Both are read as UTF-8 strings.
20
+
21
+ #### Arguments
22
+
23
+ ###### object
24
+ - `key: string`: __Required__ - The secret key.
25
+ - `data: string`: __Required__ - The string to sign.
26
+
27
+ #### Examples
28
+
29
+ ###### Sign a string:
30
+ ```yaml
31
+ _hmac.sha256:
32
+ key: my-secret
33
+ data: Hello World!
34
+ ```
35
+ Returns: `"ce334046c71c58d87a4c3201d1d14a3e7cdcba95041624dbcb84976a38d1c505"`.
36
+
37
+ ###### Derive a per-app secret and sign a webhook body with it:
38
+ ```yaml
39
+ _hmac.sha256:
40
+ key:
41
+ _hmac.sha256:
42
+ key:
43
+ _secret: SUPPORT_ROOT_SECRET
44
+ data:
45
+ _string.concat:
46
+ - 'app:'
47
+ - _payload: app_id
48
+ data:
49
+ _string.concat:
50
+ - _payload: timestamp
51
+ - .
52
+ - _payload: body
53
+ ```
54
+ Returns the hex signature of `<timestamp>.<body>` under the app's derived secret.
55
+
56
+ ## _hmac.sha512
57
+
58
+ ```
59
+ ({ key: string, data: string }): string
60
+ ```
61
+
62
+ The `_hmac.sha512` method computes the HMAC-SHA512 of `data` under `key`. Both are read as UTF-8 strings.
63
+
64
+ #### Arguments
65
+
66
+ ###### object
67
+ - `key: string`: __Required__ - The secret key.
68
+ - `data: string`: __Required__ - The string to sign.
69
+
70
+ #### Examples
71
+
72
+ ###### Sign a string:
73
+ ```yaml
74
+ _hmac.sha512:
75
+ key: my-secret
76
+ data: Hello World!
77
+ ```
78
+ Returns: `"498943335e4bb157626950ce4f305568a54816fe13ad5d594902f125cbd9a844f52ba9ad21105f4d8cd78907dbe5315c6be2c439688213054e04e065d3582b51"`.
@@ -16,7 +16,7 @@ Certain Lowdefy operators can be used inside of the JavaScript function block. T
16
16
  ###### Client JavaScript function prototype:
17
17
  _Function parameters passed to the operator method._
18
18
  ```js
19
- function ({ actions, args, event, input, location, lowdefyApp, lowdefyGlobal, request, state, urlQuery, user }) {
19
+ function ({ actions, args, event, input, location, lowdefyApp, lowdefyGlobal, pathParams, request, state, urlQuery, user }) {
20
20
  // Your JavaScript code here
21
21
  };
22
22
  ```
@@ -29,6 +29,7 @@ The function arguments available to the JavaScript function are:
29
29
  - `location: function`: Implements the [_location](/_location) operator.
30
30
  - `lowdefyApp: function`: Implements the [_app](/_app) operator.
31
31
  - `lowdefyGlobal: function`: Implements the [_global](/_global) operator.
32
+ - `pathParams: function`: Implements the [_path_params](/_path_params) operator.
32
33
  - `request: function`: Implements the [_request](/_request) operator.
33
34
  - `state: function`: Implements the [_state](/_state) operator.
34
35
  - `urlQuery: function`: Implements the [_url_query](/_url_query) operator.
@@ -14,7 +14,7 @@ The following location properties are available.
14
14
  - `homePageId: string`: The home page id.
15
15
  - `href: string`: The entire URL string.
16
16
  - `origin: string`: The canonical form of the origin of the specific location.
17
- - `pageId: string`: The current page id.
17
+ - `pageId: string`: The current page id. On a page with a [`path`](/page-paths) this is still the page's `id`; read its placeholder values with [`_path_params`](/_path_params).
18
18
  - `pathname: string`: A string containing an initial `/`` followed by the path of the URL, not including the query string or fragment.
19
19
  - `port: string`: The port number of the URL
20
20
  - `protocol: string`: The protocol scheme of the URL, mostly `http:` or `https:`.
@@ -25,6 +25,19 @@ The `_media` operator gets a value from the [`media`](/page-and-app-state) objec
25
25
  - `xl`: `1280px <= width < 1536px`
26
26
  - `2xl`: `1536px <= width`
27
27
 
28
+ `media` stays current while the page is open. When the browser window is resized, Lowdefy waits until the resize settles (150ms without a further resize event) and then re-evaluates the blocks that read a `media` value that changed. Only the values a block reads count: a block that reads `_media: size` is re-evaluated when the window crosses a breakpoint, not on every pixel of a resize, while a block that reads `_media: width` or the whole `media` object is re-evaluated whenever the width changes. Blocks that do not use `_media` are not re-evaluated at all. This makes `_media` suitable for responsive `visible` conditions and properties:
29
+
30
+ ```yaml
31
+ id: mobile_menu
32
+ type: Box
33
+ visible:
34
+ _eq:
35
+ - _media: size
36
+ - xs
37
+ ```
38
+
39
+ Prefer `_media: size` over `_media: width` where a breakpoint is enough, so that blocks only re-render when the layout actually changes. `darkMode` and `darkModePreference` update when dark mode is toggled. For purely visual responsive changes, CSS breakpoints in `style`, `class` and `layout` do not need `_media` at all.
40
+
28
41
  > **Note:** In v4, the largest breakpoint was `xxl` (1600px). It has been renamed to `2xl` (1536px) to align with Tailwind CSS breakpoints. See the [Migration Guide](/v4-to-v5) for details.
29
42
 
30
43
  #### Arguments
@@ -10,13 +10,15 @@ _module.endpointId: (endpointId: string): string
10
10
  _module.endpointId: (arguments: { id: string, module: string }): string
11
11
  _module.notificationId: (notificationId: string): string
12
12
  _module.notificationId: (arguments: { id: string, module: string }): string
13
+ _module.websocketId: (websocketId: string): string
14
+ _module.websocketId: (arguments: { id: string, module: string }): string
13
15
  _module.id: (true): string
14
16
  _module.id: (arguments: { module: string }): string
15
17
  ```
16
18
 
17
19
  The `_module` operator family provides access to module-scoped values during the build. `_module.var` and the string forms of the ID operators only make sense inside module config files — the build throws a clear error if you use them at the app level.
18
20
 
19
- The object form of `_module.pageId`, `_module.connectionId`, `_module.endpointId`, `_module.notificationId`, and `_module.id` also works at the app level, resolving by entry ID instead of a dependency name — useful for linking, calling, or labelling a specific module instance from app-level config without hardcoding the scoped ID. See each method below for an app-level example.
21
+ The object form of `_module.pageId`, `_module.connectionId`, `_module.endpointId`, `_module.notificationId`, `_module.websocketId`, and `_module.id` also works at the app level, resolving by entry ID instead of a dependency name — useful for linking, calling, or labelling a specific module instance from app-level config without hardcoding the scoped ID. See each method below for an app-level example.
20
22
 
21
23
  All `_module` operators resolve during the walker pass — the same phase as `_var` and `_ref`. Inside module files, they work at any depth.
22
24
 
@@ -36,7 +38,7 @@ Unlike `_var`, which requires threading variables through each `_ref`, `_module.
36
38
 
37
39
  Defaults are declared in `module.lowdefy.yaml` and resolve on read. Defaults are expressions — they can be literals, `_ref`s, `_module.var` references to other vars, or any `_build.*` tree. See [Writing Modules → Dynamic Defaults](/module-authoring#dynamic-defaults) for patterns.
38
40
 
39
- Vars with `properties` merge at the property level — only consumer-provided keys override the declared defaults, and missing properties resolve their own defaults independently.
41
+ Vars with `properties` merge at the property level — only consumer-provided keys override the declared defaults, and missing properties resolve their own defaults independently. A declared property with no consumer value and no default is left out of the object rather than set to `null`, so a block that receives the object applies its own default for that property. A property with no default that the consumer sets to `null` stays `null`.
40
42
 
41
43
  #### Arguments
42
44
 
@@ -284,6 +286,58 @@ params:
284
286
  ```
285
287
  At the app level, `module` is the module entry ID. The build resolves this to `user-admin/invite-user`.
286
288
 
289
+ ## _module.websocketId
290
+
291
+ ```
292
+ (websocketId: string): string
293
+ (arguments: { id: string, module: string }): string
294
+ ```
295
+
296
+ Resolves a websocket ID to its fully scoped ID, for a page's `subscriptions[].websocketId` and the `Subscribe`, `Unsubscribe` and `Publish` actions. The string form references the current module's websockets and only works inside module content.
297
+
298
+ The object form references a target by entry ID. Inside module content, `module` is the abstract dependency name declared in `module.lowdefy.yaml`. At the app level, `module` is the concrete module entry ID from `lowdefy.yaml`, for an app page that subscribes to a websocket a module ships.
299
+
300
+ #### Arguments
301
+
302
+ ###### string
303
+ The module-local websocket ID (as declared in the module's `websockets:` section).
304
+
305
+ ###### object
306
+ - `id: string`: The websocket ID in the target module.
307
+ - `module: string`: The abstract dependency name (in module content) or the module entry ID (in app-level config).
308
+
309
+ #### Examples
310
+
311
+ ###### Subscribe a module page to the module's own websocket:
312
+ ```yaml
313
+ subscriptions:
314
+ - websocketId:
315
+ _module.websocketId: thread-messages
316
+ payload:
317
+ ticket_id:
318
+ _state: ticket_id
319
+ ```
320
+ In a module entry with `id: support`, resolves to `support/thread-messages`.
321
+
322
+ ###### Read the channel state of a module websocket:
323
+ ```yaml
324
+ _websocket:
325
+ _string.concat:
326
+ - _module.websocketId: thread-messages
327
+ - .messages
328
+ ```
329
+
330
+ ###### Subscribe an app page to a module's websocket:
331
+ ```yaml
332
+ # lowdefy.yaml (app level)
333
+ subscriptions:
334
+ - websocketId:
335
+ _module.websocketId:
336
+ id: thread-messages
337
+ module: support
338
+ ```
339
+ At the app level, `module` is the module entry ID. The build resolves this to `support/thread-messages`.
340
+
287
341
  ## _module.id
288
342
 
289
343
  ```
@@ -1,7 +1,7 @@
1
1
  # _operator
2
2
 
3
3
  ```
4
- (arguments: {operator: string, params: any): any
4
+ (arguments: {name: string, params: any, operators?: string[]}): any
5
5
  ```
6
6
 
7
7
  The `_operator` operator evaluates an operator with the given params. This is useful if the operator needs to be chosen dynamically. The `_operator` cannot evaluate itself.
@@ -11,15 +11,16 @@ The `_operator` operator evaluates an operator with the given params. This is us
11
11
  #### Arguments
12
12
 
13
13
  ###### object
14
- - `operator: string`: The name of the operator to evaluate.
14
+ - `name: string`: The name of the operator to evaluate, such as `_sum` or `_number.round`. Names written in `name`, including the names an `_if` returns from `then` and `else` and a `_switch` returns from its branches, are loaded with the page.
15
15
  - `params: any`: The params to give to the operator.
16
+ - `operators: string[]`: The operators the call may evaluate. Required when `name` is read at runtime, from state, a request or a payload: the build fails without it, loads exactly these operators with the page (or the server), and `_operator` refuses any other name. A listed operator (`_number`) allows all its methods; a listed method (`_number.round`) allows only that method.
16
17
 
17
18
  #### Examples
18
19
 
19
20
  ###### Get a value from `urlQuery` if specified, else use the value in `state`:
20
21
  ```yaml
21
22
  _operator:
22
- operator:
23
+ name:
23
24
  _if:
24
25
  test:
25
26
  _eq:
@@ -31,3 +32,16 @@ _operator:
31
32
  key: field_to_get
32
33
  ```
33
34
  Returns: Value from `urlQuery` if `location_selector == url_query`, else the value from `state`.
35
+
36
+ ###### Apply an aggregation chosen by the user:
37
+ ```yaml
38
+ _operator:
39
+ name:
40
+ _state: aggregation # _sum or _product
41
+ operators:
42
+ - _sum
43
+ - _product
44
+ params:
45
+ _state: values
46
+ ```
47
+ Returns: The sum or product of `values`. Any other name in `aggregation` is refused.
@@ -0,0 +1,82 @@
1
+ # _path_params
2
+
3
+ ```
4
+ (key: string): string
5
+ (all: boolean): object
6
+ (arguments: {
7
+ all?: boolean,
8
+ key?: string,
9
+ default?: any,
10
+ }): any
11
+ ```
12
+
13
+ The `_path_params` operator gets a value from the page's path parameters: the values of the placeholders in the page's [`path`](/page-paths). On a page with `path: tickets/{space}/{ticket_id}`, opened at `/tickets/support/1234`, the path parameters are `{ space: 'support', ticket_id: '1234' }`.
14
+
15
+ Path parameters are set when linking to the page with `pathParams`, for example with the [`Link`](/Link) action, or by typing the URL. Unlike `input`, they are visible to the user and can be changed by the user.
16
+
17
+ > __DO NOT__ set any private or personal information in path parameters; all values in the URL are accessible publicly. Using a value that can be guessed, like an incremental `id`, can lead to security issues, since users can easily guess and access data for other `ids`.
18
+
19
+ Values are always strings, the text from the URL after decoding: `1234` is `"1234"`, and nothing is deserialized. Convert a value when you need another type, for example with [`_number.parseInt`](/_number). A page without placeholders has no path parameters, so `_path_params: true` returns `{}`.
20
+
21
+ Path parameters are kept apart from the [`urlQuery`](/_url_query): a page can have a `space` placeholder and a `space` query value, and `_path_params` only reads the placeholder. Within one [page instance](/page-paths#page-instances) the values never change, since different values open a different instance.
22
+
23
+ `_path_params` is only available in the browser. To use a value in a request, pass it in the request `payload`.
24
+
25
+ #### Arguments
26
+
27
+ ###### string
28
+ If the `_path_params` operator is called with a string argument, the value of that placeholder is returned. If the page has no such placeholder, `null` is returned.
29
+
30
+ ###### boolean
31
+ If the `_path_params` operator is called with boolean argument `true`, the object of all path parameters is returned.
32
+
33
+ ###### object
34
+ - `all: boolean`: If `all` is set to `true`, the object of all path parameters is returned. One of `all` or `key` are required.
35
+ - `key: string`: The name of the placeholder whose value is returned. If the page has no such placeholder, `null`, or the specified default value is returned. One of `all` or `key` are required.
36
+ - `default: any`: A value to return if the page has no placeholder named `key`. By default, `null` is returned.
37
+
38
+ #### Examples
39
+
40
+ ###### Get the value of the `ticket_id` placeholder:
41
+ On a page with `path: tickets/{space}/{ticket_id}`, opened at `/tickets/support/1234`:
42
+ ```yaml
43
+ _path_params: ticket_id
44
+ ```
45
+ ```yaml
46
+ _path_params:
47
+ key: ticket_id
48
+ ```
49
+ Returns: `"1234"`.
50
+
51
+ ###### Get all path parameters:
52
+ ```yaml
53
+ _path_params: true
54
+ ```
55
+ ```yaml
56
+ _path_params:
57
+ all: true
58
+ ```
59
+ Returns: `{ space: 'support', ticket_id: '1234' }`.
60
+
61
+ ###### Return a default value if the page has no such placeholder:
62
+ ```yaml
63
+ _path_params:
64
+ key: space
65
+ default: general
66
+ ```
67
+ Returns: The value of `space`, or `"general"` on a page whose path has no `{space}` placeholder.
68
+
69
+ ###### Pass a value to a request:
70
+ ```yaml
71
+ requests:
72
+ - id: get_ticket
73
+ type: MongoDBFindOne
74
+ connectionId: tickets
75
+ payload:
76
+ ticket_id:
77
+ _path_params: ticket_id
78
+ properties:
79
+ query:
80
+ _id:
81
+ _payload: ticket_id
82
+ ```
@@ -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