@lowdefy/codemods 0.0.0-experimental-20260318092212

package/v5-0-0/12-migrate-meta-styles.md

@@ -0,0 +1,149 @@
+# Migration: `meta.styles` → Direct CSS Imports (Custom Block Plugins)
+
+## Context
+
+The `meta.styles` pipeline is removed in Lowdefy v4.8. Custom block plugins that used `meta.styles = ['style.less']` to register stylesheets must switch to direct `import './style.css'` statements in the block component file.
+
+This migration targets local plugin source code (JS/TS), not YAML configs.
+
+## Scope
+
+`plugins` — scan JS/TS files in local plugin directories.
+
+## What to Do
+
+For each custom block plugin:
+
+### 1. Remove `meta.styles` from block component files
+
+Find lines like:
+
+```javascript
+BlockName.meta = {
+  category: 'display',
+  styles: ['style.less'],
+};
+```
+
+Remove the `styles` entry:
+
+```javascript
+BlockName.meta = {
+  category: 'display',
+};
+```
+
+### 2. Remove styles aggregation from `types.js`
+
+Find patterns like:
+
+```javascript
+const styles = {};
+styles.BlockName = Block.meta.styles;
+export { styles };
+```
+
+Remove the `styles` variable, the loop/assignments, and the `styles` export.
+
+### 3. Handle `.less` files
+
+For each `.less` file referenced by `meta.styles`:
+
+**Dead imports (remove):** If the `.less` file only imports antd's Less (`@import '~antd/dist/antd.less'` or similar) with no other CSS, delete it.
+
+**Convertible (rename to .css):** If the `.less` file contains plain CSS without Less-specific syntax:
+
+1. Remove any antd `@import` lines
+2. Wrap the remaining CSS in `@layer components { }`
+3. Save as `.css` (same name, different extension)
+4. Delete the old `.less` file
+
+**Complex Less (manual):** If the file uses Less variables (`@var`), functions (`darken()`, `lighten()`), mixins, or nested `&` selectors — convert to plain CSS manually first.
+
+### 4. Add direct CSS import
+
+In the block component file, add:
+
+```javascript
+import './style.css';
+```
+
+## Files to Check
+
+Glob in plugin directories: `**/*.{js,jsx,ts,tsx}`
+Grep: `meta.styles` or `styles:.*\.less`
+
+Also check: `**/types.js` for styles aggregation.
+
+## Examples
+
+### Before — block component
+
+```javascript
+import React from 'react';
+import './MyBlock.less';
+
+const MyBlock = ({ properties }) => {
+  return <div>{properties.title}</div>;
+};
+
+MyBlock.meta = {
+  category: 'display',
+  styles: ['MyBlock.less'],
+};
+
+export default MyBlock;
+```
+
+### After
+
+```javascript
+import React from 'react';
+import './MyBlock.css';
+
+const MyBlock = ({ properties }) => {
+  return <div>{properties.title}</div>;
+};
+
+MyBlock.meta = {
+  category: 'display',
+};
+
+export default MyBlock;
+```
+
+### Before — MyBlock.less
+
+```less
+@import '~antd/dist/antd.less';
+
+.my-block {
+  padding: 16px;
+  border: 1px solid #d9d9d9;
+}
+```
+
+### After — MyBlock.css
+
+```css
+@layer components {
+  .my-block {
+    padding: 16px;
+    border: 1px solid #d9d9d9;
+  }
+}
+```
+
+## Edge Cases
+
+- Some plugins may have `.less` files that import from multiple antd sub-paths — remove all antd imports
+- Check for Less syntax before auto-converting: `@` variables (not `@import` or `@layer`), `darken()`, `lighten()`, `fade()`, `.mixin()`, `& .child` nesting
+- The `import './style.css'` line may already exist if the plugin was partially migrated
+- `meta.styles` may be an empty array — just remove it
+
+## Verification
+
+1. No `.less` files should be imported by block components
+2. No `meta.styles` assignments should remain
+3. No `styles` exports in `types.js`
+4. The plugin should build without Less-related errors

