npm - @beforegolive/floating-ball - Versions diffs - 0.1.0 - Mend

@beforegolive/floating-ball 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,44 @@
+# @beforegolive/floating-ball
+React 悬浮球组件，预编译样式，零依赖配置。
+## 安装
+```bash
+npm install @beforegolive/floating-ball
+```
+## 使用
+```tsx
+import FloatingBall from '@beforegolive/floating-ball';
+function App() {
+  return (
+    <>
+      <FloatingBall
+        version="1.0.0"
+        buildTime="2026-04-06"
+        theme="light"
+      />
+    </>
+  );
+}
+```
+## API
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `version` | `string` | 必填 | 版本号 |
+| `buildTime` | `string` | 必填 | 构建时间 |
+| `theme` | `'light' \| 'dark'` | `'light'` | 主题色 |
+| `position` | `{ x: number, y: number }` | 右下角 | 初始位置 |
+| `menuItems` | `MenuItem[]` | 默认菜单 | 自定义菜单项 |
+| `storageKey` | `string` | `'floating-ball-position'` | localStorage key |
+## peerDependencies
+- react >= 18.0.0
+- react-dom >= 18.0.0
+- react-router-dom >= 6.0.0

package/index.html ADDED Viewed

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Floating Ball Demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/demo.tsx"></script>
+  </body>
+</html>

package/package.json ADDED Viewed

@@ -0,0 +1,36 @@
+{
+  "name": "@beforegolive/floating-ball",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "demo": "vite --open",
+    "build": "vite build && cp dist/src/index.d.ts dist/index.d.ts",
+    "preview": "vite preview"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "react-router-dom": ">=6.0.0"
+  },
+  "dependencies": {
+    "goober": "^2.1.18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@vitejs/plugin-react": "^4.4.1",
+    "typescript": "^5.9.3",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}

package/src/FloatingBall.tsx ADDED Viewed

