@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
@@ -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.
@@ -0,0 +1,267 @@
1
+ # Icon Sets
2
+
3
+ Lowdefy draws icons with [Lucide](https://lucide.dev). An icon-set plugin adds icons as data: a whole set such as Tabler, a few icons of your own, or replacements for Lucide icons. Blocks, Ant Design components and HTML `data-icon` all draw set icons the same way as Lucide icons, with the app's `size`, `strokeWidth` and colour.
4
+
5
+ An icon set holds no React code. Each icon is a plain object that describes its SVG, and the build writes only the icons an app uses into the app bundle.
6
+
7
+ ## Declare a set
8
+
9
+ A set has an id in lowercase kebab-case, such as `tabler`. The id is a namespace, so a plugin's `typePrefix` does not change it. Declare it in `types.js` under `iconSets`:
10
+
11
+ ```js
12
+ // src/types.js
13
+ export default {
14
+ iconSets: ['tabler'],
15
+ };
16
+ ```
17
+
18
+ Export the set from a `./iconSets` entry point:
19
+
20
+ ```json
21
+ {
22
+ "name": "@my-app/icons-tabler",
23
+ "version": "1.0.0",
24
+ "type": "module",
25
+ "exports": {
26
+ "./iconSets": "./src/iconSets.js",
27
+ "./types": "./src/types.js"
28
+ },
29
+ "files": ["src/*"]
30
+ }
31
+ ```
32
+
33
+ The `./iconSets` module runs only in Node, during the build and in the dev server. It exports an object with one entry per set id:
34
+
35
+ ```js
36
+ // src/iconSets.js
37
+ export default {
38
+ tabler: {
39
+ attrs: undefined,
40
+ semantic: { edit: 'Pencil', delete: 'Trash' },
41
+ listIcons: async () => ['Pencil', 'Trash' /* ... */],
42
+ loadIcons: async ({ names }) => ({
43
+ Pencil: {
44
+ node: [
45
+ /* ... */
46
+ ],
47
+ },
48
+ }),
49
+ },
50
+ };
51
+ ```
52
+
53
+ | Key | Required | Description |
54
+ | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
55
+ | `listIcons` | Yes | An async function that returns every icon name in the set. Search (`lowdefy_search_icons`) and the build's "did you mean" suggestions use it. |
56
+ | `loadIcons` | Yes | An async function that takes `{ names }` and returns `{ [name]: IconData }` for the names it has. Leave out names it does not have. |
57
+ | `attrs` | No | Root SVG attributes added to every icon of this set, such as `{ fill: 'currentColor', stroke: 'none' }` for a fill-based set. |
58
+ | `semantic` | No | A map from semantic names to icon names in this set. It applies when this set is the app's default set (`theme.icons.set`). |
59
+
60
+ The build calls `loadIcons` only with names the app uses, so a large set costs nothing until an app draws one of its icons.
61
+
62
+ Install the plugin like any other plugin. A set in the same pnpm workspace uses `workspace:*`:
63
+
64
+ ```yaml
65
+ plugins:
66
+ - name: '@my-app/icons-tabler'
67
+ version: 'workspace:*'
68
+ ```
69
+
70
+ Restart the dev server after you add an icon-set plugin.
71
+
72
+ ## Icon names
73
+
74
+ Icon names in a set are PascalCase: `Pencil`, `ArrowLeftRight`. Convert kebab-case file names when you build the set. An app writes a set icon in one of two ways:
75
+
76
+ - `tabler:Pencil` — a qualified name. It resolves only in the `tabler` set.
77
+ - `Pencil` — a set name. It resolves in the app's default set (`theme.icons.set`, which is `lucide` unless the app changes it), then in Lucide.
78
+
79
+ ## IconData
80
+
81
+ `loadIcons` returns each icon as `IconData`:
82
+
83
+ ```js
84
+ {
85
+ node: [
86
+ ['path', { d: 'M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4' }],
87
+ ['path', { d: 'M13.5 6.5l4 4' }],
88
+ ],
89
+ size: 24,
90
+ }
91
+ ```
92
+
93
+ | Key | Description |
94
+ | ----------------- | -------------------------------------------------------------------------------------------------- |
95
+ | `node` | Required. An array of `[tag, attrs, children?]`. `children` is another node array, so groups nest. |
96
+ | `size` | The viewBox size of a square icon: `size: 24` gives `viewBox="0 0 24 24"`. Defaults to 24. |
97
+ | `width`, `height` | Use these instead of `size` for an icon that is not square. |
98
+ | `attrs` | Root SVG attributes for this icon. |
99
+
100
+ Rules for the data:
101
+
102
+ - Attribute names are React names: `strokeWidth`, `fillRule`, `clipRule`, `className`, not `stroke-width` or `class`.
103
+ - The viewBox always starts at `0 0`. For a source with an offset viewBox such as `-2 -2 24 24`, wrap the nodes in `['g', { transform: 'translate(2 2)' }, nodes]`.
104
+ - Root `attrs` never set `strokeWidth`. Stroke width is an app setting (`theme.icons.strokeWidth`), so every set follows it. A set drawn at 1.5, such as Heroicons, should tell apps to set `theme.icons.strokeWidth: 1.5`. A `strokeWidth` on a single node inside `node` is fine.
105
+ - Leave out `key` attributes.
106
+
107
+ Every icon starts from Lucide's root attributes: `fill="none"`, `stroke="currentColor"`, round line caps and joins, and the app's stroke width. Stroke sets on a 24px grid, such as Tabler outline and `@lucide/lab`, need no `attrs`. A fill-based set sets `attrs: { fill: 'currentColor', stroke: 'none' }`. Draw with `currentColor`, so the icon's `color` works.
108
+
109
+ ## Layers: the last plugin wins
110
+
111
+ Several plugins can declare the same set id. Each one adds a layer to the set, in `plugins` order. For `lucide`, Lowdefy's built-in Lucide data is the bottom layer.
112
+
113
+ - **Per icon name, the topmost layer that has it wins.** A layer can be partial. A name it lacks falls through to the layers below it.
114
+ - **`semantic` maps layer the same way.** From lowest to highest precedence: the built-in semantic names, then the `semantic` maps of the default set's layers in plugin order, then the app's `theme.icons.aliases`.
115
+ - **Qualified names stay in their set.** `tabler:Pencil` resolves through the `tabler` layers only. If no layer has it, it is unresolved, and the build fails at an icon property. It does not fall back to Lucide.
116
+
117
+ ### Add one icon to Lucide
118
+
119
+ A plugin that declares `lucide` and has one icon makes that name work like any Lucide name, without a set prefix:
120
+
121
+ ```js
122
+ // types.js
123
+ export default { iconSets: ['lucide'] };
124
+ ```
125
+
126
+ ```js
127
+ // iconSets.js
128
+ const Invoice = {
129
+ node: [
130
+ ['path', { d: 'M4 2v20l2-1 2 1 2-1 2 1 2-1 2 1 2-1 2 1V2l-2 1-2-1-2 1-2-1-2 1-2-1-2 1Z' }],
131
+ ['path', { d: 'M8 8h8' }],
132
+ ['path', { d: 'M8 12h8' }],
133
+ ['path', { d: 'M8 16h5' }],
134
+ ],
135
+ };
136
+
137
+ export default {
138
+ lucide: {
139
+ listIcons: async () => ['Invoice'],
140
+ loadIcons: async ({ names }) => (names.includes('Invoice') ? { Invoice } : {}),
141
+ },
142
+ };
143
+ ```
144
+
145
+ ```yaml
146
+ - id: invoice_button
147
+ type: Button
148
+ properties:
149
+ title: Invoices
150
+ icon: Invoice
151
+ ```
152
+
153
+ ### Replace an icon
154
+
155
+ A layer that defines a name Lucide already has replaces it everywhere. If the layer above defines `Pencil`, every `Pencil` in the app draws the new glyph, and so do the semantic `edit` and every block that uses `edit`.
156
+
157
+ ## Select a set
158
+
159
+ `theme.icons.set` makes a set the app's default set:
160
+
161
+ ```yaml
162
+ theme:
163
+ icons:
164
+ set: tabler
165
+ ```
166
+
167
+ - PascalCase names resolve in the Tabler layers first, then in Lucide. Every Lucide name keeps working.
168
+ - The Tabler layers' `semantic` maps override the built-in semantic names. So the set re-skins block icons and Ant Design icons (close buttons, alert status icons, select arrows) as far as its map covers them. Semantic names it leaves out keep their Lucide icons.
169
+ - The app's `theme.icons.aliases` still win over both.
170
+
171
+ `theme.icons.set` must name the built-in `lucide` set or an installed set, or the build fails.
172
+
173
+ ## Example: Tabler outline icons
174
+
175
+ [Tabler](https://tabler.io/icons) outline icons use the same 24px grid and stroke attributes as Lucide. The `@tabler/icons` package ships them as node arrays in `tabler-nodes-outline.json`, keyed by kebab-case name. Convert them once, when you build the plugin package, and read the JSON in `iconSets.js`.
176
+
177
+ ```js
178
+ // scripts/convertIcons.js - run with `node scripts/convertIcons.js`
179
+ import fs from 'fs';
180
+
181
+ const source = new URL('../node_modules/@tabler/icons/tabler-nodes-outline.json', import.meta.url);
182
+ const target = new URL('../src/tablerOutline.json', import.meta.url);
183
+
184
+ function toPascalCase(name) {
185
+ return name
186
+ .split('-')
187
+ .map((part) => part[0].toUpperCase() + part.slice(1))
188
+ .join('');
189
+ }
190
+
191
+ const nodes = JSON.parse(fs.readFileSync(source, 'utf8'));
192
+ const icons = {};
193
+ Object.entries(nodes).forEach(([name, node]) => {
194
+ icons[toPascalCase(name)] = { node };
195
+ });
196
+ fs.writeFileSync(target, JSON.stringify(icons));
197
+ ```
198
+
199
+ `pencil` becomes `Pencil`, and `arrow-left-right` becomes `ArrowLeftRight`. The file already leaves out Tabler's invisible bounding-box path, and its attributes are React names, so it needs no other changes.
200
+
201
+ ```js
202
+ // src/iconSets.js
203
+ import { readFile } from 'fs/promises';
204
+
205
+ let iconsPromise;
206
+
207
+ function readIcons() {
208
+ iconsPromise ??= readFile(new URL('./tablerOutline.json', import.meta.url), 'utf8').then(
209
+ JSON.parse
210
+ );
211
+ return iconsPromise;
212
+ }
213
+
214
+ async function listIcons() {
215
+ return Object.keys(await readIcons());
216
+ }
217
+
218
+ async function loadIcons({ names }) {
219
+ const icons = await readIcons();
220
+ const found = {};
221
+ names.forEach((name) => {
222
+ if (icons[name]) found[name] = icons[name];
223
+ });
224
+ return found;
225
+ }
226
+
227
+ export default {
228
+ tabler: {
229
+ semantic: {
230
+ add: 'Plus',
231
+ close: 'X',
232
+ delete: 'Trash',
233
+ edit: 'Pencil',
234
+ search: 'Search',
235
+ settings: 'Settings',
236
+ },
237
+ listIcons,
238
+ loadIcons,
239
+ },
240
+ };
241
+ ```
242
+
243
+ ```js
244
+ // src/types.js
245
+ export default { iconSets: ['tabler'] };
246
+ ```
247
+
248
+ An app can now use `tabler:Pencil` anywhere, or set `theme.icons.set: tabler` to draw Tabler icons by default.
249
+
250
+ ## The react-icons compatibility set
251
+
252
+ Lowdefy 6 and earlier used [react-icons](https://react-icons.github.io/react-icons/) names such as `AiOutlineUser`. `@lowdefy/icons-react-icons` is an icon set, `react-icons`, that holds every react-icons 5.6.0 icon under its old name. Use it when names come from data the build cannot rewrite, such as icon names stored in a database, or for brand icons that Lucide does not have.
253
+
254
+ ```yaml
255
+ plugins:
256
+ - name: '@lowdefy/icons-react-icons'
257
+ version: '^7'
258
+ theme:
259
+ icons:
260
+ set: react-icons
261
+ ```
262
+
263
+ - Old names such as `AiOutlineUser` resolve in the compatibility set. Lucide names and semantic names still work.
264
+ - The set has no `semantic` map, so block icons and Ant Design icons are Lucide either way.
265
+ - Without `set: react-icons`, reach an old name with its qualified name: `react-icons:FaWhatsapp`.
266
+
267
+ The compatibility set is a migration aid. [V6 to V7](/v6-to-v7) shows how to move an app to Lucide names.
@@ -2,7 +2,7 @@
2
2
 
3
3
  Lowdefy plugins provides an interface to extend the platform functionality with custom javascript code. Plugins are installed into the Lowdefy app during the Lowdefy build process, and as a result are included as part of the Vite client build output. This enables plugin developers to use any npm packages when building Lowdefy plugins.
4
4
 
5
- Lowdefy plugins can be used to create custom blocks, connections, requests, action, operators and auth providers, adapters, callbacks and events. These plugins are written as standard [npm modules](https://docs.npmjs.com/about-packages-and-modules#about-modules), so community plugins can be published to npm, and the workspace and git protocols can be used for project specific or private plugins. Since plugins are npm packages most Javascript features and third-party npm packages can be used in plugins.
5
+ Lowdefy plugins can be used to create custom blocks, connections, requests, action, operators and auth providers, adapters, callbacks and events. [Icon-set plugins](/plugins-icon-sets) add icons as data. These plugins are written as standard [npm modules](https://docs.npmjs.com/about-packages-and-modules#about-modules), so community plugins can be published to npm, and the workspace and git protocols can be used for project specific or private plugins. Since plugins are npm packages most Javascript features and third-party npm packages can be used in plugins.
6
6
 
7
7
  ## Using a plugin
8
8
 
@@ -27,3 +27,29 @@ plugins:
27
27
  version: 1.0.0
28
28
  typePrefix: Other
29
29
  ```
30
+
31
+ ## Plugin meta
32
+
33
+ Every plugin type can describe itself to the build and to AI coding agents through a `meta` object. For blocks it is the `meta.js` next to the block (`category`, `valueType`, `initValue`, `cssKeys`, `events`, `properties`, ...), for requests it is the `meta` property on the request function (`checkRead`, `checkWrite`), and for operators a package may export a `./metas` module with one object per operator, mirroring `./schemas`.
34
+
35
+ All three accept `meta.hazards`: a list of behaviours of the type that its schema cannot express, which the dev server's docs and MCP endpoint return to agents alongside the schema (see [AI agent docs](/ai-agent-docs)). Each hazard is:
36
+
37
+ ```yaml
38
+ hazards:
39
+ - id: html-style-stripped # kebab-case, unique within the type
40
+ message: Content is sanitised with DOMPurify, so <style>, <script> and inline event handlers are removed. Use DangerousHtml for a trusted <style> block.
41
+ see: display-blocks/html # a docs slug, or null
42
+ ```
43
+
44
+ The `message` is one or two plain sentences saying what happens and what to do instead. Only add a hazard for a behaviour that is verified in the plugin's code — an agent will rely on it.
45
+
46
+ A block marks each property that holds a URL with `urlKind` in its `properties` schema: `url` for a link the engine opens (a colon-less value is read as `https://`), `href` for a link the browser opens, `src` for a resource the block loads, and `srcSet` for a list of sources. A [dynamic blocks policy](/dynamic-page-content#dynamic-blocks-policies) checks marked properties against its pages and origins whatever they are called. Every other property is judged by its name (`url`, `href`, `src`, `image`, ...), so a property whose name looks like a URL key but holds something else, such as a field name, is marked `urlKind: false`.
47
+
48
+ ```js
49
+ properties: {
50
+ type: 'object',
51
+ properties: {
52
+ indexUrl: { type: 'string', urlKind: 'src', description: 'URL of the search index.' },
53
+ },
54
+ },
55
+ ```
@@ -0,0 +1,19 @@
1
+ # Plugins
2
+
3
+ Everything in Lowdefy is a plugin — every block, operator, action, and connection
4
+ is an npm package, and your app can install more. A browsable catalog of official
5
+ and community plugins is coming; until then, the
6
+ [community plugins repository](https://github.com/lowdefy/community-plugins) lists
7
+ what the community has published.
8
+
9
+ ## Build a plugin
10
+
11
+ How the plugin system works and what a plugin package contains.
12
+
13
+ Set up a workspace and develop plugins against a local app.
14
+
15
+ Write a custom action.
16
+
17
+ Write a custom connection and requests.
18
+
19
+ Write a custom operator.