@hardanonymous/marquee-selector 0.0.1

package/docs/README.md

@@ -0,0 +1,621 @@
+# MarqueeSelector 框選功能文檔
+
+## 概述
+
+`MarqueeSelector` 是一個框架無關的 JavaScript/TypeScript 框選工具，允許使用者通過滑鼠拖曳選取頁面上的元素。它提供了高度的靈活性和可定制性，支援多個目標配置、文字選取保護、拖拽元素保護等功能。
+
+## 特性
+
+✅ **框架無關**：純 Vanilla JavaScript 實現，可在任何前端框架中使用  
+✅ **多目標支援**：可同時追蹤多組不同的選取目標，各有獨立的回調  
+✅ **智能保護機制**：
+  - 自動保護可拖拽元素（`draggable="true"`）
+  - 保護文字選取區域（input、textarea、contenteditable 等）
+✅ **完整生命週期**：提供 `onSelectionStart`、`onSelectionChange`、`onSelectionEnd`、`onClearClick` 回調  
+✅ **精確碰撞檢測**：支援滾動容器，使用 client 座標進行精確的碰撞檢測  
+✅ **記憶體優化**：使用 WeakMap 快取選取狀態，避免記憶體洩漏  
+✅ **CSS 可定制**：通過 CSS 變數輕鬆定制外觀
+
+## 安裝
+
+將 `MarqueeSelector.ts` 和 `marquee-selector.css` 放入專案中：
+
+```typescript
+import { MarqueeSelector } from '@/utils/MarqueeSelector';
+import '@/styles/marquee-selector.css';
+```
+
+## 基本使用
+
+### 1. 初始化
+
+```typescript
+const marquee = new MarqueeSelector({
+  container: document.body, // 或 '.container' 選擇器
+  allowTextSelectionOn: ['p', '.text-content'] // 可選：額外允許文字選取的元素
+});
+```
+
+### 2. 添加目標配置
+
+```typescript
+marquee.addTarget({
+  selector: '.selectable-item', // CSS 選擇器或 HTMLElement
+  
+  onSelectionStart: (targetElement) => {
+    console.log('開始框選:', targetElement);
+  },
+  
+  onSelectionChange: (selectedElements) => {
+    console.log('選取變化:', selectedElements);
+    // 更新 UI 狀態
+    selectedElements.forEach(el => el.classList.add('selected'));
+  },
+  
+  onSelectionEnd: (selectedElements) => {
+    console.log('框選結束:', selectedElements);
+  },
+  
+  onClearClick: (selectedElements) => {
+    console.log('點擊空白處，清除選取:', selectedElements);
+    // 清除選取狀態
+    selectedElements.forEach(el => el.classList.remove('selected'));
+  }
+});
+```
+
+### 3. 啟用框選
+
+```typescript
+marquee.enable();
+```
+
+### 4. 清理資源
+
+```typescript
+marquee.destroy();
+```
+
+## API 參考
+
+### MarqueeSelectorOptions
+
+初始化選項配置：
+
+```typescript
+interface MarqueeSelectorOptions {
+  /**
+   * 容器元素的實例或選擇器字串
+   * 這是滑鼠事件監聽的目標，也是計算相對座標的基準
+   */
+  container: HTMLElement | string;
+
+  /**
+   * 允許文字選取的元素選擇器（這些元素上不會啟動框選）
+   * 預設已包含: input, textarea, [contenteditable], pre, code
+   * @example ['p', '.text-content', '[contenteditable]']
+   */
+  allowTextSelectionOn?: string[];
+}
+```
+
+### MarqueeTargetConfig
+
+目標配置：
+
+```typescript
+interface MarqueeTargetConfig {
+  /**
+   * 可以是單一或多個 CSS 選擇器，或直接傳入 HTMLElement（或其陣列）
+   * @example '.item'
+   * @example ['.item-a', '.item-b']
+   * @example document.querySelector('.item')
+   * @example [element1, element2]
+   */
+  selector: string | string[] | HTMLElement | HTMLElement[];
+
+  /**
+   * 框選開始時的回調（首次移動滑鼠時觸發）
+   * @param targetElement 滑鼠按下的目標元素
+   */
+  onSelectionStart?: (targetElement: HTMLElement) => void;
+
+  /**
+   * 選取變化時的回調（框選過程中持續觸發）
+   * @param selectedElements 當前選取的元素陣列
+   */
+  onSelectionChange?: (selectedElements: HTMLElement[]) => void;
+
+  /**
+   * 框選結束時的回調（滑鼠放開時觸發）
+   * @param selectedElements 最終選取的元素陣列
+   */
+  onSelectionEnd?: (selectedElements: HTMLElement[]) => void;
+
+  /**
+   * 點擊空白處時的回調（框選結束後，點擊非選取元素時觸發）
+   * 使用者可在此回調中決定是否清除選取、執行其他操作等
+   * @param selectedElements 當前選取的元素陣列
+   */
+  onClearClick?: (selectedElements: HTMLElement[]) => void;
+}
+```
+
+### 公開方法
+
+```typescript
+class MarqueeSelector {
+  /**
+   * 啟用框選功能
+   */
+  enable(): void;
+
+  /**
+   * 停用框選功能
+   */
+  disable(): void;
+
+  /**
+   * 檢查是否啟用
+   */
+  isEnabled(): boolean;
+
+  /**
+   * 動態新增目標配置
+   */
+  addTarget(config: MarqueeTargetConfig): void;
+
+  /**
+   * 銷毀實例，移除所有事件監聽器
+   */
+  destroy(): void;
+}
+```
+
+## 進階使用
+
+### 多目標配置
+
+可以為不同類型的元素設定不同的選取邏輯：
+
+```typescript
+// 配置 A：拖曳項目
+marquee.addTarget({
+  selector: '.draggable-item',
+  onSelectionChange: (selected) => {
+    selectedItems.value = selected.map(el => el.dataset.id);
+  }
+});
+
+// 配置 B：樹節點
+marquee.addTarget({
+  selector: '.tree-node',
+  onSelectionChange: (selected) => {
+    selectedNodes.value = selected.map(el => el.dataset.nodeId);
+  }
+});
+```
+
+### Vue 3 整合
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue';
+import { MarqueeSelector } from '@/utils/MarqueeSelector';
+import '@/styles/marquee-selector.css';
+
+const containerRef = ref<HTMLElement>();
+const selectedIds = ref<number[]>([]);
+let marquee: MarqueeSelector | null = null;
+
+onMounted(() => {
+  if (containerRef.value) {
+    marquee = new MarqueeSelector({
+      container: containerRef.value
+    });
+
+    marquee.addTarget({
+      selector: '.item',
+      onSelectionChange: (elements) => {
+        selectedIds.value = elements.map(el => 
+          Number(el.getAttribute('data-id'))
+        );
+      },
+      onClearClick: () => {
+        selectedIds.value = [];
+      }
+    });
+
+    marquee.enable();
+  }
+});
+
+onUnmounted(() => {
+  marquee?.destroy();
+});
+</script>
+
+<template>
+  <div ref="containerRef">
+    <div 
+      v-for="item in items" 
+      :key="item.id"
+      :data-id="item.id"
+      class="item"
+      :class="{ selected: selectedIds.includes(item.id) }"
+    >
+      {{ item.name }}
+    </div>
+  </div>
+</template>
+```
+
+### React 整合
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import { MarqueeSelector } from './utils/MarqueeSelector';
+import './styles/marquee-selector.css';
+
+function App() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [selectedIds, setSelectedIds] = useState<number[]>([]);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const marquee = new MarqueeSelector({
+      container: containerRef.current
+    });
+
+    marquee.addTarget({
+      selector: '.item',
+      onSelectionChange: (elements) => {
+        const ids = elements.map(el => 
+          Number(el.getAttribute('data-id'))
+        );
+        setSelectedIds(ids);
+      },
+      onClearClick: () => {
+        setSelectedIds([]);
+      }
+    });
+
+    marquee.enable();
+
+    return () => marquee.destroy();
+  }, []);
+
+  return (
+    <div ref={containerRef}>
+      {items.map(item => (
+        <div
+          key={item.id}
+          data-id={item.id}
+          className={`item ${selectedIds.includes(item.id) ? 'selected' : ''}`}
+        >
+          {item.name}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### 與拖拽功能整合
+
+```vue
+<template>
+  <div ref="containerRef">
+    <div
+      v-for="item in items"
+      :key="item.id"
+      :data-id="item.id"
+      class="item"
+      :class="{ selected: selectedIds.includes(item.id) }"
+      draggable="true"
+      @dragstart="onDragStart($event, item)"
+    >
+      {{ item.name }}
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+// MarqueeSelector 會自動偵測 draggable="true" 的元素
+// 在這些元素上按下滑鼠時，不會啟動框選，而是觸發拖拽
+
+const onDragStart = (event: DragEvent, item: Item) => {
+  // 如果該項目未被選取，則只拖拽自己
+  if (!selectedIds.value.includes(item.id)) {
+    selectedIds.value = [item.id];
+  }
+  
+  // 拖拽所有選取的項目
+  const draggedItems = items.filter(i => 
+    selectedIds.value.includes(i.id)
+  );
+  
+  event.dataTransfer?.setData('text/plain', 
+    JSON.stringify(draggedItems)
+  );
+};
+</script>
+```
+
+## 工作原理
+
+### 1. 事件流程
+
+#### 主要事件流程
+
+```mermaid
+flowchart TD
+    Start([MouseDown 左鍵]) --> CheckPriority{檢查文字選取或拖拽?<br/>isTextSelectionAllowed<br/>或 draggable 元素}
+    CheckPriority -->|是<br/>優先處理| Return[返回，不啟動框選<br/>允許文字選取或拖拽]
+    CheckPriority -->|否<br/>可以框選| Record[記錄起始座標<br/>監聽 mousemove/mouseup<br/>hasStarted = false]
+    Record --> FirstMove{MouseMove<br/>第一次移動?}
+    FirstMove -->|是| SetStarted[hasStarted = true<br/>觸發 onSelectionStart]
+    SetStarted --> UpdateBox[更新框選框位置]
+    FirstMove -->|否| UpdateBox
+    UpdateBox --> Collision[碰撞檢測<br/>AABB Algorithm]
+    Collision --> Changed{選取變化?}
+    Changed -->|是| TriggerChange[觸發 onSelectionChange]
+    Changed -->|否| ContinueMove{繼續移動?}
+    TriggerChange --> ContinueMove
+    ContinueMove -->|是| FirstMove
+    ContinueMove -->|否| MouseUp[MouseUp]
+    MouseUp --> HasStartedCheck{hasStarted?}
+    HasStartedCheck -->|否| End1[結束]
+    HasStartedCheck -->|是| TriggerEnd[觸發 onSelectionEnd]
+    TriggerEnd --> HasClearHandler{有 onClearClick<br/>且有選取?}
+    HasClearHandler -->|否| End2[結束]
+    HasClearHandler -->|是| BindClick[綁定 click 事件]
+    BindClick --> WaitClick[等待使用者點擊]
+    WaitClick --> Click[Click 事件]
+    Click --> IsEmpty{點擊空白處?}
+    IsEmpty -->|是| TriggerClear[觸發 onClearClick<br/>清空快取]
+    IsEmpty -->|否| SkipClear[跳過清除]
+    TriggerClear --> UnbindClick[移除 click 監聽器]
+    SkipClear --> UnbindClick
+    UnbindClick --> End3[結束]
+```
+
+#### 保護機制檢查流程
+
+**主要決策流程（優先級：文字選取 = 拖拽 > 框選）**
+
+```mermaid
+flowchart TD
+    Start([MouseDown 點擊目標]) --> CallCheck[檢查優先級]
+    CallCheck --> TextCheck{isTextSelectionAllowed?}
+    TextCheck -->|是| Return[返回，不啟動框選]
+    TextCheck -->|否| DragCheck{target.draggable 或<br/>最近的 draggable 祖先?}
+    DragCheck -->|是| Return
+    DragCheck -->|否| StartSelection[啟動框選]
+```
+
+**isTextSelectionAllowed 內部判斷邏輯**
+
+```mermaid
+flowchart TD
+    Start([isTextSelectionAllowed<br/>檢查目標元素]) --> MatchSelector{匹配<br/>allowTextSelectionSelectors<br/>選擇器?}
+    MatchSelector -->|否| CheckUserSelect{CSS userSelect<br/>!== 'none'?}
+    MatchSelector -->|是| ReturnTrue1[返回 true]
+    CheckUserSelect -->|否| ReturnFalse[返回 false]
+    CheckUserSelect -->|是| HasTextNode{包含文字節點?}
+    HasTextNode -->|否| ReturnFalse
+    HasTextNode -->|是| ReturnTrue2[返回 true]
+```
+
+#### onClearClick 觸發機制
+
+```mermaid
+flowchart TD
+    Start([框選結束 MouseUp]) --> HasHandler{任何 target<br/>有 onClearClick?}
+    HasHandler -->|否| End1[結束]
+    HasHandler -->|是| HasSelection{任何 target<br/>有選取項目?}
+    HasSelection -->|否| End2[結束]
+    HasSelection -->|是| Bind[setTimeout 綁定<br/>click 事件監聽器]
+    Bind --> Wait[等待點擊...]
+    Wait --> Clicked[Click 事件觸發]
+    Clicked --> ForEach[遍歷每個 target]
+    ForEach --> HasClearClick{target 有<br/>onClearClick?}
+    HasClearClick -->|否| MoreTargets{還有 target?}
+    HasClearClick -->|是| HasItems{target 有<br/>選取項目?}
+    HasItems -->|否| MoreTargets
+    HasItems -->|是| IsClickOnTarget{點擊在<br/>選取範圍內?}
+    IsClickOnTarget -->|是| MoreTargets
+    IsClickOnTarget -->|否| TriggerClear[觸發 onClearClick<br/>清空該 target 快取]
+    TriggerClear --> MoreTargets
+    MoreTargets -->|是| ForEach
+    MoreTargets -->|否| Unbind[移除 click 監聽器]
+    Unbind --> End3[結束]
+```
+
+### 2. 碰撞檢測
+
+使用 `getBoundingClientRect()` 進行精確的 AABB (Axis-Aligned Bounding Box) 碰撞檢測：
+
+```typescript
+const isIntersecting = !(
+  elRect.right < boxClientLeft ||
+  elRect.left > boxClientRight ||
+  elRect.bottom < boxClientTop ||
+  elRect.top > boxClientBottom
+);
+```
+
+### 3. 座標轉換
+
+支援滾動容器，自動處理相對座標與 client 座標的轉換：
+
+```typescript
+// 相對座標 → Client 座標
+const boxClientLeft = relLeft - container.scrollLeft + containerRect.left;
+const boxClientTop = relTop - container.scrollTop + containerRect.top;
+```
+
+### 4. 內建保護機制
+
+#### 文字選取與拖拽保護（平級優先）
+
+```typescript
+// 文字選取和拖拽都優先於框選
+if (this.isTextSelectionAllowed(target) || target.draggable || target.closest('[draggable="true"]')) {
+  return; // 允許文字選取或拖拽，不啟動框選
+}
+```
+
+#### 文字選取保護
+
+```typescript
+// 預設保護的元素
+const defaultTextSelectors = [
+  'input', 
+  'textarea', 
+  '[contenteditable]', 
+  'pre', 
+  'code'
+];
+
+// 檢查是否應該允許文字選取
+private isTextSelectionAllowed(target: HTMLElement): boolean {
+  // 檢查選擇器匹配
+  for (const selector of this.allowTextSelectionSelectors) {
+    if (target.matches(selector) || target.closest(selector)) {
+      return true;
+    }
+  }
+  
+  // 檢查 CSS userSelect 屬性
+  const computedStyle = window.getComputedStyle(target);
+  if (computedStyle.userSelect !== 'none') {
+    // 檢查是否包含文字節點
+    // ...
+  }
+  
+  return false;
+}
+```
+
+## CSS 自定義
+
+`marquee-selector.css` 提供了以下 CSS 變數：
+
+```css
+.marquee-selection-box {
+  --marquee-bg: rgba(0, 123, 255, 0.1);
+  --marquee-border: 1px solid rgba(0, 123, 255, 0.5);
+  
+  position: absolute;
+  background-color: var(--marquee-bg);
+  border: var(--marquee-border);
+  pointer-events: none;
+  z-index: 9999;
+  display: none;
+}
+
+.marquee-selection-box.active {
+  display: block;
+}
+
+.disable-user-select,
+.disable-user-select * {
+  user-select: none !important;
+  -webkit-user-select: none !important;
+  -moz-user-select: none !important;
+  -ms-user-select: none !important;
+}
+```
+
+### 自定義外觀
+
+```css
+/* 在你的 CSS 中覆寫變數 */
+.marquee-selection-box {
+  --marquee-bg: rgba(255, 0, 0, 0.15);
+  --marquee-border: 2px dashed red;
+  border-radius: 4px;
+}
+```
+
+## 效能考量
+
+### 1. WeakMap 快取
+
+使用 `WeakMap` 儲存每個 target 的選取狀態，當 target 配置被垃圾回收時，自動清理快取：
+
+```typescript
+private targetSelectionCache = new WeakMap<MarqueeTargetConfig, HTMLElement[]>();
+```
+
+### 2. 變化檢測
+
+只在選取狀態真正改變時才觸發 `onSelectionChange`：
+
+```typescript
+const targetChanged = 
+  selectedForTarget.length !== lastForTarget.length ||
+  selectedForTarget.some((el, i) => el !== lastForTarget[i]);
+
+if (targetChanged) {
+  // 觸發回調
+}
+```
+
+### 3. 事件委派
+
+使用綁定方法避免重複創建函式：
+
+```typescript
+private _onMouseMove = this.onMouseMove.bind(this);
+private _onMouseUp = this.onMouseUp.bind(this);
+```
+
+## 常見問題
+
+### Q: 如何避免與拖拽功能衝突？
+
+A: `MarqueeSelector` 內建了拖拽元素檢測，會自動跳過 `draggable="true"` 的元素及其子元素。
+
+### Q: 如何在點擊時不觸發框選？
+
+A: 只有在滑鼠移動後才會觸發 `onSelectionStart`，單純點擊（無移動）不會觸發任何選取回調。
+
+### Q: 如何清除選取？
+
+A: 使用 `onClearClick` 回調，在使用者點擊空白處時清除選取狀態：
+
+```typescript
+onClearClick: (selectedElements) => {
+  selectedElements.forEach(el => el.classList.remove('selected'));
+  selectedIds.value = [];
+}
+```
+
+### Q: 是否支援觸控裝置？
+
+A: 目前僅支援滑鼠事件。觸控支援需要額外實作 `touchstart`、`touchmove`、`touchend` 事件。
+
+### Q: 如何限制框選範圍？
+
+A: 通過 `container` 選項限制框選區域，框選框和碰撞檢測都相對於該容器。
+
+### Q: 可以同時選取多組不同的元素嗎？
+
+A: 可以。使用多次 `addTarget()` 添加不同的目標配置，每個配置都有獨立的選取狀態和回調。
+
+## 授權
+
+請依照專案授權使用。
+
+## 更新日誌
+
+### v1.0.0 (2026-01-11)
+- ✨ 初始版本
+- ✨ 支援多目標配置
+- ✨ 內建拖拽元素保護
+- ✨ 完整生命週期回調
+- ✨ WeakMap 快取優化
+- ✨ CSS 變數支援

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@hardanonymous/marquee-selector",
+  "version": "0.0.1",
+  "description": "A framework-agnostic marquee selection library with drag & text selection protection",
+  "author": "hardanonymous <hard25670559@gmail.com>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./style.css": "./dist/marquee-selector.css"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "marquee",
+    "selection",
+    "drag-selection",
+    "box-selection",
+    "marquee-selection",
+    "typescript",
+    "framework-agnostic",
+    "vue",
+    "react",
+    "vanilla-js"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hardanonymous/marquee-selector.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hardanonymous/marquee-selector/issues"
+  },
+  "homepage": "https://github.com/hardanonymous/marquee-selector#readme",
+  "devDependencies": {
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.5",
+    "cssnano": "^7.1.2",
+    "cssnano-preset-default": "^7.0.10",
+    "rollup": "^4.9.0",
+    "rollup-plugin-postcss": "^4.0.2",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  }
+}