react-edge-dock 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Your Name]
+
+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,41 @@
+# react-edge-dock
+
+A zero-dependency React + TypeScript library for customizable draggable edge-docked floating buttons with popup support.
+
+## Features
+
+- 🎯 Zero dependencies (React only)
+- 🎨 Fully customizable and headless
+- 📱 Touch and pointer event support
+- 🎬 Smooth animations with spring physics
+- 📦 TypeScript first with full type safety
+- 🎮 Multiple docking modes (free, auto, manual)
+- 💡 Smart popup positioning
+- ⚡ Performance optimized with transform: translate3d
+
+## Installation
+
+```bash
+npm install react-edge-dock
+```
+
+## Quick Start
+
+```tsx
+import { EdgeDock } from 'react-edge-dock';
+
+function App() {
+  return (
+    <EdgeDock
+      dockMode="auto"
+      animation={true}
+      button={<button>🚀</button>}
+      popup={<div>Your content here</div>}
+    />
+  );
+}
+```
+
+## API
+
+See the [example.tsx](./example.tsx) file for more detailed usage examples.

package/dist/EdgeDock.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { EdgeDockProps } from './types';
+/**
+ * EdgeDock - A customizable draggable edge-docked floating button with popup
+ *
+ * @example
+ * ```tsx
+ * <EdgeDock
+ *   dockMode="auto"
+ *   animation={true}
+ *   button={<button>Click me</button>}
+ *   popup={<div>Popup content</div>}
+ * />
+ * ```
+ */
+export declare function EdgeDock(props: EdgeDockProps): React.JSX.Element;
+//# sourceMappingURL=EdgeDock.d.ts.map

package/dist/EdgeDock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeDock.d.ts","sourceRoot":"","sources":["../src/EdgeDock.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,qBAkF5C"}

package/dist/EdgeDock.js