@@ -0,0 +1,357 @@
+import { useState, useRef, useEffect, useCallback } from "react";
+import { css, setup } from "goober";
+import type { FloatingBallProps, MenuItem, Position, VersionInfo } from "../types";
+// 初始化 goober
+setup(css);
+// 样式定义
+const ballStyle = css`
+  position: fixed;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  cursor: grab;
+  user-select: none;
+  color: white;
+  font-size: 10px;
+  border: 2px solid rgba(255, 255, 255, 0.9);
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
+  opacity: 0.85;
+  &:active {
+    cursor: grabbing;
+  }
+`;
+const menuOverlayStyle = css`
+  position: fixed;
+  inset: 0;
+  z-index: 40;
+`;
+const menuStyle = css`
+  position: fixed;
+  z-index: 50;
+  background-color: #ffffff;
+  border-radius: 8px;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
+  border: 1px solid rgba(0, 0, 0, 0.1);
+  padding: 8px 0;
+  min-width: 144px;
+`;
+const menuItemStyle = css`
+  width: 100%;
+  padding: 8px 16px;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  font-size: 14px;
+  color: #333;
+  cursor: pointer;
+  background: none;
+  border: none;
+  text-align: left;
+  &:hover {
+    background-color: rgba(0, 0, 0, 0.05);
+  }
+`;
+interface InternalProps extends FloatingBallProps {
+  versionInfo?: VersionInfo;
+}
+const DEFAULT_WIDTH = 80;
+const DEFAULT_HEIGHT = 32;
+const DEFAULT_BORDER_RADIUS = 12;
+const FloatingBall = ({
+  extraMenuItems,
+  onClick,
+  storageKey = "floating-ball-position",
+  defaultPosition = { x: 16, y: 16 },
+  width = DEFAULT_WIDTH,
+  height = DEFAULT_HEIGHT,
+  borderRadius = DEFAULT_BORDER_RADIUS,
+  bgColor = "rgb(34, 139, 34)",
+  className = "",
+  zIndex = 2999,
+  versionInfo,
+}: InternalProps) => {
+  const [position, setPosition] = useState<Position>(() => {
+    const saved = localStorage.getItem(storageKey);
+    if (saved) {
+      try {
+        return JSON.parse(saved);
+      } catch {
+        return defaultPosition;
+      }
+    }
+    return defaultPosition;
+  });
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+  const isDraggingRef = useRef(false);
+  const dragStartRef = useRef({ x: 0, y: 0 });
+  const positionRef = useRef(position);
+  const clickTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const touchHandledRef = useRef(false);
+  const doubleClickFiredRef = useRef(false);
+  const ballRef = useRef<HTMLDivElement>(null);
+  const lastTapRef = useRef<{ time: number; x: number; y: number } | null>(null);
+  useEffect(() => {
+    positionRef.current = position;
+  }, [position]);
+  const handleDragStart = useCallback((clientX: number, clientY: number) => {
+    isDraggingRef.current = false;
+    dragStartRef.current = { x: clientX, y: clientY };
+  }, []);
+  const handleDragMove = useCallback(
+    (clientX: number, clientY: number) => {
+      const dx = clientX - dragStartRef.current.x;
+      const dy = clientY - dragStartRef.current.y;
+      if (Math.abs(dx) > 5 || Math.abs(dy) > 5) {
+        isDraggingRef.current = true;
+      }
+      if (isDraggingRef.current) {
+        const newX = Math.max(0, Math.min(window.innerWidth - width, positionRef.current.x + dx));
+        const newY = Math.max(0, Math.min(window.innerHeight - height, positionRef.current.y + dy));
+        setPosition({ x: newX, y: newY });
+        dragStartRef.current = { x: clientX, y: clientY };
+      }
+    },
+    [width, height]
+  );
+  const handleDragEnd = useCallback(() => {
+    if (isDraggingRef.current) {
+      localStorage.setItem(storageKey, JSON.stringify(positionRef.current));
+    }
+  }, [storageKey]);
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      if (e.button !== 0) return;
+      handleDragStart(e.clientX, e.clientY);
+      const handleMouseMove = (moveEvent: MouseEvent) => {
+        handleDragMove(moveEvent.clientX, moveEvent.clientY);
+      };
+      const handleMouseUp = () => {
+        handleDragEnd();
+        isDraggingRef.current = false;
+        document.removeEventListener("mousemove", handleMouseMove);
+        document.removeEventListener("mouseup", handleMouseUp);
+      };
+      document.addEventListener("mousemove", handleMouseMove);
+      document.addEventListener("mouseup", handleMouseUp);
+    },
+    [handleDragStart, handleDragMove, handleDragEnd]
+  );
+  const handleClick = useCallback(() => {
+    if (touchHandledRef.current) {
+      return;
+    }
+    if (onClick === false) return;
+    if (extraMenuItems && extraMenuItems.length > 0) {
+      if (clickTimerRef.current) {
+        clearTimeout(clickTimerRef.current);
+      }
+      clickTimerRef.current = setTimeout(() => {
+        clickTimerRef.current = null;
+        if (!isDraggingRef.current && !doubleClickFiredRef.current) {
+          onClick ? onClick() : window.location.reload();
+        }
+      }, 300);
+    } else {
+      if (!isDraggingRef.current) {
+        onClick ? onClick() : window.location.reload();
+      }
+    }
+  }, [onClick, extraMenuItems]);
+  const handleDoubleClick = useCallback(() => {
+    if (clickTimerRef.current) {
+      clearTimeout(clickTimerRef.current);
+      clickTimerRef.current = null;
+    }
+    if (!isDraggingRef.current && extraMenuItems && extraMenuItems.length > 0) {
+      setIsMenuOpen(true);
+    }
+    doubleClickFiredRef.current = true;
+    setTimeout(() => {
+      doubleClickFiredRef.current = false;
+    }, 400);
+  }, [extraMenuItems]);
+  const handleMouseDownBall = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation();
+      handleMouseDown(e);
+    },
+    [handleMouseDown]
+  );
+  useEffect(() => {
+    const ball = ballRef.current;
+    if (!ball) return;
+    const onTouchStart = (e: TouchEvent) => {
+      if (e.touches.length !== 1) return;
+      handleDragStart(e.touches[0].clientX, e.touches[0].clientY);
+    };
+    const onTouchMove = (e: TouchEvent) => {
+      if (e.touches.length !== 1) return;
+      handleDragMove(e.touches[0].clientX, e.touches[0].clientY);
+      if (isDraggingRef.current) {
+        e.preventDefault();
+      }
+    };
+    const onTouchEnd = (_e: TouchEvent) => {
+      handleDragEnd();
+      if (!isDraggingRef.current) {
+        const now = Date.now();
+        const lastTap = lastTapRef.current;
+        const isMobileDoubleTap =
+          lastTap &&
+          now - lastTap.time < 300 &&
+          Math.abs(position.x - lastTap.x) < 10 &&
+          Math.abs(position.y - lastTap.y) < 10;
+        if (isMobileDoubleTap) {
+          lastTapRef.current = null;
+          if (clickTimerRef.current) {
+            clearTimeout(clickTimerRef.current);
+            clickTimerRef.current = null;
+          }
+          if (extraMenuItems && extraMenuItems.length > 0) {
+            setIsMenuOpen(true);
+          }
+          doubleClickFiredRef.current = true;
+          setTimeout(() => {
+            doubleClickFiredRef.current = false;
+          }, 400);
+          touchHandledRef.current = true;
+          return;
+        }
+        lastTapRef.current = { time: now, x: position.x, y: position.y };
+        if (clickTimerRef.current) {
+          clearTimeout(clickTimerRef.current);
+        }
+        if (extraMenuItems && extraMenuItems.length > 0) {
+          clickTimerRef.current = setTimeout(() => {
+            clickTimerRef.current = null;
+            lastTapRef.current = null;
+            if (!doubleClickFiredRef.current) {
+              onClick ? onClick() : window.location.reload();
+            }
+          }, 300);
+        } else {
+          onClick ? onClick() : window.location.reload();
+        }
+        touchHandledRef.current = true;
+      }
+    };
+    const onDblClick = () => {
+      handleDoubleClick();
+    };
+    ball.addEventListener("touchstart", onTouchStart, { passive: false });
+    ball.addEventListener("touchmove", onTouchMove, { passive: false });
+    ball.addEventListener("touchend", onTouchEnd);
+    ball.addEventListener("dblclick", onDblClick);
+    return () => {
+      ball.removeEventListener("touchstart", onTouchStart);
+      ball.removeEventListener("touchmove", onTouchMove);
+      ball.removeEventListener("touchend", onTouchEnd);
+      ball.removeEventListener("dblclick", onDblClick);
+    };
+  }, [handleDragStart, handleDragMove, handleDragEnd, handleDoubleClick]);
+  const defaultMenuItems: MenuItem[] = [
+    { label: "刷新", icon: "🔄", action: () => window.location.reload() },
+    { label: "回到首页", icon: "🏠", action: () => { window.location.href = "/"; } },
+  ];
+  const menuItems: MenuItem[] = [...defaultMenuItems, ...(extraMenuItems || [])];
+  const closeMenu = useCallback(() => {
+    setIsMenuOpen(false);
+  }, []);
+  return (
+    <>
+      <div
+        ref={ballRef}
+        className={ballStyle}
+        style={{
+          left: position.x,
+          top: position.y,
+          width,
+          height,
+          borderRadius,
+          zIndex,
+          backgroundColor: bgColor,
+        }}
+        onMouseDown={handleMouseDownBall}
+        onClick={handleClick}
+      >
+        {versionInfo?.buildTime && (
+          <span style={{ opacity: 0.8, lineHeight: 1.1, textAlign: "center", margin: 0 }}>
+            {versionInfo.buildTime}
+          </span>
+        )}
+        {versionInfo?.version && (
+          <span style={{ opacity: 0.8, lineHeight: 1.1, textAlign: "center", margin: 0, fontWeight: "bold" }}>
+            v{versionInfo.version}
+          </span>
+        )}
+      </div>
+      {isMenuOpen && menuItems.length > 0 && (
+        <>
+          <div className={menuOverlayStyle} onClick={closeMenu} />
+          <div
+            className={menuStyle}
+            style={{
+              left: Math.max(16, Math.min(position.x, window.innerWidth - 160)),
+              top: position.y + height + 8,
+            }}
+          >
+            {menuItems.map((item, index) => (
+              <button
+                key={`${item.label}-${index}`}
+                className={menuItemStyle}
+                onClick={() => {
+                  setIsMenuOpen(false);
+                  item.action();
+                }}
+              >
+                {item.icon && <span>{item.icon}</span>}
+                <span>{item.label}</span>
+              </button>
+            ))}
+          </div>
+        </>
+      )}
+    </>
+  );
+};
+export default FloatingBall;
+export type { FloatingBallProps, MenuItem, Position, VersionInfo };

