@knotx/plugins-canvas-scrollbar 0.4.11 → 0.4.13

package/README.en.md

@@ -0,0 +1,190 @@
+# @knotx/plugins-canvas-scrollbar
+
+Canvas scrollbar plugin that provides custom scrollbar functionality for the canvas.
+
+## Installation
+
+```bash
+npm install @knotx/plugins-canvas-scrollbar
+```
+
+## Overview
+
+`@knotx/plugins-canvas-scrollbar` is a canvas scrollbar plugin for the KnotX framework that provides custom scrollbar functionality for the canvas. When canvas content exceeds the visible area, scrollbars are automatically displayed, allowing users to quickly navigate to different areas of the canvas by dragging the scrollbars.
+
+## Implementation Principles
+
+The plugin dynamically calculates scrollbar position and size by monitoring canvas transform state and content dimensions:
+
+1. **Scrollbar Calculation**: Calculates scrollbar position and size based on canvas content dimensions, visible area, and transform state
+2. **Interaction Handling**: Supports clicking scrollbar tracks and dragging scrollbar thumbs
+3. **Auto-hide**: Supports configurable auto-hide delay time for scrollbars
+4. **Style Customization**: Supports custom scrollbar styles and dimensions
+
+## Dependencies
+
+This plugin depends on the following packages:
+
+- `@knotx/core` - Core functionality
+- `@knotx/decorators` - Decorator support
+- `@knotx/plugins-canvas` - Canvas plugin (peer dependency)
+- `@knotx/jsx` - JSX support (peer dependency)
+- `react` - React framework (peer dependency)
+
+## API Usage
+
+### Basic Usage
+
+```typescript
+import { CanvasScrollbar } from '@knotx/plugins-canvas-scrollbar'
+
+// Create scrollbar plugin instance
+const scrollbar = new CanvasScrollbar()
+
+// Register plugin in engine
+engine.use(scrollbar)
+```
+
+### Configuration Options
+
+```typescript
+const scrollbar = new CanvasScrollbar().init({
+  style: {
+    track: {
+      backgroundColor: '#f0f0f0',
+      borderRadius: '4px'
+    },
+    thumb: {
+      backgroundColor: '#999',
+      borderRadius: '4px'
+    }
+  },
+  size: 12,
+  offset: 5,
+  minThumbSize: 40,
+  hideTimeout: 2000
+})
+```
+
+### Complete Example
+
+```typescript
+import { Engine } from '@knotx/core'
+import { Canvas } from '@knotx/plugins-canvas'
+import { CanvasScrollbar } from '@knotx/plugins-canvas-scrollbar'
+
+const engine = new Engine()
+
+// Register canvas plugin
+engine.use(new Canvas())
+
+// Register scrollbar plugin
+engine.use(new CanvasScrollbar().init({
+  style: {
+    track: {
+      backgroundColor: 'rgba(0, 0, 0, 0.1)',
+      borderRadius: '6px'
+    },
+    thumb: {
+      backgroundColor: 'rgba(0, 0, 0, 0.3)',
+      borderRadius: '6px'
+    }
+  },
+  size: 10,
+  offset: 8,
+  minThumbSize: 50,
+  hideTimeout: 3000
+}))
+```
+
+## Configuration Interface
+
+### CanvasScrollbarConfig
+
+```typescript
+interface CanvasScrollbarConfig {
+  /**
+   * CSS styles for track and thumb
+   */
+  style?: ScrollbarStyle
+  /**
+   * Width/height of track and thumb
+   */
+  size?: number
+  /**
+   * Distance from boundary
+   */
+  offset?: number
+  /**
+   * Minimum width/height of thumb
+   */
+  minThumbSize?: number
+  /**
+   * Scrollbar hide timeout
+   */
+  hideTimeout?: number
+}
+```
+
+### ScrollbarStyle
+
+```typescript
+interface ScrollbarStyle {
+  track: CSSProperties
+  thumb: CSSProperties
+}
+```
+
+## Default Configuration
+
+```typescript
+const defaultConfig = {
+  style: {
+    track: {},
+    thumb: {}
+  },
+  offset: 3,
+  size: 8,
+  minThumbSize: 30,
+  hideTimeout: 0
+}
+```
+
+## Interactive Features
+
+### Scrollbar Dragging
+
+- Support for dragging horizontal and vertical scrollbar thumbs
+- Real-time canvas view position updates
+- Smooth dragging experience
+
+### Track Clicking
+
+- Support for clicking scrollbar tracks for quick navigation
+- Automatic target position calculation
+- Smooth scrolling animation
+
+### Auto Show/Hide
+
+- Show scrollbars when mouse enters canvas area
+- Delay-hide scrollbars when mouse leaves canvas area
+- Configurable hide delay time
+
+## File Directory Structure
+
+```
+packages/plugins-canvas-scrollbar/
+├── src/
+│   ├── canvas-scrollbar.tsx  # Canvas scrollbar plugin main file
+│   └── index.ts             # Export file
+├── dist/                    # Build output directory
+├── CHANGELOG.md            # Change log
+├── package.json            # Package configuration
+├── build.config.ts         # Build configuration
+├── eslint.config.mjs       # ESLint configuration
+└── tsconfig.json           # TypeScript configuration
+```
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,190 @@
+# @knotx/plugins-canvas-scrollbar
+
+画布滚动条插件，为画布提供自定义滚动条功能。
+
+## 安装
+
+```bash
+npm install @knotx/plugins-canvas-scrollbar
+```
+
+## 基本概述
+
+`@knotx/plugins-canvas-scrollbar` 是 KnotX 框架的画布滚动条插件，为画布提供自定义的滚动条功能。当画布内容超出可视区域时，会自动显示滚动条，用户可以通过拖拽滚动条来快速导航到画布的不同区域。
+
+## 实现原理
+
+该插件通过监听画布的变换状态和内容尺寸，动态计算滚动条的位置和大小：
+
+1. **滚动条计算**：基于画布内容尺寸、可视区域和变换状态计算滚动条的位置和大小
+2. **交互处理**：支持点击滚动条轨道和拖拽滚动条滑块
+3. **自动隐藏**：支持配置滚动条的自动隐藏延迟时间
+4. **样式定制**：支持自定义滚动条的样式和尺寸
+
+## 依赖插件
+
+该插件依赖以下包：
+
+- `@knotx/core` - 核心功能
+- `@knotx/decorators` - 装饰器支持
+- `@knotx/plugins-canvas` - 画布插件（peer dependency）
+- `@knotx/jsx` - JSX 支持（peer dependency）
+- `react` - React 框架（peer dependency）
+
+## API 使用
+
+### 基本使用
+
+```typescript
+import { CanvasScrollbar } from '@knotx/plugins-canvas-scrollbar'
+
+// 创建滚动条插件实例
+const scrollbar = new CanvasScrollbar()
+
+// 在引擎中注册插件
+engine.use(scrollbar)
+```
+
+### 配置选项
+
+```typescript
+const scrollbar = new CanvasScrollbar().init({
+  style: {
+    track: {
+      backgroundColor: '#f0f0f0',
+      borderRadius: '4px'
+    },
+    thumb: {
+      backgroundColor: '#999',
+      borderRadius: '4px'
+    }
+  },
+  size: 12,
+  offset: 5,
+  minThumbSize: 40,
+  hideTimeout: 2000
+})
+```
+
+### 完整示例
+
+```typescript
+import { Engine } from '@knotx/core'
+import { Canvas } from '@knotx/plugins-canvas'
+import { CanvasScrollbar } from '@knotx/plugins-canvas-scrollbar'
+
+const engine = new Engine()
+
+// 注册画布插件
+engine.use(new Canvas())
+
+// 注册滚动条插件
+engine.use(new CanvasScrollbar().init({
+  style: {
+    track: {
+      backgroundColor: 'rgba(0, 0, 0, 0.1)',
+      borderRadius: '6px'
+    },
+    thumb: {
+      backgroundColor: 'rgba(0, 0, 0, 0.3)',
+      borderRadius: '6px'
+    }
+  },
+  size: 10,
+  offset: 8,
+  minThumbSize: 50,
+  hideTimeout: 3000
+}))
+```
+
+## 配置接口
+
+### CanvasScrollbarConfig
+
+```typescript
+interface CanvasScrollbarConfig {
+  /**
+   * 轨道以及滑块的css样式
+   */
+  style?: ScrollbarStyle
+  /**
+   * 轨道以及滑块的宽度/高度
+   */
+  size?: number
+  /**
+   * 距离边界的距离
+   */
+  offset?: number
+  /**
+   * 滑块的最小宽度/高度
+   */
+  minThumbSize?: number
+  /**
+   * 滚动条消失延迟
+   */
+  hideTimeout?: number
+}
+```
+
+### ScrollbarStyle
+
+```typescript
+interface ScrollbarStyle {
+  track: CSSProperties
+  thumb: CSSProperties
+}
+```
+
+## 默认配置
+
+```typescript
+const defaultConfig = {
+  style: {
+    track: {},
+    thumb: {}
+  },
+  offset: 3,
+  size: 8,
+  minThumbSize: 30,
+  hideTimeout: 0
+}
+```
+
+## 交互功能
+
+### 滚动条拖拽
+
+- 支持拖拽水平和垂直滚动条滑块
+- 实时更新画布视图位置
+- 平滑的拖拽体验
+
+### 轨道点击
+
+- 支持点击滚动条轨道快速跳转
+- 自动计算目标位置
+- 平滑的滚动动画
+
+### 自动显示/隐藏
+
+- 鼠标进入画布区域时显示滚动条
+- 鼠标离开画布区域时延迟隐藏滚动条
+- 支持配置隐藏延迟时间
+
+## 文件目录结构
+
+```
+packages/plugins-canvas-scrollbar/
+├── src/
+│   ├── canvas-scrollbar.tsx  # 画布滚动条插件主文件
+│   └── index.ts             # 导出文件
+├── dist/                    # 编译输出目录
+├── CHANGELOG.md            # 变更日志
+├── package.json            # 包配置
+├── build.config.ts         # 构建配置
+├── eslint.config.mjs       # ESLint 配置
+└── tsconfig.json           # TypeScript 配置
+```
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knotx/plugins-canvas-scrollbar",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Canvas Scrollbar Plugin for Knotx",
   "author": "boenfu",
   "license": "MIT",
@@ -29,21 +29,21 @@
   ],
   "peerDependencies": {
     "react": ">=17.0.0",
-    "@knotx/jsx": "0.4.11",
-    "@knotx/plugins-canvas": "0.4.11"
+    "@knotx/jsx": "0.4.13",
+    "@knotx/plugins-canvas": "0.4.13"
   },
   "dependencies": {
-    "@knotx/core": "0.4.11",
-    "@knotx/decorators": "0.4.11"
+    "@knotx/core": "0.4.13",
+    "@knotx/decorators": "0.4.13"
   },
   "devDependencies": {
     "@types/react": "^17.0.0",
     "react": "^17.0.0",
-    "@knotx/build-config": "0.4.11",
-    "@knotx/eslint-config": "0.4.11",
-    "@knotx/jsx": "0.4.11",
-    "@knotx/plugins-canvas": "0.4.11",
-    "@knotx/typescript-config": "0.4.11"
+    "@knotx/build-config": "0.4.13",
+    "@knotx/eslint-config": "0.4.13",
+    "@knotx/jsx": "0.4.13",
+    "@knotx/plugins-canvas": "0.4.13",
+    "@knotx/typescript-config": "0.4.13"
   },
   "scripts": {
     "build": "unbuild",