@kaitify/react 0.0.1-beta.1

package/docs/.vitepress/config.ts

@@ -0,0 +1,185 @@
+import { defineConfig } from 'vitepress'
+import path from 'path'
+import fs from 'fs'
+
+const getMenuList = () => {
+  const items = fs.readdirSync(path.resolve(__dirname, '../../src/editor/menu/built-in'))
+  const folderNames: string[] = []
+  for (const item of items) {
+    const itemPath = path.join(path.resolve(__dirname, '../../src/editor/menu/built-in'), item)
+    const stats = fs.statSync(itemPath)
+    if (stats.isDirectory()) {
+      folderNames.push(item)
+    }
+  }
+  const menuNames: string[] = []
+  folderNames.forEach(item => {
+    const list = fs.readdirSync(path.resolve(__dirname, `../../src/editor/menu/built-in/${item}`))
+    for (const el of list) {
+      if (el.endsWith('.tsx')) {
+        const lastIndex = el.lastIndexOf('.tsx')
+        const name = el.substring(0, lastIndex)
+        menuNames.push(name)
+        //创建内置菜单的md文件
+        const docPath = path.join(path.resolve(__dirname, '../../docs/menus/built-in'), `${name}.md`)
+        if (!fs.existsSync(docPath)) {
+          fs.writeFileSync(docPath, '', { encoding: 'utf-8' })
+        }
+      }
+    }
+  })
+  return menuNames
+}
+
+export default defineConfig({
+  base: '/docs/kaitify-react/',
+  title: 'kaitify-react',
+  description: '一个基于@kaitify/core开发的react富文本编辑器核心库',
+  lastUpdated: true,
+  cleanUrls: true,
+  head: [
+    ['link', { rel: 'icon', type: 'image/png', href: 'https://www.so-better.cn/docs/kaitify-core/logo.png' }],
+    ['meta', { name: 'viewport', content: 'width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no' }]
+  ],
+  outDir: 'kaitify-react',
+  themeConfig: {
+    logo: {
+      src: 'https://www.so-better.cn/docs/kaitify-core/logo.png'
+    },
+    outline: {
+      label: '本页目录',
+      level: [2, 5]
+    },
+    nav: [
+      { text: '指南', link: '/guide/introduction', activeMatch: '/guide' },
+      { text: '内置菜单', link: '/menus/introduction', activeMatch: '/menus' },
+      {
+        text: '在线体验',
+        link: 'https://www.so-better.cn/run?lib=kaitify-react',
+        target: '_blank'
+      },
+      { text: '更新日志', link: '/changelog' }
+    ],
+    sidebar: {
+      '/guide': [
+        {
+          text: '开始使用',
+          items: [
+            {
+              text: '简介',
+              link: '/guide/introduction'
+            },
+            {
+              text: '安装',
+              link: '/guide/install'
+            },
+            {
+              text: '快速上手',
+              link: '/guide/quick-start'
+            }
+          ]
+        },
+        {
+          text: '组件',
+          items: [
+            {
+              text: 'Wrapper',
+              link: '/guide/wrapper'
+            },
+            {
+              text: 'Bubble',
+              link: '/guide/bubble'
+            },
+            {
+              text: 'Menu',
+              link: '/guide/menu'
+            },
+            {
+              text: 'Divider',
+              link: '/guide/divider'
+            },
+            {
+              text: 'Tabs',
+              link: '/guide/tabs'
+            },
+            {
+              text: 'Checkbox',
+              link: '/guide/checkbox'
+            },
+            {
+              text: 'Icon',
+              link: '/guide/icon'
+            }
+          ]
+        },
+        {
+          text: '其他',
+          items: [
+            {
+              text: '菜单快捷键',
+              link: '/guide/shortcut'
+            },
+            {
+              text: '国际化支持',
+              link: '/guide/locale'
+            }
+          ]
+        }
+      ],
+      '/menus': [
+        {
+          text: '开始使用',
+          items: [
+            {
+              text: '简介',
+              link: '/menus/introduction'
+            }
+          ]
+        },
+        {
+          text: '内置菜单',
+          items: getMenuList().map(name => {
+            return {
+              text: name,
+              link: `/menus/built-in/${name}`
+            }
+          })
+        }
+      ]
+    },
+    socialLinks: [
+      { icon: 'npm', link: 'https://www.npmjs.com/package/@kaitify/react' },
+      { icon: 'gitee', link: 'https://gitee.com/so-better/kaitify-react' },
+      { icon: 'github', link: 'https://github.com/so-better/kaitify-react' }
+    ],
+    search: { provider: 'local' },
+    lastUpdated: {
+      text: '上次更新'
+    },
+    docFooter: {
+      prev: 'Prev',
+      next: 'Next'
+    },
+    darkModeSwitchTitle: '切换到深色模式',
+    lightModeSwitchTitle: '切换到浅色模式',
+    darkModeSwitchLabel: '主题风格切换',
+    sidebarMenuLabel: '菜单目录',
+    returnToTopLabel: '返回顶部',
+    externalLinkIcon: true
+  },
+  markdown: {
+    image: {
+      lazyLoading: true
+    },
+    theme: {
+      dark: 'github-dark',
+      light: 'github-light'
+    },
+    codeCopyButtonTitle: '复制代码'
+  },
+  vite: {
+    server: {
+      port: 5401
+    }
+  }
+})

