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

package/content/display-blocks/pollingtimer.md

@@ -1,263 +0,0 @@
-# PollingTimer
-
-A headless timer that renders nothing and triggers its `onTick` event every `interval` milliseconds while it is running. Use it to poll a request until a background job completes, or to refresh a page on a schedule. Start and stop it with the `start`, `stop` and `toggle` methods, or set `autoStart` to start it on mount. The timer always stops when the block unmounts.
-
-## Poll a request until a job is done
-
-Start the timer when a background job is kicked off, fetch the job status on every tick, and stop the timer with the `stop` method once the job reports it is done:
-
-```yaml
-requests:
-  - id: create_job
-    type: MongoDBInsertOne
-    connectionId: jobs
-    properties:
-      doc:
-        status: queued
-  - id: get_job
-    type: MongoDBFindOne
-    connectionId: jobs
-    payload:
-      job_id:
-        _state: job_id
-    properties:
-      query:
-        _id:
-          _payload: job_id
-blocks:
-  - id: job_poller
-    type: PollingTimer
-    properties:
-      interval: 3000
-    events:
-      onTick:
-        - id: fetch_job
-          type: Request
-          params: get_job
-        - id: stop_when_done
-          type: CallMethod
-          skip:
-            _ne:
-              - _request: get_job.status
-              - done
-          params:
-            blockId: job_poller
-            method: stop
-  - id: start_job
-    type: Button
-    properties:
-      title: Start job
-    events:
-      onClick:
-        - id: create_job
-          type: Request
-          params: create_job
-        - id: set_job_id
-          type: SetState
-          params:
-            job_id:
-              _request: create_job.insertedId
-        - id: start_polling
-          type: CallMethod
-          params:
-            blockId: job_poller
-            method: start
-```
-
-## Timing
-
-The next tick is scheduled `interval` ms after the `onTick` actions finish, so a slow request never causes ticks to overlap or pile up. Stopping the timer while `onTick` actions are running lets them finish, but no further tick is scheduled.
-
-`pauseWhenHidden` pauses the timer while `document.visibilityState` is `hidden`, so a visible browser window that has lost focus keeps ticking. The page `onVisible` and `onHidden` events also fire when the window gains or loses focus, so use them instead when you want to react to focus changes, for example to refresh data once when the user returns.
-
-The engine keeps a history of every event it runs, so each tick adds an `onTick` entry. For a timer that runs for a long time, prefer a longer `interval` or a `maxTicks` limit.
-
-```yaml
-- id: job_timer
-  type: PollingTimer
-  properties:
-    interval: 1000
-  events:
-    onTick:
-      - id: job_timer_set_status
-        type: SetState
-        params:
-          job_status:
-            _if:
-              test:
-                _gte:
-                  - _event: tick
-                  - 5
-              then: done
-              else: running
-      - id: job_timer_stop_when_done
-        type: CallMethod
-        skip:
-          _ne:
-            - _state: job_status
-            - done
-        params:
-          blockId: job_timer
-          method: stop
-- id: job_timer_controls
-  type: Box
-  layout:
-    gap: 8
-  blocks:
-    - id: job_timer_start
-      type: Button
-      properties:
-        title: Start Job
-        icon: CirclePlay
-      events:
-        onClick:
-          - id: job_timer_set_running
-            type: SetState
-            params:
-              job_status: running
-          - id: job_timer_call_start
-            type: CallMethod
-            params:
-              blockId: job_timer
-              method: start
-    - id: job_timer_status
-      type: Span
-      properties:
-        content:
-          _nunjucks:
-            template: "Job status: {{ status }}"
-            on:
-              status:
-                _if_none:
-                  - _state: job_status
-                  - not started
-```
-
-```yaml
-- id: manual_timer
-  type: PollingTimer
-  properties:
-    interval: 1000
-  events:
-    onTick:
-      - id: manual_timer_set_tick
-        type: SetState
-        params:
-          manual_ticks:
-            _event: tick
-- id: manual_timer_controls
-  type: Box
-  layout:
-    gap: 8
-  blocks:
-    - id: manual_timer_start
-      type: Button
-      properties:
-        title: Start
-        icon: CirclePlay
-      events:
-        onClick:
-          - id: manual_timer_call_start
-            type: CallMethod
-            params:
-              blockId: manual_timer
-              method: start
-    - id: manual_timer_stop
-      type: Button
-      properties:
-        title: Stop
-        icon: CirclePause
-      events:
-        onClick:
-          - id: manual_timer_call_stop
-            type: CallMethod
-            params:
-              blockId: manual_timer
-              method: stop
-    - id: manual_timer_toggle
-      type: Button
-      properties:
-        title: Toggle
-        icon: ArrowRightLeft
-      events:
-        onClick:
-          - id: manual_timer_call_toggle
-            type: CallMethod
-            params:
-              blockId: manual_timer
-              method: toggle
-- id: manual_timer_ticks
-  type: Span
-  properties:
-    content:
-      _nunjucks:
-        template: "Ticks: {{ ticks }}"
-        on:
-          ticks:
-            _state: manual_ticks
-```
-
-```yaml
-- id: limited_timer
-  type: PollingTimer
-  properties:
-    interval: 1000
-    autoStart: true
-    maxTicks: 5
-  events:
-    onTick:
-      - id: limited_timer_set_tick
-        type: SetState
-        params:
-          limited_ticks:
-            _event: tick
-- id: limited_timer_ticks
-  type: Span
-  properties:
-    content:
-      _nunjucks:
-        template: "Ticks: {{ ticks }} of 5"
-        on:
-          ticks:
-            _state: limited_ticks
-```
-
-```yaml
-- id: background_timer
-  type: PollingTimer
-  properties:
-    interval: 2000
-    autoStart: true
-    pauseWhenHidden: false
-  events:
-    onTick:
-      - id: background_timer_set_tick
-        type: SetState
-        params:
-          background_ticks:
-            _event: tick
-- id: background_timer_ticks
-  type: Span
-  properties:
-    content:
-      _nunjucks:
-        template: "Ticks while this tab was open or hidden: {{ ticks }}"
-        on:
-          ticks:
-            _state: background_ticks
-```
-
-| Property | Type | Default | Description |
-| --- | --- | --- | --- |
-| `interval` | integer | - | Milliseconds to wait after the `onTick` actions of one tick finish before the next tick fires. Changing it while the timer is waiting restarts the wait. |
-| `autoStart` | boolean | `false` | Start ticking when the block mounts. Off by default, so the timer is started with the `start` method. |
-| `maxTicks` | integer | - | Stop the timer after this many ticks. The `onTick` event of the last tick is still triggered. Unlimited by default. |
-| `pauseWhenHidden` | boolean | `true` | Pause ticking while the browser tab is hidden (`document.visibilityState`), and resume when it becomes visible again. Ticks missed while hidden are not fired on resume; the next tick fires `interval` ms after the tab is visible. |
-
-| Event | Event Data | Description |
-| --- | --- | --- |
-| `onTick` | `{ tick }` | Trigger actions on every tick while the timer is running. The next tick is scheduled `interval` ms after the `onTick` actions finish, so ticks never overlap. |
-
-No CSS keys defined.
-
-No slots defined.

