webapp.ui.lib

v1.0.6

Published

5 days ago

Thư viện component UI cho React 19 + Tailwind CSS 4, hỗ trợ Microsoft Fluent 2 preset và hơn 70+ controls.

0High
0Medium
0Low

webapp.ui.lib

Bộ thư viện component UI toàn diện, hiệu năng cao và chuẩn hoá dành cho React 19 và Tailwind CSS 4, kết hợp nền tảng Radix UI, hỗ trợ sẵn preset thiết kế Microsoft Fluent 2.

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

🚀 Hơn 70+ Components & Controls: Bao phủ đầy đủ từ Forms, Data Table ảo hoá, Masonry thác nước, Cây thư mục, Biểu đồ, đến các Trình xem đa phương tiện nâng cao (Office Word .docx/.doc 97-2003, Excel, PowerPoint .pptx, PDF, Zip, Media, HTML sandbox an toàn, Zoom ảnh) và một số tiện ích khác.
🎨 Đa dạng phong cách & Themes:
- Hỗ trợ Dark Mode chuẩn xác theo class .dark hoặc hook useTheme().
- Tích hợp sẵn preset Microsoft Fluent 2 với bo góc mềm mại, đổ bóng Fluent Elevation và màu sắc chuẩn mực.
- Tùy biến Design Tokens linh hoạt qua CSS layer (wwui-tokens) không lo xung đột.
⚡ Tối ưu dung lượng & Tree-shaking:
- Xuất bản chuẩn ESM phân tách chunk chi tiết và bản UMD đơn lẻ.
- Tự động nạp lười (Lazy Loading) các thư viện nặng (SheetJS xlsx, PDF.js, Fabric.js) chỉ khi người dùng mở định dạng tài liệu tương ứng.
🛡️ TypeScript First: Khai báo .d.ts đầy đủ, chuẩn xác, tự động gợi ý props và kiểu dữ liệu.

1. Cài Đặt

Cài đặt từ NPM Registry:

npm install webapp.ui.lib
# hoặc
pnpm add webapp.ui.lib
# hoặc
yarn add webapp.ui.lib

Hoặc cài từ file `.tgz` (phân phối nội bộ/offline):

npm install ./vendor/webapp.ui.lib-1.0.0.tgz

Yêu cầu môi trường: react và react-dom phiên bản ^19.0.0. Các thư viện phụ thuộc cho types và logic hiển thị (radix-ui, @tanstack/react-table, recharts...) sẽ được npm tự động cài đặt theo dependencies.

2. Bắt Đầu Nhanh (Quick Start)

2.1. Nạp CSS và bọc Provider

Ở file khởi chạy ứng dụng (ví dụ main.tsx hoặc App.tsx), nạp stylesheet và bọc component bằng AppProviders:

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { AppProviders } from "webapp.ui.lib";

// Bắt buộc: Nạp CSS đã biên dịch của thư viện
import "webapp.ui.lib/styles.css";

import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <AppProviders defaultStyleVariant="fluent">
      <App />
    </AppProviders>
  </StrictMode>
);

AppProviders đã tích hợp sẵn:

QueryClientProvider (React Query)
TooltipProvider (Tooltip)
ThemeProvider (Theme & Fluent 2 Style)
GlobalConfirmAlertProvider (Hộp thoại xác nhận toàn cục qua useGlobalConfirmAlert())
Toaster (khung hiển thị cho toast từ webapp.ui.lib/ui/use-toast; không phải sonner)

3. Cách Thức Import

Thư viện hỗ trợ 2 hình thức import linh hoạt:

A. Barrel Import (Thuận tiện & Gọn gàng)

Bundler (Vite, Next.js, Rollup) tự động tree-shake nhờ kiến trúc ESM tách file:

import { Button, Input, DataTable, Masonry } from "webapp.ui.lib";

B. Subpath Import (Kiểm soát tuyệt đối kích thước bundle)

import { Button } from "webapp.ui.lib/ui/button";
import { DataTable } from "webapp.ui.lib/ui/data-table/data-table";
import { Masonry } from "webapp.ui.lib/ui/masonry";
import { DocumentViewerControl } from "webapp.ui.lib/ui/document-viewer/index"; // thư mục → thêm /index
import { useDebounce } from "webapp.ui.lib/hooks/use-debounce";
import { cn } from "webapp.ui.lib/lib/utils";

4. Danh Mục Controls & Bảng Tra Cứu

Chi tiết hướng dẫn đầy đủ kèm ví dụ mã nguồn từng control có thể xem tại CONTROLS.md.

5. Tùy Biến Giao Diện & Themes

5.1. Chuyển đổi Theme Sáng / Tối

Sử dụng hook useTheme:

import { useTheme } from "webapp.ui.lib";

function ThemeToggle() {
  const { theme, setTheme } = useTheme();
  return (
    <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
      Chế độ: {theme}
    </button>
  );
}

