# @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`