@edmicro/olkit

v2.1.20

Published

8 days ago

Ôn Luyện Design System UI Component Library for Angular

0High
0Medium
0Low

angular design-system onluyen olkit ui-library tailwind components

@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.
🌲 Tree-shaking tối ưu với Secondary Entry Points: Mỗi component có entry point riêng (@edmicro/olkit/button, @edmicro/olkit/modal, etc.) giúp giảm bundle size xuống ~25KB khi chỉ import 1 component thay vì 1.9MB khi import từ main entry point.
🎨 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 và design tokens.
🌓 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.
🧩 Tích hợp liền mạch với @edmicro/olkit-icons: Tự động bundle sẵn toàn bộ các icon lõi (Core icons) phục vụ đóng/mở, thông báo, điều hướng.

📦 1. Cài đặt

Cài đặt @edmicro/olkit cùng với gói icons phụ thuộc @edmicro/olkit-icons:

# Cài đặt qua NPM
npm install @edmicro/olkit @edmicro/olkit-icons

# Hoặc qua Yarn / Bun / PNPM
yarn add @edmicro/olkit @edmicro/olkit-icons
bun add @edmicro/olkit @edmicro/olkit-icons
pnpm add @edmicro/olkit @edmicro/olkit-icons

🎨 2. Cấu hình Styles (Bắt buộc)

Thêm file olkit.css vào mục styles trong file angular.json của dự án:

"architect": {
  "build": {
    "options": {
      "styles": [
        "node_modules/@edmicro/olkit/olkit.css",
        "src/styles.scss"
      ]
    }
  }
}

💡 Tại sao chỉ cần thêm vào angular.json?
File olkit.css là bản CSS độc lập đã được biên dịch sẵn toàn bộ Design Tokens (màu sắc Ôn Luyện, bo góc, bóng đổ) và toàn bộ utility classes. Việc khai báo trực tiếp vào angular.json đảm bảo hoạt động tương thích 100% trên mọi dự án Angular (SCSS / CSS, có hoặc không có Tailwind CSS).
⚠️ Lưu ý: Sau khi lưu file angular.json, hãy khởi động lại dev server (Ctrl + C và chạy lại ng serve / npm start) để Angular áp dụng stylesheet mới.

🚀 3. Hướng dẫn sử dụng cơ bản

✅ Phương pháp khuyến nghị: Import từ Secondary Entry Points (Tree-shakable)

Để tối ưu bundle size, nên import từng component từ entry point riêng:

import { Component } from '@angular/core';
// Import từng component từ secondary entry point riêng
import { OlButton } from '@edmicro/olkit/button';
import { OlAlert } from '@edmicro/olkit/alert';
import { OlModal } from '@edmicro/olkit/modal';
import { OlTabs, OlTabItem } from '@edmicro/olkit/tabs';
import { OlAccordion, OlAccordionItem } from '@edmicro/olkit/accordion';
import { OlInput } from '@edmicro/olkit/input';
import { OlSelect } from '@edmicro/olkit/select';

@Component({
  selector: 'app-dashboard',
  standalone: true,
  imports: [
    OlButton,
    OlAlert,
    OlModal,
    OlTabs,
    OlTabItem,
    OlAccordion,
    OlAccordionItem,
    OlInput,
    OlSelect,
  ],
  templateUrl: './dashboard.component.html',
})
export class DashboardComponent {
  isModalOpen = false;

  openModal() {
    this.isModalOpen = true;
  }
}

Lợi ích: Bundle chỉ chứa đúng những gì bạn sử dụng → giảm từ ~1.9MB xuống còn ~25KB cho mỗi component.

📦 Danh sách Secondary Entry Points

Tất cả components đều có secondary entry point riêng theo pattern @edmicro/olkit/{component-name}:

Layout & Navigation:

@edmicro/olkit/accordion - Accordion, AccordionItem
@edmicro/olkit/app-header - AppHeader
@edmicro/olkit/app-nav - AppNav (sidebar navigation)
@edmicro/olkit/banner - Banner
@edmicro/olkit/bottom-nav - BottomNav, BottomNavItem
@edmicro/olkit/breadcrumb - Breadcrumb, BreadcrumbItem
@edmicro/olkit/drawer - Drawer, DrawerHeader, DrawerFooter
@edmicro/olkit/footer - Footer
@edmicro/olkit/menubar - Menubar
@edmicro/olkit/navbar - Navbar, NavbarItem, NavDropdown
@edmicro/olkit/sidebar - Sidebar, SidebarGroup, SidebarItem, SidebarSubmenu
@edmicro/olkit/tabs - Tabs, TabItem
@edmicro/olkit/stepper - Stepper, StepItem

Forms & Input:

@edmicro/olkit/input - Input
@edmicro/olkit/select - Select
@edmicro/olkit/cascade-select - CascadeSelect
@edmicro/olkit/checkbox - Checkbox
@edmicro/olkit/radio - Radio
@edmicro/olkit/forms-autocomplete - Autocomplete
@edmicro/olkit/forms-checkbox-radio-form - CheckboxRadioForm
@edmicro/olkit/forms-checkbox-radio-group - CheckboxRadioGroup
@edmicro/olkit/forms-file-input - FileInput
@edmicro/olkit/forms-file-upload - FileUpload, FileDropzone, FileItem
@edmicro/olkit/forms-helper - Helper
@edmicro/olkit/forms-input-counter - InputCounter
@edmicro/olkit/forms-label - Label
@edmicro/olkit/forms-otp-input - OtpInput
@edmicro/olkit/forms-range - Range
@edmicro/olkit/forms-rich-text-editor - RichTextEditor
@edmicro/olkit/forms-segmented - Segmented
@edmicro/olkit/forms-shared - FieldFrame, FieldLabel
@edmicro/olkit/forms-tag-input - TagInput
@edmicro/olkit/forms-textarea - Textarea
@edmicro/olkit/forms-timepicker - Timepicker
@edmicro/olkit/forms-toggle - Toggle
@edmicro/olkit/forms-toggle-group - ToggleGroup
@edmicro/olkit/forms-toggle-input - ToggleInput
@edmicro/olkit/datepicker - Datepicker, DateRangePicker

