@libs-ui/components-scroll-overlay 0.2.355-14 → 0.2.355-15

package/README.md

@@ -0,0 +1,158 @@
+# @libs-ui/components-scroll-overlay
+
+> Directive tạo thanh cuộn tùy chỉnh (custom scrollbar) thay thế thanh cuộn mặc định của trình duyệt.
+
+## Giới thiệu
+
+`LibsUiComponentsScrollOverlayDirective` là một standalone Angular directive giúp tạo ra thanh cuộn tùy chỉnh với giao diện đẹp mắt, hỗ trợ kéo thả, tự động ẩn hiện và tùy biến màu sắc.
+
+### Tính năng
+
+- ✅ Custom Scrollbar (thay thế native scrollbar)
+- ✅ Hỗ trợ cả chiều ngang (Horizontal) và chiều dọc (Vertical)
+- ✅ Tự động ẩn hiện khi hover
+- ✅ Hỗ trợ kéo thả (Drag & Drop) thanh cuộn
+- ✅ Tùy biến màu sắc, kích thước
+- ✅ Hỗ trợ Mobile/Touch devices (thông qua `getDragEventByElement`)
+- ✅ Resize Observer tự động cập nhật kích thước
+
+## Khi nào sử dụng
+
+- Khi cần giao diện thanh cuộn đồng bộ trên các trình duyệt/hệ điều hành khác nhau.
+- Khi cần thanh cuộn nhỏ gọn, overlay lên nội dung mà không chiếm diện tích layout.
+- Khi cần tùy biến màu sắc thanh cuộn theo theme của ứng dụng.
+
+## Cài đặt
+
+```bash
+# npm
+npm install @libs-ui/components-scroll-overlay
+
+# yarn
+yarn add @libs-ui/components-scroll-overlay
+```
+
+## Import
+
+```typescript
+import { LibsUiComponentsScrollOverlayDirective } from '@libs-ui/components-scroll-overlay';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiComponentsScrollOverlayDirective],
+  // ...
+})
+export class YourComponent {}
+```
+
+## Ví dụ
+
+### Basic
+
+Thêm directive vào phần tử có `overflow: scroll` hoặc `overflow: auto`.
+
+```html
+<div
+  LibsUiComponentsScrollOverlayDirective
+  class="h-[300px] w-full overflow-y-auto">
+  <!-- Content dài -->
+</div>
+```
+
+### With Options
+
+```html
+<div
+  LibsUiComponentsScrollOverlayDirective
+  [options]="{
+    scrollbarColor: '#e5e7eb',
+    scrollThumbColor: '#9ca3af',
+    scrollbarWidth: 8,
+    scrollbarPadding: 0
+  }"
+  class="h-[300px] w-full overflow-y-auto">
+  <!-- Content -->
+</div>
+```
+
+## API
+
+### LibsUiComponentsScrollOverlayDirective
+
+Selector: `[LibsUiComponentsScrollOverlayDirective]`
+
+#### Inputs
+
+| Property                | Type                    | Default        | Description                                                   |
+| ----------------------- | ----------------------- | -------------- | ------------------------------------------------------------- |
+| `[options]`             | `IScrollOverlayOptions` | `{}`           | Cấu hình cho thanh cuộn (màu sắc, kích thước, behavior).      |
+| `[classContainer]`      | `string`                | `''`           | Class CSS thêm vào container bao ngoài (do directive tạo ra). |
+| `[elementScroll]`       | `HTMLElement`           | `Host Element` | Element cần scroll (mặc định là element gắn directive).       |
+| `[elementCheckScrollX]` | `HTMLElement`           | `undefined`    | Element để tính toán scroll width (nếu khác element scroll).  |
+| `[elementCheckScrollY]` | `HTMLElement`           | `undefined`    | Element để tính toán scroll height (nếu khác element scroll). |
+| `[debugMode]`           | `boolean`               | `false`        | Bật chế độ debug log.                                         |
+| `[ignoreInit]`          | `boolean`               | `false`        | Nếu true, directive sẽ không khởi tạo scrollbar.              |
+
+#### Outputs
+
+| Property            | Type    | Description                              |
+| ------------------- | ------- | ---------------------------------------- |
+| `(outScroll)`       | `Event` | Emit khi scroll event xảy ra.            |
+| `(outScrollX)`      | `Event` | Emit khi scroll chiều ngang thay đổi.    |
+| `(outScrollY)`      | `Event` | Emit khi scroll chiều dọc thay đổi.      |
+| `(outScrollTop)`    | `Event` | Emit khi scroll lên đầu (scrollTop = 0). |
+| `(outScrollBottom)` | `Event` | Emit khi scroll xuống cuối.              |
+
+## Types & Interfaces
+
+```typescript
+export type TYPE_SCROLL_DIRECTION = 'X' | 'Y';
+export type TYPE_SCROLL_OVERFLOW = 'hidden' | 'scroll';
+
+export interface IScrollOverlayOptions {
+  ignoreTransparentScrollBarColorDefault?: boolean; // Nếu true, dùng 'auto' thay vì 'transparent' cho scrollbar-color
+  scrollbarWidth?: number; // Độ rộng của track scrollbar (default: 10)
+  scrollbarColor?: string; // Màu nền của track
+  scrollbarHoverColor?: string; // Màu nền của track khi hover
+  scrollThumbColor?: string; // Màu của thanh cuộn (thumb)
+  scrollThumbHoverColor?: string; // Màu của thanh cuộn khi hover
+  scrollbarPadding?: number; // Padding cho thumb (default: 2)
+  scrollX?: TYPE_SCROLL_OVERFLOW; // 'scroll' hoặc 'hidden' cho chiều ngang
+  scrollXOpacity0?: boolean; // Nếu true, thanh cuộn ngang vĩnh viễn ẩn (opacity 0) nhưng vẫn scroll được? (Check logic: visible but opacity 0)
+  scrollY?: TYPE_SCROLL_OVERFLOW; // 'scroll' hoặc 'hidden' cho chiều dọc
+  scrollYOpacity0?: boolean; // Tương tự cho chiều dọc
+}
+```
+
+## Styling
+
+Directive tự động inject styles vào thẻ `<style id="id-style-tag-custom-scroll-overlay">` trong `<head>`.
+Cấu trúc DOM được tạo ra:
+
+```html
+<div class="lib-ui-scroll-overlay-container ...">
+  <!-- Host Element -->
+  <div class="scrollbar-track scrollbar-track-X">
+    <div class="scrollbar-thumb scrollbar-thumb-X"></div>
+  </div>
+  <div class="scrollbar-track scrollbar-track-Y">
+    <div class="scrollbar-thumb scrollbar-thumb-Y"></div>
+  </div>
+</div>
+```
+
+## Công nghệ
+
+| Technology | Version | Purpose             |
+| ---------- | ------- | ------------------- |
+| Angular    | 18+     | Framework           |
+| RxJS       | 7.x     | Event Handling      |
+| DOM API    | -       | Scroll Manipulation |
+
+## Demo
+
+```bash
+npx nx serve core-ui
+```
+
+Truy cập: `http://localhost:4500/components/scroll-overlay`

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@libs-ui/components-scroll-overlay",
-  "version": "0.2.355-14",
+  "version": "0.2.355-15",
   "peerDependencies": {
     "@angular/core": ">=18.0.0",
-    "@libs-ui/utils": "0.2.355-14",
+    "@libs-ui/utils": "0.2.355-15",
     "rxjs": "~7.8.0"
   },
   "sideEffects": false,