@aseansc/ui 4.0.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/CHANGELOG.md +966 -0
- package/README.md +1018 -0
- package/fesm2022/aseansc-ui.mjs +10524 -0
- package/fesm2022/aseansc-ui.mjs.map +1 -0
- package/package.json +50 -0
- package/tokens/_primitive.scss +155 -0
- package/tokens/_semantic.scss +187 -0
- package/tokens/_typography.scss +106 -0
- package/tokens/fonts/inter-latin-ext.woff2 +0 -0
- package/tokens/fonts/inter-latin.woff2 +0 -0
- package/tokens/fonts/inter-vietnamese.woff2 +0 -0
- package/tokens/index.scss +14 -0
- package/tokens/layout/_core.scss +24 -0
- package/tokens/layout/_footer.scss +8 -0
- package/tokens/layout/_main.scss +19 -0
- package/tokens/layout/_menu.scss +151 -0
- package/tokens/layout/_mixins.scss +15 -0
- package/tokens/layout/_preloading.scss +49 -0
- package/tokens/layout/_responsive.scss +110 -0
- package/tokens/layout/_topbar.scss +159 -0
- package/tokens/layout/_typography.scss +68 -0
- package/tokens/layout/_utils.scss +25 -0
- package/tokens/layout/layout.scss +13 -0
- package/tokens/layout/variables/_common.scss +20 -0
- package/tokens/layout/variables/_dark.scss +5 -0
- package/tokens/layout/variables/_light.scss +5 -0
- package/tokens/preset.css +1276 -0
- package/tokens/preset.scss +122 -0
- package/types/aseansc-ui.d.ts +3148 -0
package/README.md
ADDED
|
@@ -0,0 +1,1018 @@
|
|
|
1
|
+
# @aseansc/ui
|
|
2
|
+
|
|
3
|
+
ASC Internal UI Component Library — Angular 22 · PrimeNG 21 · TailwindCSS 4
|
|
4
|
+
|
|
5
|
+
> **Vì sao PrimeNG 21 chứ không phải 22?** Từ v22.0.0, PrimeNG bắt buộc license key
|
|
6
|
+
> thương mại (PrimeUI) — thiếu key sẽ hiện banner "Invalid PrimeUI License" đè lên UI.
|
|
7
|
+
> Project chưa mua license nên chủ động cap ở PrimeNG 21.x (tổ hợp Angular 22 + PrimeNG 21
|
|
8
|
+
> không chính thức được PrimeTek support — peer dependency của PrimeNG 21 khai báo
|
|
9
|
+
> `@angular/core@^21.0.7` — nhưng đã verify build/test/runtime thực tế hoạt động đúng).
|
|
10
|
+
> Nếu sau này mua license, gỡ cap này ở `libs/ui/package.json` (`primeng`, `@primeuix/themes`)
|
|
11
|
+
> và `package.json` gốc.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Migration — v0.5.x → v0.6.0
|
|
16
|
+
|
|
17
|
+
**Breaking: Tailwind spacing scale** — base unit đổi từ `0.25rem` sang `1px`. Tất cả numeric spacing class cần nhân ×4:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
p-4 → p-16 gap-2 → gap-8 px-6 → px-24
|
|
21
|
+
w-12 → w-48 h-6 → h-24 mt-1 → mt-4
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Chạy lệnh migrate tự động trong project:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
# Dùng Perl (Linux/macOS) — backup trước khi chạy
|
|
28
|
+
find src \( -name "*.ts" -o -name "*.html" \) | xargs perl -pi -e \
|
|
29
|
+
's/\b(p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap|w|h)-([1-9][0-9]*)\b/$1."-".($2*4)/ge'
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Hoặc xem [CHANGELOG](./CHANGELOG.md) để biết chi tiết.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Installation
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npm install @aseansc/ui
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Peer dependencies
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npm install @angular/core@^22 @angular/cdk@^22 primeng@^21
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Setup
|
|
51
|
+
|
|
52
|
+
### 1. `app.config.ts`
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
import { ApplicationConfig, provideZoneChangeDetection,
|
|
56
|
+
provideBrowserGlobalErrorListeners } from '@angular/core';
|
|
57
|
+
import { provideRouter } from '@angular/router';
|
|
58
|
+
import { provideHttpClient } from '@angular/common/http';
|
|
59
|
+
import { provideAnimations } from '@angular/platform-browser/animations';
|
|
60
|
+
import { provideAscUI } from '@aseansc/ui';
|
|
61
|
+
import { appRoutes } from './app.routes';
|
|
62
|
+
|
|
63
|
+
export const appConfig: ApplicationConfig = {
|
|
64
|
+
providers: [
|
|
65
|
+
provideBrowserGlobalErrorListeners(),
|
|
66
|
+
provideAscUI({
|
|
67
|
+
theme: { darkMode: false },
|
|
68
|
+
locale: 'vi-VN', // 'vi-VN' | 'en-US'
|
|
69
|
+
table: { rows: 20 },
|
|
70
|
+
}),
|
|
71
|
+
provideAnimations(),
|
|
72
|
+
provideZoneChangeDetection({ eventCoalescing: true }),
|
|
73
|
+
provideRouter(appRoutes),
|
|
74
|
+
provideHttpClient(),
|
|
75
|
+
],
|
|
76
|
+
};
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### 2. `styles.scss`
|
|
80
|
+
|
|
81
|
+
```scss
|
|
82
|
+
@import "@aseansc/ui/preset.css";
|
|
83
|
+
@use 'prismjs/themes/prism-okaidia.css';
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Lưu ý: dòng import preset **phải** dùng cú pháp CSS `@import` (không phải Sass `@use`) —
|
|
87
|
+
package ship sẵn `@source` trỏ vào chính bundle của `@aseansc/ui` bên trong file này, để Tailwind
|
|
88
|
+
tự động nhận diện các class Tailwind dùng trong component của lib. Nếu dùng `@use` thay vì
|
|
89
|
+
`@import`, Sass sẽ inline/flatten nội dung trước khi tới Tailwind và `@source` sẽ không còn
|
|
90
|
+
resolve đúng — lúc đó bạn sẽ phải tự thêm `@source '../node_modules/@aseansc/ui';`
|
|
91
|
+
thủ công trong app của mình.
|
|
92
|
+
|
|
93
|
+
### 3. `postcss.config.json` (workspace root)
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"plugins": {
|
|
98
|
+
"@tailwindcss/postcss": {}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### 4. Root component template
|
|
104
|
+
|
|
105
|
+
```html
|
|
106
|
+
<asc-toast />
|
|
107
|
+
<asc-confirm-dialog />
|
|
108
|
+
<router-outlet />
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## Components
|
|
114
|
+
|
|
115
|
+
### Layout — `AscLayout`
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
import { AscLayout } from '@aseansc/ui';
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
```html
|
|
122
|
+
<asc-layout [menuItems]="menuItems" [topBarLogo]="logoTpl" [breadCrumb]="breadcrumbTpl">
|
|
123
|
+
<router-outlet />
|
|
124
|
+
</asc-layout>
|
|
125
|
+
|
|
126
|
+
<ng-template #breadcrumbTpl>
|
|
127
|
+
<asc-breadcrumb />
|
|
128
|
+
</ng-template>
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Toggle dark mode via the sun/moon button in the topbar — adds/removes `.app-dark` on `<html>`.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
#### Breadcrumb — `AscBreadcrumb`
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
import { AscBreadcrumb } from '@aseansc/ui';
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
**Auto-router mode** — khai báo `data.breadcrumb` trong route config, không cần truyền gì thêm:
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
// app.routes.ts
|
|
145
|
+
{
|
|
146
|
+
path: 'form',
|
|
147
|
+
data: { breadcrumb: 'Form' },
|
|
148
|
+
children: [
|
|
149
|
+
{ path: 'input', data: { breadcrumb: 'Input' }, loadComponent: ... },
|
|
150
|
+
],
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
```html
|
|
155
|
+
<asc-breadcrumb />
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
**Manual mode** — truyền `items` thủ công:
|
|
159
|
+
|
|
160
|
+
```html
|
|
161
|
+
<asc-breadcrumb
|
|
162
|
+
[items]="[{ label: 'Admin', routerLink: '/admin' }, { label: 'Users' }]"
|
|
163
|
+
[home]="{ icon: 'pi pi-home', routerLink: '/' }"
|
|
164
|
+
/>
|
|
165
|
+
|
|
166
|
+
<!-- Ẩn home icon -->
|
|
167
|
+
<asc-breadcrumb [items]="items" [home]="null" />
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
### Form
|
|
173
|
+
|
|
174
|
+
#### Auto Complete — `AscAutoCompleteComponent`
|
|
175
|
+
|
|
176
|
+
```html
|
|
177
|
+
<!-- Single -->
|
|
178
|
+
<asc-form-field label="Nhân viên">
|
|
179
|
+
<asc-auto-complete
|
|
180
|
+
[formControl]="ctrl"
|
|
181
|
+
[suggestions]="results"
|
|
182
|
+
optionLabel="fullName"
|
|
183
|
+
placeholder="Tìm kiếm..."
|
|
184
|
+
(completeMethod)="onSearch($event)"
|
|
185
|
+
/>
|
|
186
|
+
</asc-form-field>
|
|
187
|
+
|
|
188
|
+
<!-- Multiple (chip mode) -->
|
|
189
|
+
<asc-auto-complete
|
|
190
|
+
[formControl]="ctrl"
|
|
191
|
+
[suggestions]="results"
|
|
192
|
+
optionLabel="name"
|
|
193
|
+
[multiple]="true"
|
|
194
|
+
(completeMethod)="onSearch($event)"
|
|
195
|
+
/>
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
```ts
|
|
199
|
+
results = signal<Employee[]>([]);
|
|
200
|
+
|
|
201
|
+
onSearch(query: string) {
|
|
202
|
+
this.results.set(
|
|
203
|
+
this.employees.filter(e => e.fullName.toLowerCase().includes(query.toLowerCase()))
|
|
204
|
+
);
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
| Input | Type | Default | Mô tả |
|
|
209
|
+
|-----------------|-----------|---------|----------------------------------------------------------|
|
|
210
|
+
| `suggestions` | `any[]` | `[]` | Danh sách gợi ý — cập nhật từ `(completeMethod)` |
|
|
211
|
+
| `optionLabel` | `string` | `''` | Property hiển thị khi value là object |
|
|
212
|
+
| `optionValue` | `string` | `''` | Property dùng làm value (mặc định: cả object) |
|
|
213
|
+
| `minLength` | `number` | `1` | Số ký tự tối thiểu trước khi tìm kiếm |
|
|
214
|
+
| `delay` | `number` | `300` | Delay (ms) trước khi emit |
|
|
215
|
+
| `multiple` | `boolean` | `false` | Chọn nhiều — hiển thị dạng chip |
|
|
216
|
+
| `forceSelection`| `boolean` | `false` | Bắt buộc chọn từ danh sách |
|
|
217
|
+
| `dropdown` | `boolean` | `false` | Hiển thị nút dropdown |
|
|
218
|
+
| `showClear` | `boolean` | `false` | Hiển thị nút xoá |
|
|
219
|
+
|
|
220
|
+
| Output | Mô tả |
|
|
221
|
+
|------------------|------------------------------------------|
|
|
222
|
+
| `completeMethod` | Emit text user đang gõ (string) |
|
|
223
|
+
|
|
224
|
+
#### Input Mask — `AscInputMaskComponent`
|
|
225
|
+
|
|
226
|
+
Input với định dạng cố định. Ký tự mask: `9`=chữ số · `a`=chữ cái · `*`=alphanumeric · `?`=optional từ ký tự đó.
|
|
227
|
+
|
|
228
|
+
```html
|
|
229
|
+
<!-- Số điện thoại -->
|
|
230
|
+
<asc-form-field label="Số điện thoại">
|
|
231
|
+
<asc-input-mask [formControl]="ctrl" mask="0999 999 999" placeholder="0xxx xxx xxx" />
|
|
232
|
+
</asc-form-field>
|
|
233
|
+
|
|
234
|
+
<!-- Ngày tháng -->
|
|
235
|
+
<asc-input-mask [formControl]="ctrl" mask="99/99/9999" placeholder="dd/mm/yyyy" />
|
|
236
|
+
|
|
237
|
+
<!-- CCCD 12 số -->
|
|
238
|
+
<asc-input-mask [formControl]="ctrl" mask="999999999999" />
|
|
239
|
+
|
|
240
|
+
<!-- MST doanh nghiệp -->
|
|
241
|
+
<asc-input-mask [formControl]="ctrl" mask="9999999999-999" />
|
|
242
|
+
|
|
243
|
+
<!-- unmask=true → model lưu chuỗi thuần, không có ký tự phân cách -->
|
|
244
|
+
<asc-input-mask [formControl]="ctrl" mask="0999 999 999" [unmask]="true" />
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
| Input | Type | Default | Mô tả |
|
|
248
|
+
|---------------|-----------|----------|-----------------------------------------------------------------------|
|
|
249
|
+
| `mask` | `string` | required | Pattern định dạng. |
|
|
250
|
+
| `placeholder` | `string` | `''` | Placeholder khi chưa nhập. |
|
|
251
|
+
| `slotChar` | `string` | `'_'` | Ký tự đại diện cho slot trống. |
|
|
252
|
+
| `autoClear` | `boolean` | `true` | Tự xoá nếu blur mà chưa điền đủ mask. |
|
|
253
|
+
| `showClear` | `boolean` | `false` | Hiển thị nút ×. |
|
|
254
|
+
| `readonly` | `boolean` | `false` | Chỉ đọc. |
|
|
255
|
+
| `unmask` | `boolean` | `false` | `true` → model value là chuỗi thuần không có ký tự phân cách. |
|
|
256
|
+
|
|
257
|
+
| Output | Mô tả |
|
|
258
|
+
|------------|--------------------------------|
|
|
259
|
+
| `complete` | Emit khi user điền đủ mask. |
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
#### Button — `AscButtonComponent`
|
|
264
|
+
|
|
265
|
+
```html
|
|
266
|
+
<asc-button label="Lưu" icon="pi pi-save" (clicked)="onSave()" />
|
|
267
|
+
<asc-button label="Huỷ" variant="outlined" severity="secondary" />
|
|
268
|
+
<asc-button label="Xoá" severity="danger" [loading]="loading" />
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
#### Input — `AscInputComponent`
|
|
272
|
+
|
|
273
|
+
```html
|
|
274
|
+
<asc-form-field label="Email">
|
|
275
|
+
<asc-input formControlName="email" placeholder="Nhập email..." />
|
|
276
|
+
</asc-form-field>
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
#### Textarea — `AscTextareaComponent`
|
|
280
|
+
|
|
281
|
+
```html
|
|
282
|
+
<asc-textarea formControlName="note" [rows]="4" [maxLength]="500" [showCounter]="true" />
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
#### Input Number — `AscInputNumberComponent`
|
|
286
|
+
|
|
287
|
+
```html
|
|
288
|
+
<asc-input-number formControlName="amount" mode="currency" currency="VND" />
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
#### Password — `AscPasswordComponent`
|
|
292
|
+
|
|
293
|
+
```html
|
|
294
|
+
<asc-password formControlName="password" [feedback]="true" />
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
#### Select — `AscSelectComponent`
|
|
298
|
+
|
|
299
|
+
```html
|
|
300
|
+
<asc-select formControlName="status" [options]="statusOptions" optionLabel="label" optionValue="value" />
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
#### Datepicker — `AscDatepickerComponent`
|
|
304
|
+
|
|
305
|
+
```html
|
|
306
|
+
<asc-datepicker formControlName="date" dateFormat="dd/MM/yyyy" />
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
#### Checkbox — `AscCheckboxComponent`
|
|
310
|
+
|
|
311
|
+
```html
|
|
312
|
+
<asc-checkbox formControlName="agree" label="Tôi đồng ý với điều khoản" />
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
#### Radio — `AscRadioComponent`
|
|
316
|
+
|
|
317
|
+
```html
|
|
318
|
+
<asc-radio formControlName="gender" [options]="genderOptions" optionLabel="label" optionValue="value" />
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
#### Upload — `AscUpload`
|
|
322
|
+
|
|
323
|
+
```html
|
|
324
|
+
<!-- Image (default) -->
|
|
325
|
+
<asc-upload formControlName="avatar" uploadMode="img" [maxSizePerFile]="2000000">
|
|
326
|
+
<div empty>Kéo thả ảnh vào đây</div>
|
|
327
|
+
</asc-upload>
|
|
328
|
+
|
|
329
|
+
<!-- Excel / CSV -->
|
|
330
|
+
<asc-upload formControlName="sheet" uploadMode="excelFile" />
|
|
331
|
+
|
|
332
|
+
<!-- Word / Text -->
|
|
333
|
+
<asc-upload formControlName="doc" uploadMode="docFile" />
|
|
334
|
+
|
|
335
|
+
<!-- PDF only -->
|
|
336
|
+
<asc-upload formControlName="report" uploadMode="pdfFile" />
|
|
337
|
+
|
|
338
|
+
<!-- All document types (.pdf .doc .docx .xls .xlsx .csv .txt) -->
|
|
339
|
+
<asc-upload formControlName="attachment" uploadMode="file" />
|
|
340
|
+
|
|
341
|
+
<!-- Any file -->
|
|
342
|
+
<asc-upload formControlName="misc" uploadMode="all" />
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
| `uploadMode` | Accept |
|
|
346
|
+
|---------------|-----------------------------------------|
|
|
347
|
+
| `img` | `image/*` |
|
|
348
|
+
| `pdfFile` | `.pdf` |
|
|
349
|
+
| `docFile` | `.doc, .docx, .txt` |
|
|
350
|
+
| `excelFile` | `.xls, .xlsx, .csv` |
|
|
351
|
+
| `file` | `.pdf, .doc, .docx, .xls, .xlsx, .csv, .txt` |
|
|
352
|
+
| `all` | `*/*` |
|
|
353
|
+
|
|
354
|
+
---
|
|
355
|
+
|
|
356
|
+
### Data
|
|
357
|
+
|
|
358
|
+
#### Table — `AscTableComponent`
|
|
359
|
+
|
|
360
|
+
```html
|
|
361
|
+
<asc-table [data]="rows" [columns]="cols" [loading]="loading" (lazyLoad)="onLoad($event)">
|
|
362
|
+
<!-- type='custom': dùng [ascTableCell]="key" để render tự do -->
|
|
363
|
+
<ng-template [ascTableCell]="'status'" let-value let-row="row">
|
|
364
|
+
<p-tag [value]="value" />
|
|
365
|
+
</ng-template>
|
|
366
|
+
</asc-table>
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
**Column types:**
|
|
370
|
+
|
|
371
|
+
```ts
|
|
372
|
+
columns: AscTableColumn[] = [
|
|
373
|
+
{ field: 'name', header: 'Tên', type: 'avatar' },
|
|
374
|
+
{ field: 'email', header: 'Email', type: 'text' },
|
|
375
|
+
{ field: 'active', header: 'Hoạt động', type: 'boolean' },
|
|
376
|
+
{ field: 'joinDate', header: 'Ngày vào', type: 'date' },
|
|
377
|
+
{ field: 'lastSeen', header: 'Lần cuối', type: 'datetime' },
|
|
378
|
+
// Number — thousandSep + locale kiểm soát ký tự phân cách
|
|
379
|
+
{ field: 'score', header: 'Điểm', type: 'number',
|
|
380
|
+
format: { thousandSep: true } }, // 8.000 (vi-VN mặc định)
|
|
381
|
+
{ field: 'score', header: 'Điểm', type: 'number',
|
|
382
|
+
format: { thousandSep: true, locale: 'en-US' } }, // 8,000
|
|
383
|
+
{ field: 'score', header: 'Điểm', type: 'number',
|
|
384
|
+
format: { thousandSep: false } }, // 8000
|
|
385
|
+
// Currency
|
|
386
|
+
{ field: 'salary', header: 'Lương', type: 'currency',
|
|
387
|
+
format: { locale: 'vi-VN' } },
|
|
388
|
+
// Badge — map value → label + severity
|
|
389
|
+
{ field: 'status', header: 'Trạng thái', type: 'badge',
|
|
390
|
+
badgeMap: {
|
|
391
|
+
active: { label: 'Hoạt động', severity: 'success' },
|
|
392
|
+
inactive: { label: 'Tạm dừng', severity: 'warn' },
|
|
393
|
+
},
|
|
394
|
+
},
|
|
395
|
+
// Custom template
|
|
396
|
+
{ field: 'progress', header: 'Tiến độ', type: 'custom', templateKey: 'progress' },
|
|
397
|
+
];
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
**Lazy load — `pageNumber`/`pageSize`:** khi `[lazy]="true"`, `(lazyLoad)` emit `AscTableLazyLoadEvent` gồm `first`/`rows` (chuẩn PrimeNG) **và** `pageNumber`/`pageSize` (0-based, `pageNumber = Math.floor(first / rows)`) — dùng thẳng cho BE theo convention `pageNumber`/`pageSize`, khỏi phải tự tính lại ở service layer:
|
|
401
|
+
|
|
402
|
+
```html
|
|
403
|
+
<asc-table [data]="rows" [columns]="cols" [lazy]="true" [totalRecords]="total" (lazyLoad)="onLoad($event)" />
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
```ts
|
|
407
|
+
onLoad({ pageNumber, pageSize }: AscTableLazyLoadEvent) {
|
|
408
|
+
this.api.post({ authenType: 'getAllMeeting', data: { pageNumber, pageSize }, endpoint: 'feApi' })
|
|
409
|
+
.subscribe(res => { this.rows = res.data; this.total = res.total; });
|
|
410
|
+
}
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
#### Icon — `AscIconComponent`
|
|
414
|
+
|
|
415
|
+
Render icon SVG **inline** (không phải `<img>`) bằng cách fetch qua HTTP từ app consume — cho phép style màu qua CSS `currentColor` và kích thước tuỳ ý. Khác với PrimeIcon (font class như `pi pi-user`), dùng khi cần icon SVG tuỳ chỉnh của riêng app.
|
|
416
|
+
|
|
417
|
+
```html
|
|
418
|
+
<asc-icon src="/assets/icons/user.svg" size="24px" />
|
|
419
|
+
<asc-icon src="/assets/icons/star.svg" size="24px" (loadError)="onIconError($event)" />
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
```ts
|
|
423
|
+
onIconError(err: unknown) {
|
|
424
|
+
console.warn('Không tải được icon', err);
|
|
425
|
+
}
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
| Input | Type | Default | Mô tả |
|
|
429
|
+
|-------------|-----------|-----------|--------------------------------------------------------------------|
|
|
430
|
+
| `src` | `string` | required | URL tới file `.svg` — fetch qua HTTP. |
|
|
431
|
+
| `size` | `string` | `'1em'` | Kích thước CSS áp cho `width`/`height` (vd `'24px'`, `'1.5rem'`). |
|
|
432
|
+
|
|
433
|
+
| Output | Mô tả |
|
|
434
|
+
|-------------|-------------------------------------------------|
|
|
435
|
+
| `loadError` | Emit khi fetch SVG lỗi (404, network...). |
|
|
436
|
+
|
|
437
|
+
SVG được fetch và cache theo `src` qua `AscIconService` (`providedIn: 'root'`) — nhiều `<asc-icon>` cùng `src` chỉ gọi HTTP đúng 1 lần. File SVG nên dùng `fill="currentColor"`/`stroke="currentColor"` để kế thừa màu từ CSS `color` của phần tử cha.
|
|
438
|
+
|
|
439
|
+
**Yêu cầu:** app phải gọi `provideHttpClient()` (thường đã có sẵn nếu dùng `@aseansc/http`).
|
|
440
|
+
|
|
441
|
+
⚠️ **Bảo mật:** nội dung SVG được render qua `DomSanitizer.bypassSecurityTrustHtml` (bỏ qua sanitize) để giữ style/`currentColor`. **Chỉ dùng `src` trỏ tới icon do chính app kiểm soát** (vd thư mục `assets` nội bộ) — **không** truyền URL do user nhập, vì sẽ mở lỗ hổng XSS.
|
|
442
|
+
|
|
443
|
+
**Best practice — đừng hardcode `src` rải rác khắp template.** Gom hết đường dẫn icon vào **1 file const duy nhất**, giống cách app thường tổ chức route path hay i18n key — lợi ích: đổi thư mục/CDN icon chỉ sửa 1 chỗ, gõ nhầm tên bị TypeScript bắt lỗi ngay, và IDE autocomplete được tên icon.
|
|
444
|
+
|
|
445
|
+
```ts
|
|
446
|
+
// src/app/shared/constants/app-icons.const.ts
|
|
447
|
+
const ICON_BASE = '/assets/icons';
|
|
448
|
+
|
|
449
|
+
export const AppIcons = {
|
|
450
|
+
user: `${ICON_BASE}/user.svg`,
|
|
451
|
+
star: `${ICON_BASE}/star.svg`,
|
|
452
|
+
bell: `${ICON_BASE}/bell.svg`,
|
|
453
|
+
} as const;
|
|
454
|
+
|
|
455
|
+
export type AppIconName = keyof typeof AppIcons;
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
```ts
|
|
459
|
+
// some.component.ts
|
|
460
|
+
import { AppIcons } from '../shared/constants/app-icons.const';
|
|
461
|
+
|
|
462
|
+
@Component({ ... })
|
|
463
|
+
export class SomeComponent {
|
|
464
|
+
protected readonly icons = AppIcons; // expose cho template dùng
|
|
465
|
+
}
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
```html
|
|
469
|
+
<!-- some.component.html — không còn chuỗi path rải rác -->
|
|
470
|
+
<asc-icon [src]="icons.user" size="24px" />
|
|
471
|
+
<asc-icon [src]="icons.star" size="24px" />
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
Nếu app có nhiều icon và muốn tách theo nhóm chức năng (thay vì 1 file phẳng), chia theo domain — `nav-icons.const.ts`, `action-icons.const.ts` — rồi gộp lại nếu cần:
|
|
475
|
+
|
|
476
|
+
```ts
|
|
477
|
+
// shared/constants/icons/nav-icons.const.ts
|
|
478
|
+
export const NavIcons = { home: '/assets/icons/nav/home.svg', ... } as const;
|
|
479
|
+
|
|
480
|
+
// shared/constants/icons/action-icons.const.ts
|
|
481
|
+
export const ActionIcons = { delete: '/assets/icons/action/delete.svg', ... } as const;
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
#### Picklist — `AscPicklistComponent`
|
|
485
|
+
|
|
486
|
+
```html
|
|
487
|
+
<asc-picklist [(source)]="available" [(target)]="selected"
|
|
488
|
+
optionLabel="name" sourceHeader="Nguồn" targetHeader="Đã chọn" />
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
#### Avatar — `AscAvatarComponent` / `AscAvatarGroupComponent`
|
|
492
|
+
|
|
493
|
+
```html
|
|
494
|
+
<!-- Ảnh -->
|
|
495
|
+
<asc-avatar image="/assets/user.jpg" size="large" />
|
|
496
|
+
|
|
497
|
+
<!-- Chữ viết tắt + màu nền -->
|
|
498
|
+
<asc-avatar label="NT" [style]="{ background: '#F74036', color: '#fff' }" />
|
|
499
|
+
|
|
500
|
+
<!-- Icon mặc định (pi-user) -->
|
|
501
|
+
<asc-avatar />
|
|
502
|
+
|
|
503
|
+
<!-- Nhóm avatar chồng nhau -->
|
|
504
|
+
<asc-avatar-group>
|
|
505
|
+
<asc-avatar image="/u1.jpg" size="large" />
|
|
506
|
+
<asc-avatar image="/u2.jpg" size="large" />
|
|
507
|
+
<asc-avatar label="+3" size="large" [style]="{ background: '#dee2e6', color: '#495057' }" />
|
|
508
|
+
</asc-avatar-group>
|
|
509
|
+
```
|
|
510
|
+
|
|
511
|
+
| Input | Type | Default | Mô tả |
|
|
512
|
+
|----------|-----------------------------------|-------------|----------------------------------------------------|
|
|
513
|
+
| `image` | `string` | `''` | URL ảnh — ưu tiên cao nhất |
|
|
514
|
+
| `label` | `string` | `''` | Chữ viết tắt — fallback khi không có image |
|
|
515
|
+
| `icon` | `string` | `''` | PrimeIcon — fallback, mặc định `pi pi-user` |
|
|
516
|
+
| `size` | `'normal'\|'large'\|'xlarge'` | `'normal'` | 2rem / 3rem / 4rem |
|
|
517
|
+
| `shape` | `'circle'\|'square'` | `'circle'` | Hình dạng |
|
|
518
|
+
| `style` | `Record<string, string>` | `{}` | Inline style (màu nền/chữ) |
|
|
519
|
+
|
|
520
|
+
#### Timeline — `AscTimelineComponent`
|
|
521
|
+
|
|
522
|
+
```html
|
|
523
|
+
<asc-timeline [items]="history" />
|
|
524
|
+
<asc-timeline [items]="history" align="alternate" />
|
|
525
|
+
<asc-timeline [items]="steps" layout="horizontal" align="top" />
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
```ts
|
|
529
|
+
import { AscTimelineItem } from '@aseansc/ui';
|
|
530
|
+
|
|
531
|
+
history: AscTimelineItem[] = [
|
|
532
|
+
{ title: 'Tạo cuộc họp', date: '01/06/2026', status: 'info', icon: 'pi pi-plus' },
|
|
533
|
+
{ title: 'Gửi lời mời', date: '01/06/2026', status: 'info', icon: 'pi pi-send',
|
|
534
|
+
description: '12 thành viên được mời' },
|
|
535
|
+
{ title: 'Đang diễn ra', date: '08/06/2026', status: 'warn', icon: 'pi pi-spin pi-spinner' },
|
|
536
|
+
{ title: 'Hoàn thành', date: '08/06/2026', status: 'success', icon: 'pi pi-check' },
|
|
537
|
+
];
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
| Input | Type | Default | Mô tả |
|
|
541
|
+
|----------|---------------------------------------------|--------------|--------------------------------------|
|
|
542
|
+
| `items` | `AscTimelineItem[]` | `[]` | Danh sách sự kiện |
|
|
543
|
+
| `align` | `'left'\|'right'\|'alternate'\|'top'\|'bottom'` | `'left'` | Căn chỉnh content |
|
|
544
|
+
| `layout` | `'vertical'\|'horizontal'` | `'vertical'` | Hướng timeline |
|
|
545
|
+
|
|
546
|
+
`AscTimelineItem`: `title` (required), `description?`, `date?`, `icon?`, `status?` (`success`/`info`/`warn`/`danger`/`secondary`).
|
|
547
|
+
|
|
548
|
+
---
|
|
549
|
+
|
|
550
|
+
### Overlay
|
|
551
|
+
|
|
552
|
+
#### Toast & Confirm (programmatic)
|
|
553
|
+
|
|
554
|
+
```ts
|
|
555
|
+
import { AscToastService, AscConfirmService } from '@aseansc/ui';
|
|
556
|
+
|
|
557
|
+
// Toast
|
|
558
|
+
this.toast.success('Lưu thành công');
|
|
559
|
+
this.toast.error('Có lỗi xảy ra');
|
|
560
|
+
|
|
561
|
+
// Confirm dialog — preset
|
|
562
|
+
this.confirm.delete('Xoá bản ghi này?', () => this.delete(id));
|
|
563
|
+
this.confirm.save('Lưu thay đổi?', () => this.save());
|
|
564
|
+
this.confirm.leave(() => this.router.navigate(['/']));
|
|
565
|
+
|
|
566
|
+
// Confirm dialog — generic
|
|
567
|
+
this.confirm.show({ message: 'Bạn có chắc?', accept: () => this.doIt() });
|
|
568
|
+
|
|
569
|
+
// Confirm popup (anchor to click event)
|
|
570
|
+
onDelete(event: MouseEvent) {
|
|
571
|
+
this.confirm.popup(event, {
|
|
572
|
+
message: 'Xoá bản ghi này?',
|
|
573
|
+
accept: () => this.delete(),
|
|
574
|
+
});
|
|
575
|
+
}
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
Đặt `<asc-confirm-popup />` trong layout để dùng `confirm.popup()`:
|
|
579
|
+
|
|
580
|
+
```html
|
|
581
|
+
<asc-confirm-popup />
|
|
582
|
+
```
|
|
583
|
+
|
|
584
|
+
#### Dialog — `AscDialogComponent`
|
|
585
|
+
|
|
586
|
+
```html
|
|
587
|
+
<asc-dialog [(visible)]="showDialog" header="Tiêu đề">
|
|
588
|
+
<p>Nội dung dialog</p>
|
|
589
|
+
<ng-template ascDialogFooter>
|
|
590
|
+
<asc-button label="Đóng" severity="secondary" (clicked)="showDialog = false" />
|
|
591
|
+
</ng-template>
|
|
592
|
+
</asc-dialog>
|
|
593
|
+
```
|
|
594
|
+
|
|
595
|
+
#### Sidebar — `AscSidebarComponent`
|
|
596
|
+
|
|
597
|
+
```html
|
|
598
|
+
<asc-sidebar [(visible)]="showSidebar" position="right">
|
|
599
|
+
<p>Nội dung sidebar</p>
|
|
600
|
+
</asc-sidebar>
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
#### Popover — `AscPopoverComponent`
|
|
604
|
+
|
|
605
|
+
```html
|
|
606
|
+
<asc-button label="Mở popover" (clicked)="pop.toggle($event)" />
|
|
607
|
+
<asc-popover #pop>
|
|
608
|
+
<p>Nội dung popover</p>
|
|
609
|
+
</asc-popover>
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
#### Tooltip — `AscTooltipDirective`
|
|
613
|
+
|
|
614
|
+
```html
|
|
615
|
+
<asc-button label="Lưu" ascTooltip="Lưu thay đổi" tooltipPosition="top" />
|
|
616
|
+
<span ascTooltip="Thông tin thêm">Hover vào đây</span>
|
|
617
|
+
```
|
|
618
|
+
|
|
619
|
+
---
|
|
620
|
+
|
|
621
|
+
### Panel
|
|
622
|
+
|
|
623
|
+
#### Tabs — `AscTabsComponent` / `AscTabComponent`
|
|
624
|
+
|
|
625
|
+
```html
|
|
626
|
+
<asc-tabs [(value)]="activeTab">
|
|
627
|
+
<asc-tab value="info" label="Thông tin" icon="pi pi-user">
|
|
628
|
+
<p>Nội dung thông tin...</p>
|
|
629
|
+
</asc-tab>
|
|
630
|
+
<asc-tab value="settings" label="Cài đặt" icon="pi pi-cog">
|
|
631
|
+
<p>Nội dung cài đặt...</p>
|
|
632
|
+
</asc-tab>
|
|
633
|
+
</asc-tabs>
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
#### Stepper — `AscStepperComponent` / `AscStepComponent`
|
|
637
|
+
|
|
638
|
+
```html
|
|
639
|
+
<asc-stepper [(value)]="activeStep">
|
|
640
|
+
<asc-step [value]="1" label="Thông tin">
|
|
641
|
+
<p>Bước 1...</p>
|
|
642
|
+
<asc-button label="Tiếp theo" icon="pi pi-arrow-right" iconPos="right"
|
|
643
|
+
(clicked)="activeStep.set(2)" />
|
|
644
|
+
</asc-step>
|
|
645
|
+
<asc-step [value]="2" label="Xác nhận">
|
|
646
|
+
<p>Bước 2...</p>
|
|
647
|
+
<asc-button label="Quay lại" severity="secondary" (clicked)="activeStep.set(1)" />
|
|
648
|
+
<asc-button label="Hoàn tất" severity="success" (clicked)="activeStep.set(3)" />
|
|
649
|
+
</asc-step>
|
|
650
|
+
<asc-step [value]="3" label="Hoàn thành">
|
|
651
|
+
<p>Hoàn tất!</p>
|
|
652
|
+
</asc-step>
|
|
653
|
+
</asc-stepper>
|
|
654
|
+
```
|
|
655
|
+
|
|
656
|
+
---
|
|
657
|
+
|
|
658
|
+
### Feedback
|
|
659
|
+
|
|
660
|
+
#### Spinner — `AscSpinnerComponent`
|
|
661
|
+
|
|
662
|
+
Loading indicator tròn dùng để hiển thị trạng thái chờ.
|
|
663
|
+
|
|
664
|
+
```html
|
|
665
|
+
<asc-spinner />
|
|
666
|
+
<asc-spinner size="lg" />
|
|
667
|
+
<asc-spinner size="xl" strokeWidth="2" />
|
|
668
|
+
```
|
|
669
|
+
|
|
670
|
+
| Input | Type | Default | Mô tả |
|
|
671
|
+
|---------------|-----------------------------------|----------|------------------------|
|
|
672
|
+
| `size` | `'xs'\|'sm'\|'md'\|'lg'\|'xl'` | `'md'` | Kích thước (16–80px) |
|
|
673
|
+
| `strokeWidth` | `string` | `'4'` | Độ dày nét SVG (1–10) |
|
|
674
|
+
|
|
675
|
+
#### Badge — `AscBadgeComponent`
|
|
676
|
+
|
|
677
|
+
Label nhỏ dùng để đánh dấu trạng thái, danh mục.
|
|
678
|
+
|
|
679
|
+
```html
|
|
680
|
+
<asc-badge label="Mới" />
|
|
681
|
+
<asc-badge label="Thành công" severity="success" />
|
|
682
|
+
<asc-badge label="Cảnh báo" severity="warn" [rounded]="true" />
|
|
683
|
+
<asc-badge label="Lỗi" severity="danger" icon="pi pi-times" />
|
|
684
|
+
```
|
|
685
|
+
|
|
686
|
+
| Input | Type | Default | Mô tả |
|
|
687
|
+
|------------|---------------------------------------------------------------------------|-------------|----------------------|
|
|
688
|
+
| `label` | `string` | _(required)_| Nội dung badge |
|
|
689
|
+
| `severity` | `'primary'\|'success'\|'warn'\|'danger'\|'info'\|'secondary'\|'contrast'` | `'primary'` | Màu sắc |
|
|
690
|
+
| `rounded` | `boolean` | `false` | Bo tròn hoàn toàn |
|
|
691
|
+
| `icon` | `string` | — | PrimeIcon class |
|
|
692
|
+
|
|
693
|
+
#### Alert — `AscAlertComponent`
|
|
694
|
+
|
|
695
|
+
Thông báo inline dạng banner, hỗ trợ đóng.
|
|
696
|
+
|
|
697
|
+
```html
|
|
698
|
+
<asc-alert severity="success" title="Lưu thành công" text="Dữ liệu đã được cập nhật." />
|
|
699
|
+
<asc-alert severity="warn" title="Cảnh báo" [closable]="true" (closed)="onDismiss()">
|
|
700
|
+
<p>Nội dung <strong>phức tạp</strong> với HTML.</p>
|
|
701
|
+
</asc-alert>
|
|
702
|
+
```
|
|
703
|
+
|
|
704
|
+
| Input | Type | Default | Mô tả |
|
|
705
|
+
|------------|----------------------------------------|----------|------------------------------------|
|
|
706
|
+
| `severity` | `'success'\|'info'\|'warn'\|'danger'` | `'info'` | Loại alert |
|
|
707
|
+
| `title` | `string` | — | Tiêu đề |
|
|
708
|
+
| `text` | `string` | — | Nội dung văn bản |
|
|
709
|
+
| `closable` | `boolean` | `false` | Hiển thị nút đóng |
|
|
710
|
+
|
|
711
|
+
| Output | Mô tả |
|
|
712
|
+
|----------|-----------------------------|
|
|
713
|
+
| `closed` | Emit khi user bấm đóng |
|
|
714
|
+
|
|
715
|
+
#### Skeleton — `AscSkeletonComponent`
|
|
716
|
+
|
|
717
|
+
Placeholder hiển thị trong khi data đang load.
|
|
718
|
+
|
|
719
|
+
```html
|
|
720
|
+
<!-- Preset nhanh -->
|
|
721
|
+
<asc-skeleton preset="text" />
|
|
722
|
+
<asc-skeleton preset="avatar" />
|
|
723
|
+
<asc-skeleton preset="button" />
|
|
724
|
+
|
|
725
|
+
<!-- Tuỳ chỉnh -->
|
|
726
|
+
<asc-skeleton shape="rectangle" width="200px" height="120px" />
|
|
727
|
+
<asc-skeleton shape="circle" width="64px" height="64px" />
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
| Input | Type | Mô tả |
|
|
731
|
+
|----------------|---------------------------------------------------|----------------------------------------|
|
|
732
|
+
| `preset` | `'text'\|'avatar'\|'button'\|'image'\|'thumbnail'`| Shortcut định kích thước sẵn |
|
|
733
|
+
| `shape` | `'rectangle'\|'circle'` | Hình dạng (default: `'rectangle'`) |
|
|
734
|
+
| `width` | `string` | Ghi đè chiều rộng từ preset |
|
|
735
|
+
| `height` | `string` | Ghi đè chiều cao từ preset |
|
|
736
|
+
| `borderRadius` | `string` | Border radius tuỳ chỉnh |
|
|
737
|
+
|
|
738
|
+
#### Progress Bar — `AscProgressBarComponent`
|
|
739
|
+
|
|
740
|
+
Thanh tiến trình cho thấy % hoàn thành hoặc trạng thái đang xử lý.
|
|
741
|
+
|
|
742
|
+
```html
|
|
743
|
+
<!-- Xác định giá trị -->
|
|
744
|
+
<asc-progress-bar [value]="75" />
|
|
745
|
+
<asc-progress-bar [value]="uploadPercent" unit="%" [showValue]="true" />
|
|
746
|
+
|
|
747
|
+
<!-- Indeterminate — xử lý không biết bao lâu -->
|
|
748
|
+
<asc-progress-bar mode="indeterminate" />
|
|
749
|
+
```
|
|
750
|
+
|
|
751
|
+
| Input | Type | Default | Mô tả |
|
|
752
|
+
|-------------|-----------------------------------|------------------|-----------------------------|
|
|
753
|
+
| `value` | `number` | — | Giá trị (0–100) |
|
|
754
|
+
| `mode` | `'determinate'\|'indeterminate'` | `'determinate'` | Chế độ hiển thị |
|
|
755
|
+
| `showValue` | `boolean` | `false` | Hiển thị % bên trong thanh |
|
|
756
|
+
| `unit` | `string` | `'%'` | Đơn vị hiển thị |
|
|
757
|
+
| `color` | `string` | — | Màu thanh (hex/CSS var) |
|
|
758
|
+
|
|
759
|
+
#### Empty State — `AscEmptyStateComponent`
|
|
760
|
+
|
|
761
|
+
Giao diện khi không có dữ liệu để hiển thị.
|
|
762
|
+
|
|
763
|
+
```html
|
|
764
|
+
<asc-empty-state title="Không có dữ liệu" description="Chưa có bản ghi nào được tạo." />
|
|
765
|
+
|
|
766
|
+
<!-- Với action button -->
|
|
767
|
+
<asc-empty-state title="Chưa có cuộc họp nào" icon="pi pi-calendar">
|
|
768
|
+
<asc-button label="Tạo cuộc họp" icon="pi pi-plus" (clicked)="openCreate()" />
|
|
769
|
+
</asc-empty-state>
|
|
770
|
+
```
|
|
771
|
+
|
|
772
|
+
| Input | Type | Mô tả |
|
|
773
|
+
|---------------|----------|----------------------------------------------------|
|
|
774
|
+
| `title` | `string` | _(required)_ Tiêu đề |
|
|
775
|
+
| `icon` | `string` | PrimeIcon class (default: `'pi pi-inbox'`) |
|
|
776
|
+
| `description` | `string` | Mô tả bổ sung |
|
|
777
|
+
|
|
778
|
+
`ng-content` dùng cho action buttons hoặc nội dung custom.
|
|
779
|
+
|
|
780
|
+
#### Loading Bar — `AscLoadingBarComponent`
|
|
781
|
+
|
|
782
|
+
Thanh loading mỏng 3px cố định ở đầu trang, dùng kết hợp với `AscLoadingService` từ `@aseansc/http` để hiện/ẩn tự động theo trạng thái API call.
|
|
783
|
+
|
|
784
|
+
```ts
|
|
785
|
+
// app.component.ts
|
|
786
|
+
import { AscLoadingService } from '@aseansc/http';
|
|
787
|
+
|
|
788
|
+
loading = inject(AscLoadingService);
|
|
789
|
+
```
|
|
790
|
+
|
|
791
|
+
```html
|
|
792
|
+
<!-- app.component.html — đặt trước mọi content -->
|
|
793
|
+
<asc-loading-bar [visible]="loading.isLoading()" />
|
|
794
|
+
<p-toast />
|
|
795
|
+
<p-confirmdialog />
|
|
796
|
+
<router-outlet />
|
|
797
|
+
```
|
|
798
|
+
|
|
799
|
+
| Input | Type | Default | Mô tả |
|
|
800
|
+
|-----------|-----------|---------|----------------------------------------------|
|
|
801
|
+
| `visible` | `boolean` | `false` | Hiển thị/ẩn bar. Thường bind với `isLoading()` |
|
|
802
|
+
|
|
803
|
+
#### Loading Overlay — `AscLoadingOverlayComponent`
|
|
804
|
+
|
|
805
|
+
Overlay toàn màn hình với spinner ở giữa, block hoàn toàn tương tác người dùng trong khi xử lý tác vụ nặng. Có `backdrop-filter: blur(2px)` và z-index 10000.
|
|
806
|
+
|
|
807
|
+
```ts
|
|
808
|
+
// app.component.ts
|
|
809
|
+
import { AscLoadingService } from '@aseansc/http';
|
|
810
|
+
|
|
811
|
+
loading = inject(AscLoadingService);
|
|
812
|
+
```
|
|
813
|
+
|
|
814
|
+
```html
|
|
815
|
+
<!-- app.component.html -->
|
|
816
|
+
<asc-loading-overlay [visible]="loading.isLoading()" />
|
|
817
|
+
<!-- hoặc kèm message -->
|
|
818
|
+
<asc-loading-overlay [visible]="loading.isLoading()" message="Đang xử lý..." />
|
|
819
|
+
<p-toast />
|
|
820
|
+
<p-confirmdialog />
|
|
821
|
+
<router-outlet />
|
|
822
|
+
```
|
|
823
|
+
|
|
824
|
+
| Input | Type | Default | Mô tả |
|
|
825
|
+
|-----------|-----------|---------|-----------------------------------------------------|
|
|
826
|
+
| `visible` | `boolean` | `false` | Hiển thị/ẩn overlay. |
|
|
827
|
+
| `message` | `string` | `''` | Text tuỳ chọn hiển thị dưới spinner (vd: `'Đang xử lý...'`). |
|
|
828
|
+
|
|
829
|
+
---
|
|
830
|
+
|
|
831
|
+
## Validation Error Messages — `AscMessageErrorPipe`
|
|
832
|
+
|
|
833
|
+
`AscMessageErrorPipe` chuyển Angular validator error key thành human-readable message theo locale. Pipe này được `AscFormFieldComponent` dùng tự động — bạn không cần gọi trực tiếp khi dùng `<asc-form-field>`. Tuy nhiên bạn có thể dùng độc lập trong bất kỳ template nào.
|
|
834
|
+
|
|
835
|
+
### Cú pháp
|
|
836
|
+
|
|
837
|
+
```html
|
|
838
|
+
{{ errorKey | ascMessageError : label : control.errors }}
|
|
839
|
+
```
|
|
840
|
+
|
|
841
|
+
| Tham số | Type | Mô tả |
|
|
842
|
+
|----------------|--------------------|----------------------------------------------------|
|
|
843
|
+
| `errorKey` | `string` | Angular validator error key: `'required'`, `'email'`, ... |
|
|
844
|
+
| `label` | `string` | Tên field hiển thị trong message: `'Email'`, `'Họ tên'` |
|
|
845
|
+
| `control.errors` | `ValidationErrors \| null` | `AbstractControl.errors` — để pipe đọc metadata (vd: `minlength.requiredLength`) |
|
|
846
|
+
|
|
847
|
+
### Dùng trực tiếp trong template
|
|
848
|
+
|
|
849
|
+
```ts
|
|
850
|
+
import { AscMessageErrorPipe } from '@aseansc/ui';
|
|
851
|
+
|
|
852
|
+
@Component({
|
|
853
|
+
imports: [AscMessageErrorPipe, ReactiveFormsModule, KeyValuePipe],
|
|
854
|
+
template: `
|
|
855
|
+
<input [formControl]="emailCtrl" />
|
|
856
|
+
@if (emailCtrl.errors && emailCtrl.touched) {
|
|
857
|
+
@for (err of emailCtrl.errors | keyvalue; track err.key) {
|
|
858
|
+
<span class="error">
|
|
859
|
+
{{ err.key | ascMessageError : 'Email' : emailCtrl.errors }}
|
|
860
|
+
</span>
|
|
861
|
+
}
|
|
862
|
+
}
|
|
863
|
+
`,
|
|
864
|
+
})
|
|
865
|
+
export class MyForm {
|
|
866
|
+
emailCtrl = new FormControl('', [Validators.required, Validators.email]);
|
|
867
|
+
}
|
|
868
|
+
```
|
|
869
|
+
|
|
870
|
+
Kết quả:
|
|
871
|
+
|
|
872
|
+
| Validator | Output |
|
|
873
|
+
|-------------------------|-------------------------------------------|
|
|
874
|
+
| `Validators.required` | `Email là bắt buộc` |
|
|
875
|
+
| `Validators.email` | `Email không đúng định dạng email` |
|
|
876
|
+
| `Validators.minLength(6)` | `Email phải có ít nhất 6 ký tự` |
|
|
877
|
+
| `Validators.maxLength(100)` | `Email không được vượt quá 100 ký tự` |
|
|
878
|
+
| `Validators.min(0)` | `Email phải lớn hơn hoặc bằng 0` |
|
|
879
|
+
| `Validators.max(100)` | `Email phải nhỏ hơn hoặc bằng 100` |
|
|
880
|
+
| `Validators.pattern(...)` | `Email không đúng định dạng` |
|
|
881
|
+
|
|
882
|
+
### Built-in error keys
|
|
883
|
+
|
|
884
|
+
| Key | Validator tương ứng |
|
|
885
|
+
|-----------------|----------------------------------------------|
|
|
886
|
+
| `required` | `Validators.required` |
|
|
887
|
+
| `requiredTrue` | `Validators.requiredTrue` |
|
|
888
|
+
| `email` | `Validators.email` |
|
|
889
|
+
| `minlength` | `Validators.minLength(n)` |
|
|
890
|
+
| `maxlength` | `Validators.maxLength(n)` |
|
|
891
|
+
| `min` | `Validators.min(n)` |
|
|
892
|
+
| `max` | `Validators.max(n)` |
|
|
893
|
+
| `pattern` | `Validators.pattern(...)` |
|
|
894
|
+
| `phone` | custom validator |
|
|
895
|
+
| `url` | custom validator |
|
|
896
|
+
| `dateRange` | custom validator |
|
|
897
|
+
| `passwordMatch` | custom validator |
|
|
898
|
+
| `unique` | custom validator |
|
|
899
|
+
| `_fallback` | mọi key không có trong map → `"{label} không hợp lệ"` |
|
|
900
|
+
|
|
901
|
+
### Override message của built-in key
|
|
902
|
+
|
|
903
|
+
Truyền `validation.messages` vào `provideAscUI()` — chỉ cần khai báo key muốn đổi, các key còn lại giữ nguyên mặc định:
|
|
904
|
+
|
|
905
|
+
```ts
|
|
906
|
+
// app.config.ts
|
|
907
|
+
provideAscUI({
|
|
908
|
+
locale: 'vi-VN',
|
|
909
|
+
validation: {
|
|
910
|
+
messages: {
|
|
911
|
+
required: (label) => `${label} không được bỏ trống`,
|
|
912
|
+
minlength: (label, errors) => {
|
|
913
|
+
const min = (errors?.['minlength'] as any)?.requiredLength;
|
|
914
|
+
return `${label} tối thiểu ${min} ký tự`;
|
|
915
|
+
},
|
|
916
|
+
},
|
|
917
|
+
},
|
|
918
|
+
})
|
|
919
|
+
```
|
|
920
|
+
|
|
921
|
+
### Thêm error key cho custom validator
|
|
922
|
+
|
|
923
|
+
Tạo validator trả về object với key tùy chọn, sau đó đăng ký message tương ứng:
|
|
924
|
+
|
|
925
|
+
```ts
|
|
926
|
+
// validators/phone.validator.ts
|
|
927
|
+
export function phoneValidator(): ValidatorFn {
|
|
928
|
+
return (control) => {
|
|
929
|
+
const valid = /^(0[3|5|7|8|9])\d{8}$/.test(control.value);
|
|
930
|
+
return valid ? null : { phone: true }; // key = 'phone'
|
|
931
|
+
};
|
|
932
|
+
}
|
|
933
|
+
```
|
|
934
|
+
|
|
935
|
+
```ts
|
|
936
|
+
// validator với metadata (để pipe đọc thêm thông tin)
|
|
937
|
+
export function passwordStrengthValidator(minScore: number): ValidatorFn {
|
|
938
|
+
return (control) => {
|
|
939
|
+
const score = calcScore(control.value);
|
|
940
|
+
return score >= minScore ? null : { passwordStrength: { minScore, actualScore: score } };
|
|
941
|
+
};
|
|
942
|
+
}
|
|
943
|
+
```
|
|
944
|
+
|
|
945
|
+
```ts
|
|
946
|
+
// app.config.ts
|
|
947
|
+
provideAscUI({
|
|
948
|
+
validation: {
|
|
949
|
+
messages: {
|
|
950
|
+
// Key khớp với key trả về từ validator
|
|
951
|
+
phone: (label) =>
|
|
952
|
+
`${label} không đúng định dạng (vd: 0912345678)`,
|
|
953
|
+
|
|
954
|
+
passwordStrength: (label, errors) => {
|
|
955
|
+
const { minScore, actualScore } = (errors?.['passwordStrength'] ?? {}) as any;
|
|
956
|
+
return `${label} chưa đủ mạnh (điểm: ${actualScore}/${minScore})`;
|
|
957
|
+
},
|
|
958
|
+
},
|
|
959
|
+
},
|
|
960
|
+
})
|
|
961
|
+
```
|
|
962
|
+
|
|
963
|
+
```ts
|
|
964
|
+
// dùng trong form
|
|
965
|
+
password = new FormControl('', [
|
|
966
|
+
Validators.required,
|
|
967
|
+
passwordStrengthValidator(3),
|
|
968
|
+
]);
|
|
969
|
+
```
|
|
970
|
+
|
|
971
|
+
Template hiển thị tự động qua `<asc-form-field>`:
|
|
972
|
+
|
|
973
|
+
```html
|
|
974
|
+
<asc-form-field label="Mật khẩu">
|
|
975
|
+
<asc-password formControlName="password" />
|
|
976
|
+
</asc-form-field>
|
|
977
|
+
```
|
|
978
|
+
|
|
979
|
+
---
|
|
980
|
+
|
|
981
|
+
## Dark Mode
|
|
982
|
+
|
|
983
|
+
The library uses `.app-dark` on `<html>` to toggle dark mode. PrimeNG components and Tailwind utilities both respond to this class automatically — the `dark` variant is already registered by `@aseansc/ui/preset.css` (see [Setup](#2-stylesscss)), no extra config needed.
|
|
984
|
+
|
|
985
|
+
---
|
|
986
|
+
|
|
987
|
+
## i18n
|
|
988
|
+
|
|
989
|
+
```ts
|
|
990
|
+
provideAscUI({ locale: 'vi-VN' }) // mặc định — Tiếng Việt
|
|
991
|
+
provideAscUI({ locale: 'en-US' }) // English
|
|
992
|
+
```
|
|
993
|
+
|
|
994
|
+
### Đổi ngôn ngữ runtime — không cần reload
|
|
995
|
+
|
|
996
|
+
`locale` truyền vào `provideAscUI()` chỉ set giá trị **khởi tạo**. Để đổi ngôn ngữ khi app đang chạy (vd: dropdown chọn ngôn ngữ trên topbar), dùng `AscLocaleService` — mọi label, message, và cả translation nội bộ của PrimeNG (tên tháng, filter operator trong table, aria label...) sẽ tự cập nhật ngay lập tức, không cần reload trang.
|
|
997
|
+
|
|
998
|
+
```ts
|
|
999
|
+
import { AscLocaleService } from '@aseansc/ui';
|
|
1000
|
+
|
|
1001
|
+
@Component({ ... })
|
|
1002
|
+
export class LanguageSwitcherComponent {
|
|
1003
|
+
private locale = inject(AscLocaleService);
|
|
1004
|
+
|
|
1005
|
+
switchToEnglish() {
|
|
1006
|
+
this.locale.setLocale('en-US');
|
|
1007
|
+
}
|
|
1008
|
+
|
|
1009
|
+
// Đọc locale hiện tại (signal) — dùng để highlight nút đang active, v.v.
|
|
1010
|
+
protected readonly currentLocale = this.locale.locale;
|
|
1011
|
+
}
|
|
1012
|
+
```
|
|
1013
|
+
|
|
1014
|
+
---
|
|
1015
|
+
|
|
1016
|
+
## License
|
|
1017
|
+
|
|
1018
|
+
UNLICENSED — Internal use only.
|