tan-ui-kit

v1.0.2

Published

13 days ago

Đây là bộ thư viện UI Components (Web Components) được phát triển bằng Angular Elements. SDK cung cấp các thẻ HTML tuỳ chỉnh (Custom Elements) có thể hoạt động hoàn toàn độc lập trên **bất kỳ framework Frontend nào** (React, Vue, Angular, Svelte) hoặc thậ

Downloads

383

0High
0Medium
0Low

neo_tee

TAN UI KIT

Đây là bộ thư viện UI Components (Web Components) được phát triển bằng Angular Elements. SDK cung cấp các thẻ HTML tuỳ chỉnh (Custom Elements) có thể hoạt động hoàn toàn độc lập trên bất kỳ framework Frontend nào (React, Vue, Angular, Svelte) hoặc thậm chí là HTML tĩnh (Vanilla JS).

Đặc biệt, SDK đã được đóng gói và nhúng sẵn Tailwind CSS, cho phép người dùng bên ngoài có thể tự do tuỳ biến style một cách linh hoạt nhất.

📦 Cài đặt

Cài đặt thông qua NPM, Yarn hoặc pnpm:

npm install tan-ui-kit
# hoặc
pnpm install tan-ui-kit
# hoặc
yarn add tan-ui-kit

🚀 Hướng dẫn tích hợp

1. Dành cho dự án React (Vite / Next.js / CRA)

Ở file chạy gốc của dự án (ví dụ src/main.jsx hoặc src/index.js), hãy gọi import một lần duy nhất:

// src/main.jsx
import 'tan-ui-kit'; 
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')).render(<App />);

Cách sử dụng trong Component React (Đặc biệt lưu ý cách bắt sự kiện bằng useRef đối với React 18 trở xuống):

import React, { useEffect, useRef } from 'react';

export default function App() {
  const btnRef = useRef(null);

  useEffect(() => {
    const btn = btnRef.current;
    
    // Bắt CustomEvent 'onClick' từ SDK phát ra
    const handleSdkClick = (e) => {
      alert('Đã click nút TAN Button!');
    };

    if (btn) btn.addEventListener('onClick', handleSdkClick);
    return () => {
      if (btn) btn.removeEventListener('onClick', handleSdkClick);
    }
  }, []);

  return (
    <div style={{ padding: '24px' }}>
      {/* Các Component hiển thị cơ bản */}
      <tan-header title="Hệ thống TAN"></tan-header>
      
      <tan-card title="Thông tin thẻ" content="Gói cước của bạn đang hoạt động bình thường.">
        {/* Tuỳ biến style bằng custom-class (hỗ trợ Tailwind CSS) */}
        <tan-button 
          ref={btnRef} 
          color="primary" 
          label="Gia hạn ngay"
          custom-class="w-full text-lg shadow-md mt-4">
        </tan-button>
      </tan-card>
    </div>
  );
}

2. Dành cho dự án Vue 3

Việc sử dụng Web Component trên Vue cực kỳ mượt mà vì Vue hỗ trợ Native Custom Events.

Ở file main.js của Vue, bạn cũng import SDK:

import { createApp } from 'vue'
import App from './App.vue'
import 'tan-ui-kit'; // Khởi tạo SDK

createApp(App).mount('#app')

Ở file .vue, bạn không cần dùng ref để bắt sự kiện như React, cứ viết @on-click thẳng vào template:

<template>
  <div class="p-6">
    <tan-header title="Vue + TAN SDK"></tan-header>
    
    <tan-card title="Bảng điều khiển">
      <!-- Bắt sự kiện bằng @onClick -->
      <tan-button 
        color="secondary" 
        label="Huỷ thao tác"
        @onClick="handleCancel">
      </tan-button>
    </tan-card>
  </div>
</template>

<script setup>
const handleCancel = (event) => {
  console.log('Vue nhận được sự kiện từ nút:', event);
  alert('Đã huỷ thao tác!');
}
</script>

3. Dành cho dự án Angular (Dự án khác)

