@arcgis/codemod 6.0.0-next.43 → 6.0.0-next.45

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/README.md CHANGED
@@ -3,20 +3,20 @@
3
3
  A codemod toolkit for updating and modernizing ArcGIS Maps SDK for JavaScript codebases.
4
4
 
5
5
  This package provides automated refactors to help migrate away from deprecated or legacy patterns.
6
- These include codemods for removing the `__esri` namespace and
7
- converting global namespace types to explicit `@arcgis/core` imports,
8
- normalizing legacy Calcite icon names,
9
- and updating geometry operator usage.
10
6
 
11
7
  ## Requirements
12
8
 
13
9
  - Node.js 24
14
10
  - A project using the ArcGIS Maps SDK for JavaScript
15
- - This codemod operates exclusively on TypeScript files. You do not need to run this tool if the project does not use TypeScript.
11
+ - Supported file types depend on the codemod. The `feature-next-to-feature` codemod supports JavaScript, TypeScript, JSX, TSX, and HTML; `features-next-to-features` supports JavaScript, TypeScript, JSX, and TSX.
16
12
 
17
13
  ## Before you begin
18
14
 
19
- Ensure your project's dependencies are up to date, for example by running `pnpm install`.
15
+ Ensure your project's dependencies are up to date, for example by running `npm install`.
16
+
17
+ In a monorepo environment, build your project before running the codemod.
18
+
19
+ Before running a codemod that migrates to newer APIs, update the affected dependencies to versions that include those newer APIs.
20
20
 
21
21
  If your project uses **ESLint, Prettier, or other formatters/linters**, run them after the codemod to ensure consistent formatting.
22
22
 
@@ -25,7 +25,7 @@ If your project uses **ESLint, Prettier, or other formatters/linters**, run them
25
25
  > that is under version control (Git) so you can review changes using `git diff` or your IDE’s diff tools. If your
26
26
  > project is not under version control, create a backup before running the codemod.
27
27
 
28
- By default, codemods run on all TypeScript files in the current directory and subdirectories.
28
+ By default, codemods run on supported source files in the current directory and subdirectories.
29
29
  You can manually run it on a different directory by providing it as an argument.
30
30
 
31
31
  Codemods respect `.gitignore` files and will not modify any files ignored by them.
@@ -33,8 +33,12 @@ Codemods respect `.gitignore` files and will not modify any files ignored by the
33
33
  ## Available codemods
34
34
 
