docs(canvas): explain gestures, coordinate spaces and creation planning

This commit is contained in:
2026-11-11 23:46:22 +08:00
parent afa30d4b35
commit 62a0755350
9 changed files with 158 additions and 0 deletions
+8
View File
@@ -1,13 +1,20 @@
/**
* 组件声明式引用路径的遍历器,供复制/解散等纯规划复用。
* 只访问自有字段,不用字符串相似度猜 ID;这里 yield 可写 slot,调用者必须先复制数据再改。
*/
import type { Json } from './types.ts';
import { fault } from './values.ts';
/** Own JSON fields only. A * segment enumerates an array, never object keys. */
/** 用显式 stack 遍历 path,返回终端字段的 parent/key;缺失普通字段直接跳过。
* * 只允许数组,非数组抛错;反向压栈使最终输出仍按原数组顺序。 */
export function* copySlots(data: Json, path: readonly string[]): Generator<{parent: Record<string, Json>; key: string}> {
const work: {value: Json; depth: number}[] = [{value: data, depth: 0}];
while (work.length) {
const {value, depth} = work.pop()!, key = path[depth];
if (key === '*') {
if (!Array.isArray(value)) throw fault('invalid_copy_reference');
// 终端 * 直接枚举数组项位置;非终端 * 继续匹配下一路径段。
if (depth === path.length - 1) { for (let i = 0; i < value.length; i++) yield {parent: value as unknown as Record<string, Json>, key: String(i)}; }
else for (let i = value.length - 1; i >= 0; i--) work.push({value: value[i], depth: depth + 1});
} else if (value && typeof value === 'object' && Object.hasOwn(value, key)) {
@@ -16,6 +23,7 @@ export function* copySlots(data: Json, path: readonly string[]): Generator<{pare
}
}
}
/** 在 slot 上读取引用 ID;null 代表无引用,many 要求数组,每个 ID 必须非空字符串。 */
export function* copyReferenceIds(data: Json, ref: {path: readonly string[]; many?: boolean}): Generator<string> {
for (const {parent, key} of copySlots(data, ref.path)) {
const value = parent[key]; if (value === null) continue;