Khi dùng Web Component trong một dự án Angular khác, bạn cần import SDK và cấu hình CUSTOM_ELEMENTS_SCHEMA để Angular không báo lỗi thẻ HTML lạ.

Bước 1: Import SDK ở file main.ts (hoặc app.component.ts):

import 'tan-ui-kit';

Bước 2: Thêm CUSTOM_ELEMENTS_SCHEMA vào Component (nếu dùng Standalone) hoặc app.module.ts:

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Bắt buộc phải có dòng này
  template: `
    <tan-header title="Angular App"></tan-header>
    
    <!-- Truyền props và bắt sự kiện y hệt component nội bộ -->
    <tan-button 
      color="primary" 
      label="Xác nhận"
      (onClick)="handleAction($event)">
    </tan-button>
  `
})
export class AppComponent {
  handleAction(event: Event) {
    console.log('Angular nhận event:', event);
  }
}

4. Dành cho HTML Tĩnh (Vanilla JS)

Nếu bạn không dùng Node.js hay Framework nào, chỉ có 1 file .html trống, hãy gọi thẳng SDK từ kho CDN (Unpkg/JSDelivr).

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Demo HTML thuần</title>
  
  <!-- Nhúng SDK thông qua CDN -->
  <script src="https://unpkg.com/tan-ui-kit@latest" type="module"></script>
</head>
<body style="background: #f1f5f9; padding: 20px; font-family: sans-serif;">

  <tan-header title="HTML Tĩnh"></tan-header>

  <tan-card title="Card tĩnh">
    <tan-button id="myBtn" color="primary" label="Bấm vào tôi"></tan-button>
  </tan-card>

  <script>
    // Bắt sự kiện bằng Javascript thuần
    document.addEventListener('DOMContentLoaded', () => {
      const btn = document.getElementById('myBtn');
      btn.addEventListener('onClick', () => {
        alert('Hello từ Vanilla JS!');
      });
    });
  </script>
</body>
</html>

📚 API Reference (Danh sách Component)

1. `<tan-header>`

2. `<tan-card>`

3. `<tan-button>`

4. `<tan-input>`

5. `<tan-checkbox>`

6. `<tan-switch>`

7. `<tan-tag>`

8. `<tan-alert>`

9. `<tan-select>`

| Thuộc tính (Prop) | Kiểu dữ liệu | Mặc định | Mô tả | | :--- | :--- | :--- | :--- | | placeholder | string | "Select..." | Gợi ý mặc định | | options | string (JSON Array) | "[]" | Mảng các tuỳ chọn dạng chuỗi JSON [{"label":"","value":""}] |

10. `<tan-table>`

| Thuộc tính (Prop) | Kiểu dữ liệu | Mặc định | Mô tả | | :--- | :--- | :--- | :--- | | columns | string (JSON Array) | "[]" | Cấu hình cột dạng JSON [{"title":"","key":""}] | | data-source | string (JSON Array) | "[]" | Dữ liệu các hàng dạng JSON (các key phải map với cột) |

11. `<tan-drawer>`

12. `<tan-tree>`

| Thuộc tính (Prop) | Kiểu dữ liệu | Mặc định | Mô tả | | :--- | :--- | :--- | :--- | | data | string (JSON Array) | "[]" | Dữ liệu dạng mảng JSON đa cấp (có thuộc tính children) |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

TAN UI KIT

📦 Cài đặt

🚀 Hướng dẫn tích hợp

1. Dành cho dự án React (Vite / Next.js / CRA)

2. Dành cho dự án Vue 3

3. Dành cho dự án Angular (Dự án khác)

4. Dành cho HTML Tĩnh (Vanilla JS)

📚 API Reference (Danh sách Component)

1. <tan-header>

2. <tan-card>

3. <tan-button>

4. <tan-input>

5. <tan-checkbox>

6. <tan-switch>

7. <tan-tag>

8. <tan-alert>

9. <tan-select>

10. <tan-table>

11. <tan-drawer>

12. <tan-tree>