@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/operators/_and.md

@@ -0,0 +1,76 @@
+# _and
+
+```
+(values: any[]): boolean
+```
+
+The `_and` operator performs a logical `and` over an array of inputs, using javascript [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) and [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) rules.
+
+It only returns true if all the values in the array are truthy (not `false`, `0`, `null`, `undefined`, or the empty string `""`). Else it returns false.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### array
+An array of values over which to perform a logical and.
+
+#### Examples
+
+###### Two `true` values:
+```yaml
+_and:
+  - true
+  - true
+```
+Returns: `true`
+
+###### Array of `true` and `false` values:
+```yaml
+_and:
+  - true
+  - true
+  - true
+  - false
+```
+Returns: `false`
+
+###### Check if two boolean inputs are true:
+```yaml
+_and:
+  - _state: confirm_accept_terms
+  - _state: confirm_accept_privacy_policy
+```
+Returns: `true` if both inputs are `true`
+
+###### Truthy values:
+```yaml
+_and:
+  - "Hello"
+  - 42
+  - []
+  - key: value
+```
+Returns: `true`
+
+###### Falsy values:
+```yaml
+_and:
+  - true
+  - null
+```
+Returns: `false`
+
+```yaml
+_and:
+  - true
+  - 0
+```
+Returns: `false`
+
+```yaml
+_and:
+  - true
+  - ""
+```
+Returns: `false`

package/content/operators/_api.md

