@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.
@@ -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.