@lowdefy/docs-content 0.0.0-experimental-20260928120643 → 6.1.0

package/content/concepts/blocks.md

@@ -1,150 +0,0 @@
-# Blocks
-
-A Lowdefy page is compiled out of an arrangement of blocks. Every HTML element of this page is rendered as a result of a block placed and configured on the page. A Lowdefy Block is just a React component. A large number of default blocks make it easy to build apps with Lowdefy, and for more specific requirements, custom blocks can be added to apps as [plugins](/plugins).
-
-Blocks make it simple for Lowdefy developers to create apps since they only have to decide which block type to use, where in the layout the block should render, and what the block should do by defining the block's `properties` and `events`. How a block implements these `properties` and `events` is up to the specific block type.
-
-All Lowdefy blocks are categorized according to their primary function:
-- `display` - Display page elements.
-- `input` - Modify a value in [`state`](/page-and-app-state).
-- `container` - Render other blocks into [`content slots`](/layout).
-- `list` - Render `content slots` and blocks for each element in the data array represented in [`state`](/page-and-app-state).
-
-When `state` updates or a requests call completes, the Lowdefy engine re-evaluates all operators and re-renders blocks for which the operator evaluation is different from the previous render result. The result is _live updates_ to all blocks on a page. Operators can be used to build _live update_ logic into all block fields, except for the `id`, `type`, `slots` and `blocks` fields.
-
-The schema for a Lowdefy block is:
-
-- `id: string`: An identifier for a block. For `Input` blocks the block `id` sets the field key which the block will modify in `state`. Field _dot-notation_ can be used to express fields which are nested in objects or arrays.
-- `type: string`: __Required__ - This is the block type identifier and defines what block to use. The block type used must either be a default block type or can defined in the app's [`plugins`](/plugins) configuration.
-- `properties: object`: All the settings passed to a block component. __Operators are evaluated__.
-- `blocks: array`: An array of blocks to render to the default `content` slot for `container` and `list` blocks. See [layout](/layout-overview) for more details on how to use the `blocks` array.
-- `slots: object`: Used to set the content slots and content layout settings for `container` and `list` blocks. See [layout](/layout-overview) for more details on how to use `slots`.
-- `events: object`: Used to define [`actions`](/events-and-actions) that run when the block triggers an [`event`](/events-and-actions).
-- `layout: object`: Used to define the [layout](/layout-overview) settings for a block. __Operators are evaluated__.
-- `skeleton: object`: Used to overwrite a block's default loading behavior by rendering a skeleton. Any block types from [`@lowdefy/blocks-basic`](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins/blocks/blocks-basic/src/blocks) and [`@lowdefy/blocks-loaders`](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins/blocks/blocks-loaders/src/blocks) can be used in the skeleton definition, including sub-blocks. __Operators are evaluated__.
-- `loading: boolean`: When true, renders the block in loading. If a `skeleton` is defined, it will be rendered, else the block's default loading behavior will be rendered. __Operators are evaluated__.
-- `required: boolean | string`: For `input` blocks, whether or not a value is required in `state` when the [`Validate`](/Validate) action is called. Can be either a boolean or a string that is used as the validation error message . __Operators are evaluated__.
-- `class: string | array | object`: CSS class names to apply to the block. Supports Tailwind CSS utility classes. __Operators are evaluated__.
-- `style: css object`: Inline CSS styles. Flat CSS targets the layout wrapper. Use `.`-prefixed keys (e.g. `.element`, `.header`, `.body`) to target specific block parts. __Operators are evaluated__.
-- `validate: array`: A list of validation tests to pass when the [`Validate`](/Validate) action is called. __Operators are evaluated__.
-- `visible: boolean`: Controls whether or not to render a block. Operators are generally used here, and must evaluate to `false` to make the block invisible. Blocks with `visible: false` are excluded from `state`. __Operators are evaluated__.
-
-## Block types
-
-Lowdefy has a set of default block types as defined in the Lowdefy docs. Most of the default Lowdefy blocks aim to cover a very generic implementation of the [Ant Design](https://ant.design/components/overview) React component library, but some addition component libraries are also included. To use all the default block types, you can simply use the block `type` key, such as [`Button`](/Button), [`TextInput`](/TextInput), or [`Box`](/Box).
-
-###### Default block type config example:
-```yaml
-lowdefy: 6.0.0
-pages:
-  - id: example_dashboard
-    type: PageHeaderMenu
-    blocks:
-      - id: basic_chart
-        type: EChart
-        properties:
-          # ... EChart properties
-```
-
-However, the default types can be overwritten or additional types can be defined as required. This is done by defining additional [`plugins`](/plugins).
-
-## Input block validation
-
-All `input` block types maintain a value in the page [`state`](/page-and-app-state). This value is set to the field name matching the block `id`. Nested fields can be created by using _dot notation_ in the `id` to specify the field path, for example, `id: "a.b.c"` will produce a value `{"a": {"b": {"c": null }}}` in the page `state`.
-
-Client side field validation can be applied by setting the `required` and / or `validate` block fields. Field validation is first evaluated when the [`Validate`](/Validate) action is invoked on a page.
-
-##### required schema:
-
-`required` can be a `boolean` or `string` type. When `required: true` the field label will indicate this with a red asterisk for user feedback, and a value will have to be supplied to the field in order to pass validation. If `required` is set to a `string`, this string will be used as the feedback message when the validation fails.
-
-```yaml
-- id: name
-  type: TextInput
-  required: Please provide your name.
-  properties:
-    title: Name
-```
-
-##### validate schema:
-
-The `validate` field takes an `array` of test `objects` to evaluate before passing the field validation. This list of tests are evaluated sequentially, so the first test that fails will be used as the feedback message to the user.
-
-The schema for the validation test `objects`:
-- `pass: boolean`: __Required__ - The test that validates if this item passes or not. This is usually written with operators which evaluate to `true` or `false`. __Operators are evaluated__.
-- `message: string`: __Required__ - The feedback message to the user if this validation tests fails. __Operators are evaluated__.
-- `status: enum`: The feedback type to present to the user. Option are `error` and `warning`. Default is `error`. __Operators are evaluated__.
-
-The following `validate` example first verifies that something was entered into the `email` field, then checks that the field passes a email regex validation using the [`_regex`](/_regex) operator:
-
-```yaml
-  - id: email
-    type: TextInput
-    validate:
-      - message: Please enter a email address.
-        status: error
-        pass:
-          _ne:
-            - _state: email
-            - null
-      - message: Please provide a valid email address.
-        status: error
-        pass:
-          _regex: '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$'
-    properties:
-      title: Email
-```
-
-## Block events
-
-By default all blocks implement `onMount` and `onMountAsync` events. Both the `onMount` and `onMountAsync` events are triggered when the block is mounted. For the `onMount` event, the block only mounts when the event action chain is completed, however, for the `onMountAsync` event, the block will mount as soon as possible while the event actions complete execution.
-
-Apart from the `onMount` and `onMountAsync` events, most blocks also implement their own block specific events such as `onOpen` for [Modal](/Modal) or `onClick` for [Button](/Button). See the events tab on each block's documentation for more details.
-
-See [the events and actions page](/events-and-actions) for more details.
-
-## Block loading
-
-Blocks will only start rendering when the `onInit` event has completed its actions. The `onMount` event on blocks will render blocks with loading active. By default, some blocks will change behavior while they are loading. For example, input blocks will be disabled during loading. The loading behavior of blocks can be controlled using the `loading` block property. Setting `loading` to `true` on a container or list block, will result in rendering all child blocks with loading active.
-
-Often it is useful to render a skeleton of blocks instead of the blocks' default loading behavior. When block definitions are provided to the `skeleton` property on a block, this `skeleton` definition will be rendered when loading is active. Any block types from [`@lowdefy/blocks-basic`](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins/blocks/blocks-basic/src/blocks) and [`@lowdefy/blocks-loaders`](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins/blocks/blocks-loaders/src/blocks) can be used as the skeleton definition. Skeleton blocks are not real blocks, they do not have values in state or events, but they can contain other skeleton blocks as children.
-
-##### Block `loading` and `skeleton` example:
-
-```yaml
-pages:
-  - id: page_one
-    type: Box
-    blocks:
-      # ...
-      - id: paragraph_one
-        type: Paragraph
-        loading:
-          _eq:
-            - _state: done
-            - false
-        skeleton:
-          type: SkeletonParagraph
-          properties:
-            lines: 1
-        properties:
-          content: Lorem ipsum dolor sit amet.
-      # ...
-```
-
-## TLDR
-  - All user interfaces in Lowdefy are assembled out of blocks, which are React components.
-  #### Block types
-  - There are four block categories: `display`, `input`, `container` and `list`.
-  - Operators re-evaluate on every [`state`](/page-and-app-state) update or when request calls complete. This allows blocks to _live update_.
-  - Lowdefy has built in default block types, however this can be overwritten or extended with custom blocks by defining [`plugins`](/plugins) on the Lowdefy config root.
-  - `input` blocks maintain a value in `state` matching the block `id` key. _Dot notation_ applies to specify nested fields.
-  #### Block validation
-  - Field level input validation can be achieved by marking an `input` block as `required` or by specifying a list of `validate` tests.
-  - Validation is invoked using the [`Validate`](/Validate) action.
-  #### Block events
-  - All blocks have`onMount` and `onMountAsync` events.
-  - Each block implements it's own additional events such as `onClick` etc.
-  #### Block loading
-  - Some blocks gracefully handle a loading state while `onMount` events are being executed.
-  - A block's default loading can be overwritten by defining custom `skeleton` settings on a block.

package/content/concepts/dynamic-page-content.md

@@ -1,304 +0,0 @@
-# Dynamic Page Content
-
-Dynamic page content lets parts of a page — or a whole page — be resolved on the server at page load. You place a `Dynamic` block on a page and point it at an [API endpoint](/lowdefy-api). When the page is requested, the server calls the endpoint's routine in-process, the routine returns block config, and the server validates that config and splices it into the page before responding. The client renders the result like any other page.
-
-Dynamic page content is useful when the structure of a page depends on runtime data:
-
-- A dashboard whose sections depend on the user's role, plan, or feature flags.
-- A form generated from a workflow definition stored in a database.
-- A product page whose layout comes from a CMS record.
-- Table views, kanban columns, or navigation derived from tenant configuration.
-
-For content where only the _data_ changes, use [requests](/connections-and-requests) — they are cached, re-fetchable, and don't reset page state. Reach for dynamic page content when the _blocks themselves_ need to change per request.
-
-## How It Works
-
-1. A user requests a page containing a `Dynamic` block.
-2. The server checks page authorization as usual, then calls the endpoint configured on each `Dynamic` block — in-process, no HTTP. The endpoint's own auth is also checked against the user's session.
-3. The routine executes with a payload containing the block's `params`, the `pageId`, the `blockId`, and the page request's `urlQuery`.
-4. The routine returns `{ blocks: [...] }` — ordinary Lowdefy block config.
-5. The server builds and validates the returned blocks: block, action and operator types must be in the app's client bundle, block properties are validated against each block type's schema, and `Request` actions must reference requests defined statically on the page.
-6. The validated blocks become the `Dynamic` block's content, and the page is sent to the client.
-
-If resolution fails, the `Dynamic` block renders its `fallback` slot (or nothing) and the error is logged on the server — the page still loads. Set `required: true` to fail the whole page request instead.
-
-## The Dynamic Block
-
-```yaml
-- id: insights
-  type: Dynamic
-  properties:
-    endpointId: resolve_insights # Required. The endpoint that resolves this content.
-    params: # Optional. Static values passed to the endpoint.
-      area: insights
-    required: false # Optional. true fails the page load on resolution failure.
-    types: # Optional. Extra types the endpoint may return.
-      blocks:
-        - Statistic
-  slots:
-    fallback: # Optional. Rendered when resolution fails.
-      blocks:
-        - id: insights_unavailable
-          type: Html
-          properties:
-            html: Insights are unavailable right now.
-```
-
-`params` must not contain operators — the page config is static. Runtime values belong in the endpoint routine, which reads the payload with `_payload` and the session with `_user`.
-
-A page that should be entirely dynamic is just a page whose body is a single `Dynamic` block.
-
-## The Resolver Endpoint
-
-The endpoint is a normal API endpoint. Use `type: InternalApi` so it has no HTTP route — it is then only callable by the server itself.
-
-The endpoint receives this payload:
-
-- `params: object` - The `Dynamic` block's `params`, verbatim.
-- `pageId: string` - The page being resolved.
-- `blockId: string` - The `Dynamic` block's id.
-- `urlQuery: object` - The query parameters of the page request.
-
-The routine must return an object with a `blocks` array:
-
-```yaml
-api:
-  - id: resolve_insights
-    type: InternalApi
-    auth:
-      public: false
-    routine:
-      - id: get_sections
-        type: MongoDBFind
-        connectionId: mongodb
-        properties:
-          query:
-            roles:
-              $in:
-                _user: roles
-            area:
-              _payload: params.area
-      - :return:
-          blocks:
-            _array.map:
-              on:
-                _step: get_sections
-              callback:
-                _function:
-                  __object.assign:
-                    - id:
-                        __args: 0.section_id
-                      type: Statistic
-                      properties:
-                        title:
-                          __args: 0.title
-                        value:
-                          __args: 0.value
-```
-
-All operators registered on the server — including shared operators like `_state`, `_if` and `_string` — are evaluated during `:return` (`_state` reads the routine's own `:set_state` state). To defer an operator to the client instead, prefix it with one extra underscore, the same convention `_function` bodies use for `__args`:
-
-```yaml
-- :return:
-    blocks:
-      - id: greeting
-        type: Html
-        properties:
-          html:
-            __state: name_input # unescaped to `_state` — evaluates on the client
-```
-
-The server strips one leading underscore from `__`-prefixed keys in the returned config, so `__state` reaches the client as `_state` and binds to page state like any static block. Client-only operators (`_request`, `_global`, ...) have no server implementation and need no escaping, but the `__` form works for them too and is the consistent style.
-
-> **Never place `_secret` in returned block config.** It evaluates during `:return` and the resulting value ships to the browser.
-
-### Data in the returned config is literal
-
-While a Dynamic block's endpoint evaluates its `:return`, data read at runtime stays data. That covers step results, the payload, routine state, `:for` items, and values built from data, such as `_json.parse` of a stored string. Three rules apply:
-
-- **Data cannot carry operators.** No operator may return a value that contains operators. A record holding `{ _request: ... }` or `{ __state: ... }` fails resolution, and the block renders its fallback. The error names the operator and where in its result the operator was found.
-- **Data cannot be a block or an action.** Without a [dynamic blocks policy](#dynamic-blocks-policies), every block and action in the returned content must be written in the `:return` config. Data may fill values inside those blocks (an id, a title, a type, a list of options), but a block or action that is itself data an operator returned, or a copy of it, fails resolution. To render stored block config, check it with a `ValidateDynamic` step under a policy.
-- **Data cannot become an operator by merging.** An object from data that `_object.assign` merges with other config must not be left with an operator key alone, for example next to a key whose value is a function or evaluates to undefined on the client.
-
-Data may nest at most 200 levels deep; deeper data fails resolution with an error saying so. Only keys that name one of the app's operators count as operators. Data such as a search hit's `{ _score: 0.5 }` or `{ _source: { ... } }` stays data.
-
-Write client operators in the `:return` config itself. Only operators that pass their own already-checked params through — `_if`, `_switch`, `_if_none`, `_get`, `_args`, `_function`, `_log`, `_array` and `_object` (except `_object.fromEntries` and `_object.defineProperty`) — may return them, so mapping data rows into blocks with `_array.map` and `_function` works as shown above.
-
-These patterns return config through data and fail resolution:
-
-- **Blocks built up in routine state** (`:set_state` in a loop, then `_state` in `:return`). Build the list inside `:return` with `_array.map` or `_array.concat`.
-- **Blocks returned by a nested endpoint** and read with `_step`. Share block config with `_ref` instead.
-- **A `:for` over a literal list of block configs**, read with `_item`. Map the list inside `:return`.
-- **Blocks built by `_js` or `_jsonata`.** Return the data from them and map it into blocks inside `:return`.
-- **Stored block config returned as it is**, whether read directly, picked out with `_get`, or copied or extended by an `_array.map` callback (`__args: 0`, `__object.assign`). Put the Dynamic block under a policy and return the content through `ValidateDynamic` (see [Rendering stored content under a policy](#rendering-stored-content-under-a-policy)).
-
-## Using urlQuery in the Routine
-
-The page request's query string is forwarded to the resolver as `urlQuery` in the payload. A page loaded as `/products?category=shoes&sort=price` resolves with `urlQuery: { category: 'shoes', sort: 'price' }`:
-
-```yaml
-api:
-  - id: resolve_products
-    type: InternalApi
-    routine:
-      - id: get_products
-        type: MongoDBFind
-        connectionId: mongodb
-        properties:
-          query:
-            category:
-              _payload: urlQuery.category
-          options:
-            sort:
-              - - _payload: urlQuery.sort
-                - 1
-      - :return:
-          blocks:
-            - id: product_count
-              type: Html
-              properties:
-                html:
-                  _string.concat:
-                    - 'Found '
-                    - _array.length:
-                        _step: get_products
-                    - ' products in "'
-                    - _payload: urlQuery.category
-                    - '"'
-```
-
-The resolver executes on every navigation to the page — a menu link, a `Link` action (including to the same page), or the browser back and forward buttons all re-resolve the content on the server. Dynamic page config is never served from a client cache.
-
-## Client Bundle Types
-
-The client bundle is fixed at build time — resolved content can only use block, action and operator types the build included. Types used on static pages are always available. To use a type that appears _only_ in dynamic content, declare it on the `Dynamic` block:
-
-```yaml
-- id: insights
-  type: Dynamic
-  properties:
-    endpointId: resolve_insights
-    types:
-      blocks:
-        - Statistic
-        - EChart
-      actions:
-        - CopyToClipboard
-      operators:
-        - _number
-```
-
-The build bundles declared types into the client. If a routine returns a type that is not in the bundle, resolution fails with a clear error instead of a silently broken page.
-
-## Dynamic Blocks Policies
-
-A dynamic blocks policy, declared under `policies.dynamicBlocks` in `lowdefy.yaml`, lets a Dynamic block render block config that is stored as data — a form built by a form builder, or config a model generated — within limits the app declares. The policy lists what the content may use. Anything unlisted fails, and the policy is checked twice with the same function: by a `ValidateDynamic` step before the content is stored, and on every page get before the content renders.
-
-```yaml
-policies:
-  dynamicBlocks:
-    - id: generated_form
-      blocks:
-        - Title
-        - Paragraph
-        - TextInput
-        - Selector
-      actions:
-        - SetState
-        - CallAPI
-      operators:
-        - _state
-        - _eq
-        - _if
-      endpoints:
-        - submit_form_response
-      links:
-        pages:
-          - form_submitted
-        origins:
-          - https://example.com
-      state: form
-```
-
-| Key             | Default   | Meaning                                                                                                     |
-| --------------- | --------- | ----------------------------------------------------------------------------------------------------------- |
-| `id`            | required  | Policy id, referenced by Dynamic blocks and steps.                                                          |
-| `blocks`        | required  | Block types the content may use. `Dynamic` cannot be listed.                                                |
-| `actions`       | `[]`      | Action types the content may use.                                                                           |
-| `operators`     | `[]`      | Client operator names. `_string` allows every `_string` method. `_operator` cannot be listed.               |
-| `endpoints`     | `[]`      | Endpoints a `CallAPI` action in the content may call.                                                       |
-| `requests`      | `[]`      | Page requests a `Request` action may call. The build checks every page that hosts the policy defines them.  |
-| `links.pages`   | `[]`      | Pages the content may navigate to, by `pageId` or by an app path such as `/form_submitted`.                 |
-| `links.origins` | `[]`      | Exact origins (`https://example.com`) the content may link to or load from.                                 |
-| `state`         | none      | When set, input block ids, `SetState` keys and `_state` reads must sit under this state path.               |
-| `html`          | `false`   | When `false`, no string in the content may contain HTML tag syntax.                                         |
-| `limits`        | see below | `depth` (10), `blocks` (500), `bytes` (262144) and `actionsPerEvent` (20). They can be raised, not removed. |
-
-Besides the lists, a policy requires literal values wherever the content names a target: `properties`, `style`, events and action lists; the params of `Link`, `CallAPI`, `Request` and `SetState`; every `_state` key; and every `pageId` and URL. URLs must be app paths or use a listed origin — including image sources, markdown links and CSS `url()`. A block's properties schema marks which properties hold a URL (see [Plugins](/plugins-introduction)), so a URL property is checked whatever it is called, such as `Search` `indexUrl` or `QRCode` `icon`; every value no schema marks, including action params and the properties of blocks that mark none, is checked by its key (`url`, `href`, `src`, ...). URLs are read as the browser reads them, so surrounding spaces and embedded tabs or newlines do not hide one.
-
-> With `html: false`, an operator that builds strings (`_string`, `_uri`, `_base64`, `_json`) can still assemble HTML at render time from content that passed the check. The build warns when a policy lists one. Leave them out of policies for generated content.
-
-### Rendering stored content under a policy
-
-Put the policy on the Dynamic block, and return the content through a `ValidateDynamic` step with the same policy. Data stays literal in a Dynamic endpoint (see [Data in the returned config is literal](#data-in-the-returned-config-is-literal)); the blocks of a `ValidateDynamic` step that passed with the block's policy are the one exception.
-
-```yaml
-pages:
-  - id: form
-    type: PageHeaderMenu
-    blocks:
-      - id: generated
-        type: Dynamic
-        properties:
-          endpointId: get_form_blocks
-          policy: generated_form
-      - id: submit
-        type: Button
-        properties:
-          title: Submit
-        events:
-          onClick:
-            - id: save
-              type: CallAPI
-              params:
-                endpointId: submit_form_response
-                payload:
-                  answers:
-                    _state: form
-
-api:
-  - id: get_form_blocks
-    type: InternalApi
-    routine:
-      - id: get_form
-        type: MongoDBFindOne
-        connectionId: forms
-        properties:
-          query:
-            _id:
-              _payload: urlQuery.formId
-      - id: check
-        type: ValidateDynamic
-        properties:
-          policy: generated_form
-          blocks:
-            _step: get_form.blocks
-      - :return:
-          blocks:
-            _step: check.blocks
-```
-
-The policy's types are bundled into the page, so a Dynamic block with `policy` does not declare `properties.types`. Content that breaks the policy at page get renders the fallback, and the log lists each violation.
-
-### Checking generated content
-
-A generator calls `ValidateDynamic` with `throwOnInvalid: false` and feeds the errors back to the model. Each error has a `path` into the submitted content, a `rule` and a `message`. `DescribeDynamicPolicy` returns what the policy allows, with the properties schema of each block and the params schema of each action and operator, to build the prompt from. See [Validating Dynamic Content As A Routine Step](/lowdefy-api#validating-dynamic-content-as-a-routine-step).
-
-## Rules and Limitations
-
-- **No `requests` in resolved content.** Request artifacts are written at build time. Resolved blocks reference requests defined statically on the page via `Request` actions, or call endpoints with `CallAPI`.
-- **Nesting is allowed** — resolved content may contain further `Dynamic` blocks, up to 5 levels deep.
-- **Page state resets per visit.** Dynamic pages build a fresh context on every navigation, since the server may resolve different content each time. Keep cross-navigation state in `_global` or `_url_query`.
-- **Endpoint auth always applies.** A public page pointing at a role-protected endpoint renders the fallback for users without the role — useful for role-gated sections.
-- **Data cannot carry operators or be blocks.** Operators in step results, payload or state returned into `:return` fail resolution, and so do blocks and actions that are data, except the blocks of a `ValidateDynamic` step under the block's policy. See [Data in the returned config is literal](#data-in-the-returned-config-is-literal) and [Dynamic Blocks Policies](#dynamic-blocks-policies).
-- **`blockId` namespace is shared.** Resolved blocks share the page's state namespace, so `_state` binds across static and dynamic blocks. Keep blockIds unique, as on any page.