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

package/src/guides/form-control.md

@@ -0,0 +1,269 @@
+# Form Control Guide
+
+Form controls define the inputs and fields within a form.
+
+## Base Configuration
+
+All controls share these common properties (inheriting from `abstract-control`):
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `string` | The control name (key in the form value). |
+| `label` | `string` | The label displayed to the user. |
+| `kind` | `string` | The type of control (e.g., `input`, `select`). |
+| `isRequired` | `boolean` | Whether the field is mandatory. |
+| `isDisabled` | `boolean` | Whether the control is disabled by default. |
+| `isReadonly` | `boolean` | Whether the control is read-only. |
+| `state` | `any` | The initial value/state of the control. |
+| `validatorList` | `array<string>` | List of Angular validators (e.g., `['required', 'email']`). |
+| `cssClass` | `string` | Custom CSS classes for the control. |
+| `template` | `string` | Path to a custom Handlebars template file. |
+
+## Form Field Options
+
+Controls that render within a Material Form Field (Input, Select, Date, etc.) support additional options:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `hasClearButton` | `boolean` | Adds a button to clear the input value. |
+| `prefixButton` | `object` | Adds a button/icon to the start of the field. |
+| `suffixButton` | `object` | Adds a button/icon to the end of the field. |
+
+### Example: Input with Icon and Clear Button
+```yaml
+- name: search
+  kind: input
+  label: Search
+  hasClearButton: true
+  formField:
+    prefixButton:
+      icon: search
+```
+
+## Control Kinds
+
+### Input
+
+Standard text input field.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `inputType` | `string` | HTML input type (e.g., `text`, `password`, `email`). Default: `text`. |
+| `placeholder` | `string` | Placeholder text. |
+
+```yaml
+- name: email
+  kind: input
+  inputType: email
+  label: Email Address
+  placeholder: Enter your email
+  isRequired: true
+```
+
+### Select
+
+Dropdown selection control.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `multiple` | `boolean` | Allow multiple selections. |
+| `optionList` | `array` | Static list of options. |
+| `upstream` | `object` | Load options from an API. See [Upstream Guide](./upstream.md). |
+
+```yaml
+- name: role
+  kind: select
+  label: User Role
+  options:
+    - value: admin
+      display: Administrator
+    - value: user
+      display: Standard User
+```
+
+
+### Checkbox
+
+Boolean checkbox control.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `labelPosition` | `string` | Valid values: `before`, `after`. |
+
+```yaml
+- name: isActive
+  kind: checkbox
+  label: Active
+  state: true
+```
+
+### Textarea
+
+Multi-line text input.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `minRows` | `number` | Minimum number of rows. |
+| `maxRows` | `number` | Maximum number of rows. |
+
+```yaml
+- name: description
+  kind: textarea
+  label: Description
+  autosize:
+    minRows: 3
+```
+
+### Date
+
+Date picker control.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `placeholder` | `string` | Placeholder text. |
+
+```yaml
+- name: birthday
+  kind: date
+  label: Birthday
+  placeholder: Select a date
+```
+
+### Slide Toggle
+
+Material design slide toggle.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `labelPosition` | `string` | Valid values: `before`, `after`. |
+
+```yaml
+- name: notifications
+  kind: slide-toggle
+  label: Enable Notifications
+```
+
+### Autocomplete
+
+Input with autocomplete suggestions.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `upstream` | `object` | Source for suggestion data. See [Upstream Guide](./upstream.md). |
+| `toDisplay` | `object` | Property to use for display label. |
+| `toValue` | `object` | Property to use for the control value. |
+
+```yaml
+- name: city
+  kind: autocomplete
+  label: City
+  upstream:
+    kind: open-api
+    operationId: searchCities
+  toDisplay:
+    property: name
+  toValue:
+    property: id
+```
+
+### Table Select
+
+Opens a dialog with a table to select an item.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `title` | `string` | Title of the selection window. |
+| `columnList` | `array` | Columns to display in the selection table. |
+| `upstream` | `object` | Data source for the table. See [Upstream Guide](./upstream.md). |
+
+```yaml
+- name: project
+  kind: table-select
+  label: Project
+  upstream:
+    kind: open-api
+    operationId: listProjects
+  columnList:
+    - name: name
+```
+
+### Autocomplete Table Select
+
+Combines autocomplete with table selection.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `title` | `string` | Title of the selection window. |
+| `columnList` | `array` | Columns to display in the selection table. |
+| `upstream` | `object` | Data source. See [Upstream Guide](./upstream.md). |
+
+```yaml
+- name: company
+  kind: autocomplete-table-select
+  backend: nestjs
+  formField:
+    cssClass: "w-[500px]"
+  toValue:
+    property: uuid
+  columnList:
+    - name: name
+      hasFilter: true
+  resolver:
+    upstream:
+      kind: open-api
+      operationId: company-getByUuid
+      mapper:
+        kind: resolve
+        value: uuid
+  upstream:
+    kind: open-api
+    operationId: company-getFilter
+    mapper:
+      kind: paged
+      pageIndex: page
+      pageSize: size
+      sortBy: sort
+      sortDirection: order
+      list: entities
+      total: maxCount
+```
+
+## Custom Templates
+
+You can provide a custom Handlebars template for any control using the `template` property. This allows full control over the generated HTML for that specific form field.
+
+```yaml
+- name: customField
+  kind: input
+  template: libs/my-lib/src/templates/custom-input.hbs
+```
+
+
+## Validators
+
+Validators are defined as a list of strings mapped to Angular validators. You can also use regex patterns.
+
+```yaml
+validatorList:
+  - required
+  - email
+  - "pattern(/^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$/)"
+```
+
+## Advanced Upstream Configuration
+
+For controls like `select` or `autocomplete`, you often need to map data from an API.
+
+```yaml
+- name: type
+  kind: select
+  backend: nestjs
+  upstream:
+    kind: open-api
+    operationId: options-controller-getReportTypes
+    mapper:
+      kind: options
+      toFunction: ToOptionsFromObject
+      toValue: Number
+```
+

