@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
package/README.md CHANGED
@@ -6,6 +6,7 @@ Lowdefy documentation extracted as markdown, for serving to AI coding agents via
6
6
 
7
7
  - `content/<section>/<slug>.md` — one markdown file per docs page (concepts, tutorial, operators, actions, connections, blocks, ...).
8
8
  - `index.json` — manifest of all docs: `{ version, docs: [{ slug, title, section, path, kind?, typeName? }] }`. `kind`/`typeName` map a plugin type (e.g. operator `_get`) to its doc.
9
+ - `hazards.json` — framework-level hazards served by the dev MCP alongside schemas, docs and config lookups: `[{ id, appliesTo: { kinds?, types?, when? }, message, see }]`. This file is hand-authored and committed, not generated — `pnpm docs:content` wipes `content/` but leaves it untouched. Add an entry only for a behaviour verified in the framework source.
9
10
 
10
11
  ## Regenerating content
11
12
 
@@ -14,7 +14,7 @@ The `DownloadCsv` action is used to generate and download a CSV file from a set
14
14
 
15
15
  ###### object
16
16
  - `filename: string`: __Required__ - The name for the generated CSV file.
17
- - `data: any[]`: __Required__ - The set of data used to generate the CSV file.
17
+ - `data: any[]`: __Required__ - The set of data used to generate the CSV file, as an array of objects. If it is empty or missing, the file contains only the header row from `fields`.
18
18
  - `fields: string[]`: __Required__ - The field definitions the set of data will be mapped to in the generated CSV file.
19
19
 
20
20
  #### Examples