package/v5-0-0/13-rename-xxl-to-2xl.md

@@ -0,0 +1,39 @@
+# Prompt 01: Rename `xxl` to `2xl`
+
+Complexity: **Moderate** (false positive risk — `xxl` may appear as block IDs or custom data)
+
+## Goal
+
+Rename all `xxl` breakpoint references to `2xl` in Lowdefy YAML configs. This covers YAML keys, quoted string values, and bare values.
+
+## Scope
+
+Search all `.yaml` and `.yml` files in the project (excluding `.` directories and `node_modules`).
+
+## What to Find
+
+1. **YAML keys** -- `xxl:` at the start of a line (after optional whitespace). Examples: `  xxl:`, `xxl: { span: 4 }`
+2. **Quoted strings** -- `"xxl"` or `'xxl'` as values (typically `_media` comparisons like `_eq: [_media: size, "xxl"]`)
+3. **Bare values** -- `xxl` as an unquoted value after `- ` or `: ` at end of line
+
+## How to Apply
+
+For each file with matches:
+
+1. Show the user every matching line with its line number and file path.
+2. Ask the user to confirm no matches are false positives (block IDs, custom properties named `xxl`, or string data unrelated to breakpoints).
+3. After confirmation, apply these replacements in each file:
+   - `xxl:` key at start of line (preserving indent) becomes `2xl:`
+   - `"xxl"` becomes `"2xl"`
+   - `'xxl'` becomes `'2xl'`
+   - Bare `xxl` after `- ` or `: ` at end of line becomes `2xl`
+
+## False Positive Checklist
+
+- A YAML key `xxl:` that is a block ID or custom property name (not a breakpoint override)
+- A string value `"xxl"` stored as data (not a `_media` comparison)
+- Any `xxl` inside comments (leave comments alone -- they are documentation)
+
+## Completion
+
+Report the number of files modified and replacements made.

package/v5-0-0/14-rename-gutter-to-gap.md

@@ -0,0 +1,78 @@
+# Migration: Rename `gutter` → `gap`
+
+## Context
+
+The `gutter` property on layout slots is renamed to `gap` in the new Tailwind-compatible grid. The `contentGutter` property (parent layout content gap inheritance) is also renamed — directly to `gap` (the `content*` prefix is dropped, see prompt 03).
+
+## What to Do
+
+Apply these renames in all YAML files:
+
+| Find             | Replace |
+| ---------------- | ------- |
+| `gutter:`        | `gap:`  |
+| `contentGutter:` | `gap:`  |
+
+Order matters: replace `contentGutter:` before `gutter:` to avoid partial matching.
+
+No user confirmation needed — these renames are unambiguous. The `gutter` property name does not exist in any other Lowdefy context.
+
+## Files to Check
+
+Glob: `**/*.{yaml,yml}`
+Grep: `gutter:`
+
+## Examples
+
+### Before
+
+```yaml
+- id: my_row
+  type: Box
+  slots:
+    content:
+      gutter: 16
+      blocks: [...]
+```
+
+### After
+
+```yaml
+- id: my_row
+  type: Box
+  slots:
+    content:
+      gap: 16
+      blocks: [...]
+```
+
+### Before — contentGutter
+
+```yaml
+- id: page_layout
+  type: PageHeaderMenu
+  layout:
+    contentGutter: 24
+```
+
+### After
+
+```yaml
+- id: page_layout
+  type: PageHeaderMenu
+  layout:
+    gap: 24
+```
+
+## Edge Cases
+
+- Do not rename `gutter` inside string values, operator expressions, or code blocks
+- Only rename YAML keys (at the start of a line after whitespace), not values
+
+## Verification
+
+```
+grep -rn 'gutter:' --include='*.yaml' --include='*.yml' .
+```
+
+Should return zero matches.

package/v5-0-0/15-rename-content-prefix.md

