@knotx/plugins-background 0.4.12 → 0.4.14

package/README.en.md

@@ -0,0 +1,226 @@
+# @knotx/plugins-background
+
+Background plugin that provides visual background patterns for the KnotX canvas.
+
+## Installation
+
+```bash
+npm install @knotx/plugins-background
+```
+
+## Overview
+
+The Background plugin provides various background patterns for the KnotX canvas, including dots, lines, and cross patterns. This plugin enhances user experience by providing grid-like visual references.
+
+## Implementation Principle
+
+The Background plugin implements background effects using SVG pattern definitions and repeating tiles. The plugin renders in the Background layer, positioned below all other elements. Key principles:
+
+1. **SVG Pattern Generation**: Uses SVG `<defs>` and `<pattern>` to create repeatable background patterns
+2. **Dynamic Style Calculation**: Dynamically adjusts background offset and gaps based on canvas transform state (zoom, pan)
+3. **Pattern Type Support**: Supports three pattern types - dots, lines, and cross
+
+## Dependencies
+
+### Core Dependencies
+- `@knotx/core`: Provides base plugin architecture
+- `@knotx/decorators`: Provides decorator support
+- `@knotx/jsx`: Provides JSX support
+
+### Plugin Dependencies
+- `@knotx/plugins-canvas`: Retrieves canvas transform state and container information
+
+## API Documentation
+
+### Main Classes
+
+#### Background
+
+The main class of the Background plugin, extending `BasePlugin`.
+
+```typescript
+export class Background extends BasePlugin<'background', BackgroundConfig> {
+  name = 'background' as const
+}
+```
+
+### Configuration Options
+
+#### BackgroundConfig
+
+```typescript
+export type BackgroundConfig = Omit<BackgroundProps, 'id'>
+
+export interface BackgroundProps {
+  /** Background color */
+  color?: string
+  /** Background base color */
+  bgColor?: string
+  /** Gap between pattern repetitions */
+  gap?: number | [number, number]
+  /** Size of a single pattern element */
+  size?: number
+  /** Pattern offset */
+  offset?: number | [number, number]
+  /** Line width for line patterns */
+  lineWidth?: number
+  /** Pattern variant type */
+  variant?: BackgroundVariant
+  /** Styles applied to the container */
+  style?: Record<string, any>
+}
+```
+
+#### BackgroundVariant
+
+```typescript
+export enum BackgroundVariant {
+  Lines = 'lines',
+  Dots = 'dots',
+  Cross = 'cross',
+}
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { Background, BackgroundVariant } from '@knotx/plugins-background'
+
+const engine = new Engine({
+  plugins: [Background],
+  pluginConfig: {
+    background: {
+      variant: BackgroundVariant.Dots,
+      color: '#ddd',
+      gap: 20,
+    },
+  },
+})
+```
+
+### Dots Background
+
+```typescript
+const engine = new Engine({
+  plugins: [Background],
+  pluginConfig: {
+    background: {
+      variant: BackgroundVariant.Dots,
+      color: '#999',
+      bgColor: '#f5f5f5',
+      gap: 20,
+      size: 2,
+    },
+  },
+})
+```
+
+### Lines Background
+
+```typescript
+const engine = new Engine({
+  plugins: [Background],
+  pluginConfig: {
+    background: {
+      variant: BackgroundVariant.Lines,
+      color: '#ddd',
+      lineWidth: 1,
+      gap: 20,
+    },
+  },
+})
+```
+
+### Cross Background
+
+```typescript
+const engine = new Engine({
+  plugins: [Background],
+  pluginConfig: {
+    background: {
+      variant: BackgroundVariant.Cross,
+      color: '#ddd',
+      lineWidth: 1,
+      gap: 20,
+      size: 10,
+    },
+  },
+})
+```
+
+### Custom Styling
+
+```typescript
+const engine = new Engine({
+  plugins: [Background],
+  pluginConfig: {
+    background: {
+      variant: BackgroundVariant.Dots,
+      color: '#4A90E2',
+      bgColor: '#F0F4F8',
+      gap: [30, 20], // Different horizontal and vertical gaps
+      offset: [10, 5], // Offset values
+      style: {
+        opacity: 0.8,
+      },
+    },
+  },
+})
+```
+
+## Integration with Other Plugins
+
+### Integration with Canvas Plugin
+
+The Background plugin depends on the Canvas plugin for transform state and container information:
+
+```typescript
+import { Background, BackgroundVariant } from '@knotx/plugins-background'
+import { Canvas } from '@knotx/plugins-canvas'
+
+const engine = new Engine({
+  plugins: [Canvas, Background],
+  pluginConfig: {
+    canvas: {
+      // canvas configuration
+    },
+    background: {
+      variant: BackgroundVariant.Dots,
+      color: '#ddd',
+    },
+  },
+})
+```
+
+## File Directory Structure
+
+```
+packages/plugins-background/
+├── src/
+│   ├── background.tsx          # Main implementation file
+│   └── index.ts               # Export file
+├── dist/                      # Build output directory
+├── package.json              # Package configuration
+├── build.config.ts           # Build configuration
+├── tsconfig.json             # TypeScript configuration
+├── eslint.config.mjs         # ESLint configuration
+└── CHANGELOG.md              # Changelog
+```
+
+### Core Files Description
+
+- **background.tsx**: Contains the main implementation of the Background plugin, including SVG pattern generation, style calculation, and rendering logic
+- **index.ts**: Exports the Background class and related type definitions
+
+## Notes
+
+1. **Performance Optimization**: The Background plugin uses SVG patterns for good performance, but performance optimization might be needed on extremely large canvases
+2. **Browser Compatibility**: Depends on SVG features, consider target browser compatibility
+3. **Style Hierarchy**: The Background plugin renders in the Background layer, ensuring it's below all other elements
+4. **Responsive Design**: The background automatically adjusts based on canvas transform state, no manual handling required
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,226 @@
+# @knotx/plugins-background
+
+背景插件，为 KnotX 画布提供可视化背景模式。
+
+## 安装
+
+```bash
+npm install @knotx/plugins-background
+```
+
+## 概述
+
+Background 插件为 KnotX 画布提供了多种背景模式，包括点状、线状和交叉模式。该插件可以增强用户体验，提供网格化的视觉参考。
+
+## 实现原理
+
+Background 插件通过 SVG 模式定义和重复平铺的方式实现背景效果。插件在 Background 层渲染，位于所有其他元素之下。主要原理：
+
+1. **SVG 模式生成**：使用 SVG `<defs>` 和 `<pattern>` 创建可重复的背景图案
+2. **动态样式计算**：根据画布变换状态（缩放、平移）动态调整背景的偏移和间隙
+3. **图案类型支持**：支持点状（dots）、线状（lines）和交叉（cross）三种图案
+
+## 依赖关系
+
+### 核心依赖
+- `@knotx/core`：提供基础插件架构
+- `@knotx/decorators`：提供装饰器支持
+- `@knotx/jsx`：提供 JSX 支持
+
+### 插件依赖
+- `@knotx/plugins-canvas`：获取画布变换状态和容器信息
+
+## API 文档
+
+### 主要类
+
+#### Background
+
+背景插件的主要类，继承自 `BasePlugin`。
+
+```typescript
+export class Background extends BasePlugin<'background', BackgroundConfig> {
+  name = 'background' as const
+}
+```
+
+### 配置选项
+
+#### BackgroundConfig
+
+```typescript
+export type BackgroundConfig = Omit<BackgroundProps, 'id'>
+
+export interface BackgroundProps {
+  /** 背景颜色 */
+  color?: string
+  /** 背景的底色 */
+  bgColor?: string
+  /** 图案重复之间的间隙 */
+  gap?: number | [number, number]
+  /** 单个图案元素的大小 */
+  size?: number
+  /** 图案的偏移量 */
+  offset?: number | [number, number]
+  /** 线条模式的线宽 */
+  lineWidth?: number
+  /** 图案变体类型 */
+  variant?: BackgroundVariant
+  /** 应用于容器的样式 */
+  style?: Record<string, any>
+}
+```
+
+#### BackgroundVariant
+
+```typescript
+export enum BackgroundVariant {
+  Lines = 'lines',
+  Dots = 'dots',
+  Cross = 'cross',
+}
+```
+
+## 使用示例
+
+### 基本用法
+
+```typescript
+import { Background, BackgroundVariant } from '@knotx/plugins-background'
+
+const engine = new Engine({
+  plugins: [Background],
+  pluginConfig: {
+    background: {
+      variant: BackgroundVariant.Dots,
+      color: '#ddd',
+      gap: 20,
+    },
+  },
+})
+```
+
+### 点状背景
+
+```typescript
+const engine = new Engine({
+  plugins: [Background],
+  pluginConfig: {
+    background: {
+      variant: BackgroundVariant.Dots,
+      color: '#999',
+      bgColor: '#f5f5f5',
+      gap: 20,
+      size: 2,
+    },
+  },
+})
+```
+
+### 线条背景
+
+```typescript
+const engine = new Engine({
+  plugins: [Background],
+  pluginConfig: {
+    background: {
+      variant: BackgroundVariant.Lines,
+      color: '#ddd',
+      lineWidth: 1,
+      gap: 20,
+    },
+  },
+})
+```
+
+### 交叉背景
+
+```typescript
+const engine = new Engine({
+  plugins: [Background],
+  pluginConfig: {
+    background: {
+      variant: BackgroundVariant.Cross,
+      color: '#ddd',
+      lineWidth: 1,
+      gap: 20,
+      size: 10,
+    },
+  },
+})
+```
+
+### 自定义样式
+
+```typescript
+const engine = new Engine({
+  plugins: [Background],
+  pluginConfig: {
+    background: {
+      variant: BackgroundVariant.Dots,
+      color: '#4A90E2',
+      bgColor: '#F0F4F8',
+      gap: [30, 20], // 不同的水平和垂直间隙
+      offset: [10, 5], // 偏移量
+      style: {
+        opacity: 0.8,
+      },
+    },
+  },
+})
+```
+
+## 与其他插件的集成
+
+### 与 Canvas 插件集成
+
+Background 插件依赖 Canvas 插件提供的变换状态和容器信息：
+
+```typescript
+import { Background, BackgroundVariant } from '@knotx/plugins-background'
+import { Canvas } from '@knotx/plugins-canvas'
+
+const engine = new Engine({
+  plugins: [Canvas, Background],
+  pluginConfig: {
+    canvas: {
+      // canvas 配置
+    },
+    background: {
+      variant: BackgroundVariant.Dots,
+      color: '#ddd',
+    },
+  },
+})
+```
+
+## 文件目录结构
+
+```
+packages/plugins-background/
+├── src/
+│   ├── background.tsx          # 主要实现文件
+│   └── index.ts               # 导出文件
+├── dist/                      # 构建输出目录
+├── package.json              # 包配置文件
+├── build.config.ts           # 构建配置
+├── tsconfig.json             # TypeScript 配置
+├── eslint.config.mjs         # ESLint 配置
+└── CHANGELOG.md              # 更新日志
+```
+
+### 核心文件说明
+
+- **background.tsx**：包含 Background 插件的主要实现，包括 SVG 模式生成、样式计算和渲染逻辑
+- **index.ts**：导出 Background 类和相关类型定义
+
+## 注意事项
+
+1. **性能优化**：Background 插件使用 SVG 模式，性能良好，但在极大的画布上可能需要考虑性能优化
+2. **浏览器兼容性**：依赖 SVG 特性，需要考虑目标浏览器的兼容性
+3. **样式层级**：Background 插件渲染在 Background 层，确保在所有其他元素之下
+4. **响应式设计**：背景会根据画布的变换状态自动调整，无需手动处理
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knotx/plugins-background",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "description": "Background Plugin for Knotx",
   "author": "boenfu",
   "license": "MIT",
