ejsc-mna-component 🎨

The Core UI Component Library & Design System for 365 Mini App Applications.

ejsc-mna-component là thư viện linh kiện giao diện (UI Components) chuẩn hóa cho các ứng dụng 365 Mini App. Được xây dựng dựa trên nguyên lý thiết kế Atomic Design, tối ưu hóa cho màn hình di động (Mobile First), hỗ trợ responsive hoàn hảo, tích hợp sẵn Tailwind CSS v4 cùng hệ thống animation mượt mà từ Framer Motion.

📑 Mục Lục

• 1. Tính Năng Nổi Bật
• 2. Cài Đặt & Tích Hợp Styles
• 3. Danh Sách Component Chi Tiết
  • 3.1 Base & Typography
  • 3.2 Điều Hướng Navigation
  • 3.3 Layout & Structure
  • 3.4 Nhập Liệu Data Entry
  • 3.5 Feedback & Overlays (Sheet, Toast)
• 4. Danh Sách Custom Hooks
• 5. Giấy Phép & Bản Quyền

1. Tính Năng Nổi Bật

• 🎨 Tailwind CSS v4 Native: Thiết kế dựa trên Design Tokens chuẩn hóa, dễ dàng tùy biến theme.
• 📱 Mobile UX First: Tích hợp các thao tác di động tự nhiên như Pull-to-Refresh, Swipe-to-Dismiss, Keyboard-Avoid.
• 🚀 Performant Animations: Tối ưu chuyển động mượt mà 60fps nhờ Framer Motion.
• ♿ Accessible Components: Chuẩn hóa ARIA attributes và hỗ trợ i18n đa ngôn ngữ.
• 🛠️ Full TypeScript Typing: Hỗ trợ Auto-complete thuộc tính và kiểm tra lỗi kiểu dữ liệu nghiêm ngặt.

2. Cài Đặt & Tích Hợp Styles

Cài đặt thư viện:

# Cài đặt qua pnpm (khuyên dùng)
pnpm add [email protected]

# Hoặc cài đặt qua npm
npm install [email protected]

Tích hợp file CSS vào dự án:

Nhập file CSS styles vào file entry point của dự án (ví dụ src/main.tsx hoặc src/index.css):

import 'ejsc-mna-component/dist/styles.css';

3. Danh Sách Component Chi Tiết

3.1 Base & Typography

Text

Thành phần hiển thị văn bản chuẩn hệ thống.

import { Text } from 'ejsc-mna-component';

<Text variant="h1" weight="bold" color="brand">Tiêu Đề Chính</Text>
<Text variant="sub" color="sub">Mô tả phụ cho nội dung</Text>

| Thuộc tính (Prop) | Kiểu Dữ Liệu | Mặc Định | Mô Tả | | :--- | :--- | :--- | :--- | | variant | h1 | h2 | h3 | base | sub | caption | tiny | base | Định dạng kích thước chữ | | color | main | sub | brand | white | danger | success | main | Màu sắc văn bản | | weight | normal | medium | semibold | bold | normal | Độ đậm của chữ | | align | left | center | right | left | Căn lề văn bản |

Button

Nút bấm tương tác hỗ trợ trạng thái loading, icon và giao diện block.

import { Button } from 'ejsc-mna-component';

<Button theme="brand" size="md" block onClick={handleClick}>Bắt Đầu Ngay</Button>
<Button theme="ghost" loading={isLoading}>Tùy Chọn</Button>

| Thuộc tính | Kiểu Dữ Liệu | Mặc Định | Mô Tả | | :--- | :--- | :--- | :--- | | theme | brand | neutral | danger | ghost | warning | brand | Màu sắc chủ đạo của nút | | size | sm | md | lg | md | Kích thước nút | | loading | boolean | false | Hiển thị hiệu ứng chờ loading | | block | boolean | false | Chiều rộng 100% container |

3.2 Điều Hướng Navigation

AppBar

Thanh tiêu đề cố định phía trên trang.

import { AppBar } from 'ejsc-mna-component';

<AppBar title="Thông Tin Tài Khoản" onBack={() => navigate(-1)} />

Tabs

Bộ chuyển đổi tab nội dung linh hoạt.

import { Tabs } from 'ejsc-mna-component';

<Tabs 
  activeKey={active} 
  onChange={setActive}
  items={[
    { key: 'all', label: 'Tất Cả' },
    { key: 'pending', label: 'Đang Xử Lý' }
  ]} 
/>

3.3 Layout & Structure

StandardPage

Layout khung trang chuẩn tích hợp sẵn AppBar và tính năng kéo để làm mới (Pull-to-refresh).

import { StandardPage } from 'ejsc-mna-component';

<StandardPage 
  title="Trang Chủ" 
  onRefresh={handleRefreshData}
>
  <div className="p-4">Nội dung trang</div>
</StandardPage>

KeyboardAvoidWrapper

Tự động đẩy giao diện lên khi bàn phím ảo di động xuất hiện, tránh che lấp ô nhập liệu.

import { KeyboardAvoidWrapper } from 'ejsc-mna-component';

<KeyboardAvoidWrapper offset={20}>
  <Input label="Số điện thoại" />
</KeyboardAvoidWrapper>

3.4 Nhập Liệu Data Entry

Input

Ô nhập liệu văn bản hỗ trợ icon prefix/suffix và thông báo lỗi.

import { Input } from 'ejsc-mna-component';

<Input 
  label="Số Điện Thoại" 
  placeholder="09xxx..." 
  error={errors.phone}
  prefix={<PhoneIcon />}
/>

DatePickerWheel & WheelPicker

Bộ chọn dữ liệu dạng bánh xe cuộn tương tác phong cách Native di động.

import { DatePickerWheel } from 'ejsc-mna-component';

<DatePickerWheel 
  value={selectedDate} 
  onSelect={(v) => setSelectedDate(v)} 
  title="Chọn Ngày Sinh"
/>

3.5 Feedback & Overlays (Sheet, Toast)

Sheet (Bottom Sheet Modal)

Màn hình trượt từ dưới lên cho menu tùy chọn hoặc thông tin bổ sung.

import { Sheet, SheetHeader, SheetBody } from 'ejsc-mna-component';

<Sheet open={isOpen} onClose={() => setOpen(false)} layout="inset">
  <SheetHeader title="Tùy Chọn Thao Tác" onClose={() => setOpen(false)} />
  <SheetBody>
    <div>Nội dung Bottom Sheet</div>
  </SheetBody>
</Sheet>

toast

Thông báo nhanh gọi trực tiếp từ hàm logic:

import { toast } from 'ejsc-mna-component';

// Gọi trực tiếp trong hàm xử lý
toast.success('Lưu thông tin thành công!');
toast.error('Có lỗi xảy ra, vui lòng thử lại.');

4. Danh Sách Custom Hooks

| Custom Hook | Giá Trị Trả Về | Mô Tả | | :--- | :--- | :--- | | usePullToRefresh | { pullDistance, isRefreshing, progress } | Quản lý trạng thái và khoảng cách kéo làm mới trang | | useKeyboard | { isOpen, keyboardHeight } | Theo dõi trạng thái ẩn/hiện và chiều cao của bàn phím di động | | useLoadMore | { loading, hasMore, loadMore } | Quản lý logic tự động phân trang khi cuộn xuống cuối danh sách |

5. Giấy Phép & Bản Quyền

© 2026 365EJSC Teams. Distributed under the MIT License.