@@ -0,0 +1,67 @@
+# Migration: Drop `content*` Prefix from Layout Properties
+
+## Context
+
+Layout properties were previously namespaced with a `content` prefix to distinguish content-area config from block-level config. The new grid system removes this distinction — the prefix is dropped.
+
+Note: `contentGutter` is already handled by prompt 02 (renamed directly to `gap`).
+
+## What to Do
+
+Apply these renames in all YAML files:
+
+| Find                | Replace      |
+| ------------------- | ------------ |
+| `contentAlign:`     | `align:`     |
+| `contentJustify:`   | `justify:`   |
+| `contentDirection:` | `direction:` |
+| `contentWrap:`      | `wrap:`      |
+| `contentOverflow:`  | `overflow:`  |
+
+No user confirmation needed — these renames are unambiguous. The `content*` property names do not exist in any other Lowdefy context.
+
+## Files to Check
+
+Glob: `**/*.{yaml,yml}`
+Grep: `contentAlign:|contentJustify:|contentDirection:|contentWrap:|contentOverflow:`
+
+## Examples
+
+### Before
+
+```yaml
+- id: main_layout
+  type: PageHeaderMenu
+  layout:
+    contentAlign: middle
+    contentJustify: center
+    contentDirection: column
+    contentWrap: nowrap
+    contentOverflow: auto
+```
+
+### After
+
+```yaml
+- id: main_layout
+  type: PageHeaderMenu
+  layout:
+    align: middle
+    justify: center
+    direction: column
+    wrap: nowrap
+    overflow: auto
+```
+
+## Edge Cases
+
+- Do not rename inside string values, operator expressions, or code blocks
+- Only rename YAML keys (at the start of a line after whitespace), not values
+
+## Verification
+
+```
+grep -rn 'contentAlign:\|contentJustify:\|contentDirection:\|contentWrap:\|contentOverflow:' --include='*.yaml' --include='*.yml' .
+```
+
+Should return zero matches.

package/v5-0-0/16-rename-align-to-selfAlign.md

@@ -0,0 +1,44 @@
+# Prompt 04: Rename `layout.align` to `layout.selfAlign`
+
+Complexity: **Moderate** (ambiguous context -- requires structural analysis)
+
+## Goal
+
+Rename `align:` to `selfAlign:` when it appears as a child of a `layout:` block. This property controlled block self-alignment in the parent row; the new grid system renames it to avoid collision with content `align`.
+
+## Prerequisites
+
+Run **after** prompt 03. Prompt 03 renames `contentAlign` to `align`. After that step, any `align:` that was _already_ present under `layout:` (before the content-prefix rename) is a self-alignment property and should become `selfAlign:`.
+
+## Scope
+
+Search all `.yaml` and `.yml` files in the project (excluding `.` directories and `node_modules`).
+
+## What to Find
+
+`align:` as a YAML key that appears indented under a `layout:` parent block. Use indentation tracking:
+
+1. Scan lines. When you encounter `layout:` as a key, record its indent level.
+2. Subsequent lines indented deeper than the `layout:` key are children of that block.
+3. When a non-empty, non-comment line appears at the same or lesser indentation, the `layout:` block has ended.
+4. Within the `layout:` block, any `align:` key (at child indentation) is a candidate.
+
+Skip blank lines and comment lines when tracking block boundaries.
+
+## How to Apply
+
+For each file with matches:
+
+1. Show the user every matching `align:` line with its line number, file path, and surrounding context (2-3 lines above and below).
+2. Explain the ambiguity: after prompt 03, both old self-alignment `align:` and newly-renamed content `align:` (from `contentAlign`) exist. Only the old self-alignment instances should become `selfAlign:`.
+3. Ask the user to confirm each match. Typical heuristic: if `align:` is directly under `layout:` on a block definition (not in a `slots:` or area config section), it is self-alignment.
+4. After confirmation, replace confirmed `align:` lines with `selfAlign:` (preserving indent).
+
+## False Positive Checklist
+
+- `align:` that was just renamed from `contentAlign:` by prompt 03 (content area alignment -- should stay as `align:`)
+- `align:` in area or slot config (not under `layout:` -- should stay as `align:`)
+
+## Completion
+
+Report the number of files modified and replacements made.

package/v5-0-0/17-rename-moment-to-dayjs.md