package/src/guides/header-button.md

@@ -0,0 +1,57 @@
+# Header Button Guide
+
+Header buttons are actions placed in the top section of the table component, typically used for global actions like "Create New", "Import", or "Export".
+
+## Button Kinds
+
+| Kind | Description |
+| :--- | :--- |
+| `default` | A standard button (default). |
+| `form` | Opens a form (usually in a dialog) when clicked. |
+| `navigation` | Navigates to a route when clicked. |
+| `method` | Calls a specific method when clicked. |
+
+## Configuration
+
+Header buttons share common properties with table actions.
+
+```yaml
+headerButton:
+  kind: form
+  icon: add
+  text: Create Project
+  options:
+    # Form configuration here
+```
+
+## Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `kind` | `string` | The type of button (alias: `role`). |
+| `icon` | `string` | Material icon name. |
+| `text` | `string` | The button label. |
+| `disabled`| `boolean`| Whether the button is disabled. |
+| `permission`| `string`| Required permission to see the button. |
+| `color` | `string` | Material color (e.g., `primary`, `accent`). |
+| `options` | `object` | Kind-specific configuration (e.g., form details). |
+
+## Examples
+
+### Navigation Header Button
+```yaml
+headerButton:
+  kind: navigation
+  icon: arrow_back
+  text: Back to Dashboard
+  route: /dashboard
+```
+
+### Method Header Button
+```yaml
+headerButton:
+  kind: method
+  icon: download
+  text: Export CSV
+  method: exportData
+```

package/src/guides/table-action.md

@@ -0,0 +1,120 @@
+# Table Action Guide
+
+Table actions allow users to perform operations on specific rows or on the table as a whole.
+
+## Row Actions
+
+Row actions are typically rendered in an "Actions" column at the end of the row.
+
+```yaml
+actionList:
+  - type: edit
+    icon: edit
+    tooltip: Edit User
+  - type: delete
+    icon: delete
+    confirm: true # Shows a confirmation dialog before executing
+```
+
+## Action Types
+
+The `type` property defines the behavior of the action.
+
+| Type | Description |
+| :--- | :--- |
+| `operation` | Generic operation, often linked to a backend method. |
+| `dialog` | Opens a dialog component. |
+| `navigation` | Navigates to a different route. |
+| `form` | Opens a form (often in a dialog) to edit/create data. |
+| `open-api` | Directly calls an OpenAPI operation. |
+
+## Common Properties
+
+| Property | Description |
+| :--- | :--- |
+| `icon` | Material icon name. |
+| `tooltip` | Text shown on hover. |
+| `confirm` | If `true`, requires user confirmation. |
+| `refresh` | If `true`, refreshes the table after completion. |
+| `inHeader` | If `true`, the action is placed in the table header (global action). |
+| `permission` | (Optional) Permission string required to see/execute the action. |
+| `checkFunction` | JavaScript expression string to dynamically check visibility (e.g. `!element.archived`). |
+| `color` | Angular Material color palette name (e.g. `primary`, `accent`, `warn`). |
+| `role` | (Alias: `kind`) The role of the action (e.g. `method`, `navigation`). |
+
+## Examples
+
+### Navigation Action
+```yaml
+- type: details
+  icon: visibility
+  role: navigation
+  options:
+    route: "/users/user/{{uuid}}/details"
+
+```
+
+### Header Action (e.g., Create New)
+```yaml
+- type: create
+  icon: add
+  inHeader: true
+  role: form
+```
+
+### Action with Confirmation
+```yaml
+- type: archive
+  icon: archive
+  confirm: true
+  color: warn
+  permission: user.archive
+  checkFunction: "!element.archived"
+  successMessage: "Item archived successfully"
+
+```
+
+## Form Actions
+
+You can use the `form` kind (or role) to open a form when an action is triggered. This is commonly used for "Create" or "Edit" actions.
+
+### Defining the Form
+
+You can define the form structure directly within the action using `formOptions`.
+
+```yaml
+- type: create
+  kind: form
+  icon: add
+  formOptions:
+    controlList:
+      - name: name
+        label: Name
+        required: true
+```
+
+### Pre-filling Data
+
+Use the `loadFrom` property to pre-fill the form with data from the row or an API call.
+
+- **From Row**: The form is automatically populated with the row data if `formInitial` is true.
+- **From API**:
+
+```yaml
+- type: edit
+  kind: form
+  icon: edit
+  loadFrom:
+    operationId: getUserDetails
+    parameters: true # Uses row data as parameters
+```
+
+### Saving Data
+
+The form submission is handled by an `operationId` (if connected to an API).
+
+```yaml
+formOptions:
+  submit:
+    operationId: updateUser
+```

package/src/guides/table-column.md

@@ -0,0 +1,185 @@
+# Table Column Guide
+
+Table columns define the data displayed in each column and how it's rendered.
+
+## Base Configuration
+
+All columns share these common properties:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `string` | The property name from the row data (Required). |
+| `title` | `string` | The header label. Defaults to `name` if not provided. |
+| `kind` | `string` | The type of column (e.g., `date`, `options`). Default: `text`. |
+| `sortable` | `boolean` | Enable sorting for this column. |
+| `hasFilter` | `boolean` | Enable filtering for this column. |
+| `hidden` | `boolean` | Initially hide the column. |
+| `nowrap` | `boolean` | Prevent text wrapping in cells. |
+| `cssClass` | `string` | Custom CSS class for the cell. |
+| `pipeList` | `array` | List of Angular pipes to apply to the value. |
+| `modifiers` | `array` | List of column modifiers. |
+| `template` | `string` | Path to a custom Handlebars template file. |
+| `filterControl` | `object` | Configuration for a custom filter input (e.g. specific CSS class). |
+
+## Column Kinds
+
+### Text (Default)
+
+Renders the value as plain text. You can use pipes to format the text.
+
+```yaml
+- name: email
+  title: Email Address
+  sortable: true
+```
+
+### Date
+
+Formats the value as a date.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `format` | `string` | The date format string (compatible with Angular's `date` pipe). |
+
+```yaml
+- name: createdAt
+  kind: date
+  title: Created Date
+  format: "dd.MM.yyyy HH:mm"
+```
+
+### Options
+
+Maps value codes to display labels. Useful for enums or status fields.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `optionList` | `array` | List of value-display pairs. |
+
+**Option Structure:**
+- `value`: The raw data value (string, number, boolean).
+- `display`: Text to display.
+
+```yaml
+- name: status
+  kind: options
+  optionList:
+    - value: ACTIVE
+      display: Active
+    - value: INACTIVE
+      display: Inactive
+```
+
+### Boolean
+
+Renders a standard check/close icon for boolean values.
+
+```yaml
+- name: verified
+  kind: boolean
+  title: Is Verified?
+```
+
+### Link
+
+Renders the value as a clickable link.
+
+```yaml
+- name: website
+  kind: link
+```
+
+### Icon
+
+Renders the value as a Material icon name.
+*Note: The value from the row data must be a valid icon name (e.g., 'home', 'settings').*
+
+```yaml
+- name: iconName
+  kind: icon
+```
+
+### Copy to Clipboard
+
+Renders the value with a button to copy it to the clipboard. Useful for IDs, tokens, or hashes.
+
+```yaml
+- name: apiKey
+  kind: copy-to-clipboard
+  title: API Key
+```
+
+### Component
+
+Renders a custom Angular component within the cell.
+*The component to be rendered is typically determined by convention or further configuration not detailed here.*
+
+```yaml
+- name: profile
+  kind: component
+```
+
+### Spinner
+
+Renders a loading spinner. Often used for columns tracking async operations or status.
+
+```yaml
+- name: isProcessing
+  kind: spinner
+```
+
+### Tree
+
+Used for the primary column in a Tree Table to display the hierarchy (expander icons/indentation).
+
+```yaml
+- name: name
+  kind: tree
+  title: Folder Name
+```
+
+### Custom
+
+Allows you to provide a custom HTML template directly in the config.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `html` | `string` | The HTML content to render in the cell. |
+
+```yaml
+- name: details
+  kind: custom
+  html: "<span class='badge'>{{ element.status }}</span>"
+```
+
+### Custom Template File
+
+For more complex customizations where inline HTML is insufficient, you can provide a path to a Handlebars template file.
+
+```yaml
+- name: fancyColumn
+  template: libs/shared/templates/fancy-cell.hbs
+```
+
+## Advanced Usage
+
+### Using Pipes
+
+You can apply multiple pipes to any column.
+
+```yaml
+- name: amount
+  pipeList:
+    - name: currency
+      args: ["EUR"]
+```
+
+### Column Modifiers
+
+Modifiers change the behavior of how columns are generated or displayed.
+
+```yaml
+- name: id
+  modifiers:
+    - primary-key
+```

package/src/guides/table-component.md

@@ -0,0 +1,51 @@
+# Table Component Schematic Guide
+
+The `table-component` schematic is used to generate a comprehensive Angular Material table component, optionally connected to a NestJS backend.
+
+## Basic Usage
+
+To generate a table component, you define it in a `schematic.yaml` or `schematic.json` file.
+
+```yaml
+- package: "@rxap/schematic-angular"
+  name: table-component
+  options:
+    name: user-list
+    project: admin-panel
+    feature: user
+    columnList:
+      - name: email
+      - name: name
+```
+
+## Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `string` | The name of the component and entity. |
+| `project` | `string` | The target project (frontend). |
+| `feature` | `string` | The feature module name. |
+| `nestModule` | `string` | (Optional) The NestJS module name for backend generation. |
+| `backend` | `object \| string` | [Backend Configuration](./backend.md) |
+| `columnList` | `array` | [Column Definitions](./table-column.md) |
+| `actionList` | `array` | [Action Definitions](./table-action.md) |
+| `filterList` | `array` | [Filter Definitions](./table-filter.md) |
+| `headerButton` | `object` | [Header Button Configuration](./header-button.md) |
+| `modifiers` | `array` | [Table Modifiers](./table-modifiers.md) |
+| `upstream` | `object` | [Upstream Configuration](./upstream.md) |
+| `sortable` | `boolean \| object` | Whether the table is sortable and its default state. |
+| `cssClass` | `string \| array \| object` | Custom CSS classes for the table. |
+| `selectColumn` | `boolean` | Whether to add a checkbox selection column. |
+| `fullWidth` | `boolean` | Whether the table should take the full width of its container. |
+
+## Detailed Guides
+
+Dive into specific options for more advanced configurations:
+
+- [**Table Columns**](./table-column.md): Learn about different column types (text, date, custom, etc.).
+- [**Table Actions**](./table-action.md): Add row actions like edit, delete, or custom operations.
+- [**Backend Configuration**](./backend.md): Connect your table to a NestJS or OpenAPI-based API.
+- [**Table Filters**](./table-filter.md): Add search and filter controls to your table.
+- [**Header Buttons**](./header-button.md): Add buttons to the table header for actions like "Create".
+- [**Table Modifiers**](./table-modifiers.md): Tweak the table behavior and appearance with modifiers.
+- [**Upstream Data**](./upstream.md): Configure data mapping and pagination for complex data sources.