@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/concepts/lists.md

@@ -0,0 +1,144 @@
+# Lists
+
+List category blocks render multiple [`content areas`](/layout), based on data in the [`state`](/page-and-app-state) object.
+
+Since the content area might contain input blocks, the block has an array value in state, with it's `block id` as key. For each item in the array, an content area (or set of content areas is rendered). Multiple list blocks can be nested.
+
+### List indices and block ids
+
+If a block is to be rendered in an list's content area, the block id should contain a list index placeholder (specified with the `$` symbol) for each list it is a part of. These placeholders will be populated with the blocks `list indices`. The `list indices` are a array of integers, indicating at which position in the list the block is, for each level of list blocks (zero indexed). The block id should be in valid dot-notation once the placeholders have been substituted.
+
+This can be made more clear with a example. Suppose we have a list block with id `contacts`. Inside this list we have a text input block for the contact name. We would like our state to look like:
+```yaml
+contacts:
+  - name: Name 1
+  - name: Name 2
+```
+
+The id for the text input block should be `contacts.$.name`. Each text input block will be given an indexed id based on it's position in the contacts list (`contacts.0.name`, `contacts.1.name`, etc.).
+
+Suppose we also want to add a emails array for each contact. To do this, we can add another list block in the `contacts` array, and add a text input inside the emails array. If we want the emails to be a array of strings, i.e. our `state` should look like:
+
+```yaml
+contacts:
+  - name: Name 1
+    emails:
+      - email1@example.com
+      - email2@example.com
+  - name: Name 2
+    emails: []
+```
+
+our config should look like:
+```yaml
+id: contacts
+type: ControlledList
+properties:
+  # ...
+blocks:
+  - id: contacts.$.name
+    type: TextInput
+    properties:
+      # ...
+  - id: contacts.$.emails
+    type: ControlledList
+    properties:
+      # ...
+    blocks:
+      - id: contacts.$.emails.$
+        type: TextInput
+        properties:
+          # ...
+```
+
+Note that the id of the emails list block is `contacts.$.emails` and that it has one `$` placeholder since it is inside the `contacts` list, and the id of the email text input is `contacts.$.emails.$`, which has two `$` placeholders since it is in both the `contacts` and `contacts.$.emails` lists.
+
+The ids of the `contacts.$.emails.$` text input blocks will look like `contacts.0.emails.3` or `contacts.2.emails.1`, and this will result in the `state` where the emails on a contact are an array of strings.
+
+### List indices in operators
+
+List indices are also supported in "getter" operators like `_state`. If the operator is given a key that contains `$` placeholders, and the operator is called from a block with list indices, the placeholders will be populated with the blocks list indices. These indices are populated on `actions` called by the block, and are even populated in `connections` and `requests` if the block that triggered the `Request` action has list indices. This can be used to get values from the `state` array the block is a part of, or even values from another array at the same index.
+
+### List block methods
+
+List blocks can provide methods to change their values. These are
+
+#### `pushItem`
+Add an item at the end of the list.
+
+#### `unshiftItem`
+Add an item at the start of the list.
+
+#### `removeItem`
+Remove an item at the specified index.
+
+#### `moveItemDown`
+Move the item at the specified index one position to the start of the list. If the item is at the start if the list, the item remains at position `0`.
+
+#### `moveItemUp`
+Move the item at the specified index one position to the end of the list. If the item is at the end if the list, the item remains at it's position.
+
+#### Example
+```yaml
+id: page
+type: PageHeaderMenu
+blocks:
+  - id: add_item_at_start
+    type: Button
+    events:
+      onClick:
+        - id: add_item_at_start
+          type: CallMethod
+          params:
+            blockId: list
+            method: unshiftItem
+  - id: add_item_at_end
+    type: Button
+    events:
+      onClick:
+        - id: add_item_at_end
+          type: CallMethod
+          params:
+            blockId: list
+            method: pushItem
+  - id: list
+    type: List
+    blocks:
+      - id: list.$.move_item_down
+        type: Button
+        events:
+          onClick:
+            - id: move_item_down
+              type: CallMethod
+              params:
+                blockId: list
+                method: moveItemDown
+                args:
+                  - _index: 0 # Get the first index in the indices array
+      - id: list.$.move_item_up
+        type: Button
+        events:
+          onClick:
+            - id: move_item_up
+              type: CallMethod
+              params:
+                blockId: list
+                method: moveItemUp
+                args:
+                  - _index: 0
+      - id: list.$.remove_item
+        type: Button
+        events:
+          onClick:
+            - id: remove_item
+              type: CallMethod
+              params:
+                blockId: list
+                method: removeItem
+                args:
+                  - _index: 0
+```
+
+### Lists and state
+
+List blocks create a content area for each item in `state`. If `state` is updated, the list block will also update, creating or destroying content areas as necessary. Thus list blocks can also be manipulated by setting `state` directly using the [`SetState`](/SetState) operator.