@@ -0,0 +1,41 @@
+# 01 — Rename `_moment` to `_dayjs`
+
+**Complexity:** Simple
+
+Rename all `_moment` operator keys to `_dayjs` across the Lowdefy app's YAML config files.
+
+## What to Change
+
+The `_moment` operator is replaced by `_dayjs` in Lowdefy v5. Every YAML key that starts with `_moment` followed by `:` or `.` must be renamed to `_dayjs`.
+
+Patterns:
+
+| Before                      | After                      |
+| --------------------------- | -------------------------- |
+| `_moment:`                  | `_dayjs:`                  |
+| `_moment.format:`           | `_dayjs.format:`           |
+| `_moment.humanizeDuration:` | `_dayjs.humanizeDuration:` |
+| `- _moment:`                | `- _dayjs:`                |
+| `- _moment.diff:`           | `- _dayjs.diff:`           |
+
+The rename applies to all `_moment` + method combinations. The method name itself does not change.
+
+## Instructions
+
+1. Find all `.yaml` and `.yml` files in the project (excluding `node_modules/` and hidden directories).
+
+2. In each file, search for `_moment` used as a YAML key — that is, `_moment` followed by either `:` (standalone operator) or `.` (operator with method). It may appear after whitespace, a list dash, or at the start of a line.
+
+3. Replace each `_moment` with `_dayjs`, preserving the rest of the line exactly.
+
+4. Report:
+
+   - Each file modified and the number of replacements in it.
+   - Total files modified and total replacements.
+
+5. If no matches are found, report: "No `_moment` usage found. Nothing to rename."
+
+## Scope
+
+- Only rename YAML keys, not arbitrary string values. The pattern `_moment` inside a quoted string value (e.g., `description: "Uses _moment for dates"`) should **not** be changed.
+- Do not modify files in `node_modules/`, `.git/`, or other hidden directories.

package/v5-0-0/18-report-thresholds-usage.md

