@daxiangme/form-vue 0.1.0 → 0.1.2

package/LICENSE

@@ -1,2 +1,21 @@
-MIT License. See the workspace root LICENSE for the complete text.
+MIT License
 
+Copyright (c) 2026 daxiangme
+
+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

@@ -1,12 +1,26 @@
 # @daxiangme/form-vue
 
-Vue 3 + Element Plus 的 DX Form 设计器和运行渲染器。
+> Visual Form Designer and Schema-Driven Renderer for Vue 3 + Element Plus
+
+`@daxiangme/form-vue` 是 Form Builder 的唯一推荐使用入口，提供可嵌入的拖拽式设计器、Schema 驱动运行渲染器、弹窗与抽屉模块、字段规则和声明式事件流。
+
+![Form Builder 设计器总览](https://raw.githubusercontent.com/daxiangme/form-builder/v0.1.1/docs/assets/screenshots/designer-overview.png)
+
+## 安装
+
+已有 Vue 3 和 Element Plus 的应用只需要安装主包：
+
+```bash
+pnpm add @daxiangme/form-vue
+```
+
+主包要求 Vue `^3.5.0` 和 Element Plus `^2.11.0`。新建工程或尚未安装这两个 Peer Dependencies 时，可以一次性安装：
 
 ```bash
-pnpm add @daxiangme/form-core @daxiangme/form-vue vue element-plus
+pnpm add @daxiangme/form-vue vue element-plus
 ```
 
-样式顺序固定为：
+按以下顺序引入样式：
 
 ```ts
 import 'element-plus/dist/index.css'
@@ -14,24 +28,119 @@ import 'element-plus/theme-chalk/dark/css-vars.css'
 import '@daxiangme/form-vue/style.css'
 ```
 
+## 注册组件
+
+```ts
+import { createApp } from 'vue'
+import ElementPlus from 'element-plus'
+import { DaxiangFormVue } from '@daxiangme/form-vue'
+
+import App from './App.vue'
+
+createApp(App).use(ElementPlus).use(DaxiangFormVue).mount('#app')
+```
+
+## 设计表单
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  FormDesigner,
+  createDemoDesignerDocument,
+  type DesignerDocument,
+} from '@daxiangme/form-vue'
+
+const document = ref<DesignerDocument>(createDemoDesignerDocument('purchase-application'))
+
+function handleSave(nextDocument: DesignerDocument) {
+  document.value = nextDocument
+}
+</script>
+
+<template>
+  <div class="designer-host">
+    <FormDesigner v-model="document" @save-request="handleSave" />
+  </div>
+</template>
+
+<style scoped>
+.designer-host {
+  height: 100vh;
+}
+</style>
+```
+
+`FormDesigner` 使用受控 `modelValue`，负责编辑文档并发出保存、导出与诊断事件；业务持久化由宿主决定。
+
+## 渲染表单
+
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue'
-import { createEmptyDesignerDocument, type DesignerRuntimeValueStore } from '@daxiangme/form-core'
-import { FormDesigner, FormRenderer } from '@daxiangme/form-vue'
+import {
+  FormRenderer,
+  createDemoDesignerDocument,
+  type DesignerRuntimeValueStore,
+  type DesignerSubmissionProjection,
+} from '@daxiangme/form-vue'
 
-const document = ref(createEmptyDesignerDocument('form-1'))
+const document = createDemoDesignerDocument('purchase-application')
 const value = ref<DesignerRuntimeValueStore>({ fields: {}, collections: {} })
+
+function handleSubmit(projection: DesignerSubmissionProjection) {
+  console.info(projection)
+}
 </script>
 
 <template>
-  <FormDesigner v-model="document" @save-request="saveDocument" />
-  <FormRenderer v-model="value" :document="document" mode="CREATE" />
+  <FormRenderer v-model="value" :document="document" mode="CREATE" @submit="handleSubmit" />
 </template>
 ```
 
