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