package/content/input-blocks/captcha.md

@@ -1,40 +0,0 @@
-# Captcha
-
-Renders a captcha widget (Cloudflare Turnstile) and writes the minted token into state under its blockId. Configure `provider` and `siteKey` from the `_build.authConfig` projection when `auth.captcha` is enabled. The `reset` method clears the value and mints a fresh token; expiry clears the value automatically.
-
-> The widget script loads from the provider's CDN at render - apps behind a strict CSP should allowlist challenges.cloudflare.com. Tokens are single-use and short-lived: pass the block value as the `captchaToken` param of auth actions, and call the block's `reset` method from the action's `onError` chain to mint a fresh token for retries.
-
-```yaml
-- id: captcha_basic
-  type: Captcha
-  properties:
-    provider: cloudflare-turnstile
-    siteKey: 1x00000000000000000000AA
-```
-
-```yaml
-- id: captcha_compact
-  type: Captcha
-  properties:
-    provider: cloudflare-turnstile
-    siteKey: 1x00000000000000000000AA
-    theme: light
-    size: compact
-```
-
-| Property | Type | Default | Description |
-| --- | --- | --- | --- |
-| `provider` | string | `"cloudflare-turnstile"` | Captcha provider to render. Normally fed from the auth config projection: { _build.authConfig: captcha.provider }. Enum: `cloudflare-turnstile`. |
-| `siteKey` | string | - | The provider site key - public, rendered into the page. Normally fed from the auth config projection: { _build.authConfig: captcha.siteKey }. |
-| `theme` | string | `"auto"` | Widget theme. Enum: `auto`, `light`, `dark`. |
-| `size` | string | `"normal"` | Widget size. Enum: `normal`, `compact`, `flexible`. |
-
-| Event | Event Data | Description |
-| --- | --- | --- |
-| `onSuccess` | \- | Trigger actions when the captcha challenge succeeds and a token is minted. |
-| `onExpire` | \- | Trigger actions when the minted token expires - the block value is cleared so a late submit fails with a clear missing-token error. |
-| `onError` | \- | Trigger actions when the captcha provider reports an error. |
-
-No CSS keys defined.
-
-No slots defined.

