@nipe-solutions/flex-layout-codemod 2.0.0-beta.1 → 2.0.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 2.0.0-beta.3
+
+### Minor Changes
+
+- 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.
+
+## 2.0.0-beta.2
+
+### Minor Changes
+
+- 89c6f92: Make migration planning the default, require `--write` to apply project changes, and publish schema-2 reports with explicit execution and application state.
+- 77391e3: Launch the public documentation site and browser-only single-template migration playground, and point package metadata to the production documentation homepage.
+- f058c0b: Add opt-in Tailwind conversion for the archived orientation breakpoints and project-configured print fallback behavior.
+- 40e3719: Add an explicit native CSS target that updates templates and one owned companion stylesheet as a recoverable transaction.
+- 029562c: Add opt-in migration of safe literal responsive image sources to native picture markup with atomic template validation and report-based review locations.
+- 6f8ef7a: Convert literal Angular Flex-Layout Grid directives, including standard responsive aliases, when Tailwind compiler output and element ownership prove an exact migration.
+
+### Patch Changes
+
+- 4715a71: Add an executable compatibility inventory and rewrite beta onboarding around safe previews, pinned team installation, exact support boundaries, and copyable CLI workflows.
+
 ## 2.0.0-beta.1
 
 ### Minor Changes

package/README.md

@@ -1,100 +1,56 @@
 # Angular Flex-Layout Codemod
 
-A safety-first codemod for migrating projects away from the archived Angular Flex-Layout library.
+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.
 
-Version 2 remains a prerelease under active development. It does not claim production-ready conversion coverage. See the [compatibility reference](docs/compatibility.md) for the current directive-by-directive status and safety limitations.
+> Plan first. Review unresolved cases. Write only when you are ready.
 
-Install a published v2 beta as a development dependency with `npm install --save-dev @nipe-solutions/flex-layout-codemod@beta`. Maintainers should follow the reviewed [release process](docs/architecture/release-process.md); merging a version pull request does not publish the package.
+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.
 
-## Current scope
+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).
 
-The v2 engine parses templates with the Angular compiler and applies validated source-range edits. It preserves comments, control-flow syntax, interpolation, line endings, and all unrelated source text instead of serializing the template as generic HTML.
+## Requirements and installation
 
-The current prerelease converts documented static inputs and literal responsive inputs using the standard Angular Flex-Layout viewport aliases (`xs` through `xl`, `lt-*`, and `gt-*`) to exact Tailwind CSS v4 arbitrary media variants. For example, `fxLayout.sm="row"` becomes `[@media_screen_and_(min-width:_600px)_and_(max-width:_959.98px)]:flex-row` alongside the other layout utilities. Dynamic bindings, orientation, print, and custom breakpoints, unsupported directives, and responsive families with conflicting overlapping values remain unchanged with structured review results. Ambiguous behavior is never approximated silently.
+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:
 
-Literal responsive `ngClass.<alias>` and `ngStyle.<alias>` values use the same 13-alias boundary. Class values are split with Angular `NgClass`'s ECMAScript-whitespace rule and convert only when every token is in the compiler-proven built-in Tailwind CSS v4 surface, retains the host element as its CSS target, and can be emitted byte-for-byte for Tailwind's raw template scanner. Style declarations convert to arbitrary-property utilities only when Flex-Layout's quote removal, semicolon splitting, exact-key application order, Angular unit handling, CSS priority, fallback ownership, and responsive precedence can be represented exactly. Distinct exact ordinary keys that apply to the same CSS property, including `font-size` and `font-size.px`, are preserved because their result can depend on `NgStyle` activation history. Unsuffixed `ngClass` and `ngStyle` siblings are treated as replaceable fallback authorities rather than silently left as always-active values.
-
-```html
-<!-- input -->
-<div ngClass.sm="flex items-center"></div>
-<div ngStyle.lt-md="font-size.px: 14; color: #334155"></div>
-
-<!-- output -->
-<div
-  class="[@media_screen_and_(min-width:_600px)_and_(max-width:_959.98px)]:flex [@media_screen_and_(min-width:_600px)_and_(max-width:_959.98px)]:items-center"
-></div>
-<div
-  class="[@media_screen_and_(max-width:_959.98px)]:[font-size:14px] [@media_screen_and_(max-width:_959.98px)]:[color:#334155]"
-></div>
-```
-
-Application classes, project plugin utilities, custom-theme-dependent candidates such as `bg-brand-500`, unsafe style values, bindings, interpolation, and deprecated `class.<alias>` or `style.<alias>` selectors remain in place with review diagnostics. The current mode does not inspect project styles or Tailwind configuration and does not generate a companion stylesheet.
-
-Existing literal classes use a broader conservative ownership check than generated-candidate admission. Compiler-modeled Tailwind utilities contribute every stable declaration they emit, including inferred arbitrary text sizes, directional border style/width pairs, and shadow color custom properties. A recognized pinned Tailwind utility whose complete property set is not modeled is treated as an unknown CSS authority and blocks an intersecting conversion instead of being silently ignored; ordinary application classes such as `card` remain additive.
-
-Literal `fxShow` and `fxHide` inputs are converted when the element's complete display behavior is provable. The conversion follows Angular Flex-Layout coercion: `fxShow="false"` hides, `fxHide="false"` shows, and other literal strings, including `"0"`, are truthy before `fxHide` inversion. Literal values use Angular-decoded text, so an entity-spelled value such as `fals&#101;` has the same semantics as `false`. Hiding uses `hidden`; a responsive shown state after base hiding restores only a display value proven by a converted `fxLayout` or one unambiguous base Tailwind display utility.
-
-```html
-<!-- input -->
-<div fxLayout="column" fxShow="false" fxShow.sm></div>
-
-<!-- output -->
-<div
-  class="flex flex-col box-border hidden [@media_screen_and_(min-width:_600px)_and_(max-width:_959.98px)]:flex"
-></div>
+```bash
+npm install --save-dev --save-exact @nipe-solutions/flex-layout-codemod@beta
 ```
 
-The complete visibility family is preserved when it contains a binding or interpolation, an orientation, print, or custom alias, conflicting overlapping states, an unverified restoration display, a partially overlapping responsive layout display without safe ownership, or an unsafe class/style interaction. A literal or bound style that can control `display` always blocks conversion. An unresolved responsive class or style authority also preserves related visibility output when it may control `display`. A bound class blocks a family that needs generated classes, but does not block an all-shown no-op whose attributes can simply be removed. See the [compatibility reference](docs/compatibility.md) and [visibility architecture](docs/architecture/visibility-semantics.md) for the exact boundary.
+See [Installation and requirements](https://angular-flex-layout-codemod.nipesolutions.com/docs/installation) for the project-baseline checklist.
 
-## CLI workflow
+## Plan, review, write
 
-Run the codemod for one Angular template or a directory:
+Create a plan and an optional JSON report without changing project templates or stylesheets:
 
 ```bash