Buttons & Actions:

@edmicro/olkit/button - Button, DownloadAppButton
@edmicro/olkit/button-group - ButtonGroup

Feedback & Overlays:

@edmicro/olkit/alert - Alert
@edmicro/olkit/alert-dialog - AlertDialog
@edmicro/olkit/modal - Modal, ModalHeader, ModalFooter
@edmicro/olkit/toast - Toast (Snackbar)
@edmicro/olkit/popover - Popover, PopoverContent
@edmicro/olkit/tooltip - Tooltip
@edmicro/olkit/progress - Progress, ProgressBarTop, LoadingOverlay, ProgressBarService
@edmicro/olkit/skeleton - Skeleton
@edmicro/olkit/spinner - Spinner

Data Display:

@edmicro/olkit/avatar - Avatar, AvatarGroup
@edmicro/olkit/badge - Badge
@edmicro/olkit/card - Card
@edmicro/olkit/chart - Chart
@edmicro/olkit/carousel - Carousel, CarouselSlide
@edmicro/olkit/chat-bubble - ChatBubble, ChatContainer
@edmicro/olkit/dropdown - Dropdown, DropdownItem, DropdownHeader, DropdownSearch
@edmicro/olkit/empty - Empty
@edmicro/olkit/gallery - Gallery, GalleryItem
@edmicro/olkit/image-preview - ImagePreview
@edmicro/olkit/list-group - ListGroup, ListGroupItem
@edmicro/olkit/pagination - Pagination
@edmicro/olkit/rating - Rating
@edmicro/olkit/table - Table (DataTable)
@edmicro/olkit/tree - Tree

Utilities:

@edmicro/olkit/aspect-ratio - AspectRatio
@edmicro/olkit/clipboard - Clipboard
@edmicro/olkit/collapse - Collapse
@edmicro/olkit/command - Command
@edmicro/olkit/device-mockup - DeviceMockup
@edmicro/olkit/frame - Frame
@edmicro/olkit/item - Item
@edmicro/olkit/jumbotron - Jumbotron
@edmicro/olkit/kbd - Kbd
@edmicro/olkit/logo - Logo
@edmicro/olkit/pattern - Pattern
@edmicro/olkit/resizable - Resizable
@edmicro/olkit/scroll-area - ScrollArea
@edmicro/olkit/scrollspy - Scrollspy
@edmicro/olkit/separator - Separator

Core:

@edmicro/olkit/core - Core utilities, services, overlays

⚠️ Phương pháp cũ: Import từ main entry point (không khuyến nghị)

// ❌ KHÔNG khuyến nghị - bundle toàn bộ library (~1.9MB)
import {
  OlButton,
  OlAlert,
  OlModal,
  OlTabs,
  OlTabItem,
} from '@edmicro/olkit';

Main entry point (@edmicro/olkit) vẫn hoạt động để tương thích ngược, nhưng sẽ bundle toàn bộ library vào production build.

💻 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, green, red, orange, ghost, tertiary, dark, white.

<!-- 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 / Mặc định) -->
<ol-button color="brand" [pill]="true">Bo trò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>

🔔 Alerts (`<ol-alert>`)

Thông báo phản hồi ngữ cảnh: info, danger (red), success (green), warning (orange), neutral.

<!-- 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, hỗ trợ backdrop dismiss, phím ESC, nhiều kích thước:

<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>

📑 Tabs (`<ol-tabs>` & `<ol-tab-item>`)

<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>

📂 Accordion (`<ol-accordion>` & `<ol-accordion-item>`)

<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>

🎯 Sử dụng Icon với `@edmicro/olkit-icons`

Để hiển thị icon tùy biến ở bất kỳ đâu trong ứng dụng:

import { Component } from '@angular/core';
import { OlIcon, provideOlIcons } from '@edmicro/olkit-icons';
import { solar_home_2_linear } from '@edmicro/olkit-icons/solar';
import { lucide_search } from '@edmicro/olkit-icons/lucide';

@Component({
  standalone: true,
  imports: [OlIcon],
  providers: [
    provideOlIcons({ solar_home_2_linear, lucide_search })
  ],
  template: `
    <ol-icon name="solar_home_2_linear" size="base" class="text-brand" />
    <ol-icon name="lucide_search" [size]="20" />
  `
})
export class MyComponent {}

🛠️ 5. Cập nhật phiên bản mới

# Nâng lên bản mới nhất của cả 2 gói
npm install @edmicro/olkit@latest @edmicro/olkit-icons@latest

# Xem các phiên bản đã phát hành trên NPM
npm view @edmicro/olkit versions
npm view @edmicro/olkit-icons versions

📄 License & Bản quyền

LICENSE — Giấy phép MIT chính
THIRD-PARTY-NOTICES — Thông báo đầy đủ về các thư viện mã nguồn mở bên thứ ba

📞 Liên hệ & Hỗ trợ

Đơn vị phát triển: EDMICRO — Đội ngũ Frontend Ôn Luyện V4
Figma Design System: Ôn Luyện Design System
GitLab Repository: https://gitlab.edmicro.io/onluyenpub/olkit-deploy

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme