primeng-forms-utils 0.1.0
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/README.md +212 -0
- package/package.json +45 -0
package/README.md
ADDED
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
# primeng-forms-utils
|
|
2
|
+
|
|
3
|
+
Biblioteca utilitaria para Angular + PrimeNG focada em formularios dinamicos.
|
|
4
|
+
|
|
5
|
+
## Objetivo
|
|
6
|
+
|
|
7
|
+
Centralizar a definicao de campos, validacoes, layout e saida de valor em uma configuracao TypeScript, evitando templates grandes e repetitivos nas paginas Angular.
|
|
8
|
+
|
|
9
|
+
## O que a biblioteca faz
|
|
10
|
+
|
|
11
|
+
- monta ou complementa um `FormGroup`;
|
|
12
|
+
- aplica validacoes declarativas e validadores Angular customizados;
|
|
13
|
+
- renderiza os componentes PrimeNG atuais, como `p-select`, `p-datepicker`, `pTextarea` e `p-inputNumber`;
|
|
14
|
+
- organiza os campos em grid de 12 colunas responsivo;
|
|
15
|
+
- suporta labels acima ou ao lado do campo;
|
|
16
|
+
- exibe asterisco antes da label quando o campo for obrigatorio;
|
|
17
|
+
- exibe dica rapida por meio de um icone com tooltip;
|
|
18
|
+
- suporta `text`, `number`, `money`, `percent`, `textarea`, `select`, `enum`, `image`, `date`, `radio` e `checkbox`;
|
|
19
|
+
- suporta grupos de `checkbox` com valor em array;
|
|
20
|
+
- suporta upload de imagem com preview local;
|
|
21
|
+
- persiste campos de data como string UTC no `FormControl`;
|
|
22
|
+
- permite customizar aparencia de campos por configuracao;
|
|
23
|
+
- resolve mensagens de erro via configuracao do campo, traducoes externas e fallback padrao.
|
|
24
|
+
|
|
25
|
+
## O que a biblioteca nao faz
|
|
26
|
+
|
|
27
|
+
- nao executa submit;
|
|
28
|
+
- nao persiste dados;
|
|
29
|
+
- nao toma decisoes de negocio;
|
|
30
|
+
- nao faz upload automatico de arquivos.
|
|
31
|
+
|
|
32
|
+
## Componentes principais
|
|
33
|
+
|
|
34
|
+
- `DynamicFormComponent`: componente raiz do formulario.
|
|
35
|
+
- `DynamicFieldComponent`: adaptador que escolhe qual componente PrimeNG renderizar.
|
|
36
|
+
- `DynamicFormBuilderService`: cria ou complementa `FormGroup`.
|
|
37
|
+
- `dynamic-field-config.ts`: contratos centrais da biblioteca.
|
|
38
|
+
|
|
39
|
+
## Layout padrao
|
|
40
|
+
|
|
41
|
+
- o formulario usa grid de 12 colunas;
|
|
42
|
+
- no mobile, cada campo ocupa `12/12`;
|
|
43
|
+
- a partir de `md`, se `colSpan` nao for informado, o campo ocupa `6/12`;
|
|
44
|
+
- quando a soma dos spans ultrapassa 12, o proximo campo quebra para a linha de baixo automaticamente;
|
|
45
|
+
- o espacamento entre campos e `8px`.
|
|
46
|
+
|
|
47
|
+
## Aparencia por campo
|
|
48
|
+
|
|
49
|
+
Cada campo pode receber um bloco opcional `appearance` para sobrescrever tokens visuais do PrimeNG no proprio campo.
|
|
50
|
+
|
|
51
|
+
Exemplo:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
appearance: {
|
|
55
|
+
borderColor: '#0f766e',
|
|
56
|
+
hoverBorderColor: '#0d9488',
|
|
57
|
+
focusBorderColor: '#0f766e',
|
|
58
|
+
invalidBorderColor: '#dc2626',
|
|
59
|
+
backgroundColor: '#ffffff',
|
|
60
|
+
textColor: '#0f172a',
|
|
61
|
+
placeholderColor: '#64748b',
|
|
62
|
+
focusRingColor: 'rgba(15, 118, 110, 0.18)',
|
|
63
|
+
borderRadius: '0.75rem'
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Observacoes:
|
|
68
|
+
|
|
69
|
+
- hoje essa customizacao cobre principalmente `text`, `textarea` e `select`;
|
|
70
|
+
- a API foi desenhada para crescer para outros componentes sem mudar o contrato do consumidor.
|
|
71
|
+
|
|
72
|
+
## Exemplo
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import { FormGroup } from '@angular/forms';
|
|
76
|
+
import {
|
|
77
|
+
DynamicErrorTranslations,
|
|
78
|
+
DynamicFieldConfig,
|
|
79
|
+
utcDateNotBeforeTodayValidator
|
|
80
|
+
} from 'primeng-forms-utils';
|
|
81
|
+
|
|
82
|
+
enum UserRole {
|
|
83
|
+
Admin = 'admin',
|
|
84
|
+
Reviewer = 'reviewer',
|
|
85
|
+
User = 'user'
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const form = new FormGroup({});
|
|
89
|
+
|
|
90
|
+
const errorTranslations: DynamicErrorTranslations = {
|
|
91
|
+
required: 'Esse campo e obrigatorio.',
|
|
92
|
+
email: 'Informe um e-mail valido.',
|
|
93
|
+
minlength: ({ errorValue }) => `Minimo de ${(errorValue as { requiredLength: number }).requiredLength} caracteres.`,
|
|
94
|
+
maxlength: ({ errorValue }) => `Maximo de ${(errorValue as { requiredLength: number }).requiredLength} caracteres.`,
|
|
95
|
+
min: ({ errorValue }) => `Valor minimo: ${(errorValue as { min: number }).min}.`,
|
|
96
|
+
max: ({ errorValue }) => `Valor maximo: ${(errorValue as { max: number }).max}.`,
|
|
97
|
+
pattern: 'Formato invalido.'
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
const fields: DynamicFieldConfig[] = [
|
|
101
|
+
{
|
|
102
|
+
name: 'name',
|
|
103
|
+
type: 'text',
|
|
104
|
+
label: 'Nome',
|
|
105
|
+
placeholder: 'Informe o nome',
|
|
106
|
+
quickHint: 'Esse nome sera exibido no cadastro principal.',
|
|
107
|
+
appearance: {
|
|
108
|
+
borderColor: '#0f766e',
|
|
109
|
+
hoverBorderColor: '#0d9488',
|
|
110
|
+
focusBorderColor: '#0f766e',
|
|
111
|
+
focusRingColor: 'rgba(15, 118, 110, 0.18)'
|
|
112
|
+
},
|
|
113
|
+
validators: [{ type: 'required' }, { type: 'minLength', value: 3 }]
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
name: 'role',
|
|
117
|
+
type: 'enum',
|
|
118
|
+
label: 'Perfil',
|
|
119
|
+
colSpan: 6,
|
|
120
|
+
labelPosition: 'side',
|
|
121
|
+
placeholder: 'Selecione um perfil',
|
|
122
|
+
enumConfig: {
|
|
123
|
+
values: UserRole,
|
|
124
|
+
showIcons: true,
|
|
125
|
+
options: [
|
|
126
|
+
{ enumValue: UserRole.Admin, label: 'Administrador', icon: 'pi pi-shield' },
|
|
127
|
+
{ enumValue: UserRole.Reviewer, label: 'Revisor', icon: 'pi pi-eye' },
|
|
128
|
+
{ enumValue: UserRole.User, label: 'Usuario', icon: 'pi pi-user' }
|
|
129
|
+
]
|
|
130
|
+
}
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
name: 'price',
|
|
134
|
+
type: 'money',
|
|
135
|
+
label: 'Preco',
|
|
136
|
+
colSpan: 6,
|
|
137
|
+
moneyConfig: {
|
|
138
|
+
currency: 'BRL',
|
|
139
|
+
locale: 'pt-BR',
|
|
140
|
+
currencyDisplay: 'symbol',
|
|
141
|
+
minFractionDigits: 2,
|
|
142
|
+
maxFractionDigits: 2
|
|
143
|
+
}
|
|
144
|
+
},
|
|
145
|
+
{
|
|
146
|
+
name: 'startDate',
|
|
147
|
+
type: 'date',
|
|
148
|
+
label: 'Data inicial',
|
|
149
|
+
colSpan: 6,
|
|
150
|
+
dateConfig: {
|
|
151
|
+
dateFormat: 'dd/mm/yy',
|
|
152
|
+
showIcon: true
|
|
153
|
+
},
|
|
154
|
+
controlValidators: [utcDateNotBeforeTodayValidator()]
|
|
155
|
+
},
|
|
156
|
+
{
|
|
157
|
+
name: 'permissions',
|
|
158
|
+
type: 'checkbox',
|
|
159
|
+
label: 'Permissoes',
|
|
160
|
+
colSpan: 6,
|
|
161
|
+
optionLayout: 'vertical',
|
|
162
|
+
initialValue: ['read', 'create'],
|
|
163
|
+
options: [
|
|
164
|
+
{ label: 'Ler', value: 'read' },
|
|
165
|
+
{ label: 'Criar', value: 'create' },
|
|
166
|
+
{ label: 'Remover', value: 'delete' }
|
|
167
|
+
]
|
|
168
|
+
}
|
|
169
|
+
];
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
```html
|
|
173
|
+
<pfu-dynamic-form
|
|
174
|
+
[form]="form"
|
|
175
|
+
[fields]="fields"
|
|
176
|
+
[errorTranslations]="errorTranslations"
|
|
177
|
+
/>
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## Demo visual
|
|
181
|
+
|
|
182
|
+
Existe um app Angular standalone em [demo/README.md](C:/bibliotecas/primeng-forms-utils/demo/README.md:1) para validar visualmente:
|
|
183
|
+
|
|
184
|
+
- layout responsivo em grid de 12 colunas;
|
|
185
|
+
- `colSpan` padrao `6/12` quando nao informado;
|
|
186
|
+
- todos os tipos de campo suportados;
|
|
187
|
+
- customizacao visual por `appearance`;
|
|
188
|
+
- payload em tempo real e snapshot de submit.
|
|
189
|
+
|
|
190
|
+
## Diretiva de loading
|
|
191
|
+
|
|
192
|
+
Use a diretiva `pfuLoading` em qualquer container para sobrepor a area com um painel branco semitransparente e spinner central.
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
import { LoadingDirective } from 'primeng-forms-utils';
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
```html
|
|
199
|
+
<div [pfuLoading]="isLoading">
|
|
200
|
+
Conteudo do container
|
|
201
|
+
</div>
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## Proximos passos recomendados
|
|
205
|
+
|
|
206
|
+
1. Cobrir mais tokens visuais em `appearance`, inclusive `checkbox`, `radio`, `datepicker` e `inputnumber`.
|
|
207
|
+
2. Adicionar testes unitarios para builder, layout e rendering condicional.
|
|
208
|
+
3. Publicar snapshots visuais do demo para facilitar revisao em PR.
|
|
209
|
+
|
|
210
|
+
## Documentacao para LLMs
|
|
211
|
+
|
|
212
|
+
Existe um manual dedicado para implementacao e extensao por outras LLMs em [docs/LLM_IMPLEMENTATION_MANUAL.md](C:/bibliotecas/primeng-forms-utils/docs/LLM_IMPLEMENTATION_MANUAL.md:1).
|
package/package.json
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "primeng-forms-utils",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Angular utility library for dynamic forms built on top of PrimeNG.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"angular",
|
|
7
|
+
"primeng",
|
|
8
|
+
"forms",
|
|
9
|
+
"dynamic-forms",
|
|
10
|
+
"typescript"
|
|
11
|
+
],
|
|
12
|
+
"license": "MIT",
|
|
13
|
+
"sideEffects": false,
|
|
14
|
+
"type": "module",
|
|
15
|
+
"main": "./dist/fesm2022/primeng-forms-utils.mjs",
|
|
16
|
+
"module": "fesm2022/primeng-forms-utils.mjs",
|
|
17
|
+
"types": "./dist/index.d.ts",
|
|
18
|
+
"exports": {
|
|
19
|
+
".": {
|
|
20
|
+
"types": "./index.d.ts",
|
|
21
|
+
"default": "./fesm2022/primeng-forms-utils.mjs",
|
|
22
|
+
"esm2022": "./esm2022/primeng-forms-utils.mjs",
|
|
23
|
+
"esm": "./esm2022/primeng-forms-utils.mjs"
|
|
24
|
+
},
|
|
25
|
+
"./package.json": {
|
|
26
|
+
"default": "./package.json"
|
|
27
|
+
}
|
|
28
|
+
},
|
|
29
|
+
"files": [
|
|
30
|
+
"dist",
|
|
31
|
+
"src",
|
|
32
|
+
"demo"
|
|
33
|
+
],
|
|
34
|
+
"peerDependencies": {
|
|
35
|
+
"@angular/common": "^18.0.0",
|
|
36
|
+
"@angular/compiler": "^18.0.0",
|
|
37
|
+
"@angular/core": "^18.0.0",
|
|
38
|
+
"@angular/forms": "^18.0.0",
|
|
39
|
+
"primeng": "^18.0.0"
|
|
40
|
+
},
|
|
41
|
+
"typings": "index.d.ts",
|
|
42
|
+
"dependencies": {
|
|
43
|
+
"tslib": "^2.3.0"
|
|
44
|
+
}
|
|
45
|
+
}
|