-`FormDesigner` 只发出保存和导出请求，不代替宿主调用业务接口。`FormRenderer` 的文件、目录、OCR、扫码、定位、远程验证和导航能力都通过 `FormRuntimeAdapters` 显式注入；缺少端口时操作失败关闭。
+`FormRenderer` 使用同一份文档渲染新增、编辑、只读和详情状态，并输出稳定的提交投影。
+
+## 模块、规则与事件
+
+主表单、弹窗与抽屉共用同一份 `DesignerDocument 1.0`。字段高级配置集中管理状态条件、公式与联动、验证规则、提交策略和组件事件；事件使用可视化步骤与条件分支表达。
+
+![弹窗与抽屉模块设计](https://raw.githubusercontent.com/daxiangme/form-builder/v0.1.1/docs/assets/screenshots/overlay-module-designer.png)
+
+![字段高级配置](https://raw.githubusercontent.com/daxiangme/form-builder/v0.1.1/docs/assets/screenshots/advanced-field-config.png)
+
+![声明式事件流](https://raw.githubusercontent.com/daxiangme/form-builder/v0.1.1/docs/assets/screenshots/event-flow-designer.png)
+
+## 运行效果与主题
+
+弹窗和抽屉在运行态使用真实 Element Plus 外壳。组件默认消费 Element Plus CSS Variables，深色模式直接跟随宿主的 `html.dark`。
+
+![表单运行预览](https://raw.githubusercontent.com/daxiangme/form-builder/v0.1.1/docs/assets/screenshots/runtime-preview.png)
+
+![Element Plus 深色主题](https://raw.githubusercontent.com/daxiangme/form-builder/v0.1.1/docs/assets/screenshots/dark-theme.png)
+
+## 宿主能力 Adapter
+
+基础设计与渲染不要求额外安装 Adapter。上传、目录、数据源、远程验证、OCR、扫码、定位、导航和业务动作需要宿主通过 `FormRuntimeAdapters` 注入相应端口；缺少端口时保留配置和静态外观，真实动作会明确失败关闭。
+
+主包同时导出常用文档门面和运行类型：
+
+```ts
+import {
+  createEmptyDesignerDocument,
+  decodeDesignerDocument,
+  diagnoseDesignerDocument,
+  serializeDesignerDocument,
+  type DesignerDocument,
+  type FormRuntimeAdapters,
+} from '@daxiangme/form-vue'
+```
+
+## 高级扩展与内部架构
+
+内部依赖固定为 `form-vue -> form-core <- form-adapter`。纯 TypeScript 文档内核和宿主适配工厂继续以 [`@daxiangme/form-core`](https://www.npmjs.com/package/@daxiangme/form-core) 与 [`@daxiangme/form-adapter`](https://www.npmjs.com/package/@daxiangme/form-adapter) 提供给高级集成方；普通 Vue 应用无需单独安装它们。
+
+当前版本支持 Vue 3、Element Plus 与现代 ESM 浏览器工程，不承诺 CommonJS、SSR 或其他 UI 框架。
 
-深色模式直接跟随 Element Plus 的 `html.dark`，包内不维护第二套主题状态。
+## License
 
-`FormDesigner` 会占满直接父容器；消费方需要为该父容器提供确定高度，但不要求父容器使用 Flex 布局。
+[MIT](https://github.com/daxiangme/form-builder/blob/v0.1.1/LICENSE) © 2026 daxiangme

package/dist/index.d.ts

@@ -2,11 +2,19 @@ import { ComponentOptionsMixin } from 'vue';
 import { ComponentProvideOptions } from 'vue';
 import { ComputedRef } from 'vue';
 import { CreateComponentPublicInstanceWithMixins } from 'vue';
+import { createDefaultDesignerFieldBehavior } from '@daxiangme/form-core';
+import { createDemoDesignerDocument } from '@daxiangme/form-core';
+import { createEmptyDesignerDocument } from '@daxiangme/form-core';
+import { decodeDesignerDocument } from '@daxiangme/form-core';
 import { DefineComponent } from 'vue';
+import { DesignerAppearance } from '@daxiangme/form-core';
 import { DesignerDevice } from '@daxiangme/form-core';
 import { DesignerDiagnostic } from '@daxiangme/form-core';
 import { DesignerDocument } from '@daxiangme/form-core';
+import { DesignerDocumentDecodeResult } from '@daxiangme/form-core';
 import { DesignerDropTarget } from '@daxiangme/form-core';
+import { DesignerField } from '@daxiangme/form-core';
+import { DesignerFieldId } from '@daxiangme/form-core';
 import { DesignerInitialDataModel } from '@daxiangme/form-core';
 import { DesignerLayoutNode } from '@daxiangme/form-core';
 import { DesignerOverlayModule } from '@daxiangme/form-core';
@@ -14,12 +22,20 @@ import { DesignerRuntimeAdapters } from '@daxiangme/form-core';
 import { DesignerRuntimeMode } from '@daxiangme/form-core';
 import { DesignerRuntimeValueStore } from '@daxiangme/form-core';
 import { DesignerSubmissionProjection } from '@daxiangme/form-core';
+import { DesignerValidationResult } from '@daxiangme/form-core';
+import { diagnoseDesignerDocument } from '@daxiangme/form-core';
+import { FormDesignerCatalogs } from '@daxiangme/form-core';
+import { FormDesignerHostCapabilities } from '@daxiangme/form-core';
+import { FormFieldAccessLevel } from '@daxiangme/form-core';
+import { FormFieldAccessMap } from '@daxiangme/form-core';
 import { FormRuntimeAdapterContext } from '@daxiangme/form-core';
+import { FormRuntimeAdapters } from '@daxiangme/form-core';
 import { GlobalComponents } from 'vue';
 import { GlobalDirectives } from 'vue';
 import { Plugin as Plugin_2 } from 'vue';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
+import { serializeDesignerDocument } from '@daxiangme/form-core';
 
 declare const __VLS_component: DefineComponent<__VLS_Props, {
 markClean: () => void;
@@ -158,6 +174,7 @@ flushContentVertical: boolean;
 declare type __VLS_Props = {
     modelValue: DesignerDocument;
     initialDataModel?: DesignerInitialDataModel;
+    catalogs?: FormDesignerCatalogs;
     adapters?: DesignerRuntimeAdapters;
     adapterContext?: FormRuntimeAdapterContext;
     /** @deprecated 请使用 adapters。 */
@@ -168,6 +185,7 @@ declare type __VLS_Props_2 = {
     document: DesignerDocument;
     modelValue?: DesignerRuntimeValueStore;
     mode?: Exclude<DesignerRuntimeMode, 'DESIGN'>;
+    fieldAccess?: FormFieldAccessMap;
     device?: DesignerDevice;
     adapters?: DesignerRuntimeAdapters;
     adapterContext?: FormRuntimeAdapterContext;
@@ -324,6 +342,12 @@ declare type __VLS_WithTemplateSlots_2<T, S> = T & {
     };
 };
 
+export { createDefaultDesignerFieldBehavior }
+
+export { createDemoDesignerDocument }
+
+export { createEmptyDesignerDocument }
+
 /** 返回与 Vue 代理隔离的当前文档。 */
 declare function currentDocument(): DesignerDocument;
 
@@ -332,11 +356,49 @@ declare const DaxiangFormVue: Plugin_2;
 export { DaxiangFormVue }
 export default DaxiangFormVue;
 
+export { decodeDesignerDocument }
+
+export { DesignerAppearance }
+
 /** 设计画布的受控视口档位。 */
 export declare type DesignerCanvasViewportPreset = 'FIT' | 'PC_1920' | 'PC_1440' | 'PC_1280' | 'PC_1024' | 'MOBILE_440' | 'MOBILE_375';
 
+export { DesignerDiagnostic }
+
+export { DesignerDocument }
+
+export { DesignerDocumentDecodeResult }
+
+export { DesignerField }
+
+export { DesignerFieldId }
+
+export { DesignerInitialDataModel }
+
+export { DesignerLayoutNode }
+
+export { DesignerRuntimeAdapters }
+
+export { DesignerRuntimeMode }
+
+export { DesignerRuntimeValueStore }
+
+export { DesignerSubmissionProjection }
+
+export { DesignerValidationResult }
+
+export { diagnoseDesignerDocument }
+
 export declare const FormDesigner: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 
+export { FormDesignerCatalogs }
+
+export { FormDesignerHostCapabilities }
+
+export { FormFieldAccessLevel }
+
+export { FormFieldAccessMap }
+
 export declare const FormIcon: DefineComponent<__VLS_Props_3, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_3> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 export declare const FormModalShell: __VLS_WithTemplateSlots_2<typeof __VLS_component_2, __VLS_TemplateResult_2["slots"]>;
@@ -367,6 +429,10 @@ overlayOnly: boolean;
 showToolbar: boolean;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
 
+export { FormRuntimeAdapterContext }
+
+export { FormRuntimeAdapters }
+
 /** 替换文档时重新执行一次性参数判定，并刷新只读来源索引。 */
 declare function replaceDocument(document: DesignerDocument, keepHistory?: boolean): void;
 
@@ -374,4 +440,6 @@ declare function requestClose(): void;
 
 declare function requestConfirm(): void;
 
+export { serializeDesignerDocument }
+
 export { }