@@ -28,19 +28,19 @@
     "dist"
   ],
   "peerDependencies": {
-    "@knotx/core": "0.4.12",
-    "@knotx/decorators": "0.4.12",
-    "@knotx/jsx": "0.4.12",
-    "@knotx/plugins-canvas": "0.4.12"
+    "@knotx/core": "0.4.14",
+    "@knotx/decorators": "0.4.14",
+    "@knotx/jsx": "0.4.14",
+    "@knotx/plugins-canvas": "0.4.14"
   },
   "devDependencies": {
-    "@knotx/build-config": "0.4.12",
-    "@knotx/core": "0.4.12",
-    "@knotx/decorators": "0.4.12",
-    "@knotx/eslint-config": "0.4.12",
-    "@knotx/jsx": "0.4.12",
-    "@knotx/plugins-canvas": "0.4.12",
-    "@knotx/typescript-config": "0.4.12"
+    "@knotx/build-config": "0.4.14",
+    "@knotx/core": "0.4.14",
+    "@knotx/decorators": "0.4.14",
+    "@knotx/eslint-config": "0.4.14",
+    "@knotx/jsx": "0.4.14",
+    "@knotx/plugins-canvas": "0.4.14",
+    "@knotx/typescript-config": "0.4.14"
   },
   "scripts": {
     "build": "unbuild",