@os-team-11/editor 0.1.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 os-team-11 contributors
+
+This software bundles or references @hufe921/canvas-editor
+(https://github.com/Hufe921/canvas-editor), which is licensed under the MIT
+License by Hufe921. All rights in the upstream software remain with its
+authors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# @os-team-11/editor
+
+基于 [@hufe921/canvas-editor](https://github.com/Hufe921/canvas-editor) 的招投标文档编辑器 React 组件，提供结构化 JSON 数据（`BidSchema`）与所见即所得编辑之间的双向适配。
+
+- **结构化数据优先**：以 `BidSchema` 作为单一数据源，AI/后端无需直接操作 canvas-editor 内部结构
+- **工具栏开箱即用**：内置 36 个常用按钮（字体、段落、列表、表格、图片、公式等），支持动态溢出折叠到「更多」
+- **可定制**：主题（亮/暗）、工具栏按钮、渲染器均可覆盖
+- **AI 问答**：M5.2 起内置选区右键菜单接入自定义 `ask` 函数
+
+## 安装
+
+```bash
+npm install @os-team-11/editor
+# 或
+pnpm add @os-team-11/editor
+```
+
+### Peer dependencies
+
+本包把以下依赖声明为 `peerDependencies`，需要使用方自行安装：
+
+```bash
+npm install react@^18 react-dom@^18 @hufe921/canvas-editor@^0.9.0
+```
+
+React 19 也支持。canvas-editor 必须与 peer range 内版本兼容。
+
+## 快速开始
+
+```tsx
+import { BidEditor, validateBid, type BidSchema } from '@os-team-11/editor'
+
+const sample: BidSchema = {
+  meta: {
+    title: 'XX 项目招标文件',
+    docNo: 'ZB-2026-001',
+    tenderer: 'XX 采购中心',
+    version: '1.0.0',
+    generatedAt: '2026-06-16T00:00:00Z',
+  },
+  page: {
+    size: 'A4',
+    margins: { top: 96, right: 96, bottom: 96, left: 96 },
+  },
+  sections: [
+    {
+      id: 'sec-1',
+      title: '第一章 投标邀请',
+      level: 1,
+      blocks: [
+        { type: 'heading', level: 2, text: '一、项目概况' },
+        { type: 'paragraph', text: '本次招标的项目为 XX 系统建设。' },
+        { type: 'list', ordered: true, items: ['独立法人', '具备相关资质'] },
+      ],
+    },
+  ],
+}
+
+export default function App() {
+  const result = validateBid(sample)
+  if (!result.success) throw new Error('invalid bid')
+
+  return (
+    <div style={{ height: '100vh' }}>
+      <BidEditor bid={result.data} onChange={next => console.log(next)} />
+    </div>
+  )
+}
+```
+
+样式通过入口 `import './react/styles.css'` 自动注入，多数构建器（Vite / Webpack 5 / Rollup）会自动打包到产物里。若样式没生效，手动 `import '@os-team-11/editor/dist/index.css'` 即可。
+
+## Props
+
+### `BidEditorProps`
+
+| Prop          | 类型                                | 默认值   | 说明                                                   |
+| ------------- | ----------------------------------- | -------- | ------------------------------------------------------ |
+| `bid`         | `BidSchema`                         | -        | **必填**，编辑器数据源                                 |
+| `onChange`    | `(bid: BidSchema) => void`          | -        | 调用 `handle.getBid()` 时触发（读时触发，非实时）      |
+| `readOnly`    | `boolean`                           | `false`  | 只读模式，工具栏隐藏                                   |
+| `toolbar`     | `ToolbarConfig \| false`            | `true`   | 工具栏配置，`false` 完全隐藏                           |
+| `theme`       | `Partial<Theme>`                    | 内置亮色 | 主题覆盖，`{ dark: true }` 切换暗色                    |
+| `renderers`   | `Renderers`                         | -        | 覆盖按钮、下拉、AI 对话等渲染                          |
+| `fieldPanel`  | `boolean`                           | `false`  | 显示右侧字段面板                                       |
+| `ai`          | `AIConfig`                          | -        | AI 问答配置（必传 `ask` 函数才启用）                   |
+| `breakpoint`  | `'mobile' \| 'tablet' \| 'desktop'` | 自动     | 强制断点；`mobile` 隐藏工具栏                          |
+| `className`   | `string`                            | -        | 根容器 class                                           |
+| `style`       | `CSSProperties`                     | -        | 根容器 inline style                                    |
+| `ref`         | `Ref<BidEditorHandle>`              | -        | 命令式 API 句柄                                        |
+
+### `BidEditorHandle`（ref 方法）
+
+| Method       | 签名                | 说明                                                         |
+| ------------ | ------------------- | ------------------------------------------------------------ |
+| `getBid`     | `() => BidSchema`   | 拉取当前文档，触发 `onChange`                                |
+| `getCommand` | `() => unknown`     | 暴露 canvas-editor 的 `command` 对象（执行具体格式化命令）   |
+| `print`      | `() => void`        | 调用浏览器打印，可用于导出 PDF                               |
+| `focus`      | `() => void`        | 当前版本为 noop（canvas-editor 0.9.x 无公开 focus API）     |
+
+## 工具栏配置
+
+`ToolbarConfig` 三种形态：
+
+```tsx
+// 1. 默认全套（36 个按钮分 8 组）
+<BidEditor bid={bid} toolbar={true} />
+
+// 2. 自定义扁平按钮列表
+<BidEditor bid={bid} toolbar={['bold', 'italic', 'underline', '|', 'undo', 'redo']} />
+
+// 3. 按组配置 + 隐藏指定按钮
+<BidEditor
+  bid={bid}
+  toolbar={{
+    hide: ['math', 'comment'],  // 从默认配置里移除指定按钮
+  }}
+/>
+
+// 4. 关闭工具栏
+<BidEditor bid={bid} toolbar={false} />
+```
+
+### 36 个可用按钮 ID
+
+```
+font-family, font-size,
+bold, italic, underline, strikeout, superscript, subscript,
+color, highlight,
+align-left, align-center, align-right, align-justify, line-height,
+h1, h2, h3, h4, list-ol, list-ul, indent, outdent,
+undo, redo, format-painter, clear-format,
+table, image, hyperlink, separator, page-break, math, control, date,
+comment
+```
+
+工具栏宽度超出容器时，溢出的按钮组会自动折叠到「⋯ 更多」下拉，无需手动配置。
+
+## 主题
+
+```tsx
+<BidEditor
+  bid={bid}
+  theme={{
+    dark: true,                       // 切换暗色
+    colors: { primary: '#FF7A00' },   // 覆盖品牌色
+    fontSize: 14,
+  }}
+/>
+```
+
+完整 `Theme` 结构：
+
+```ts
+interface Theme {
+  colors: {
+    primary: string
+    text: string
+    border: string
+    background: string
+    hover: string
+    active: string
+  }
+  radius: { button: number; container: number }
+  spacing: { button: number; group: number }
+  fontSize: number
+  fontFamily: string
+  dark?: boolean
+}
+```
+
+## AI 问答（M5.2）
+
+传入 `ask` 函数即可启用。用户选中文本后右键菜单会出现「AI 问答」选项。
+
+```tsx
+<BidEditor
+  bid={bid}
+  ai={{
+    ask: async ({ selectedText, question, fullDocument }) => {
+      const res = await fetch('/api/ai-ask', {
+        method: 'POST',
+        body: JSON.stringify({ selectedText, question, fullDocument }),
+      })
+      return (await res.json()).answer
+    },
+    label: 'AI 问答',
+    placeholder: '问 AI 任何问题...',
+    includeFullDocument: false,
+  }}
+/>
+```
+
+AI 对话 UI 默认内置，可通过 `renderers.aiDialog` 完全替换。
+
+## 数据结构
+
+### `BidSchema`
+
+```ts
+interface BidSchema {
+  meta: BidMeta
+  page: BidPage
+  sections: BidSection[]
+}
+
+interface BidMeta {
+  title: string
+  docNo: string
+  tenderer: string
+  version: string
+  generatedAt: string
+  generator?: string
+}
+
+interface BidPage {
+  size: 'A4' | 'Letter' | { width: number; height: number }
+  margins: { top: number; right: number; bottom: number; left: number }
+  header?: { template: string; showOnFirstPage: boolean }
+  footer?: { template: string }
+  watermark?: { text: string; opacity: number }
+}
+
+interface BidSection {
+  id: string
+  title: string
+  level: 1 | 2 | 3
+  blocks: BidBlock[]
+}
+
+type BidBlock =
+  | { type: 'heading'; level: 2 | 3 | 4; text: string }
+  | { type: 'paragraph'; text: string }
+  | { type: 'list'; ordered: boolean; items: string[] }
+  | { type: 'table'; rows: string[][]; caption?: string }
+  | { type: 'image'; src: string; alt?: string; caption?: string }
+```
+
+用 `validateBid(sample)` 在渲染前校验数据合法性，避免坏数据导致运行时崩溃。
+
+## 命令式 API 示例
+
+```tsx
+import { useRef } from 'react'
+import { BidEditor, type BidEditorHandle } from '@os-team-11/editor'
+
+function App() {
+  const ref = useRef<BidEditorHandle>(null)
+
+  const handlePrint = () => ref.current?.print()
+  const handleSave = () => {
+    const latest = ref.current?.getBid()  // 触发 onChange
+    // 发送到后端
+  }
+
+  return (
+    <>
+      <button onClick={handlePrint}>打印 / PDF</button>
+      <button onClick={handleSave}>保存</button>
+      <BidEditor ref={ref} bid={bid} />
+    </>
+  )
+}
+```
+
+## 已知限制
+
+- **`onChange` 是读时触发**：仅在调用 `ref.getBid()` 时触发，不是编辑时实时推送。canvas-editor 0.9.x 没有公开的内容变更事件，M6 评估接入事件化。
+- **`bid` prop 对身份敏感**：传入新对象（即使内容相同）会触发 destroy + recreate。父组件频繁重渲染时用 `useState` / `useMemo` 记忆。
+- **`readOnly` 仅隐藏工具栏**：底层 canvas-editor 仍可编辑。完整只读等上游支持，计划 M5.1。
+- **部分命令可能不生效**：`indent` / `outdent` / `comment` 在 canvas-editor 0.9.x 上方法名可能不一致，M5.1 修复。
+
+## 浏览器支持
+
+- Chrome / Edge ≥ 90
+- Safari ≥ 14
+- Firefox ≥ 88
+
+依赖 `ResizeObserver`、`PointerEvent`、CSS Custom Properties。
+
+## 许可证
+
+[MIT](./LICENSE) © os-team-11 contributors
+
+本包基于 [@hufe921/canvas-editor](https://github.com/Hufe921/canvas-editor)（MIT License, © Hufe921）构建。