package/content/concepts/logger.md

@@ -0,0 +1,43 @@
+# Logger
+
+### Source Maps
+
+To enable readable stack traces in Sentry, set the `SENTRY_AUTH_TOKEN` environment variable during build:
+
+```
+SENTRY_AUTH_TOKEN=your-auth-token
+```
+
+This will upload source maps to Sentry during the client build.
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SENTRY_DSN` | Sentry Data Source Name (DSN) for server-side error capture |
+| `SENTRY_AUTH_TOKEN` | (Optional) Auth token for source map uploads during build |
+
+Example `.env` file:
+
+```
+# .env
+SENTRY_DSN=https://abc123@o123456.ingest.sentry.io/1234567
+SENTRY_AUTH_TOKEN=your-auth-token
+```
+
+### Disabling Sentry
+
+To disable Sentry for specific environments:
+
+- **Disable client only:** Set `logger.sentry.client: false`
+- **Disable server only:** Set `logger.sentry.server: false`
+- **Disable completely:** Remove the `SENTRY_DSN` environment variable
+
+### Error Context
+
+When errors are captured, Lowdefy automatically includes:
+
+- **Page ID:** The current page where the error occurred
+- **Block ID:** The block that triggered the error (if applicable)
+- **Config Location:** The source file and line number in your YAML config
+- **User Context:** Configured user fields for authenticated sessions

package/content/concepts/lowdefy-schema.md

@@ -0,0 +1,365 @@
+# Lowdefy App Schema
+
+A Lowdefy app is written as YAML or JSON files, which are combined together using the [`_ref`](/_ref) operator when the app is built into a configuration object that describes the app. This object has different sections that describe different parts of the Lowdefy app.
+
+> A good understanding of YAML is needed before starting with Lowdefy. If you don't have any experience using YAML, you can find a good introduction video <a href = "https://www.youtube.com/watch?v=cdLNKUoMc6c">here</a>.
+
+The root schema for a Lowdefy app is:
+- `lowdefy: string`: __Required__ - The Lowdefy version number that the app uses. This is required and cannot be a reference to another file.
+- `name: string`: A name for the application.
+- `version: string`: The version number of the app that you are building. This is optional and allows you indicate the version of your app.
+- `slug: string`: A kebab-case identifier for the app, available via the [`_app`](/_app) operator. Must match the pattern `^[a-z][a-z0-9]*(-[a-z0-9]+)*$` (lowercase letters and digits, hyphen-separated, must start with a letter).
+- `description: string`: A free-form description of the app.
+- `license: string`: A [SPDX license ID](https://spdx.org/licenses/). You can use this to indicate the project's license if you are licensing your project under a specific software license. If you wish to indicate to others that you do not grant the right to use your project, you can use `UNLICENSED` for this field. How you share your Lowdefy config is up to you.
+- `cli: object`: An object with configuration for the CLI.
+- `config: object`: An object with app configuration like the home page pageId.
+- `auth: object` An object with authentication and authorization configuration.
+- `global: object`: A data object that can be accessed anywhere in the app using the [`_global`](/_global) operator.
+- `connections: object[]`: An array of [`connection`](/connections-and-requests) objects.
+- `plugins: object[]`: An array of `plugin` objects to customize and add block types.
+- `modules: object[]`: An array of module entries. Each module references a reusable configuration package distributed via GitHub or local file paths. See [Modules](/modules) for details.
+- `menus: object[]`: An array of menu objects.
+- `pages: object[]`: An array of page objects.
+
+All of the above fields (along with the framework version and the build git SHA) are also available at runtime via the [`_app`](/_app) operator.
+
+Pages are made up of blocks. Blocks have the following basic schema:
+- `id: string`: An identifier for a block.
+- `type: string`: __Required__ - This is the block type identifier and defines which block will render.
+- `properties: object`: The settings passed to a block component.
+- `layout`: Control how the block will be rendered in the page flow, or in other words, how the block is placed in relation to other blocks. See [layout](/layout-overview) for more details.
+- `blocks: array`: An array of blocks to render within this block.
+
+Find the more detailed block schema [here](/blocks).
+
+> <h3> YAML file extensions </h3>
+<p> Both files with the <code>.yaml</code> and <code>.yml</code> file extensions are supported as YAML files. </p>
+<h3> JSON instead of YAML </h3>
+<p> Since you can reference JSON files, you can build your app using JSON instead of YAML files. The <code>lowdefy.yaml</code> file needs to be a YAML file, but all other configuration can be in referenced JSON files. It also makes sense to use JSON instead of YAML if you are generating configuration using code. </p>
+
+## Config
+
+The config object has the following properties:
+
+- `basePath: string`: Set the base path to serve the Lowdefy application from. This will route all pages under `https://example.com/<base-path>/<page-id>` instead of the default `https://example.com/<page-id>`. The basePath value must start with "/".
+- `homePageId: string`: The id of the page that will load when a visitor navigates to the home route, in other words, when the visitor navigates to `yourdomain.com` or `yourdomain.com/`.
+- `requestTimeout: number`: Maximum time in milliseconds a request may run before the server returns a timeout. This protects against requests that hang on an upstream call (database, SMTP, an external API) running all the way to the host's function limit — important on serverless platforms that bill by execution duration. Defaults to `30000` (30 seconds). Set to `0` to disable. Agent streaming routes are exempt, since they are long-lived by design.
+
+## Auth
+
+The auth object is used to configure user authentication, and has the following properties:
+
+- `adapter: object`: Configure a database adapter.
+- `api: object`: Configure which APIs should be protected.
+- `authPages: object`: Configure pages like the sign in page used by authentication flows.
+- `callbacks: object[]`: Configure callback functions.
+- `debug: boolean`: Can be set to false to disable auth debugging if the log level is set to debug.
+- `events: object[]`: Configure event functions.
+- `pages: object`: Configure which pages should be protected.
+- `providers: object[]`: Configure authentication providers.
+- `session: object`: Configure session.
+- `theme: object`: Configure theme for default authentication pages.
+- `userFields: object`: Map data from the provider to the user object.
+- `advanced: object`: Set advanced authentication options.
+
+See more about how user authentication and authorization [here](/users-introduction).
+
+## Global
+
+In a Lowdefy app, you can define global variables in the __global__ object, which can be accessed using the [`_global`](/_global) operator, and modified using the [`SetGlobal`](/SetGlobal) action. This is a good place to store data or configuration that is used over various pages throughout the app, for example, user preferences that can be modified using `SetGlobal` on one page and easily referenced on all others.
+
+## Connections
+
+In a Lowdefy app you can integrate with other services like API's or databases using `connections` and `requests`. Use connections to configure the settings to a service, for example, settings such as urls or [`secrets`](/secrets) like passwords or API keys. Requests use connections to interact with external services, for example, inserting a data record or executing a query on a database, or simply calling an API end-point.
+
+See more about how `connections` and `requests` are used together [here](/connections-and-requests).
+
+## Plugins
+
+The plugins section is used to configure which plugin packages should be used in the app. It contains an array of plugin definitions, which have the following properties:
+
+- `name: string`: The name of the package. If published to npm, this is the name under which the package is published on npm.
+- `version: string`: An npm or pnpm version specifier of the package to use.
+- `typePrefix: string`: A prefix to append to all types exported by the package to prevent type name clashes.
+
+## Menus
+
+Menu objects describe links to pages, within the app or external. Menu lists are filtered to only show pages that the user is authorized to see as a result of public, private or [role based access controlled (RBAC)](/roles) pages. Blocks such as [PageSiderMenu](/PageSiderMenu) render menu links. If no menu defined, a default menu is created, containing links to all pages defined in the app.
+
+See more about how menu objects are used and defined [here](/menus).
+
+## APIs
+
+API objects define server-side endpoints that execute routines i.e. sequences of steps and control structures that run on the server with access to connections, secrets, and server-side operators.
+
+Each API should have an `id` that is unique among all APIs in the app. Each API is called from the client using the [`CallAPI`](/CallAPI) action with the `endpointId` parameter matching the API's id.
+
+APIs must have a `routine` that defines the execution logic. The routine executes sequentially by default and returns a response to the client through [`:return`](/:return) or [`:reject`](/:reject) control statements.
+
+By default, APIs are public and can be accessed without authentication, just like pages. To require authentication or restrict access to specific roles, APIs must be configured in the `auth` section of your `lowdefy.yaml` file.
+
+See the [APIs documentation](/lowdefy-api) for more information on how to use and define them.
+
+## Pages
+
+Pages in a Lowdefy app are actually just blocks, the building blocks of a Lowdefy app, with a few extra restrictions and features.
+
+Each page should have an `id` that is unique among all pages in the app. Each page is served with the `pageId` as the url route. That is, if a page is created with id `page1`, it will be served at `domain.com/page1`. Module pages use the path `/{entryId}/{pageId}` — for example, a page `users-list` in a module entry `team-users` is served at `domain.com/team-users/users-list`.
+
+If `properties.title` is set on a page block, the title will be set as the page title (This is the title displayed on the tabs in your browser).
+
+Let's have a look at how to define a page and it's blocks. We can start with a simple page a card block on it. We can add a title to our card, by making use of the card block's title property. We can also add a paragraph block to our card so that it won't be so empty.
+
+###### lowdefy.yaml
+```yaml
+lowdefy: LOWDEFY_VERSION
+
+pages:
+  - id: page1
+    type: PageHeaderMenu
+    properties:
+      title: Page 1
+    blocks:
+      - id: content_card
+        type: Card
+        properties:
+          title: Title
+        blocks:
+          - id: paragraph
+            type: Paragraph
+            properties:
+              content: This is a paragraph on Page 1.
+```
+
+Let's add another card to our page and give it some blocks which will allow us to get input from the user.
+
+###### lowdefy.yaml
+```yaml
+lowdefy: LOWDEFY_VERSION
+
+pages:
+  - id: page1
+    type: PageHeaderMenu
+    properties:
+      title: Page 1
+    blocks:
+      - id: content_card
+        type: Card
+        properties:
+          title: Title
+        blocks:
+          - id: paragraph
+            type: Paragraph
+            properties:
+              content: This is a paragraph on Page 1.
+      - id: input_card
+        type: Card
+        blocks:
+          - id: text_input
+            type: TextInput
+            properties:
+              label:
+                title: Please Enter Your Name
+          - id: radio_selector
+            type: RadioSelector
+            properties:
+              label:
+                title: How Are You Feeling?
+                colon: false
+              options:
+                - label: Meh
+                  value: 1
+                  disabled: false
+                - label: Okay
+                  value: 2
+                  disabled: false
+                - label: Good
+                  value: 3
+                  disabled: false
+                - label: Great
+                  value: 4
+                  disabled: false
+                - label: Amazing Now That I'm Using Lowdefy
+                  value: 5
+                  disabled: false
+```
+
+In order to build our page further, we will need to add more blocks. Let's leave this page as is and add another page, with it's own card block containing a title block and a paragraph block.
+
+###### lowdefy.yaml
+```yaml
+lowdefy: LOWDEFY_VERSION
+
+pages:
+  - id: page1
+    type: PageHeaderMenu
+    properties:
+      title: Page 1
+    blocks:
+      - id: content_card
+        type: Card
+        properties:
+          title: Title
+        blocks:
+          - id: paragraph
+            type: Paragraph
+            properties:
+              content: This is a paragraph on Page 1.
+      - id: input_card
+        type: Card
+        blocks:
+          - id: text_input
+            type: TextInput
+            properties:
+              label:
+                title: Please Enter Your Name
+          - id: radio_selector
+            type: RadioSelector
+            properties:
+              label:
+                title: How Are You Feeling?
+                colon: false
+              options:
+                - label: Meh
+                  value: 1
+                  disabled: false
+                - label: Okay
+                  value: 2
+                  disabled: false
+                - label: Good
+                  value: 3
+                  disabled: false
+                - label: Great
+                  value: 4
+                  disabled: false
+                - label: Amazing Now That I'm Using Lowdefy
+                  value: 5
+                  disabled: false
+  - id: page2
+    type: PageHeaderMenu
+    properties:
+      title: Page 2
+    blocks:
+      - id: content_card
+        type: Card
+        properties:
+          title: Title
+        blocks:
+          - id: paragraph
+            type: Paragraph
+            properties:
+              content: This is a paragraph on Page 2.
+```
+
+In order to keep files neat and generally easier to read and understand, we suggest making use of references and templating.
+
+## References and templates
+
+References and templates have the following use cases:
+
+- Splitting out the config for readability and code navigation.
+- Splitting out a piece of config in order to use the exact same config in multiple places.
+- Using a reference with variables to make use of a shared piece of config with dynamic variables.
+- Using a `.njk` file to create config files using the Nunjucks templating language.
+- Using resolver and transformer functions to create Lowdefy config using Javascript functions.
+
+References can be used anywhere in the configuration, as long as the configuration resolves to comply with the Lowdefy app schema. Templating can be taken further by referencing [Nunjucks](https://mozilla.github.io/nunjucks/) template files by simply adding .njk to the file extensions, for example, .yaml.njk. Nunjucks templates hydrate variables at build time, before the yaml is parsed, enabling Nunjucks features like for-loops and if-statements.
+
+See more about references and templates [here](/references-and-templates).
+
+## Suppressing Build Validation with ~ignoreBuildChecks
+
+The `~ignoreBuildChecks` property suppresses build-time validation errors and warnings. Suppression cascades down to all descendant config objects.
+
+### Syntax
+
+```yaml
+# Suppress all checks for this object and descendants
+~ignoreBuildChecks: true
+
+# Suppress only specific check types
+~ignoreBuildChecks:
+  - state-refs
+  - types
+```
+
+### Available Check Slugs
+
+| Slug | What it suppresses |
+|------|-------------------|
+| `state-refs` | Undefined `_state` reference warnings |
+| `payload-refs` | Undefined `_payload` reference warnings |
+| `step-refs` | Undefined `_step` reference warnings |
+| `link-refs` | Invalid Link action page reference warnings |
+| `request-refs` | Invalid Request action reference warnings |
+| `connection-refs` | Nonexistent connection ID references |
+| `types` | All type validation (blocks, operators, actions, requests, connections) |
+| `schema` | JSON schema validation errors |
+
+### Example: Dynamic State
+
+Custom blocks can register state at runtime using `methods.registerEvent`. Since this state doesn't exist during build, you can suppress the validation warning:
+
+###### pages/custom-feature.yaml
+```yaml
+blocks:
+  - id: custom_block
+    type: CustomBlock
+    properties:
+      onClick:
+        _state: dynamicState  # Created by block at runtime
+        ~ignoreBuildChecks: true  # Suppress all build checks
+```
+
+Without `~ignoreBuildChecks`, the build would warn:
+```
+[Config Warning] _state references "dynamicState" but no block with id "dynamicState" exists
+```
+
+### Example: Page-Level Suppression
+
+Suppression cascades to all children, so you can set it on a page to affect all blocks:
+
+```yaml
+pages:
+  - id: dynamic-page
+    type: Box
+    ~ignoreBuildChecks:
+      - state-refs  # Only suppress state reference warnings
+    blocks:
+      - id: block1
+        type: TextInput
+        properties:
+          value:
+            _state: dynamicField  # No warning (inherited from page)
+```
+
+### Example: Custom Plugin Types
+
+When using custom plugin types that aren't registered, you can suppress type validation:
+
+```yaml
+blocks:
+  - id: custom_block
+    type: MyCustomBlock  # Custom type not in registry
+    ~ignoreBuildChecks:
+      - types
+    properties:
+      title: Hello
+```
+
+> **Note:** `~ignoreBuildChecks` only affects build-time validation. Runtime errors still occur if references don't exist. Only use this for references you know will be valid at runtime.
+
+## Lowdefy versions and version updates
+
+Lowdefy is versioned using semantic versioning, with a three part version number, with the form `major.minor.patch`. Lowdefy is under active development and is widely used in enterprise projects. New features and fixes are published on a regular basis, see our [changelog](https://github.com/lowdefy/lowdefy/blob/main/CHANGELOG.md) for the latest release notes.
+
+[TODO]: <> (# TODO: Add roadmap, for whats to expect next.)
+
+To update the version of your app, change the `lowdefy` version field in the `lowdefy.yaml` file, and redeploy the app. You might also need to make some changes to your app configuration to be compatible with the new version.
+
+Patch updates only contain fixes, and you should be safe to update to a patched version without any changes to your app. Since we are actively developing new features, most releases will be minor version updates, and patches won't be made to older versions.
+
+Minor version changes include new features. At this stage, since the project is still in early development, they might also have minor breaking changes to individual blocks, actions, operators or connections. Please check the [changelog](https://github.com/lowdefy/lowdefy/blob/main/CHANGELOG.md) to see if any configuration changes are needed before updating.
+
+Major version updates may include major breaking changes or architecture changes. You might need to make more changes to your configuration to be compatible with the new version. We don't intend to release major versions regularly, and try to minimize breaking changes.