package/docs/.vitepress/global.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/docs/.vitepress/theme/index.ts

@@ -0,0 +1,6 @@
+import DefaultTheme from 'vitepress/theme'
+import './style.less'
+
+export default {
+  extends: DefaultTheme
+}

package/docs/.vitepress/theme/style.less

@@ -0,0 +1,17 @@
+:root {
+  --vp-home-hero-name-background: linear-gradient(120deg, #8b1bbf 20%, #308af3);
+  --vp-home-hero-name-color: transparent;
+  --vp-c-indigo-1: #1269cd;
+  --vp-c-indigo-2: #1e79e1;
+  --vp-c-indigo-3: #308af3;
+
+  --vp-code-block-bg: #f7f8fa;
+
+  h5 > .VPBadge.danger {
+    font-family: var(--vp-font-family-mono);
+  }
+
+  &.dark {
+    --vp-code-block-bg: #1f1f22;
+  }
+}

package/docs/.vitepress/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "target": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "preserve",
+    "strict": true,
+    "isolatedModules": true,
+    "skipLibCheck": true
+  },
+  "include": ["./**/*.ts", "./**/*.d.ts"]
+}

package/docs/changelog.md

@@ -0,0 +1,10 @@
+---
+lastUpdated: false
+title: 更新日志
+---
+
+# 更新日志
+
+## v0.0.1-beta.1 <Badge type="tip" text='2025.10.30' />
+
+- kaitify-react 的第一个发布版本

package/docs/guide/bubble.md

