@byteluck-fe/model-driven-controls 7.1.0-beta.2 → 7.1.0-beta.4

package/dist/types/catalog/control-tree.d.ts

@@ -0,0 +1,49 @@
+export type ControlTreePath = ReadonlyArray<string | number>;
+/**
+ * 保存态与构造态控件共有的最小结构。
+ *
+ * 历史保存模型可能只有 `control_type`，构造态则通常使用 `controlType`；遍历只依赖
+ * `type` 与 `props`，避免为了读取纯 JSON 控件树加载 Designer、Vue 或 DOM。
+ */
+export interface ControlTreeNode {
+    readonly type: string;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly children?: unknown;
+    readonly [key: string]: unknown;
+}
+export interface ControlTreeVisit {
+    node: ControlTreeNode;
+    path: ControlTreePath;
+    parent?: ControlTreeNode;
+    source: 'root' | 'children' | 'nested-prop';
+    nestedPropKey?: string;
+}
+export interface ControlTreeTraversalOptions {
+    /**
+     * 宿主额外确认会保存控件节点的 props 槽位。默认槽位始终保留，不能由调用方覆盖。
+     */
+    additionalNestedPropKeys?: readonly string[];
+}
+export type ControlTreeVisitor = (visit: ControlTreeVisit) => void;
+/**
+ * 当前公共模型中已确认的 props 嵌套控件槽位。footers 仍存在于历史列表 Schema。
+ */
+export declare const CONTROL_TREE_NESTED_PROP_KEYS: readonly ["headers", "footers"];
+/**
+ * 只要求保存态与构造态共有字段；不要求 id/controlType，兼容待诊断的历史节点。
+ */
+export declare function isControlTreeNode(value: unknown): value is ControlTreeNode;
+/**
+ * 以前序稳定顺序遍历一个控件或控件数组。visitor 只接收只读视图，本函数不修改输入。
+ */
+export declare function visitControlTree(value: unknown, visitor: ControlTreeVisitor, options?: ControlTreeTraversalOptions): void;
+/** 返回稳定顺序的节点与路径，不复制页面 JSON 或 props。 */
+export declare function collectControlTreeNodes(value: unknown, options?: ControlTreeTraversalOptions): ControlTreeVisit[];
+/**
+ * 为整棵树补齐 catalog 已核实的 Runtime 缺失属性语义。
+ *
+ * - 缺失与 own-property `undefined` 使用 absent Runtime 值；`null` 和其它显式值保留。
+ * - 结果使用 catalog 公共构造属性名，适合实例化兼容，不是持久化 Schema 升级。
+ * - 未变化时保留原引用；变化时只复制命中节点及其祖先，不修改输入对象。
+ */
+export declare function applyRuntimeAbsentDefaultsToControlTree<T>(value: T, options?: ControlTreeTraversalOptions): T;

package/dist/types/catalog/index.d.ts

@@ -1,2 +1,3 @@
 export * from './types';
 export * from './query';
+export * from './control-tree';

package/dist/types/catalog/query.d.ts

@@ -1,4 +1,5 @@
-import { ControlCatalogInfo, ControlDefinition, ControlLocaleMessageFact, ControlSavedPropertyFact, ControlSettingFact } from './types';
+import { ControlAuthoringFacts, ControlAuthoringPropertyFact, ControlCatalogInfo, ControlDefinition, ControlLocaleMessageFact, ResolvedControlSavedPropertyValue, ControlSavedPropertyFact, ControlSettingFact } from './types';
+import { JsonObject } from '@byteluck-fe/model-driven-core/contracts';
 /** 返回独立副本，避免调用方污染进程内共享 catalog。 */
 export declare function getControlDefinition(type: string): ControlDefinition | undefined;
 /** 控件列表按 type 稳定排序，生成器与运行时查询顺序保持一致。 */
@@ -15,6 +16,31 @@ export declare function getControlSettingFacts(type: string): ControlSettingFact
  * propertyNameMap 与 defaultProps，才能作为控件切换时的能力证据。
  */
 export declare function getControlSavedPropertyFact(type: string, savedPropertyKey: string): ControlSavedPropertyFact | undefined;
