@nipe-solutions/flex-layout-codemod 2.0.0-beta.2 → 2.0.0-beta.3
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/CHANGELOG.md +6 -0
- package/README.md +22 -137
- package/dist/cli.js +3 -2
- package/dist/cli.js.map +1 -1
- package/package.json +3 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2.0.0-beta.3
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- ca82744: Expand the documentation site into a comprehensive migration reference with production-verified CLI, diagnostic, compatibility, report, and transformation contracts. Add review-first workflow guidance, target-specific explorers and examples, responsive documentation navigation, and keyboard-accessible code regions.
|
|
8
|
+
|
|
3
9
|
## 2.0.0-beta.2
|
|
4
10
|
|
|
5
11
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -1,171 +1,56 @@
|
|
|
1
1
|
# Angular Flex-Layout Codemod
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Angular Flex-Layout Codemod is a review-first CLI for migrating supported Angular Flex-Layout template directives to Tailwind CSS v4 or native CSS. Version 2 remains a prerelease.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> Plan first. Review unresolved cases. Write only when you are ready.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The codemod changes only cases for which it can produce a supported equivalent. When it cannot prove that boundary, it leaves the source in place and reports a diagnostic instead of guessing.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Read the [detailed documentation](https://angular-flex-layout-codemod.nipesolutions.com/docs), or try a single template in the separate [browser playground](https://angular-flex-layout-codemod.nipesolutions.com/#playground).
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Requirements and installation
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
The complete directive-by-directive status, including grid, image, breakpoint, and class/style boundaries, is in [docs/compatibility.md](docs/compatibility.md). Treat that reference as the beta’s compatibility contract.
|
|
16
|
-
|
|
17
|
-
## Quick start
|
|
18
|
-
|
|
19
|
-
Evaluate the published beta without installing it. This safely previews the migration and does not write templates:
|
|
20
|
-
|
|
21
|
-
```bash
|
|
22
|
-
npx @nipe-solutions/flex-layout-codemod@beta ./src
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
Read the terminal summary and diagnostics before applying any migration. A clean Git worktree makes the resulting template diff easy to inspect.
|
|
26
|
-
|
|
27
|
-
## Install for a team or CI
|
|
28
|
-
|
|
29
|
-
Install the beta as an exact development dependency. `--save-exact` records the prerelease resolved from the `beta` tag, so the package manifest and lockfile keep the team on that reviewed version:
|
|
13
|
+
The CLI requires Node.js 24 or newer. Install the current beta as an exact development dependency so your package manifest and lockfile retain the reviewed version:
|
|
30
14
|
|
|
31
15
|
```bash
|
|
32
16
|
npm install --save-dev --save-exact @nipe-solutions/flex-layout-codemod@beta
|
|
33
17
|
```
|
|
34
18
|
|
|
35
|
-
|
|
19
|
+
See [Installation and requirements](https://angular-flex-layout-codemod.nipesolutions.com/docs/installation) for the project-baseline checklist.
|
|
36
20
|
|
|
37
|
-
##
|
|
21
|
+
## Plan, review, write
|
|
38
22
|
|
|
39
|
-
|
|
23
|
+
Create a plan and an optional JSON report without changing project templates or stylesheets:
|
|
40
24
|
|
|
41
25
|
```bash
|
|
42
26
|
npx flex-layout-codemod ./src --report ./reports/flex-layout.json
|
|
43
27
|
```
|
|
44
28
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
If any template has a parse error, no project changes are applied and terminal output labels the remaining edits as planned. In the default plan mode, `application` remains `{ "status": "skipped", "reason": "plan-only" }` even when parsing fails. When `--write` was requested, a parse error produces `{ "status": "skipped", "reason": "parse-errors" }`. Neither outcome presents proposed template or stylesheet actions as applied writes.
|
|
29
|
+
Review the proposed output and every unresolved diagnostic. The report is the command's intentional filesystem output in plan mode.
|
|
48
30
|
|
|
49
|
-
|
|
31
|
+
Apply the reviewed Tailwind CSS plan explicitly:
|
|
50
32
|
|
|
51
33
|
```bash
|
|
52
34
|
npx flex-layout-codemod ./src --target tailwind --write
|
|
53
35
|
```
|
|
54
36
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
### Native CSS companion stylesheet
|
|
58
|
-
|
|
59
|
-
Use the native CSS target when the documented Flex-only surface is appropriate:
|
|
60
|
-
|
|
61
|
-
```bash
|
|
62
|
-
npx flex-layout-codemod ./src --target css --stylesheet ./src/flex-layout-migration.css --write
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
The migration updates templates and the one named companion stylesheet as a transaction. It owns only the marked `flex-layout-codemod` block, preserves handwritten CSS surrounding that block, retains unmatched owned rules because the stylesheet may serve templates outside the selected invocation, and keeps shared rules deduplicated across files. The current CLI has no complete-project pruning mode. On ordinary failures or handled interruption it rolls the changed templates and stylesheet back together.
|
|
66
|
-
|
|
67
|
-
The stylesheet path may use any filename accepted as a regular file. If it ends in `.html` and is inside a folder input, that exact selected path is excluded from template discovery so reruns remain byte-idempotent. Stylesheet, template, and JSON-report destinations must remain physically distinct; existing file identity and conservative case/Unicode-normalized aliases for missing paths are checked before application and again before report replacement.
|
|
68
|
-
|
|
69
|
-
No filesystem workflow can promise durable rollback after abrupt process termination, power loss, or a storage failure. If the command reports unconfirmed recovery, stop and inspect the listed paths, reconcile them with Git or a verified backup, then rerun only after the project is consistent.
|
|
70
|
-
|
|
71
|
-
## Examples
|
|
72
|
-
|
|
73
|
-
This converted example is the same static layout and gap case exercised by the migration fixtures:
|
|
74
|
-
|
|
75
|
-
```html
|
|
76
|
-
<!-- input -->
|
|
77
|
-
<div fxLayout="column" fxLayoutGap="4"></div>
|
|
78
|
-
|
|
79
|
-
<!-- output -->
|
|
80
|
-
<div class="flex flex-col box-border gap-[4px]"></div>
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
Literal Grid containers and children use compiler-verified arbitrary properties when no exact built-in utility exists:
|
|
84
|
-
|
|
85
|
-
```html
|
|
86
|
-
<!-- input -->
|
|
87
|
-
<section gdColumns="12rem 1fr" gdGap="1rem"><div gdColumn="2"></div></section>
|
|
88
|
-
|
|
89
|
-
<!-- output -->
|
|
90
|
-
<section class="grid [grid-template-columns:12rem_1fr] [grid-gap:1rem]"><div class="[grid-column:2]"></div></section>
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
Orientation and print conversion require explicit source-configuration evidence. These flags assert settings you have already verified in the Angular application's Flex-Layout configuration; the codemod does not discover them:
|
|
94
|
-
|
|
95
|
-
```bash
|
|
96
|
-
# Source uses addOrientationBps: true and printWithBreakpoints: ['md', 'handset']
|
|
97
|
-
npx flex-layout-codemod ./src --orientation-breakpoints --print-with-breakpoints md,handset --write
|
|
98
|
-
|
|
99
|
-
# Source explicitly uses printWithBreakpoints: []
|
|
100
|
-
npx flex-layout-codemod ./src --print-with-breakpoints none --write
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
With orientation enabled, all nine archived aliases are available: `handset`, `handset.portrait`, `handset.landscape`, `tablet`, `tablet.portrait`, `tablet.landscape`, `web`, `web.portrait`, and `web.landscape`. Print conversion reproduces configured responsive fallback values, while an explicit `.print` value takes precedence.
|
|
104
|
-
|
|
105
|
-
Responsive image migration is a separate opt-in because introducing `<picture>` changes the image's parent and may affect CSS or test selectors. After reviewing that risk, enable literal standard-breakpoint sources with `--responsive-images`:
|
|
106
|
-
|
|
107
|
-
```bash
|
|
108
|
-
npx flex-layout-codemod ./src --responsive-images --report ./reports/flex-layout.json --write
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
```html
|
|
112
|
-
<!-- input -->
|
|
113
|
-
<img src="hero.png" src.lt-sm="hero-mobile.png" alt="Hero" />
|
|
114
|
-
|
|
115
|
-
<!-- output -->
|
|
116
|
-
<picture
|
|
117
|
-
><source media="screen and (max-width: 599.98px)" srcset="hero-mobile.png" />
|
|
118
|
-
<img src="hero.png" alt="Hero"
|
|
119
|
-
/></picture>
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
Only literal values using the 13 standard viewport aliases convert. Dynamic values, orientation, print, custom aliases, ambiguous URLs, structural directives on the image, and images already inside `<picture>` remain unchanged. Use the JSON report's file paths and source offsets to review every converted `imgSrc` occurrence and check selectors that assume the `<img>` has its former parent. Interactive file navigation is deferred to the CLI upgrade.
|
|
123
|
-
|
|
124
|
-
This fixture is intentionally preserved because the value is a runtime Angular expression. The report records a `dynamic-binding` review diagnostic and the source remains unchanged:
|
|
125
|
-
|
|
126
|
-
```html
|
|
127
|
-
<div [fxFlex]="basis"></div>
|
|
128
|
-
```
|
|
37
|
+
For native CSS output, target limits, output paths, and recovery behavior, follow the [migration workflow](https://angular-flex-layout-codemod.nipesolutions.com/docs/workflow). Keep the migration on a clean branch and review the resulting diff and application tests.
|
|
129
38
|
|
|
130
|
-
##
|
|
39
|
+
## Documentation
|
|
131
40
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
| Code | Meaning |
|
|
139
|
-
| ---: | ---------------------------------------------------------------------------------------------------------- |
|
|
140
|
-
| `0` | Planning or application completed cleanly, or unresolved work was accepted with `--allow-unresolved`. |
|
|
141
|
-
| `1` | Configuration, parsing, project I/O, transaction, report writing, or an internal invariant failed. |
|
|
142
|
-
| `2` | Planning or application completed safely, but `review`, `unsupported`, or `invalid` results remain strict. |
|
|
143
|
-
|
|
144
|
-
For an informational CI report that accepts unresolved work while retaining every diagnostic, use:
|
|
145
|
-
|
|
146
|
-
```bash
|
|
147
|
-
npx flex-layout-codemod ./src --report ./reports/flex-layout.json --allow-unresolved
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
`--allow-unresolved` changes only the final exit code; it does not hide diagnostics or alter the migration output.
|
|
151
|
-
|
|
152
|
-
## Known boundaries
|
|
153
|
-
|
|
154
|
-
Tailwind CSS v4 remains the default target. A native CSS target is available with `--target css --stylesheet <path>` for exactly eight Flex semantic families at base and the 13 standard viewport aliases. Grid, visibility, responsive class/style, orientation, print, and custom aliases remain preserved for CSS. Responsive `imgSrc` remains an independent opt-in native `<picture>` migration. See [docs/compatibility.md](docs/compatibility.md) for exact supported forms and diagnostic codes before planning a large migration.
|
|
155
|
-
|
|
156
|
-
The CSS target does not inspect project styles, Tailwind configuration, Sass, or Less; it updates only its one owned companion block. Dynamic Angular bindings are not evaluated.
|
|
41
|
+
- [Migration guide](https://angular-flex-layout-codemod.nipesolutions.com/docs)
|
|
42
|
+
- [Compatibility by target and directive](https://angular-flex-layout-codemod.nipesolutions.com/docs/compatibility)
|
|
43
|
+
- [Diagnostics and remediation](https://angular-flex-layout-codemod.nipesolutions.com/docs/diagnostics)
|
|
44
|
+
- [Complete CLI reference](https://angular-flex-layout-codemod.nipesolutions.com/docs/cli)
|
|
45
|
+
- [JSON reports and CI](https://angular-flex-layout-codemod.nipesolutions.com/docs/reports)
|
|
46
|
+
- [Safety, transactions, and recovery](https://angular-flex-layout-codemod.nipesolutions.com/docs/safety)
|
|
157
47
|
|
|
158
48
|
## Contributing and support
|
|
159
49
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
```bash
|
|
163
|
-
npm ci
|
|
164
|
-
npm run verify
|
|
165
|
-
```
|
|
50
|
+
Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Use [GitHub Issues](https://github.com/NIPE-Solutions/flex-layout-migrator/issues) for reproducible, redacted migration cases. Report vulnerabilities only through [GitHub private vulnerability reporting](https://github.com/NIPE-Solutions/flex-layout-migrator/security/advisories/new); see [SECURITY.md](SECURITY.md) and [support guidance](docs/SUPPORT.md).
|
|
166
51
|
|
|
167
|
-
|
|
52
|
+
Maintainers should follow the reviewed [release process](docs/architecture/release-process.md).
|
|
168
53
|
|
|
169
54
|
## License
|
|
170
55
|
|
|
171
|
-
MIT
|
|
56
|
+
[MIT](LICENSE)
|
package/dist/cli.js
CHANGED
|
@@ -7,7 +7,7 @@ import * as path17 from "path";
|
|
|
7
7
|
// package.json
|
|
8
8
|
var package_default = {
|
|
9
9
|
name: "@nipe-solutions/flex-layout-codemod",
|
|
10
|
-
version: "2.0.0-beta.
|
|
10
|
+
version: "2.0.0-beta.3",
|
|
11
11
|
description: "A safety-first codemod for migrating Angular Flex-Layout templates to native CSS or Tailwind CSS.",
|
|
12
12
|
type: "module",
|
|
13
13
|
engines: {
|
|
@@ -45,7 +45,8 @@ var package_default = {
|
|
|
45
45
|
format: "prettier --check .",
|
|
46
46
|
"format:write": "prettier --write .",
|
|
47
47
|
verify: "npm run format && npm run lint && npm run typecheck && npm run test:coverage && npm run build && npm run package:check",
|
|
48
|
-
"verify:website": "npm run format && npm run lint && npm run test:website && npm run typecheck:website && npm run verify:website-assets && npm run build:website && npm run verify:website-static && npm run test:e2e:website",
|
|
48
|
+
"verify:website": "npm run format && npm run lint && npm run test:website && npm run typecheck:website && npm run verify:website-assets && npm run verify:docs && npm run build:website && npm run verify:website-static && npm run test:e2e:website",
|
|
49
|
+
"verify:docs": "node scripts/verify-documentation-contract.mjs",
|
|
49
50
|
"verify:website-static": "node scripts/verify-website-static.mjs",
|
|
50
51
|
"package:check": "node scripts/verify-package.mjs",
|
|
51
52
|
changeset: "changeset add",
|