@lowdefy/codemods 6.0.0 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/registry.json +33 -1
- package/v6-0-0/01-migrate-plugin-packages.md +1 -1
- package/v6-0-0/03-request-timeout.md +96 -0
- package/v6-0-0/04-report-type-overrides.md +110 -0
- package/v7-0-0/01-react-icons-to-lucide.md +327 -0
- package/v7-0-0/02-clickable-html-data-events.md +102 -0
- package/v7-0-0/03-nested-event-bubbling.md +190 -0
- package/v7-0-0/react-icons-to-lucide.json +3040 -0
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# Migration: List `ClickableHtml` data events in `dataEvents`
|
|
2
|
+
|
|
3
|
+
## Context
|
|
4
|
+
|
|
5
|
+
From Lowdefy v7, a `ClickableHtml` block only fires the events its `dataEvents` property lists. A
|
|
6
|
+
`data-event` in the block's HTML whose name is not listed does nothing, and a click on it logs a
|
|
7
|
+
console warning. A block with no `dataEvents` fires no events from its HTML.
|
|
8
|
+
|
|
9
|
+
Before v7, any `data-event` in the HTML fired the block event it named. HTML is often built from
|
|
10
|
+
request or user data, and sanitising keeps `data-*` attributes, so markup inside that data could
|
|
11
|
+
fire any event the block declares. Listing the events makes the author say which ones the HTML may
|
|
12
|
+
fire, and lets an event require a confirmation whatever the markup says.
|
|
13
|
+
|
|
14
|
+
```yaml
|
|
15
|
+
# v6
|
|
16
|
+
- id: rows
|
|
17
|
+
type: ClickableHtml
|
|
18
|
+
properties:
|
|
19
|
+
html: '<button data-event="onEdit" data-id="1">Edit</button>'
|
|
20
|
+
events:
|
|
21
|
+
onEdit: [...]
|
|
22
|
+
|
|
23
|
+
# v7
|
|
24
|
+
- id: rows
|
|
25
|
+
type: ClickableHtml
|
|
26
|
+
properties:
|
|
27
|
+
dataEvents:
|
|
28
|
+
- onEdit
|
|
29
|
+
html: '<button data-event="onEdit" data-id="1">Edit</button>'
|
|
30
|
+
events:
|
|
31
|
+
onEdit: [...]
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
An entry is an event name, or `{ name, confirm }`. `confirm: true` asks before every click with the
|
|
35
|
+
element's `data-confirm` message or "Are you sure?"; a string is the message.
|
|
36
|
+
|
|
37
|
+
## What to Do
|
|
38
|
+
|
|
39
|
+
### Step 1: Find every ClickableHtml block
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
grep -rn 'type:\s*ClickableHtml' --include='*.yaml' --include='*.yml' --include='*.njk' --include='*.json' .
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Also check local plugin code and `_js` code that builds block config at runtime.
|
|
46
|
+
|
|
47
|
+
`Dynamic` blocks get their content from an API endpoint at page load. Check those endpoints'
|
|
48
|
+
routines for `ClickableHtml` block config they return, and give it `dataEvents` there too. Config the
|
|
49
|
+
routine reads from a database or another store is out of reach of this codemod: list every such
|
|
50
|
+
endpoint in the report so the author can update the stored config.
|
|
51
|
+
|
|
52
|
+
### Step 2: Add `dataEvents` to each block
|
|
53
|
+
|
|
54
|
+
For each block, skip it when it already sets `properties.dataEvents`. Otherwise work out the
|
|
55
|
+
event names its HTML fires:
|
|
56
|
+
|
|
57
|
+
- **HTML written in config** (a literal string, a `_ref` template, or a `_nunjucks` template in
|
|
58
|
+
config): the names in every `data-event="..."` attribute, including inside
|
|
59
|
+
`data-popover-content`.
|
|
60
|
+
- **HTML built at runtime** (from `_request`, `_state`, `_payload`, an API response or `_js`): the
|
|
61
|
+
names cannot all be read from config, so take the keys of the block's `events`, except
|
|
62
|
+
`onTextSelection`, `onMount` and `onMountAsync`, which the block fires itself. Mark these in the
|
|
63
|
+
report.
|
|
64
|
+
|
|
65
|
+
Add the names to `properties.dataEvents`. When there are none, add nothing.
|
|
66
|
+
|
|
67
|
+
For an event whose actions delete or change data (`CallAPI`, `Request`, `CallMethod` or
|
|
68
|
+
`SetState` that removes records), and whose HTML elements carry `data-confirm`, write the entry as
|
|
69
|
+
`{ name: onDelete, confirm: true }`, so every click on it asks even where the markup leaves out
|
|
70
|
+
`data-confirm`.
|
|
71
|
+
|
|
72
|
+
### Step 3: Check HTML built from data
|
|
73
|
+
|
|
74
|
+
For each block whose `html` is built from `_request`, `_state`, `_payload`, `_user` or an API
|
|
75
|
+
response, check that values from that data are escaped: `_nunjucks` escapes `{{ values }}` unless
|
|
76
|
+
they are marked `safe`, while `_string.concat` and `_js` do not escape. Report every value that is
|
|
77
|
+
inserted unescaped; do not change the templates.
|
|
78
|
+
|
|
79
|
+
### Step 4: Report
|
|
80
|
+
|
|
81
|
+
Produce a report with one entry per block:
|
|
82
|
+
|
|
83
|
+
- File path and line number, and the block `id`.
|
|
84
|
+
- The `dataEvents` added, and whether they came from `data-event` attributes in config or from
|
|
85
|
+
`events` keys (HTML built at runtime).
|
|
86
|
+
- Events given `confirm: true`.
|
|
87
|
+
- Unescaped data found in Step 3.
|
|
88
|
+
- Endpoints behind `Dynamic` blocks that return `ClickableHtml` config from a database or another
|
|
89
|
+
store, which the author must update.
|
|
90
|
+
|
|
91
|
+
Share the report with the app author, who should remove any listed event the HTML is not meant to
|
|
92
|
+
fire.
|
|
93
|
+
|
|
94
|
+
## Scope
|
|
95
|
+
|
|
96
|
+
`app`: all YAML and Nunjucks config, including shared components, modules and templates reached
|
|
97
|
+
through `_ref`.
|
|
98
|
+
|
|
99
|
+
## Files to Check
|
|
100
|
+
|
|
101
|
+
Glob: `**/*.{yaml,yml,njk,json}`
|
|
102
|
+
Grep: `type:\s*ClickableHtml`
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
# Migration: Keep nested events that depend on each other
|
|
2
|
+
|
|
3
|
+
## Context
|
|
4
|
+
|
|
5
|
+
From Lowdefy v7, a browser event runs only the innermost block event that handles it. When a
|
|
6
|
+
block with actions for an event fires, the blocks around it skip that same browser event:
|
|
7
|
+
|
|
8
|
+
- A `Button` with `onClick` inside a clickable `Card` or `Box` runs only the button's `onClick`.
|
|
9
|
+
- A clickable block inside a `List` row does not also run the row block's `onClick`.
|
|
10
|
+
- A `Switch`, `CheckboxSwitch` or other input inside a clickable block runs its own `onChange`, not
|
|
11
|
+
the outer `onClick`.
|
|
12
|
+
- In an `AgGrid` block, clicking a cell button, link, menu, input or selection checkbox runs only
|
|
13
|
+
that control's event, not `onRowClick` or `onCellClick`.
|
|
14
|
+
|
|
15
|
+
Before v7, all of these events ran, and the outer event ran after the inner one. Almost always that
|
|
16
|
+
was a bug the app worked around, like a delete button that also opened the card it sits in. The
|
|
17
|
+
new behaviour fixes those cases without changes, so **this codemod leaves most nested events
|
|
18
|
+
alone**. It only changes the few places where the app clearly depended on both events running.
|
|
19
|
+
|
|
20
|
+
`bubble: true` on the inner event restores the v6 behaviour for that event:
|
|
21
|
+
|
|
22
|
+
```yaml
|
|
23
|
+
events:
|
|
24
|
+
onClick:
|
|
25
|
+
bubble: true
|
|
26
|
+
try:
|
|
27
|
+
- id: set_filter
|
|
28
|
+
type: SetState
|
|
29
|
+
params:
|
|
30
|
+
filter: open
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## What to Do
|
|
34
|
+
|
|
35
|
+
### Step 1: Find nested event pairs
|
|
36
|
+
|
|
37
|
+
List every **pair** of an inner block and an ancestor block where one browser event used to run
|
|
38
|
+
both:
|
|
39
|
+
|
|
40
|
+
- The ancestor has `onClick`, and a descendant has `onClick`, `onChange` (inputs toggled by a
|
|
41
|
+
click: `Switch`, `CheckboxSwitch`, `Checkbox`-type inputs, `Selector`, `ButtonSelector`,
|
|
42
|
+
`RadioSelector`, `RatingSlider`), or another click event (`onRowClick`, `onCellClick`, `onMenuClick`,
|
|
43
|
+
`onTagClick`, `onItemClick`, `onSelect`).
|
|
44
|
+
- Descendants include blocks in `blocks`, `slots` and `areas`, blocks in `_ref` components and
|
|
45
|
+
templates, and rows of `List`-category blocks.
|
|
46
|
+
- Skip pairs where the inner block is in a `Modal`, `Drawer` or other popup that the ancestor
|
|
47
|
+
contains. Those clicks already did not reach the ancestor.
|
|
48
|
+
|
|
49
|
+
Separately, list each `AgGrid*` block that has `onRowClick` or `onCellClick` **and** cell controls:
|
|
50
|
+
`cell.type: buttons`, `menu`, `link`, `avatar` with a `link`, `selector`, `multipleSelector`,
|
|
51
|
+
`switch`, `textInput` or `paragraphInput`.
|
|
52
|
+
|
|
53
|
+
### Step 2: Keep a pair bubbling only when it has a data dependency
|
|
54
|
+
|
|
55
|
+
For each nested pair, add `bubble: true` to the **inner** event only when the outer event reads
|
|
56
|
+
something the inner event writes. That is, the outer event's actions (including `skip`,
|
|
57
|
+
`:if`/`:switch` conditions and params) read a value that one of the inner event's actions sets,
|
|
58
|
+
without the outer event setting it first:
|
|
59
|
+
|
|
60
|
+
- `_state: key` (or a sub-path of it) where the inner event runs `SetState` on `key`, or the inner
|
|
61
|
+
block is an input whose value is `key` (its `blockId`) and the inner event is its `onChange`.
|
|
62
|
+
- `_global: key` where the inner event runs `SetGlobal` on `key`.
|
|
63
|
+
- `_actions: action_id` of an action in the inner event.
|
|
64
|
+
|
|
65
|
+
Example that keeps bubbling (the card's Request needs the filter the tag sets):
|
|
66
|
+
|
|
67
|
+
```yaml
|
|
68
|
+
# v6: clicking a Tag set the filter, then the Card's onClick fetched with it
|
|
69
|
+
- id: filter_card
|
|
70
|
+
type: Card
|
|
71
|
+
events:
|
|
72
|
+
onClick:
|
|
73
|
+
- id: fetch
|
|
74
|
+
type: Request
|
|
75
|
+
params: fetch_tickets # its payload reads _state: filter
|
|
76
|
+
blocks:
|
|
77
|
+
- id: open_tag
|
|
78
|
+
type: Tag
|
|
79
|
+
events:
|
|
80
|
+
onClick:
|
|
81
|
+
- id: set_filter
|
|
82
|
+
type: SetState
|
|
83
|
+
params:
|
|
84
|
+
filter: open
|
|
85
|
+
|
|
86
|
+
# v7
|
|
87
|
+
- id: open_tag
|
|
88
|
+
type: Tag
|
|
89
|
+
events:
|
|
90
|
+
onClick:
|
|
91
|
+
bubble: true
|
|
92
|
+
try:
|
|
93
|
+
- id: set_filter
|
|
94
|
+
type: SetState
|
|
95
|
+
params:
|
|
96
|
+
filter: open
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
When the outer event reads a request's response (`_request`), check whether that request's payload
|
|
100
|
+
reads a value the inner event sets, and treat that as a dependency too.
|
|
101
|
+
|
|
102
|
+
Convert an action list to the `{ try, catch }` form when you add `bubble`, keeping any existing
|
|
103
|
+
`catch`, `debounce` or `shortcut`.
|
|
104
|
+
|
|
105
|
+
Do **not** add `bubble: true` in any other case, even when both events look related. The outer
|
|
106
|
+
event running as well was usually the bug, for example:
|
|
107
|
+
|
|
108
|
+
- The outer event navigates (`Link`), opens something (`CallMethod` `open`/`toggleOpen`, a
|
|
109
|
+
`Modal`/`Drawer`), or selects the item, and the inner block is a control with its own purpose
|
|
110
|
+
(edit, delete, copy, toggle, menu).
|
|
111
|
+
- The inner event already does everything the outer one does.
|
|
112
|
+
|
|
113
|
+
### Step 3: AgGrid row clicks that cell controls relied on
|
|
114
|
+
|
|
115
|
+
For each `AgGrid*` block from Step 1, `bubble` cannot help, because the row event and the cell
|
|
116
|
+
control's event belong to the same block. Look for cell control events (the `eventName` of cell
|
|
117
|
+
buttons and menu items, `onCellLink`, and cell input events) whose actions read state that
|
|
118
|
+
`onRowClick` or `onCellClick` sets, usually a selected row:
|
|
119
|
+
|
|
120
|
+
```yaml
|
|
121
|
+
# v6: clicking the Edit button also ran onRowClick, which set selected_row first
|
|
122
|
+
events:
|
|
123
|
+
onRowClick:
|
|
124
|
+
- id: select_row
|
|
125
|
+
type: SetState
|
|
126
|
+
params:
|
|
127
|
+
selected_row:
|
|
128
|
+
_event: row
|
|
129
|
+
onEditClick:
|
|
130
|
+
- id: open_editor
|
|
131
|
+
type: CallMethod
|
|
132
|
+
params:
|
|
133
|
+
blockId: edit_modal
|
|
134
|
+
method: open
|
|
135
|
+
- id: fill_form
|
|
136
|
+
type: SetState
|
|
137
|
+
params:
|
|
138
|
+
form:
|
|
139
|
+
_state: selected_row # set by onRowClick in v6
|
|
140
|
+
|
|
141
|
+
# v7: set the row in the button's own event; cell events carry the row as _event: row
|
|
142
|
+
onEditClick:
|
|
143
|
+
- id: select_row_for_edit
|
|
144
|
+
type: SetState
|
|
145
|
+
params:
|
|
146
|
+
selected_row:
|
|
147
|
+
_event: row
|
|
148
|
+
- id: open_editor
|
|
149
|
+
...
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Copy the `SetState` actions from `onRowClick`/`onCellClick` to the start of the control's event,
|
|
153
|
+
with new action ids, when they only use `_event: row` or other values the control's event also
|
|
154
|
+
has (cell button and menu events have `row`; `onCellLink` has `row` and `link`). Do not copy
|
|
155
|
+
`rowIndex`, `selected`, `cell` or `colId` reads, which cell control events do not carry; report
|
|
156
|
+
those instead.
|
|
157
|
+
|
|
158
|
+
### Step 4: Report
|
|
159
|
+
|
|
160
|
+
Produce a report with three sections:
|
|
161
|
+
|
|
162
|
+
1. **Changed.** Each inner event given `bubble: true`, and each AgGrid control event given copied
|
|
163
|
+
actions: file path, line number, block id, event name, and the value that creates the
|
|
164
|
+
dependency (for example `_state: filter`, set by `set_filter`).
|
|
165
|
+
2. **Needs a decision.** Dependencies you could not resolve: outer events that read `_request`
|
|
166
|
+
responses you could not trace, AgGrid control events that read `rowIndex`/`selected`/`cell`,
|
|
167
|
+
and nested events whose blocks are built at runtime (`Dynamic` blocks, `_js`, config from
|
|
168
|
+
requests).
|
|
169
|
+
3. **New behaviour, no change.** The count of nested pairs and AgGrid grids left as they are,
|
|
170
|
+
grouped by pattern (button in clickable card or box, control in list row, input in clickable
|
|
171
|
+
block, AgGrid cell control), with file paths. The author can scan these for the rare case
|
|
172
|
+
where the outer event should still run.
|
|
173
|
+
|
|
174
|
+
## Scope
|
|
175
|
+
|
|
176
|
+
`app`: all YAML and Nunjucks config, including shared components, modules and templates reached
|
|
177
|
+
through `_ref`.
|
|
178
|
+
|
|
179
|
+
## Files to Check
|
|
180
|
+
|
|
181
|
+
Glob: `**/*.{yaml,yml,njk,json}`
|
|
182
|
+
Grep: `onClick:|onRowClick:|onCellClick:`
|
|
183
|
+
|
|
184
|
+
## Verification
|
|
185
|
+
|
|
186
|
+
- `lowdefy build` passes.
|
|
187
|
+
- Every `bubble: true` added in Step 2 is on an inner event whose ancestor reads a value it sets,
|
|
188
|
+
and is listed in the report.
|
|
189
|
+
- Clicking each changed control in the running app still runs both events, and clicking controls
|
|
190
|
+
from the "no change" list runs only the control's event.
|