5.2. Microsoft Fluent 2 Style Preset

Kích hoạt phong cách Microsoft Fluent 2:

Cách 1: Qua ThemeProvider / AppProviders:

<AppProviders defaultStyleVariant="fluent">
  <App />
</AppProviders>

Cách 2: Gán thuộc tính hoặc class HTML:

<html data-theme-style="fluent">
<!-- hoặc <body class="theme-fluent"> -->

Cách 3: Import trực tiếp preset CSS:

import "webapp.ui.lib/themes/fluent.css";

5.3. Ghi đè Tokens CSS

Tất cả các biến màu và kích thước của thư viện nằm trong cascade layer @layer wwui-tokens. Bạn có thể ghi đè đơn giản ở bất kỳ file CSS nào của dự án mà không cần !important:

:root {
  --radius: 8px;
  --primary: #0f6cbd;
}

.dark {
  --primary: #2886de;
}

6. Bản Phân Phối UMD (Thẻ `<script>`)

Nếu cần nhúng nhanh qua thẻ script truyền thống:

File UMD: dist/umd/webapp.ui.lib.umd.cjs (đã nhúng sẵn toàn bộ CSS bên trong JS).
Yêu cầu các biến toàn cục: window.React, window.ReactDOM, window.jsxRuntime.
Biến toàn cục lộ ra: window.WWAppUI.

7. Giấy Phép & Bản Quyền (License & Compliance)

Mã nguồn thư viện: Phát hành theo giấy phép tự do MIT License (Copyright (c) 2026 minhvb). Cho phép sử dụng tự do trong cả dự án mã nguồn mở và thương mại (commercial).
Thư viện bên thứ ba: Danh sách chi tiết toàn bộ các thành phần mã nguồn mở bên thứ ba cùng văn bản bản quyền tương ứng được lưu trữ đầy đủ tại THIRD_PARTY_LICENSES.txt.
Âm lịch Việt Nam: Module vietnam-lunar được viết độc lập, tính trực tiếp từ công thức thiên văn của Jean Meeus (Astronomical Algorithms, 2nd ed.) và đa thức ΔT của Espenak & Meeus (NASA); phát hành theo MIT cùng thư viện.
Trình đọc PowerPoint (.pptx) & Word cũ (.doc): Sử dụng thư viện giải nén fflate (MIT) và thư viện Compound File Binary CFB từ xlsx (Apache-2.0), logic phân tích tài liệu được viết độc lập bằng TypeScript thuần tuân theo tài liệu đặc tả mở của Microsoft.

Ghi nhận: TS. Hồ Ngọc Đức và `amlich.js`

Module vietnam-lunar tham khảo các bài viết về âm lịch Việt Nam cùng chương trình amlich.js của TS. Hồ Ngọc Đức: đây là tài liệu đã giúp phổ biến cách hiểu luật lịch âm dương Việt Nam theo hướng tính toán thiên văn, và chỉ ra những điểm khiến lịch Việt Nam khác lịch Trung Quốc (múi giờ +7, các năm Tết lệch ngày như 1985, 2007, 2030).

Phần tham khảo: các quy tắc lập lịch - mùng 1 là ngày có điểm sóc theo giờ địa phương, tháng chứa Đông chí là tháng 11, tháng nhuận là tháng đầu tiên không có trung khí - cùng cách đặt vấn đề "tính lịch từ vị trí Mặt Trời và Mặt Trăng". Đây là những quy ước chung của lịch âm dương mà các bài viết của TS. Hồ Ngọc Đức trình bày rõ ràng, dễ tiếp cận bằng tiếng Việt.

Xin trân trọng cảm ơn TS. Hồ Ngọc Đức vì những đóng góp cho việc tra cứu và tính toán âm lịch Việt Nam.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

webapp.ui.lib

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

1. Cài Đặt

Cài đặt từ NPM Registry:

Hoặc cài từ file .tgz (phân phối nội bộ/offline):

2. Bắt Đầu Nhanh (Quick Start)

2.1. Nạp CSS và bọc Provider

3. Cách Thức Import

A. Barrel Import (Thuận tiện & Gọn gàng)

B. Subpath Import (Kiểm soát tuyệt đối kích thước bundle)

4. Danh Mục Controls & Bảng Tra Cứu

5. Tùy Biến Giao Diện & Themes

5.1. Chuyển đổi Theme Sáng / Tối

5.2. Microsoft Fluent 2 Style Preset

5.3. Ghi đè Tokens CSS

6. Bản Phân Phối UMD (Thẻ <script>)

7. Giấy Phép & Bản Quyền (License & Compliance)

Ghi nhận: TS. Hồ Ngọc Đức và amlich.js

Hoặc cài từ file `.tgz` (phân phối nội bộ/offline):

6. Bản Phân Phối UMD (Thẻ `<script>`)

Ghi nhận: TS. Hồ Ngọc Đức và `amlich.js`