@sdcorejs/angular 20.1.2 → 20.1.4

package/README.md

@@ -1,885 +1,205 @@
 # @sdcorejs/angular
 
-> Angular UI library built on Angular Material - supports Angular 19 / 20 / 21.
+Angular Material-based UI building blocks for data-heavy business applications. The package combines standalone components, consistent form controls, workflow primitives, application services, theming, and localization for Angular 19, 20, and 21.
 
-[![Angular](https://img.shields.io/badge/Angular-19%2B-red)](https://angular.dev)
-[![Angular Material](https://img.shields.io/badge/Angular_Material-19%2B-purple)](https://material.angular.io)
+[![npm version](https://img.shields.io/npm/v/@sdcorejs/angular.svg)](https://www.npmjs.com/package/@sdcorejs/angular)
+[![monthly npm downloads](https://img.shields.io/npm/dm/@sdcorejs/angular.svg)](https://www.npmjs.com/package/@sdcorejs/angular)
+[![Angular 19, 20, and 21](https://img.shields.io/badge/Angular-19%20%7C%2020%20%7C%2021-DD0031?logo=angular&logoColor=white)](#compatibility)
+[![MIT license](https://img.shields.io/github/license/sdcorejs/sdcorejs-angular.svg)](https://github.com/sdcorejs/sdcorejs-angular/blob/main/LICENSE)
 
-**🚀 [Showcase](https://sdcorejs.github.io/sdcorejs-angular)** · **📖 [Storybook — code samples, props & API](https://sdcorejs.github.io/portal-template)**
+[Showcase](https://sdcorejs.github.io/sdcorejs-angular/) · [Quick start](#quick-start) · [API manifest](https://sdcorejs.github.io/sdcorejs-angular/docs/latest/index.json) · [Source](https://github.com/sdcorejs/sdcorejs-angular) · [Changelog](https://github.com/sdcorejs/sdcorejs-angular/blob/main/CHANGELOG.md) · [Issues](https://github.com/sdcorejs/sdcorejs-angular/issues)
 
----
+## Compatibility
 
-## Table of Contents / Mục lục
+Install the package major that matches your Angular application.
 
-- [Getting Started / Cài đặt](#getting-started--cài-đặt)
-- [Theming / SCSS Customization](#theming--scss-customization)
-- [AI Agent Usage Guardrails](#ai-agent-usage-guardrails)
-- [Components](#components)
-  - [SdButton](#sdbutton)
-  - [SdBadge](#sdbadge)
-  - [SdSection](#sdsection)
-  - [SdModal](#sdmodal)
-  - [SdTable](#sdtable)
-  - [SdAvatar](#sdavatar)
-  - [Other Components](#other-components--các-component-khác)
-- [Form Components](#form-components)
-- [CRUD Patterns / Code mẫu CRUD](#crud-patterns--code-mẫu-crud)
-- [Contributing Guide / Hướng dẫn đóng góp](#contributing-guide--hướng-dẫn-đóng-góp)
+| Angular | Package                 | Recommended install                                                                              |
+| ------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
+| 19.x    | `@sdcorejs/angular@^19` | `npm install @sdcorejs/angular@^19 @angular/material@^19 @angular/material-date-fns-adapter@^19` |
+| 20.x    | `@sdcorejs/angular@^20` | `npm install @sdcorejs/angular@^20 @angular/material@^20 @angular/material-date-fns-adapter@^20` |
+| 21.x    | `@sdcorejs/angular@^21` | `npm install @sdcorejs/angular@^21 @angular/material@^21 @angular/material-date-fns-adapter@^21` |
 
----
+The package manifests accept Angular 19–21 peers, while releases provide an Angular-aligned package line for each major. The first version number is reserved for Angular compatibility, so read the [changelog](https://github.com/sdcorejs/sdcorejs-angular/blob/main/CHANGELOG.md) for explicitly labeled breaking changes before upgrading.
 
-## Getting Started / Cài đặt
+## Installation and setup
 
-### Prerequisites / Yêu cầu
-
-| Dependency                           | Version                             |
-| ------------------------------------ | ----------------------------------- |
-| `@angular/core`                      | `^19.0.0 \|\| ^20.0.0 \|\| ^21.0.0` |
-| `@angular/material`                  | `^19.0.0 \|\| ^20.0.0 \|\| ^21.0.0` |
-| `@angular/material-date-fns-adapter` | `^19.0.0 \|\| ^20.0.0 \|\| ^21.0.0` |
-| `date-fns`                           | `^3 \|\| ^4`                        |
-
-### Installation / Cài đặt
+The examples below use Angular 19; replace `19` with your application's Angular major.
 
 ```bash
-npm install @sdcorejs/angular
+npm install @sdcorejs/angular@^19 @angular/material@^19 @angular/material-date-fns-adapter@^19
 ```
 
-### Setup
-
-**1. Import global styles / Import style toàn cục**
-
-Thêm vào `angular.json` (hoặc `styles.scss` của app):
-
-```json
-// angular.json
-{
-  "styles": ["node_modules/@sdcorejs/angular/assets/scss/sd-core.scss"]
-}
-```
-
-hoặc trong `styles.scss`:
+Load the global stylesheet once:
 
 ```scss
+/* styles.scss */
 @use '@sdcorejs/angular/assets/scss/sd-core';
 ```
 
-**2. Import Material Icons font / Font icon**
-
-Thêm vào `index.html`:
-
-```html
-<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined" rel="stylesheet" />
-<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;600&display=swap" rel="stylesheet" />
-```
-
-**3. Configure providers / Cấu hình providers**
-
-```typescript
-// app.config.ts
-import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideAnimationsAsync(),
-    // ... các providers khác
-  ],
-};
-```
-
----
-
-## Theming / SCSS Customization
-
-`sd-core.scss` emits the Angular Material M3 theme with `mat.theme(...)`.
-Prefer Core UI variables such as `--sd-primary`, `--sd-surface`, `--sd-text`,
-and `--sd-border` in application code. Material system variables remain an
-implementation detail for Angular Material overrides.
-
-### CSS Variables
-
-`@sdcorejs/angular` sử dụng CSS custom properties (variables) để quản lý màu sắc. Mỗi màu được expose dưới dạng `--sd-<color>`.
+The stylesheet includes the Roboto, Material Icons, and Material Symbols font files used by the library. No Google Fonts link is required. `@sdcorejs/utils`, `date-fns`, and other declared implementation dependencies install transitively.
 
-**Available color tokens / Các biến màu sắc:**
+## Quick start
 
-Core UI exposes a small public token surface: semantic palettes for component
-states, plus neutral tokens for surface, text, border, and disabled states.
-
-| Variable | Default bridge / fallback | Description |
-| -------- | ------------------------- | ----------- |
-| `--sd-primary` | `var(--mat-sys-primary, #005cbb)` | Main action color |
-| `--sd-primary-light` | `color-mix(in srgb, var(--sd-primary) 14%, white)` | Soft primary background |
-| `--sd-primary-dark` | `color-mix(in srgb, var(--sd-primary) 84%, black)` | Hover/active primary shade |
-| `--sd-primary-contrast` | `#ffffff` | Text/icon on primary |
-| `--sd-secondary` | `var(--mat-sys-secondary, #5c6270)` | Secondary action/accent |
-| `--sd-secondary-light` | `color-mix(in srgb, var(--sd-secondary) 12%, white)` | Soft secondary background |
-| `--sd-secondary-dark` | `color-mix(in srgb, var(--sd-secondary) 84%, black)` | Hover/active secondary shade |
-| `--sd-secondary-contrast` | `#ffffff` | Text/icon on secondary |
-| `--sd-info`, `--sd-success`, `--sd-warning`, `--sd-error` | Semantic base colors | Info, success, warning, and error states |
-| `--sd-*-light` / `--sd-*-dark` / `--sd-*-contrast` | Generated from each semantic base | Soft background, active shade, and readable foreground |
-| `--sd-surface` | `var(--mat-sys-surface, #fdfbff)` | App/page surface |
-| `--sd-surface-muted` | `var(--mat-sys-surface-container-highest, #e7e8ed)` | Muted neutral background |
-| `--sd-text` | `var(--mat-sys-on-surface, #1a1b1f)` | Primary text |
-| `--sd-text-secondary` | `var(--mat-sys-on-surface-variant, #44474f)` | Secondary text |
-| `--sd-text-muted` | `color-mix(in srgb, var(--sd-text) 62%, transparent)` | Muted text |
-| `--sd-border` | `var(--mat-sys-outline-variant, #c4c6d0)` | Divider/subtle border |
-| `--sd-border-strong` | `var(--mat-sys-outline, #74777f)` | Strong border/focus outline |
-| `--sd-disabled-bg` | `color-mix(in srgb, var(--sd-text) 8%, transparent)` | Disabled background |
-| `--sd-disabled-text` | `color-mix(in srgb, var(--sd-text) 60%, transparent)` | Disabled text/icon |
-
-### Custom Theme / Tuỳ chỉnh theme
-
-Ghi đè theme mặc định bằng cách truyền map SCSS vào mixin `theme()`:
-
-```scss
-// styles.scss
-@use '@sdcorejs/angular/assets/scss/themes/default' as default;
-
-html {
-  @include default.theme(
-    (
-      primary: #7c3aed,
-      primary-light: #ede9fe,
-      primary-dark: #5b21b6,
-      success: #10b981,
-      error: #ef4444,
-    )
-  );
-}
-```
-
-Chỉ cần override các màu muốn thay đổi — các màu còn lại giữ nguyên giá trị mặc định.
-
-### Utility Classes / Các class tiện ích
-
-Thư viện cung cấp sẵn các utility class:
-
-```html
-<!-- Text color -->
-<span class="text-primary">Text màu primary</span>
-<span class="text-error">Text màu error</span>
-
-<!-- Background -->
-<div class="bg-primary-light">Background nhạt</div>
-
-<!-- Spacing (đơn vị px, từ 0–200) -->
-<div class="mt-16 mb-8 px-24">margin-top: 16px, padding: 0 24px</div>
-
-<!-- Gap -->
-<div class="d-flex gap-8">gap: 8px</div>
-
-<!-- Grid -->
-<div class="sd-grid-container grid-cols-3">
-  <div class="col-span-2">Chiếm 2 cột</div>
-  <div class="col-span-1">Chiếm 1 cột</div>
-</div>
-
-<!-- Bootstrap grid -->
-<div class="row">
-  <div class="col-6">50%</div>
-  <div class="col-6">50%</div>
-</div>
-```
-
----
-
-## AI Agent Usage Guardrails
-
-Use this section as a checklist when generating SDCoreJS Angular code from online docs.
-
-### 1. Standalone imports are mandatory
-
-Every component, directive, and pipe used in a standalone template must be listed in the host component's `imports`. This includes template-only directives such as `sdTableCellDef`, `sdTableFilterDef`, `sdSuffixDef`, `sdViewDef`, `sdItemDef`, and shared display pipes.
+This standalone component renders a primary action and shows the button's built-in loading state while work is in progress. No SDCoreJS-specific provider is required for this example.
 
 ```ts
-import { Component } from '@angular/core';
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
 import { SdButton } from '@sdcorejs/angular/components/button';
-import {
-  SdTable,
-  SdTableCellDefDirective,
-  SdTableFilterDefDirective,
-  SdTableFooterDefDirective,
-  SdTableTitleDefDirective,
-} from '@sdcorejs/angular/components/table';
-import { SdInput, SdInputNumber, SdSelect } from '@sdcorejs/angular/forms';
-import { SdItemDefDefDirective, SdSuffixDefDirective, SdViewDefDirective } from '@sdcorejs/angular/forms/directives';
-import { SdFormatDatePipe, SdFormatDatetimePipe, SdFormatNumberPipe, SdViewPipe } from '@sdcorejs/angular/pipes';
 
 @Component({
+  selector: 'app-root',
   standalone: true,
-  imports: [
-    SdButton,
-    SdTable,
-    SdTableCellDefDirective,
-    SdTableFilterDefDirective,
-    SdTableFooterDefDirective,
-    SdTableTitleDefDirective,
-    SdInput,
-    SdInputNumber,
-    SdSelect,
-    SdItemDefDefDirective,
-    SdSuffixDefDirective,
-    SdViewDefDirective,
-    SdFormatNumberPipe,
-    SdFormatDatePipe,
-    SdFormatDatetimePipe,
-    SdViewPipe,
-  ],
-  templateUrl: './list.component.html',
-})
-export class ListComponent {}
-```
-
-Common missed imports:
-
-| Template usage                            | Required import                                                       |
-| ----------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------- |
-| `<ng-template sdTableCellDef="amount">`   | `SdTableCellDefDirective` from `@sdcorejs/angular/components/table`   |
-| `<ng-template sdTableFilterDef="status">` | `SdTableFilterDefDirective` from `@sdcorejs/angular/components/table` |
-| `<ng-template sdTableTitleDef="name">`    | `SdTableTitleDefDirective` from `@sdcorejs/angular/components/table`  |
-| `<ng-template sdTableFooterDef="amount">` | `SdTableFooterDefDirective` from `@sdcorejs/angular/components/table` |
-| `<ng-template sdTableExpandDef>`          | `SdTableExpandDefDirective` from `@sdcorejs/angular/components/table` |
-| `<ng-template sdSuffixDef>`               | `SdSuffixDefDirective` from `@sdcorejs/angular/forms/directives`      |
-| `<ng-template sdViewDef>`                 | `SdViewDefDirective` from `@sdcorejs/angular/forms/directives`        |
-| `<ng-template sdItemDef>`                 | `SdItemDefDefDirective` from `@sdcorejs/angular/forms/directives`     |
-| `                                         | sdFormatNumber`                                                       | `SdFormatNumberPipe` from `@sdcorejs/angular/pipes`   |
-| `                                         | sdFormatDate`                                                         | `SdFormatDatePipe` from `@sdcorejs/angular/pipes`     |
-| `                                         | sdFormatDatetime`                                                     | `SdFormatDatetimePipe` from `@sdcorejs/angular/pipes` |
-| `                                         | sdView`                                                               | `SdViewPipe` from `@sdcorejs/angular/pipes`           |
-
-### 2. Table cells use dense form controls
-
-When rendering an editable SD form control inside `<sd-table>` cell templates or custom inline filter templates, always use `size="sm"` and `hideInlineError`. This keeps row height stable and surfaces validation through the compact error icon/tooltip instead of inserting inline error text inside the table row.
-
-```html
-<sd-table [option]="tableOption">
-  <ng-template sdTableCellDef="quantity" let-row>
-    <sd-input-number size="sm" hideInlineError type="positive" [precision]="0" [(model)]="row.quantity"> </sd-input-number>
-  </ng-template>
-
-  <ng-template sdTableCellDef="status" let-row>
-    <sd-select size="sm" hideInlineError [items]="statusList" valueField="code" displayField="name" [(model)]="row.status"> </sd-select>
-  </ng-template>
-
-  <ng-template sdTableFilterDef="keyword" let-filter let-update="update">
-    <sd-input size="sm" hideInlineError [(model)]="filter.keyword" (keyupEnter)="update()"> </sd-input>
-  </ng-template>
-</sd-table>
-```
-
-### 3. Prefer shared display pipes
-
-Do not create app-local pipes for common display formatting.
-
-```html
-<!-- Good -->
-{{ row.amount | sdFormatNumber : 0 | sdView }} {{ row.issueDate | sdFormatDate | sdView }} {{ row.updatedAt | sdFormatDatetime : 'dd/MM/yyyy
-HH:mm' | sdView }} {{ row.tags | sdView }}
-
-<!-- Avoid -->
-{{ row.amount | customCurrency }} {{ row.issueDate | date : 'dd/MM/yyyy' }} {{ row.tags?.join(', ') || '--' }}
-```
-
-- `sdFormatNumber` formats numbers using SDCoreJS locale configuration.
-- `sdFormatDate` formats date-only values with default `dd/MM/yyyy`.
-- `sdFormatDatetime` formats date-time values with default `dd/MM/yyyy HH:mm:ss`.
-- `sdView` renders `--` for `null`, `undefined`, `''`, `NaN`, and empty arrays; primitive arrays render as `A, B`.
-
-### 4. Command icons default to Material Symbols Outlined
-
-Table row commands and child command menu items default to the outline Material icon font set. Only set `fontSet` when a specific icon family is required.
-
-```ts
-command: {
-  align: 'right',
-  commands: [
-    { icon: 'edit', title: 'Edit', click: row => this.edit(row) },
-    {
-      icon: 'more_vert',
-      title: 'More',
-      children: [
-        { icon: 'visibility', title: 'View', click: row => this.view(row) },
-        { icon: 'delete', title: 'Delete', color: 'error', click: row => this.delete(row) },
-      ],
-    },
-  ],
-}
-```
-
----
-
-## Components
-
-> Tất cả component đều là **standalone** và sử dụng **Angular Signals** API.  
-> All components are **standalone** and use **Angular Signals** API.
-
-### SdButton
-
-```typescript
-import { SdButton } from '@sdcorejs/angular/components/button';
-```
-
-**Inputs:**
-
-| Input        | Type                                       | Default       | Description                        |
-| ------------ | ------------------------------------------ | ------------- | ---------------------------------- |
-| `type`       | `'fill' \| 'light' \| 'outline' \| 'text'` | `'light'`     | Kiểu nút                           |
-| `color`      | `Color`                                    | `'secondary'` | Màu sắc                            |
-| `size`       | `'sm' \| 'md' \| 'lg'`                     | `'sm'`        | Kích thước                         |
-| `title`      | `string`                                   | —             | Nhãn nút                           |
-| `prefixIcon` | `string`                                   | —             | Icon Material trước text           |
-| `suffixIcon` | `string`                                   | —             | Icon Material sau text             |
-| `disabled`   | `boolean`                                  | `false`       | Vô hiệu hoá                        |
-| `loading`    | `boolean`                                  | `false`       | Trạng thái loading (tự chặn click) |
-| `tooltip`    | `string`                                   | —             | Tooltip khi hover                  |
-| `width`      | `string`                                   | —             | CSS width tuỳ chỉnh                |
-
-**Output:** `(click): EventEmitter<Event>` — có throttle 300ms, tự chặn khi `disabled` hoặc `loading`.
-
-```html
-<sd-button type="fill" color="primary" title="Lưu" prefixIcon="save" (click)="onSave()" />
-<sd-button type="outline" color="error" prefixIcon="delete" tooltip="Xoá" />
-<sd-button type="light" title="Huỷ" (click)="modal.close()" />
-<sd-button type="fill" color="primary" title="Đang xử lý" [loading]="true" />
-```
-
----
-
-### SdBadge
-
-```typescript
-import { SdBadge } from '@sdcorejs/angular/components/badge';
-```
-
-**Inputs:**
-
-| Input     | Type                         | Default       | Description       |
-| --------- | ---------------------------- | ------------- | ----------------- |
-| `type`    | `'tag' \| 'round' \| 'icon'` | `'icon'`      | Kiểu badge        |
-| `color`   | `Color`                      | `'secondary'` | Màu sắc           |
-| `title`   | `string \| number`           | —             | Nội dung hiển thị |
-| `icon`    | `string`                     | —             | Icon Material     |
-| `size`    | `Size`                       | `'sm'`        | Kích thước        |
-| `tooltip` | `string`                     | —             | Tooltip           |
-
-Shorthand color inputs (boolean): `primary`, `secondary`, `success`, `info`, `warning`, `error`.
-
-```html
-<sd-badge type="tag" color="success" title="Hoạt động" />
-<sd-badge type="round" [warning]="true" title="Chờ duyệt" />
-<sd-badge type="icon" color="error" icon="close" title="Từ chối" />
-```
-
----
-
-### SdSection
-
-```typescript
-import { SdSection } from '@sdcorejs/angular/components/section';
-```
-
-**Inputs:**
-
-| Input         | Type      | Default     | Description                |
-| ------------- | --------- | ----------- | -------------------------- |
-| `title`       | `string`  | _required_  | Tiêu đề section            |
-| `subTitle`    | `string`  | —           | Tiêu đề phụ                |
-| `icon`        | `string`  | —           | Icon Material              |
-| `iconColor`   | `Color`   | `'primary'` | Màu icon                   |
-| `collapsible` | `boolean` | `false`     | Cho phép thu gọn           |
-| `collapsed`   | `boolean` | `false`     | Trạng thái ban đầu thu gọn |
-| `hideHeader`  | `boolean` | `false`     | Ẩn phần header             |
-
-```html
-<sd-section title="Thông tin cơ bản" icon="person" iconColor="primary">
-  <!-- nội dung -->
-</sd-section>
-
-<sd-section title="Cài đặt nâng cao" icon="settings" collapsible [collapsed]="true">
-  <!-- nội dung ẩn mặc định -->
-</sd-section>
-```
-
----
-
-### SdModal
-
-```typescript
-import { SdModal } from '@sdcorejs/angular/components/modal';
-```
-
-**Inputs:**
-
-| Input             | Type                                     | Default     | Description                      |
-| ----------------- | ---------------------------------------- | ----------- | -------------------------------- |
-| `title`           | `string`                                 | —           | Tiêu đề modal                    |
-| `color`           | `Color`                                  | `'primary'` | Màu header                       |
-| `width`           | `'sx' \| 'sm' \| 'md' \| 'lg' \| string` | `'md'`      | Độ rộng (md = 60vw)              |
-| `height`          | `string`                                 | `'auto'`    | Chiều cao                        |
-| `view`            | `'dialog' \| 'bottom-sheet'`             | auto        | Tự động bottom-sheet trên mobile |
-| `lazyLoadContent` | `boolean`                                | `true`      | Lazy render nội dung             |
-
-**Output:** `(sdClosed): EventEmitter` — phát ra khi modal đóng.
-
-**Methods** (dùng qua `@ViewChild`):
-
-- `modal.open()` — mở modal
-- `modal.close()` — đóng modal
-
-> ⚠️ Nội dung modal phải đặt trong `<ng-template>`.
-
-```html
-<sd-modal #myModal title="Thêm mới" width="md" (sdClosed)="onClosed()">
-  <ng-template>
-    <div class="modal-body p-16">
-      <!-- nội dung form -->
-    </div>
-    <div class="modal-footer d-flex justify-content-end gap-8 p-16">
-      <sd-button title="Huỷ" (click)="myModal.close()" />
-      <sd-button type="fill" color="primary" title="Lưu" (click)="onSave()" />
-    </div>
-  </ng-template>
-</sd-modal>
-
-<sd-button title="Mở modal" prefixIcon="add" (click)="myModal.open()" />
-```
-
----
-
-### SdTable
-
-```typescript
-import { SdTable } from '@sdcorejs/angular/components/table';
-import type { SdTableOption, SdTableColumn } from '@sdcorejs/angular/components/table';
-```
-
-SdTable nhận một object `option` duy nhất kiểu `SdTableOption<T>`.
-
-**Column types / Kiểu cột:**
-
-| `type`          | Mô tả                     |
-| --------------- | ------------------------- |
-| `'string'`      | Văn bản                   |
-| `'number'`      | Số (tự format)            |
-| `'boolean'`     | True/False                |
-| `'date'`        | Ngày                      |
-| `'datetime'`    | Ngày giờ                  |
-| `'time'`        | Giờ                       |
-| `'values'`      | Enum từ danh sách cố định |
-| `'lazy-values'` | Enum load async           |
-| `'children'`    | Cột nhóm (multi-header)   |
-
-**Local table:**
-
-```typescript
-option: SdTableOption<Product> = {
-  type: 'local',
-  items: () => this.products,
-  columns: [
-    { field: 'code', type: 'string', title: 'Mã', width: '120px' },
-    { field: 'name', type: 'string', title: 'Tên', sortable: true },
-    { field: 'price', type: 'number', title: 'Đơn giá', align: 'right' },
-    {
-      field: 'active',
-      type: 'boolean',
-      title: 'Kích hoạt',
-      useBadge: val => ({ color: val ? 'success' : 'secondary', title: val ? 'Có' : 'Không' }),
-    },
-  ],
-  paginate: { pageSize: 20 },
-  reload: { visible: true },
-};
-```
-
-**Server-side table:**
-
-```typescript
-option: SdTableOption<Product> = {
-  type: 'server',
-  items: async (filterRequest, pagingReq) => {
-    const res = await this.service.search({
-      keyword: filterRequest.keyword,
-      page: pagingReq.page,
-      pageSize: pagingReq.pageSize,
-    });
-    return { items: res.data, total: res.total };
-  },
-  columns: [
-    { field: 'code', type: 'string', title: 'Mã', width: '120px' },
-    { field: 'name', type: 'string', title: 'Tên', sortable: true },
-    {
-      field: 'status',
-      type: 'values',
-      title: 'Trạng thái',
-      useBadge: val => ({ color: val === 'ACTIVE' ? 'success' : 'secondary', title: val }),
-    },
-  ],
-  command: {
-    align: 'right',
-    commands: [
-      { icon: 'edit', color: 'primary', title: 'Sửa', click: row => this.onEdit(row) },
-      { icon: 'delete', color: 'error', title: 'Xoá', click: row => this.onDelete(row) },
-    ],
-  },
-};
-```
-
-```html
-<sd-table #sdTable [option]="option" />
-```
+  imports: [SdButton],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <sd-button type="fill" color="primary" title="Save changes" [loading]="saving()" (click)="save()" />
 
-**Tree rows / Dòng cây:**
+    <p aria-live="polite">{{ status() }}</p>
+  `,
+})
+export class AppComponent {
+  readonly saving = signal(false);
+  readonly status = signal('Ready');
 
-`tree` là discriminated union theo `loadType`. Icon expand (`chevron_right` / `expand_more`) nằm ở **cột đầu** — cột STT khi bật `index`, ngược lại cột data đầu tiên — thụt lề theo cấp.
+  async save(): Promise<void> {
+    this.saving.set(true);
+    this.status.set('Saving…');
 
-```typescript
-// loadType: 'static' — children embedded sẵn trong mỗi row
-tree: { loadType: 'static', childrenKey: 'children', defaultExpanded: 1 }
+    await new Promise<void>(resolve => setTimeout(resolve, 700));
 
-// loadType: 'lazy' — nạp con khi bung (Promise); hasChildren gate icon expand
-tree: {
-  loadType: 'lazy',
-  hasChildren: (row) => row.type === 'Folder',     // chỉ Folder mới có icon expand
-  onExpandChildren: (row) => api.getChildren(row.id),  // () => Promise<T[]>
+    this.status.set('Saved');
+    this.saving.set(false);
+  }
 }
 ```
 
-- **Child-level search** (`type: 'local'` + `loadType: 'static'`): lọc inline tìm cả **cấp con** — giữ nhánh cha của node khớp, ẩn sibling không khớp, tự bung tới node khớp. Clear filter khôi phục cây.
-- **Lazy loading**: spinner hiện trong ô chevron khi `onExpandChildren` đang chạy; `hasChildren` quyết định dòng nào hiện icon (không truyền = mọi node đều hiện).
+Replace the timer with your typed service call and reset `saving` in a `finally` block in production code.
 
----
+## Main capabilities
 
-### SdAvatar
+| Area              | Representative APIs                                                                                                             |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| UI components     | Navigation/data state, PDF preview, job progress, audit diff, modals, drawers, tabs, charts, editors, and document tooling      |
+| Data and workflow | Local/server tables, entity/tree pickers, query builders, unsaved-change guards, background tasks, upload, and Excel import     |
+| Form controls     | Text/mask, number, time/time range, date/date range, datetime, select, autocomplete, checkbox, radio, switch, chip, and color   |
+| Services          | Typed API/retry/cancel, ref-counted loading, graph-safe persistence/cache/storage, viewport signals, notifications, and exports |
+| Portal modules    | Auth, Keycloak, permission, layout, and icon modules                                                                            |
+| Localization      | Built-in `vi`, `en`, `ja`, `ko`, and `zh` catalogs, plus a synchronous custom-catalog provider                                  |
 
-```typescript
-import { SdAvatar } from '@sdcorejs/angular/components/avatar';
-```
-
-```html
-<sd-avatar src="/api/avatar/123" name="Nguyễn Văn A" size="md" /> <sd-avatar name="NVA" color="primary" size="lg" />
-```
-
----
-
-### Other Components / Các component khác
-
-| Component           | Import                                          | Mô tả                             |
-| ------------------- | ----------------------------------------------- | --------------------------------- |
-| `SdTabRouter`       | `@sdcorejs/angular/components/tab-router`       | Tab navigation với Angular Router |
-| `SdSideDrawer`      | `@sdcorejs/angular/components/side-drawer`      | Drawer layout trái/phải           |
-| `SdUploadFile`      | `@sdcorejs/angular/components/upload-file`      | Upload file                       |
-| `SdQuickAction`     | `@sdcorejs/angular/components/quick-action`     | Nút action dạng icon              |
-| `SdHistory`         | `@sdcorejs/angular/components/history`          | Lịch sử thay đổi                  |
-| `SdImportExcel`     | `@sdcorejs/angular/components/import-excel`     | Wizard import Excel               |
-| `SdQueryBuilder`    | `@sdcorejs/angular/components/query-builder`    | Visual query builder              |
-| `SdCodeEditor`      | `@sdcorejs/angular/components/code-editor`      | Code editor (PrismJS)             |
-| `SdMiniEditor`      | `@sdcorejs/angular/components/mini-editor`      | Rich text editor nhỏ              |
-| `SdDocumentBuilder` | `@sdcorejs/angular/components/document-builder` | Document builder                  |
-| `SdAnchorMain`      | `@sdcorejs/angular/components/anchor`           | Anchor / mục lục cuộn trang       |
-| `SdView`            | `@sdcorejs/angular/components/view`             | View wrapper read-only            |
-
----
-
-## Form Components
-
-```typescript
-import {
-  SdInput, // Text input
-  SdInputNumber, // Number input
-  SdSelect, // Dropdown
-  SdAutocomplete, // Autocomplete
-  SdDate, // Date picker
-} from '@sdcorejs/angular/forms';
-```
+The [live showcase](https://sdcorejs.github.io/sdcorejs-angular/) demonstrates components, forms, and services. The [latest API manifest](https://sdcorejs.github.io/sdcorejs-angular/docs/latest/index.json) lists every published reference document without duplicating the full API here.
 
-```html
-<sd-input [(model)]="form.name" label="Họ tên" [required]="true" />
+## Standalone and subpath imports
 
-<sd-input-number [(model)]="form.price" label="Đơn giá" [min]="0" suffix="VNĐ" />
+Prefer public leaf entry points so dependencies stay explicit and unused entry points can be removed from the application graph. The package declares `sideEffects: false`.
 
-<sd-select [(model)]="form.status" label="Trạng thái" [items]="statusList" valueField="value" displayField="label" />
-
-<sd-date [(model)]="form.birthday" label="Ngày sinh" />
+```ts
+import { SdButton } from '@sdcorejs/angular/components/button';
+import { SdTable, type SdTableOption } from '@sdcorejs/angular/components/table';
+import { SdInput } from '@sdcorejs/angular/forms/input';
+import { SdNotifyService } from '@sdcorejs/angular/services/notify';
+import { I18nService } from '@sdcorejs/angular/i18n';
 ```
 
----
+Import standalone components in the host component's `imports` array and inject services normally.
 
-## CRUD Patterns / Code mẫu CRUD
+Form controls use `[(model)]`. For group validation, pass a `FormGroup` through `[form]` and provide a `name`; SDCoreJS controls do not use `formControlName` or `[(ngModel)]` as their integration contract.
 
-### List Component
-
-```typescript
-// product-list.component.ts
-import { Component, OnInit, ViewChild, signal } from '@angular/core';
-import { SdTable, SdTableOption } from '@sdcorejs/angular/components/table';
-import { SdButton } from '@sdcorejs/angular/components/button';
-import { SdModal } from '@sdcorejs/angular/components/modal';
-import { SdSection } from '@sdcorejs/angular/components/section';
-import { SdInput, SdSelect } from '@sdcorejs/angular/forms';
-
-interface Product {
-  id: number;
-  code: string;
-  name: string;
-  price: number;
-  status: 'ACTIVE' | 'INACTIVE';
-}
+```ts
+import { Component } from '@angular/core';
+import { FormGroup } from '@angular/forms';
+import { SdInput } from '@sdcorejs/angular/forms/input';
 
 @Component({
-  selector: 'app-product-list',
-  templateUrl: './product-list.component.html',
+  selector: 'app-customer-form',
   standalone: true,
-  imports: [SdTable, SdButton, SdModal, SdSection, SdInput, SdSelect],
+  imports: [SdInput],
+  template: `
+    <sd-input [form]="customerForm" name="customerName" label="Customer name" required maxlength="100" [(model)]="customer.name" />
+  `,
 })
-export class ProductListComponent implements OnInit {
-  @ViewChild('formModal') formModal!: SdModal;
-  @ViewChild('sdTable') sdTable?: SdTable<Product>;
-
-  selectedItem: Product | null = null;
-  formData: Partial<Product> = {};
-  isSaving = signal(false);
-
-  readonly STATUS_LIST = [
-    { value: 'ACTIVE', label: 'Hoạt động' },
-    { value: 'INACTIVE', label: 'Dừng' },
-  ];
-
-  option!: SdTableOption<Product>;
-
-  constructor(private service: ProductService) {}
-
-  ngOnInit() {
-    this.option = {
-      type: 'server',
-      items: async (filter, paging) => this.service.search(filter, paging),
-      columns: [
-        { field: 'code', type: 'string', title: 'Mã', width: '120px' },
-        { field: 'name', type: 'string', title: 'Tên', sortable: true },
-        { field: 'price', type: 'number', title: 'Đơn giá', align: 'right' },
-        {
-          field: 'status',
-          type: 'values',
-          title: 'Trạng thái',
-          option: { items: this.STATUS_LIST, valueField: 'value', displayField: 'label' },
-          useBadge: val => ({
-            color: val === 'ACTIVE' ? 'success' : 'secondary',
-            title: this.STATUS_LIST.find(s => s.value === val)?.label,
-          }),
-        },
-      ],
-      command: {
-        align: 'right',
-        commands: [
-          { icon: 'edit', color: 'primary', title: 'Sửa', click: row => this.openForm(row) },
-          { icon: 'delete', color: 'error', title: 'Xoá', click: row => this.onDelete(row) },
-        ],
-      },
-      paginate: { pageSize: 20 },
-      reload: { visible: true },
-    };
-  }
-
-  openForm(item?: Product) {
-    this.selectedItem = item || null;
-    this.formData = item ? { ...item } : { status: 'ACTIVE' };
-    this.formModal.open();
-  }
-
-  async onSave() {
-    this.isSaving.set(true);
-    try {
-      if (this.selectedItem) {
-        await this.service.update(this.selectedItem.id, this.formData);
-      } else {
-        await this.service.create(this.formData);
-      }
-      this.formModal.close();
-      this.sdTable?.reload?.();
-    } finally {
-      this.isSaving.set(false);
-    }
-  }
-
-  async onDelete(item: Product) {
-    if (!confirm(`Xoá "${item.name}"?`)) return;
-    await this.service.delete(item.id);
-    this.sdTable?.reload?.();
-  }
+export class CustomerFormComponent {
+  readonly customerForm = new FormGroup({});
+  readonly customer = { name: '' };
 }
 ```
 
-### Template
-
-```html
-<!-- product-list.component.html -->
-<div class="d-flex justify-content-between align-items-center mb-16">
-  <h2>Danh sách sản phẩm</h2>
-  <sd-button type="fill" color="primary" title="Thêm mới" prefixIcon="add" (click)="openForm()" />
-</div>
-
-<sd-table #sdTable [option]="option" />
-
-<sd-modal #formModal [title]="selectedItem ? 'Chỉnh sửa' : 'Thêm mới'" width="md">
-  <ng-template>
-    <div class="modal-body p-16">
-      <sd-section title="Thông tin sản phẩm" icon="inventory">
-        <div class="row">
-          <div class="col-6">
-            <sd-input [(model)]="formData.code" label="Mã" [required]="true" />
-          </div>
-          <div class="col-6">
-            <sd-select [(model)]="formData.status" label="Trạng thái" [items]="STATUS_LIST" valueField="value" displayField="label" />
-          </div>
-          <div class="col-12">
-            <sd-input [(model)]="formData.name" label="Tên sản phẩm" [required]="true" />
-          </div>
-          <div class="col-6">
-            <sd-input-number [(model)]="formData.price" label="Đơn giá" suffix="VNĐ" />
-          </div>
-        </div>
-      </sd-section>
-    </div>
-    <div class="modal-footer d-flex justify-content-end gap-8 p-16">
-      <sd-button title="Huỷ" (click)="formModal.close()" />
-      <sd-button type="fill" color="primary" title="Lưu" prefixIcon="save" [loading]="isSaving()" (click)="onSave()" />
-    </div>
-  </ng-template>
-</sd-modal>
-```
+## Theming
 
----
-
-## Contributing Guide / Hướng dẫn đóng góp
-
-### Cấu trúc thư viện / Project structure
-
-```
-sdcorejs-angular/
-├── src/
-│   └── public-api.ts           # Entry point chính
-├── assets/
-│   └── scss/
-│       ├── sd-core.scss        # SCSS entry (import vào app)
-│       ├── core/               # Base utilities (color, grid, form, ...)
-│       └── themes/             # Theme mặc định + Material theme
-├── components/                 # UI Components
-│   ├── button/
-│   ├── table/
-│   ├── modal/
-│   └── ...
-├── forms/                      # Form components
-│   ├── input/
-│   ├── select/
-│   └── ...
-├── directives/                 # Angular directives
-├── pipes/                      # Angular pipes
-├── services/                   # Shared services
-├── utilities/                  # Types, models, helpers
-└── modules/                    # Feature modules (layout, permission, ...)
-```
-
-### Thêm component mới / Adding a new component
-
-**1. Tạo thư mục component:**
-
-```
-components/
-└── my-component/
-    ├── index.ts                         # Export public API
-    ├── ng-package.json                  # ng-packagr entry
-    └── src/
-        ├── my-component.component.ts
-        ├── my-component.component.html
-        └── my-component.component.scss
-```
+`sd-core.scss` loads the reset, utilities, bundled fonts, semantic colors, form styles, and Angular Material theme baseline. Override public semantic colors with `sd.theme()`:
 
-**2. `ng-package.json`:**
+```scss
+@use '@sdcorejs/angular/assets/scss/sd-core';
+@use '@sdcorejs/angular/assets/scss/themes/default' as sd;
 
-```json
-{
-  "$schema": "../../../../node_modules/ng-packagr/ng-package.schema.json",
-  "lib": {
-    "entryFile": "index.ts"
-  }
+html {
+  @include sd.theme(
+    (
+      primary: #2563eb,
+      primary-light: #dbeafe,
+      primary-dark: #1d4ed8,
+    )
+  );
 }
 ```
 
-**3. `index.ts`:**
-
-```typescript
-export * from './src/my-component.component';
-```
+See the [assets and SCSS reference](https://sdcorejs.github.io/sdcorejs-angular/docs/latest/assets/STYLE-GUIDE.md) for supported `--sd-*` tokens, Material M3 guidance, utilities, fonts, and image assets.
 
-**4. Component template:**
+## Internationalization
 
-```typescript
-// my-component.component.ts
-import { ChangeDetectionStrategy, Component, input } from '@angular/core';
-import { SdBaseSecureComponent } from '@sdcorejs/angular/components/base';
-import { Color } from '@sdcorejs/angular/utilities';
+Set the default Core UI language through `SD_CORE_CONFIGURATION`:
 
-@Component({
-  selector: 'sd-my-component',
-  templateUrl: './my-component.component.html',
-  styleUrl: './my-component.component.scss',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  standalone: true,
-  imports: [],
-})
-export class SdMyComponent extends SdBaseSecureComponent {
-  color = input<Color, Color | undefined | null>('primary', {
-    transform: value => value || 'primary',
-  });
-
-  title = input<string | undefined | null>(undefined);
-}
-```
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { type ISdCoreConfiguration, SD_CORE_CONFIGURATION } from '@sdcorejs/angular/configurations';
 
-**5. Export từ `components/index.ts`:**
+const sdCoreConfig = {
+  language: 'en',
+} satisfies ISdCoreConfiguration;
 
-```typescript
-// components/index.ts
-export * from '@sdcorejs/angular/components/my-component';
+export const appConfig: ApplicationConfig = {
+  providers: [{ provide: SD_CORE_CONFIGURATION, useValue: sdCoreConfig }],
+};
 ```
 
-### Quy ước / Conventions
+`I18nService.setLanguage()` persists a built-in language and reloads by default. A complete custom catalog can be supplied through the synchronous `language: () => catalog` hook. See the [i18n reference](https://sdcorejs.github.io/sdcorejs-angular/docs/latest/i18n/i18n.md) for catalog typing and fallback behavior.
 
-| Mục              | Quy ước                                                       |
-| ---------------- | ------------------------------------------------------------- |
-| Selector         | `sd-<tên-component>`                                          |
-| Class name       | `Sd<TênComponent>` (Pascal)                                   |
-| Input            | Dùng `input<T>()` signal, **không** dùng `@Input()` decorator |
-| Null safety      | Input transform phải handle `null/undefined`                  |
-| Base class       | Extend `SdBaseSecureComponent` cho component có permission    |
-| Change detection | Luôn dùng `ChangeDetectionStrategy.OnPush`                    |
-| Standalone       | Luôn `standalone: true`                                       |
-| Colors           | Dùng `Color` type, không hardcode màu                         |
+## Documentation and examples
 
-### Build
+| Resource                                                                                                                                                                             | Purpose                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| [Live showcase](https://sdcorejs.github.io/sdcorejs-angular/)                                                                                                                        | Interactive component, form, and service demos                             |
+| [Button example source](https://github.com/sdcorejs/sdcorejs-angular/blob/main/versions/v19/projects/showcase/src/app/pages/components/button/button-demo.component.ts)              | Action variants, icons, disabled state, and loading state                  |
+| [Input example source](https://github.com/sdcorejs/sdcorejs-angular/blob/main/versions/v19/projects/showcase/src/app/pages/forms/input/input-demo.component.ts)                      | Model binding, validation, and viewed states                               |
+| [Table example source](https://github.com/sdcorejs/sdcorejs-angular/blob/main/versions/v19/projects/showcase/src/app/pages/components/table/table-demo.component.ts)                 | Data, selection, filters, grouping, paging, and tree workflows             |
+| [Persistence example source](https://github.com/sdcorejs/sdcorejs-angular/blob/main/versions/v19/projects/showcase/src/app/pages/services/persistence/persistence-demo.component.ts) | Graph round-trip, identity, envelopes, and error containment               |
+| [Latest API manifest](https://sdcorejs.github.io/sdcorejs-angular/docs/latest/index.json)                                                                                            | Discover all Markdown docs for the latest release                          |
+| [Versions registry](https://sdcorejs.github.io/sdcorejs-angular/docs/versions.json)                                                                                                  | Select docs matching an installed package version                          |
+| [Machine-readable catalog](https://sdcorejs.github.io/sdcorejs-angular/docs/catalog.json)                                                                                            | Discover documentation across maintained package lines                     |
+| [E2E attributes](https://github.com/sdcorejs/sdcorejs-angular/blob/main/versions/v19/projects/sdcorejs-angular/docs/E2E-ATTRIBUTES.md)                                               | Stable runtime selectors and state attributes                              |
+| [1.4 migration guide](https://github.com/sdcorejs/sdcorejs-angular/blob/main/docs/migrations/1.4.md)                                                                                 | Dedupe, loading, persistence, connector, responsive, and signal migrations |
 
-```bash
-# Build toàn bộ thư viện
-ng-packagr -p ng-package.json
+## Versioning
 
-# Watch mode
-ng-packagr -p ng-package.json --watch
-```
+- Use `@sdcorejs/angular@^19`, `@^20`, or `@^21` to match the application's Angular major.
+- Maintained package lines are released from the same feature surface with required Angular-major adaptations.
+- Consumer-breaking changes and migration notes are recorded in the [changelog](https://github.com/sdcorejs/sdcorejs-angular/blob/main/CHANGELOG.md).
+- Before adopting the `1.4` suffix, follow the [1.4 migration guide](https://github.com/sdcorejs/sdcorejs-angular/blob/main/docs/migrations/1.4.md).
+- Version-pinned reference docs remain available under `https://sdcorejs.github.io/sdcorejs-angular/docs/<package-version>/`.
 
-### Versioning
+## Contributing
 
-Scheme: `<angular-major>.0.<release>`. Major digit **khoá theo Angular line** (19.x = Angular 19, 20.x = Angular 20, 21.x = Angular 21) — **KHÔNG** dùng để báo breaking. Mỗi release publish đồng thời 3 major cùng nội dung feature, chỉ khác Angular shim.
+Contributions are welcome through focused pull requests. See the [repository contribution workflow](https://github.com/sdcorejs/sdcorejs-angular#contributing) for setup, validation, and source-workspace guidance.
 
-- Luôn pin theo Angular line của bạn: `npm i @sdcorejs/angular@^19` (hoặc `@^20` / `@^21`).
-- Breaking change được ghi rõ ở `CHANGELOG.md`, mục **Changed (BREAKING for consumers)**, kèm migration.
+## Support
 
----
+Use [GitHub Issues](https://github.com/sdcorejs/sdcorejs-angular/issues) for reproducible bugs and focused feature proposals. Include the Angular major, package version, a minimal reproduction, and the expected behavior.
 
-## QA / E2E
+## Maintainer
 
-Core UI components expose runtime state via lowercase `data-*` attributes for e2e selectors. The full catalog, component matrix, selector cookbook, and YAML schema for AI agents live in `docs/E2E-ATTRIBUTES.md` in the source repository.
+**Trần Thuận Nghĩa** — Full Stack Developer and maintainer of `@sdcorejs/angular`. He builds practical, strongly typed web applications and reusable tools that make complex business workflows easier to deliver and maintain.
 
----
+[SDCoreJS on GitHub](https://github.com/sdcorejs) · [LinkedIn](https://www.linkedin.com/in/tran-thuan-nghia/) · [Email](mailto:tran.thuan.nghia@gmail.com)
 
 ## License
 
-MIT - see the LICENSE file.
+MIT © Trần Thuận Nghĩa. See the [repository license](https://github.com/sdcorejs/sdcorejs-angular/blob/main/LICENSE).