@rxap/schematic-angular 19.1.1-dev.3 → 19.2.0-dev.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [19.2.0-dev.0](https://gitlab.com/rxap/packages/compare/@rxap/schematic-angular@19.1.1-dev.3...@rxap/schematic-angular@19.2.0-dev.0) (2026-01-13)
+
+### Features
+
+- **docs:** add custom template support in column and control guides ([25b56e0](https://gitlab.com/rxap/packages/commit/25b56e01eb6acb6fc6482f14718c148d19d14380))
+- **docs:** add detailed schematic guides for Angular components ([c2e0da8](https://gitlab.com/rxap/packages/commit/c2e0da80662274620d2e0d4120c317d240c80a38))
+- **docs:** enhance table column, action, and form control guides ([c4e1b66](https://gitlab.com/rxap/packages/commit/c4e1b66256c608044d5634f4bfa82d36a1832cfe))
+- **schematics:** add examples for accordion and table components ([c1125e0](https://gitlab.com/rxap/packages/commit/c1125e0e2a99c1a6f685a1cbbf9dcf548ba6744f))
+
 ## [19.1.1-dev.3](https://gitlab.com/rxap/packages/compare/@rxap/schematic-angular@19.1.1-dev.2...@rxap/schematic-angular@19.1.1-dev.3) (2025-09-18)
 
 **Note:** Version bump only for package @rxap/schematic-angular

package/GUIDES.md

@@ -0,0 +1,160 @@
+# Developer Guide: Generating Angular Material Tables & NestJS Controllers with @rxap/schematics
+
+This guide explains how to use `@rxap/schematic-composer` in conjunction with `@rxap/schematic-angular` to auto-generate an Angular Material table component and its corresponding NestJS controller.
+
+## Overview
+
+The process involves creating a declarative configuration file (`schematic.yaml`) that defines the table structure and backend requirements. The `@rxap/schematic-composer:compose` generator reads this file and executes the `@rxap/schematic-angular:table-component` schematic with the provided options.
+
+> [!TIP]
+> For more detailed information on all available options, check out the [Detailed Table Component Guide](./src/guides/table-component.md).
+
+> [!TIP]
+> Need to create forms? Check out the [Form Component Guide](./src/guides/form-component.md) and [Form Control Guide](./src/guides/form-control.md).
+
+
+## Prerequisites
+
+Ensure you have the following packages in your Nx workspace:
+- `@rxap/schematic-composer`
+- `@rxap/schematic-angular`
+
+## step 1: Create `schematic.yaml`
+
+Create a `schematic.yaml` file in your feature directory (e.g., `libs/feature/user/src/lib/schematic.yaml`). This file tells the composer which schematics to run.
+
+### File Structure
+
+The file expects an array of schematic definitions. Each definition contains:
+
+- **package**: The npm package containing the schematic (e.g., `@rxap/schematic-angular`).
+- **name**: The name of the schematic to run (e.g., `table-component`).
+- **options**: The configuration object passed to the schematic.
+
+## Step 2: Configure the Table Component
+
+To generate both the **Angular Table** and the **NestJS Controller**, you must configure the `table-component` options correctly.
+
+### Key Options
+
+| Option | Description | Required | Example |
+| :--- | :--- | :--- | :--- |
+| `name` | The name of the component/entity. | Yes | `user-list` |
+| `project` | The name of the *frontend* project. | Inferred* | `admin-panel` |
+| `feature` | The feature module name where the component belongs. | Inferred* | `user` |
+| `nestModule` | The name of the **NestJS module** where the controller should be created. | **Yes** (for backend) | `api-user` |
+| `backend` | Configuration for data handling. Setup for NestJS generation. | **Yes** | `{ kind: 'nestjs' }` |
+| `columnList` | Array of columns to display. | Yes | `[{ name: 'email', kind: 'text' }]` |
+
+*\*Inferred when using the `--file` option with the composer generator.*
+
+
+### Backend Configuration (Critical)
+
+To trigger the generation of a NestJS controller, you must set the `backend` option to `nestjs` and provide the `nestModule`.
+
+```yaml
+backend:
+  kind: nestjs
+  # Optional: Specify backend project if different from context
+  # project: api-app 
+  # Optional: OpenAPI server ID
+  # serverId: main 
+nestModule: api-user
+# controllerName: user # Optional: overrides default controller name
+```
+
+This configuration tells the schematic to:
+1.  Create a standard Angular Material Table.
+2.  Generate/Update a NestJS Controller in the specified `nestModule` (`api-user`).
+3.  Create a `getPage` method in the controller to handle pagination, sorting, and filtering.
+4.  Connect the Angular table data source to this backend endpoint automatically.
+
+## Example `schematic.yaml`
+
+Here is a complete example that generates a "User Table" with:
+-   Columns: ID, Email, Name
+-   Backend: NestJS Controller in `api-user` module
+-   Frontend: `admin-panel` project, `user` feature
+
+```yaml
+- package: "@rxap/schematic-angular"
+  name: table-component
+  options:
+    # --- Frontend Location ---
+    project: admin-panel
+    feature: user
+    name: user-list
+    
+    # --- Backend Configuration ---
+    # This triggers the NestJS controller generation
+    backend:
+      kind: nestjs
+    nestModule: api-user
+    # Optional: explicitly set controller name if different from 'name'
+    # controllerName: user 
+    
+    # --- Table Structure ---
+    columnList:
+      - name: id
+        kind: text
+        label: ID
+      - name: email
+        kind: text
+        label: Email Address
+      - name: name
+        kind: text
+        label: Full Name
+    
+    # --- Optional: Filters & Actions ---
+    filterList:
+      - name: email
+        kind: input
+        label: Filter by Email
+    
+    actionList:
+      - name: edit
+        type: icon
+        icon: edit
+        tooltip: Edit User
+```
+
+## Step 3: Run the Generator
+
+The easiest and recommended way to execute your `schematic.yaml` is by using the `--file` option. This allows the generator to automatically infer the **project**, **feature**, and **target directory** from the file's location.
+
+```bash
+yarn nx generate @rxap/schematic-composer:compose --file libs/feature/user/src/lib/schematic.yaml
+```
+
+> [!NOTE]
+> When using the `--file` option, you can typically omit `project`, `feature`, and `directory` from your `schematic.yaml` file, as they will be detected based on the path provided.
+
+### Alternative: Search by Directory
+
+If you want the generator to search for all `schematic.yaml` files within a directory tree:
+
+```bash
+yarn nx generate @rxap/schematic-composer:compose --directory libs/feature/user/src/lib
+```
+
+**Arguments:**
+-   `--file`: (Primary) The direct path to your `schematic.yaml`.
+-   `--directory`: A starting directory to search for one or more `schematic.yaml` files.
+-   `--filter`: (Optional) If searching via directory, filter for schematic files within a specific sub-folder name.
+
+
+## Important Notes for AI Agents
+
+When generating code for users:
+
+1.  **Prefer the `--file` option:** When executing the composer, always use the `--file` argument with the path to the `schematic.yaml` you just created.
+2.  **Target Locations:** Even though `--file` infers locations, ensure the `schematic.yaml` itself is placed in the correct logical feature directory of the workspace.
+3.  **Identify the Backend Module:** Ask the user or search for the NestJS module (`nestModule`) that should own the backend logic.
+4.  **Backend Integration:** Ensure `backend: { kind: 'nestjs' }` and `nestModule` are correctly set to enable controller generation.
+
+
+## Troubleshooting
+
+-   **Controller not generated?** Check if `backend.kind` is set to `nestjs` and `nestModule` is specified and exists.
+-   **"Module not found" errors?** Ensure the `nestModule` name matches the library name in `nx.json` or `project.json`.

package/README.md

@@ -8,6 +8,7 @@ Provides schematics for generating Angular components, services, and related fil
 ![NPM](https://img.shields.io/npm/l/@rxap/schematic-angular)
 
 - [Installation](#installation)
+- [Guides](#guides)
 
 # Installation
 
@@ -15,3 +16,166 @@ Provides schematics for generating Angular components, services, and related fil
 ```bash
 yarn add @rxap/schematic-angular
 ```
+# Guides
+
+# Developer Guide: Generating Angular Material Tables & NestJS Controllers with @rxap/schematics
+
+This guide explains how to use `@rxap/schematic-composer` in conjunction with `@rxap/schematic-angular` to auto-generate an Angular Material table component and its corresponding NestJS controller.
+
+## Overview
+
+The process involves creating a declarative configuration file (`schematic.yaml`) that defines the table structure and backend requirements. The `@rxap/schematic-composer:compose` generator reads this file and executes the `@rxap/schematic-angular:table-component` schematic with the provided options.
+
+> [!TIP]
+> For more detailed information on all available options, check out the [Detailed Table Component Guide](./src/guides/table-component.md).
+
+> [!TIP]
+> Need to create forms? Check out the [Form Component Guide](./src/guides/form-component.md) and [Form Control Guide](./src/guides/form-control.md).
+
+
+## Prerequisites
+
+Ensure you have the following packages in your Nx workspace:
+- `@rxap/schematic-composer`
+- `@rxap/schematic-angular`
+
+## step 1: Create `schematic.yaml`
+
+Create a `schematic.yaml` file in your feature directory (e.g., `libs/feature/user/src/lib/schematic.yaml`). This file tells the composer which schematics to run.
+
+### File Structure
+
+The file expects an array of schematic definitions. Each definition contains:
+
+- **package**: The npm package containing the schematic (e.g., `@rxap/schematic-angular`).
+- **name**: The name of the schematic to run (e.g., `table-component`).
+- **options**: The configuration object passed to the schematic.
+
+## Step 2: Configure the Table Component
+
+To generate both the **Angular Table** and the **NestJS Controller**, you must configure the `table-component` options correctly.
+
+### Key Options
+
+| Option | Description | Required | Example |
+| :--- | :--- | :--- | :--- |
+| `name` | The name of the component/entity. | Yes | `user-list` |
+| `project` | The name of the *frontend* project. | Inferred* | `admin-panel` |
+| `feature` | The feature module name where the component belongs. | Inferred* | `user` |
+| `nestModule` | The name of the **NestJS module** where the controller should be created. | **Yes** (for backend) | `api-user` |
+| `backend` | Configuration for data handling. Setup for NestJS generation. | **Yes** | `{ kind: 'nestjs' }` |
+| `columnList` | Array of columns to display. | Yes | `[{ name: 'email', kind: 'text' }]` |
+
+*\*Inferred when using the `--file` option with the composer generator.*
+
+
+### Backend Configuration (Critical)
+
+To trigger the generation of a NestJS controller, you must set the `backend` option to `nestjs` and provide the `nestModule`.
+
+```yaml
+backend:
+  kind: nestjs
+  # Optional: Specify backend project if different from context
+  # project: api-app 
+  # Optional: OpenAPI server ID
+  # serverId: main 
+nestModule: api-user
+# controllerName: user # Optional: overrides default controller name
+```
+
+This configuration tells the schematic to:
+1.  Create a standard Angular Material Table.
+2.  Generate/Update a NestJS Controller in the specified `nestModule` (`api-user`).
+3.  Create a `getPage` method in the controller to handle pagination, sorting, and filtering.
+4.  Connect the Angular table data source to this backend endpoint automatically.
+
+## Example `schematic.yaml`
+
+Here is a complete example that generates a "User Table" with:
+-   Columns: ID, Email, Name
+-   Backend: NestJS Controller in `api-user` module
+-   Frontend: `admin-panel` project, `user` feature
+
+```yaml
+- package: "@rxap/schematic-angular"
+  name: table-component
+  options:
+    # --- Frontend Location ---
+    project: admin-panel
+    feature: user
+    name: user-list
+    
+    # --- Backend Configuration ---
+    # This triggers the NestJS controller generation
+    backend:
+      kind: nestjs
+    nestModule: api-user
+    # Optional: explicitly set controller name if different from 'name'
+    # controllerName: user 
+    
+    # --- Table Structure ---
+    columnList:
+      - name: id
+        kind: text
+        label: ID
+      - name: email
+        kind: text
+        label: Email Address
+      - name: name
+        kind: text
+        label: Full Name
+    
+    # --- Optional: Filters & Actions ---
+    filterList:
+      - name: email
+        kind: input
+        label: Filter by Email
+    
+    actionList:
+      - name: edit
+        type: icon
+        icon: edit
+        tooltip: Edit User
+```
+
+## Step 3: Run the Generator
+
+The easiest and recommended way to execute your `schematic.yaml` is by using the `--file` option. This allows the generator to automatically infer the **project**, **feature**, and **target directory** from the file's location.
+
+```bash
+yarn nx generate @rxap/schematic-composer:compose --file libs/feature/user/src/lib/schematic.yaml
+```
+
+> [!NOTE]
+> When using the `--file` option, you can typically omit `project`, `feature`, and `directory` from your `schematic.yaml` file, as they will be detected based on the path provided.
+
+### Alternative: Search by Directory
+
+If you want the generator to search for all `schematic.yaml` files within a directory tree:
+
+```bash
+yarn nx generate @rxap/schematic-composer:compose --directory libs/feature/user/src/lib
+```
+
+**Arguments:**
+-   `--file`: (Primary) The direct path to your `schematic.yaml`.
+-   `--directory`: A starting directory to search for one or more `schematic.yaml` files.
+-   `--filter`: (Optional) If searching via directory, filter for schematic files within a specific sub-folder name.
+
+
+## Important Notes for AI Agents
+
+When generating code for users:
+
+1.  **Prefer the `--file` option:** When executing the composer, always use the `--file` argument with the path to the `schematic.yaml` you just created.
+2.  **Target Locations:** Even though `--file` infers locations, ensure the `schematic.yaml` itself is placed in the correct logical feature directory of the workspace.
+3.  **Identify the Backend Module:** Ask the user or search for the NestJS module (`nestModule`) that should own the backend logic.
+4.  **Backend Integration:** Ensure `backend: { kind: 'nestjs' }` and `nestModule` are correctly set to enable controller generation.
+
+
+## Troubleshooting
+
+-   **Controller not generated?** Check if `backend.kind` is set to `nestjs` and `nestModule` is specified and exists.
+-   **"Module not found" errors?** Ensure the `nestModule` name matches the library name in `nx.json` or `project.json`.
+

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "19.1.1-dev.3",
+  "version": "19.2.0-dev.0",
   "name": "@rxap/schematic-angular",
   "description": "Provides schematics for generating Angular components, services, and related files, particularly focused on creating tables, forms, data grids, and accordions with NestJS integration. It offers tools for generating UI elements with backend connectivity, including data sources, methods, and form handling. This package aims to streamline the development of data-driven Angular applications with a focus on material design and backend integration.\n",
   "license": "GPL-3.0-or-later",
@@ -7,12 +7,12 @@
     "@angular-devkit/core": "19.2.1",
     "@angular-devkit/schematics": "19.2.1",
     "@nx/devkit": "20.5.0",
-    "@rxap/schematics-ts-morph": "^19.1.1-dev.3",
-    "@rxap/schematics-utilities": "^19.0.5-dev.2",
-    "@rxap/ts-morph": "^1.6.0-dev.2",
-    "@rxap/utilities": "^16.5.0-dev.0",
-    "@rxap/workspace-ts-morph": "^19.1.13-dev.3",
-    "@rxap/workspace-utilities": "^19.8.1-dev.2",
+    "@rxap/schematics-ts-morph": "^19.1.1-dev.4",
+    "@rxap/schematics-utilities": "^19.0.5-dev.3",
+    "@rxap/ts-morph": "^1.6.0-dev.3",
+    "@rxap/utilities": "^16.5.0-dev.1",
+    "@rxap/workspace-ts-morph": "^19.1.13-dev.4",
+    "@rxap/workspace-utilities": "^19.8.1-dev.3",
     "colors": "1.4.0",
     "handlebars": "^4.7.8",
     "ts-morph": "18.0.0",
@@ -45,7 +45,7 @@
   },
   "schematics": "./collection.json",
   "type": "commonjs",
-  "gitHead": "ef20bc50270ad0727a111d54e48cb279ff3ed5cf",
+  "gitHead": "69d6ee61a20632f52b77de621089334a34f45e03",
   "types": "./src/index.d.ts",
   "main": "./src/index.js"
 }

package/src/examples/feature/dashboard/dashboard-accordion/schematics.yaml

@@ -0,0 +1,226 @@
+package: "@rxap/schematic-angular"
+name: accordion-component
+options:
+  name: dashboard
+  backend: nestjs
+  multiple: true
+  header:
+    property:
+      name: name
+  persistent:
+    property:
+      name: uuid
+  identifier:
+    source: route
+    property:
+      name: uuid
+  upstream:
+    kind: open-api
+    operationId: dashboard-controller-getByUuid@legacy
+  propertyList:
+    - name: dashboardType
+      type: number
+      source: "dashboardType!"
+    - name: name
+      source: "name!"
+  itemList:
+    - name: general-information
+      kind: switch
+      switch:
+        property:
+          name: dashboardType
+          type: number
+        defaultCase:
+          itemList:
+            - kind: data-grid
+              name: dashboard
+              title: Allgemeine Informationen
+              propertyList:
+                - name: name
+                  type: string
+                  source: "name!"
+                - name: location
+                  source: "location?.uuid!"
+                  type: string
+                - name: link
+                  source: "link!"
+                  type: string
+                - name: company
+                  source: "company?.uuid!"
+                  type: string
+                - name: dashboardType
+                  source: "dashboardType!"
+                  type: number
+              upstream:
+                kind: open-api
+                operationId: dashboard-controller-getByUuid@legacy
+              dataGrid:
+                itemList:
+                  - name: name
+                    hasCellDef: true
+                    formControl:
+                      kind: input
+                  - name: location
+                    pipeList:
+                      - name: company
+                        namedImport: CompanyPipe
+                        moduleSpecifier: "@digitaix/eurogard-pipes"
+                      - async
+                      - getFromObject:name
+                    formControl:
+                      kind: autocomplete-table-select
+                      backend: nestjs
+                      toValue:
+                        property:
+                          name: uuid
+                      columnList:
+                        - name: name
+                          hasFilter: true
+                      resolver:
+                        upstream:
+                          kind: open-api
+                          operationId: company-gui-controller-getByUuid@legacy
+                          mapper:
+                            kind: resolve
+                            value: uuid
+                      upstream:
+                        kind: open-api
+                        operationId: company-gui-controller-getByFilter@legacy
+                        mapper:
+                          kind: paged
+                          pageIndex: page
+                          pageSize: size
+                          sortBy: sort
+                          sortDirection: order
+                          list: entities
+                          total: maxCount
+                          filter:
+                            eq: ':'
+                            join: ';'
+                  - name: link
+                    kind: link
+                    target: _blank
+                    formControl:
+                      kind: input
+                      inputType: url
+                  - name: company
+                    type: string
+                    isReadonly: true
+                    pipeList:
+                      - name: company
+                        namedImport: CompanyPipe
+                        moduleSpecifier: "@digitaix/eurogard-pipes"
+                      - async
+                      - "getFromObject:'name'"
+                  - name: dashboardType
+                    header: Typ
+                    type: number
+                    isReadonly: true
+                    pipeList:
+                      - name: toDashboardTypesEnumValue
+                        namedImport: ToDashboardTypesEnumValuePipe
+                        moduleSpecifier: enum
+                      - async
+        case:
+          - test: 2
+            itemList:
+              - kind: data-grid
+                name: cloud-dashboard
+                title: Allgemeine Informationen
+                propertyList:
+                  - name: name
+                    type: string
+                    source: "name!"
+                  - name: company
+                    source: "company?.uuid!"
+                    type: string
+                  - name: dashboardType
+                    source: "dashboardType!"
+                    type: number
+                upstream:
+                  kind: open-api
+                  operationId: dashboard-controller-getByUuid@legacy
+                dataGrid:
+                  itemList:
+                    - name: name
+                      hasCellDef: true
+                      formControl:
+                        kind: input
+                    - name: company
+                      type: string
+                      isReadonly: true
+                      pipeList:
+                        - name: company
+                          namedImport: CompanyPipe
+                          moduleSpecifier: "@digitaix/eurogard-pipes"
+                        - async
+                        - "getFromObject:'name'"
+                    - name: dashboardType
+                      header: Typ
+                      type: number
+                      isReadonly: true
+                      pipeList:
+                        - name: toDashboardTypesEnumValue
+                          namedImport: ToDashboardTypesEnumValuePipe
+                          moduleSpecifier: enum
+                        - async
+    - name: layout
+      kind: switch
+      permission: dashboard.layout.get
+      switch:
+        property:
+          name: dashboardType
+          type: number
+        case:
+          - test: 2
+            itemList:
+              - name: cloud-dashboard
+                upstream:
+                  kind: open-api
+                  operationId: dashboard-controller-getByUuid@legacy
+                kind: default
+                title: Layouts
+                propertyList:
+                  - name: layoutList
+                    isArray: true
+                    source: "layoutList!"
+    - name: reference
+      kind: tree-table
+      title: Zuordnung
+      table:
+        cssClass:
+          - "!min-w-0"
+        propertyList:
+          - name: referenceUuid
+          - name: type
+        columnList:
+          - name: isReferenced
+            cssClass:
+              - "!w-[200px]"
+              - "min-w-[200px]"
+              - "max-w-[200px]"
+            kind: component
+            filterControl:
+              kind: select
+              formField:
+                cssClass:
+                  - "w-[200px]"
+          - name: name
+            filterControl:
+              kind: input
+            cssClass:
+              - "w-[500px]"
+              - "max-w-[500px]"
+              - "min-w-[250px]"
+            type: string
+            kind: default
+          - name: scopeType
+            cssClass:
+              - "!w-[280px]"
+              - "min-w-[280px]"
+              - "max-w-[280px]"
+            type: number
+            kind: component
+            filterControl:
+              kind: select
+              backend: nestjs