@@ -0,0 +1,71 @@
+---
+title: Bubble 气泡栏
+---
+
+# Bubble 气泡栏
+
+`Bubble` 组件是 `kaitify-react` 的内置组件，必须放置在 `Wrapper` 组件的 `children` 中
+
+## Props 参数
+
+##### visible <Badge type="danger" text="boolean" />
+
+是否显示气泡栏，默认为 `false`
+
+##### match <Badge type="danger" text="KNodeMatchOptionType" />
+
+指定气泡栏出现的位置条件，每次更新气泡位置时会判断光标是否在符合条件的节点下，如果符合则根据该节点的真实 `dom` 进行定位，否则只根据光标位置进行定位
+
+关于该属性的释义，同 [kaitify 中的 Editor 的 getMatchNodeBySelection 方法中的入参](https://www.so-better.cn/docs/kaitify-core/apis/editor-function#getmatchnodebyselection)
+
+##### hideOnMousedown <Badge type="danger" text="boolean" />
+
+鼠标在编辑器内按下时是否隐藏气泡栏，默认为 `false`，如果该值为 `true`，在鼠标按下时即使 `visible` 属性是 `true`，也无法显示气泡栏
+
+##### children <Badge type="danger" text="ReactNode" />
+
+气泡栏的子组件
+
+##### style <Badge type="danger" text="CSSProperties" />
+
+气泡栏的样式
+
+##### className <Badge type="danger" text="string" />
+
+气泡栏的样式类
+
+##### onShow <Badge type="danger" text="(el: Element) => void" />
+
+气泡栏显示前触发的事件
+
+##### onShowing <Badge type="danger" text="(el: Element) => void" />
+
+气泡栏显示时触发的事件
+
+##### onShown <Badge type="danger" text="(el: Element) => void" />
+
+气泡栏显示后触发的事件
+
+##### onHide <Badge type="danger" text="(el: Element) => void" />
+
+气泡栏隐藏前触发的事件
+
+##### onHiding <Badge type="danger" text="(el: Element) => void" />
+
+气泡栏隐藏时触发的事件
+
+##### onHidden <Badge type="danger" text="(el: Element) => void" />
+
+气泡栏隐藏后触发的事件
+
+## API 组件属性/方法
+
+`Bubble` 提供了部分属性/方法可以通过组件实例来调用
+
+##### elRef <Badge type="danger" text="React.MutableRefObject<HTMLDivElement | null>" />
+
+获取组件实例即气泡栏的 `dom` 元素
+
+##### popperInstance <Badge type="danger" text="React.MutableRefObject<Instance | null>" />
+
+`popperjs` 创建的浮层实例对象

package/docs/guide/checkbox.md

@@ -0,0 +1,38 @@
+---
+title: Checkbox 复选框
+---
+
+# Checkbox 复选框
+
+`Checkbox` 组件是 `kaitify-react` 的一个 `UI` 组件，该组件与编辑器具体的功能无关，它一般用于带浮层的菜单中，用来进行勾选
+
+## 基本使用
+
+```tsx
+import { useState } from 'react'
+import { Checkbox } from '@kaitify/react'
+
+export default function App() {
+  const [checked, setChecked] = useState(false)
+
+  return <Checkbox label='我是复选框' checked={checked} onChange={setChecked} />
+}
+```
+
+## Props 参数
+
+##### checked <Badge type="danger" text="boolean" />
+
+复选框的值
+
+##### onChange <Badge type="danger" text="(checked: boolean) => void" />
+
+复选框选择事件
+
+##### disabled <Badge type="danger" text="boolean" />
+
+复选框是否禁用
+
+##### label <Badge type="danger" text="string" />
+
+复选框右侧显示的文字内容

package/docs/guide/divider.md

@@ -0,0 +1,41 @@
+---
+title: Divider 菜单分隔线
+---
+
+# Divider 菜单分隔线
+
+`Divider` 组件是 `kaitify-react` 的一个 `UI` 组件，该组件与编辑器具体的功能无关，它仅仅是为了排列多个 `Menu` 组件时，能够更好的为 `Menu` 组件划区
+
+因此，`Divider` 组件是放置在 `Menu` 组件之间的
+
+## 基本使用
+
+```tsx
+import { useState } from 'react'
+import { Wrapper, Menu, Divider } from '@kaitify/react'
+
+export default function App() {
+  const [content, setContent] = useState('<p>hello</p>')
+  return (
+    <Wrapper
+      value={content}
+      onChange={v => setContent(v)}
+      placeholder='输入正文内容...'
+      before={
+        <>
+          <Menu>菜单1</Menu>
+          <Menu>菜单2</Menu>
+          <Menu>菜单3</Menu>
+          <Divider />
+          <Menu>菜单4</Menu>
+          <Menu>菜单5</Menu>
+          <Menu>菜单6</Menu>
+          <Divider />
+          <Menu>菜单7</Menu>
+          <Menu>菜单8</Menu>
+        </>
+      }
+    ></Wrapper>
+  )
+}
+```

package/docs/guide/icon.md

@@ -0,0 +1,34 @@
+---
+title: Icon 图标
+---
+
+# Icon 图标
+
+`Icon` 组件是 `kaitify-react` 的一个 `UI` 组件，通过该组件你可以在你想要的地方展示不同的图标
+
+## 基本使用
+
+```tsx
+import { Icon } from '@kaitify/react'
+export default function App() {
+  return <Icon name='solar:home-bold-duotone' />
+}
+```
+
+## Props 参数
+
+##### name <Badge type="danger" text="string" />
+
+图标的值，目前仅支持 `kaitify` 内置图标（暂不对外提供具体的使用）和 `@iconify/react` 图标，可在[https://icon-sets.iconify.design/](https://icon-sets.iconify.design/)上查找你想用的图标并复制其 `name` 使用
+
+##### size <Badge type="danger" text="string | number" />
+
+图标的大小，如果是数字默认单位为 `px`，默认图标大小为父元素的字体大小
+
+##### style <Badge type="danger" text="CSSProperties" />
+
+图标的额外样式
+
+##### className <Badge type="danger" text="string" />
+
+图标的样式类

package/docs/guide/install.md

@@ -0,0 +1,70 @@
+---
+title: 安装
+---
+
+# 安装
+
+## 下载 kaitify-react 本地到使用
+
+- 下载地址：[kaitify-react](https://registry.npmmirror.com/@kaitify/react/download/@kaitify/react-0.0.1-beta.1.tgz)
+- 下载完成后最终解压得到一个 package 文件夹，进入 package 文件夹后，将 package 目录下的整个 lib 目录拷贝到你的项目下
+- 在 html 页面中引入 js
+
+```html
+<!-- 使用全局构建版本 -->
+<script src="lib/kaitify-react.umd.js" type="text/javascript"></script>
+```
+
+```html
+<!-- 使用es模块构建版本 -->
+<script type="module">
+  import { Wrapper } from 'lib/kaitify-react.es.js'
+</script>
+```
+
+## 通过 CDN 使用 kaitify-react
+
+你可以借助 `script` 标签直接通过 CDN 来使用 `kaitify-react`
+
+```html
+<!-- 引入固定版本的kaitify -->
+<script src="https://unpkg.com/@kaitify/react@0.0.1-beta.1/lib/kaitify-react.umd.js"></script>
+<!-- 始终引入最新的kaitify -->
+<script src="https://unpkg.com/@kaitify/react/lib/kaitify-react.umd.js"></script>
+```
+
+```html
+<!-- 使用CDN上的es模块构建版本 -->
+<script type="module">
+  import { Wrapper } from 'https://unpkg.com/@kaitify/react/lib/kaitify-react.es.js'
+</script>
+```
+
+## 通过 npm/yarn/pnpm 安装 kaitify-react
+
+> 假设你已了解关于  html、css  和  javascript  的中级知识，并且对于 npm，es6，webpack 已经有了足够的了解，我们更推荐这类安装方式
+
+::: code-group
+
+```bash [npm]
+npm install @kaitify/react
+
+# 安装指定版本
+npm install @kaitify/react@0.0.1-beta.1
+```
+
+```bash [yarn]
+yarn install @kaitify/react
+
+# 安装指定版本
+yarn install @kaitify/react@0.0.1-beta.1
+```
+
+```bash [pnpm]
+pnpm install @kaitify/react
+
+# 安装指定版本
+pnpm install @kaitify/react@0.0.1-beta.1
+```
+
+:::

package/docs/guide/introduction.md

@@ -0,0 +1,28 @@
+---
+title: 简介
+---
+
+# 简介
+
+## 前言
+
+`kaitify-react` 是一套基于 `kaitify` 富文本编辑器核心库进行开发和设计的富文本编辑器，使用 `React` 框架作视图渲染，并提供相关的组件供开发者使用
+
+本文档不再对 `kaitify` 进行赘述，关于编辑器底层的核心理念，在 `kaitify` 文档中都有讲述，如果你对 `kaitify` 有兴趣，可以访问 [@kaitify/core 文档](https://www.so-better.cn/docs/kaitify-core/)，获取进一步的了解
+
+## 结合 React
+
+`kaitify` 是一个基于原生 `js` 的富文本编辑器核心库，在 `React` 项目中进行使用的话，可能需要进行一些组件的封装，并且需要为更好地与 `React` 结合而进行开发与设计
+
+`kaitify-react` 的目的就是为了帮助开发者解决这一问题，减少一些基本工作，同时提供了可以直接拿来使用的必要组件，并且设计了一套基本的 `UI` 样式
+
+`kaitify-react` 最低支持的 react 版本是 react 18
+
+## 视图渲染
+
+`kaitify` 的视图渲染采用完全原生 `js` 的写法，我们称之为 `js-render`，而在 `kaitify-react` 中，我们自定义了视图渲染的逻辑，采用 `React` 的 `ReactNode` 来作视图渲染
+
+因此编辑器本身不关心视图如何进行渲染，只需要专注于内部逻辑的处理，视图渲染的部分我们完全交给 `React` 去处理
+
+> [!TIP] 怎么样？
+> 接下来去更详细地了解 `kaitify-react` 是怎么使用的吧~

package/docs/guide/locale.md

@@ -0,0 +1,67 @@
+---
+title: 国际化支持
+---
+
+# 国际化支持
+
+`kaitify-react` 默认为中文环境，即显示的相关文字都是中文
+
+同时支持英文和日语、韩语环境，即显示的相关文字都是英文、日语、韩语
+
+## 中文环境
+
+`Wrapper` 组件的 `locale` 属性设置为 `zh-CN` 或者不设置
+
+```tsx
+import { useState } from 'react'
+import { Wrapper } from '@kaitify/react'
+
+export default function App() {
+  const [content, setContent] = useState('<p>hello</p>')
+  return <Wrapper locale='zh-CN' value={content} onChange={v => setContent(v)} placeholder='输入正文内容...'></Wrapper>
+}
+```
+
+## 英文环境
+
+`Wrapper` 组件的 `locale` 属性设置为 `en-US`
+
+```tsx
+import { useState } from 'react'
+import { Wrapper } from '@kaitify/react'
+
+export default function App() {
+  const [content, setContent] = useState('<p>hello</p>')
+  return <Wrapper locale='en-US' value={content} onChange={v => setContent(v)} placeholder='输入正文内容...'></Wrapper>
+}
+```
+
+## 韩语环境
+
+`Wrapper` 组件的 `locale` 属性设置为 `ko-KR`
+
+```tsx
+import { useState } from 'react'
+import { Wrapper } from '@kaitify/react'
+
+export default function App() {
+  const [content, setContent] = useState('<p>hello</p>')
+  return <Wrapper locale='ko-KR' value={content} onChange={v => setContent(v)} placeholder='输入正文内容...'></Wrapper>
+}
+```
+
+## 日语环境
+
+`Wrapper` 组件的 `locale` 属性设置为 `ja-JP`
+
+```tsx
+import { useState } from 'react'
+import { Wrapper } from '@kaitify/react'
+
+export default function App() {
+  const [content, setContent] = useState('<p>hello</p>')
+  return <Wrapper locale='ja-JP' value={content} onChange={v => setContent(v)} placeholder='输入正文内容...'></Wrapper>
+}
+```
+
+编辑器自身可能体现不出来中英文环境的差别，`kaitify-react` 提供了内置的 `Menu`，当设置 `locale` 为 `en-US` 后，这些内置 `Menu` 中的汉字都会转为英文，其他语言同理