@@ -0,0 +1,58 @@
1
+ # EmailOtpSend
2
+
3
+ ```
4
+ (params: {
5
+ email: string
6
+ captchaToken?: string
7
+ }): void
8
+ ```
9
+
10
+ The `EmailOtpSend` action emails a one-time sign-in code to an address. It requires `auth.emailOTP` to be enabled — see [Configuration](/auth-configuration).
11
+
12
+ A code is typed into the tab the person started from, so the sign-in survives corporate mail security that pre-fetches links (which consumes a single-use magic link before the person clicks it), and it works when the email is read on another device.
13
+
14
+ Use [`EmailOtpVerify`](/EmailOtpVerify) to complete the sign-in with the code.
15
+
16
+ When `auth.magicLink` is enabled alongside `auth.emailOTP`, the magic-link email already carries the code: the [`Login`](/Login) action with `magicLink: true` sends one email that serves both paths, and `EmailOtpSend` is then only needed for a code-only page that offers no link at all.
17
+
18
+ Under an invite-only signup policy an address that is not admitted gets no email, and the action still resolves successfully — the response is identical either way, so the "check your email" screen gives nothing away about who has an account.
19
+
20
+ #### Parameters
21
+
22
+ ###### object
23
+ - `email: string`: __required__ - The email address to send the sign-in code to.
24
+ - `captchaToken: string`: A captcha token minted by a `Captcha` block, sent as the `x-captcha-response` header when `auth.captcha` is enabled. Tokens are single-use, so reset the `Captcha` block in `onError` for retries.
25
+
26
+ #### Examples
27
+
28
+ ###### Send a sign-in code:
29
+ ```yaml
30
+ - id: send_code
31
+ type: EmailOtpSend
32
+ params:
33
+ email:
34
+ _state: email
35
+ ```
36
+
37
+ ###### Send a code and tell the user to check their inbox:
38
+ ```yaml
39
+ - id: send_code
40
+ type: Button
41
+ properties:
42
+ title: Send code
43
+ events:
44
+ onClick:
45
+ - id: validate
46
+ type: Validate
47
+ params:
48
+ regex: ^email$
49
+ - id: send
50
+ type: EmailOtpSend
51
+ params:
52
+ email:
53
+ _state: email
54
+ - id: sent
55
+ type: DisplayMessage
56
+ params:
57
+ content: Check your email for the sign-in code.
58
+ ```
@@ -0,0 +1,79 @@
1
+ # EmailOtpVerify
2
+
3
+ ```
4
+ (params: {
5
+ email: string
6
+ otp: string
7
+ callbackUrl?: {
8
+ home?: boolean
9
+ pageId?: string
10
+ url?: string
11
+ urlQuery?: object
12
+ pathParams?: object
13
+ } | false
14
+ }): void
15
+ ```
16
+
17
+ The `EmailOtpVerify` action signs a user in with the one-time code emailed to them by [`EmailOtpSend`](/EmailOtpSend), or carried on the magic-link email when `auth.magicLink` and `auth.emailOTP` are both enabled. It requires `auth.emailOTP` to be enabled — see [Configuration](/auth-configuration).
18
+
19
+ On success the session cookie is set — creating the account on first sign-in, unless `emailOTP.disableSignUp` is `true` — and the browser lands on the resolved `callbackUrl`. Three sources are consulted, in order:
20
+
21
+ 1. The `callbackUrl` param, if given.
22
+ 2. The `?callbackUrl=` query parameter, which Lowdefy sets when it redirects an unauthenticated user to the sign-in page.
23
+ 3. The app's home page.
24
+
25
+ To sign in without navigating, set `callbackUrl: false` — valid here, unlike on the magic-link and social paths, because this is a plain JSON sign-in with no redirect hop.
26
+
27
+ If the user has two-factor authentication enrolled, the code mints a challenge rather than a session: the action navigates to `authPages.twoFactor` carrying the resolved destination as `?callbackUrl=`, where [`TwoFactorVerify`](/two-factor) finishes the sign-in, and the event chain stops.
28
+
29
+ An expired, mistyped or already-used code is the auth server rejecting the attempt, not an app fault. The action throws a `UserError`: `catch` actions still run and the message still displays, but it is logged to the browser console only and is never reported to the server.
30
+
31
+ #### Parameters
32
+
33
+ ###### object
34
+ - `email: string`: __required__ - The email address the code was sent to.
35
+ - `otp: string`: __required__ - The one-time code from the email.
36
+ - `callbackUrl: object | false`: Set to `false` to sign in without navigating. As an object:
37
+ - `home: boolean`: Land on the app's home page.
38
+ - `pageId: string`: The pageId to land on.
39
+ - `url: string`: The URL to land on. An absolute URL is not `basePath`-prefixed, so it can be an external landing page.
40
+ - `urlQuery: object`: The urlQuery to set on the destination.
41
+ - `pathParams: object`: Values for the placeholders in the destination page's [`path`](/page-paths), by placeholder name.
42
+
43
+ #### Examples
44
+
45
+ ###### Sign in with the code and land on the home page (or the page the user was bounced from):
46
+ ```yaml
47
+ - id: verify_code
48
+ type: EmailOtpVerify
49
+ params:
50
+ email:
51
+ _state: email
52
+ otp:
53
+ _state: otp
54
+ ```
55
+
56
+ ###### Sign in and land on a specific page:
57
+ ```yaml
58
+ - id: verify_code
59
+ type: EmailOtpVerify
60
+ params:
61
+ email:
62
+ _state: email
63
+ otp:
64
+ _state: otp
65
+ callbackUrl:
66
+ pageId: dashboard
67
+ ```
68
+
69
+ ###### Sign in inside a modal, without navigating:
70
+ ```yaml
71
+ - id: verify_code
72
+ type: EmailOtpVerify
73
+ params:
74
+ email:
75
+ _state: email
76
+ otp:
77
+ _state: otp
78
+ callbackUrl: false
79
+ ```
@@ -0,0 +1,43 @@
1
+ # GetLocalStorage
2
+
3
+ ```
4
+ (params: {
5
+ key: string,
6
+ default?: any
7
+ }): any
8
+ ```
9
+
10
+ The `GetLocalStorage` action reads a value from the browser's [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). Values written by the [`SetLocalStorage`](/SetLocalStorage) action are deserialized, so objects, arrays and dates are returned as the same types that were stored.
11
+
12
+ Local storage is per browser, so a value stored in one browser is not available in another. Keys are kept per app: Lowdefy stores the value under a key that names the app's `slug` and base path, so apps served from the same origin do not read or overwrite each other's values. A value stored under the bare key before keys were kept per app is moved to the app's key the first time `GetLocalStorage` reads it.
13
+
14
+ Values are kept when a user signs out, so do not store secrets, tokens or personal data in local storage.
15
+
16
+ A value that was not written by `SetLocalStorage` and is not valid JSON is returned as the plain string that is stored. If the browser blocks local storage, the action returns the `default` value, as if the key were not set. Keys starting with `lowdefy_` or `lf-` are reserved for settings Lowdefy stores itself, such as the dark mode preference, and the action throws an error if one is used.
17
+
18
+ #### Parameters
19
+
20
+ ###### object
21
+ - `key: string`: __Required__ - The local storage key to read. Keys starting with `lowdefy_` or `lf-` are reserved.
22
+ - `default: any`: The value returned when the key is not set in local storage, or when the browser blocks local storage.
23
+
24
+ #### Response
25
+
26
+ The value stored at the key, or the `default` value when the key is not set or local storage is blocked. When the key is not set and no `default` is given, the response is `undefined`.
27
+
28
+ #### Examples
29
+
30
+ ###### Restore a user preference on page load:
31
+ ```yaml
32
+ - id: read_preference
33
+ type: GetLocalStorage
34
+ params:
35
+ key: dashboard_filters
36
+ default:
37
+ status: open
38
+ - id: apply_preference
39
+ type: SetState
40
+ params:
41
+ filters:
42
+ _actions: read_preference.response
43
+ ```
@@ -9,8 +9,11 @@
9
9
  input?: object,
