generate-ui-cli 2.1.7 → 2.3.0

package/README.md

@@ -4,6 +4,7 @@ Generate CRUD screens (List, Create/Edit, Delete), typed API services, and route
 
 Goal: stop rewriting repetitive CRUD and start with a functional, scalable UI foundation.
 
+![Example ](image.png)
 ## What GenerateUI Does
 
 Given an `openapi.yaml` (or `.json`), GenerateUI can generate:
@@ -49,17 +50,67 @@ npx generate-ui --help
 
 ## Recommended Workflow
 
-GenerateUI works in two main steps:
+GenerateUI default flow is a single command:
+
+1. Read OpenAPI and generate schemas
+2. Generate Angular code
+
+All in:
+- `generate-ui generate`
+
+## Recommended Setup (No Paths in Commands)
+
+Create `generateui-config.json` at the root of your Angular project:
+
+```json
+{
+  "openapi": "openapi.yaml",
+  "schemas": "src/generate-ui",
+  "features": "src/app/features",
+  "appTitle": "Store",
+  "defaultRoute": "",
+  "menu": {
+    "autoInject": true
+  },
+  "views": {
+    "ProductsAdmin": "cards",
+    "getProducts": "list",
+    "CharacterAdmin": "cards"
+  }
+}
+```
+
+Note: `list` is treated as table-style rendering.
+
+## Complete Step-by-Step
+
+1. Configure `generateui-config.json` at the project root.
+   Edit it before generation whenever you want to change `appTitle`, `defaultRoute`, `menu.autoInject`, or `views`.
+2. Run full generation:
+
+```bash
+generate-ui generate
+```
 
-1. Read the OpenAPI and generate `screens.json`
-2. Generate Angular code from `screens.json`
+3. Review generated files in `src/generate-ui/overlays`.
+4. If needed, review generated vs override changes:
 
-## 1) Generate `screens.json`
+```bash
+generate-ui merge --feature ProductsAdmin
+```
+
+Advanced commands:
+- `generate-ui schema` -> generate schemas only
+- `generate-ui angular` -> regenerate Angular from existing schemas (`--no-watch` to run once)
+
+## 1) Default Full Generation
 
 ```bash
-generate-ui generate --openapi openapiWeather.yaml
+generate-ui generate
 ```
 
+`generate-ui generate` reads paths from `generateui-config.json` when available.
+
 What happens after this command:
 
 - GenerateUI reads your OpenAPI and detects endpoints.
@@ -78,20 +129,51 @@ What you should review now:
 
 Tip: this is the best moment to adjust naming and structure before generating code.
 
-## 2) Generate Angular code from `screens.json`
+## 2) Advanced Commands
 
 ```bash
+generate-ui schema
 generate-ui angular
 ```
 
-What happens after this command:
+What they do:
+
+- `schema` generates or updates `generated/` and `overlays/` from OpenAPI.
+- `angular` regenerates Angular output from existing overlays.
+- `angular` keeps live sync while editing `*.screen.json` (use `--no-watch` to run once).
 
-- For each screen defined in `screens.json`, GenerateUI creates:
+For each screen defined in overlays, Angular generation creates:
   - a feature folder
   - list and form components (create/edit)
   - a typed API service
   - DTO/types files
   - route definitions
+  - `menu.json` and `menu.gen.ts` (if present in `generate-ui/`)
+
+Generated/overrides folders:
+
+- `features/generated/` → generated code (always overwritten)
+- `features/overrides/` → your custom edits (never overwritten)
+
+Routes prefer `overrides/` when a matching file exists.
+
+Tip: when you regenerate and want to see what changed, compare files with:
+
+```bash
+diff -u features/generated/<Feature>/<Feature>.component.ts \
+  features/overrides/<Feature>/<Feature>.component.ts
+```
+
+Interactive merge (pick which changes to keep):
+
+```bash
+generate-ui merge --feature ProductsAdmin
+```
+
+Options:
+
+- `--file component.ts|component.html|component.scss|all`
+- `--tool code|meld|kdiff3|bc` (default: `code`)
 
 What you should review now:
 
@@ -103,24 +185,93 @@ What you should review now:
 Note:
 If your project uses custom routing, standalone components, or advanced layouts, you may need to adjust how routes are plugged in.
 
-Defaults:
-- `--schemas` defaults to the last generated path (stored in `~/.generateui/config.json`), otherwise `./src/generate-ui` (or `./frontend/src/generate-ui` / `./generate-ui`)
-- `--features` defaults to `./src/app/features` when `./src/app` exists; otherwise it errors and asks for `--features`
+Defaults (for advanced commands):
+- `--schemas` defaults to the last generated path (stored in `~/.generateui/config.json`), otherwise `./src/generate-ui` (or `./generate-ui`)
+- `--features` defaults to `./src/app/features`
+- Generated files are placed under `features/generated/` and your manual edits go in `features/overrides/`
 
-Optional paths:
+## Smart admin screens (Dev plan)
 
