@ehfuse/overlay-scrollbar 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KIM YOUNG JIN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# OverlayScrollbar
+
+A React component that provides a custom overlay scrollbar with smooth animations and auto-hide functionality.
+
+## 📚 Documentation
+
+-   **[Getting Started (English)](https://github.com/ehfuse/overlay-scrollbar/blob/main/docs/getting-started-en.md)** - Complete setup and usage guide
+-   **[시작하기 (한국어)](https://github.com/ehfuse/overlay-scrollbar/blob/main/docs/getting-started-ko.md)** - 설치 및 사용법 가이드
+
+## Features
+
+-   🎨 **Custom styled scrollbar** - Beautiful overlay scrollbar that doesn't take up content space
+-   ⚡ **Smooth animations** - Smooth fade-in/out transitions with customizable timing
+-   🔍 **Auto-hide functionality** - Automatically hides when not needed and shows on scroll/hover
+-   📱 **Responsive design** - Adapts to container size changes with ResizeObserver
+-   🎯 **Interactive** - Support for click-to-scroll and drag-to-scroll functionality
+-   🔧 **TypeScript support** - Full TypeScript support with proper type definitions
+-   🪶 **Lightweight** - No external dependencies except React
+-   ♿ **Accessible** - Maintains native scroll behavior while providing visual enhancements
+
+## Installation
+
+```bash
+npm install @ehfuse/overlay-scrollbar
+```
+
+or
+
+```bash
+yarn add @ehfuse/overlay-scrollbar
+```
+
+## Quick Start
+
+For detailed setup instructions, see the [Getting Started Guide](https://github.com/ehfuse/overlay-scrollbar/blob/main/docs/getting-started-en.md).
+
+```tsx
+import React from "react";
+import { OverlayScrollbar } from "@ehfuse/overlay-scrollbar";
+
+function App() {
+    return (
+        <div style={{ height: "400px" }}>
+            <OverlayScrollbar>
+                <div style={{ height: "1000px" }}>
+                    {/* Your scrollable content here */}
+                </div>
+            </OverlayScrollbar>
+        </div>
+    );
+}
+```
+
+## Usage
+
+### Basic Usage
+
+```tsx
+import React from "react";
+import { OverlayScrollbar } from "@ehfuse/overlay-scrollbar";
+
+function App() {
+    return (
+        <div style={{ height: "400px" }}>
+            <OverlayScrollbar>
+                <div style={{ height: "1000px" }}>
+                    {/* Your scrollable content here */}
+                    <p>Long content that requires scrolling...</p>
+                </div>
+            </OverlayScrollbar>
+        </div>
+    );
+}
+```
+
+### With Ref Access
+
+```tsx
+import React, { useRef } from "react";
+import {
+    OverlayScrollbar,
+    OverlayScrollbarRef,
+} from "@ehfuse/overlay-scrollbar";
+
+function App() {
+    const scrollbarRef = useRef<OverlayScrollbarRef>(null);
+
+    const scrollToTop = () => {
+        scrollbarRef.current?.scrollTo({ top: 0, behavior: "smooth" });
+    };
+
+    const getScrollInfo = () => {
+        if (scrollbarRef.current) {
+            console.log("Scroll Top:", scrollbarRef.current.scrollTop);
+            console.log("Scroll Height:", scrollbarRef.current.scrollHeight);
+            console.log("Client Height:", scrollbarRef.current.clientHeight);
+        }
+    };
+
+    return (
+        <div style={{ height: "400px" }}>
+            <button onClick={scrollToTop}>Scroll to Top</button>
+            <button onClick={getScrollInfo}>Get Scroll Info</button>
+
+            <OverlayScrollbar ref={scrollbarRef}>
+                <div style={{ height: "1000px" }}>
+                    {/* Your scrollable content here */}
+                </div>
+            </OverlayScrollbar>
+        </div>
+    );
+}
+```
+
+### With Custom Styling
+
+```tsx
+import React from "react";
+import { OverlayScrollbar } from "@ehfuse/overlay-scrollbar";
+
+function App() {
+    return (
+        <OverlayScrollbar
+            className="my-scrollbar"
+            style={{
+                height: "400px",
+                border: "1px solid #ccc",
+                borderRadius: "8px",
+            }}
+            onScroll={(event) => {
+                console.log("Scrolled!", event);
+            }}
+        >
+            <div style={{ height: "1000px", padding: "20px" }}>
+                {/* Your content */}
+            </div>
+        </OverlayScrollbar>
+    );
+}
+```
+
+## API Reference
+
+### Props
+
+| Prop        | Type                     | Default | Description                                |
+| ----------- | ------------------------ | ------- | ------------------------------------------ |
+| `children`  | `ReactNode`              | -       | The content to be scrolled                 |
+| `className` | `string`                 | -       | Additional CSS class for the container     |
+| `style`     | `React.CSSProperties`    | -       | Additional inline styles for the container |
+| `onScroll`  | `(event: Event) => void` | -       | Callback fired when scrolling occurs       |
+
+### Ref Methods
+
+The component exposes several methods through ref:
+
+| Method               | Type                                 | Description                              |
+| -------------------- | ------------------------------------ | ---------------------------------------- |
+| `getScrollContainer` | `() => HTMLDivElement \| null`       | Returns the scrollable container element |
+| `scrollTo`           | `(options: ScrollToOptions) => void` | Scrolls to a specific position           |
+| `scrollTop`          | `number`                             | Gets the current scroll top position     |
+| `scrollHeight`       | `number`                             | Gets the total scrollable height         |
+| `clientHeight`       | `number`                             | Gets the visible height of the container |
+
+### ScrollToOptions
+
+```typescript
+interface ScrollToOptions {
+    top?: number;
+    left?: number;
+    behavior?: "auto" | "smooth";
+}
+```
+
+## Behavior
+
+-   **Auto-hide**: The scrollbar automatically hides after 0.7 seconds of inactivity during wheel scroll or regular scrolling
+-   **Hover reveal**: Hovering over the right edge (20px wide area) shows the scrollbar with track background
+-   **Interactive scrolling**:
+    -   Click on the track to jump to that position
+    -   Drag the thumb for precise scrolling
+    -   Mouse wheel scrolling works normally
+-   **Responsive**: Automatically adapts to content and container size changes
+-   **Smooth animations**: All show/hide transitions are smoothly animated
+
+## Styling
+
+The component uses CSS-in-JS for styling and automatically hides native scrollbars. The custom scrollbar has:
+
+-   **Track**: Semi-transparent background that appears on hover/interaction
+-   **Thumb**: The draggable scrollbar handle with hover effects
+-   **Positioning**: 8px wide, positioned 2px from the right edge
+-   **Colors**: Configurable through CSS custom properties (future enhancement)
+
+## Browser Support
+
+-   Chrome/Edge: Full support
+-   Firefox: Full support
+-   Safari: Full support
+-   Mobile browsers: Touch scrolling supported, overlay scrollbar hidden on mobile
+
+## Performance
+
+-   Uses `ResizeObserver` for efficient size change detection
+-   Debounced scroll events to prevent excessive re-renders
+-   Passive event listeners where possible
+-   Minimal DOM manipulation and optimized for 60fps animations
+
+## License
+
+MIT © [KIM YOUNG JIN](mailto:ehfuse@gmail.com)
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Issues
+
+If you find any bugs or have feature requests, please create an issue on [GitHub](https://github.com/ehfuse/overlay-scrollbar/issues).

package/dist/OverlayScrollbar.d.ts

@@ -0,0 +1,43 @@
+/**
+ * OverlayScrollbar.tsx
+ *
+ * A React component that provides a custom overlay scrollbar with smooth animations and auto-hide functionality
+ *
+ * @license MIT
+ * @copyright 2025 KIM YOUNG JIN (ehfuse@gmail.com)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import React, { ReactNode } from "react";
+interface OverlayScrollbarProps {
+    className?: string;
+    style?: React.CSSProperties;
+    children: ReactNode;
+    onScroll?: (event: Event) => void;
+}
+export interface OverlayScrollbarRef {
+    getScrollContainer: () => HTMLDivElement | null;
+    scrollTo: (options: ScrollToOptions) => void;
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+export declare const OverlayScrollbar: React.ForwardRefExoticComponent<OverlayScrollbarProps & React.RefAttributes<OverlayScrollbarRef>>;
+export default OverlayScrollbar;
+//# sourceMappingURL=OverlayScrollbar.d.ts.map

package/dist/OverlayScrollbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OverlayScrollbar.d.ts","sourceRoot":"","sources":["../OverlayScrollbar.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,EAA4C,SAAS,EAAmC,MAAM,OAAO,CAAC;AAEpH,UAAU,qBAAqB;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC;AAGD,MAAM,WAAW,mBAAmB;IAChC,kBAAkB,EAAE,MAAM,cAAc,GAAG,IAAI,CAAC;IAChD,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,mGAue5B,CAAC;AAEF,eAAe,gBAAgB,CAAC"}

package/dist/core/OverlayScrollbar.d.ts

@@ -0,0 +1,43 @@
+/**
+ * OverlayScrollbar.tsx
+ *
+ * A React component that provides a custom overlay scrollbar with smooth animations and auto-hide functionality
+ *
+ * @license MIT
+ * @copyright 2025 KIM YOUNG JIN (ehfuse@gmail.com)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import React, { ReactNode } from "react";
+interface OverlayScrollbarProps {
+    className?: string;
+    style?: React.CSSProperties;
+    children: ReactNode;
+    onScroll?: (event: Event) => void;
+}
+export interface OverlayScrollbarRef {
+    getScrollContainer: () => HTMLDivElement | null;
+    scrollTo: (options: ScrollToOptions) => void;
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+export declare const OverlayScrollbar: React.ForwardRefExoticComponent<OverlayScrollbarProps & React.RefAttributes<OverlayScrollbarRef>>;
+export default OverlayScrollbar;
+//# sourceMappingURL=OverlayScrollbar.d.ts.map

package/dist/core/OverlayScrollbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OverlayScrollbar.d.ts","sourceRoot":"","sources":["../../core/OverlayScrollbar.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,EAKV,SAAS,EAGZ,MAAM,OAAO,CAAC;AAEf,UAAU,qBAAqB;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC;AAGD,MAAM,WAAW,mBAAmB;IAChC,kBAAkB,EAAE,MAAM,cAAc,GAAG,IAAI,CAAC;IAChD,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,mGAogB3B,CAAC;AAEH,eAAe,gBAAgB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import React, { ReactNode } from 'react';
+
+/**
+ * OverlayScrollbar.tsx
+ *
+ * A React component that provides a custom overlay scrollbar with smooth animations and auto-hide functionality
+ *
+ * @license MIT
+ * @copyright 2025 KIM YOUNG JIN (ehfuse@gmail.com)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+interface OverlayScrollbarProps {
+    className?: string;
+    style?: React.CSSProperties;
+    children: ReactNode;
+    onScroll?: (event: Event) => void;
+}
+interface OverlayScrollbarRef {
+    getScrollContainer: () => HTMLDivElement | null;
+    scrollTo: (options: ScrollToOptions) => void;
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+declare const OverlayScrollbar: React.ForwardRefExoticComponent<OverlayScrollbarProps & React.RefAttributes<OverlayScrollbarRef>>;
+
+export { OverlayScrollbar, OverlayScrollbar as default };
+export type { OverlayScrollbarRef };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,gBAAgB,IAAI,OAAO,EAC3B,gBAAgB,GACnB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC"}