package/content/input-blocks/placesautocomplete.md

@@ -1,319 +0,0 @@
-# PlacesAutocomplete
-
-Address input with place suggestions from the Google Places Autocomplete Data API. Must be wrapped in a `GoogleMapsScript` block. The block value is an object: selecting a suggestion fetches the configured place fields, renames them through `resultMapping` and writes them to the value, while typing writes the free text to `labelField` so a form always holds a usable address. Typing, selecting or clearing first removes the keys the previous place wrote, so typed text never keeps another place's coordinates; sibling keys written by other blocks are preserved, and the value becomes null when none remain. `onPlaceChanged` receives the mapped place, `onChange` the new value, and `onError` fires when the Places API request fails.
-
-> The PlacesAutocomplete block must be wrapped in a GoogleMapsScript block, with a valid Google Maps API key that has the Places API (New) enabled. Load the places library on the script, `libraries: [places]`, so it is ready on first render; when it is not listed the block imports it on demand through `google.maps.importLibrary`. Outside a GoogleMapsScript, or when the places library cannot be loaded, the block is a plain text input that still writes the label field. Suggestions are requested `debounce` milliseconds (default 250) after the last keystroke. The examples on this page require a configured API key to return suggestions.
-
-```yaml
-- id: pa_default
-  type: PlacesAutocomplete
-```
-
-```yaml
-- id: pa_title
-  type: PlacesAutocomplete
-  properties:
-    title: Delivery address
-    placeholder: Search for an address
-- id: pa_label_extra
-  type: PlacesAutocomplete
-  properties:
-    title: Site address
-    label:
-      extra: Start typing, then pick a suggestion to capture the full address.
-      tooltip: Addresses are verified against Google Places.
-```
-
-```yaml
-- id: pa_fetch_fields
-  type: PlacesAutocomplete
-  properties:
-    title: Address
-    fetchFields:
-      - addressComponents
-      - location
-      - id
-      - displayName
-```
-
-```yaml
-- id: pa_result_mapping
-  type: PlacesAutocomplete
-  properties:
-    title: Address
-    fetchFields:
-      - location
-      - addressComponents
-    resultMapping:
-      formattedAddress: address.line1
-      location: address.coordinates
-      addressComponents: address.components
-    labelField: address.line1
-```
-
-```yaml
-- id: pa_region_codes
-  type: PlacesAutocomplete
-  properties:
-    title: Address in the United Kingdom
-    requestOptions:
-      includedRegionCodes:
-        - gb
-- id: pa_location_bias
-  type: PlacesAutocomplete
-  properties:
-    title: Near central London
-    requestOptions:
-      includedPrimaryTypes:
-        - street_address
-      locationBias:
-        center:
-          lat: 51.5074
-          lng: -0.1278
-        radius: 20000
-```
-
-```yaml
-- id: pa_size_small
-  type: PlacesAutocomplete
-  properties:
-    title: Small
-    size: small
-- id: pa_size_middle
-  type: PlacesAutocomplete
-  properties:
-    title: Middle
-    size: middle
-- id: pa_size_large
-  type: PlacesAutocomplete
-  properties:
-    title: Large
-    size: large
-```
-
-```yaml
-- id: pa_variant_filled
-  type: PlacesAutocomplete
-  properties:
-    title: Filled
-    variant: filled
-- id: pa_variant_borderless
-  type: PlacesAutocomplete
-  properties:
-    title: Borderless
-    variant: borderless
-- id: pa_variant_underlined
-  type: PlacesAutocomplete
-  properties:
-    title: Underlined
-    variant: underlined
-```
-
-```yaml
-- id: pa_disabled
-  type: PlacesAutocomplete
-  properties:
-    title: Disabled
-    disabled: true
-- id: pa_no_clear
-  type: PlacesAutocomplete
-  properties:
-    title: Clear button hidden
-    allowClear: false
-```
-
-```yaml
-- id: pa_custom_icon
-  type: PlacesAutocomplete
-  properties:
-    title: Address
-    optionsIcon:
-      name: home
-      color: "#1890ff"
-    loadingPlaceholder: Searching addresses...
-    notFoundContent: No matching address
-```
-
-```yaml
-- id: pa_required
-  type: PlacesAutocomplete
-  required: true
-  properties:
-    title: Address
-  validate:
-    - message: An address must be selected.
-      status: error
-      pass:
-        _if_none:
-          - _state: pa_required.formattedAddress
-          - false
-```
-
-```yaml
-- id: pa_events
-  type: PlacesAutocomplete
-  properties:
-    title: Address
-    fetchFields:
-      - location
-  events:
-    onPlaceChanged:
-      - id: pa_place_changed_message
-        type: DisplayMessage
-        params:
-          content:
-            _string.concat:
-              - "Selected: "
-              - _event: place.formattedAddress
-          duration: 2
-    onError:
-      - id: pa_error_message
-        type: DisplayMessage
-        params:
-          status: error
-          content:
-            _event: message
-    onSearch:
-      - id: pa_search_state
-        type: SetState
-        params:
-          pa_last_search:
-            _event: value
-    onClear:
-      - id: pa_clear_state
-        type: SetState
-        params:
-          pa_last_search: null
-```
-
-Delivery details
-
-```yaml
-- id: pa_form_title
-  type: Title
-  properties:
-    content: Delivery details
-    level: 4
-- id: pa_form_address
-  type: PlacesAutocomplete
-  properties:
-    title: Street address
-    placeholder: Search for a delivery address
-    fetchFields:
-      - addressComponents
-      - location
-    label:
-      extra: Pick a suggestion to capture the coordinates for the driver.
-- id: pa_form_instructions
-  type: TextArea
-  properties:
-    title: Delivery instructions
-    placeholder: Gate code, buzzer, where to leave the parcel
-- id: pa_form_submit
-  type: Button
-  properties:
-    title: Save address
-    icon: save
-```
-
-| Property | Type | Default | Description |
-| --- | --- | --- | --- |
-| `allowClear` | boolean | `true` | Allow the user to clear the input. Clearing removes the place keys from the block value, and sets the value to null when no sibling keys remain. |
-| `autoFocus` | boolean | `false` | Autofocus to the block on page load. |
-| `backfill` | boolean | `false` | Backfill the highlighted suggestion into the input when using the keyboard. |
-| `bordered` | boolean | `true` | Whether or not the input has a border style. Deprecated, use variant instead. |
-| `debounce` | number | `250` | Milliseconds to wait after the last keystroke before requesting suggestions from the Places API. |
-| `defaultOpen` | boolean | `false` | Initial open state of the suggestions dropdown. |
-| `disabled` | boolean | `false` | Disable the block if true. |
-| `fetchFields` | array | - | Place fields to fetch when a suggestion is selected, in camelCase, for example `addressComponents`, `location` or `viewport`. `formattedAddress` is always fetched. See [Place fields](https://developers.google.com/maps/documentation/javascript/reference/place#Place). |
-| `label` | object | - | Label properties. |
-| `label.align` | string | `"left"` | Align label left or right when inline. Enum: `left`, `right`. |
-| `label.colon` | boolean | `true` | Append label with colon. |
-| `label.disabled` | boolean | `false` | Hide input label. |
-| `label.extra` | string | - | Extra text to display beneath the content - supports html. |
-| `label.hasFeedback` | boolean | `true` | Display feedback extra from validation, this does not disable validation. |
-| `label.inline` | boolean | `false` | Render input and label inline. |
-| `label.span` | number | - | Label inline span. |
-| `label.title` | string | - | Label title - supports html. |
-| `label.tooltip` | string \| object | - | Help tooltip shown via an icon beside the label. A string sets the tooltip text (supports html), or an object to also customize the icon and color. Use the block's onTooltipClick event to respond to clicks on the icon. |
-| `label.tooltip.title` | string | - | Tooltip text shown on hover - supports html. |
-| `label.tooltip.icon` | string | `"help"` | Icon name to show beside the label: a semantic name like `help`, a Lucide icon name like `CircleQuestionMark`, or a set-qualified name like `tabler:HelpCircle`. |
-| `label.tooltip.color` | string | - | Color of the tooltip icon. |
-| `labelField` | string | `"formattedAddress"` | The key in the block value, after `resultMapping` is applied, that is displayed in the input and written when the user types free text. Typing removes the keys the previous place wrote (the mapped `input`, `id`, `formattedAddress` and `fetchFields` keys), so typed text never carries another place's fields. |
-| `loadingPlaceholder` | string | `"Loading..."` | Text displayed in the dropdown while suggestions are being fetched. |
-| `notFoundContent` | string | `"No results found"` | Text displayed in the dropdown when the search returns no suggestions. |
-| `optionsIcon` | string \| object | `"location"` | Icon displayed before each suggestion in the dropdown: a semantic name like `location`, a Lucide icon name like `MapPin`, or a set-qualified name like `tabler:MapPin`, or properties of an Icon block. |
-| `placeholder` | string | `"Start typing to search"` | Placeholder text inside the block before the user types input. |
-| `requestOptions` | object | - | Additional options passed to the autocomplete request. See [AutocompleteRequest](https://developers.google.com/maps/documentation/javascript/reference/autocomplete-data#AutocompleteRequest). |
-| `requestOptions.includedPrimaryTypes` | array | - | Restrict suggestions to these place types, for example `street_address` or `locality`. |
-| `requestOptions.includedRegionCodes` | array | - | Restrict suggestions to these regions, as up to 15 CLDR two character region codes, for example `["us", "gb"]`. |
-| `requestOptions.language` | string | - | The language in which to return the suggestions. |
-| `requestOptions.locationBias` | object | - | Bias suggestions towards an area, as a circle or a rectangle. Cannot be used with locationRestriction. |
-| `requestOptions.locationRestriction` | object | - | Restrict suggestions to an area, as a circle or a rectangle. Cannot be used with locationBias. |
-| `requestOptions.origin` | object | - | The origin from which the distance to a suggestion is calculated, as a lat and lng object. |
-| `requestOptions.origin.lat` | number | - | Lateral coordinate. |
-| `requestOptions.origin.lng` | number | - | Longitudinal coordinate. |
-| `requestOptions.region` | string | - | The region code used to format the suggestions. |
-| `resultMapping` | object | - | Rename the fetched place fields before they are written to the block value. Dotted target paths are nested, for example `{ formattedAddress: address.line1, location: geometry.location }`. |
-| `size` | string | `"middle"` | Size of the block. Enum: `small`, `middle`, `large`. |
-| `theme` | object | - | Antd design token overrides for this block. See [antd design tokens](https://ant.design/components/overview#design-token). See [Ant Design select tokens](https://ant.design/components/select#design-token). |
-| `theme.borderRadius` | number | `6` | Border radius of the input. |
-| `theme.borderRadiusLG` | number | `8` | Border radius for large size. |
-| `theme.borderRadiusSM` | number | `4` | Border radius for small size. |
-| `theme.controlHeight` | number | `32` | Height of the input. |
-| `theme.controlHeightLG` | number | `40` | Height for large size. |
-| `theme.controlHeightSM` | number | `24` | Height for small size. |
-| `theme.fontSize` | number | `14` | Font size of the input text. |
-| `theme.fontSizeLG` | number | `16` | Font size for large size. |
-| `theme.fontSizeSM` | number | `14` | Font size for small size. |
-| `theme.colorPrimary` | string | - | Primary color, used for focus border and active state. |
-| `theme.colorPrimaryHover` | string | - | Primary hover color, used for hover border state. |
-| `theme.colorBgContainer` | string | `"#ffffff"` | Background color of the selector. |
-| `theme.colorBgElevated` | string | `"#ffffff"` | Background color of the dropdown. |
-| `theme.colorText` | string | - | Text color of the input. |
-| `theme.colorTextPlaceholder` | string | - | Placeholder text color. |
-| `theme.colorTextDisabled` | string | - | Text color when disabled. |
-| `theme.colorBorder` | string | - | Border color of the input. |
-| `theme.hoverBorderColor` | string | - | Border color when hovered. |
-| `theme.activeBorderColor` | string | - | Border color when focused/active. |
-| `theme.activeOutlineColor` | string | - | Outline color when focused. |
-| `theme.clearBg` | string | `"#ffffff"` | Background color of the clear button. |
-| `theme.optionSelectedBg` | string | `"#e6f4ff"` | Background color of the selected option. |
-| `theme.optionSelectedColor` | string | `"rgba(0, 0, 0, 0.88)"` | Text color of the selected option. |
-| `theme.optionSelectedFontWeight` | number | `600` | Font weight of the selected option. |
-| `theme.optionActiveBg` | string | `"rgba(0, 0, 0, 0.04)"` | Background color of the active (hovered) option. |
-| `theme.optionFontSize` | number | `14` | Font size of dropdown option text. |
-| `theme.optionHeight` | number | `32` | Height of each dropdown option. |
-| `theme.optionLineHeight` | number | - | Line height of dropdown option text. |
-| `theme.optionPadding` | string \| number | `"5px 12px"` | Padding of each dropdown option. |
-| `theme.selectorBg` | string | `"#ffffff"` | Background color of the selector input. |
-| `theme.zIndexPopup` | number | `1050` | Z-index of the dropdown popup. |
-| `theme.showArrowPaddingInlineEnd` | number | `18` | Right padding when the arrow icon is shown. |
-| `theme.lineWidth` | number | `1` | Border width of the input. |
-| `theme.paddingInline` | number | `11` | Horizontal padding of the input. |
-| `title` | string | - | Title to describe the input component, if no title is specified the block id is displayed - supports html. |
-| `variant` | string | `"outlined"` | Input visual variant. When set, takes precedence over bordered. Enum: `outlined`, `filled`, `borderless`, `underlined`. |
-
-| Event | Event Data | Description |
-| --- | --- | --- |
-| `onBlur` | \- | Trigger actions when the input loses focus. |
-| `onChange` | `{ value }` | Trigger actions after the block value changes, by typing, by selecting a suggestion or by clearing the input. |
-| `onClear` | \- | Trigger actions when the input is cleared. |
-| `onError` | `{ message }` | Trigger actions when fetching suggestions or place fields fails, for example when the Places API is not enabled on the API key. When fetching place fields fails, the typed text stays in the block value and onPlaceChanged is not triggered. |
-| `onFocus` | \- | Trigger actions when the input gains focus. |
-| `onPlaceChanged` | `{ place, value }` | Trigger actions after a suggestion is selected and its place fields have been fetched and written to the block value. |
-| `onSearch` | `{ value }` | Trigger actions when the search text changes. |
-| `onTooltipClick` | \- | Trigger actions when the tooltip icon is clicked. |
-
-| Key | Target |
-| --- | --- |
-| `/block` | Outer block wrapper (always available). |
-| `/element` | The PlacesAutocomplete input element. |
-| `/selector` | The inner value container of the input (antd `content` semantic slot). |
-| `/label` | The PlacesAutocomplete label. |
-| `/extra` | The PlacesAutocomplete extra content. |
-| `/feedback` | The PlacesAutocomplete validation feedback. |
-| `/options` | Each suggestion in the dropdown. |
-| `/popup` | The suggestions dropdown. |
-
-No slots defined.