fint-angular-ui-components

v0.2.1

Published

23 days ago

Angular UI Components Library with Storybook

0High
0Medium
0Low

vaquan2001

angular ui components library storybook charts

FINT Angular UI Components

Thư viện UI Components xây dựng bằng Angular 20, Storybook 9 và ng-zorro-antd. Bao gồm các components như Alert, Button, Input, Charts (Column, Line, Pie, Stack) và nhiều hơn nữa.

📦 Cài đặt

npm install fint-angular-ui-components

Hoặc với yarn:

yarn add fint-angular-ui-components

Dependencies bắt buộc

Package này yêu cầu các peer dependencies sau:

npm install @angular/common@^20.0.0 @angular/core@^20.0.0 ng-zorro-antd@^20.4.0 apexcharts@^5.3.0 ng-apexcharts@^2.0.0 ng-recaptcha@^13.2.0

🚀 Cách sử dụng

Import Components trong Angular

Package này sử dụng Standalone Components của Angular. Bạn có thể import trực tiếp vào component hoặc module của mình.

Cách 1: Import trực tiếp trong Standalone Component

import { Component } from '@angular/core';
import { AlertComponent } from 'fint-angular-ui-components';
import { ButtonComponent } from 'fint-angular-ui-components';
import { InputComponent } from 'fint-angular-ui-components';

@Component({
  selector: 'app-my-component',
  standalone: true,
  imports: [AlertComponent, ButtonComponent, InputComponent],
  template: `
    <lib-alert type="success" message="Thành công!" />
    <lib-button type="primary" size="large">Click me</lib-button>
    <lib-input placeholder="Nhập text..." />
  `
})
export class MyComponent {}

Cách 2: Import trong NgModule (Traditional)

import { NgModule } from '@angular/core';
import { AlertComponent, ButtonComponent, InputComponent } from 'fint-angular-ui-components';

@NgModule({
  imports: [
    AlertComponent,
    ButtonComponent,
    InputComponent
  ],
  // ... rest of module config
})
export class AppModule {}

Cách 3: Import nhiều components cùng lúc

import {
  AlertComponent,
  BreadcrumbComponent,
  ButtonComponent,
  CheckboxComponent,
  IconComponent,
  InputComponent,
  RadioComponent,
  SelectComponent,
  SpinComponent,
  TextComponent,
  TextAreaComponent,
  UploadComponent,
  // Charts
  ColumnChartComponent,
  LineChartComponent,
  PieChartComponent,
  StackChartComponent
} from 'fint-angular-ui-components';

📚 Danh sách Components

UI Components

AlertComponent (<lib-alert>) - Hiển thị thông báo
BreadcrumbComponent (<lib-breadcrumb>) - Điều hướng breadcrumb
ButtonComponent (<lib-button>) - Nút bấm
CaptchaComponent (<lib-captcha>) - ReCAPTCHA
CheckboxComponent (<lib-checkbox>) - Checkbox
IconComponent (<lib-icon>) - Icon
InputComponent (<lib-input>) - Input text
RadioComponent (<lib-radio>) - Radio button
SelectComponent (<lib-select>) - Dropdown select
SpinComponent (<lib-spin>) - Loading spinner
TextComponent (<lib-text>) - Text display
TextAreaComponent (<lib-text-area>) - Textarea
UploadComponent (<lib-upload>) - Upload file

Chart Components (ApexCharts)

ColumnChartComponent (<lib-column-chart>) - Biểu đồ cột
LineChartComponent (<lib-line-chart>) - Biểu đồ đường
PieChartComponent (<lib-pie-chart>) - Biểu đồ tròn
StackChartComponent (<lib-stack-chart>) - Biểu đồ cột xếp chồng

💡 Ví dụ sử dụng

Alert Component

<lib-alert 
  type="success" 
  message="Thao tác thành công!"
  [closeable]="true"
/>

Button Component

<lib-button 
  type="primary" 
  size="large"
  (click)="handleClick()"
>
  Submit
</lib-button>

Column Chart

