@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/actions/resetvalidation.md

@@ -0,0 +1,85 @@
+# ResetValidation
+
+```
+(void): void
+(blockId: string): void
+(blockIds: string[]): void
+(params: {
+  blockId?: string|string[],
+  regex?: string|string[],
+}): void
+```
+
+The `ResetValidation` action is used to reset validation flags on input fields.
+
+By default when a page is opened, no validation flags are set on any input fields. When the `Validate` is called, a validation flag is set on input fields matching the validation params. To reset the validation flags, use the `ResetValidation` action.
+
+The `ResetValidation` action `blockIds` or `regex` params are used to limit which blocks validation errors and warnings should be reset.
+
+#### Parameters
+
+###### void
+The `ResetValidation` action lowers validation flags on all blocks on the page if called without params.
+
+###### string
+A blockId of the block for which to lower validation flags.
+
+###### string[]
+An array of blockIds of the blocks for which to lower validation flags.
+
+###### object
+  - `blockId?: string|string[]`: A blockId or an array of the blockIds of the blocks for which to lower validation flags
+  - `regex?: string|string[]`: A regex string pattern or an array of regex string patterns to match the blockIds for which to lower validation flags.
+
+#### Examples
+
+###### Lower validation flags for all inputs on the page:
+```yaml
+- id: reset_all
+  type: ResetValidation
+```
+
+###### Lower validation flags for a single input:
+```yaml
+- id: reset_my_input
+  type: ResetValidation
+  params: my_input
+```
+
+###### Lower validation flags for a list of inputs:
+```yaml
+- id: reset_input_a_and_b
+  type: ResetValidation
+  params:
+    - my_input_a
+    - my_input_b
+```
+
+###### Lower validation flags for all inputs matching a regex pattern:
+```yaml
+- id: reset_foo
+  type: ResetValidation
+  params:
+    regex: ^foo\.
+```
+
+###### Lower validation flags for all inputs matching a list of regex patterns:
+```yaml
+- id: reset_foo_and_price
+  type: ResetValidation
+  params:
+    regex:
+      - ^foo\.
+      - ^.*price.*$
+```
+
+###### Lower validation flags for all inputs matching a list of regex patterns and a blockId:
+```yaml
+- id: reset_foo_price_and_my_input
+  type: ResetValidation
+  params:
+    blockId: my_input
+    regex:
+      - ^foo\.
+      - ^.*price.*$
+```

package/content/actions/scrollto.md

@@ -0,0 +1,85 @@
+# ScrollTo
+
+```
+(params: {
+  top?: number,
+  left?: number,
+  behavior?: enum
+}): void
+
+(params: {
+  blockId: string,
+  options: {
+    behavior?: enum,
+    block? enum,
+    inline?: enum
+  }
+}): void
+```
+
+The `ScrollTo` action is used to scroll the users browser. It is often used to scroll back to the top
+of a long form after resetting the form, or to scroll the user to the top of a page after linking to a new page.
+
+The `ScrollTo` action has two modes - scrolling to a block and scrolling to x and y coordinates on a page.
+
+> When scrolling to a block, `ScrollTo` implements [`Element.scrollIntoView()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView), while
+when scrolling to coordinates, it implements [`Window.scrollTo()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/scrollTo).
+
+#### Parameters
+
+######  Scroll to coordinates
+- `top: number`: Specifies the number of pixels along the Y axis to scroll the window.
+- `left: number`: Specifies the number of pixels along the X axis to scroll the window.
+- `behavior: enum`: Defines the transition animation. One of `auto` or `smooth`.
+
+######  Scroll to a block
+- `blockId: string`: __Required__ - The blockId of a block to scroll to.
+- `options: object`: _Object_
+  - `behavior: enum`: Defines the transition animation. One of `auto` or `smooth`. Defaults to `auto`.
+  - `block: enum`: Defines vertical alignment. One of `start`, `center`, `end`, or `nearest`. Defaults to `start`.
+  - `inline: enum`: Defines horizontal alignment. One of `start`, `center`, `end`, or `nearest`. Defaults to `nearest`.
+
+#### Examples
+
+######  Scroll to a block:
+```yaml
+- id: scroll_to_block
+  type: ScrollTo
+  params:
+    blockId: my_block
+```
+
+######  Scroll to the top of the page:
+```yaml
+- id: scroll_to_top
+  type: ScrollTo
+  params:
+    top: 0
+```
+
+######  Scroll to the top of the page after linking from a previous page:
+```yaml
+- id: link_button
+  type: Button
+  events:
+    onClick:
+      - id: link_
+        type: Link
+        params:
+          pageId: next_page
+      - id: scroll_to_top
+        type: ScrollTo
+        params:
+          top: 0
+```
+
+######  Scroll to the centre of a block:
+```yaml
+- id: scroll_to_block
+  type: ScrollTo
+  params:
+    blockId: my_block
+    options:
+      block: center
+      inline: center
+```