+/**
+ * 按保存键返回单个紧凑 authoring 事实；不存在或未被真实默认模型物化时失败关闭。
+ */
+export declare function getControlAuthoringPropertyFact(type: string, savedPropertyKey: string): ControlAuthoringPropertyFact | undefined;
+/**
+ * 返回一个控件的紧凑 authoring 事实，属性按保存键稳定排序；不复制完整 catalog。
+ */
+export declare function getControlAuthoringFacts(type: string): ControlAuthoringFacts | undefined;
+/**
+ * 解析一个保存属性的有效值，仅在 catalog 已登记历史缺失语义时补值。
+ *
+ * `null` 是显式 JSON 值，不能与缺失/undefined 混为一谈。调用方可传 camelCase
+ * 构造态或 snake_case 保存态 props，返回值始终指出公共构造属性名。
+ */
+export declare function resolveControlSavedPropertyValue(input: {
+    controlType: string;
+    savedPropertyKey: string;
+    props: JsonObject;
+}): ResolvedControlSavedPropertyValue | undefined;
+/**
+ * 为 Designer 等构造态消费者补齐 Runtime 已核实的历史缺失语义。
+ *
+ * 未命中时保留原对象引用；命中时只浅拷贝 props 并写入公共属性名，不修改保存态原对象。
+ */
+export declare function applyControlRuntimeAbsentDefaults(controlType: string, props: JsonObject): JsonObject;
 /** headless 按稳定 key 窄查消息事实，避免复制整份 catalog。 */
 export declare function getControlLocaleMessageFact(key: string): ControlLocaleMessageFact | undefined;
 export declare function getControlCatalogInfo(): ControlCatalogInfo;

package/dist/types/catalog/types.d.ts

@@ -1,5 +1,5 @@
 import { ControlCatalogSchemaVersion, JsonObject, JsonValue, HeadlessControlNode, ModelDrivenBaseControlType } from '@byteluck-fe/model-driven-core/contracts';
