@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/operators/_string.md

@@ -0,0 +1,327 @@
+# _string
+
+The `_string` operator can be used to run javascript [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) methods.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+# Operator methods:
+
+## _string.charAt
+
+```
+(arguments: {on: string, index: number}): string
+(arguments: [on: string, index: number]): string
+```
+
+The `_string.charAt` method returns a string consisting of [the single UTF-16 code (character) unit located at the specified offset](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charAt) into the string.
+
+## _string.concat
+
+```
+(strings: string[]): string
+```
+
+The `_string.concat` method [concatenates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat) strings.
+
+For label-style interpolation (`"Updates (5)"`), prefer [`_string.format`](#format) — it's more concise and renders `null`/`undefined` values as empty strings.
+
+## _string.format
+
+```
+(template: string, ...values: any[]): string
+(arguments: { template: string, on?: object }): string
+```
+
+The `_string.format` method substitutes placeholders in a template string with values. Two input forms are supported:
+
+**Positional (array form)** — `{0}`, `{1}`, ... refer to elements after the template:
+```yaml
+_string.format:
+  - 'Updates ({0})'
+  - _request: get_counts.0.update
+```
+
+**Named (object form)** — `{name}` placeholders are looked up in `on`:
+```yaml
+_string.format:
+  template: 'Updates ({count}) since {date}'
+  on:
+    count:
+      _request: get_counts.0.update
+    date:
+      _date.format:
+        - YYYY-MM-DD
+        - _state: lastSync
+```
+
+**Behavior**:
+- `null` and `undefined` values render as an empty string. This often makes `_if_none` unnecessary — `_string.format: ['Updates ({0})', null]` produces `'Updates ()'` directly.
+- Missing positional indexes or named keys render as an empty string.
+- Non-string values are coerced via `String(v)`. For object/array values, use [`_json.stringify`](/_json) first.
+- To include a literal `{` or `}`, use `{{` or `}}`.
+- Use [`_nunjucks`](/_nunjucks) when you need conditionals, loops, or filters.
+
+## _string.endsWith
+
+```
+(arguments: {
+  on: string,
+  searchString: string,
+  length?: number
+}): boolean
+(arguments: [
+  on: string,
+  searchString: string,
+  length?: number
+]): boolean
+```
+
+The `_string.endsWith` method determines whether a string [ends with the characters of a specified string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith), returning `true` or `false` as appropriate.
+
+## _string.includes
+
+```
+(arguments: {
+  on: string,
+  searchString: string,
+  position?: number
+}): boolean
+(arguments: [
+  on: string,
+  searchString: string,
+  position?: number
+]): boolean
+```
+
+The `_string.includes` method determines whether [one string may be found within another string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes), returning `true` or `false` as appropriate.
+
+## _string.indexOf
+
+```
+(arguments: {
+  on: string,
+  searchValue: string,
+  fromIndex?: number
+}): number
+(arguments: [
+  on: string,
+  searchValue: string,
+  fromIndex?: number
+]): number
+```
+
+The `_string.indexOf` method returns the index within string of the [first occurrence of the specified value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf), starting the search at `fromIndex`. Returns `-1` if the value is not found.
+
+## _string.length
+
+```
+(string: string): number
+```
+
+The `_string.length` method returns the [length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length) of a string.
+
+## _string.lastIndexOf
+
+```
+(arguments: {
+  on: string,
+  searchValue: string,
+  fromIndex?: number
+}): number
+(arguments: [
+  on: string,
+  searchValue: string,
+  fromIndex?: number
+]): number
+```
+
+The `_string.lastIndexOf` method returns the index within string of the [last  occurrence of the specified value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/lastIndexOf), searching backwards from `fromIndex`. Returns `-1` if the value is not found.
+
+## _string.match
+
+```
+(arguments: {
+  on: string,
+  regex: string,
+  regexFlags?: string
+}): string[]
+```
+
+The `_string.match` method returns the [result of matching a string against a regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match).
+
+## _string.normalize
+
+```
+(arguments: {on: string, form?: enum}): string
+(arguments: [on: string, form?: enum]): string
+```
+
+The `_string.normalize` method returns the [Unicode Normalization Form](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) of the string.
+
+## _string.padEnd
+
+```
+(arguments: {
+  on: string,
+  targetLength: number,
+  padString?: string
+}): string
+(arguments: [
+  on: string,
+  targetLength: number,
+  padString?: string
+]): string
+```
+
+The `_string.padEnd` method [pads the string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/padEnd) with a given string (repeated, if needed) so that the resulting string reaches a given length. The padding is applied from the end of the string.
+
+## _string.padStart
+
+```
+(arguments: {
+  on: string,
+  targetLength: number,
+  padString?: string
+}): string
+(arguments: [
+  on: string,
+  targetLength: number,
+  padString?: string
+]): string
+```
+
+The `_string.padStart` method [pads the string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/padEnd) with a given string (repeated, if needed) so that the resulting string reaches a given length. The padding is applied from the start of the string.
+
+## _string.repeat
+
+```
+(arguments: {on: string, count: number}): string
+(arguments: [on: string, count: number]): string
+```
+
+The `_string.repeat` method returns a string which contains [the specified number of copies of the string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat) on which it was called, concatenated together.
+
+## _string.replace
+
+```
+(arguments: {
+  on: string,
+  regex: string,
+  newSubstr: string,
+  regexFlags?: string
+}): string
+```
+
+The `_string.replace` method returns a string with [some or all matches of a pattern replaced by a replacement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace).
+
+## _string.search
+
+```
+(arguments: {
+  on: string,
+  regex: string,
+  regexFlags?: string
+}): number
+```
+
+The `_string.search` method executes a [search for a match between a regular expression and a string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/search). It returns the index of the first match between the regular expression and the given string, or `-1` if no match was found.
+
+## _string.slice
+
+```
+(arguments: {
+  on: string,
+  start: number,
+  end?: number
+}): string
+(arguments: [
+  on: string,
+  start: number,
+  end?: number
+]): string
+```
+
+The `_string.slice` method [extracts a section](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) of a string.
+
+## _string.split
+
+```
+(arguments: {on: string, separator?: string}): string[]
+(arguments: [on: string, separator?: string]): string[]
+```
+
+The `_string.split` method [divides a string into an array of substrings](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split), splitting on the provided separator.
+
+## _string.startsWith
+
+```
+(arguments: {
+  on: string,
+  searchString: string,
+  position?: number
+}): boolean
+(arguments: [
+  on: string,
+  searchString: string,
+  position?: number
+]): boolean
+```
+
+The `_string.startsWith` method determines whether a string [starts with the characters of a specified string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith), returning `true` or `false` as appropriate.
+
+## _string.substring
+
+```
+(arguments: {
+  on: string,
+  start: number,
+  end?: number
+}): string
+(arguments: [
+  on: string,
+  start: number,
+  end?: number
+]): string
+```
+
+The `_string.startsWith` method returns [the part of the string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) between the `start` and `end` indexes, or to the end of the string.
+
+## _string.toLowerCase
+
+```
+(string: string): string
+```
+
+The `_string.toLowerCase` method converts the string to [lower case](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase).
+
+## _string.toUpperCase
+
+```
+(string: string): string
+```
+
+The `_string.toUpperCase` method converts the string to [upper case](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase).
+
+## _string.trim
+
+```
+(string: string): string
+```
+
+The `_string.trim` method [removes whitespace from both ends](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/Trim) of a string.
+
+## _string.trimEnd
+
+```
+(string: string): string
+```
+
+The `_string.trimEnd` method [removes whitespace from the end](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimEnd) of a string.
+
+## _string.trimStart
+
+```
+(string: string): string
+```
+
+The `_string.trimStart` method [removes whitespace from the start](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimStart) of a string.

package/content/operators/_subtract.md

@@ -0,0 +1,24 @@
+# _subtract
+
+```
+([minuend: number, subtrahend: number]): number
+```
+
+The `_subtract` operator takes an array of two numbers as input and returns the second number subtracted from the first.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### array
+An array of two numbers.
+
+#### Examples
+
+###### Subtract a number:
+```yaml
+_subtract:
+  - 12
+  - 4
+```
+Returns: `8`

package/content/operators/_sum.md

@@ -0,0 +1,45 @@
+# _sum
+
+```
+(values: any[]): number
+```
+
+The `_sum` operator takes the sum of the values given as input. If a value is not a number, the value is skipped.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+#### array
+An array of values to add.
+
+#### Examples
+
+###### Two numbers:
+```yaml
+_sum:
+  - 3
+  - 4
+```
+Returns: `7`
+
+###### Array of numbers:
+```yaml
+_sum:
+  - 1
+  - 2
+  - 3
+  - 4
+```
+Returns: `10`
+
+###### Non-numbers are skipped:
+```yaml
+_sum:
+  - 1
+  - null
+  - 3
+  - "four"
+  - 5
+```
+Returns: `9`

package/content/operators/_switch.md

@@ -0,0 +1,37 @@
+# _switch
+
+```
+(arguments: {branches: {if: boolean, then: any}[], default: any}): any
+```
+
+The `_switch` operator evaluates an array of conditions and returns the `then` argument of the first item for which the `if` argument evaluates to `true`. If no condition evaluates to `true`, the value of the `default` argument is returned.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### object
+  - `branches:`
+      `if: boolean`: The boolean result of a test.
+      `then: any`: The value to return if the test is `true`.
+  - `default: any`: The value to return if all the `if` tests are `false`.
+
+#### Examples
+
+###### Return a value based on a series of conditions:
+```yaml
+_switch:
+  branches:
+    - if:
+        _eq:
+          - x
+          - y
+      then: A
+    - if:
+        _eq:
+          - x
+          - z
+      then: B
+  default: C
+```
+Returns: `"C"` since both of the `if` tests are `false`.

package/content/operators/_t.md

@@ -0,0 +1,96 @@
+# _t
+
+```
+(key: string): string
+(arguments: {
+  key: string,
+  values?: object,
+  locale?: string,
+}): string
+```
+
+The `_t` operator translates a string key against the app's `config.i18n` message catalogs, with [ICU MessageFormat](https://formatjs.io/docs/core-concepts/icu-syntax/) interpolation. It's the primary way app authors localize their own strings.
+
+Resolution order: the active locale's messages → `en-US` messages → built-in framework messages → the key itself. The active locale is resolved from the user's preference (`SetLocale`/`localStorage`), then the browser's `navigator.languages` best-fit, then `config.i18n.defaultLocale`. Lowdefy always uses `en-US` as the missing-key fallback, so plugin and module authors should ship `en-US` translations as a baseline.
+
+Configure messages on `config.i18n.messages.{locale}`:
+
+```yaml
+config:
+  i18n:
+    defaultLocale: en-US
+    locales:
+      - { code: en-US, label: English, antd: en_US, dayjs: en }
+      - { code: de-DE, label: Deutsch, antd: de_DE, dayjs: de }
+    messages:
+      en-US:
+        greeting: 'Hello, {name}!'
+        cart.items: '{count, plural, one {# item} other {# items}}'
+      de-DE:
+        greeting: 'Hallo, {name}!'
+        cart.items: '{count, plural, one {# Artikel} other {# Artikel}}'
+```
+
+`_t` is also used by the engine for built-in framework strings (e.g. `engine.action.loading`, `engine.validation.fieldRequired`). Override any built-in by adding the same key under `config.i18n.messages.{locale}`.
+
+**Inside plugin code:** the runtime equivalent for custom block and action plugins is `methods.translate(key, values)`. Same lookup chain, same overrides — see the [i18n concept page](/i18n) for plugin authoring patterns and the `./messages` manifest format.
+
+#### Arguments
+
+###### string
+The translation key to look up.
+
+###### object
+  - `key: string`: The translation key.
+  - `values: object`: Values to interpolate into the message via ICU MessageFormat.
+  - `locale: string`: BCP 47 locale code to force this lookup into a specific locale, regardless of the user's active locale.
+
+#### Examples
+
+###### Translate a simple key:
+```yaml
+_t: greeting
+```
+Returns: the active-locale message at `messages.{active}.greeting`, or the `en-US` message, or the key.
+
+###### Interpolate values:
+```yaml
+_t:
+  key: greeting
+  values:
+    name:
+      _user: name
+```
+Returns: e.g. `"Hallo, Ada!"` when active is `de-DE`.
+
+###### Pluralize via ICU MessageFormat:
+```yaml
+_t:
+  key: cart.items
+  values:
+    count:
+      _state: itemCount
+```
+Returns: `"3 items"` / `"3 Artikel"` etc., respecting the locale's plural rules.
+
+###### Force a specific locale:
+```yaml
+_t:
+  key: greeting
+  locale: en-US
+```
+Returns: the en-US message regardless of the active locale.
+
+###### Override a built-in framework string:
+```yaml
+config:
+  i18n:
+    defaultLocale: de-DE
+    locales:
+      - { code: de-DE, label: Deutsch, antd: de_DE, dayjs: de }
+    messages:
+      de-DE:
+        engine.validation.fieldRequired: 'Pflichtfeld'
+        engine.action.loading: 'Laden'
+```
+The engine's built-in messages (used by `Validate`, `Request`, etc.) now render in German.

package/content/operators/_theme.md

@@ -0,0 +1,65 @@
+# _theme
+
+```
+(key: string): any
+(all: boolean): any
+(arguments: {
+  all?: boolean,
+  key?: string,
+  default?: any,
+}): any
+```
+
+The `_theme` operator gets a value from the app's antd theme seed tokens, as configured in `theme.antd.token` in `lowdefy.yaml`. This is useful for accessing theme values in expressions, such as setting colors or sizes dynamically based on the app's theme.
+
+> The `_theme` operator is **client-side only**. It accesses seed tokens only — for derived tokens (like hover/active color variants), use CSS variables instead: `var(--ant-color-primary-hover)`.
+
+See the [Theming](/theming) concept page for details on configuring your app's theme.
+
+#### Arguments
+
+###### string
+If the `_theme` operator is called with a string argument, the value of that token key from `theme.antd.token` is returned. If the token is not found, `null` is returned.
+
+###### boolean
+If the `_theme` operator is called with boolean argument `true`, the entire seed token object is returned.
+
+###### object
+  - `all: boolean`: If `all` is set to `true`, the entire seed token object is returned. One of `all` or `key` are required.
+  - `key: string`: The value of the specified token is returned. If not found, `null` or the specified default value is returned. One of `all` or `key` are required.
+  - `default: any`: A value to return if the token key is not found. By default, `null` is returned.
+
+#### Examples
+
+###### Get the primary color token:
+```yaml
+_theme: colorPrimary
+```
+Returns: `"#1677ff"` (or whatever `colorPrimary` is set to in your theme config).
+
+###### Get a token with a default value:
+```yaml
+_theme:
+  key: colorBgContainer
+  default: '#ffffff'
+```
+Returns the value of `colorBgContainer` from the theme, or `"#ffffff"` if not set.
+
+###### Get all seed tokens:
+```yaml
+_theme:
+  all: true
+```
+Returns the entire `theme.antd.token` object.
+
+###### Use in a block property:
+```yaml
+- id: my_paragraph
+  type: Paragraph
+  properties:
+    content: The theme's primary color is set to...
+  style:
+    .element:
+      color:
+        _theme: colorPrimary
+```

package/content/operators/_type.md

@@ -0,0 +1,78 @@
+# _type
+
+```
+(type: enum): boolean
+(arguments: {
+  type: string,
+  on?: any,
+  key?: string
+}): boolean
+```
+
+The `_type` operator performs a type test on an object, and returns true if the object is of the specified type.
+
+The regex operator has shorthand argument definitions that can be used on web client.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### object
+  - `type: enum`: __Required__ - The type to test. Can be one of:
+    - `string`
+    - `array`
+    - `date`
+    - `object`
+    - `boolean`
+    - `number`
+    - `integer`
+    - `null`
+    - `undefined`
+    - `none` (`null` or `undefined`)
+    - `primitive` (`undefined`, `null`, `string`, `number`, `boolean`, or `date`)
+  - `on: any`: The value to test. One of `on` or `key` must be specified unless the operator is used in an input block.
+  - `key: string`: The key of a value in `state` to test. One of `on` or `key` must be specified unless the operator is used in an input block.
+
+###### string
+The type to test. The string shorthand can only be used in an input block, and the tested value will be the block's value.
+
+#### Examples
+
+###### Check if a value is a number:
+```yaml
+_type:
+  type: number
+  on:
+    _state: input
+```
+Returns: `true` if a number.
+
+###### Using the key of the value in `state`:
+```yaml
+_type:
+  type: number
+  key: input
+```
+Returns: `true` if a number.
+
+###### Using the value of the block in which the operator is evaluated:
+```yaml
+id: input
+type: TextInput
+validate:
+  - message: This field id required.
+    status: error
+    pass:
+      _not:
+        _type: none
+```
+Returns: `true` if the input is none.
+
+###### Test if an id in the `urlQuery` is undefined or null:
+```yaml
+_type:
+  type: none
+  on:
+    _url_query: id
+```
+Returns: `true` if the id is none,