@@ -0,0 +1,37 @@
+# 02 — Report `thresholds` Usage
+
+**Complexity:** Moderate
+
+Find `thresholds` parameter usage inside `_moment.humanizeDuration` or `_dayjs.humanizeDuration` blocks and advise on removal.
+
+## Background
+
+In Lowdefy v5, the `thresholds` parameter on `humanizeDuration` is accepted but **ignored**. Dayjs supports only global thresholds (identical to moment's defaults). Per-call custom thresholds have no effect.
+
+## Instructions
+
+1. Find all `.yaml` and `.yml` files in the project (excluding `node_modules/` and hidden directories).
+
+2. In each file, search for `_moment.humanizeDuration` or `_dayjs.humanizeDuration` blocks that contain a `thresholds:` key. The `thresholds:` key appears as an indented child of the `humanizeDuration` operator block.
+
+3. For each match found:
+
+   - Record the file path, line number of the `humanizeDuration` call, and line number of the `thresholds` key.
+   - Read the surrounding context (the humanizeDuration block plus a few lines of the thresholds config).
+
+4. If matches are found, present a **REVIEW NEEDED** report:
+
+   > The following configs use `thresholds` with `humanizeDuration`. In Lowdefy v5 (dayjs), `thresholds` is accepted but ignored. Dayjs uses default thresholds (same as moment defaults).
+
+   For each match, show the file, line number, and the relevant YAML context. Then advise:
+
+   - If the app does not depend on custom threshold behavior (changing when durations switch units, e.g., "show weeks after 7 days"), no action is needed — the defaults match.
+   - If the app does depend on custom thresholds, the `thresholds` property can be removed since it has no effect. The output will use dayjs defaults.
+   - Removing the `thresholds` key is recommended for clarity, since it is now a no-op.
+
+5. If no matches are found, report: "No `thresholds` usage found. No review needed."
+
+## Scope
+
+- This prompt is **report-only**. Do not automatically remove `thresholds` keys. Present findings and let the user decide.
+- Search for `thresholds` only within humanizeDuration operator blocks, not elsewhere in the config.

package/v5-0-0/19-responsive-style-breakpoints.md

@@ -0,0 +1,121 @@
+# Migration: Responsive Style Breakpoints → Tailwind Classes
+
+## Context
+
+Lowdefy v4 supported responsive breakpoint keys inside `style:` blocks (e.g., `sm:`, `md:`, `lg:`). This feature is removed in v4.8 — responsive styling now uses Tailwind utility classes via the new `class` property.
+
+## What to Do
+
+For each block that uses responsive breakpoint keys inside `style:`, convert the responsive styles to equivalent Tailwind utility classes on the `class` property.
+
+### Common Tailwind Mappings
+
+| CSS Property     | Tailwind Prefix | Example                     |
+| ---------------- | --------------- | --------------------------- |
+| `padding`        | `p-`            | `padding: 16` → `p-4`       |
+| `margin`         | `m-`            | `margin: 8` → `m-2`         |
+| `display: none`  | `hidden`        |                             |
+| `display: block` | `block`         |                             |
+| `display: flex`  | `flex`          |                             |
+| `fontSize`       | `text-`         | `fontSize: 24` → `text-2xl` |
+| `width`          | `w-`            | `width: '100%'` → `w-full`  |
+| `gap`            | `gap-`          | `gap: 16` → `gap-4`         |
+
+Tailwind breakpoint prefixes: `sm:`, `md:`, `lg:`, `xl:`, `2xl:`
+
+### Conversion approach
+
+1. Find `style:` blocks with breakpoint keys (`sm:`, `md:`, `lg:`, `xl:`, `xxl:` / `2xl:`)
+2. For each breakpoint, map the CSS properties to Tailwind classes
+3. Add the classes to the block's `class` property (create if it doesn't exist)
+4. Remove the breakpoint keys from `style:`
+5. If `style:` becomes empty after removing breakpoints, remove the `style:` block entirely
+
+## Files to Check
+
+Glob: `**/*.{yaml,yml}`
+Grep: `sm:|md:|lg:|xl:|2xl:|xxl:` (within `style:` blocks on Lowdefy blocks)
+
+**Important:** `layout.sm.span` (antd Col responsive) is NOT affected — only `style.sm.*` breakpoints are removed. Don't touch responsive keys under `layout:`.
+
+## Examples
+
+### Before — responsive padding
+
+```yaml
+- id: container
+  type: Box
+  style:
+    padding: 64
+    sm:
+      padding: 32
+    md:
+      padding: 48
+```
+
+### After
+
+```yaml
+- id: container
+  type: Box
+  class: p-16 sm:p-8 md:p-12
+```
+
+### Before — responsive visibility
+
+```yaml
+- id: sidebar
+  type: Box
+  style:
+    display: none
+    md:
+      display: block
+```
+
+### After
+
+```yaml
+- id: sidebar
+  type: Box
+  class: hidden md:block
+```
+
+### Before — mixed responsive and static styles
+
+```yaml
+- id: card
+  type: Card
+  style:
+    /element:
+      borderRadius: 8
+      fontSize: 24
+      sm:
+        fontSize: 16
+```
+
+### After
+
+```yaml
+- id: card
+  type: Card
+  style:
+    /element:
+      borderRadius: 8
+  class: text-2xl sm:text-base
+```
+
+## Edge Cases
+
+- Not all CSS properties have direct Tailwind equivalents — for complex properties (transforms, animations, specific pixel values), use arbitrary values: `class: "p-[17px] sm:p-[9px]"`
+- If the block already has a `class` property, append the responsive classes to it
+- Pixel-to-Tailwind-unit conversion: Tailwind uses a 4px scale (1 unit = 4px). `padding: 16` → `p-4`, `margin: 8` → `m-2`
+- Some responsive styles may be better left as custom CSS — use judgment for complex layouts
+- This migration requires understanding the visual intent, not just mechanical replacement
+
+## Verification
+
+```
+grep -rn 'sm:\|md:\|lg:\|xl:\|2xl:' --include='*.yaml' --include='*.yml' . | grep -v layout | grep -v node_modules
+```
+
+Remaining matches should only be inside `layout:` blocks (which are not affected) or non-Lowdefy YAML files.