package/src/demo.tsx ADDED Viewed

@@ -0,0 +1,64 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { BrowserRouter, useNavigate } from 'react-router-dom';
+import FloatingBall from './FloatingBall';
+const VERSION = '1.0.0';
+const now = new Date();
+const BUILD_TIME = `${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}(${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')})`;
+function DemoApp() {
+  const navigate = useNavigate();
+  const extraMenuItems = [
+    {
+      label: '打开笔记页面',
+      icon: '📝',
+      action: () => {
+        navigate('/notes');
+      },
+    },
+  ];
+  return (
+    <div style={{ padding: '20px', fontFamily: 'system-ui' }}>
+      <h1>Floating Ball Demo</h1>
+      <p>点击悬浮球：刷新页面</p>
+      <p>双击悬浮球：打开菜单</p>
+      <p>拖拽悬浮球：移动位置</p>
+      <div style={{ marginTop: '100px' }}>
+        <h2>页面内容</h2>
+        <p>这是演示页面，用于测试悬浮球组件。</p>
+      </div>
+      <FloatingBall
+        extraMenuItems={extraMenuItems}
+        storageKey="floating-ball-position"
+        defaultPosition={{ x: 16, y: 16 }}
+        width={80}
+        height={32}
+        borderRadius={12}
+        bgColor="rgb(34, 139, 34)"
+        versionInfo={{
+          version: VERSION,
+          buildTime: BUILD_TIME,
+        }}
+      />
+    </div>
+  );
+}
+function App() {
+  return (
+    <BrowserRouter>
+      <DemoApp />
+    </BrowserRouter>
+  );
+}
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