-```bash
-generate-ui angular \
-  --schemas /path/to/generate-ui \
-  --features /path/to/angular/features
+When you are logged in and Dev features are enabled, GenerateUI creates **one Admin screen per entity** when it finds a collection GET endpoint.
+
+Example:
+
+- `GET /products` → `ProductsAdmin`
+- `GET /users` → `UsersAdmin`
+
+If the API also includes:
+
+- `GET /entity/{id}` → the Admin list links to a Detail screen
+- `PUT/PATCH /entity/{id}` → the Admin list links to Edit
+- `DELETE /entity/{id}` → Delete actions with confirmation modal
+
+The Admin list is generated in addition to the basic screens (list, get by id, create, update, delete). It is never a replacement.
+
+### generateui-config.json
+
+GenerateUI creates a `generateui-config.json` at your project root on first `generate`. You can edit it to:
+
+- inject a sidebar menu layout automatically (when `menu.autoInject` is not `false`)
+- add a default redirect for `/` using `defaultRoute`
+- show a custom app title in the menu (`appTitle`)
+
+Example:
+
+```json
+{
+  "openapi": "openapi.yaml",
+  "schemas": "src/generate-ui",
+  "features": "src/app/features",
+  "appTitle": "Store",
+  "defaultRoute": "",
+  "menu": {
+    "autoInject": true
+  },
+  "views": {
+    "ProductsAdmin": "cards",
+    "getProducts": "list",
+    "CharacterAdmin": "cards"
+  }
+}
 ```
 
-Custom output folder for `generate`:
+Notes:
+- If `menu.autoInject` is `false`, the menu layout is not injected.
+- `defaultRoute` must match a path in `routes.gen.ts` (the same path used by the router).
+- You can provide either the final route path or an `operationId`; the generator normalizes it to the correct path.
+- You can override the menu by adding `menu.overrides.json` inside your `generate-ui/` folder (it replaces the generated menu entirely).
+- You can choose a default list view per screen (table vs cards) by adding a `views` map:
+
+```json
+{
+  "views": {
+    "ProductsAdmin": "cards",
+    "GetProducts": "table"
+  }
+}
+```
 
-```bash
-generate-ui generate --openapi youropenapi.yaml --output /path/to/generate-ui
+Example `menu.overrides.json`:
+
+```json
+{
+  "groups": [
+    {
+      "id": "cadastros",
+      "label": "Cadastros",
+      "items": [
+        { "id": "GetCharacter", "label": "Personagens", "route": "getCharacter" },
+        { "id": "GetLocation", "label": "Localizações", "route": "getLocation" }
+      ]
+    }
+  ],
+  "ungrouped": [
+    { "id": "GetEpisode", "label": "Episódios", "route": "getEpisode" }
+  ]
+}
 ```
 
+
 ## Login (Dev plan)
 
 ```bash
@@ -142,7 +293,7 @@ Telemetry can be disabled by setting `telemetry=false` in `~/.generateui/config.
 
 GenerateUI usually creates route files such as:
 
-- `src/generate-ui/routes.gen.ts` or `frontend/src/generate-ui/routes.gen.ts` or `generate-ui/routes.gen.ts`
+- `src/generate-ui/routes.gen.ts` or `generate-ui/routes.gen.ts`
 
 Example (Angular Router):
 
@@ -168,7 +319,7 @@ Step-by-step:
 1) Generate files:
 
 ```bash
-generate-ui generate --openapi /path/to/openapi.yaml
+generate-ui generate
 generate-ui angular
 ```
 
@@ -203,13 +354,13 @@ npm ls @angular/router
 ## Example Generated Structure
 
 ```txt
-src/generate-ui/ or frontend/src/generate-ui/ or generate-ui/
+src/generate-ui/ or generate-ui/
   generated/
   overlays/
   routes.json
   routes.gen.ts
   screens.json
-frontend/src/app/features/
+src/app/features/
   users/
     users.component.ts
     users.service.gen.ts
@@ -236,15 +387,54 @@ You can edit files inside `overlays/` to customize labels, placeholders, hints,
 
 Even after the Angular TypeScript files are generated, changes you make in `overlays/` will be mirrored the next time you regenerate.
 
+
+### Theme / colors / fonts (quick change)
+
+The generated UI uses CSS variables. To update the entire app theme at once, edit your app's root `styles.css`:
+
+```css
+:root {
+  --bg-page: #f7f3ef;
+  --bg-surface: #ffffff;
+  --bg-ink: #0f172a;
+  --color-text: #111827;
+  --color-muted: #6b7280;
+  --color-primary: #0f766e;
+  --color-primary-strong: #0891b2;
+  --color-accent: #f97316;
+  --shadow-card: 0 24px 60px rgba(15, 23, 42, 0.12);
+}
+```
+
+Changing these variables updates buttons, cards, menu, inputs, and backgrounds across the app.
+
+#### Fonts
+
+Fonts are defined in `styles.css` as well. You can:
+
+- swap the Google Fonts import at the top, and
+- update the `font-family` on `body`.
+
+Example:
+
+```css
+@import url("https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700&display=swap");
+
+body {
+  font-family: "Manrope", "Helvetica Neue", Arial, sans-serif;
+}
+```
+
 ## Common Issues and Fixes
 
-### "required option '-o, --openapi <path>' not specified"
+### "Missing OpenAPI file"
 
-You ran the command without passing the OpenAPI file.
+`generate-ui generate` did not find `openapi` in `generateui-config.json`.
 
 Fix:
 ```bash
-generate-ui generate --openapi /path/to/openapi.yaml
+# set "openapi" in generateui-config.json and run:
+generate-ui generate
 ```
 
 ### "An endpoint exists but no screen was generated"
@@ -292,7 +482,6 @@ Check:
 - [ ] Layout presets (minimal / enterprise / dashboard)
 - [ ] Design system adapters (Material / PrimeNG / custom)
 - [ ] Filters and real pagination
-- [ ] UI schema overrides (visual control without touching OpenAPI)
 - [ ] React support
 
 ## Contributing