35
35
  - [`refactor-out-esri-namespace`](#refactor-out-the-__esri-namespace)
36
+ - [`refactor-component-types`](#refactor-component-types)
36
37
  - [`normalize-calcite-icon-names`](#normalize-calcite-icon-names)
37
38
  - [`geometry-operator-renames`](#rename-geometry-operators)
39
+ - [`rename-next-list-components`](#rename-next-list-components)
40
+ - [`feature-next-to-feature`](#migrate-feature-next-to-feature)
41
+ - [`features-next-to-features`](#rename-features-next)
38
42
 
39
43
  ### Refactor out the `__esri` namespace
40
44
 
@@ -76,6 +80,73 @@ The codemod will emit warnings for cases it cannot safely rewrite, including:
76
80
 
77
81
  These will be reported in the console. Manually review all changes before committing.
78
82
 
83
+ ### Refactor component types
84
+
85
+ Migrates deprecated global component types to explicit component imports and framework helpers.
86
+
87
+ ```sh
88
+ npx @arcgis/codemod@latest run refactor-component-types [<target-directory>]
89
+ ```
90
+
91
+ Update component dependencies before running; the codemod assumes the replacement APIs are available.
92
+
93
+ Codemod edits:
94
+
95
+ Replace global `HTML*Element` types with the exported component class.
96
+
97
+ ```ts
98
+ // Before
99
+ const map = document.querySelector<HTMLArcgisMapElement>("#map");
100
+
101
+ // After
102
+ import type { ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
103
+ const map = document.querySelector<ArcgisMap>("#map");
104
+ ```
105
+
106
+ Replace generic `*CustomEvent<T>` type helpers with specific event type:
107
+
108
+ ```ts
109
+ // Before
110
+ import type { ArcgisMapCustomEvent } from "@arcgis/map-components";
111
+
112
+ map.addEventListener("arcgisViewReadyChange", handleReadyChange);
113
+ function handleReadyChange(event: ArcgisMapCustomEvent<void>) {
114
+ console.log(event.currentTarget.zoom);
115
+ }
116
+
117
+ // After
118
+ import type { ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
119
+
120
+ map.addEventListener("arcgisViewReadyChange", handleReadyChange);
121
+ function handleReadyChange(event: ArcgisMap["arcgisViewReadyChange"]) {
122
+ console.log(event.currentTarget.zoom);
123
+ }
124
+ ```
125
+
126
+ Use JSX prop helpers with explicitly imported component types:
127
+
128
+ ```tsx
129
+ // Before
130
+ import type { ReactArcgisMap } from "@arcgis/map-components/types/react";
131
+
132
+ function Map(props: ReactArcgisMap) {
133
+ return <arcgis-map {...props} />;
134
+ }
135
+
136
+ // After
137
+ import type { ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
138
+ import type { ToReactProps } from "@arcgis/map-components/types/react";
139
+
140
+ function Map(props: ToReactProps<ArcgisMap>) {
141
+ return <arcgis-map {...props} />;
142
+ }
143
+ ```
144
+
145
+ For Preact, use `ToPreactProps<ArcgisMap>` from `@arcgis/map-components/types/preact`.
146
+ For Stencil, use `ToStencilProps<ArcgisMap>` from `@arcgis/map-components/types/stencil`.
147
+
148
+ Global event payload maps like `HTMLArcgisMapElementEventMap` become `ArcgisMap["@eventTypes"]`.
149
+
79
150
  ### Normalize Calcite icon names
80
151
 
81
152
  The `normalize-calcite-icon-names` codemod updates camelCase and legacy Calcite icon names to their normalized
@@ -130,6 +201,86 @@ const options: BufferExecuteOptions = { unit: "meters" };
130
201
  const buffered = bufferExecute(polyline, 250, options);
131
202
  ```
132
203
 
204
+ ### Rename Next List Components
205
+
206
+ In version 6.0, the next-generation Basemap Layer List, Catalog Layer List, Layer List, and Table List components
207
+ replace their original components. The `rename-next-list-components` codemod updates component tags, package
208
+ subpaths, and public TypeScript symbols to remove the `next` suffix.
209
+
210
+ Run it in the root of your project or with an explicit target directory:
211
+
212
+ ```sh
213
+ npx @arcgis/codemod run rename-next-list-components [<target-directory>]
214
+ ```
215
+
216
+ **Before:**
217
+
218
+ ```tsx
219
+ import type { ArcgisLayerListNext } from "@arcgis/map-components/components/arcgis-layer-list-next";
220
+
221
+ const layerList: ArcgisLayerListNext = document.createElement("arcgis-layer-list-next");
222
+ ```
223
+
224
+ **After:**
225
+
226
+ ```tsx
227
+ import type { ArcgisLayerList } from "@arcgis/map-components/components/arcgis-layer-list";
228
+
229
+ const layerList: ArcgisLayerList = document.createElement("arcgis-layer-list");
230
+ ```
231
+
232
+ ### Migrate Feature (next) to Feature
233
+
234
+ In version 6.0, `arcgis-feature-next` is removed and `arcgis-feature` uses its implementation.
235
+ To update static component tags, imports, element types, and common DOM queries in JavaScript,
236
+ TypeScript, JSX, TSX, and HTML files, run the following command. Local aliases and re-export names are preserved.
237
+
238
+ ```sh
239
+ npx @arcgis/codemod run feature-next-to-feature [<target-directory>]
240
+ ```
241
+
242
+ Review the changes and manually update dynamic references, CSS selectors, framework templates, the removed
243
+ `viewModel` property, and promise chaining on `nextMedia`, `previousMedia`, or `setActiveMedia`.
244
+ The media methods now return `void`. React wrappers are no longer available in 6.0; replace them with
245
+ `<arcgis-feature>` and migrate event handlers manually. The codemod warns about wrapper usages it finds.
246
+
247
+ ### Rename Features (Next)
248
+
249
+ In version 6.0, `arcgis-features-next` is replaced by `arcgis-features`.
250
+ The `features-next-to-features` codemod updates static `@arcgis/map-components` imports,
251
+ imported `ArcgisFeaturesNext` types and their references, JSX tags, and literal DOM tag names passed to
252
+ `querySelector`, `querySelectorAll`, `createElement`, `getElementsByTagName`, `closest`, and `matches`.
253
+ Existing import aliases are preserved; IDs, labels, and other application strings are not renamed.
254
+
255
+ ```sh
256
+ npx @arcgis/codemod run features-next-to-features [<target-directory>]
257
+ ```
258
+
259
+ **Before:**
260
+
261
+ ```tsx
262
+ import type { ArcgisFeaturesNext } from "@arcgis/map-components/components/arcgis-features-next";
263
+ const element = document.querySelector<ArcgisFeaturesNext["el"]>("arcgis-features-next");
264
+ const view = <arcgis-features-next />;
265
+ ```
266
+
267
+ **After:**
268
+
269
+ ```tsx
270
+ import type { ArcgisFeatures } from "@arcgis/map-components/components/arcgis-features";
271
+ const element = document.querySelector<ArcgisFeatures["el"]>("arcgis-features");
272
+ const view = <arcgis-features />;
273
+ ```
274
+
275
+ Review remaining references reported by the codemod. Dynamic imports, re-exports, indirect tag names, compound selectors,
276
+ HTML/CSS templates, and standalone HTML/CSS files require manual migration. Standalone HTML/CSS files
277
+ are not scanned.
278
+
279
+ This codemod only automates the component rename. Applications already using `arcgis-features` must
280
+ also review the [6.0 Features migration notes](https://developers.arcgis.com/javascript/latest/v6-0/#features),
281
+ including removed methods, the abilities property rename, and translation overrides.
282
+ These changes depend on application behavior and are not rewritten automatically.
283
+
133
284
  ## Versioning
134
285
 
135
286
  The codemods are available until the corresponding deprecated feature is removed.