@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/list-blocks/listselector.md

@@ -0,0 +1,301 @@
+# ListSelector
+
+Data-driven vertical list of headerless cards that doubles as a single-select input. Each card body is rendered from a Nunjucks template against its row item. Clicking a card sets the block value to that data item and highlights it; set `selectable: false` to turn selection off and render a read-only card list. Virtualized via `react-virtuoso` so thousands of variable-height cards render smoothly, with a memoized row component to skip unnecessary re-renders. Optional client-side search bar filters rows by text across any field paths, a built-in loading skeleton stands in while data loads, and `onChange` / `onClick` events report `{ value, index, item }` for the row that was clicked.
+
+```yaml
+- id: basic_card_list
+  type: ListSelector
+  properties:
+    data:
+      - Alpha
+      - Beta
+      - Gamma
+    html: |
+      <h3>{{ index + 1 }}. {{ item }}</h3>
+```
+
+```yaml
+- id: select_list
+  type: ListSelector
+  properties:
+    hoverable: true
+    data:
+      - id: 1
+        name: Starter
+        price: $0
+      - id: 2
+        name: Pro
+        price: $20
+      - id: 3
+        name: Enterprise
+        price: $99
+    html: |
+      <strong>{{ item.name }}</strong>
+      <div style="color:#666;">{{ item.price }} / month</div>
+  events:
+    onChange:
+      - id: capture_selected
+        type: SetState
+        params:
+          selected_plan:
+            _event: value
+- id: selected_plan_display
+  type: Paragraph
+  properties:
+    content:
+      _nunjucks:
+        template: "Selected: {{ selected_plan.name }}"
+        on:
+          _state: true
+```
+
+```yaml
+- id: readonly_list
+  type: ListSelector
+  properties:
+    selectable: false
+    data:
+      - One
+      - Two
+      - Three
+    html: |
+      <span>{{ item }}</span>
+```
+
+```yaml
+- id: empty_list
+  type: ListSelector
+  properties:
+    data: []
+    noData: No people to show yet.
+    html: |
+      <span>{{ item.name }}</span>
+```
+
+```yaml
+- id: people_card_list
+  type: ListSelector
+  properties:
+    hoverable: true
+    bordered: false
+    data:
+      - name: Ada Lovelace
+        email: ada@example.com
+        role: Mathematician
+      - name: Linus Torvalds
+        email: linus@example.com
+        role: Engineer
+      - name: Grace Hopper
+        email: grace@example.com
+        role: Computer Scientist
+    html: |
+      <div style="display:flex; flex-direction:column; gap:4px;">
+        <strong>{{ item.name }}</strong>
+        <span style="color:#666;">{{ item.role }}</span>
+        <a href="mailto:{{ item.email }}">{{ item.email }}</a>
+      </div>
+```
+
+```yaml
+- id: click_card_list
+  type: ListSelector
+  properties:
+    hoverable: true
+    data:
+      - id: 1
+        label: First
+      - id: 2
+        label: Second
+      - id: 3
+        label: Third
+    html: |
+      <h4>{{ item.label }}</h4>
+      <p>Click to see which row was selected.</p>
+  events:
+    onClick:
+      - id: capture_clicked
+        type: SetState
+        params:
+          clicked_card:
+            _event: true
+```
+
+```yaml
+- id: compact_card_list
+  type: ListSelector
+  properties:
+    size: small
+    gap: 4
+    data:
+      - One
+      - Two
+      - Three
+      - Four
+    html: |
+      <span>{{ item }}</span>
+```
+
+```yaml
+- id: large_card_list
+  type: ListSelector
+  properties:
+    hoverable: true
+    height: 480
+    data:
+      _string.split:
+        on:
+          _string.repeat:
+            on: x,
+            count: 999
+        separator: ","
+    html: >
+      <h4>Row {{ index + 1 }}</h4>
+
+      <p>This list renders one thousand cards. Only rows in (and near) the
+      viewport are mounted in the DOM.</p>
+```
+
+```yaml
+- id: search_all_card_list
+  type: ListSelector
+  properties:
+    hoverable: true
+    height: 360
+    search: {}
+    data:
+      - name: Ada Lovelace
+        email: ada@example.com
+        role: Mathematician
+      - name: Linus Torvalds
+        email: linus@example.com
+        role: Engineer
+      - name: Grace Hopper
+        email: grace@example.com
+        role: Computer Scientist
+      - name: Alan Turing
+        email: alan@example.com
+        role: Mathematician
+      - name: Margaret Hamilton
+        email: margaret@example.com
+        role: Software Engineer
+    html: >
+      <strong>{{ item.name }}</strong>
+
+      <div style="color:#666;">{{ item.role }} · <a href="mailto:{{ item.email
+      }}">{{ item.email }}</a></div>
+```
+
+```yaml
+- id: search_fields_card_list
+  type: ListSelector
+  properties:
+    hoverable: true
+    height: 360
+    search:
+      placeholder: Filter by name…
+      fields:
+        - name
+      minLength: 1
+    data:
+      - name: Ada Lovelace
+        email: ada@example.com
+        role: Mathematician
+      - name: Linus Torvalds
+        email: linus@example.com
+        role: Engineer
+      - name: Grace Hopper
+        email: grace@example.com
+        role: Computer Scientist
+    html: |
+      <strong>{{ item.name }}</strong>
+      <div style="color:#666;">{{ item.role }}</div>
+```
+
+```yaml
+- id: keyed_list
+  type: ListSelector
+  properties:
+    valueKey: id
+    primaryKey: id
+    data:
+      - id: 1
+        name: Starter
+        price: $0
+      - id: 2
+        name: Pro
+        price: $20
+      - id: 3
+        name: Enterprise
+        price: $99
+    html: |
+      <strong>{{ item.name }}</strong>
+      <div style="color:#888;">{{ item.price }} / month</div>
+  events:
+    onChange:
+      - id: capture_keyed
+        type: SetState
+        params:
+          keyed_plan_id:
+            _event: value
+- id: keyed_plan_display
+  type: Paragraph
+  properties:
+    content:
+      _nunjucks:
+        template: 'Selected plan id: {{ keyed_plan_id if keyed_plan_id != null else "—"
+          }}'
+        on:
+          _state: true
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | array | `[]` | Array of items. Each item is rendered as one card by passing it to the html Nunjucks template as `item`. |
+| `html` | string | - | Nunjucks template used to render the body of each card. The context exposes `item` (the current data row) and `index` (the zero-based row index). |
+| `selectable` | boolean | `true` | Enable selecting a card. When true, clicking a card sets the block value to that data item and highlights it. When false, the block is a read-only card list that stores no value. |
+| `allowDeselect` | boolean | `true` | Allow clicking the selected card again to clear the selection (sets the value to null). Ignored when `selectable` is false. |
+| `valueKey` | string | - | Field of each data item stored as the block value when a card is selected (e.g. "id"). Omit to store the whole item. Lets the selection be driven with SetState using a simple key. Supports dotted paths. |
+| `primaryKey` | string | - | Field used to match the current value (e.g. set with SetState) back to a card for highlighting. Defaults to `valueKey`. Set this when the stored value is the whole item but a single field (e.g. "id") uniquely identifies it. Supports dotted paths. |
+| `bordered` | boolean | `true` | Toggles the border around each card. |
+| `hoverable` | boolean | `false` | Lift each card up when hovered. |
+| `size` | string | `"default"` | Card size. Enum: `default`, `small`. |
+| `gap` | number | `8` | Pixel gap between cards. |
+| `height` | number \| string | - | Optional pixel height (number) or CSS height string of the scroll container. When omitted, the list scrolls with the page. |
+| `overscan` | number | `400` | Pixels of off-screen rows to render above and below the viewport. Increase for smoother fast-scroll, decrease to reduce DOM cost. |
+| `noData` | string | - | Text shown in place of the list when the `data` array is empty. Defaults to the `blocks.listSelector.noData` message ("No data"). |
+| `search` | object | - | Optional client-side search bar above the list. When this property is set, a debounced search input filters rows by text. Omit to hide the bar. |
+| `search.placeholder` | string | `"Search…"` | Placeholder text in the input. |
+| `search.fields` | array | - | Dotted field paths to match against (e.g. "user.name"). When omitted, every field path is searched (whole-item stringify). |
+| `search.caseSensitive` | boolean | `false` | Match case exactly. |
+| `search.debounce` | number | `150` | Milliseconds to wait after the last keystroke before filtering. |
+| `search.sticky` | boolean | `true` | Stick the search bar to the top while scrolling. |
+| `search.allowClear` | boolean | `true` | Show a clear (×) icon in the input. |
+| `search.minLength` | number | `0` | Skip filtering until the query is at least this many characters. |
+| `search.noResultsText` | string | `"No results"` | Text shown when the filter matches zero items. |
+| `theme` | object | - | Antd design token overrides for the cards. See [antd design tokens](https://ant.design/components/overview#design-token). See [Ant Design card tokens](https://ant.design/components/card#design-token). |
+| `theme.bodyPadding` | number | `24` | Padding of each card body. |
+| `theme.bodyPaddingSM` | number | `12` | Padding of each card body for small cards. |
+| `theme.borderRadiusLG` | number | `8` | Border radius of each card. |
+| `theme.colorBorderSecondary` | string | - | Border color of each card. |
+| `theme.colorBgContainer` | string | - | Background color of each card body. |
+| `theme.colorText` | string | - | Text color inside each card. |
+| `theme.boxShadowTertiary` | string | - | Shadow applied to each card on hover when hoverable is true. |
+
+| Event | Event Data | Description |
+| --- | --- | --- |
+| `onChange` | `{ value, index, item }` | Triggered when the selection changes (only fires when `selectable` is true). |
+| `onClick` | `{ index, item }` | Triggered when a card is clicked. |
+| `onSearch` | `{ value, resultCount }` | Triggered when the debounced search query changes (only fires when the `search` property is set). |
+
+| Key | Target |
+| --- | --- |
+| `/block` | Outer block wrapper (always available). |
+| `/element` | The list container. |
+| `/card` | Each Card element. |
+| `/body` | Each Card body. |
+| `/selected` | The selected card. |
+| `/search` | The search bar wrapper above the list. |
+| `/noResults` | The "no results" placeholder shown when the search filter matches zero items. |
+| `/noData` | The "no data" placeholder shown when the data array is empty. |
+
+No slots defined.

package/content/list-blocks/masonrylist.md

@@ -0,0 +1,230 @@
+# MasonryList
+
+Masonry-style grid layout for list data. Items flow into columns and stack vertically, filling gaps left by shorter items. Provide an array in state and use _state operators in the template to access each item's data.
+
+```yaml
+- id: ml_basic
+  type: MasonryList
+  properties:
+    columns: 3
+    gutter: 16
+  blocks:
+    - id: ml_basic.$.card
+      type: Card
+      class:
+        _state: ml_basic.$.bg
+      properties:
+        size: small
+      blocks:
+        - id: ml_basic.$.title_block
+          type: Title
+          properties:
+            content:
+              _state: ml_basic.$.title
+            level: 5
+        - id: ml_basic.$.desc_block
+          type: Paragraph
+          properties:
+            content:
+              _state: ml_basic.$.desc
+```
+
+```yaml
+- id: ml_two
+  type: MasonryList
+  properties:
+    columns: 2
+    gutter: 16
+  blocks:
+    - id: ml_two.$.card
+      type: Card
+      class:
+        _state: ml_two.$.bg
+      properties:
+        size: small
+      blocks:
+        - id: ml_two.$.title_block
+          type: Title
+          properties:
+            content:
+              _state: ml_two.$.title
+            level: 5
+        - id: ml_two.$.body_block
+          type: Paragraph
+          properties:
+            content:
+              _state: ml_two.$.body
+```
+
+```yaml
+- id: ml_gutter_tight
+  type: MasonryList
+  properties:
+    columns: 3
+    gutter: 6
+  blocks:
+    - id: ml_gutter_tight.$.card
+      type: Card
+      class: bg-bg-layout
+      properties:
+        size: small
+      blocks:
+        - id: ml_gutter_tight.$.label_block
+          type: Paragraph
+          properties:
+            content:
+              _state: ml_gutter_tight.$.label
+- id: ml_gutter_wide
+  type: MasonryList
+  properties:
+    columns: 3
+    gutter: 24
+  blocks:
+    - id: ml_gutter_wide.$.card
+      type: Card
+      class: bg-bg-layout
+      properties:
+        size: small
+      blocks:
+        - id: ml_gutter_wide.$.label_block
+          type: Paragraph
+          properties:
+            content:
+              _state: ml_gutter_wide.$.label
+```
+
+```yaml
+- id: ml_notes
+  type: MasonryList
+  properties:
+    columns: 3
+    gutter: 12
+  blocks:
+    - id: ml_notes.$.card
+      type: Card
+      class:
+        _state: ml_notes.$.bg
+      properties:
+        size: small
+      blocks:
+        - id: ml_notes.$.row
+          type: Box
+          layout:
+            justify: space-between
+            align: center
+          blocks:
+            - id: ml_notes.$.title_block
+              type: Title
+              layout:
+                flex: 1 1 0
+              properties:
+                content:
+                  _state: ml_notes.$.title
+                level: 5
+            - id: ml_notes.$.tag_block
+              type: Tag
+              layout:
+                flex: 0 0 auto
+              properties:
+                title:
+                  _state: ml_notes.$.tag
+                color:
+                  _state: ml_notes.$.color
+        - id: ml_notes.$.body_block
+          type: Paragraph
+          properties:
+            content:
+              _state: ml_notes.$.body
+```
+
+```yaml
+- id: ml_team
+  type: MasonryList
+  properties:
+    columns: 4
+    gutter: 12
+  blocks:
+    - id: ml_team.$.card
+      type: Card
+      properties:
+        size: small
+      blocks:
+        - id: ml_team.$.header
+          type: Box
+          layout:
+            gap: 8
+            align: center
+          blocks:
+            - id: ml_team.$.avatar
+              type: Avatar
+              layout:
+                flex: 0 0 auto
+              properties:
+                content:
+                  _state: ml_team.$.initials
+                backgroundColor:
+                  _state: ml_team.$.bg
+            - id: ml_team.$.name_block
+              type: Title
+              layout:
+                flex: 1 1 0
+              properties:
+                content:
+                  _state: ml_team.$.name
+                level: 5
+        - id: ml_team.$.role_block
+          type: Paragraph
+          properties:
+            content:
+              _state: ml_team.$.role
+```
+
+```yaml
+- id: ml_seq
+  type: MasonryList
+  properties:
+    columns: 3
+    gutter: 16
+    sequential: true
+  blocks:
+    - id: ml_seq.$.card
+      type: Card
+      class:
+        _state: ml_seq.$.bg
+      properties:
+        size: small
+      blocks:
+        - id: ml_seq.$.title_block
+          type: Title
+          properties:
+            content:
+              _state: ml_seq.$.title
+            level: 5
+        - id: ml_seq.$.desc_block
+          type: Paragraph
+          properties:
+            content:
+              _state: ml_seq.$.desc
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `columns` | integer \| object | - | Number of columns, or responsive breakpoint object (e.g. { xs: 1, sm: 2, md: 3 }). |
+| `fresh` | boolean | `false` | Force refresh the masonry layout. |
+| `gutter` | number \| array | - | Gap between items in pixels. Number or [horizontal, vertical] array. |
+| `sequential` | boolean | `false` | Render items sequentially (top to bottom, then next column). Default is balanced column-fill. |
+| `theme` | object | - | Antd design token overrides for this block. Masonry uses global motion tokens for item animations. See [antd design tokens](https://ant.design/components/overview#design-token). See [Ant Design masonry tokens](https://ant.design/components/masonry). |
+| `theme.motionDurationSlow` | string | `"0.3s"` | Duration of item position and fade-in animations. |
+| `theme.motionDurationFast` | string | `"0.1s"` | Duration of item fade-out animations. |
+| `theme.motionEaseOut` | string | `"cubic-bezier(0.215, 0.61, 0.355, 1)"` | Easing function for item animations. |
+
+No events defined.
+
+| Key | Target |
+| --- | --- |
+| `/block` | Outer block wrapper (always available). |
+| `/element` | The MasonryList element. |
+
+| Slot | Description |
+| --- | --- |
+| `content` | Blocks rendered for each masonry item. |

package/content/migration/upgrade-guide.md

@@ -0,0 +1,106 @@
+# Upgrade Guide
+
+This guide explains how the Lowdefy upgrade system works — independent of any specific version.
+
+For version-specific migration details, see:
+- [Version 5 to Version 6](/v5-to-v6)
+- [Version 4 to Version 5](/v4-to-v5)
+- [Version 3 to Version 4](/v3-to-v4)
+
+## Quick start
+
+```bash
+npx lowdefy upgrade
+```
+
+That's it. The command reads your current version from `lowdefy.yaml`, fetches the latest codemods, resolves the upgrade chain, and walks you through each step.
+
+## How Lowdefy versioning works
+
+Lowdefy follows [semantic versioning](https://semver.org/). Major versions (4.0 → 5.0) contain breaking changes. Minor and patch versions are backwards-compatible.
+
+When breaking changes ship, the `@lowdefy/codemods` package is updated with migration prompts for the new version. The `lowdefy upgrade` command uses this package to guide the migration.
+
+## The `lowdefy upgrade` command
+
+The upgrade command:
+
+1. Reads your current version from `lowdefy.yaml`.
+2. Queries npm for the latest stable Lowdefy version (or uses `--to`).
+3. Fetches `@lowdefy/codemods@latest` — a single package containing all migration prompts for all versions.
+4. Resolves the upgrade chain — which intermediate versions need codemods.
+5. Presents migration prompts phase by phase.
+6. Updates `lowdefy.yaml` after each phase and suggests a git commit.
+
+### Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--to <version>` | Target version to upgrade to | Latest stable |
+| `--plan` | Show the upgrade plan without executing | |
+| `--resume` | Resume a previously interrupted upgrade | |
+| `--config-directory` | Change config directory | `.` |
+| `--log-level` | Log level (debug, info, warn, error) | `info` |
+
+See the [CLI reference](/cli) for the full command documentation.
+
+## Multi-version upgrades
+
+The upgrade command handles jumps across multiple versions. If you're on 4.5.0 and the latest is 6.0.0, the command resolves the full chain:
+
+```
+4.5.0 → 5.0.0 → 6.0.0
+```
+
+Each step in the chain is a **phase**. The command walks you through all prompts for phase 1, updates `lowdefy.yaml`, suggests a commit, then moves to phase 2. This gives you clean git history per version jump.
+
+The version chain is computed from `registry.json` in the `@lowdefy/codemods` package. Each entry specifies a target version and a `from` semver range. The resolver walks the entries in order until the current version reaches the target.
+
+## How prompts work
+
+Every codemod is a self-contained markdown prompt. For each codemod, the CLI presents three options:
+
+1. **Copy prompt to clipboard** — paste into Claude Code, ChatGPT, Cursor, or any AI coding tool.
+2. **View migration guide** — read the step-by-step instructions and apply changes manually.
+3. **Skip for now** — mark as pending. Return later with `--resume`.
+
+Each prompt includes:
+
+- What changed and why
+- Before/after YAML examples
+- How to find affected files (glob patterns, grep patterns)
+- Edge cases to watch for
+- Verification steps
+
+This format works with any AI coding tool. Copy the prompt, paste it into your tool of choice, and let it scan your project and apply changes. Prompts can also be followed manually without any AI tool.
+
+## Resuming interrupted upgrades
+
+If you stop mid-upgrade (skip a codemod, close the terminal, or hit an error), run:
+
+```bash
+npx lowdefy upgrade --resume
+```
+
+The command reads `.lowdefy/upgrade-state.json` — a file that tracks which phases and codemods have completed — and picks up where you left off.
+
+If you skip codemods, the build warns about pending migrations:
+
+```
+⚠ Warning: 2 codemod(s) were skipped during upgrade.
+  Run "npx lowdefy upgrade --resume" to complete them.
+  Or add --skip-codemod-check to suppress this warning.
+```
+
+Suppress this with `--skip-codemod-check` or `cli.skipCodemodCheck: true` in `lowdefy.yaml`.
+
+## Manual upgrades
+
+If you prefer to upgrade without the command:
+
+1. Read the version-specific migration guide (e.g. [V5 to V6](/v5-to-v6)).
+2. Apply each breaking change manually using the before/after examples.
+3. Update the `lowdefy:` version in `lowdefy.yaml`.
+4. Run `lowdefy dev` and fix any remaining issues.
+
+The upgrade command automates this process, but every change is documented in the migration guides for manual reference.