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

package/content/migration/v3-to-v4.md

@@ -1,417 +0,0 @@
-# Version 3 to Version 4
-
-## Payload on Requests
-
-In version 3, the `state`, `global`, `input`, `urlQuery` and `event` data objects were sent with the request. This allowed the use of the [`_state`](/_state), [`_global`](/_global), [`_input`](/_input), [`_url_query`](/_url_query) and [`_event`](/_event) operators inside requests and connections. If the state became too large, this would result in a payload size exceeded error on request calls.
-
-In version 4, these operators can no longer be used in requests, and request payloads are introduced. Payloads can be used to specify the data that should be sent with the request. The data specified in the payload can be accessed using the `_payload` operator. Operators are evaluated in the payload before it is sent, so operators such as [`_state`](/_state) and [`_global`](_global) can be used in the payload.
-
-If only the [`_state`](/_state) operator was used, the entire state object can be set as the payload:
-
-###### Version 3:
-
-```yaml
-id: api_call
-type: AxiosHttp
-connectionId: my_api
-properties:
-  url: /products/new
-  method: post
-  data:
-    name:
-      _state: name
-    product_category:
-      _state: name
-```
-
-###### Version 4:
-
-```yaml
-id: api_call
-type: AxiosHttp
-connectionId: my_api
-payload:
-  _state: true
-properties:
-  url: /products/new
-  method: post
-  data:
-    name:
-      _payload: name
-    product_category:
-      _payload: product_category
-```
-
-The payload can also be created more explicitly using more than one operator type:
-
-###### Version 3:
-
-```yaml
-id: api_call
-type: AxiosHttp
-connectionId: my_api
-properties:
-  url: /products/update
-  method: post
-  data:
-    id:
-      _url_query: id
-    name:
-      _state: name
-```
-
-###### Version 4:
-
-```yaml
-id: api_call
-type: AxiosHttp
-connectionId: my_api
-payload:
-  id:
-    _url_query: id
-  name:
-    _state: name
-properties:
-  url: /products/new
-  method: post
-  data:
-    id:
-      _payload: id
-    name:
-      _payload: name
-```
-
-The `user` data object is still available in requests, and the [`_user`](/_user) operator should be used in the request properties not in they payload as malicious users can modify the data sent in payload.
-
-###### Don't do:
-
-```yaml
-id: api_call
-type: AxiosHttp
-connectionId: my_api
-payload:
-  # ...
-  created_by:
-    _user: id
-properties:
-  url: /products/new
-  method: post
-  data:
-    # ...
-    created_by:
-      _payload: created_by
-```
-
-###### Do:
-
-```yaml
-id: api_call
-type: AxiosHttp
-connectionId: my_api
-payload:
-  # ...
-properties:
-  url: /products/new
-  method: post
-  data:
-    # ...
-    created_by:
-      _user: id
-```
-
-> If you see a warning message like `Operator type "_state" was used but is not defined.`, you are using the `_state` operator in a request's properties and should move it to payload.
-
-## Icons
-
-The Ant Design icons used in version 3 have been replaced by [React Icons](https://react-icons.github.io/react-icons/), which has a much larger library of icons to choose from, including the Ant Design icons. To use a React Icon, set the `icon` or `icon.name` property to the React Icon name.
-
-To convert existing Ant Design icons to React Icons, the icon names should be changed to the new format:
-
-###### Version 3:
-
-```yaml
-id: save_button
-type: Button
-properties:
-  icon: SaveOutlined
-```
-
-###### Version 4:
-
-```yaml
-# Using the same Ant Design icon
-id: save_button
-type: Button
-properties:
-  icon: AiOutlineSave
-```
-
-```yaml
-# Using the Font Awesome icon
-id: save_button
-type: Button
-properties:
-  icon: FaRegSave
-```
-
-## Renames and Minor changes
-
-The `Message` action has been renamed to [`DisplayMessage`](/DisplayMessage). Change the type name of `Message` actions to [`DisplayMessage`](/DisplayMessage).
-
-The `onEnter` and `onEnterAsync` events have been removed as their functionality is duplicated by the `onMount` and `onMountAsync` events. Rename all `onEnter` and `onEnterAsync` events to `onMount` and `onMountAsync` respectively.
-
-Duplicate action ids in the same action chain were allowed in version 3, but are not allowed in version 4. If you get a build error about duplicate action ids, give the actions unique ids.
-
-The `Notification` action has been removed. Switch to the [`DisplayMessage`](/DisplayMessage) action, or use a [`Notification`](/Notification) block and the `CallMethod` action to open the notification.
-
-The 404 page is now always a public page.
-
-The [`Anchor`](/Anchor) block properties schema has changed. The `href` property has been removed and it now takes the same props as the [`Link`](/Link) action.
-
-The [`_yaml.parse`](/_yaml) operator now takes an object with a `on` property or an array where the first argument is the string to parse, instead of just a string, to allow it to take additional options.
-
-The `ChromeColorSelector`, `CircleColorSelector`, `CompactColorSelector`, `GithubColorSelector`, `SliderColorSelector`, `SwatchesColorSelector`, and `TwitterColorSelector` have been replaced by the [`ColorSelector`](/ColorSelector) block.
-
-The `color` properties in blocks like [`MobileMenu`](/MobileMenu), [`PageHeaderMenu`](/PageHeaderMenu), [`PageSiderMenu`](/PageSiderMenu) have been removed. Use Ant Design theme less variables instead.
-
-The [`_var`](/_var) operator `name` param has been renamed to `key` to be more consistent with other getter operators.
-
-The `_format` operator has been replaced with the [`_intl`](/_intl) and [`_moment`](/_moment) operator, with some minor schema changes. Note: `_moment` was renamed to [`_dayjs`](/_dayjs) in v5.
-
-The format of dates in the output of the  [`_json.stringify`](/_json) and [`_yaml.stringify`](/_yaml) operators, as well as in URL query parameters has changed from `_date: {iso_date_string}` to `~d: {iso_date_string}`.
-
-## Block Loading States
-
-The page loading states in version 4 have been improved. In general apps should load a lot faster. Blocks will now be a lot less likely to show a loading state and rather render as normal, and render their children. Input blocks will be disabled while in a loading state. This contributes to users seeing useful content sooner, and to less layout shifts once the app finishes loading.
-
-In version 3, blocks had a `loading` property to specify the loading skeleton that should be used while the block is in a loading state. This functionality has been replaced by the `skeleton` property. The `loading` property is now used to control the loading state of the block. The block will be in a loading state if an `onInit` or `onMount` event is busy, if a parent block is loading or if the `loading` property evaluates to true. See more about loading [here](/blocks).
-
-The convert from version 3 to version 4, replace the `loading` property on blocks with the `skeleton` property.
-
-###### Version 3:
-
-```yaml
-id: paragraph_one
-type: Markdown
-loading:
-  type: SkeletonParagraph
-  properties:
-    lines: 5
-properties:
-  content:
-    _request: get_text.body_text
-```
-
-###### Version 4:
-
-```yaml
-id: paragraph_one
-type: Markdown
-skeleton:
-  type: SkeletonParagraph
-  properties:
-    lines: 5
-properties:
-  content:
-    _request: get_text.body_text
-```
-
-```yaml
-# Keep the block in loading while the request is loading
-id: paragraph_one
-type: Markdown
-loading:
-  _eq:
-    - _request: get_text
-    - null
-skeleton:
-  type: SkeletonParagraph
-  properties:
-    lines: 5
-properties:
-  content:
-    _request: get_text.body_text
-```
-
-## Static files
-
-Static files placed in the `public` folder of your project were always served from the public url path - for example `https://example.com/public/filename.jpeg`. These files are now served from the root path of your app. The example above will now be served from `https://example.com/filename.jpeg`. This allows you to serve files like `robots.txt` and `sitemap.xml` from the root path. Change all references in your config to the new paths.
-
-If you still want to serve assets under the `/public` path, you can add an addition `public` folder inside the existing `public` folder:
-
-```txt
-.
-├─ public
-│  └─ public
-│     └─ my-logo.jpeg
-└─ lowdefy.yaml
-```
-
-## Authentication Changes
-
-In version 4, authentication has been reworked to use [NextAuth.js](https://next-auth.js.org), which offers a lot more flexibility and additional features - read more [here](/users-introduction).
-
-To migrate a version 3 OpenID Connect provider, at least the following needs to be done:
-- The `config.auth` property has moved to the `auth` root level property.
-- The `config.auth.openId` properties have been removed, replace them with configuration for your provider:
-```yaml
-auth:
-  providers:
-    - id: auth0
-      type: Auth0Provider
-      properties:
-        clientId:
-          _secret: AUTH0_CLIENT_ID
-        clientSecret:
-          _secret: AUTH0_CLIENT_SECRET
-        issuer:
-          _secret: AUTH0_ISSUER
-```
-
-- The `NEXTAUTH_SECRET` environment variable needs to be set to a secure secret value (replacing `LOWDEFY_SECRET_JWT_SECRET`).
-- The callback URLs configured with the provider change from `{{ protocol }}{{ host }}/auth/openid-callback` to `{{ protocol }}{{ host }}/api/auth/callback/{{ providerId }}`.
-- The `Login` and `Logout` action params have changed between V3 and V4.
-
-## Custom Blocks, Actions and Operators
-
-Custom blocks, the `JsAction` action and the `_js` operator have been replaced by the new Lowdefy plugin system which is an easier, more powerful and standardized way to extend actions, blocks, connections, operators and the authentication system with custom JavaScript. See the [plugin documentation](/plugins-introduction) for more information on how to use and develop plugins.
-
-The [AgGrid](https://github.com/lowdefy/blocks-aggrid) custom blocks have been added as default Lowdefy blocks, so these blocks can now be used without any additional configuration.
-
-## Context has been removed
-
-In version 3, the first block on a page needed to be a `context` category block. This was because in version 3 you could have multiple context blocks on the same page, each with it's own separate state.
-
-This feature was found to be unnecessary, created additional complexity and was difficult to understand, so it was removed.
-
-The `Context` type block was removed, as it was a `Box` block that also created a context. The `Context` block can be replaced by a `Box`.
-
-If the `Context` block is no longer necessary it can also be removed:
-
-###### Version 3:
-
-```yaml
-id: '404'
-type: Context
-style:
-  minHeight: 100vh
-blocks:
-  - id: 404_result
-    type: Result
-    properties:
-      status: 404
-      title: '404'
-      subTitle: Sorry, the page you are visiting does not exist.
-```
-
-###### Version 4:
-
-```yaml
-id: '404'
-type: Result
-style:
-  minHeight: 100vh
-properties:
-  status: 404
-  title: '404'
-  subTitle: Sorry, the page you are visiting does not exist.
-```
-
-## Other removed blocks
-
-In version 4 the `PageHCF`, `PageHCSF`, `PageHSCF`, and `PageSHCF` blocks have been removed. Instead you can now use the `Layout`, `Header`, `Content`, `Sider` and `Footer` blocks. See more about this [here](https://4x.ant.design/components/layout/).
-
-###### Layout, Header-Content-Footer example:
-
-```yaml
-id: layout
-type: Layout
-style:
-  textAlign: center
-blocks:
-  - id: header
-    type: Header
-    blocks:
-      - id: Title
-        type: Title
-        properties:
-          content: Header
-        style:
-          backgroundColor: red
-  - id: content
-    type: Content
-    blocks:
-      - id: Title
-        type: Title
-        style:
-          backgroundColor: green
-        properties:
-          content: Content
-  - id: footer
-    type: Footer
-    blocks:
-      - id: Title
-        type: Title
-        style:
-          backgroundColor: blue
-        properties:
-          content: Footer
-```
-
-## Server Configuration
-
-The `LOWDEFY_SERVER_BASE_PATH` environment variable configuration option has been removed. To configure a base path, use the `config.basePath` configuration option.
-
-``yaml
-lowdefy: 6.0.0
-
-config:
-  basePath: /foo
-```
-
-The `_build.env` operator can be used to set the base path using an environment variable:
-```yaml
-lowdefy: 6.0.0
-
-config:
-  basePath:
-    _build.env: LOWDEFY_BASE_PATH
-```
-
-The `LOWDEFY_SERVER_PUBLIC_DIRECTORY` and `LOWDEFY_SERVER_BUILD_DIRECTORY` are no longer supported because configuration is bundled with the server at build time.
-
-The `LOWDEFY_SERVER_PORT` environment variable has been replaced by the `PORT` environment variable.
-
-## _change_case
-
-The options splitRegex and stripRegex are no longer supported in v4 and the following have been renamed:
-  - paramCase to kebabCase
-  - headerCase to trainCase
-
-###### Version 3:
-
-```yaml
-_change_case.paramCase:
-  on: example string
-```
-
-###### Version 4:
-
-```yaml
-_change_case.kebabCase:
-  on: example string
-```
-
-###### Version 3:
-
-```yaml
-_change_case.headerCase:
-  on: example string
-```
-
-###### Version 4:
-
-```yaml
-_change_case.trainCase:
-  on: example string
-```

package/content/migration/v6-to-v7.md

@@ -1,222 +0,0 @@
-# Version 6 to Version 7
-
-This guide covers the icon changes when upgrading from Lowdefy v6 to v7. For the new auth system, see [Auth Upgrade](/auth-upgrade).
-
-Lowdefy v7 draws every icon with [Lucide](https://lucide.dev) instead of [react-icons](https://react-icons.github.io/react-icons/). Icon names change from react-icons names (`AiOutlineDelete`) to semantic names (`delete`) and Lucide names (`Trash`). Blocks and Ant Design components draw Lucide icons too, so an app has one icon style.
-
-## Summary of breaking changes
-
-| Change                                         | Impact                                 | Action                                                                   |
-| ---------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
-| react-icons names are not built in             | Almost every app                       | Run `lowdefy upgrade`, or install the compatibility set                  |
-| An unknown icon name fails the build           | Apps with old or misspelled names      | Fix the name the error names                                             |
-| `_operator` names read at runtime need a list  | Apps with a runtime `_operator` name   | List the operators it may call in `operators`                            |
-| Dynamic blocks render only written blocks      | Apps returning stored blocks as data   | Use a policy with `ValidateDynamic`                                      |
-| Block and Ant Design icons are Lucide          | All apps                               | None; check screens that depend on the old look                          |
-| `theme.icons.aliases` targets are Lucide names | Apps with aliases                      | Drop the `Lu` prefix: `LuReceipt` becomes `Receipt`                      |
-| Icon hover titles come from the new names      | Apps that show Icon block hover titles | Set `title` where the text matters                                       |
-| `react-icons` is not a server dependency       | Plugins that import `react-icons`      | Render `components.Icon` with a name, or add `react-icons` to the plugin |
-| `ClickableHtml` fires only listed data events  | Apps that use `data-event`             | Run `lowdefy upgrade`, or list the events in `dataEvents`                |
-
-## Icon names
-
-An icon name has one of three forms:
-
-- **Semantic:** `edit`, `delete`, `chevron-down`. Built-in names for common jobs. [Theming](/theming) lists them all.
-- **Lucide:** `Pencil`, `CreditCard`. The PascalCase name from [lucide.dev/icons](https://lucide.dev/icons).
-- **Qualified:** `lucide:Pencil`. A name in a named [icon set](/plugins-icon-sets).
-
-```yaml
-# v6
-- id: delete_button
-  type: Button
-  properties:
-    title: Delete
-    icon: AiOutlineDelete
-- id: card_icon
-  type: Icon
-  properties:
-    name: AiOutlineCreditCard
-
-# v7
-- id: delete_button
-  type: Button
-  properties:
-    title: Delete
-    icon: delete
-- id: card_icon
-  type: Icon
-  properties:
-    name: CreditCard
-```
-
-## Run the codemod
-
-```bash
-npx lowdefy upgrade
-```
-
-The v7 phase includes the `react-icons-to-lucide` codemod. It rewrites icon names as text, so it reaches:
-
-- YAML, Nunjucks (`.njk`) and JSON config
-- single-quoted names in `_js` code
-- string literals and `meta.icons` in local plugin code
-- `theme.icons.aliases` targets
-
-Each old name maps to a semantic name where one fits, otherwise to a Lucide name. `Lu*` names drop the prefix (`LuPencil` becomes `Pencil`). The table lives in `@lowdefy/codemods` at `v7-0-0/react-icons-to-lucide.json`, and the build uses the same table for its error suggestions.
-
-The codemod reports what it cannot decide for you:
-
-- **Judgement calls**, where the closest Lucide glyph differs from the old one.
-- **Known losses**: filled variants (`AiFillStar`), brand icons such as WhatsApp, and Word and PDF file glyphs. Lucide has no equivalents.
-- **Runtime icon names**: icon properties set from `_state`, `_payload` or `_request`. The codemod does not change data. Use the compatibility set for names stored in a database.
-
-## Build errors for old names
-
-A literal icon name at an icon property that resolves to nothing fails the build. An old react-icons name gets a migration message:
-
-```
-Icon "AiOutlineDelete" is a react-icons name. Lowdefy 7 uses Lucide icons.
-Use "delete" (or "Trash"). To keep react-icons names, install @lowdefy/icons-react-icons
-and set theme.icons.set: react-icons. Run `lowdefy upgrade` to migrate names automatically.
-```
-
-Old Ant Design names such as `HomeOutlined` get the same message, pointing at their semantic name. In v6 these names drew nothing, so the error may show icons that were missing all along.
-
-An icon property is a key ending in `icon` (`icon`, `prefixIcon`, `suffixIcon`, ...), its `name` field, the Icon block's `name`, a `data-icon` attribute in HTML, and `theme.icons.aliases` and `theme.icons.include`. Names inside an operator are bundled but not checked. An unknown name that reaches the page at runtime draws a red `icon-missing` icon.
-
-## Keep old names: the compatibility set
-
-`@lowdefy/icons-react-icons` holds every react-icons 5.6.0 icon under its old name. Install it to keep old names working without edits, or for names stored in data:
-
-```yaml
-plugins:
-  - name: '@lowdefy/icons-react-icons'
-    version: '^7'
-theme:
-  icons:
-    set: react-icons
-```
-
-Old names then resolve in the compatibility set, and semantic and Lucide names still work. Block and Ant Design icons stay Lucide. Without `set: react-icons`, reach an old name with its qualified name: `react-icons:FaWhatsapp`. See [Icon Sets](/plugins-icon-sets).
-
-## Visual changes
-
-- **Block icons are Lucide.** Date picker calendars, input validation marks, selector arrows, the loading spinner, menu toggles and the dark mode toggle all use semantic names and draw Lucide icons.
-- **Ant Design icons are Lucide.** Close buttons on modals, drawers, tags and alerts, alert and message status icons, collapse and menu arrows, pagination arrows, and button spinners use the same semantic names. Spin, Progress, QRCode, the Empty and Result illustrations, and the date picker panel arrows stay as Ant Design draws them.
-- **Stroke width is a setting.** Lucide draws a 2px line on a 24px grid. Set `theme.icons.strokeWidth: 1.5` for a lighter look closer to Ant Design outline icons, or set `strokeWidth` on one icon.
-- **Size is unchanged.** Icons default to `1em`, as before. Change it with `theme.icons.size`.
-- **`color` and `rotate` go through CSS.** `color` colours stroke and fill icons alike, and `rotate` now turns the icon.
-- **Hover titles change.** The Icon block's title comes from the name: `Pencil` gives "Pencil", and `more-vertical` gives "More vertical". Old names in the compatibility set give titles such as "Ai outline user". Set `title` where the text matters, or `title: ''` for none.
-- **Icons without a title are hidden from screen readers** (`aria-hidden`).
-
-## `theme.icons`
-
-`theme.icons.aliases` targets are now Lucide or qualified names. The codemod rewrites them:
-
-```yaml
-# v6
-theme:
-  icons:
-    aliases:
-      invoice: LuReceipt
-    include:
-      - LuFlag
-
-# v7
-theme:
-  icons:
-    aliases:
-      invoice: Receipt
-    include:
-      - Flag
-```
-
-`theme.icons` also has new keys: `set`, `size`, `strokeWidth` and `nonScalingStroke`. See [Theming](/theming).
-
-## `_operator` names read at runtime
-
-An `_operator` whose `name` is read at runtime (from state, a request, a payload or `__args`) must list the operators it may call in `operators`, or the build fails. The build loads exactly those operators with the page, so the call works on a direct page load, and `_operator` refuses any other name. A literal `name`, and the literal branches an `_if` or `_switch` returns, need no list.
-
-```yaml
-# v6
-_operator:
-  name:
-    _state: aggregation
-  params:
-    _state: values
-
-# v7
-_operator:
-  name:
-    _state: aggregation
-  operators:
-    - _sum
-    - _product
-  params:
-    _state: values
-```
-
-## Blocks returned as data by a Dynamic endpoint
-
-A `Dynamic` block without a dynamic blocks policy renders only the blocks and actions its endpoint writes in its `:return` config. Block config the endpoint reads as data (a database record, routine state, a nested endpoint's result) and returns as it is now renders the block's fallback, even when it holds no operators. Data can still fill values in written blocks, for example by mapping stored fields into blocks with `_array.map`.
-
-To render stored or generated block config, declare a [dynamic blocks policy](/dynamic-page-content#dynamic-blocks-policies) that lists what the content may use, put it on the `Dynamic` block, and return the content through a `ValidateDynamic` step with the same policy:
-
-```yaml
-- id: check
-  type: ValidateDynamic
-  properties:
-    policy: stored_content
-    blocks:
-      _step: get_record.blocks
-- :return:
-    blocks:
-      _step: check.blocks
-```
-
-## Plugins
-
-Blocks no longer import icons from `react-icons` or `@ant-design/icons`, and the Lowdefy server no longer installs `react-icons`. A local block plugin should render icons by name with `components.Icon`, and list the names it uses in its `meta.icons`, so apps can restyle them:
-
-```js
-// v6
-import { AiOutlineDelete } from 'react-icons/ai';
-<AiOutlineDelete />;
-
-// v7
-<components.Icon blockId={`${blockId}_delete`} events={events} properties="delete" />;
-```
-
-A plugin that must keep importing `react-icons` adds it to its own `dependencies`.
-
-## Auth links and client addresses
-
-These changes affect apps with auth. See [Auth Upgrade](/auth-upgrade), [Auth configuration](/auth-configuration) and [Deploy with Docker](/docker#behind-a-reverse-proxy).
-
-- **Pinned auth URL.** With `auth.email` configured, the production server refuses to start unless `BETTER_AUTH_URL` or the current environment's `url` in `config.environments` is set, so emailed auth links cannot take their host from a request. The dev server is unchanged.
-- **Client address.** The server takes the client address for auth rate limits, sessions and request logs from the connection, and reads `X-Forwarded-For` only from the proxies listed in `config.trustedProxies`. Behind a reverse proxy or load balancer, list it there; otherwise every client shares the proxy's rate limits. On Vercel nothing changes.
-- **Email link pages.** `SignUp` and `SendVerificationEmail` without a `callbackUrl` send the verification link to `auth.authPages.verifyEmail` (default `/verify-email`), not the home page. `RequestPasswordReset` without `redirectTo` sends the reset link to `auth.authPages.resetPassword` (default `/reset-password`). The build warns when the app sends these emails and the page does not exist.
-
-## `ClickableHtml` data events
-
-A `ClickableHtml` block now fires only the events its `dataEvents` property lists. A `data-event` whose name is not listed does nothing and logs a console warning, and a block without `dataEvents` fires no events from its HTML. HTML is often built from request or user data, and sanitising keeps `data-*` attributes, so in v6 markup inside that data could fire any event the block declared.
-
-```yaml
-# v6
-- id: rows
-  type: ClickableHtml
-  properties:
-    html: '<i data-icon="delete" data-event="onDelete" data-id="42" data-confirm="Delete?"></i>'
-
-# v7
-- id: rows
-  type: ClickableHtml
-  properties:
-    dataEvents:
-      - name: onDelete
-        confirm: true
-    html: '<i data-icon="delete" data-event="onDelete" data-id="42" data-confirm="Delete?"></i>'
-```
-
-An entry is an event name, or `{ name, confirm }`: with `confirm`, every click on the event asks first, whatever the markup says. The `clickable-html-data-events` codemod in `lowdefy upgrade` adds `dataEvents` to each block and reports HTML built from data that inserts values without escaping them. It only reaches the app's files: add `dataEvents` yourself to `ClickableHtml` blocks that [dynamic page content](/dynamic-page-content) builds at page load, for example from config stored in a database. See [HTML attributes](/html-attributes).