@@ -0,0 +1,254 @@
+# _api
+
+```
+(endpointId: string): any
+```
+
+The `_api` operator returns the response object from an API endpoint that has been called using the [`CallAPI`](/CallAPI) action. This operator is only available on the client side (in pages) and provides access to the full API response object including the response data, loading state, success status, and any errors. If the API endpoint has not yet been called or is still executing, the returned value is `null`. Dot notation is supported for accessing nested properties.
+
+If the call was made with `holdValue: true` on the [`CallAPI`](/CallAPI) action, the previous response is retained on the entry while the new call is loading. `_api: <endpointId>.response` keeps returning the previous data instead of going to `null`, while `_api: <endpointId>.loading` still reflects the in-flight state. The previous response is also retained if the new call errors.
+
+The response includes the following fields:
+
+- `blockId: string`: The block id of the block from which the API call was initiated.
+- `endTimestamp: date`: The timestamp when the API call ended.
+- `endpointId: string`: The endpoint id of the API endpoint that was called.
+- `error: object`: Any error if the API endpoint failed or used :reject.
+- `holdValue: boolean`: Present (and `true`) when the call was made with `holdValue: true`.
+- `loading: boolean`: When `true`, the API endpoint is awaiting a response.
+- `pageId: string`: The page id of the page from which the API call was initiated.
+- `payload: object`: The payload sent with the API call.
+- `response: object`: The data returned by the API endpoint's :return statement.
+- `responseTime: number`: The time taken to get the response in milliseconds.
+- `startTimestamp: date`: The timestamp when the API call started.
+- `status: string`: The status of the API call.
+- `success: boolean`: When `true`, the API call completed successfully.
+
+#### Arguments
+
+###### string
+The endpoint id of the API endpoint that was called using the CallAPI action.
+
+#### Examples
+
+###### Accessing the full API response object:
+```yaml
+blocks:
+  - id: fetch_button
+    type: Button
+    properties:
+      title: Load User Data
+    events:
+      onClick:
+        - id: call_user_api
+          type: CallAPI
+          params:
+            endpointId: get_user_profile
+            payload:
+              user_id:
+                _state: selected_user_id
+
+  - id: api_response_display
+    type: Descriptions
+    properties:
+      items:
+        _api: get_user_profile  # Returns the full response object
+```
+Returns: The complete API response object containing response, error, success, status, loading, and timing information.
+
+###### Using dot notation to access the response data:
+```yaml
+blocks:
+  - id: user_name_display
+    type: Paragraph
+    properties:
+      content:
+        _if:
+          test:
+            _api: get_user_profile.success
+          then:
+            _string.concat:
+              - 'Welcome, '
+              - _api: get_user_profile.response.name
+          else: 'User not loaded'
+
+  - id: user_email_display
+    type: Html
+    properties:
+      html:
+        _nunjucks:
+          template: |
+            <div>
+              <span>Email:</span>
+              <span>
+                {{ email }}
+              </span>
+            </div>
+          on:
+            email:
+              _api: get_user_profile.response.email
+```
+
+###### Checking loading and error states:
+```yaml
+events:
+  onMount:
+    - id: fetch_products
+      type: CallAPI
+      params:
+        endpointId: get_products
+    - id: set_products_list
+      type: SetState
+      params:
+        products_list
+          _api: fetch_products.response.products
+
+blocks:
+  - id: loading_text
+    type: Html
+    visible:
+      _api: fetch_products.loading # Show loading text while API is loading
+    properties:
+      html: '<div class="secondary">Loading...</div>'
+
+  - id: error_message
+    type: Alert
+    visible:
+      _not:
+        _api: fetch_products.success
+    properties:
+      type: error
+      message:
+        _if:
+          test:
+            _api: fetch_products.error
+          then:
+            _api: fetch_products.error.message
+          else: 'An error occurred'
+
+  - id: products_list
+    type: List
+    visible:
+      _and:
+        - _api: fetch_products.success
+        - _not:
+            _api: fetch_products.loading
+```
+
+###### Working with multiple API calls:
+```yaml
+blocks:
+  - id: load_all_button
+    type: Button
+    properties:
+      title: Load All Data
+    events:
+      onClick:
+        - id: fetch_user
+          type: CallAPI
+          params:
+            endpointId: get_current_user
+
+        - id: fetch_permissions
+          type: CallAPI
+          params:
+            endpointId: get_user_permissions
+            payload:
+              user_id:
+                _api: get_current_user.response._id
+
+        - id: fetch_dashboard_data
+          type: CallAPI
+          params:
+            endpointId: get_dashboard_stats
+            payload:
+              permission_level:
+                _api: get_user_permissions.response.level
+
+  - id: dashboard_container
+    type: Box
+    visible:
+      _and:
+        - _api: get_current_user.success
+        - _api: get_user_permissions.success
+        - _api: get_dashboard_stats.success
+    blocks:
+      - id: welcome_message
+        type: Title
+        properties:
+          content:
+            _string.concat:
+              - 'Dashboard for '
+              - _api: get_current_user.response.name
+
+      - id: stats_display
+        type: Statistic
+        properties:
+          title: Total Revenue
+          value:
+            _api: get_dashboard_stats.response.total_revenue
+```
+
+###### Using API response in form validation:
+```yaml
+blocks:
+  - id: check_username_button
+    type: Button
+    properties:
+      title: Check Availability
+    events:
+      onClick:
+        - id: check_username
+          type: CallAPI
+          params:
+            endpointId: validate_username
+            payload:
+              username:
+                _state: username_input
+
+  - id: username_input
+    type: TextInput
+    properties:
+      title: Username
+      disabled:
+        _eq:
+          - _api: validate_username.response.available
+          - false
+      label:
+        extra:
+          _if:
+            test:
+              _api: validate_username.response
+            then:
+              _if:
+                test:
+                  _api: validate_username.response.available
+                then: 'Username is available!'
+                else: 'Username is already taken'
+            else: 'Enter a username and check availability'
+```
+
+###### Accessing API response time and metadata:
+```yaml
+blocks:
+  - id: api_debug_info
+    type: Descriptions
+    properties:
+      items:
+        - label: API Status
+          value:
+            _api: fetch_data.status
+        - label: Success
+          value:
+            _api: fetch_data.success
+        - label: Response Time
+          value:
+            _string.concat:
+              - _api: fetch_data.responseTime
+              - 'ms'
+        - label: Timestamp
+          value:
+            _date.format:
+              - _api: fetch_data.endTimestamp
+              - 'HH:mm:ss'
+```

package/content/operators/_app.md