10
10
  newTab?:boolean,
11
11
  pageId?: string,
12
+ pathParams?: object,
13
+ replace?: boolean,
14
+ scroll?: boolean,
12
15
  url?: string,
13
- urlQuery? object
16
+ urlQuery?: object
14
17
  }): void
15
18
  ```
16
19
 
@@ -18,6 +21,18 @@ The `Link` action is used to link a user to another page. An input can be passed
18
21
  `urlQuery`, which is visible to the user, but persists if the browser is refreshed, or by using the `input` object, which is not
19
22
  visible to the user.
20
23
 
24
+ To link to a page with a [`path`](/page-paths), give the values of its placeholders in `pathParams`. A page with
25
+ `path: tickets/{space}/{ticket_id}`, linked to with `pageId: ticket` and `pathParams: { space: support, ticket_id: '1234' }`,
26
+ opens at `/tickets/support/1234`. Every placeholder needs a value: a missing, `null` or empty value, or a value of `.`
27
+ or `..`, fails the link with an error naming the page and the placeholder. For a `Link` action with a
28
+ literal `pageId`, the build checks that `pathParams` names every placeholder.
29
+
30
+ Links set as block properties, such as the [`Anchor`](/Anchor) block's `pageId` and table or grid cell links, can
31
+ only be built for pages the user may open. On a public page, such a link to a protected page with a `path` fails
32
+ while the user is logged out. Use a `Link` action, or an HTML link with `data-page-id` (see
33
+ [HTML attributes](/html-attributes#links)), there instead: the build collects these links, so a logged-out
34
+ user is sent to sign in and then on to the page.
35
+
21
36
  #### Parameters
22
37
 
23
38
  ###### string
@@ -30,6 +45,9 @@ The pageId of a page in the app to link to.
30
45
  - `input: object`: Object to set as the input for the linked page.
31
46
  - `newTab: boolean`: Open the link in a new tab.
32
47
  - `pageId: string`: The pageId of a page in the app to link to.
48
+ - `pathParams: object`: Values for the placeholders in the linked page's [`path`](/page-paths), by placeholder name. Values are converted to strings.
49
+ - `replace: boolean`: Replace the current browser history entry instead of pushing a new one, so the browser back button skips this navigation. Defaults to `false`.
50
+ - `scroll: boolean`: Scroll to the top of the page after navigating. Set to `false` to keep the current scroll position, for example when a same-page link only updates the `urlQuery`. Defaults to `true`.
33
51
  - `url: string`: Link to an external url.
34
52
  - `urlQuery: object`: Object to set as the urlQuery for the linked page.
35
53
 
@@ -94,6 +112,21 @@ The pageId of a page in the app to link to.
94
112
  _state: id
95
113
  ```
96
114
 
115
+ ###### Link to a page with a path:
116
+ For a page with `path: tickets/{space}/{ticket_id}`:
117
+ ```yaml
118
+ - id: link_path_params
119
+ type: Link
120
+ params:
121
+ pageId: ticket
122
+ pathParams:
123
+ space: support
124
+ ticket_id:
125
+ _state: ticket_id
126
+ urlQuery:
127
+ tab: comments
128
+ ```
129
+
97
130
  ###### Set the input of the page that is linked to:
