@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
@@ -0,0 +1,293 @@
1
+ # HTML attributes
2
+
3
+ Every block that renders HTML understands a small set of `data-*` attributes: `Html`, `ClickableHtml`, `DangerousHtml`, HTML properties such as Tooltip titles, Card titles and Alert messages, ag-grid cell HTML, and the `EventLog` block. They give HTML the icons, tooltips, links, status tags, dates, numbers, avatars, copy buttons, truncation, text tones and confirmations that apps otherwise build by hand with inline styles and templates, and they look and behave the same in every app.
4
+
5
+ The attributes work on HTML from anywhere: page config, `_nunjucks` templates, request results and messages that API endpoints build on the server.
6
+
7
+ | Attribute | On | Effect |
8
+ |---|---|---|
9
+ | `data-icon="edit"` | any element | Renders the icon inside the element. |
10
+ | `data-tooltip="Text"` | any element | Shows a tooltip on hover and keyboard focus. |
11
+ | `data-popover="id"` | any element | Click, Enter or Space toggles a popover showing the element with `data-popover-content="id"`. |
12
+ | `data-event="onName"` | any element | `ClickableHtml` only: fires the block event `onName`, when the block's `dataEvents` lists it. |
13
+ | `data-page-id="page"` | `<a>` | A link to a page of the app, opened without reloading the app. |
14
+ | `data-url-query="key=value"` | `<a data-page-id>` | The link's query string. |
15
+ | `data-link` | `<a href="/path">` | Opens an app path without reloading the app. |
16
+ | `data-new-tab` | `<a href>` | Opens the link in a new tab. |
17
+ | `data-tag="success"` | any element | A tinted status tag. |
18
+ | `data-status="success"` | any element | A status dot before the text. |
19
+ | `data-time="relative"` | `<time datetime>` | A date as relative, date, datetime, time or a dayjs format. |
20
+ | `data-format="currency"` | any element | The element's number as number, currency, percent, compact or bytes. |
21
+ | `data-avatar="Jane Doe"` | any element, `<img>` | Initials in a theme colour; a fallback for a broken image. |
22
+ | `data-copy` | any element | A copy button for the element's text or the attribute's value. |
23
+ | `data-truncate="2"` | block element | Clamps text to 1–6 lines, with the full text in a tooltip when it is cut off. |
24
+ | `data-tone="secondary"` | any element | Text in a theme tone: secondary, tertiary, quaternary, success, warning, error or info. |
25
+ | `data-confirm="Delete?"` | `data-event` element | `ClickableHtml` only: asks before the event fires. |
26
+
27
+ Attribute values are plain text, names, numbers or colours. They are never read as HTML, templates or code, and HTML is sanitised before the attributes are applied.
28
+
29
+ Sanitising keeps every `data-*` attribute, so markup that reaches the HTML from user or request data can use these attributes too. Escape that data when you build the HTML: `_nunjucks` escapes `{{ values }}` unless they are marked `safe`, while `_string.concat` and `_js` do not escape.
30
+
31
+ ## Icons
32
+
33
+ `data-icon` renders an icon inside the element. Use a built-in semantic name such as `edit`, `delete`, `warning` or `external-link`, a name from `theme.icons.aliases`, or a [Lucide](https://lucide.dev/icons) name such as `Receipt`. The icon takes the element's font size and text colour. See [Theming](/theming) for the icon names and aliases.
34
+
35
+ ```html
36
+ <i data-icon="success" style="color: var(--ant-color-success)"></i> Saved
37
+ ```
38
+
39
+ An icon on its own is decorative to screen readers unless the element has a `data-tooltip` or an `aria-label`. An unknown name written in config fails the build. An unknown name that only appears at runtime renders nothing and logs a console warning.
40
+
41
+ ## Tooltips and popovers
42
+
43
+ `data-tooltip` shows a themed tooltip on hover and keyboard focus. A `title` on the same element is removed so only one tooltip shows.
44
+
45
+ `data-popover="id"` toggles a popover on click, Enter or Space. Its content is the element with `data-popover-content="id"` in the same HTML; give that element the `hidden` attribute. Icons, tooltips, links and `data-event` all work inside popover content.
46
+
47
+ ```yaml
48
+ - id: row_actions
49
+ type: ClickableHtml
50
+ properties:
51
+ dataEvents:
52
+ - onEdit
53
+ - onArchive
54
+ html: >
55
+ <i data-icon="edit" data-event="onEdit" data-id="42" data-tooltip="Edit"></i>
56
+ <span data-popover="more">More <i data-icon="chevron-down"></i></span>
57
+ <div data-popover-content="more" hidden>
58
+ <p data-event="onArchive" data-id="42"><i data-icon="folder"></i> Archive</p>
59
+ </div>
60
+ events:
61
+ onEdit:
62
+ - id: edit
63
+ type: SetState
64
+ params:
65
+ editing: { _event: id }
66
+ onArchive:
67
+ - id: archive
68
+ type: SetState
69
+ params:
70
+ archiving: { _event: id }
71
+ ```
72
+
73
+ Popovers close on a click outside, on Escape, on a second click on the trigger, and after a `data-event` inside them fires. When the block's HTML changes while a popover is open, for example when a request refreshes the data it is built from, the popover stays open, showing the new content, as long as the new HTML still has the trigger: an element with the same tag and the same `data-*` attributes. Otherwise it closes.
74
+
75
+ ## Events
76
+
77
+ In `ClickableHtml`, an element with `data-event="onName"` fires the block event `onName` when clicked, and its default browser action is prevented. The event object holds the element's other `data-*` attributes with snake_case keys, so `data-event="onEdit" data-record-id="42"` gives `{ record_id: "42" }`. Targets that are not links or buttons become keyboard focusable, and Enter or Space clicks them. `Html` fires no events.
78
+
79
+ The block's `dataEvents` property lists the events its HTML may fire. A `data-event` whose name is not listed does nothing, and a click on it logs a console warning; with no `dataEvents` the HTML fires no events. List an event by name, or as `{ name, confirm }` to make every click on it ask first (see [Confirm before an event](#confirm-before-an-event)):
80
+
81
+ ```yaml
82
+ - id: rows
83
+ type: ClickableHtml
84
+ properties:
85
+ dataEvents:
86
+ - onEdit
87
+ - name: onDelete
88
+ confirm: Delete this row?
89
+ html:
90
+ _nunjucks:
91
+ template: |
92
+ {% for row in rows %}
93
+ <p>{{ row.name }}
94
+ <i data-icon="edit" data-event="onEdit" data-id="{{ row._id }}"></i>
95
+ <i data-icon="delete" data-event="onDelete" data-id="{{ row._id }}"></i>
96
+ </p>
97
+ {% endfor %}
98
+ on:
99
+ rows:
100
+ _request: get_rows
101
+ ```
102
+
103
+ An event's `data-*` attributes come from the HTML, so treat them as user input: the event's actions should check that the user may act on the record they name, as they would for any other input. HTML built from user or request data must escape that data (see above), so the data cannot add `data-event` elements of its own.
104
+
105
+ A `ClickableHtml` block in [dynamic page content](/dynamic-page-content) comes from an API endpoint at page load, often from config stored in a database, so it needs `dataEvents` there too: `lowdefy upgrade` cannot reach config that is not in the app's files.
106
+
107
+ ## Links
108
+
109
+ Use `data-page-id` for links to pages of your app, instead of writing the href:
110
+
111
+ ```html
112
+ <a data-page-id="contact-details" data-url-query="_id={{ _id }}">{{ name }}</a>
113
+ ```
114
+
115
+ Lowdefy sets the `href` (including the app's `basePath`), and a plain click opens the page without reloading the app, the same as a [`Link`](/Link) action with `pageId` and `urlQuery`. Middle-click, Ctrl or Cmd-click, "copy link" and hover preview work as for any link. `data-url-query` is a query string (`a=1&b=2`); its values reach the page's `_url_query` the same way the `Link` action's `urlQuery` does.
116
+
117
+ For a page with a [`path`](/page-paths), give the values of its placeholders in `data-path-params`, a JSON object, the same as the `Link` action's `pathParams`:
118
+
119
+ ```html
120
+ <a data-page-id="ticket" data-path-params='{"space":"support","ticket_id":"{{ _id }}"}'>{{ title }}</a>
121
+ ```
122
+
123
+ Lowdefy builds the page's URL from its path, so this link opens `/tickets/support/1234` for a page with `path: tickets/{space}/{ticket_id}`. The page reads the values with [`_path_params`](/_path_params). Use single quotes around the attribute so the JSON can use double quotes. When `data-path-params` is not a JSON object, the link is not set and a warning is logged to the browser console. When `data-path-params` is a JSON object as written in your config, the build checks that it gives every placeholder of the page a value. An attribute that only becomes JSON when the HTML renders is checked when the link is set, and a missing value fails with an error naming the page and the placeholder.
124
+
125
+ The build checks every `data-page-id` it can read in your config, including HTML built by API endpoints, and warns when a page does not exist, with a suggestion for a likely typo. Values built from templates, such as `data-page-id="{{ page }}"`, are not checked. Inside a module, build the page id with `_module.pageId` (for example in a `_string.concat`); the build checks the resolved id.
126
+
127
+ Use `data-page-id` to write a link. When you already have a whole URL, for example a notification's stored `link` field, `data-link` opens it without reloading the app. The path is relative to the app, like the `Link` action's `url`, so Lowdefy adds the `basePath`. The build does not check `data-link` paths.
128
+
129
+ ```html
130
+ <a href="/tickets-view?_id=42" data-link>Ticket 42</a>
131
+ ```
132
+
133
+ Only hrefs that start with a single `/` and have no `#` are handled; everything else stays a normal link. Plain `<a href="/…">` links without `data-link` keep reloading the page, because paths like `/api/…` or files in `public/` are not app pages.
134
+
135
+ `data-new-tab` opens any link in a new tab. HTML is sanitised, which removes `target` attributes, so write `data-new-tab` instead of `target="_blank"`:
136
+
137
+ ```html
138
+ <a data-page-id="report" data-new-tab>Open report</a>
139
+ <a href="https://example.com/help" data-new-tab>Help</a>
140
+ ```
141
+
142
+ `data-link="false"` and `data-new-tab="false"` turn the attribute off, so a template can write `data-new-tab="{{ new_tab }}"`.
143
+
144
+ In `ClickableHtml`, a link that also has `data-event` fires the event and does not navigate. In an ag-grid cell, the grid's `onRowClick` still fires when a link in the row is clicked, as it does for `link` cells.
145
+
146
+ ## Status tags and dots
147
+
148
+ `data-tag` renders the element as a tinted tag, and `data-status` puts a coloured dot before its text. Both look the same as the ag-grid block's `tag` cells and follow the app theme and dark mode.
149
+
150
+ ```html
151
+ <span data-tag="success">Approved</span>
152
+ <span data-tag="orange">On hold</span>
153
+ <span data-status="processing">Syncing</span>
154
+ <span data-tag>{{ category }}</span>
155
+ ```
156
+
157
+ The value is one of:
158
+
159
+ - **A tone:** `success`, `processing`, `info`, `warning`, `error`, `default`, or an Ant Design preset colour: `red`, `volcano`, `orange`, `gold`, `yellow`, `lime`, `green`, `cyan`, `blue`, `geekblue`, `purple`, `magenta`. Tones use theme colours.
160
+ - **A CSS colour:** `#1677ff`, `rgb(22 119 255)`, or a theme variable such as `var(--ant-color-primary)`.
161
+ - **Anything else, or nothing:** the colour is picked from the value, or from the element's text when the attribute has no value, so the same text always gets the same colour. `data-tag="{{ category_id }}"` keeps a colour stable when the category is renamed.
162
+
163
+ The text is the label, so colour is never the only signal. Override the look with your own styles: the built-in styles have no specificity, so any class, Tailwind utility or inline style wins.
164
+
165
+ ## Dates and times
166
+
167
+ `data-time` formats the date in the element's `datetime` attribute, or in its text when it has none, in the app's locale and the browser's time zone:
168
+
169
+ ```html
170
+ <time datetime="{{ updated }}" data-time="relative"></time>
171
+ <time datetime="{{ created }}" data-time="date"></time>
172
+ <time datetime="{{ created }}" data-time="D MMM YYYY"></time>
173
+ ```
174
+
175
+ | Value | Renders |
176
+ |---|---|
177
+ | `relative` | `3 hours ago`, kept current while the page is open. Hovering shows the exact date and time. |
178
+ | `date` | `Sep 25, 2026` |
179
+ | `datetime`, or no value | `Sep 25, 2026, 3:30 PM` |
180
+ | `time` | `3:30 PM` |
181
+ | anything else | a [dayjs format](https://day.js.org/docs/en/display/format), such as `D MMM YYYY` |
182
+
183
+ The date can be an ISO string, anything dayjs parses, or epoch milliseconds (12 or more digits). A value that is not a date leaves the text as it is and logs a console warning, so put a readable fallback inside the element. Dates from the server are best sent as ISO strings, so they show in the reader's time zone instead of the server's.
184
+
185
+ ## Numbers
186
+
187
+ `data-format` formats the element's number, with the same formatting as the ag-grid block's `number` cells:
188
+
189
+ ```html
190
+ <span data-format="currency" data-currency="ZAR">{{ total }}</span>
191
+ <span data-format="percent" data-decimals="1">{{ ratio }}</span>
192
+ <span data-format="compact">{{ views }}</span>
193
+ <span data-format="bytes">{{ size }}</span>
194
+ ```
195
+
196
+ | Value | Example |
197
+ |---|---|
198
+ | `number`, or no value | `1234.5` → `1,234.5` |
199
+ | `currency` | `1234.5` with `data-currency="EUR"` → `€1,234.50` in English. `data-currency` (a three-letter currency code) is required. |
200
+ | `percent` | `0.123` → `12.3%` (the value is a fraction) |
201
+ | `compact` | `1500` → `1.5K` |
202
+ | `bytes` | `1536` → `1.5 kB` (base 1000) |
203
+
204
+ `data-decimals="2"` fixes the number of decimals. The text must be a plain decimal number such as `-1234.5`; anything else, like `1,234` or `N/A`, is left as it is. Formatted numbers use tabular figures, so columns line up.
205
+
206
+ ## Avatars
207
+
208
+ `data-avatar` renders a person's initials in a theme colour picked from their name, the same initials and colour as the ag-grid block's `avatar` cells. No image service is called.
209
+
210
+ ```html
211
+ <span data-avatar="{{ name }}"></span> {{ name }}
212
+ <img data-avatar="{{ name }}" src="{{ picture }}">
213
+ <span data-avatar="{{ name }}" data-avatar-shape="square"></span>
214
+ ```
215
+
216
+ On an `<img>`, the initials replace the image when it has no `src` or fails to load. The avatar is 24px by default; set `style="--lf-avatar-size: 40px; --lf-avatar-font-size: 16px"` to resize it. Next to the visible name the avatar is hidden from screen readers; on its own it is announced by the name.
217
+
218
+ ## Copy to clipboard
219
+
220
+ `data-copy` adds a copy button to the element. It copies the attribute's value, or the element's text when the attribute has no value:
221
+
222
+ ```html
223
+ <code data-copy>{{ api_key }}</code>
224
+ <span data-copy="{{ ticket_id }}">Ticket #{{ ticket_id }}</span>
225
+ ```
226
+
227
+ After a copy the icon shows a check, its tooltip says "Copied" and screen readers hear "Copied". When the copied value differs from the text, the button's label shows it in full ("Copy: 42"), with invisible characters such as zero-width spaces and direction marks spelled out as `[U+200B]`, so the HTML cannot show one text and copy another unnoticed. A copy click only copies: it does not trigger a surrounding `data-event`, link or grid row click. Copying needs a secure (HTTPS or localhost) page. The button labels use the `client.copy`, `client.copyValue`, `client.copied` and `client.copyFailed` [translation keys](/i18n).
228
+
229
+ ## Truncation
230
+
231
+ `data-truncate` clamps text to a number of lines and ends it with an ellipsis. The full text shows in a tooltip, but only when the text is actually cut off:
232
+
233
+ ```html
234
+ <div data-truncate>{{ title }}</div>
235
+ <div data-truncate="3">{{ description }}</div>
236
+ ```
237
+
238
+ No value or `1` is one line; `2` to `6` clamp to that many lines. Truncation makes the element a block, so put it on block content such as a `div` or `p`, not on a word in a sentence. On a table cell or list item it breaks the table or list layout, so truncate a `<div>` inside the cell instead. A `data-copy` button on a truncated element is placed after it, so it is never cut off. Screen readers still read the full text. A `title` or `data-tooltip` on the element replaces the automatic tooltip.
239
+
240
+ ## Text tone
241
+
242
+ `data-tone` colours text with a theme tone, so it follows the theme and dark mode:
243
+
244
+ ```html
245
+ <span data-tone="secondary">Added {{ created }}</span>
246
+ <span data-tone="error">Failing</span>
247
+ ```
248
+
249
+ | Tone | Colour |
250
+ |---|---|
251
+ | `secondary` | Secondary text |
252
+ | `tertiary` | Tertiary text, for supplementary details such as timestamps |
253
+ | `quaternary` | Quaternary text, for placeholders such as an empty-value dash |
254
+ | `success`, `warning`, `error`, `info` | Ant Design's status text colours |
255
+
256
+ On the default light theme `tertiary`, `quaternary` and the status tones fall below WCAG AA contrast for body text. Use them for supplementary text and short labels whose words carry the meaning ("Failing"), never as the only way information is shown. On an element that also has `data-tag`, `data-tone` sets the text colour. In page config you can also use the Tailwind theme classes (`text-text-secondary`); in HTML built by templates, requests or API endpoints use `data-tone`, because Tailwind never sees those strings.
257
+
258
+ ## Confirm before an event
259
+
260
+ In `ClickableHtml`, `data-confirm` on a `data-event` element asks before the event fires:
261
+
262
+ ```yaml
263
+ - id: rows
264
+ type: ClickableHtml
265
+ properties:
266
+ dataEvents:
267
+ - onDelete
268
+ html: >
269
+ <i data-icon="delete" data-event="onDelete" data-id="42"
270
+ data-tooltip="Delete" data-confirm="Delete this row?"></i>
271
+ events:
272
+ onDelete:
273
+ - id: delete
274
+ type: CallAPI
275
+ params:
276
+ endpointId: delete-row
277
+ payload:
278
+ id: { _event: id }
279
+ ```
280
+
281
+ A click, Enter or Space opens a confirmation with the message, OK and Cancel. Only OK fires the event, once. Cancel, Escape and a click outside close it without firing. Focus moves to Cancel when it opens, so a stray key press never confirms; Tab to OK and press Enter to confirm. Focus returns to the element afterwards; after OK inside a popover, it returns to the popover's trigger. Clicking the element again while its confirmation is open keeps it open.
282
+
283
+ With no value the message is "Are you sure?" (the `client.confirm` [translation key](/i18n)); OK and Cancel follow the app's locale. The event object includes `confirm` along with the element's other `data-*` attributes. A confirm inside a popover keeps the popover open until OK fires the event. `data-confirm` has no effect in `Html`, or on an element without `data-event`.
284
+
285
+ `data-confirm` only asks where the markup says so. For an event that deletes or changes data, list it in `dataEvents` with `confirm`, so every click on it asks whatever the markup says: `confirm: true` asks with the element's `data-confirm` message or "Are you sure?", and a string is the message, in place of the element's.
286
+
287
+ `confirm` asks whenever it is set to anything but `false`, so an empty message or one an operator could not find (`null`) still asks, with the element's or the default message.
288
+
289
+ When the block's HTML changes while a confirmation is open, the confirmation closes without firing. An event's `data-*` values can name a record by its position (`data-index="{{ loop.index0 }}"`), and new HTML can put another record there, so OK could otherwise act on a record the user did not choose. Click the element again to confirm against the new HTML.
290
+
291
+ ## Plugin blocks
292
+
293
+ A block plugin that renders HTML gets these attributes by rendering through `renderHtml` or `HtmlComponent` from `@lowdefy/block-utils`. A block that runs its own sanitiser and sets `innerHTML` directly does not.
@@ -106,7 +106,7 @@ User preference persists to `localStorage`. Clear it (and fall back to browser/d
106
106
 
107
107
  **Resolution at startup:**
108
108
 
109
- 1. User preference in `localStorage` (`lowdefy_locale`)
109
+ 1. User preference in `localStorage` (kept per app)
110
110
  2. Browser `navigator.languages` best-fit against `config.i18n.locales`
111
111
  3. `config.i18n.defaultLocale`
112
112
 
@@ -162,12 +162,17 @@ config:
162
162
  | `client.requestError` | `Request error` | Fallback when an API response has no message |
163
163
  | `client.backAriaLabel` | `back` | Aria label on browser-back links |
164
164
  | `client.shortcutThen` | `then` | Sequence shortcut badge separator |
165
+ | `client.copy` | `Copy` | Label of a `data-copy` button in HTML |
166
+ | `client.copyValue` | `Copy: {value}` | Label of a `data-copy` button whose value differs from its text |
167
+ | `client.copied` | `Copied` | Announced after a `data-copy` copy |
168
+ | `client.copyFailed` | `Copy failed` | Announced when a `data-copy` copy fails |
169
+ | `client.confirm` | `Are you sure?` | Message of a `data-confirm` with no value |
165
170
  | `errorPage.name` | `Error` | Full-page error fallback heading |
166
171
  | `errorPage.message` | `An error has occurred.` | Full-page error fallback body |
167
172
  | `errorPage.homeLink` | `Return to home page` | Full-page error fallback link |
168
173
  | `server.genericError` | `Something went wrong.` | Message of any server error that is not an author error or an auth refusal |
169
174
 
170
- `server.genericError` is the message users see for any server error that is not an author error (`:throw`, `:reject`, a failed `ValidateSchema` step, a plugin's `UserError`) or an authentication refusal. The server translates it for the request's locale, the same way in development and production, and it is the message that `_actions`, `_request_details` and [`_error`](/_error) read in page config. To show something else for one action, set `messages.error` on the action to override its error toast. To show the real message, read it with [`_error`](/_error) inside the endpoint's `:catch` and send it on, for example `:throw: { _error: message }`.
175
+ `server.genericError` is the message users see for any server error that is not an author error (`:throw`, `:reject`, a failed `ValidateSchema` step, a plugin's `UserError`) or an authentication or authorization refusal. The server translates it for the request's locale, the same way in development and production, and it is the message that `_actions`, `_request_details` and [`_error`](/_error) read in page config. To show something else for one action, set `messages.error` on the action to override its error toast. To show the real message, read it with [`_error`](/_error) inside the endpoint's `:catch` and send it on, for example `:throw: { _error: message }`.
171
176
 
172
177
  ## Localizing block defaults
173
178
 
@@ -218,7 +223,7 @@ config:
218
223
  agent.antdx.actions.feedbackDislike: 'Gefällt mir nicht'
219
224
  ```
220
225
 
221
- **Agent runtime errors.** HTTP 400/500 errors from the agent endpoint (`Only POST requests are supported.`, `Invalid agent path`, `Agent "X" does not exist.`, etc.) translate via `agent.runtime.*` keys against the request's `Accept-Language`. Server-side validation errors and stack traces stay in English (developer diagnostics).
226
+ **Agent runtime errors.** HTTP error responses from the agent endpoint (a 405 for a wrong method, a 400 for a malformed request, and so on: `Only POST requests are supported.`, `Invalid agent path`, `Agent "X" does not exist.`, etc.) translate via `agent.runtime.*` keys against the request's `Accept-Language`. Server-side validation errors and stack traces stay in English (developer diagnostics).
222
227
 
223
228
  **Agent config translation.** `agent.properties.instructions` passes through the operator parser at request time, so `_t:` works:
224
229
 
@@ -139,7 +139,7 @@ When a shortcut matches, the browser's default action for that key combination i
139
139
  type: Button
140
140
  properties:
141
141
  title: Search
142
- icon: AiOutlineSearch
142
+ icon: search
143
143
  events:
144
144
  onClick:
145
145
  shortcut: mod+K
@@ -157,7 +157,7 @@ When a shortcut matches, the browser's default action for that key combination i
157
157
  type: Button
158
158
  properties:
159
159
  title: Save
160
- icon: AiOutlineSave
160
+ icon: save
161
161
  events:
162
162
  onClick:
163
163
  shortcut: mod+S
@@ -103,7 +103,7 @@ Blocks can also be laid out using [CSS flexbox](https://developer.mozilla.org/en
103
103
  The `layout` object on blocks can be used to control how a block is placed in the layout. The `layout` properties that can be defined are:
104
104
 
105
105
  - `selfAlign`: _Enum_ - Align block vertically in the area. Options are `top`, `middle`, and `bottom`. Default `top.`
106
- - `align`: _Enum_ - Align content area children vertically. Options are `top`, `middle`, and `bottom`. Default `top.` This value flows to the content area as a default.
106
+ - `align`: _Enum_ - Align content area children vertically. Options are `top`, `middle`, and `bottom`. Default `top.` This value flows to the content area as a default. In Lowdefy v4 `layout.align` aligned the block itself within its parent — that is now `layout.selfAlign`. Setting `layout.align` on a block aligns the block's own content, never the block itself.
107
107
  - `flex`: _String_ - Set the [`flex`](https://developer.mozilla.org/en-US/docs/Web/CSS/flex) CSS property. This overwrites the `grow`, `shrink`, and `size` properties.
108
108
  - `gap`: _Number_ | _Array_ - Set the gap (space) between blocks in the content area. If an array, the first element is the horizontal gap, and the second is the vertical gap. This value flows to the content area as a default.
109
109
  - `grow`: _Number_ - Set the [`flex-grow`](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow) CSS property. Default 0.
@@ -1,5 +1,104 @@
1
1
  # Logger
2
2
 
3
+ Lowdefy provides built-in error logging and monitoring capabilities. When properly configured, errors from both client and server are captured and sent to external logging services.
4
+
5
+ ## Sentry Integration
6
+
7
+ [Sentry](https://sentry.io) is a popular error tracking and performance monitoring platform. Lowdefy has built-in Sentry integration that captures errors with rich context including page IDs, block IDs, and config file locations.
8
+
9
+ ### Quick Start
10
+
11
+ To enable Sentry, set the `SENTRY_DSN` environment variable:
12
+
13
+ ```
14
+ SENTRY_DSN=https://your-dsn@sentry.io/project
15
+ ```
16
+
17
+ With this environment variable set, Sentry will capture errors from both client and server with sensible defaults.
18
+
19
+ ### Client-Side Configuration
20
+
21
+ For client-side error capture, you also need to expose the DSN to the browser:
22
+
23
+ ```
24
+ ```
25
+
26
+ ### Configuration Options
27
+
28
+ You can customize Sentry behavior using the `logger` configuration in your `lowdefy.yaml`:
29
+
30
+ ```yaml
31
+ lowdefy: 6.1.0
32
+
33
+ logger:
34
+ sentry:
35
+ # Enable/disable client-side logging (default: true)
36
+ client: true
37
+ # Enable/disable server-side logging (default: true)
38
+ server: true
39
+ # Trace server requests (default: true on the Node server, false on Vercel)
40
+ serverTracing: true
41
+ # Sample rate for performance traces (default: 0.1)
42
+ tracesSampleRate: 0.1
43
+ # Sample rate for session replay (default: 0)
44
+ replaysSessionSampleRate: 0
45
+ # Sample rate for replay on errors (default: 0.1)
46
+ replaysOnErrorSampleRate: 0.1
47
+ # Enable user feedback widget (default: false)
48
+ feedback: false
49
+ # Override environment detection (default: auto from NODE_ENV)
50
+ environment: production
51
+ # User fields to include in error reports (default: ['id', '_id'])
52
+ userFields:
53
+ - id
54
+ - _id
55
+ ```
56
+
57
+ ### Default Configuration
58
+
59
+ If you only set `SENTRY_DSN` without any `logger.sentry` configuration, these defaults are used:
60
+
61
+ | Option | Default | Description |
62
+ |--------|---------|-------------|
63
+ | `client` | `true` | Client-side error capture enabled |
64
+ | `server` | `true` | Server-side error capture enabled |
65
+ | `serverTracing` | `true` on the Node server, `false` on Vercel | Server requests traced as transactions |
66
+ | `tracesSampleRate` | `0.1` | 10% of transactions traced |
67
+ | `replaysSessionSampleRate` | `0` | Session replay disabled by default |
68
+ | `replaysOnErrorSampleRate` | `0.1` | 10% of error sessions replayed |
69
+ | `feedback` | `false` | User feedback widget disabled |
70
+ | `userFields` | `['id', '_id']` | Only user ID fields logged |
71
+
72
+ ### Server Tracing on Vercel
73
+
74
+ On Vercel, the server reports errors only by default. Tracing sets up OpenTelemetry when a function instance starts, which adds to every cold start, and the function stays billed after each response while a sampled transaction uploads. Without tracing, a request that captures no error ends as soon as its response is sent, and one that captures an error waits only for that error to reach Sentry.
75
+
76
+ To trace server requests on Vercel anyway, set `serverTracing: true`:
77
+
78
+ ```yaml
79
+ logger:
80
+ sentry:
81
+ serverTracing: true
82
+ tracesSampleRate: 0.1
83
+ ```
84
+
85
+ `tracesSampleRate` still sets the browser's trace sampling either way. Set `serverTracing: false` to report errors only from the Node server too.
86
+
87
+ ### User Context
88
+
89
+ For authenticated users, Sentry automatically captures user context based on the `userFields` configuration. By default, only `id` and `_id` fields from the user session are included to avoid logging PII (personally identifiable information).
90
+
91
+ To include additional fields:
92
+
93
+ ```yaml
94
+ logger:
95
+ sentry:
96
+ userFields:
97
+ - id
98
+ - _id
99
+ - organization_id
100
+ ```
101
+
3
102
  ### Source Maps
4
103
 
5
104
  To enable readable stack traces in Sentry, set the `SENTRY_AUTH_TOKEN` environment variable during build: