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

package/dist/esm/catalog/control-tree.js

@@ -0,0 +1,373 @@
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_with_holes(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array(arr);
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else obj[key] = value;
+    return obj;
+}
+function _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) {
+        return Array.from(iter);
+    }
+}
+function _iterable_to_array_limit(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
+    }
+    return _arr;
+}
+function _non_iterable_rest() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        if (enumerableOnly) {
+            symbols = symbols.filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(object, sym).enumerable;
+            });
+        }
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
+function _sliced_to_array(arr, i) {
+    return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array(arr, i) || _non_iterable_rest();
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+}
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+import { applyControlRuntimeAbsentDefaults } from './query';
+/** 公共入口接受 unknown，因此对非 JSON 构造态对象也设置有界递归。 */ var MAX_CONTROL_TREE_DEPTH = 64;
+/**
+ * 当前公共模型中已确认的 props 嵌套控件槽位。footers 仍存在于历史列表 Schema。
+ */ export var CONTROL_TREE_NESTED_PROP_KEYS = [
+    'headers',
+    'footers'
+];
+function isRecord(value) {
+    return (typeof value === "undefined" ? "undefined" : _type_of(value)) === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 只要求保存态与构造态共有字段；不要求 id/controlType，兼容待诊断的历史节点。
+ */ export function isControlTreeNode(value) {
+    return Boolean(isRecord(value) && typeof value.type === 'string' && isRecord(value.props));
+}
+function nestedPropKeys(options) {
+    return Array.from(new Set(_to_consumable_array(CONTROL_TREE_NESTED_PROP_KEYS).concat(_to_consumable_array(options.additionalNestedPropKeys || []))));
+}
+function visitNestedValue(value, path, parent, nestedPropKey, propKeys, visitor, ancestors, depth) {
+    if (depth > MAX_CONTROL_TREE_DEPTH) return;
+    if (isControlTreeNode(value)) {
+        visitNode(value, path, parent, 'nested-prop', nestedPropKey, propKeys, visitor, ancestors, depth);
+        return;
+    }
+    if (!Array.isArray(value) && !isRecord(value)) return;
+    if (ancestors.has(value)) return;
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            value.forEach(function(item, index) {
+                return visitNestedValue(item, _to_consumable_array(path).concat([
+                    index
+                ]), parent, nestedPropKey, propKeys, visitor, ancestors, depth + 1);
+            });
+            return;
+        }
+        Object.entries(value).forEach(function(param) {
+            var _param = _sliced_to_array(param, 2), key = _param[0], item = _param[1];
+            return visitNestedValue(item, _to_consumable_array(path).concat([
+                key
+            ]), parent, nestedPropKey, propKeys, visitor, ancestors, depth + 1);
+        });
+    } finally{
+        ancestors.delete(value);
+    }
+}
+function visitNode(node, path, parent, source, nestedPropKey, propKeys, visitor, ancestors, depth) {
+    if (depth > MAX_CONTROL_TREE_DEPTH || ancestors.has(node)) return;
+    ancestors.add(node);
+    try {
+        // visitor 获得独立路径，即使 JavaScript 调用方强制修改也不污染后续遍历。
+        visitor({
+            node: node,
+            path: _to_consumable_array(path),
+            parent: parent,
+            source: source,
+            nestedPropKey: nestedPropKey
+        });
+        if (Array.isArray(node.children) && !ancestors.has(node.children)) {
+            ancestors.add(node.children);
+            try {
+                node.children.forEach(function(child, index) {
+                    if (!isControlTreeNode(child)) return;
+                    visitNode(child, _to_consumable_array(path).concat([
+                        'children',
+                        index
+                    ]), node, 'children', undefined, propKeys, visitor, ancestors, depth + 1);
+                });
+            } finally{
+                ancestors.delete(node.children);
+            }
+        }
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = propKeys[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var propKey = _step.value;
+                if (!Object.prototype.hasOwnProperty.call(node.props, propKey)) continue;
+                visitNestedValue(node.props[propKey], _to_consumable_array(path).concat([
+                    'props',
+                    propKey
+                ]), node, propKey, propKeys, visitor, ancestors, depth + 1);
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+    } finally{
+        ancestors.delete(node);
+    }
+}
+/**
+ * 以前序稳定顺序遍历一个控件或控件数组。visitor 只接收只读视图，本函数不修改输入。
+ */ export function visitControlTree(value, visitor) {
+    var options = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : {};
+    var propKeys = nestedPropKeys(options);
+    var ancestors = new Set();
+    if (isControlTreeNode(value)) {
+        visitNode(value, [], undefined, 'root', undefined, propKeys, visitor, ancestors, 0);
+        return;
+    }
+    if (!Array.isArray(value)) return;
+    ancestors.add(value);
+    try {
+        value.forEach(function(item, index) {
+            if (!isControlTreeNode(item)) return;
+            visitNode(item, [
+                index
+            ], undefined, 'root', undefined, propKeys, visitor, ancestors, 0);
+        });
+    } finally{
+        ancestors.delete(value);
+    }
+}
+/** 返回稳定顺序的节点与路径，不复制页面 JSON 或 props。 */ export function collectControlTreeNodes(value) {
+    var options = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+    var result = [];
+    visitControlTree(value, function(visit) {
+        return result.push(visit);
+    }, options);
+    return result;
+}
+function mapNestedValue(value, propKeys, ancestors, depth) {
+    if (depth > MAX_CONTROL_TREE_DEPTH) return value;
+    if (isControlTreeNode(value)) {
+        return mapNode(value, propKeys, ancestors, depth);
+    }
+    if (!Array.isArray(value) && !isRecord(value)) return value;
+    if (ancestors.has(value)) return value;
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            var result = value;
+            value.forEach(function(item, index) {
+                var next = mapNestedValue(item, propKeys, ancestors, depth + 1);
+                if (next === item) return;
+                if (result === value) result = _to_consumable_array(value);
+                result[index] = next;
+            });
+            return result;
+        }
+        var result1 = value;
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = Object.entries(value)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var _step_value = _sliced_to_array(_step.value, 2), key = _step_value[0], item = _step_value[1];
+                var next = mapNestedValue(item, propKeys, ancestors, depth + 1);
+                if (next === item) continue;
+                if (result1 === value) result1 = _object_spread({}, value);
+                result1[key] = next;
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+        return result1;
+    } finally{
+        ancestors.delete(value);
+    }
+}
+function mapNode(input, propKeys, ancestors, depth) {
+    if (depth > MAX_CONTROL_TREE_DEPTH || ancestors.has(input)) return input;
+    ancestors.add(input);
+    try {
+        var node = input;
+        if (Array.isArray(input.children)) {
+            var children = mapNestedValue(input.children, propKeys, ancestors, depth + 1);
+            if (children !== input.children) node = _object_spread_props(_object_spread({}, node), {
+                children: children
+            });
+        }
+        var props = node.props;
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = propKeys[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var propKey = _step.value;
+                if (!Object.prototype.hasOwnProperty.call(props, propKey)) continue;
+                var current = props[propKey];
+                var next = mapNestedValue(current, propKeys, ancestors, depth + 1);
+                if (next === current) continue;
+                if (props === node.props) props = _object_spread({}, props);
+                props[propKey] = next;
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+        if (props !== node.props) node = _object_spread_props(_object_spread({}, node), {
+            props: props
+        });
+        var normalizedProps = applyControlRuntimeAbsentDefaults(node.type, node.props);
+        if (normalizedProps !== node.props) {
+            node = _object_spread_props(_object_spread({}, node), {
+                props: normalizedProps
+            });
+        }
+        return node;
+    } finally{
+        ancestors.delete(input);
+    }
+}
+function mapRootValue(value, propKeys) {
+    var ancestors = new Set();
+    if (isControlTreeNode(value)) return mapNode(value, propKeys, ancestors, 0);
+    if (!Array.isArray(value)) return value;
+    var result = value;
+    ancestors.add(value);
+    try {
+        value.forEach(function(item, index) {
+            if (!isControlTreeNode(item)) return;
+            var next = mapNode(item, propKeys, ancestors, 0);
+            if (next === item) return;
+            if (result === value) result = _to_consumable_array(value);
+            result[index] = next;
+        });
+    } finally{
+        ancestors.delete(value);
+    }
+    return result;
+}
+/**
+ * 为整棵树补齐 catalog 已核实的 Runtime 缺失属性语义。
+ *
+ * - 缺失与 own-property `undefined` 使用 absent Runtime 值；`null` 和其它显式值保留。
+ * - 结果使用 catalog 公共构造属性名，适合实例化兼容，不是持久化 Schema 升级。
+ * - 未变化时保留原引用；变化时只复制命中节点及其祖先，不修改输入对象。
+ */ export function applyRuntimeAbsentDefaultsToControlTree(value) {
+    var options = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+    return mapRootValue(value, nestedPropKeys(options));
+}

package/dist/esm/catalog/generated/control-catalog.v1.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "model-driven.control-catalog.v1",
-  "packageVersion": "7.1.0-beta.3",
-  "sourceRevision": "sha256:5699432a72e9369aeccc3083c2479d8c12e506bb74ae068a21c89ba77f6937dc",
-  "revision": "sha256:f352354ca2e86d563cfd767830aa9c5aeab204de26401d3517824f8a45f54bdb",
+  "packageVersion": "7.1.0-beta.4",
+  "sourceRevision": "sha256:29da8bd3ec3de616fe213143170f79a1dce326ec77d5ce6398747100cd1229d1",
+  "revision": "sha256:ad4745a37643c80842d3a5a8fa9dd4a8cb13d12f61e35df972c9ef63097faddd",
   "localeMessages": {
     "CMD.approvedDocuments": {
       "key": "CMD.approvedDocuments",

package/dist/esm/catalog/index.js

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

package/dist/esm/catalog/query.js

@@ -99,6 +99,10 @@ function _sliced_to_array(arr, i) {
 function _to_consumable_array(arr) {
     return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
 }
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
 function _unsupported_iterable_to_array(o, minLen) {
     if (!o) return;
     if (typeof o === "string") return _array_like_to_array(o, minLen);
@@ -178,6 +182,129 @@ export function getControlSettingFacts(type) {
         savedPropertyKey: savedPropertyKey
     }));
 }
+var CATALOG_VALUE_TYPES = new Set([
+    'array',
+    'boolean',
+    'integer',
+    'null',
+    'number',
+    'object',
+    'string'
+]);
+function isRecord(value) {
+    return (typeof value === "undefined" ? "undefined" : _type_of(value)) === 'object' && value !== null && !Array.isArray(value);
+}
+function schemaValueTypes(value) {
+    if (!isRecord(value)) return [];
+    var result = new Set();
+    var addType = function addType(type) {
+        if (typeof type === 'string' && CATALOG_VALUE_TYPES.has(type)) {
+            result.add(type);
+        }
+    };
+    if (Array.isArray(value.type)) value.type.forEach(addType);
+    else addType(value.type);
+    if (Array.isArray(value.anyOf)) {
+        value.anyOf.forEach(function(item) {
+            return schemaValueTypes(item).forEach(function(type) {
+                return result.add(type);
+            });
+        });
+    }
+    return _to_consumable_array(result).sort();
+}
+function jsonValues(value) {
+    if (!Array.isArray(value)) return undefined;
+    // generated catalog 已是 JSON；仍复制一份，避免查询结果污染共享文档。
+    return clone(value);
+}
+function numberValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function valueTypeForDefault(value) {
+    if (value === null) return 'null';
+    if (Array.isArray(value)) return 'array';
+    if (typeof value === 'boolean') return 'boolean';
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'integer' : 'number';
+    }
+    if (typeof value === 'string') return 'string';
+    return 'object';
+}
+/**
+ * 按保存键返回单个紧凑 authoring 事实；不存在或未被真实默认模型物化时失败关闭。
+ */ export function getControlAuthoringPropertyFact(type, savedPropertyKey) {
+    var _ref, _ref1, _ref2, _ref3;
+    var definition = definitionsByType.get(type);
+    var savedFact = getControlSavedPropertyFact(type, savedPropertyKey);
+    if (!definition || !savedFact) return undefined;
+    var settingFact = definition.settingFacts.find(function(fact) {
+        return fact.savedPropertyKey === savedPropertyKey;
+    });
+    var propertySchema = isRecord(definition.propsSchema.properties) ? definition.propsSchema.properties[savedFact.propertyKey] : undefined;
+    var schemaTypes = schemaValueTypes(propertySchema);
+    var schema = isRecord(propertySchema) ? propertySchema : undefined;
+    var defaultType = valueTypeForDefault(savedFact.defaultValue);
+    // schema 联合类型、setting 类型与真实创建默认值都是独立事实；不能用某一个默认值
+    // 反向缩窄整个合法值域，否则 integer|string 之类的历史合法值会被误拒绝。
+    var valueTypes = _to_consumable_array(new Set(_to_consumable_array(schemaTypes).concat(_to_consumable_array(settingFact ? [
+        settingFact.valueType
+    ] : []), [
+        defaultType
+    ]))).sort();
+    // setting options 与当前 schema enum 尚无“完整值域”发布事实，只能作为 authoring 提示。
+    var optionHints = (settingFact === null || settingFact === void 0 ? void 0 : settingFact.options) || jsonValues(schema === null || schema === void 0 ? void 0 : schema.enum);
+    var min = (_ref = (_ref1 = settingFact === null || settingFact === void 0 ? void 0 : settingFact.min) !== null && _ref1 !== void 0 ? _ref1 : numberValue(schema === null || schema === void 0 ? void 0 : schema.minimum)) !== null && _ref !== void 0 ? _ref : numberValue(schema === null || schema === void 0 ? void 0 : schema.min);
+    var max = (_ref2 = (_ref3 = settingFact === null || settingFact === void 0 ? void 0 : settingFact.max) !== null && _ref3 !== void 0 ? _ref3 : numberValue(schema === null || schema === void 0 ? void 0 : schema.maximum)) !== null && _ref2 !== void 0 ? _ref2 : numberValue(schema === null || schema === void 0 ? void 0 : schema.max);
+    var hasTopLevelOnly = valueTypes.some(function(valueType) {
+        return valueType === 'array' || valueType === 'object';
+    });
+    return clone(_object_spread_props(_object_spread({
+        controlType: type,
+        propertyKey: savedFact.propertyKey,
+        savedPropertyKey: savedPropertyKey,
+        createDefaultValue: savedFact.defaultValue,
+        absentRuntimeValue: savedFact.absentRuntimeValue !== undefined ? {
+            known: true,
+            value: savedFact.absentRuntimeValue
+        } : {
+            known: false
+        },
+        valueTypes: valueTypes
+    }, optionHints ? {
+        optionHints: optionHints
+    } : {}, min !== undefined ? {
+        min: min
+    } : {}, max !== undefined ? {
+        max: max
+    } : {}), {
+        constraintCompleteness: hasTopLevelOnly ? 'top-level' : 'complete',
+        settingExposed: Boolean(settingFact),
+        explicitConstructionSupported: !definition.unsupportedExplicitProps.includes(savedFact.propertyKey)
+    }));
+}
+/**
+ * 返回一个控件的紧凑 authoring 事实，属性按保存键稳定排序；不复制完整 catalog。
+ */ export function getControlAuthoringFacts(type) {
+    var definition = definitionsByType.get(type);
+    if (!definition) return undefined;
+    var properties = Object.values(definition.propertyNameMap).map(function(savedPropertyKey) {
+        return getControlAuthoringPropertyFact(type, savedPropertyKey);
+    }).filter(function(fact) {
+        return fact !== undefined;
+    }).sort(function(left, right) {
+        return left.savedPropertyKey.localeCompare(right.savedPropertyKey);
+    });
+    return clone(_object_spread_props(_object_spread({
+        controlType: type,
+        baseType: definition.baseType
+    }, definition.fieldType ? {
+        fieldType: definition.fieldType
+    } : {}), {
+        catalogRevision: catalog.revision,
+        properties: properties
+    }));
+}
 /**
  * 解析一个保存属性的有效值，仅在 catalog 已登记历史缺失语义时补值。
  *

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,4 @@
-import { ControlCatalogInfo, ControlDefinition, ControlLocaleMessageFact, ResolvedControlSavedPropertyValue, 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;
@@ -16,6 +16,14 @@ 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 已登记历史缺失语义时补值。
  *

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;
@@ -28,6 +28,44 @@ export interface ControlSavedPropertyFact {
     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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byteluck-fe/model-driven-controls",
-  "version": "7.1.0-beta.3",
+  "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.3",
-    "@byteluck-fe/model-driven-settings": "7.1.0-beta.3",
-    "@byteluck-fe/model-driven-shared": "7.1.0-beta.3",
+    "@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": "7adfb426676013d0daa1ece71a415ef840b8f92e"
+  "gitHead": "82847b31dd60becd6a77ed5d831c12f57b3dc7aa"
 }