98
131
  ```yaml
99
132
  - id: link_input
@@ -105,6 +138,19 @@ The pageId of a page in the app to link to.
105
138
  _args: row.id
106
139
  ```
107
140
 
141
+ ###### Reflect state into the urlQuery without moving the page:
142
+ ```yaml
143
+ - id: sync_url
144
+ type: Link
145
+ params:
146
+ pageId: my_page_id
147
+ urlQuery:
148
+ selected:
149
+ _state: selected_id
150
+ replace: true
151
+ scroll: false
152
+ ```
153
+
108
154
  ###### Go to the previous page:
109
155
  ```yaml
110
156
  - id: link_back
@@ -10,7 +10,8 @@
10
10
  pageId?: string
11
11
  url?: string
12
12
  urlQuery?: object
13
- }
13
+ pathParams?: object
14
+ } | false
14
15
  providerId?: string,
15
16
  }): void
16
17
  ```
@@ -19,28 +20,47 @@ The `Login` action is used to start the user login flow. If only one provider is
19
20
 
20
21
  The authorization url usually hosts a page where the user can input their credentials. After the user has logged in successfully, the user is redirected to the `api/auth/callback/[provider_id]` route in the Lowdefy app, where the rest of the authorization code flow is completed.
21
22
 
22
- The `callbackUrl` parameters of the Login action specify where the user is redirected after login is complete. If `callbackUrl` parameters not set, the user will return to the page from which the action was called.
23
+ The `callbackUrl` parameter of the Login action specifies where the user lands after login is complete. Three sources are consulted, in order:
24
+
25
+ 1. The `callbackUrl` param, if given.
26
+ 2. The `?callbackUrl=` query parameter, which Lowdefy sets when it redirects an unauthenticated user to the sign-in page - so a user who was bounced there returns to the page they asked for.
27
+ 3. The app's home page.
28
+
29
+ If none of the three resolves - an app with no `homePageId` whose menu offers the signed-out user no page to fall back on - the action throws rather than staying silently on the sign-in page.
30
+
31
+ To sign in without navigating at all, set `callbackUrl: false`. This is for a login form in a modal or an embedded panel, where the session store re-renders the page with the new user in place. It is not valid for magic-link or social/OAuth sign-in, which redirect through a hop Lowdefy does not control.
32
+
33
+ A sign-in the auth server rejects - a wrong password, an expired or already-used link, an invalid code - is an expected outcome, not an app error. The action throws a `UserError`: `catch` actions on the event still run and the error message still displays, but it is logged to the browser console only and is never reported to the server. The auth server's response is available to `catch` actions as `_actions.<actionId>.error.metaData`, with a `code` (for example `INVALID_EMAIL_OR_PASSWORD`) and the HTTP `status`. A network failure or a server fault is still thrown as an action error and reported.
23
34
 
24
35
  #### Parameters
25
36
 
26
37
  ###### object
27
38
  - `authUrl: object`:
28
39
  - `urlQuery: object`: Query parameters to set for the authorization URL.
29
- - `callbackUrl: object`:
40
+ - `callbackUrl: object | false`: Set to `false` to sign in without navigating. As an object:
30
41
  - `home: boolean`: Redirect to the home page after the login flow is complete.
31
42
  - `pageId: string`: The pageId of the page to redirect to after the login flow is complete.
32
- - `url: string`: The URL to redirect to after the login flow is complete.
43
+ - `url: string`: The URL to redirect to after the login flow is complete. An absolute URL is not `basePath`-prefixed, so it can be an external landing page.
33
44
  - `urlQuery: object`: The urlQuery to set for the page the user is redirected to after login.
45
+ - `pathParams: object`: Values for the placeholders in the destination page's [`path`](/page-paths), by placeholder name.
34
46
  - `providerId: string`: The ID of the provider that should be used for login. If not set and only one provider is configured the configured provider will be used. Else the user will be redirected to a sign in page where they can choose a provider.
35
47
 
36
48
  #### Examples
37
49
 
