@aiao/rxdb-model 0.0.19 → 0.0.28

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Aiao Team
+Copyright (c) 2025-2026 Aiao Team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,11 +1,48 @@
-# rxdb-model
+# @aiao/rxdb-model
 
-This library was generated with [Nx](https://nx.dev).
+框架无关的 RxDB 实体模型核心库：从实体元数据（`EntityMetadata`）派生表单、详情页、可编辑表格与可视化查询构建器所需的全部纯逻辑，并配套 VTable 表格运行时基础设施。
 
-## Building
+## 定位与边界
 
-Run `nx build rxdb-model` to build the library.
+- **唯一输入源**：`@aiao/rxdb` 的实体装饰器体系产出的 `EntityMetadata`。
+- **框架无关**：本包不含任何 Angular / React / Vue 依赖，可被任意前端技术栈消费；三框架 UI 组件层见 `@aiao/rxdb-model-angular`（React / Vue 版本陆续提供）。
+- **与 `@aiao/rxdb` 的边界**：核心包的 `entity-field.utils`（Field Descriptor 字段语义元数据）与 `entity-value.utils`（`parseEntityFieldValue`/`formatEntityFieldValue`/`validateFieldValue` 等）服务于核心内部与插件契约；本包的同名模块面向「实体管理界面」场景（表单字段提取、字段值解析/格式化/校验、表格列构建），语义不同、请勿混用。
+- **表格引擎**：`@visactor/vtable` 与 `@visactor/vtable-editors` 为 peer 依赖（`~1.26.x`），由消费方提供。
 
-## Running unit tests
+## 模块一览
 
-Run `nx test rxdb-model` to execute the unit tests via [Vitest](https://vitest.dev/).
+| 目录                                                                    | 职责                                                                                                   |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| 根目录 `entity-field.utils` / `entity-value.utils` / `structural-equal` | 字段配置提取、字段值解析/格式化/校验、键序无关的结构化深比较                                           |
+| `entity-form/`                                                          | 元数据 → 表单字段配置（create/edit/view 三模式）、实体与表单数据双向转换（仅变化字段）、表单校验       |
+| `entity-detail/`                                                        | 元数据 → 详情页 Tab 结构（基础表单 + 每关系一个表格 Tab）                                              |
+| `entity-table/`                                                         | 可编辑表格列构建、15 个 VTable 单元格编辑器、剪贴板 / 键盘 / 主题 / tooltip / 拖拽重排等运行时基础设施 |
+| `query-builder/`                                                        | 可视化查询构建器引擎：状态服务、操作符注册表、查询转换、schema 解析、即时校验、字段树等工具            |
+
+## 使用
+
+```ts
+import { buildFormFields, buildEditableColumns, buildDetailTabs } from '@aiao/rxdb-model';
+
+const fields = buildFormFields(metadata, 'create');
+const columns = buildEditableColumns(metadata);
+const tabs = buildDetailTabs(metadata);
+```
+
+查询构建器（框架无关服务层）：
+
+```ts
+import { createQueryBuilderService } from '@aiao/rxdb-model';
+
+const qb = createQueryBuilderService<MyEntity>({ schema: { fields } });
+qb.state$.subscribe(state => console.log(state));
+qb.addRule({ field: 'title', operator: 'contains', value: 'a' });
+const rxdbQuery = qb.toRxDBQuery();
+```
+
+## 开发
+
+```bash
+pnpm nx test rxdb-model        # Vitest（node 默认环境，DOM 用例经文件头 pragma 切 happy-dom）
+pnpm nx build rxdb-model       # Vite 库构建（ES 单格式 + dts）
+```

package/dist/cn.d.ts

@@ -0,0 +1,19 @@
+import { ClassValue } from 'clsx';
+/**
+ * 拼接 CSS 类名（clsx 的薄封装）。
+ *
+ * 过滤 falsy 值并支持对象 / 数组形式的条件类名，用于替代模板字符串拼接：
+ * 模板字符串中条件类名前的分隔空格若位于行尾，会被格式化工具的尾随空白
+ * 裁剪吃掉，产生 `flex-coloverflow-auto` 这类拼接错误；本函数不存在该问题。
+ *
+ * @param inputs - 字符串类名、条件对象或数组，falsy 值会被自动忽略
+ * @returns 以单个空格连接后的类名字符串
+ *
+ * @example
+ * ```ts
+ * cn('tab-content flex-col', isForm ? 'overflow-auto p-4' : 'overflow-hidden')
+ * // 'tab-content flex-col overflow-auto p-4'
+ * ```
+ */
+export declare function cn(...inputs: ClassValue[]): string;
+//# sourceMappingURL=cn.d.ts.map

package/dist/cn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cn.d.ts","sourceRoot":"","sources":["../src/cn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAElD"}

package/dist/entity-capabilities.d.ts

@@ -0,0 +1,25 @@
+import { EntityMetadata } from '@aiao/rxdb';
+/**
+ * 实体在公开写入口上允许的界面操作
+ */
+export interface EntityCapabilities {
+    /** 可新增：`create` 为 `'both'` */
+    readonly canCreate: boolean;
+    /** 已有行可编辑：`update` 为 `'both'`；否则行只读、详情以查看模式打开 */
+    readonly canEdit: boolean;
+    /** 已有行可删除：`delete` 为 `'both'` */
+    readonly canDelete: boolean;
+}
+/**
+ * 由实体元数据派生界面能力
+ *
+ * @param metadata - 实体元数据（只读其中的 `permissions`）
+ * @returns 三项能力；未声明的操作按 `'both'` 计，即可用
+ *
+ * @example
+ * ```typescript
+ * const { canCreate, canEdit, canDelete } = deriveEntityCapabilities(getEntityMetadata(Invoice));
+ * ```
+ */
+export declare const deriveEntityCapabilities: (metadata: Pick<EntityMetadata, "permissions">) => EntityCapabilities;
+//# sourceMappingURL=entity-capabilities.d.ts.map

package/dist/entity-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-capabilities.d.ts","sourceRoot":"","sources":["../src/entity-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAuB,MAAM,YAAY,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,UAAU,IAAI,CAAC,cAAc,EAAE,aAAa,CAAC,KAAG,kBAIvF,CAAC"}

package/dist/entity-detail/detail-tabs.d.ts

@@ -1,4 +1,10 @@
-import { EntityMetadata } from '../../packages/rxdb/src/index.ts';
+import { EntityMetadata } from '@aiao/rxdb';
 import { DetailTab } from './interfaces.js';
+/**
+ * 根据实体元数据构建详情页标签列表
+ * @remarks 基本信息表单标签固定排在首位，其后为每个一对多 / 多对多关系生成一个表格标签
+ * @param metadata - 实体元数据
+ * @returns 详情页标签配置列表
+ */
 export declare function buildDetailTabs(metadata: EntityMetadata): DetailTab[];
 //# sourceMappingURL=detail-tabs.d.ts.map

package/dist/entity-detail/detail-tabs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detail-tabs.d.ts","sourceRoot":"","sources":["../../src/entity-detail/detail-tabs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/D,OAAO,KAAK,EAAiB,SAAS,EAAkB,MAAM,iBAAiB,CAAC;AAEhF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,CAgCrE"}
+{"version":3,"file":"detail-tabs.d.ts","sourceRoot":"","sources":["../../src/entity-detail/detail-tabs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/D,OAAO,KAAK,EAAiB,SAAS,EAAkB,MAAM,iBAAiB,CAAC;AAEhF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,CAgCrE"}

package/dist/entity-detail/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Entity Detail 模块
+ * 提供实体详情页标签的类型定义与构建工具
+ * @module entity-detail
+ */
 export * from './detail-tabs.js';
 export * from './interfaces.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/entity-detail/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entity-detail/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entity-detail/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}

package/dist/entity-detail/interfaces.d.ts

@@ -1,23 +1,47 @@
-import { RelationKind } from '../../packages/rxdb/src/index.ts';
+import { RelationKind } from '@aiao/rxdb';
+/**
+ * 详情页标签类型
+ */
 export type DetailTabType = 'form' | 'table';
+/**
+ * 详情页标签基础配置
+ */
 export interface DetailTabBase {
+    /** 标签唯一标识 */
     key: string;
+    /** 标签显示名称 */
     label: string;
+    /** 标签类型 */
     type: DetailTabType;
 }
+/**
+ * 表单标签配置（展示实体的基本信息表单）
+ */
 export interface DetailFormTab extends DetailTabBase {
+    /** 标签类型：表单 */
     type: 'form';
 }
+/**
+ * 表格标签配置（展示关联实体的关系数据）
+ */
 export interface DetailTableTab extends DetailTabBase {
+    /** 标签类型：表格 */
     type: 'table';
+    /** 关系名 */
     relationName: string;
+    /** 关联实体名 */
     relatedEntityName: string;
+    /** 关联实体命名空间 */
     relatedNamespace: string;
+    /** 关系类型 */
     relationKind: RelationKind;
     /** ONE_TO_MANY: 关联实体中指向当前实体的外键字段，如 'ownerId' */
     foreignKeyField?: string;
     /** MANY_TO_MANY: 关联实体中指向当前实体的关系属性名，如 'orderItems' */
     mappedProperty?: string;
 }
+/**
+ * 详情页标签配置
+ */
 export type DetailTab = DetailFormTab | DetailTableTab;
 //# sourceMappingURL=interfaces.d.ts.map

package/dist/entity-detail/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/entity-detail/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,YAAY,CAAC;IAC3B,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,cAAc,CAAC"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/entity-detail/interfaces.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,cAAc;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,cAAc;IACd,IAAI,EAAE,OAAO,CAAC;IACd,UAAU;IACV,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY;IACZ,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW;IACX,YAAY,EAAE,YAAY,CAAC;IAC3B,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,cAAc,CAAC"}

package/dist/entity-field.utils.d.ts

@@ -1,24 +1,76 @@
-import { EntityMetadata, PropertyType } from '../packages/rxdb/src/index.ts';
-export type EntityFieldType = PropertyType | `${PropertyType.boolean}` | `${PropertyType.date}` | `${PropertyType.enum}` | `${PropertyType.integer}` | `${PropertyType.number}` | `${PropertyType.string}` | `${PropertyType.uuid}` | `${PropertyType.numberArray}` | `${PropertyType.stringArray}` | `${PropertyType.keyValue}` | `${PropertyType.json}` | 'oneToOne' | 'manyToOne' | 'computed';
+import { EntityMetadata, PropertyType, FieldFormat, FieldOptions } from '@aiao/rxdb';
+/**
+ * 实体字段类型
+ * @remarks 兼容 PropertyType 枚举值及其字符串字面量形式，并包含关系字段（oneToOne / manyToOne）与计算字段（computed）的标识
+ */
+export type EntityFieldType = PropertyType | `${PropertyType.bigint}` | `${PropertyType.binary}` | `${PropertyType.boolean}` | `${PropertyType.date}` | `${PropertyType.enum}` | `${PropertyType.integer}` | `${PropertyType.number}` | `${PropertyType.string}` | `${PropertyType.uuid}` | `${PropertyType.numberArray}` | `${PropertyType.stringArray}` | `${PropertyType.keyValue}` | `${PropertyType.json}` | 'oneToOne' | 'manyToOne' | 'computed';
+/**
+ * 键值类型字段中单个键的 Schema 配置
+ */
 export interface KeyValueSchemaEntry {
+    /** 键的显示名称 */
     label?: string;
+    /** 值的类型 */
     type?: 'string' | 'number' | 'integer' | 'boolean' | 'date';
+    /** 是否必填 */
     required?: boolean;
+    /** 是否可为空 */
     nullable?: boolean;
 }
+/**
+ * 实体字段配置
+ */
 export interface EntityFieldConfig {
+    /** 字段名 */
     field: string;
+    /** 显示名称 */
     displayName: string;
+    /** 字段类型 */
     type: EntityFieldType;
+    /** 是否只读 */
     readonly?: boolean;
+    /** 是否可为空 */
     nullable?: boolean;
+    /** 是否必填 */
     required?: boolean;
+    /** 是否唯一 */
     unique?: boolean;
+    /** 枚举类型的可选值 */
     enumValues?: readonly string[];
+    /** 键值类型字段的 Schema */
     keyValueSchema?: Record<string, KeyValueSchemaEntry>;
+    /** 关系字段关联的实体名 */
     relatedEntityName?: string;
+    /** 关系字段关联实体的命名空间 */
     relatedNamespace?: string;
+    /**
+     * 字段语义标注（只影响展示与控件选择，不改变运行时值类型）
+     * 仅在元数据声明 `format` 时输出该键
+     */
+    format?: FieldFormat;
+    /**
+     * 枚举/多选值的展示元数据（label / color / disabled），键是 `enum` 的子集
+     * 仅在元数据声明 `options` 时输出该键
+     */
+    options?: FieldOptions;
+    /**
+     * 是否为加密列
+     * 仅在元数据声明 `encrypted: true` 时输出该键
+     */
+    encrypted?: boolean;
 }
+/**
+ * 从实体元数据中提取全部业务字段配置
+ * @remarks 跳过系统字段，依次收集普通属性、计算属性与关系字段
+ * @param metadata - 实体元数据
+ * @returns 字段配置列表
+ */
 export declare function extractEntityFields(metadata: EntityMetadata): EntityFieldConfig[];
+/**
+ * 从实体元数据中提取系统字段配置
+ * @remarks 始终包含只读的 id 字段，并按元数据中实际存在的属性补充时间戳与审计字段
+ * @param metadata - 实体元数据
+ * @returns 系统字段配置列表
+ */
 export declare function extractSystemFields(metadata: EntityMetadata): EntityFieldConfig[];
 //# sourceMappingURL=entity-field.utils.d.ts.map

package/dist/entity-field.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-field.utils.d.ts","sourceRoot":"","sources":["../src/entity-field.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,YAAY,EAKb,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,GAAG,YAAY,CAAC,OAAO,EAAE,GACzB,GAAG,YAAY,CAAC,IAAI,EAAE,GACtB,GAAG,YAAY,CAAC,IAAI,EAAE,GACtB,GAAG,YAAY,CAAC,OAAO,EAAE,GACzB,GAAG,YAAY,CAAC,MAAM,EAAE,GACxB,GAAG,YAAY,CAAC,MAAM,EAAE,GACxB,GAAG,YAAY,CAAC,IAAI,EAAE,GACtB,GAAG,YAAY,CAAC,WAAW,EAAE,GAC7B,GAAG,YAAY,CAAC,WAAW,EAAE,GAC7B,GAAG,YAAY,CAAC,QAAQ,EAAE,GAC1B,GAAG,YAAY,CAAC,IAAI,EAAE,GACtB,UAAU,GACV,WAAW,GACX,UAAU,CAAC;AAEf,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA6CD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,iBAAiB,EAAE,CAsBjF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,iBAAiB,EAAE,CAiBjF"}
+{"version":3,"file":"entity-field.utils.d.ts","sourceRoot":"","sources":["../src/entity-field.utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,YAAY,EAIZ,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,GAAG,YAAY,CAAC,MAAM,EAAE,GACxB,GAAG,YAAY,CAAC,MAAM,EAAE,GACxB,GAAG,YAAY,CAAC,OAAO,EAAE,GACzB,GAAG,YAAY,CAAC,IAAI,EAAE,GACtB,GAAG,YAAY,CAAC,IAAI,EAAE,GACtB,GAAG,YAAY,CAAC,OAAO,EAAE,GACzB,GAAG,YAAY,CAAC,MAAM,EAAE,GACxB,GAAG,YAAY,CAAC,MAAM,EAAE,GACxB,GAAG,YAAY,CAAC,IAAI,EAAE,GACtB,GAAG,YAAY,CAAC,WAAW,EAAE,GAC7B,GAAG,YAAY,CAAC,WAAW,EAAE,GAC7B,GAAG,YAAY,CAAC,QAAQ,EAAE,GAC1B,GAAG,YAAY,CAAC,IAAI,EAAE,GACtB,UAAU,GACV,WAAW,GACX,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,aAAa;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW;IACX,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC5D,WAAW;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU;IACV,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,IAAI,EAAE,eAAe,CAAC;IACtB,WAAW;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW;IACX,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe;IACf,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,qBAAqB;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACrD,iBAAiB;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oBAAoB;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AA2DD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,iBAAiB,EAAE,CAsBjF;AASD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,iBAAiB,EAAE,CAQjF"}

package/dist/entity-form/form-data.d.ts

@@ -1,5 +1,26 @@
 import { EntityFormData, FormFieldConfig } from './interfaces.js';
+/**
+ * 将实体对象转换为表单数据
+ * @remarks 实体上不存在的字段以 null 填充
+ * @param entity - 源实体对象
+ * @param fields - 表单字段配置
+ * @returns 仅包含字段配置中声明字段的表单数据
+ */
 export declare function entityToFormData(entity: Record<string, unknown>, fields: FormFieldConfig[]): EntityFormData;
+/**
+ * 计算表单数据相对原实体对象的变更集
+ * @remarks 只读字段跳过；值相同（引用相等或结构化相等）的字段不进入变更集
+ * @param original - 原实体对象
+ * @param formData - 表单数据
+ * @param fields - 表单字段配置
+ * @returns 发生变化的字段及其解析后的新值
+ */
 export declare function formDataToEntityChanges(original: Record<string, unknown>, formData: EntityFormData, fields: FormFieldConfig[]): Record<string, unknown>;
+/**
+ * 根据字段配置创建默认表单数据
+ * @remarks 只读字段不参与；布尔字段默认为 false，字符串 / 数字数组默认为空数组，其余字段默认为 null
+ * @param fields - 表单字段配置
+ * @returns 默认表单数据
+ */
 export declare function createDefaultFormData(fields: FormFieldConfig[]): EntityFormData;
 //# sourceMappingURL=form-data.d.ts.map

package/dist/entity-form/form-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"form-data.d.ts","sourceRoot":"","sources":["../../src/entity-form/form-data.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,cAAc,CAM3G;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,eAAe,EAAE,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,cAAc,CAqB/E"}
+{"version":3,"file":"form-data.d.ts","sourceRoot":"","sources":["../../src/entity-form/form-data.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,cAAc,CAM3G;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,eAAe,EAAE,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,cAAc,CAqB/E"}

package/dist/entity-form/form-fields.d.ts

@@ -1,6 +1,24 @@
-import { EntityMetadata } from '../../packages/rxdb/src/index.ts';
+import { EntityMetadata } from '@aiao/rxdb';
 import { FormFieldConfig, FormMode } from './interfaces.js';
+/**
+ * 根据实体元数据和表单模式构建表单字段列表
+ * @remarks 创建模式排除计算字段且不含系统字段；编辑模式追加只读的系统字段；查看模式全部字段设为只读
+ * @param metadata - 实体元数据
+ * @param mode - 表单模式
+ * @returns 表单字段配置列表
+ */
 export declare function buildFormFields(metadata: EntityMetadata, mode: FormMode): FormFieldConfig[];
+/**
+ * 按字段的 order 升序排序
+ * @remarks 未设置 order 的字段按 0 处理，返回新数组而不修改原数组
+ * @param fields - 表单字段配置
+ * @returns 排序后的字段列表
+ */
 export declare function sortFormFields(fields: FormFieldConfig[]): FormFieldConfig[];
+/**
+ * 过滤掉标记为隐藏的字段
+ * @param fields - 表单字段配置
+ * @returns 可见字段列表
+ */
 export declare function filterVisibleFields(fields: FormFieldConfig[]): FormFieldConfig[];
 //# sourceMappingURL=form-fields.d.ts.map

package/dist/entity-form/form-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"form-fields.d.ts","sourceRoot":"","sources":["../../src/entity-form/form-fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEjE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,GAAG,eAAe,EAAE,CAY3F;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAE3E;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAEhF"}
+{"version":3,"file":"form-fields.d.ts","sourceRoot":"","sources":["../../src/entity-form/form-fields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,GAAG,eAAe,EAAE,CAY3F;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAEhF"}

package/dist/entity-form/form-validation.d.ts

@@ -1,5 +1,18 @@
 import { FieldValidationError } from '../entity-value.utils.js';
 import { EntityFormData, FormFieldConfig, FormValidationResult } from './interfaces.js';
+/**
+ * 校验单个表单字段值
+ * @param field - 表单字段配置
+ * @param value - 待校验的字段值
+ * @returns 校验错误；校验通过时返回 null
+ */
 export declare function validateField(field: FormFieldConfig, value: unknown): FieldValidationError | null;
+/**
+ * 校验整份表单数据
+ * @remarks 只读与隐藏字段不参与校验
+ * @param fields - 表单字段配置
+ * @param data - 表单数据
+ * @returns 校验结果（是否通过及错误列表）
+ */
 export declare function validateForm(fields: FormFieldConfig[], data: EntityFormData): FormValidationResult;
 //# sourceMappingURL=form-validation.d.ts.map

package/dist/entity-form/form-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"form-validation.d.ts","sourceRoot":"","sources":["../../src/entity-form/form-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE7F,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAEjG;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,oBAAoB,CAQlG"}
+{"version":3,"file":"form-validation.d.ts","sourceRoot":"","sources":["../../src/entity-form/form-validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAA4B,KAAK,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE7F;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAEjG;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,oBAAoB,CAQlG"}

package/dist/entity-form/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Entity Form 模块
+ * 提供表单数据转换、字段构建与校验等工具
+ * @module entity-form
+ */
 export * from './form-data.js';
 export * from './form-fields.js';
 export * from './form-validation.js';

package/dist/entity-form/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entity-form/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entity-form/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC"}

package/dist/entity-form/interfaces.d.ts

@@ -1,45 +1,105 @@
+import { FieldFormat, FieldOptions } from '@aiao/rxdb';
 import { EntityFieldType, KeyValueSchemaEntry } from '../entity-field.utils.js';
+/**
+ * 表单模式
+ */
 export type FormMode = 'view' | 'edit' | 'create';
+/**
+ * 表单字段配置
+ */
 export interface FormFieldConfig {
+    /** 字段名 */
     field: string;
+    /** 显示名称 */
     displayName: string;
+    /** 字段类型 */
     type: EntityFieldType;
+    /** 是否只读 */
     readonly?: boolean;
+    /** 是否可为空 */
     nullable?: boolean;
+    /** 是否必填 */
     required?: boolean;
+    /** 是否唯一 */
     unique?: boolean;
+    /** 枚举类型的可选值 */
     enumValues?: readonly string[];
+    /** 键值类型字段的 Schema */
     keyValueSchema?: Record<string, KeyValueSchemaEntry>;
+    /** 关系字段关联的实体名 */
     relatedEntityName?: string;
+    /** 关系字段关联实体的命名空间 */
     relatedNamespace?: string;
+    /** 字段语义标注（只影响展示与控件选择，不改变运行时值类型） */
+    format?: FieldFormat;
+    /** 枚举/多选值的展示元数据（label / color / disabled） */
+    options?: FieldOptions;
+    /** 是否为加密列 */
+    encrypted?: boolean;
+    /** 是否隐藏 */
     hidden?: boolean;
+    /** 排序权重 */
     order?: number;
+    /** 占位提示 */
     placeholder?: string;
+    /** 帮助文本 */
     helpText?: string;
+    /** 占据的栅格列数（1 或 2） */
     span?: 1 | 2;
 }
+/**
+ * 表单字段值变更事件
+ */
 export interface FormFieldChangeEvent {
+    /** 字段名 */
     field: string;
+    /** 字段类型 */
     type: EntityFieldType;
+    /** 变更后的值 */
     value: unknown;
+    /** 变更前的值 */
     previousValue: unknown;
 }
+/**
+ * 表单数据（字段名到字段值的映射）
+ */
 export interface EntityFormData {
+    /** 字段值（字段名 → 值） */
     [field: string]: unknown;
 }
+/**
+ * 表单校验结果
+ */
 export interface FormValidationResult {
+    /** 是否通过校验 */
     valid: boolean;
+    /** 错误列表 */
     errors: FormFieldValidationError[];
 }
+/**
+ * 表单字段校验错误
+ */
 export interface FormFieldValidationError {
+    /** 出错字段名 */
     field: string;
+    /** 错误提示信息 */
     message: string;
 }
+/**
+ * 关联实体数据提供者
+ * @remarks 根据实体名（与可选命名空间）返回可选的关联实体列表
+ */
 export interface RelatedEntityProvider {
+    /** 按实体名（与可选命名空间）取得可关联实体条目 */
     (entityName: string, namespace?: string): RelatedEntityItem[];
 }
+/**
+ * 关联实体条目
+ */
 export interface RelatedEntityItem {
+    /** 实体 ID */
     id: string;
+    /** 显示名称 */
     displayName: string;
 }
 //# sourceMappingURL=interfaces.d.ts.map

package/dist/entity-form/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/entity-form/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAErF,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,wBAAwB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAAC;CAC/D;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/entity-form/interfaces.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAErF;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU;IACV,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,IAAI,EAAE,eAAe,CAAC;IACtB,WAAW;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW;IACX,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe;IACf,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,qBAAqB;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACrD,iBAAiB;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oBAAoB;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,aAAa;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW;IACX,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU;IACV,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,IAAI,EAAE,eAAe,CAAC;IACtB,YAAY;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,YAAY;IACZ,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,aAAa;IACb,KAAK,EAAE,OAAO,CAAC;IACf,WAAW;IACX,MAAM,EAAE,wBAAwB,EAAE,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,YAAY;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,aAAa;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,WAAW;IACX,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/entity-list/manual-order-list.d.ts

@@ -0,0 +1,92 @@
+import { EntityMetadata, OrderBy } from '@aiao/rxdb';
+import { RowMoveEvent } from '../entity-table/vtable/table-row-move.js';
+/** 列表排序判定需要的实体元数据 */
+export type ManualOrderListMetadata = Pick<EntityMetadata, 'manualOrder' | 'propertyMap'>;
+/** 列表的固定查询（详情页关系标签传入），结构同查询构建器的规则组 */
+export interface ListFixedQuery {
+    /** 规则组合方式 */
+    readonly combinator: 'and' | 'or';
+    /** 规则；嵌套规则组视为不能钉住排序域 */
+    readonly rules: readonly unknown[];
+}
+/**
+ * 判定列表能否拖拽排序时用到的列表状态
+ */
+export interface ListReorderState {
+    /** 当前实体元数据；未注册实体为 `undefined` */
+    readonly metadata: ManualOrderListMetadata | undefined;
+    /** 列头排序状态；只有 `normal`（未按列排序）时显示的才是手动顺序 */
+    readonly sortOrder: 'asc' | 'desc' | 'normal';
+    /** 用户在筛选框里加了条件 */
+    readonly hasUserFilter: boolean;
+    /** 列表处于关联选择模式 */
+    readonly selectMode: boolean;
+    /** 外部传入的固定查询 */
+    readonly fixedQuery: ListFixedQuery | undefined;
+    /** 排序域已全部加载：没有下一页且不在加载中 */
+    readonly fullyLoaded: boolean;
+    /** 存在只读行（无编辑权限） */
+    readonly hasReadonlyRows: boolean;
+    /** 存在未落库的草稿行 */
+    readonly hasDrafts: boolean;
+    /** 存在未完成的单元格编辑写入 */
+    readonly hasPendingEdits: boolean;
+    /** 上一次拖拽的重排还没落定 */
+    readonly reorderPending: boolean;
+}
+/**
+ * 固定查询是否恰好钉住一条完整的排序域
+ *
+ * @param groupFields - 实体声明的分组字段
+ * @param fixedQuery - 列表的固定查询
+ * @returns 整表排序要求没有固定条件；分组排序要求只有对全部分组字段各一条等值（或 `null`）条件
+ */
+export declare function pinsSingleOrderDomain(groupFields: readonly string[], fixedQuery: ListFixedQuery | undefined): boolean;
+/**
+ * 实体列表当前是否允许拖拽排序
+ *
+ * @param state - 列表状态
+ * @returns 全部条件满足时为 `true`：手动排序实体、字符串主键、未按列排序、无用户筛选、非选择模式、
+ *   固定查询钉住一条完整排序域、已全部加载、没有只读行 / 草稿 / 未完成编辑 / 未落定的重排
+ *
+ * @example
+ * ```typescript
+ * const enabled = canReorderEntityList({ metadata, sortOrder: 'normal', fixedQuery, ...flags });
+ * ```
+ */
+export declare function canReorderEntityList(state: ListReorderState): boolean;
+/**
+ * 列表未按列排序时的游标排序
+ *
+ * @param metadata - 实体元数据；未注册实体为 `undefined`
+ * @returns 手动排序实体为 `[分组字段… asc, sortOrder asc, id asc]`，其余为 `[id desc]`
+ */
+export declare function defaultListOrderBy(metadata: Pick<EntityMetadata, 'manualOrder'> | undefined): OrderBy[];
+/**
+ * 行拖放落库时与界面交互的钩子
+ */
+export interface RowMoveCommitHooks {
+    /** 放下这一刻列表是否允许拖拽排序（{@link canReorderEntityList} 的结论） */
+    readonly enabled: boolean;
+    /** 落库重排，通常是 `repository.reorder(move.id, { prevId, nextId })` */
+    reorder(move: RowMoveEvent): Promise<unknown>;
+    /** 把表格行恢复成最近一次已提交的顺序 */
+    restore(): void;
+    /** 重排进行中状态变化 */
+    setPending(pending: boolean): void;
+    /** 显示（或用 `null` 清除）落库错误 */
+    setError(error: unknown): void;
+}
+/**
+ * 协调一次行拖放的落库
+ *
+ * @param move - 表格读出的拖放结果
+ * @param hooks - 界面钩子
+ * @returns 落库成功为 `true`；不允许拖拽或落库失败为 `false`，此时表格已恢复原顺序
+ *
+ * @remarks
+ * 不允许时零写入，直接恢复表格（程序触发的拖放事件同样被拒）。成功后不改表格，
+ * 由活查询按数据库重查的结果刷新；失败时显式恢复，下一次拖拽照常可用。
+ */
+export declare function commitRowMove(move: RowMoveEvent, hooks: RowMoveCommitHooks): Promise<boolean>;
+//# sourceMappingURL=manual-order-list.d.ts.map

package/dist/entity-list/manual-order-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-order-list.d.ts","sourceRoot":"","sources":["../../src/entity-list/manual-order-list.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,OAAO,EAKb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAE7E,qBAAqB;AACrB,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,cAAc,EAAE,aAAa,GAAG,aAAa,CAAC,CAAC;AAE1F,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,aAAa;IACb,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;IAClC,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,GAAG,SAAS,CAAC;IACvD,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC9C,kBAAkB;IAClB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,iBAAiB;IACjB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,gBAAgB;IAChB,QAAQ,CAAC,UAAU,EAAE,cAAc,GAAG,SAAS,CAAC;IAChD,2BAA2B;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,mBAAmB;IACnB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,gBAAgB;IAChB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,oBAAoB;IACpB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,mBAAmB;IACnB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAUD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,cAAc,GAAG,SAAS,GAAG,OAAO,CAQrH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CASrE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,aAAa,CAAC,GAAG,SAAS,GAAG,OAAO,EAAE,CAIvG;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iEAAiE;IACjE,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,wBAAwB;IACxB,OAAO,IAAI,IAAI,CAAC;IAChB,gBAAgB;IAChB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAiBnG"}