@aiao/code-editor-vue 0.0.23 → 0.0.25

package/README.md

@@ -14,7 +14,6 @@ pnpm add @aiao/code-editor-vue
 <script lang="ts" setup>
 import { ref } from 'vue';
 import { CodeEditor } from '@aiao/code-editor-vue';
-import '@aiao/code-editor-vue/style.css';
 
 const code = ref('const answer = 42;');
 </script>
@@ -51,7 +50,8 @@ const code = ref('const answer = 42;');
 | `autoFocus`           | `boolean`                                  | `false`             | 仅初始化时读取       |
 | `root`                | `Document \| ShadowRoot`                   | `undefined`         | 仅初始化时传给编辑器 |
 
-空字符串或 `plaintext` 会清空语言扩展。未知语言和加载失败会报告错误并保持纯文本状态。快速切换语言时，只有最后一次请求可以更新当前编辑器。
+空字符串或 `plaintext` 会清空语言扩展。未知语言和加载失败会**降级为纯文本**并发出 `language-error`
+（见下），编辑器本身继续可用。快速切换语言时，只有最后一次请求可以更新当前编辑器。
 
 自定义语言列表使用核心包的公开类型：
 
@@ -68,15 +68,77 @@ const languages: readonly CodeEditorLanguageDescription[] = [myLanguage];
 
 ## Events
 
-| 事件           | 参数              | 触发时机               |
-| -------------- | ----------------- | ---------------------- |
-| `update:value` | `(value: string)` | 用户修改文档           |
-| `change`       | `(value: string)` | 用户修改文档           |
-| `focus`        | `()`              | 编辑器内容区域获得焦点 |
-| `blur`         | `()`              | 编辑器内容区域失去焦点 |
+| 事件             | 参数                               | 触发时机                                                   |
+| ---------------- | ---------------------------------- | ---------------------------------------------------------- |
+| `update:value`   | `(value: string)`                  | 用户修改文档                                               |
+| `change`         | `(value: string)`                  | 用户修改文档                                               |
+| `focus`          | `()`                               | 编辑器内容区域获得焦点                                     |
+| `blur`           | `()`                               | 编辑器内容区域失去焦点                                     |
+| `language-error` | `(error: CodeEditorLanguageError)` | 语言查不到（`not-found`）或 `load()` 失败（`load-failed`） |
+
+## 语言错误
+
+降级为纯文本时编辑器仍然可用，但宿主需要能观测到这件事 —— `language-error` 就是这个通道：
+
+```vue
+<script lang="ts" setup>
+import type { CodeEditorLanguageError } from '@aiao/code-editor';
+import { CodeEditor } from '@aiao/code-editor-vue';
+
+function onLanguageError(error: CodeEditorLanguageError) {
+  // 'not-found' 是配置错误，重试没有意义；'load-failed' 通常是网络或分包问题，可以重试。
+  if (error.kind === 'load-failed') retry(error.language);
+}
+</script>
+
+<template>
+  <CodeEditor :language="lang" @language-error="onLanguageError" />
+</template>
+```
+
+载荷形状（`kind` / `language` / `message` / `cause`）由核心包定义，三端一致：
+Angular 是 `(aoLanguageError)` 输出，React 是 `onLanguageError` 回调。
+
+## 模板 ref 用法
+
+组件通过 `defineExpose` 暴露命令式 API，供模板 ref 访问底层 `EditorView`：
+
+```vue
+<script lang="ts" setup>
+import { ref } from 'vue';
+import { CodeEditor } from '@aiao/code-editor-vue';
+import type { CodeEditorExpose } from '@aiao/code-editor-vue';
+
+const editorRef = ref<CodeEditorExpose | null>(null);
+const code = ref('const answer = 42;');
+
+function focusEditor() {
+  editorRef.value?.focus();
+}
+</script>
+
+<template>
+  <CodeEditor v-model:value="code" ref="editorRef" />
+</template>
+```
+
+四个成员与 React 的 `CodeEditorHandle`、Angular 组件实例上的同名成员逐字对齐，跨端迁移时命令式面不需要改写：
+
+| 成员    | 类型                     | 说明                                            |
+| ------- | ------------------------ | ----------------------------------------------- |
+| `view`  | `EditorView \| null`     | 底层 CodeMirror 实例，未挂载或已卸载时为 `null` |
+| `host`  | `HTMLDivElement \| null` | 宿主 `div` 元素，未挂载或已卸载时为 `null`      |
+| `focus` | `() => void`             | 聚焦编辑器内容区域                              |
+| `blur`  | `() => void`             | 使编辑器内容区域失焦                            |
 
 ## 公开类型
 
 ```ts
-import type { CodeEditorEmits, CodeEditorProps, CodeEditorSetup, CodeEditorTheme } from '@aiao/code-editor-vue';
+import type {
+  CodeEditorEmits,
+  CodeEditorExpose,
+  CodeEditorProps,
+  CodeEditorSetup,
+  CodeEditorTheme
+} from '@aiao/code-editor-vue';
 ```

package/dist/CodeEditor.vue.d.ts

@@ -1,22 +1,27 @@
-import { CodeEditorProps, CodeEditorSetup } from './code-editor.types.js';
-declare const __VLS_export: import('vue').DefineComponent<CodeEditorProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+import { CodeEditorExpose, CodeEditorProps, CodeEditorSetup } from './code-editor.types.js';
+declare const __VLS_export: import('vue').DefineComponent<CodeEditorProps, CodeEditorExpose, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
     blur: () => any;
     change: (value: string) => any;
     focus: () => any;