package/src/index.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export { default } from './FloatingBall';
2	+ export type { FloatingBallProps, MenuItem, Position, VersionInfo } from '../types';

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "declaration": true,
+    "declarationDir": "./dist",
+    "noEmit": false
+  },
+  "include": ["src", "types"]
+}

package/types/index.ts ADDED Viewed

@@ -0,0 +1,44 @@
+export interface MenuItem {
+  /** 显示的标签 */
+  label: string;
+  /** 图标（emoji 或 HTML） */
+  icon?: string;
+  /** 点击后的行为 */
+  action: () => void;
+}
+export interface FloatingBallProps {
+  /** 附加菜单项（常驻项：刷新、回到首页） */
+  extraMenuItems?: MenuItem[];
+  /** 刷新菜单项的点击行为 */
+  onRefresh?: () => void;
+  /** 回到首页菜单项的点击行为 */
+  onGoHome?: () => void;
+  /** 单击行为（默认刷新页面），设为 false 禁用单击 */
+  onClick?: (() => void) | false;
+  /** localStorage 存储位置持久化的 key */
+  storageKey?: string;
+  /** 默认位置 */
+  defaultPosition?: Position;
+  /** 悬浮球尺寸 */
+  width?: number;
+  height?: number;
+  /** 圆角 */
+  borderRadius?: number;
+  /** 背景色，默认蓝色 */
+  bgColor?: string;
+  /** 样式类名 */
+  className?: string;
+  /** 层级 */
+  zIndex?: number;
+}
+export interface Position {
+  x: number;
+  y: number;
+}
+export interface VersionInfo {
+  version?: string;
+  buildTime?: string;
+}

package/vite.config.ts ADDED Viewed

@@ -0,0 +1,31 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import dts from 'vite-plugin-dts'
+import { resolve } from 'path'
+export default defineConfig({
+  plugins: [react(), dts({
+    include: 'src/index.ts',
+  })],
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.ts'),
+      name: 'FloatingBall',
+      formats: ['es'],
+      fileName: 'index',
+    },
+    rollupOptions: {
+      external: ['react', 'react-dom', 'react-router-dom'],
+      output: {
+        globals: {
+          react: 'React',
+          'react-dom': 'ReactDOM',
+          'react-router-dom': 'ReactRouterDOM',
+        },
+      },
+    },
+  },
+  server: {
+    open: true,
+  },
+})