@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/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.