package/content/actions/setdarkmode.md

@@ -0,0 +1,62 @@
+# SetDarkMode
+
+```
+(params?: {
+  darkMode?: 'system' | 'light' | 'dark'
+}): void
+```
+
+The `SetDarkMode` action sets the user's dark mode preference. When called without params, it cycles through `light`, `dark`, and `system`. When `darkMode` is provided, it sets the preference to that value.
+
+- `'system'`: Follow the operating system's dark mode preference (and update live when the OS setting changes).
+- `'light'`: Force light mode.
+- `'dark'`: Force dark mode.
+
+The preference is persisted to `localStorage` and triggers re-rendering of the root Ant Design `ConfigProvider`. All blocks and `_media: darkMode` expressions update automatically.
+
+> **Note:** If the app's `theme.darkMode` config is set to `'light'` or `'dark'`, the developer has locked the mode. `SetDarkMode` still stores the user's preference, but it won't take visual effect until the config is changed to `'system'`.
+
+#### Parameters
+
+###### object (optional)
+  - `darkMode: 'system' | 'light' | 'dark'`: Set the dark mode preference. When omitted, cycles through light, dark, and system.
+
+#### Examples
+
+###### Cycle dark mode preference:
+```yaml
+- id: toggle_button
+  type: Button
+  properties:
+    title: Toggle Dark Mode
+    icon:
+      _if:
+        test:
+          _media: darkMode
+        then: AiOutlineSun
+        else: AiOutlineMoon
+  events:
+    onClick:
+      - id: toggle
+        type: SetDarkMode
+```
+
+###### Set dark mode to follow system preference:
+```yaml
+events:
+  onClick:
+    - id: use_system
+      type: SetDarkMode
+      params:
+        darkMode: system
+```
+
+###### Force dark mode:
+```yaml
+events:
+  onClick:
+    - id: enable_dark
+      type: SetDarkMode
+      params:
+        darkMode: dark
+```

package/content/actions/setfocus.md

@@ -0,0 +1,33 @@
+# SetFocus
+
+```
+(params: string): void
+```
+
+This action implements the [HTMLElement.focus()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) method.
+
+The `SetFocus` action sets focus on the specified HTML element, provided it can receive focus. It takes an id of the HTML element as a parameter.
+By default, when focusing an element, the browser will scroll it into view and may provide visible indication of the focus, typically by displaying a "focus ring" around the element.
+
+Note that for blocks like `TextInput`, the id of the HTML input element is not equal to the block id, since the block includes other HTML elements like the label, extra text and icons. You can inspect the HTML elements in the browser to find the correct element id.
+
+#### Parameters
+
+###### string
+String that is the ID of the HTML element to focus.
+
+#### Examples
+
+###### Set a TextInput block in focus when another TextInput's value changes:
+```yaml
+- id: text_input_1
+  type: TextInput
+  events:
+    onChange:
+      - id: set_focus
+        type: SetFocus
+        # Note that the params is an HTML element ID, and not a Block ID.
+        params: text_input_2_input 
+- id: text_input_2
+  type: TextInput
+```

package/content/actions/setglobal.md

@@ -0,0 +1,63 @@
+# SetGlobal
+
+```
+(toSet: object): void
+```
+
+The `SetGlobal` action sets values to the `global` object. It takes an object as parameters, and sets each of those values to the `global` object.
+This is useful if you need to set a value that needs to be available across multiple pages in the app, like the id of a currently selected
+object. `SetGlobal` works just like [`SetState`](/SetState), except it sets to the `global` object and not `state`.
+
+#### Parameters
+
+###### object
+Object with key value pairs to set in `global`.
+
+#### Examples
+
+###### Set a single value to global:
+```yaml
+- id: set_selected_company
+  type: SetGlobal
+  params:
+    selected_selected_company:
+      _state: company.id
+```
+
+###### Set multiple values to state:
+```yaml
+- id: multiple_values
+  type: SetGlobal
+  params:
+    firstName: Monica
+    lastName: Geller
+    address:
+      street: 90 Bedford St
+      city: New York
+      zipCode: '10014'
+      country: US
+    friends:
+      - Ross Geller
+      - Rachel Green
+      - Chandler Bing
+      - Phoebe Buffay
+      - Joey Tribbiani
+```
+
+###### Using dot notation:
+```yaml
+- id: dot_notation
+  type: SetGlobal
+  params:
+    firstName: Monica
+    lastName: Geller
+    address.street: 90 Bedford St
+    address.city: New York
+    address.zipCode: '10014'
+    address.country: US
+    friends.0: Ross Geller
+    friends.1: Rachel Green
+    friends.2: Chandler Bing
+    friends.3: Phoebe Buffay
+    friends.5: Joey Tribbiani
+```