-flex-layout-codemod ./src --target tailwind --output ./migrated-src
+npx flex-layout-codemod ./src --report ./reports/flex-layout.json
 ```
 
-Preview the same migration plan without writing templates, while also creating a JSON report:
+Review the proposed output and every unresolved diagnostic. The report is the command's intentional filesystem output in plan mode.
 
-```bash
-flex-layout-codemod ./src --target tailwind --output ./migrated-src --dry-run --report ./reports/flex-layout.json
-```
-
-Only changed `.html` files are written during a real migration. For a single-file input, the planned output path must end in `.html` (case-insensitive); omitting `--output` keeps the default in-place behavior. For a folder input, `--output` remains a directory and each derived template output retains its `.html` path. `--dry-run` applies and validates edits in memory but does not write template output or create its missing parent directories. A requested `--report <path>` is an explicit reporting side effect and is still written atomically during a dry-run. The report path must be nonblank and end in `.json` (case-insensitive). Migratable inputs and planned template outputs exclusively use `.html`, so this structural rule prevents report collisions while allowing reports anywhere, including inside input or output trees. Invalid output and report paths are rejected before migration without creating output or report directories.
-
-Unresolved `review`, `unsupported`, or `invalid` results are strict by default. To preserve the same diagnostics and migration output while accepting unresolved work in automation, use:
+Apply the reviewed Tailwind CSS plan explicitly:
 
 ```bash
-flex-layout-codemod ./src --dry-run --allow-unresolved
+npx flex-layout-codemod ./src --target tailwind --write
 ```
 
-The CLI uses these exit codes:
-
-| Code | Meaning                                                                                |
-| ---: | -------------------------------------------------------------------------------------- |
-|  `0` | Migration completed with no unresolved results, or `--allow-unresolved` accepted them. |
-|  `1` | Configuration, parsing, template I/O, report writing, or an internal invariant failed. |
-|  `2` | Migration completed safely, but unresolved results remain in strict mode.              |
-
-JSON reports use schema version `1`. Report paths use forward slashes and are relative to the input root; a single-file input is represented by its basename, never an absolute checkout path. Files are path-sorted, results retain source order, and the summary is derived from those file results.
+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.
 
-Each non-parse report result represents one source directive occurrence. Measure responsive class and style adoption by counting `ngClass`, `ngStyle`, `class`, and `style` results by status in a representative migration report. This occurrence ratio is an inventory of the scanned templates, not a claim that the same percentage of an application or its runtime behavior was converted.
+## Documentation
 
-Use version control and review the generated diff before replacing application templates. Native CSS output remains outside the current scope.
+- [Migration guide](https://angular-flex-layout-codemod.nipesolutions.com/docs)
+- [Compatibility by target and directive](https://angular-flex-layout-codemod.nipesolutions.com/docs/compatibility)
+- [Diagnostics and remediation](https://angular-flex-layout-codemod.nipesolutions.com/docs/diagnostics)
+- [Complete CLI reference](https://angular-flex-layout-codemod.nipesolutions.com/docs/cli)
+- [JSON reports and CI](https://angular-flex-layout-codemod.nipesolutions.com/docs/reports)
+- [Safety, transactions, and recovery](https://angular-flex-layout-codemod.nipesolutions.com/docs/safety)
 
-The TypeScript extension API changed in v2: mutable Cheerio converters were replaced by immutable `ConversionAdapter` plans and structured `ConversionResult` values. These prerelease APIs may continue to evolve before v2 is stable.
+## Contributing and support
 
-## Development
-
-The repository requires Node.js 24 and npm 11.
-
-```bash
-npm ci
-npm run verify
-```
+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).
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Security reports belong in [GitHub private vulnerability reporting](https://github.com/NIPE-Solutions/flex-layout-migrator/security/advisories/new); other support routes are documented in [docs/SUPPORT.md](docs/SUPPORT.md).
+Maintainers should follow the reviewed [release process](docs/architecture/release-process.md).
 
 ## License
 
-MIT
+[MIT](LICENSE)