<lib-column-chart
  [series]="[{ name: 'Sales', data: [30, 40, 35, 50, 49] }]"
  [categories]="['Jan', 'Feb', 'Mar', 'Apr', 'May']"
  title="Monthly Sales"
  height="350"
/>

🛠️ Development

Nếu bạn muốn đóng góp hoặc chạy project locally:

Bắt đầu nhanh

Yêu cầu: Node >=20 LTS, npm hoặc yarn
Cài đặt: npm install hoặc yarn install
Chạy app Angular: npm start → http://localhost:4200
Chạy Storybook: npm run storybook → http://localhost:6006
Build library: npm run build:lib
Publish: npm publish --access public

🔧 Alias TypeScript (For Development)

Khi develop trong project này, alias được cấu hình trong tsconfig.json:

| Alias | Thư mục đích | Công dụng | | --- | --- | --- | | @ui/* | src/lib/ui/* | Thư viện UI tái sử dụng dưới dạng standalone component | | @components/* | src/lib/components/* | Thành phần nội bộ khác (nếu có) |

Ví dụ import trong Storybook:

import { InputComponent } from '@ui/input';

🛠️ Script tạo UI Component cùng Storybook

Script yarn generate:sb <ComponentName> (hoặc npm run generate:sb) giúp tạo nhanh component standalone và story tương ứng.

Mặc định script tạo:

src/lib/ui/<component>/<component>.component.{ts,html,css,spec.ts}
src/lib/ui/<component>/index.ts
src/helper/<component>.stories.helpers.ts
src/stories/ui/<component>.stories.ts

Story được phát sinh sẽ import component qua alias @ui/.... Các flag hữu ích:

--title=Section/Name đặt tiêu đề Storybook.
--prefix=app đổi selector Angular (mặc định app).
--here tạo file ngay tại thư mục hiện tại thay vì src/lib/ui.
--force ghi đè file đã tồn tại.

Sau khi chạy script:

Điều chỉnh template, logic, CSS trong component.
Cập nhật helper test trong src/helper nếu story cần play function.
Chạy yarn storybook để kiểm tra giao diện.

Script tạo Example màn hình

Sử dụng yarn example:sb <ExampleName> để tạo component ví dụ (demo flow hoàn chỉnh) tại src/examples cùng story trong src/stories/examples.

Selector mặc định: example-<kebab-case>.
Story được đặt dưới nhánh Examples/<ExampleName>.
Có thể truyền --force hoặc --here tương tự script component.

Cấu trúc mã nguồn chính

src/lib/ui/ – Thư viện UI chính, mỗi component là standalone, có barrel index.ts phục vụ alias.
src/stories/ui/ – Storybook story cho UI component. Ưu tiên import qua @ui/....
src/examples/ – Component ví dụ minh họa luồng nghiệp vụ.
src/stories/examples/ – Storybook story cho nhóm example.
src/helper/ – Play function và helper dùng trong Storybook interaction test.
scripts/ – Script Node phục vụ tạo scaffolding (new-component.mjs, new-example.mjs).

Giữ cấu trúc trên giúp đồng bộ alias và tránh lỗi import.

Quy tắc khi phát triển component

Component nên ở dạng standalone (standalone: true) và tự khai báo styleUrls/templateUrl cục bộ.
Cập nhật barrel index.ts để Storybook và các dự án khác import qua alias.
Viết unit test cơ bản (*.spec.ts) ít nhất kiểm tra khởi tạo và hành vi chính.
Tạo story với tags: ['autodocs'] để tận dụng tài liệu tự động.
Nếu story cần tương tác, tạo helper tương ứng trong src/helper để tái sử dụng.

Tài liệu nên đọc

Angular Standalone Components: https://angular.dev/guide/standalone-components
Storybook cho Angular: https://storybook.js.org/docs/angular
Ng Zorro Ant Design: https://ng.ant.design/docs/introduce/en
Angular CLI & Workspace: https://angular.dev/tools/cli
Testing với Angular & Jasmine: https://angular.dev/guide/testing

Đọc qua các tài liệu trên trước khi bắt đầu giúp thống nhất phong cách code và tận dụng tối đa workflow hiện có.