package/content/actions/setlocale.md

@@ -0,0 +1,69 @@
+# SetLocale
+
+```
+(params?: {
+  locale?: string
+}): void
+```
+
+The `SetLocale` action sets the user's active locale preference for the app. The preference is persisted to `localStorage` (`lowdefy_locale`) and triggers re-rendering of the root Ant Design `ConfigProvider`. All blocks, `_t` translations, `_locale` operators, antd-built-in strings (date pickers, modals, validation), and dayjs date formatting update automatically.
+
+- `locale`: A BCP 47 code declared in `config.i18n.locales` (e.g. `'en-US'`, `'de-DE'`).
+- `'auto'` (or no params): Clears the user preference. The app falls back to the browser language best-fit, then to `config.i18n.defaultLocale`.
+
+`SetLocale` is a no-op when `config.i18n` is not configured.
+
+#### Parameters
+
+###### object (optional)
+  - `locale: string`: A BCP 47 locale code declared in `config.i18n.locales`, or `'auto'` to clear the preference.
+
+#### Examples
+
+###### Switch to German:
+```yaml
+events:
+  onClick:
+    - id: switch_de
+      type: SetLocale
+      params:
+        locale: de-DE
+```
+
+###### Wire a language picker:
+
+`_locale: supported` returns an array of locale descriptors `{ code, label, antd, dayjs }`. Selector options must be `{ value, label }` pairs, so map each descriptor onto that shape:
+```yaml
+- id: lang_picker
+  type: Selector
+  properties:
+    options:
+      _array.map:
+        on:
+          _locale: supported
+        callback:
+          _function:
+            value:
+              __args: 0.code
+            label:
+              __args: 0.label
+    value:
+      _locale: active
+  events:
+    onChange:
+      - id: set_locale
+        type: SetLocale
+        params:
+          locale:
+            _state: lang_picker
+```
+
+###### Reset to browser/default:
+```yaml
+events:
+  onClick:
+    - id: reset_locale
+      type: SetLocale
+      params:
+        locale: auto
+```

package/content/actions/setstate.md

@@ -0,0 +1,70 @@
+# SetState
+
+```
+(toSet: object): void
+```
+
+The `SetState` action sets values in `state`. It takes an object as parameters, and sets each of those values to the `state` object.
+This is useful if you want to initialize `state`, set a flag after an action has executed (eg. to disable a button), or to set the result
+of a request to state.
+
+#### Parameters
+
+###### object
+Object with key value pairs to set in `state`.
+
+#### Examples
+
+###### Set a single value to state:
+```yaml
+- id: single_value
+  type: SetState
+  params:
+    message: Hello
+```
+
+###### Set multiple values to state:
+```yaml
+- id: multiple_values
+  type: SetState
+  params:
+    firstName: Monica
+    lastName: Geller
+    address:
+      street: 90 Bedford St
+      city: New York
+      zipCode: '10014'
+      country: US
+    friends:
+      - Ross Geller
+      - Rachel Green
+      - Chandler Bing
+      - Phoebe Buffay
+      - Joey Tribbiani
+```
+
+###### Using dot notation:
+```yaml
+- id: dot_notation
+  type: SetState
+  params:
+    firstName: Monica
+    lastName: Geller
+    address.street: 90 Bedford St
+    address.city: New York
+    address.zipCode: '10014'
+    address.country: US
+    friends.0: Ross Geller
+    friends.1: Rachel Green
+    friends.2: Chandler Bing
+    friends.3: Phoebe Buffay
+    friends.5: Joey Tribbiani
+```
+
+###### Initialize state with the value of a request:
+```yaml
+- id: initialize
+  type: SetState
+  params:
+    _request: getUser
+```

package/content/actions/throw.md