@@ -0,0 +1,114 @@
+# _app
+
+```
+(key: string): any
+(all: boolean): any
+(arguments: {
+  all?: boolean,
+  key?: string,
+  default?: any,
+}): any
+```
+
+The `_app` operator reads structured app metadata declared in `lowdefy.yaml` together with build-environment facts captured by the build. It runs on the client, the server, and at build time.
+
+The metadata object has the following keys:
+
+  - `slug`: From the root `slug` field. **Required when referenced in string form** — `_app: slug` (or `_build.app: slug`) fails the build when `slug` is not declared in `lowdefy.yaml`. This guards against a `null` slug silently scoping namespaced data (e.g. MongoDB filters). The object form with an explicit `default` (`_app: { key: slug, default: ... }`) is the deliberate escape hatch: it returns the default instead of throwing, for the rare site that knowingly tolerates an unset slug. When set, the slug must be kebab-case (`^[a-z][a-z0-9]*(-[a-z0-9]+)*$`) — lowercase letters and digits, hyphen-separated, starts with a letter, no leading/trailing/consecutive hyphens, no underscores. An app that never references `slug` need not declare it.
+  - `name`: From the root `name` field. Free-form string.
+  - `version`: From the root `version` field. Free-form string.
+  - `description`: From the root `description` field. Free-form string.
+  - `license`: From the root `license` field. Free-form string.
+  - `lowdefyVersion`: From the root `lowdefy` field — the framework version the app targets.
+  - `gitSha`: The build's git commit SHA. Resolved at build time in three steps: the `LOWDEFY_GIT_SHA` environment variable (when set non-empty) wins; otherwise the build runs `git rev-parse HEAD`; if both fail (no `.git`, no `git` binary, env unset), `gitSha` is `null`. The build does not error in any case. Build-time and runtime reads return the same value.
+
+Missing root fields yield `null` — every key in the metadata is always present. The sole exception is `slug`: referencing it fails the build when it is not set (see above).
+
+Unknown keys return `null`. Dot-paths against the flat shape also return `null` (no exception).
+
+#### Build time and runtime
+
+`_app` resolves at **build time** and at runtime, and both produce the same value (app metadata is fixed at build). In most positions, write `_app: slug` — the build bakes it into the artifact. Inside a `_build.*` operator (for example as a [`_build.object.fromEntries`](/_build) map key), use the `_build.app` form so it resolves in time to be consumed by the surrounding build operator. See [`_build`](/_build).
+
+#### Root metadata fields accept literals and `_build.*` only
+
+The root metadata fields (`slug`, `name`, `description`, `version`, `license`, `lowdefy`) are resolved before the rest of the config, so they accept only literals and [`_build.*`](/_build) operators. `_ref`, `_var`, and static `_` operators are not resolved in these positions and fail the build with a clear error naming the field. Use `_build.env` for a deploy-time slug or name (for example `slug: { _build.env: APP_SLUG }`).
+
+#### Pinning `gitSha` in deploy environments
+
+Several common deploy paths strip `.git` before the build runs — Docker images that `COPY` only built output, hermetic PaaS sandboxes (Vercel, Netlify, Render), and CI runners with `actions/checkout` configured to fetch only a shallow tree without `.git`. In those environments, `git rev-parse HEAD` fails and `_app: gitSha` resolves to `null` unless `LOWDEFY_GIT_SHA` is set. Map your platform's commit env var via shell expansion in the build command:
+
+| Platform        | Build command                                              |
+| --------------- | ---------------------------------------------------------- |
+| Vercel          | `LOWDEFY_GIT_SHA=$VERCEL_GIT_COMMIT_SHA lowdefy build`     |
+| Netlify         | `LOWDEFY_GIT_SHA=$COMMIT_REF lowdefy build`                |
+| Render          | `LOWDEFY_GIT_SHA=$RENDER_GIT_COMMIT lowdefy build`         |
+| GitHub Actions  | `LOWDEFY_GIT_SHA=$GITHUB_SHA lowdefy build`                |
+| Docker (CLI)    | `--build-arg LOWDEFY_GIT_SHA=$(git rev-parse HEAD)`        |
+
+#### Arguments
+
+###### string
+If the `_app` operator is called with a string argument, the value of the key in the app metadata is returned. If the key is not found, `null` is returned. Dot notation is supported.
+
+###### boolean
+If the `_app` operator is called with the boolean argument `true`, the entire app metadata object is returned.
+
+###### object
+  - `all: boolean`: If `all` is set to `true`, the entire app metadata object is returned. One of `all` or `key` are required.
+  - `key: string`: The value of the key in the app metadata is returned. If the value is 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 `key` is not found. By default, `null` is returned if a value is not found.
+
+#### Examples
+
+###### Get the app slug:
+```yaml
+_app: slug
+```
+```yaml
+_app:
+  key: slug
+```
+Returns: The value of `slug` declared in `lowdefy.yaml`.
+
+###### Get the app name:
+```yaml
+_app: name
+```
+Returns: The value of the root `name` field.
+
+###### Get the entire app metadata object:
+```yaml
+_app: true
+```
+```yaml
+_app:
+  all: true
+```
+Returns: The full `{ slug, name, version, description, license, lowdefyVersion, gitSha }` object.
+
+###### Return a default value if `gitSha` was not captured:
+```yaml
+_app:
+  key: gitSha
+  default: dev
+```
+Returns: The git SHA, or `"dev"` when unavailable (e.g. local dev with no `LOWDEFY_GIT_SHA` and no `.git`).
+
+###### Scope a MongoDB request by app slug:
+```yaml
+filter:
+  created.app_name:
+    _app: slug
+```
+Returns: A filter document with `created.app_name` equal to the app's slug.
+
+###### Show the version in a page title:
+```yaml
+title:
+  _string.concat:
+    - { _app: name }
+    - ' v'
+    - { _app: version }
+```
+Returns: e.g. `"My App v1.2.3"`.