-export type ControlCatalogValueType = 'array' | 'boolean' | 'integer' | 'number' | 'object' | 'string';
+export type ControlCatalogValueType = 'array' | 'boolean' | 'integer' | 'null' | 'number' | 'object' | 'string';
 export interface ControlSettingFact {
     controlType: string;
     propertyKey: string;
@@ -16,11 +16,62 @@ export interface ControlSettingFact {
  * 才会产生此事实。它只证明目标控件支持该保存属性，不自动授权跨控件继承或任意写入。
  */
 export interface ControlSavedPropertyFact {
+    /** 新建控件时由真实 Designer 工厂物化的默认值。 */
     controlType: string;
     defaultValue: JsonValue;
+    /**
+     * 历史保存态缺少该属性时，当前 Runtime 实际采用的值。
+     *
+     * 该字段只描述已经核实的兼容语义；未登记时调用方不得猜测或套用创建默认值。
+     */
+    absentRuntimeValue?: JsonValue;
     propertyKey: string;
     savedPropertyKey: string;
 }
+export type ControlAuthoringConstraintCompleteness = 'complete' | 'top-level';
+export type ControlAuthoringAbsentRuntimeValueFact = {
+    known: false;
+} | {
+    known: true;
+    value: JsonValue;
+};
+/**
+ * 单个保存属性的紧凑 authoring 事实。
+ *
+ * 事实只证明目标控件真实物化了该保存属性；宿主仍必须通过自己的版本化策略准入写入。
+ * createDefaultValue 与 absentRuntimeValue 分别描述“新建”与“历史缺失”语义，不能互换。
+ */
+export interface ControlAuthoringPropertyFact {
+    controlType: string;
+    propertyKey: string;
+    savedPropertyKey: string;
+    createDefaultValue: JsonValue;
+    absentRuntimeValue: ControlAuthoringAbsentRuntimeValueFact;
+    valueTypes?: ControlCatalogValueType[];
+    /** Designer setting/schema 提供的候选提示；未声明完整性，不能作为穷举值域拒绝输入。 */
+    optionHints?: JsonValue[];
+    min?: number;
+    max?: number;
+    constraintCompleteness?: ControlAuthoringConstraintCompleteness;
+    /** 该属性是否出现在当前 Designer setting 可见面；false 不等于禁止，由宿主策略决定。 */
+    settingExposed: boolean;
+    /** 显式构造是否能由 headless 工厂完整表达；保存态 Patch 不因此自动获得授权。 */
+    explicitConstructionSupported: boolean;
+}
+/** 单控件窄投影，不包含 defaultSchema、完整 propsSchema、settings 或组件实现。 */
+export interface ControlAuthoringFacts {
+    controlType: string;
+    baseType: ModelDrivenBaseControlType;
+    fieldType?: string;
+    catalogRevision: string;
+    properties: ControlAuthoringPropertyFact[];
+}
+export interface ResolvedControlSavedPropertyValue {
+    propertyKey: string;
+    savedPropertyKey: string;
+    value: JsonValue;
+    source: 'explicit' | 'absent_runtime_value';
+}
 /** 由 i18n_messages 发布生成的紧凑文案事实，不包含运行时 i18n 实例。 */
 export interface ControlLocaleMessageFact {
     key: string;
@@ -92,6 +143,8 @@ export interface ControlDefinition {
     /** 显式构造存在无法确定性表达的副作用，headless 对这些输入 fail-closed。 */
     unsupportedExplicitProps: string[];
     propertyNameMap: Record<string, string>;
+    /** 仅登记已核实的“保存属性缺失时 Runtime 如何解释”事实。 */
+    absentRuntimeDefaults?: Record<string, JsonValue>;
     settings: JsonObject[];
     settingFacts: ControlSettingFact[];
     eventKeys: string[];

package/dist/types/listControls/SubTable/property.d.ts

@@ -246,6 +246,13 @@ interface SubTablePropertyInterface<Mode extends MODE | 'Schema', Control extend
 }
 declare class SubTableControlProperty<Mode extends MODE | 'Schema', Control extends object = ControlType<Mode>> extends ListControlProperty<Mode, Control> implements SubTablePropertyInterface<Mode, Control> {
     static readonly Rules: typeof SubTableControlPropertyRules;
+    /**
+     * 历史页面未保存 label_position 时，Runtime 一直按左右布局解释。
+     * 新建控件仍使用构造器中的 top；catalog 将两类语义分开发布，供 Designer 对齐历史运行态。
+     */
+    static readonly catalogAbsentRuntimeDefaults: {
+        readonly labelPosition: "left";
+    };
     static readonly RuntimeRules: typeof SubtableControlRuntimeRules;
     /**
      * 标题

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byteluck-fe/model-driven-controls",
-  "version": "7.1.0-beta.2",
+  "version": "7.1.0-beta.4",
   "description": "> TODO: description",
   "author": "郝晨光 <2293885211@qq.com>",
   "homepage": "",
@@ -49,10 +49,10 @@
     "postpublish": "node ../../scripts/postpublish.js"
   },
   "dependencies": {
-    "@byteluck-fe/model-driven-core": "7.1.0-beta.2",
-    "@byteluck-fe/model-driven-settings": "7.1.0-beta.2",
-    "@byteluck-fe/model-driven-shared": "7.1.0-beta.2",
+    "@byteluck-fe/model-driven-core": "7.1.0-beta.4",
+    "@byteluck-fe/model-driven-settings": "7.1.0-beta.4",
+    "@byteluck-fe/model-driven-shared": "7.1.0-beta.4",
     "async-validator": "3.5.1"
   },
-  "gitHead": "68b8a947f7a0bc1b0e4ec68a71aafac5e0e7cd37"
+  "gitHead": "82847b31dd60becd6a77ed5d831c12f57b3dc7aa"
 }