+    "language-error": (error: import('@aiao/code-editor').CodeEditorLanguageError) => any;
     "update:value": (value: string) => any;
 }, string, import('vue').PublicProps, Readonly<CodeEditorProps> & Readonly<{
     onBlur?: (() => any) | undefined;
     onChange?: ((value: string) => any) | undefined;
     onFocus?: (() => any) | undefined;
+    "onLanguage-error"?: ((error: import('@aiao/code-editor').CodeEditorLanguageError) => any) | undefined;
     "onUpdate:value"?: ((value: string) => any) | undefined;
 }>, {
     readonly autoFocus: boolean;
+    readonly describedBy: string;
     readonly disabled: boolean;
     readonly highlightWhitespace: boolean;
     readonly indentUnit: string;
     readonly indentWithTab: boolean;
     readonly language: string;
     readonly languages: readonly import('@aiao/code-editor').CodeEditorLanguageDescription[];
+    readonly label: string;
+    readonly labelledBy: string;
     readonly lineWrapping: boolean;
     readonly placeholder: string;
     readonly readonly: boolean;

package/dist/CodeEditor.vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CodeEditor.vue.d.ts","sourceRoot":"","sources":["../src/CodeEditor.vue"],"names":[],"mappings":"AAuQA,OAAO,KAAK,EAAmB,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAkQhG,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;6EAIhB,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}
+{"version":3,"file":"CodeEditor.vue.d.ts","sourceRoot":"","sources":["../src/CodeEditor.vue"],"names":[],"mappings":"AAuVA,OAAO,KAAK,EAAmB,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AA8UlH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6EAKhB,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}

package/dist/code-editor.types.d.ts

@@ -1,29 +1,173 @@
-import { CodeEditorLanguageDescription, CodeEditorTheme } from '@aiao/code-editor';
+import { CodeEditorLanguageDescription, CodeEditorLanguageError, CodeEditorTheme } from '@aiao/code-editor';
+import { EditorView } from '@codemirror/view';
 /** CodeMirror 预置扩展集合。 */
 export type CodeEditorSetup = 'basic' | 'minimal' | null;
-/** Vue CodeEditor 的公开属性。 */
+/**
+ * Vue CodeEditor 的公开属性。
+ *
+ * @remarks 与 Angular 的 inputs、React 的 props 同名同义；仅初始化生效的两项
+ * （{@link CodeEditorProps.autoFocus} / {@link CodeEditorProps.root}）在各自条目上标注。
+ */
 export interface CodeEditorProps {
+    /**
+     * 挂载后立即聚焦编辑器。
+     *
+     * @defaultValue false
+     * @remarks **仅挂载时读取一次**，后续变更被忽略。`disabled` 或 `readonly` 为真时
+     * 不抢焦点 —— 否则用户得到一个无法输入、也无从得知为什么无法输入的控件。
+     */
     readonly autoFocus?: boolean;
+    /**
+     * 补充说明元素的 id，写成内部 textbox 的 `aria-describedby`。
+     *
+     * @remarks 属性落在 CodeMirror 的 `.cm-content` 上 —— 承担 `role="textbox"` 的是它，
+     * 不是组件的宿主元素。空串按「未设置」处理。三端同名同义。
+     */
+    readonly describedBy?: string;
+    /**
+     * 禁用：只读且不可编辑，并向辅助技术报告 `aria-disabled`。
+     *
+     * @defaultValue false
+     * @remarks 与 `readonly` 是独立的两个属性，任一为真都会让编辑器不可编辑；
+     * 区别在于禁用还会写出 `aria-disabled` 并抑制 `autoFocus`。
+     */
     readonly disabled?: boolean;
+    /**
+     * 显示空白字符。
+     *
+     * @defaultValue false
+     */
     readonly highlightWhitespace?: boolean;
+    /**
+     * 一级缩进使用的字符串。
+     *
+     * @defaultValue '  '（两个空格，三端一致）
+     */
     readonly indentUnit?: string;
+    /**
+     * 允许 Tab 键缩进。
+     *
+     * @defaultValue false
+     * @remarks 打开后 Tab 不再移动焦点，键盘用户会被困在编辑器里 —— 这是可达性取舍，
+     * 三端默认一致地关闭。
+     */
     readonly indentWithTab?: boolean;
+    /**
+     * 语法高亮语言名或别名；`''` 与 `'plaintext'` 表示不高亮。
+     *
+     * @defaultValue 'sql'
+     * @remarks 查不到或 `load()` 失败时**降级为纯文本**并继续可用，同时发出
+     * `language-error` 事件（见 {@link CodeEditorEmits}）。快速切换时只有最后一次请求生效。
+     */
     readonly language?: string;
+    /**
+     * 候选语言列表；空列表表示不高亮。
+     *
+     * @defaultValue SUPPORT_LANGUAGES
+     * @remarks 传内联字面量（`:languages="[myLang]"`）是有成本的：每轮更新都是新数组，
+     * 而 `watch` 按引用触发。组件会再判断当前语言解析到的 description 是否真的换了 ——
+     * 只有真换了才重新 `load()`，但这层判断本身仍要跑，稳定引用（模块级常量或 `computed`）更省。
+     */
     readonly languages?: readonly CodeEditorLanguageDescription[];
+    /**
+     * 可访问名称，写成内部 textbox 的 `aria-label`。
+     *
+     * @remarks 落点与 {@link CodeEditorProps.describedBy} 相同。
+     */
+    readonly label?: string;
+    /**
+     * 承担标签的元素 id，写成内部 textbox 的 `aria-labelledby`。
+     *
+     * @remarks 落点与 {@link CodeEditorProps.describedBy} 相同。
+     */
+    readonly labelledBy?: string;
+    /**
+     * 自动换行。
+     *
+     * @defaultValue false
+     */
     readonly lineWrapping?: boolean;
+    /**
+     * 空文档时显示的占位文本。
+     *
+     * @defaultValue ''
+     */
     readonly placeholder?: string;
+    /**
+     * 只读：仍可聚焦、可选择、可复制，但不能改。
+     *
+     * @defaultValue false
+     * @remarks 只挡编辑**命令**，不挡宿主同步 —— `value` 变化照样写进文档，
+     * 否则只读的受控用法直接失效。
+     */
     readonly readonly?: boolean;
+    /**
+     * CodeMirror 挂载的 DOM 根，用于 Shadow DOM 场景。
+     *
+     * @remarks **仅挂载时读取一次** —— CodeMirror 无法在构造后改 root。
+     * 需要换 root 时请用 `v-if` 或 `:key` 强制重建组件。
+     */
     readonly root?: Document | ShadowRoot;
+    /**
+     * CodeMirror 预设扩展集；`null` 表示不加载任何预设。
+     *
+     * @defaultValue 'basic'
+     */
     readonly setup?: CodeEditorSetup;
+    /**
+     * 主题。
+     *
+     * @defaultValue 'light'
+     */
     readonly theme?: CodeEditorTheme;
+    /**
+     * 文档内容，配合 `v-model:value` 使用。
+     *
+     * @defaultValue ''
+     * @remarks **不是严格受控**：组件不会把用户编辑写回本属性，也不会在每次更新时
+     * 强行拉平文档。本属性变化时只同步公共前后缀之间的那一段差量，光标、选区与滚动位置都保留，
+     * 且不进 undo 栈。父组件忽略 `update:value` 时编辑器会保留用户输入。
+     */
     readonly value?: string;
 }
 /** Vue CodeEditor 的公开事件。 */
 export interface CodeEditorEmits {
+    /** 编辑器内容区域失去焦点。 */
     blur: [];
+    /** 用户编辑导致的内容变化；宿主经 `value` 的程序化写入**不**触发。 */
     change: [value: string];
+    /** 编辑器内容区域获得焦点。 */
     focus: [];
+    /**
+     * 语言解析或加载失败。
+     *
+     * @remarks
+     * CEV-004：这条路径此前只有一条 `console.error`，宿主完全观测不到 ——
+     * 拿不到错误、没有重试或降级的机会，用户只看到高亮突然消失。
+     * 降级策略不变（清空语言扩展退回纯文本），日志也保留，本事件是**新增的**观测通道。
+     * 载荷由核心包定义，与 Angular 的 `aoLanguageError` 输出、React 的 `onLanguageError`
+     * 回调逐字一致：`kind` 为 `'not-found'` 时是配置错误，重试没有意义；
+     * 为 `'load-failed'` 时通常是网络或分包问题，可以重试。
+     */
+    'language-error': [error: CodeEditorLanguageError];
+    /** `v-model:value` 的更新通道，触发时机与 `change` 相同。 */
     'update:value': [value: string];
 }
+/**
+ * `defineExpose` 暴露给模板 ref 的命令式 API。
+ *
+ * @remarks 四个成员与 React 的 `CodeEditorHandle`、Angular 组件实例上的同名成员
+ * 逐字对齐（CEA-009）—— 跨端迁移时命令式面不需要改写。
+ */
+export interface CodeEditorExpose {
+    /** 底层 CodeMirror EditorView，未挂载或已卸载时为 null。 */
+    readonly view: EditorView | null;
+    /** 宿主 `div` 元素（CodeMirror 挂载所在的容器），未挂载或已卸载时为 null。 */
+    readonly host: HTMLDivElement | null;
+    /** 移开键盘焦点；未挂载时是空操作。 */
+    blur(): void;
+    /** 把键盘焦点交给编辑器内容区域；未挂载时是空操作。 */
+    focus(): void;
+}
 export type { CodeEditorTheme } from '@aiao/code-editor';
 //# sourceMappingURL=code-editor.types.d.ts.map

package/dist/code-editor.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-editor.types.d.ts","sourceRoot":"","sources":["../src/code-editor.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAExF,yBAAyB;AACzB,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC;AAEzD,4BAA4B;AAC5B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4BAA4B;AAC5B,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,EAAE,CAAC;IACT,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACxB,KAAK,EAAE,EAAE,CAAC;IACV,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"code-editor.types.d.ts","sourceRoot":"","sources":["../src/code-editor.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACjH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,yBAAyB;AACzB,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC9D;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4BAA4B;AAC5B,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,IAAI,EAAE,EAAE,CAAC;IACT,6CAA6C;IAC7C,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACxB,mBAAmB;IACnB,KAAK,EAAE,EAAE,CAAC;IACV;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,CAAC,KAAK,EAAE,uBAAuB,CAAC,CAAC;IACnD,+CAA+C;IAC/C,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IACrC,uBAAuB;IACvB,IAAI,IAAI,IAAI,CAAC;IACb,+BAA+B;IAC/B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.d.ts

@@ -5,7 +5,6 @@
  * ```vue
  * <script setup lang="ts">
  * import { CodeEditor } from '@aiao/code-editor-vue';
- * import '@aiao/code-editor-vue/style.css';
  * </script>
  *
  * <template>
@@ -13,6 +12,6 @@
  * </template>
  * ```
  */
-export type { CodeEditorEmits, CodeEditorProps, CodeEditorSetup, CodeEditorTheme } from './code-editor.types.js';
+export type { CodeEditorEmits, CodeEditorExpose, CodeEditorProps, CodeEditorSetup, CodeEditorTheme } from './code-editor.types.js';
 export { default as CodeEditor } from './CodeEditor.vue';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACjH,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,24 +1,21 @@
-import { computed as e, createElementBlock as t, defineComponent as n, mergeProps as r, onMounted as i, onUnmounted as a, openBlock as o, ref as s, shallowRef as c, watch as l } from "vue";
-import { SUPPORT_LANGUAGES as u, findLanguageByName as d } from "@aiao/code-editor";
+import { computed as e, createElementBlock as t, defineComponent as n, mergeProps as r, onMounted as ee, onUnmounted as te, openBlock as i, ref as ne, shallowRef as re, watch as a } from "vue";
+import { SUPPORT_LANGUAGES as o, buildCodeEditorContentAttributes as s, codeEditorLanguageLoadFailed as ie, codeEditorLanguageNotFound as c, computeMinimalDocumentChange as ae, isSameResolvedLanguage as l, resolveCodeEditorLanguage as u, shouldAutoFocusCodeEditor as d } from "@aiao/code-editor";
 import { indentWithTab as f } from "@codemirror/commands";
-import { indentUnit as p } from "@codemirror/language";
-import { Annotation as m, Compartment as h, EditorState as g } from "@codemirror/state";
-import { oneDark as _ } from "@codemirror/theme-one-dark";
-import { EditorView as v, highlightWhitespace as y, keymap as b, placeholder as x } from "@codemirror/view";
-import { basicSetup as S, minimalSetup as C } from "codemirror";
+import { indentUnit as oe } from "@codemirror/language";
+import { Annotation as se, Compartment as p, EditorState as m, Transaction as h } from "@codemirror/state";
+import { oneDark as g } from "@codemirror/theme-one-dark";
+import { EditorView as _, highlightWhitespace as v, keymap as y, placeholder as b } from "@codemirror/view";
+import { basicSetup as x, minimalSetup as S } from "codemirror";
 //#endregion
 //#region src/CodeEditor.vue
-var w = /*#__PURE__*/ ((e, t) => {
-	let n = e.__vccOpts || e;
-	for (let [e, r] of t) n[e] = r;
-	return n;
-})(/* @__PURE__ */ n({
+var C = /* @__PURE__ */ n({
 	__name: "CodeEditor",
 	props: {
 		autoFocus: {
 			type: Boolean,
 			default: !1
 		},
+		describedBy: { default: "" },
 		disabled: {
 			type: Boolean,
 			default: !1
@@ -33,7 +30,9 @@ var w = /*#__PURE__*/ ((e, t) => {
 			default: !1
 		},
 		language: { default: "sql" },
-		languages: { default: () => u },
+		languages: { default: () => o },
+		label: { default: "" },
+		labelledBy: { default: "" },
 		lineWrapping: {
 			type: Boolean,
 			default: !1
@@ -52,118 +51,158 @@ var w = /*#__PURE__*/ ((e, t) => {
 		"blur",
 		"change",
 		"focus",
+		"language-error",
 		"update:value"
 	],
-	setup(n, { emit: u }) {
-		let w = n, T = u, E = s(null), D = c(null), O = e(() => ({
+	setup(n, { expose: o, emit: C }) {
+		let w = n, T = C, E = ne(null), D = re(null), ce = e(() => ({
 			"aria-disabled": w.disabled || void 0,
-			class: "aiao-code-editor"
-		})), k = new h(), A = new h(), j = new h(), M = new h(), N = new h(), P = new h(), F = new h(), I = new h(), L = new h(), R = new h(), z = m.define(), B = {
-			basic: S,
-			minimal: C
-		}, V = 0;
-		i(() => {
+			class: "aiao-code-editor",
+			style: {
+				display: "block",
+				fontSize: "0.875rem",
+				height: "100%",
+				overflow: "hidden",
+				width: "100%"
+			}
+		})), O = new p(), k = new p(), A = new p(), j = new p(), M = new p(), N = new p(), P = new p(), F = new p(), I = new p(), L = new p(), R = new p(), z = se.define(), B = {
+			basic: x,
+			minimal: S
+		}, V = 0, H;
+		ee(() => {
 			let e = E.value;
 			if (!e) return;
-			let t = new v({
+			let t = m.create({
+				doc: w.value,
+				extensions: [
+					O.of(W()),
+					k.of([]),
+					A.of([]),
+					j.of([]),
+					M.of([]),
+					N.of([]),
+					P.of([]),
+					F.of([]),
+					I.of([]),
+					L.of([]),
+					R.of([]),
+					_.theme({
+						"&": {
+							fontSize: "0.875rem",
+							height: "100%"
+						},
+						"&.cm-focused": {
+							outline: "2px solid Highlight",
+							outlineOffset: "-2px"
+						},
+						".cm-gutters": {
+							background: "initial",
+							border: "none"
+						},
+						".cm-scroller": { overflow: "auto" }
+					}),
+					_.domEventObservers({
+						blur: () => T("blur"),
+						focus: () => T("focus")
+					}),
+					_.updateListener.of((e) => {
+						let t = e.transactions.some((e) => e.annotation(z));
+						if (!e.docChanged || t) return;
+						let n = e.state.doc.toString();
+						T("update:value", n), T("change", n);
+					})
+				]
+			}), n = new _({
 				parent: e,
-				state: g.create({
-					doc: w.value,
-					extensions: [
-						k.of(U()),
-						A.of([]),
-						j.of([]),
-						M.of([]),
-						N.of([]),
-						P.of([]),
-						F.of([]),
-						I.of([]),
-						L.of([]),
-						R.of([]),
-						v.domEventObservers({
-							blur: () => T("blur"),
-							focus: () => T("focus")
-						}),
-						v.updateListener.of((e) => {
-							let t = e.transactions.some((e) => e.annotation(z));
-							if (!e.docChanged || t) return;
-							let n = e.state.doc.toString();
-							T("update:value", n), T("change", n);
-						})
-					]
-				}),
+				state: t,
 				...w.root ? { root: w.root } : {}
 			});
-			D.value = t, W(), G(), q(), J(), Y(), X(), Z(), w.autoFocus && t.focus();
-		}), a(() => {
+			D.value = n, G(), K(), J(), X(), Z(), Q(), $(), Y(), w.autoFocus && d(w) && n.focus();
+		}), te(() => {
 			V += 1;
 			let e = D.value;
 			D.value = null, e?.destroy();
-		}), l(() => w.value, (e) => {
+		}), a(() => w.value, (e) => {
 			let t = D.value;
-			!t || t.state.doc.toString() === e || t.dispatch({
-				annotations: z.of(!0),
-				changes: {
-					from: 0,
-					insert: e,
-					to: t.state.doc.length
-				}
+			if (!t) return;
+			let n = ae(t.state.doc.toString(), e ?? "");
+			n && t.dispatch({
+				annotations: [z.of(!0), h.addToHistory.of(!1)],
+				changes: n,
+				scrollIntoView: !1
 			});
-		}), l(() => w.setup, H), l(() => w.theme, W), l([() => w.language, () => w.languages], G), l([() => w.readonly, () => w.disabled], q), l(() => w.placeholder, J), l([() => w.indentWithTab, () => w.indentUnit], Y), l(() => w.lineWrapping, X), l(() => w.highlightWhitespace, Z);
-		function H() {
-			D.value?.dispatch({ effects: k.reconfigure(U()) });
-		}
+		}), a(() => w.setup, U), a(() => w.theme, G), a([() => w.language, () => w.languages], le), a([() => w.readonly, () => w.disabled], J), a(() => w.placeholder, X), a([() => w.indentWithTab, () => w.indentUnit], Z), a(() => w.lineWrapping, Q), a(() => w.highlightWhitespace, $), a([
+			() => w.describedBy,
+			() => w.disabled,
+			() => w.label,
+			() => w.labelledBy
+		], Y);
 		function U() {
-			return w.setup === null ? [] : B[w.setup];
+			D.value?.dispatch({ effects: O.reconfigure(W()) });
 		}
 		function W() {
-			D.value?.dispatch({ effects: j.reconfigure(w.theme === "dark" ? _ : []) });
+			return w.setup === null ? [] : B[w.setup];
 		}
 		function G() {
+			D.value?.dispatch({ effects: A.reconfigure(w.theme === "dark" ? g : []) });
+		}
+		function le() {
+			let e = u(w.language, w.languages);
+			l(H, e) || K();
+		}
+		function K() {
 			let e = ++V, t = D.value;
 			if (!t) return;
-			let n = w.language;
-			if (!n || n === "plaintext" || w.languages.length === 0) {
-				t.dispatch({ effects: A.reconfigure([]) });
+			let n = w.language, r = u(n, w.languages);
+			if (H = r, r.kind !== "found") {
+				t.dispatch({ effects: k.reconfigure([]) }), r.kind === "not-found" && (console.error(`[CodeEditor] Language '${n}' not found.`), T("language-error", c(n)));
 				return;
 			}
-			let r = d(n, w.languages);
-			if (!r) {
-				console.error(`[CodeEditor] Language '${n}' not found.`), t.dispatch({ effects: A.reconfigure([]) });
-				return;
-			}
-			r.load().then((n) => {
-				K(e, t) && t.dispatch({ effects: A.reconfigure(n.extension) });
+			r.description.load().then((n) => {
+				q(e, t) && t.dispatch({ effects: k.reconfigure(n.extension) });
 			}, (r) => {
-				K(e, t) && (console.error(`[CodeEditor] Failed to load language '${n}':`, r), t.dispatch({ effects: A.reconfigure([]) }));
+				q(e, t) && (t.dispatch({ effects: k.reconfigure([]) }), console.error(`[CodeEditor] Failed to load language '${n}':`, r), T("language-error", ie(n, r)));
 			});
 		}
-		function K(e, t) {
+		function q(e, t) {
 			return e === V && D.value === t;
 		}
-		function q() {
+		function J() {
 			let e = D.value;
 			if (!e) return;
 			let t = w.readonly || w.disabled;
-			e.dispatch({ effects: [M.reconfigure(g.readOnly.of(t)), N.reconfigure(v.editable.of(!t))] });
-		}
-		function J() {
-			D.value?.dispatch({ effects: P.reconfigure(w.placeholder ? x(w.placeholder) : []) });
+			e.dispatch({ effects: [j.reconfigure(m.readOnly.of(t)), M.reconfigure(_.editable.of(!t))] });
 		}
 		function Y() {
-			D.value?.dispatch({ effects: [F.reconfigure(w.indentWithTab ? b.of([f]) : []), I.reconfigure(w.indentUnit ? p.of(w.indentUnit) : [])] });
+			let e = s(w);
+			D.value?.dispatch({ effects: R.reconfigure(_.contentAttributes.of(e)) });
 		}
 		function X() {
-			D.value?.dispatch({ effects: L.reconfigure(w.lineWrapping ? v.lineWrapping : []) });
+			D.value?.dispatch({ effects: N.reconfigure(w.placeholder ? b(w.placeholder) : []) });
 		}
 		function Z() {
-			D.value?.dispatch({ effects: R.reconfigure(w.highlightWhitespace ? y() : []) });
+			D.value?.dispatch({ effects: [P.reconfigure(w.indentWithTab ? y.of([f]) : []), F.reconfigure(w.indentUnit ? oe.of(w.indentUnit) : [])] });
+		}
+		function Q() {
+			D.value?.dispatch({ effects: I.reconfigure(w.lineWrapping ? _.lineWrapping : []) });
+		}
+		function $() {
+			D.value?.dispatch({ effects: L.reconfigure(w.highlightWhitespace ? v() : []) });
 		}
-		return (e, n) => (o(), t("div", r(O.value, {
+		return o({
+			get view() {
+				return D.value;
+			},
+			get host() {
+				return D.value ? E.value : null;
+			},
+			blur: () => D.value?.contentDOM.blur(),
+			focus: () => D.value?.focus()
+		}), (e, n) => (i(), t("div", r(ce.value, {
 			ref_key: "editorRef",
 			ref: E
 		}), null, 16));
 	}
-}), [["__scopeId", "data-v-64632146"]]);
+});
 //#endregion
-export { w as CodeEditor };
+export { C as CodeEditor };

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@aiao/code-editor-vue",
-  "version": "0.0.23",
+  "version": "0.0.25",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aiao-io/rxdb.git",
+    "directory": "packages/code-editor-vue"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "style": "./dist/index.css",
   "exports": {
     "./package.json": "./package.json",
-    "./style.css": "./dist/index.css",
     ".": {
-      "@aiao/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
@@ -18,6 +21,10 @@
   },
   "files": [
     "dist",
+    "src",
+    "!src/**/*.spec.*",
+    "!src/**/*.test.*",
+    "!src/**/__tests__/**",
     "!**/*.tsbuildinfo"
   ],
   "publishConfig": {
@@ -30,15 +37,15 @@
     ]
   },
   "peerDependencies": {
-    "vue": ">=3.5.0"
+    "vue": "^3.5.41"
   },
   "dependencies": {
     "@codemirror/commands": "^6.10.4",
-    "@codemirror/language": "^6.12.4",
+    "@codemirror/language": "6.12.4",
     "@codemirror/state": "6.7.1",
     "@codemirror/theme-one-dark": "^6.1.3",
-    "@codemirror/view": "^6.43.5",
+    "@codemirror/view": "6.43.8",
     "codemirror": "^6.0.1",
-    "@aiao/code-editor": "0.0.23"
+    "@aiao/code-editor": "0.0.25"
   }
 }

package/src/CodeEditor.vue

@@ -0,0 +1,316 @@
+<script lang="ts" setup>
+import type { ResolvedCodeEditorLanguage } from '@aiao/code-editor';
+import {
+  buildCodeEditorContentAttributes,
+  codeEditorLanguageLoadFailed,
+  codeEditorLanguageNotFound,
+  computeMinimalDocumentChange,
+  isSameResolvedLanguage,
+  resolveCodeEditorLanguage,
+  shouldAutoFocusCodeEditor,
+  SUPPORT_LANGUAGES
+} from '@aiao/code-editor';
+import { indentWithTab as indentWithTabCommand } from '@codemirror/commands';
+import { indentUnit as indentUnitExt } from '@codemirror/language';
+import { Annotation, Compartment, EditorState, type Extension, Transaction } from '@codemirror/state';
+import { oneDark } from '@codemirror/theme-one-dark';
+import {
+  EditorView,
+  highlightWhitespace as highlightWhitespaceExt,
+  keymap,
+  placeholder as placeholderExt
+} from '@codemirror/view';
+import { basicSetup, minimalSetup } from 'codemirror';
+import { computed, onMounted, onUnmounted, ref, shallowRef, watch } from 'vue';
+
+import type { CodeEditorEmits, CodeEditorExpose, CodeEditorProps, CodeEditorSetup } from './code-editor.types.js';
+
+const props = withDefaults(defineProps<CodeEditorProps>(), {
+  autoFocus: false,
+  describedBy: '',
+  disabled: false,
+  highlightWhitespace: false,
+  indentUnit: '  ',
+  indentWithTab: false,
+  language: 'sql',
+  label: '',
+  labelledBy: '',
+  languages: () => SUPPORT_LANGUAGES,
+  lineWrapping: false,
+  placeholder: '',
+  readonly: false,
+  setup: 'basic',
+  theme: 'light',
+  value: ''
+});
+
+const emit = defineEmits<CodeEditorEmits>();
+const editorRef = ref<HTMLDivElement | null>(null);
+const viewRef = shallowRef<EditorView | null>(null);
+const hostAttributes = computed(() => ({
+  'aria-disabled': props.disabled || undefined,
+  class: 'aiao-code-editor',
+  style: {
+    display: 'block',
+    fontSize: '0.875rem',
+    height: '100%',
+    overflow: 'hidden',
+    width: '100%'
+  }
+}));
+const setupConf = new Compartment();
+const languageConf = new Compartment();
+const themeConf = new Compartment();
+const readonlyConf = new Compartment();
+const editableConf = new Compartment();
+const placeholderConf = new Compartment();
+const indentWithTabConf = new Compartment();
+const indentUnitConf = new Compartment();
+const lineWrappingConf = new Compartment();
+const highlightWhitespaceConf = new Compartment();
+const a11yConf = new Compartment();
+const External = Annotation.define<boolean>();
+const setupExtensions = {
+  basic: basicSetup,
+  minimal: minimalSetup
+} satisfies Record<Exclude<CodeEditorSetup, null>, Extension>;
+let languageRequest = 0;
+/** 最近一次**已生效**的语言解析结果，用于跳过等价的重复配置（CEV-003）。 */
+let appliedLanguage: ResolvedCodeEditorLanguage | undefined;
+
+onMounted(() => {
+  const parent = editorRef.value;
+  if (!parent) return;
+
+  const state = EditorState.create({
+    doc: props.value,
+    extensions: [
+      setupConf.of(getSetupExtension()),
+      languageConf.of([]),
+      themeConf.of([]),
+      readonlyConf.of([]),
+      editableConf.of([]),
+      placeholderConf.of([]),
+      indentWithTabConf.of([]),
+      indentUnitConf.of([]),
+      lineWrappingConf.of([]),
+      highlightWhitespaceConf.of([]),
+      a11yConf.of([]),
+      EditorView.theme({
+        '&': { fontSize: '0.875rem', height: '100%' },
+        '&.cm-focused': { outline: '2px solid Highlight', outlineOffset: '-2px' },
+        '.cm-gutters': { background: 'initial', border: 'none' },
+        '.cm-scroller': { overflow: 'auto' }
+      }),
+      EditorView.domEventObservers({
+        blur: () => emit('blur'),
+        focus: () => emit('focus')
+      }),
+      EditorView.updateListener.of(update => {
+        const external = update.transactions.some(transaction => transaction.annotation(External));
+        if (!update.docChanged || external) return;
+        const value = update.state.doc.toString();
+        emit('update:value', value);
+        emit('change', value);
+      })
+    ]
+  });
+  const view = new EditorView({
+    parent,
+    state,
+    ...(props.root ? { root: props.root } : {})
+  });
+
+  viewRef.value = view;
+  updateTheme();
+  updateLanguage();
+  updateReadonly();
+  updatePlaceholder();
+  updateIndent();
+  updateLineWrapping();
+  updateHighlightWhitespace();
+  updateAccessibility();
+  // CEA-008 / CER-006（用户可见的行为修正）：`disabled` / `readonly` 都会把编辑器配成
+  // 不可编辑，此时仍然抢焦点，用户只会得到一个无法输入、也无从得知为什么无法输入的控件。
+  if (props.autoFocus && shouldAutoFocusCodeEditor(props)) view.focus();
+});
+
+onUnmounted(() => {
+  languageRequest += 1;
+  const view = viewRef.value;
+  viewRef.value = null;
+  view?.destroy();
+});
+
+watch(
+  () => props.value,
+  value => {
+    const view = viewRef.value;
+    if (!view) return;
+    // CEV-001：早先是 `{ from: 0, to: doc.length }` 全文替换 —— CodeMirror 会把落在
+    // 替换区内的光标映射到区间起点，宿主保存 / 格式化 / 协同同步一次就把用户送回文档开头。
+    // 差量计算走核心包，三端共用同一份实现。
+    const changes = computeMinimalDocumentChange(view.state.doc.toString(), value ?? '');
+    if (!changes) return;
+    view.dispatch({
+      // `External` 只被本组件的 update listener 用来阻止回调环路，CodeMirror 的 history
+      // **不认识**它；少了 `addToHistory.of(false)`，宿主回写照样进 undo 栈。
+      annotations: [External.of(true), Transaction.addToHistory.of(false)],
+      changes,
+      scrollIntoView: false
+    });
+  }
+);
+watch(() => props.setup, updateSetup);
+watch(() => props.theme, updateTheme);
+watch([() => props.language, () => props.languages], syncLanguage);
+watch([() => props.readonly, () => props.disabled], updateReadonly);
+watch(() => props.placeholder, updatePlaceholder);
+watch([() => props.indentWithTab, () => props.indentUnit], updateIndent);
+watch(() => props.lineWrapping, updateLineWrapping);
+watch(() => props.highlightWhitespace, updateHighlightWhitespace);
+watch([() => props.describedBy, () => props.disabled, () => props.label, () => props.labelledBy], updateAccessibility);
+
+function updateSetup() {
+  viewRef.value?.dispatch({
+    effects: setupConf.reconfigure(getSetupExtension())
+  });
+}
+
+function getSetupExtension(): Extension {
+  return props.setup === null ? [] : setupExtensions[props.setup];
+}
+
+function updateTheme() {
+  viewRef.value?.dispatch({
+    effects: themeConf.reconfigure(props.theme === 'dark' ? oneDark : [])
+  });
+}
+
+/**
+ * `language` / `languages` 变化后的语言同步。
+ *
+ * CEV-003：`watch` 按数组**引用**触发。父组件写 `:languages="[myLang]"` 这类内联字面量时，
+ * 每轮更新都会重新查找、`load()` 并 reconfigure 语言 compartment ——
+ * 受控大文档等于每次输入都整篇重新词法分析。判定基准改成
+ * 「当前语言实际解析到的 description identity」，与 Angular / React 同构。
+ */
+function syncLanguage() {
+  const resolved = resolveCodeEditorLanguage(props.language, props.languages);
+  if (isSameResolvedLanguage(appliedLanguage, resolved)) return;
+  updateLanguage();
+}
+
+/**
+ * **无条件**重新应用语言配置。挂载时以及 {@link syncLanguage} 判定确有变化时调用。
+ */
+function updateLanguage() {
+  const request = ++languageRequest;
+  const view = viewRef.value;
+  if (!view) return;
+
+  const language = props.language;
+  const resolved = resolveCodeEditorLanguage(language, props.languages);
+  appliedLanguage = resolved;
+  if (resolved.kind !== 'found') {
+    view.dispatch({ effects: languageConf.reconfigure([]) });
+    // CEV-004：`none` 是「明确不高亮」，不是错误；只有 `not-found` 才报给宿主。
+    if (resolved.kind === 'not-found') {
+      console.error(`[CodeEditor] Language '${language}' not found.`);
+      emit('language-error', codeEditorLanguageNotFound(language));
+    }
+    return;
+  }
+
+  // 解析结果里已经带着命中的 description —— 早先这里又 `findLanguageByName` 查了一遍，
+  // 同一份查找逻辑跑两次，两处结果分叉时没有任何信号。
+  void resolved.description.load().then(
+    support => {
+      if (!isCurrentLanguageRequest(request, view)) return;
+      view.dispatch({ effects: languageConf.reconfigure(support.extension as Extension) });
+    },
+    (error: unknown) => {
+      if (!isCurrentLanguageRequest(request, view)) return;
+      view.dispatch({ effects: languageConf.reconfigure([]) });
+      console.error(`[CodeEditor] Failed to load language '${language}':`, error);
+      emit('language-error', codeEditorLanguageLoadFailed(language, error));
+    }
+  );
+}
+
+function isCurrentLanguageRequest(request: number, view: EditorView) {
+  return request === languageRequest && viewRef.value === view;
+}
+
+function updateReadonly() {
+  const view = viewRef.value;
+  if (!view) return;
+  const readonly = props.readonly || props.disabled;
+  view.dispatch({
+    effects: [
+      readonlyConf.reconfigure(EditorState.readOnly.of(readonly)),
+      editableConf.reconfigure(EditorView.editable.of(!readonly))
+    ]
+  });
+}
+
+/**
+ * 把无障碍属性写到真正承担 `role="textbox"` 的 `.cm-content` 上。
+ *
+ * CEA-008 / CER-006：只在宿主 `div` 上补 `aria-*` 是把缺陷换个位置 —— 屏幕阅读器进到
+ * textbox 之后读到的仍然是一个没有可访问名称、只报 `aria-readonly` 的多行文本框。
+ * `readonlyConf` 让 CodeMirror 写出 `aria-readonly`，但「只读」与「禁用」不是一回事，
+ * 禁用语义必须单独告知。属性字典由核心包计算，三端共用同一份实现。
+ */
+function updateAccessibility() {
+  const attributes = buildCodeEditorContentAttributes(props);
+  viewRef.value?.dispatch({ effects: a11yConf.reconfigure(EditorView.contentAttributes.of(attributes)) });
+}
+
+function updatePlaceholder() {
+  viewRef.value?.dispatch({
+    effects: placeholderConf.reconfigure(props.placeholder ? placeholderExt(props.placeholder) : [])
+  });
+}
+
+function updateIndent() {
+  viewRef.value?.dispatch({
+    effects: [
+      indentWithTabConf.reconfigure(props.indentWithTab ? keymap.of([indentWithTabCommand]) : []),
+      indentUnitConf.reconfigure(props.indentUnit ? indentUnitExt.of(props.indentUnit) : [])
+    ]
+  });
+}
+
+function updateLineWrapping() {
+  viewRef.value?.dispatch({
+    effects: lineWrappingConf.reconfigure(props.lineWrapping ? EditorView.lineWrapping : [])
+  });
+}
+
+function updateHighlightWhitespace() {
+  viewRef.value?.dispatch({
+    effects: highlightWhitespaceConf.reconfigure(props.highlightWhitespace ? highlightWhitespaceExt() : [])
+  });
+}
+
+defineExpose<CodeEditorExpose>({
+  get view() {
+    return viewRef.value;
+  },
+  // 跟着 `view` 一起置空：`editorRef` 在卸载后仍可能残留元素引用，
+  // 而 handle 的契约是「未挂载或已卸载时为 null」，三端逐字一致（CEA-009）。
+  get host() {
+    return viewRef.value ? editorRef.value : null;
+  },
+  blur: () => viewRef.value?.contentDOM.blur(),
+  focus: () => viewRef.value?.focus()
+});
+</script>
+
+<template>
+  <div
+    v-bind="hostAttributes"
+    ref="editorRef"
+  />
+</template>

package/src/code-editor.types.ts

@@ -0,0 +1,177 @@
+import type { CodeEditorLanguageDescription, CodeEditorLanguageError, CodeEditorTheme } from '@aiao/code-editor';
+import type { EditorView } from '@codemirror/view';
+
+/** CodeMirror 预置扩展集合。 */
+export type CodeEditorSetup = 'basic' | 'minimal' | null;
+
+/**
+ * Vue CodeEditor 的公开属性。
+ *
+ * @remarks 与 Angular 的 inputs、React 的 props 同名同义；仅初始化生效的两项
+ * （{@link CodeEditorProps.autoFocus} / {@link CodeEditorProps.root}）在各自条目上标注。
+ */
+export interface CodeEditorProps {
+  /**
+   * 挂载后立即聚焦编辑器。
+   *
+   * @defaultValue false
+   * @remarks **仅挂载时读取一次**，后续变更被忽略。`disabled` 或 `readonly` 为真时
+   * 不抢焦点 —— 否则用户得到一个无法输入、也无从得知为什么无法输入的控件。
+   */
+  readonly autoFocus?: boolean;
+  /**
+   * 补充说明元素的 id，写成内部 textbox 的 `aria-describedby`。
+   *
+   * @remarks 属性落在 CodeMirror 的 `.cm-content` 上 —— 承担 `role="textbox"` 的是它，
+   * 不是组件的宿主元素。空串按「未设置」处理。三端同名同义。
+   */
+  readonly describedBy?: string;
+  /**
+   * 禁用：只读且不可编辑，并向辅助技术报告 `aria-disabled`。
+   *
+   * @defaultValue false
+   * @remarks 与 `readonly` 是独立的两个属性，任一为真都会让编辑器不可编辑；
+   * 区别在于禁用还会写出 `aria-disabled` 并抑制 `autoFocus`。
+   */
+  readonly disabled?: boolean;
+  /**
+   * 显示空白字符。
+   *
+   * @defaultValue false
+   */
+  readonly highlightWhitespace?: boolean;
+  /**
+   * 一级缩进使用的字符串。
+   *
+   * @defaultValue '  '（两个空格，三端一致）
+   */
+  readonly indentUnit?: string;
+  /**
+   * 允许 Tab 键缩进。
+   *
+   * @defaultValue false
+   * @remarks 打开后 Tab 不再移动焦点，键盘用户会被困在编辑器里 —— 这是可达性取舍，
+   * 三端默认一致地关闭。
+   */
+  readonly indentWithTab?: boolean;
+  /**
+   * 语法高亮语言名或别名；`''` 与 `'plaintext'` 表示不高亮。
+   *
+   * @defaultValue 'sql'
+   * @remarks 查不到或 `load()` 失败时**降级为纯文本**并继续可用，同时发出
+   * `language-error` 事件（见 {@link CodeEditorEmits}）。快速切换时只有最后一次请求生效。
+   */
+  readonly language?: string;
+  /**
+   * 候选语言列表；空列表表示不高亮。
+   *
+   * @defaultValue SUPPORT_LANGUAGES
+   * @remarks 传内联字面量（`:languages="[myLang]"`）是有成本的：每轮更新都是新数组，
+   * 而 `watch` 按引用触发。组件会再判断当前语言解析到的 description 是否真的换了 ——
+   * 只有真换了才重新 `load()`，但这层判断本身仍要跑，稳定引用（模块级常量或 `computed`）更省。
+   */
+  readonly languages?: readonly CodeEditorLanguageDescription[];
+  /**
+   * 可访问名称，写成内部 textbox 的 `aria-label`。
+   *
+   * @remarks 落点与 {@link CodeEditorProps.describedBy} 相同。
+   */
+  readonly label?: string;
+  /**
+   * 承担标签的元素 id，写成内部 textbox 的 `aria-labelledby`。
+   *
+   * @remarks 落点与 {@link CodeEditorProps.describedBy} 相同。
+   */
+  readonly labelledBy?: string;
+  /**
+   * 自动换行。
+   *
+   * @defaultValue false
+   */
+  readonly lineWrapping?: boolean;
+  /**
+   * 空文档时显示的占位文本。
+   *
+   * @defaultValue ''
+   */
+  readonly placeholder?: string;
+  /**
+   * 只读：仍可聚焦、可选择、可复制，但不能改。
+   *
+   * @defaultValue false
+   * @remarks 只挡编辑**命令**，不挡宿主同步 —— `value` 变化照样写进文档，
+   * 否则只读的受控用法直接失效。
+   */
+  readonly readonly?: boolean;
+  /**
+   * CodeMirror 挂载的 DOM 根，用于 Shadow DOM 场景。
+   *
+   * @remarks **仅挂载时读取一次** —— CodeMirror 无法在构造后改 root。
+   * 需要换 root 时请用 `v-if` 或 `:key` 强制重建组件。
+   */
+  readonly root?: Document | ShadowRoot;
+  /**
+   * CodeMirror 预设扩展集；`null` 表示不加载任何预设。
+   *
+   * @defaultValue 'basic'
+   */
+  readonly setup?: CodeEditorSetup;
+  /**
+   * 主题。
+   *
+   * @defaultValue 'light'
+   */
+  readonly theme?: CodeEditorTheme;
+  /**
+   * 文档内容，配合 `v-model:value` 使用。
+   *
+   * @defaultValue ''
+   * @remarks **不是严格受控**：组件不会把用户编辑写回本属性，也不会在每次更新时
+   * 强行拉平文档。本属性变化时只同步公共前后缀之间的那一段差量，光标、选区与滚动位置都保留，
+   * 且不进 undo 栈。父组件忽略 `update:value` 时编辑器会保留用户输入。
+   */
+  readonly value?: string;
+}
+
+/** Vue CodeEditor 的公开事件。 */
+export interface CodeEditorEmits {
+  /** 编辑器内容区域失去焦点。 */
+  blur: [];
+  /** 用户编辑导致的内容变化；宿主经 `value` 的程序化写入**不**触发。 */
+  change: [value: string];
+  /** 编辑器内容区域获得焦点。 */
+  focus: [];
+  /**
+   * 语言解析或加载失败。
+   *
+   * @remarks
+   * CEV-004：这条路径此前只有一条 `console.error`，宿主完全观测不到 ——
+   * 拿不到错误、没有重试或降级的机会，用户只看到高亮突然消失。
+   * 降级策略不变（清空语言扩展退回纯文本），日志也保留，本事件是**新增的**观测通道。
+   * 载荷由核心包定义，与 Angular 的 `aoLanguageError` 输出、React 的 `onLanguageError`
+   * 回调逐字一致：`kind` 为 `'not-found'` 时是配置错误，重试没有意义；
+   * 为 `'load-failed'` 时通常是网络或分包问题，可以重试。
+   */
+  'language-error': [error: CodeEditorLanguageError];
+  /** `v-model:value` 的更新通道，触发时机与 `change` 相同。 */
+  'update:value': [value: string];
+}
+
+/**
+ * `defineExpose` 暴露给模板 ref 的命令式 API。
+ *
+ * @remarks 四个成员与 React 的 `CodeEditorHandle`、Angular 组件实例上的同名成员
+ * 逐字对齐（CEA-009）—— 跨端迁移时命令式面不需要改写。
+ */
+export interface CodeEditorExpose {
+  /** 底层 CodeMirror EditorView，未挂载或已卸载时为 null。 */
+  readonly view: EditorView | null;
+  /** 宿主 `div` 元素（CodeMirror 挂载所在的容器），未挂载或已卸载时为 null。 */
+  readonly host: HTMLDivElement | null;
+  /** 移开键盘焦点；未挂载时是空操作。 */
+  blur(): void;
+  /** 把键盘焦点交给编辑器内容区域；未挂载时是空操作。 */
+  focus(): void;
+}
+
+export type { CodeEditorTheme } from '@aiao/code-editor';

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @aiao/code-editor-vue
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { CodeEditor } from '@aiao/code-editor-vue';
+ * </script>
+ *
+ * <template>
+ *   <CodeEditor v-model:value="code" language="typescript" />
+ * </template>
+ * ```
+ */
+export type {
+  CodeEditorEmits,
+  CodeEditorExpose,
+  CodeEditorProps,
+  CodeEditorSetup,
+  CodeEditorTheme
+} from './code-editor.types.js';
+export { default as CodeEditor } from './CodeEditor.vue';

package/src/vue-shims.d.ts

@@ -0,0 +1,5 @@
+declare module '*.vue' {
+  import { defineComponent } from 'vue';
+  const component: ReturnType<typeof defineComponent>;
+  export default component;
+}

package/dist/index.css

@@ -1,2 +0,0 @@
-.aiao-code-editor[data-v-64632146]{width:100%;height:100%;font-size:.875rem;display:block;overflow:hidden}.aiao-code-editor[data-v-64632146] .cm-editor{height:100%}.aiao-code-editor[data-v-64632146] .cm-scroller{overflow:auto}
-/*$vite$:1*/