@composy/kanban-core 0.0.1 → 0.0.2

package/README.md

@@ -1,37 +1,171 @@
-# @composy/kanban-core
-
-鐪嬫澘瑙嗗浘搴擄紝鏀寔鎷栨嫿鍗＄墖涓庡垪绠＄悊
-
-## 功能特性
-
-- 🚀 高性能核心引擎
-- 🎨 TypeScript 类型完整
-- 📦 支持 ESM / CJS 双格式输出
-
-## 安装
-
-```bash
-npm install @composy/kanban-core
-```
-
-## 快速开始
-
-```typescript
-import { /* 需要的导出 */ } from '@composy/kanban-core'
-
-// 根据实际 API 使用
-```
-
-## 目录结构
-
-```
-packages/core/
-├── src/              # 源码
-├── package.json
-├── tsconfig.json     # ESM 构建配置
-└── tsconfig.cjs.json # CJS 构建配置
-```
-
-## License
-
-MIT
+# @composy/kanban-core
+
+基于实际源码能力构建的 **看板视图核心库**，是 LDesign Kanban
+workspace 的框架无关 TypeScript 核心。核心由 `KanbanBoard`
+门面类统一编排 5 个子系统：`ColumnManager`（列与卡片数据管理）、`DragController`（卡片/列拖拽）、`FilterEngine`（筛选与搜索）、`Renderer`（DOM 渲染）、`EventEmitter`（事件总线）。内置卡片增删改移、跨列拖拽、列折叠、WIP 限制、标签、优先级、多条件筛选、搜索、看板数据导入导出、生命周期事件与自定义渲染器等能力，适用于任务管理、项目管理等看板场景。
+
+## 安装
+
+```bash
+# pnpm
+pnpm add @composy/kanban-core
+
+# npm
+npm install @composy/kanban-core
+```
+
+> 框架适配（如 Vue 3）请安装对应的 `@composy/kanban-vue` 适配包，直接消费本核心模块。
+
+## 目录结构
+
+基于真实 `src/` 布局：
+
+```
+src/
+├── index.ts                     # 入口，聚合导出
+├── core/                        # KanbanBoard / EventEmitter / ColumnManager / DragController / FilterEngine / Renderer
+├── types/index.ts               # Label/Card/Column/Board/KanbanOptions/KanbanEventMap/FilterCriteria/BoardData
+├── styles/kanban.less           # 看板样式（编译为 index.css）
+├── version.ts                   # VERSION 常量
+└── utils/                       # dom.ts / id.ts
+```
+
+## 核心 API 详表
+
+### 类与工厂
+
+| 名称                | 类型 | 签名                                                            | 用途                                                                |
+| ------------------- | ---- | --------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `KanbanBoard`       | 类   | `new KanbanBoard(options: KanbanOptions)`                       | 看板主类：编排列/卡片管理、拖拽、筛选、渲染、事件，对外暴露完整 API |
+| `createKanbanBoard` | 函数 | `(options: KanbanOptions) => KanbanBoard`                       | 创建看板实例的工厂函数                                              |
+| `EventEmitter`      | 类   | `new EventEmitter()`                                            | 轻量事件总线，提供 `on/once/off/emit/removeAll`                     |
+| `ColumnManager`     | 类   | `new ColumnManager(events: EventEmitter)`                       | 列与卡片数据的增删改查、移动、折叠等管理                            |
+| `DragController`    | 类   | `new DragController(events: EventEmitter, classPrefix: string)` | 卡片/列拖拽交互控制，跨列拖放                                       |
+| `FilterEngine`      | 类   | `new FilterEngine(events: EventEmitter)`                        | 按多条件筛选卡片、关键词搜索、清除筛选                              |
+| `Renderer`          | 类   | `new Renderer(container, events, dragController, options)`      | 将列/卡片渲染为 DOM，支持自定义卡片与列头渲染器                     |
+
+### KanbanBoard 实例方法（真实签名）
+
+| 名称                                                   | 类型 | 签名                                                                                | 用途                                                      |
+| ------------------------------------------------------ | ---- | ----------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `addColumn` / `removeColumn`                           | 方法 | `(partial: Partial<Column>) => Column` / `(id: string) => Column \| undefined`      | 添加并重渲染 / 移除列                                     |
+| `updateColumn` / `moveColumn` / `toggleColumnCollapse` | 方法 | `(id, changes?) / (id, toIndex) / (id) => void`                                     | 更新列 / 移动列顺序 / 折叠展开                            |
+| `getColumns` / `getColumn`                             | 方法 | `() => Column[]` / `(id: string) => Column \| undefined`                            | 获取全部/单列                                             |
+| `addCard` / `removeCard`                               | 方法 | `(columnId, partial) => Card \| undefined` / `(cardId) => Card \| undefined`        | 向指定列添加 / 移除卡片                                   |
+| `updateCard` / `moveCard`                              | 方法 | `(cardId, changes) / (cardId, toColumnId, toIndex) => void`                         | 更新 / 移动卡片（支持跨列）                               |
+| `getCard` / `getAllCards` / `getCardCount`             | 方法 | `(cardId: string) => Card \| undefined` / `() => Card[]` / `() => number`           | 卡片查询                                                  |
+| `filter` / `search` / `clearFilter`                    | 方法 | `(criteria: FilterCriteria) => void` / `(keyword: string) => Card[]` / `() => void` | 按条件筛选 / 关键词搜索 / 清除筛选                        |
+| `exportData` / `importData`                            | 方法 | `() => BoardData` / `(data: BoardData) => void`                                     | 导出看板数据（含版本/标题/列/标签/导出时间） / 导入并渲染 |
+| `on` / `once` / `off`                                  | 方法 | `(event: string, handler: EventHandler) => () => void`                              | 事件监听/一次性/移除                                      |
+| `getLabels` / `addLabel` / `removeLabel`               | 方法 | `() => Label[]` / `(label: Label) => void` / `(id: string) => void`                 | 标签管理                                                  |
+| `getBoardElement`                                      | 方法 | `() => HTMLElement \| null`                                                         | 获取看板根 DOM 元素                                       |
+| `getOptions`                                           | 方法 | `() => Readonly<KanbanOptions>`                                                     | 获取配置快照                                              |
+| `destroy` / `isDestroyed`                              | 方法 | `() => void` / `() => boolean`                                                      | 销毁实例 / 是否已销毁                                     |
+
+### 类型
+
+| 名称                                  | 类型 | 签名                                              | 用途                                                                          |
+| ------------------------------------- | ---- | ------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `Board` / `Column` / `Card` / `Label` | 接口 | —                                                 | 看板数据模型（看板/列/卡片/标签）                                             |
+| `BoardData`                           | 接口 | `{ version; title; columns; labels; exportedAt }` | 看板导入导出数据格式                                                          |
+| `KanbanOptions`                       | 接口 | —                                                 | 配置项：容器/列/标签/标题/拖拽开关/搜索/渲染器/各类回调                       |
+| `KanbanEventMap`                      | 接口 | —                                                 | 事件映射：ready/destroy/error、card:_, column:_, filter:_, data:_ 等          |
+| `FilterCriteria`                      | 接口 | —                                                 | 筛选条件：keyword/labelIds/assignees/priorities/columnIds/dueDateRange/custom |
+| `VERSION`                             | 常量 | `string`                                          | 包版本号，随 `exportData` 写入                                                |
+
+## 使用示例
+
+基于真实导出，创建看板并操作数据与事件：
+
+```ts
+import { createKanbanBoard } from '@composy/kanban-core'
+
+const board = createKanbanBoard({
+  container: '#board', // CSS 选择器或 HTMLElement
+  title: '迭代看板',
+  draggable: true,
+  crossColumnDrag: true,
+  searchable: true,
+  columns: [
+    { id: 'todo', title: '待办', order: 0 },
+    { id: 'done', title: '已完成', order: 1 },
+  ],
+  onCardClick: card => window.dispatchEvent(new CustomEvent('kanban-card-click', { detail: card })),
+  onCardMove: (card, from, to, _index) =>
+    window.dispatchEvent(new CustomEvent('kanban-card-move', { detail: { card, from, to } })),
+})
+
+// 添加列与卡片
+board.addColumn({ id: 'doing', title: '进行中', order: 1, wipLimit: 3 })
+board.addCard('todo', { id: 'c1', title: '设计评审', priority: 'high' })
+
+// 跨列移动、折叠
+board.moveCard('c1', 'doing', 0)
+board.toggleColumnCollapse('todo')
+
+// 筛选与搜索
+board.search('设计')
+board.filter({ priorities: ['high'], columnIds: ['todo'] })
+board.clearFilter()
+
+// 事件监听
+const offReady = board.on('ready', () =>
+  document.documentElement.setAttribute('data-kanban-ready', 'true')
+)
+offReady()
+
+// 导入导出
+const data = board.exportData()
+board.importData(data)
+
+// 销毁
+board.destroy()
+```
+
+### Data normalization and boundaries
+
+- Imported and initial columns are cloned into the core model. Column and card order values are
+  normalized before rendering and moving.
+- moveColumn and moveCard clamp an out-of-range index to the valid destination range. Move events
+  and callbacks report the effective index.
+- importData rejects a payload without a columns array and emits the error event instead of mutating
+  the board.
+- Invalid card or range dates do not match dueDateRange filters. An empty search clears the active
+  search criteria.
+
+## 构建脚本 & 验证命令
+
+```bash
+pnpm build          # 构建产物（es/lib/esm/dist，含 index.css）
+pnpm type-check     # 类型检查
+pnpm lint / lint:check / lint:fix   # 代码规范（/0-warning 严格 / 自动修复）
+pnpm test           # 单元测试（可加 --watch/--coverage/--changed/--failed/--ui）
+pnpm release        # 发布
+```
+
+## 产物说明
+
+构建由 `@composy/builder`（`ldesign-builder build`）驱动，产出多格式产物：
+
+| 目录    | 说明                                               | package.json 入口                     |
+| ------- | -------------------------------------------------- | ------------------------------------- |
+| `es/`   | ES Modules（含 `.d.ts` 类型声明）                  | `module` / `exports.import` / `types` |
+| `lib/`  | CommonJS（`.cjs`）                                 | `main` / `exports.require`            |
+| `esm/`  | ESM 兼容产物                                       | 随 `exports` 子路径分发               |
+| `dist/` | 浏览器压缩产物（含 `index.css` / `index.min.css`） | `unpkg` / `jsdelivr` / `browser`      |
+
+`sideEffects: false` 便于 tree-shaking。`exports`
+提供子路径：`./core`、`./types`、`./utils`（均支持通配符深层路径）。`src/styles/kanban.less`
+编译后通过 `style` 字段与 `./dist/index.css`、`./dist/index.min.css` 子路径提供样式。
+
+## 备注
+
+- **框架无关**：本包为纯核心逻辑，不绑定 React/Vue；框架适配由上层 `@composy/kanban-vue` 等提供。
+- **peerDeps**：无运行期第三方运行时依赖，`devDependencies`
+  仅含构建/测试工具（`@composy/builder`、`@composy/testing`、`@composy/release`、eslint、tsc）。
+- **入站密钥**：`publishConfig.registry` 指向私有 npm 源
+  `http://npm.longrise.cn:6286/`，发布时按该源执行。
+- **样式引入**：使用本包需额外引入编译产物 CSS（如
+  `@composy/kanban-core/dist/index.css`），入口 JS 中的 Less 导入由 Builder 在构建时提取。
+- **自定义渲染**：通过 `KanbanOptions.cardRenderer` / `columnHeaderRenderer`
+  可接管卡片与列头 DOM 渲染。

