@edmicro/olkit 1.0.1

package/README.md

@@ -0,0 +1,298 @@
+# @edmicro/olkit - Ôn Luyện Design System UI Library
+
+Thư viện thành phần giao diện người dùng (UI Components) chuẩn hoá 100% theo **Figma Ôn Luyện Design System** dành cho Angular (phiên bản 18+).
+
+---
+
+## 🌟 Tính năng nổi bật
+
+- 🎯 **100% Chuẩn Figma Ôn Luyện**: Chuẩn hoá toàn bộ token màu sắc Brand Prime (`#2B4182`), Crimson Red (`#C70036`), Emerald Green (`#007A55`), Orange (`#FF5A1F`), Grayscale, Shadows, Radii.
+- ⚡ **100% Standalone Components**: Import độc lập từng component trực tiếp vào Component/Page mà không cần NgModule cồng kềnh, tối ưu Tree-shaking tối đa.
+- 🎨 **Không bắt buộc cài Tailwind CSS**: Tích hợp sẵn file CSS độc lập `olkit.css` đã được pre-compile toàn bộ utility classes.
+- 🌓 **Hỗ trợ Dark Mode / Light Mode**: Tự động chuyển đổi hoặc quản lý theo class `.dark`.
+- 📱 **Hỗ trợ đa nền tảng & thiết bị**: Tương thích responsive cho Web, Tablet, Mobile Web và Webview Hybrid App.
+
+---
+
+## 📦 1. Cài đặt
+```bash
+# Cài đặt qua Bun
+bun add @edmicro/olkit
+
+# Hoặc qua NPM
+npm install @edmicro/olkit
+
+# Hoặc qua Yarn
+yarn add @edmicro/olkit
+```
+
+
+---
+
+## 🎨 2. Cấu hình Styles
+
+### Trường hợp A: Dự án **KHÔNG** sử dụng Tailwind CSS
+Chỉ cần thêm file `olkit.css` vào file CSS chính của dự án hoặc trong `angular.json`:
+
+**Cách 1: Thêm vào `src/styles.css` (hoặc `styles.scss`)**
+```css
+@import '@edmicro/olkit/olkit.css';
+```
+
+**Cách 2: Thêm vào `angular.json`**
+```json
+"architect": {
+  "build": {
+    "options": {
+      "styles": [
+        "node_modules/@edmicro/olkit/olkit.css",
+        "src/styles.css"
+      ]
+    }
+  }
+}
+```
+
+---
+
+### Trường hợp B: Dự án **ĐANG CÓ** Tailwind CSS v4
+Trong file `src/styles.css`, bạn có thể import trực tiếp:
+```css
+@import "tailwindcss";
+@import "@edmicro/olkit/olkit.css";
+```
+
+Hoặc nếu dự án dùng **Tailwind CSS v3**, thêm path vào `tailwind.config.js`:
+```js
+module.exports = {
+  content: [
+    "./src/**/*.{html,ts}",
+    "./node_modules/@edmicro/olkit/**/*.{js,mjs}"
+  ],
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          50: '#F5F8FF',
+          100: '#E3EAFF',
+          200: '#D2DCFA',
+          300: '#A3BAFF',
+          400: '#8C9ED4',
+          500: '#6D7FB3',
+          600: '#5168AC',
+          700: '#2B4182', // Onluyen - Prime
+          800: '#203165',
+          900: '#152147',
+          950: '#0D142B',
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🚀 3. Hướng dẫn sử dụng Components
+
+Do tất cả component đều là **Standalone**, bạn chỉ cần import component nào bạn thực sự sử dụng vào mảng `imports: [...]` của Angular Component.
+
+```typescript
+import { Component } from '@angular/core';
+import { 
+  ButtonComponent, 
+  DownloadAppButtonComponent,
+  AlertComponent, 
+  AccordionComponent, 
+  AccordionItemComponent,
+  ModalComponent,
+  TabsComponent,
+  TabItemComponent
+} from '@edmicro/olkit';
+
+@Component({
+  selector: 'app-dashboard',
+  standalone: true,
+  imports: [
+    ButtonComponent,
+    DownloadAppButtonComponent,
+    AlertComponent,
+    AccordionComponent,
+    AccordionItemComponent,
+    ModalComponent,
+    TabsComponent,
+    TabItemComponent
+  ],
+  templateUrl: './dashboard.component.html'
+})
+export class DashboardComponent {
+  isModalOpen = false;
+
+  openModal() {
+    this.isModalOpen = true;
+  }
+}
+```
+
+---
+
+## 💻 4. Code Mẫu Chi Tiết Từng Component
+
+### 🔘 Buttons (`<ol-button>`)
+Hỗ trợ đầy đủ biến thể theo Figma Ôn Luyện: `brand` (#2B4182), `green` (#007A55), `red` (#C70036), `orange` (#FF5A1F), `ghost`, `tertiary`, `dark`, `white`.
+
+```html
+<!-- 1. Màu sắc cơ bản -->
+<ol-button color="brand" size="md">Bắt đầu ngay</ol-button>
+<ol-button color="green" size="md">Nộp bài</ol-button>
+<ol-button color="red" size="md">Thoát bài thi</ol-button>
+<ol-button color="orange" size="md">Tạm dừng</ol-button>
+
+<!-- 2. Kiểu Outline & Ghost -->
+<ol-button color="brand" [outline]="true">Nút viền Brand</ol-button>
+<ol-button color="ghost">Nút trong suốt (Ghost)</ol-button>
+<ol-button color="tertiary">Nút phụ Tertiary</ol-button>
+
+<!-- 3. Kích thước (xs, sm, md, lg, xl) -->
+<ol-button size="xs">Cực nhỏ (xs)</ol-button>
+<ol-button size="sm">Nhỏ (sm)</ol-button>
+<ol-button size="md">Tiêu chuẩn (md)</ol-button>
+<ol-button size="lg">Lớn (lg)</ol-button>
+<ol-button size="xl">Rất lớn (xl)</ol-button>
+
+<!-- 4. Kiểu bo góc (Pill / 12px / Mặc định) -->
+<ol-button color="brand" [pill]="true">Bo tròn hoàn toàn (Pill)</ol-button>
+
+<!-- 5. Trạng thái Loading & Disabled -->
+<ol-button color="brand" [loading]="true" loadingText="Đang xử lý...">Đăng nhập</ol-button>
+<ol-button color="brand" [disabled]="true">Vô hiệu hóa</ol-button>
+
+<!-- 6. Button chứa Icon -->
+<ol-button color="brand">
+  <svg class="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
+  </svg>
+  Thêm mới
+</ol-button>
+```
+
+---
+
+### 📲 Nút Tải Ứng Dụng (`<ol-download-app-button>`)
+Nút tải chuẩn nhận diện App Store & Google Play từ Figma Ôn Luyện (tự động thích ứng Light/Dark mode).
+
+```html
+<!-- Tự động thích ứng theme theo hệ thống / dark class -->
+<ol-download-app-button store="appstore" (clicked)="onDownloadIos()" />
+<ol-download-app-button store="googleplay" (clicked)="onDownloadAndroid()" />
+
+<!-- Ép giao diện Sáng hoặc Tối -->
+<ol-download-app-button store="appstore" theme="light" />
+<ol-download-app-button store="googleplay" theme="dark" />
+```
+
+---
+
+### 🔔 Alerts (`<ol-alert>`)
+Thông báo phản hồi ngữ cảnh: `info`, `danger` (red), `success` (green), `warning` (orange), `dark`.
+
+```html
+<!-- Thông báo đơn giản -->
+<ol-alert color="info">Đây là thông báo thông tin hệ thống.</ol-alert>
+<ol-alert color="success">Chúc mừng bạn đã hoàn thành bài thi với 100 điểm!</ol-alert>
+<ol-alert color="danger">Đã có lỗi xảy ra trong quá trình lưu kết quả.</ol-alert>
+<ol-alert color="warning">Thời gian làm bài còn lại dưới 5 phút.</ol-alert>
+
+<!-- Thông báo có nút đóng (Dismissible) -->
+<ol-alert color="info" [dismissible]="true" (closed)="onAlertClosed()">
+  Bạn có thể tắt thông báo này khi đã đọc xong.
+</ol-alert>
+
+<!-- Thông báo dạng Border Accent -->
+<ol-alert color="danger" [border]="true">
+  Lỗi bảo mật: Phiên làm việc đã hết hạn.
+</ol-alert>
+```
+
+---
+
+### 🪟 Modals (`<ol-modal>`)
+Cửa sổ hộp thoại tương tác cao, có thể backdrop dismiss, ESC key, nhiều kích thước:
+
+```html
+<ol-button color="brand" (click)="isModalOpen = true">Mở Modal</ol-button>
+
+<ol-modal 
+  [(isOpen)]="isModalOpen" 
+  title="Xác nhận nộp bài thi" 
+  size="md"
+  [dismissible]="true"
+>
+  <p class="text-sm text-gray-600 dark:text-gray-300">
+    Bạn còn 3 câu chưa hoàn thành. Bạn có chắc chắn muốn nộp bài thi ngay bây giờ không?
+  </p>
+
+  <div slot="footer" class="flex justify-end gap-3">
+    <ol-button color="ghost" (click)="isModalOpen = false">Làm tiếp</ol-button>
+    <ol-button color="brand" (click)="submitExam()">Xác nhận nộp</ol-button>
+  </div>
+</ol-modal>
+```
+
+---
+
+### 📂 Accordion (`<ol-accordion>` & `<ol-accordion-item>`)
+
+```html
+<ol-accordion [alwaysOpen]="false">
+  <ol-accordion-item title="Chương 1: Khái niệm cơ bản" [isOpen]="true">
+    Nội dung lý thuyết và các định nghĩa cơ bản của chương 1...
+  </ol-accordion-item>
+
+  <ol-accordion-item title="Chương 2: Phương pháp giải bài tập">
+    Các dạng bài tập thường gặp và phương pháp giải chi tiết...
+  </ol-accordion-item>
+
+  <ol-accordion-item title="Chương 3: Đề thi thử">
+    Bộ 10 đề thi thử bám sát cấu trúc mới nhất...
+  </ol-accordion-item>
+</ol-accordion>
+```
+
+---
+
+### 📑 Tabs (`<ol-tabs>` & `<ol-tab-item>`)
+
+```html
+<ol-tabs variant="underline">
+  <ol-tab-item title="Tổng quan" [active]="true">
+    <p>Nội dung tổng quan khoá học...</p>
+  </ol-tab-item>
+
+  <ol-tab-item title="Danh sách bài học">
+    <p>Chi tiết từng bài học trong lộ trình...</p>
+  </ol-tab-item>
+
+  <ol-tab-item title="Đánh giá & Bình luận">
+    <p>Phản hồi từ học sinh và giáo viên...</p>
+  </ol-tab-item>
+</ol-tabs>
+```
+
+---
+
+## 🛠️ 5. Cập nhật phiên bản mới
+
+Khi có bản phát hành mới từ GitLab, bạn chỉ cần chạy lệnh cập nhật:
+
+```bash
+# Cập nhật lại package từ repository
+npm install git+https://gitlab.edmicro.io/onluyenpub/olkit-deploy.git#v1.0.1
+```
+
+---
+
+## 📄 Bản quyền & Liên hệ
+- **Đơn vị phát triển**: EDMICRO - Đội ngũ Frontend Ôn Luyện V4.
+- **Figma Design System**: [Ôn Luyện Design System](https://www.figma.com/design/lip4g3PkcupVurtCxXCkEz/%C3%94n-Luy%E1%BB%87n-Design-System?node-id=2542-21012)
+- **GitLab Repository**: [https://gitlab.edmicro.io/onluyenpub/olkit-deploy](https://gitlab.edmicro.io/onluyenpub/olkit-deploy)