package/content/operators/_args.md

@@ -0,0 +1,65 @@
+# _args
+
+```
+(key: string): any
+(key: integer): any
+(all: boolean): any
+(arguments: {
+  all?: boolean,
+  key?: string | integer,
+  default?: any
+}): any
+```
+
+The `_args` operator gets a value from the `arguments` array passed to a function operator. The `arguments` array is an array of all the positional arguments passed to the function.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### string
+If the `_args` operator is called with a string argument, the value of the key in the `arguments` array is returned. If the value is not found, `null` is returned. Dot notation and [block list indexes](/lists) are supported.
+
+###### integer
+If the `_args` operator is called with a integer argument, the value at that index in the `arguments` array is returned. If the value is not found, `null` is returned. Dot notation and [block list indexes](/lists) are supported.
+
+###### boolean
+If the `_args` operator is called with boolean argument `true`, the entire `arguments` array is returned.
+
+###### object
+  - `all: boolean`: If `all` is set to `true`, the entire `arguments` array is returned. One of `all` or `key` are required.
+  - `key: string | integer`: The value of the key or index in the `arguments` array is returned. If the value is not found, `null`, or the specified default value is returned. Dot notation and [block list indexes](/lists) are supported. One of `all` or `key` are required.
+  - `default: any`: A value to return if the `key` is not found in `arguments`. By default, `null` is returned if a value is not found.
+
+#### Examples
+
+###### Map over an array:
+
+```yaml
+_array.map:
+  on:
+    - firstName: Ted
+      lastName: Mosby
+    - firstName: Robin
+      lastName: Scherbatsky
+    - firstName: Marshall
+      lastName: Eriksen
+    - firstName: Lily
+      lastName: Aldrin
+    - firstName: Barney
+      lastName: Stinson
+  callback:
+    _function:
+      __string.concat:
+        - __args: 0.firstName
+        - ' '
+        - __args: 0.lastName
+```
+Returns:
+```yaml
+- Ted Mosby
+- Robin Scherbatsky
+- Marshall Eriksen
+- Lily Aldrin
+- Barney Stinson
+```