@composy/keyboard-core 0.0.1 → 0.0.2

package/README.md

@@ -1,37 +1,156 @@
-# @composy/keyboard-core
-
-高性能虚拟键盘组件库，支持 Vue 3，提供字母、数字、车牌号等多种键盘布局
-
-## 功能特性
-
-- 🚀 高性能核心引擎
-- 🎨 TypeScript 类型完整
-- 📦 支持 ESM / CJS 双格式输出
-
-## 安装
-
-```bash
-npm install @composy/keyboard-core
-```
-
-## 快速开始
-
-```typescript
-import { /* 需要的导出 */ } from '@composy/keyboard-core'
-
-// 根据实际 API 使用
-```
-
-## 目录结构
-
-```
-packages/core/
-├── src/              # 源码
-├── package.json
-├── tsconfig.json     # ESM 构建配置
-└── tsconfig.cjs.json # CJS 构建配置
-```
-
-## License
-
-MIT
+# @composy/keyboard-core
+
+基于实际源码能力构建的 **框架无关虚拟键盘核心模块**，是 `@composy/keyboard-workspace` 内
+`@composy/keyboard-vue`
+的底层。本模块不依赖任何 UI 框架，纯 TypeScript 实现，提供键盘状态管理（`KeyboardManager`）、弹出层位置计算（`PositionManager`）、DOM 渲染（`KeyboardRenderer`）、内置/自定义布局注册、主题系统、输入框光标/文本工具与设备检测能力。内置 qwerty、数字、金额、身份证、手机号、车牌号、邮箱、网址、搜索等 20+ 种场景化布局，特别支持车牌号输入时的"省份 → 字母数字"智能切换，适用于 PC 与移动端的下沉式虚拟键盘输入场景。
+
+## 安装
+
+```bash
+# pnpm
+pnpm add @composy/keyboard-core
+
+# npm
+npm install @composy/keyboard-core
+```
+
+> 框架适配（如 Vue 3）请安装对应的 `@composy/keyboard-vue` 适配包，直接消费本核心模块。
+
+## 目录结构
+
+基于真实 `src/` 布局：
+
+```
+src/
+├── index.ts                  # 入口，聚合导出各子模块
+├── managers/                 # keyboard-manager / position-manager / keyboard-renderer
+├── layouts/                  # 20+ 内置布局：qwerty/number/symbol/license-plate/idcard/phone/amount/bankcard/verifycode/email/url/search/punct 等
+├── themes/                   # 主题系统：types.ts / presets.ts / index.ts
+├── types/                    # 类型定义：keyboard.ts / position.ts / index.ts
+├── utils/                    # dom / device / formatters / event-emitter / random
+└── icons.ts                  # 图标
+```
+
+## 核心 API 详表
+
+### 类（Manager）
+
+| 名称               | 类型 | 签名                                                                                        | 用途                                                                                   |
+| ------------------ | ---- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `KeyboardManager`  | 类   | `new KeyboardManager(options: KeyboardOptions = {})`，继承 `EventEmitter<KeyboardEventMap>` | 键盘状态管理核心：显示/隐藏、大小写切换、按键处理、绑定输入框、车牌号智能切换          |
+| `PositionManager`  | 类   | `new PositionManager(config: PopupPositionConfig = {})`                                     | 计算键盘弹出层位置，支持移动端 bottom-sheet、PC 端 top/bottom 自适应翻转与视口边界调整 |
+| `KeyboardRenderer` | 类   | `new KeyboardRenderer(options: KeyboardRendererOptions = {})`                               | 框架无关的键盘 DOM 渲染器：创建 DOM、注入样式、绑定输入框、管理主题与位置              |
+
+### 工厂函数
+
+| 名称                     | 类型 | 签名                                                      | 用途                |
+| ------------------------ | ---- | --------------------------------------------------------- | ------------------- |
+| `createKeyboardManager`  | 函数 | `(options?: KeyboardOptions) => KeyboardManager`          | 创建键盘管理器实例  |
+| `createPositionManager`  | 函数 | `(config?: PopupPositionConfig) => PositionManager`       | 创建位置管理器实例  |
+| `createKeyboardRenderer` | 函数 | `(options?: KeyboardRendererOptions) => KeyboardRenderer` | 创建 DOM 渲染器实例 |
+
+### 布局函数
+
+| 名称                  | 类型 | 签名                                                          | 用途                                 |
+| --------------------- | ---- | ------------------------------------------------------------- | ------------------------------------ |
+| `registerLayout`      | 函数 | `(name: string, layout: KeyboardConfig): void`                | 注册自定义布局（不允许覆盖内置布局） |
+| `registerLayouts`     | 函数 | `(layouts: Record<string, KeyboardConfig>): void`             | 批量注册自定义布局                   |
+| `unregisterLayout`    | 函数 | `(name: string): boolean`                                     | 移除自定义布局，返回是否成功         |
+| `getLayout`           | 函数 | `(type: KeyboardType \| string): KeyboardConfig \| undefined` | 按类型或名称获取布局配置             |
+| `getAvailableLayouts` | 函数 | `(): string[]`                                                | 获取所有可用布局名称数组             |
+| `hasLayout`           | 函数 | `(name: string): boolean`                                     | 判断布局是否存在                     |
+
+### 常量（布局与数据）
+
+| 名称                                                                                                                                                                            | 类型 | 签名             | 用途                                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| `qwertyLayout`/`numberLayout`/`integerLayout`/`symbolLayout`/`symbolLayout2`                                                                                                    | 常量 | `KeyboardConfig` | 标准字母 / 数字 / 整数 / 两种符号布局                                                                       |
+| `licensePlateLayout` 等                                                                                                                                                         | 常量 | `KeyboardConfig` | 车牌号系列（另有 `licensePlateProvinceLayout`/`licensePlateLetterLayout`/`licensePlateAlphanumericLayout`） |
+| `idcardLayout`/`phoneLayout`/`phoneSimpleLayout`/`amountLayout`/`amountSimpleLayout`/`bankcardLayout`/`verifycodeLayout`/`emailLayout`/`urlLayout`/`searchLayout`/`punctLayout` | 常量 | `KeyboardConfig` | 场景化与输入场景键盘布局                                                                                    |
+| `PROVINCES`/`PLATE_LETTERS`/`EMAIL_SUFFIXES`                                                                                                                                    | 常量 | `string[]`       | 车牌省份简称数组 / 车牌允许字母数组 / 常用邮箱后缀数组                                                      |
+
+### 类型
+
+| 名称                            | 类型 | 签名                                                                                                                                    | 用途                                                                                    |
+| ------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `KeyboardType`                  | 类型 | `qwerty`/`number`/`integer`/`symbol`/`license-plate`/`idcard`/`phone`/`amount`/`bankcard`/`verifycode`/`email`/`url`/`search` 等 20+ 种 | 键盘类型联合类型                                                                        |
+| `KeyType`                       | 类型 | `char`/`backspace`/`shift`/`space`/`enter`/`tab`/`close`/`clear`/`done`/`custom`                                                        | 按键类型                                                                                |
+| `KeyDefinition` / `KeyboardRow` | 接口 | —                                                                                                                                       | 单个按键定义（id/type/label/value/width/icon/options/data）/ 键盘行（keys + className） |
+| `KeyboardConfig`                | 接口 | —                                                                                                                                       | 键盘布局配置（type/name/rows/supportShift/switchable）                                  |
+| `KeyboardState`                 | 接口 | —                                                                                                                                       | 键盘运行时状态（visible/type/isUpperCase/value/cursorPosition/maxLength）               |
+| `KeyboardEventMap`              | 接口 | —                                                                                                                                       | 事件映射：keypress/input/backspace/clear/confirm/show/hide/switch/shift/stateChange     |
+| `KeyboardOptions`               | 接口 | —                                                                                                                                       | 键盘选项（type/value/maxLength/customLayouts/enableVibrate 等）                         |
+
+> 另有 `PopupPlacement`、`PopupPositionConfig`、`PopupPositionResult`、`Position`、`BoundingRect`
+> 及 DOM/设备工具函数等由各子模块通过 `export *` 一并导出，均以 `src/index.ts` 实际导出为准。
+
+## 使用示例
+
+直接使用 DOM 渲染器（框架无关）：
+
+```ts
+import {
+  createKeyboardRenderer,
+  getAvailableLayouts,
+  KeyboardManager,
+} from '@composy/keyboard-core'
+
+// 渲染器：绑定输入框并自动管理 DOM/位置/主题
+const input = document.querySelector<HTMLInputElement>('#plate')
+if (!input) throw new Error('Missing #plate input')
+const keyboard = createKeyboardRenderer({
+  type: 'license-plate', // 车牌号键盘（自动省份→字母数字切换）
+  maxLength: 8,
+  enableVibrate: true,
+  onInput: v => console.info('输入:', v),
+  onConfirm: v => console.info('确认:', v),
+})
+keyboard.bindInput(input) // 聚焦时自动打开，阻止原生键盘
+keyboard.open(input)
+keyboard.setValue('京')
+keyboard.destroy()
+
+// 底层管理器：手动控制状态
+const manager = new KeyboardManager({ type: 'qwerty', maxLength: 6 })
+manager.on('confirm', ({ value }) => console.info(value))
+manager.show()
+manager.handleKey({ id: 'a', type: 'char', label: { lower: 'a', upper: 'A' } })
+console.info(getAvailableLayouts())
+manager.destroy()
+```
+
+## 构建脚本 & 验证命令
+
+```bash
+pnpm build          # 构建产物（es/lib/esm/dist）
+pnpm type-check     # 类型检查
+pnpm type-check:cjs # CJS 配置类型检查
+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/` | 浏览器 UMD/IIFE 压缩产物          | `unpkg` / `jsdelivr` / `browser`      |
+
+`sideEffects: false` 便于 tree-shaking。`exports`
+提供子路径：`./layouts`、`./managers`、`./themes`、`./types`、`./utils`（均支持通配符深层路径）。
+
+## 备注
+
+- **框架无关 / peerDeps**：纯核心逻辑，不绑定 React/Vue，无运行期第三方依赖；框架适配由上层
+  `@composy/keyboard-vue` 等提供，`devDependencies` 仅含构建/测试工具。
+- **车牌号智能切换**：使用 `license-plate`
+  键盘时，会根据当前输入长度自动在省份键盘（第 1 位）与字母数字键盘（第 2-8 位）之间切换。
+- **自定义布局**：通过 `registerLayout`/`registerLayouts`
+  注册，内置布局不可被同名覆盖（会打印告警）。
+- **主题系统**：渲染器支持通过 `theme` 传入主题名或
+  `ThemeConfig`，应用 CSS 变量（`--keyboard-*`）实现皮肤定制。