package/dist/index.css

@@ -2,140 +2,140 @@
 /* @composy/kanban-core - Default Styles */
 .kanban-board {
   width: 100%;
-  min-height: 400px;
+  min-height: var(--ld-px-400);
   overflow-x: auto;
   overflow-y: hidden;
   max-width: 100%;
 }
 .kanban-columns {
   display: flex;
-  gap: 16px;
-  padding: 8px;
+  gap: var(--ld-px-16);
+  padding: var(--ld-px-8);
   min-height: 100%;
   align-items: flex-start;
 }
 /* Column */
 .kanban-column {
-  flex: 0 0 280px;
-  max-width: 280px;
-  background: #f4f5f7;
-  border-radius: 8px;
+  flex: 0 0 var(--ld-px-280);
+  max-width: var(--ld-px-280);
+  background: var(--ld-bg-surface);
+  border-radius: var(--ld-px-8);
   display: flex;
   flex-direction: column;
-  max-height: calc(100vh - 200px);
+  max-height: calc(100vh - var(--ld-px-200));
   transition: opacity 0.2s, box-shadow 0.2s;
 }
 .kanban-column--collapsed {
-  flex: 0 0 48px;
-  max-width: 48px;
-  min-height: 200px;
+  flex: 0 0 var(--ld-px-48);
+  max-width: var(--ld-px-48);
+  min-height: var(--ld-px-200);
 }
 .kanban-column--dragging {
   opacity: 0.5;
 }
 .kanban-column--drag-over {
-  box-shadow: 0 0 0 2px #4c9aff;
+  box-shadow: 0 0 0 var(--ld-px-2) var(--ld-primary-500);
 }
 /* Column Header */
 .kanban-column-header {
   display: flex;
   align-items: center;
-  gap: 6px;
-  padding: 10px 12px;
-  border-bottom: 1px solid #e1e4e8;
+  gap: var(--ld-px-6);
+  padding: var(--ld-px-10) var(--ld-px-12);
+  border-bottom: var(--ld-px-1) solid var(--ld-border);
   -webkit-user-select: none;
      -moz-user-select: none;
           user-select: none;
 }
 .kanban-column-drag-handle {
   cursor: grab;
-  color: #a0a0a0;
-  font-size: 12px;
-  letter-spacing: -3px;
+  color: var(--ld-text-secondary);
+  font-size: var(--ld-px-12);
+  letter-spacing: calc(-1 * var(--ld-px-3));
   line-height: 1;
-  padding: 2px 0;
+  padding: var(--ld-px-2) 0;
 }
 .kanban-column-drag-handle:active {
   cursor: grabbing;
 }
 .kanban-column-color {
-  width: 12px;
-  height: 12px;
-  border-radius: 3px;
+  width: var(--ld-px-12);
+  height: var(--ld-px-12);
+  border-radius: var(--ld-px-3);
   flex-shrink: 0;
 }
 .kanban-column-title {
-  font-size: 14px;
+  font-size: var(--ld-px-14);
   font-weight: 600;
-  color: #172b4d;
+  color: var(--ld-text-primary);
   flex: 1;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 .kanban-column-count {
-  font-size: 12px;
-  color: #6b778c;
-  background: #dfe1e6;
-  border-radius: 10px;
-  padding: 1px 8px;
+  font-size: var(--ld-px-12);
+  color: var(--ld-text-secondary);
+  background: var(--ld-bg-hover);
+  border-radius: var(--ld-px-10);
+  padding: var(--ld-px-1) var(--ld-px-8);
   flex-shrink: 0;
 }
 .kanban-column-count--limit {
-  background: #ffebe6;
-  color: #bf2600;
+  background: var(--ld-danger-50);
+  color: var(--ld-danger-700);
 }
 .kanban-column-collapse-btn,
 .kanban-column-actions-btn {
   background: none;
   border: none;
   cursor: pointer;
-  color: #6b778c;
-  font-size: 12px;
-  padding: 2px 4px;
-  border-radius: 3px;
+  color: var(--ld-text-secondary);
+  font-size: var(--ld-px-12);
+  padding: var(--ld-px-2) var(--ld-px-4);
+  border-radius: var(--ld-px-3);
   line-height: 1;
 }
 .kanban-column-collapse-btn:hover,
 .kanban-column-actions-btn:hover {
-  background: #dfe1e6;
-  color: #172b4d;
+  background: var(--ld-bg-hover);
+  color: var(--ld-text-primary);
 }
 /* Column Body */
 .kanban-column-body {
   flex: 1;
   overflow-y: auto;
-  padding: 8px;
-  min-height: 40px;
+  padding: var(--ld-px-8);
+  min-height: var(--ld-px-40);
 }
 .kanban-column-body--drag-over {
-  background: #e3f2fd;
-  border-radius: 0 0 8px 8px;
+  background: var(--ld-primary-50);
+  border-radius: 0 0 var(--ld-px-8) var(--ld-px-8);
 }
 /* Placeholder */
 .kanban-placeholder {
-  background: #e3f2fd;
-  border: 2px dashed #90caf9;
-  border-radius: 6px;
-  margin-bottom: 8px;
-  min-height: 40px;
+  background: var(--ld-primary-50);
+  border: var(--ld-px-2) dashed var(--ld-primary-300);
+  border-radius: var(--ld-px-6);
+  margin-bottom: var(--ld-px-8);
+  min-height: var(--ld-px-40);
   transition: height 0.15s ease;
 }
 /* Card */
 .kanban-card {
-  background: #fff;
-  border-radius: 6px;
-  padding: 10px 12px;
-  margin-bottom: 8px;
+  background: var(--ld-bg-container);
+  border-radius: var(--ld-px-6);
+  padding: var(--ld-px-10) var(--ld-px-12);
+  margin-bottom: var(--ld-px-8);
   cursor: pointer;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.08);
+  box-shadow: var(--ld-shadow-1);
   transition: box-shadow 0.2s, transform 0.15s, opacity 0.2s;
-  border: 1px solid transparent;
+  border: var(--ld-px-1) solid transparent;
   position: relative;
 }
 .kanban-card:hover {
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
-  border-color: #e1e4e8;
+  box-shadow: var(--ld-shadow-2);
+  border-color: var(--ld-border);
 }
 .kanban-card--dragging {
   opacity: 0.4;
@@ -147,50 +147,50 @@
   left: 0;
   top: 0;
   bottom: 0;
-  width: 3px;
-  border-radius: 6px 0 0 6px;
+  width: var(--ld-px-3);
+  border-radius: var(--ld-px-6) 0 0 var(--ld-px-6);
 }
 .kanban-card-priority--low {
-  background: #36b37e;
+  background: var(--ld-success-500);
 }
 .kanban-card-priority--medium {
-  background: #ffab00;
+  background: var(--ld-warning-500);
 }
 .kanban-card-priority--high {
-  background: #ff5630;
+  background: var(--ld-danger-500);
 }
 .kanban-card-priority--urgent {
-  background: #bf2600;
+  background: var(--ld-danger-700);
 }
 /* Card Labels */
 .kanban-card-labels {
   display: flex;
   flex-wrap: wrap;
-  gap: 4px;
-  margin-bottom: 6px;
+  gap: var(--ld-px-4);
+  margin-bottom: var(--ld-px-6);
 }
 .kanban-card-label {
   display: inline-block;
-  padding: 1px 8px;
-  border-radius: 3px;
-  font-size: 11px;
-  color: #fff;
+  padding: var(--ld-px-1) var(--ld-px-8);
+  border-radius: var(--ld-px-3);
+  font-size: var(--ld-px-11);
+  color: var(--ld-text-inverse);
   font-weight: 500;
   line-height: 1.6;
 }
 /* Card Title */
 .kanban-card-title {
-  font-size: 14px;
+  font-size: var(--ld-px-14);
   font-weight: 500;
-  color: #172b4d;
+  color: var(--ld-text-primary);
   line-height: 1.4;
   word-break: break-word;
 }
 /* Card Description */
 .kanban-card-desc {
-  font-size: 12px;
-  color: #6b778c;
-  margin-top: 4px;
+  font-size: var(--ld-px-12);
+  color: var(--ld-text-secondary);
+  margin-top: var(--ld-px-4);
   line-height: 1.4;
   display: -webkit-box;
   -webkit-line-clamp: 2;
@@ -202,26 +202,26 @@
   display: flex;
   align-items: center;
   justify-content: space-between;
-  margin-top: 8px;
-  gap: 8px;
+  margin-top: var(--ld-px-8);
+  gap: var(--ld-px-8);
 }
 .kanban-card-assignees {
   display: flex;
-  gap: -4px;
+  gap: calc(-1 * var(--ld-px-4));
 }
 .kanban-card-avatar {
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: 24px;
-  height: 24px;
+  width: var(--ld-px-24);
+  height: var(--ld-px-24);
   border-radius: 50%;
-  background: #dfe1e6;
-  color: #42526e;
-  font-size: 11px;
+  background: var(--ld-bg-hover);
+  color: var(--ld-text-secondary);
+  font-size: var(--ld-px-11);
   font-weight: 600;
-  border: 2px solid #fff;
-  margin-left: -4px;
+  border: var(--ld-px-2) solid var(--ld-text-inverse);
+  margin-left: calc(-1 * var(--ld-px-4));
 }
 .kanban-card-avatar:first-child {
   margin-left: 0;
@@ -230,78 +230,78 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: 24px;
-  height: 24px;
+  width: var(--ld-px-24);
+  height: var(--ld-px-24);
   border-radius: 50%;
-  background: #c1c7d0;
-  color: #42526e;
-  font-size: 10px;
+  background: var(--ld-gray-400);
+  color: var(--ld-text-secondary);
+  font-size: var(--ld-px-10);
   font-weight: 600;
-  border: 2px solid #fff;
-  margin-left: -4px;
+  border: var(--ld-px-2) solid var(--ld-text-inverse);
+  margin-left: calc(-1 * var(--ld-px-4));
 }
 .kanban-card-due {
-  font-size: 12px;
-  color: #6b778c;
+  font-size: var(--ld-px-12);
+  color: var(--ld-text-secondary);
   display: flex;
   align-items: center;
-  gap: 4px;
+  gap: var(--ld-px-4);
 }
 .kanban-card-due--overdue {
-  color: #ff5630;
+  color: var(--ld-danger-500);
   font-weight: 600;
 }
 /* Add Buttons */
 .kanban-add-card {
-  padding: 0 4px;
+  padding: 0 var(--ld-px-4);
 }
 .kanban-add-card-btn {
   width: 100%;
-  padding: 6px 8px;
+  padding: var(--ld-px-6) var(--ld-px-8);
   background: none;
   border: none;
-  border-radius: 6px;
-  color: #6b778c;
-  font-size: 13px;
+  border-radius: var(--ld-px-6);
+  color: var(--ld-text-secondary);
+  font-size: var(--ld-px-13);
   cursor: pointer;
   text-align: left;
   transition: background 0.15s, color 0.15s;
 }
 .kanban-add-card-btn:hover {
-  background: #dfe1e6;
-  color: #172b4d;
+  background: var(--ld-bg-hover);
+  color: var(--ld-text-primary);
 }
 .kanban-add-column {
-  flex: 0 0 280px;
+  flex: 0 0 var(--ld-px-280);
 }
 .kanban-add-column-btn {
   width: 100%;
-  padding: 10px;
-  background: rgba(0, 0, 0, 0.04);
-  border: 2px dashed #d0d4d9;
-  border-radius: 8px;
-  color: #6b778c;
-  font-size: 14px;
+  padding: var(--ld-px-10);
+  background: var(--ld-bg-surface-soft);
+  border: var(--ld-px-2) dashed var(--ld-gray-300);
+  border-radius: var(--ld-px-8);
+  color: var(--ld-text-secondary);
+  font-size: var(--ld-px-14);
   cursor: pointer;
   transition: background 0.15s, border-color 0.15s, color 0.15s;
 }
 .kanban-add-column-btn:hover {
-  background: rgba(0, 0, 0, 0.08);
-  border-color: #a5adba;
-  color: #172b4d;
+  background: var(--ld-bg-hover);
+  border-color: var(--ld-gray-500);
+  color: var(--ld-text-primary);
 }
 /* Scrollbar */
 .kanban-column-body::-webkit-scrollbar {
-  width: 6px;
+  width: var(--ld-px-6);
 }
 .kanban-column-body::-webkit-scrollbar-track {
   background: transparent;
 }
 .kanban-column-body::-webkit-scrollbar-thumb {
-  background: #c1c7d0;
-  border-radius: 3px;
+  background: var(--ld-gray-400);
+  border-radius: var(--ld-px-3);
 }
 .kanban-column-body::-webkit-scrollbar-thumb:hover {
-  background: #a5adba;
+  background: var(--ld-gray-500);
 }
-/*# sourceMappingURL=src/styles/kanban.less.map */
+/*# sourceMappingURL=src\styles\kanban.less.map */