38
- ###### Login and return to the same page:
50
+ ###### Login and land on the home page (or the page the user was bounced from):
39
51
  ```yaml
40
52
  - id: login
41
53
  type: Login
42
54
  ```
43
55
 
56
+ ###### Login in a modal, without navigating:
57
+ ```yaml
58
+ - id: login
59
+ type: Login
60
+ params:
61
+ callbackUrl: false
62
+ ```
63
+
44
64
  ###### Login with the google provider:
45
65
  ```yaml
46
66
  - id: login_with_google
@@ -7,6 +7,7 @@
7
7
  pageId?: string
8
8
  url?: string
9
9
  urlQuery?: object
10
+ pathParams?: object
10
11
  }
11
12
  redirect?: boolean,
12
13
  }): void
@@ -14,16 +15,17 @@
14
15
 
15
16
  When the `Logout` action is called, the user data and authorization cookies are cleared by the app.
16
17
 
17
- The `callbackUrl` parameters of the Logout action specify where the user is redirected after logout is complete. If `callbackUrl` parameters not set, the user will return to the page from which the action was called.
18
+ The `callbackUrl` parameter of the Logout action specifies where the user lands after logout is complete. Unlike the `Login` action it has no default and does not read the `?callbackUrl=` query: with no `callbackUrl` the page is reloaded and the server re-applies the page's auth rules, which sends a signed-out user off a protected page to the sign-in page. Defaulting to the home page instead could land them on a page they may no longer see.
18
19
 
19
20
  #### Parameters
20
21
 
21
22
  ###### object
22
23
  - `callbackUrl: object`:
23
- - `home: boolean`: Redirect to the home page after the login flow is complete.
24
- - `pageId: string`: The pageId of the page to redirect to after the login flow is complete.
25
- - `url: string`: The URL to redirect to after the login flow is complete.
26
- - `urlQuery: object`: The urlQuery to set for the page the user is redirected to after login.
24
+ - `home: boolean`: Redirect to the home page after the logout flow is complete.
25
+ - `pageId: string`: The pageId of the page to redirect to after the logout flow is complete.
26
+ - `url: string`: The URL to redirect to after the logout flow is complete. An absolute URL is not `basePath`-prefixed, so it can be an external logout landing page.
27
+ - `urlQuery: object`: The urlQuery to set for the page the user is redirected to after logout.
28
+ - `pathParams: object`: Values for the placeholders in the destination page's [`path`](/page-paths), by placeholder name.
27
29
  - `redirect: boolean`: If set to `false` the user session will be cleared, but the page will not be reloaded.
28
30
 
29
31
  #### Examples
@@ -0,0 +1,117 @@
1
+ # MagicLinkVerify
2
+
3
+ ```
4
+ (params?: {
5
+ callbackUrl?: {
6
+ home?: boolean
7
+ pageId?: string
8
+ url?: string
9
+ urlQuery?: object
10
+ pathParams?: object
11
+ }
12
+ errorCallbackUrl?: {
13
+ home?: boolean
14
+ pageId?: string
15
+ url?: string
16
+ urlQuery?: object
17
+ pathParams?: object
18
+ }
19
+ newUserCallbackUrl?: {
20
+ home?: boolean
21
+ pageId?: string
22
+ url?: string
23
+ urlQuery?: object
24
+ pathParams?: object
25
+ }
26
+ token?: string
27
+ }): void
28
+ ```
29
+
30
+ The `MagicLinkVerify` action completes a magic-link sign-in from the landing page the sign-in email points at. It navigates the browser to the auth server's verify endpoint, which sets the session cookie and redirects the user on to their destination.
31
+
32
+ ## Why a landing page
33
+
34
+ A magic-link token is single-use, and the verify endpoint consumes it on the **first** `GET` of the URL. Corporate mail security — Microsoft Defender Safe Links, Proofpoint URL Defense, Mimecast — fetches every link in a message as it is delivered. When the email links straight at the verify endpoint the scanner spends the token minutes before the person clicks, and the person lands on the auth error page with `INVALID_TOKEN`.
35
+
36
+ Setting [`auth.authPages.magicLink`](/auth-configuration#the-magic-link-landing-page) to a page in your app moves the email's link to that page, carrying the token and callback destinations on the URL query. Fetching a Lowdefy page has no side effect, so the token stays unspent until a person clicks a button that runs `MagicLinkVerify`.
37
+
38
+ This action **must** be bound to a click. Do not run it in `onMount` and do not auto-redirect from the landing page: scanning sandboxes that execute JavaScript would consume the token anyway, and you would be no better off than linking at the verify endpoint directly.
39
+
40
+ ## Defaults come from the URL query
41
+
42
+ Every parameter is optional. The auth server minted the landing URL with the verify query on it, so the action reads its defaults from the page's own URL:
43
+
44
+ | Parameter | Default |
45
+ | --------- | ------- |
46
+ | `token` | the `?token=` query parameter |
47
+ | `callbackUrl` | the `?callbackURL=` query parameter, else the auth server's default |
48
+ | `newUserCallbackUrl` | the `?newUserCallbackURL=` query parameter, else `callbackUrl` |
49
+ | `errorCallbackUrl` | the `?errorCallbackURL=` query parameter, else `auth.authPages.error` |
50
+
51
+ Pass a parameter only to override what the email carried. The action throws if there is no token in either place, because there is nothing to verify.
52
+
53
+ `callbackUrl: false` is not valid here. Verification redirects through a hop the app does not control, so there is no staying put.
54
+
55
+ The event chain ends after this action, like every other action that navigates the browser away — a step after it would race the page being replaced.
56
+
57
+ #### Parameters
58
+
59
+ ###### object
60
+ - `token: string`: The single-use magic-link token. Defaults to the `?token=` URL query parameter of the landing page.
61
+ - `callbackUrl: object`: Where a successful sign-in lands. Defaults to the `?callbackURL=` URL query parameter.
62
+ - `home: boolean`: Land on the app's home page.
63
+ - `pageId: string`: The pageId to land on.
64
+ - `url: string`: The URL to land on. An absolute URL is not `basePath`-prefixed, so it can be an external landing page.
65
+ - `urlQuery: object`: The urlQuery to set on the destination.
66
+ - `pathParams: object`: Values for the placeholders in the destination page's [`path`](/page-paths), by placeholder name.
67
+ - `newUserCallbackUrl: object`: Where a sign-in that creates a new account lands, for a first-run or onboarding page. Defaults to the `?newUserCallbackURL=` URL query parameter. Same fields as `callbackUrl`.
68
+ - `errorCallbackUrl: object`: Where a failed verification lands, with the reason in `?error=`. Defaults to the `?errorCallbackURL=` URL query parameter, then to `auth.authPages.error`. Same fields as `callbackUrl`.
69
+
70
+ #### Examples
71
+
72
+ ###### The landing page, with everything taken from the URL query:
73
+ ```yaml
74
+ id: magic-link
75
+ type: PageHeaderMenu
76
+ blocks:
77
+ - id: content
78
+ type: Box
79
+ blocks:
80
+ - id: title
81
+ type: Title
82
+ properties:
83
+ content: Sign in
84
+ level: 3
85
+ - id: description
86
+ type: Paragraph
87
+ properties:
88
+ content: Click the button below to finish signing in.
89
+ - id: verify_button
90
+ type: Button
91
+ properties:
92
+ title: Sign in
93
+ events:
94
+ onClick:
95
+ - id: verify
96
+ type: MagicLinkVerify
97
+ ```
98
+
99
+ ###### Send a new user to an onboarding page instead:
100
+ ```yaml
101
+ - id: verify
102
+ type: MagicLinkVerify
103
+ params:
104
+ newUserCallbackUrl:
105
+ pageId: welcome
106
+ ```
107
+
108
+ ###### Override where a successful sign-in lands:
109
+ ```yaml
110
+ - id: verify
111
+ type: MagicLinkVerify
112
+ params:
113
+ callbackUrl:
114
+ pageId: dashboard
115
+ urlQuery:
116
+ source: magic-link
117
+ ```
@@ -28,7 +28,7 @@ The `PdfMake` action is used to generate and download a PDF file from a set of d
28
28
  type: Button
29
29
  properties:
30
30
  title: Download PDF
31
- icon: AiOutlineDownload
31
+ icon: download
32
32
  events:
33
33
  onClick:
34
34
  - id: make_pdf
@@ -53,7 +53,7 @@ The `PdfMake` action is used to generate and download a PDF file from a set of d
53
53
  textAlign: center
54
54
  properties:
55
55
  title: Generate & Download PDF
56
- icon: AiOutlineDownload
56
+ icon: download
57
57
  color: '#6293F8'
58
58
  events:
59
59
  onMount:
@@ -0,0 +1,29 @@
1
+ # PostHogAlias
2
+
3
+ ```
4
+ (params: {
5
+ alias: string,
6
+ }): Promise<null>
7
+ ```
8
+
9
+ The `PostHogAlias` action points a second id at the person PostHog already knows, for example when an app has its own identifier alongside the one used by [`PostHogIdentify`](/PostHogIdentify).
10
+
11
+ When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
12
+
13
+ The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
14
+
15
+ #### Parameters
16
+
17
+ ###### object
18
+ - `alias: string`: __Required__ - The second id for the current person.
19
+
20
+ #### Examples
21
+
22
+ ###### Alias a customer number:
23
+ ```yaml
24
+ - id: alias_person
25
+ type: PostHogAlias
26
+ params:
27
+ alias:
28
+ _user: customerNumber
29
+ ```
@@ -0,0 +1,49 @@
1
+ # PostHogCapture
2
+
3
+ ```
4
+ (params: {
5
+ event: string,
6
+ properties?: object,
7
+ groups?: object,
8
+ }): Promise<null>
9
+ ```
10
+
11
+ The `PostHogCapture` action captures a named product event in [PostHog](https://posthog.com).
12
+
13
+ Autocapture already records clicks and pageviews, so keep the set of named events small. Every event is billable, and a funnel of thirty near identical events tells you less than one of five. Never send personally identifiable information as a property.
14
+
15
+ When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
16
+
17
+ The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
18
+
19
+ #### Parameters
20
+
21
+ ###### object
22
+ - `event: string`: __Required__ - The event name. Snake case names that read as a completed action, like `report_submitted`, work best in funnels.
23
+ - `properties: object`: Event properties.
24
+ - `groups: object`: Groups to attach to this one event, as `{ groupType: groupKey }`. Sent to PostHog as the `$groups` property.
25
+
26
+ #### Examples
27
+
28
+ ###### Capture an event after a request:
29
+ ```yaml
30
+ - id: submit_report
31
+ type: Button
32
+ properties:
33
+ title: Submit report
34
+ events:
35
+ onClick:
36
+ - id: submit
37
+ type: Request
38
+ params: submit_report
39
+ - id: capture_event
40
+ type: PostHogCapture
41
+ params:
42
+ event: report_submitted
43
+ properties:
44
+ report_type:
45
+ _state: report_type
46
+ line_item_count:
47
+ _array.length:
48
+ _state: line_items
49
+ ```
@@ -0,0 +1,38 @@
1
+ # PostHogCapturePageLeave
2
+
3
+ ```
4
+ (params: {
5
+ properties?: object,
6
+ }): Promise<null>
7
+ ```
8
+
9
+ The `PostHogCapturePageLeave` action captures a `$pageleave` event by hand, the counterpart to [`PostHogPageview`](/PostHogPageview). PostHog uses pageleaves to compute bounce rate and time on page.
10
+
11
+ `posthog-js` captures a pageleave itself when the tab is closed, as long as automatic pageviews are on, because `capture_pageleave` defaults to `if_capture_pageview`. With `capture_pageview: false`, set `capture_pageleave: true` in the [`PostHogInit`](/PostHogInit) options to keep them, or use this action, for example before a `Link` or `Logout` action. The page `onHidden` event is not a page leave: it also fires when the browser window loses focus.
12
+
13
+ When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
14
+
15
+ The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
16
+
17
+ #### Parameters
18
+
19
+ ###### object
20
+ - `properties: object`: Properties to add to the `$pageleave` event.
21
+
22
+ #### Examples
23
+
24
+ ###### Capture a pageleave before signing out:
25
+ ```yaml
26
+ - id: sign_out
27
+ type: Button
28
+ properties:
29
+ title: Sign out
30
+ events:
31
+ onClick:
32
+ - id: capture_pageleave
33
+ type: PostHogCapturePageLeave
34
+ - id: reset_posthog
35
+ type: PostHogReset
36
+ - id: logout
37
+ type: Logout
38
+ ```