@@ -0,0 +1,69 @@
+import React from 'react';
+import { useEdgeDock } from './useEdgeDock';
+/**
+ * EdgeDock - A customizable draggable edge-docked floating button with popup
+ *
+ * @example
+ * ```tsx
+ * <EdgeDock
+ *   dockMode="auto"
+ *   animation={true}
+ *   button={<button>Click me</button>}
+ *   popup={<div>Popup content</div>}
+ * />
+ * ```
+ */
+export function EdgeDock(props) {
+    const { button, popup, className, style, dockMode, dockEdge, position, animation, popupGap, zIndex, onDockChange, isPopupOpen, onPopupChange, } = props;
+    const { state, buttonRef, popupRef, closePopup, buttonStyles, popupStyles, buttonProps, } = useEdgeDock({
+        dockMode,
+        dockEdge,
+        position,
+        animation,
+        popupGap,
+        zIndex,
+        onDockChange,
+        isPopupOpen,
+        onPopupChange,
+    });
+    // Render button content
+    const renderButton = () => {
+        if (typeof button === 'function') {
+            return button(state);
+        }
+        return button || React.createElement(DefaultButton, null);
+    };
+    // Render popup content
+    const renderPopup = () => {
+        if (!popup)
+            return null;
+        if (typeof popup === 'function') {
+            return popup(state, closePopup);
+        }
+        return popup;
+    };
+    return (React.createElement(React.Fragment, null,
+        React.createElement("div", { ref: buttonRef, className: className, style: style ? { ...buttonStyles, ...style } : buttonStyles, onPointerDown: buttonProps.onPointerDown, onClick: buttonProps.onClick },
+            React.createElement("div", { style: buttonProps.style }, renderButton())),
+        popup && (React.createElement("div", { ref: popupRef, style: popupStyles, onClick: (e) => e.stopPropagation() }, renderPopup()))));
+}
+/**
+ * Default button component
+ */
+function DefaultButton() {
+    return (React.createElement("div", { style: {
+            width: 48,
+            height: 48,
+            borderRadius: '50%',
+            backgroundColor: '#0070f3',
+            color: 'white',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            fontSize: 24,
+            fontWeight: 'bold',
+            boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
+            cursor: 'pointer',
+            userSelect: 'none',
+        } }, "\u26A1"));
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * react-edge-dock
+ * A zero-dependency React + TypeScript library for customizable draggable edge-docked floating buttons
+ */
+export { EdgeDock } from './EdgeDock';
+export { useEdgeDock } from './useEdgeDock';
+export type { DockEdge, DockMode, Position, DockState, EdgeDockConfig, EdgeDockProps, UseEdgeDockReturn, ViewportBounds, ElementDimensions, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * react-edge-dock
+ * A zero-dependency React + TypeScript library for customizable draggable edge-docked floating buttons
+ */
+export { EdgeDock } from './EdgeDock';
+export { useEdgeDock } from './useEdgeDock';

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+import { ReactNode } from 'react';
+/**
+ * Dock edge position
+ */
+export type DockEdge = 'left' | 'right' | 'top' | 'bottom';
+/**
+ * Dock mode determines how the button snaps
+ */
+export type DockMode = 'free' | 'auto' | 'manual';
+/**
+ * 2D position coordinates
+ */
+export interface Position {
+    x: number;
+    y: number;
+}
+/**
+ * Dock state information
+ */
+export interface DockState {
+    /** Current position in pixels */
+    position: Position;
+    /** Current docked edge (null if in free mode) */
+    dockedEdge: DockEdge | null;
+    /** Whether the button is currently being dragged */
+    isDragging: boolean;
+    /** Whether the popup is currently open */
+    isPopupOpen: boolean;
+}
+/**
+ * Configuration for EdgeDock component
+ */
+export interface EdgeDockConfig {
+    /** Docking behavior mode */
+    dockMode?: DockMode;
+    /** Fixed edge for manual dock mode */
+    dockEdge?: DockEdge;
+    /** Initial or controlled position */
+    position?: Position;
+    /** Enable snap animations */
+    animation?: boolean;
+    /** Gap between button and popup in pixels */
+    popupGap?: number;
+    /** z-index for the dock container */
+    zIndex?: number;
+    /** Callback when dock state changes */
+    onDockChange?: (state: DockState) => void;
+    /** Controlled popup open state */
+    isPopupOpen?: boolean;
+    /** Callback when popup state changes */
+    onPopupChange?: (isOpen: boolean) => void;
+}
+/**
+ * Props for EdgeDock component
+ */
+export interface EdgeDockProps extends EdgeDockConfig {
+    /** Custom button element or render prop */
+    button?: ReactNode | ((state: DockState) => ReactNode);
+    /** Custom popup content or render prop */
+    popup?: ReactNode | ((state: DockState, close: () => void) => ReactNode);
+    /** Additional CSS class for container */
+    className?: string;
+    /** Additional inline styles for container */
+    style?: React.CSSProperties;
+}
+/**
+ * Return type for useEdgeDock hook
+ */
+export interface UseEdgeDockReturn {
+    /** Current dock state */
+    state: DockState;
+    /** Ref to attach to draggable button element */
+    buttonRef: React.RefObject<HTMLDivElement>;
+    /** Ref to attach to popup element */
+    popupRef: React.RefObject<HTMLDivElement>;
+    /** Toggle popup open/closed */
+    togglePopup: () => void;
+    /** Close popup */
+    closePopup: () => void;
+    /** Open popup */
+    openPopup: () => void;
+    /** Set position programmatically */
+    setPosition: (position: Position) => void;
+    /** Inline styles for button container */
+    buttonStyles: React.CSSProperties;
+    /** Inline styles for popup container */
+    popupStyles: React.CSSProperties;
+    /** Props to spread on button for drag handling */
+    buttonProps: {
+        onPointerDown: (e: React.PointerEvent) => void;
+        onClick: (e: React.MouseEvent) => void;
+        style: React.CSSProperties;
+    };
+}
+/**
+ * Internal viewport bounds
+ */
+export interface ViewportBounds {
+    width: number;
+    height: number;
+}
+/**
+ * Internal element dimensions
+ */
+export interface ElementDimensions {
+    width: number;
+    height: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/useEdgeDock.d.ts

@@ -0,0 +1,6 @@
+import type { EdgeDockConfig, UseEdgeDockReturn } from './types';
+/**
+ * Main hook for edge dock functionality
+ */
+export declare function useEdgeDock(config?: EdgeDockConfig): UseEdgeDockReturn;
+//# sourceMappingURL=useEdgeDock.d.ts.map

package/dist/useEdgeDock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEdgeDock.d.ts","sourceRoot":"","sources":["../src/useEdgeDock.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EAId,iBAAiB,EAGlB,MAAM,SAAS,CAAC;AA4IjB;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,GAAE,cAAmB,GAAG,iBAAiB,CAiT1E"}

package/dist/useEdgeDock.js

@@ -0,0 +1,356 @@
+import { useRef, useState, useCallback, useEffect } from 'react';
+/**
+ * Calculate which edge is closest to the given position
+ */
+function getClosestEdge(pos, viewport) {
+    const distanceToLeft = pos.x;
+    const distanceToRight = viewport.width - pos.x;
+    const distanceToTop = pos.y;
+    const distanceToBottom = viewport.height - pos.y;
+    const minDistance = Math.min(distanceToLeft, distanceToRight, distanceToTop, distanceToBottom);
+    if (minDistance === distanceToLeft)
+        return 'left';
+    if (minDistance === distanceToRight)
+        return 'right';
+    if (minDistance === distanceToTop)
+        return 'top';
+    return 'bottom';
+}
+/**
+ * Snap position to edge based on dock mode
+ */
+function snapToEdge(pos, edge, viewport, buttonDimensions) {
+    const halfWidth = buttonDimensions.width / 2;
+    const halfHeight = buttonDimensions.height / 2;
+    switch (edge) {
+        case 'left':
+            return {
+                x: halfWidth,
+                y: Math.max(halfHeight, Math.min(viewport.height - halfHeight, pos.y)),
+            };
+        case 'right':
+            return {
+                x: viewport.width - halfWidth,
+                y: Math.max(halfHeight, Math.min(viewport.height - halfHeight, pos.y)),
+            };
+        case 'top':
+            return {
+                x: Math.max(halfWidth, Math.min(viewport.width - halfWidth, pos.x)),
+                y: halfHeight,
+            };
+        case 'bottom':
+            return {
+                x: Math.max(halfWidth, Math.min(viewport.width - halfWidth, pos.x)),
+                y: viewport.height - halfHeight,
+            };
+    }
+}
+/**
+ * Constrain position within viewport bounds
+ */
+function constrainToViewport(pos, viewport, buttonDimensions) {
+    const halfWidth = buttonDimensions.width / 2;
+    const halfHeight = buttonDimensions.height / 2;
+    return {
+        x: Math.max(halfWidth, Math.min(viewport.width - halfWidth, pos.x)),
+        y: Math.max(halfHeight, Math.min(viewport.height - halfHeight, pos.y)),
+    };
+}
+/**
+ * Calculate popup position based on button position
+ */
+function calculatePopupPosition(buttonPos, buttonDimensions, popupDimensions, viewport, gap) {
+    const halfButtonWidth = buttonDimensions.width / 2;
+    const halfButtonHeight = buttonDimensions.height / 2;
+    // Determine optimal placement
+    const spaceRight = viewport.width - (buttonPos.x + halfButtonWidth);
+    const spaceLeft = buttonPos.x - halfButtonWidth;
+    const spaceBottom = viewport.height - (buttonPos.y + halfButtonHeight);
+    const spaceTop = buttonPos.y - halfButtonHeight;
+    let x = buttonPos.x;
+    let y = buttonPos.y;
+    let origin = 'center';
+    // Horizontal positioning
+    if (spaceRight >= popupDimensions.width + gap) {
+        // Open to the right
+        x = buttonPos.x + halfButtonWidth + gap;
+        origin = 'left';
+    }
+    else if (spaceLeft >= popupDimensions.width + gap) {
+        // Open to the left
+        x = buttonPos.x - halfButtonWidth - gap - popupDimensions.width;
+        origin = 'right';
+    }
+    else {
+        // Center horizontally
+        x = Math.max(0, Math.min(viewport.width - popupDimensions.width, buttonPos.x - popupDimensions.width / 2));
+    }
+    // Vertical positioning
+    if (spaceBottom >= popupDimensions.height + gap) {
+        // Open downward
+        y = buttonPos.y + halfButtonHeight + gap;
+        origin = origin === 'left' || origin === 'right' ? `${origin} top` : 'top';
+    }
+    else if (spaceTop >= popupDimensions.height + gap) {
+        // Open upward
+        y = buttonPos.y - halfButtonHeight - gap - popupDimensions.height;
+        origin = origin === 'left' || origin === 'right' ? `${origin} bottom` : 'bottom';
+    }
+    else {
+        // Center vertically
+        y = Math.max(0, Math.min(viewport.height - popupDimensions.height, buttonPos.y - popupDimensions.height / 2));
+    }
+    return {
+        position: { x, y },
+        origin,
+    };
+}
+/**
+ * Main hook for edge dock functionality
+ */
+export function useEdgeDock(config = {}) {
+    const { dockMode = 'auto', dockEdge, position: controlledPosition, animation = true, popupGap = 12, zIndex = 9999, onDockChange, isPopupOpen: controlledPopupOpen, onPopupChange, } = config;
+    const buttonRef = useRef(null);
+    const popupRef = useRef(null);
+    // Internal state
+    const [position, setPositionInternal] = useState(controlledPosition || { x: window.innerWidth - 60, y: window.innerHeight - 60 });
+    const [dockedEdge, setDockedEdge] = useState(null);
+    const [isDragging, setIsDragging] = useState(false);
+    const [isPopupOpenInternal, setIsPopupOpenInternal] = useState(false);
+    const [isAnimating, setIsAnimating] = useState(false);
+    const [popupPosition, setPopupPosition] = useState({ x: 0, y: 0 });
+    const [popupOrigin, setPopupOrigin] = useState('center');
+    // Drag state
+    const dragStateRef = useRef({
+        isDragging: false,
+        startX: 0,
+        startY: 0,
+        startPosX: 0,
+        startPosY: 0,
+        hasMoved: false,
+    });
+    const isPopupOpen = controlledPopupOpen ?? isPopupOpenInternal;
+    // Get current state
+    const state = {
+        position,
+        dockedEdge,
+        isDragging,
+        isPopupOpen,
+    };
+    // Update controlled position
+    useEffect(() => {
+        if (controlledPosition) {
+            setPositionInternal(controlledPosition);
+        }
+    }, [controlledPosition]);
+    // Calculate popup position when it opens or button moves
+    useEffect(() => {
+        if (isPopupOpen && buttonRef.current && popupRef.current) {
+            const buttonRect = buttonRef.current.getBoundingClientRect();
+            const popupRect = popupRef.current.getBoundingClientRect();
+            const result = calculatePopupPosition(position, { width: buttonRect.width, height: buttonRect.height }, { width: popupRect.width, height: popupRect.height }, { width: window.innerWidth, height: window.innerHeight }, popupGap);
+            setPopupPosition(result.position);
+            setPopupOrigin(result.origin);
+        }
+    }, [isPopupOpen, position, popupGap]);
+    // Notify state changes
+    useEffect(() => {
+        if (onDockChange) {
+            onDockChange(state);
+        }
+    }, [position, dockedEdge, isDragging, isPopupOpen]);
+    // Set position with constraints
+    const setPosition = useCallback((newPos) => {
+        if (!buttonRef.current)
+            return;
+        const buttonRect = buttonRef.current.getBoundingClientRect();
+        const viewport = { width: window.innerWidth, height: window.innerHeight };
+        const buttonDimensions = { width: buttonRect.width, height: buttonRect.height };
+        let finalPos = constrainToViewport(newPos, viewport, buttonDimensions);
+        if (dockMode === 'auto') {
+            const edge = getClosestEdge(finalPos, viewport);
+            finalPos = snapToEdge(finalPos, edge, viewport, buttonDimensions);
+            setDockedEdge(edge);
+        }
+        else if (dockMode === 'manual' && dockEdge) {
+            finalPos = snapToEdge(finalPos, dockEdge, viewport, buttonDimensions);
+            setDockedEdge(dockEdge);
+        }
+        else {
+            setDockedEdge(null);
+        }
+        setPositionInternal(finalPos);
+    }, [dockMode, dockEdge]);
+    // Toggle popup
+    const togglePopup = useCallback(() => {
+        const newState = !isPopupOpen;
+        if (controlledPopupOpen === undefined) {
+            setIsPopupOpenInternal(newState);
+        }
+        onPopupChange?.(newState);
+    }, [isPopupOpen, controlledPopupOpen, onPopupChange]);
+    const closePopup = useCallback(() => {
+        if (controlledPopupOpen === undefined) {
+            setIsPopupOpenInternal(false);
+        }
+        onPopupChange?.(false);
+    }, [controlledPopupOpen, onPopupChange]);
+    const openPopup = useCallback(() => {
+        if (controlledPopupOpen === undefined) {
+            setIsPopupOpenInternal(true);
+        }
+        onPopupChange?.(true);
+    }, [controlledPopupOpen, onPopupChange]);
+    // Pointer down handler
+    const handlePointerDown = useCallback((e) => {
+        if (!buttonRef.current)
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        const target = e.currentTarget;
+        target.setPointerCapture(e.pointerId);
+        dragStateRef.current = {
+            isDragging: true,
+            startX: e.clientX,
+            startY: e.clientY,
+            startPosX: position.x,
+            startPosY: position.y,
+            hasMoved: false,
+        };
+        setIsDragging(true);
+        setIsAnimating(false);
+        // Close popup when starting to drag
+        if (isPopupOpen) {
+            closePopup();
+        }
+    }, [position, isPopupOpen, closePopup]);
+    // Pointer move handler
+    useEffect(() => {
+        const handlePointerMove = (e) => {
+            if (!dragStateRef.current.isDragging || !buttonRef.current)
+                return;
+            const deltaX = e.clientX - dragStateRef.current.startX;
+            const deltaY = e.clientY - dragStateRef.current.startY;
+            // Mark as moved if dragged more than 5px
+            if (Math.abs(deltaX) > 5 || Math.abs(deltaY) > 5) {
+                dragStateRef.current.hasMoved = true;
+            }
+            const newPos = {
+                x: dragStateRef.current.startPosX + deltaX,
+                y: dragStateRef.current.startPosY + deltaY,
+            };
+            const buttonRect = buttonRef.current.getBoundingClientRect();
+            const viewport = { width: window.innerWidth, height: window.innerHeight };
+            const buttonDimensions = { width: buttonRect.width, height: buttonRect.height };
+            // During drag, only constrain to viewport (no snapping)
+            const constrainedPos = constrainToViewport(newPos, viewport, buttonDimensions);
+            setPositionInternal(constrainedPos);
+        };
+        const handlePointerUp = () => {
+            if (!dragStateRef.current.isDragging)
+                return;
+            dragStateRef.current.isDragging = false;
+            setIsDragging(false);
+            // Apply snapping after drag ends
+            if (animation) {
+                setIsAnimating(true);
+            }
+            // Snap to edge if needed
+            if (buttonRef.current) {
+                const buttonRect = buttonRef.current.getBoundingClientRect();
+                const viewport = { width: window.innerWidth, height: window.innerHeight };
+                const buttonDimensions = { width: buttonRect.width, height: buttonRect.height };
+                let finalPos = position;
+                if (dockMode === 'auto') {
+                    const edge = getClosestEdge(position, viewport);
+                    finalPos = snapToEdge(position, edge, viewport, buttonDimensions);
+                    setDockedEdge(edge);
+                }
+                else if (dockMode === 'manual' && dockEdge) {
+                    finalPos = snapToEdge(position, dockEdge, viewport, buttonDimensions);
+                    setDockedEdge(dockEdge);
+                }
+                setPositionInternal(finalPos);
+            }
+        };
+        document.addEventListener('pointermove', handlePointerMove);
+        document.addEventListener('pointerup', handlePointerUp);
+        return () => {
+            document.removeEventListener('pointermove', handlePointerMove);
+            document.removeEventListener('pointerup', handlePointerUp);
+        };
+    }, [position, dockMode, dockEdge, animation]);
+    // Click handler (only trigger if not dragged)
+    const handleClick = useCallback((e) => {
+        if (dragStateRef.current.hasMoved) {
+            e.preventDefault();
+            e.stopPropagation();
+            return;
+        }
+        togglePopup();
+    }, [togglePopup]);
+    // Handle window resize
+    useEffect(() => {
+        const handleResize = () => {
+            if (buttonRef.current) {
+                const buttonRect = buttonRef.current.getBoundingClientRect();
+                const viewport = { width: window.innerWidth, height: window.innerHeight };
+                const buttonDimensions = { width: buttonRect.width, height: buttonRect.height };
+                let newPos = constrainToViewport(position, viewport, buttonDimensions);
+                if (dockMode === 'auto') {
+                    const edge = getClosestEdge(newPos, viewport);
+                    newPos = snapToEdge(newPos, edge, viewport, buttonDimensions);
+                    setDockedEdge(edge);
+                }
+                else if (dockMode === 'manual' && dockEdge) {
+                    newPos = snapToEdge(newPos, dockEdge, viewport, buttonDimensions);
+                }
+                setPositionInternal(newPos);
+            }
+        };
+        window.addEventListener('resize', handleResize);
+        return () => window.removeEventListener('resize', handleResize);
+    }, [position, dockMode, dockEdge]);
+    // Button styles
+    const buttonStyles = {
+        position: 'fixed',
+        left: 0,
+        top: 0,
+        transform: `translate3d(${position.x}px, ${position.y}px, 0) translate(-50%, -50%)`,
+        transition: isAnimating && animation ? 'transform 0.3s cubic-bezier(0.34, 1.56, 0.64, 1)' : 'none',
+        cursor: isDragging ? 'grabbing' : 'grab',
+        touchAction: 'none',
+        userSelect: 'none',
+        zIndex,
+        willChange: isDragging ? 'transform' : 'auto',
+    };
+    // Popup styles
+    const popupStyles = {
+        position: 'fixed',
+        left: popupPosition.x,
+        top: popupPosition.y,
+        zIndex: zIndex + 1,
+        opacity: isPopupOpen ? 1 : 0,
+        pointerEvents: isPopupOpen ? 'auto' : 'none',
+        transformOrigin: popupOrigin,
+        transform: isPopupOpen ? 'scale(1)' : 'scale(0.95)',
+        transition: animation ? 'opacity 0.2s ease, transform 0.2s cubic-bezier(0.34, 1.56, 0.64, 1)' : 'none',
+    };
+    const buttonProps = {
+        onPointerDown: handlePointerDown,
+        onClick: handleClick,
+        style: { userSelect: 'none', touchAction: 'none' },
+    };
+    return {
+        state,
+        buttonRef,
+        popupRef,
+        togglePopup,
+        closePopup,
+        openPopup,
+        setPosition,
+        buttonStyles,
+        popupStyles,
+        buttonProps,
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "react-edge-dock",
+  "version": "1.0.0",
+  "description": "A zero-dependency React TypeScript library for customizable draggable edge-docked floating buttons with popup support",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/react-edge-dock.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/react-edge-dock/issues"
+  },
+  "homepage": "https://github.com/yourusername/react-edge-dock#readme",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "react",
+    "typescript",
+    "draggable",
+    "floating-button",
+    "edge-dock",
+    "popup",
+    "overlay",
+    "headless"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "typescript": "^5.3.0"
+  }
+}