@@ -0,0 +1,72 @@
+# Throw
+
+```
+(params: {
+  throw?: boolean,
+  message?: string,
+  metaData?: any
+}): void
+```
+
+The `Throw` action is used throw an error to the user and log to the console. If `throw: true`, the `Throw`
+action will throw an error, and this will stop the execution of actions that are defined after it. If the action does not thrown, the `Throw` action will do nothing and the actions defined after it will be executed.
+
+#### Parameters
+
+- `throw: boolean`: Throws an error and stops the action chain when `true` or continues the action chain when `false` or undefined.
+- `message: string`: The error message to show to the user and log to the console if `throw: true`. This message can be overridden by setting the action's `messages.error`.
+- `metaData: any`: Data to log to the console if `throw: true`.
+
+#### Examples
+
+###### Throw with custom message:
+```yaml
+- id: foo_throw
+  type: Throw
+  params:
+    throw:
+      _eq:
+        - _state: lukes_father
+        - Darth Vader
+    message: Nooooooooooooooooo
+```
+
+###### Throw with metaData:
+```yaml
+- id: foo_throw
+  type: Throw
+  params:
+    throw:
+      _eq:
+        - _state: lukes_father
+        - Darth Vader
+    message: Nooooooooooooooooo
+    metaData:
+      realisation: Luke kissed his sister
+```
+###### Override custom message:
+```yaml
+- id: foo_throw
+  type: Throw
+  messages:
+    error: Meh.
+  params:
+    throw:
+      _eq:
+        - _state: lukes_father
+        - Darth Vader
+    message: Nooooooooooooooooo
+```
+###### Fail silently:
+```yaml
+- id: foo_throw
+  type: Throw
+  messages:
+    error: false
+  params:
+    throw:
+      _eq:
+        - _state: lukes_father
+        - Darth Vader
+    message: Nooooooooooooooooo
+```

package/content/actions/validate.md

@@ -0,0 +1,87 @@
+# Validate
+
+```
+(void): void
+(blockId: string): void
+(blockIds: string[]): void
+(blockIds: string[]): void
+(params: {
+  blockId?: string|string[],
+  regex?: string|string[],
+}): void
+```
+
+The `Validate` action is used to validate a users input, usually before information is inserted into a database using a request.
+It is used in conjunction with the `required` and `validate` fields on input blocks. If the validation fails, the `Validate` action will fail, and this will stop the execution of actions that are defined after it.
+
+The first time a `Validate` action is called, validation errors and warnings are shown to the user. The [`Reset`](/Reset) action resets the validation status and the page `state`. The [`ResetValidation`](/ResetValidation) action resets only the validation status.
+
+The `Validate` action `blockIds` or `regex` params are used to limit which blocks are validated. Only the matched blocks will be validated, and validation results are shown for only those matched blocks.
+
+#### Parameters
+
+###### void
+The `Validate` action validates all blocks on the page if called without params.
+
+###### string
+A blockId of the block to validate.
+
+###### string[]
+An array of blockIds of the blocks to validate.
+
+###### object
+  - `blockId?: string|string[]`: A blockId or an array of the blockIds of the blocks to validate.
+  - `regex?: string|string[]`: A regex string pattern or an array of regex string patterns to match the blockIds to validate.
+
+#### Examples
+
+###### Validate all inputs on the page:
+```yaml
+- id: validate_all
+  type: Validate
+```
+
+###### Validate a single input:
+```yaml
+- id: validate_my_input
+  type: Validate
+  params: my_input
+```
+
+###### Validate a list of inputs:
+```yaml
+- id: validate_input_a_and_b
+  type: Validate
+  params:
+    - my_input_a
+    - my_input_b
+```
+
+###### Validate all inputs matching a regex pattern:
+```yaml
+- id: validate_foo
+  type: Validate
+  params:
+    regex: ^foo\.
+```
+
+###### Validate all inputs matching a list of regex patterns:
+```yaml
+- id: validate_foo_and_price
+  type: Validate
+  params:
+    regex:
+      - ^foo\.
+      - ^.*price.*$
+```
+
+###### Validate all inputs matching a list of regex patterns and a blockId:
+```yaml
+- id: validate_foo_price_and_my_input
+  type: Validate
+  params:
+    blockId: my_input
+    regex:
+      - ^foo\.
+      - ^.*price.*$
+```

package/content/actions/wait.md

@@ -0,0 +1,24 @@
+# Wait
+
+```
+(params: {
+  ms: integer,
+}): void
+```
+
+The `Wait` waits for the set number of milliseconds before returning.
+
+#### Parameters
+
+###### object
+  - `ms: integer`: __Required__ - The number of milliseconds to wait.
+
+#### Examples
+
+###### Wait for 500 milliseconds:
+```yaml
+- id: wait
+  type: Wait
+  params:
+    ms: 500
+```